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.


  • 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)\]


    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 \))


  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)]
     >>> ['quenching' in dir(WD.Na)]

    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

    Load response functions:

     >>> 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()