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
numpy
matplotlib
```
## Installation
Download from archive or via git, then run
```python
python setup.py install
```
If you downloaded via git and want to keep updating via git, you can also use
```python
python setup.py develop
```
This way the package is always read in from the git directory.
## Example
```python
import plutoplot as pp
sim = pp.Simulation("path_to_simulation")
print(sim.grid)
# Access to grid coordinates
sim.x1
sim.vx1
# Access to simulation steps
sim[3].rho
# 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:
```python
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:
```python
sim = Simulation('sim_dir')
sim.ini['section']['option']
sim.definitions['options']
```
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:
```python
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
```python
sim.vars
# or
sim[i].vars
# e.g. ['rho', 'vx1', 'vx2', 'vx3', 'prs']
```
The variable names in this list can be then accessed from the `PlutoData` objects:
```python
sim[0].rho
sim[-1].vx1
```
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(p.map(func, 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
try:
......@@ -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,
max=len(self)-1,
value=self._index(n)),
description="Simulation frame")
value=self._index(n)))
plot.children[0].description = "Simulation frame"
plot.children[0].layout.width = "20%"
display(plot)
except (NameError, ImportError):
pass
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