beta_shape_pnpi/docs/README.md

title, date, tags, status

title	date	tags	status
Beta Spectrum Calculator — Knowledge Base	2026-04-26	vault/overview	active

Beta Spectrum Calculator — Knowledge Base

This Obsidian vault is the scientific reference behind the beta-spectrum shape calculator (beta_spectrum). Since v0.5.0 the repository is dedicated solely to high-precision spectrum-shape calculation: detector response, data calibration, and fitting/extraction analyses are separate projects, and their literature was removed from this vault.

Purpose

Organize the physics theory behind β-decay spectrum calculations into structured, interconnected notes that inform the implementation of correction components in the codebase.

Key external references (cited inline in the notes): Hayen et al., Rev. Mod. Phys. 90, 015008 (2018); Sirlin (1967–2011); Hayen et al., J. Phys. G (2019) on first-forbidden transitions. Nuclear-structure shape-factor theory is external to this repository.

Directory Structure

docs/
├── README.md                          ← You are here
├── 00-beta-spectrum-overview.md       ← Master equation & full correction list
├── 02-phase-space.md                  ← Baseline spectral shape
├── test-architecture.md               ← Test organization & strategy
├── corrections/                       ← All correction components
│   ├── 01-fermi-function.md           ← Fermi function F₀(Z,W)
│   ├── 02-finite-size.md              ← Nuclear size: L₀, U, DFS
│   ├── 03-screening.md                ← Atomic screening S(Z,W)
│   ├── 04-exchange.md                 ← Atomic exchange X(Z,W)
│   ├── 05-radiative.md                ← Outer radiative R(W,W₀)
│   ├── 06-recoil.md                   ← Recoil: R_N, Q, weak magnetism
│   ├── 08-atomic-overlap.md           ← Atomic mismatch r(Z,W)
│   └── 09-chemical-effects.md         ← Molecular environment
└── (refs removed; literature research resumes in dedicated projects)

Calculator Architecture

SpectrumComponent (ABC, base.py)
 ├── PhaseSpace              → 02-phase-space.md
 ├── FermiFunction           → corrections/01-fermi-function.md
 ├── FiniteSizeL0            → corrections/02-finite-size.md
 ├── ChargeDistributionU     → corrections/02-finite-size.md
 ├── ScreeningCorrection     → corrections/03-screening.md
 ├── ExchangeCorrection      → corrections/04-exchange.md
 ├── RadiativeCorrection     → corrections/05-radiative.md
 └── (recoil component)      → corrections/06-recoil.md (not yet implemented)

BetaSpectrum (spectrum.py) — multiplicative composition + from_config()
BetaSpectrumAnalyzer (output/core.py) — plotting, CSV export

Correction Implementation Status

#	Correction	Module	Note	Status
1	Phase space	phase_space.py	Baseline	✓ implemented
2	Fermi function	fermi.py	Coulomb interaction	✓ implemented
3	Finite size	finite_size.py	L₀, U, DFS	✓ implemented
4	Screening	screening.py	Atomic screening	✓ implemented
5	Exchange	exchange.py	Atomic exchange	✓ implemented
6	Radiative	radiative.py	Outer RC	✓ implemented
7	Recoil	recoil.py	R_N, Q, weak magnetism	✗ not yet implemented
8	Shape factor	—	C(Z,W) is an input parameter (external nuclear-structure theory)	out of scope
9	Atomic overlap	—	r(Z,W)	documentation only
10	Chemical effects	—	molecular environment	documentation only

Key Variables and Units

• W — total electron energy in units of m_e c^2 (natural units, m_e = 1)
• T or E_{\text{kin}} — kinetic energy (keV or MeV)
• W_0 — endpoint total energy
• Z_{\text{parent}}, Z_{\text{daughter}} — atomic numbers
• \alpha \approx 1/137.036 — fine structure constant
• \gamma = \sqrt{1 - (\alpha Z)^2}

Conversion: W = 1 + T / m_e c^2, with m_e c^2 = 510.998950 keV.

Precision Goal

The calculator aims for accurate to a few parts in 10^{-4} down to 1 keV for low-to-medium Z nuclei, following the approach of Hayen et al. (2018).