wimpydd is hosted by Hepforge, IPPP Durham

#### Element

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 

Element targets are instantiated by the element class, that takes as an argument a string with the element symbol. By convention element symbols must begin with a capital letter. The string must correspond to a file in the directory WimPyDD/Targets containing the required information. For instance the xenon element, with symbol Xe, is instantiated with:

 >>> Xenon=WD.element('Xe')

and the class requires the text file Xe.tab in WimPyDD/Targets. The content of such plain text file is the following:

The first three rows contain the element full name, symbol, and atomic number $$Z$$. For each of the element isotopes each of the following lines initializes the mass atomic mass number $$A$$ in the first column, the fractional abundance in the second column and the target spin $$j_T$$ in the third column. Finally for pre-defined elements the last column contains an internal integer code itar that is used to initialize the nuclear response functions $$W_{l,T}^{\tau\tau^{\prime}}(q)$$ provided in Anand et al. and Catena et al. for the 30 isotopes $$T$$=$$^{12}C$$, $$^{19}F$$, $$^{23}Na$$, $$^{28}Si$$, $$^{70}Ge$$, $$^{72}Ge$$, $$^{73}Ge$$, $$^{74}Ge$$, $$^{76}Ge$$, $$^{127}I$$, $$^{128}Xe$$, $$^{129}Xe$$, $$^{130}Xe$$, $$^{131}Xe$$, $$^{132}Xe$$ $$^{134}Xe$$, $$^{136}Xe$$, $$^{16}O$$, $$^{40}Ar$$, $$^{40}Ca$$, $$H$$, $$^{3}He$$, $$^{4}He$$, $$^{14}N$$, $$^{20}Ne$$, $$^{24}Mg$$, $$^{27}Al$$, $$^{32}S$$,$$^{56}Fe$$, $$^{59}Ni$$.

Besides adding a file in WimPyDD/Targets, for new elements or isotopes for which numerical calculations of the $$W_{l,T}^{\tau,\tau^\prime}(q)$$ functions are not available, the internal code itar must be set to zero. It is possible to provide the corresponding nuclear response function (or to override the default definitions) adding the file name_func_w.py in the directory WimPyDD/Targets/Nuclear_response_functions with name one of the entries of the isotopes attribute of the element class. The file must contain a function func_w_custom(q) with the same behaviour of each of the functions contained in the func_w method. i.e. it must depend on the single argument q and return an array with shape (8,2,2).

For instance, in order to change $$W_{l,T}$$ for $$T$$=$$^{129}Xe$$ the custom definition must be contained in the file 129Xe_func_w.py, since 129Xe is one of the entries of the WD.Xe.isotopes attribute. A few examples of custom definition files are provided with the WimPyDD distribution. If for a nuclear isotope itar=0 and no file is present in WimPyDD/Targets/Nuclear_response_functions the corresponding nuclear response functions are set to zero and its contribution to the output of signal routines set to zero.

#### Main attributes and methods of the element class

 >>> dir(WD.Ge)
     ['a', 'abundance', 'average_a', 'average_mass', 'func_w',
     'isotopes', 'itar', 'mass', 'n_isotopes', 'name',
     'nt_kg', 'spin', 'symbol', 'z']
 >>> WD.Ge.a
     array([70, 72, 73, 74, 76])

Returns an array with the mass numbers of each isotope.

 >>> WD.Ge.abundance
     array([0.2052, 0.274 , 0.077 , 0.3652, 0.0775])

Returns an array with the fractional abundances of each isotope.

 >>> WD.Ge.average_a
     72.70777855641207

Returns the average over isotopes of the mass number.

 >>> WD.Ge.average_mass
     67.69094183601963

Returns the average over isotopes of the mass in GeV.

 >>> WD.Ge.func_w[2](q=0.1)[3]
     array([[6.02002596, 3.13170007],
             3.13170007, 1.66589114]])

