Store energy-dependent isomeric production data verbatim in depletion chains

docs/source/io_formats/depletion_chain.rst

@@ -96,6 +96,85 @@ element has the following attributes:
   :branching_ratio:
     The branching ratio for the reaction
 
+In addition to these attributes, a ``<reaction>`` element may contain zero or
+more :ref:`io_chain_isomeric` sub-elements carrying verbatim energy-dependent
+isomeric production data from the source evaluation.
+
+.. _io_chain_isomeric:
+
+---------------------------------
+``<isomeric_production>`` Element
+---------------------------------
+
+.. versionadded:: 0.15.4
+
+The ``<isomeric_production>`` element stores energy-dependent isomeric
+production data (ENDF MF=9 yields and/or MF=10 partial cross sections) for the
+final state produced by the parent ``<reaction>`` element, exactly as given in
+the source evaluation. The scalar ``branching_ratio`` attributes on
+``<reaction>`` elements remain authoritative for consumers that do not use
+this data, and the scalar branching ratios of a reaction type always sum to
+about one. Note that the stored functions are verbatim evaluation data: an
+MF=10 partial cross section requires an external total cross section to form a
+branching ratio, and the per-state MF=9 yields of a reaction do not
+necessarily sum to one when the ground-state share is implicit.
+
+A ``<reaction>`` element may hold several ``<isomeric_production>`` elements,
+e.g. when a final state that could not be matched to a known metastable state
+is folded onto the ground-state target. Consumers should sum the tables of all
+instances attached to one target; OpenMC never performs arithmetic on the
+stored data.
+
+This element has the following attributes:
+
+  :level:
+    ENDF LFS level number of the final state, verbatim from the source
+    evaluation. This is a level index, not a metastable-state index.
+
+  :excitation_energy:
+    Excitation energy of the final state in [eV] (the MF=8 ELFS value when
+    present, otherwise QM minus QI). Zero for the ground state.
+
+Each ``<isomeric_production>`` element contains one or more ``<table>``
+sub-elements, each holding one tabulated function with the following
+attributes and sub-elements:
+
+  :mf:
+    ENDF file number the data comes from: 9 for energy-dependent yields
+    (dimensionless multiplicities of the reaction cross section) or 10 for
+    partial production cross sections in [b]
+
+  :mt:
+    ENDF reaction number of the section that supplied the data
+
+  :source:
+    Source library identifier as recorded in the evaluation header,
+    e.g. 'ENDF/B-8.1' or 'TENDL-2023.1'
+
+  :QM:
+    Mass-difference Q value in [eV], verbatim from the TAB1 header
+
+  :QI:
+    Reaction Q value for this particular state in [eV], verbatim from the
+    TAB1 header
+
+  :breakpoints:
+    Whitespace-separated breakpoints of the interpolation regions
+
+  :interpolation:
+    Whitespace-separated ENDF interpolation scheme codes for each region,
+    following the same convention as :class:`openmc.data.Tabulated1D`
+
+  :energies:
+    Sub-element listing the incident neutron energies in [eV]
+
+  :values:
+    Sub-element listing the tabulated yields or cross sections
+
+Only ENDF "scheme 1" isomeric data (MF=8/9/10) is represented in the chain
+file. Evaluations that encode isomer production via MF=6 product distributions
+or via discrete-level reaction sections are not captured.
+
 .. _io_chain_nfy:
 
 ------------------------------------

docs/source/pythonapi/deplete.rst

@@ -124,6 +124,8 @@ for a depletion chain:
    ReactionTuple
    FissionYieldDistribution
    FissionYield
+   ProductionTable
+   IsomericProduction
 
 The :class:`Chain` class uses information from the following module variable: