From 40d083605609dad8e48eea00bf9e257f4a2aba0e Mon Sep 17 00:00:00 2001 From: Evgeniy Unzhakov Date: Wed, 30 Sep 2026 03:11:05 +0300 Subject: [PATCH] docs: document core spectrum, physical branch columns, CSV-driven plots --- README.md | 11 +++++++++-- TODO.md | 4 ++++ 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4822f3b..4321a54 100644 --- a/README.md +++ b/README.md @@ -122,12 +122,19 @@ Defined in `beta_spectrum/spectrum.py`. Orchestrates the calculation: In `beta_spectrum.output`. Provides debugging and visualization tools: -- `total_spectrum(normalize=True/False)` — computed spectrum array +- `total_spectrum(normalize=True/False)` — computed spectrum array; raises `ValueError` when every branch is degenerate (non-positive integral) +- `physical_branch_spectrum(i)` — physical spectrum of branch *i*: the core (phase space × Fermi function) times every enabled higher-order correction, clamped beyond the branch endpoint (unnormalized) +- `universal_factor()` — product of the components shared across all branches (Fermi function and the universal higher-order corrections) - `plot_analysis(save_path=None, show_components=True)` — plot with two modes: - `show_components=True` (debug mode): 4-panel figure (spectrum, components, cumulative effect, deviations) - `show_components=False` (normal mode): single spectrum plot with nuclear data header - All plots include commit hash and UTC timestamp for traceability -- `export_to_csv(filename)` — export via pandas DataFrame with YAML-style metadata header + - Plots are built *from the exported CSV file* (temporary full-verbosity export), so a plot always shows exactly the bytes the CSV export produces +- `export_to_csv(filename)` — export via pandas DataFrame with YAML-style metadata header: + - the basic spectrum is always the core `phase_space × fermi` (the header carries a `# core:` line); finite size, charge distribution, screening, exchange and radiative are higher-order corrections + - `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 `normalize_to_one=True` each branch column integrates to 1 (intensity ignored, no total 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 ______________________________________________________________________ diff --git a/TODO.md b/TODO.md index f857d41..ec2e097 100644 --- a/TODO.md +++ b/TODO.md @@ -101,6 +101,10 @@ output/ ← output, visualization, CSV export - [x] 322 tests pass - [x] README updated with new architecture diagram and Quick Start examples - [x] Version bumped to 0.4.0 +- [ ] Decide: restore or delete the `detector_response` module — it was removed from + `beta_spectrum/components/` together with its tests, but `fitter/model.py` keeps a + duck-typed optional hook and `DEFAULT_JSON_SCHEMA` keeps the detector keys; + restore from git history (commits up to `5f99566`) if convolution is needed again ______________________________________________________________________