struphy 3.2.0

Multi-model plasma physics package

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.

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

In case you face troubles with install/compile:

1. check the prerequisites
2. visit trouble shooting

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.

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.

Available models

Check the list of currently available models in the documentation. 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:

• Install
• Userguide
• Available models
• Numerical methods

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 [e-mail] (Maintainer)
• @max-models [e-mail] (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).