beta_shape_pnpi/TODO.md

Strategic Development Roadmap

Scientific Scope

High-precision calculation of beta-decay spectrum shapes. Given a nuclide, decay data and a set of correction toggles, the calculator produces C(W)-level spectral shapes accurate to a few parts in 10⁻⁴ down to 1 keV for low-to-medium Z nuclei (Hayen et al. approach).

For forbidden nonunique decays the shape factor C(W) enters the calculated spectrum as an input. Extracting C(W) from measured spectra and parametrizing it through coupling constants (SSM/SSNME, g_V/g_A fits, detector response modeling) is analysis work that lives in separate dedicated projects and is out of scope for this repository since v0.5.0.

---

Package Architecture (v0.5.0)

Single distributable, beta_spectrum:

beta_spectrum/               ← theory-only core package
│   ├── __init__.py          ← public API
│   ├── base.py              ← SpectrumComponent base
│   ├── constants.py         ← physical constants
│   ├── utils.py             ← T_to_W, W_to_T, momentum
│   ├── spectrum.py          ← BetaSpectrum, SpectrumConfig, BranchConfig
│   ├── nuclear_data.py      ← paceENSDF integration + JSON input
│   ├── cli.py               ← bs_pnpi command-line interface
│   ├── logging_utils.py     ← structured logging helpers
│   ├── components/          ← individual correction factors
│   │   ├── phase_space.py
│   │   ├── fermi.py
│   │   ├── finite_size.py
│   │   ├── screening.py
│   │   ├── exchange.py
│   │   └── radiative.py
│   ├── data/
│   │   └── exchange_coeff.csv
│   └── output/              ← visualization, CSV export subpackage
│       ├── core.py          ← BetaSpectrumAnalyzer
│       ├── csv_export.py    ← CSVEmitter
│       └── visualization.py ← Visualizer, parse_spectrum_csv

Rationale

• Pure theory. Given a nuclide and corrections, the package produces a theoretical spectrum. No fitting, no experimental data, no detector convolution.
• beta_spectrum.output is a calculation-output subpackage (plotting and CSV export of computed spectra), not data analysis.

Scope Reduction (v0.5.0)

• exp_data/ and fitter/ packages (experimental data handling, calibration, χ² fit engine, C(W)/g_V/g_A extraction), their tests, the bs_exp CLI and the ROOT extra: removed from this repository (restore from history up to 67de4e3 if an analysis project needs them).
• detector_response.py: removed earlier (up to 5f99566); the deletion decision is now final.
• data/raw/ local copies of detector runs and Am-241 calibration files: removed (canonical copies on experiment storage).
• docs/gA-extraction/, docs/nuclear-structure/, docs/refs/, docs/corrections/07-detector-response.md: removed; literature and nuclear-structure research is to be redone in dedicated projects.

---

Roadmap: Calculator Capability

C1. Nuclear Data & Input Flexibility

• paceENSDF integration: get_decay_info_from_paceENSDF(), decay_info_to_config(), create_config_from_source(), FORBIDDENNESS_MAP, --nuclide CLI flag
• Measured per-branch transition endpoints from ENSDF (max endpoint across branches defines the spectrum endpoint)
• JSON custom input (load_json_input(), json_to_config()), CLI flags override file values only when explicitly given
• Input sanity checks:
  • |Z_parent - Z_daughter| must equal 1 (beta decay)
  • For beta_minus: Z_daughter = Z_parent + 1; for beta_plus/ec: Z_daughter = Z_parent - 1
  • Warn if decay_type contradicts Z values
  • Validate endpoint_MeV > 0 and endpoint_MeV > level_energy_keV/1000
  • Cross-check transition_type against ENSDF forbiddenness

C2. Multiple Branch Decays

• BranchConfig dataclass, multi-branch BetaSpectrum with per-branch calculators
• Intensity normalization to 100% across branches; per-branch spectra masked beyond their endpoint
• --intensity-cutoff CLI filter
• Core invariant: phase space × Fermi function included unconditionally (phase_space and fermi have no toggles)
• Physical branch spectra and universal factor in CSV export; --separate-branches normalization mode

