struphy 3.4.0__tar.gz → 3.6.0__tar.gz

struphy-3.6.0/PKG-INFO

@@ -0,0 +1,300 @@
+Metadata-Version: 2.4
+Name: struphy
+Version: 3.6.0
+Summary: Multi-model plasma physics package
+Author: Max Planck Institute for Plasma Physics
+Author-email: stefan.possanner@ipp.mpg.de, max.lindqvist@ipp.mpg.de, eric.sonnendruecker@ipp.mpg.de
+License: 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.
+Project-URL: homepage, https://struphy-hub.github.io/struphy/index.html
+Project-URL: documentation, https://struphy-hub.github.io/struphy/index.html
+Project-URL: repository, https://github.com/struphy-hub/struphy
+Project-URL: changelog, https://github.com/struphy-hub/struphy/blob/devel/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/struphy-hub/struphy/issues
+Keywords: plasma physics, fusion, numerical modeling, partial differential equations, energetic particles
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<=2.5.0
+Requires-Dist: cunumpy<=0.7.0,>=0.6.3
+Requires-Dist: pyccel<=2.2.3,>=2.2.0
+Requires-Dist: maybempi>=0.1.2
+Requires-Dist: feectools<=0.10.0,>=0.10.0
+Requires-Dist: scipy<=1.18.0
+Requires-Dist: h5py<=3.16.0
+Requires-Dist: h5netcdf<=1.8.1
+Requires-Dist: xarray<=2026.9.0
+Requires-Dist: matplotlib<=3.11.0
+Requires-Dist: pyyaml<=6.0.3
+Requires-Dist: vtk<=9.7.0
+Requires-Dist: tqdm<=4.70.0
+Requires-Dist: argcomplete<=3.7.0
+Requires-Dist: ipywidgets<=8.1.8
+Requires-Dist: plotly<=7.1.0
+Requires-Dist: pyvista<=0.49.0
+Requires-Dist: trame<=4.0.0
+Requires-Dist: trame-vtk<=2.11.8
+Requires-Dist: trame-vuetify<=3.3.0
+Requires-Dist: nest_asyncio2<=1.7.2
+Requires-Dist: vtk<=9.7.0
+Requires-Dist: pytest<=9.1.0
+Requires-Dist: pytest-mpi<=0.6
+Requires-Dist: pytest-testmon<=2.2.0
+Requires-Dist: ruff==0.16.10
+Requires-Dist: line_profiler<=5.0.2
+Requires-Dist: scope-profiler<=0.7.3,>=0.5.0
+Provides-Extra: mpi
+Requires-Dist: mpi4py<=4.1.1; extra == "mpi"
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda12x; extra == "gpu"
+Provides-Extra: phys
+Requires-Dist: gvec<=1.5.0,>=1.1.0; extra == "phys"
+Requires-Dist: desc-opt<=0.17.1; extra == "phys"
+Provides-Extra: pproc
+Requires-Dist: plasma-plots>=0.1.0; extra == "pproc"
+Provides-Extra: dev
+Requires-Dist: struphy[mpi]; extra == "dev"
+Requires-Dist: struphy[pproc]; extra == "dev"
+Requires-Dist: notebook; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: nbstripout; extra == "dev"
+Requires-Dist: tomli-w; extra == "dev"
+Requires-Dist: kaleido; extra == "dev"
+Requires-Dist: pandas; extra == "dev"
+Requires-Dist: scope-profiler[pproc]; extra == "dev"
+Requires-Dist: slurm-script-generator>=0.3.6; extra == "dev"
+Provides-Extra: doc
+Requires-Dist: struphy[phys]; extra == "doc"
+Requires-Dist: struphy[pproc]; extra == "doc"
+Requires-Dist: jupyter; extra == "doc"
+Requires-Dist: nbconvert; extra == "doc"
+Requires-Dist: ipykernel; extra == "doc"
+Requires-Dist: sphinx; extra == "doc"
+Requires-Dist: sphinx-design; extra == "doc"
+Requires-Dist: lxml_html_clean; extra == "doc"
+Requires-Dist: sphinxcontrib-napoleon; extra == "doc"
+Requires-Dist: sphinx-copybutton; extra == "doc"
+Requires-Dist: sphinx-collections; extra == "doc"
+Requires-Dist: pydata-sphinx-theme; extra == "doc"
+Requires-Dist: nbsphinx; extra == "doc"
+Requires-Dist: m2r2; extra == "doc"
+Requires-Dist: myst-parser; extra == "doc"
+Requires-Dist: docutils; extra == "doc"
+Requires-Dist: ipyparallel; extra == "doc"
+Requires-Dist: scope-profiler[pproc]; extra == "doc"
+Provides-Extra: likwid
+Requires-Dist: struphy[dev]; extra == "likwid"
+Requires-Dist: pylikwid; extra == "likwid"
+Provides-Extra: all
+Requires-Dist: struphy[phys]; extra == "all"
+Requires-Dist: struphy[pproc]; extra == "all"
+Requires-Dist: struphy[dev]; extra == "all"
+Requires-Dist: struphy[mpi]; extra == "all"
+Requires-Dist: struphy[doc]; extra == "all"
+Requires-Dist: struphy[likwid]; extra == "all"
+Dynamic: license-file
+
+
+
+![STRUPHY Header](https://raw.githubusercontent.com/struphy-hub/.github/refs/heads/main/profile/struphy_header_with_subs.png)
+
+<p>
+
+<a href="https://github.com/struphy-hub/struphy/releases"><img src="https://img.shields.io/github/v/release/struphy-hub/struphy?label=Release" alt="Release"></a> <a href="https://github.com/struphy-hub/struphy/blob/devel/LICENSE"><img src="https://img.shields.io/badge/License-MIT-violet" alt="License"></a> <a href="https://mybinder.org/v2/gh/struphy-hub/struphy-tutorials/main"><img src="https://img.shields.io/badge/launch-tutorials-579ACA.svg?logo=data:image/png;base64,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" alt="badge"></a> <a href="https://github.com/struphy-hub/struphy/actions/workflows/scheduled-ubuntu.yml"><img src="https://github.com/struphy-hub/struphy/actions/workflows/scheduled-ubuntu.yml/badge.svg" alt="Ubuntu latest"></a> <a href="https://github.com/struphy-hub/struphy/actions/workflows/scheduled-macos.yml"><img src="https://github.com/struphy-hub/struphy/actions/workflows/scheduled-macos.yml/badge.svg" alt="MacOS latest"></a> <a href="https://github.com/struphy-hub/struphy/actions/workflows/static_analysis.yml"><img src="https://github.com/struphy-hub/struphy/actions/workflows/static_analysis.yml/badge.svg" alt="ruff"></a> <a href="https://pypi.org/project/struphy/"><img src="https://img.shields.io/pypi/v/struphy?label=PyPI" alt="PyPI"></a> <a href="https://pepy.tech/projects/struphy"><img src="https://img.shields.io/pepy/dt/struphy?label=PyPI%20downloads" alt="PyPI Downloads"></a>
+</p>
+
+# Welcome!
+
+**This is a Python package for solving partial differential equations (PDEs) mainly - but not exclusively - for plasma physics.**
+
+**STRUPHY** stands for **STRU**cture-**P**reserving **HY**brid code (or **STRU**cture-preserving **PHY**sics code). The package provides off-the-shelf models for plasma physics problems, such as
+
+- Maxwell’s equations
+- Magneto-hydrodynamics (MHD)
+- Multi-fluid models
+- Vlasov-Poisson and Vlasov-Maxwell kinetic models
+- Drift-kinetic models for strongly magnetized plasma
+- MHD-kinetic hybrid models
+
+All models can be run on multiple cores through MPI (distributed memory) and OpenMP (shared memory). The compute-intensive parts of the code are translated and compiled (“transpiled”) using [pyccel](https://github.com/pyccel/pyccel), giving you the speed of Fortran or C while working within the familiar Python environment.
+
+Explore Struphy on its website **[struphy-hub.github.io](https://struphy-hub.github.io/)**: the models and their equations, the numerical methods, domains, equilibria and a gallery of examples.
+
+The code is freely available under an [MIT license](https://github.com/struphy-hub/struphy/blob/devel/LICENSE) - Copyright (c) 2019-2026, Struphy developers, Max Planck Institute for Plasma Physics.
+
+![Max Planck Institute Logo](https://raw.githubusercontent.com/struphy-hub/.github/refs/heads/main/profile/MPI_PP_Logo_Vertical_E_green_rgb_centered.png)
+
+## Quick install
+
+Struphy is available on [PyPI](https://pypi.org/project/struphy/), so you can install it with pip:
+
+    pip install -U struphy
+    struphy compile -j 4
+
+`-j 4` compiles the kernels in parallel on four cores. In case you face troubles with install/compile:
+
+1.  check the [prerequisites](https://struphy-hub.github.io/struphy/sections/install.html#requirements)
+2.  visit [trouble shooting](https://struphy-hub.github.io/struphy/sections/install.html#trouble-shooting)
+
+## Examples
+
+Ready-to-run simulations, each with a parameter file and a post-processing script, are in the repository [struphy-examples](https://github.com/struphy-hub/struphy-examples), one folder per model and case. Its tags match the Struphy releases, so clone the tag of your installed version (`struphy --version`), for example
+
+```
+git clone --branch vX.Y.Z https://github.com/struphy-hub/struphy-examples.git
+cd struphy-examples/VlasovAmpereOneSpecies/two_stream
+python params_two_stream.py
+python pproc_two_stream.py
+```
+
+![Two-stream instability: phase space of the electrons at t = 0, 25 and 50](https://raw.githubusercontent.com/struphy-hub/struphy/main/doc/pics/readme_two_stream.png)
+
+*Two-stream instability: the electron distribution function f(x, v) at t = 0, 25 and 50, computed with the model [VlasovAmpereOneSpecies](https://struphy-hub.github.io/models/vlasov-ampere-one-species/) in a FEEC-PIC discretization (particle-in-cell markers for the electrons, finite element exterior calculus splines for the electric field). Two counter-streaming beams roll up into a phase-space vortex.*
+
+To look at finished examples and their results without running anything, browse the [examples gallery](https://struphy-hub.github.io/examples/) on the Struphy website.
+
+## AI coding agents
+
+Struphy ships a usage guide for AI coding agents (Claude Code, Codex, Copilot, Cursor, ...) that matches your installed version. It explains how to set up, run and post-process simulations. Print it with
+
+```
+struphy agents
+```
+
+To make it available in your own project, run this in the project folder:
+
+```
+struphy agents --install
+```
+
+This copies the Struphy skills (`setup-simulation`, `postprocess-simulation`) to `.claude/skills/` and adds a short pointer to the guide to `AGENTS.md` and `CLAUDE.md`, so your agent finds it automatically. Run it again after upgrading Struphy. Developers changing Struphy itself find the coding guidelines in [AGENTS.md](https://github.com/struphy-hub/struphy/blob/devel/AGENTS.md).
+
+## Available models
+
+Check the list of currently [available models](https://struphy-hub.github.io/struphy/sections/models.html). If you want to see a particular model implemented, please let us know via [issues](https://github.com/struphy-hub/struphy/issues).
+
+## Documentation
+
+The doc is on [Github pages](https://struphy-hub.github.io/struphy/index.html), we recommend in particular to visit:
+
+- [Website](https://struphy-hub.github.io/) (overview of models, numerics and examples)
+- [Install](https://struphy-hub.github.io/struphy/sections/install.html)
+- [Userguide](https://struphy-hub.github.io/struphy/sections/userguide.html)
+- [Available models](https://struphy-hub.github.io/struphy/sections/models.html)
+- [Numerical methods](https://struphy-hub.github.io/struphy/sections/numerics.html)
+
+The same doc is also on [Read the Docs](https://struphy.readthedocs.io/en/latest/), which also has the doc pages of older Struphy versions, starting from 3.1.0 (version menu of Read the Docs). The Read the Docs build does not execute the notebooks in the doc (e.g. the tutorials): they appear there without any outputs. The GitHub pages build executes them.
+
+## Example: solve Maxwell’s equations
+
+Use the command line to generate a default launch file:
+
+    struphy params Maxwell
+
+This will create `params_Maxwell.py` in your current working directory (cwd). You can open the file and - if you feel like it already - change some parameters. Start the simulation with
+
+    python params_Maxwell.py
+
+The default output is in `sim_1/` in your cwd. You can change the output path via the class `EnvironmentOptions` in the parameter file.
+
+For plots and diagnostics of the output, install [plasma-plots](https://struphy-hub.github.io/plasma-plots) with `pip install "struphy[pproc]"`; `Output` loads it automatically, adding `out.plot`, `out.analysis` and `.plasma.plot` on every product.
+
+Parallel simulations are run for example with
+
+    pip install -U mpi4py
+    mpirun -n 4 python params_Maxwell.py
+
+You can also put the run command in a batch script.
+
+## Python API
+
+Try out the Python API in a Jupyter notebook or any Python environment. For example, you can create a simulation object and show the domain and equilibrium magnetic field of the linear MHD model via
+
+``` python
+from struphy import (
+    Simulation,
+    domains,
+    equils,
+)
+from struphy.models import LinearMHD
+
+model = LinearMHD()
+
+domain = domains.DESCunit()
+equil = equils.DESCequilibrium(use_nfp=False)
+
+sim = Simulation(
+    model=model,
+    domain=domain,
+    equil=equil,
+)
+
+sim.show_domain(scalars="absB0", window_size = (850, 250), zoom_factor=2.0)
+```
+
+![](https://raw.githubusercontent.com/struphy-hub/struphy/main/README_files/figure-commonmark/cell-2-output-1.png)
+
+This will show the domain and equilibrium magnetic field of the linear MHD model. You can find more examples in the [documentation](https://struphy-hub.github.io/struphy/index.html).
+
+## Tutorials on Binder
+
+Get familiar with Struphy right away on [mybinder](https://mybinder.org/v2/gh/struphy-hub/struphy-tutorials/main) - no installation needed.
+
+## Docker
+
+If you want to get started right away without installing anything, you can use the [Docker image](https://hub.docker.com/r/spossann/struphy) - just pull and run:
+
+    docker pull spossann/struphy:main
+    docker run -it --rm spossann/struphy:main
+    ls struphy_*
+
+This will show three available Struphy environments, which you can activate for example via
+
+    source struphy_fortran_/env_fortran_/bin/activate
+
+There is also a [Docker image with just the prerequisites](https://hub.docker.com/r/spossann/ubuntu-for-struphy) (on Ubuntu), so you can install and compile Struphy on top of it yourself:
+
+    docker pull spossann/ubuntu-for-struphy:main
+    docker run -it --rm spossann/ubuntu-for-struphy:main
+
+## Get in touch
+
+- [Issues](https://github.com/struphy-hub/struphy/issues)
+- [Discussions](https://github.com/struphy-hub/struphy/discussions)
+- [@spossann](https://github.com/spossann) [stefan.possanner@ipp.mpg.de](mailto:spossann@ipp.mpg.de) (Maintainer)
+- [@max-models](https://github.com/max-models) [max.lindqvist@ipp.mpg.de](mailto:Max.Lindqvist@ipp.mpg.de) (Maintainer)
+- [LinkedIn profile](https://www.linkedin.com/company/struphy/)
+
+## Publications
+
+- D. Bell, M.C. Pinto, S. Possanner, E. Sonnendrücker,
+[**The linearized Vlasov–Maxwell system as a Hamiltonian system**](https://doi.org/10.1016/j.jcp.2026.114765),
+Journal of Computational Physics, Volume 555, 114765 (2026).
+
+- V. Carlier, M.C. Pinto, [**Variational discretizations of ideal magnetohydrodynamics in smooth regime using structure-preserving finite elements**](https://doi.org/10.1016/j.jcp.2024.113647),
+Journal of Computational Physics, Volume 523, 113647 (2025).
+
+- Y. Li, M.C. Pinto, F. Holderied, S. Possanner, E. Sonnendrücker, [**Geometric Particle-In-Cell discretizations of a plasma hybrid model with kinetic ions and mass-less fluid electrons**](https://doi.org/10.1016/j.jcp.2023.112671), Journal of Computational Physics 498, 112671 (2023).
+
+- S. Possanner, F. Holderied, Y. Li, B.-K. Na, D. Bell, S. Hadjout and Y. Güçlü, [**High-Order Structure-Preserving Algorithms for Plasma Hybrid Models**](https://link.springer.com/chapter/10.1007/978-3-031-38299-4_28), International Conference on Geometric Science of Information, 263-271, Springer Nature Switzerland (2023).
+
+- F. Holderied, S. Possanner, [**Magneto-hydrodynamic eigenvalue solver for axisymmetric equilibria based on smooth polar splines**](https://doi.org/10.1016/j.jcp.2022.111329), Journal of Computational Physics 464, 111329 (2022).
+
+- F. Holderied, S. Possanner, X. Wang, [**MHD-kinetic hybrid code based on structure-preserving finite elements with particles-in-cell**](https://doi.org/10.1016/j.jcp.2021.110143), Journal of Computational Physics 433, 110143 (2021).
+
+- F. Holderied, S. Possanner, A. Ratnani, X. Wang, [**Structure-preserving vs. standard particle-in-cell methods: The case of an electron hybrid model**](https://doi.org/10.1016/j.jcp.2019.109108), Journal of Computational Physics 402, 109108 (2020).

struphy-3.6.0/README.md

@@ -0,0 +1,189 @@
+
+
+![STRUPHY Header](https://raw.githubusercontent.com/struphy-hub/.github/refs/heads/main/profile/struphy_header_with_subs.png)
+
+<p>
+
+<a href="https://github.com/struphy-hub/struphy/releases"><img src="https://img.shields.io/github/v/release/struphy-hub/struphy?label=Release" alt="Release"></a> <a href="https://github.com/struphy-hub/struphy/blob/devel/LICENSE"><img src="https://img.shields.io/badge/License-MIT-violet" alt="License"></a> <a href="https://mybinder.org/v2/gh/struphy-hub/struphy-tutorials/main"><img src="https://img.shields.io/badge/launch-tutorials-579ACA.svg?logo=data:image/png;base64,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" alt="badge"></a> <a href="https://github.com/struphy-hub/struphy/actions/workflows/scheduled-ubuntu.yml"><img src="https://github.com/struphy-hub/struphy/actions/workflows/scheduled-ubuntu.yml/badge.svg" alt="Ubuntu latest"></a> <a href="https://github.com/struphy-hub/struphy/actions/workflows/scheduled-macos.yml"><img src="https://github.com/struphy-hub/struphy/actions/workflows/scheduled-macos.yml/badge.svg" alt="MacOS latest"></a> <a href="https://github.com/struphy-hub/struphy/actions/workflows/static_analysis.yml"><img src="https://github.com/struphy-hub/struphy/actions/workflows/static_analysis.yml/badge.svg" alt="ruff"></a> <a href="https://pypi.org/project/struphy/"><img src="https://img.shields.io/pypi/v/struphy?label=PyPI" alt="PyPI"></a> <a href="https://pepy.tech/projects/struphy"><img src="https://img.shields.io/pepy/dt/struphy?label=PyPI%20downloads" alt="PyPI Downloads"></a>
+</p>
+
+# Welcome!
+
+**This is a Python package for solving partial differential equations (PDEs) mainly - but not exclusively - for plasma physics.**
+
+**STRUPHY** stands for **STRU**cture-**P**reserving **HY**brid code (or **STRU**cture-preserving **PHY**sics code). The package provides off-the-shelf models for plasma physics problems, such as
+
+- Maxwell’s equations
+- Magneto-hydrodynamics (MHD)
+- Multi-fluid models
+- Vlasov-Poisson and Vlasov-Maxwell kinetic models
+- Drift-kinetic models for strongly magnetized plasma
+- MHD-kinetic hybrid models
+
+All models can be run on multiple cores through MPI (distributed memory) and OpenMP (shared memory). The compute-intensive parts of the code are translated and compiled (“transpiled”) using [pyccel](https://github.com/pyccel/pyccel), giving you the speed of Fortran or C while working within the familiar Python environment.
+
+Explore Struphy on its website **[struphy-hub.github.io](https://struphy-hub.github.io/)**: the models and their equations, the numerical methods, domains, equilibria and a gallery of examples.
+
+The code is freely available under an [MIT license](https://github.com/struphy-hub/struphy/blob/devel/LICENSE) - Copyright (c) 2019-2026, Struphy developers, Max Planck Institute for Plasma Physics.
+
+![Max Planck Institute Logo](https://raw.githubusercontent.com/struphy-hub/.github/refs/heads/main/profile/MPI_PP_Logo_Vertical_E_green_rgb_centered.png)
+
+## Quick install
+
+Struphy is available on [PyPI](https://pypi.org/project/struphy/), so you can install it with pip:
+
+    pip install -U struphy
+    struphy compile -j 4
+
+`-j 4` compiles the kernels in parallel on four cores. In case you face troubles with install/compile:
+
+1.  check the [prerequisites](https://struphy-hub.github.io/struphy/sections/install.html#requirements)
+2.  visit [trouble shooting](https://struphy-hub.github.io/struphy/sections/install.html#trouble-shooting)
+
+## Examples
+
+Ready-to-run simulations, each with a parameter file and a post-processing script, are in the repository [struphy-examples](https://github.com/struphy-hub/struphy-examples), one folder per model and case. Its tags match the Struphy releases, so clone the tag of your installed version (`struphy --version`), for example
+
+```
+git clone --branch vX.Y.Z https://github.com/struphy-hub/struphy-examples.git
+cd struphy-examples/VlasovAmpereOneSpecies/two_stream
+python params_two_stream.py
+python pproc_two_stream.py
+```
+
+![Two-stream instability: phase space of the electrons at t = 0, 25 and 50](https://raw.githubusercontent.com/struphy-hub/struphy/main/doc/pics/readme_two_stream.png)
+
+*Two-stream instability: the electron distribution function f(x, v) at t = 0, 25 and 50, computed with the model [VlasovAmpereOneSpecies](https://struphy-hub.github.io/models/vlasov-ampere-one-species/) in a FEEC-PIC discretization (particle-in-cell markers for the electrons, finite element exterior calculus splines for the electric field). Two counter-streaming beams roll up into a phase-space vortex.*
+
+To look at finished examples and their results without running anything, browse the [examples gallery](https://struphy-hub.github.io/examples/) on the Struphy website.
+
+## AI coding agents
+
+Struphy ships a usage guide for AI coding agents (Claude Code, Codex, Copilot, Cursor, ...) that matches your installed version. It explains how to set up, run and post-process simulations. Print it with
+
+```
+struphy agents
+```
+
+To make it available in your own project, run this in the project folder:
+
+```
+struphy agents --install
+```
+
+This copies the Struphy skills (`setup-simulation`, `postprocess-simulation`) to `.claude/skills/` and adds a short pointer to the guide to `AGENTS.md` and `CLAUDE.md`, so your agent finds it automatically. Run it again after upgrading Struphy. Developers changing Struphy itself find the coding guidelines in [AGENTS.md](https://github.com/struphy-hub/struphy/blob/devel/AGENTS.md).
+
+## Available models
+
+Check the list of currently [available models](https://struphy-hub.github.io/struphy/sections/models.html). If you want to see a particular model implemented, please let us know via [issues](https://github.com/struphy-hub/struphy/issues).
+
+## Documentation
+
+The doc is on [Github pages](https://struphy-hub.github.io/struphy/index.html), we recommend in particular to visit:
+
+- [Website](https://struphy-hub.github.io/) (overview of models, numerics and examples)
+- [Install](https://struphy-hub.github.io/struphy/sections/install.html)
+- [Userguide](https://struphy-hub.github.io/struphy/sections/userguide.html)
+- [Available models](https://struphy-hub.github.io/struphy/sections/models.html)
+- [Numerical methods](https://struphy-hub.github.io/struphy/sections/numerics.html)
+
+The same doc is also on [Read the Docs](https://struphy.readthedocs.io/en/latest/), which also has the doc pages of older Struphy versions, starting from 3.1.0 (version menu of Read the Docs). The Read the Docs build does not execute the notebooks in the doc (e.g. the tutorials): they appear there without any outputs. The GitHub pages build executes them.
+
+## Example: solve Maxwell’s equations
+
+Use the command line to generate a default launch file:
+
+    struphy params Maxwell
+
+This will create `params_Maxwell.py` in your current working directory (cwd). You can open the file and - if you feel like it already - change some parameters. Start the simulation with
+
+    python params_Maxwell.py
+
+The default output is in `sim_1/` in your cwd. You can change the output path via the class `EnvironmentOptions` in the parameter file.
+
+For plots and diagnostics of the output, install [plasma-plots](https://struphy-hub.github.io/plasma-plots) with `pip install "struphy[pproc]"`; `Output` loads it automatically, adding `out.plot`, `out.analysis` and `.plasma.plot` on every product.
+
+Parallel simulations are run for example with
+
+    pip install -U mpi4py
+    mpirun -n 4 python params_Maxwell.py
+
+You can also put the run command in a batch script.
+
+## Python API
+
+Try out the Python API in a Jupyter notebook or any Python environment. For example, you can create a simulation object and show the domain and equilibrium magnetic field of the linear MHD model via
+
+``` python
+from struphy import (
+    Simulation,
+    domains,
+    equils,
+)
+from struphy.models import LinearMHD
+
+model = LinearMHD()
+
+domain = domains.DESCunit()
+equil = equils.DESCequilibrium(use_nfp=False)
+
+sim = Simulation(
+    model=model,
+    domain=domain,
+    equil=equil,
+)
+
+sim.show_domain(scalars="absB0", window_size = (850, 250), zoom_factor=2.0)
+```
+
+![](https://raw.githubusercontent.com/struphy-hub/struphy/main/README_files/figure-commonmark/cell-2-output-1.png)
+
+This will show the domain and equilibrium magnetic field of the linear MHD model. You can find more examples in the [documentation](https://struphy-hub.github.io/struphy/index.html).
+
+## Tutorials on Binder
+
+Get familiar with Struphy right away on [mybinder](https://mybinder.org/v2/gh/struphy-hub/struphy-tutorials/main) - no installation needed.
+
+## Docker
+
+If you want to get started right away without installing anything, you can use the [Docker image](https://hub.docker.com/r/spossann/struphy) - just pull and run:
+
+    docker pull spossann/struphy:main
+    docker run -it --rm spossann/struphy:main
+    ls struphy_*
+
+This will show three available Struphy environments, which you can activate for example via
+
+    source struphy_fortran_/env_fortran_/bin/activate
+
+There is also a [Docker image with just the prerequisites](https://hub.docker.com/r/spossann/ubuntu-for-struphy) (on Ubuntu), so you can install and compile Struphy on top of it yourself:
+
+    docker pull spossann/ubuntu-for-struphy:main
+    docker run -it --rm spossann/ubuntu-for-struphy:main
+
+## Get in touch
+
+- [Issues](https://github.com/struphy-hub/struphy/issues)
+- [Discussions](https://github.com/struphy-hub/struphy/discussions)
+- [@spossann](https://github.com/spossann) [stefan.possanner@ipp.mpg.de](mailto:spossann@ipp.mpg.de) (Maintainer)
+- [@max-models](https://github.com/max-models) [max.lindqvist@ipp.mpg.de](mailto:Max.Lindqvist@ipp.mpg.de) (Maintainer)
+- [LinkedIn profile](https://www.linkedin.com/company/struphy/)
+
+## Publications
+
+- D. Bell, M.C. Pinto, S. Possanner, E. Sonnendrücker,
+[**The linearized Vlasov–Maxwell system as a Hamiltonian system**](https://doi.org/10.1016/j.jcp.2026.114765),
+Journal of Computational Physics, Volume 555, 114765 (2026).
+
+- V. Carlier, M.C. Pinto, [**Variational discretizations of ideal magnetohydrodynamics in smooth regime using structure-preserving finite elements**](https://doi.org/10.1016/j.jcp.2024.113647),
+Journal of Computational Physics, Volume 523, 113647 (2025).
+
+- Y. Li, M.C. Pinto, F. Holderied, S. Possanner, E. Sonnendrücker, [**Geometric Particle-In-Cell discretizations of a plasma hybrid model with kinetic ions and mass-less fluid electrons**](https://doi.org/10.1016/j.jcp.2023.112671), Journal of Computational Physics 498, 112671 (2023).
+
+- S. Possanner, F. Holderied, Y. Li, B.-K. Na, D. Bell, S. Hadjout and Y. Güçlü, [**High-Order Structure-Preserving Algorithms for Plasma Hybrid Models**](https://link.springer.com/chapter/10.1007/978-3-031-38299-4_28), International Conference on Geometric Science of Information, 263-271, Springer Nature Switzerland (2023).
+
+- F. Holderied, S. Possanner, [**Magneto-hydrodynamic eigenvalue solver for axisymmetric equilibria based on smooth polar splines**](https://doi.org/10.1016/j.jcp.2022.111329), Journal of Computational Physics 464, 111329 (2022).
+
+- F. Holderied, S. Possanner, X. Wang, [**MHD-kinetic hybrid code based on structure-preserving finite elements with particles-in-cell**](https://doi.org/10.1016/j.jcp.2021.110143), Journal of Computational Physics 433, 110143 (2021).
+
+- F. Holderied, S. Possanner, A. Ratnani, X. Wang, [**Structure-preserving vs. standard particle-in-cell methods: The case of an electron hybrid model**](https://doi.org/10.1016/j.jcp.2019.109108), Journal of Computational Physics 402, 109108 (2020).