# dmdd¶

A python package that enables simple simulation and Bayesian posterior analysis of nuclear-recoil data from dark matter direct detection experiments for a wide variety of theories of dark matter-nucleon interactions. The code is being actively developed on GitHub; please feel free to contribute pull requests or raise issues.

`dmdd`

has the following features:

- Calculation of the nuclear-recoil rates for various non-standard momentum-, velocity-, and spin-dependent scattering models.
- Calculation of the appropriate nuclear response functions triggered by the chosen scattering model.
- Inclusion of natural abundances of isotopes for a variety of target elements: Xe, Ge, Ar, F, I, Na.
- Simple simulation of data (where data is a list of nuclear recoil energies, including Poisson noise) under different models.
- Bayesian analysis (parameter estimation and model selection) of data using
`MultiNest`

.

All rate and response functions directly implement the calculations of Anand et al. (2013) and Fitzpatrick et al. (2013) (for non-relativistic operators, in `rate_genNR`

and `rate_NR`

), and Gresham & Zurek (2014) (for UV-motivated scattering models in `rate_UV`

). Simulations follow the prescription from Gluscevic & Peter (2014) and Gluscevic et al. (2015).

## Dependencies¶

All of the package dependencies (listed below) are contained within the Anaconda python distribution, except for `MultiNest`

and `PyMultinest`

.

For simulations, you will need:

- basic python scientific packages (
`numpy`

,`scipy`

,`matplotlib`

) `cython`

To do posterior analysis, you will also need:

`MultiNest`

`PyMultiNest`

To install these two, follow the instructions here.

## Installation¶

Install `dmdd`

either using pip:

```
pip install dmdd
```

or by cloning the repository:

```
git clone https://github.com/veragluscevic/dmdd.git
cd dmdd
python setup.py install
```

Note that if you do not set the `DMDD_MAIN_PATH`

environment variable, then importing `dmdd`

will create `~/.dmdd`

and use that location to store simulations and posterior samples.

## Usage¶

For a quick tour of usage, check out the tutorial notebook; for more complete documentation, read the docs; and for the most important formulas and definitions regarding the `rate_NR`

and `rate_genNR`

modules, see also here.

## Basic Usage¶

Here is a quick example of basic usage:

```
from dmdd import UV_Model, Experiment, MultinestRun
model1 = UV_Model('SI_Higgs', ['mass', 'sigma_si'], fixed_params={'fnfp_si': 1})
model2 = UV_Model('SD_fu', ['mass','sigma_sd'], fixed_params={'fnfp_sd': -1.1})
xe = Experiment('Xe', 'xenon', 5, 40, 1000, eff.efficiency_Xe)
run = MultinestRun('sim', [xe,ge], model1,{'mass':50.,'sigma_si':70.},
model2, prior_ranges={'mass':(1,1000), 'sigma_sd':(0.001,1000)})
run.fit()
run.visualize()
```

## Attribution¶

This package was originally developed for Gluscevic et al (2015). If you use this code in your research, please cite this ASCL reference, and the following publications: Gluscevic et al (2015), Anand et al. (2013), Fitzpatrick et al. (2013), and Gresham & Zurek (2014).