 |
TkN 2.5
Toolkit for Nuclei
|
|
TkN 2.5
Toolkit for Nuclei
|
The TkN library gives access to a large amount of nuclear properties as:
These properties are taken from different official sources (see the data sources section) and merged in a sqlite3 home-made database.
In the ENSDF database, used for levels and decay properties, more than one dataset can be accessible for a given nucleus (usually one dataset per reaction). This is taken into account in TkN using the dataset manager
To easily browse the database, a database manager is provided. It allows for example to create list of nuclei on given ranges of neutron or proton numbers, or any other selections.
To manage the different data units, a units manager is also provided to convert the data extracted from the database in the requested units.
Finally, TkN has been developed in thread safe way to allow a multi-thread access to the TkN database.
All the following used classes are part of the 'tkn' namespace. If you are using the tkn-root executable, the namespace is already loaded, but in a c++ macro or project, use the following for an easier access:
To access any nuclear property, a tknucleus needs to be created. it can be created using its symbol, or its proton and mass number:
A nucleus can also be create only using it's element name or charge number. In such case, the most stable isotope will be returned, and the most abundant in case of multiple stable nuclei:
The main properties of a nucleus can be printed with:
For each element, the following properties can be available:
Then, for each isotope, the following properties can be available from the databases (see (see the data sources section)):
From the mass excess values, the following properties are calculated in TkN:
to see the available properties for a given nucleus, use the tknucleus::list_properties() method:
The results can be filtered using a regular expression:
To test if a property is available, use the use the tknucleus::has_property() method:
For a faster access to the most used properties, few specific methods have been added to tknucleus objects:
| method name | description |
|---|---|
| get_a() | nucleon number |
| get_n() | neutron number |
| get_z() | proton number |
| get_symbol() | nucleus name (ex: 12C) |
| get_element_name() | element name (ex: Carbon) |
| get_element_symbol() | element symbol (ex: C) |
| is_known() | returns true if the nucleus is known in the database |
| is_stable() | returns true if the nucleus is stable |
| is_bound() | returns true if the binding energy is positive |
| is_z_magic() | is Z a magic number |
| is_n_magic() | is N a magic number |
| is_doubly_magic() | is nucleus doubly magic |
| get_abundance() | abundance for stable nuclei (in %) |
| get_binding_energy_over_a() | binding energy per nucleon (MeV) (unit as parameter) |
| get_lifetime() | ground state lifetime in seconds (unit as parameter) |
| get_mass_excess() | mass excess (MeV) (unit as parameter) |
| get_radius() | charge radius (fm) |
| get_magnetic_dipole() | magnetic dipole moment (μN) |
| get_electric_quadrupole() | electric quadrupole moment (barn) |
| get_jpi() | ground state spin and parity as a string |
| get_xrays() | vector of the known xray energies |
| get_decay_mode_str() | decay modes as a string |
| get_decay_modes() | decay modes as a vector of decay and branching ratio |
| get_discovery_year() | year of discovery of the isotope |
| get_ground_state() | access the ground state tkn::tklevel |
| get_level_scheme() | access the tkn::tklevel_scheme |
| get_fission_yield(tkstring _parent, bool _cumulative=false) | get the fission yield of for a given fissioning nucleus (cumulative or not) |
The above methods giving access to a measure (ex: get_lifetime() ), are directly returning the value as a double. Dedicated methods allows to access the tkn::tkmeasure to access to units, uncertainties... etc (see Measures and units).
For exemple, for the lifetime, the method get_lifetime_measure() returns the tkmeasure object.
For all the nuclei with known data on the ENSDF or XUNDL databases, it is possible to access to a tkn::tklevel_scheme object.
The level scheme is determined for a given dataset see the dataset section.
For one dataset, the level scheme gives access to the nuclear levels and decay information see the level section or the decay section
For any nucleus, it is possible to access to its level scheme composed of the known levels and decays. Print the known levels as follows:
The level list can be retrieved using:
or using a lambda function to filter the levels (e.g. all the positive parity states in):
A level can also been accessed directly by its name (e.g. the first 3⁺ state):
, or using its energy (the closest level in energy will be returned):
The get_level(...) methods return a tkn::tklevel object, and the get_levels(...) methods return a vector of tkn::tklevel objects.
In some cases, a level or a full band is known only relatively to an offset X because the bandhead energy is not known. The level energy in this case is its energy related to the bandhead offset (ex: X+100). The default method get_energy() in this case will return a "nan" value to avoid confusions. To test if a level is known only with an offset, use the method is_energy_offset(). To obtain its relative energy, use the get_energy() with the _with_offset option.
Here are the main method that can be applied on a tklevel:
| method name | description |
|---|---|
| get_energy() | returns the energy in keV |
| is_energy_offset() | to know if the level is only known relatively to an offset |
| get_offset_bandhead() | returns the band offset value |
| get_lifetime() | to get the lifetime in seconds |
| get_spin_parity() | to get the spin and parity as a tkn::tkspin_parity object |
| get_spin_parity_str() | to get the spin and parity as a string |
| is_stable() | returns true if the level is stable |
| is_isomer() | returns true if the level is an isomer |
| get_isomer_level() | returns the isomer level (1st, second,...) |
| is_yrast() | returns true if the level is yrast |
| get_decays_up() | returns the list of decays that populate this level |
| get_decays_down() | returns the list of decays that depopulate this level |
| has_comment() | returns true if a comment on this level exists |
| get_comment() | returns the comment on this level |
| is_uncertain() | returns true if the level is uncertain |
| print() | prints the main level information (as already used above) |
The above methods giving access to a measure (ex: get_lifetime() ), are directly returning the value as a double. Dedicated methods allows to access the tkn::tkmeasure to access to units, uncertainties... etc (see Measures and units).
For example, for the lifetime, the method get_lifetime_measure() returns the tkmeasure object.
As for the levels, from the level scheme, it is possible to access to all the known decays of a nucleus. In the current version, only gamma decays are implemented. Support for additional decay types (beta, EC, alpha, particle) is planned in a future version.
Print the known decays as follows:
It is also possible to print at the same time the levels and its associated decays:
As for the levels, The decay list can be retrieved using:
It is also possible to restrict the decay list to a type of decay:
As for the moment only tkn::tkgammadecay are included, it is advised to only use this second option to easily benefit from the tkgammadecay methods on the decay list.
The same can be done using a lambda function to filter the decays (e.g. only decays coming from a level lower than 1 MeV):
A decay can also been accessed directly by its name (e.g. the decay from the first 3⁺ to the first 2⁺ state):
, or using its energy (the closest level in energy will be returned):
The get_decay(...) methods return a tkn::tkdecay object, and the get_decays(...) methods return a vector of tkn::tkdecay objects. As explained, if we want to play only with gamma decays, the template access get_decay<tkgammadecay>(...) methods return a tkn::tkgammadecay object, and the get_decays<tkgammadecay>(...) methods return a vector of tkn::tkgammadecay the tkn::tkgammadecay class inherits from the tkn::tkdecay, so all methods applicable for a tkdecay are also valid for a tkgammadecay.
Here are the main method that can be applied on a tkdecay:
| method name | description |
|---|---|
| get_energy() | to get the energy in keV |
| get_decay_type() | to get the decay type (enum: kgamma, kbeta, kec, kalpha, kparticle); currently only kgamma decays are stored in the database |
| get_level_from() | returns the parent level |
| get_level_to() | returns the daughter level |
| has_comment() | returns true if a comment on this level exists |
| get_comment() | returns the comment on this level |
| is_uncertain() | returns true if the level is uncertain |
| print() | prints the main decay information (as already used above) |
Here are the main method that can be applied on a tkgammadecay:
| method name | description |
|---|---|
| get_relative_intensity() | get the gamma relative intensity (100% corresponds to the most intense gamma-ray) |
| get_mixing_ratio() | get the mixing ratio |
| get_conv_coeff() | get the gamma conversion coefficient |
| get_trans_prob(bool _elec, int _L, bool _WU) | get the transition probability |
| get_multipolarity() | get the transition multipolarity as a string |
The above methods giving access to a measure (ex: get_conv_coeff() ), are directly returning the value as a double. Dedicated methods allows to access the tkn::tkmeasure to access to units, uncertainties... etc (see Measures and units).
For example, for the lifetime, the method get_conv_coeff_measure() returns the tkmeasure object.
The database used for the levels and decays is extracted from the ENSDF database.
For a given nucleus, the database is composed of different validated datasets, corresponding to different ways to produce the nucleus. A global dataset named : "ADOPTED LEVELS, GAMMAS" is used to merge all the different datasets in one. This is the default dataset of any nucleus in TkN.
TkN allows to load the different datasets. For a given nucleus, the datasets and their associated ID can be listed using:
The datasets are displayed in two sections: evaluated ENSDF datasets and non-evaluated XUNDL datasets. The publication date of each dataset (in YYYY-MM format) is shown in brackets when available, e.g. [2024-01].
To display dataset comments alongside the list, pass the "com" option:
The dataset can be selected as follows (using the Coulomb Excitation dataset ids):
The current dataset object can be retrieved and inspected programmatically:
To iterate over all available datasets:
Here are the main methods available on a tkdataset:
| method name | description |
|---|---|
| get_id() | returns the dataset integer ID |
| get_name() | returns the dataset name as a string |
| get_comment() | returns the dataset comment string (can be empty) |
| has_comment() | returns true if a comment is available |
| get_date() | returns the publication date in YYYY-MM format (can be empty) |
| has_date() | returns true if a publication date is available |
| get_source() | returns the source string: "ENSDF" or "XUNDL" |
| is_xundl() | returns true if the dataset comes from XUNDL |
The TkN data manager is key part of the TkN library. It reads the TkN sqlite3 database, builds the C++ structures in memory and makes the links between these structures and any object created by the user. This way, the level scheme of a nucleus is only built once, even if the user creates the corresponding nucleus millions of times.
It also allows the user to easily browse the full database via the use of the gmanager singleton. For example, we can loop on all the existing nuclei using:
As seen previously with the levels and decays, we can also use a lambda expression to filter the list of nuclei, e.g. the carbon isotopes:
Some tools are also provided to easily loop on the Z or N known ranges:
To handle the fact that a measure is always associated to a specific unit and an uncertainty, that can be in some cases asymmetric, a dedicated class called tkn::tkmeasure has been created.
In addition, a tkmeasure gives some properties on the measure, like if the measure is uncertain, is coming from a systematic study or from calculations. It can also handle the fact that some measures are given as a limit value.
The standard way to access a tkmeasure is using the tkproperty_list::get() method:
To list the accessible tkmeasure properties, use:
The same applies for a tklevel or a tkdecay:
In this case, the lifetime uncertainty is asymmetric, we can access it as follows:
As seen in the tkn::tkmeasure class, tkn offers the possibility to convert some measure into different units
Currently, tkn handles three unit types: Energy, Time and Length. Few other units are included in tkn but that cannot be converted
The available energy units are the following: eV, keV, MeV, GeV, TeV
The available time units are the following: as, fs, ps, ns, us, ms, s, min, h, d, y
The available length units are the following: am, fm, pm, nm, um, mm, cm, m
In general, units can be converted only in the scale of a same type. One exception is given for the energy to time conversion. For very low lifetimes, it is common to express the width of a level in energy. This conversion is taken into account in tkn.
The TkN library can be used in a multi-threaded code.
In the examples, you can find an example of a multi-thread use of the TkN library, see the example
1.13.2