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).
