3. Data Configuration¶

OpenMC relies on a variety of physical data in order to carry out transport simulations, depletion simulations, and other common tasks. As a user, you are responsible for specifying one or more of the following:

Cross sections (XML) – A cross sections XML file (commonly named cross_sections.xml) contains a listing of other data files, in particular neutron cross sections, photon cross sections, and windowed multipole data. Each of those files, in turn, uses a HDF5 format (see Nuclear Data File Formats). In order to run transport simulations with continuous-energy cross sections, you need to specify this file.
Depletion chain (XML) – A depletion chain XML file contains decay data, fission product yields, and information on what neutron reactions can result in transmutation. This file is needed for depletion/activation calculations as well as some basic functions in the openmc.data module.
Multigroup cross sections (HDF5) – OpenMC can also perform transport simulations using multigroup data. In this case, multigroup cross sections are stored in a single HDF5 file. Thus, in order to run a multigroup transport simulation, this file needs to be specified.

Each of the above files can specified in several ways. In the Python API, a runtime configuration variable openmc.config can be used to specify any of the above and is initialized using a set of environment variables.

3.1. Runtime Configuration¶

Data sources for OpenMC can be specified at runtime in Python using the openmc.config variable. This variable acts like a dictionary and stores key-values pairs, where the values are file paths (strings or path-like objects) and the key can be one of the following:

"cross_sections": Indicates the path to the cross sections XML file that lists HDF5 format neutron cross sections, photon cross sections, and windowed multipole data. At startup, this is initialized with the value of the OPENMC_CROSS_SECTIONS environment variable. Note that the openmc.Materials.cross_sections attribute will override this, if specified.
"chain_file": Indicates the path to the depletion chain XML file that contains decay data, fission product yields, and what neutron reactions may result in transmutation of a target nuclide. At startup, this is initialized with the value of the OPENMC_CHAIN_FILE environment variable.
"mg_cross_sections": Indicates the path to an HDF5 file that contains multigroup cross sections. At startup, this is initialized with the value of the OPENMC_MG_CROSS_SECTIONS environment variable. Note that the openmc.Materials.cross_sections attribute will override this if specified.

If you want to persistently set the environment variables used to initialized the configuration, export them from your shell profile (.profile or .bashrc in bash).

3.2. Continuous-Energy Cross Sections¶

3.2.1. Using Pregenerated Libraries¶

Various evaluated nuclear data libraries have been processed into the HDF5 format required by OpenMC and can be found at https://openmc.org. Unless you have specific data needs, it is highly recommended to use one of the pregenerated libraries. You can find both libraries generated by the OpenMC development team as well as libraries based on ACE files distributed elsewhere. To use these libraries, download the archive file, unpack it, and then specify the path of the cross_sections.xml file contained in the unpacked directory as described in Runtime Configuration.

3.2.2. Manually Creating a Library from ACE files¶

If you have ACE format data that was produced with NJOY, such as that distributed with MCNP or Serpent, it can be converted to the HDF5 format using the using the Python API. Several sources provide openly available ACE data including the ENDF/B, JEFF, and TENDL libraries as well as the LANL Nuclear Data Team.

The openmc.data module in the Python API enables users to directly convert ACE data to OpenMC’s HDF5 format and create a corresponding cross_sections.xml file. For those who prefer to use the API directly, the openmc.data.IncidentNeutron and openmc.data.ThermalScattering classes can be used to read ACE data and convert it to HDF5. For continuous-energy incident neutron data, use the IncidentNeutron.from_ace() class method to read in an existing ACE file and the IncidentNeutron.export_to_hdf5() method to write the data to an HDF5 file.

u235 = openmc.data.IncidentNeutron.from_ace('92235.710nc')
u235.export_to_hdf5('U235.h5')

If you have multiple ACE files for the same nuclide at different temperatures, you can use the IncidentNeutron.add_temperature_from_ace() method to append cross sections to an existing IncidentNeutron instance:

u235 = openmc.data.IncidentNeutron.from_ace('92235.710nc')
for suffix in [711, 712, 713, 714, 715, 716]:
    u235.add_temperature_from_ace('92235.{}nc'.format(suffix))
u235.export_to_hdf5('U235.h5')

Similar methods exist for thermal scattering data:

light_water = openmc.data.ThermalScattering.from_ace('lwtr.20t')
for suffix in range(21, 28):
    light_water.add_temperature_from_ace('lwtr.{}t'.format(suffix))
light_water.export_to_hdf5('lwtr.h5')

Once you have created corresponding HDF5 files for each of your ACE files, you can create a library and export it to XML using the openmc.data.DataLibrary class:

library = openmc.data.DataLibrary()
library.register_file('U235.h5')
library.register_file('lwtr.h5')
...
library.export_to_xml()

At this point, you will have a cross_sections.xml file that you can use in OpenMC.

Hint

The IncidentNeutron class allows you to view/modify cross sections, secondary angle/energy distributions, probability tables, etc. For a more thorough overview of the capabilities of this class, see the example notebook.

3.2.3. Manually Creating a Library from ENDF files¶

