# 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

- [x] paceENSDF integration: `get_decay_info_from_paceENSDF()`, `decay_info_to_config()`, `create_config_from_source()`, FORBIDDENNESS_MAP, `--nuclide` CLI flag
- [x] Measured per-branch transition endpoints from ENSDF (max endpoint across branches defines the spectrum endpoint)
- [x] 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

- [x] `BranchConfig` dataclass, multi-branch `BetaSpectrum` with per-branch calculators
- [x] Intensity normalization to 100% across branches; per-branch spectra masked beyond their endpoint
- [x] `--intensity-cutoff` CLI filter
- [x] Core invariant: phase space × Fermi function included unconditionally (`phase_space` and `fermi` have no toggles)
- [x] 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
- [x] Structured logging (`-v`, `-vv`, `-q`, `--log-file`)
- [x] CSV metadata headers (ISO timestamp, nuclide, decay, calculation params, version, commit hash)
- [x] `--dry-run`, `--version`, single-letter aliases for every long option
- [x] 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