plasma_plots.cli

The plasma-plots command: quick looks at simulation output without writing Python.

Installed as plasma-plots (also python -m plasma_plots). It opens a Struphy run folder (as a Struphy Output) or any file xarray can read (netCDF, zarr, …) and saves or displays figures of it. It has no plot options of its own: plot calls an accessor method by name with key=value arguments, so every plot method works from the command line::

plasma-plots info sim_1
plasma-plots plot sim_1 em_fields/phi slice t=-1 eta3=0 -o phi.png
plasma-plots plot sim_1 . energies -o energies.html
plasma-plots plot sim_1 . energies -o energies.tex
plasma-plots plot sim_1 em_fields/phi slice t=-1 eta3=0 --show
plasma-plots movie sim_1 em_fields/phi eta3=0 -o phi.gif
plasma-plots quicklook sim_1 -o figures/

plasma-plots guide prints the package guide, plasma-plots api the API index.

Attributes

Name	Description
WHOLE	The PRODUCT that names the whole source: the run (out.plot) or the file's Dataset.

Classes

Name	Description
CLIError	A problem with the command line or its data, reported without a traceback.

Functions

Name	Description
main	Run the plasma-plots command.
open_source	Open path: a Struphy Output for a run folder, else an xarray.Dataset.
parse_value	A key=value value as Python: an int, a float, a bool, None, a list or a string.
plot_methods	The plot methods of obj available to plasma-plots plot.
quicklook	Save or display the standard figures of source; return the files written.
quicklook_plot	The plot method and options of a quick look at array, or None if there is none.

WHOLEattributemodule attribute#

View source

WHOLE = '.'

The PRODUCT that names the whole source: the run (out.plot) or the file’s Dataset.

CLIErrorclass#

View source

class CLIError(Exception)

Bases: Exception

A problem with the command line or its data, reported without a traceback.

mainfunction#

View source

def main(argv=None) -> int

Run the plasma-plots command.

Parameters

Name	Type	Default	Description
argv	list of str	None	The arguments after the command name. Default: sys.argv[1:].

Returns

int

The exit code: 0 on success, 1 on an error (with a diagnostic), 2 on a usage error (from argparse, which exits itself).

Examples

>>> main(
...     [
...         "plot",
...         "sim_1",
...         "em_fields/phi",
...         "slice",
...         "t=-1",
...         "eta3=0",
...         "-o",
...         "phi.png",
...     ]
... )
0

open_sourcefunction#

View source

def open_source(path)

Open path: a Struphy Output for a run folder, else an xarray.Dataset.

Struphy runs are automatically post-processed with default options when needed. Existing processed output is reused.

Parameters

Name	Type	Description
path	str or pathlib.Path	A Struphy run folder, or a file (or zarr store) that xarray.open_dataset reads.

Returns

struphy.Output or xarray.Dataset

The opened output. A GVEC Dataset is converted with plasma_plots.from_gvec().

parse_valuefunction#

View source

def parse_value(text: str, source=None)

A key=value value as Python: an int, a float, a bool, None, a list or a string.

An integer stays an int (a position, t=-1) and a decimal number becomes a float (the nearest coordinate value, t=0.35). true/false/none are True, False and None; text starting with [ or { is JSON; commas make a list (eta3=0,0.25,0.5); @name is another product of the same source (e.g. other=@phi). Anything else is a string.

Parameters

Name	Type	Default	Description
text	str	required	The value as typed.
source	struphy.Output or xarray.Dataset	None	Where @name looks up products.

Returns

object

The value.

Examples

>>> parse_value("-1"), parse_value("0.35"), parse_value("eta1")
(-1, 0.35, 'eta1')
>>> parse_value("0,0.5"), parse_value("none")
([0, 0.5], None)

plot_methodsfunction#

View source

def plot_methods(obj, *, show=False) -> list[str]

The plot methods of obj available to plasma-plots plot.

Parameters

Name	Type	Default	Description
obj	(xarray.DataArray, xarray.Dataset or struphy.Output)	required	A product, or a run.
show	bool	False	Include interactive viewers and PyVista scenes. Default: False.

Returns

list of str

Method names; profile.gantt style for the profiling plots of a run.

quicklookfunction#

View source

def quicklook(source, directory=None, *, formats=('png'), dpi=None, log=None, show=False, products=None, selection=None) -> list[str]

Save or display the standard figures of source; return the files written.

For a Struphy run: the energy budget and the scalars, the equilibrium, and a quick look (quicklook_plot()) at every other product; for a Dataset, a quick look at every variable. A figure that fails is reported through log and skipped.

Parameters

Name	Type	Default	Description
source	struphy.Output or xarray.Dataset	required	What to plot, as open_source() returns it.
directory	str or pathlib.Path	None	Where to save the figures; created if needed. Omit to only display them.
formats	sequence of str	('png')	File formats, each of every figure, e.g. ("png", "html"). Default: ("png",).
dpi	int	None	Resolution of images.
log	callable	None	Receives one line per figure written or skipped. Default: print.
show	bool	False	Display each figure; close its window to continue. Default: False.
products	sequence of str	None	Only draw these products, omitting the standard run overview plots.
selection	dict	None	Dimension selections shared by products: integers index, other numbers select nearest coordinates.

Returns

list of str

The files written.

Examples

>>> quicklook(out, "figures", formats=("png", "html"))

quicklook_plotfunction#

View source

def quicklook_plot(array) -> tuple[str, dict] | None

The plot method and options of a quick look at array, or None if there is none.

A time series draws timeseries; a field with one drawn dimension a lineout and one with two or more a slice of its first two (logical ones first), each at t=-1 and at position 0 of every other dimension (e.g. component=0, eta3=0). Marker Datasets draw their trajectories.

Parameters

Name	Type	Description
array	xarray.DataArray or xarray.Dataset	A product.

Returns

tuple of (str, dict) or None

The plot method’s name and its keyword arguments.

Examples

>>> quicklook_plot(phi)  # dims t, eta1, eta2, eta3
('slice', {'x': 'eta1', 'y': 'eta2', 't': -1, 'eta3': 0})