1 Introduction

As our understanding of nuclear physics continues to evolve, it is becoming increasingly important to have easy access to reliable, comprehensive and updated nuclear structure data. Accurate data are essential for theoretical model, data analysis software and simulation code development, and plays a crucial role in advancing our understanding of the behavior of atomic nuclei.

Over the past few decades, significant progress has been made in the experimental measurement of nuclear structure data, resulting in a vast amount of information on isotope ground states (binding energy, abundance...), excited states (energy, lifetime, spin-parity...) and decays (energy, branching ratio, multipolarity...). These information are compiled by different research groups and spread among different databases. Nuclear structure and decay data are, for example, compiled and evaluated by the International Network of Nuclear Structure and Decay Data (NSDD) evaluators that provide recommended values to be used in basic and applied research [1].

These databases, already widely used in the scientific community, were historically created as text files with non-standard formats, and are mainly used to feed websites. However, accessing and utilizing these data with automatic processes, inside analysis codes, has remained challenging for many researchers due to the complexity and diversity of formats of the available data sets. To address this issue, we developed the Toolkit for Nuclei (TkN) C++ library that provides easy access to nuclear structure data. Our software utilizes a comprehensive and frequently updated database, built from different sources described in Sect. 2.1.

2 The TkN database

The TkN library aims at giving access to a large amount of properties of chemical elements, nuclear isotopes, excited states and decays. These properties are gathered from different official sources and merged in a homemade and periodically updated SQlite [2] database. This update process is guaranteed at least as long as the data sources are publicly available.

2.1 Data sources

The information on chemical elements are downloaded from the PubChem website [3] in JSON format [4]. The different units were added manually, and column names have been slightly adapted. X-ray data are extracted from the X-RAY DATA BOOKLET [5] and then converted in JSON format.

The largest database in nuclear physics that have been used in this project is provided by the International Network of Nuclear Structure and Decay Data evaluators (NSDD) [1], named “Evaluated Nuclear Structure Data File” (ENSDF) [6]. It contains all the published values in nuclear physics on the excited states and decay properties, after being evaluated by the NSDD members using well-defined methodologies. The coordination of the evaluation effort and its web and journal dissemination is carried out by the National Nuclear Data Center (NNDC) at Brookhaven National Laboratory [7].

This database has the great advantage of having, for each nucleus, separated data-sets dedicated to the reaction mechanism that has been used to produce the nucleus of interest, and a combined one, named “adopted levels and gammas,” that merge all the individual data-sets in one. The disadvantage of this database is that it is stored in an old ASCII-file that is not trivial to decode. NNDC is also providing another database in the same format, named “eXperimental Unevaluated Nuclear Data List” (XUNDL) [8], containing published data, but still waiting to go through the NSDD evaluation process.

Another rich and useful database that has been used is the one distributed by the Nuclear Data Section of the International Atomic Energy Agency (IAEA-NDS), called Live Chart [9]. This database is using the ENSDF as input, but also a wider range of data sources very useful for nuclear ground-state properties as:

  • The atomic mass evaluation [10, 11] for mass excess values,

  • The nubase evaluation [12] for abundance and year of discovery of isotopes,

  • The nuclear ground-state charge radii [13],

  • The nuclear magnetic dipole moments [14, 15],

  • The nuclear electric quadrupole moments [16]

It provides powerful searching and plotting tools for web applications and recently, an API has been distributed to download the database content in CSV file format [17]. The disadvantage of this database is that it does not contain the individual data-sets of ENSDF (only the “adopted” one).

The last database that has been used in this project is the NUDAT3 [18] database, distributed by NNDC. Most of its data sources are similar to the already discussed one, but some additional information can be obtained like the quadrupole deformation, or yields of \(^{252}\)Cf spontaneous fission source or \(^{235}\)U and \(^{239}\)Pu thermal neutron-induced fission. This database is directly downloaded from the NUDAT3 web site in JSON format.

As a consequence, it has been decided to combine these three databases to take all the data related to nuclear and decay properties from ENSDF and XUNDL databases, the ground-state properties from the IAEA-NDS API and the remaining missing from NUDAT3.

The TkN database is thus built by parsing ASCII, CSV and JSON files, with dedicated classes (see Sect. 3.1), to fill the homemade SQlite TkN database, much more efficient in terms of access time. This SQlite database is to be seen as a TkN internal object, transparent for the user, used to fasten and facilitate the access to the data by the user interface (see 3.2). It should be noted that TkN is not to be compared to the existing databases mentioned. It is a complementary utility for different applications. For a fast web search on a very specific query, the existing web-based databases like ENSDF or Live Chart are much more user-friendly and efficient. But for integration into analysis or simulation code with high computation needs, the TkN database is more suited.

