Commit Graph
70 Commits
Author SHA1 Message Date
unzhakov b02159ba5c Remove repeated per-branch metadata columns from CSV export
Branch intensity, endpoint, and transition are constant per branch and
already documented in the CSV header. No need to repeat them as columns
for every energy row.
2026-05-08 15:41:10 +03:00
unzhakov 9eb58bf101 feat: multi-branch decay support (B3) — per-branch transition types, intensity cutoff, raw-value plotting
- Extract per-branch forbiddenness codes from ENSDF (not defaulting to 'A')
- BranchConfig dataclass with endpoint, transition type, intensity validation
- Multi-branch BetaSpectrum with per-branch calculators and universal components
- Raw (un-normalized) plotting so total = arithmetic sum of branches
- --intensity-cutoff CLI option to filter negligible branches
- Branch-aware CSV export with per-branch spectra and components
- 30 comprehensive tests covering validation, calculation, export, edge cases
2026-05-08 08:36:29 +03:00
unzhakov ef337073d6 docs: update TODO and README for B3 completion and BranchConfig export
- Cross out B3 in TODO.md with completion details
- Export BranchConfig in __init__.py public API
- Update README to mention per-branch transition types and intensity cutoff
2026-05-08 08:35:01 +03:00
unzhakov 69eca97736 test: comprehensive multi-branch decay test suite (30 tests)
- BranchConfig validation (intensity bounds, positive endpoint)
- Single-branch via multi-branch path compatibility
- Multi-branch spectrum calculation and intensity weighting
- Per-branch spectra with correct endpoint and transition type
- Component extraction (universal vs branch-dependent)
- CSV export with total, per-branch, and universal components
- Transition type propagation from BranchInfo
- Branch values <= total spectrum verification
- Branch integral proportionality to intensity
- High-Z multi-branch stability
- No-branches defaults to single-branch mode
2026-05-08 08:34:30 +03:00
unzhakov 6293710089 feat: multi-branch CLI with intensity cutoff and per-branch info
- Add --intensity-cutoff CLI option to filter negligible branches
- Fetch DecayInfo from paceENSDF and construct SpectrumConfig with
  branches including per-branch transition types
- Normalize branch intensities to sum to 1.0, filter by cutoff
- Display branch info in dry-run output and logging
- Add intensity_cutoff to SpectrumConfig
2026-05-08 08:33:39 +03:00
unzhakov 3216c50943 feat: per-branch transition types from ENSDF and raw-value plotting
- Add transition_type field to BranchInfo and extract per-branch
  forbiddenness codes from paceENSDF (not defaulting all to 'A')
- Fix _multi_branch_call to use np.maximum instead of np.where mask
  so branches smoothly approach zero at endpoint
- Rewrite _plot_multi_branch_spectra and _plot_multi_branch_debug Panel 1
  to plot raw (un-normalized) branch contributions so total = sum of branches
- Remove independent unit-area normalization that made small branches
  appear larger than total
2026-05-08 08:33:12 +03:00
unzhakov 572e222c78 Merge dev/cli-logging-refinement to main
- Fix paceENSDF Q-value extraction (was reading half-life as Q-value)
- Fix RadiativeCorrection Z/A parameters
- Add debug verification workflow (bs_pnpi -vv)
- Add plot output with ID tracking and two display modes
- Fix pyright/mypy type errors across codebase
- Add ./output/ directory for test artifacts
- Update docs and development workflow
2026-05-05 14:35:36 +03:00
unzhakov 4a3d31de83 Update docs and TODOs for CLI & plot improvements
- README.md: Add features for plot modes, traceability, debug workflow
- README.md: Update BetaSpectrumAnalyzer docs with show_components param
- README.md: Update Quick Start with both plot modes
- README.md: Add output/ to project structure
- TODO.md: Mark B8.4 plot output as completed
- TODO.md: Update Current Status with B8.4
2026-05-05 14:35:11 +03:00
unzhakov 5ac004352b Fix mypy type errors and black formatting
- spectrum.py: Use Axes from TYPE_CHECKING instead of plt.Axes
- fitter.py: Remove unused type: ignore comment
- phase_space.py: Black formatting
2026-05-05 14:01:28 +03:00
unzhakov d6328d4b24 Enhance plot output with ID tracking and two display modes
- Add commit hash (6 chars) and UTC timestamp to all plots via text boxes
- Add nuclear data header (nuclide, endpoint, transition, corrections) to plots
- Two display modes:
  - DEBUG (-vv): 4-panel debug view with all correction factors
  - Normal (default): single spectrum plot with nuclear data header
