Welcome!

This is a Python package for solving partial differential equations (PDEs) mainly - but not exclusively - for plasma physics.

STRUPHY stands for STRUcture-Preserving HYbrid code (or STRUcture-preserving PHYsics 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, giving you the speed of Fortran or C while working within the familiar Python environment.

Explore Struphy on its website 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 - Copyright (c) 2019-2026, Struphy developers, Max Planck Institute for Plasma Physics.

Quick install

Struphy is available on PyPI, 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
2. visit trouble shooting

Examples

Ready-to-run simulations, each with a parameter file and a post-processing script, are in the repository 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: the electron distribution function f(x, v) at t = 0, 25 and 50, computed with the model VlasovAmpereOneSpecies 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 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.

Available models

Check the list of currently available models. If you want to see a particular model implemented, please let us know via issues.

Documentation

The doc is on Github pages, we recommend in particular to visit:

• Website (overview of models, numerics and examples)
• Install
• Userguide
• Available models
• Numerical methods

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

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)

This will show the domain and equilibrium magnetic field of the linear MHD model. You can find more examples in the documentation.

Tutorials on Binder

Get familiar with Struphy right away on mybinder - no installation needed.

Docker

If you want to get started right away without installing anything, you can use the Docker image - 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 (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
• Discussions
• @spossann stefan.possanner@ipp.mpg.de (Maintainer)
• @max-models max.lindqvist@ipp.mpg.de (Maintainer)
• LinkedIn profile

Publications

• D. Bell, M.C. Pinto, S. Possanner, E. Sonnendrücker, The linearized Vlasov–Maxwell system as a Hamiltonian system, 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, 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, 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, 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, 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, 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, Journal of Computational Physics 402, 109108 (2020).