Input and Output

A complete example of the configuration file is shown below, which can be found in the app directory of the source code.

Listing 2 complete DarkProp configuration file

id = "example"

[input]
type = "halo"  # "halo" "flux" "intensity" "sample" "source"
dm_model = "SI"  # "SI" "SIHelm" "SolarDM" "DMElectron"
medium_model = "HomoEarth"  # "HomoEarth" "HomoElectronEarth" "PREM" "Sun"

mchis = [0.1]  # [GeV]
sigmas = [1e-34]  # [cm^2]
# mchi_file = "./input_mchi.txt"
# sigma_file = "./input_sigma.txt"
mmed = 1e2  # mediator mass [GeV]
mediator_limit = "" # "heavy" "light" or ""
# Tcut = 1e-5  # cutoff energy [GeV]

[input.halo]
rho_0 = 0.3  # [GeV/cm^3]
v_esc = 544.0  # [km/s]
v_0 = 220.0  # [km/s]
v_earth = [0.0, 0.0, 240.0]  # [km/s]
v_min = 1e-5  # [km/s]
v_max = -1.0  # [km/s] negative value means v_earth + v_esc
v_cut = 1e-5  # [km/s] cutoff speed overwrite Tcut

[input.flux]
point_source = false
flux_file = "./input_flux.txt"  # arbitariry name
# Tmin = 1e-3  # [GeV]
# Tmax = 1e2   # [GeV]

[input.intensity]
intensity_file = "./input_intensity.hdf5"  # intensity hdf5 file name
select_mass = [0, 1, 3]  # select masses in the intensity file with index

[input.sample]
sample_file = "./input_sample.hdf5"  # arbitariry name

[input.source]
inv_cdf_r_file = ""
inv_cdf_T_file = ""

[input.solardm]
solar_density_integral_file = ""
temperature_scale = 1.0

[input.geniebdm]
tune = "GDM23_00a_01_000"
xsec_file = "xsec_DMHAD.xml"
cache_file = ""
event_generator_list = "DMHAD-NOFSI"  # "DMCEL" "DMEL-NOFSI", "DMDIS-NOFSI", "DMRES-NOFSI"
messenger_thresholds = "Messenger_whisper.xml"
origin_gz = 1.0  # the original gz used to calculate the xsec_file
xsec_spline_knots = 1000

[output]
outdir = "./out"
overwrite = false
file_name_style = "short"  # "short" "long"
maximal_simulation = 10_000_000
sample_size = 10000  # number of samples on each ring
depth = [1.4]  # [km]
rings = 10  # number of rings
cos_theta_lower = -1.0  # lower bound of ring angle
cos_theta_upper = 1.0   # upper bound of ring angle
ring_space = "linear"  # "linear" "cos_linear"
axis = [1.0, 0.0, 0.0]  # axis of the ring it is always v_earth in halo model

chunk_size = 1000  # hdf5 chunk size
store_time = false
full_tracks = 10  # the number of full tracks to output, do not output if 0

[output.log]
screen_log_lag = 1000 # screen log output interval
warning_long_track = 1000_000


[numerical]
random_seed = 1
interp_Tmin = 1e-100
interp_num = 10000
sample_buffer_size = 10000

This is a TOML format configuration file consisting of parameter-value pairs. Some parameters can be missing and the default values will be used. The parameters are grouped into three main sections (tables) input, output, and numerical which are written in square brackets on a line by themselves. A section may have subsections defined as the [section.subsection] form. Comments are started with a # symbol.

Using the configuration file above, DarkProp will simulate halo DM with mass \(m_\chi = 0.1~\text{GeV}\) and cross section \(\sigma_{\chi p} = 10^{-30}~\text{cm}^2\) in velocity range from 1 cm/s to 784 km/s (in the Earth frame). The events of particles crossing a 1.4 km depth underground surface will be stored in the file ./out/example/example_m0_s0.hdf5.

The Galactic coordinate system is used in darkprop with the Galactic longitude \(l\) from \(0\) to \(2\pi\) and the Galactic latitude \(b\) from \(-\pi/2\) to \(\pi/2\). The transformation between Cartesian coordinates and Galactic coordinates is

(12)\[\begin{split}x &= r \cos b \cos l, \\ y &= r \cos b \sin l, \\ z &= r \sin b.\end{split}\]

The following is a detailed explanation of the input parameters and the output files.

Configuration parameters

