---

name: setup-runtime description: "Route OpenMC installation, CPU/native builds, data and environment checks, XML execution, parallel run configuration, bounded testing, and broad runtime troubleshooting." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

OpenMC setup and runtime

Use this route when the task is about installing OpenMC, building its executable or shared library, configuring nuclear data, exporting or running XML inputs, choosing OpenMP/MPI execution settings, or diagnosing a broad environment or runtime failure. Establish the smallest required readiness gates before running anything expensive; a Python import alone is never evidence that native transport or library mode is ready.

Route by the user's immediate need

• Install or build: read install-and-build.md.
• Run inputs, select flags, or configure parallelism: read cli-and-execution.md.
• A command, data path, XML input, shared library, or test fails: read troubleshooting.md and run the safe diagnostic helper when useful: check_openmc_environment.py with python scripts/check_openmc_environment.py --help. The no-argument form checks only the Python package and reports optional gates as skipped; add --executable openmc, --library PATH, or --cross-sections PATH to make those checks requested. A PATH executable is probed with only a fixed --version argument, never with model input or a shell.
• Model objects, geometry, materials, sources, or settings semantics: route to the model/geometry skill rather than duplicating its API guidance.
• Tally/statepoint interpretation: route to the tallies/results skill.
• Nuclear-data formats, processing, MGXS, or depletion semantics: route to the nuclear-data/depletion skill after this route has established that the runtime and data paths are valid.
• C API/library internals, random ray, CMFD, weight windows, or specialized optional integrations: route to the advanced-solvers skill.

Readiness distinction

Before a requested operation, record the gate result rather than collapsing missing prerequisites into one generic failure:

• API/XML-only work needs the Python API gate.
• Command-line transport, plotting, volume calculations, and subprocess-backed executor calls need both the Python API and executable gates.
• C-API/library-mode features additionally need the native-library gate.
• Transport and data-dependent depletion need a passing data gate as well.

The bundled diagnostic is a non-mutating structural probe, not a transport smoke test. Its exit status is nonzero only when the always-on package check or an explicitly requested executable, library, or data-index check fails.

Treat these as separate gates and report them separately:

1. Python API gate: python -c "import openmc; print(openmc.__version__)" succeeds and the package dependencies are usable. This supports model construction and XML generation, but does not prove that a native transport runtime exists.
2. Executable gate: openmc --version or an explicit executable path works. This is required for command-line transport, plotting, volume calculations, and Python executor calls that launch a subprocess.
3. Native-library gate: import openmc.lib loads libopenmc and is only required for C-API/library-mode features such as Model.init_lib, depletion workflows that use the C API, and selected advanced operations. A Python import failure caused by a missing shared library is not evidence that the base Python package is broken.
4. Data gate: a usable cross_sections.xml is configured and every file it references exists. A configured index with broken HDF5 references is still a failed data gate.

Do not claim a simulation is ready until the relevant gate for that operation is positive. Keep MPI, DAGMC, libMesh, UWUW, NCrystal, and other optional features explicitly conditional on their compiler, library, and CMake checks; MPI is not assumed available.

Safety and reproducibility boundaries

• Prefer a virtual/Conda environment and an out-of-source native build. Do not download nuclear data or mutate shell startup files on the user's behalf.
• Treat model Python and XML as executable/untrusted input. Inspect paths and working directories before running them, and use a dedicated output directory.
• Start with tiny API/XML checks or selected unit tests. Transport, regression, depletion, and full-suite runs require both the native executable and the data prerequisites and can be expensive.
• For comparable tests, use a strict-floating-point native build when needed and bound OpenMP threads (the project recommends OMP_NUM_THREADS=2 for test stability). Do not imply that bitwise agreement follows from arbitrary compiler, thread, or MPI configurations.

Operational handoff

When this route completes, report the package version/import result, executable path/version or the reason that gate is unavailable, native-library binding result, data-index parse result including missing or non-file references, build flags, thread/process settings, XML/output location, and the next route if the request is about model construction or results. Keep data, executable, and shared-library findings separate. Link to the detailed references rather than expanding their APIs in this router.