Deplete: Flux mode (mg-flux); faster collapse via SparseXSTable

[yrrepy]

Description

Currently when Deplete collapses mg-flux in Flux mode via from_multigroup_flux;
from_multigroup_flux acquires the CE XS on the HDF5 (ACE) grid and averages the XS points on the grid to the collapse_energies energy group structure, using a flat-in-bin approximation for each energy group. This gets us the σ_g to then collapse with the φ_g.

It does this acquisition from the CE XS per material, per nuclide, per reaction.
Group cross sections were re-derived from the continuous-energy data for every nuclide and reaction, on every material.
When depleting 10,000++ material domains (as is customary for a large R2S mesh, or other voxel-wise activation problem), this can become quite slow. Re-factoring below achieves collapse speedups of 6-60x.

This PR re-factors such that the acquisition from the CE XS is only done once, and this data populates a SparseXSTable. A new group_xs C API exposes the flux-independent group-averaged XS; it shares one kernel with collapse_rate. The SparseXSTable now populated with all the necessary σ_g for a problem (σ_g per nuclide, per reaction) and thence this matrix can be collapsed with all the φ_g of each material to form the one group collapsed cross-section.

Pseudo-code, illustrating the structure of the loops:

Existing

for material i in 1..N:                     # correct: flux φ_i differs per domain
    with TemporarySession():                # init OpenMC + reload XS data
        for nuclide in nuclides:          
            for reaction in reactions:     
                # collapse_rate re-derives σ̄_g from CE data here, every time —
                # flux-INDEPENDENT, yet recomputed for every material  ← waste
                xs[nuc, rxn] = collapse_rate(mt, T, energies, flux_i)

This PR

# STEP 1 — flux-independent averaging, done ONCE
table = _build_xs_table_ce(nuclides, reactions, energies, T)
#   for nuclide × reaction:  row = group_xs(mt, T, energies)   # σ̄_g
#   keep only non-zero rows  ->  _SparseXSTable.xs_matrix [n_pairs × G]

# STEP 2 — collapse, still per material-domain
for material i in 1..N:                     # still per-material (φ_i)
    phi      = flux_i / flux_i.sum()
    micros_i = table.collapse(phi)          # xs_matrix @ phi  ≡  Σ_g σ̄_g·φ_g  (one mat-vec)

New implementation is compatible with the Independent and Coupled Operators.
Note that the SparseXSTable is unique to a group-structure + XS temperature.

Benchmarking

I have benchmarked on the FNG model, existing method and this PR.
collapse_speed_fng.py
fomg_16k.npy.tar.gz
fng_neutron.xml, bounding_boxes.json are needed from https://zenodo.org/records/10660030
Any cross-sections.xml and chain.xml should do.

FNG: 7 material (types), 54 nuclides, 36 reactions
Using energy-strucutres: UKAEA-1102 and FOMG-16k
Varying mesh size: 10k, 20k, 40k, 60k, 80k.
Full OMP for transport, no MPI. Collapse benefits from no parallelization.

Speed-ups are on the order of 6x for FOMG-16k. And 20-60x for UKAEA-1102.
Collapse processing time for 40k+ materials decreases from ~30 minutes to a minute.

Microxs results here (and elsewhere in tests) are bitwise identical and unchanged by the new collapse method.

Background

This feature comes from my GENDF Isomeric workflow
https://github.com/yrrepy/openmc/tree/iso-gendf-mpi_Sync2b-bis
1284c19
4f4de43

The faster collapse in GENDF came from this SparseXSTable, not from GENDF being inherently faster to work with.

I am trying to splice off very useful features from that workflow, that will hopefully pave the way to it's integration.

Future Plans

1. Currently Deplete Flux only does the "flat-in-bin" approximation, a follow-up PR will mirror PREPRO:
   http://redcullen1.net/homepage.new/Papers/PREPRO2023/PREPRO2023.pdf

a) Input an arbitrary tabulated linearly interpolable weighting spectrum, or,
b) “flat” or constant weight in each group, or,
c) 1/E across section entire energy range, or,
d) Maxwellian to 1/E to Fission to Constant

2. Next up from the GENDF workflow is a global_microxs_hdf5 that is MPI optimized.
   Each MPI rank reads only its local materials slices from the microxs.hdf5 (which differs from the r2s.py microxs.hdf5). This reduces the amount of RAM per MPI rank, enabling more MPI ranks to be run in parallel. (Generally Deplete is more limited by RAM, than it is by available CPU ranks).
   https://github.com/yrrepy/openmc/tree/Enhance-Deplete-MPI
   1c0961c
   244b251

3. GENDF isomeric XS depletion reuses this exact collapse machinery (SparseXSTable)

TLDR;

Flux-mode depletion re-derived group cross sections from CE data per material; this builds them once into a SparseXSTable and reuses them. ~6–60× faster collapse, identical results.

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)

[paulromano]

Thanks a lot for this PR @yrrepy and look forward to the next ones too! I'm on leave through the end of this week so I won't have time to look at this in full until next week.