From 052a01980a444cf9098596aac31d33a575962635 Mon Sep 17 00:00:00 2001
From: Evgeniy Unzhakov <unzhakov_ev@pnpi.nrcki.ru>
Date: Fri, 17 Apr 2026 15:27:26 +0300
Subject: [PATCH] Initial README

To be edited
---
 README.md | 304 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 304 insertions(+)

diff --git a/README.md b/README.md
index e69de29..32f74f7 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,304 @@
+# Beta Spectrum Calculation Toolkit
+
+## Overview
+
+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.
+
+---
+
+## Core Concept
+
+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)
+]
+
+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
+
+---
+
+## 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/
+│
+├── pyproject.toml
+├── README.md
+```
+
+---
+
+## Architecture
+
+### `SpectrumComponent` (base class)
+
+Defined in `base.py`.
+
+All physics corrections inherit from this class and implement:
+
+```python
+def __call__(self, W: np.ndarray) -> np.ndarray
+```
+
+This makes every component:
+
+* stateless (or minimally stateful)
+* vectorized
+* composable
+
+---
+
+### `Spectrum`
+
+Defined in `spectrum.py`.
+
+Responsible for:
+
+* combining all components
+* evaluating the total spectrum
+* managing energy grids
+
+Typical usage pattern:
+
+```python
+spectrum = Spectrum(
+    components=[
+        PhaseSpace(W0),
+        FermiFunction(Z),
+        ScreeningCorrection(Z),
+        ExchangeCorrection(Z),
+        RadiativeCorrection(W0),
+    ]
+)
+
+values = spectrum(W)
+```
+
+---
+
+## Components
+
+Each correction is implemented as an independent module under:
+
+```
+beta_spectrum/components/
+```
+
+---
+
+### Phase Space (`phase_space.py`)
+
+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 ).
+
+---
+
+## Notebooks
+
+Located in:
+
+```
+notebooks/
+```
+
+Used for:
+
+* testing corrections individually
+* plotting spectra
+* debugging numerical behavior
+
+---
+
+## Design Principles
+
+### 1. Modularity
+
+Each physical effect is isolated in its own component.
+
+---
+
+### 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
+
+---
+
+### 3. Vectorization
+
+All components operate on NumPy arrays:
+
+* no Python loops in hot paths
+* efficient evaluation over dense grids
+
+---
+
+### 4. Extensibility
+
+New corrections can be added by subclassing:
+
+```python
+class NewCorrection(SpectrumComponent):
+    def __call__(self, W):
+        return ...
+```
+
+---
+
+## Typical Workflow
+
+1. Define endpoint energy ( W_0 )
+2. Construct energy grid
+3. Initialize components
+4. Combine into spectrum
+5. Evaluate and plot
+
+---
+
+## Future Extensions
+
+Planned improvements include:
+
+* support for multiple decay branches
+* nuclear shape factor implementations
+* improved atomic corrections
+* validation against reference spectra
+* export utilities and CLI tools
+
+---
+
+## Notes
+
+* Units are typically expressed in natural units ( m_e = 1 )
+* Energies can be converted from MeV externally
+* 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.