Repository navigation
Description
Task
T-021· Milestone M2 — Scenario + kinematic2d · Size S · Priority P0 · Epic #2Implements FR-SCN-003
Branch
feat/t-021-normalisation-to-the-unit-hypercube— one task = one branch = one PR (doc 32 §6)
Summary
Implement scenario/normalize.py and wire ScenarioSpace.to_unit / from_unit per doc 06 §4.1: linear, log scale, integer rounding, categorical index encoding.
Context / motivation
Every algorithm (GP, samplers, clustering, risk maps) works in [0,1]^d. FR-SCN-003 requires lossless float round-trips (|error| < 1e-9) and exact int/categorical round-trips.
Scope
In scope
- Vectorised
to_unit(values) -> ndarray (d,)andfrom_unit(u) -> dict, batch variants(n,d). - Log scale:
u = (log x − log low)/(log high − log low). - Int: round-half-even after inverse mapping; categorical:
u ∈ [i/k, (i+1)/k)→ choice i (document), forward maps to bin centre. - Clipping of
uto [0,1] with a warning on out-of-range input.
Implementation guidance
- Pure functions, no I/O. Inputs validated against bounds before mapping (
ValidationError). - Standards: respect the layering contracts (doc 16 §2) and conventions in doc 34; no hard-coded tunables — thresholds/defaults come from typed settings (doc 27); no magic numbers (ruff
PLR2004); public APIs typed (mypy strict) and documented.
Acceptance criteria
- Hypothesis round-trip passes 10 000 examples (
max_examplesoverride) for floats/ints/categoricals. - Log-scale midpoint of [5, 1000] lux maps to
sqrt(5·1000). - 100 % coverage of
normalize.py. - Tests listed below added and green in CI; coverage of new code meets the gate in doc 18 §3.
- Docs, config reference and CHANGELOG
Unreleasedupdated where behaviour, keys or interfaces changed. - Definition of Done (doc 32 §3) satisfied.
Tests required
tests/property/scenario/test_normalize_roundtrip.py,tests/unit/scenario/test_normalize.py.
Dependencies
Blocked by: #33 (T-020b)
Blocks: #36 (T-023), #37 (T-024), #38 (T-025), #126 (T-070a)
Parallelization notes
Files / paths owned by this task — avoid editing other paths; shared files (pyproject.toml entry points, cli/main.py, api/routers/__init__.py, router.tsx, docker/compose.yaml, ci.yml) are append-only:
backend/src/roboprobe/scenario/normalize.py- backend/src/roboprobe/scenario/space.py (2 methods delegate)
Parallel with T-022 (different module).
Definition of Done
Per doc 32 §3 and AGENTS.md §5: lint, format, mypy strict and import-linter green; tests added and passing; docs updated; PR template completed with Closes #<this issue>; Conventional Commit messages referencing T-021 (doc 16 §6); commits authored only by the repository owner identity (AGENTS.md §4); CI green; reviewer checklist (doc 32 §5.1) satisfied.
References
Design docs: doc 06 §4.1 · doc 05 §3 · doc 02 §3.1 · doc 18 §4.1
Requirements: FR-SCN-003 (traceability: doc 28)
External:
Metadata
Metadata
Assignees
Labels
Projects
- StatusShow more project fieldsIn review
Activity
warehouse_v1.yaml#33ScenarioSpace.with_pins) #38