From d8c521f6f82870aa3148ff484ffb1c0e98641fe6 Mon Sep 17 00:00:00 2001 From: Evgeniy Unzhakov Date: Sat, 2 May 2026 22:23:37 +0300 Subject: [PATCH] docs: update README with CLI, nuclear data integration, and additional modules --- README.md | 148 ++++++++++-------------------------------------------- 1 file changed, 27 insertions(+), 121 deletions(-) diff --git a/README.md b/README.md index 34f3209..0a63b89 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,10 @@ beta_shape_pnpi/ │ ├── constants.py # Physical constants (natural units, m_e = 1) │ ├── utils.py # Helpers: T<->W conversion, momentum, nuclear radius │ ├── spectrum.py # BetaSpectrum + BetaSpectrumAnalyzer classes +│ ├── nuclear_data.py # paceENSDF integration + JSON input support +│ ├── cli.py # Command-line interface (bs_pnpi) +│ ├── fitter.py # χ² curve fitting for C(W) extraction +│ ├── cw_extractor.py # C(W) shape factor extraction + gV/gA analysis │ └── components/ │ │ ├── phase_space.py ✓ Phase space shape (p·W·(W₀−W)²) │ │ ├── fermi.py ✓ Coulomb correction (loggamma for stability) @@ -55,17 +59,23 @@ beta_shape_pnpi/ │ │ ├── screening.py ✓ Atomic electron screening (ratio method) │ │ ├── exchange.py ✓ Hayen-2018 empirical fit coefficients │ │ ├── radiative.py ✓ Outer radiative corrections, soft-photon resummation +│ │ ├── detector_response.py ✓ Analytical detector response models │ │ └── recoil.py ✗ Not yet implemented ├── tests/ -│ ├── test_radiative.py # Radiative correction tests (24 tests) -│ ├── test_exchange.py # Exchange correction tests -│ ├── test_fermi.py # Fermi function tests -│ ├── test_finite_size.py # Finite size correction tests -│ ├── test_phase_space.py # Phase space tests -│ ├── test_screening.py # Screening correction tests -│ └── test_spectrum.py # Integration tests +│ ├── test_radiative.py # Radiative correction tests (24 tests) +│ ├── test_exchange.py # Exchange correction tests +│ ├── test_fermi.py # Fermi function tests +│ ├── test_finite_size.py # Finite size correction tests +│ ├── test_phase_space.py # Phase space tests +│ ├── test_screening.py # Screening correction tests +│ ├── test_spectrum.py # Integration tests +│ ├── test_detector_response.py# Detector response tests +│ ├── test_fitter.py # Curve fitter tests +│ ├── test_cw_extractor.py # C(W) extraction tests +│ └── test_nuclear_data.py # paceENSDF + JSON input tests (23 tests) └── data/ - └── exchange_coeff.csv # Tabulated coefficients for X(Z,W), Z=2..120 + ├── exchange_coeff.csv # Tabulated coefficients for X(Z,W), Z=2..120 + └── custom_input_example.json # Sample JSON input file ``` ______________________________________________________________________ @@ -133,122 +143,18 @@ ______________________________________________________________________ | Phase Space | `phase_space.py` | ✓ | Baseline $p W (W_0 - W)^2$ with transition-type-dependent forbidden factors and 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 | +| 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 | +| Detector Response | `detector_response.py` | ✓ | Analytical models: Gaussian, Gaussian+tail, Tikhonov, tabulated | | Recoil | `recoil.py` | ✗ | Stub only, not yet implemented | -______________________________________________________________________ +## Additional Modules -## 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, - transition_type="F1", # first forbidden non-unique - use_fermi=True, - use_screening=False, # disable atomic screening - use_exchange=True, - use_radiative=True, -) -``` - -______________________________________________________________________ - -## Transition Types - -The `transition_type` parameter in `SpectrumConfig` determines the **forbidden factor** applied to the phase space calculation. This encodes the angular momentum and parity selection rules for the nuclear transition: - -| Type | Name | Forbidden Order | $\\Delta J^\\pi$ | Forbidden Factor | -| ----- | ----------------------------- | --------------- | ------------------------------------- | --------------------------------------------------------- | -| `A` | Allowed | 0 | $0^+, 1^+$ | $1$ | -| `F1` | First forbidden (non-unique) | 1 | $0^-, 1^-, 2^\\pm$ | $p\_\\nu^2 + p_e^2$ | -| `F1U` | First forbidden (unique) | 1 | $2^-$ | $p\_\\nu^2 + p_e^2$ | -| `F2` | Second forbidden (non-unique) | 2 | $1^\\pm, 2^+, 3^\\pm$ | $p\_\\nu^4 + \\frac{3}{10}p\_\\nu^2 p_e^2 + p_e^4$ | -| `F2U` | Second forbidden (unique) | 2 | $3^-$ | $p\_\\nu^4 + \\frac{3}{10}p\_\\nu^2 p_e^2 + p_e^4$ | -| `F3` | Third forbidden (non-unique) | 3 | $0^\\pm, 1^\\pm, 2^\\pm, 3^+, 4^\\pm$ | $p\_\\nu^6 + 7p\_\\nu^4 p_e^2 + 7p\_\\nu^2 p_e^4 + p_e^6$ | -| `F3U` | Third forbidden (unique) | 3 | $4^-$ | $p\_\\nu^6 + 7p\_\\nu^4 p_e^2 + 7p\_\\nu^2 p_e^4 + p_e^6$ | -| `F4` | Fourth forbidden (unique) | 4 | $5^-$ | $p\_\\nu^6 + 7p\_\\nu^4 p_e^2 + 7p\_\\nu^2 p_e^4 + p_e^6$ | - -The forbidden factor multiplies the baseline phase space $p_e W_e p\_\\nu W\_\\nu$, modifying the spectral shape at higher energies. The even/odd suffix (`U`) distinguishes **unique** transitions (single contributing nuclear matrix element) from **non-unique** ones (multiple contributing matrix elements). - -> [!note] Shape factor -> For a complete treatment of forbidden transitions, the nuclear **shape factor** $C(Z,W)$ from `[[10-nuclear-structure]]` should also be included. This is not yet implemented in the calculator. - -## Dependencies - -**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 under `beta_spectrum/components/`. - -### 2. Numerical Stability - -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. - -### 4. Extensibility - -New corrections are added by subclassing: - -```python -class NewCorrection(SpectrumComponent): - def __call__(self, W): - return ... -``` - -______________________________________________________________________ - -## Development Status - -**Version:** 0.2.0\ -**Status:** Active development — core physics engine is functional with comprehensive test coverage. - -### Remaining Work - -- Implement nuclear recoil correction in `recoil.py` (see \[[07-recoil-effects]\]) -- Declare pandas as a runtime dependency in `pyproject.toml` -- Satisfy mypy strict type-checking requirements -- CLI entry point and multiple decay branch support -- Implement nuclear shape factors C(Z,W) for forbidden transitions -- Implement neutrino radiative corrections (Sirlin 2011) - -______________________________________________________________________ - -## Knowledge Base - -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: - -| # | 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 - -- 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 +| Module | Description | +| --------------------- | -------------------------------------------------------------------------------------------------------------- | +| `nuclear_data.py` | paceENSDF integration + JSON input for automated `SpectrumConfig` generation | +| `cli.py` | Command-line interface (`bs_pnpi`) for quick spectrum calculations | +| `fitter.py` | χ² curve fitting for C(W) shape factor extraction from experimental data | +| `cw_extractor.py` | C(W) extraction pipeline with gV/gA coupling constant analysis |