C3. Recoil and Weak Magnetism

Theory documented in docs/corrections/06-recoil.md; implementation pending.

• Implement recoil correction (R_N, Q terms, weak magnetism) as a SpectrumComponent

C4. Beta+ / Electron Capture Support

• Fermi function sign change for positrons
• Radiative corrections for β⁺ (Sirlin corrections differ for e⁻ vs e⁺)
• Screening correction for positrons (different atomic interaction)
• Exchange correction (negligible for β⁺ but check)

C5. Neutrino Spectrum Support

• Convenience analyser methods for plotting neutrino spectra (convert electron spectrum, plot both scaled)
• Neutrino radiative correction h(W̃, W0) per Sirlin 2011; conversion f_ν(W_ν) = f_e(W̃) · [1 + (α/2π)(h − g)]

C6. Neutrino Mass Effects

Implemented: neutrino_mass_MeV config field, modified phase space factor √(1 − m_ν²/(W₀−W)²), --neutrino-mass CLI option.

• Document which corrections need m_ν as an additional input parameter
• Study impact on radiative corrections (mass singularities)

C7. Automated Report Generation

• Procedurally generated PDF report for a calculation:
  • Parameter table (nuclide, decay data, enabled corrections, version, commit)
  • Component plots (phase space, Fermi, each correction factor)
  • Total spectrum with all corrections applied
  • References to theoretical sources

C8. CLI & Output Improvements

• Auto-deduce transition_type from nuclear data (remove as explicit parameter where possible)
• Auto-deduce decay_type from Z_parent vs Z_daughter difference
• Structured logging (-v, -vv, -q, --log-file)
• CSV metadata headers (ISO timestamp, nuclide, decay, calculation params, version, commit hash)
• --dry-run, --version, single-letter aliases for every long option
• Plots built from the exported CSV; commit hash + UTC timestamp stamps; normal/debug display modes

---

Deferred (Not Planned)

Additional Corrections

Additional corrections beyond the implemented set require complex implementation with project-wide consequences; deferred as far-future work.

Theoretical Shape Factors C(Z,W)

Never computed here. Shell-model / QRPA transition densities and effective interactions belong to nuclear-structure codes; this repository treats C(W) as an input parameter of the spectrum model. The dedicated research into nuclear shape factors will be redone in separate projects.

---

Current Status

Version: v0.5.0 — theory-only scope reduction. Calculation logic unchanged from v0.4.1.

Completed (v0.3.x — theory core)

• All implemented theoretical corrections: phase space, Fermi function, finite size, screening, exchange, radiative (with delta_cut resummation)
• Multi-branch decay support (unified single/multi-branch)
• CLI (bs_pnpi) with paceENSDF integration, structured logging, --dry-run, --version, --log-file
• CSV metadata headers with branch info
• paceENSDF DecayInfo retrieval (Z, A, endpoint, transition type, half-life, spin/parity, branches)
• Notebook quality control with nbmake and auto-save plot hooks
• Plot output: unified multi-branch approach, externalized headers, consistent titles

Completed (v0.4.0 — package split, later obsolete)

• Interim split into beta_spectrum / exp_data / fitter packages
• Superseded by the v0.5.0 scope reduction: the analysis packages were removed entirely

Completed (v0.4.1 — normalization & CLI)

• Core spectrum made unconditional (phase_space × fermi): core toggles removed, physical branch spectra in CSV export, plots built from the exported CSV
• Normalization audit fixes: lone surviving branch defines the spectrum, CLI options propagate through the JSON flow, positive-integral guard for both export modes, paceENSDF per-branch measured endpoints (Co60 fixed), single delegated paceENSDF config builder
• CLI surface refresh: --separate-branches rename, single-letter aliases, dry-run cleanup, stale detector_* JSON schema keys removed

Completed (v0.5.0 — scope reduction)

• Removal of exp_data/, fitter/, raw detector data, analysis notebooks/scripts
• Documentation rewrite to theory-only scope
• 280 tests pass (theory-only suite), ruff + mypy clean

Next Immediate Step

• C1 input sanity checks (decay/Z consistency, endpoint validation)
• C3 recoil & weak magnetism correction implementation