GIDI+: a GNDS 2.0 suite of C++ APIs to access nuclear and atomic data for use in radiation transport codes

. GIDI + is a C ++ package that reads GNDS formatted nuclear reaction and structure data, and photo-atomic reaction data as needed by radiation transport codes. As of version 3.25, GIDI + supports reading GNDS 2.0 formatted data. GNDS is a new extensible hierarchy that has been internationally adopted as the new standard for storing nuclear and photo-atomic data, replacing ENDF-6 which has been the standard since the 1960’s. GIDI + 3.25 supports the GNDS 2.0 map ﬁle which can contain a list of all GNDS data needed to make a complete nuclear reaction data library as needed by radiation transport codes. GIDI + has functions that make it easy to obtain multi-group data from a GNDS ﬁle, including summed data (e.g., summing multi-group reaction cross sections to obtain the total multi-group cross section). In addition, the MCGIDI sub-package of GIDI + can be used by Monte Carlo transport codes to look up data (e.g., cross section, deposition energy) as a function of projectile energy and material temperature. The MCGIDI sub-package can use either GNDS multi-group or continuous energy data. MCGIDI also has functions for sampling a reaction from a GNDS reactionSuite and functions for sampling a reaction’s outgoing particle energy and angular data. Recent work on GIDI + includes: supporting GNDS 2.0, speeding up load times and adding support for URR probability tables. GIDI + is currently implemented in LLNL’s Mercury [4] (Monte Carlo) and Ardra [5] (deterministic) radiation transport codes. An e ﬀ ort to update GEANT4 to use the latest GIDI + is underway and should be completed by March 2023. GIDI + is released under the MIT license and can be found at github.com / LLNL / gidiplus.


Introduction
The Generalized Nuclear Data Structure [2,3] (GNDS) is a new standard for storing nuclear reaction and structure data as well as photo-atomic reaction data. Version 2.0 of GNDS has recently been approved by an international community. This paper's focus is on the General Interaction Data Interface code package (GIDI+) which is a suite of C++ APIs and some C codes that can be used by radiation transport codes to read and access GNDS data from a file. The latest GIDI+ version 3.25 supports GNDS 2.0 data and can be downloaded at github.com/LLNL/gidiplus.
The main sub-packages of GIDI+ are LUPI, HAPI, PoPI, GIDI, MCGIDI and numericalFunctions. A brief description of each and needed third party packages follows.

LUPI
The Livermore Utility Package Interface (LUPI) is a set of C++ convenience functions and classes used by the other C++ sub-packages in GIDI+. In general, user do not interact with this sub-package.

HAPI
The Hierarchical API (HAPI) package is a set of C++ classes designed to serve as an abstract layer between other GIDI+ sub-package and GNDS files. In this way, only HAPI needs to know what file type (e.g., XML, HDF5) is used to represent the GNDS data. In general, user do not interact with this sub-package.

PoPI
The Properties of Particles Interface (PoPI) package is a set of C++ functions and classes for reading and accessing GNDS PoPs data.

GIDI
The General Interaction Data Interface (GIDI) package is a set of C++ functions and classes for reading and accessing data in GNDS map and reactionSuite files. In addition, GIDI reads LLNL fluxes and multi-group files. An LLNL fluxes file uses existing GNDS nodes to store a list of fluxes as a function of temperature T , projectile energy E and outgoing particle angle θ (i.e., f (T, E, µ) where µ = cos(θ)). An LLNL multi-group file uses existing GNDS nodes to store a list of multi-group boundaries. The fluxes and multi-group files are useful for storing fluxes and multi-group boundaries needed to generate multi-group data and for collapsing multi-group data.

MCGIDI
The Monte Carlo General Interaction Data Interface (MCGIDI) package is a set of C++ classes that can be used by a Monte Carlo transport code to look up the value of a physical quantity (e.g., cross section) and to sample a reaction and its outgoing particle data (i.e., energy and angles). MCGIDI loads its data from GIDI class instances. MGIDI classes have functions to serialize their data for MPI and GPUs use, and can run on GPUs (e.g., CUDA and HIP).

