Build fine energy group structures

[yrrepy]

Description

This PR follows up #3564.
It was requested to not have the large energy structures in the Python file but rather in an .H5.

The implementation here one ups that, a generic method, build_fine_group_structure, that can be used to build these types of formulaic fine energy group structures. Pretty dang sleek if I do say so myself!
These structures often follow similar styles, 1000 groups per decade between 1eV and 100 keV, etc.
The built method allows equal-lethargy or equal-width groups per interval.

FOMG-16000, VESTA-43000, VESTA-100000 are added as named groups that immediately leverage this functionality to populate their GROUP_STRUCTURES

N.B.

• FOMG-16000 was built for and is recommended for fusion
• VESTA-43000 was built for and is recommended for LWR (U-238 dominated systems)

These two energy structures are explicitly included on tests/unit_tests/fine_group_structures_reference.npz, and VESTA-43000 of the npz is tested against build_fine_group_structure.
FOMG is included on the npz, but the tests compare hard coded equations of FOMG-16000 and VESTA-100000 against build_fine_group_structure.
I manually prepared in Excel the npz energy structures.

These types of energy structure are needed for the multi-group binning (MGB) method of neutron activation.
Found in Aleph, VESTA, Shift and SMURE.

https://doi.org/10.1051/snamc/201405203
morgan2013.pdf
https://www.kns.org/files/pre_paper/44/20A-413-%EA%B9%80%EA%B2%BD%EB%AF%BC-%EB%B0%9C%ED%91%9C%EC%9E%90%EB%A3%8C.pdf
https://etheses.whiterose.ac.uk/id/eprint/4427/1/PhD_Thesis_Corrected_FINAL_FINAL_3_9_13.pdf
https://www.osti.gov/etdeweb/servlets/purl/20902503 https://roma.sckcen.be/ws/portalfiles/portal/4558859/An_Optimum_Approach_to_Monte_Carlo_Burn_Up.pdf https://rsicc.ornl.gov/codes/ccc/ccc7/ccc-769.html
https://www.tandfonline.com/doi/abs/10.13182/NSE07-A2695

AI Assistance

• Harness: Claude Code
• Model: Claude Fable 5.1, Opus 5.5, Opus 5.5
• Reasoning effort: max, high, max
  Planning/orchestration/final review, implementation, review

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)

Summary by CodeRabbit

• New Features
  • Added a utility for building fine energy-group structures using linear or logarithmic spacing.
  • Added the FOMG-16000, VESTA-43000, and VESTA-100000 energy-group structures.
• Documentation
  • Updated the multigroup cross-section API documentation to include the new utility.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 19e49800-6757-4c45-8f23-ae3976fbfcad

📥 Commits

Reviewing files that changed from the base of the PR and between aa4afc4 and 103e6da.

📒 Files selected for processing (5)

• docs/source/pythonapi/mgxs.rst
• openmc/mgxs/__init__.py
• openmc/mgxs/groups.py
• tests/unit_tests/fine_group_structures_reference.npz
• tests/unit_tests/test_mgxs_fine_group_structures.py

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

📝 Walkthrough

The change adds build_fine_group_structure to openmc.mgxs and registers the FOMG-16000, VESTA-43000, and VESTA-100000 energy-group structures. Unit tests cover builder inputs, generated boundaries, structure references, and name lookup.

Changes: Fine-energy group structures

Layer / File(s)	Summary
Fine-group boundary builder openmc/mgxs/groups.py, openmc/mgxs/__init__.py, docs/source/pythonapi/mgxs.rst, tests/unit_tests/test_mgxs_fine_group_structures.py	Adds and exports build_fine_group_structure. The function validates macro-boundaries, group counts, and spacing, then generates linear or logarithmic subdivisions. Tests cover its inputs, output boundaries, and errors.
Registered energy structures openmc/mgxs/__init__.py, tests/unit_tests/test_mgxs_fine_group_structures.py	Registers FOMG-16000, VESTA-43000, and VESTA-100000 with their reference documentation. Tests compare their edges with reference data and verify name lookup.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Suggested reviewers: paulromano

Merge Risk: ⚪ Minimal · up to 103e6

No merge-blocking issue is established; the change is ready for normal checks.

Security architecture risk: 🔵 Low · up to 103e6

The change is additive and preserves existing consumer behavior. No introduced security-boundary weakness was identified. Caller-selected group counts determine memory use, and exposure through applications accepting untrusted inputs remains outside the reviewed scope.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — Caller-selected group counts control local boundary-array allocation and downstream energy-axis dimensions. This is a resource-consumption capability, not an established attack path: existing consumers already accepted arbitrary energy-edge sequences, and external application exposure is unknown.

Trust Boundaries and Controls

• observed — The builder enforces finite, non-negative, strictly increasing macro-boundaries, exact interval-vector lengths, positive integer-indexable counts, permitted spacing values, positive logarithmic lower bounds, and increasing output edges. EnergyFilter retains catalog-key validation.

Resilience and Maintainability Implications

• inferred — Validation or allocation failure before return does not publish partial builder results or mutate the catalog. Normal EnergyGroups construction copies catalog arrays, preserving the existing ownership model. Direct mutation of the public catalog remains possible and predates this PR.

Pre-merge checks · 4 · 1

Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 12.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 16 functions across 3 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description check		The description explains the motivation, implementation, added structures, references, AI assistance, and completed checklist. It identifies follow-up issue #3564, although it does not use the templat…
Title check		The title is concise and accurately describes the main change: adding support for building fine energy group structures.

Full details: Docstring Coverage

Explanation

Docstring coverage is 12.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 16 functions across 3 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}