docs: rewrite README, TODO, AGENTS and CONVENTIONS to theory-only scope

Compactify the descriptive markdown: scope statement replaces the g_V-extraction goal, package architecture describes the single theory-only distributable, roadmap keeps calculator capabilities (C1-C8) and drops the analysis tracks, structure trees match the actual file layout, the bs_exp debug step and detector-parameter convention wording are dropped.
2026-10-05 17:20:27 +03:00
parent e8b73eb20f
commit 6aced1d8ac
4 changed files with 147 additions and 376 deletions
@@ -2,6 +2,8 @@

 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.

+Since v0.5.0 the project scope is the spectrum-shape **calculation** alone: detector response modeling, data calibration and fitting/extraction live in separate, dedicated projects.
+
 **Features:**

 - Numerical evaluation from near-zero kinetic energies up to the endpoint
@@ -11,6 +13,8 @@ A modular Python package for calculating high-precision **beta decay energy spec
  - Normal mode: single spectrum plot with nuclear data header
  - Debug mode (`-vv`): 4-panel view with all correction factors
  - All plots include commit hash and UTC timestamp for traceability
+- Multi-branch decays with intensity weighting and per-branch endpoints
+- Nuclear data retrieval from ENSDF via paceENSDF (`bs_pnpi --nuclide Tc99`)
 - Comprehensive scientific reference in [`docs/`](docs/)
 - Debug verification workflow: `bs_pnpi -vv` validates all parameters end-to-end

@@ -22,7 +26,7 @@ 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 $C_i(W)$ is an independently implemented and toggleable component.
+Each $C_i(W)$ is an independently implemented and toggleable component. The phase space and the Fermi function are the unconditional core: every spectrum carries their product, and the higher-order corrections multiply on top of it.

 ______________________________________________________________________

