Commit ff6b1aa9 authored by Simeon Doetsch's avatar Simeon Doetsch

Added some documentation

parent 52d2737f
......@@ -4,4 +4,106 @@ This is a Python 3 library for plotting output data from the [PLUTO code](http:/
This library is under development and mostly specialized on the functionality I personally need. Nonetheless I will try to make the code as widely applicable and documented as possible.
There is no completed documentation yet, but most functions/classes should have a docstring.
\ No newline at end of file
## Requirements
Python >=3.6
## Installation
Download from archive or via git, then run
python install
If you downloaded via git and want to keep updating via git, you can also use
python develop
This way the package is always read in from the git directory.
## Example
import plutoplot as pp
sim = pp.Simulation("path_to_simulation")
# Access to grid coordinates
# Access to simulation steps
# time evolution of mean pressure
mean_prs = sim.reduce(lambda D : D.prs.mean())
## Concepts
`plutoplot` offers three main classes for handling simulation data:
- `Simulation`: for a simulation
- `PlutoData`: for a single simulation data frame
- `Grid`: for the PLUTO domain grid
For data loading the user only has to instantiate a `Simulation`, the grid
and the `PlutoData` objects are created from the `Simulation` when needed.
`PlutoData` uses lazy loading for the actual data, which means the data is
loaded when is first needed, not on object instantiation.
Each variable is loaded seperately (independent of PLUTO save format),
e.g. when only density is needed, pressure is never put into memory.
## Simulation instantiation
A `Simulation` can be instantiated with:
Simulation(sim_dir='', format=None, coordinates=None)
- `sim_dir`: Simulation directory (directory with `pluto.ini` and `definitions.h`).
plutoplot searchs for the gridfile and simulation data first in `sim_dir`,
then in `sim_dir/data`, and then looks up the data directory in `pluto.ini`.
Default: Current working directory
- `format`: file format of the simulation data, currently supports `double` and `float`
in both `single_file` and `multiple_files` mode.
Default: `double` and `float` are tried in that order
- `coordinates`: coordinate system of the simulation grid.
Supports `cartesian`, `spherical`, `polar`, `cylindrical`.
Only necessary for projecting the grind into a cartesian system (e.g. for plotting).
Default: Read coordinate system from `definitions.h`, using `cartesian` as fallback
## Access `pluto.ini` and `definitions.h`
`plutoplot` can load the PLUTO configuration files:
sim = Simulation('sim_dir')
The returned objects for `pluto.ini` (`Pluto_ini`) and `definitions.h` (`Definitions_H`)
are thin wrappers around `OrderedDict`s.
## Data access
The simulation steps can be optained from the `Simulation` object with the subscript syntax:
sim = Simulation('sim_dir')
initial = sim[0]
last = sim[-1]
It supports the Python conventions for indexing (zero indexed, negative numbers
are handled as `len(sim)-i`)
Which variables are saved by PLUTO are accesible with
# or
# e.g. ['rho', 'vx1', 'vx2', 'vx3', 'prs']
The variable names in this list can be then accessed from the `PlutoData` objects:
The data is then returned as Numpy arrays, and can be used as usual.
## Plotting
......@@ -10,11 +10,11 @@ def generate_coord_mapping(coordinates: str) -> dict:
'polar': {
'r': 'x1',
'phi': 'x2',
'z': 'x2'
'cylindrical': {
'r': 'x1',
'phi': 'x2',
'z': 'x3'
'spherical': {
......@@ -39,11 +39,11 @@ def generate_tex_mapping(coordinates: str) -> dict:
'x2': 'y',
'x3': 'z'
'polar': {
'cylindrical': {
'x1': 'r',
'x2': 'z'
'cylindrical': {
'polar': {
'x1': 'r',
'x2': r'\phi',
'x3': 'z'
......@@ -74,6 +74,8 @@ def generate_coordinate_mesh(coordinates, x1, x2):
y = r * np.cos(theta)
return x, y
elif coordinates == 'cylindrical':
return x1, x2
elif coordinates == 'polar':
r, phi = np.meshgrid(x1, x2)
x = r * np.cos(phi)
y = r * np.sin(phi)
......@@ -188,7 +188,10 @@ class Simulation:
return np.array(, self.iter()), dtype=dtype)
def plot(self, *args, n: int=-1, **kwargs) -> None:
"""Plot last data file, or data file n. All other arguments forwarded to PlutoData.plot()"""
Plot last data file, or data file n. All other arguments forwarded to PlutoData.plot()
No return, because it would interfere with interactive output in Jupyter Notebook
# Use widget to choose timestep if inside Jupyter Notebook
......@@ -196,14 +199,15 @@ class Simulation:
import ipywidgets as widgets
def handler(i):
self[i].plot(*args, **kwargs)
widgets.interact(handler, i=widgets.IntSlider(min=0,
plot = widgets.interactive(handler, i=widgets.IntSlider(min=0,
description="Simulation frame")
plot.children[0].description = "Simulation frame"
plot.children[0].layout.width = "20%"
except (NameError, ImportError):
self[n].plot(*args, **kwargs)
self[n].plot(*args, **kwargs)
def __len__(self) -> int:
return self.n
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment