 |
TkN 2.3
Toolkit for Nuclei
|
|
TkN 2.3
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.
Finnally, TkN has been developped 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_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_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_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 is 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 is 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 is the level is stable |
| is_isomer() | returns true is the level is an isomer |
| get_isomer_level() | returns the isomer level (1st, second,...) |
| is_yrast() | returns true is the level 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 a the level is uncertain |
| print() | prints the main level informations (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 exemple, 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. Particle decays are planned to be added in next TkN 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:
Is 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_levels(...) 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_levels<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 [kbeta, kec, kalpha, kparticle, kgamma], but only kgamma for the moment |
| 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 a the level is uncertain |
| print() | prints the main level informations (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% correspond the the more intence gamma-ray) as a tkn::tkmeasure |
| 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 exemple, 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:
As shown in the above example, TkN also include the non evaluated datasets (XUNDL). These datasets are coming from recently published data, but that have still not been evaluated by the National Nuclear Data Center.
The dataset can be selected as follows (using the Coulomb Excitation dataset ids):
The TkN data manager is key part of the TkN library. It reads the TkN sqlite3 database, build the C++ structures in memory and make 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 create the corresponding nucleus millions times.
Is 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 assymetric, 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 strudy 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 asymetric, 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 en Lenght. 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 lenght 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