This Section details the classes and functions on which the Programming section is built
1. ndlab module¶
This is the user entry point to interrogate the database and to write custom software. It provides:
Functions to retrieve data
Functions to handle SQL
Classes to handle values and uncertainites
Classes modelling nuclear structure
Functions to create them
Static classes to build the fields and filter parameters
This page documents the main functions the user should call, for full documentation see the source code
Querying the database¶
Functions to retrieve data¶
These take two parameters , see 1. Retrieval functions. Some of them are specific for feeding data into a pandas dataframe
- ndlab.csv_data(fields, filter)[source]¶
CSV data from a query
- Parameters:
fields (str) – list of comma-separated
ndlaborm
fieldsfilter (str) – filter condition built with
ndlaborm
fields
- Returns:
CSV structure with the data
- Return type:
str
fields = "NUCLIDE.Z, NUCLIDE.ATOMIC_MASS"
filter = "NUCLIDE.NUC_ID = '135XE'"
csv = nl.csv_data(fields, filter)
print(csv)
>>z,atomic_mass
>>54,134907231.441
- ndlab.json_data(fields, filter)[source]¶
JSON data from a query
- Parameters:
fields (str) – list of comma-separated
ndlaborm
fieldsfilter (str) – filter condition built with
ndlaborm
fields
- Returns:
JSON structure with the result set
- Return type:
str
fields = "NUCLIDE.Z, NUCLIDE.ATOMIC_MASS"
filter = "NUCLIDE.NUC_ID = '135XE'"
json = nl.json_data(fields, filter)
print(json)
>>[ {'z':'54' ,'atomic_mass':'134907231.441'}]
- ndlab.pandas_df(fields, filter, pandas)[source]¶
Creates a dataframe
If the database is local, calls pandas’ read_sql method using
query_build
to build the query, andquery_con
to get the db connectionIf the database is remote, calls the server API
- Parameters:
fields (str) – list of comma-separated
ndlaborm
fieldsfilter (str) – filter condition built with
ndlaborm
fieldspandas (Object) – the pandas module imported in the calling environment. E.g. pass when
pd
when usingimport pandas as pd
- Returns:
the pandas dataframe
- Return type:
Dataframe
import pandas as pd
fields = "NUCLIDE.Z, NUCLIDE.ATOMIC_MASS"
filter = "NUCLIDE.NUC_ID = '135XE'"
df = nl.pandas_df(fields, filter, pd)
print(df)
>> z atomic_mass
>>0 54 1.349072e+08
- ndlab.pandas_df_nl(list, pandas)[source]¶
Returns a Dataframe from a list of
ndlab.Ndm_base
classes- Parameters:
list (List) – list of ndlab class instances pandas (Object): the pandas module imported in the calling environment. E.g. pass when
pd
when usingimport pandas as pd
- Returns:
the pandas dataframe
- Return type:
Dataframe
import pandas as pd
nuc = nl.nuclide("135XE")
levels = nuc.levels()
df = nl.pandas_df_nl(levels, pd)
df
z n nucid l_seqno energy energy_unc half_life half_life_unc half_life_units half_life_sec ... jp_order jp_method jp_str quadrupole_em quadrupole_em_unc dipole_mm dipole_mm_unc questionable configuration isospin
0 54 81 135XE 0 0.000 0.000000 9.14 0.02 h 32904.0 ... 1 0 3/2+ 0.214 0.007 0.9032 0.0007 NaN NaN NaN
1 54 81 135XE 1 288.455 0.000015 0.00 0.00 NaN 0.0 ... 1 0 1/2+ 0.000 0.000 0.0000 0.0000 NaN NaN NaN
2 54 81 135XE 2 526.551 0.000013 15.29 0.05 m
- ndlab.csv_nl(nl_items)[source]¶
CSV from a list of
ndlab.Ndm_base
classesfor each instance, calls its csv() method and composes the overall result
- Parameters:
nl_items (Object[]) – list with ndlab class instances
- Returns:
the CSV
- Return type:
String
nuc = nl.nuclide("135XE")
levels = nuc.levels()
print(nl.csv_ndm(levels))
z,n,nucid,l_seqno,energy,energy_unc,half_life,half_life_unc,half_life_units,half_life_sec,half_life_sec_unc,j,parity,jp_order,jp_method,jp_str,quadrupole_em,quadrupole_em_unc,dipole_mm,dipole_mm_unc,questionable,configuration,isospin
54,81,135XE,0,0.0,0,9.14,0.02,h,32904.0,72.0,1.5,0,1,0,3/2+,0.214,0.007,0.9032,0.0007,,,
54,81,135XE,1,288.455,1.5e-05,0,0,,0,0,0.5,0,1,0,1/2+,0,0,0,0,,,
54,81,135XE,2,526.551,1.3e-05,15.29,0.05,m,917.4,3.0,5.5,1,1,0,11/2-,0,0,0,0,,,
- ndlab.pandas_csv_nl(nl_items)[source]¶
Text stream with CSV from a list of
ndlab.Ndm_base
classesReady to be plugged into pandas. For each instance, calls its csv() method and composes the overall result
- Parameters:
nl_items (Object[]) – list with ndlab class instances
- Returns:
text stream with the CSV
- Return type:
StringIO
nuc = nl.nuclide("135XE")
levels = nuc.levels()
stream = nl.pandas_csv_nl(levels)
stream
<_io.StringIO at 0x7f7e20420d30>
Functions to handle SQL¶
- ndlab.query_build(fields, filter='')[source]¶
The SQL query associated with fields and filter
- Parameters:
fields (str) – list of comma-separated
ndlaborm
fieldsfilter (str) – filter condition built with
ndlaborm
fields
- Returns:
the SQL
- Return type:
String
fields = " GAMMA.ENERGY "
filter = "GAMMA.NUC.Z = 4 and GAMMA.START_LEVEL.ENERGY > 700"
sql = nl.query_build(fields, filter)
sql
'select gammas.energy from gammas,nuclides as gam_nuc,levels as gam_lev_s where gammas.nucid=gam_nuc.nucid and gammas.nucid = gam_lev_s.nucid and gammas.l_seqno = gam_lev_s.l_seqno and gam_nuc.z = 4 and gam_lev_s.energy > 700'
- ndlab.query_con()[source]¶
The connection to the database
- Returns:
The connection to the database
- Return type:
Connection
pd.read_sql(" select * from nuclides ", nl.query_con())
Managing Values and Uncertainities¶
Implementing the ISO Vocabulary, these classes are used as instance variables, see below
- class ndlab.Property(name='')[source]¶
Models the ISO VIM
Upper class with only the name of the property
- class ndlab.Quantity(name='')[source]¶
Models the ISO VIM and handles the uncertainties propagation with ufloat from the uncertainties package
- sep¶
The CSV separator to be used when dumping to CSV
- Type:
string
- Variables:
nominal (string) – name
value (float) – float value
unc (string) – uncertainity as string
unc_num (float) – uncertainity as float
Operator – Operator
- create(unc, operator='=')[source]¶
Creates a Quantity from a value, and uncertainty, and an operator.
Used internally from overloaded mathematical functions
- Parameters:
value (float) – value
unc (float) – uncertainty
operator (Operator) – operator
- ufloat()[source]¶
ufloat of the `uncertainties <https://pythonhosted.org/uncertainties/`__ package from
value
anduncertainty
Functions creating data model classes¶
ndlab.levels()
will populate instances of ndlab.Level
.A ndlab.Level
can also be indirectly created from an instance of ndlab.Nuclide
by accessing its ndlab.Nuclide.levels()
method
- ndlab.nuclide(nucid)[source]¶
A
ndlab.Nuclide
from its identifyer
- ndlab.nuclides(filter='')[source]¶
A list of
ndlab.Nuclide
- ndlab.levels(filter='')[source]¶
A list of
ndlab.Level
- ndlab.gammas(filter='')[source]¶
A list of
ndlab.Gamma
- ndlab.dr_gammas(filter='')[source]¶
A list of
ndlab.Dr_gamma
- ndlab.dr_alphas(filter='')[source]¶
A list of
ndlab.Dr_alpha
- ndlab.dr_beta_ms(filter='')[source]¶
A list of
ndlab.Dr_betam
- ndlab.dr_anti_nus(filter='')[source]¶
A list of
ndlab.Dr_anti_nu
- ndlab.dr_beta_ps(filter='')[source]¶
A list of
ndlab.Dr_betap
- ndlab.dr_nus(filter='')[source]¶
A list of
ndlab.Dr_nu
- ndlab.cum_fys(filter='')[source]¶
A list of
ndlab.Cum_fy
- ndlab.ind_fys(filter='')[source]¶
A list of
ndlab.Ind_fy
Data model classes¶
ndlab.Nuclide¶
- class ndlab.Nuclide[source]¶
The properties of given Z and N pair
Note that properties like Half-life, etc are to be accessed through its ground state (gs)
- Variables:
z (int) – number of protons
n (int) – number of neutrons
nucid (str) – nuclide id mass + element symbol 135XE
charge_radius (Quantity) – charge radius
atomic_mass (Quantity) – atomic mass
mass_excess (Quantity) – mass excess
binding_en (Quantity) – binding en
beta_decay_en (Quantity) – beta decay energy
s2n (Quantity) – 2-neutron separation energy
s2p (Quantity) – 2-protons separation energy
qa (Quantity) – Q-value for alpha decay
abundance (Quantity) – natural abundance in mole fraction
gs (Level) – ground state
daughters (Nuclide[]) – direct daughters of the nuclide, including excited states decays
parents (Nuclide[]) – parents of the nuclide
daughters_chain (Nuclide[]) – all possible offsprings of the nuclide
parents_chain (Nuclide[]) – all possible ancestors of the nuclide
decays (Decay[]) – all decays, including fron metastable states, for which decay radiations are given
- csv()¶
Generates a String with the CSV representation for an instance of class
the attribute _cst_title stores the first row of the csv with the field names
- Returns:
the csv
- Return type:
string
- gammas(filter='NO_PARAM')[source]¶
Gamma transitions between levels of this nuclide
- Parameters:
filter (str) – filter passed to the function by the user. It may contain only fields of the NUCLIDE entity
- Returns:
the list of
ndlab.Gamma
of this nuclide
- levels(filter='NO_PARAM')[source]¶
Energy levels of this nuclide
- Parameters:
filter (str) – filter passed to the function by the user. It may contain only fields of the NUCLIDE entity
- Returns:
the list of
ndlab.Level
of this nuclide
ndlab.Level¶
- class ndlab.Level[source]¶
Properties of an energy eigenstate of a Nuclide
z, n, and nucid are for convenience. The can be accessed also through the ‘nuclide’ property
- Variables:
z (int) – number of protons of the nuclide
n (int) – number of neutron of the nuclide
nucid (string) – nuclide’s indentifier, e.g. 135XE
l_seqno (int) – sequential number or the level, 0 being the g.s.
energy (Quantity) – energy in keV
half_life (Quantity) – H-l in the units given by the evaluation
half_life_units (string) – units given by the evaluation
half_life_sec (Quantity) – H-l given in seconds
jp_str (string) – Jp given in the evaluation
jp_order (int) – occurrence of this Jp value, 0 being the one closest to the g.s.
j (float) – Angular momentum assignment given by RIPL
parity (int) – parity assignment given by RIPL
jp_method (string) – method of jp assignment by RIPL
quadrupole_em (Quantity) – Quadrupole electric moment in barn
dipole_mm (Quantity) – Dipole magnetic moment in nuclear magnetons
questionable (string) – whether the existence is questionable
configuration (string) – nuclear configuration
isospin (string) – isospin
nuclide (Nuclide) – access to the nuclide
daughters (Nuclide[]) – the direct daughters of the level decay, if any
- csv()¶
Generates a String with the CSV representation for an instance of class
the attribute _cst_title stores the first row of the csv with the field names
- Returns:
the csv
- Return type:
string
- gammas(filter='NO_PARAM')[source]¶
Gamma transitions starting from this level
- Parameters:
filter (str) – filter passed to the function by the user. It may contain only fields of the LEVEL entity
- Returns:
the list of
ndlab.Gamma
starting from this level
ndlab.Gamma¶
- class ndlab.Gamma[source]¶
Electromagnetic transition between levels of the same nuclide
z, n, and nucid can be accessed also through the ‘nuclide’ property. l_seqno can be accessed though the ‘level’ property
- Variables:
z (int) – number of protons of the nuclide
n (int) – number of neutron of the nuclide
nucid (string) – nuclide’s indentifier, e.g. 135XE
l_seqno (int) – sequential number of the start level, 0 being the g.s.
g_seqno (int) – sequential number of this gamma within the start level gammas, 0 being the lowest energy one
nuclide (Nuclide) – the nuclide
start_level (Level) – the start level
end_level (Level) – the start level
energy (Quantity) – energy [keV]
rel_photon_intens (Quantity) – relative photon intensity %
multipolarity (string) – multipolarity
mixing_ratio (Quantity) – mixing ratio
tot_conv_coeff (Quantity) – total conversion coefficient
bew (Quantity) – reduced electric transition probabilities in Weisskopf units
bew_order (Quantity) – bew order
bmw (Quantity) – reduced magnetic transition probabilities in Weisskopf units
bmw_order (Quantity) – bmx order
questionable (string) – whether the existence is questionable
- csv()¶
Generates a String with the CSV representation for an instance of class
the attribute _cst_title stores the first row of the csv with the field names
- Returns:
the csv
- Return type:
string
ndlab.L_decay¶
- class ndlab.L_decay[source]¶
Decay process
Description of a level decay: parent, daughter, radiations, etc… nucid , l_seqno, and daughter_nucid are for convenience. The can be accessed also through the ‘nuclide’, ‘daughter’, and ‘level’ properties, respectively
- Variables:
nucid (string) – decaying nuclide indentifier, e.g. 135XE
l_seqno (int) – sequential number or the decaying level, 0 being the g.s.
daughter_nucid (string) – daughter nuclide indentifier, e.g. 135XE
perc (Quantity) – decays per 100 decay of the parent
nuclide (Nuclide) – the parent nuclide
level (Level) – the parent level
daughters (Nuclide[]) – the direct daughters of the decay
nuclide – the parent nuclide
mode (Decay_mode) – the decay mode
toten_recoil (Quantity) – total recoil energy [keV]
q_togs (Quantity) – Q-value [keV]
- alphas(filter='NO_PARAM')[source]¶
Alpha radiation from this decay
- Parameters:
filter (str) – filter passed to the function by the user. It may contain only fields of the DR_ALPHA entity
- Returns:
the list of
ndlab.Dr_alpha
from this decay
- annihil(filter='NO_PARAM')[source]¶
Annihilation radiation from this decay
- Parameters:
filter (str) – filter passed to the function by the user. It may contain only fields of the DR_ANNIHIL entity
- Returns:
the list of
ndlab.Dr_annihil
from this decay
- anti_nus(filter='NO_PARAM')[source]¶
Anti neutrino radiation from this decay
- Parameters:
filter (str) – filter passed to the function by the user. It may contain only fields of the DR_ANTI_NU entity
- Returns:
the list of
ndlab.Dr_anti_nu
from this decay
- betas_m(filter='NO_PARAM')[source]¶
Beta- radiation from this decay
- Parameters:
filter (str) – filter passed to the function by the user. It may contain only fields of the DR_BETAM entity
- Returns:
the list of
ndlab.Dr_betam
from this decay
- betas_p(filter='NO_PARAM')[source]¶
Beta+ radiation from this decay
- Parameters:
filter (str) – filter passed to the function by the user. It may contain only fields of the DR_BETAP entity
- Returns:
the list of
ndlab.Dr_betap
from this decay
- convels(filter='NO_PARAM')[source]¶
Conversion electrons from this decay
- Parameters:
filter (str) – filter passed to the function by the user. It may contain only fields of the DR_CONV_EL entity
- Returns:
the list of
ndlab.dr_conv_el
from this decay
- csv()¶
Generates a String with the CSV representation for an instance of class
the attribute _cst_title stores the first row of the csv with the field names
- Returns:
the csv
- Return type:
string
- dr_photon_tot(filter='NO_PARAM')[source]¶
Photons emitted in the decay process, if any, regardless of the daughter or the radiation type (X- or Gamma- ray)
- Parameters:
filter (str) – filter passed to the function by the user. It may contain only fields of the DR_PHOTON_TOTAL entity
- Returns:
the list of
ndlab.Dr_photon_tot
from this decay
- gammas(filter='NO_PARAM')[source]¶
Gamma radiation from this decay
The radiation is emitted by the daughter
- Parameters:
filter (str) – filter passed to the function by the user. It may contain only fields of the DR_GAMMA entity
- Returns:
the list of
ndlab.Dr_gamma
from this decay
- tot_measured_en()[source]¶
Total energy emitted per 100 decays of the parent
calculated as sum (energy * intensity / 100 ) over all radiations
- Returns:
the total energy
- Return type:
- tot_rad_en(radiations)[source]¶
Energy emitted by a set of radiations
calculated as energy * intensity / 100
- Parameters:
radiations (Decay_radiation) – list of any decay radiations
- Returns:
the energy
- Return type:
ndlab.Cum_fy¶
ndlab.Ind_fy¶
ndlab.Decay_radiation¶
- class ndlab.Decay_radiation[source]¶
Base class for decay radiations
Its Attributes are inherited by all the Dr_* classes describing each type of radiation
parent_nucid , parent_l_seqno, daughter_nucid, and daughter_l_seqno are for convenience. The can be accessed also through the ‘nuclide’, ‘daughter’, and ‘level’ properties, respectively
- Variables:
parent (Nuclide) – the parent nuclide
daughter (Nuclide) – the daughter nuclide
parent_level (Level) – the parent level
fed_level (Level) – the daughter level populated by the decay
decay (L_decay) – access to the level decay, with all the other radiations emitted
energy (Quantity) – energy [keV]
intensity (Quantity) – for 100 decays of the parent
parent_nucid (string) – parent nuclide indentifier, e.g. 135XE
parent_l_seqno (int) – sequential number or the parent level, 0 being the g.s.
daughter_nucid (string) – daughter nuclide indentifier, e.g. 135XE
daughter_l_seqno (int) – sequential number or the daughter level populated, 0 being the g.s.
decay_code (int) – code of the decay, see the DECAY_* constants in ndlaborm
ndlab.Dr_gamma¶
- class ndlab.Dr_gamma[source]¶
Gamma decay radiation
Inherits all the attributes of
Gamma
- Variables:
parent (Nuclide) – the parent nuclide
parent_level (Level) – the parent level
decay (L_decay) – access to the level decay, with all the other radiations emitted
intensity (Quantity) – for 100 decays of the parent
parent_nucid (string) – parent nuclide indentifier, e.g. 135XE
parent_l_seqno (int) – sequential number or the parent level, 0 being the g.s.
decay_code (int) – code of the decay, see the DECAY_* constants in ndlaborm
- csv()¶
Generates a String with the CSV representation for an instance of class
the attribute _cst_title stores the first row of the csv with the field names
- Returns:
the csv
- Return type:
string
ndlab.Dr_alpha¶
- class ndlab.Dr_alpha[source]¶
Alpha decay radiation
Inherits all the attributes of
Decay_radiation
- Variables:
hindrance (Quantity) – hindrance factor
- csv()¶
Generates a String with the CSV representation for an instance of class
the attribute _cst_title stores the first row of the csv with the field names
- Returns:
the csv
- Return type:
string
ndlab.Dr_betam¶
- class ndlab.Dr_betam[source]¶
Beta- decay radiation
Inherits all the attributes of
Decay_radiation
Contains the energy of the associated anti-neutrino- Variables:
- csv()¶
Generates a String with the CSV representation for an instance of class
the attribute _cst_title stores the first row of the csv with the field names
- Returns:
the csv
- Return type:
string
ndlab.Dr_betap¶
- class ndlab.Dr_betap[source]¶
Beta+/Electron Capture decay radiation
Inherits all the attributes of
Dr_betam
Contains the energy of the associated neutrino- Variables:
- csv()¶
Generates a String with the CSV representation for an instance of class
the attribute _cst_title stores the first row of the csv with the field names
- Returns:
the csv
- Return type:
string
ndlab.Dr_anti_nu¶
- class ndlab.Dr_anti_nu[source]¶
Anti neutrino decay radiation
Inherits all the attributes of
Decay_radiation
Contains the energy of the associated electron- csv()¶
Generates a String with the CSV representation for an instance of class
the attribute _cst_title stores the first row of the csv with the field names
- Returns:
the csv
- Return type:
string
ndlab.Dr_nu¶
- class ndlab.Dr_nu[source]¶
Neutrino decay radiation
Inherits all the attributes of
Decay_radiation
The fields energy, intensity, log_ft, trans_type, endpoint, bp_energy refer to the emission via beta+ process The fields intensity_ec, energy_ec refer to the emission via electron capture- Variables:
intensity (Quantity) – intensity for emission via beta+ process
energy (Quantity) – mean energy for emission via beta+ capture process
intensity_ec (Quantity) – intensity for emission via electron capture process
energy_ec (Quantity) – mean energy for emission via electron capture process
logft (Quantity) – Log ft for the beta+ decay
endpoint (Quantity) – end point energy [keV] the beta+ decay
trans_type (String) – transition type
- csv()¶
Generates a String with the CSV representation for an instance of class
the attribute _cst_title stores the first row of the csv with the field names
- Returns:
the csv
- Return type:
string
ndlab.Dr_delayed¶
- class ndlab.Dr_delayed[source]¶
Delayed particle emission
Inherits all the attributes of
Decay_radiation
- Variables:
energy_x (Quantity) – energy of the intermediate state
particle (string) – delayed particle
- csv()¶
Generates a String with the CSV representation for an instance of class
the attribute _cst_title stores the first row of the csv with the field names
- Returns:
the csv
- Return type:
string
2. ndlaborm module¶
The static classes in this module are described in here. They are the building blocks of the fields and filter parameters of the data-retrieval functions.
For example to refer to the level-energy, use LEVEL.ENERGY
You can access the code and its comments here
3. ndlabdblink module¶
Talks with the database and retrieves the data. You can access the code and its comments