Allow calculations without neutrons to skip neutron data entirely

[GuySten]

Description

Stacked on #64, a cross section cache fix for pre-existing bugs this work exposed, which is going upstream on its own. Review #64 first; the diff here is only the feature.

Photon and electron transport are driven entirely by per-element data, so a calculation in which no neutrons appear does not need neutron cross sections. OpenMC nevertheless requires a type="neutron" entry in cross_sections.xml for every nuclide in every material and then reads the corresponding HDF5 file, whether or not a neutron is ever transported.

That is not only wasteful. ENDF/B-VII.1 carries photoatomic data for every element through Z=100, but its neutron sublibrary has no evaluation for neon, ytterbium, osmium or platinum — so none of those four can appear in a photon calculation at all, even though every cross section such a calculation needs is sitting in the library. It fails in Python, at Material.add_element, before OpenMC starts:

ValueError: Unable to expand element Pt because the cross section library
provided does not contain any of the natural isotopes for that element.

Platinum is the one most likely to be missed: it is the encapsulation and the radiopaque marker of brachytherapy sources, and Yb-169 is itself a brachytherapy source isotope.

The photon transport step of an R2S calculation is the other motivating case: its source comes from the decay of activated materials, so it transports no neutrons of its own.

settings.run_mode = 'fixed source'
settings.photon_transport = True
settings.neutron_transport = False          # new
settings.source = openmc.IndependentSource(particle='photon')

With that, cross_sections.xml only has to list the photon data for the elements in the model.

How nuclide properties are obtained without a library

