About

Sapphire++ is an acronym and stands for \"Simulating astrophysical plasmas and particles with highly relativistic energies in C++\".

It is a code to simulate the interaction of charged particles with a background plasma, a typical example is the propagation and acceleration of cosmic rays. To this end it solves a Vlasov-Fokker-Planck (VFP) equation in mixed coordinates, namely

$$ \frac{\partial f}{\partial t} + (\mathbf{u} + \mathbf{v}) \cdot \nabla{x} f - \gamma m \frac{\mathrm{D} \mathbf{u}}{\mathrm{D} t} \cdot \nabla{p}f - \mathbf{p} \cdot\nabla{x} \mathbf{u}\cdot \nabla{p} f + q \mathbf{v} \cdot \left( \mathbf{B} \times \nabla{p} f \right) = \frac{\nu}{2} \Delta{\theta, \varphi} f + S . $$

Sapphire++ is developed by Nils Schween, Florian Schulze and Brian Reville members of the Astrophysical Plasma Theory group located at the Max-Planck-Institut für Kernphysik in Heidelberg, Germany.

Installation

Sapphire++ builds on top of the deal.II finite element library. To install deal.II and other prerequisites for Sapphire++ we provide an installation script. Run the script by executing:

shell chmod u+x install-dealii.sh ./install-dealii.sh

To download Sapphire++ itself, you can either get the latest release as a tarball on the release page or clone the repository:

shell git clone https://github.com/sapphirepp/sapphirepp

Afterwards you can compile Sapphire++, with cmake and make:

shell cd sapphirepp export DEAL_II_DIR="path/to/deal.II" cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DEXAMPLES=ON make --directory=build

A detailed description of the installation process can be found in the documentation.

Getting started

To run Sapphire++ you need to provide a parameter file:

shell ./build/sapphirepp parameter-template.prm

You enable parallel execution by using mpirun:

shell mpirun -np N ./build/sapphirepp parameter-template.prm

where N is the number of processors to use.

Comprehensive documentation is available on our website sapphire.org. There, you can find a quick-start guide and various tutorials. The source code for the examples is located in the examples folder.

If you have any questions, feel free to reach out to us via the GitHub Discussions page for support and community interaction.

Contributing

We welcome contributions to Sapphire++. If you want to contribute code, please follow the contribution guidelines and our code of conduct.

Licence and citation

Sapphire++ is distributed under the LGPL 3.0 license.

If you use Sapphire++ in your research, please cite the following paper and the software:

Schween, N. W. and Schulze, F. and Reville, B., Sapphire++: A Particle Transport Code Combining a Spherical Harmonic Expansion and the Discontinuous Galerkin Method, 2025, DOI: https://doi.org/10.1016/j.jcp.2024.113690

bibtex @article{Sapphirepp2025, title = {Sapphire++: A particle transport code combining a spherical harmonic expansion and the discontinuous Galerkin method}, journal = {Journal of Computational Physics}, volume = {523}, pages = {113690}, year = {2025}, issn = {0021-9991}, doi = {https://doi.org/10.1016/j.jcp.2024.113690}, url = {https://www.sciencedirect.com/science/article/pii/S0021999124009380}, author = {Nils W. Schween and Florian Schulze and Brian Reville}, keywords = {Numerical methods, Vlasov-Fokker-Planck, Cosmic rays, Discontinuous Galerkin method, Spherical harmonics, Particle acceleration}, abstract = {We present Sapphire++, an open-source code designed to numerically solve the Vlasov–Fokker–Planck equation for astrophysical applications. Sapphire++ employs a numerical algorithm based on a spherical harmonic expansion of the distribution function, expressing the Vlasov–Fokker–Planck equation as a system of partial differential equations governing the evolution of the expansion coefficients. The code utilises the discontinuous Galerkin method in conjunction with implicit and explicit time stepping methods to compute these coefficients, providing significant flexibility in its choice of spatial and temporal accuracy. We showcase the code's validity using examples. In particular, we simulate the acceleration of test particles at a parallel shock and compare the results to analytical predictions. The Sapphire++ code Image 1 is available as a free and open-source tool for the community.} }

The reference to the Sapphire++ software can be found on Zenodo.

Sapphire++ builds on top of the deal.II library. We therefore strongly encourage you to cite the deal.II library as well.