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

• WD.dsigma_der(element,hamiltonian,mchi,v,er,**args)
that calculates the differential cross section \((d\sigma/dE_R)_T\) on target \(T\) (in cm\(^2\)/keV)


• WD.diff_rate(target,hamiltonian,mchi, energy,vmin,delta_eta,**arg)
that calculates the differential rate \(dR/dE_R\) or \(dR/dE_{ee}\) (in events/keV) without including the response of the detector.


• WD.wimp_dd_rate(exp,hamiltonian,vmin,delta_eta,mchi,**args)
that calculates the integrated expected rates \( S^{(0,1)}_{[E_1^{\prime},E_2^{\prime}]} \) including the response of the detector in the interval \( [E_1^{\prime},E_2^{\prime}]\) (in number of events) interpolating the integrated response functions loaded (or calculated) by:

WD.load_response_functions(exp,hamiltonian)

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

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'])




2. Differential rate

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




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