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 described below.


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.xml occupy 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.


Tallies Specification – tallies.xml

This file describes what physical quantities should be tallied during the simulation (fluxes, reaction rates, currents, etc.).

Geometry Plotting Specification – plots.xml

This file gives specifications for producing slice or voxel plots of the geometry.


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:

  <occupation>Health Physicist</occupation>

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.

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”. However, it is strongly recommended to generate input files 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: openmc.Geometry for geometry.xml, openmc.Materials for materials.xml, openmc.Settings for 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()

# Create geometry
geometry = openmc.Geometry()

# Assign simulation settings
settings = openmc.Settings()

Once a model has been created and exported to XML, a simulation can be run either by calling openmc directly from a shell or by using the openmc.run() function from Python.

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 tallies.out file 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.


Default unit