4. Basics of Using OpenMC¶
4.1. Running a Model¶
When you build and install OpenMC, you will have an openmc
executable on your system. When you run
openmc, the first thing it will do
is look for a set of XML files that describe the model you want to
simulate. Three of these files are required and another three are optional, as
- Materials Specification – materials.xml
- This file describes what materials are present in the problem and what they are composed of. Additionally, it indicates where OpenMC should look for a cross section library.
- Geometry Specification – geometry.xml
- This file describes how the materials defined in
materials.xmloccupy regions of space. Physical volumes are defined using constructive solid geometry, described in detail in Defining Geometry.
- Settings Specification – settings.xml
- This file indicates what mode OpenMC should be run in, how many particles to simulate, the source definition, and a whole host of miscellaneous options.
OpenMC models should be treated as code, and it is important to be careful with code from untrusted sources.
4.1.1. eXtensible Markup Language (XML)¶
Unlike many other Monte Carlo codes which use an arbitrary-format ASCII file with “cards” to specify a particular geometry, materials, and associated run settings, the input files for OpenMC are structured in a set of XML files. XML, which stands for eXtensible Markup Language, is a simple format that allows data to be exchanged efficiently between different programs and interfaces.
Anyone who has ever seen webpages written in HTML will be familiar with the structure of XML whereby “tags” enclosed in angle brackets denote that a particular piece of data will follow. Let us examine the follow example:
<person> <firstname>John</firstname> <lastname>Smith</lastname> <age>27</age> <occupation>Health Physicist</occupation> </person>
Here we see that the first tag indicates that the following data will describe a person. The nested tags firstname, lastname, age, and occupation indicate characteristics about the person being described.
In much the same way, OpenMC input uses XML tags to describe the geometry, the materials, and settings for a Monte Carlo simulation. Note that because the XML files have a well-defined structure, they can be validated using the openmc-validate-xml script or using Emacs nXML mode.
4.1.2. Creating Input Files¶
The most rudimentary option for creating input files is to simply write them from scratch using the XML format specifications. This approach will feel familiar to users of other Monte Carlo codes such as MCNP and Serpent, with the added bonus that the XML formats feel much more “readable”. Alternatively, input files can be generated using OpenMC’s Python API, which is introduced in the following section.
4.2. Python API¶
OpenMC’s Python API defines a set of functions and classes
that roughly correspond to elements in the XML files. For example, the
openmc.Cell Python class directly corresponds to the
<cell> Element in XML. Each XML file itself also has a corresponding class:
settings.xml, and so on. To
create a model then, one creates instances of these classes and then uses the
export_to_xml() method, e.g.,
Geometry.export_to_xml(). Most scripts
that generate a full model will look something like the following:
# Create materials materials = openmc.Materials() ... materials.export_to_xml() # Create geometry geometry = openmc.Geometry() ... geometry.export_to_xml() # Assign simulation settings settings = openmc.Settings() ... settings.export_to_xml()
4.2.1. Identifying Objects¶
In the XML user input files, each object (cell, surface, tally, etc.) has to be uniquely identified by a positive integer (ID) in the same manner as MCNP and Serpent. In the Python API, integer IDs can be assigned but it is not strictly required. When IDs are not explicitly assigned to instances of the OpenMC Python classes, they will be automatically assigned.
4.3. Viewing and Analyzing Results¶
After a simulation has been completed by running openmc, you will have several output files that were created:
- An ASCII file showing the mean and standard deviation of the mean for any user-defined tallies.
- An HDF5 file with a complete description of the geometry and materials used in the simulation.
- An HDF5 file with the complete results of the simulation, including tallies as well as the final source distribution. This file can be used both to view/analyze results as well as restart a simulation if desired.
For a simple simulation with few tallies, looking at the
might be sufficient. For anything more complicated (plotting results, finding a
subset of results, etc.), you will likely find it easier to work with the
statepoint file directly using the
openmc.StatePoint class. For more
details on working with statepoints, see Working with State Points.
4.4. Physical Units¶
Unless specified otherwise, all length quantities are assumed to be in units of centimeters, all energy quantities are assumed to be in electronvolts, and all time quantities are assumed to be in seconds.
4.5. ERSN-OpenMC Graphical User Interface¶
A third-party Java-based user-friendly graphical user interface for creating XML input files called ERSN-OpenMC is developed and maintained by members of the Radiation and Nuclear Systems Group at the Faculty of Sciences Tetouan, Morocco. The GUI also allows one to automatically download prerequisites for installing and running OpenMC.