plasma-plots 0.1.0__tar.gz

plasma_plots-0.1.0/LICENSE

@@ -0,0 +1,16 @@
+Copyright (c) 2019-2026, Struphy developers, Max Planck Institute for Plasma Physics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and 
+associated documentation files (the "Software"), to deal in the Software without restriction, 
+including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, 
+and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, 
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial 
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT 
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

plasma_plots-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: plasma-plots
+Version: 0.1.0
+Summary: Plots and diagnostics of labeled xarray output from plasma simulations, such as Struphy
+Author-email: Max Lindqvist <max.lindqvist@ipp.mpg.de>
+License: MIT
+Project-URL: Homepage, https://github.com/struphy-hub/plasma-plots
+Project-URL: Repository, https://github.com/struphy-hub/plasma-plots
+Project-URL: Documentation, https://struphy-hub.github.io/plasma-plots
+Project-URL: Issues, https://github.com/struphy-hub/plasma-plots/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: xarray
+Requires-Dist: ipywidgets
+Provides-Extra: netcdf
+Requires-Dist: netCDF4; extra == "netcdf"
+Provides-Extra: pyvista
+Requires-Dist: pyvista; extra == "pyvista"
+Requires-Dist: imageio; extra == "pyvista"
+Provides-Extra: profiling
+Requires-Dist: scope-profiler[pproc]; extra == "profiling"
+Provides-Extra: plotly
+Requires-Dist: plotly; extra == "plotly"
+Requires-Dist: kaleido; extra == "plotly"
+Provides-Extra: gallery
+Requires-Dist: plotly; extra == "gallery"
+Requires-Dist: kaleido; extra == "gallery"
+Requires-Dist: scope-profiler[pproc]>=0.6.1; extra == "gallery"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: h5py; extra == "dev"
+Requires-Dist: griffe; extra == "dev"
+Provides-Extra: desc
+Requires-Dist: desc-opt; extra == "desc"
+Dynamic: license-file
+
+# 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](https://gprivate.com/6m80q).
+
+Plots and diagnostics of labeled xarray data from plasma simulations: the
+output of [Struphy](https://github.com/struphy-hub/struphy), and of any code
+whose arrays follow the same conventions (dimensions `t`, `eta1`/`eta2`/`eta3`,
+mapped coordinates `X`/`Y`/`Z`, see
+[Getting started](https://struphy-hub.github.io/plasma-plots/guides/getting-started/)).
+It also reads [GVEC](https://gvec.readthedocs.io)'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:
+
+```bash
+pip install plasma-plots
+pip install "plasma-plots[netcdf]"
+pip install "plasma-plots[netcdf,plotly]"
+```
+
+| Extra | Enables | Dependencies |
+| --- | --- | --- |
+| `netcdf` | Read netCDF3/netCDF4 files through xarray and the CLI | `netCDF4` |
+| `plotly` | Interactive browser plots and static Plotly exports | `plotly`, `kaleido` |
+| `pyvista` | 3-D scenes and rendering | `pyvista`, `imageio` |
+| `profiling` | Timing summaries and profiling plots | `scope-profiler[pproc]` |
+| `desc` | Evaluate DESC equilibria | `desc-opt` |
+| `gallery` | Export Struphy example-gallery figures and profiling | `plotly`, `kaleido`, `scope-profiler[pproc]>=0.6.1` |
+| `dev` | Tests, linting and documentation tooling | `pytest`, `ruff`, `h5py`, `griffe` |
+
+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`](https://github.com/struphy-hub/struphy/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:
+
+```python
+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)
+```
+
+> [!IMPORTANT]
+> For xarray data that doesn't come from an `Output`, `import plasma_plots`
+> first. Without it you get
+> `AttributeError: 'DataArray' object has no attribute 'plasma'`.
+
+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](API.md) (or
+`plasma-plots api`) is a one-page index of every accessor method and function, and
+[AGENTS.md](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](https://struphy-hub.github.io/plasma-plots/guides/command-line/)).
+
+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.

plasma_plots-0.1.0/README.md

@@ -0,0 +1,96 @@
+# 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](https://gprivate.com/6m80q).
+
+Plots and diagnostics of labeled xarray data from plasma simulations: the
+output of [Struphy](https://github.com/struphy-hub/struphy), and of any code
+whose arrays follow the same conventions (dimensions `t`, `eta1`/`eta2`/`eta3`,
+mapped coordinates `X`/`Y`/`Z`, see
+[Getting started](https://struphy-hub.github.io/plasma-plots/guides/getting-started/)).
+It also reads [GVEC](https://gvec.readthedocs.io)'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:
+
+```bash
+pip install plasma-plots
+pip install "plasma-plots[netcdf]"
+pip install "plasma-plots[netcdf,plotly]"
+```
+
+| Extra | Enables | Dependencies |
+| --- | --- | --- |
+| `netcdf` | Read netCDF3/netCDF4 files through xarray and the CLI | `netCDF4` |
+| `plotly` | Interactive browser plots and static Plotly exports | `plotly`, `kaleido` |
+| `pyvista` | 3-D scenes and rendering | `pyvista`, `imageio` |
+| `profiling` | Timing summaries and profiling plots | `scope-profiler[pproc]` |
+| `desc` | Evaluate DESC equilibria | `desc-opt` |
+| `gallery` | Export Struphy example-gallery figures and profiling | `plotly`, `kaleido`, `scope-profiler[pproc]>=0.6.1` |
+| `dev` | Tests, linting and documentation tooling | `pytest`, `ruff`, `h5py`, `griffe` |
+
+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`](https://github.com/struphy-hub/struphy/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:
+
+```python
+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)
+```
+
+> [!IMPORTANT]
+> For xarray data that doesn't come from an `Output`, `import plasma_plots`
+> first. Without it you get
+> `AttributeError: 'DataArray' object has no attribute 'plasma'`.
+
+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](API.md) (or
+`plasma-plots api`) is a one-page index of every accessor method and function, and
+[AGENTS.md](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](https://struphy-hub.github.io/plasma-plots/guides/command-line/)).
+
+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.

plasma_plots-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "plasma-plots"
+version = "0.1.0"
+description = "Plots and diagnostics of labeled xarray output from plasma simulations, such as Struphy"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Max Lindqvist", email = "max.lindqvist@ipp.mpg.de" }]
+requires-python = ">=3.11"
+dependencies = ["matplotlib", "numpy", "xarray", "ipywidgets"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+
+[project.scripts]
+plasma-plots = "plasma_plots.cli:main"
+
+[project.optional-dependencies]
+# Read netCDF3 and netCDF4 files through xarray (including the CLI).
+netcdf = ["netCDF4"]
+pyvista = ["pyvista", "imageio"]
+profiling = ["scope-profiler[pproc]"]
+# backend="plotly": interactive Plotly versions of the plots; kaleido saves them as PNG/SVG/PDF
+plotly = ["plotly", "kaleido"]
+# the output helpers of the struphy-hub example gallery (plasma_plots.gallery): Plotly figures,
+# their static PNGs (kaleido) and the profiling export, which needs scope-profiler 0.6.1 or newer
+gallery = ["plotly", "kaleido", "scope-profiler[pproc]>=0.6.1"]
+dev = ["pytest", "ruff", "h5py", "griffe"]
+# plasma_plots.from_desc: evaluating DESC equilibria (tests/test_desc.py, the DESC guide)
+desc = ["desc-opt"]
+
+[project.urls]
+Homepage = "https://github.com/struphy-hub/plasma-plots"
+Repository = "https://github.com/struphy-hub/plasma-plots"
+Documentation = "https://struphy-hub.github.io/plasma-plots"
+Issues = "https://github.com/struphy-hub/plasma-plots/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+# Restrict collection to our own tests: the struphy submodule now lives at
+# ./struphy (with its own nested feectools submodule), and bare `pytest`
+# would otherwise recurse into their test suites too -- and fail on their
+# own optional dependencies (e.g. psydac) that plasma-plots has no need of.
+testpaths = ["tests"]
+# Real struphy simulations (compiled kernels, ~1 min): skipped unless requested with
+# `pytest --run-simulations` (see tests/conftest.py); run in the docs workflow.
+markers = ["simulation: runs a real struphy simulation; needs compiled kernels"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]
+ignore = [
+    "E265",
+    "E402",
+    "E701",
+    "E722",
+    "E731",
+    "E741",
+    "E742",
+    "E743",
+    "E902",
+    "F401",
+    "F403",
+    "F405",
+    "F841",
+]

plasma_plots-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

plasma_plots-0.1.0/src/plasma_plots/__init__.py

@@ -0,0 +1,169 @@
+"""Plots and diagnostics of labeled xarray data from plasma simulations, such as Struphy's output.
+
+plasma-plots adds accessors to the objects Struphy returns; you rarely call a function directly:
+
+* ``out.plot`` and ``out.analysis`` on a Struphy ``Output``: whole-run plots and diagnostics.
+* ``array.plasma.plot``, ``.analysis`` and ``.data`` on every ``xarray.DataArray``, e.g. a product
+  from ``out.evaluate("em_fields/phi")``.
+* ``dataset.plasma.plot``, ``.analysis`` and ``.data`` on marker Datasets such as orbits.
+
+Creating a Struphy ``Output`` loads plasma-plots, so its output needs no import. For xarray data
+from elsewhere, ``import plasma_plots`` first; without it, ``.plasma`` raises
+``AttributeError: 'DataArray' object has no attribute 'plasma'``.
+
+Printing an accessor lists its methods (``print(phi.plasma.plot)``), and ``help()`` on a method
+shows every parameter (``help(phi.plasma.plot.slice)``). ``plasma-plots guide`` (or
+``python -m plasma_plots guide``) prints this guide, ``plasma-plots api`` an index of every method and
+function with its signature. The ``plasma-plots`` command also saves figures from the shell, e.g.
+``plasma-plots plot sim_1 em_fields/phi slice t=-1 eta3=0 -o phi.png`` or
+``plasma-plots quicklook sim_1 -o figures/`` (``plasma-plots --help``).
+
+A post-processing pipeline
+--------------------------
+>>> from struphy import Output  # doctest: +SKIP
+>>> out = Output("sim_1")  # the run's output folder
+>>> out.plot.energies().save("energies.png")  # the energy budget and its drift
+>>> # dims (t, eta1, eta2, eta3), coordinates X, Y, Z
+>>> phi = out.evaluate("em_fields/phi")
+>>> phi.plasma.plot.slice(coords="physical", plane="XY", t=-1, eta3=0).save(
+...     "phi.png"
+... )
+>>> phi.plasma.plot.animation(x="eta1", y="eta2", eta3=0).save(
+...     "phi.gif", writer="pillow"
+... )
+>>> # complex amplitudes over mode numbers m, n
+>>> modes = phi.plasma.analysis.mode_spectrum()
+>>> # the strongest (m, n) over time
+>>> phi.plasma.plot.mode_amplitudes(top=4, fit=True)
+>>> # guiding-center orbits, by orbit class
+>>> out.kinetic_ions.orbits.plasma.plot.poloidal()
+
+Selecting what to show
+----------------------
+Name every dimension a plot doesn't draw: an integer is a position (``t=-1`` the last, ``t=0`` the
+first) and a float the nearest coordinate value (``t=0.35``). Slices draw two dimensions: logical
+ones (``x="eta1", y="eta2"``), or physical ones with ``coords="physical", plane="XY"`` (or
+``"XZ"``, ``"YZ"``, ``"RZ"``). ``array.plasma.data.<plot>(...)`` returns the selected data a plot
+would draw, instead of the figure.
+
+What is where
+-------------
+* Time series and rates: ``plot.timeseries(fit=(t0, t1), reference=...)``,
+  ``analysis.growth_rate``, ``analysis.damping_rate``, ``analysis.envelope``,
+  ``analysis.oscillation_frequency`` (from zero crossings).
+* Profiles: ``plot.lineout``, ``plot.profiles``, ``plot.line_animation`` (``alongside=`` for
+  panels in sync), each with ``reference=`` for exact solutions; ``analysis.map_coordinate`` for
+  physical coordinates (``eta1`` → ``r`` in m).
+* Several plots in one figure: ``with plasma_plots.figure(2, 1) as fig:`` and ``ax=fig[0]``,
+  ``ax=fig[1]``.
+* 2-D fields: ``plot.slice``, ``plot.panels``, ``plot.animation``, ``plot.viewer``,
+  ``plot.frames``, with ``levels=`` (contour lines), ``overlays=`` (a second field's contours,
+  boundary, lines, points), ``symmetric=``, ``robust=``; ``plot.vector`` for vector fields.
+* 3-D views (``pip install "plasma-plots[pyvista]"``): ``plot.isosurface``, ``plot.slices_3d``,
+  ``plot.glyphs``, ``plot.streamlines``, ``plot.movie``; ``data.to_vtk`` for ParaView.
+* Spectra: ``analysis.time_fft``, ``analysis.spectral_peaks``, ``analysis.filter_time``,
+  ``analysis.mode_spectrum``, ``analysis.matrix_pencil``, ``analysis.cross_spectrum``;
+  ``plot.power_spectrum``, ``plot.spectrogram``, ``plot.mode_amplitudes``, ``plot.mode_profiles``.
+* Dispersion relations: ``plot.dispersion(branches=...)``, ``analysis.dispersion`` and
+  ``.plasma.analysis.trace_branch(theory)`` on the spectrum.
+* Comparing with theory: ``analysis.error(exact)``, ``plot.against_theory(theory)``,
+  ``analysis.project_mode``; convergence studies with ``plot.convergence``.
+* Vector calculus on mapped domains: ``analysis.gradient``, ``analysis.divergence``,
+  ``analysis.curl``, ``analysis.flux_function``, ``analysis.toroidal_components``.
+* Particles: ``dataset.plasma.plot.scatter``, ``.animation`` (``trail=``, ``paths=``,
+  ``color="classification"``), ``.paths``, ``.poloidal``,
+  ``.orbit_grid``, ``.orbit_classification``, ``.orbits_3d``; ``dataset.plasma.analysis.
+  classify_orbits``, ``.orbit_invariants``, ``.bounce_period``; binned distributions with
+  ``plot.slice(x="eta1", y="v1")`` and ``analysis.velocity_moments``.
+* Whole runs: ``out.plot.energies``, ``out.plot.scalars``, ``out.plot.equilibrium``,
+  ``out.plot.profile``; ``out.analysis.linear_mhd_energies``, ``out.analysis.time_fft``,
+  ``out.analysis.mode_spectrum``.
+* Integrals: ``plasma_plots.analysis.volume_integral`` and ``field_energy``;
+  ``analysis.surface_average`` for flux-surface averages.
+* GVEC equilibria: ``.plasma`` reads ``state.evaluate(...)`` itself, ``plasma_plots.from_gvec(ds)``
+  attaches the geometry to every variable; poloidal planes with
+  ``overlays={"coordinate_lines": {"rho": 4, "theta_P": 8}}`` (and ``plane="X1X2"``), ι with
+  ``plot.lineout(rationals=4)`` and ``analysis.rational_surfaces``.
+* DESC equilibria: ``plasma_plots.from_desc(eq, ["|B|", "iota", "sqrt(g)"], rho=11, theta=64,
+  zeta=40)`` evaluates them into the same flux-coordinate Datasets (``sfl="pest"`` for the PEST
+  angle ``theta_P``); DESC's names stay, ``ev["|B|"].plasma.plot...``.
+* Analytic theory to compare with (plain functions, not accessors): ``plasma_plots.theory.kinetic``
+  (Landau damping, beam instabilities, Weibel), ``.waves`` (MHD, Hall-MHD and cold-plasma waves,
+  drift waves, continua), ``.parameters`` (plasma parameters, Struphy's units), ``.orbits``,
+  ``.exact`` (Riemann problem, dam break, diffusion, ...) and ``.numerics`` (time-integrator and
+  discretization errors). Their functions go straight into ``branches=``, ``reference=`` and
+  ``theory=``, e.g. ``phi.plasma.plot.dispersion(branches={"kinetic": kinetic.langmuir})``.
+
+Plots return a ``PlotResult`` (``.fig``, ``.ax``, ``.save(path)``, ``.show()``); animations a
+``matplotlib.animation.FuncAnimation`` (keep a reference; ``.save("a.gif", writer="pillow")``); 3-D
+views a ``pyvista.Plotter`` (``.show()``, ``.screenshot(path)``; ``pyvista.OFF_SCREEN = True`` in
+scripts). Analysis methods return labeled xarray objects, which have ``.plasma`` in turn.
+
+Every Matplotlib plot also draws as an interactive Plotly figure (``pip install
+"plasma-plots[plotly]"``): ``phi.plasma.plot.slice(t=-1, eta3=0, backend="plotly")``, or
+``plasma_plots.set_backend("plotly")`` for all of them. The result is a ``PlotResult`` too
+(``.save("phi.html")``); animations and viewers get a slider. See
+:mod:`plasma_plots.plotly_backend`.
+
+Under MPI (``mpirun -n 4 python script.py``), plots are drawn and saved on rank 0 only; the other
+ranks get a ``SkippedPlot`` whose methods do nothing, so one script runs unchanged in serial and
+in parallel. Analysis runs on every rank. See :mod:`plasma_plots.mpi`.
+
+The functions behind the accessors, for plain ``xarray.DataArray`` input, are in
+``plasma_plots.plotting``, ``.analysis``, ``.spectral``, ``.spectral_plots``, ``.pyvista_plots``
+and ``.arrays``.
+
+Guides and the full reference: https://struphy-hub.github.io/plasma-plots (for language models:
+https://struphy-hub.github.io/plasma-plots/llms.txt).
+
+Example
+-------
+Runs as is, on synthetic data:
+
+>>> import matplotlib
+>>> matplotlib.use("Agg")
+>>> import numpy as np
+>>> import xarray as xr
+>>> import plasma_plots
+>>> t = np.linspace(0.0, 20.0, 201)
+>>> x = np.linspace(0.0, 1.0, 64, endpoint=False)
+>>> phi = xr.DataArray(
+...     0.01 * np.exp(0.1 * t)[:, None] * np.sin(2 * np.pi * x)[None],
+...     dims=("t", "eta1"),
+...     coords={"t": t, "eta1": x},
+...     name="phi",
+... )
+>>> # the k = 1 amplitude over t
+>>> amplitude = phi.plasma.analysis.project_mode(dim="eta1", number=1)
+>>> round(
+...     float(amplitude.plasma.analysis.growth_rate(window=(5.0, 20.0)).rate),
+...     3,
+... )
+0.1
+>>> result = phi.plasma.plot.slice(x="eta1", y="t")  # a space-time map
+>>> type(result).__name__
+'PlotResult'
+"""
+
+from . import \
+    output_accessors  # noqa: F401  (registers Output.plot, if struphy is installed)
+from .accessors import PlasmaAccessor
+from .desc import from_desc
+from .figures import figure
+from .gvec import from_gvec
+from .mpi import SkippedPlot, is_plotting_rank, mpi_rank
+from .plotly_backend import get_backend, set_backend
+from .plotting import save_figure
+
+__all__ = [
+    "SkippedPlot",
+    "PlasmaAccessor",
+    "figure",
+    "from_desc",
+    "from_gvec",
+    "get_backend",
+    "is_plotting_rank",
+    "mpi_rank",
+    "save_figure",
+    "set_backend",
+]

plasma_plots-0.1.0/src/plasma_plots/__main__.py

@@ -0,0 +1,11 @@
+"""``python -m plasma_plots``: the ``plasma-plots`` command (see :mod:`plasma_plots.cli`).
+
+Without a command it prints the package guide (the same as ``help(plasma_plots)``);
+``python -m plasma_plots api`` prints the API index (see ``API.md``).
+"""
+
+import sys
+
+from plasma_plots.cli import main
+
+sys.exit(main())