unzhakov
8314cee29c
- Shrink global AGENTS.md: 153 → 56 lines (−63%) Removed: git workflow, TDD, overthinking guards, code style, reasoning protocol Kept: personality, git basics, thinking levels, general principles, backend - Create project AGENTS.md: 71 lines Added: stack/commands, GitHub Flow git workflow, Conventional Commits, TDD (Python-specific), quality gates, debug verification - Trim CONVENTIONS.md: 161 → 68 lines (−58%) Removed: verbose examples, redundant unit convention section, lengthy SpectrumComponent code example - Delete DEVELOPMENT.md: 238 lines → 0 (migrated to AGENTS.md) Setup/release checklist removed (not agent concerns) Git workflow, TDD, quality gates, notebook QC, debug verification all migrated to AGENTS.md - Update README.md project structure Total per-session metadata: 552 → 195 lines (−65%)
2.3 KiB
2.3 KiB
Project Conventions
Physical, mathematical, and architectural conventions governing code correctness.
1. Natural Units
All internal calculations use natural units:
m_e = ℏ = c = 1
m_e is the electron rest mass. Fundamental unit for energy, mass, momentum, and time.
2. Energy Representation
Internal: total energy W in m_e units (W = 1.0 = rest mass, W > 1.0 = kinetic).
External API: human-readable MeV/keV. Check the unit suffix in parameter names:
_MeVsuffix → value is in MeV_keVsuffix → value is in keV (detector params only)- No suffix on energy → value is in m_e units (internal)
Conversion
Always use central utilities — never hardcode constants or manual arithmetic:
from beta_spectrum.utils import T_to_W, W_to_T
from beta_spectrum.constants import ME_MEV, ME_KEV, ALPHA, MP_MEV
3. SpectrumComponent Design
All spectral components follow a common interface:
- Stateless or minimally stateful — no mutable state depending on input
- Vectorized — accept/return
np.ndarray, support broadcasting - Consistent energy variable — always
W(total energy in m_e units) internally - Callable interface — implement
__call__(W)for uniform usage - Return correction factor — multiplicative factor, typically ~0.1 to 10
4. Logging
- No verbosity (default): errors and warnings only
-v(INFO): source selection, component init, workflow steps, output locations-vv(DEBUG): all INFO + detailed internals (parameters, ranges, evaluation counts)
Each SpectrumComponent logs:
- INFO at init: component name + key parameters
- DEBUG at evaluation: energy point count, input/output ranges
5. Nuclear Data Notation
- Element:
Tc,Ru,U - Nuclide:
Tc99,Ru99,U238 - Decay:
Tc99 -> Ru99(parent → daughter) - CSV headers use element notation:
# nuclide: Tc99 -> Ru99 (Z=43->44)
6. Physics Testing Guidelines
When testing physics components, verify:
- Physical constraints — values at thresholds, endpoints, boundaries match known physics
- Positivity — no unphysical negative values
- Shape correctness — output shape matches input (vectorized)
- Type safety — components accept/return
np.ndarray - Numerical stability — no NaN/inf in physical range (except where physically expected)