wimpydd is hosted by Hepforge, IPPP Durham

#### Getting Started

Import WiPyDD by typing:

 >>> import WimPyDD as WD

WimPyDD provides three routines to calculate expected signals (click on each argument to learn more):

Glossary (see arXiv:2106.06207 for details):

$$E_R$$: nuclear recoil energy
$$E_{ee}$$: electron-equivalent energy=$$Q(E_R)E_R$$ with $$Q(E_R)$$ the quenchig factor
$$E^{\prime}$$: visible energy including the effect of the detector energy resolution.

Inputs:

• element: is an element object instantiated by the element class. WimPyDD provides a list of predefined elements that can be listed typing:

•  >>> WD.list_elements()
     WD.Al WD.Ar WD.C WD.Ca WD.F WD.Fe WD.Ge WD.H WD.He WD.I
     WD.Mg WD.N WD.Na WD.Ne WD.Ni WD.O WD.S WD.Si WD.W WD.Xe

A summary of any WimPyDD object can be obtained using print():

 >>> print(WD.Ge)
     germanium, symbol Ge, atomic number 32, average mass 67.691, 5 isotopes.

The element class allows to implement new elements or modify existing ones.

• target: a single element or a composite target obtained taking the linear combination of elements with stoichiometric coefficients or using the target class. Examples,

Define $$NaI$$:

 >>> nai=WD.Na+WD.I or nai=WD.target('NaI')

Define $$C_3F_8$$:

 >>>c3f8= WD.C*3+WD.F*8 or c3f8= WD.target('C3F8')
• hamiltonian: an object instantiated by the eft_hamiltonian class.

In WimPyDD two pre-defined Hamiltonians are provided, SI for a standard spin-independent coupling and SD for a spin-dependent interactions. The eft_hamiltonian class allows to implement a generic Hamiltonian $${\cal H}=\sum_{\tau=0,1} \sum_{j} c_j^{\tau}(w_i,q) {\cal O}_{j}^{\tau}$$ either in the base of operators of Anand et al. or that of the operators of Gondolo et al.
• vmin, delta_eta: samplings of the $$v_k$$, $$\delta\eta_k^{(0,1)}$$ quantities in the parameterization of the velocity integral: $\eta(v,t)= \int_{v}^{\infty}\frac{f(v^{\prime},t)}{v^{\prime}}\,dv^{\prime}=\eta^{(0)}(v)+\eta^{(1)}(v)*\cos\left (\frac{2\pi}{T}(t-t_0)\right)$

$\eta^{(0,1)}(v)=\sum_{k=1}^{N_s}\delta\eta_k(t)\theta(v_k-v)$

with $$f(v)$$, the WIMP velocity distribution, $$t_0$$=2 June, $$T$$=1 year (yearly modulation time-dependence due to rotation of the Earth around the Sun). They can be calculated using the streamed_halo_function routines:

for $$\delta\eta^0$$,

 >>> vmin,delta_eta0=WD.streamed_halo_function()

and for $$\delta\eta^1$$ by setting yearly_modulation=True,

 >>> vmin,delta_eta1=WD.streamed_halo_function(yearly_modulation=True)

that by default returns 1000 linearly spaced values from 0 to the escape velocity of the $$\delta\eta^{(0,1)}_k$$'s for a standard Maxwellian velocity distribution $$f(\vec{v})$$ with standard values of the Galactic parameters.

The streamed_halo_function routine allows to change the astropysical parameters and to calculate $$\delta\eta_k^{(0,1)}$$ for a user-defined $$f(v)$$.

• exp: object instantiated by the experiment class, containing all the required information about the experimental set-up: the target, the energy bins, the energy resolution, the efficiency, the quenching factors, and the exposure.

WimPyDD provides 3 built-in experiments: XENON_1T_2018, PICO60_2019 and DAMA_LIBRA_2019. Each experiment comes with a full set of integrated response functions tables in the base of operators of Anand et al. for WIMP spin $$j_\chi$$=1/2 and assuming Wilson coefficients independent on the transferred momentum.
• er:recoil energy $$E_R$$; mchi:WIMP mass $$m_\chi$$; v:WIMP incoming velocity; energy: recoil energy $$E_R$$ or electron-equivalent energy $$E_{ee}$$, depending if the target has the quenching attribute; **args: list of keyworded arguments with the parameters of the Wilson coefficients of the effective Hamiltonian.

