Feature/shower energy

[francois-drielsma]

Description

This PR implements parametric shower energy reconstruction for electromagnetic showers in liquid argon. The new ShowerParametricEnergyProcessor fits the true shower energy from visible calorimetric deposits using a forward regression approach based on theoretical shower development models. The fitter samples 3D points from parametric longitudinal (Gamma distribution) and transverse (Grindhammer-Peters) profiles, predicts box-wise energy depositions, and minimizes the chi-square against reconstructed calorimetric energies to extract the initial shower energy.

Motivation and Context

Calorimetric energy reconstruction in modular liquid argon detectors suffers from systematic biases due to missing energy from invisible energy, nuclear effects, thresholding, and detector inefficiencies. This parametric approach corrects these biases by modeling the full 3D shower development and accounting for energy that escapes detector boundaries or falls below reconstruction thresholds. The method is particularly important for electromagnetic showers where containment and energy resolution are critical for physics analyses.

Type of Change

• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue) — fixes float conversion in calorimetric scaling

How Has This Been Tested?

The implementation has been tested on:

• Electromagnetic shower samples from neutrino interactions in ND-LAr detector geometry
• Energy range validation from O(1000) MeV to O(10000) MeV
• Comparison between Grindhammer-Peters and custom log-based longitudinal parameterizations
• Chi-square minimization convergence and stability tests

Test Configuration:

• OS: macOS (development), Linux (production)
• Python version: 3.9+
• SPINE version: feature/shower-energy branch (commits up to 04c62f55)
• Detector geometry: ND-LAr (module and TPC modes)

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings or errors
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Key Implementation Details

Core Components

1. ShowerEnergyFitter (in spine/utils/shower.py)

   • Performs chi-square minimization over trial shower energies
   • Samples points from parametric shower models using configurable random seeds for reproducibility
   • Supports multiple geometry modes: single detector, module-wise, and TPC-wise energy accounting
   • Implements uncertainty model based on Monte Carlo sampling statistics with configurable floor

2. ShowerParametricEnergyProcessor (in spine/post/reco/shower.py)

   • Post-processor that applies the fitter to reconstructed shower particles
   • Integrates with existing SPINE reconstruction chain (requires direction and calo_ke upstream)
   • Computes box-wise energy depositions from reconstructed points
   • Replaces calorimetric energy (calo_ke) with fitted parametric energy

3. Shower Physics Utilities (in spine/utils/shower.py)

   • sample_shower_points(): Sample 3D points from factorized shower model
   • shower_energy_density_3d(): Compute volumetric energy density at arbitrary points
   • shower_long_params_gp(): Grindhammer-Peters longitudinal parametrization
   • shower_long_params_lar(): Custom LAr-tuned longitudinal parametrization
   • shower_transverse_params_gp(): GP transverse radial profile parameters

Configuration Parameters

• n_points: Number of Monte Carlo samples per energy trial (default: 10000)
• seed: Random seed for reproducible sampling
• sigma_floor: Minimum per-box energy uncertainty in MeV (default: 1.0)
• energy_bounds: Valid energy range for fitting (default: 1-10000 MeV)
• xatol: Absolute tolerance on fitted energy (default: 1.0 MeV)
• use_gp: Toggle between GP and custom longitudinal parametrizations
• mode: Geometry partitioning mode ("detector", "module", "tpc")

Bug Fixes

• Fixed calorimetric scaling factors in CalorimetricEnergyProcessor to ensure float type conversion when evaluating string expressions (previously returned numpy.ndarray for scalar results)

Additional Notes

• The parametric model assumes electromagnetic shower development; extension to hadronic showers would require different parametrizations
• Currently only applied to shower-like particles (SHOWR_SHP); tracks are unaffected
• Energy bounds should be set appropriately for physics use cases — the GP longitudinal model is only valid above ~120 MeV
• Computational cost scales with n_points; 10000 samples provides good accuracy-speed tradeoff for typical applications
• The method is particularly effective for showers near detector boundaries where containment corrections are largest

[codecov]

Codecov Report

❌ Patch coverage is 15.86538% with 175 lines in your changes missing coverage. Please review.
✅ Project coverage is 15.14%. Comparing base (26c9066) to head (41c12f0).
⚠️ Report is 10 commits behind head on main.

Files with missing lines	Patch %	Lines
src/spine/utils/shower.py	14.45%	142 Missing ⚠️
src/spine/post/reco/shower.py	20.51%	31 Missing ⚠️
src/spine/post/reco/calo.py	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #120      +/-   ##
==========================================
+ Coverage   15.02%   15.14%   +0.11%     
==========================================
  Files         273      273              
  Lines       20639    20843     +204     
==========================================
+ Hits         3102     3156      +54     
- Misses      17537    17687     +150     

Flag	Coverage Δ
unittests	15.14% <15.86%> (+0.11%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/spine/utils/globals.py	100.00% <100.00%> (ø)
src/spine/post/reco/calo.py	21.25% <0.00%> (ø)
src/spine/post/reco/shower.py	22.80% <20.51%> (-0.68%)	⬇️
src/spine/utils/shower.py	19.65% <14.45%> (+19.65%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.