Returns the 2$$\times$$2 matrix for the nuclear response function $$W^{\tau\tau^{\prime}}_{l,T}$$ = $$W^{\tau\tau^{\prime}}_{\Phi^{\prime\prime},^{73}Ge}$$.

The attribute func_w is an array of functions of the nuclear response function $$W_{l,T}^{\tau\tau^{\prime}}(q)$$ for each isotope (the index of the array corresponds to each entry of the isotopes attribute array). It returns an array with shape (8,2,2)=(l,tau,tau_prime) corresponding to 2$$\times$$2 matrix for each of the 8 nuclear currents $$l$$ with $$l=(0,1,2,3,4,5,6,7) \rightarrow (M,\Sigma^{\prime\prime},\Sigma^{\prime},\Phi^{\prime\prime}, \tilde{\Phi}^{\prime}, \Delta, \Phi^{\prime\prime}M, \Delta\Sigma^{\prime})$$

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

Contains an array with strings with the isotopes names.

 >>> WD.Ge.itar
     array([5, 6, 7, 8, 9])

Contains an array with the internal codes itar for each isotope of the element. itar=1,...30 is a progressive number corresponding to each of the 30 isotopes for which the nuclear response functions are available in the literature. itar must be set to 0 for isotopes for which default nuclear response functions are not available.

 >>> WD.Ge.mass
     array([65.17 , 67.032, 67.963, 68.894, 70.756])

Returns an array with the masses of the isotopes in GeV.

 >>> WD.Ge.n_isotopes
     5

Integer with the number of isotopes.

 >>> WD.Ge.name
     'germanium'

String with the element name.

 >>> WD.Ge.nt_kg
     array([1.69899841e+24, 2.26864310e+24, 6.37538389e+23, 3.02375350e+24, 6.41678249e+23])

Array with the number of targets per kg for each isotope.

 >>> WD.Ge.spin
     array([0. , 0. , 4.5, 0. , 0. ])

Array with the spin $$j_T$$ of each isotope.

 >>> WD.Ge.symbol
     'Ge'

String with the element symbol.

 >>> WD.Ge.z
     32

Integer with the element atomic number.

print() can be used to get a summary of the element properties:

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

#### Target

A target is a combination of elements with stoichiometric coefficients. In WimPyDD this can be achieved by simply taking a linear combination of elements with integer coefficients. For example, to define the Octafluoropropane target $$C_3 F_8$$:

 >>> carbon=WD.element('C')
 >>> fluorine=WD.element('F')
 >>> octafluoropropane=3*sodium+8*fluorine

Alternatively, the user can also define a target in the following way:

 >>> c3f8=WD.target('C3F8')

The element symbols must begin with a capital letter in order for the input string passed to the target class to be parsed correctly (so the string 'NaI' initializes sodium iodine, while 'nai' returns an error) . A short summary of the targer can be obtained by using print():

 >>> print(c3f8)
     C3F8 contains:
     carbon, symbol C, atomic number 6, average mass 11.182, 2 isotopes.
     fluorine, symbol F, atomic number 9, average mass 17.689, 1 isotopes.
     Isotope-averaged mass: 175.058723

#### Main attributes of the target class

 >>> dir(c3f8)
     ['element', 'formula', 'mass', 'n', 'n_targets', 'nt_kg']
 >>> [element.name for element in c3f8.element]
     ['carbon', 'fluorine']

The element attribute is an array with the element objects contained in the target.

 >>> c3f8.formula
     'C3F8'

A string with the target formula.

 >>> c3f8.mass
     175.058723

A float with the molecular total mass in GeV.

 >>> c3f8.n
     array([3, 8])

An array with the stoichiometric coefficients.

 >>> c3f8.n_targets
     2

An integer with the number of elements in the target.

 >>> c3f8.nt_kg
     array([9.60469705e+24, 2.56125255e+25])

An array with the number of targets per kg of molecular composite for each element.