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%)
69 lines
2.3 KiB
Markdown
69 lines
2.3 KiB
Markdown
# 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:
|
|
- `_MeV` suffix → value is in MeV
|
|
- `_keV` suffix → 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:
|
|
|
|
```python
|
|
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)
|