Nuclear data

Nuclide identifiers, name dialects, and data sources in Nucleide.

Nucleide carries a small, self-contained set of nuclear reference data and a canonical nuclide identifier that can be translated into the naming dialects used by MCNP, Serpent, FLUKA, and other codes.

Canonical nuclide identifier

Every nuclide is stored as a single u32 called the nucid:

where:

• $Z$ is the atomic number,
• $A$ is the mass number,
• $S$ is the metastable state index ($0$ = ground state).

Name dialects

Nucleide converts between several legacy code conventions.

ARMI database keys (nU235, MCC3) resolve through the same identifier for post-expansion mass fractions in the emission bridge and R2S snapshot adapter (Touran et al.)^touran-2017.

Data sources

Nucleide embeds nine reference tables at compile time and parses them lazily on first access.

Atomic masses

• Source: AME2020 atomic mass evaluation (Huang et al., Chinese Physics C 45, 030002/030003, 2021)^{huang-2021wang-2021}, plus ENDF/B-VIII.0 excitation energies for isomers (see below).
• Coverage: 3,557 ground-state nuclides with $Z \geq 1$, plus one row per ENDF/B-VIII.0 isomer tape (738 rows): $m = m_{\mathrm{ground}} + E^*/931.49410242\,\mathrm{u}$ with $E^*$ (in eV) from the tape’s File-1 MT451 ELIS record. Isomer tapes with unset (ELIS = 0) entries carry the ground-state mass; isomers without a tape fall back to the ground-state mass at lookup time. No NUBASE import: ENDF excitation energies only.
• File: crates/nuclei/src/data/ame2020.tsv.
• Units: unified atomic mass units (u).
• Generator path: ground rows are condensed from the AME2020 mass.mas20 table and carried verbatim on every --endf-decay8 run (read_ame_grounds in scripts/gen-nuclear-data.py); only isomer rows are re-appended, so grounds are never orphaned. The script has no AME2020 re-parse path: refresh grounds from mass.mas20, then re-run --endf-decay8 to re-append isomers.

Natural abundances

• Source: vendored isotopic compositions, expressed as fractions. No generator path in this repo emits the table (scripts/gen-nuclear-data.py only reads it for monoisotopic-element detection), so the exact transcription path is TO BE SOURCED. Values cross-check identical to the OpenMC NATURAL_ABUNDANCE tabulation (see validation/results.md: 289 isotopes, max abs diff 0.0).
• Coverage: 289 naturally occurring nuclides, including the isomer Ta-180m.
• File: crates/nuclei/src/data/natural_abundance.tsv.
• Units: fraction in $[0, 1]$.

Half-lives

• Source: ENDF/B-VIII.0 decay evaluations (IAEA / BNL-NNDC)^brown-2018.
• Coverage: 3,561 radionuclides; stable nuclides are absent.
• File: crates/nuclei/src/data/half_life.tsv.
• Units: seconds.
• Regeneration: T1/2 is the first value of each tape’s MF8/MT457 summary LIST record (ENDF-102 §8.4.1); stable (NST != 0) and zero-half-life tapes yield no rows. Regenerate with python3 scripts/gen-nuclear-data.py --endf-decay8 <dir> --out <dir> from zips/ENDF-B-VIII.0_decay.zip (--help pins the source URL and zip MD5); the writer reproduces the committed data rows byte-identically.

Decay branches

Per-branch daughters (decay_branches, table decay_branch_table) from the ENDF/B-VIII.0 decay sublibrary^brown-2018 (MF8/MT457 NDK records: RTYP decay-mode code, RFS daughter state flag, BR branching fraction):

• Source: ENDF/B-VIII.0 decay tapes (same checkout basis as the half-life table). RTYP digits apply in emission order (ENDF-102 §8.4; OpenMC decay.py digit table): beta- gives $Z+1$, EC/beta+ gives $Z-1$, alpha gives $Z-2$/$A-4$, IT is unchanged, and delayed neutrons/protons subtract the emitted nucleons. The mode token is the initial event.
• Coverage: 5,068 branches over 3,541 parents. Spontaneous-fission and fission-family branches are dropped (depletion matrices skip sf gains), so strong SF emitters sum to $1 - \mathrm{BR(SF)}$. Tapes with zero half-life or stable flags yield no rows, so effectively-stable entries stay absent, matching the half-life table’s stable-absent convention.
• File: crates/nuclei/src/data/decay_branches.tsv.
• Units: branching fractions in $[0, 1]$; modes are beta-, ec/beta+, alpha, IT, sf (parses only), n, p.
• Scope: evaluated branching data for chain building — never for spectroscopy or safety use.

See decay_branches in the Python API.

Fission yields

