struphy 3.4.0__tar.gz → 3.5.0__tar.gz

struphy-3.5.0/PKG-INFO

@@ -0,0 +1,298 @@
+Metadata-Version: 2.4
+Name: struphy
+Version: 3.5.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.9.0,>=0.9.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://pypi.org/project/struphy/"><img src="https://img.shields.io/pypi/dm/struphy.svg?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](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)
+
+## 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)
+```
+
+![](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.5.0/README.md

@@ -0,0 +1,187 @@
+
+
+![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://pypi.org/project/struphy/"><img src="https://img.shields.io/pypi/dm/struphy.svg?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](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)
+
+## 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)
+```
+
+![](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).