Add Obsidian knowledge base (docs/) and update README with docs structure
This commit is contained in:
@@ -1,16 +1,13 @@
|
||||
# Beta Spectrum Calculation Toolkit
|
||||
|
||||
## Overview
|
||||
A modular Python package for calculating high-precision **beta decay energy spectra**. It models the spectral shape of nuclear transitions by combining well-established physical corrections into a coherent, configurable pipeline.
|
||||
|
||||
This project provides a modular and extensible framework for calculating high-precision **beta decay energy spectra**. It is designed to model the spectral shape of a given nuclear transition by combining well-established physical corrections into a coherent and configurable pipeline.
|
||||
|
||||
The primary goal is to enable accurate numerical evaluation of the beta spectrum:
|
||||
|
||||
* from near-zero kinetic energies up to the endpoint
|
||||
* with controlled inclusion of higher-order corrections
|
||||
* using a clean, composable architecture
|
||||
|
||||
The framework focuses purely on **spectrum formation**, independent of any specific experimental or phenomenological application.
|
||||
**Features:**
|
||||
* Numerical evaluation from near-zero kinetic energies up to the endpoint
|
||||
* Selective inclusion of higher-order corrections via `SpectrumConfig` toggles
|
||||
* Clean, composable component architecture
|
||||
* Built-in visualization and CSV export via `BetaSpectrumAnalyzer`
|
||||
* Comprehensive scientific reference in [`docs/`](docs/)
|
||||
|
||||
---
|
||||
|
||||
@@ -18,56 +15,48 @@ The framework focuses purely on **spectrum formation**, independent of any speci
|
||||
|
||||
The beta spectrum is constructed as a product of independent correction factors:
|
||||
|
||||
[
|
||||
N(W) \propto p W (W_0 - W)^2 \times \prod_i C_i(W)
|
||||
]
|
||||
$$N(W) \propto p W (W_0 - W)^2 \times \prod_i C_i(W)$$
|
||||
|
||||
Each correction is implemented as a standalone component:
|
||||
|
||||
* phase space
|
||||
* Coulomb interaction (Fermi function)
|
||||
* finite nuclear size
|
||||
* screening
|
||||
* exchange
|
||||
* radiative corrections
|
||||
* recoil effects
|
||||
|
||||
This modular approach allows:
|
||||
|
||||
* easy validation of individual corrections
|
||||
* selective enabling/disabling of physics effects
|
||||
* flexible extension with new components
|
||||
Each $C_i(W)$ is an independently implemented and toggleable component.
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
beta_corr_pnpi/
|
||||
├── beta_spectrum/
|
||||
│ ├── base.py
|
||||
│ ├── spectrum.py
|
||||
│ ├── constants.py
|
||||
│ ├── utils.py
|
||||
│ │
|
||||
│ ├── components/
|
||||
│ │ ├── phase_space.py
|
||||
│ │ ├── fermi.py
|
||||
│ │ ├── finite_size.py
|
||||
│ │ ├── screening.py
|
||||
│ │ ├── exchange.py
|
||||
│ │ ├── radiative.py
|
||||
│ │ └── recoil.py
|
||||
│ │
|
||||
│ ├── data/
|
||||
│ │ └── exchange_coeff.csv
|
||||
│ │
|
||||
│ └── __init__.py
|
||||
│
|
||||
├── tests/
|
||||
│
|
||||
beta_shape_pnpi/
|
||||
├── pyproject.toml
|
||||
├── README.md
|
||||
├── docs/ # Obsidian knowledge base (physics theory & references)
|
||||
│ ├── README.md # Vault overview + navigation index
|
||||
│ ├── Hayen2017_summary.md # Full paper summary backbone
|
||||
│ ├── 00-beta-spectrum-overview.md # Master equation, all corrections table
|
||||
│ ├── 01-fermi-function.md # Fermi function F₀(Z,W)
|
||||
│ ├── 02-phase-space.md # Phase space p·W·(W₀−W)²
|
||||
│ ├── 03-finite-size.md # L₀, U, DFS corrections
|
||||
│ ├── 04-screening-correction.md # Atomic screening S(Z,W)
|
||||
│ ├── 05-exchange-correction.md # Electron exchange X(Z,W)
|
||||
│ ├── 06-radiative-corrections.md # Outer radiative δᵣ(W,W₀)
|
||||
│ ├── 07-recoil-effects.md # Weak magnetism, recoil kinematics
|
||||
│ ├── 10-nuclear-structure.md # Shape factor C(Z,W), BB vs HS formalisms
|
||||
│ ├── 12-atomic-overlap.md # Bahcall correction r(Z,W)
|
||||
│ ├── 13-chemical-effects.md # Molecular environment effects
|
||||
│ └── refs-hayen2017.md # Key equations reference table, citations
|
||||
├── beta_spectrum/
|
||||
│ ├── __init__.py # Public API: constants, utilities, classes
|
||||
│ ├── base.py # Abstract SpectrumComponent base class
|
||||
│ ├── constants.py # Physical constants (natural units, m_e = 1)
|
||||
│ ├── utils.py # Helpers: T<->W conversion, momentum, nuclear radius
|
||||
│ ├── spectrum.py # BetaSpectrum + BetaSpectrumAnalyzer classes
|
||||
│ └── components/
|
||||
│ │ ├── phase_space.py ✓ Phase space shape (p·W·(W₀−W)²)
|
||||
│ │ ├── fermi.py ✓ Coulomb correction (loggamma for stability)
|
||||
│ │ ├── finite_size.py ✓ L0 expansion + charge distribution U term
|
||||
│ │ ├── screening.py ✓ Atomic electron screening (ratio method)
|
||||
│ │ ├── exchange.py ✓ Hayen-2018 empirical fit coefficients
|
||||
│ │ ├── radiative.py ✓ Outer radiative corrections, soft-photon resummation
|
||||
│ │ └── recoil.py ✗ Not yet implemented
|
||||
└── data/
|
||||
└── exchange_coeff.csv # Tabulated coefficients for X(Z,W), Z=2..120
|
||||
```
|
||||
|
||||
---
|
||||
@@ -76,163 +65,109 @@ beta_corr_pnpi/
|
||||
|
||||
### `SpectrumComponent` (base class)
|
||||
|
||||
Defined in `base.py`.
|
||||
|
||||
All physics corrections inherit from this class and implement:
|
||||
Defined in `beta_spectrum/base.py`. All physics corrections inherit from this abstract base and implement:
|
||||
|
||||
```python
|
||||
def __call__(self, W: np.ndarray) -> np.ndarray
|
||||
```
|
||||
|
||||
This makes every component:
|
||||
This makes every component stateless (or minimally stateful), vectorized, and composable.
|
||||
|
||||
* stateless (or minimally stateful)
|
||||
* vectorized
|
||||
* composable
|
||||
### `BetaSpectrum`
|
||||
|
||||
Defined in `beta_spectrum/spectrum.py`. Orchestrates the calculation:
|
||||
* Combines components multiplicatively via `__call__(W)`
|
||||
* Factory method `from_config(config)` for declarative setup
|
||||
* Generates energy grids with `get_energy_grid(config)`
|
||||
* Returns individual component values via `calculate_components(W)`
|
||||
|
||||
### `BetaSpectrumAnalyzer`
|
||||
|
||||
Also in `spectrum.py`. Provides debugging and visualization tools:
|
||||
* `total_spectrum(normalize=True/False)` — computed spectrum array
|
||||
* `plot_analysis(save_path=None)` — 4-panel matplotlib figure (spectrum, components, cumulative effect, deviations from unity)
|
||||
* `export_to_csv(filename)` — export via pandas DataFrame
|
||||
* `get_data()` — return all numerical data for custom analysis
|
||||
|
||||
---
|
||||
|
||||
### `Spectrum`
|
||||
|
||||
Defined in `spectrum.py`.
|
||||
|
||||
Responsible for:
|
||||
|
||||
* combining all components
|
||||
* evaluating the total spectrum
|
||||
* managing energy grids
|
||||
|
||||
Typical usage pattern:
|
||||
## Quick Start
|
||||
|
||||
```python
|
||||
spectrum = Spectrum(
|
||||
components=[
|
||||
PhaseSpace(W0),
|
||||
FermiFunction(Z),
|
||||
ScreeningCorrection(Z),
|
||||
ExchangeCorrection(Z),
|
||||
RadiativeCorrection(W0),
|
||||
]
|
||||
from beta_spectrum import SpectrumConfig, BetaSpectrum, BetaSpectrumAnalyzer
|
||||
|
||||
config = SpectrumConfig(
|
||||
Z_parent=90, # Thorium-232 (example)
|
||||
Z_daughter=91,
|
||||
A_number=232,
|
||||
endpoint_MeV=4.8, # Q-value
|
||||
)
|
||||
|
||||
spectrum = BetaSpectrum.from_config(config)
|
||||
W, E_MeV = spectrum.get_energy_grid(config)
|
||||
values = spectrum(W)
|
||||
|
||||
analyzer = BetaSpectrumAnalyzer(spectrum, config)
|
||||
analyzer.plot_analysis() # Show/ save 4-panel figure
|
||||
analyzer.export_to_csv("output.csv") # Export data to CSV
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Components
|
||||
|
||||
Each correction is implemented as an independent module under:
|
||||
| Component | Module | Status | Description |
|
||||
|---|---|---:|---|
|
||||
| Phase Space | `phase_space.py` | ✓ | Baseline $p W (W_0 - W)^2$, optional neutrino mass support |
|
||||
| Fermi Function | `fermi.py` | ✓ | Relativistic Coulomb correction via `scipy.special.loggamma` |
|
||||
| Finite Size L0 | `finite_size.py` | ✓ | Low-Z expansion from Hayen et al. with prefactor |
|
||||
| Charge Distribution U | `finite_size.py` | ✓ | Second-order $(1/5)(\alpha Z W R)^2$ correction |
|
||||
| Screening | `screening.py` | ✓ | Ratio method with logistic switching, energy shift $V_0$ |
|
||||
| Exchange | `exchange.py` | ✓ | Hayen-2018 Table X empirical fit (CSV data for Z=2..120) |
|
||||
| Radiative | `radiative.py` | ✓ | Outer radiative corrections (Hayen Eq. 47–53), soft-photon resummation at endpoint |
|
||||
| Recoil | `recoil.py` | ✗ | Stub only, not yet implemented |
|
||||
|
||||
```
|
||||
beta_spectrum/components/
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
Use `SpectrumConfig` to selectively enable/disable each correction:
|
||||
|
||||
```python
|
||||
config = SpectrumConfig(
|
||||
Z_parent=20, Z_daughter=21, A_number=40, endpoint_MeV=5.0,
|
||||
use_fermi=True,
|
||||
use_screening=False, # disable atomic screening
|
||||
use_exchange=True,
|
||||
use_radiative=True,
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase Space (`phase_space.py`)
|
||||
## Dependencies
|
||||
|
||||
Implements:
|
||||
|
||||
[
|
||||
p W (W_0 - W)^2
|
||||
]
|
||||
|
||||
Provides the baseline spectral shape.
|
||||
|
||||
---
|
||||
|
||||
### Fermi Function (`fermi.py`)
|
||||
|
||||
Accounts for Coulomb interaction between the emitted electron and nucleus.
|
||||
|
||||
---
|
||||
|
||||
### Finite Size (`finite_size.py`)
|
||||
|
||||
Corrects for non-pointlike nuclear charge distribution.
|
||||
|
||||
---
|
||||
|
||||
### Screening (`screening.py`)
|
||||
|
||||
Includes atomic electron screening effects.
|
||||
|
||||
* modifies low-energy behavior
|
||||
* becomes negligible at high energies
|
||||
|
||||
---
|
||||
|
||||
### Exchange (`exchange.py`)
|
||||
|
||||
Accounts for electron exchange with atomic orbitals.
|
||||
|
||||
* dominant at very low energies
|
||||
* requires empirical coefficients (loaded from CSV)
|
||||
|
||||
---
|
||||
|
||||
### Radiative (`radiative.py`)
|
||||
|
||||
Implements outer radiative corrections:
|
||||
|
||||
* based on analytical expressions
|
||||
* includes optional endpoint resummation
|
||||
* handles logarithmic divergences near endpoint
|
||||
|
||||
---
|
||||
|
||||
### Recoil (`recoil.py`)
|
||||
|
||||
Includes nuclear recoil corrections.
|
||||
|
||||
---
|
||||
|
||||
## Data Files
|
||||
|
||||
### `exchange_coeff.csv`
|
||||
|
||||
Contains tabulated coefficients for exchange correction.
|
||||
|
||||
Loaded dynamically based on nuclear charge ( Z ).
|
||||
**Runtime:** numpy, scipy (for `loggamma`, `spence`), matplotlib (plotting), pandas (CSV export)
|
||||
**Dev:** pytest, black, ruff, mypy (strict mode configured in `pyproject.toml`)
|
||||
|
||||
---
|
||||
|
||||
## Design Principles
|
||||
|
||||
### 1. Modularity
|
||||
|
||||
Each physical effect is isolated in its own component.
|
||||
|
||||
---
|
||||
Each physical effect is isolated in its own component under `beta_spectrum/components/`.
|
||||
|
||||
### 2. Numerical Stability
|
||||
|
||||
Special care is taken near:
|
||||
|
||||
* ( W \to 1 ) (threshold)
|
||||
* ( W \to W_0 ) (endpoint)
|
||||
|
||||
Typical strategies include:
|
||||
|
||||
* small epsilon regularization
|
||||
* safe evaluation of logarithms and powers
|
||||
* masking invalid regions
|
||||
|
||||
---
|
||||
Care near $W \to 1$ (threshold) and $W \to W_0$ (endpoint):
|
||||
* `np.clip` / epsilon floors for regularization
|
||||
* Safe logarithms via `scipy.special.loggamma` and dilogarithm
|
||||
* Masking invalid regions
|
||||
|
||||
### 3. Vectorization
|
||||
|
||||
All components operate on NumPy arrays:
|
||||
|
||||
* no Python loops in hot paths
|
||||
* efficient evaluation over dense grids
|
||||
|
||||
---
|
||||
All components operate on NumPy arrays — no Python loops in hot paths.
|
||||
|
||||
### 4. Extensibility
|
||||
|
||||
New corrections can be added by subclassing:
|
||||
New corrections are added by subclassing:
|
||||
|
||||
```python
|
||||
class NewCorrection(SpectrumComponent):
|
||||
@@ -242,47 +177,39 @@ class NewCorrection(SpectrumComponent):
|
||||
|
||||
---
|
||||
|
||||
## Typical Workflow
|
||||
## Development Status
|
||||
|
||||
1. Define endpoint energy ( W_0 )
|
||||
2. Construct energy grid
|
||||
3. Initialize components
|
||||
4. Combine into spectrum
|
||||
5. Evaluate and plot
|
||||
**Version:** 0.1.2
|
||||
**Status:** Active development — core physics engine is functional; recoil correction and tests remain incomplete.
|
||||
|
||||
### Remaining Work
|
||||
|
||||
* Implement nuclear recoil correction in `recoil.py` (see [[07-recoil-effects]])
|
||||
* Add unit / integration tests (pytest configured but no test files)
|
||||
* Declare pandas as a runtime dependency in `pyproject.toml`
|
||||
* Satisfy mypy strict type-checking requirements
|
||||
* CLI entry point and multiple decay branch support
|
||||
|
||||
---
|
||||
|
||||
## Future Extensions
|
||||
## Knowledge Base
|
||||
|
||||
Planned improvements include:
|
||||
The [`docs/`](docs/) directory contains the complete scientific reference for beta spectrum shape corrections, organized as an Obsidian vault. It is structured around Hayen et al., *Rev. Mod. Phys.* **90**, 015008 (2017) and maps directly to calculator components:
|
||||
|
||||
* support for multiple decay branches
|
||||
* nuclear shape factor implementations
|
||||
* improved atomic corrections
|
||||
* validation against reference spectra
|
||||
* export utilities and CLI tools
|
||||
| # | Note | Calculator Module | Status |
|
||||
|---|------|-------------------|--------|
|
||||
| 1 | [[01-fermi-function]] | `components/fermi.py` | ✓ implemented |
|
||||
| 2 | [[03-finite-size]] | `components/finite_size.py` | ✓ implemented |
|
||||
| 3 | [[04-screening-correction]] | `components/screening.py` | ✓ implemented |
|
||||
| 4 | [[05-exchange-correction]] | `components/exchange.py` | ✓ implemented |
|
||||
| 5 | [[06-radiative-corrections]] | `components/radiative.py` | ✓ implemented |
|
||||
| 6 | [[07-recoil-effects]] | `components/recoil.py` | ✗ not yet implemented |
|
||||
|
||||
Notes prefixed with `10-`, `12-`, `13-` cover nuclear structure, atomic overlap, and chemical effects — important for future extensions but outside the current calculator scope.
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
* Units are typically expressed in natural units ( m_e = 1 )
|
||||
* Energies can be converted from MeV externally
|
||||
* Physical constants are defined in natural units ($m_e = 1$); energies can be converted from MeV via utilities in `utils.py`
|
||||
* The framework assumes familiarity with beta decay theory
|
||||
|
||||
---
|
||||
|
||||
## License / Usage
|
||||
|
||||
(To be defined)
|
||||
|
||||
---
|
||||
|
||||
## Author Notes
|
||||
|
||||
This project is under active development and serves both as:
|
||||
|
||||
* a computational tool
|
||||
* a structured reference for beta spectrum calculations
|
||||
|
||||
Updates may refine both physics implementations and code structure.
|
||||
|
||||
Reference in New Issue
Block a user