Fission product yields (fission_yields, table fission_yield_table) from the ENDF/B-VIII.0 neutron-induced (nfy) and spontaneous (sfy) fission-yield sublibraries^brown-2018 (MF8/MT454 independent and MF8/MT459 cumulative records; one row per (ZAFP, FPS, Y, dY) product per incident-energy set):

• Source: both sublibraries are unchanged carries of ENDF/B-VII.1 evaluations per the tapes’ README.txt — the England et al. ENDF-349 evaluations (EVAL-JUL89) except Pu-239 (Chadwick–Kawano, EVAL-NOV11). The Mattera–Sonzogni cumulative-yield correction is not applied; values are verbatim from the tapes, and dY = 0 is the no-uncertainty sentinel (it occurs exactly on the zero-yield rows of this sublibrary).
• Coverage: 151,490 rows over 36 parents and 122 incident-energy sets; the FPS isomeric-state flag maps to a GNDS _m{state} suffix with the same convention as the decay-branch RFS flag. Independent sets sum to ≈ 2.0 (two fragments per fission); cumulative sets add precursor decay-chain feed (summing far above 2).
• File: crates/nuclei/src/data/fission_yields.tsv.
• Units: yields as fractions (Y, dY); energies in eV (spontaneous sets use E = 0).
• Scope: screening-level chain data — the depletion matrix consumes the lowest-energy independent set (OpenMC get_default_fission_yields convention), and crates/depletion falls back to this library when a chain XML omits <neutron_fission_yields> for a fissionable parent.

See fission_yields/fission_yield in the Python API.

Simple cross sections

Approximate total microscopic cross sections (simple_xs in crates/nuclei/src/data.rs, table simple_xs_table), returned as (thermal, fast-14 MeV) pairs:

• Source: thermal (0.0253 eV) totals from NIST 2200 m/s bound scattering/absorption converted to free-atom totals (xs·(A/(A+1))² + xs_a); 14-MeV totals from ENDF/B-VII.1 MF3/MT1^{chadwick-2011}. ENDF File 3 alone cannot supply thermal values inside resonance ranges (it holds background only there), and resonance nuclides without a NIST row (Cs-137, Co-60, I-135, Xe-135) plus isomers are absent by construction.
• Coverage: 241 nuclides; anything else returns None.
• File: crates/nuclei/src/data/simple_xs.tsv.
• Units: barns.
• Scope: screening-level scoping only — never for transport or safety calculations; use an evaluated library instead.

See simple_xs in the Python API.

Neutron scattering lengths

Bound scattering lengths (scattering_length, table scattering_length_table), returned as (coherent, incoherent) pairs:

• Source: the NIST NCNR tabulation of Sears (1992)^sears-1992 and its update (complex absorbing lengths by real part; incoherent derived from the spin-incoherent cross section where the table gives only σ).
• Coverage: 267 nuclides (tabulated isotopes plus monoisotopic element attributions); anything else returns None.
• File: crates/nuclei/src/data/scattering_lengths.tsv.
• Units: femtometres.
• Note: the Python scattering_length accessor returns the coherent element only; use the table lookup for the full pair.

See scattering_length in the Python API.

Decay energies

Mean prompt recoverable energy per decay (decay_energy_mev, table decay_energy_table):

• Source: ENDF/B-VII.1 decay tapes^{chadwick-2011} (MF8/MT457 summary components, paired uncertainties skipped; delayed-neutron kinetic energy included, neutrinos never appear). Daughter gammas belong to the daughter row, so chain codes must sum members (Cs-137 prompt ≈ 0.179 MeV; the 662 keV line lives on Ba-137m).
• Coverage: 3,557 nuclides with decay-heat data (every ENDF/B-VII.1 decay tape with a nonzero summary, all isomers included); stable nuclides return None.
• File: crates/nuclei/src/data/decay_energy.tsv.
• Units: MeV per decay.
• Scope: decay-heat estimates only — never for spectroscopy, dose, or safety use.
• Basis note: this table stays on ENDF/B-VII.1 while the half-life and decay-branch tables use ENDF/B-VIII.0 (different sublibrary vintages).

See decay_energy in the Python API; composition-level heat lives under decay_heat in nucleide.material.

Dose factors

External-air/soil, ingestion, and inhalation factors (dose_factor, table dose_table):

• Source: the BSD-3 PyNE dbgen/dosefactors*.csv tables (93 rows each; proximate provenance HNF-SD-WM-TI-707 Rev.1^hnf-1999 with App. O of HNF-5636^hnf-5636; GENII/EPA/DOE are 3 parallel evaluations). +D (plus daughters) folds into the parent. Air is EPA-only: GENII/DOE air rows are -1 sentinels.
• Coverage: 93 folded nuclides × 4 pathways × 3 sources (1,116 rows); anything else returns None.
• File: crates/nuclei/src/data/dose_factors.tsv.
• Units: air mrem/h per Ci/m³, soil mrem/h per Ci/m² (15 cm slab), ingest/inhale mrem/pCi.
• Scope: screening-level dose-per-gram estimates only — not for safety decisions (upstream PyNE disclaimer).