numericalFunctions
This is C package that is used by both GIDI+ and FUDGE [1] to support math operations on onedimensional point-wise functions (e.g., adding two pointwise cross sections). In general, user do not interact with this sub-package.

Third party code packages
In addition to GIDI+, the third party code package pugixml 1.8 must be download and placed in the GIDI+ Misc sub-directory. Note, it is the zipped pugixml-1.8.zip file that GIDI+ needs. This package is used by HAPI to parse XML files. If HDF5 support is needed, then HDF5 must be installed separately and GIDI+ must be told the installed location of HDF5 via the HDF5_PATH Makefile macro or environmental variable.

Installing GIDI+
GIDI+ can be downloaded from the site github.com/LLNL/gidiplus. At this site, the README.md section describes how to download GIDI+ and more details on how to build it. GIDI+ uses a Makefile to build and generally a user only needs to define the macros CXX, CXXFLAGS, CC and CFLAGS to build GIDI+. In fact, often only the C++ option -std=c++11 is needed as GIDI+ implements some C++ 11 features. The following two unix commands will build GIDI+ and check the build, respectively: make -s CXXFLAGS="-std=c++11" make -s CXXFLAGS="-std=c++11" check The following shows an example of how to include HDF5 support in the build: make -s CXXFLAGS="-std=c++11" \ HDF5_PATH="/usr/lib64" Table 1 shows an example of the usage of GIDI+ with line numbers of the left side for reference. GIDI and MCGIDI allow the user to choose which particles will be transported. Currently, LLNL data libraries 1 support 1 Most data libraries currently only give complete information for transporting neutrons. the transporting of n, p, d, t, h, a and γ but GNDS and GIDI+ are not restricted to these particles. Any particle with complete transport data (e.g., with multiplicity and distribution specified) can be transported using GIDI+. To inform GIDI+ what particles to transport, one creates a GIDI::Particles instance (see lines 1-4) and adds a GIDI::Particle instance for each particle to transport. The GIDI::Particle is created (not shown in example) with needed transport information (e.g., flux, multi-group boundaries).