2.2 References

When a work using TkN is published, it is essential that, in addition to this article, references are made to the original databases used. If the experimental data used are from ENSDF or XUNDL databases, citation guidelines are specified on the ENSDF website [6]. For data coming from NUDAT3, as mentioned on their website, it is recommended to use the following reference: “National Nuclear Data Center, information extracted from the NuDat database, https://www.nndc.bnl.gov/nudat/.” For the other sources (chemical element properties, X-rays or data coming from the IAEA-NDS API, the aforementioned references in Sect. 2.1 have to be used.

2.3 Database structure

The database structure was designed to avoid as much information redundancy as possible. It is composed of five tables linked with foreign joints as presented on Fig. 1. The content of the tables is the following:

  • element: properties of chemical elements,

  • isotope: ground-state properties of all known isotopes of each element,

  • dataset: a dataset links the information of a given nuclear level scheme (levels and decays) to the way the nucleus has been produced,

  • level: excited states properties, each level being associated to the isotope it belongs and the dataset it was extracted from,

  • decay: decay properties, associated to the parent and daughter levels.

The full list of table columns is detailed in Appendix A. In its current format, the TkN database contains 118 elements, 3559 isotopes, 23,523 datasets, 602385 levels and 760,888 decays for a total size of about 180 MB.

For the data following the ENSDF data format [19] (ENSDF and XUNDL sources), the choice has been made to only parse properties having a dedicated field in this format. Some other properties are given as comments in this format, as band structures, cross sections. Extracting automatically such information is not straight-forward and is thus not included in the current TkN version. Nevertheless, if users have specific needs that can be extracted, the missing data can be added case by case in the next TkN releases.

Fig. 1
figure 1

Schematic layout of the TkN database. The detailed content of each table is listed in Appendix A

Full size image

2.4 Database generation

X-ray and element properties are not frequently updated: the associated input files are directly stored in the TkN sources. However, isotope properties (ground state, levels and decays) are in constant evolution. For this reason, the TkN database is regenerated every month to take into account each new release of nuclear structure data evaluation.

To allow for data versioning, each database contains the dates of the ENSDF and XUNDL release used. The automatic database generation is handled by a crontab task [20] executed on CNRS servers every 15th of each month. The user can then download or update the TkN database to integrate any new published physics properties, using the dedicated executable (see 3.3).

3 Code structure

The TkN library is made of two parts: the first one allows to build the SQlite database, while the second one provides an interface for the user to access the data. Each part is made of C++ classes, under the tkn namespace, and some program utilities.

3.1 Database builder

The first part of the TkN library is in charge of collecting the information from the different sources and building the SQLite [2] database. From the code point of view, this corresponds to the classes in the directory src/builder and of some executable programs dedicated to this task.

The builder directory is composed of individual classes, each dedicated to its specific SQL table in the database. These classes are in charge of parsing the input data files from the different sources described in Sect. 2.1, and writing the extracted information in the database. The dataset, level and decay tables are handled by a global builder class (ensdf_builder) since they require to parse ENSDF data file format [19].

Since the TkN database is not built by the user, this part of the library was only included in the project for sake of information. It is not compiled by default but can be activated using a dedicated CMake [21] flag.

3.2 User interface

The TkN user interface is a C++ shared library providing multiple classes to access the database and manipulate in an intuitive way its content. When creating a new nucleus (tknucleus class), either by its name or atomic and mass number, the user can access any of the properties cited in Sect. 2.3, using specific predefined methods.

Data on excited states and decays are handled by the tklevel_scheme class. The ENSDF database provides information from different datasets that correspond to different reaction mechanisms used to produce a nucleus. To take it into account in the TkN database, each nucleus is associated to a list of available datasets, corresponding to a specific level scheme that contains its nuclear levels and decays. As defined in the ENSDF format, a global dataset named: “ADOPTED LEVELS, GAMMAS” is used to merge all the individual datasets in one. If it exists, this is the default dataset of any nucleus. To access to the nuclear properties of a nucleus, the user can either use the global dataset, or select a specific dataset, depending on the physics case. In case of XUNDL datasets, a specific tag is added to specify that the dataset has not yet been evaluated.

