OpenMC Guide
Running Simulations in OpenMC
What you'll learn
- Run a model and pass runtime options such as threads and MPI arguments.
- Identify the files a run leaves behind and what each one holds.
- Open the path returned by model.run() as a statepoint before reading results.
Before you start
Running a model, and what it leaves behind
Once geometry, materials, settings, and tallies exist, model.run() exports them to XML, launches the OpenMC executable, and waits for it to finish. Pass threads=N for shared-memory parallelism, or mpi_args for a distributed run across nodes; pass geometry_debug=True if you suspect an overlap or undefined-space error and want it caught at every collision rather than only where a particle happens to wander.
model = openmc.Model(geometry, materials, settings, tallies)
model.run(threads=4)
# model.run(mpi_args=['mpiexec', '-n', '4'])
# model.run(geometry_debug=True) # slower, but catches overlaps and gapsTutorial snippet — no separate file in examples repo
A finished run leaves a statepoint.<batch>.h5 file holding every tally result and, for an eigenvalue run, k-effective; a summary.h5 with the geometry and material definitions; and a tallies.out text dump of the same tally data. particle_*.h5 track files only appear if you turned on particle tracking with settings.track — most runs never produce one.
Start any new model with a small particle count before committing to a production run. Geometry and API mistakes surface just as reliably at 1,000 particles as at a million, and finding them there costs seconds instead of an hour.
Running the pin cell
The pin cell run is the plain, single-process case — no threads argument, no MPI, because the model is small enough that startup overhead would dominate. This is the same call that appears on Example: Pin Cell.
model = openmc.Model(geometry, materials, settings, tallies)
# model.run() hands back the Path to the statepoint it wrote
statepoint_path = model.run()
with openmc.StatePoint(statepoint_path) as sp:
keff = sp.keff
print(f"k-effective: {keff.nominal_value:.5f} ± {keff.std_dev:.5f}")Tutorial snippet — no separate file in examples repo
Try It Yourself
model.run() hands back a Path to the statepoint file it wrote, not the results themselves. Reaching for .keff on that return value fails only after the transport solve has finished, which on a real model can mean losing an hour of compute to a one-line mistake.
openmc.StatePoint(...) before reading keff. Using it as a context manager also closes the HDF5 file when you are done.Check yourself
- Run a model and pass runtime options such as threads and MPI arguments?
- Identify the files a run leaves behind and what each one holds?
- Open the path returned by
model.run()as a statepoint before reading results?