If you need to create a nuclear data library and you do not already have suitable ACE files or you need to further customize the data (for example, adding more temperatures), the IncidentNeutron.from_njoy() and ThermalScattering.from_njoy() methods can be used to create data instances by directly running NJOY. Both methods require that you pass the name of ENDF file(s) that are passed on to NJOY. For example, to generate data for Zr-92:

zr92 = openmc.data.IncidentNeutron.from_njoy('n-040_Zr_092.endf')

By default, data is produced at room temperature, 293.6 K. You can also specify a list of temperatures that you want data at:

zr92 = openmc.data.IncidentNeutron.from_njoy(
    'n-040_Zr_092.endf', temperatures=[300., 600., 1000.])

The IncidentNeutron.from_njoy() method assumes you have an executable named njoy available on your path. If you want to explicitly name the executable, the njoy_exec optional argument can be used. Additionally, the stdout argument can be used to show the progress of the NJOY run.

To generate a thermal scattering file, you need to specify both an ENDF incident neutron sub-library file as well as a thermal neutron scattering sub-library file; for example:

light_water = openmc.data.ThermalScattering.from_njoy(
    'neutrons/n-001_H_001.endf', 'thermal_scatt/tsl-HinH2O.endf')

Once you have instances of IncidentNeutron and ThermalScattering, a library can be created by using the export_to_hdf5() methods and the DataLibrary class as described in Manually Creating a Library from ACE files.

3.2.4. Enabling Resonance Scattering Treatments¶

In order for OpenMC to correctly treat elastic scattering in heavy nuclides where low-lying resonances might be present (see Energy-Dependent Cross Section Model), the elastic scattering cross section at 0 K must be present. If the data you are using was generated via IncidentNeutron.from_njoy(), you will already have 0 K elastic scattering cross sections available. Otherwise, to add 0 K elastic scattering cross sections to an existing IncidentNeutron instance, you can use the IncidentNeutron.add_elastic_0K_from_endf() method which requires an ENDF file for the nuclide you are modifying:

u238 = openmc.data.IncidentNeutron.from_hdf5('U238.h5')
u238.add_elastic_0K_from_endf('n-092_U_238.endf')
u238.export_to_hdf5('U238_with_0K.h5')

With 0 K elastic scattering data present, you can turn on a resonance scattering method using Settings.resonance_scattering.

Note

The process of reconstructing resonances and generating tabulated 0 K cross sections can be computationally expensive, especially for nuclides like U-238 where thousands of resonances are present. Thus, running the IncidentNeutron.add_elastic_0K_from_endf() method may take several minutes to complete.

3.2.5. Photon Cross Sections¶

Photon interaction data is needed to run OpenMC with photon transport enabled. Some of this data, namely bremsstrahlung cross sections from Seltzer and Berger, mean excitation energy from the NIST ESTAR database, and Compton profiles calculated by Biggs et al. and available in the Geant4 G4EMLOW data file, is distributed with OpenMC. The rest is available from the NNDC, which provides ENDF data from the photo-atomic and atomic relaxation sublibraries of the ENDF/B-VII.1 library.

Most of the pregenerated HDF5 libraries available at https://openmc.org already have photon interaction data included. If you are building a data library yourself, it is possible to use the Python API directly to convert photon interaction data from an ENDF or ACE file to an HDF5 file. The openmc.data.IncidentPhoton class contains an IncidentPhoton.from_ace() method that will generate photon data from an ACE table and an IncidentPhoton.export_to_hdf5() method that writes the data to an HDF5 file:

u = openmc.data.IncidentPhoton.from_ace('92000.12p')
u.export_to_hdf5('U.h5')

Similarly, the IncidentPhoton.from_endf() method can be used to read photon data from an ENDF file. In this case, both the photo-atomic and atomic relaxation sublibrary files are required:

u = openmc.data.IncidentPhoton.from_endf('photoat-092_U_000.endf',
                                         'atom-092_U_000.endf')

Once the HDF5 files have been generated, a library can be created using the DataLibrary class as described in Manually Creating a Library from ACE files.

3.3. Chain Files¶

Pregenerated depletion chain XML files can be found at https://openmc.org. Additionally, depletion chains can be generated using the openmc.deplete.Chain class. In particular, the from_endf() method allows a chain to be generated starting from a set of ENDF incident neutron, decay, and fission product yield sublibrary files. Once you’ve downloaded or generated a depletion chain XML file, make sure to specify its path as described in Runtime Configuration.

3.4. Windowed Multipole Data¶

OpenMC is capable of using windowed multipole data for on-the-fly Doppler broadening. A comprehensive multipole data library containing all nuclides in ENDF/B-VII.1 is available on GitHub. To obtain this library, download and unpack an archive (.zip or .tag.gz) from GitHub. Once unpacked, you can use the openmc.data.DataLibrary class to register the .h5 files as described in Manually Creating a Library from ACE files.

The official ENDF/B-VII.1 HDF5 library includes the windowed multipole library, so if you are using this library, the windowed multipole data will already be available to you.

3.5. Multigroup Cross Sections¶

Multigroup cross section libraries are generally tailored to the specific calculation to be performed. Therefore, at this point in time, OpenMC is not distributed with any pre-existing multigroup cross section libraries. However, if a multigroup library file is downloaded or generated, the path to the file needs to be specified as described in Runtime Configuration. For an example of how to create a multigroup library, see this MG mode notebook.