 |
Sapphire++
v1.2.0-61-g8c25586 |
|
Sapphire++
v1.2.0-61-g8c25586 |
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\, . \]
\(f\) is the distribution function of the particles, i.e. their number density in phase space. \(\mathbf{u}\) is the velocity of the background plasma, e.g. the velocities of a plasma around a collisionless shock as observed after supernova explosions. Note that the momentum \(\mathbf{p}\) is given in mixed coordinates, meaning it is defined relative to the background field \(\mathbf{u}\). \(\mathbf{B}\) is mean magnetic field of this plasma. \(S\) is a source term representing the injection of the charged particles. They interact with the background plasma via isotropic and elastic scattering off fluctuations of the plasma's mean electromagnetic fields. \(\nu\) is the corresponding scattering frequency. \(\mathbf{u}\), \(\mathbf{B}\), \(S\) and \(\nu\) are the input of the simulation and can be analytical functions of \(t, \mathbf{x}\) and \(p\). The distribution function \(f\) is its output.
Sapphire++ tries to exploit that the distributions of energetic and charged particles are in many physical environments almost isotropic. It, thus, expresses \(f\) as a series of spherical harmonics, i.e.
\[ f(t, \mathbf{x}, \mathbf{p}) = \sum^{\infty}_{l = 0} \sum^{l}_{m = 0} \sum^{1}_{s = 0} f_{lms}(t, \mathbf{x}, p) Y_{lms}(\theta,\varphi) \, , \]
where \(\mathbf{p} = p \, (\cos\theta, \sin\theta \cos\varphi, \sin\theta \sin\varphi)^T\) is used. The zeroth order term is the isotropic part and higher order terms represent the anisotropies of the distribution function. Sapphire++ computes the expansion coefficients \(f_{lms}\), hence it solves a system of partial differential equations (PDEs), which is derived from the above VFP equation.
A distinguishing feature of Sapphire++ is that it solves this system of PDEs by applying the discontinuous Galerkin (dG) method. The dG method is a finite element method which is particularly suited for the shown VFP equation.
The full implementation details can be found in [10] and [11].
Even though primarily developed in the context of cosmic-ray physics, Sapphire++ can be applied in the context of inertial confinement fusion, or for example to compute the transport of radiation (interpreting \(f\) as the intensity).
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.
You can install Sapphire++ either from source or use Docker.
Sapphire++ uses the C++ library deal.II to solve the differential equations with finite elements. We use MPI to parallelize Sapphire++. For optimized parallel grid generation and linear algebra operations, we use p4est and PETSc through their interface in deal.II. In order to compile and use Sapphire++ you need the following programs installed:
dotTo install deal.II and all necessary prerequisites for Sapphire++, we provide an installation script. Download the script and it with run the script by executing:
Follow the on-screen instructions during the installation process. If you encounter any problems during installation please refer to the designated Installation Issues Discussion.
You can obtain Sapphire++ either as a tarball from the release page, or by cloning the git repository:
Afterwards you can compile Sapphire++, with cmake and make:
Developers are advised to use the following cmake options:
Release build before starting extensive simulation runs.A pre-built Docker container is available on Docker Hub.
Pull the container from Docker Hub:
Start the container (no edits):
To use the precompiled version of Sapphire++ use:
Results will be saved in your local results folder.
Start the container with persistent source access:
To keep changes to the source code, clone the Sapphire++ repository and mount it to the container:
Now you can edit files on your host and compile inside the container:
Results will be saved in your local sapphirepp/results folder.
To run Sapphire++, you need to provide a parameter file:
You enable parallel execution by using mpirun:
where N is the number of processors to use.
For a brief introduction, refer to our quick-start guide. Additional information and detailed examples can be found in the examples section.
If you have any questions, feel free to reach out to us via the GitHub Discussions page for support and community interaction.
1.12.0