As stated on the NNDC website [7], this database contains evaluated nuclear data, i.e., recommended values following a careful analysis of the available data. However, the accuracy of the data, the absence of errors or the absence of conflicting datasets cannot be guaranteed. The aim of this work is not to analyze the accuracy of the sources used, but to facilitate access to them.

The level scheme class (tklevel_scheme) also links levels and decays: each decay is associated to the parent and daughter levels, and each level contains a list of populating and depopulating decays, allowing for example to easily determine coincident decays.

The information on a measure (e.g., a level lifetime) is handled by a tkmeasure object. A TkN measure contains, if defined: a value, an uncertainty (symmetric or asymmetric), a unit, and a tag. The tag can contain different information, such as the fact that a value is given as a lower or upper limit or results from a calculation or a systematic. For example, in the case of the spin and/or parity assignment of a nuclear level, its attribution can be tagged as firm or tentative.

A measure comes, in most cases, with a unit. A dedicated unit manager has been implemented in TkN to allow a measure to be expressed in the desired unit. In general, units can be converted only in the scale of a same type (time, energy or length). One exception is given for the energy to time conversion. Indeed, the lifetime of very short lived levels is often expressed in terms of its intrinsic width (energy type unit).

The interface between the SQlite database and the user classes is handled by the tkmanager class. For optimizing the TkN efficiency, it has been decided to preload all the element and nucleus ground-state properties at the creation of the tkmanager singleton. This allows the manager to know the full list of available nuclei. Methods are provided to allow for the user to conveniently loop over the available nuclei. However, the amount of data contained in ENSDF, taking into account all the known levels, decays and datasets is so important that is has been decided to not preload all of them by default. It has been preferred to load in memory the content of a level scheme (so for a given dataset), only when the user accesses it for the first time. Once a level scheme has been loaded, it stays in memory.

3.3 TkN programs

To generate the database, the TkN builder part comes with three executable programs:

  • tkn-ensdf-update: downloads the NNDC data files,

  • tkn-create: builds the TkN SQlite database, calling the different builder classes,

  • tkn-explorer: explores the TkN SQlite database (a more user-friendly equivalent is included in the user interface programs).

Regarding the user interface, TkN provides different executable programs:

  • tkn-db-update: downloads/updates TkN database,

  • tkn-root: opens a ROOT [22] prompt terminal with the TkN library linked (compiled only when using ROOT, see part 4.1),

  • tkn-print: lists in the terminal different properties for a given nucleus,

  • tkn-config: provides information on the current TkN installation (version, git branch, compilation flags...) that are useful for linking TkN to other packages (inspired from the root-config executable of the ROOT package).

3.4 Examples

A list of examples is provided in the TkN project to help users manipulate the various data accessible in the TkN database. As an example, Fig. 2 is produced with TkN, and the source code is provided in the examples. This image represents the sudden increase of nuclear deformation at N = 60 in the A\(\sim \)100 island of deformation region, using four different experimental observables: the two neutron separation energy, measured from mass measurements \(S_{{{\text{2n}}}} \), the nuclear charge radius \( r_{{{\text{ch}}}} \), the normalized electric transition probability of the first E2 gamma transition B(E2:\(2^+_1 \rightarrow 0^+_1\))/A and the first \(2^+\) state energy \(E(2^+)\). Without TkN, producing such an image would require to extract data from the literature on ground state, nuclear levels and gamma decay properties for all these nuclei. Using TkN, it requires only a few lines of code.

Fig. 2
figure 2

Representation the sudden increase of nuclear deformation at N = 60 in the A\(\sim \)100 island of deformation region, using four different experimental observables: the two neutron separation energy \(S_{{{\text{2n}}}} \), the nuclear charge radius \( r_{{{\text{ch}}}} \), the normalized electric transition probability B(E2:\(2^+_1 \rightarrow 0^+_1\))/A and the first \(2^+\) state energy \(E(2^+)\)

Full size image

In addition, a dedicated ROOT based C++ class, named tknuclear_chart, has been implemented to provide for the user a convenient way to represent physical values over the Segrè chart. Figure 3 is using this class to represent the nuclear mass excess as a function of the proton and neutron number. The bottom and left panels present the mass excess projected respectively on the neutron/proton numbers, for each isotopic/isotonic chains.

Fig. 3
figure 3

Mass excess of all measured isotopes using the tknuclear_chart class for graphical representation

Full size image