@@ -31,67 +35,46 @@ ______________________________________________________________________
 ```
 beta_shape_pnpi/
 ├── pyproject.toml
-├── docs/                          # Obsidian knowledge base (physics theory & references)
-│   ├── README.md                  # Vault overview + navigation index
-│   ├── 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
-│   ├── 08-detector-response.md        # Detector response models
-│   ├── 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
-├── beta_spectrum/           ← pure theory core
-│   ├── __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 + SpectrumConfig + BranchConfig
-│   ├── nuclear_data.py      # paceENSDF integration + JSON input support
-│   ├── cli.py               # Command-line interface (bs_pnpi)
-│   ├── logging_utils.py     # Structured logging helpers
-│   └── 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
-├── beta_spectrum/output/    ← output, plotting, visualization, CSV export
-│   ├── __init__.py          # BetaSpectrumAnalyzer, CSVEmitter, Visualizer
-│   ├── core.py              # BetaSpectrumAnalyzer base class
-│   ├── csv_export.py        # CSV export functionality
-│   └── visualization.py     # Plotting and visualization functionality
-├── exp_data/                ← experimental data handling
-│   ├── __init__.py          # ExpSpectrum, EnergyCalibrator, GaussianFitter, etc.
-│   ├── spectrum.py          # ExpSpectrum dataclass (energies, counts, errors, metadata)
-│   ├── calibration.py       # EnergyCalibrator (linear/quadratic channel→energy)
-│   ├── fitters.py           # GaussianFitter + PeakFitter for cal sources
-│   └── corrections.py       # DeadTimeCorrection, PileUpCorrection, BackgroundSubtractor
-├── fitter/                  ← analysis framework
-│   ├── __init__.py          # SpectrumModel, SpectrumFitter, CWExtractor, etc.
-│   ├── model.py             # SpectrumModel (BetaSpectrum + DetectorResponse wrapper)
-│   ├── fit_engine.py        # SpectrumFitter + CurveFitter + FitConfig + FitResult
-│   ├── extractor.py         # CWExtractor, GVAExtractor, CWExtractionResult, GVAExtractionResult
-│   └── result.py            # AnalysisResult + FitSummary
-├── tests/
-│   ├── exp_data/            # exp_data module tests
-│   ├── fitter/              # fitter module tests
-│   ├── physics/             # Physics component tests
-│   ├── quality/             # Code quality tests (logging, API, nuclear data)
-│   ├── integration/         # Full pipeline integration tests
-│   └── common/              # Shared hypothesis + property tests
+├── docs/                          ← Obsidian knowledge base (physics theory)
+│   ├── README.md                  ← Vault overview + navigation index
+│   ├── 00-beta-spectrum-overview.md
+│   ├── 02-phase-space.md
+│   └── corrections/               ← One note per correction component
+├── beta_spectrum/                 ← theory-only core package
+│   ├── __init__.py                ← Public API
+│   ├── base.py                    ← Abstract SpectrumComponent base class
+│   ├── constants.py               ← Physical constants (natural units, m_e = 1)
+│   ├── utils.py                   ← T<->W conversion, momentum, nuclear radius
+│   ├── spectrum.py                ← BetaSpectrum + SpectrumConfig + BranchConfig
+│   ├── nuclear_data.py            ← paceENSDF integration + JSON input support
+│   ├── cli.py                     ← Command-line interface (bs_pnpi)
+│   ├── logging_utils.py           ← Structured logging helpers
+│   ├── 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
+│   ├── data/
+│   │   └── exchange_coeff.csv     ← Tabulated coefficients for X(Z,W), Z=2..120
+│   └── output/                    ← visualization, CSV export
+│       ├── core.py                ← BetaSpectrumAnalyzer
+│       ├── csv_export.py          ← CSV export
+│       └── visualization.py       ← Plotting built from exported CSV
 ├── data/
-│   ├── exchange_coeff.csv         # Tabulated coefficients for X(Z,W), Z=2..120
-│   └── custom_input_example.json  # Sample JSON input file
-├── output/                      # Test run outputs (gitignored except .gitkeep)
-├── AGENTS.md                    # Agent instructions: stack, git workflow, TDD, quality gates
-├── CONVENTIONS.md               # Physics conventions: natural units, energy representation, component design
-├── TODO.md                      # Development roadmap
+│   └── custom_input_example.json  ← Sample JSON input file
+├── notebooks/                     ← Calculator notebook + nbmake conftest
+├── output/                        ← Test run outputs (gitignored except .gitkeep)
+├── tests/
+│   ├── physics/                   ← Physics component tests
+│   ├── quality/                   ← Code quality tests (logging, API, nuclear data)
+│   ├── integration/               ← CLI and pipeline integration tests
+│   └── common/                    ← Shared hypothesis + property tests
+├── scripts/                       ← docs_check.py, notebook runners
+├── AGENTS.md                      ← Agent instructions: stack, git workflow, TDD, quality gates
+├── CONVENTIONS.md                 ← Physics conventions: natural units, energy representation, component design
+├── TODO.md                        ← Development roadmap
 ```

 ______________________________________________________________________
@@ -134,7 +117,7 @@ In `beta_spectrum.output`. Provides debugging and visualization tools:
  - `branch_{i}_spectrum` columns contain the *physical* branch spectra weighted by intensity and normalized so that the sum of branch columns equals `total_spectrum`
  - with `separate_branches=True` (CLI `--separate-branches`) each branch column integrates to 1 (intensity ignored, no total_spectrum column)
 - `parse_spectrum_csv(path)` — read an exported CSV and its metadata header (module function in `beta_spectrum.output.visualization`)
- `get_data()` — return all numerical data for custom analysis
+- `get_data()` — return all numerical data for downstream analysis

 ______________________________________________________________________

