darkprop C++ Library
The core of DarkProp is a header only template library which can be used by including the header files. The advantage of using the library directly is that you can flexibly customize the simulation and extend the physical models through inheritance.
The template parameters are Vector and Value. The internal Vector type
darkprop::Vector3d and the Value type double will be used by default.
Alternatively, Eigen::Vector3d in the Eigen 3
library has also been tested.
Warning
Since DarkProp uses the natural unit system with \(\text{GeV}\equiv 1\), the
Value type cannot be float. In general use double. long double is also
supported, but it is generally only used in test situations with precision requirements
due to the lower efficiency.
Usage
The DarkProp library should be available after the cmake installation. To use the library simply include the needed headers in your source code like this
#include <darkprop/core.hpp>
#include <darkprop/IO.hpp> // optional hdf5 io
Below is an working example.
Example
1/*
2 * Simulate 50 trajectories.
3 */
4
5#include <iostream>
6#include <string>
7#include <fstream>
8#include <filesystem>
9#include "darkprop/core.hpp"
10
11int main(void)
12{
13 using namespace darkprop::constants; // using rEarth
14 using namespace darkprop::units; // using cm, GeV, sec
15
16 double sigma = 1e-32 * cm * cm; // cross section
17 double mchi = 10 * GeV; // DM mass
18 double t = 0.0; // initial time
19
20 double vcut = 1.0 * cm / sec; // cutoff velocity
21 double Tcut = 0.5 * mchi * vcut * vcut; // cutoff kinetic energy
22
23 // initial position (constants::rEarth is defined in Const.hpp)
24 darkprop::Vector3d init_r(0.0, 0.0, rEarth);
25
26 // initial velocity
27 double vi = 220.0 * km / sec;
28 darkprop::Vector3d init_v(0.0, 0.0, -vi);
29
30 // instantiating the DM particle and the Earth
31 darkprop::SIDM dm(sigma, mchi, t);
32 darkprop::HomoEarth earth;
33
34 // need a random number generator
35 darkprop::RandomNumber rn;
36
37 std::filesystem::create_directory("out");
38
39 // simulate 50 tracks
40 std::size_t number_of_tracks = 50;
41 for (std::size_t i = 0; i < number_of_tracks; ++i) {
42 dm.t = 0.0; // time is not used in this case
43 dm.setR(init_r); // reset position
44 dm.setV(init_v); // reset velocity
45 dm.in_medium = true; // reset the flag
46
47 // simulate full trajectory
48 auto events = simulate_track(dm, earth, Tcut, rn);
49
50 // output: only store the position of all events in csv files
51 std::string filename = "out/trajectory-";
52 filename = filename + std::to_string(i) + ".csv";
53 std::ofstream off(filename);
54 off << std::scientific;
55 off.precision(16);
56 for (const auto& event : events) {
57 off << event.r[0] << " "
58 << event.r[1] << " "
59 << event.r[2] << std::endl;
60 }
61 }
62 return 0;
63}
Simulation Outline
The input of a simulation is the initial state of the incident particle (initial position,
momentum, kinetic energy, and time, etc.). They can be set using the
basic interface defined in the Particle base class.
The Initialization.hpp file provides some functions to produce DM with specific
distributions. The Injector.hpp file provides some Injectors for typical
particle injection scenarios.
The output of DarkProp’s built-in simulation functions is a
std::vector of Event (std::vector<Event>). Users can freely write their
functions to store or analyze these data. DarkProp provides tool functions in IO.hpp
for storing data in HDF5 format. The HDF5 format is suitable for storing large data sets in
scientific computing and widely supported by various programming languages.
To perform a simulation, first create an Medium instance and a Particle instance (their concrete subclasses), then set the initial state of the Particle, and then call propagate and scatter functions in a loop, or use the implemented simulation functions.
DarkProp is designed to change the state of the particle in place, instead of storing the entire trajectory in memory. Therefore, necessary analysis needs to be written in the simulation function (e.g. to find out the events passing through a sphere) and the output is also determined by the user.
Class Inheritance
