Metadata-Version: 2.4
Name: struphy
Version: 3.2.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.4.3
Requires-Dist: cunumpy<=0.1.1
Requires-Dist: pyccel<=2.2.3,>=2.2.0
Requires-Dist: feectools<=0.1.3
Requires-Dist: scipy<=1.17.1
Requires-Dist: h5py<=3.16.0
Requires-Dist: matplotlib<=3.10.8
Requires-Dist: pyyaml<=6.0.3
Requires-Dist: vtk<=9.6.1
Requires-Dist: tqdm<=4.68.1
Requires-Dist: argcomplete<=3.6.3
Requires-Dist: ipywidgets<=8.1.8
Requires-Dist: plotly<=6.8.0
Requires-Dist: pyvista<=0.48.0
Requires-Dist: trame<=3.13.0
Requires-Dist: trame-vtk<=2.11.8
Requires-Dist: trame-vuetify<=3.2.2
Requires-Dist: nest_asyncio2<=1.7.2
Requires-Dist: vtk<=9.6.1
Requires-Dist: pytest<=9.0.3
Requires-Dist: pytest-mpi<=0.6
Requires-Dist: pytest-testmon<=2.2.0
Requires-Dist: ruff<=0.15.12,>=0.15.0
Requires-Dist: line_profiler<=5.0.2
Requires-Dist: scope-profiler<=0.1.9,>=0.1.7
Provides-Extra: mpi
Requires-Dist: mpi4py<=4.1.1; extra == "mpi"
Provides-Extra: phys
Requires-Dist: gvec<=1.4.1,>=1.1.0; extra == "phys"
Requires-Dist: desc-opt<=0.17.1; extra == "phys"
Provides-Extra: dev
Requires-Dist: struphy[mpi]; extra == "dev"
Requires-Dist: notebook; extra == "dev"
Requires-Dist: autopep8; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: ssort; extra == "dev"
Requires-Dist: add-trailing-comma; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: nbstripout; extra == "dev"
Requires-Dist: tabulate; extra == "dev"
Requires-Dist: tomli-w; extra == "dev"
Requires-Dist: kaleido; extra == "dev"
Requires-Dist: pandas; extra == "dev"
Provides-Extra: doc
Requires-Dist: struphy[phys]; 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"
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[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="isort and 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.

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

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)

## 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](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:

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

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