3.5 Performances

Building the tkmanager (i.e., reading the full element and isotope tables) requires few milliseconds. The time needed to read all the levels and decays of all the known isotopes for the first time is about 13 s. As it is then stored in memory, a second reading of the complete database is of the order of 20 ms.

The TkN user interface has been developed in order to be thread safe. In other words, it can be used in a multi-threaded program without any thread conflicts. Some tests have been realized on a machine with two CPU Intel(R) Xeon(R) Silver 4112 @ 2.60GHz, for a total of 16 available threads. The program used (available on the TkN documentation, see Sect. 4.4) generates a random existing nucleus, from which a random nuclear level is read in its default level scheme. The time needed to generate \(10^{8}\) levels with a single thread is around 170 s (13 s to load the database and 157 s for the processing). With 16 threads, this time drops to 30 s (still 13 s to load the database and 17 s for the processing).

4 Software management

4.1 Software prerequisites

One of the main goal of the TkN library development was to provide a light library, easily linkable to any other software. For this reason, it has been decided to limit as much as possible the prerequisites:

  • An Unix architecture (MacOS or Linux),

  • Git (to download and update the project),

  • A cmake version at least 3.8 (project written using the modern CMake techniques and methods),

  • A compiler supporting C++17 (a C++11 patch is also provided),

  • If linked with ROOT, a ROOT version greater than 6.20.

The SQLite library is integrated inside the TkN source code using the amalgamation file. The JSON parser NLohmann [23] is also integrated as a single header file integration.

4.2 Code distribution

The TkN source code is hosted on the IN2P3 Gitlab server [24]. This allows for code version control, multiple developers collaboration, use of continuous integration process and automatic documentation generation.

Regarding the code development organization, TkN is hosted on a main git repository containing a production and a preproduction branch. Each new development, which has been tested and validated, is pushed on the preproduction branch. For each new code release, the preproduction branch is pushed on the production branch, generating a dedicated tag associated to a new TkN version number. Any developer works on its own forked repository and merge the new developments on the main repository once validated.

The TkN version number is composed of a major and a minor number (e.g., 1.0). Each new minor value corresponds to new features in the library that don’t break the compatibility with TkN database content. On the contrary, a new major number means that the database content has been modified (e.g., new physics properties added). For this reason, the database generation is associated to a TkN version number, to ensure the compatibility between the source code and the database format.

This project is distributed under the CECILL-B license [25], which is a free software license agreement for CNRS members.

4.3 Continuous integration

The source code is automatically built and tested using the Gitlab continuous integration (CI) capabilities. A dedicated docker [26] image has been created to manage the CI operations. After any new git push on the TkN repository, the project is compiled with the different compilation options (e.g., with or without ROOT), and the unitary tests performed using the GoogleTest [27] framework are executed.

On the preproduction branch, a Cppcheck analysis [28] of the code is executed, and analyzed using SonarQube [29].

4.4 Documentation

The TkN code is fully commented and documented on a dedicated web site [30] hosted on Gitlab pages. The C++ code comments are integrated in the documentation using the Doxygen framework [31], providing indications on how to use any C++ methods and classes of the library. In addition, the documentation web site includes a comprehensive user guide to provide users with information on data sources, latest release notes, help with installing TkN or linking it to other projects and a comprehensive manual of TkN’s main features. Finally, many examples are provided.

The TkN documentation is automatically generated by the Gitlab CI configuration. The home page of the web site is dedicated to the production branch of the Gitlab repository, but the other git branches documentation can be accessed using specific sub pages.

5 Conclusions and perspectives

The TkN project provides to physicists a new, fast and user-friendly interface library to access and manipulate a huge amount of published data related to atomic and nuclear physics. As an example, it is already used in the Cubix software [32] that provides a new graphical user interface for gamma-ray spectroscopy analysis. TkN is used in this project to show, on a gamma-ray spectrum, the transitions already known in the observed nuclei, or to find which nucleus can correspond to the transitions measured in coincidence.

Nevertheless, a selection has been made by the developers, which is not exhaustive, of the data type to include in this database. Its content will evolve, depending on the uses and wishes of the community. For example, it is already planned for the next major version, to include particle non-electromagnetic decays. There are also longer-term plans to integrate nuclear reaction databases like the experimental nuclear reaction data (EXFOR) [33, 34].

Another aspect of the perspectives for the TkN library is to make it accessible to a wider part of the scientific community, by providing python and Julia interfaces.