In this section we use the section.subsection.parameter notation for parameters. The type of each parameter is marked after it and the unit of the dimensional parameters are also indicated in square brackets behind. The default value, if defined, is written in parentheses.

id String
The id parameter should be defined before any other sections. Its value will be the prefix of the output files.

[input]

input.type String
The type of the initial conditions. Options:

“halo”:

Halo DM simulation.

“flux”:

Isotropic arbitrary incident flux in tabular form.

“intensity”:

Anisotropic arbitrary incident flux in HDF5 format.

“sample”:

Samples of initial conditions in HDF5 format.

“source”:

Production of DM from internal of the medium.
input.dm_model String
Choosing the DM model implemented in DarkProp. Options (case insensitive):

“SI”:

Spin independent constant cross section (class SIDM).

“SIHelm”:

Spin independent constant cross section with the Helm nuclear form factor (class SIHelmDM).

“DMElectron”:

DM-electron vector coupling (class DMElectron).

“SolarDM”:

The solar dark matter model (class SolarDM).
input.medium_model String
Choosing the medium model implemented in DarkProp. Options (case insensitive):

“HomoEarth”:

A homogeneous Earth model composed of 8 components (class HomoEarth).

“PREM”:

The Preliminary Reference Earth Model (class PREMEarth).

“HomoElectronEarth”:

A homogeneous Earth model composed of electrons (class HomoElectronEarth).

“Sun”:

A Sun model (class Sun).
input.mchis Array [GeV]
List of DM particle masses.
input.sigmas Array [\(\text{cm}^2\)]
List of DM-nucleon scattering cross sections \(\sigma_{\chi p}\).
input.mchi_file String
Path of a text file containing a list of DM particle masses in GeV. Its effect is the same as the input.mchis parameter. If both parameters exist, it will override input.mchis.

The file should contain only one column of numbers, or a single line of numbers separated by spaces.
input.sigma_file String
Path of a text file containing a list of cross sections in \(\text{cm}^2\). Its effect is the same as the input.sigmas parameter. If both parameters exist, it will override input.sigmas.

This file should contain only one column of numbers, or a single line of numbers separated by spaces.
input.mmed Float [GeV] (default 0.0)
The mediator mass.
input.mediator_limit String (default “”)
The limitation case of the mediator mass \(m_\phi\). Options:

“light”:

\(m_\phi \to 0\).

“heavy”:

\(m_\phi \to \infty\).

“”:

An empty string means no limit is taken.
input.Tcut Float [GeV]
The termination energy of the simulation. The simulation of the trajectory will stop when the kinetic energy of the particle is less than input.Tcut.

If input.type is "halo", this parameter will be overwritten by the input.halo.v_cut parameter as \(T_\text{cut}= \frac{1}{2}m_\chi v_\text{cut}^2\).

If input.type is "flux", this parameter can be absent, and \(T_\text{cut}\) will be the lowest energy of the input flux.
[input.halo]
The parameters in this subsection only take effect if input.type is "halo".
- input.halo.v_esc Float [km/s]
  The escape speed of the standard halo model (SHM) velocity distribution.
- input.halo.v_0 Float [km/s]
  The most probable speed of the SHM velocity distribution.
- input.halo.v_earth Array [km/s]
  The 3-D velocity of the Earth. The direction will be used to determine the isodetection rings.
- input.halo.v_min Float [km/s]
  The lower bound of sampling velocity in the Earth frame.
- input.halo.v_max Float [km/s]
  The upper bound of sampling velocity in the Earth frame. It will be \(v_\oplus + v_\text{esc}\) if a negative value is given.
- input.halo.v_cut Float [km/s]
  The termination speed of the simulation. It overwrites the input.Tcut parameter.
[input.flux]
The parameters in this subsection only take effect if input.type is "flux".
- input.flux.point_source Boolean (default false)
  Choosing if injecting from a point source. Options:
  
  true:
  
  DM particles come from the same direction.
  
  false:
  
  DM particles are injected isotropically.
