---

name: nuclear-data-depletion description: "Use OpenMC nuclear-data libraries, cross_sections.xml indexes, depletion chains, MGXS/MicroXS workflows, depletion integrators, restarts, and data-dependent validation with explicit runtime gates." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Nuclear data and depletion

Use this route when the task involves continuous-energy or multigroup nuclear data, ENDF/ACE/HDF5 conversion, a depletion or activation chain, MGXS/MicroXS, transport-independent depletion, depletion results, or a restart/decay/R2S workflow. This route explains the data and depletion contract; it does not replace the model, executable, or result-reader routes.

Triage before changing code or running anything

1. Identify the requested artifact. Is it a data index, a referenced HDF5 library, a depletion-chain XML, an MGXS library, a MicroXS table, a model input, or a depletion_results.h5 file? Do not treat one as another.
2. Check the smallest gates. A Python API/XML check can work with no transport data. A continuous-energy transport or coupled depletion run needs a native executable and a usable cross-section index. A coupled depletion operator additionally needs the native shared library because it uses openmc.lib. An independent operator needs a valid chain and supplied flux/MicroXS data; its numerical solve can be transport-free, but import and operator behavior still depend on the installed package and, for some helpers, the native binding.
3. Validate paths before blaming physics. Run the bundled, read-only XML diagnostic with an explicit index path: python path/to/validate_data_paths.py --cross-sections /path/to/cross_sections.xml. It never downloads data. Read data-formats.md for path resolution and HDF5 checks.
4. Choose the workflow. Read depletion-and-mgxs-workflows.md for chain/operator/integrator/MGXS choices. Read troubleshooting.md before repairing a failure or retrying a data-dependent run.

Runtime gates and honest claims

Report these independently rather than collapsing them into “OpenMC works”:

• API gate: import openmc, openmc.data, and the requested pure-Python classes/signatures work. This supports object construction, XML parsing, chain/MicroXS shape checks, and some result-file readers.
• Native-library gate: import openmc.lib loads libopenmc.so (or the platform equivalent). It is required for C API/library mode and the transport-coupled depletion operator. Base Python import can succeed while this gate fails.
• Executable gate: an OpenMC executable is available for transport, MGXS tally generation, and helpers that launch a transport subprocess.
• Continuous-energy data gate: cross_sections.xml parses, its referenced files exist, and each referenced HDF5 file has a compatible file type/schema. An index alone is not a library.
• Chain gate: the selected chain XML parses and contains the nuclides, decay paths, reactions, and fission-yield data needed by the calculation.
• MG gate: a supplied or generated mgxs.h5 has compatible group metadata, datasets, materials/nuclides, and model energy_mode='multi-group' settings.

With the known inspection environment, treat Python 3.12 and the representative base APIs as available, libopenmc.so as unavailable until a native build proves otherwise, and OPENMC_CROSS_SECTIONS as unset. Do not download a data bundle or run transport merely to improve this verdict.

Route by need

• Index, HDF5, ENDF/ACE, chain schema, or path semantics: read data-formats.md, then run the validator.
• Coupled depletion, independent/decay-only depletion, timestep units, integrators, transfer rates, MicroXS, MGXS generation, or restart: read depletion-and-mgxs-workflows.md.
• A missing file, XML parse error, unknown nuclide/reaction, unit mismatch, zero/negative rates, restart mismatch, or MGXS schema issue: read troubleshooting.md.
• Materials, geometry, source, or settings construction: route to model-geometry; return here for depletion volumes, data gates, chain choice, and normalization.
• Executable, build, OPENMC_CROSS_SECTIONS, or broad environment setup: route to setup-runtime.
• Statepoint, summary, tally, or generic HDF5 result analysis: route to tallies-results. Depletion-result semantics stay here, including Results.get_atoms, get_keff, and reaction rates.
• C API lifecycle, optional native integrations, or C++ build details: route to advanced-solvers.

Safe operating procedure

1. Record the package/API version, requested data artifact, selected files, and whether the intended result is data-free, data-dependent, native-library, executable, or optional-backend work.
2. Use explicit paths and a dedicated output directory. Never infer a data path from the current working directory when the input can name it explicitly.
3. Validate the index and referenced HDF5 files before creating a transport operator. Validate the chain independently; inspect naming, units, reaction coverage, and fission yields before interpreting a result.
4. For MGXS, fix the energy-group edges and ordering before constructing tallies or consuming arrays. For MicroXS, verify the (nuclide, reaction, group) shape and barn units, and ensure each flux has the matching group count.
5. For depletion, state the operator, normalization (power, power_density, or source_rates), timestep units, integrator, solver/substeps, material volumes, and restart/continuation policy. A zero source rate is a valid decay-only setup, not evidence that transport data was checked.
6. Preserve raw paths and validation output in the task's review area, not in this runtime tree. Report skipped transport/native/data checks explicitly.

Definition of done

A data/depletion task is complete only when the requested files and units are identified, relevant data paths and schemas are checked, the chosen operator and integrator semantics are consistent, and every unavailable native or data gate is reported. A successful API/XML/parser check must not be reported as a successful transport, MGXS tally, or coupled depletion run.

Bundled check

The validator is intentionally narrow and safe: it accepts an explicit --cross-sections XML path, parses without network access, resolves <directory>, <library>, and <depletion_chain> references, reports missing files and malformed XML, and performs lightweight HDF5 file-type, version, and listed-top-level-group checks when h5py is available. See validate_data_paths.py for its command-line contract.

Evidence boundary

This skill distills the public openmc.data, openmc.deplete, and openmc.mgxs APIs, user-guide data/depletion/processing guidance, nuclear-data/depletion/MGXS format descriptions, the small depletion and multigroup examples, and the data, depletion, MGXS, restart, and transport-free test expectations. It deliberately omits bundled nuclear-data archives, download automation, private environment paths, and expensive transport/regression commands.