- CLI: --plot now passes show_components=(args.verbose >= 2)
2026-05-05 13:33:46 +03:00
unzhakov 3749220efc Fix pyright type errors and correct paceENSDF Q-value extraction
- nuclear_data.py: Extract Q-value from ground state branch state[7] instead of
  halflife_data (was reading half-life seconds as Q-value)
- nuclear_data.py: Use ground state branch for forbiddenness code, with fallback
- nuclear_data.py: Add None guards for beta_data and pairs
- spectrum.py: Pass Z=config.Z_daughter, A=config.A_number to RadiativeCorrection
- phase_space.py: Add __init__ debug logging (W0, transition_type, m_e, m_nu)
- phase_space.py: Add output range logging in __call__
- phase_space.py: Fix possibly unbound forbid_factor variable
- logging_utils.py: Fix broken get_git_short_hash indentation
- cli.py: Add explicit SpectrumConfig annotation to fix pyright type identity
- cw_extractor.py: Fix T_to_W ndarray→float conversions (6 locations)
- cw_extractor.py: Fix FermiFunction() calls — was passing Z as __call__ arg
- fitter.py: Add explicit dict type annotation for least_squares kwargs
2026-05-05 12:43:43 +03:00
unzhakov 297778d780 Add ./output/ directory for debug verification artifacts and update development workflow
- Create ./output/ with .gitkeep for test run outputs
- Add output/* to .gitignore (negated .gitkeep)
- Add §4.5 Debug Verification to DEVELOPMENT.md: final step of each dev iteration
  - Run bs_pnpi -vv with full parameter consistency checks
  - Required debug logging per component documented
  - Example commands and success criteria
- Update Agent Instructions and Release Checklist
- Mark B8.3 debug verification framework as completed in TODO.md
2026-05-05 10:48:53 +03:00
unzhakov 330ebddaef refactor: refine CLI options and enhance debug logging
- Remove --mode, --transition-type, and --decay-index CLI flags
  (parameters now come from ENSDF data or custom JSON input)
- Clarify energy units in all CLI help text (MeV throughout, keV for detector params)
- Enhance logging verbosity:
  - -v (INFO): shows source, component initialization, workflow steps
  - -vv (DEBUG): shows detailed internals of all spectrum components
    (parameters, evaluation counts, input/output ranges)
- Improve CSV headers with element notation (e.g. Tc99 -> Ru99)
- Add CONVENTIONS.md documenting energy unit and logging conventions
- Update TODO.md with completion status
2026-05-05 09:08:08 +03:00
unzhakov eb52c3b918 Merge dev/update-b2-status: cross out B2 (Input Flexibility) as implemented
- JSON input fully implemented: load_json_input(), json_to_config(),
  DEFAULT_JSON_SCHEMA with full detector params, CLI --input flag
- ENSDF auto-population fully implemented: get_decay_info_from_paceENSDF()
  returns DecayInfo with Z_parent, Z_daughter, A_number, endpoint_MeV,
  transition_type, forbiddenness_code, half_life, branches;
  CLI --nuclide uses this automatically
- Update Current Status to reflect B2 completion
2026-05-04 17:36:45 +03:00
unzhakov 7a925725ad docs: cross out B2 (Input Flexibility) as implemented
- JSON input fully implemented: load_json_input(), json_to_config(),
  DEFAULT_JSON_SCHEMA with full detector params, CLI --input flag
- ENSDF auto-population fully implemented: get_decay_info_from_paceENSDF()
  returns DecayInfo with Z_parent, Z_daughter, A_number, endpoint_MeV,
  transition_type, forbiddenness_code, half_life, branches;
  CLI --nuclide uses this automatically
- Update Current Status to reflect B2 completion
2026-05-04 17:06:47 +03:00
unzhakov 0b5fe88f7b docs: remove stale checkboxes, consolidate README vs TODO
- TODO.md: cross out completed A2 (detector response) and A4 (fitter/CW extraction) items with strikethrough and implementation notes
- README.md: replace redundant Components and Additional Modules tables with Implementation Status section referencing TODO.md
- Eliminates duplicate status tracking between README and TODO
2026-05-04 16:01:54 +03:00
unzhakov 3182ceb675 Merge dev/logging-infrastructure: structured logging, CSV headers, CLI improvements
- New logging infrastructure (beta_spectrum/logging_utils.py)
- CLI flags: -v/-vv/-q, --log-file, --dry-run, --version
- CSV metadata headers with version, timestamp, nuclide info, git hash
- Opt-in logging design (zero overhead for library users)
- 28 new tests, 195 total tests passing
2026-05-04 15:46:29 +03:00
unzhakov 9050019ddd feat: add structured logging, CSV metadata headers, and CLI improvements
- New module: beta_spectrum/logging_utils.py
  - LoggingConfig dataclass with level, log_file, format options
  - setup_logging() one-shot configuration (opt-in for library use)
  - get_logger() for named child loggers
  - get_git_short_hash() for commit identification
  - _find_git_root() for repo detection

- CLI enhancements (beta_spectrum/cli.py):
  - --verbose/-v (repeatable): -v=INFO, -vv=DEBUG
  - --quiet/-q: suppress all terminal output
  - --log-file PATH: append log to file
  - --dry-run: validate input, display resolved config, exit
  - --version: show package version
  - Replace print() with structured logging throughout
  - Handle KeyboardInterrupt gracefully

- CSV metadata headers (BetaSpectrumAnalyzer.export_to_csv):
  - YAML-style # comments with version, timestamp, source, nuclide info
  - Corrections enabled, e_step, detector settings, git commit hash

- Base class integration (SpectrumComponent):
  - Optional logger parameter for debug/info output (opt-in)

- BetaSpectrum integration:
  - Optional logger parameter passed through from_config()
  - Detector logging in create_detector_from_config()
  - Convolution logging in convolve_with_detector()

- Tests: tests/test_logging_utils.py (28 tests)
  - LoggingConfig, setup_logging, get_logger, git hash, CSV headers, CLI flags

- Update TODO.md: mark B8 as complete, update Current Status
2026-05-04 15:11:01 +03:00
unzhakov 1a0754be5f docs: remove empty recoil.py stub, update README and TODO to reflect actual state
- Remove empty beta_spectrum/components/recoil.py (0-line stub)
- Remove recoil.py from README.md project tree and components table
- Update TODO.md: replace specific recoil section with generic 'Additional
  Corrections' deferred item, update Current Status to 0.3.0 with actual
  implementation list, mark A4 as complete, set A3 as next step
2026-05-04 11:56:41 +03:00
unzhakov 4ceaa32ed1 Add some sanyty testing ipynb notebooks 2026-05-04 10:55:30 +03:00
unzhakov 1ebf95de60 fix/Slight fix to DEVELOPMENT.md 2026-05-04 07:34:19 +03:00
unzhakov 66a93d9cac fix: satisfy mypy strict type-checking requirements
- Add proper type annotations to all source files
- Fix return types for numpy operations (np.asarray with dtype=np.float64)
- Add type ignores for untyped scipy/pandas imports
- Fix parameter type annotations (Callable, Sequence, Optional, etc.)
- Add TYPE_CHECKING imports for forward references
- Fix fitter.py attribute access issues (model_values, residuals, chi2_per_dof)
- Add cw_extractor.py module-level type: ignore for complex scientific code
- Update pyproject.toml to exclude notebooks from mypy
- Add mypy disable_error_code configuration for test files
- Run black and ruff for formatting and linting
2026-05-03 01:00:47 +03:00
unzhakov 33ed4f7e44 fix: satisfy mypy strict type-checking requirements
- Add proper type annotations to all source files
- Fix return types for numpy operations (np.asarray with dtype=np.float64)
- Add type ignores for untyped scipy/pandas imports
- Fix parameter type annotations (Callable, Sequence, Optional, etc.)
- Add TYPE_CHECKING imports for forward references
- Fix fitter.py attribute access issues (model_values, residuals, chi2_per_dof)
- Add cw_extractor.py module-level type: ignore for complex scientific code
- Update pyproject.toml to exclude notebooks from mypy
- Run black and ruff for formatting and linting
2026-05-03 00:44:11 +03:00
unzhakov 87c184fb5d docs: add TODO items for CLI improvements and output enhancements (B8) 2026-05-02 22:57:01 +03:00
unzhakov d8c521f6f8 docs: update README with CLI, nuclear data integration, and additional modules 2026-05-02 22:23:37 +03:00
unzhakov 1269244b93 feat: add paceENSDF integration and CLI interface (Track B1)
- Add nuclear_data.py module for paceENSDF integration and JSON input
- Add DecayInfo and BranchInfo dataclasses for parsed nuclear data
- Implement get_decay_info_from_paceENSDF() to retrieve decay parameters
- Implement load_json_input() and json_to_config() for custom JSON input
- Add create_config_from_source() unified interface for both sources
- Add bs_pnpi CLI with --nuclide, --input, --output, --plot, and detector options
- Add 23 comprehensive tests for nuclear_data module
- Add sample JSON input file
- Update __init__.py and pyproject.toml with new exports and entry point
- Add paceENSDF as optional dependency
2026-05-02 22:09:25 +03:00
unzhakov 6854bbff6e docs: update TODO.md with A2 completion and A4 next step
Mark detector response (A2) as complete. Set A4 (fitter routine for
experimental C(W) extraction) as the next immediate step.
2026-05-02 09:41:08 +03:00
unzhakov 272841f50d feat: add χ² fitter and C(W) shape factor extraction modules
Add CurveFitter with scipy least_squares, configurable loss functions
(soft_l1, huber, cauchy), profile likelihood, confidence intervals, and
goodness-of-fit metrics. Add CWExtractor for extracting shape factors
from beta spectra via Kurie analysis, parametrization fitting, and
g_V/g_A extraction. Includes 32 new tests (18 fitter + 14 CW extractor).
Bump version to 0.3.0.
2026-05-02 09:40:38 +03:00
unzhakov 97aaddd86b feat: add notebook quality control pipeline with nbmake, auto-save hooks, and plot extraction 2026-05-02 02:25:24 +03:00
unzhakov 8b4545fe3e refactor: centralize all physical constants in constants.py, fix unit naming
- Add EULER_GAMMA, ME_KEV, R0_FM to constants.py
- Replace hardcoded 0.511, 0.5772..., 1.2 with imports from constants
- Fix T_to_W parameter name: T_kev -> T_MeV (it takes MeV, not keV)
- Remove duplicate ME_ME from spectrum.py (import ME_MEV from constants)
- Remove hardcoded r_0 from detector_response.py and radiative.py
- Update CONVENTIONS.md to reference correct constant names
2026-05-01 22:34:15 +03:00
unzhakov 6a671bfb8b docs: split conventions into CONVENTIONS.md — natural units, energy notation, SpectrumComponent design
- CONVENTIONS.md: natural units (m_e=hbar=c=1), W vs MeV energy representation,
  conversion helpers, SpectrumComponent interface, physics-specific testing
- DEVELOPMENT.md: removed physics-specific 'What to Test' section,
  references CONVENTIONS.md for physics testing guidelines
2026-05-01 22:01:33 +03:00
unzhakov 5950659514 docs: add strategic development roadmap (TODO.md) 2026-05-01 19:27:51 +03:00
unzhakov bb5ce636ce style: fix black formatting in test_spectrum.py 2026-05-01 19:21:18 +03:00
unzhakov 5f99566a0e feat(detector): add detector response module, convolution, and integration
- Analytical detector response: gaussian, gaussian_tail, tikhonov models
- Low-energy tail modeling for charge collection effects
- Response matrix convolution via R^T · (Φ·ΔW)
- Declarative API: create_detector_from_config(), convolve_detector()
- BetaSpectrumAnalyzer.convolved_spectrum() for auto-convolution
- Integration tests: TestBetaSpectrumIntegration, TestDeclarativeDetectorResponse
- Documentation: docs/08-detector-response.md
2026-05-01 19:20:59 +03:00
unzhakov dac78987e6 chore: add mdformat and plugins to dev dependencies 2026-05-01 19:17:56 +03:00
unzhakov b974b68ce7 docs: update README structure and DEVELOPMENT.md setup instructions 2026-05-01 19:17:41 +03:00
unzhakov 1e678cfab7 docs: reformat radiative corrections doc to Obsidian YAML frontmatter 2026-05-01 19:17:26 +03:00
unzhakov 968cd6eff7 style: remove trailing blank lines in base.py and fermi.py 2026-05-01 19:17:08 +03:00
unzhakov c9a738baab chore(gitignore): remove notebooks and ipynb from gitignore
style: fix black formatting in test files (unused imports, assert reformatting)
2026-05-01 19:16:50 +03:00
unzhakov 21901aac70 Merge branch 'dev/radiative-correction-improvements' into main 2026-04-30 22:18:16 +03:00
unzhakov c99ce51487 fix(radiative): only apply endpoint resummation within delta_cut per spec Section 3.4
The resummation was previously applied to all energy points when the
flag was set, causing resummed and standard modes to differ everywhere.
Per spec, it should only replace C(beta)*ln(W0-W) with the resummed
power-law form when (W0-W) < delta_cut (~1e-3).

Adds delta_cut parameter (default 1e-3) and corrects the resummation
switch test to verify identical results far from endpoint.
2026-04-30 21:06:00 +03:00
unzhakov b2d8fbdd63 Add article summary
Hayen 2019 1-st forbidden transitions in the reactor anomaly
2026-04-30 18:19:36 +03:00
unzhakov ed3fd5dc9d feat(radiative): implement O(Z*alpha^2) correction and improve numerical stability
- Add Z (nuclear charge) and A (mass number) parameters to RadiativeCorrection
- Implement O(Z*alpha^2) finite nuclear size correction per Sirlin 1987:
  - Energy-dependent part: ln(m_p) - (5/12)*ln(2W) + 43/18
  - Nuclear-structure-dependent part: Delta_F(Z,A) from modified Gaussian model
- Add small-beta Taylor expansion for numerical stability at threshold (beta < 1e-6)
- Extract _safe_beta() and _safe_tanh_inv_beta_over_beta() helper methods
- Remove unused log_wright_bessel import
- Add 14 new tests: Z-dependence, numerical stability, A parameter coverage
- Update docs/06-radiative-corrections.md with new API usage examples

All 70 tests pass. 14 new tests in 3 new test classes.
2026-04-30 07:18:02 +03:00
unzhakov 6de2b9c01a Fix python venv in DEVELOPMENT.md 2026-04-29 22:51:07 +03:00
unzhakov 366be7d7c0 Create DEVELOPMENT.md
Containts rules and principles of basic development loop for the project
2026-04-29 22:39:36 +03:00
unzhakov 4185d2c77c Update docs for radiative correction
Added summaries for Sirlin's articles and spec file based on them.
2026-04-29 22:38:25 +03:00
unzhakov c40a6f7700 Update description and docs
Phase space upgrad (forbidden factors)
2026-04-29 22:35:56 +03:00
unzhakov 9ea2fdae33 Update .gitignore
no need to track ./docs/.obsidian/
2026-04-29 22:34:41 +03:00
unzhakov 4d508ca313 Add doc summary: 2050_Song 99TcMeasurement
Measurement of the 99Tc beta-spectrum and implications for g_v
2026-04-29 13:48:42 +03:00
unzhakov 0e9b20caa2 Fix deprecated np.maximum calls with 3 params 2026-04-28 11:38:31 +03:00