- input.flux.flux_file String [\(\text{GeV}\), \(\text{GeV}^{-1}\text{cm}^{-2}\text{s}^{-1}\text{sr}^{-1}\)]
  The path to a file containing the incident fluxes.
  
  The file should be a space separated CSV file with multiple columns. The first column (column 0) is the kinetic energy of the DM particle. The following columns are the corresponding DM fluxes of different masses and cross sections which are set by the input.mchis (or input.mchi_file) and input.sigmas (or input.sigma_file) parameters. These masses and cross sections constitute 2-dimensional grid points. The flux of the \(i\)-th mass and the \(j\)-th cross section is at the \((1 + j + i \times N_s)\)-th column, where \(N_s\) is the number of cross sections. The unit of energy is GeV and the unit of flux is \(\text{GeV}^{-1}\text{cm}^{-2}\text{s}^{-1}\text{sr}^{-1}\).
- input.flux.Tmin Float (default 0.0)
  The lower boundary of the sampling kinetic energy. If \(\leq 0\), it will be set to be the smallest energy in the flux_file.
- input.flux.Tmax Float (default 0.0)
  The upper boundary of the sampling kinetic energy. If \(\leq 0\), it will be set to be the largest energy in the flux_file.

[input.intensity]

The parameters in this subsection only take effect if input.type is "intensity".

input.intensity.intensity_file String

The path to a file containing anisotropic incident fluxes.

The file must be a HDF5 file with the following definitive structure:

file
|--mchi          {Nm}         DM particle mass [GeV]
|--sigma         {SCALAR}     DM-nucleon cross section [cm^2]
|--m_0           Group        the first DM particle mass
|  |--mchi       {SCALAR}     DM particle mass in this group [GeV]
|  |--b          {Nb}         Galactic latitude [rad]
|  |--l          {Nl}         Galactic longitude [rad]
|  |--T          {NT}         DM kinetic energy [GeV]
|  |--intensity  {Nb, Nl, NT} DM intensity (flux) [GeV^-1 cm^-2 s^-1 sr^-1]
|
|--m_1           Group
|--m_2           Group
|  ...
|--m_{Nm - 1}    Group

darkprop will sample initial conditions based on the interpolation of the 3-dimensional intensity grid for each DM mass.

input.intensity.select_mass Array (default [])
An array of indices to select a subset of DM particle masses from the intensity_file for simulation. If empty, all masses are selected.

[input.sample]
The parameters in this subsection only take effect if input.type is "sample".
- input.sample.sample_file String
  The path to a file containing individual initial conditions.
  
  The file must be a HDF5 file with the following definitive structure:
  
  file |--mchi {Nm} DM particle mass [GeV] |--ran_E {NE} DM kinetic energy [GeV] |--ran_bl {NE, 2} latitude, longitude [rad] |--weight {Nm, NE} weights of the samples
[input.source]
The parameters in this subsection only take effect if input.type is "source".
- input.source.inv_cdf_r_file String
  The path to a file containing the inverse CDF of radius distribution of the source.
  
  The file should be a space separated CSV file with two columns. The first column is the CDF ranges from 0 to 1. The second column is the radius r, in unit of cm.
- input.source.inv_cdf_T_file String
  The path to a file containing the inverse CDF of kinetic energy distribution of the source.
  
  The file should be a space separated CSV file with two columns. The first column is the CDF ranges from 0 to 1. The second column is the kinetic energy T, in unit of MeV.
[input.solardm]
The parameters in this subsection only take effect if input.dm_model is "SolarDM".
- input.solardm.solar_density_integral_file String
  The path to a file containing the normalized density integral of the Sun.
  
  The file should be a space separated CSV file with three columns. The first column is \(y\), the second column is \(x\), and the third column is \(z\). The definitions are given in the documentation of the Sun model.
  
  The file should be grouped in blocks that separated by an empty line. In each block the numbers (\(y\)) in the first column are the same.
- input.solardm.temperature_scale Float (default 1.0)
  A scale factor multiplied to the solar temperature.

[output]

outdir String
The directory saving all outputs. The directory will be created if it does not exist.
overwrite Boolean (default false)
Choosing whether to overwrite existing output files.
file_name_style String (default “long”)
Naming style of the output files. Options:

“long”:

“{outdir}/{id}/{id}_mchi{mchi:.3e}GeV_sigma{sigma:.3e}cm2.hdf5”

“short”:

