dmdd 0.2

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.

``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) <http://arxiv.org/abs/1308.6288>`_ and `Fitzpatrick et al. (2013) <https://inspirehep.net/record/1094068?ln=en>`_ (for non-relativistic operators, in ``rate_genNR`` and ``rate_NR``), and `Gresham & Zurek (2014) <http://arxiv.org/abs/1401.3739>`_ (for UV-motivated scattering models in ``rate_UV``). Simulations follow the prescription from `Gluscevic & Peter (2014) <http://adsabs.harvard.edu/abs/2014JCAP...09..040G>`_ and `Gluscevic et al. (2015) <http://arxiv.org/abs/1506.04454>`_.


Dependencies
------------

All of the package dependencies (listed below) are contained within the `Anaconda python distribution <http://continuum.io/downloads>`_, 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 <http://astrobetter.com/wiki/MultiNest+Installation+Notes>`_.


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 <https://github.com/veragluscevic/dmdd/blob/master/dmdd_tutorial.ipynb>`_; for more complete documentation, `read the docs <http://dmdd.rtfd.org>`_; and for the most important formulas and definitions regarding the ``rate_NR`` and ``rate_genNR`` modules, see also `here <https://github.com/veragluscevic/dmdd/blob/master/rate_calculators.pdf>`_.

Attribution
-----------

This package was originally developed for `Gluscevic et al (2015) <http://arxiv.org/abs/1506.04454>`_. If you use this code in your research, please cite `this ASCL reference <http://ascl.net/code/search/dmdd>`_, and the following publications: `Gluscevic et al (2015) <http://arxiv.org/abs/1506.04454>`_, `Anand et al. (2013) <http://arxiv.org/abs/1308.6288>`_, `Fitzpatrick et al. (2013) <https://inspirehep.net/record/1094068?ln=en>`_, and `Gresham & Zurek (2014) <http://arxiv.org/abs/1401.3739>`_.