Metadata-Version: 2.4
Name: py-pluto
Version: 1.2.2
Summary: PyPLUTO: Plotting routines for PLUTO
Author: D. Crocco, D. Melon Fuksman, M. Bugli, V. Berta, E. Puzzoni, A. Mignone, B. Vaidya
Author-email: "G. Mattia" <mattia@mpia.de>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: astropy>=7.2.0
Requires-Dist: contourpy>=1.2.1
Requires-Dist: numpy>=2.0.0
Requires-Dist: matplotlib>=3.8.4
Requires-Dist: scipy>=1.13.0
Requires-Dist: numexpr>=2.10.0
Requires-Dist: h5py>=3.11.0
Requires-Dist: inifix>=7.0.0
Requires-Dist: PySide6 ; extra == "gui"
Requires-Dist: pastamarkers ; extra == "pasta"
Project-URL: Changelog, https://github.com/GiMattia/PyPLUTO/blob/main/CHANGELOG.md
Project-URL: Examples, https://github.com/GiMattia/PyPLUTO/tree/main/Examples
Project-URL: Homepage, https://github.com/GiMattia/PyPLUTO
Provides-Extra: gui
Provides-Extra: pasta

# PyPLUTO: a data analysis Python package for the PLUTO code

| Category | Badges |
| --- | --- |
| Package |  ![Python Versions](https://img.shields.io/badge/Python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-3776AB.svg?style=flat&logo=python&logoColor=white) [![PyPI version](https://img.shields.io/pypi/v/py-pluto)](https://pypi.org/project/py-pluto/) |
| Reliability | [![Windows Tests](https://github.com/GiMattia/PyPLUTO/actions/workflows/test_windows.yml/badge.svg)](https://github.com/GiMattia/PyPLUTO/actions/workflows/test_windows.yml) [![MacOS Tests](https://github.com/GiMattia/PyPLUTO/actions/workflows/test_macos.yml/badge.svg)](https://github.com/GiMattia/PyPLUTO/actions/workflows/test_macos.yml) [![Linux Tests](https://github.com/GiMattia/PyPLUTO/actions/workflows/test_linux.yml/badge.svg)](https://github.com/GiMattia/PyPLUTO/actions/workflows/test_linux.yml) ![Coverage Report](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/GiMattia/384b1f3a3a3b74cdbd65c4e3dce0632f/raw/pytest-coverage-comment__main.json) |
| Docs & Community | [![Project Status: Active](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) [![Documentation](https://readthedocs.org/projects/pypluto/badge/?version=latest)](https://pypluto.readthedocs.io/en/latest/?badge=latest)  [![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?logo=discord&logoColor=white)](https://discord.gg/63A3sM9UtX)  [![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) |
| Citation | [![DOI](https://joss.theoj.org/papers/10.21105/joss.08448/status.svg)](https://doi.org/10.21105/joss.08448) [![Arxiv](https://img.shields.io/badge/arXiv-2501.09748-8F1515?style=flat&logo=arxiv&logoColor=red)](https://doi.org/10.48550/arXiv.2501.09748) [![Zenodo](https://zenodo.org/badge/DOI/10.5281/zenodo.19650848.svg)](https://doi.org/10.5281/zenodo.19650848) |

PyPLUTO is a Python library which loads and plots the data obtained from the
PLUTO code simulations.
The aim of this package is to simplify some non-trivial python routines in order
to quickly recover effective plots that are suited for scientific publications.

The package is designed to be used in both an interactive environment like
ipython shell or Jupyter notebook and standard Python scripts.

The package is structured as follow:

- the Load class is used to load the data from the PLUTO simulation fluid files.
- the LoadPart class is used to load the data from the PLUTO simulation particle files.
- the Image class is used to visualize the loaded data.
- the GUI subpackage allows for a quick interactive script-free visualization.
- physical units can be attached to loaded variables via the `astropy` library.
- additional functions (e.g., to show the images) are included in the package.

The package includes a set of examples in the `Examples` directory.

The package requires Python 3.11 or newer (CI tests 3.12, 3.13, and 3.14)
and the following core dependencies:

- `astropy`
- `contourpy`
- `h5py`
- `inifix`
- `matplotlib`
- `numexpr`
- `numpy`
- `scipy`

The GUI requires the optional dependency `PySide6`, installable via
`pip install py-pluto[gui]`.

The package is provided with a `LICENSE` file which contains the license terms.

The package is provided with an extensive documentation in the `Docs` directory.

## Installation Instructions

To install the PyPLUTO package, you can use the following methods:

The easiest way to install PyPLUTO is through uv. Open your terminal and run the following command:

```bash
uv add py-pluto
```

Ensure that you are using Python 3.11 or newer, as the package is compatible from this version onwards.
Installation through pip is also possible through the command:

```bash
pip install py-pluto
```

This method allows installation in a non-editable mode, and it is recommended to use a virtual environment to avoid conflicts with other packages.

## Quick Start

```python
import pyPLUTO as pp
```

Simulations can be loaded by just providing the path to the simulation directory. The last output (if not specific
file is selected) is automatically found, as well as the available PLUTO file in the selected folder.

```python
D = pp.Load()
print(D)
```

Relevant simulations attributes (such as the computational grid, the geometry and the variables to load) are found automatically.
The data can be plotted through the Image class, which acts as a simplified matplotlib wrapper.
An example of 1D plot of the density can be:

```python
D = pp.Load()
pp.Image().plot(D.x1, D.rho)
pp.show()
```

while 2D plots can be created with

```python
D = pp.Load()
pp.Image().display(D.rho, x1=D.x1, x2=D.x2, cpos="right")
pp.show()
```

## Examples

In order to test PyPLUTO capabilities, even without the PLUTO code, we provide
an extensive tests suite with all the necessary data.
In this way, PyPLUTO can be explored without any knowledge of the PLUTO code.
All the tests are located in the `Examples` directory and are aimed at showing
how to exploit the package capabilities.

From an installed package, examples are available through:

```bash
pypluto-examples list
pypluto-examples copy
pypluto-examples run test01_sod
```

Equivalent Python API:

```python
import pyPLUTO as pp

print(pp.examples_path())        # installed examples directory
pp.copy_examples()               # creates ./pypluto_examples
pp.run_example("test01_sod")     # runs one example script
```

### Maintainer notes for examples

- Canonical sources stay in `Examples/` (repo root).
- Installed users fetch a cached copy from GitHub (matching package version tag when available).
- Before release, keep `Examples/` in sync with the release tag and verify CLI:

```bash
python3 -m build
pip install dist/py_pluto-*.whl
pypluto-examples list
```

## The GUI

A Graphical User Interface has been implemented in order to simplify and enhance the visualization and analysis of simulation data.
The GUI is built with PySide6 and allows users to load and visualize 1D and 2D fluid data (or slices) from PLUTO simulations.
To run the GUI after the package installation, one should simply run the command

```bash
pypluto-gui
```

from the terminal. More details on how to use the GUI can be found in the documentation.

## Documentation

For more detailed instructions and additional installation options, please refer to the PyPLUTO documentation where you can find comprehensive guides and examples.

## Cite This Repository

If you use this repository in your research or projects, please cite the JOSS paper.

```
@ARTICLE{2025JOSS...10.8448M,
       author = {{Mattia}, Giancarlo and {Crocco}, Daniele and {Melon Fuksman}, David and {Bugli}, Matteo and {Berta}, Vittoria and {Puzzoni}, Eleonora and {Mignone}, Andrea and {Vaidya}, Bhargav},
        title = "{PyPLUTO: a data analysis Python package for the PLUTO code}",
      journal = {The Journal of Open Source Software},
     keywords = {astronomy, magnetohydrodynamics, computational astrophysics, data visualization, Python, Instrumentation and Methods for Astrophysics},
         year = 2025,
        month = sep,
       volume = {10},
       number = {113},
          eid = {8448},
        pages = {8448},
          doi = {10.21105/joss.08448},
archivePrefix = {arXiv},
       eprint = {2501.09748},
 primaryClass = {astro-ph.IM},
       adsurl = {https://ui.adsabs.harvard.edu/abs/2025JOSS...10.8448M},
      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}
```

We recommend to put one the following expressions in your manuscript:

"The figures presented in this paper were generated using the PyPLUTO package (citation to the paper)"

"This research has benefited from the PyPLUTO package for data visualization (citation to the paper)"

## Contributing

If you have any questions, suggestions or find a bug, feel free to open an issue or fork the repository and create a pull request.
Any contribution aimed at helping the PLUTO code community to have better plots with less efforts will be greatly appreciated.
If you want to contribute to PyPLUTO please follow the instruction present in the CONTRIBUTING.md file.

