ACTINV problem specification (actinv-spec-1)
One JSON document drives the CLI, Python API and validation harness. Unknown fields, non-finite numbers and invalid
hashes are errors; literal paths use the CLI working directory (shell ~ expansion is not performed inside JSON).
Any path field or decay primary/fallback string may instead carry a symbolic reference
catalog:<artifact-id> naming an artifact in the embedded data catalog (actinv data list prints the IDs, e.g.
catalog:tendl-2025-patched-neutron-709g). The reference resolves to <data-root>/v<catalog-version>/<artifact path>,
where the data root is $ACTINV_DATA_DIR when set and ./actinv-data otherwise. An omitted or null sha256 is
filled from the catalog declaration; a declared hash that disagrees with the catalog is an error, as is a reference
to an artifact that is not installed. This keeps problem files portable between machines while remaining
hash-pinned — actinv new emits catalog references by default.
Start from a complete example
Create a valid, editable problem with its full spectrum:
actinv new problem.json
actinv validate problem.json
Your first calculation walks through installing data and solving it. This reference describes optional fields and advanced input formats. JSON fragments below belong inside a complete problem; they are not standalone runnable inputs.
Required inputs
| field | meaning |
|---|---|
projectile | neutron, proton, deuteron, triton, helion (He-3), alpha or gamma; omission preserves the historical neutron default. |
library.path | ACTINV .npz activation library; the adjacent <stem>_index.json is also required. May be omitted only when every schedule step has zero flux (see Decay-only runs). |
library.sha256 | Optional declared hash. ACTINV always computes the library hash and fails if a declaration differs. The index’s recorded library hash is checked too. |
decay.primary | ENDF-6 radioactive-decay sublibrary. |
decay.fallback | Optional second decay sublibrary; records absent from the primary are taken from it. |
material.composition | Natural element symbols or explicit nuclides (U235, Ba137m1) and nonnegative values interpreted by material.basis. |
spectrum.flux_per_group | Group-integrated fluxes. descending: true reverses the supplied order before use. |
schedule | At least one duration plus exactly one of flux (multiplier), wall_loading_MW_m2 or, with a kerma section, a power target (power_W_cm3 / power_W_per_g; an explicit flux: 0 beside a power target is accepted); optional partition, feed, removal, spectrum, library. Accepted duration units: seconds, minutes, hours, days and years. |
fission_yields | Optional hash-pinned ENDF-6 neutron-induced fission-yield evaluations, and optional spontaneous-fission yields and neutron multiplicities; see below. Empty/omitted preserves the explicit no-yields leakage path. |
uncertainty | Optional neutron-only MF=33 sidecar and response selection; omission reads no covariance file and preserves the ordinary path. |
radiological | Optional hash-pinned clearance, waste, ingestion, or inhalation response table; omission reads no table. |
damage | Optional hash-pinned actinv-damage-table-1 or actinv-damage-table-2 (kinematic) damage-energy table plus per-element displacement energies; required when outputs contains damage. |
kerma | Optional hash-pinned actinv-kerma-table-1 heating table; adds per-step kerma heating and enables power-driven schedule steps (power_W_cm3 / power_W_per_g, with material.density_g_cm3 for the former). |
The certificate records computed SHA-256 values for the activation library, its index, primary/fallback decay data, every fission-yield evaluation, the photon response, covariance sidecar, and radiological table when present. A declaration is a constraint, not a value copied into the certificate.
Material bases
material.mass_g defaults to 1 g. Inventories remain per gram; the mass scales the total photon rates and powers.
material.density_g_cm3 is optional (finite and positive); only the step summary’s per-cm³ totals use it.
Composition keys are case-insensitive natural element symbols or explicit SymbolA[mN] nuclides. Bare m means
m1, so BA137M, Ba137m and Ba137m1 identify the same state; aliases which collide are an error. A natural
element and one of its explicit isotopes cannot appear together. An unknown element symbol is an error, and so is a
natural element without tabulated natural isotopic abundances (Tc, Pm, Po, At, Rn, Fr, Ra, Ac): give those as
explicit nuclides, since a natural key would otherwise contribute no atoms. Explicit mass-based entries use the selected decay
evaluation’s AWR times 1.00866491595 u and fail if that record is absent. A literal atoms_per_g entry may instead
be ledgered as absent from the solvable chain; a photon-response calculation still requires its mass.
wt_percent(default): each value is grams per 100 g. Values are used as stated rather than silently normalized; a total other than 100 is ledgered. Photon-response mixing normalizes them to mass fractions.atom_fraction: values are arbitrary elemental atom ratios. Natural isotopes are expanded and the mixture is normalized to one gram using the abundance-weighted elemental masses.atoms_per_g: each value is an elemental atom density per gram and is expanded by natural isotopic abundance.
All three bases apply identically to explicit nuclides: literal atom density for atoms_per_g, grams per 100 g for
wt_percent, and an arbitrary atom ratio normalized to one gram for atom_fraction. Response-function mixing
aggregates explicit isotopes back to elemental mass fractions.
Projectile and spectrum
Neutrons use fispact-709 with exactly 709 values, or any other FISPACT-II neutron structure listed under
Group structures with exactly that structure’s group count. Proton, deuteron, triton, helion and alpha use
fispact-162 with exactly 162 values and require options.temperature_K: 0; charged specs reject fission-yield files. custom requires one more
strictly increasing boundary than flux values. Those boundaries must match the activation library to 1e-12
relative. total, when present, rescales group values while preserving shape; a positive total with an all-zero
flux_per_group has no shape to scale and is rejected. The spec, library index, group
structure and temperature must all identify the same projectile/data build before matrix assembly.
spectrum.relative_error is an optional array, the same length and order as flux_per_group (honouring
descending): each group’s transport-tally statistical relative standard uncertainty. It is accepted and carried
but otherwise unused unless uncertainty.channels requests "flux" (see below); requesting that channel with no
relative_error given is an error naming the spectrum.
Spectrum conversion (spectrum.rebin)
spectrum.rebin converts a spectrum supplied in its own groups onto a library structure inside the run
(FISPACT-II GRPCONVERT, CNVTYPE and LIMGRP). With it, spectrum.structure names the destination structure
(fispact-709, fispact-162 or a refinement such as fispact-709x4; not custom), and boundaries_eV
(strictly ascending, one more than the flux values) plus flux_per_group describe the supplied groups.
| field | meaning | default |
|---|---|---|
convention | equal_lethargy (CNVTYPE 0): flux is spread uniformly in lethargy inside a source group. equal_energy (CNVTYPE 1): uniformly in energy. | equal_lethargy |
emin_eV | LIMGRP lower limit: flux in source groups below it is folded into the first group above it, whose lower edge becomes emin_eV. | none |
emax_eV | LIMGRP upper limit: flux above it is folded into the last group below it, whose upper edge becomes emax_eV. | none |
total rescales the supplied spectrum before conversion. relative_error cannot accompany rebin (it is indexed by
the supplied groups). Flux falling outside the destination structure’s range is not discarded silently: it is
reported. The ledger gains spectrum_conversion (one record per converted spectrum, the base spectrum first, then
any step spectrum) holding convention, cnvtype, destination_structure, source_groups, destination_groups,
emin_eV, emax_eV, limit_flux_moved_from_below, limit_flux_moved_from_above, source_total,
destination_total, outside_destination_below, outside_destination_above, flux_conservation_residual (the
relative closure of source against destination plus outside flux; checked to 1e-12) and exact_grid. A spectrum
without rebin is unchanged and adds nothing to the ledger.
A conversion that leaves no flux in the destination structure (a source wholly below or above its range) is an
error naming the spectrum, because every irradiating step would silently become pure decay; a partial loss is not
refused, so read outside_destination_below and outside_destination_above. emin_eV and emax_eV are checked
when the spec is validated: a limit at or above the whole supplied spectrum (emin_eV) or at or below it
(emax_eV) is an error, while a limit that falls outside the spectrum on the other side leaves that side
unchanged, as the FISPACT-II manual allows. A source group that straddles a limit keeps all of its flux inside the
shortened group (LIMGRP moves its boundary to the limit, it does not split the group), so the part of that group
beyond the limit is redistributed but is not counted in limit_flux_moved_from_below or
limit_flux_moved_from_above, which report only the groups wholly beyond the limit; the total is conserved either
way.
A fragment (group boundaries in eV, flux in n cm^-2 s^-1, merged into a complete problem):
"spectrum": {
"structure": "fispact-709",
"boundaries_eV": [1.0e-3, 1.0, 1.0e3, 1.0e6, 2.0e7],
"flux_per_group": [1.0e9, 4.0e9, 5.0e9, 1.0e9],
"descending": false,
"rebin": {"convention": "equal_lethargy", "emin_eV": 1.0e-2, "emax_eV": 1.5e7}
}
Wall loading (wall_loading_MW_m2)
A schedule step gives exactly one of flux (a multiplier on the spectrum’s total) and wall_loading_MW_m2 (first
wall loading in MW m^-2, FISPACT-II WALL); giving both or neither is an error. FISPACT-II section 4.91 scales the
flux by wall / wall_in_file, the wall loading recorded with the spectrum. ACTINV follows that rule when the
spectrum declares spectrum.wall_loading_MW_m2 (the loading its group fluxes correspond to): the step multiplier is
wall / spectrum.wall_loading_MW_m2. Without a reference, ACTINV uses the manual’s closing statement of section
4.91, “a current C, of 4.44 x 10^13 n cm^-2 s^-1 is equivalent to 1 MW m^-2” (a 14 MeV neutron current), and sets
the step’s total flux to wall x 4.44e13 n cm^-2 s^-1 with the spectrum’s shape; that needs a spectrum with a
positive total. The constant is spec::WALL_CURRENT_PER_MW_M2. A step spectrum uses its own reference. A zero
loading is a cooling step on any spectrum, with or without a reference. The 14 MeV equivalence describes a neutron
current, so without spectrum.wall_loading_MW_m2 a wall step is refused for a proton, deuteron, triton, helion,
alpha or gamma projectile; declare the reference loading instead.
The two bases differ in what they do with flux that rebin places outside the destination structure. With a
reference the multiplier is wall / reference applied to the converted spectrum, so flux lost outside the
destination lowers the step flux. Without one the multiplier is wall x 4.44e13 over the converted spectrum’s sum,
so the step flux is wall x 4.44e13 whatever was lost. Also without a reference, the step flux does not depend on
spectrum.total (only the shape is used), so a scan that scales spectrum.total changes nothing for such steps;
with a reference it scales them. The ledger
gains wall_loading, one record per wall step: step, wall_loading_MW_m2, basis
(spectrum_reference_wall_loading or 14_MeV_current_equivalence), reference_wall_loading_MW_m2,
current_per_MW_m2_cm2_s, flux_multiplier and step_total_flux_cm2_s.
A fragment (the reference loading belongs to the spectrum’s group fluxes):
"spectrum": {"wall_loading_MW_m2": 4.15},
"schedule": [
{"dt": "1 y", "wall_loading_MW_m2": 2.0},
{"dt": "10 y", "flux": 0}
]
Partition (schedule[].partition)
partition is a map from element symbol to the fraction of that element’s atoms kept at the start of the step
(FISPACT-II section 4.54 PARTITION: a value of 0.01 for Ar reduces Ar by a factor of 100). Every nuclide and
isomeric state of the element is scaled; the removed atoms move to the removal sink that removal also uses and are
reported as removed_atoms_per_g. Fractions must lie in [0, 1] and keys must be elements. The split is applied
before the step evolves and also acts on the uncertainty tangents and the comparison solution. An empty
partition: {} is no partition. A composition isotope of the element that has no decay record is not a chain state,
but the partition scales it too (its atoms move to the sink and the step summary shows the kept share).
A partition removes bulk atoms, which the trace formulation cannot represent (it holds the bulk undepleted), so
options.mode: "trace" with a partition is an error, and auto selects coupled. The ledger gains partition:
applied (per step and element: step, element, fraction_kept, removed_atoms_per_g), mode,
mode_forced_coupled (true only when auto would otherwise have chosen trace: burn-up or the decay of a
radioactive bulk nuclide already select coupled), numerical_floor_atoms_per_g_max and removed_atoms_per_g_final.
Partition is not accepted by mesh specs, study specs, reverse solves or the waste-composition solve, and is refused
together with pathways and schedule library overrides.
The coupled formulation carries the bulk material as a state, so its CRAM numerical scale alpha0 x max(N) (see the
numerical floor diagnostic) can sit above trace-level activation products; populations
below it are reported, not removed. A partition that moves an otherwise trace run onto coupled therefore changes
the precision at which trace products are resolved. numerical_floor_atoms_per_g_max is the worst step’s scale in the
ledger’s partition entry; compare it with the products you care about, or set options.mode explicitly.
A fragment:
"schedule": [
{"dt": "1 y", "flux": 1.0},
{"dt": "1 d", "flux": 0, "partition": {"Ar": 0.01, "Fe": 0.5}}
]
Named data overrides (overrides)
overrides is an optional list replacing data for a named nuclide (FISPACT-II section 4.53 OVER). They are
applied while the reaction and decay networks are assembled, and each is listed in the ledger under overrides.
kind | FISPACT-II | fields | effect |
|---|---|---|---|
cross_section | ACROSS | nuclide, mt, value (barns, >= 0) | Sets the reaction’s one-group collapsed cross section for the run’s spectrum. Product branching is kept. |
cross_section_scale | none (ACTINV) | nuclide, mt, value (> 0) | Multiplies the collapsed value. |
half_life | ALAM | nuclide, value, units (default s) | Replaces the half-life; the units are any schedule duration unit. |
cross_section_uncertainty | ADCROSS | nuclide, mt, value | Replaces the relative standard uncertainty of the reaction; needs the cross_section_mf33 channel and a covariance. |
half_life_uncertainty | ADLAM | nuclide, value | Replaces the decay constant’s relative standard uncertainty; needs the decay_constants channel. |
Differences from the manual: FISPACT-II selects an ACROSS reaction by daughter, ACTINV by ENDF reaction number
mt; ADCROSS/ADLAM take a relative standard uncertainty, not an error factor. A cross-section rescale keeps the
correlations of the covariance row. A name that matches no library row or decay record is an error. Cross-section
value overrides cannot be combined with uncertainty (the MF=33 collapse is anchored to the library value), and an
absolute cross_section cannot be combined with self_shielding. Duplicate overrides, and a cross_section and a
cross_section_scale on the same reaction, are rejected. A cross-section override’s ledger entry records the
one-group collapsed value before and after, under the base spectrum only.
An absolute cross_section is one barn value imposed under every spectrum of the schedule: a step with its own
spectrum gets the same number as the base spectrum (the product branching still follows each spectrum). It cannot
set a nonzero value on a reaction that collapses to zero under a spectrum, so the check is made against the base
spectrum when a step uses it and against the spectrum of every step that irradiates; the spectrum of a cooling step
never reads the cross section and is not checked.
A fragment (names are resolved against the library and decay data when the problem is run):
"overrides": [
{"nuclide": "Fe56", "kind": "cross_section_scale", "mt": 16, "value": 0.8},
{"nuclide": "Co60", "kind": "half_life", "value": 5.27, "units": "y"}
]
Decay-only runs
A spec whose every step has zero flux needs no activation library: omit library (or leave library.path empty)
and spectrum. The decay data and the material are read as usual and the schedule is a pure decay/cooling
history. A spec that omits library with any irradiating step is rejected with a message naming the step rule.
Everything that needs a library is rejected for a decay-only spec: uncertainty, self_shielding, damage,
fission_yields files, kerma, options.rate_scale, options.yield_scale, library.sha256 and cross-section
overrides. half_life overrides remain allowed; half_life_uncertainty needs an uncertainty section, which a
decay-only run does not support, so it is refused. A spec that gives a step spectrum but no base spectrum, or a
library but no spectrum, is refused with a message saying that a spectrum is required. The ledger and certificate
carry
decay_only: true and the library and library-index inputs are null. Runs that supply a library are unchanged.
Mesh specs still require a library.
Fission yields
fission_yields is optional. Each file is one hash-pinned ENDF evaluation for one parent:
"fission_yields": {
"files": [
{
"path": "/data/endfb-viii.0-nfpy/nfy-092_U_235.endf",
"sha256": "64 hexadecimal digits"
}
],
"energy": "fixed",
"fixed_energy_eV": 0.0253
}
The production source is MF=8/MT=454 independent yield. MF=8/MT=459 cumulative tables are parsed and checked, and
enter the matrix only when yields is "cumulative" (below). Every independent table must sum to two fission fragments within 1e-6; values are not
renormalized. Duplicate parents, energies or products, malformed/truncated records, negative/nonfinite values and hash
mismatches fail closed.
energy: "fixed" requires a finite nonnegative fixed_energy_eV; selection is exact, linearly interpolated, or
clamped to the evaluated range. energy: "spectrum_average" is the default and forbids fixed_energy_eV; it uses
the fission-rate-weighted representative incident energy separately for each parent. The certificate records the
requested energy, selected bracket, interpolation weight, clamp decision, product count and effective yield sum.
Fissioning parents without a matching file remain explicit leakage and never borrow another parent’s evaluation.
Rate-weighted energy, parent selection and cumulative yields
Three further options, all opt-in; without them every output is unchanged.
energy: "rate_weighted" forbids fixed_energy_eV and mixes the evaluation’s tabulated yield sets instead of
interpolating at one energy. For each parent and each distinct step spectrum, with tabulated incident energies
E_1 < ... < E_K, library group fission rates r_g = phi_g sigma_f,g (the parent’s MT=18 group cross section
and the spectrum’s group flux) and group energies E_g = sqrt(E_lo E_hi), the weights are
w_k = sum_g r_g h_k(E_g) / sum_g r_g
where h_k are the piecewise-linear hat functions on the E_k (h_1 = 1 at and below E_1, h_K = 1 at and
above E_K; between two tabulated energies the two adjacent hats are 1 - w and w, the weights
effective() uses at one energy). The yield of product i is Y_i = sum_k w_k Y_{k,i} over the tables with
nonzero weight; a product missing from one of them counts as zero yield and zero uncertainty. The standard
uncertainty is sqrt(sum_k w_k^2 sigma_{k,i}^2). A spectrum confined to one group therefore gives the same yields
as "fixed" at that group’s midpoint. A parent with no fission rate in a spectrum (sum r_g = 0) falls back to the
spectrum_average rule, which also finds no fission energy there, so it carries no yields in that spectrum; the
weights record names the fallback. Every distinct step spectrum gets its own weights. The mixing needs the
groupwise library rows, so a spectrum-collapsed cache is not used. It cannot be combined with the
fission_yields uncertainty channel.
parents selects which parents’ fission feeds products:
"fission_yields": {
"files": [
{"path": "/data/endfb-viii.0-nfpy/nfy-092_U_235.endf", "sha256": "64 hexadecimal digits"},
{"path": "/data/endfb-viii.0-nfpy/nfy-094_Pu_239.endf", "sha256": "64 hexadecimal digits"}
],
"parents": {"include": ["U235", "Pu239"]}
}
Give exactly one of include or exclude, a nonempty list of nuclide names (U235, Am242m1). A parent with a
yield file that the selection leaves out keeps its fission reaction and loses nothing from the burn-up diagonal; its
whole fission rate goes to leakage and is booked per parent as fission_unselected_to_leakage. These are refused
before any output: both include and exclude, an empty list, a name that is not a nuclide, a named parent without a
yield file in files, and a named parent with no fission (MT=18) row in the activation library.
yields: "cumulative" (default "independent") reads the MF=8/MT=459 tables in place of MT=454, with the same energy
selection and the same parents filter; an evaluation without MT=459 is refused. Cumulative yields already include
the feeding of each product by its fission-product precursors, and the decay chain feeds the product again, so the
inventory counts that feeding twice. This is an approximation the run reports and does not correct: the ledger’s
fission_cumulative_overlap gives, for each active parent, the summed cumulative yield and the share of it carried
by products that have a direct decay precursor (a chain nuclide with a positive decay edge to the product) that also
has a positive cumulative yield from the same parent.
Spontaneous fission
Without further input, a decay state’s spontaneous-fission branch (RTYP 6) is booked to leakage and counted
in the ledger’s spontaneous_fission_branches_to_leakage. fission_yields.spontaneous routes it to products
instead, and supplies the neutron multiplicity for a spontaneous-fission neutron source. A fission after another
transition (RTYP 2.6, β-delayed fission) is not spontaneous fission of the parent: it is always booked to leakage and
counted in unmodelled_decay_branches_to_leakage. Every input is hash-pinned and optional, but the object must
declare at least one:
"fission_yields": {
"spontaneous": {
"files": [{"path": "/data/sfy/spontaneous-yields.endf", "sha256": "64 hexadecimal digits"}],
"nubar_endf": {"path": "/data/endfb-viii.0-decay/endf-b-viii-0_decay.dat", "sha256": "..."},
"nubar_table": {"path": "nubar.json", "sha256": "..."}
}
}
filesare ENDF-6 MF=8/MT=454 spontaneous-fission yield evaluations (the ENDF/Bsfysublibrary, same record layout as the neutron-induced files). A file may hold one material or the whole sublibrary; each material is one parent. Yields are read at the lowest tabulated incident energy, which is0for spontaneous fission, and the same checks apply (independent yields sum to two fragments within1e-6, no renormalization). A state with a spontaneous-fission branch and a yield evaluation sendsλ · BR_SF · yieldto each fragment, so one decay makes two product atoms and nothing goes to leakage. A fragment absent from the decay library is booked to leakage by name. A state with the branch and no evaluation keeps the branch on leakage and is named underledger.spontaneous_fission.uncovered_to_leakage; no other parent’s yields are borrowed. Only a branch that is the whole decay mode is routed.nubar_endfnames an ENDF file whose MF=1 MT=452 (total, preferred) or MT=456 (prompt) section gives each state’s spontaneous-fission neutron multiplicity. The total includes the delayed neutrons that follow the fission (for Cf-252, 3.7676 total against 3.7590 prompt), so the neutron source is about 0.2 % above the prompt-neutron source at fission time there, and differs by each nuclide’s own delayed fraction elsewhere. The multiplicity is taken atE = 0(a polynomial’s constant term, or the lowest tabulated point, recorded in the ledger). The ENDF/B-VIII.0 decay sublibrary carries these values (Cf-252: 3.7676). Do not name a neutron sublibrary: its MF=1 is the induced-fission multiplicity.nubar_tablenames a JSON document{"source": "<citation>", "nubar": {"Cf252": 3.7676, ...}}. The citation is required and recorded in the certificate; keys are explicit nuclide names. Its entries overridenubar_endffor the same state. ACTINV builds in no multiplicity, and a state with an SF branch and no multiplicity is reported as uncovered, never estimated.
With any nubar_* input every step gains fission.spontaneous_neutron_source (see Read your results).
Fission count and burn-up
options.fission (absent by default) adds a fission.count block to every step:
"options": { "fission": { "energy_per_fission_MeV": 200.0 } }
energy_per_fission_MeV defaults to 200, a conventional round figure and not a nuclide-specific energy; it affects
only the MWd/kg burn-up and must be finite and positive. The option works without fission-yield files: every library
fission (MT=18) row whose target nuclide is a state of the decay chain is counted, whether or not yields exist for it
(a row whose target has no decay record is listed under targets_absent_from_decay_library and is not counted). Both this option and
fission_yields.spontaneous are refused by the native waste composition solve. The count integrates one flux
multiplier per step, so options.fission is refused with power-driven steps (whose multiplier is solved per
sub-interval) and with schedule library overrides (the count reads the base library’s MT=18 rates).
fission_yields.spontaneous reads decay data only and combines with both.
MF=33 uncertainty
uncertainty is optional and neutron-only. uncertainty.covariance names an actinv-covariance-1 sidecar
(path and a mandatory sha256); the adjacent <stem>_index.json must link the exact activation-library/index
hashes, neutron projectile, group-boundary hash and every target/source identity. ACTINV recomputes and records
both sidecar and index hashes before matrix assembly. covariance may be omitted only when channels is exactly
["flux"] (flux-only mode, below); any other channels value still requires it, and when present MF=33 is
propagated exactly as always regardless of what else channels requests.
responses accepts the canonical selectors heat.total, heat.alpha, heat.beta, heat.gamma,
activity:Nuclide, activity:*, and activity.total (the aggregate propagated directly through the
full covariance — not a root-sum-square combination of per-nuclide bands). Selectors must be unique.
An empty or omitted list selects all four heat
components plus every activity reported at that step. confidence_level defaults to 0.95 and must be strictly
between zero and one. require_complete defaults to false; when true, an active activation row without a valid
MF=33 self-covariance — or a nonzero-sensitivity parameter in any requested channel without uncertainty data —
fails rather than returning a partial band.
channels is optional and accepts "cross_section_mf33" (the implicit default), "decay_constants",
"fission_yields" and "flux". When omitted, only the MF=33 cross-section channel is evaluated and the channel
fields are absent from the output. decay_constants propagates
each radioactive chain member’s decay-constant uncertainty sigma_lambda = lambda * dT_half/T_half read from the
pinned decay file’s MF=8/MT=457 record. fission_yields propagates each populated fission edge’s independent-yield
DY read from the pinned MF=8/MT=454 file at the requested yield energy. Both channels are diagonal — the
evaluations carry no correlation data — and each reports its own sensitivity list, standard uncertainty and
coverage. A nuclide or product with no declared uncertainty is named in uncovered_decay_constants /
uncovered_yield_products.
The flux channel (1.4.0) propagates each input group’s transport-tally statistical error (spectrum.relative_error, or a mesh
cell’s own flux-file relative_error — a mesh cell without one is an error naming that cell) as a first-order,
diagonal (uncorrelated group-to-group) channel: the parameter is the log of that group’s absolute flux after
total scaling, its direction is the reaction-only burn matrix a unit flux confined to that group alone would
produce, and its sensitivity is exactly the response’s own sensitivity to that group’s flux level. Each
flux_sensitivities parameter reports its group in the order the spec declared flux_per_group (undoing
descending for that label only — energy bounds, flux and standard uncertainty are unaffected, since they name
the same physical group either way). The channel’s
variance is sum((s_g * e_g)^2) over groups with a positive sensitivity and a given error; a fully-correlated
alternative bound, sum(|s_g| * e_g), is reported alongside it (flux_fully_correlated_bound) for a worst-case,
correlated-error comparison. flux needs no covariance sidecar by itself: channels: ["flux"] alone (covariance
omitted) is
flux-only mode — MF=33 is not propagated and the band is the flux channel alone, with the method and band name
naming that. Everything else the flux collapse depends on (self-shielding row scale, rate_scale, fission-yield
selection, mode and pruning choices) is held at the nominal run’s values. The flux channel is diagonal, needs no
covariance and is not a nuclear-data parameter, so it is excluded from voi, isomer and design (below): those
report ranks over parameters an experiment could better-measure, and a transport tally’s statistical error only
shrinks by running more particle histories.
voi is optional ({"top": N}, 1–256) and emits a value-of-information table inside each requested response: the
top parameters ranked by |variance_share| — the share of the propagated variance each parameter carries
(s_i·(Σ·s)_i over the MF=33 block, (s_i·σ_i)² for the diagonal decay/yield channels — negative shares are
emitted, not hidden, under anticorrelation) — plus the total propagated variance the band was built on and an
unranked summary naming sensitivity-bearing parameters with no covariance coverage. The table answers “which
measurement most buys down this band”: removing a parameter’s uncertainty drops the variance by its share.
Each requested response reports its nominal value, local sensitivity to every active collapsed row in response units
per barn, MF=33 standard uncertainty, relative standard uncertainty when defined, the requested two-sided normal
interval, an alternate-CRAM-order difference, and a conservative interval expanded by that numerical-method bound.
When extra channels are requested the record adds per-channel sensitivity lists, per-channel standard uncertainties
and a combined_standard_uncertainty equal to the root-sum-of-squares across channels, plus a channels report
naming each channel’s coverage. Coverage is complete only when every nonzero-sensitivity parameter in every
requested channel has evaluated uncertainty data. Missing evaluated cross-reaction terms contribute zero and are
counted; they are not invented. A state-resolved (MF=10) product row takes its reaction’s MF=33 covariance, fully
correlated with the reaction total, so a product such as Co-58 from Ni-58(n,p) is in the band. Its isomer-branching
uncertainty (MF=40) is not. Such a response counts these rows in parameters_from_reaction_total, its
cross_section_mf33 channel says so in note, and its coverage is partial. These intervals are neither tolerance
limits nor safety margins, and exclude MF=32 resonance-parameter and MF=40 production covariance, decay-yield and
cross-channel correlation, material-composition, response-coefficient and model uncertainty — the uncovered_remainder channel names these.
Absent a requested flux channel, incident-flux uncertainty is excluded there too; with flux requested, that
entry instead names the narrower remainder the channel does not cover (systematic flux uncertainty from the
transport model, geometry and transport nuclear data — the channel covers only the tally’s own statistical error).
Additional uncertainty reporting
| Field | Meaning |
|---|---|
isomer | Optional object with top (1–256), reporting isomer-resolved variance and pathway partitions |
design | Optional object with top (1–256), ranking variance removed by a perfect measurement using the covariance model |
unmodeled_relative | Declared finite nonnegative relative term; adds (u * nominal)^2 to variance |
unmodeled_table | Hash-pinned actinv-unmodeled-table-1 file, optional material-family key, and nonnegative fallback |
unmodeled_evalspread | Hash-pinned actinv-eval-spread-1 artifact supplying its suggested relative term |
Only one of the three unmodeled_* sources may be declared. A relative error term cannot cover a zero or missing-channel prediction. It supplements the declared band; it does not establish coverage of all excluded uncertainty sources. isomer.top and design.top default to voi.top when set, otherwise 20.
Radiological responses
radiological is optional. Its table is strict JSON with format actinv-radiological-table-1; the declared SHA-256
is mandatory and is recomputed before the calculation. ACTINV ships no default table and makes no jurisdiction or
scenario selection. A minimal table is:
{
"format": "actinv-radiological-table-1",
"title": "Example only",
"source": {
"citation": "Issuing authority and publication",
"edition": "2026",
"url": "https://example.invalid/source",
"jurisdiction": "example"
},
"responses": [
{
"id": "clearance-2026",
"kind": "clearance_index",
"basis": "Describe the applicable material and scenario",
"coefficients": {"Co60": 100.0, "Mn56": 1000.0}
}
]
}
Response IDs and canonical nuclide keys must be unique. kind is clearance_index, waste_index,
ingestion_dose, inhalation_dose, a2, or activity_limit. Clearance/waste coefficients are limits in Bq/kg;
ingestion/inhalation coefficients are in Sv/Bq; a2 coefficients are A2 transport values in Bq (the FISPACT-II ATWO
index sum(A_i / A2_i), reported per gram of material); activity_limit coefficients are any other absolute activity
limit in Bq (A1, an exempt consignment or practice total), giving sum(A_i / limit_i) per gram of material. A2 values
are bundled (below), or supply your own table, converting IAEA TBq values to Bq. Every coefficient must be finite and positive. An empty responses selector chooses every
table response in table order; otherwise only the named unique IDs are evaluated.
Each step reports the selected value, unit, covered and missing activity, activity-coverage fraction, contributing
nuclide count, and sorted active nuclides without a coefficient. Missing coefficients are not treated as zero.
require_complete: true rejects the entire calculation when any selected response lacks a coefficient for positive
activity. The certificate retains the table hash, source metadata, kind, basis, and coefficient count.
A response may also carry two optional lists for what a coefficient cannot say. Tables without them are read exactly as before, so existing hash-pinned tables are unaffected.
unlimited: canonical nuclides whose source limit is “Unlimited”. They have no coefficient (listing one that has a coefficient is an error). Their activity counts as covered and contributes zero, because an unlimited A1 or A2 limit adds nothing tosum(A_i / limit_i). The step lists the active ones inunlimited_active_nuclides; they are not inmissing_active_nuclides, sorequire_complete: trueaccepts them.covered_by_parent: a map from a progeny to the parents whose value already includes it. While any listed parent has positive activity, the progeny’s activity counts as covered and contributes zero, even when the progeny has a coefficient of its own, so a decay chain holding both is not counted twice. The step lists these ascovered_by_parentpairs ofnuclideandparent. With no listed parent present the progeny is evaluated like any other nuclide: its own coefficient, or missing. Every parent must itself have a coefficient or beunlimited, a nuclide may not be its own parent, and the map may not contain a cycle.
Both keys are omitted from the step output when nothing in them is active, and the certificate gives
unlimited_count and covered_by_parent_count only for a response that uses them.
{
"format": "actinv-radiological-table-1",
"title": "Example only",
"source": {
"citation": "Issuing authority and publication",
"edition": "2026",
"url": "https://example.invalid/source",
"jurisdiction": "example"
},
"responses": [
{
"id": "a2-example",
"kind": "a2",
"basis": "A2 in Bq",
"coefficients": {"Co60": 4.0e11, "Cs137": 6.0e11},
"unlimited": ["Mn53"],
"covered_by_parent": {"Ba137m1": ["Cs137"]}
}
]
}
See the qualification boundary before using a regulatory table.
A table’s source may also carry the optional strings scope, retrieved, source_file, source_sha256,
converter, licence, and row_provenance. When present they are nonempty and are kept in the certificate.
Bundled regulatory tables
ACTINV ships a few regulatory tables inside the program, converted from public sources by scripts that are kept in
the repository. They are opt-in: set radiological.table.path to bundled:NAME. Nothing is selected for you, there
is no default jurisdiction, and an unknown name is an error that lists the available names.
"radiological": {
"table": {"path": "bundled:us-49cfr173-a2"},
"responses": ["a2-u-medium"]
}
actinv fills a missing sha256 from the bundled table and rejects a different one. Other front ends must declare
the 64-hex-digit SHA-256 of the table, which is recorded in the result like any other table.
| Name | Source and scope | Coefficient | Licence |
|---|---|---|---|
us-49cfr173-a1, us-49cfr173-a2 | 49 CFR 173.435 (eCFR, 2026-10-13), the IAEA SSR-6 Rev.1 (2018) Table 2 A1 and A2 values. United States transport of radioactive material. | A1 or A2 in Bq (from TBq) | US Government work, public domain |
us-49cfr173-exempt-concentration | 49 CFR 173.436, exempt material activity concentration. Transport. | Bq/kg (from Bq/g) | public domain |
us-49cfr173-exempt-consignment | 49 CFR 173.436, exempt consignment activity. Transport. | activity in Bq | public domain |
euratom-2013-59-annex-vii-a | Council Directive 2013/59/Euratom, Annex VII Table A Part 1: exemption and clearance of solid material, artificial radionuclides. European Union (national law may differ). | Bq/kg (from kBq/kg) | EU reuse with attribution |
euratom-2013-59-annex-vii-b-concentration | Annex VII Table B column 2, exemption of moderate amounts. | Bq/kg (from kBq/kg) | EU reuse with attribution |
euratom-2013-59-annex-vii-b-activity | Annex VII Table B column 3, total activity for exemption. | activity in Bq | EU reuse with attribution |
de-strlschv-2018-anlage-4 | Strahlenschutzverordnung 2018, Anlage 4 Tabelle 1: unrestricted clearance (column 3) and the specific clearance routes (columns 6 to 11 and 14), one clearance_index response per route. Germany. Not an official version. | Bq/kg (from Bq/g) | official work, section 5(1) UrhG |
uk-epr-2016-sch23-pt3-table-2 | Environmental Permitting (England and Wales) Regulations 2016, Schedule 23 Part 3 Table 2, concentration of radionuclides in a solid or relevant liquid. United Kingdom (England and Wales). | Bq/kg (from Bq/g) | Open Government Licence v3.0 |
ca-nsrdr-2000-207-schedule-2 | Nuclear Substances and Radiation Devices Regulations (SOR/2000-207), Schedule 2, unconditional clearance levels. Canada. Not an official version. | Bq/kg (from Bq/g) | Reproduction of Federal Law Order (SI/97-5) |
Each table’s source block names the title, edition, URL, retrieval date, SHA-256 of the source file, converter script
(scripts/regulatory/), and licence. The converters read the downloaded file and type no numbers. Tables and the
per-row sidecars are under crates/actinv-core/data/regulatory/; a sidecar (*.rows.json) holds the original row text,
footnote markers, flags, and the reason any source row is not in a table. ACTINV does not read the sidecars.
How to read the tables:
- Limits in Bq, not Bq/kg. The A1, A2, and total-activity tables hold an activity in Bq, with response kind
a2(A2) oractivity_limit(A1, exempt consignment, Directive Table B column 3). The index is the number of limits per gram of material; multiply by the mass in grams to compare a consignment or inventory. - Uranium. The transport tables list uranium by lung-absorption type. Each carries three responses that differ only
in the uranium rows:
...-u-fast,...-u-medium,...-u-slow. An emptyresponseslist returns all three; choose one deliberately. - Unlimited rows. Rows with no finite limit (“Unlimited” in 49 CFR 173.435: Mn-53, Ni-59, Zr-93, I-129, Th-232 and
others) are listed in the response’s
unlimitedlist. Their activity is covered and contributes zero, so an activation inventory that holds them still satisfiesrequire_complete: true. A few uranium rows are unlimited in only one lung-absorption response, as in the source (U-236 in-u-fast). - Element-level rows. Rows such as
U (nat)orRb(nat)cannot be coefficients. They are in the sidecar. ACTINV reports their activity as uncovered and never as zero, sorequire_complete: truerejects a run that needs them. - Parents with progeny. Rows marked as including progeny (footnote (b) in 173.436, (1) or (2) in the Directive) keep
the parent’s value, and the table’s
covered_by_parentmap lists the progeny of each such parent. While the parent has activity, a listed progeny (Ba-137m under Cs-137, Rh-106 under Ru-106, Pa-234m under Th-234) is covered with zero contribution instead of being reported as missing; a progeny that has its own row (Y-90 under Sr-90) is not summed a second time. The inventory does not need editing. If the progeny is present without its parent, it uses its own row or is missing, as for any nuclide. 49 CFR 173.435 footnote (a) only refers to the IAEA SSR-6 list of such parents, which the CFR does not reproduce; for those tables the converter uses the 173.436 footnote (b) progeny lists for the parents that carry footnote (a). Footnote (a) parents that the 173.436 list does not name have nocovered_by_parententry, so their progeny can still appear as missing; the rows sidecar marks themparent_with_progeny_not_in_173_436_list. - Notes kept in the sidecar only. The A2 of Mo-99 in the table is 0.6 TBq; 49 CFR 173.435 footnote (i) gives 0.74 TBq for domestic use. The Directive’s Table B K-40 entry carries the note on potassium salts below 1000 kg. Neither is in the coefficient tables; read the sidecar rows when either applies.
- Source anomalies are recorded rather than corrected: the Directive’s Table B lists U-240 twice (the nuclide-alone row is used), and its parent/progeny marks disagree with its progeny lists for a few nuclides.
- Isomer labels. Three CFR rows use lifetimes (
Eu-150,Np-236,Ta-178). They are mapped to ACTINV isomer states by the decay half-lives in ENDF/B-VIII.0, and flagged in the sidecar.
These tables carry the regulation’s numbers only. Whether a table applies to your material, jurisdiction, and use is your decision.
Building the ICRP 119 dose-coefficient table locally
ICRP Publication 119 (the carrier of the ICRP 72 public ingestion and inhalation coefficients) is copyrighted, so ACTINV does not ship its values. If you have a copy of the PDF, generate a table for your own use:
python3 -I scripts/regulatory/fetch_icrp119.py --pdf P119.pdf --out icrp119.json --fispact-convention
This needs pdftotext (poppler). The script reads Annex F (ingestion, adult) and Annex G (inhalation, 1 um AMAD,
adult, types F/M/S) and writes one response per variant (ingestion-adult-variant1, inhalation-adult-F, …) next
to an icrp119.variants.json that records every choice. With --fispact-convention it adds
ingestion-adult-fispact-max and inhalation-adult-fispact-max, the maximum over the f1 variants and over F/M/S,
which is the convention found in FISPACT-II’s hazards file for its ICRP 72 rows. Keep the output out of version
control and do not redistribute it. --download-url URL --yes-download fetches the PDF first, but only from a URL you
confirm.
scripts/regulatory/compare_fispact.py compares a table with the clearance, A2, or hazards files of a FISPACT-II
2012 data bundle that you hold. It is a QA report, not a feature; the FISPACT files are never copied into ACTINV.
Damage observables (dpa)
damage is optional and is required when options.outputs contains "damage". Its table is strict JSON with
format actinv-damage-table-1; the declared SHA-256 is mandatory and is recomputed before the calculation. The
table’s projectile must match the problem projectile, and its boundaries_eV must be the activation library’s
boundaries exactly — actinv build-damage produces tables collapsed onto the same group structure.
A table row is a per-group damage-energy production cross section in barn·eV, keyed by a canonical explicit nuclide
(Fe56, Ta180m1) or a canonical element symbol (Fe); an element row covers every material nuclide of that
element without its own row. Rows must be nonnegative, finite, and exactly boundaries - 1 in length. Target keys
are validated against the canonical naming rules — fe56 is an error, not a synonym.
displacement_energy_eV maps canonical element symbols to positive displacement energies; with a table-1 file every
covered element must have one, with an actinv-damage-table-2 file an omitted element takes the energy the table
records, and a nuclide key there is an error. require_complete: true rejects the run when any material
composition nuclide lacks a row. Uncovered nuclides are otherwise named in the ledger’s
damage.uncovered_targets and reduce covered_atom_fraction; they are never treated as zero data.
Each step reports damage: total damage_energy_eV_per_g_s, material dpa_rate_per_s, cumulative dpa, the
covered-atom fraction, and a per-element block of atoms_per_g, damage_energy_eV_per_g_s, dpa_rate_per_s,
dpa. The displacement model is NRT: dpa_rate = 0.8 * damage_energy_per_atom_per_s / (2 * E_d); the material
rate is the covered-atom-weighted mean of the element rates. Damage targets are the material’s
composition-resolved nuclides — transmutation products are not counted, and in coupled mode the evolved target
inventories are used. The ledger records the table hash, covered elements, displacement energies, uncovered
targets, model, and units; the certificate records the table’s provenance and the computed input hash.
Damage-energy production comes from ENDF-6 MF=3/MT=444 sections. TENDL-2025 and EAF-2010 as distributed do not
carry MT=444. For TENDL-2025 neutron targets that are stable or have a half-life of at least one year, the data
catalog (1.2.0) ships a ready table, catalog:tendl-2025-neutron-damage, built with the kinematic method; for other
data, build tables from heatr-processed or equivalent damage-energy evaluations, or build an
actinv-damage-table-2 table with actinv build-damage --method kinematic.
Kinematic damage energy and the table-2 format
--method kinematic computes the damage-energy cross section channel by channel on the 0 K pointwise grid
(resonances included for MT=2 and MT=102). Elastic scattering and the discrete two-body levels use the MF=4 or
MF=6 LAW=2 angular distribution and the MF=3 Q value; single-particle continua (MT=91, 649, 699, 749, 799, 849,
and MT=103-107 when no level MTs exist) use MF=6 LAW=1 Kalbach-Mann or Legendre distributions; capture uses the
incident momentum plus the photon recoil. Recoil energy becomes damage energy through the Lindhard partition in
Robinson’s fit (NJOY HEATR df); a recoil below E_d produces none. E_d defaults per element to the table NJOY2016
HEATR applies when no ed is given (Be 31, C 31, Mg 25, Al 27, Si 25, Ca 40, Ti through Cu 40, Zr 40, Nb 40, Mo 60,
Ag 60, Ta 90, W 90, Au 30, Pb 25 eV; 25 eV for any other element); --displacement-energy EL=eV overrides it. Quadrature is Gauss-Legendre in the emission
cosine, split at the threshold and the NRT breakpoints, and the incident-energy grid is refined until a lin-lin
midpoint agrees within 1e-3. The group collapse is the flat-lethargy weighting of the other builders.
Capture recoil: with --capture-photons evaluated (default) the photon spectra of MF=6 are used where the
evaluation carries them, and the result is flagged evaluated_photon_spectrum: one recoiling nucleus takes the
incident neutron’s momentum and the summed expected photon recoil (the momenta of a cascade emitted before the nucleus
has slowed down add as a single recoil), and its damage energy is partitioned once. With per-photon, NJOY HEATR’s
treatment of MF=6 photon data (tabsq6), each photon’s recoil E_gamma^2 / (2 (A + 1) m_n c^2) is partitioned
separately and averaged over the discrete lines and the continuum, times the photon multiplicity, with no
incident-neutron momentum; the result is flagged per_photon_spectrum. The multiplicity is taken at each record’s
incident energy and the product is interpolated linearly between records, as HEATR does; each continuum panel is
integrated by 8-point Gauss-Legendre after splitting at the photon energies whose recoil reaches the displacement
threshold and the NRT breakpoints (HEATR uses 4-point Gauss-Legendre over the whole panel). Where the evaluation has no
MF=6 photons, per-photon falls back to the one-photon treatment. With one-photon (and the fallbacks), the excitation
energy is emitted as one photon (NJOY HEATR capdam), flagged excitation_energy_one_photon_upper_bound. A cascade of
several photons recoils less than one photon, so the one-photon value is an upper bound; the treatments therefore
differ for capture. The mode is recorded as model.capture_photons and is part of the cache key.
Continuum recoil: with --continuum-recoil kinematic (default) the residual’s recoil in an MF=6 continuum channel
(MT=91, 649, 699, 749, 799, 849 and the lumped MT=103-107) follows from momentum conservation with the emitted
particle’s evaluated energy distribution and, for Kalbach-Mann data without an explicit slope, Kalbach’s systematics;
it is consistent with the ejectile data. With evaluated, where the section carries a residual-nucleus subsection
with an explicit LAW=1 recoil energy distribution (a heavy product under LCT=1 or LCT=3, read as a laboratory
spectrum), the damage comes from that spectrum, as NJOY HEATR does: per incident-energy record the recoil histogram is
passed through the damage function, the record values are interpolated linearly in energy and multiplied by the
multiplicity (each panel is integrated by 8-point Gauss-Legendre after splitting where the response is not smooth;
HEATR uses a trapezoid on the damage function). Channels without such a subsection (including LAW=4 and
centre-of-mass recoil spectra) keep the kinematic recoil. In the TENDL-2025 evaluations of Fe-56, Cr-52 and Ni-58 the
two differ for MT=91, because the recoil spectrum lies partly outside the kinematic window of the neutron data. The
mode is recorded as model.continuum_recoil, each continuum channel note carries recoil (evaluated_recoil_spectrum
or kinematic_no_evaluated_recoil) when evaluated is requested, and channels.evaluated_recoil_channels counts the
channels that used the evaluated spectrum.
Every other non-elastic channel that has a cross section is uncovered: the table records its cross section and an
upper bound on its damage energy from the largest recoil the kinematics allow, D <= T. Ultra-narrow analytic
resonance lines that the pointwise grid does not carry are not added to the damage cross sections.
A table-2 file has the table-1 fields (format actinv-damage-table-2, source, projectile, group_structure,
boundaries_eV, units, targets) and these additions. displacement.displacement_energy_eV maps each element to
the E_d the recoil integrals were built with, and displacement.arc_dpa holds the constants b, c and the fit’s
reference displacement energy for the elements in Table 1 of Nordlund et al., Nat. Commun. 9, 1084 (2018) (Fe, Cu,
Ni, Pd, Pt, W; other elements have no arc-dpa output). The arc-dpa displacement count is evaluated at that reference
energy (Fe 40, Cu 33, Ni 39, Pd 41, Pt 42, W 70 eV), whatever E_d the damage energy and the NRT count use, because
the constants are only defined there; a table built at the reference energy is unchanged by this. Each target row holds damage_energy_barn_eV (the total, equal
to elastic + inelastic + disappearance), the three partials, uncovered_xs_barn, uncovered_damage_upper_barn_eV,
displacement_nrt_barn, displacement_arc_barn (when constants exist) and an informational channels record. The
total feeds the linear dpa exactly as a table-1 file does.
The 0 K resonance reconstruction sets a finite negative cross section to zero, as NJOY RECONR does for a negative
resonance-range value. When that happens for an MT, the target’s channels.zero_k_clipped array gains a record
{mt, points, min_barn, min_energy_eV, low_eV, high_eV} (the number of distinct clipped energies, the most negative
value and its energy, and the energy span of the clipped points); the key is absent for an evaluation with no negative
value. A nonfinite value still fails the build. With --continue-on-error true, an evaluation whose processing fails is
skipped: the top-level failed array lists {file, sha256, error} for each, sorted by file, the file still appears in
files, and the array is absent from a table with no failure.
With a table-2 file each step and each element add dpa_nrt_rate_per_s, dpa_nrt (exact NRT, integrated over the
recoil spectrum), dpa_arc_rate_per_s, dpa_arc (absent unless every covered element has constants),
damage_energy_uncovered_upper_eV_per_g_s, dpa_uncovered_upper_bound_rate_per_s and dpa_uncovered_upper_bound
(damage-energy bound divided by E_d). The step adds he_appm_per_dpa, the cumulative He-3 plus He-4 appm over the
cumulative linear dpa, when gas output is requested. An explicit displacement_energy_eV in the spec must equal the
table’s build value for every covered element; otherwise validation fails and names the rebuild command. A covered
element the spec omits takes the table’s value, and the ledger’s damage.displacement_energy_eV lists the energies
used while damage.displacement_energy_source names each covered element’s source, "spec" or "table". Where an
element’s arc reference energy is below its E_d, dpa_uncovered_upper_bound divides by the lower energy so that it
bounds the arc count as well.
Kerma heating and power-driven steps
kerma is optional. It adds an instantaneous nuclear-heating output to every step and lets a schedule step name a
heating power instead of a flux, as FISPACT-II’s POWER keyword does. Without a kerma section, and without a
step that names a power, the problem, its result and its ledger are byte-for-byte what they were before.
"material": {"composition": {"Fe": 100.0}, "density_g_cm3": 7.874},
"kerma": {
"table": {"path": "/data/kerma/fe_kerma.json", "sha256": "64 hexadecimal digits"},
"power_tolerance": 0.001,
"max_substeps": 64,
"top": 10
},
"schedule": [
{"dt": "1 y", "power_W_cm3": 150.0},
{"dt": "10 y", "flux": 0}
]
kerma.table is a hash-pinned actinv-kerma-table-1 file; the declared SHA-256 is recomputed before the run.
require_complete: true rejects the run when a material nuclide has no heating row (otherwise such nuclides add no
heating and are named in the ledger’s kerma.uncovered_composition_targets). Heating is summed over the decay
chain’s states, so coverage is judged there too: a composition isotope with no decay record is not a chain state and
heats nothing, whichever table row would match it, so it is listed as uncovered (and rejected by require_complete).
A kerma section is refused in a decay-only spec, which has no activation library whose group structure the table
must match. power_tolerance (default 0.001,
open interval (0, 1)), max_substeps (default 64, 1 to 4096) and top (default 10, the number of contributors listed
per step) are described below.
Table format. Strict JSON; unknown fields are an error.
| field | meaning |
|---|---|
format | actinv-kerma-table-1. |
source | citation, edition, url, all nonempty. |
projectile, group_structure, boundaries_eV | The projectile must match the problem; boundaries_eV must equal the activation library’s boundaries exactly. |
units | kerma_barn_eV_per_group. |
targets | Canonical explicit nuclide (Fe56, Ta180m1) or element (Fe) keys, each with one finite barn·eV value per group. A nuclide row wins over its element’s row. |
damage_energy_targets | Optional, same keys; nonnegative barn·eV damage-energy production. Every key must be covered by a targets row (a damage row is read through the heating row of the same state); one without is an error. |
temperature_K, files, uncovered | Optional provenance: the table’s temperature, per-file SHA-256s, and the evaluations that had no kerma section. |
A targets row is the group average of NJOY HEATR’s total heating kerma, ENDF MT=301, in eV·barn per atom; the
optional damage_energy_targets rows are the group-averaged total damage-energy production, MT=444 (NJOY2016
heatr.f90 header: MT=301 total kerma, 444 total damage energy). An atom of nuclide i in group fluxes phi_g
(particles cm⁻² s⁻¹) deposits k_i = sum_g K_ig * phi_g * 1e-24 * 1.602176634e-19 watts. Whether the photon energy
of a capture is counted as heating depends on HEATR’s local flag when the table was made (default 0: gamma rays
are transported and their energy is not deposited at the reaction site); ACTINV reads the table as given and cannot
see that choice, so state it in the table’s source.edition. An element row (Fe) gives every
isotope of that element without a row of its own, and every transmutation product of it, the natural-element
value, and counts them as covered, so covered_atom_fraction is a statement about rows, not about the quality of
their data; an isomer does not fall back to its ground-state row, only to the element row. A negative group value
(energy-balance kerma can go negative where an evaluation’s photon-production data are inconsistent) is accepted and named in the certificate’s
targets_with_negative_group_values; a negative damage-energy value is an error. A table is built from NJOY output
with scripts/build_kerma_table.py (below).
Power-driven steps. A step names power_W_cm3 or power_W_per_g instead of flux; the three are mutually
exclusive (flux: 0 beside a power target is accepted because that is what a result echo carries; any other flux
with a power target is an error). A power must be finite and positive, so cooling stays flux: 0. power_W_cm3
needs material.density_g_cm3 (finite, positive; otherwise unused) and is converted to W per gram with it; the
gram-based inventories need no density. A power-driven step requires a kerma section, uses the step’s own
spectrum when it has one, and may combine with feed/removal. It is refused with uncertainty,
options.screen, options.fission, pathways, schedule library overrides, the reverse and study tools and mesh
specs. It does combine with partition, and in trace mode the first-product pathways table is built from the
multipliers each sub-interval applied.
The flux multiplier on the step’s spectrum is chosen so that the instantaneous heating
sum_i N_i(t) * k_i(spectrum) * multiplier equals the requested power, with N_i the evolving atoms per gram of
every nuclide that has a kerma row (transmutation products with a row contribute). FISPACT-II fixes the flux once
per POWER card from the inventory at the start of the interval, and the user is expected to break a long
irradiation into sub-steps by hand. ACTINV does that automatically: the step is split into equal sub-intervals, the
multiplier is set at the start of each from the composition then reached, and every sub-interval’s end-of-interval
power is compared with the request. If the largest relative departure (the power drift) exceeds power_tolerance
the number of sub-intervals doubles (up to max_substeps) and the step is solved again from its start. A cap of 1
reproduces FISPACT-II’s start-of-step normalization. The achieved multipliers, the total flux in each sub-interval
and the worst drift are reported (see results); a step that hits
max_substeps above the tolerance is reported with converged: false and listed in the ledger, not hidden;
actinv run also prints a warning on stderr naming each such step (the result file is unchanged). The default
tolerance and cap do not converge a strongly burning case (for B-10 under a power target, 64 sub-intervals leave a
drift of about 1.5 % and about 1024 are needed), so check converged. The drift measures the interval end only,
which bounds the interior when power varies monotonically across a sub-interval.
A power step needs heating from the material it starts with. The flux used for pruning, and the first sub-interval’s multiplier, come from the composition at the start of the run, so a power step is refused before the schedule starts when that starting material has no kerma heating under the step’s spectrum, even if an earlier step would breed a nuclide that has a row. Start such a schedule with a flux-driven step on a material that has heating, or add a row for the starting material. A heating that turns negative (a legal negative table row) or non-finite during a step is reported as such, and a heating that vanishes in a refined attempt names the sub-interval and says that a coarser attempt had run.
A fragment (the kerma table pattern above supplies kerma; power_W_per_g needs no density):
"kerma": {
"table": {"path": "/data/kerma/fe_kerma.json", "sha256": "64 hexadecimal digits"},
"max_substeps": 256
},
"schedule": [
{"dt": "30 d", "power_W_per_g": 0.05},
{"dt": "1 d", "flux": 0}
]
Rate pruning and the automatic burnup-mode choice are decided before the schedule is solved, so for a power-driven
step they use the flux amplitude implied by the starting composition (reported per step as
estimated_flux_multiplier). If the achieved multipliers differ greatly from it, set options.prune and
options.mode explicitly.
Kerma output. With a kerma section every step reports its instantaneous heating at the step’s end. Flux-driven
steps use their flux multiplier; a power step uses its final sub-interval’s. See the results guide for the fields.
Build a kerma table
python3 scripts/build_kerma_table.py OUTPUT.json --pendf fe56.pendf \
--boundaries-from damage_table.json --group-structure fispact-709 \
--temperature-K 293.6 --damage-energy
python3 scripts/build_kerma_table.py OUTPUT.json --gendf fe56.gendf --group-structure my-groups
The script reads ENDF-6 tapes written by NJOY2016 and runs no NJOY. --pendf takes a HEATR-processed PENDF: its
pointwise MF=3/MT=301 (and with --damage-energy MT=444) section is collapsed onto the boundaries of
--boundaries-from (any JSON with a boundaries_eV list) with a flat-in-lethargy weight, the weighting
actinv build-damage uses; linear-linear sections only, and zero outside the section’s energy range. --gendf takes
GROUPR output, whose own group averages and EGN boundaries are used; GROUPR must have been run with lord=0,
nsigz=1 and one temperature per tape, and a GENDF names every material as a ground state because it carries no
isomer designation. A material without MT=301 is listed under uncovered, never zero-filled. Several tapes may be
combined into one table; two materials mapping to the same target are an error. The output file’s SHA-256 is printed
for pinning into kerma.table.
Self-shielding
self_shielding is optional; omission preserves the ordinary unshielded path byte-for-byte. Its table names a
hash-pinned actinv-shield-table-1 artifact — the declared SHA-256 is recomputed before the calculation and a
mismatch is an error. Build tables with actinv build-shielding EVAL_DIR OUT.json; the table’s group boundaries
must equal the activation library’s exactly. Instead of a table, a geometry section selects the
resolved-resonance sigmoid-curve model described below; exactly one of the two is required.
dilution selects the background dilution each covered nuclide sees: "composition" derives
sigma0_i = sum_j(n_j * sigma_p,j) / n_i from the declared material (table potential cross sections where the
nuclide is covered, an analytic channel-radius estimate elsewhere, named as estimates in the ledger);
"fixed" applies the validated positive sigma0_b to every covered nuclide. Factors interpolate in
ln(sigma0) x sqrt(T) and clamp at the grid ends.
Each covered group applies a full-group Bondarenko fold, not a flat lethargy blend: the unresolved-range segment
carries its probability-table weight mean w = sigma0/(sigma0+sigma_t) and weighted moment sigma_x*w, a
resolved-range segment carries the same moments from a pointwise quadrature of the reconstructed resonance cross
sections, Doppler-broadened (SIGMA1) to each temperature column, and the uncovered part is suppressed by sigma0/(sigma0+sigma_t,background) over the smooth MF=3 background. The emitted
group_factors are the applied scale; factors remains the covered-segment factor for reporting, and tables
without group_factors fall back to the flat (1-c)+c*f blend.
Material nuclides absent from the table are named shielding_uncovered and their rates are untouched;
require_shielding_complete: true fails the run instead. The section rejects any sha256 or boundary mismatch.
The ledger and certificate record the table hash, dilution mode, effective sigma0 per nuclide, applied factors,
and method limits — including that damage observables are not shielded and composition dilution uses the
declared material, not evolved inventories.
When uncertainty is also present, the MF=33 collapse weights each row’s spectrum integral by that row’s
shield factors (the collapse_weighted convention: sigma_i = sum_g phi_g * f_i,g * sigma_i,g / sum_g phi_g),
so the propagated parameters are the same shielded one-group cross sections the depletion matrix uses; the
run checks the collapsed nominals against the shielded fold bitwise. The same fold applies on the
study.robustness MF=33 sampling path.
Monte Carlo sampling statistics
The study.robustness sampling path is the equivalent of FISPACT-II SENSITIVITY/MCSAMPLE. By default
it reports each response’s sample mean, std and sampling error. Declare robustness.statistics (an object,
{} for the defaults) to add a sampling_statistics block per case:
"robustness": {
"samples": 1000, "seed": 17, "responses": ["total_activity_bq_per_g"],
"channels": {"cross_section_mf33": true, "flux_rel_std": 0.05},
"covariance": {"path": "cov.npz", "sha256": "..."},
"statistics": {"percentiles": [2.5, 16, 50, 84, 97.5], "histogram_bins": 20,
"correlation_top": 10, "bootstrap_resamples": 200}
}
Per response and cooling time it gives the distribution (n, mean, std, skewness, min, max,
percentiles, optional histogram), a bootstrap convergence block (standard error of the std and of every
requested percentile), the linear first_order std for the same response when the run computed it (with the
ratio and the gap in bootstrap standard errors), and input_correlations: the Pearson and Spearman
correlation of the response with each sampled input parameter, ranked by |spearman| and cut to
correlation_top, each parameter named by channel and target nuclide, MT, decay-constant or yield edge. A
case-level response_correlation matrix gives the Pearson correlation between all requested responses.
Percentiles are exact order statistics (nearest rank): the smallest sample value x_(k) with
k/n >= p/100, k = max(1, ceil(n p/100)) computed in exact arithmetic on the decimal p; there is no
interpolation. Spearman uses average ranks for ties. One sample has no standard deviation (std is null), and
correlations, the response matrix and the bootstrap need at least three samples; below that they report
{"status": "insufficient_samples"} with the count. The first_order std is compared only when
cross_section_mf33 is the sole enabled channel (the first-order propagation carries that channel only);
otherwise the study’s local_vs_nonlinear has status: "not_comparable" with the enabled channels, and each
first_order says the same.
The sampled input is the natural log of each applied multiplicative factor. Without statistics the
robustness record is unchanged. See the study reference
for every field.
A runnable walkthrough lives at examples/shielding_demo.json: pure W-186 under a 4–25 keV custom spectrum at
fixed sigma0_b = 0.1 — the ledger names every applied factor and W-187 activity lands ~28% below the
unshielded solve of the same problem.
Dilution overrides
self_shielding.dilution_overrides (table mode only) replaces the computed background dilution for chosen
nuclides and groups, the equivalent of FISPACT-II SSFDILUTION:
"dilution_overrides": {"W182": {"300": 100.0, "301": 80.0}, "W184": {"194": 2.5}}
Keys are canonical nuclide names; inner keys are library group indices (0-based, ascending energy, the same
indices as applied_factors); values are positive finite dilution cross sections in barns. For a named group the
supplied sigma0 is used in place of the nuclide’s "composition" or "fixed" value; every other group keeps
the computed one. A nuclide the table does not cover, or a group the table does not carry for that nuclide, is an
error. The ledger and certificate list the applied overrides under dilution_overrides; the reported
sigma0_eff_b remains the computed value.
A fragment with the section it belongs to (the table supplies the covered nuclides and groups):
"self_shielding": {
"table": {"path": "shielding_table.json", "sha256": "..."},
"dilution": "composition",
"dilution_overrides": {"Fe56": {"300": 100.0, "301": 80.0}, "Fe54": {"194": 2.5}}
}
Geometry self-shielding (resolved resonances)
self_shielding.geometry selects FISPACT-II’s SSFGEOMETRY model instead of the Bondarenko table: the
“universal sigmoid curve” of Martinho, Goncalves and Salgado. It is exclusive with table, dilution, sigma0_b
and dilution_overrides, as SSFGEOMETRY and PROBTABLE are exclusive.
"self_shielding": {
"geometry": {
"shape": "foil",
"length_cm": 0.01,
"density_g_cm3": 19.3,
"resonance_files": [{"path": "n_W184.endf", "sha256": "..."}],
"choose": ["W"],
"reactions": "all"
}
}
A fragment that takes the density from the material (the geometry omits density_g_cm3):
"material": {"basis": "wt_percent", "composition": {"FE": 100.0}, "density_g_cm3": 7.874},
"self_shielding": {
"geometry": {
"shape": "wire",
"length_cm": 0.05,
"resonance_files": [{"path": "n_Fe056.endf", "sha256": "..."}]
}
}
shapeis"foil"(length_cm= thickness),"wire"or"sphere"(length_cm= radius), or"cylinder"(length_cm= radius plusheight_cm). Dimensions must be finite and positive;height_cmis required for, and only for, a cylinder. The effective length isy = 1.5 t(foil),2 r(wire),r(sphere),1.65 r h / (r + h)(cylinder). These are the rules of the manual’s Table 25 as quoted; they are not limits of one another (a long thin cylinder tends to1.65 r, the wire is2 r; a wide flat one tends to1.65 h, the foil is1.5 t), so choose the shape that describes the target rather than reading one as the limit of another.density_g_cm3converts the declared material (atoms per gram) to number densities. It may be omitted whenmaterial.density_g_cm3is declared; the geometry then uses that value. When both are given they must agree to1e-9relative, and one of the two is required. FISPACT-II instead takes atoms per unit area or length fromSSFFUEL/SSFMASS; ACTINV uses the run’s own material and a density.resonance_filesare hash-pinned ENDF-6 neutron evaluations, one nuclide each, carrying MF=2/MT=151 resolved resonance parameters (Breit-Wigner, Reich-Moore or R-matrix-limited, LRF=1, 2, 3 or 7). An empty list, an evaluation without MF=2, or one without a resolved range is an error. An LRF=7 feature that cannot be read as the widths below (an unknown channel reference, a KRM other than 3) is an error rather than a dropped resonance. A file may hold several MF=2 isotopes (a natural-element evaluation): each is keyed by its own ZAI, never by the material’s ZA, and an isotope with no usable resolved resonance is listed inresonance_data_unused. Only levels inside the[EL, EH]of the range that lists them count as resonance peaks: R-matrix spin groups carry poles above the resolved range (W-186 lists three near 10.1-10.4 keV withEH= 10 keV) that feed the in-range cross section but are not peaks, so they are dropped and counted per nuclide in the ledger’sshielding.geometry.resonances_outside_range(omitted when none).profile(optional,"none","endfb8"or"tendl", default"none") applies the same tape normalization asbuild-library --profileto each resonance file before it is read. Use"endfb8"for ENDF/B-VIII.1 evaluations (Cu-63, for example, lists a photon exit channel the strict reader refuses without it).chooserestricts the correction to listed nuclides or elements (SSFCHOOSE); every entry must be in the material. A nuclide entry must be supplied by a resonance file (otherwise the run is refused). An element entry shields the isotopes that a file supplies and names the others inshielding_uncovered, as whenchooseis absent (an error underrequire_shielding_complete). Withoutchooseevery material nuclide that a file supplies is shielded; other material nuclides are named inshielding_uncovered.reactionsis"all"(default; FISPACT-II applies the factor to every reaction of the shielded nuclide) or"capture"(MT 102 only).
For each resolved resonance i of a shielded nuclide, z_i = N * sigma_peak,i * y * sqrt(Gamma_gamma/Gamma), with
N the nuclide number density, sigma_peak,i = 4 pi/k^2 * g * Gamma_n/Gamma the Breit-Wigner peak cross section
and g = (2J+1)/(2(2I+1)). The resonance factor is G(z) = (A1 - A2)/(1 + (z/z0)^p) + A2 with A1 = 1.000,
A2 = 0.060, z0 = 2.70, p = 0.82 (FISPACT-II manual Eqs. 43-48). The factor applied in a library group is the
mean of G over the resonances peaking in that group, weighted by w_i = (Gamma_gamma/E^2) * g Gamma_n/Gamma
(Eqs. 49-50); groups without resonance peaks are untouched. The scaled cross sections feed the same per-group fold
as the Bondarenko path, including the MF=33 collapse.
For R-matrix-limited (LRF=7) evaluations, which ENDF/B-VIII and FENDL-3.2c use for many nuclides, the per-resonance
widths come from the spin groups’ channels, classified by their particle pair: the incident-neutron pair (MT=2) gives
the neutron channels, the capture pair (MT=102, including the eliminated photon channel) the capture channels, and
every other channel (fission, charged particles, inelastic) counts only toward the total. Gamma_n, Gamma_gamma
and Gamma are the sums of the channel widths over those three sets. With widths listed (IFG=0) each channel contributes its
magnitude; with reduced-width amplitudes (IFG=1) it contributes 2 P gamma^2, with the penetrability P at the
resonance energy from the same radii, penetrability flags and channel wave numbers as the LRF=7 reconstruction
(P = 1 for the photon channel). Under either, a channel closed at the resonance energy (its pair’s threshold at
or above it) contributes nothing. g uses the spin group’s
|J| and the target spin of the neutron pair, and A is that pair’s mass ratio. Resonances at non-positive energy
or without a positive neutron or capture width are skipped, as for the other formalisms. The single-level sigmoid
model does not use the interference between channels or between resonances that the LRF=7 formalism carries.
The ledger shielding.geometry block and the certificate record, per shielded nuclide, the number density and the
applied factor for each group with its energy range and resonance count, the effective length, and the resonance
file hashes (resonance_files_sha256, certificate inputs.shielding_resonance_files). Limits: the peak cross
section is the single-level Breit-Wigner value (FISPACT-II cites Froehner, JEFF Report 18, for it without
reproducing the formula); only the shielded nuclide’s own peak enters Sigma_tot, the other mixture components are
neglected (the model assumes non-overlapping resonances); the unresolved range, damage and temperature dependence
are not treated; and the sigmoid fit is an approximation to Monte Carlo results for simple shapes, not a
transport calculation.
Mixture self-shielding (pointwise cross sections)
This option is new in 1.7.2. Protocol P178 compared it with OpenMC’s continuous-energy reaction rates; it has not been compared with measurements.
On four fusion materials held out from its development (Eurofer-97, Inconel 718, a W-Ni-Fe heavy alloy and copper), ACTINV’s mixture self-shielding brought every listed resonance-capture rate within 3.4% of OpenMC’s continuous-energy rate on the same ENDF/B-VIII.1 data, where the unshielded rates differed by up to 32.3%. 7 of 73 listed capture rows were not scored or did not reach a 0.5% standard error and are not covered by that sentence. Evidence: rates and verdict.
Reconstructing every nuclide’s pointwise cross sections makes a run with a multi-nuclide alloy take minutes rather
than seconds. The reconstruction is done once per nuclide per run, and actinv mesh plans each distinct material
once, so the cost does not grow with the number of cells.
self_shielding.mixture computes per-group resonance self-shielding factors at run time from the material’s own
pointwise cross sections, in place of a precomputed Bondarenko table or the sigmoid curve. It is exclusive with
table and geometry (and with dilution, sigma0_b and dilution_overrides).
"self_shielding": {
"mixture": {
"evaluation_files": [{"path": "n_Cu063.endf", "sha256": "..."}, {"path": "n_Cu065.endf", "sha256": "..."}],
"profile": "endfb8",
"require_complete": false
}
}
evaluation_filesare hash-pinned raw 0 K ENDF-6 neutron evaluations, one nuclide per file (the inputsbuild-libraryreads), each with MF=2/MT=151 resolved resonance parameters and its MF=3 background. The files are verified against their SHA-256 like the geometry’sresonance_files.pointwise_filesreplaceevaluation_files(give one or the other): hash-pinnedactinv-pointwise-1tables, one nuclide each, already at the run temperature (see below).profiledoes not apply to them.profile(optional,"none","endfb8"or"tendl", default"none") applies thebuild-library --profiletape normalization to each file before it is read.require_complete(optional, defaultfalse) refuses the run when a material nuclide above 1e-6 atom fraction has no evaluation file. Without it, such nuclides enter the mixture total through the analytic potential-scattering estimate and are listed in the ledger asbackground_estimated.
For each material nuclide with a file, ACTINV reconstructs the total, elastic, fission and capture cross sections
at the run temperature (resonance contribution plus MF=3 background, Doppler broadened, as build-library does).
The flux is weighted as 1 / Sigma_t(E) per unit lethargy, where Sigma_t is the macroscopic total of the whole
declared mixture. In each library group that overlaps the nuclide’s resolved range, the nuclide’s factor for a channel
is the flux-weighted mean of its cross section over the whole group divided by its plain lethargy mean. The factors
scale the nuclide’s group cross sections as the other modes do (mt 2 elastic, mt 18/19 fission, mt 102 capture, every
other reaction the total factor). Groups that do not overlap a resolved range are unshielded, including the unresolved
range. The method needs a positive run temperature_K. A negative 0 K value (a negative MF=3 background under a
resonance-interference minimum, as in ENDF/B-VIII.1 Fe-54 elastic) is set to zero, as NJOY RECONR does.
With pointwise_files, nothing is reconstructed: each table is used as given, and every library group within its
energy range is shielded, since where the cross sections are smooth the factor is 1. A table is a JSON object with
format "actinv-pointwise-1", nuclide (for example "Cu63"), temperature_K, and energy_eV, total_b,
elastic_b, capture_b and optional fission_b (barns, linear in energy, energies ascending). Its temperature must
be within 1 K of the run’s temperature_K; ACTINV does not re-broaden it. actinv.openmc.export_pointwise writes
these tables from an OpenMC HDF5 library at one of its stored temperatures (OpenMC’s 294 K set serves ACTINV’s
293.6 K default), and ActinvR2SManager uses it for every material by default. A run then takes seconds rather
than minutes. Protocol P190 compared this mode with OpenMC’s continuous-energy rates:
On P178’s four models, ACTINV’s mixture self-shielding with pointwise cross sections exported from OpenMC’s ENDF/B-VIII.1 HDF5 library at 294 K, instead of reconstructed ENDF-6 evaluations, brought every listed resonance-capture rate within 3.4% of OpenMC’s continuous-energy rate on the same data; each region’s run took at most 73.4 s. 7 of 73 listed capture rows were not scored or did not reach a 0.5% standard error and are not covered by the sentence above. Evidence: record and verdict.
The ledger shielding.mixture block records the profile, temperature, evaluation files with their hashes, the
covered and background_estimated nuclides, per covered nuclide the number of groups and the smallest applied
scale for each channel, and in zero_k_clips every reaction whose negative 0 K values were set to zero (points,
energy range and the most negative value). With pointwise tables, pointwise_temperatures_K gives each covered
nuclide’s table temperature and the certificate lists the tables as shielding_pointwise_files.
Gas production (H and He isotopes)
This option was added in 1.4.0.
options.gas: true (default false) tracks the light charged-particle products of neutron activation — H1, H2,
H3, He3 and He4 — as real inventory nuclides, exactly as FISPACT-II does. Every neutron reaction’s light-particle
multiplicities (protons, deuterons, tritons, He-3, alphas) are read from a table built from the ENDF-6 reaction
definitions for MT 11–45 (excluding the 18–21 and 38 fission MTs), 102–117 and 152–200; MT 4 and 51–91 (inelastic)
and MT 102 emit none. A product row whose MT is not in the table (MT 18, fission, is the practical case: ternary
gas is not modelled) contributes no ejectiles and is named in the ledger’s gas.uncovered, keyed by MT, with its
share of the reaction rate. Each decaying nuclide’s own modes also feed the gas states directly: branching × λ
into He4 for every RTYP digit 4 (alpha) and into H1 for every digit 7 (proton).
Because the five gas states are real chain nuclides, they decay and react further like any other state — H3
decays to He3 at its own tabulated half-life, and a secondary reaction such as He3(n,p)H3 applies when the
library carries it — and they appear in the ordinary inventory, activity_Bq_per_g and heat_W_per_g output,
not only in the block below. If a light nuclide is absent from the decay library, a stable sink stands in for it
and the ledger’s gas.missing_light_states names it. Trace mode feeds the gas states from bulk material targets
through the unit-source mechanism exactly as it feeds any other product, including the hybrid reservoir treatment
when H or He is itself a bulk material constituent; the gas edges are ordinary edges in the graph pruning already
operates on, so options.prune needs no gas-specific handling.
options.gas is refused together with uncertainty, and for any projectile other than neutron (v1). With
gas off, every byte of PreparedRun, the result and the ledger is unchanged from a pre-P92 run; gas is absent
from the spec echo and fingerprint entirely rather than serialized as false.
Each step gains a gas block when enabled: per species (H1, H2, H3, He3, He4) it gives atoms_per_g
(the same quantity the main inventory reports for that nuclide), produced_atoms_per_g (atoms_per_g minus the
material’s initial population of that nuclide, ordinarily zero) and appm (produced_atoms_per_g per 1e6 atoms
of the material’s total initial population). It also gives inventory_appm (atoms_per_g per 1e6 initial
atoms, the initial content included). It also gives H_appm (H1+H2+H3), He_appm (He3+He4), their inventory
counterparts H_inventory_appm and He_inventory_appm, and initial_atoms_per_g, the appm normalization
denominator. The two conventions differ only for a light nuclide the material starts with, e.g. hydrogen in
a hydrocarbon. FISPACT-II’s printed APPM OF is the inventory convention (P95); compare against
inventory_appm, not appm. These fields are plain f64 inventory populations and dimensionless ratios computed at
result serialization, not raw inputs converted at a Spec::physical_inputs boundary, so they stay
outside the P16 typed-quantity inventory (docs/QUANTITIES.md, which P16 pins by hash), as
inventory[].atoms_per_g does. The ledger’s gas block records the ejectile table
version, uncovered and missing_light_states.
Step summary
summary (optional) adds a complete inventory report, steps[].summary, to every step: a FISPACT-II-style
nuclide table, element table, decay-mode activity totals and dominant-contributor rankings. Without it the result is
unchanged and no summary key is written.
| Field | Default | Meaning |
|---|---|---|
nuclides | true | Emit the per-nuclide table. |
elements | true | Emit the per-element table. |
dominant_top | 10 | Entries kept in each dominant-contributor list; 1 to 256. |
min_atoms | 0 | FISPACT MIND: omit nuclide-table rows whose absolute atoms (atoms × material.mass_g) fall below this. Finite and not negative. |
include_stable | true | false is FISPACT NOSTABLE: omit stable nuclides from the nuclide table. A state with no decay record (a light stand-in, a bulk nuclide missing from the chain, or any state with decay_data: false) is not called stable and stays in the table. |
depletion | false | true is FISPACT DEPLETION: add summary.depletion, the per-step depletion table of every initial-material nuclide. |
min_atoms and include_stable trim the nuclide table only. Totals, the element table and the dominant rankings
always include every state, so a filtered table still reconciles with its totals. The same summary section is
accepted by the mesh specification and applies to every cell.
depletion is opt-in within the summary: without it no depletion key appears in steps[].summary, and the ledger
and certificate carry no depletion entry. It works with trace and coupled mode, with per-step spectra, and with
schedule library switches (each step reports the rates of the library it ran on). With an uncertainty section that
supplies MF=33 covariance, each reaction channel also carries the relative standard uncertainty of its one-group
rate. A schedule step’s removal appears as its own removal channel, and a feed into an initial nuclide as
negative depletion with no channel. The decay channel’s half-life uncertainty is reported whatever
uncertainty.channels lists. Read your results describes the emitted fields.
{
"material": {"mass_g": 10.0, "density_g_cm3": 7.87, "composition": {"Fe": 100}},
"summary": {"dominant_top": 5, "min_atoms": 1e6, "include_stable": false}
}
Read your results describes the emitted fields.
Pathways and routes analysis
The optional pathways object asks for a full source-to-target route analysis (FISPACT-II’s ROUTES and
UNCERTAINTY pathway tables). It is opt-in: without it the result is byte-identical to a run that never heard of
it, and it is independent of the older options.outputs entry pathways, which keeps the trace-mode
first-product table. That table (the result’s pathways array) now also attributes production fed by the decay of
radioactive bulk nuclides (for example Ar-40 from natural K-40), listing the decaying bulk nuclide as from; a
nuclide in the inventory that no listed chain explains makes pathway_closure 1.
"pathways": {
"targets": ["Mn54", "Co60"],
"sources": [],
"max_depth": 10,
"path_floor": 0.005,
"loop_floor": 0.01,
"max_paths": 100
}
| Field | Default | Meaning |
|---|---|---|
targets | [] | Target nuclides. Empty selects the dominant nuclides of the final step automatically. |
rank_by | "activity" | Ranking for automatic targets: "activity" or "heat" at the final step. |
top_targets | 10 | Number of automatic targets. |
sources | [] | Source nuclides. Empty selects every initial nuclide (in trace mode the bulk material’s nuclides, plus feed when the schedule declares one). |
max_depth | 10 | Largest number of edges between a source and a target (1 to 64). |
path_floor | 0.005 | A route is kept when it carries at least this fraction of its target’s inventory. |
loop_floor | 0.01 | A walk that revisits a nuclide is kept when it raises its loop-erased path’s contribution by at least this fraction. |
max_paths | 100 | Routes reported per target; the excess is dropped smallest first and shows up in the residual. |
by_step | false | Also report every route’s atoms at the end of each schedule step. |
fission_parents | [] | Nuclide names. When nonempty, routes may pass through fission edges only from these parents; the inventory is unchanged, and what the other parents’ fission products received is reported as unexplained in each target’s closure residual. Empty places no restriction. |
Nuclide names are explicit nuclides such as Mn54 or Co60m1. A source that is not an initial nuclide, or a target
that is not a tracked state of the run, is named in the result’s notes rather than failing the run.
fission_parents removes only edges that are fission edges of a parent outside the list (a chain product with a
nonzero yield in the parent’s tables). A parent and product pair that also carries a decay or another reaction keeps
its edge, because the matrix entry cannot be split; that fission share stays attributed.
Each route is integrated exactly rather than estimated. For a route x0 -> x1 -> ... -> xk, ACTINV solves the
linear chain with every node’s full removal rate (decay, all reactions and declared removal) on the diagonal and
only the route’s own edge as the source, through every schedule step, using the same per-step rates the main solve
used. The solve is a dense matrix exponential of the small bidiagonal system, so there is no Bateman closed form
and equal rates are harmless. The analysis is linear in the source atoms and works in both trace and coupled
modes. A route is at most max_depth edges long; the search discards a branch as soon as an upper bound on what
it can still deliver falls below the smallest target’s path_floor, so default settings stay fast on large
networks. The search tree is capped at 2,000,000 nodes. If the shared search exceeds that, every target is searched
again on its own floor and the budget is divided evenly among the sources, so one tiny target or one wide source
cannot starve the others; a target whose search still ran out of budget reports search_truncated: true and the
truncated_sources, and the notes name it. At most 8 x max_paths candidate routes per target are integrated, the
largest upper bounds first; the number cut is candidates_dropped_by_cap on the target (and in the notes).
The loop_floor test is applied after, and in addition to, path_floor: a loop walk is dropped when it raises its
loop-erased path by less than loop_floor even if it alone carries more than path_floor of the target. With the
default loop_floor of 0.01 the residual can therefore exceed path_floor; set loop_floor near 0 to account for
every walk above path_floor.
Edge labels name the decay mode or reaction that connects two nuclides. Spontaneous-fission products are labelled
SF, atoms supplied by a schedule feed are feed, and an edge into the removal sink is removal. Labels come from
the decay and reaction tables, not from the run’s rates: a reaction that has a row in the library is named even when
its collapsed rate is zero in this spectrum, and when a decay and a reaction connect the same pair the label joins
them ((n,n')/IT).
The target inventory is the sum over every walk through the graph of that walk’s chain contribution. Walks that
never repeat a nuclide are reported as ordinary routes. A walk that revisits a nuclide (for example a
(n,g) reaction followed by a decay back to the parent) has is_loop: true, names its loop-erased base_path,
and reports loop_gain, its contribution relative to that base path. The floors apply to routes and loop walks
separately, so a route below path_floor alone is not promoted by the loops attached to it.
Combining schedule features
The schedule features were built independently, and some pairs would be half-applied rather than wrong, so they are refused when the spec is validated, with a message naming both features:
| feature | refused together with |
|---|---|
power-driven steps (power_W_cm3 / power_W_per_g) | uncertainty, options.screen, options.fission, pathways, schedule library overrides, wall_loading_MW_m2 on the same step |
schedule partition | pathways, schedule library overrides, options.mode: "trace" |
schedule library overrides | uncertainty, options.gas, self_shielding, damage, fission_yields.files, options.rate_scale, power-driven steps, kerma, partition, options.fission, cross-section overrides, pathways, spectrum.rebin on a step spectrum, decay-only runs |
wall_loading_MW_m2, spectrum.rebin, half-life overrides and fission_yields.spontaneous
combine with all of these. A power step may carry a partition.
Photon options
The entire photon object is optional. Without a response file, ACTINV still emits evaluated line/multigroup photon
sources and energy-closure diagnostics, but dose fields are null.
| field | meaning | default |
|---|---|---|
group_structure | fispact-24, steiner-22, or custom with group_boundaries_eV. | fispact-24 |
group_boundaries_eV | Finite, nonnegative, strictly increasing photon boundaries. | none |
response | External actinv-photon-response-1 JSON and mandatory SHA-256 declaration. | none |
build_up_factor | Semi-infinite-slab screening factor B. | 2 |
gamma_constant_cutoff_eV | Lower energy cutoff for specific gamma constants. | 20,000 eV |
point_source | Optional point-source dose, the FISPACT-II DOSE 2 analog; see below. | none |
bremsstrahlung | Optional bremsstrahlung component, the FISPACT-II BREMSSTRAHLUNG analog; see below. | none |
missing_spectra | "report" or "estimate": what to do with a nuclide that has a mean EM energy and no photon spectrum, the FISPACT-II SPEK analog; see below. | "report" |
exclude_xrays | Remove the decay records’ X-ray spectra (STYP 9) from the photon source, the FISPACT-II NOXRAY analog; see below. | false |
Build response data with scripts/build_photon_response.py; see the data-source record. A response must contain attenuation
curves for every material element to produce the contact-dose proxy.
Photon power in groups whose centroid is below the response’s lowest tabulated energy (1 keV for the shipped NIST
response) does not enter the proxy. It is reported as dose_response_subthreshold_power_W_g. The proxy is still given
when that power is at most 1e-4 of the step’s total photon power; a nuclide’s own proxy follows the same rule with
that nuclide’s power. The limit is fixed. Below 1 keV the air-to-material ratio is not tabulated and can move by up to
about an order of magnitude in light elements, so a 1e-4 share leaves the proxy low by at most about 1e-3. If the
share is larger, the proxy is null; use a response that reaches lower energies or a transport calculation. Groups
above the response’s highest energy, missing elements and power outside the group structure still make the proxy null.
Steiner 22-group structure
group_structure: "steiner-22" selects the 22-group “Steiner” gamma structure that FISPACT-II uses for GROUP 1.
The boundaries are the “22 Group” column of Table 6 of the FISPACT-II User Manual (UKAEA-R(18)001; Table 5 of
UKAEA-CCFE-RE(21)02): 0, 0.01, 0.10, 0.20, 0.40, 1.00, 1.50, then 0.5 MeV steps to 8.00, then 10.00, 12.00 and
14.00 MeV. Unlike the 24-group structure, which extends to 20 MeV here, the table stops at 14 MeV; photons above it are
counted in the overflow diagnostics and, as for any structure that omits source photons, make the contact and
point-source doses null. Combining steiner-22 with group_boundaries_eV is an error.
"photon": {
"group_structure": "steiner-22"
}
Point-source dose (photon.point_source)
Absent by default; when present every step’s photon_source gains point_source_dose. It is the FISPACT-II DOSE 2
analog: manual Eq. (63), D = C sum_i mu_a(E_i) exp(-mu(E_i) r) m_s S(E_i) / (4 pi r^2), where the step’s grouped
photon source is a point source and each group acts at its centroid energy, as in the contact dose. mu_a is the
response’s air mass energy-absorption coefficient, the same curve the contact dose uses. Eq. (63) has no build-up
factor, so build_up_factor plays no part.
| field | meaning | default |
|---|---|---|
distance_m | Source-to-detector distance in metres. Must be at least 0.3. | required |
air_attenuation | Apply the air transmission exp(-mu r) of Eq. (63). | true |
air_density_g_cm3 | Converts the air mass attenuation to a linear coefficient. | 1.20479e-3 (NIST dry air near sea level) |
FISPACT-II raises a dist below 0.3 m to 0.3 m and prints a message; ACTINV rejects it so the configured distance is
the one used. The source mass is material.mass_g, which defaults to 1 g, so the default matches FISPACT-II’s 1 g
convention; for another mass the dose scales linearly and gamma_air_dose_Sv_h_per_g gives the 1 g value. Air
transmission needs an air_mass_attenuation curve (NIST table 4 mu/rho) in the photon response: build it with
scripts/build_photon_response.py --air-attenuation. A response without that curve gives a null dose and an
unavailable_reason when air_attenuation is true; set it false to ask for the unattenuated dose. The dose is
null with a reason under the same conditions as the contact proxy: no response, power above the response’s top
energy or outside the group structure, or a sub-threshold share above 1e-4. It is also null while a nuclide has
decay-record gamma energy but no photon spectrum (unrepresented_gamma_power_W_g above zero in photon_source): that
power never reaches the groups, so the sum would be low by an unknown amount; it is added to excluded_power_W.
photon.missing_spectra: "estimate" places that power in the groups instead. A
dose is never reported for a non-finite or non-positive distance, mass or air density.
point_source, bremsstrahlung, missing_spectra: "estimate" and exclude_xrays need the photon source, which is
built only when options.outputs is absent or contains photons or dose. A specification that sets any of them with
an options.outputs list lacking both is rejected.
The fragment below belongs inside a complete problem; it is not a standalone input.
"photon": {
"point_source": {"distance_m": 1.0, "air_attenuation": false}
}
Bremsstrahlung (photon.bremsstrahlung)
Absent by default. nuclides lists canonical nuclide names (Cl36, Ar42, K42), as FISPACT-II’s
BREMSSTRAHLUNG keyword does; duplicates, elements and non-canonical spellings are errors. Each listed nuclide with
positive activity at a step is treated as emitting f beta-minus electrons per decay, each at its mean beta energy
E0. Manual Eqs. (65)-(67) then give, per electron and group [E_i, E_i+1] (keV, a = 2.76e-6 per keV), aZ[E0 ln(E_i+1/E_i) - (E_i+1 - E_i)] photons when E0 >= E_i+1, aZ[E0 ln(E0/E_i) - (E0 - E_i)] when E_i < E0 < E_i+1, and none when
E0 <= E_i, carrying the bin-midpoint energy (E_i + E_i+1)/2, all multiplied by f. The same expressions are
applied to the continuous beta spectrum through its mean energy, as the manual does. The result is a separate photon_source.bremsstrahlung
block with its own groups, per-nuclide groups, contact dose (the B/2 mu_a/mu_m slab formula, in Gy/h) and, when
point_source is set, point-source dose. It is never added to the decay-photon groups, powers or dose proxies; add
the two doses yourself if you want the total.
Inputs are never inferred. The decay record’s beta-minus (STYP 1) spectrum gives ER, the average beta-minus energy
per decay of the parent, which already includes the branching ratio. f is the summed branching ratio of the decay
modes whose RTYP carries a beta-minus electron (the digit 1 in its decimal spelling: 1.0, or 1.5 for beta-minus followed
by neutron emission; RTYP 10 does not count), and E0 = ER / f is the mean energy of one electron. Cu-64 (38.5 %
beta-minus) therefore uses 0.385 electrons of 190.7 keV, not one electron of 73.4 keV; a pure beta-minus emitter has
f = 1 and E0 = ER. Each nuclide reports electrons_per_decay and mean_beta_energy_eV. The light-particle mean
energy, which also counts conversion and Auger electrons, is not substituted. Z is the atom-fraction
mean atomic number of the declared material (Eq. 68; the manual says atom fractions even though mass fractions are
used elsewhere), taken from the initial composition. A nuclide that lacks ER or has no beta-minus decay mode (f of
zero), or any nuclide when Z is unavailable
(a material element without natural-isotope data), is listed in missing_inputs with the missing input, contributes
nothing, and sets inputs_complete to false; the totals then cover only the nuclides that were evaluated. Listed
nuclides without activity appear in requested_nuclides_without_activity.
Approximations: this is the manual’s thin approximation, not electron transport. Eq. (66) diverges in a group whose
lower edge is 0 eV, such as the first group of both built-in structures; the manual does not say how FISPACT-II
treats it, so ACTINV leaves that group empty and reports the exact energy the model places there as
zero_lower_edge_group_power_W_g. The block also reports how complete the grouped photons are, against the manual’s
analytic emitted energy a Z E0^2 / 2 per electron (Eq. 65 integrated over energy):
zero_lower_edge_energy_fraction: the share of that energy in the zero-lower-edge group, which the grouped photons lack. For a first edge of 10 keV it is 19 % atE0 = 100 keV, 8 % at 250 keV and 4 % at 500 keV. The contact proxy absorbs some of this, but the point-source dose does not, so treat it as a lower bound when the fraction is large.energy_closure: the energy placed in the groups plus the zero-edge energy, over the same analytic total. Eq. (67) gives every photon of a group the bin-midpoint energy, as FISPACT-II does, and ACTINV keeps that rule. A group holding many low-energy photons is therefore over-credited and the closure is above 1 (about 1.6 forE0 = 120 keVwith 10, 100 and 200 keV edges), while photons beyond the last group edge make it fall below 1. The rule is a documented approximation, not a measurement of the emitted energy.
Both are null when no nuclide was evaluated. FISPACT-II selects candidates by half-life and mean-energy criteria
(appendix C.7.5) for its PRINTLIB 4 listing; ACTINV applies no such filter and evaluates exactly the nuclides you
list.
The fragment below belongs inside a complete problem; it is not a standalone input.
"photon": {
"bremsstrahlung": {"nuclides": ["Cl36", "K42"]}
}
Nuclides without a photon spectrum (photon.missing_spectra)
"report" is the default. A nuclide whose decay record gives a mean electromagnetic energy E_em but no gamma or
X-ray spectrum (STYP 0 or 9) adds its power to unrepresented_gamma_power_W_g, and the point-source dose stays null.
"estimate" is the FISPACT-II SPEK analog. Each such nuclide gets a photon-number spectrum
n(E) = C exp(-a E / E_max) on (0, E_max], with a = 14 and C set so the spectrum’s energy is E_em. The
spectrum is integrated exactly into every photon group (the closed form of the exponential integral, not a midpoint
rule) and added to the step source. Its power moves from unrepresented_gamma_power_W_g to
estimated_gamma_power_W_g. E_max follows the decay mode with the largest summed branching ratio, using the first
RTYP digit (RTYP 10, unknown origin, is “other”):
| dominant mode | E_max |
|---|---|
| beta-minus (1) | twice the mean light-particle energy per decay (MT=457 index 0); 5 MeV when that is not positive |
| beta-plus or electron capture (2) | 5 MeV |
| isomeric transition (3) | E_em |
| any other mode, or no mode | 5 MeV |
A tie goes to the mode earlier in that table. Beyond the manual’s rule, E_max is also capped by the largest Q-value
among the nuclide’s modes with positive branching, when one is positive, so no estimated photon carries more energy
than the decay releases. Photons above the top of the group structure are counted in the overflow diagnostics, as for
an evaluated spectrum.
The estimate is a model. Each dose ACTINV computes from the grouped source is linear in group power, so a nuclide of
power P contributes between P times the smallest and P times the largest dose per unit power over the energy
intervals of the groups whose lower edge is below the nuclide’s energy cap (its Q-value cap, else the top of the group
structure), each interval clipped to the cap. The dose model places each group’s power at the group’s centroid energy.
Whatever the spectrum inside a group, that centroid lies in the group’s interval, so the model’s dose per unit power is
its value at some energy in the union of the intervals. The bounds are the exact extrema of that value over the union,
not samples: the intervals are split at every knot of the response curves, where the log-log curves are power laws. For
the contact proxy the air-to-material ratio is log-concave on each piece, so the extrema are at the ends or at one
stationary point found by bisection. For the point-source dose the value is A E^q exp(-c E^p), with extrema at the
ends or at E* = (q / (c p))^(1/p). An energy below the response’s lowest tabulated energy gives no dose, as in the
model, so it enters as zero; with such energies in range the lower bound is zero. The bounds hold for any spectrum that
conserves the nuclide’s power below the cap and contain the estimate by construction. If an interval reaches past the
response’s top energy, the range is null. actinv inspect decay --estimated-spectrum lists each nuclide’s intervals
as allowed_intervals_eV.
Each step’s photon_source gains:
estimated_gamma_power_W_g: the power of the estimated nuclides;estimated_spectra:model,exponent_a,contact_gamma_air_dose_proxy_Gy_hand, withpoint_source,point_source_gamma_air_dose_Sv_h, each withrepresented_only(evaluated spectra alone, as"report"gives it),estimate,lower,upper,estimated_shareandunavailable_reason; andby_nuclide, one entry per estimated nuclide withdecay_mode,e_max_manual_eV,e_max_eV,q_cap_eV,e_cap_eV,photons_per_decay,power_W_g, itsgroups, andcontact_gamma_air_dose_proxy_Gy_handpoint_source_gamma_air_dose_Sv_has{estimate, lower, upper, share_of_step_estimate}.
The step’s own contact_gamma_air_dose_proxy_Gy_h stays the value from evaluated spectra; the estimate and bounds are
in estimated_spectra. The step’s groups, source_power_W_g and photon rates include the estimated nuclides.
point_source_dose.gamma_air_dose_Sv_h (and its per-gram value) is defined as the estimate of
estimated_spectra.point_source_gamma_air_dose_Sv_h: the dose of the evaluated nuclides’ groups plus each estimated
nuclide’s own sum over its groups at their centroids. It is not one dose of the combined step groups, where estimated
and evaluated photons would share a group centroid. It is given instead of withheld, and is withheld, with the reason,
when that estimate is null. Its range is in the same block. A range is null for the same reasons as a dose: no response,
power outside the response or the group structure, or a sub-threshold share above 1e-4. The estimates are not
evaluated data: actinv inspect decay DECAY_PATH NUCLIDE --estimated-spectrum prints the estimate beside the
evaluated grouped spectrum.
X-ray exclusion (photon.exclude_xrays)
false by default. With true, the STYP 9 content of every nuclide is removed from the photon source after the
nuclide’s evaluated spectrum has been scaled to its E_em, as FISPACT-II’s NOXRAY does. The scale is the same one
the source uses without the option, so the remaining gamma lines keep their power. The removed power is reported as
excluded_xray_power_W_g in photon_source and, per nuclide, in by_nuclide; it is not part of
source_power_W_g and is not counted as unrepresented. A nuclide whose only photon content is X-rays contributes no
photons. Heat, activity and inventory are not affected.
The fragment below belongs inside a complete problem; it is not a standalone input.
"photon": {
"missing_spectra": "estimate",
"exclude_xrays": true
}
Options and result
mode is auto, trace, or coupled. cram_order is 16 (default) or 48; an uncertainty run evaluates the
other order as its separately reported numerical-method comparison. For each initial nuclide, auto computes the
base-spectrum reaction-loss
optical depth tau = loss_rate * sum(dt * flux_multiplier) and burn-up fraction -expm1(-tau); it selects trace
only when the largest fraction is strictly below 1e-6. The controlling nuclide, optical depth and fraction are
ledgered. Explicitly requested modes are always honored. prune is rate, reach, or none: reach keeps every
nuclide reachable from the material; rate (the default) also drops nuclides whose proven population bound over the
whole schedule is below bmin_atoms_per_g (default 1e-8), and the ledger’s rate_pruning block bounds what that
can change in total activity and heat. The outputs list
controls optional pathway and photon/dose calculations; the core inventory/activity/heat diagnostics remain in each
result step.
The ordered schedule is the pulse representation: every positive flux multiplier scales all base projectile rates,
and zero is an exact decay-only gap. Results are emitted after every segment. Each step records the current multiplier
as flux, cumulative elapsed t_s, cumulative multiplier-weighted exposure flux_weighted_time_s, and physical
fluence_n_cm2 (base total flux times weighted exposure). Scientific notation in a duration, such as 1e-8 s, is
accepted as a number rather than mistaken for a unit suffix.
Any step may also carry its own spectrum — the same shape as the base spectrum — replacing it for that step’s
duration while flux still scales the step’s total. This expresses pulsed or multi-field irradiations where the
spectrum shape itself changes between segments (for example fusion pulses at different field positions or a spallation
pulse inside a thermal field). A step spectrum must share the base spectrum’s structure and group count; an override
identical to the base deduplicates to it. The physical fluence sums each step’s own spectrum total times its
multiplier-weighted duration, and the schedule ledger reports how many steps declared overrides as step_spectra.
Multi-spectrum schedules always collapse on the groupwise library rows (never the pre-collapsed artifact). Combined
with uncertainty, the MF=33 collapse expands to one parameter per (spectrum, library row): each step’s tangent
directions are the rows collapsed under its own spectrum, decay-constant directions stay spectrum-independent, and
the propagated covariance carries the cross-spectrum blocks φ_sᵀ C φ_s' so a single physical draw propagates
through every step’s collapse. Each sensitivity parameter reports its spectrum index (0 = base).
Any step may also declare an optional library override (and, when that library is for a different projectile than
the spec’s, the matching projectile). The override is sticky: the step and every later step collapse their reaction
rates from the new library until a step names another library, or names the spec’s own library again to return to
it. The step that switches must carry its own spectrum in the new library’s group structure (fispact-709 for a
neutron library, fispact-162 for any other projectile, or custom with boundaries equal to the library’s); later
steps on that library keep it as their default spectrum, and may replace it for a single step with their own. A
projectile without a library is rejected. Each overriding library is verified like the base library (hashes,
index projectile, group structure, and temperature: a neutron library must match options.temperature_K, any other
projectile’s index must say 0 K), and its path joins the prepared-data fingerprint.
A fragment that irradiates under the base library, then switches to a second neutron library with its own spectrum
(here on custom boundaries equal to that library’s) and cools:
"schedule": [
{"dt": "300 s", "flux": 1.0},
{"dt": "1 h", "flux": 1.0,
"library": {"path": "tendl-2025-neutron-high.npz"},
"spectrum": {"structure": "custom", "boundaries_eV": [1.0e-5, 1.0, 1.0e6, 2.0e7],
"flux_per_group": [1.0e9, 5.0e9, 1.0e9]}},
{"dt": "1 d", "flux": 0.0}
]
A fragment that switches to a proton library, which needs the matching projectile on the switching step:
"schedule": [
{"dt": "300 s", "flux": 1.0},
{"dt": "1 h", "flux": 1.0,
"library": {"path": "tendl-2025-proton-162g.npz"},
"projectile": "proton",
"spectrum": {"structure": "custom", "boundaries_eV": [1.0e5, 1.0e6, 1.0e7, 1.0e8],
"flux_per_group": [1.0e8, 5.0e8, 1.0e8]}},
{"dt": "1 d", "flux": 0.0}
]
All libraries share the one decay chain, so the state vector is the same through a switch: the inventory at the end
of one step is the initial inventory of the next, and only the collapsed rate triplets change. A product that the
decay chain does not know leaks exactly as in a single-library run; each overriding library’s unmapped products,
products without decay data, isomer fallbacks and absent targets are listed under ledger.step_libraries, together
with the steps it served, its fluence and material_nuclides_without_rows (initial-material nuclides with no row in
that library: they do not react on the steps it serves), and the library and index hashes appear under
certificate.inputs.step_libraries. The cumulative fluence_* fields add every step’s own spectrum total whatever
its projectile; the per-library fluence is the one to read across a switch. Pathway attribution covers the base
library only and is suppressed (named in ledger.step_libraries.pathways_suppressed). Overrides cannot be combined
with uncertainty, options.gas, self_shielding, damage, fission_yields or options.rate_scale (each is built
on one library’s rows), nor with power-driven steps, kerma, partition, options.fission, cross-section overrides
or the full pathways analysis (each reads the base library’s rates, groups or per-step matrix), with mesh mode, or
inside a study; the spec is refused rather than half-applied.
Any step may also declare optional feed and removal maps. feed entries are explicit nuclides
(Co60, Ta180m1) with constant rates in atoms s⁻¹ g⁻¹, applied during the declaring step regardless of the
multiplier — a feed on a zero-flux cooling step still delivers atoms. removal entries are nuclides or element
symbols with first-order rates in s⁻¹; an element applies its rate to every tracked isotope and isomer of that
element, and a nuclide key removes only that state. Removed atoms accumulate in a dedicated sink reported as
removed_atoms_per_g, present only when a step declares removal. In trace mode the constant-reservoir material
nuclides are exempt from removal — the trace formulation holds them undepleted — unless the same nuclide is also
fed, in which case the fed atoms are carried in a real state and are removable. Every exempted reservoir nuclide
is named in the ledger under feed_removal.removal_reservoir_exempt, along with the per-nuclide totals fed and
the declared removals. Pathway attribution covers production chains only and is suppressed when a schedule
declares feed or removal.
For non-neutron projectiles (proton, deuteron, triton, helion, alpha and gamma), steps expose the generic fluence_particles_cm2
and identify the projectile in the result, ledger, certificate and prepared/mesh compatibility records. Neutron
results retain their historical bytes and fluence_n_cm2 field when projectile is omitted.
Screening and perturbation options
options.screen accepts {"bmin_atoms_per_g": value} with a finite nonnegative value and requires prune: "rate". It applies the declared screening threshold and emits a screen certificate that widens heat.*, activity.total and activity:<nuclide> responses (their band edges, or the nominal value without a band) by the pruning bounds of the rate_pruning ledger block, which include the shortfall of kept nuclides. Other responses are not certified. Inspect that certificate and coverage before relying on a screened calculation.
The optional scale maps support explicit perturbations for sensitivity and sampling workflows:
| Field | Key | Value |
|---|---|---|
options.rate_scale | Activation-library row index as a string | Multiplicative collapsed-reaction-rate factor |
options.decay_scale | Explicit radioactive nuclide, such as Mn56 | Multiplicative decay-constant factor |
options.yield_scale | Explicit parent:product, such as U235:I135 | Multiplicative independent-yield factor |
Applied factors are recorded in the ledger. Absent or stable decay targets and absent yield pairs are named errors. Decay scaling changes decay edges and the corresponding activity, heat, photon, and dose responses consistently; yield uncertainties scale with their yields.
Build an activation library
The production builder is part of the actinv binary:
actinv build-library INPUT OUTPUT.npz \
--format auto --projectile auto --groups fispact-709 \
--temperature-K 293.6 --workers 4 --cache /data/actinv-cache
INPUT is one ENDF-6 evaluation or a directory. --format accepts auto, tendl or eaf; --projectile accepts
auto, neutron, proton, deuteron, triton, helion, alpha or gamma; --groups accepts any named structure under
Group structures (a neutron build takes fispact-709 or another neutron grid; the
charged-particle and gamma builds take fispact-162) or a custom boundary file. Neutron defaults are 709 groups and 293.6 K; the other projectiles’ defaults are 162
groups and 0 K (gamma, like the other non-neutron projectiles, refuses a nonzero temperature — TENDL does not carry
a Doppler-broadened gamma sublibrary). The adjacent <stem>_index.json records source hashes, normalized options,
group hash, builder fingerprint, target ledgers and the final NPZ hash. A content-addressed cache is optional and
revalidated before reuse.
Group structures
The named structures are FISPACT-II’s own standard grids. Each is vendored as a JSON file under
crates/actinv-data/data/fispact_<N>_groups.json whose source field names the ebins_<N> file of FISPACT-II’s
ebins.tar.bz2 and that file’s SHA-256; the boundaries are copied verbatim and are checked in the unit tests against
the published first, second, middle, penultimate and last values. Boundaries are stored ascending after loading.
| Name | Groups | Upper edge | Use |
|---|---|---|---|
fispact-66 (WIMS/LANL) | 66 | 25 MeV | neutron |
fispact-69 (WIMS) | 69 | 10 MeV | neutron |
fispact-100 (GAM-II) | 100 | 14.918 MeV | neutron |
fispact-172 (XMAS) | 172 | 19.6403 MeV | neutron |
fispact-175 (VITAMIN-J) | 175 | 19.6403 MeV | neutron |
fispact-211 (VITAMIN-J+) | 211 | 55 MeV | neutron |
fispact-315 (TRIPOLI) | 315 | 19.64 MeV | neutron |
fispact-351 (TRIPOLI+) | 351 | 55 MeV | neutron |
fispact-586 (CASMO) | 586 | 20 MeV | neutron |
fispact-616 (RED/LLNL) | 616 | 20 MeV | neutron |
fispact-709 (CCFE) | 709 | 1 GeV | neutron (default) |
fispact-1102 (UKAEA) | 1102 | 1 GeV | neutron |
fispact-162 (CCFE) | 162 | 1 GeV (5 keV floor) | proton, deuteron, triton, helion, alpha, gamma |
An xN suffix (fispact-1102x2) refines each group log-uniformly into N subgroups, as it does for 709. A spectrum
on any of these structures must supply exactly the structure’s group count, and its library must have been built on
the same named structure: the name, group count and boundary hash are all checked, and a flux on a different grid
must be rebinned to the library first or given as custom boundaries matching the library. Group edges above an evaluation’s
upper energy carry zero cross section, so a 20 MeV grid is the natural pairing for a 20 MeV evaluation and only the
709, 1102 and 162 grids reach the 200 MeV upper limit of the TENDL neutron evaluations and beyond.
High-energy spallation splice
build-library --spallation TABLE.json [--splice-energy-MeV MEV] is the counterpart of FISPACT-II’s
USESPALLATION: above a splice energy (default 200 MeV) the residual-production cross sections of a separate,
user-supplied high-energy library are merged into the activation library. Nothing is fetched or generated; the table
is the only source of the spliced values and ACTINV ships none.
The table is JSON with schema actinv-spallation-residuals-1 (unknown fields are rejected):
{
"schema": "actinv-spallation-residuals-1",
"description": "required free text naming the code, version and run that produced the data",
"projectile": "proton",
"boundaries_eV": [2.0e8, 2.4e8, 2.8e8, "...", 1.0e9],
"targets": [
{"za": 82208, "liso": 0, "channels": [
{"mt": 5,
"loss_barns": [0.9, 0.8, "..."],
"products": [{"zap": 80200, "lfs": 0, "sigma_barns": [0.002, 0.003, "..."]}]}
]}
]
}
boundaries_eVare ascending and must equal the library’s group boundaries from the effective splice energy to the top of the library (to1e-12relative), so each table group is exactly one library group. Everysigma_barnsandloss_barnsarray has one finite, nonnegative value per table group.- The splice energy snaps up to the nearest library boundary, so no group mixes two sources.
splice 200 MeVis exact onfispact-709andfispact-162; on the log-spacedfispact-1102it becomes 208.93 MeV. Both the requested and the effective energy are recorded. A splice at or below the lowest boundary, or leaving no group above it (an EAF-range 20 MeV grid), is an error. - A product is the row
(mt, zap, lfs, MF=10)of its target;loss_barns, if given, is the matching target-depletion row. An existing row with the same key has its spliced groups replaced; a new row is appended after the target’s rows with zero cross section below the splice. Rows the table does not name, and every group below the splice, keep their values bit for bit. Spliced channels leave the other MTs of the same target untouched, so an evaluation that already tabulates overlapping reactions above the splice counts them as well; as in FISPACT-II, the user chooses the splice energy and the table’s content. - Use an MT that carries no gas-production accounting (MT 5 is conventional); a channel whose MT is in the
hydrogen/helium table also receives its ejectile counts under
options.gas. - Table targets absent from the library are skipped and listed. The table’s
projectilemust equal the library’s.
The index gains a spallation block (omitted without the option, leaving the index unchanged) with the table path
and SHA-256, its description, the requested and effective splice energies, the first spliced group, the rows
replaced and added in total and per target, and the skipped targets. Each affected target’s ledger carries a line with
the same counts. Library rows that the table does not replace keep their values even when they are nonzero at or
above the splice (a production row of the library has a different lmf from the table’s MF=10 row, so the table’s row
is appended beside it and the production is counted twice); the block lists them as
untouched_rows_nonzero_in_spliced_groups (a count and the first 50 rows), and build-library warns on standard
error when the count is not zero.
Triton and helion projectiles
--projectile triton and --projectile helion build from ENDF-6 evaluations whose incident-particle record is
NSUB 10030 (triton, projectile ZA (1, 3)) or NSUB 20030 (He-3, ZA (2, 3)), on the same CCFE-162 structure and the
same MF=3/6/8/10 families as the other charged projectiles. The projectile is read from the evaluation, not from a file
name, and AWI must be within 10% of mass number 3. Residual arithmetic is target + projectile − emitted particles
(for example Fe-56 + t gives Co-59 for MT=102, Fe-56 + He-3 gives Ni-59), and the MT=5 residual production of charged
projectiles uses the same MF=6/MF=8/MF=10 path as proton, deuteron and alpha. ACTINV ships no triton or helion
library: the TENDL t and h sublibraries are the intended source, but none is in the standard catalog, so build the
library yourself and check its coverage in the target ledgers.
Gamma (photonuclear) projectile
--projectile gamma builds from the TENDL g sublibrary (public, TENDL-2025): NSUB 0, projectile ZA (0, 0), AWI
required to be exactly 0.0. Residual arithmetic is target + photon − emitted particles on the CCFE-162 group
structure, the same structure and MF=3/6/8/10 families the proton/deuteron/alpha path already uses. Some gamma MTs
(for example 50, 51 and 91 — single-neutron production to the ground state, a discrete level, or the continuum) carry
MF=3/6 cross sections without an MF=8 product declaration; the builder resolves their ground-state residual from the
ENDF MT reaction definition instead of dropping the row, and records every such resolution in the target ledger.
Single-neutron production is counted once. When MT=4 carries its own MF=8 state-resolved declaration
(TENDL-2025 Ta-181 and W-186, for example), MT=4 is used and every MT50–91 detail section is skipped. When MT=4 has no
MF=8 of its own and MT50–91 detail is present, MT=4 is skipped and the detail sections carry the channel. Each skip is
recorded in the target ledger.
Photofission is recognized only as a total cross section: the MF=10 IZAP=−1 total-fission sentinel (TENDL-2025),
or, under a normalization profile such as --profile tendl, the TENDL-2017 encoding of the same quantity as a single
MF=10 IZAP=0 LFS=0 section with no MF=3 MT=18 (P98, recorded in the ledger). An evaluation that declares actual
photofission product yields under MT=18 fails closed, since photofission yields are out of scope for v1. TENDL-2017
gamma files also contain MF=3 tables that start above the reaction threshold while the MF=10 states carry the ramp
from threshold. Under the default profile these fail closed on the emitted-state sum, or, where the state sum
stays within the standard zero-total envelope, are scaled to the zero total with a ledger record, so build TENDL-2017
gamma files with --profile tendl. Under --profile tendl the
builder applies the MF=3 threshold extension (P100): for each such MT it extends the MF=3 table below its first
energy E3 with the summed MF=10 states (ZAP ≥ 0), one point at each energy below E3 that a state tabulates, plus a
joining point at E3 carrying the states’ summed left limit, interpolated lin-lin. The extension applies only when
every state is lin-lin below E3; otherwise the MT is left unchanged and the ledger says why. Each extension writes a
MT<n>: MF=3 threshold extension: … ledger line, and remaining per-group differences are reconciled and recorded as
state_sum_normalized. Without the extension the threshold group’s production would be scaled to the zero MF=3
total and lost. No TENDL-2025 gamma file triggers it.
Pass --decay (and --decay-fallback) when building a gamma library: isomer labels then resolve against the decay
sublibrary the runtime uses. Without decay data the builder falls back to its target catalog and label ranks.
Gamma activation libraries are not yet published through actinv data fetch — that is a separate release decision.
Build a damage-energy table
actinv build-damage INPUT OUTPUT.json \
--projectile auto --groups fispact-709 --temperature-K 293.6 --cache /data/actinv-damage-cache
INPUT is one ENDF-6 evaluation or a directory. Every MF=3/MT=444 damage-energy production section is collapsed
through the same parser, temperature check, and lethargy integration as build-library; --projectile, --groups,
--temperature-K, and --cache share that command’s semantics. The result is a strict actinv-damage-table-1
document: group-structure label and boundaries, per-file SHA-256 provenance, a targets map of canonical nuclide
rows, and an uncovered list naming every evaluation without MT=444 — absent sections are reported, never
zero-filled. The output file’s SHA-256 is printed on success for pinning into damage.table.
Build an MF=33 covariance sidecar
actinv build-covariance INPUT ACTIVATION.npz OUTPUT.cov.npz \
--workers 4 --cache /data/actinv-cov-cache
INPUT must be the neutron ENDF corpus from which ACTIVATION.npz was built. Source hashes, filenames, MAT,
ZA/LISO target identities and the adjacent activation index must all agree. The builder supports strict MF=33 NI
forms LB=0–6, 8 and 9; NC components, foreign or cross-sublibrary references, lumped MTL, malformed dimensions and
unknown forms fail with MAT/MF/MT context. Its separate <stem>_index.json records the activation identities, source
manifest, representation inventory, builder fingerprint and final sidecar hash. Per-source checkpoints are
content-addressed and revalidated; worker count and cache reuse do not change canonical bytes. Raw evaluations,
checkpoints and generated sidecars remain external data and must not be committed.
--mf33-from DIR takes the covariances of an input from the file of the same name in DIR, when there is one; the
input itself still binds the target to the activation library by its SHA-256, and nothing but MF=33 is read from the
other file. The index records that file’s SHA-256 as the target’s mf33_source_sha256 and includes it in the source
manifest. A file in DIR without an input of the same name, without MF=33, or with an MF=33 material that is not
the input’s target is refused.
When photons are requested (or outputs is omitted), steps[].photon_source contains:
- evaluated discrete line rates and per-nuclide evaluated/source yields;
- group photon rates, energy centroids and emitted powers, per gram and for
material.mass_g; - raw energy moments, explicit
E_EMnormalization factors and represented-power fraction; - specific gamma constants in
Gy m2/(Bq s)andmGy m2/(GBq h)when a response is supplied; contact_gamma_air_dose_proxy_Gy_h, response coverage, and explicit ungrouped/unrepresented power;dose_response_subthreshold_power_W_g, only when non-zero: photon power below the response’s lowest energy, omitted from the proxy.point_source_dose, only withphoton.point_source: distance, mass, dose in Sv/h and per gram, excluded power and the reason a dose isnull; eachby_nuclideentry gainspoint_source_gamma_air_dose_Sv_h;bremsstrahlung, only withphoton.bremsstrahlung: the separate component described above;estimated_gamma_power_W_gandestimated_spectra, only withphoton.missing_spectra: "estimate": the estimated nuclides and the estimate and bounds of each dose, described above;excluded_xray_power_W_g, only withphoton.exclude_xrays; eachby_nuclideentry gains the same key.
Use one-based result step numbers for transport export:
actinv export-openmc result.json 2 source.py
actinv export-mcnp result.json 2 source.sdef
Both exports use the photon-group centroids and total photons/s. The point at the origin is a placeholder, not a spatial activation model. An export fails if custom boundaries omitted any source photons.
For mesh results, actinv export-openmc-mesh mesh_result.ndjson STEP source.py writes a distributed spatial
source: one openmc.IndependentSource per mesh cell, sampled uniformly inside the cell’s recorded bounds_cm
(openmc.stats.Box), with a discrete photon-energy distribution taken from the cell’s exported group centroids and
probabilities, and the cell’s absolute photon rate as strength. The fragment ends with TOTAL_PHOTONS_S, the
absolute sum over all cells. Cells whose photon source is zero contribute no entry; a cell with photons but missing
geometry, a missing step, an unrequested photon output, or an inconsistent group total fails the export closed.
Flux interchange (actinv-flux-1)
Transport spectra are canonicalized before activation. The format is newline-delimited JSON: exactly one header,
the declared number of ordered cell records, and one closing footer. A cell value is integrated flux in
n cm^-2 s^-1 (neutron) or particles cm^-2 s^-1 (photon and the other non-neutron projectiles) for that energy
group—not flux density per eV or lethargy. Every ID is unique and every ordinal begins at zero and increases by one.
The strict reader rejects blank, malformed, missing, duplicate, extra and trailing records, invalid totals,
nonfinite/negative values and inconsistent geometry.
actinv import-flux openmc statepoint.h5 flux.ndjson \
--tally 7 --source-rate 1.0e15 --energy-floor-eV 1.0e-5 --window-rows 16384
actinv import-flux meshtal meshtal flux.ndjson \
--tally 24 --source-rate 1.0e15 --energy-floor-eV 1.0e-5
actinv import-flux mctal mctal flux.ndjson \
--tally 4 --source-rate 1.0e15 --energy-floor-eV 1.0e-5
actinv import-flux fispact fluxes flux.ndjson --groups descending-boundaries.json
The OpenMC and MCNP source rate is mandatory and positive. It converts a per-source-particle tally to physical flux;
FISPACT fluxes values are already absolute and are not rescaled. If the source grid starts at zero, an explicit
positive --energy-floor-eV below the next boundary is required and both the original zero and replacement are kept
in provenance. Every importer hashes and re-stats its input and publishes the canonical file by sibling temporary-file
rename only after the footer closes.
Supported subsets are deliberately narrow:
- OpenMC statepoint major 18, one selected
flux/total/tracklength tally with exactly one 3D Cartesian regular or rectilinearMeshFilterand oneEnergyFilter, in either order, plus an optional single-binParticleFilter(neutronorphoton; more than one particle bin is refused, since a multi-particle tally mixes flux across particle types into one row). A tally with noParticleFilteris legacy behaviour and is accepted only when the mesh spec’s projectile isneutron; a photonParticleFilterwritesparticles cm^-2 s^-1flux and aparticlemetadata field, and a mesh run whose projectile disagrees with the imported flux’s particle units fails before solving. Importing an unfiltered or neutron-filtered tally writes byte-identical output to the pre-P94 importer; - MCNP traditional rectangular XYZ neutron FMESH
meshtalcolumn output with energy rows and optional checked totals; - MCNP energy-binned F4:N
mctalwith one cell-ID F dimension, singleton remaining dimensions and optional checked total energy bins; - standard FISPACT-II
fluxes: N descending group values, first-wall loading, then its identifying title, against an explicitly supplied descending group-boundary JSON file.
Structured meshes (OpenMC, meshtal) above 100,000,000 cells are refused before any allocation is sized by the declared dimensions.
Other scores, particles, estimators, filters, dimensions, mesh shapes, multipliers, responses, cumulative/time bins or file variants produce a named error rather than a guessed interpretation.
Independent mesh specification (actinv-mesh-spec-1)
Mesh mode replaces the ordinary spectrum with a mandatory canonical-file path and SHA-256. All cells receive the
same explicit library, decay data, optional fission-yield files, material, schedule, options, photon configuration,
uncertainty configuration, and radiological configuration, and solve independently. Covariance and radiological
data are verified and prepared once; workers borrow them rather than re-reading or cloning them per cell.
{
"spec": "actinv-mesh-spec-1",
"title": "iron activation mesh",
"projectile": "neutron",
"library": {
"path": "/data/actinv_tendl2025_n_709g.npz",
"sha256": "64 hexadecimal digits"
},
"decay": {"primary": "/data/endf-b-viii-0_decay.dat"},
"material": {
"mass_g": 1.0,
"basis": "wt_percent",
"composition": {"Fe": 100.0}
},
"flux": {
"path": "flux.ndjson",
"sha256": "64 hexadecimal digits"
},
"schedule": [
{"dt": "5 min", "flux": 1.0},
{"dt": "1 h", "flux": 0.0}
],
"options": {
"mode": "auto",
"prune": "rate",
"bmin_atoms_per_g": 1e-8,
"temperature_K": 293.6
},
"chunk_cells": 64,
"threads": 4,
"group_workloads": true,
"cell_result_fields": ["steps", "pruned_states", "total_states", "certificate"],
"memory_limit_bytes": 4000000000,
"resume": false
}
chunk_cells defaults to 64 and is bounded to 1–65,536. threads defaults to 1 and is bounded to 1–256. Execute it
with actinv mesh mesh.json mesh-result.ndjson. Immutable activation/decay/response data are verified, decompressed
and prepared once. Canonical cells are read a chunk at a time, restored to input order after Rayon execution, and
written as actinv-mesh-result-1 header/cell/footer records.
group_workloads defaults to true: cells whose rebinned activation-group flux vectors are byte-identical share one
solved result (keyed by the SHA-256 of the f64 little-endian group bytes, memo bounded to 256 distinct workloads and
512 MiB of memoized result bytes).
Reuse changes only scheduling — every cell record is bit-identical to a group_workloads: false run, and the
footer records the count as cells_served_from_reuse. cell_result_fields keeps only the named top-level
RunResult fields in each cell record; absent means the complete record, and an unknown name is rejected at
validation.
An entry can also be dotted, steps.<field>[.<key>...] (P90), to keep only part of each step instead of the
whole steps array: <field> must be a StepOut field (e.g. heat_W_per_g, photon_source), and further
segments descend through JSON objects — steps.photon_source.groups keeps only photon_source.groups (with
every key of each group entry, since the path ends there), dropping photon_source’s other fields and every
other step field. steps and a steps.<field> entry cannot both appear. A path that reaches an array or a
scalar with segments still to consume is rejected at validation, as is a key that does not exist at that point
in StepOut’s shape — except inside a nuclide- or response-keyed map (activity_Bq_per_g, uncertainty.responses,
damage.elements), which can only be selected whole, not narrowed to one dynamic key. A selected field that is
absent in a given step (e.g. photon_source with no photon output) is left out of that step’s object, exactly as
in the complete record; every emitted step object otherwise holds step plus the selected paths. With any dotted
entry present, the cell text is assembled directly from RunResult/StepOut fields rather than by serializing
and then pruning the whole result, so a large unselected field (e.g. the per-nuclide inventory) is never built.
memory_limit_bytes is a post-hoc guard: after each completed chunk the process peak RSS
(/proc/self/status VmHWM) is compared to the limit and the run aborts with a named error carrying both numbers.
It is refused at validation on platforms without that accounting (it could never fire there). Without resume
the output is written atomically, so a tripped guard keeps no completed cells; pair it with resume: true.
resume: true makes the output file itself the checkpoint. The run writes directly (not via atomic rename); on
start it validates any existing file: the header must equal byte-for-byte the header a fresh run would emit —
including the spec_fingerprint_sha256 field, the canonical-JSON SHA-256 of the spec with resume, threads,
chunk_cells and memory_limit_bytes removed. Complete in-order cell records stand; a torn final line is
truncated; a mid-file corrupt or out-of-order record is a named error; a file whose footer is already present
returns its summary without re-solving. Only unfinished cells are re-executed, and a completed resume is
byte-identical to an uninterrupted run except the footer’s timing fields. A resumed run reproduces the
uninterrupted cells_served_from_reuse count because completed prefix cells seed the grouping memo.
Matching source/library boundaries use a bit-identical copy path. Other positive grids use FISPACT’s default equal
flux per unit lethargy rule. Every cell result includes source_total, rebinned destination_total, underflow,
overflow, closure and method; energy outside the library is never folded into an edge group or renormalized away.
The ordinary run result is nested without per-cell timing. Only footer wall_time_s and cells_per_s vary with
scheduling; header and ordered cell bytes are deterministic across chunk and thread counts. The header certificate
binds the declared/computed canonical hash and its embedded transport/auxiliary hashes. Any cell or footer failure
names the failing premise and leaves no final result file.
Numerical floor diagnostic
numerical_floor_atoms_per_g retains its existing serialized name and value
alpha0 * max(N) for compatibility. It is a CRAM asymptotic diagnostic scale,
not a bound on total numerical error, factorization/solve roundoff or each
reported population’s accuracy. heat_bound_from_below_floor_W_per_g is the
computed heat subtotal of the reported below-scale populations, not a bound on
all numerical dose or heat error. The ledger marks
numerical_floor.is_total_numerical_error_bound = false explicitly.
CRAM shifted-system solves use bounded iterative refinement against the original matrix, with compensated residual accumulation and fused-product error terms. This applies to scalar, batched and tangent solves; it does not replace physical inputs, filter small positive populations or establish a universal forward-error bound. Independent numerical checks remain necessary for the claimed domain.