Physics Data And Cross Sections

This page explains how neomc currently ingests, validates, binds, and uses physics data. For real users, this is as important as the process list itself: transport only works when the right element-resolved tables are present and cover every material component used in the run.

Mental Model

The current coupled-EM data path is:

upstream reference files
  -> importer functions
  -> runtime tables
  -> per-material process builders
  -> transport driver

In practical terms:

reference_root + material elements
  -> photon/electron importers
  -> PhotonRuntimeTable / ElectronRuntimeTable
  -> PhotonMaterialProcess / ElectronMaterialProcess
  -> CoupledEmModel or MixedTransportModel

Runtime Table Types

The main public runtime-table types are:

• PhotonRuntimeTable
• ElectronRuntimeTable
• DecayRuntimeTable
• NeutronMicroscopicCrossSectionTable

These are compact neomc runtime objects. They are what transport and source code consume. The transport layer does not read upstream HDF5 or ENDF files directly during a run.

Photon Data

Photon data is stored per element in PhotonElementData.

What PhotonElementData Contains

The public fields show that the imported photon table contains:

• energy grid;
• coherent cross section;
• incoherent cross section;
• photoelectric cross section;
• pair-production cross section in the electron field;
• pair-production cross section in the nuclear field;
• heating cross section;
• coherent and incoherent scattering factors;
• Compton profile data;
• shell binding energies and shell electron counts;
• subshell photoelectric data;
• subshell transition data for atomic relaxation;
• mean excitation energy and shell ionization data used by charged transport support code.

Photon Importers

The public importer entry points are:

• nndc_photon_hdf5_path
• import_nndc_photon_hdf5
• import_nndc_photon_elements
• import_nndc_photon_runtime_table

The user-facing pattern is:

1. determine which elements appear in the material set;
2. resolve the per-element upstream file path under reference_root;
3. import those elements;
4. build one PhotonRuntimeTable.

Electron Data

Electron data is stored per element in ElectronElementData.

What ElectronElementData Contains

The public fields show that the imported electron table contains:

• elastic cross section;
• bremsstrahlung cross section;
• excitation cross section;
• ionization subshell binding energies;
• ionization subshell cross sections;
• elastic angular distributions;
• bremsstrahlung photon spectra;
• optional Seltzer-Berger bremsstrahlung data;
• optional Sternheimer density-effect data;
• bremsstrahlung electron-energy tables;
• excitation energy-loss tables;
• ionization ejected-electron spectra.

The enclosing ElectronRuntimeTable also contains:

• electron/positron MSC correction data;
• shared Goudsmit-Saunderson MSC angular-grid data.

Electron Importers

The public importer entry points are:

• endfb_eedl_electron_endf_path
• import_eedl_electron_endf
• import_endfb_eedl_electron_elements
• import_endfb_eedl_electron_runtime_table

As with photons, the intended user flow is element-driven: import only the elements actually used by the current material set, then build one runtime table covering those elements.

Decay Data

Decay data is stored in DecayRuntimeTable, which contains DecayNuclideData records.

Each nuclide record contains:

• nuclide identity;
• atomic and mass number;
• half-life;
• source_path;
• decay modes;
• emission records.

Public importer entry points:

• import_endfb_decay_endf
• import_endfb_decay_runtime_table

This table is consumed by:

• sample_decay_event
• StaticDecayInventorySource
• evolve_decay_inventory
• evolve_one_group_activation_inventory

Neutron Microscopic Cross-Section Data

NeutronMicroscopicCrossSectionTable is the current public neutron data surface.

Each table contains:

• one target nuclide;
• one MT reaction identifier;
• one reaction classification;
• source_path;
• energy grid;
• microscopic cross section in barns.

Public helpers include:

• neutron_reaction_type_from_mt
• neutron_reaction_type_name
• validate_neutron_microscopic_cross_section_table
• evaluate_neutron_microscopic_cross_section_barn

Public importer entry point:

• import_endfb_neutron_mf3

These tables are now also the data input for the experimental neutron transport package. Current neutron transport uses a narrow subset: total, elastic, and capture reactions in a free-flight / sink-accounting model.

Stopping-Power And Range Reference Data

The public data surface also includes stopping-power and range reference utilities used by benchmarks and validation workflows.

Electron Stopping-Power Tables

ElectronStoppingPowerTable contains:

• material name;
• source_path;
• energy grid;
• collision mass stopping power;
• radiative mass stopping power;
• total mass stopping power;
• CSDA range.

Public helpers:

• validate_electron_stopping_power_table
• evaluate_electron_collision_mass_stopping_mev_cm2_per_g
• evaluate_electron_radiative_mass_stopping_mev_cm2_per_g
• evaluate_electron_total_mass_stopping_mev_cm2_per_g
• evaluate_electron_csda_range_g_cm2

