wimpydd is hosted by Hepforge, IPPP Durham






Experiment

The experiment class collects in a single object all the required input about the experimental set-up necessary to calculate the integrated response functions with the response of the detector: the target, the energy bins, the energy resolution, the efficiency, the quenching factors, the exposure. All the corresponding information must be collected in a subdirectory of the WimPyDD/Experiments folder whose name is the main argument of the experiment class. The distribution of WimPyDD comes with three pre-defined experiment folders: 

 WimPyDD/Experiments/XENON_1T_2018
 WimPyDD/Experiments/PICO60_2019
 WimPyDD/Experiments/DAMA_LIBRA_2019

that can be used as templates to implement additional detectors. They contain implementations of XENON_1T, PICO60 and DAMA/LIBRA. Each of them 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. They are stored in the folders: 

 WimPyDD/Experiments/XENON_1T_2018/Response_functions/spin_1_2
 WimPyDD/Experiments/PICO60_2019/Response_functions/spin_1_2
 WimPyDD/Experiments/DAMA_LIBRA_2019/Response_functions/spin_1_2

and are loaded by the load_response_functions routine. For instance, if: 

 >>> pico60=WD.experiment('PICO60_2019')

the files in the following table are searched in the directory WimPyDD/Experiments/PICO60_2019

Physical quantity (unit) Default(if missing file) File name
\(T\) (target material) no default target.tab
\(MT_0\) (kg day) 1 exposure.tab
\(\epsilon(E^{\prime})\) 1 efficiency.tab
efficiency.py
\({\cal G}(E^{\prime},E_{ee})\) \(\delta(E^{\prime}-E_{ee})\) resolution.py
\(q_T(E_R)\) 1 element.name+_quenching.tab
element.name+_quenching.py
(ex:xenon_quenching.tab)
\([E^{\prime}_1,E^{\prime}_2]\) (keV) \(E^{\prime}_1\)=\(E^{\prime}_2\)=1 keV
(no integral - differential rate)		 data.tab
Modifier 1 modifier.py

and the call: 

 >>> WD.load_response_functions(WD.PICO60_2019,WD.SI,0.5)

loads the response functions table: 

WimPyDD/Experiments/PICO60_2019/Response_functions/spin_1_2/c1_c1.tab

for the built-in Hamiltonian WD.SI and j_chi=0.5.

When WimPyDD is imported the built-in experiment objects WD.XENON_1T_2018, WD.PICO60_2019 and WD.DAMA_LIBRA_2019 are already instantiated. In particular an object identical to WD.XENON_1T_2018 can be instantiated using:

 >>> xenon_1t_2018=WD.experiment('XENON_1T_2018')

where the string 'XENON_1T_2018' is the name of the folder:

WimPyDD/Experiments/XENON_1T_2018

which contains the following files:

target.tab
exposure.tab
data.tab
efficiency.tab
resolution.py
xenon_quenching.tab

Attributes and methods of the experiment class

The information collected from the input folder is stored in the attributes and methods of the experiment class. For instance, for the xenon_1t_2018 object defined above:

 >>> [attr for attr in dir(xenon_1t_2018) if '__' not in attr] 
     ['data', 'diff_response_functions', 'efficiency', 'exposure', 'modifier',
     'name', 'resolution', 'response_functions', 'target'] 

 >>> xenon_1t_2018.data
     (array([ 3., 70.,  7.]),)

returns a tuple where each entry is an array with the content of a line of data.tab,

 >>> print(xenon_1t_2018.target)
     Xe contains:
     xenon, symbol Xe, atomic number 54, average 
     mass 122.322, 9 isotopes
     Isotope-averaged mass: 122.32212558999998

returns the target,

 >>> er=1
 >>> xenon_1t_2018.target.element[0].quenching(e=er)
     0.9148

returns a function with the quenching factor for each element attribute of the target,

 >>> xenon_1t_2018.efficiency(10)
     0.6990545499245079

returns a function with the the efficiency,:

 >>> xenon_1t_2018.exposure
     362440.0

