Quick Start¶

Installation¶

pip install emout

For 3D visualization with PyVista:

pip install "emout[pyvista]"

Dask-based remote execution is automatically available on Python 3.10+ (no extra install needed).

Loading Simulation Data¶

import emout

data = emout.Emout("output_dir")

Emout scans the directory for HDF5 files and the parameter file (plasma.inp or plasma.toml). Variable names are resolved from the EMSES filename convention:

Attribute	Source file pattern	Description
`data.phisp`	`phisp00_0000.h5`	Electrostatic potential
`data.nd1p`	`nd1p00_0000.h5`	Species-1 number density
`data.j1x`	`j1x00_0000.h5`	Species-1 current density (x)
`data.ex`	`ex00_0000.h5`	Electric field (x)
`data.bz`	`bz00_0000.h5`	Magnetic field (z)
`data.rex`	relocated from `ex`	Relocated electric field (x)
`data.j1xy`	`j1x` + `j1y`	2D vector (auto-combined)
`data.j1xyz`	`j1x` + `j1y` + `j1z`	3D vector (auto-combined)
`data.icur`	`icur` (text)	Current data (pandas DataFrame)
`data.pbody`	`pbody` (text)	Conductor data (pandas DataFrame)

Each attribute is a time-series object. Indexing by timestep returns a NumPy-compatible array:

len(data.phisp)       # Number of timesteps
data.phisp[0].shape   # (nz, ny, nx)
data.phisp[-1]        # Last timestep

Your First Plot¶

# 2D color map of potential on the xz-plane (y = ny/2) at the last timestep
data.phisp[-1, :, data.inp.ny // 2, :].plot()

After slicing out a 2D or 1D array, call .plot() to visualize it with SI unit labels.

Note: slice axis order is (t, z, y, x) — this is the reverse of the (x, y, z) convention you may be used to from NumPy. The example above reads as t=-1 (last step), z=: (all), y=ny/2 (fixed), x=: (all), which produces an xz-plane. Every slice expression in emout uses this order, so rewrite slices copied in from other code before using them.

Appended Simulation Outputs¶

If the simulation continued into additional directories:

# Automatic detection
data = emout.Emout("output_dir", ad="auto")

# Manual specification
data = emout.Emout("output_dir", append_directories=["output_dir_2", "output_dir_3"])

Particle Data¶

EMSES particle outputs are automatically grouped by species:

p4 = data.p4              # Species 4
p4.x, p4.y, p4.z          # Position time series
p4.vx, p4.vy, p4.vz       # Velocity time series
p4.tid                     # Trace ID

# Convert to pandas Series
data.p4.vx[0].val_si.to_series().hist(bins=200)