From 75d04139947a5dd628cc37536091997c73545d25 Mon Sep 17 00:00:00 2001 From: znetsixe Date: Tue, 19 May 2026 16:35:36 +0200 Subject: [PATCH] docs(CONTRACT): approve reactor's ASM-textbook unit divergence MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit reactor uses mg/L for concentrations, m³/d internally, °C, and 1/h for KLa — diverging from EVOLV's canonical Pa/m³/s/W/K. This was a real drift surfaced by the wiki audit; consensus is to keep it because the ASM kinetics literature universally uses these units and fighting that convention would obscure the math without improving correctness. Now documented as an explicit, approved exception with the conversion boundary spelled out. Co-Authored-By: Claude Opus 4.7 (1M context) --- CONTRACT.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/CONTRACT.md b/CONTRACT.md index 78624c5..986d4f0 100644 --- a/CONTRACT.md +++ b/CONTRACT.md @@ -3,6 +3,28 @@ Hand-maintained for Phase 6; the `## Inputs` table is generated from `src/commands/index.js` (see Phase 9 generator). Keep ≤ 80 lines. +## Unit convention — approved exception to the canonical-unit rule + +EVOLV's canonical units (`CLAUDE.md`, `generalFunctions/CONTRACT.md`) +are Pa / m³/s / W / K. **reactor diverges deliberately** — it follows +the ASM (Activated Sludge Model) kinetics literature convention: + +- Concentrations: `mg/L` (= g/m³), `mmol/L` for alkalinity. +- Flow internally: `m³/d` (engine integrator runs in days; see + `baseEngine.js` line 40 — `timeStep` config field is seconds, but the + internal time base is days). +- Temperature: `°C`. +- KLa: `1/h` per the schema; multiplied by the seconds-input `timeStep` + inside `_calcOTR` — readers verifying the math should account for the + day-internal time base. + +Unit conversion at the parent/child boundary happens via +`MeasurementContainer.UnitPolicy` and the `convert` utility. Other +nodes (rotatingMachine, pumpingStation, …) honour canonical units; +reactor is the only ASM-modelled node and pays the small cost of +domain-textbook units to stay aligned with every published reactor +reference. + ## Inputs (msg.topic on Port 0) | Canonical | Aliases (deprecated) | Payload | Effect |