 |
Sapphire++
v1.1.0-204-g9dbe481 |
|
Sapphire++
v1.1.0-204-g9dbe481 |
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 [9] and [10].
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 the Astrophysical Plasma Theory group located at the Max-Planck-Institut für Kernphysik in Heidelberg, Germany.
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 the 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. There are a few common errors occurring during installation:
If the script aborts due to failed tests from a missing Fortran compiler. This sometimes occurs when testing the PETSc installation. You can try rerunning the script but skip the installation PETSc (it should be installed successfully already).
If the installation process is interrupted during the compilation of deal.II, this is often due to compiler running out of memory. At this stage, you can resume the installation with the following commands:
where X.X.X represents the version number of deal.II, and N specifies the number of threads to use for the compilation. To avoid memory issues, we recommend restarting the compilation with fewer threads.
For macOS user, deal.II offers prepackaged .dmg files with all dependencies included. To install, follow the deal.II Mac OS X Instructions.
If you have trouble installing deal.II, refer to the deal.II installation instructions.
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.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