unzhakov
dc8e26403b
Remove gA-extraction notes, nuclear-structure notes, paper-summary refs, detector-response correction note and the finished test migration checklist. Rewrite the vault index for the single-package theory calculator; repoint dangling wiki-links in surviving notes to inline citations; refresh docs_check.py (drop bs_exp CLI check, register removed files). Literature and nuclear-structure research resumes in dedicated projects; the removed notes are recoverable from history.
167 lines
8.8 KiB
Markdown
167 lines
8.8 KiB
Markdown
# 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
|