struphy 3.1.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)
• 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.

Tutorials

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

Quick install

Quick install on your computer (using a virtual environment):

python -m venv struphy_env
source struphy_env/bin/activate
pip install -U pip
pip install -U struphy
struphy compile

In case you face troubles with install/compile:

1. check the prerequisites
2. visit trouble shooting

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.

Quick run

As an example, let’s say we want to solve Maxwell’s equations. We can use the CLI and generate a default launch file via

struphy params Maxwell

Hit yes when prompted - this will create the file params_Maxwell.py in your current working directory (cwd). You can open the file and - if you feel like it already - change some parameters, then run

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.

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

Documentation

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

• Install
• Userguide
• Available models
• Numerical methods

Get in touch

• Issues
• Discussions
• @spossann [e-mail] (Maintainer)
• @max-models [e-mail] (Maintainer)
• LinkedIn profile

Citing Struphy

• 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 2023, 263-271, Springer Nature Switzerland.