Mickey: Python scripts to tame Pluto

Python toolkit for analyzing and visualizing magnetohydrodynamic (MHD) simulations from the Pluto code. Provides coordinate transformations (regridding), mass/energy/angular momentum calculations, and GPU-accelerated array operations.

Requirements

• pyPluto which contains the module to read binary files generated by Pluto
• nmmn: supporting python modules for scientific analysis.
• [OPTIONAL] PGI compiler (pgcc) compiler to make use of GPU or CPU acceleration for fast array handling. Only required for changing coordinate basis (i.e. regridding; cf. C extensions).
• [OPTIONAL] SWIG: needed to interface the python modules and fast C routines.

Features

• Data Loading: Read Pluto binary output files via pyPLUTO
• Visualization: Plot simulation variables in 1D, 2D, and 3D
• Coordinate Transformations: Fast regridding between coordinate systems (Cartesian ↔ Spherical) with optional GPU acceleration
• Physics Analysis: Compute mass accretion rates, total mass, energy, and angular momentum
• Performance: 100x speedup on NVIDIA GPUs vs pure Python for large arrays

Installation

(1) Make sure you have pyPluto installed (ignore this step if you already installed it):

git clone git@github.com:black-hole-group/pyPLUTO.git

(2) Install nmmn (ignore this step if you already installed it)

pip install nmmn

Keep in mind that nmmn and Mickey are being continuously updated. To get their bleeding-edge versions, it is recommended to install using the python setup.py develop method, cd to the directory where the packages are located and issue a git pull.

(3) Setup environment variables for Pluto and the python scripts, to make sure that they will be found when needed

export PLUTO_DIR=/home/user/pluto
export PYTHONPATH=/home/user/pyPLUTO:/home/user/mickey/src:$PYTHONPATH

Add the above lines to your .bash_profile (MacOS) or .bashrc (Linux) file for convenience.

(4) OPTIONAL Install the PGI compilers. GPU acceleration is only supported in Linux.

(5) OPTIONAL Install SWIG.

sudo apt install swig # installs system-wide
conda install swig # installs for anaconda distro

(6) Install Mickey,

git clone git@github.com:rsnemmen/mickey.git
cd mickey

You have now two options to install Mickey. You can:

i. install the module on the system’s python library path

python setup.py install  # compile C extensions and install

or...

ii. install the package with a symlink, so that changes to the source files will be immediately available:

python setup.py develop

This last method is preferred since it allows for easily updating Mickey to the latest changes in the repo (git pull). You may need to run the last command with sudo. Also, if the C extension source code was updated, you will need to recompile these extensions.

C extensions

Mickey includes a couple of C extensions for speeding up some array operations which are too slow in Python (e.g. changing the coordinate basis of an array). They are located at ./src. When running the setup commands above, the C extensions should be automatically compiled with the PGI compiler (pgcc).

If you want to compile them yourself,

cd src
make

By default, mickey will compile with GPU support enabled for a NVIDIA GPU. If you want to disable GPU-use,

make CPU=1

(it does not really matter what comes after the = above).

---

NOTE

GPUs can speed up regridding by a factor of 100 compared to CPU w/ pure Python (regrid), and 5-10x compared to CPU w/ C (make CPU=1).

---

Usage

Quick Start

from mickey import Pluto
import pyPLUTO as pp

# Load Pluto simulation data
p = Pluto('/path/to/pluto/data')

# Visualize density
p.plotVar('density')

For more detailed examples, please see the jupyter notebook mickey-tutorial.ipynb.

Branch explanation

• master: stable branch, with recommended optimizations (one hopes)

Testing branches

• openacc: fast and furious regridding. NVIDIA GPU recommended for max speed
• swig: C-extensions for faster regridding, incorporated through SWIG. Serial code
• openmp: C-extensions for optimization, SWIG interface, OpenMP acceleration. Very similar to branch swig
• opencl: incorporated using C and PyOpenCL

License

Mickey is released under the MIT License. See LICENSE file for details.

TODO

• compute energy
• compute how much mass was lost from the volume due to outflows
• more examples, put them in a jupyter notebook