plasma-plots

Note: This library is 100% written by AI, I have literally not looked at a single line of code. So why should you trust it? You should trust it because of the following LEAN 4 PROOF.

Plots and diagnostics of labeled xarray data from plasma simulations: the output of Struphy, and of any code whose arrays follow the same conventions (dimensions t, eta1/eta2/eta3, mapped coordinates X/Y/Z, see Getting started). It also reads GVEC's equilibrium evaluations directly. It is a separate package, so it can evolve and release independently of the Struphy runtime.

Full documentation: https://struphy-hub.github.io/plasma-plots

Installation

Python 3.11 or newer is required; CI tests Python 3.11 and 3.12. The base install plots in-memory xarray data. Install extras for file formats and optional renderers:

pip install plasma-plots
pip install "plasma-plots[netcdf]"
pip install "plasma-plots[netcdf,plotly]"

Struphy, GVEC and Zarr are separate installations; no extra above installs them. Struphy users need the compatible output API described below. Install gvec for GVEC evaluation or zarr to open Zarr stores. MP4 export requires system ffmpeg; Matplotlib windows require a working GUI/display, and static Plotly exports through Kaleido require a compatible Chrome installation.

For development, install with pip install -e ".[dev]".

Struphy compatibility

Struphy integration is tested against commit caddd229a3fcba1fada577d1af46d012e93d8b49 (the repository's pinned submodule, reporting version 3.3.0). Use that revision for a reproducible installation; compatibility with other Struphy revisions, including older published builds, is not guaranteed. Struphy is optional when working with ordinary xarray data.

Usage

Creating a Struphy Output loads plasma-plots, which registers out.plot, out.analysis and the .plasma accessor on every product:

from struphy.post_processing.output import Output

out = Output("path/to/run")
out.evaluate("em_fields/phi").plasma.plot.slice(x="eta1", y="eta2", t=-1)

In Python, import plasma_plots; help(plasma_plots) (or plasma-plots guide in a terminal) gives an overview, printing an accessor lists its methods (print(phi.plasma.plot)), and help() on a method shows every parameter. For language models and coding agents, the documentation is available as plain text at https://struphy-hub.github.io/plasma-plots/llms.txt. API.md (or plasma-plots api) is a one-page index of every accessor method and function, and AGENTS.md explains the code for agents working on it.

From the shell, the plasma-plots command saves figures of a Struphy run folder or a netCDF file without any Python: plasma-plots info sim_1, plasma-plots plot sim_1 em_fields/phi slice t=-1 eta3=0 -o phi.png, plasma-plots quicklook sim_1 -o figures/ (see the command-line guide).

Direct plotting functions are available from plasma_plots.plotting; analysis functions are in plasma_plots.analysis.

The accessor provides time-series, lineout, slice, panel, vector, comparison, animation, and marker-trajectory plots. For three-dimensional scalar fields, install the optional PyVista dependency (pip install plasma-plots[pyvista]) and use field.plasma.plot.volume(t=-1), then call show() on the returned plotter.

Every Matplotlib plot can also be an interactive Plotly figure, with hover values, zoom and, for animations, a slider: pip install plasma-plots[plotly] and pass backend="plotly" (field.plasma.plot.slice(t=-1, backend="plotly")), or call plasma_plots.set_backend("plotly") once.