In order to run a simulation with OpenMC, you will need cross section data for each nuclide or material in your problem. OpenMC can be run in continuous-energy or multi-group mode.
In continuous-energy mode, OpenMC uses a native HDF5 format (see io_nuclear_data
) to store all nuclear data. Pregenerated HDF5 libraries can be found at https://openmc.org; unless you have specific data needs, it is highly recommended to use one of the pregenerated libraries. Alternatively, 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 <create_xs_library>
. Several sources provide openly available ACE data including the ENDF/B, JEFF, and TENDL libraries as well as the LANL Nuclear Data Team. In addition to tabulated cross sections in the HDF5 files, OpenMC relies on windowed
multipole <windowed_multipole>
data to perform on-the-fly Doppler broadening.
In multi-group mode, OpenMC utilizes an HDF5-based library format which can be used to describe nuclide- or material-specific quantities.
When scripts_openmc
is run, it will look for several environment variables that indicate where cross sections can be found. While the location of cross sections can also be indicated through the openmc.Materials.cross_sections
attribute (or in the materials.xml
<io_materials>
file), if you always use the same set of cross section data, it is often easier to just set an environment variable that will be picked up by default every time OpenMC is run. The following environment variables are used:
OPENMC_CROSS_SECTIONS
Indicates the path to the
cross_sections.xml <io_cross_sections>
summary file that is used to locate HDF5 format cross section libraries if the user has not specifiedopenmc.Materials.cross_sections
(equivalently, thecross_sections
inmaterials.xml <io_materials>
).OPENMC_MG_CROSS_SECTIONS
Indicates the path to an
HDF5 file <io_mgxs_library>
that contains multi-group cross sections if the user has not specifiedopenmc.Materials.cross_sections
(equivalently, thecross_sections
inmaterials.xml <io_materials>
).
To set these environment variables persistently, export them from your shell profile (.profile
or .bashrc
in bash).
Various evaluated nuclear data libraries have been processed into the HDF5 format required by OpenMC and can be found at https://openmc.org. 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 set your OPENMC_CROSS_SECTIONS
environment variable to the absolute path of the cross_sections.xml
file contained in the unpacked directory.
openmc.data
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 <io_cross_sections>
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.
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 create_xs_library
.
In order for OpenMC to correctly treat elastic scattering in heavy nuclides where low-lying resonances might be present (see energy_dependent_xs_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.
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 create_xs_library
.
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 create_xs_library
.
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.
Multi-group 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 multi-group cross section libraries. However, if obtained or generated their own library, the user should set the OPENMC_MG_CROSS_SECTIONS
environment variable to the absolute path of the file library expected to used most frequently.
For an example of how to create a multi-group library, see the example notebook.