PyPLUTO: a data analysis Python package for the PLUTO code

Category	Badges
Package
Reliability
Docs & Community
Citation

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:

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:

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

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.

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:

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

while 2D plots can be created with

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:

pypluto-examples list
pypluto-examples copy
pypluto-examples run test01_sod

Equivalent Python API:

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:

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

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.