Example
Lines 6-7 of Table 1 load PoPs data from files. Line 9 creates a GIDI::Map::Map instance from a file. Line 11 creates an object that allows the user to control the loading of the data (e.g., turning lazy parsing on or off). Note, in line 11 the arguments to the constructor are not shown to save space. Line 12 uses the GIDI::Map::Map instance to load data for "n + O16" which is a GNDS reaction-Suite node. In GIDI+, the reactionSuite is called a protare since it represents a PROjectile interacting with a TARget for a specified Evaluation 2 (e.g., "n + O16" for ENDF/B-VIII.0). Line 13 gets the list of temperature data for the protare. For example, if the protare was processed with three temperatures for both Monte Carlo and deterministic transport, then the variable temperatures will be a C++ std::vector of length 3. Each item of temperatures is a GIDI::Styles::TemperatureInfo instance that contains the temperature as well as information needed to extract specified data from the protare for that temperature. Lines 15-16 get the multi-group cross section for the protare which, in this case, it the total cross section for "n + O16".
Line 18 creates an instance that allows the user to control how Monte Carlo data are loaded into a MCGIDI::Protare instance. Line 19 sets up a hash table which is used to speed up the look up of cross section data. Line 20-22 creates a MCGIDI::Protare instance from the data in a GIDI::Protare instance. Lines 24-25 get the total cross section for the specified material temperature and projectile energy. Lines 27-28 get the cross section for the reaction at index 2 (e.g., this is likely to be the cross section for the reaction producing "O16_e2"). Lines 30-32 sample a reaction from a MCGIDI::Protare using the random number function dRNG64 that takes the random state rngState and returns a double (both the random number function and state are user defined). Finally, the last lines sample the products from the sampled reaction and put the results (e.g., the outgoing particles' energy and angles) into the variable products. Table 2 list the multi-group functions available in GIDI. The returned object is either a GIDI::Vector (of size the number of projectile groups) or a GIDI::Matrix (of size the number of projectile groups × the number of output going particle groups) instance, as noted by the second column in the table. For multi-group data, collapsing of a GIDI::Vector and a GIDI::Matrix are supported by the Table 1. Example showing how to load two PoPs files, read in a GNDS map file, load a GNDS reactionSuite (i.e., GIDI::Protare instance), create a MCGIDI::Protare instance from the GIDI::Protare data and get the total cross section for a material temperature and projectile energy. Line numbers are shown on the left side of the code. For brevity, the constructions of some variables are not shown. . URR_protare_infos, hashIndex, temperature, energy ); 29 30 int reactionIndex = MCProtare->sampleReaction( URR_protare_infos, // Samples a reaction. 31 hashIndex, temperature, energy, crossSection, dRNG64, 32 rngState ); 33 34 MCGIDI::Reaction const *reaction = MCProtare->reaction( reactionIndex ); // Reference to the reaction. 35 reaction->sampleProducts( MCProtare, energy, input, dRNG64, // Sample products. 36 rngState, products ); GIDI::collapse functions, and transport correcting are supported by the GIDI::transportCorrect functions. Each GIDI+ sub-packages has a Test sub-directory which provides many examples on how to use that subpackage.

Recent features
Some GNDS processed files can be very large and take significant time to load into a GIDI::Protare instance. Recently, three changes were made to GIDI+ and FUDGE to reduce load time. These are: Hybrid storage which means that the data are divided into the GNDS structure, stored in XML, and the numeric data, stored in an HDF5 file. This reduces the XML GNDS file size by about 99%.
Lazy parsing where GIDI+ reads the top-level structure but defers loading specific data (e.g., cross sections, multiplicity or distribution data) until the data are referenced by the user. These data comprise the bulk of a GNDS file but, since users often only need to load a subset of the available data, loading times can be greatly reduced.
Accessing pre-summed multi-group data. GNDS does not currently have a location for storing summed multigroup data. However, GNDS does allow one to store non GNDS specified data into the applicationData node 3 . FUDGE can pre-sum multi-group data and store the summed data in the applicationData node. GIDI knows how to access these data and will return them instead of preforming its own sum if requested. Note, this feature only benefits deterministic transport codes. The LLNL FUDGE and GIDI+ teams have submitted the summed 3 Data in the applicationData node are not needed by processing and transport codes and can be skipped by any code reading a GNDS file.

EPJ Web of Conferences
, 14004 (2023) Together, the first two additions can reduce load times by a factor of 4 or 5. For deterministic transport codes, adding the third feature can significantly reduce load even more.
The GNDS specification do not support URR probability tables (URRPT). FUDGE can generate URRPT data and store them in the applicationData node. GIDI and MCGIDI has been updated to support accessing and using these data.

Future work
The GIDI development team is working with GEANT4 [6] developers to update an older version of GIDI+ in GEANT4. Much of this work is completed but testing is still needed. GIDI+ does not read resonance or covariance data since transport codes do not use them directly, although FUDGE and the new LLNL uncertainty quantification code EMU are able to use these data when preparing processed GNDS files for use by GIDI+. In addition to reading GNDS data, GIDI+ has some capabilities for writing GNDS, although FUDGE remains the primary tool at LLNL for generating, manipulating and processing GNDS data. Future plans for GIDI+ include scaling up the in-line processing capabilities, including support for on-the-fly Doppler broadening and generating temperature-specific multi-group data.
This work was performed under the auspices of the U.S. Department of Energy by Lawrence Livermore National Laboratory under Contract DE-AC52-07NA27344.