# plasma_plots.cli

*module*

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.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/cli.py#L1-L1)

## plasma_plots.cli.WHOLE

*attribute* · *module attribute*

```python
WHOLE = '.'
```

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

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/cli.py#L29-L29)

## plasma_plots.cli.CLIError

*class*

```python
class CLIError(Exception)
```

Bases: `Exception`

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

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/cli.py#L56-L57)

## plasma_plots.cli.main

*function*

```python
def main(argv=None) -> int
```

Run the ``plasma-plots`` command.

**Parameters**

- `argv` (`list of str`) (default: `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**

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

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/cli.py#L1113-L1171)

## plasma_plots.cli.open_source

*function*

```python
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**

- `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()`][plasma_plots.gvec.from_gvec].

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/cli.py#L76-L121)

## plasma_plots.cli.parse_value

*function*

```python
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**

- `text` (`str`) — The value as typed.
- `source` (`struphy.Output or xarray.Dataset`) (default: `None`) — Where ``@name`` looks up products.

**Returns**

- (`object`) — The value.

**Examples**

```pycon
>>> 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)
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/cli.py#L164-L199)

## plasma_plots.cli.plot_methods

*function*

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

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

**Parameters**

- `obj` (`(xarray.DataArray, xarray.Dataset or struphy.Output)`) — A product, or a run.
- `show` (`bool`) (default: `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.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/cli.py#L250-L278)

## plasma_plots.cli.quicklook

*function*

```python
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()`][plasma_plots.cli.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**

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

**Returns**

- (`list of str`) — The files written.

**Examples**

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

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/cli.py#L530-L661)

## plasma_plots.cli.quicklook_plot

*function*

```python
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**

- `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**

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

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/cli.py#L487-L523)