Skip to content
Smoothed particle hydrodynamics analysis and visualization with Python
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.


Smoothed particle hydrodynamics analysis and visualization with Python.

Build Status Documentation Status Anaconda Version Anaconda Platform License


Plonk supports the following SPH file formats:

  • Phantom output in HDF format.

Note: you can convert Phantom binary dumps to HDF. See the Phantom wiki for more information.

Basic usage

To read in a simulation with dump files like disc_00000.h5, ..., and evolution files like disc01.ev, ..., in the current directory, and see what dumps there are:

>>> import plonk

>>> simulation = plonk.Simulation(prefix='disc')
>>> simulation.dumps
[<plonk.Dump: "disc_00000.h5">,
 <plonk.Dump: "disc_01000.h5">]

The Dump objects contain the particle and sinks arrays, lazily loaded from the HDF5 file, as well as the dump header stored as a dictionary.

To visualize a single dump file:

>>> dump = plonk.Dump('disc_00000.h5')

>>> plonk.Visualization(
...     dump=dump,
...     render='density',
...     extent=[-200, 200, -200, 200]
...     )

For further usage, see examples folder and documentation. The code is internally documented with docstrings. Try, for example, help(plonk.Dump) or help(plonk.Visualization).


Plonk is a Python 3 only package.


The easiest and recommended way to install Plonk is via the package manager Conda

conda install plonk --channel dmentipl


conda config --add channels dmentipl
conda install plonk

Note: Using this method you don't need to have this repository on your machine.

This will install the required dependencies. For details on Conda, see


Contributions are welcome.

If you want to contribute to Plonk you should fork the repository. You can then clone it to your local machine, and use Conda to link to your local copy of the code.

git clone<user>/plonk
cd plonk && conda develop .

There is a compiled Fortran component to Plonk which is derived from Splash. You must compile this before development. This requires a Fortran compiler, e.g. gfortran. The following compiles Splash into a shared object library, and then uses Cython to build a Python interface to that library.

make install
python build_ext --inplace

You need to make sure the required dependencies are installed (via Conda). To satisfy these requirements there is a environment.yml file. You can set up a Conda environment for development and install Plonk in it:

git clone<user>/plonk && cd plonk
conda env create --name plonk_dev --file environment.yml
conda activate plonk_dev

and then follow the instructions above. (To leave the development environment: conda deactivate.)

After you have committed and pushed your changes to your forked repository you can issue a pull request:

Code style

We follow PEP 8 for code style, and use Black and isort for auto-formatting. To use Black on your changes run the following from the main repository directory:

isort plonk/**/*.py
black --skip-string-normalization plonk

To do


  • Put documentation online.


  • Check read and write of Phantom dumps.
  • Calculating extra quantities.


  • Put conda package on
  • Add pip install instructions. Add to PyPI.
  • Pull request template.
  • Add versioning and releases.


  • Making line plots from data.
  • Add analysis routines:
    • binary discs
    • dusty discs
    • magnetic fields
  • Add to visualization features:
    • physical units
    • extra calculated quantities

Future features

  • Setup initial conditions like phantomsetup.
  • Modify a dump file like moddump (from Phantom).
You can’t perform that action at this time.