Files

T

unzhakov 6aced1d8ac 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

3.2 KiB

Raw Blame History

Agent Instructions — beta-spectrum

High-precision beta decay spectrum shape calculator. Since v0.5.0 the repository is dedicated solely to spectrum shape calculation: detector response, calibration, fitting and C(W)/g_V/g_A extraction live in separate, dedicated projects.

Stack & Commands

pytest                           # all tests
nbmake notebooks/                # execute notebooks as tests
black --check .                  # formatting
ruff check .                     # linting
mypy .                           # type checking (strict)
bs_pnpi --nuclide Tc99 -vv --output ./output/verification.csv  # debug verification

Install: source ~/.pyenv/sci/bin/activate && pip install -e ".[dev]"

Git Workflow (GitHub Flow)

Never commit directly to main. Always branch: git checkout -b dev/<short-desc>
Atomic commits with Conventional Commits format:
- feat:, fix:, docs:, style:, refactor:, perf:, test:, chore:
- Imperative mood, present tense, under 72 chars
- WIP commits fine on dev branches — squash before final merge
Commit each logical change — don't wait for green. Use git add -p.
Rebase over merge for linear history: git rebase main before merge.
Delete branch locally + remotely after merge.
Update project metadata on significant changes: When a commit changes the package structure, adds/removes modules, or bumps the version, also update TODO.md and README.md to reflect the new state. This keeps documentation in sync with code.

TDD

Test-first by default. For new classes/functions: write failing test first.

RED — failing test defining desired behavior
GREEN — minimal code to pass
REFACTOR — clean up, confirm tests still pass

State which phase you're in. Name phases explicitly.

Python Testing Conventions

Tests mirror package structure: beta_spectrum/components/foo.py → tests/physics/test_foo.py
Shared fixtures in tests/conftest.py
Classes organized by feature area (e.g., TestComponentBasicProperties)
Descriptive names: test_<function>_<expected_behavior>_<context>
Include implementation-level assertions (type checks, pre/postconditions)
Use hypothesis for property-based tests where applicable
Physics tests verify: physical constraints at thresholds, positivity, monotonicity, numerical stability

Quality Gates

All must pass before merge:

pytest                           # all tests (markers: property, physics, api, quality, integration, slow, requires_ensdf)
nbmake notebooks/                # execute notebooks as tests
black --check .                  # formatting
ruff check .                     # linting
mypy .                           # type checking (strict)
python scripts/docs_check.py     # documentation consistency (version, file refs, CLI args)

Run individually to identify failures.

Debug Verification (Final Step)

After quality gates pass, run:

bs_pnpi --nuclide Tc99 -vv --output ./output/verification.csv --plot ./output/verification.png --log-file ./output/debug.log 2>&1 | tee ./output/debug_stdout.log

Verify parameter consistency across all components. Save artifacts to ./output/.

3.2 KiB Raw Blame History