Default input:

delta=0 (mass splitting $$\delta$$), j_chi=0.5 (WIMP spin $$j_\chi$$)

#### Examples:

1. Differential cross section
2. Calculate cross section on the isotopes of germanium for a spin-independent interaction, $$m_\chi$$=100 GeV, $$E_R$$=10 keV, $$v$$=300 km/s, $$\sigma_p$$=10$$^{-40}$$ cm$$^{2}$$:

 >>> WD.dsigma_der(element=WD.Ge, hamiltonian=WD.SI, mchi=100, v=300, er=10, sigma_p=1e-40)
     array([1.56458629e-35, 1.69085823e-35, 1.75363554e-35, 1.81728074e-35, 1.94942935e-35])

The output is an array containing the cross section in cm$$^2$$/keV for each of the 5 isotopes of germanium:

 >>> WD.Ge.isotopes
     array(['70Ge', '72Ge', '73Ge', '74Ge', '76Ge'])

3. Differential rate
4. Calculate differential rate on sodium iodide. In ionizators or scintillators the observed electron-equivalent energy is obtainined by multiplying the nuclear recoil energy off each element with a different quenching factor. However, built-in elements have no quenching attribute:

 >>> ['quenching' in dir(WD.I)]
     [False]
 >>> ['quenching' in dir(WD.Na)]
     [False]

Quenching is a property of both the element and the detector. So the quenching attribute is only present if the element is the target of a given experimental set-up. For instance, sodium iodide is the target attribute of the DAMA_LIBRA_2019 experiment:

 >>> ['quenching' in dir(element) for element in WD.DAMA_LIBRA_2019.target.element]
     [True, True]

The argument energy of the diff_rate routine is interpreted as the electron-equivalent energy $$E_{ee}=Q(E_R)E_R$$ for elements with a quenching factor attribute. So for a spin-dependent interaction, $$m_\chi$$=20 GeV, a standard halo function in the energy interval 1 keV $$<E_{ee}<20$$ keV (linear sample of 100 points):

 >>> import numpy as np
 >>> vmin,delta_eta0=WD.streamed_halo_function()
 >>> e_ee_vec=np.linspace(1,20,100)
 >>> diff_rate_nai=[WD.diff_rate(target=WD.DAMA_LIBRA_2019.target, hamiltonian=WD.SI,
mchi=20, energy=e_ee,vmin=vmin, delta_eta=delta_eta0) for e_ee in e_ee_vec]

The curve can be directly plotted using for instance Matplotlib:

 >>> import matplotlib.pyplot as pl
 >>> pl.plot(e_ee_vec,diff_rate_nai)
 >>> pl.yscale('log')
 >>> pl.show()

5. Integrated rate

 >>> WD.load_response_functions(WD.DAMA_LIBRA_2019,WD.SI)

Calculate rate for a spin-dependent interaction, $$m_\chi$$=20 GeV, a standard halo function, $$\sigma_p$$=10$$^{-40}$$ cm$$^{2}$$ integrated in experimental bins:

 >>> e,rate_nai=WD.wimp_dd_rate(exp=WD.DAMA_LIBRA_2019, hamiltonian=WD.SI,
vmin=vmin, delta_eta=delta_eta0, mchi=20,sigma_p=1e-40) 

The output of wimp_dd_rate consists in two arrays: the first array contains the centers of the energy bins and the second array contains the corresponding # of expected events including the effect of the response of the detector. Energy binning, exposure and other detector-related inputs are initialized through the experiment class and contained in the attributes of the WD.DAMA_LIBRA_2019 object. In Matplotlib the binned rate can be plotted using:

 >>> import matplotlib.pyplot as pl
 >>> pl.step(e,rate_nai)
 >>> pl.yscale('log')
 >>> pl.show()