# DarkProp

Monte Carlo simulation code for the propagation of dark matter particles in
matter.


# Installation

DarkProp provides an executable application `darkprop` based on the darkprop
C++ library. The `darkprop` application reads a TOML configuration file as
input and stores outputs in HDF5 format. The numerical calculations require
GSL library, and the simulation is parallelized using MPI.

Above mentioned dependencies and the build tools (`make`, `g++`) are required
to build the application. They are available in the repositories of mainstream
Linux distributions, for example

- Ubuntu 20.04+

    $ sudo apt install g++ make libgsl-dev libhdf5-mpi-dev

- Fedora 33+

    $ sudo dnf install g++ make mpich-autoload gsl-devel hdf5-mpich-devel
    $ source /etc/profile

The yuc::config tool has been included in the source for parsing TOML
configurations.

After installing the dependencies, `cd` to the `app` directory and `make`

    $ tar -xzvf darkprop-vX.Y.Z.tar.gz
    $ cd darkprop-vX.Y.Z/app
    $ make

The `darkprop.exe` file will be compiled in the current directory.

To test the executable, run

    $ mpiexec -n 4 ./darkprop.exe config.toml

where 4 is the number of CPU cores for parallel calculation. It can be replaced
with any other number that fits your machine.


# Usage

The `darkprop` application is a single executable file `darkprop.exe` which can
be copied or linked to any directory that in the `PATH` environment variable,
for example

    $ sudo cp darkprop.exe /usr/local/bin/darkprop

Here we changed the name to `darkprop`. Then the program can be launched as

    $ mpiexec -n N darkprop config.toml

where `N` is the number of CPU cores and `config.toml` is the configuration
file.

The crossing events at underground surfaces will be stored. The reconstruction
of the underground DM flux is described in the paper [^1] and is currently not
integrated in the `darkprop` application.

## Example

An example of the Earth attenuation of isotropic CRDM flux is provided in the
`examples/crdm-isotropic` directory.


# C++ library

To use the darkprop C++ library, include the header

    #include "darkprop/core.hpp"
    #include "darkprop/IO.hpp"  // optional hdf5 io

See example `examples/trajectory-csv` for basic usage.


# Python

We also provide a Python package which is a wrapper of the darkprop C++ library.
It can be installed via `pip`

    $ pip install darkprop

See `examples/python/basic-example.ipynb` for more information.


# Citation

If you use this code in your published work, please cite our paper [^1].

[^1]: C. Xia, Y. H. Xu, Y. F. Zhou, Production and Attenuation of Cosmic-Ray
      Boosted Dark Matter. arXiv: 2111.05559