“{outdir}/{id}/{id}_m{mi}_s{si}.hdf5” where mi and si are the index of mchis and sigmas.
maximal_simulation Integer (default 1000000000)
The maximum number of simulated particles. Forcibly terminate the simulation even if the number of samples has not reached the requirement, and the rest will be NaN.
sample_size Integer
The number of samples at each depth on each isodetection ring. The storage space will be allocated from the beginning based on this value, and filled with NaN.
depth Array [km]
The list of depth to collect samples.
rings Integer (default 1)
Number of isodetection rings. Any number \(\leq 1\) will be set to 1.
cos_theta_lower Float (default -1.0)
Lower boundary of the cosine of the ring angle \(\Theta\).
cos_theta_upper Float (default 1.0)
Upper boundary of the cosine of the ring angle \(\Theta\).
ring_space String (default “linear”)
The method of separating the isodetection ring angle \(\Theta\). Options:

“linear”:

\(\Theta\) is uniformly separated from 0 to \(2\pi\).

“cos_linear”:

\(\cos\Theta\) is uniformly separated from 1 to -1.
axis Array (default [1.0, 0.0, 0.0])
The axis of the isodetection ring. It takes no effect if input.type is “halo”, in which case the axis will always be input.halo.v_earth.
chunk_size Integer (default 10000)
The chunk size for HDF5 output.
store_time Boolean (default false)
Whether to store the time of the events.
full_tracks Integer (default 0)
Number of full trajectories additionally stored in the ./<output.outdir>/<id>/fulltracks directory.
[output.log]
- screen_log_lag Integer (default 10000)
  Control the frequency of screen log output.
- warning_long_track Integer (default 1000000)
  A warning will be printed once a trajectory is longer than this value.

[numerical]

The parameters in this section control some details of the numerical calculation, generally using the default values.

random_seed Integer (default -1)
The seed of the random number generator.

If the seed \(\geq 0\), the result will be reproducible.
interp_Tmin Float [GeV] (default 1e-100)
Lower boundary of the interpolation for SIHelmDM.
interp_num Integer (default 100000)
Interpolation grid points for SIHelmDM.
sample_buffer_size Integer (default 10000)
The buffer size used when input.type is "sample".

Output file format

Crossing Events

The crossing events will be stored in HDF5 files with file names specified in the file_name_style parameter. The HDF5 files contain datasets (scalar or 1D array or 2D array) arranged in groups like directories in a file system. The data file is organized as follows

file
|--mchi    {SCALAR}  DM particle mass
|--sigma   {SCALAR}  DM-nucleon cross section
|--R0      {SCALAR}  surface radius
|--Tcut    {SCALAR}  termination kinetic energy of the simulation
|--Tmin    {SCALAR}  minimal incident energy
|--Tmax    {SCALAR}  maximal incident energy
|--V0      {SCALAR}  (halo DM) most probable velocity
|--Vesc    {SCALAR}  (halo DM) escape velocity
|--Vcut    {SCALAR}  (halo DM) termination velocity of the simulation
|--Vmin    {SCALAR}  (halo DM) minimal incident veloctiy
|--Vmax    {SCALAR}  (halo DM) maximal incident velocity
|--Vearth  {3}       (halo DM) Earth's velocity
|--depth   {Ndepth}  array of the depth
|--depth_0 Group     the first depth
|  |--R          {SCALAR}  radius of the surface at this depth
|  |--depth      {SCALAR}  the detph
|  |--ring_bins  {Nrings}  array of the bins of the isodetection ring
|  |--ring_0     Group     the first ring
|  |  |--Nsample {SCALAR}  number of samples
|  |  |--Nsim    {SCALAR}  number of simulated particles
|  |  |--weight  {output.sample_size/Inf}    array of weights from IS
|  |  |--T       {output.sample_size/Inf}    array of kinetic energies
|  |  |--p       {output.sample_size/Inf, 2} array of momentum directions (b, l)
|  |  |--r       {output.sample_size/Inf, 2} array of position directions (b, l)
|  |  |--t       {output.sample_size/Inf}    array of times
|  |
|  |--ring_1            Group
|  |--ring_2            Group
|  |  ...
|  |--ring_{Nrings - 1} Group
|
|--depth_1              Group
|--depth_2              Group
|  ...
|--depth_{Ndepth - 1}   Group

Note

If output.rings <= 1, there will not be a ring_0 group but all the datasets will be in the depth_i group directly.
Nsample should be equal to the number of non-NaN data in the datasets, otherwise there is a bug or the data is corrupted.
Units are stored with each dataset as an attribute.

Full Trajectories

Currently, the full trajectories are stored in plain CSV (space separated) files. The quantities in each column are \(r_x, r_y, r_z, p_x, p_y, p_z, T\), and \(t\) respectively. The units are in km, GeV, and second.