@@ -162,27 +145,21 @@ analyzer.plot_analysis("debug.png", show_components=True)  # Debug mode (4-panel
 analyzer.export_to_csv("spectrum.csv")   # Export data to CSV
 ```

-### Fitting and C(W) extraction
+### From the command line

-```python
-from beta_spectrum import SpectrumConfig, BetaSpectrum
-from fitter import SpectrumModel, SpectrumFitter, CWExtractor
-from exp_data.spectrum import ExpSpectrum
-
-# Build theoretical model
-spectrum = BetaSpectrum.from_config(config)
-model = SpectrumModel(spectrum, detector_response=detector)
-
-# Fit to experimental data
-exp = ExpSpectrum(energies=energies_keV, counts=counts, errors=errors)
-fitter = SpectrumFitter(model, exp.energies, exp.counts, exp.errors)
-result = fitter.fit(x0=[1.0, 0.0])
-
-# Extract C(W) shape factor
-extractor = CWExtractor(config)
-cw_result = extractor.extract(measured, errors, energies_keV, model_values, endpoint_keV=Q)
+```bash
+bs_pnpi --nuclide Tc99 -vv --output spectrum.csv   # ENSDF lookup + debug export
+bs_pnpi --input data/custom_input_example.json     # JSON-driven configuration
 ```

+CLI flags (`--e-step`, `--neutrino-mass`, `--intensity-cutoff`, `--csv-separator`, `--separate-branches`) override JSON input values only when explicitly given; every long option has a single-letter alias.
+
+______________________________________________________________________
+
+## Nuclear Data (paceENSDF)
+
+`beta_spectrum.nuclear_data` retrieves decay data automatically: `get_decay_info_from_paceENSDF()`, `decay_info_to_config()`, and `create_config_from_source("paceENSDF", nuclide="Tc99")`. Z, A, endpoint energies, half-life, spin/parity, branch intensities, log*ft and forbiddenness are populated from ENSDF; per-branch endpoints are the measured transition endpoint energies (max endpoint across branches defines the spectrum endpoint). paceENSDF is an optional extra: `pip install ".[ensdf]"`.
+
 ______________________________________________________________________

 ## Implementation Status
@@ -190,9 +167,6 @@ ______________________________________________________________________
 For a complete list of implemented and planned features, see [TODO.md](TODO.md). Key highlights:

 - **Physics corrections**: phase space, Fermi function, finite size, screening, exchange, radiative (with delta_cut resummation)
- **Detector response**: not implemented — `SpectrumModel` keeps a duck-typed optional convolution hook; the analytical models were removed (restore-or-delete decision tracked in TODO.md)
 - **Multi-branch decay**: intensity-weighted sum of branch spectra, per-branch calculators with branch-specific endpoint, transition type (from ENSDF), and `--intensity-cutoff` CLI filter
- **Analysis tools**: χ² fitter (SpectrumFitter + CurveFitter), C(W) extraction pipeline, Kurie plot analysis, g_V/g_A extraction
- **Experimental data**: ExpSpectrum container, energy calibration, peak fitting, dead-time/pile-up correction
- **CLI**: `bs_pnpi --nuclide Tc99` — full paceENSDF integration (auto-lookup of Z, A, Q-value, transition type, half-life, branches, forbiddenness from ENSDF); for JSON input the file's values are used and CLI flags (`--e-step`, `--neutrino-mass`, `--intensity-cutoff`, `--csv-separator`, `--separate-branches`) override them only when explicitly given; every long option has a single-letter alias (`-N`, `-i`, `-s`, `-m`, `-o`, `-p`, `-L`, `-d`, `-c`, `-V`, `-S`, `-b`)
- **paceENSDF integration**: `get_decay_info_from_paceENSDF()`, `create_config_from_source("paceENSDF", nuclide="Tc99")`, `_parse_nuclide_symbol()` for Z=1..98, FORBIDDENNESS_MAP, `--nuclide` CLI flag; per-branch endpoints are the measured transition endpoint energies from ENSDF (max endpoint across branches defines the spectrum endpoint)
+- **CLI**: `bs_pnpi` with full paceENSDF integration, structured logging (`-v`/`-vv`/`-q`), `--dry-run`, `--version`, `--log-file`
+- **CSV metadata headers** with nuclide, decay and calculation parameters plus software version and git commit hash