returns the exposure,

 >>> xenon_1t_2018.modifier(1)
     1

returns a function with the modifier (if not defined, as in this case, set by default to a function of a single variable returning 1 

 >>> xenon_1t_2018.resolution(s1=1, nu=1)
     0.3337350204748879

provides a function with the energy resolution.

Note that in WimPyDD two pre-defined Hamiltonians are provided, SI for a standard spin-independent coupling and SD for a spin-dependent interactions.

The attribute response_functions is a dictionary containing the tabulated integrated response functions, while diff_response_functions is a dictionary containing the differential response functions. Upon the experiment object instantiation both dictionaries start empty. They are filled up with the content corresponding to the specific combinations of effective Hamiltonian/WIMP spin using the load_response_functions routine:

 >>> WD.load_response_functions(xenon_1t_2018,WD.SI)
 >>> WD.load_response_functions(xenon_1t_2018,WD.SD,j_chi=0.5)

(as in all WimPyDD routines j_chi=0.5 by default).

The arguments passed to load_response_functions are stored in the keys of the response_functions dictionary:

 >>> [(hamiltonian.name,j_chi) for hamiltonian,j_chi in xenon_1t_2018.response_functions.keys()]
     [('Spin-independent', 0.5), ('Spin-dependent', 0.5)]

The values of the dictionary are tuples containing the tables of the \(\left [\bar{{\cal R}}_{T,a}^{[E_1^{\prime},E_2^{\prime}]}\right ]_{jk}^{\tau\tau^{\prime}}(E_R)\) functions, with \(a\)=0,1,1E,1E\(^{-1}\). They can be plotted using:

 >>> WD.plot_response_functions(xenon_1t_2018,WD.SI,j_chi=0.5)
    total of 144 response functions
    28  non-vanishing response functions plotted
 >>> pl.show()


















Notice that a different response function must be calculated for each target, energy bin, \(c_i^{\tau}c_j^{\tau^{\prime}}\) combination of Wilson coefficients and \(a=0,1,1E,1E^{-1}\). However most of them usually vanish. Also the differential response functions \(r_{T,i}(E_R,E^\prime)\) can be plotted using plot_diff_response_functions. Fixing the argument er the function \(r_{T,i}\) is plotted as a function of \(E^\prime\), while fixing the argumenteprime the function \(r_{T,i}\) is plotted as a function of \(E_R\):

 >>> WD.plot_diff_response_functions(xenon_1t_2018, WD.SD, j_chi=0.5, er=10)
     8 non-vanishing differential response functions plotted
 >>> pl.show()


















 >>> WD.plot_diff_response_functions(xenon_1t_2018, WD.SD, j_chi=0.5, eprime=10)
     8 non-vanishing differential response functions plotted
 >>> pl.show()

















Experiment printout

A print(xenon_1t_2018) command prints out all the information collected from the target, the files loaded fromWimPyDD/Experiments/XENON_1T_2018, and the info about the nuclear response functions:

 >>> print(xenon_1t_2018)
     =========================================================================================
     Experiment name : XENON_1T_2018
     ******************
     Target :
     Xe contains:
     xenon, symbol Xe, atomic number 54, average mass 122.322, 9 isotopes.
     Isotope-averaged mass: 122.32212558999998
     Exposure (kg-days) : 362440.0, No help provided
     Quenching for xenon : # Q=g1*LY (g1=0.055 from FIG.3 in 1709.10149v2. LY is taken from the first figure of FIG. 7)
     ******************
     Nuclear response functions for 124Xe. Definition from Phys.Rev.C 89 (2014) 6, 065501 (e-Print: 1308.6288[hep-ph]) used for nuclear W functions as default
     Nuclear response functions for 126Xe. Definition from Phys.Rev.C 89 (2014) 6, 065501 (e-Print: 1308.6288[hep-ph]) used for nuclear W functions as default
     Nuclear response functions for 128Xe. Definition from Phys.Rev.C 89 (2014) 6, 065501 (e-Print: 1308.6288[hep-ph]) used for nuclear W functions as default
     Nuclear response functions for 129Xe. Definition from Phys.Rev.C 89 (2014) 6, 065501 (e-Print: 1308.6288[hep-ph]) used for nuclear W functions as default
     Nuclear response functions for 130Xe. Definition from Phys.Rev.C 89 (2014) 6, 065501 (e-Print: 1308.6288[hep-ph]) used for nuclear W functions as default
     Nuclear response functions for 131Xe. Definition from Phys.Rev.C 89 (2014) 6, 065501 (e-Print: 1308.6288[hep-ph]) used for nuclear W functions as default
     Nuclear response functions for 132Xe. Definition from Phys.Rev.C 89 (2014) 6, 065501 (e-Print: 1308.6288[hep-ph]) used for nuclear W functions as default
     Nuclear response functions for 134Xe. Definition from Phys.Rev.C 89 (2014) 6, 065501 (e-Print: 1308.6288[hep-ph]) used for nuclear W functions as default
     Nuclear response functions for 136Xe. Definition from Phys.Rev.C 89 (2014) 6, 065501 (e-Print: 1308.6288[hep-ph]) used for nuclear W functions as default
     ******************
     Data for XENON_1T_2018 : #counted the number of events from FIG. 3 of 1805.12562
     Efficiency for XENON_1T_2018 : # taken from FIG. 1. of 1805.12562 and converted er into s1 [PE] using xenon_1t.target.element[0].quenching(er)*er
     Resolution for XENON_1T_2018 : See Eqs. (14) and (15) of 1103.0303
     Modifier for XENON_1T_2018 : This function was not initialized and automatically set to 1
     =========================================================================================

The simplest experiment object

The only required inputs for the experiment class are the input folder name and the target. An experiment object using all the default values listed in the second column of the table above can be instantiated if the input directory is missing or empty. Upon instantiation the input directory is created if missing. This allows to create an empty experiment that can be filled up in subsequent steps with files with the energy resolution, the exposure, quenching factors, etc. For instance:

 >>> empty_ge=WD.experiment('empty_ge')
     Target not provided. Could not find Experiments/empty_ge/target.tab.
     Enter now a valid target name (no quotation marks):
     Ge

creates the directory WimPyDD/Experiments/empty_ge containing the file target.tab with all default inputs:

>>> print(empty_ge)
    =========================================================================================
    Experiment name : empty_ge
    ******************
    Target :
    Ge contains:
    germanium, symbol Ge, atomic number 32, average mass 67.691, 5 isotopes.
    Isotope-averaged mass: 67.69094183601963
    Exposure (kg-days) : 1.0, No input file provided, using 1. as default
    Quenching for germanium : This function was not initialized and automatically set to 1
    ******************
    Nuclear response functions for 70Ge. Definition from Phys.Rev.C 89 (2014) 6, 065501 (e-Print: 1308.6288[hep-ph]) used for nuclear W functions as default
    Nuclear response functions for 72Ge. Definition from Phys.Rev.C 89 (2014) 6, 065501 (e-Print: 1308.6288[hep-ph]) used for nuclear W functions as default
    Nuclear response functions for 73Ge. Definition from Phys.Rev.C 89 (2014) 6, 065501 (e-Print: 1308.6288[hep-ph]) used for nuclear W functions as default
    Nuclear response functions for 74Ge. Definition from Phys.Rev.C 89 (2014) 6, 065501 (e-Print: 1308.6288[hep-ph]) used for nuclear W functions as default
    Nuclear response functions for 76Ge. Definition from Phys.Rev.C 89 (2014) 6, 065501 (e-Print: 1308.6288[hep-ph]) used for nuclear W functions as default
    ******************
    Data for empty_ge : No input file provided, using (np.array([1.]),) as default
    Efficiency for empty_ge : This function was not initialized and automatically set to 1
    Resolution for empty_ge : This function was not initialized and automatically set to 1
    Modifier for empty_ge : This function was not initialized and automatically set to 1
    =========================================================================================