Implementation Plan for Photon MGXS Cross Sections
Based on my analysis of the OpenMC codebase, here's a structured plan to implement photon multigroup cross sections in sequential PRs:
Phase 1: Foundation & Infrastructure (PRs 1-3)
PR #1: Add Photon-Specific Tally Scores
Goal: Enable basic photon interaction tallying in OpenMC C++ core
Tasks:
Add new tally scores in C++:
'coherent' (Rayleigh scattering)
'incoherent' (Compton scattering)
'photoelectric'
'pair-production'
Update src/tallies/tally_scoring.cpp to handle these scores
Update tally score validation in C++ and Python
Add tests for basic photon score tallying
Files to modify:
include/openmc/tallies/tally.h
src/tallies/tally_scoring.cpp
openmc/tallies.py
Add tests in tests/unit_tests/
Estimated complexity: Medium (requires C++ and Python changes)
PR #2: Create ParticleType Infrastructure for MGXS
Goal: Make MGXS classes particle-type aware
Tasks:
Add particle_type attribute to base MGXS class (default to 'neutron' for backward compatibility)
Update MGXS initialization to accept particle type
Add validation to ensure neutron-only scores aren't used with photons
Update MGXS_TYPES tuple to include photon-specific reaction types
Files to modify:
mgxs.py (lines 17-45 for type definitions)
mgxs.py (base MGXS class init)
Add particle_type property with validation
Example additions to MGXS_TYPES:
Estimated complexity: Low-Medium (mostly Python, sets foundation)
PR #3: Add Photon Energy Group Structures
Goal: Define standard photon energy group structures
Tasks:
Add photon-specific energy group structures to openmc/mgxs/groups.py
Common structures:
Fine photon groups (e.g., 100-200 groups, 0.01 MeV - 100 MeV)
Coarse photon groups (e.g., 12-30 groups)
Coupled neutron-photon groups
Add documentation on appropriate energy ranges for photons
Add validation for photon energy groups
Files to modify:
openmc/mgxs/groups.py
Update GROUP_STRUCTURES dictionary
Estimated complexity: Low (data definition + documentation)
Phase 2: Basic Photon MGXS Classes (PRs 4-7)
PR #4: PhotonTotalXS Class
Goal: Implement simplest photon MGXS (total cross section)
Tasks:
Create PhotonTotalXS class inheriting from MGXS
Implement using 'flux' and 'photon-total' or sum of component scores
Override scores, filters, tallies properties
Add get_xs() method (no nu-multiplication)
Add unit tests and integration tests
Files to modify:
mgxs.py (add new class ~2000 lines)
Update get_mgxs() factory method
Add to all in openmc/mgxs/init.py
Estimated complexity: Medium
PR #5: Component Photon Cross Sections
Goal: Implement individual photon interaction XS classes
Tasks:
CoherentXS (Rayleigh scattering)
IncoherentXS (Compton scattering)
PhotoelectricXS
PairProductionXS
Each uses flux + specific score
No transport correction needed (unlike neutrons)
Files to modify:
mgxs.py (add 4 new classes)
Update factory method
Estimated complexity: Medium (repetitive but straightforward)
PR #6: PhotonHeatingXS Class
Goal: Photon heating/KERMA cross section
Tasks:
Create PhotonHeatingXS class
Uses 'heating' score (MT=525 in photon data)
Important for shutdown dose rate calculations
Add validation and tests
Files to modify:
mgxs.py
Estimated complexity: Low-Medium
PR #7: Photon Scatter Matrix
Goal: Energy transfer matrix for photon scattering
Tasks:
Create PhotonScatterMatrixXS inheriting from MatrixMGXS
Combine coherent (elastic) + incoherent (inelastic) scattering
Uses EnergyFilter and EnergyoutFilter
No nu-multiplication
Can use Legendre expansion for angular dependence (optional)
Files to modify:
mgxs.py (new class ~line 4000+)
May need to handle elastic vs inelastic separately
Estimated complexity: High (matrix handling, similar to neutron scatter matrix but simpler)
Phase 3: Library Integration (PRs 8-9)
PR #8: Update Library Class for Photons
Goal: Enable openmc.mgxs.Library to work with photons
Tasks:
Add particle parameter to Library class
Update build_library() to handle photon MGXS types
Modify mgxs_types validation for photon-specific types
Ensure photon domains work correctly
Add mixed neutron-photon library support (separate tallies)
Files to modify:
library.py
Update Library.init(), build_library()
Estimated complexity: Medium-High (central integration point)
PR #9: HDF5 Export for Photon MGXS
Goal: Enable photon MGXS export to HDF5
Tasks:
Update create_mg_mode() method in Library
Ensure photon XS data can be exported
Add photon-specific data sections in HDF5
Update MGXSLibrary class to handle photon data
May need separate photon XS library file
Files to modify:
library.py (~line 1397+)
mgxs_library.py
Estimated complexity: Medium-High
Phase 4: Advanced Features (PRs 10-12)
PR #10: Photon Current and Diffusion
Goal: Implement current and diffusion coefficient for photons
Tasks:
Create PhotonCurrent class (directional flux moments)
PhotonDiffusionCoefficient (if applicable for photons)
Uses surface currents or angular flux moments
Important for VR applications
Files to modify:
mgxs.py
Estimated complexity: Medium
PR #11: Coupled Neutron-Photon Production
Goal: Handle photon production from neutron reactions
Tasks:
Add PhotonProductionMatrixXS class
Tracks photons produced by neutron interactions
Uses 'photon-production' score (if available) or derived
Matrix from neutron energy in → photon energy out
Files to modify:
mgxs.py
May require new C++ tally scores
Estimated complexity: High (coupled physics)
PR #12: Photon MGXS for Variance Reduction
Goal: Enable FW-CADIS with photon MGXS
Tasks:
Integrate photon MGXS with weight windows
Test Random Ray + photon MGXS workflow
Add examples for shutdown dose rate with VR
Documentation for coupled neutron-photon VR
Files to modify:
model.py (update generate*_mgxs methods)
Add example notebooks
Documentation
Estimated complexity: High (application-focused)
Phase 5: Testing & Documentation (PR 13)
PR #13: Comprehensive Testing & Documentation
Goal: Full test coverage and user documentation
Tasks:
Regression tests with known photon MGXS values
Integration tests with photon transport
Jupyter notebook examples:
Basic photon MGXS generation
Shutdown dose rate with VR
Coupled neutron-photon transport
Update user documentation
Add to API reference
Files to modify:
tests/regression_tests/ (new photon MGXS tests)
docs/source/examples/
mgxs.rst
Estimated complexity: High (comprehensive coverage)
Implementation Notes:
Key Differences from Neutron MGXS:
No fission: Photons don't undergo fission
No nu-multiplication: No neutron production multiplicity
Simpler scattering: Coherent is elastic, incoherent is Compton
Different scores: Use photon-specific interaction types
Energy range: Typically 0.01 eV - 100 MeV (vs neutrons: thermal - 20 MeV)
Dependencies:
PRs 1-3 must be completed before Phase 2
PR 8 depends on PRs 4-7
PR 11 may require C++ changes (could be delayed)
PR 12 can be done after PR 8
Timeline Estimate:
Testing Strategy:
Unit tests for each new class
Integration tests with photon transport
Comparison with continuous-energy results
Verification against analytical solutions where available
Implementation Plan for Photon MGXS Cross Sections
Based on my analysis of the OpenMC codebase, here's a structured plan to implement photon multigroup cross sections in sequential PRs:
Phase 1: Foundation & Infrastructure (PRs 1-3)
PR #1: Add Photon-Specific Tally Scores
Goal: Enable basic photon interaction tallying in OpenMC C++ core
Tasks:
Add new tally scores in C++:
'coherent' (Rayleigh scattering)
'incoherent' (Compton scattering)
'photoelectric'
'pair-production'
Update src/tallies/tally_scoring.cpp to handle these scores
Update tally score validation in C++ and Python
Add tests for basic photon score tallying
Files to modify:
include/openmc/tallies/tally.h
src/tallies/tally_scoring.cpp
openmc/tallies.py
Add tests in tests/unit_tests/
Estimated complexity: Medium (requires C++ and Python changes)
PR #2: Create ParticleType Infrastructure for MGXS
Goal: Make MGXS classes particle-type aware
Tasks:
Add particle_type attribute to base MGXS class (default to 'neutron' for backward compatibility)
Update MGXS initialization to accept particle type
Add validation to ensure neutron-only scores aren't used with photons
Update MGXS_TYPES tuple to include photon-specific reaction types
Files to modify:
mgxs.py (lines 17-45 for type definitions)
mgxs.py (base MGXS class init)
Add particle_type property with validation
Example additions to MGXS_TYPES:
Estimated complexity: Low-Medium (mostly Python, sets foundation)
PR #3: Add Photon Energy Group Structures
Goal: Define standard photon energy group structures
Tasks:
Add photon-specific energy group structures to openmc/mgxs/groups.py
Common structures:
Fine photon groups (e.g., 100-200 groups, 0.01 MeV - 100 MeV)
Coarse photon groups (e.g., 12-30 groups)
Coupled neutron-photon groups
Add documentation on appropriate energy ranges for photons
Add validation for photon energy groups
Files to modify:
openmc/mgxs/groups.py
Update GROUP_STRUCTURES dictionary
Estimated complexity: Low (data definition + documentation)
Phase 2: Basic Photon MGXS Classes (PRs 4-7)
PR #4: PhotonTotalXS Class
Goal: Implement simplest photon MGXS (total cross section)
Tasks:
Create PhotonTotalXS class inheriting from MGXS
Implement using 'flux' and 'photon-total' or sum of component scores
Override scores, filters, tallies properties
Add get_xs() method (no nu-multiplication)
Add unit tests and integration tests
Files to modify:
mgxs.py (add new class ~2000 lines)
Update get_mgxs() factory method
Add to all in openmc/mgxs/init.py
Estimated complexity: Medium
PR #5: Component Photon Cross Sections
Goal: Implement individual photon interaction XS classes
Tasks:
CoherentXS (Rayleigh scattering)
IncoherentXS (Compton scattering)
PhotoelectricXS
PairProductionXS
Each uses flux + specific score
No transport correction needed (unlike neutrons)
Files to modify:
mgxs.py (add 4 new classes)
Update factory method
Estimated complexity: Medium (repetitive but straightforward)
PR #6: PhotonHeatingXS Class
Goal: Photon heating/KERMA cross section
Tasks:
Create PhotonHeatingXS class
Uses 'heating' score (MT=525 in photon data)
Important for shutdown dose rate calculations
Add validation and tests
Files to modify:
mgxs.py
Estimated complexity: Low-Medium
PR #7: Photon Scatter Matrix
Goal: Energy transfer matrix for photon scattering
Tasks:
Create PhotonScatterMatrixXS inheriting from MatrixMGXS
Combine coherent (elastic) + incoherent (inelastic) scattering
Uses EnergyFilter and EnergyoutFilter
No nu-multiplication
Can use Legendre expansion for angular dependence (optional)
Files to modify:
mgxs.py (new class ~line 4000+)
May need to handle elastic vs inelastic separately
Estimated complexity: High (matrix handling, similar to neutron scatter matrix but simpler)
Phase 3: Library Integration (PRs 8-9)
PR #8: Update Library Class for Photons
Goal: Enable openmc.mgxs.Library to work with photons
Tasks:
Add particle parameter to Library class
Update build_library() to handle photon MGXS types
Modify mgxs_types validation for photon-specific types
Ensure photon domains work correctly
Add mixed neutron-photon library support (separate tallies)
Files to modify:
library.py
Update Library.init(), build_library()
Estimated complexity: Medium-High (central integration point)
PR #9: HDF5 Export for Photon MGXS
Goal: Enable photon MGXS export to HDF5
Tasks:
Update create_mg_mode() method in Library
Ensure photon XS data can be exported
Add photon-specific data sections in HDF5
Update MGXSLibrary class to handle photon data
May need separate photon XS library file
Files to modify:
library.py (~line 1397+)
mgxs_library.py
Estimated complexity: Medium-High
Phase 4: Advanced Features (PRs 10-12)
PR #10: Photon Current and Diffusion
Goal: Implement current and diffusion coefficient for photons
Tasks:
Create PhotonCurrent class (directional flux moments)
PhotonDiffusionCoefficient (if applicable for photons)
Uses surface currents or angular flux moments
Important for VR applications
Files to modify:
mgxs.py
Estimated complexity: Medium
PR #11: Coupled Neutron-Photon Production
Goal: Handle photon production from neutron reactions
Tasks:
Add PhotonProductionMatrixXS class
Tracks photons produced by neutron interactions
Uses 'photon-production' score (if available) or derived
Matrix from neutron energy in → photon energy out
Files to modify:
mgxs.py
May require new C++ tally scores
Estimated complexity: High (coupled physics)
PR #12: Photon MGXS for Variance Reduction
Goal: Enable FW-CADIS with photon MGXS
Tasks:
Integrate photon MGXS with weight windows
Test Random Ray + photon MGXS workflow
Add examples for shutdown dose rate with VR
Documentation for coupled neutron-photon VR
Files to modify:
model.py (update generate*_mgxs methods)
Add example notebooks
Documentation
Estimated complexity: High (application-focused)
Phase 5: Testing & Documentation (PR 13)
PR #13: Comprehensive Testing & Documentation
Goal: Full test coverage and user documentation
Tasks:
Regression tests with known photon MGXS values
Integration tests with photon transport
Jupyter notebook examples:
Basic photon MGXS generation
Shutdown dose rate with VR
Coupled neutron-photon transport
Update user documentation
Add to API reference
Files to modify:
tests/regression_tests/ (new photon MGXS tests)
docs/source/examples/
mgxs.rst
Estimated complexity: High (comprehensive coverage)
Implementation Notes:
Key Differences from Neutron MGXS:
No fission: Photons don't undergo fission
No nu-multiplication: No neutron production multiplicity
Simpler scattering: Coherent is elastic, incoherent is Compton
Different scores: Use photon-specific interaction types
Energy range: Typically 0.01 eV - 100 MeV (vs neutrons: thermal - 20 MeV)
Dependencies:
PRs 1-3 must be completed before Phase 2
PR 8 depends on PRs 4-7
PR 11 may require C++ changes (could be delayed)
PR 12 can be done after PR 8
Timeline Estimate:
Testing Strategy:
Unit tests for each new class
Integration tests with photon transport
Comparison with continuous-energy results
Verification against analytical solutions where available