Public importer:

• import_geant4_estar_table

Proton Stopping And Range

The current proton stopping helper surface is a built-in NIST PSTAR water reference path:

• nist_pstar_water_proton_stopping_source
• nist_pstar_water_proton_min_energy_ev
• nist_pstar_water_proton_max_energy_ev
• nist_pstar_water_proton_electronic_mass_stopping_power
• nist_pstar_water_proton_covers_energy
• nist_pstar_water_proton_csda_range_cm

Alpha Stopping And Range

The current alpha stopping helper surface is a built-in NIST ASTAR water reference path:

• nist_astar_water_alpha_stopping_source
• nist_astar_water_alpha_min_energy_ev
• nist_astar_water_alpha_max_energy_ev
• nist_astar_water_alpha_electronic_mass_stopping_power
• nist_astar_water_alpha_csda_range_cm

The alpha transport package uses the ASTAR-water stopping model for its current CSDA electronic-stopping scope.

Provenance And Source Paths

Every imported element, table, or nuclide record includes a source_path field. That is the user-visible provenance trail inside the runtime data.

In practical terms, this means:

• imported photon records remember which upstream file produced them;
• imported electron records remember which upstream file produced them;
• imported decay nuclides remember which upstream file produced them;
• imported neutron tables remember which upstream file produced them.

This is important when validating physics results or auditing a generated runtime table.

Element Discovery And Binding

The data-import path is driven by material composition, not by a global "import everything" step.

The normal public flow is:

1. define materials;
2. resolve them into MaterialDefinition or Material;
3. call material_element_records(...);
4. import photon/electron tables for those elements;
5. populate CoupledEmPhysicsData.

The key helper here is:

• material_element_records

That gives the element list used by the importer functions.

Atomic Weights

Photon and electron material-process builders also require std::vector<ElementAtomicWeight>.

These are used to convert authored material composition into material-level properties such as:

• atom densities;
• electron density;
• effective Z;
• radiation length and related charged-transport properties.

Relevant public surfaces:

• ElementAtomicWeight
• standard_atomic_weight
• material_element_atom_densities

From Runtime Tables To Material Processes

Importing tables is only the first half of the chain. The next step is binding those per-element tables to each material in the run.

Photon Material Processes

build_photon_material_processes(...) consumes:

• materials;
• PhotonRuntimeTable;
• atomic weights;
• photon policy controls.

It produces PhotonMaterialProcess records containing:

• MaterialId;
• one PhotonInteractionProcess per material-element contribution;
• atom density per barn-cm;
• configured Compton / relaxation / triplet policies.

Electron Material Processes

build_electron_material_processes(...) consumes:

• materials;
• ElectronRuntimeTable;
• relaxation PhotonRuntimeTable;
• atomic weights.

It produces ElectronMaterialProcess records containing:

• MaterialId;
• one ElectronElementData contribution;
• atom density per barn-cm;
• charged-material transport properties;
• relaxation subshell data;
• ionization-to-relaxation shell mappings.

This is the step where raw imported cross sections become material-resolved transport data.

Why Relaxation Uses Photon Data

The current CoupledEmPhysicsData layout contains:

• photon
• electron
• relaxation
• atomic_weights

relaxation is also a PhotonRuntimeTable.

That is because the current atomic-relaxation information used by coupled EM is stored in the photon-side shell and transition data. Repository example code therefore commonly does:

• import photon table;
• assign it to physics_data.photon;
• reuse it for physics_data.relaxation.

Model Coverage Validation

The model layer performs explicit coverage checks before transport starts.

CoupledEmModel Checks

CoupledEmModel rejects a definition if:

• photon data is missing;
• electron data is missing;
• relaxation photon data is missing;
• any imported photon or electron record fails validation;
• any material component is not elemental;
• any material element is missing photon data;
• any material element is missing relaxation data;
• any material element is missing electron data.

MixedTransportModel Checks

MixedTransportModel performs the same element-coverage checks for material regions that can enter the coupled-EM side of the run.

When neutron transport is enabled, neutron physics data is also validated before the run. Missing or invalid required cross-section data is meant to fail during model construction or session compilation, not silently during tracking.

Current Material Limitation

The coupled-EM and mixed model validation code currently requires elemental material components when building EM material processes.

That means:

• ComponentKind::element is supported for EM material binding;
• nuclide-level material components are not currently accepted by the coupled-EM material coverage checks.

This is an important user constraint: if your material authoring path does not resolve to elemental composition, the current EM model build will fail.

Current Failure Modes Users Should Expect

At model construction time, the current code is expected to reject:

• missing photon element coverage;
• missing electron element coverage;
• missing relaxation element coverage;
• non-elemental EM material components;
• empty required physics tables;
• invalid imported table content.

That fail-closed behavior is part of the public semantics, not just an implementation detail.