Automated isotope identification from resonance fingerprinting

[KedoKudo]

Summary

The current 2D imaging pipeline requires users to specify the isotopes, energy axis, and material properties upfront. When these are wrong (e.g., assuming Ta-181 instead of the actual Pu-241), SAMMY still converges but produces physically meaningless results — high chi-squared, abundances > 1.0, and incorrect spatial maps. There is no feedback to the user that the isotope hypothesis is wrong.

An automated isotope identification capability would match observed resonance dip positions against known ENDF resonance energies to identify which isotopes are present and (optionally) calibrate the energy axis.

Motivation

During development of the 2D imaging pipeline (#181), we initially assumed the LANL-ORNL test data contained Ta-181 + U-235 at 13–343 eV. SAMMY fitted this without complaint, producing chi2 ~13,400 and U-235 abundance of 1.52. Only after receiving metadata from collaborators did we learn the actual composition was U-235 + Pu-241 at 1–50 eV. With the correct metadata, chi2 dropped to ~5,700 and abundances became physically reasonable.

This experience highlights the need for automated resonance fingerprinting so users can:

1. Identify unknown isotopes from transmission spectra
2. Validate their isotope hypotheses before committing to expensive batch SAMMY fitting
3. Calibrate or verify the energy axis

Proposed Approach

Phase 1: Resonance dip detection

• Extract transmission dip positions from a representative spectrum (or mean spectrum)
• Use scipy.signal.find_peaks on inverted transmission to locate resonance centers
• Characterize each dip by position, depth, and width

Phase 2: Database matching

• Build a lookup table of known resonance energies from ENDF for common isotopes (actinides, structural metals, etc.)
• Score each candidate isotope by how many of its known resonances match observed dips (within tolerance)
• Rank candidates by match rate and present top-N suggestions with confidence scores

Phase 3: Energy axis calibration (if unknown)

• Given a candidate isotope with strong, well-separated resonances, use the known resonance energies and observed bin positions to fit a linear (or polynomial) energy-vs-bin mapping
• Cross-validate by checking whether additional isotope resonances align under the calibrated axis

Phase 4: Integration with imaging pipeline

• Add an identify_isotopes() function that takes a HyperspectralData object and returns ranked isotope candidates
• Optionally integrate as a pre-check in analyze_imaging() to warn users if their specified isotopes don't match the observed resonance pattern

Verification approach from Issue #181

During the metadata verification for the 2D imaging notebook, we demonstrated the feasibility of this approach:

• With the correct energy axis (1–50 eV), 94% of known U-235 resonances and 70% of known Pu-241 resonances matched observed dips in the TIFF data
• This was done with a simple find_peaks + distance-matching script in ~30 lines of code
• A production implementation would need better peak characterization, multi-isotope deconvolution, and confidence scoring

Acceptance Criteria

• Function that detects resonance dips from a transmission spectrum
• Database of known resonance energies for common isotopes (from ENDF)
• Scoring/ranking algorithm that identifies candidate isotopes
• Energy axis calibration from matched resonance positions
• Unit tests with synthetic spectra containing known isotopes
• Integration with HyperspectralData and the imaging pipeline

Related Issues

• Create high-level imaging API for users #181 — High-level API for 2D resonance imaging (where this limitation was discovered)
• [Epic] 2D Resonance Imaging - Abundance Mapping #172 — 2D imaging epic