See dose_factor in the Python API; composition-level dose lives under dose_per_g in nucleide.material (see dose_per_g in the Python API).

FGR 15 external-dosimetry coefficients

EPA Federal Guidance Report No. 15 (July 2025)^epa-fgr15 effective dose (rate) coefficients for external exposure — ground surface (3 mm), soil to 1/5/15 cm and infinite depth, air submersion, and water immersion — per reference-person age group (newborn through adult):

• Source: the official EPA coefficient zip (data file dated 2025-05-28), downloaded at runtime by nucleide.data.fetch_fgr15 and pinned to a SHA-256 hash; nothing from the EPA file is vendored, and a hash mismatch fails loudly (EPA may have revised the file).
• Coverage: the seven Table_4_*.DAT scenario tables, 1,252 nuclides each × 6 age columns. The 28-tissue Nuclide_Coefficients/ and monoenergetic-photon Mono_Coefficients/ members are out of scope (v1).
• Units: recorded verbatim from each table header — Sv m2/Bq s for the ground-surface table, Sv m3 per Bq s for the soil-volume and immersion tables.
• File: parsed at runtime by the fgr15 module of crates/nuclei/src/fgr15.rs from the cached zip (no vendored bytes).
• Scope: external exposure only, screening-level — not for safety decisions. FGR 15 complements dose_factor/dose_per_g: the HNF-5636 factors stay the screening default for composition-level material dose, and neither source silently takes precedence — compare units before combining.

See fgr15_dose_rate and load_fgr15_table in the Python API.

Derived quantities

Decay constant

From the half-life $t_{1/2}$:

Q-values from atomic masses

Nucleide computes Q-values using AME2020 atomic masses and the neutron mass constant:

Neutron radiative capture

Example: H-1$(n,\gamma)$ gives $Q \approx 2.2246\,\mathrm{MeV}$.

Alpha decay

with $m(^4\mathrm{He}) = 4.00260325413\,\mathrm{u}$.

Assumptions and limitations

• Isomer masses are tape-derived: isomers with their own ENDF/B-VIII.0 tape resolve to $m_{\mathrm{ground}} + E^*$; isomers without one fall back to the ground-state mass at lookup time.
• Q-values stay ground-state-only: the capture/alpha helpers combine tabulated atomic masses per the textbook formulas and reject metastable inputs; isomer-resolved Q-values would need excitation bookkeeping beyond this screening-level scope.
• Natural elements are unrepresentable: a bare symbol such as "U" cannot be stored as a NuclideId because $A \geq Z$ is required. Free-form input (241Pu, 40K, Ba-137m, Ir-192n, bare ZAIDs) is normalized by normalize_nuclide_name in crates/nuclei/src/dialects.rs, which tries symbol-first parsing before mass-first so N15 stays nitrogen-15 and 92235 stays a ZAID.
• Electron binding neglected: capture Q-values use neutral atomic masses but do not correct for electron binding differences.
• Branching data is ENDF, not ENSDF: decay modes and branching ratios come from the ENDF/B-VIII.0 decay sublibrary; detailed ENSDF decay schemes and radiation spectra remain out of scope.

Related work beyond Nucleide

Adjacent data capabilities found in PyNE and OpenMC that Nucleide does not embed:

• Decay schemes: PyNE derives decay modes, branching ratios, state energies, and radiation spectra from ENSDF; OpenMC parses full decay modes from ENDF files. Nucleide carries half-lives, ENDF/B-VIII.0 branching ratios, and mean prompt decay energies (MeV per decay from ENDF/B-VII.1 MF8/MT457, not ENSDF).
• Fission product yields: PyNE exposes WIMSD and NDS yield tables; OpenMC reads yields into depletion chains.
• Q-values and energy release: PyNE’s q_val and OpenMC’s FissionEnergyRelease go beyond the capture/alpha formulas here.
• Reaction and scattering data: Nucleide carries only screening-level totals (simple_xs) and bound scattering lengths; energy-dependent cross sections, thermal S(α,β), and scattering kernels live in evaluated libraries and in both codes but remain outside Nucleide’s scope.
• Natural elements: PyNE and OpenMC accept bare element symbols and compute atomic weights from abundances; Nucleide requires a mass number.
• Living references: NuDat 3 and the IAEA LiveChart track structure and decay data between ENDF releases.