API¶
The following details the objects used in this package.
Experiment¶
-
class
dmdd.
Experiment
(name, element, Qmin, Qmax, exposure, efficiency_fn, tex_name=None, energy_resolution=True)[source]¶ An object representing a dark-matter direct-detection experiment.
This object packages all the information that defines a single “experiment”. For statistical analysis, a list of these objects is passed to initialize an instance of a
MultinestRun
object, or to initialize an instance of aSimulation
object. It can also be used on its own to explore the capabilities of an experiment with given characteristics. Experiments set up here can either have perfect energy resolution in a given analysis window, or no resolution (controlled by the parameterenergy_resolution
, default beingTrue
).Parameters: - name (
str
) – Name of experiment. - element (
str
) – Detector target element. Only single-element targets currently supported. - Qmin,Qmax – Nuclear-recoil energy range of experiment [in keV].
- exposure – Total exposure of experiment [kg-years].
- efficiency_fn (
function
) – Efficiency as a function of nuclear recoil energy. - tex_name (
str
) – Optional; provide this if you want a specific tex name on plots. - energy_resolution (
bool
) – IfTrue
, then the energy of recoil events will be taken into account in likelihood analyses using this experiment; otherwise, not (e.g., for bubble-chamber experiments).
-
NminusNbg
(sigma_val, sigma_name='sigma_si', fnfp_name='fnfp_si', fnfp_val=None, mass=50.0, Nbackground=4, v_esc=540.0, v_lag=220.0, v_rms=220.0, rho_x=0.3)[source]¶ Expected number of events minus background
Parameters: - sigma_val – Scattering cross-section for interaction with proton [cm^2]
- sigma_name – Which sigma this corresponds to (i.e., which argument of
rate_UV.R()
) - fnfp_name (
str
) – Which fnfp to use. - fnfp_val – Value of fnfp (optional).
- mass – Dark-matter particle mass in GeV.
- Nbackground – Number of background events expected.
- v_esc,v_lag,v_rms,rho_x – Passed to
rate_UV.R()
.
-
VminusVesc
(mx, v_esc=540.0, v_lag=220.0)[source]¶ This function returns the value of the minimum velocity needed to produce recoil of energy Qmin, minus escape velocity in Galactic frame.
See Eq 2.3 in (Gluscevic & Peter, 2014).
Zero of this function gives minimal dark-matter particle mass mx that can be detected with this Experiment. This is usually called by
Experiment.find_min_mass()
.Parameters: - mx – WIMP mass [GeV]
- v_esc – escape velocity in Galactic frame [km/sec]
- v_lag – rotational velocity of the Milky Way [km/sec]
Returns: Vmin - Vesc
-
find_min_mass
(v_esc=540.0, v_lag=220.0, mx_guess=1.0)[source]¶ This finds the minimum dark-matter particle mass detectable with this experiment, by finding a zero of VminusVesc.
Parameters: mx_guess – guess-value [GeV]. Other parameters documented in
Experiment.VminusVesc()
.
-
sigma_exclusion
(sigma_name, fnfp_name='fnfp_si', fnfp_val=None, mass_max=5000, Nbackground=4, mx_guess=1.0, sigma_guess=10000000000.0, v_esc=540.0, v_lag=220.0, v_rms=220.0, rho_x=0.3, mass_spacing='log', nmass_points=100, make_plot=False, ymax=None)[source]¶ Makes exclusion curve for a chosen sigma parameter.
Calculates
Experiment.sigma_limit()
for a grid of masses, and interpolates.Parameters: - sigma_name (
str
) – Name of cross-section to exclude. - mass_spacing – ‘log’ (logarithmic) or ‘lin’ (linear) spacing for mass grid.
- nmass_points – Number of points to calculate for mass grid.
- make_plot – Whether to make the plot. If
False
, then function will return arrays ofmass, sigma
. - ymax – Set the y maximum of plot axis.
For other parameters, see
Experiment.sigma_limit()
- sigma_name (
-
sigma_limit
(sigma_name='sigma_si', fnfp_name='fnfp_si', fnfp_val=None, mass=50.0, Nbackground=4, sigma_guess=10000000000.0, mx_guess=1.0, v_esc=540.0, v_lag=220.0, v_rms=220.0, rho_x=0.3)[source]¶ Returns value of sigma at which expected number of dark-matter induced recoil events is equal to the number of expected background events, N = Nbg, in order to get a rough projected exclusion for this experiment.
Parameters: - sigma_guess – Initial guess for solver.
- mx_guess – Initial guess for dark-matter particle mass in order to find the minimum mass
detectable from experiment (
Experiment.find_min_mass()
).
For other arguments, see
Experiment.NminusNbg()
- name (
Model¶
-
class
dmdd.
Model
(name, param_names, dRdQ_fn, loglike_fn, default_rate_parameters, tex_names=None, fixed_params=None, modelname_tex=None)[source]¶ A generic class describing a dark-matter scattering model.
This object facilitates handling of a “hypothesis” that describes the scattering interaction at hand (to be used either to simulate recoil spectra, or to fit them). There is an option to give any parameter a fixed value, which will not be varied if the model is used to fit data.
Subclassed by
UV_Model
.Parameters: - name (
str
) – Name of the model, matching the operator(s) name. It cannot have spaces. - param_names (
list
) – Names of the parameters. - dRdQ_fn (
function
) – Appropriate rate function. - loglike_fn (
function
) – Function that returns the log-likelihood of an array of event energies, given experimental and astrophysical parameters. Must takeQ, eff_fn, **kwargs
as arguments. - default_rate_parameters (
dict
) – Default parameters to be passed to rate function. - tex_names (
dict
) – Dictionary of LaTeX names of parameters. - fixed_params (
dict
) – Parameters of model that are not intended to be fit for.
- name (
Simulation¶
-
class
dmdd.
Simulation
(name, experiment, model, parvals, path='/home/docs/.dmdd/simulations_uv/', force_sim=False, asimov=False, nbins_asimov=20, plot_nbins=20, plot_theory=True, silent=False)[source]¶ A simulation of dark-matter direct-detection data under a given experiment and scattering model.
This object handles a single simulated data set (nuclear recoil energy spectrum). It is generaly initialized and used by the
MultinestRun
object, but can be used stand-alone.Simulation data will only be generated if a simulation with the right parameters and name does not already exist, or if
force_sim=True
is provided uponSimulation
initialization; if the data exist, it will just be read in. (Data is a list of nuclear recoil energies of “observed” events.) InitializingSimulation
with given parameters for the first time will produce 3 files, located by default at$DMDD_PATH/simulations
(or./simulations
if$DMDD_PATH
not defined):- .dat file with a list of nuclear-recoil energies (keV), drawn from a
Poisson distribution with an expected number of events given by the underlying scattering model.
- .pkl file with all relevant initialization parameters for record
- .pdf plot of the simulated recoil-energy spectrum with simulated
data points (with Poisson error bars) on top of the underlying model
Parameters: - name (
str
) – Identifier for simulation (e.g. ‘sim1’) - experiment (
Experiment
) – Experiment for simulation. - model (
Model
) – Model under which to simulate data. - parvals (
dict
) – Values of model parameters. Must contain the same parameters asmodel
. - path (
str
) – The path under which to store the simulations. - force_sim (
bool
) – IfTrue
, then redo the simulations no matter what. IfFalse
, then the simulations will be redone if and only if the given simulation parameters don’t match what has already been simulated for this simulation name. - asimov – Do asimov simulations. Not currently implemented.
- nbins_asimov – Number of asimov bins.
- plot_nbins – Number of bins to bin data in for rate plot.
- plot_theory – Whether to plot the “true” theoretical rate curve along with the simulated data.
- silent – If
True
, then print messages will be suppressed.
-
plot_data
(plot_nbins=20, plot_theory=True, save_plot=True, make_plot=True, return_plot_items=False)[source]¶ Plot simuated data.
Parameters: - plot_nbins – Number of bins for plotting.
- plot_theory – Whether to overplot the theory rate curve on top of the data points.
- save_plot – Whether to save plot under
self.plotfile
. - make_plot – Whether to make the plot. No reason really to ever
be false unless you only want the “plot items”
returned if
return_plot_items=True
is passed. - return_plot_items – If
True
, then function will return lots of things.
MultinestRun¶
-
class
dmdd.
MultinestRun
(sim_name, experiments, sim_model, param_values, fit_model, prior_ranges, prior='logflat', sim_root='/home/docs/.dmdd/simulations_uv/', chains_root='/home/docs/.dmdd/chains_uv/', force_sim=False, asimov=False, nbins_asimov=20, n_live_points=2000, evidence_tolerance=0.1, sampling_efficiency=0.3, resume=False, basename='1-', silent=False, empty_run=False)[source]¶ This object controls a single simulated data set and its MultiNest analysis.
This is a “master” class of
dmdd
that makes use of all other objects. It takes in experimental parameters, particle-physics parameters, and astrophysical parameters, and then generates a simulation (if it doesn’t already exist), and prepares to performMultiNest
analysis of simulated data. It has methods to do aMultiNest
run (MultinestRun.fit()
) and to visualize outputs (visualize()
).Model
used for simulation does not have to be the same as theModel
used for fitting. Simulated spectra from multiple experiments will be analyzed jointly ifMultiNest
run is initialized with a list of appropriateExperiment
objects.The likelihod function is an argument of the fitting model (
Model
object); for UV models it is set todmdd.rate_UV.loglikelihood()
, and for models that would correspond torate_genNR
,dmdd.rate_genNR.loglikelihood()
should be used. Both likelihood functions include the Poisson factor, and (ifenergy_resolution=True
of theExperiment
at hand) the factors that evaluate probability of each individual event (i.e. each recoil-energy measurement), given the fitting scattering model.MultiNest-related files produced by this object will go to a directory, under
$DMDD_MAIN_PATH
, with the name defined by the parameters passed. This directory name will be accessible viaself.chainspath
after the object is initialized.Parameters: - sim_name (
str
) – The name of the simulation (e.g. ‘sim1’) - experiments (
list
) – A list ofExperiment
objects, or a single such object. - sim_model (
Model
) – The true underlying model for the simulations (name cannot have spaces). - param_values (
dict
) – The values of the parameters forsim_model
. - fit_model (
Model
) – The model for MultiNest to fit to the data. Does not have to be the same assim_model
, but can be. Its name cannot have spaces. - prior_ranges (
dict
) – Dictionary of prior ranges for parameters of fit_model. e.g. {‘mass’:(1,1000), ‘sigma_si’:(0.1,1e4), etc....} - prior (
str
) – either ‘logflat’ or ‘flat’ - sim_root (
str
) – The path under which to store the simulations. - chains_root (
str
) – The path under which to store the Multinest chains. - force_sim (
bool
) – If True, then redo the simulations no matter what. If False, then the simulations will be redone if and only if the given simulation parameters don’t match what has already been simulated for this sim_name. - asimov – Do asimov simulations. Not currently implemented.
- nbins_asimov – Number of asimov bins.
- n_live_points,evidence_tolerance,sampling_efficiency,resume,basename – Parameters to pass to MultiNest, defined in the PyMultiNest documentation.
- silent – If
True
, then print messages will be suppressed. - empty_run – if
True
, then simulations are not initialized.
-
fit
(force_run=False)[source]¶ Runs MultiNest; parameters set by object initialization.
Parameters: force_run – If True
, then fit will re-run; by default, it will not, unless the simulation data has changed, or chains don’t exist.
-
flat_prior
(cube, ndim, nparams)[source]¶ Flat prior, passed to MultiNest.
Converts unit cube into correct parameter values based on flat prior within range defined by
self.prior_ranges
.
-
logflat_prior
(cube, ndim, nparams)[source]¶ Logflat prior, passed to MultiNest.
Converts unit cube into correct parameter values based on log-flat prior within range defined by
self.prior_ranges
.
-
loglikelihood_total
(cube, ndim, nparams)[source]¶ Log-likelihood function used by MultiNest.
Parameters: ndim, nparams (cube,) – Params required by MulitNest.
-
visualize
(**kwargs)[source]¶ Makes plots of data for each experiment with theoretical and best-fit models.
Also makes 2-d posteriors for each fitted parameter vs. every other. These plots get saved to
self.chainspath
.Parameters: **kwargs – Keyword arguments passed to
dmdd.dmdd_plot.plot_2d_posterior()
.
- sim_name (