A new Nuclide constructor builds a nuclide from its name alone. Z, A and the metastable state are parsed from the name; the atomic weight ratio comes from the AME2020 masses already in the tree (added in openmc-dev#4129) rather than from a data file.

Elemental evaluations such as C0, which some libraries provide in place of the individual isotopes, are supported through a new ATOMIC_WEIGHT table of natural-abundance-weighted atomic masses. ENDF/B-VII.1 is one such library — it carries C0 rather than C12 and C13 — so a material carried over from a calculation that used it may well contain one. openmc.data.atomic_mass previously knew elemental masses for only six hardcoded elements; it now computes them for every element with naturally occurring isotopes, so the Python API can read back what the C++ side accepts.

Only canonical GNDS spellings are accepted. ParticleType also parses aliases like alpha, h1 and bare PDG numbers, and accepting those would make a model run only while neutron data was being skipped.

Densities may differ in the last few digits from a run that reads neutron data, since AME2020 and a library's tabulated atomic weight ratios are not bit-identical. For elemental evaluations the difference can reach a part in a thousand. The statepoint records neutron_transport so post-processing can tell which of the two a run's masses came from.

Expanding an element with no neutron data

Element.expand() decides which isotopes exist by reading cross_sections.xml, and refused outright when the library listed none for the element — the error above. But photon data is tabulated per element, so a library with no neutron data for an element is simply silent about its isotopes, and natural abundance is the whole of what it knows.

It now falls back to natural abundance in exactly two cases: a library with no neutron data at all, as a photon-only calculation uses, and one whose photon data covers an element its neutron data skips, which is the ENDF/B-VII.1 case above. An element with neither kind of data is still an error, as are the partial cases the surrounding code already handled — C0 standing in for C12 and C13, O18 folded into O16.

A neutron calculation naming one of those four elements now fails when the data is actually wanted, reporting the missing nuclide, rather than at expansion — the same error one step later, and the price of the model being usable at all when neutrons are not transported.

Which particles get transported

A photon source turns photon transport on, because that setting is off by default and a source saying it emits photons settles something never specified.

Neutron transport has no counterpart. It is only ever off because it was asked for, so turning it back on would override an explicit choice, silently change which particles a calculation transports, and surface later as missing data rather than as the source that caused it. It also cannot be applied uniformly — a compiled source cannot be inspected before the data decision is made. So a source that emits neutrons is an error instead:

ERROR: A source emits neutrons, but neutron transport is turned off. Either
       turn it back on or give a source that does not emit neutrons.

A model specifying no source at all falls back to OpenMC's default source, which emits neutrons, and is reported the same way rather than as missing nuclide data further along.

Sources whose particles are not knowable up front are checked when the particle appears: a compiled source emitting a neutron, and a particle restart file holding one, both report it rather than transporting with no data.

Run modes

Only eigenvalue and fixed source calculations sample the external source, so sources are not checked elsewhere. A stochastic volume calculation samples no source and transports nothing, so it reports nuclide inventories without reading any neutron data — and with no data at all if the model carries no photon source. Plotting reads none either.

What is skipped for want of neutron data

• The logarithmic neutron energy grid, whose spacing would otherwise be derived from the unbounded defaults left behind when no nuclide has an energy grid.
• The minimum/maximum neutron data temperature message.
• Cell::set_temperature's interpolation bounds check, which has no temperature-dependent data to bound against.

Rejected combinations

Each of these would otherwise do nothing silently:

Combination	Reason
Eigenvalue mode	needs neutrons
Multi-group mode	multi-group data is neutron data; also covers the random ray solver, which requires it
Thermal scattering <sab>	affects neutron scattering only
NCrystal <cfg>	likewise
Resonance scattering	acts on neutron data
Multipole data	likewise
use_decay_photons (D1S)	replaces photons produced in neutron reactions, so with no neutron reactions it produces nothing. R2S, whose source is a decay source, is unaffected

Fixes found in review

Two independent reviews of this branch found problems it had made reachable:

• A nuclide-filtered tally with multiply_density off called the neutron cross section routine for whatever particle was being scored — a segfault with no neutron data. Fixed in Keep the micro cross section caches addressed correctly #64, where it belongs; the regression test stays here, since this branch is what makes the crash reachable.
• Sources OpenMC cannot inspect up front reached transport with no data, segfaulting. Now reported, with the error serialized so threads do not race through std::exit.
• Nuclide::reaction_index_ is only filled by create_derived(), which neither the new constructor nor the volume-mode early return reaches, leaving 902 garbage entries that pass the >= 0 test callers use before indexing an empty reactions_. Filled in both constructors, which also fixes the pre-existing volume mode case.
• A bad nuclide name reached the C API as std::exit rather than an error code, killing the host interpreter. openmc_load_nuclide now reports it through set_errmsg and OPENMC_E_DATA. (The same pattern in Tally::set_nuclides and read_ce_cross_sections is independent of this branch and is fixed separately in Report unresolvable nuclide names instead of terminating, and fix the tally docs #66.)

Testing

tests/unit_tests/test_neutron_transport_off.py runs against a library built by stripping everything but the photon entries out of the configured one, so a run that touched neutron data in any way could not succeed. It covers the photon-only run itself (including that densities are normalized from the tabulated masses), that the same library is still rejected without opting in, rejection of neutron sources and of each combination above, elemental evaluations, volume mode, the particle restart path, and the tally case that used to crash.

tests/unit_tests/test_element.py covers expansion against a synthetic cross_sections.xml: a photon-only library expands by natural abundance, so does a library whose neutron data skips the element while its photon data covers it (parametrized over Pt, Os, Yb and Ne), an element with neither kind of data is still refused, and non-neutron entries never count as isotope availability. Those build their own XML rather than needing a data library.

tests/cpp_unit_tests/test_nuclide.cpp covers the data-free constructor: identity and mass from the name, metastables, H1 taking the atomic rather than the bare proton mass, elemental evaluations, reaction_index_, and rejected names. Atomic weight ratios are asserted against values from a neutron data library rather than re-derived from the table under test.

Verified against the real ENDF/B-VII.1 HDF5 library: the four gap elements were confirmed by enumerating its 443 neutron and 100 photoatomic files against NATURAL_ABUNDANCE, Element('Pt').expand() reproduces the error above without this change, and a platinum photon model runs to completion with it, reading Pt photoatomic data and no neutron data at all.

Not covered: comparing a physics result with and without neutron data. That needs both runs to be possible for the same model, which they are not for these four elements.

Checklist

• I have performed a self-review of my own code
• I have run clang-format (version 18) on any C++ source files (if applicable)
• I have followed the style guidelines for Python source files (if applicable)
• I have made corresponding changes to the documentation (if applicable)
• I have added tests that prove my fix is effective or that my feature works (if applicable)

🤖 Generated with Claude Code

https://claude.ai/code/session_01JxR1sQWWnALXj39rX12v7c