docs(wiki): full 5-page wiki matching the rotatingMachine reference format
Replaces the prior stub/partial wiki with a Home + Reference-{Architecture,
Contracts,Examples,Limitations} + _Sidebar structure. Topic-contract and
data-model sections wrapped in AUTOGEN markers for the future wiki-gen tool.
Source-vs-spec contradictions surfaced and flagged inline (not silently
fixed). Pending-review notes mark sections that need a full node review.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
znetsixe
382
wiki/Home.md
382
wiki/Home.md
@@ -1,300 +1,182 @@
|
||||
# reactor
|
||||
|
||||
> **Reflects code as of `c84dd78` · regenerated `2026-05-11` via `npm run wiki:all`**
|
||||
> If this banner is stale, the page may be out of date. Treat as informative, not authoritative.
|
||||
  
|
||||
|
||||
## 1. What this node is
|
||||
A `reactor` models a single biological-treatment tank governed by the ASM3 (Activated Sludge Model No. 3) kinetics. It wraps either a CSTR (fully-mixed) or PFR (plug-flow with axial dispersion) integrator, accepts an influent stream + aeration rate, integrates the 13 ASM3 species each tick, and emits the effluent vector for the next Unit downstream (typically a `settler` or another `reactor`). A `diffuser` (Equipment Module) supplies aeration via `data.otr`; `measurement` children supply temperature and (PFR-only) dissolved-oxygen reconciliation.
|
||||
|
||||
**reactor** is an S88 Unit that wraps an ASM3 biological-process engine — either a CSTR (fully mixed tank) or a PFR (plug-flow with axial dispersion). It integrates 13 species (S_O, S_NH, X_H, X_TS, …) and emits the effluent vector each tick. Drives a settler downstream and accepts a recirculation pump child.
|
||||
> [!NOTE]
|
||||
> Pending full node review (2026-05). Content reflects `CONTRACT.md` and current source only.
|
||||
|
||||
## 2. Position in the platform
|
||||
---
|
||||
|
||||
~~~mermaid
|
||||
## At a glance
|
||||
|
||||
| Thing | Value |
|
||||
|:---|:---|
|
||||
| What it represents | One biological-treatment tank running ASM3 kinetics — aerated, anoxic, or anaerobic |
|
||||
| S88 level | Unit |
|
||||
| Use it when | You need an activated-sludge tank with nitrification / denitrification / heterotrophic growth modelled species-by-species |
|
||||
| Don't use it for | Passive equalisation tanks (no reactions), simple residence-time delays (lighter buffer is better), aerobic-only contactors where ASM3's full 13-species vector is overkill |
|
||||
| Children it accepts | `measurement` (temperature at equipment; PFR also: dissolved oxygen at numeric distance); upstream `reactor` |
|
||||
| Parents / sinks it talks to | downstream `reactor` or `settler` (via `Fluent` on Port 0); `diffuser` pushes `data.otr` in |
|
||||
|
||||
---
|
||||
|
||||
## How it fits
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
upstream[reactor<br/>upstream<br/>Unit]:::unit
|
||||
reactor[reactor<br/>Unit]:::unit
|
||||
rx[reactor<br/>Unit]:::unit
|
||||
settler[settler<br/>downstream<br/>Unit]:::unit
|
||||
diffuser[diffuser<br/>Equipment]:::equip
|
||||
tsens[measurement<br/>temperature<br/>atequipment]:::ctrl
|
||||
osens[measurement<br/>oxygen<br/>at distance]:::ctrl
|
||||
tsens[measurement<br/>temperature<br/>atEquipment]:::ctrl
|
||||
osens[measurement<br/>quantity (oxygen)<br/>at numeric distance, PFR only]:::ctrl
|
||||
|
||||
upstream -.stateChange.-> rx
|
||||
rx -->|Fluent inlet=0| settler
|
||||
diffuser -->|data.otr| rx
|
||||
tsens -.measured.-> rx
|
||||
osens -.measured.-> rx
|
||||
tsens -->|child.register| rx
|
||||
osens -->|child.register| rx
|
||||
upstream -->|child.register<br/>positionVsParent=upstream| rx
|
||||
|
||||
upstream -.stateChange.-> reactor
|
||||
reactor -->|Fluent inlet=0| settler
|
||||
settler -.stateChange.-> reactor
|
||||
diffuser -->|data.otr| reactor
|
||||
tsens -->|child.register| reactor
|
||||
osens -->|child.register| reactor
|
||||
tsens -->|temperature.measured.atEquipment| reactor
|
||||
osens -->|quantity(oxygen).measured.distance| reactor
|
||||
classDef unit fill:#50a8d9,color:#000
|
||||
classDef equip fill:#86bbdd,color:#000
|
||||
classDef ctrl fill:#a9daee,color:#000
|
||||
~~~
|
||||
```
|
||||
|
||||
S88 colours: Unit `#50a8d9`, Equipment `#86bbdd`, Control Module `#a9daee`. Source of truth: `.claude/rules/node-red-flow-layout.md`.
|
||||
S88 colours are anchored in `.claude/rules/node-red-flow-layout.md`.
|
||||
|
||||
reactor sits at the Unit level. A diffuser (Equipment) sends aeration rates via `data.otr` — it is NOT registered as a child. Measurement children (Control Module) register and supply temperature or dissolved-oxygen reconciliation. Settler is a downstream Unit that listens to `stateChange` to pull effluent; an upstream reactor drives this reactor the same way.
|
||||
reactor sits on lane **L4** (Unit). The `diffuser` (lane L3) is **not** a registered child — it just pushes aeration via the `data.otr` topic. A reactor chain (multi-stage treatment, e.g. anoxic → aerobic → aerobic) is built by registering each upstream reactor with `positionVsParent: 'upstream'`; downstream reactors then `getEffluent` from the upstream on every `stateChange`.
|
||||
|
||||
## 3. Capability matrix
|
||||
---
|
||||
|
||||
| Capability | Status | Notes |
|
||||
|---|---|---|
|
||||
| ASM3 13-species ODE integration | ✅ | CSTR + PFR engines under `kinetics/`. |
|
||||
| CSTR (fully mixed) | ✅ | Single concentration vector per tick. |
|
||||
| PFR (axial discretization) | ✅ | `resolution_L` grid cells; emits `GridProfile` alongside `Fluent`. |
|
||||
| Multi-inlet mixing | ✅ | `n_inlets`; each inlet receives its own `data.fluent` with `inlet` index. |
|
||||
| Temperature reconcile from measurement | ✅ | `temperature.measured.atEquipment` writes `engine.temperature`. Code constant: `POSITIONS.AT_EQUIPMENT`. |
|
||||
| Oxygen reconcile (PFR) | ✅ | `quantity (oxygen).measured.<distance>` maps to nearest grid cell. |
|
||||
| KLa-driven aeration | ✅ | `reactor.kla` > 0 enables internal mass transfer; falls back to `data.otr`. |
|
||||
| Speed-up factor (sim time) | ✅ | `reactor.speedUpFactor` accelerates wall-clock → process time. |
|
||||
| Dispersion override (PFR) | ✅ | `data.dispersion` updates axial `D`. |
|
||||
| Hot-swap engine type | ❌ | `reactor_type` is read once in `configure()`. |
|
||||
## Try it — 3-minute demo
|
||||
|
||||
## 4. Code map
|
||||
Import the basic example flow, deploy, and watch a CSTR consume influent over the simulation clock.
|
||||
|
||||
~~~mermaid
|
||||
flowchart TB
|
||||
subgraph nodeRED["nodeClass.js — adapter (BaseNodeAdapter)"]
|
||||
nc["buildDomainConfig()<br/>static DomainClass = Reactor<br/>static commands"]
|
||||
end
|
||||
subgraph domain["specificClass.js — orchestrator (BaseDomain)"]
|
||||
sc["Reactor.configure()<br/>_flattenEngineConfig()<br/>_buildEngine() → CSTR or PFR<br/>ChildRouter.onRegister rules"]
|
||||
end
|
||||
subgraph kinetics["src/kinetics/"]
|
||||
be["baseEngine.js<br/>BaseReactorEngine<br/>influent state, OTR, T<br/>_connectMeasurement / _connectReactor<br/>updateState() → n_iter ticks"]
|
||||
cstr["cstr.js<br/>Reactor_CSTR extends BaseReactorEngine<br/>Forward-Euler 0-D integrator"]
|
||||
pfr["pfr.js<br/>Reactor_PFR extends BaseReactorEngine<br/>FD spatial grid + Danckwerts BC"]
|
||||
end
|
||||
subgraph commands["src/commands/"]
|
||||
cmds["index.js — 6 descriptors<br/>handlers.js — 6 pure fns"]
|
||||
end
|
||||
nc --> sc
|
||||
nc --> cmds
|
||||
sc --> be
|
||||
cstr --> be
|
||||
pfr --> be
|
||||
~~~
|
||||
```bash
|
||||
curl -X POST -H 'Content-Type: application/json' \
|
||||
--data @nodes/reactor/examples/basic.flow.json \
|
||||
http://localhost:1880/flow
|
||||
```
|
||||
|
||||
| Module | Owns | Read first if you're changing… |
|
||||
|---|---|---|
|
||||
| `kinetics/baseEngine.js` | ASM3 stoichiometry + rate vector + species list. | Stoichiometric matrix, kinetic constants. |
|
||||
| `kinetics/cstr.js` | 0-D CSTR integrator + `_connectMeasurement` + `_connectReactor`. | Mixed-tank behaviour, child wiring. |
|
||||
| `kinetics/pfr.js` | Axial discretization, dispersion, grid profile emission. | PFR-specific behaviour, grid math. |
|
||||
| `commands/` | 6 input descriptors + handlers (clock, fluent, OTR, temperature, dispersion, child). | Inbound topic API, alias deprecation. |
|
||||
| `reaction_modules/` | Optional plug-in reaction modules (legacy — not yet refactored). | Adding new bio-process modules. |
|
||||
| `additional_nodes/` | Sibling Node-RED nodes (`recirculation-pump`, `settling-basin`) shipped from this repo. | Cross-node deploy in same package. |
|
||||
What to click after deploy (each inject maps one-to-one to a topic in [Reference — Contracts](Reference-Contracts#topic-contract)):
|
||||
|
||||
## 5. Topic contract
|
||||
1. `data.fluent` — inject an influent stream `{inlet: 0, F: 1000, C: [...13 species...]}` (m³/d, mg/L). The 13 species follow ASM3 ordering.
|
||||
2. `data.temperature` — set reactor temperature (default 20 °C; nitrification rates depend on this).
|
||||
3. `data.otr` (if `kla` is `NaN`) **or** rely on the configured `kla` for internal aeration.
|
||||
4. `data.clock` — push wall-clock `msg.timestamp` to advance the integrator. The engine computes `n_iter = floor(speedUpFactor × Δt_wall / timeStep_days)` internal Euler / FD steps and integrates them in one shot.
|
||||
5. Watch Port 0 (`Fluent` envelope on every advance) and Port 1 (InfluxDB scalar fields: `flow_total`, `temperature`, `S_O`…`X_TS`).
|
||||
|
||||
> **Auto-generated** from `src/commands/index.js`. Do NOT hand-edit between the markers. Re-run `npm run wiki:contract`.
|
||||
> [!IMPORTANT]
|
||||
> **GIF needed.** Demo recording of steps 1–5 with `S_NH` falling and `S_NO` rising (nitrification proceeding). Save as `wiki/_partial-gifs/reactor/01-basic-cstr.gif`, target ≤ 1 MB after `gifsicle -O3 --lossy=80`.
|
||||
|
||||
<!-- BEGIN AUTOGEN: topic-contract -->
|
||||
---
|
||||
|
||||
| Canonical topic | Aliases | Payload | Unit | Effect |
|
||||
|---|---|---|---|---|
|
||||
| `data.clock` | `clock` | `any` | — | Push the simulation clock tick (timestamp / dt) to the ASM solver. |
|
||||
| `data.fluent` | `Fluent` | `object` | — | Push the influent stream (payload: {F: flow m3/h, C: [concentrations mg/L]}). |
|
||||
| `data.otr` | `OTR` | `any` | — | Push the current oxygen-transfer rate into the reactor. |
|
||||
| `data.temperature` | `Temperature` | `any` | — | Push the current reactor temperature. |
|
||||
| `data.dispersion` | `Dispersion` | `any` | — | Push a dispersion/mixing parameter update. |
|
||||
| `child.register` | `registerChild` | `any` | — | Register a child node (settler / measurement) with this reactor. |
|
||||
## The six things you'll send
|
||||
|
||||
<!-- END AUTOGEN: topic-contract -->
|
||||
| Topic | Aliases | Payload | What it does |
|
||||
|:---|:---|:---|:---|
|
||||
| `data.clock` | `clock` | `{timestamp: ms}` (or use `msg.timestamp`) | Advance the integrator. `updateState` computes how many internal steps fit between `currentTime` and the supplied timestamp (scaled by `speedUpFactor`) and runs them. |
|
||||
| `data.fluent` | `Fluent` | `{inlet: number, F: number, C: number[13]}` | Set the per-inlet flow rate (`F`) and concentration vector (`C`). Stored in `engine.Fs[inlet]` / `engine.Cs_in[inlet]`. |
|
||||
| `data.otr` | `OTR` | numeric | Set the externally-supplied oxygen transfer rate. Used when `kla` is `NaN`; ignored otherwise (internal mass transfer takes over). |
|
||||
| `data.temperature` | `Temperature` | numeric or `{value: number}` | Set `engine.temperature` (°C). Non-numeric payloads are warned and ignored. |
|
||||
| `data.dispersion` | `Dispersion` | numeric | **PFR only** — set axial dispersion coefficient `D` (m²/d). Triggers Peclet / Courant guard warnings on the next `updateState`. |
|
||||
| `child.register` | `registerChild` | child node id (string) | Register a sibling node (`measurement`, upstream `reactor`) with this reactor. Port 2 wiring does this automatically in normal flows. |
|
||||
|
||||
## 6. Child registration
|
||||
> [!NOTE]
|
||||
> Pending full node review (2026-05). reactor's command surface is data-push only — there is **no FSM, no setpoint, no mode**. The kinetics engine runs continuous-state ODE / PDE integration; the only stateful event is `stateChange` after every successful advance.
|
||||
|
||||
~~~mermaid
|
||||
flowchart LR
|
||||
subgraph kids["accepted children (softwareType)"]
|
||||
m_t["measurement<br/>temperature<br/>positionVsParent=atEquipment"]:::ctrl
|
||||
m_o["measurement<br/>quantity (oxygen)<br/>positionVsParent=distance (numeric)"]:::ctrl
|
||||
r_up["reactor<br/>positionVsParent=upstream"]:::unit
|
||||
end
|
||||
m_t -->|temperature.measured.atEquipment| h_meas["engine._connectMeasurement<br/>(baseEngine.js)"]
|
||||
m_o -->|quantity(oxygen).measured.distance| h_meas
|
||||
r_up -.stateChange.-> h_react["engine._connectReactor<br/>(baseEngine.js)"]
|
||||
h_meas --> reconcile["reconcile T → engine.temperature<br/>reconcile O2 → state grid cell (PFR only)"]
|
||||
h_react --> pull["pull upstream getEffluent<br/>→ Fs[0] / Cs_in[0] before next tick"]
|
||||
classDef ctrl fill:#a9daee,color:#000
|
||||
classDef unit fill:#50a8d9,color:#000
|
||||
~~~
|
||||
---
|
||||
|
||||
| softwareType | filter | wired to | side-effect |
|
||||
|---|---|---|---|
|
||||
| `measurement` | `asset.type = temperature`, `positionVsParent = atEquipment` | `engine._connectMeasurement` | Writes `engine.temperature`. CSTR only honours temperature; PFR additionally reconciles `quantity (oxygen).measured.<distance>` (numeric position) → nearest grid cell DO. |
|
||||
| `measurement` | `asset.type = quantity (oxygen)`, `positionVsParent = <numeric distance>` | `engine._connectMeasurement` → `pfr._updateMeasurement` | PFR only: maps measurement to nearest grid cell by `round(pos / length × n_x)`. |
|
||||
| `reactor` | `positionVsParent = upstream` | `engine._connectReactor` | Subscribes to upstream reactor's `stateChange`; pulls `getEffluent` into `Fs[0]` / `Cs_in[0]` before next integration step. |
|
||||
## What you'll see come out
|
||||
|
||||
`diffuser` is NOT a registered child — it feeds aeration via `data.otr` on Port 0. No child-registration handshake is involved.
|
||||
|
||||
## 7. Lifecycle — what one `data.clock` advance does
|
||||
|
||||
~~~mermaid
|
||||
sequenceDiagram
|
||||
participant clock as clock injector
|
||||
participant reactor as reactor (specificClass)
|
||||
participant engine as kinetics engine (CSTR/PFR)
|
||||
participant downstream as settler / next reactor
|
||||
participant out as Port-0 output
|
||||
|
||||
clock->>reactor: data.clock { timestamp }
|
||||
reactor->>engine: updateState(timestamp)
|
||||
Note over engine: n_iter = floor(speedUpFactor × Δt / timeStep)<br/>each step calls tick(timeStep)
|
||||
engine->>engine: integrate ASM3 rates (CSTR: Forward Euler / PFR: FD)
|
||||
engine->>engine: cap S_O to saturation, clip negatives to 0
|
||||
engine->>engine: emit 'stateChange' (currentTime)
|
||||
reactor->>reactor: notifyOutputChanged → getOutput()
|
||||
reactor->>out: getOutput() → {flow_total, temperature, S_O … X_TS}
|
||||
alt PFR engine
|
||||
reactor->>out: GridProfile { grid[n_x][13], n_x, d_x, length, species }
|
||||
end
|
||||
out->>downstream: Fluent { inlet=0, F, C[13] } via stateChange listener
|
||||
~~~
|
||||
|
||||
`stateChange` re-emits on `reactor.emitter` (BaseDomain emitter) — wired in `specificClass.configure()`. Downstream settlers or chained reactors subscribed via `_connectReactor` call their own `updateState` on each `stateChange` event. The tick loop is opt-in (tick-driven via `static tickInterval`) because the reactor integrates process-time steps that have no fixed wall-clock mapping.
|
||||
|
||||
## 8. Data model — `getOutput()`
|
||||
|
||||
Port-0 process payload is the `Fluent` envelope (+ optional `GridProfile` for PFR). Port-1 telemetry is the scalar snapshot below.
|
||||
|
||||
<!-- BEGIN AUTOGEN: data-model -->
|
||||
|
||||
| Key | Type | Unit | Sample |
|
||||
|---|---|---|---|
|
||||
| `S_HCO` | number | — | `5` |
|
||||
| `S_I` | number | — | `30` |
|
||||
| `S_N2` | number | — | `0` |
|
||||
| `S_NH` | number | — | `25` |
|
||||
| `S_NO` | number | — | `0` |
|
||||
| `S_O` | number | — | `0` |
|
||||
| `S_S` | number | — | `70` |
|
||||
| `X_A` | number | — | `200` |
|
||||
| `X_H` | number | — | `2000` |
|
||||
| `X_I` | number | — | `1000` |
|
||||
| `X_S` | number | — | `100` |
|
||||
| `X_STO` | number | — | `0` |
|
||||
| `X_TS` | number | — | `3500` |
|
||||
| `flow_total` | number | — | `0` |
|
||||
| `temperature` | number | — | `20` |
|
||||
|
||||
<!-- END AUTOGEN: data-model -->
|
||||
|
||||
**Concrete sample** (CSTR mid-integration, nitrifying):
|
||||
Sample Port 0 message (CSTR mid-integration, nitrifying):
|
||||
|
||||
```json
|
||||
{
|
||||
"flow_total": 1000,
|
||||
"temperature": 15.2,
|
||||
"S_O": 2.1,
|
||||
"S_I": 30,
|
||||
"S_S": 12.4,
|
||||
"S_NH": 0.8,
|
||||
"S_N2": 4.3,
|
||||
"S_NO": 18.6,
|
||||
"S_HCO": 4.2,
|
||||
"X_I": 1050,
|
||||
"X_S": 65,
|
||||
"X_H": 2150,
|
||||
"X_STO": 4.5,
|
||||
"X_A": 215,
|
||||
"X_TS": 3680
|
||||
"topic": "Fluent",
|
||||
"payload": {
|
||||
"inlet": 0,
|
||||
"F": 1000,
|
||||
"C": [2.1, 30, 12.4, 0.8, 4.3, 18.6, 4.2, 1050, 65, 2150, 4.5, 215, 3680]
|
||||
},
|
||||
"timestamp": 1747500000000
|
||||
}
|
||||
```
|
||||
|
||||
Species ordering follows ASM3: indices 0–6 are soluble, 7–12 are particulate. `flow_total` is the effluent flow (m³/d); the reactor uses days as the time unit internally.
|
||||
The `C` array is the 13-species ASM3 vector in fixed order (indices 0–6 soluble, 7–12 particulate). For a PFR an additional message goes out on the same port **before** the effluent each advance:
|
||||
|
||||
## 9. Configuration — editor form ↔ config keys
|
||||
```json
|
||||
{
|
||||
"topic": "GridProfile",
|
||||
"payload": {
|
||||
"grid": [[...13...], [...13...], "...n_x rows..."],
|
||||
"n_x": 10,
|
||||
"d_x": 1.0,
|
||||
"length": 10,
|
||||
"species": ["S_O","S_I","S_S","S_NH","S_N2","S_NO","S_HCO","X_I","X_S","X_H","X_STO","X_A","X_TS"],
|
||||
"timestamp": 1747500000000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
~~~mermaid
|
||||
flowchart TB
|
||||
subgraph editor["Node-RED editor form (reactor.html)"]
|
||||
f1["Reactor type: CSTR / PFR"]
|
||||
f2["Volume (m³)"]
|
||||
f3["Length (m) + Resolution — PFR only"]
|
||||
f4["Alpha α (boundary condition blend)"]
|
||||
f5["Number of inlets"]
|
||||
f6["kLa (d⁻¹) — internal aeration"]
|
||||
f7["13 × initial concentration fields"]
|
||||
f8["Time step (s label) + Speed-up factor"]
|
||||
end
|
||||
subgraph config["Domain config slice (reactor.json)"]
|
||||
c1[reactor.reactor_type]
|
||||
c2[reactor.volume]
|
||||
c3["reactor.length<br/>reactor.resolution_L"]
|
||||
c4[reactor.alpha]
|
||||
c5[reactor.n_inlets]
|
||||
c6[reactor.kla]
|
||||
c7["initialState.S_O … X_TS"]
|
||||
c8["reactor.timeStep (unit: h per schema)<br/>reactor.speedUpFactor"]
|
||||
end
|
||||
f1 --> c1
|
||||
f2 --> c2
|
||||
f3 --> c3
|
||||
f4 --> c4
|
||||
f5 --> c5
|
||||
f6 --> c6
|
||||
f7 --> c7
|
||||
f8 --> c8
|
||||
~~~
|
||||
Port 1 (InfluxDB telemetry) carries the same data flattened as scalar fields — `flow_total` (m³/d), `temperature` (°C), and one field per species (`S_O`, `S_I`, `S_S`, `S_NH`, `S_N2`, `S_NO`, `S_HCO`, `X_I`, `X_S`, `X_H`, `X_STO`, `X_A`, `X_TS`, mg/L; `S_HCO` is mmol/L).
|
||||
|
||||
| Form field | Config key | Schema default | Range | Where used |
|
||||
|---|---|---|---|---|
|
||||
| Reactor type | `reactor.reactor_type` | `CSTR` | enum: `CSTR` / `PFR` (schema validator lowercases; `_buildEngine` toUpperCase guards) | engine selection in `Reactor._buildEngine()` |
|
||||
| Volume (m³) | `reactor.volume` | `1000` | > 0 | residence time, mass balance |
|
||||
| Length (m) | `reactor.length` | `10` | > 0 | PFR only — axial extent |
|
||||
| Resolution | `reactor.resolution_L` | `10` | ≥ 1 | PFR grid cell count `n_x` |
|
||||
| Alpha | `reactor.alpha` | `0.5` | 0–1 | Danckwerts (0) vs Dirichlet (1) inlet BC |
|
||||
| Inlets | `reactor.n_inlets` | `1` | ≥ 1 | `Fs[]` / `Cs_in[]` array sizes |
|
||||
| kLa (d⁻¹) | `reactor.kla` | `0` | ≥ 0; set to `NaN` to use `data.otr` instead | `_calcOTR()` in `baseEngine.js` |
|
||||
| Time step | `reactor.timeStep` | `0.001` | ≥ 0.0001 | integrator inner step (schema says `h`; HTML label says `s` — see limitation #6) |
|
||||
| Speed-up factor | `reactor.speedUpFactor` | `1` | ≥ 1 | `n_iter = floor(speedUpFactor × Δt_wall / timeStep_days)` |
|
||||
| Initial S_O | `initialState.S_O` | `0` | ≥ 0 (mg/L) | starting dissolved oxygen (caps to saturation in first tick) |
|
||||
| Initial S_NH | `initialState.S_NH` | `25` | ≥ 0 (mg/L) | starting ammonium |
|
||||
| Initial X_H | `initialState.X_H` | `2000` | ≥ 0 (mg/L) | starting heterotroph biomass |
|
||||
| Initial X_A | `initialState.X_A` | `200` | ≥ 0 (mg/L) | starting autotroph biomass — must be ≥ ~50 mg/L for nitrification; HTML default is `0.001` (footgun) |
|
||||
| Initial X_TS | `initialState.X_TS` | `3500` | ≥ 0 (mg/L) | starting TSS — drives settler split |
|
||||
| Field | Meaning |
|
||||
|:---|:---|
|
||||
| `S_O` | Dissolved oxygen. Capped to saturation at each tick via `_capDissolvedOxygen`. |
|
||||
| `S_I` | Inert soluble COD. |
|
||||
| `S_S` | Readily biodegradable substrate. |
|
||||
| `S_NH` | Ammonium nitrogen. Drops during nitrification. |
|
||||
| `S_N2` | Dinitrogen (denitrification end product). |
|
||||
| `S_NO` | Nitrate / nitrite nitrogen. Rises during nitrification. |
|
||||
| `S_HCO` | Alkalinity (bicarbonate, mmol/L). |
|
||||
| `X_I` | Inert particulate COD. |
|
||||
| `X_S` | Slowly biodegradable substrate. |
|
||||
| `X_H` | Heterotrophic biomass. |
|
||||
| `X_STO` | Stored COD in biomass. |
|
||||
| `X_A` | Autotrophic biomass. **Must be ≥ ~50 mg/L for nitrification to proceed.** |
|
||||
| `X_TS` | Total suspended solids. Drives the downstream settler split. |
|
||||
| `flow_total` | Effluent volumetric flow (m³/d) — `sum(Fs)`. |
|
||||
| `temperature` | Reactor temperature (°C). |
|
||||
|
||||
## 10. State chart
|
||||
---
|
||||
|
||||
Skipped — reactor has no FSM. It runs continuous-state ODE integration; the engine's only stateful event is `stateChange`, fired after every successful integration advance. See section 7 for the integration sequence.
|
||||
## The interesting bits
|
||||
|
||||
## 11. Examples
|
||||
### CSTR vs PFR
|
||||
|
||||
| Tier | File | What it shows | Status |
|
||||
|---|---|---|---|
|
||||
| Basic | `examples/basic.flow.json` | CSTR with one inlet, watch `Fluent` effluent | ✅ in repo |
|
||||
| Integration | `examples/integration.flow.json` | upstream reactor → reactor → settler chain | ✅ in repo |
|
||||
| Edge | `examples/edge.flow.json` | PFR with dispersion + multi-inlet | ✅ in repo |
|
||||
| Companions | `additional_nodes/*` | recirculation-pump + settling-basin Node-RED nodes shipped from this repo | ✅ in repo |
|
||||
The engine is selected once at `configure()` from `reactor.reactor_type`. The same input topics drive both, but PFR additionally:
|
||||
|
||||
One screenshot per tier where helpful. PNG ≤ 200 KB under `wiki/_partial-screenshots/reactor/`.
|
||||
- Discretises the tank along the `length` axis into `resolution_L` grid cells (`n_x`).
|
||||
- Emits a `GridProfile` message **before** the effluent each `updateState`.
|
||||
- Honours `data.dispersion` to set the axial dispersion coefficient.
|
||||
- Reconciles oxygen measurements at a **numeric** `positionVsParent` (interpreted as distance from inlet) into the nearest grid cell.
|
||||
- Warns when local Peclet ≥ 2 or Courant ≥ 0.5 (stability of the explicit FD scheme).
|
||||
|
||||
## 12. Debug recipes
|
||||
Hot-swapping engine type at runtime is not supported — redeploy the flow.
|
||||
|
||||
| Symptom | First thing to check | Where to look |
|
||||
|---|---|---|
|
||||
| Nitrification doesn't proceed (S_NH stays high) | `initialState.X_A` must be ≥ ~50 mg/L. Defaulting to `0.001` (a known footgun) means no autotrophs. | `generalFunctions/src/configs/reactor.json` |
|
||||
| `Fluent` effluent flow zero | No `data.clock` ticks arriving, or `data.fluent` never set `Fs[0] > 0`. | `commands/handlers.js`, engine `setInfluent` |
|
||||
| PFR `GridProfile` not emitted | `reactor_type` set to `CSTR` — only PFR emits grid. | `_buildEngine` switch |
|
||||
| Settler downstream not updating | `stateChange` event listener path: settler must subscribe to `reactor.emitter`, NOT `reactor.measurements.emitter`. | settler `_connectReactor` |
|
||||
| Temperature reconcile silently ignored | Child measurement's `asset.type` not `temperature` exactly, or `positionVsParent` not `atEquipment`. | `engine._connectMeasurement` |
|
||||
| Integrator slow / stalls | `reactor.timeStep` too small for `speedUpFactor`. Internal `n_iter` count blows up. | `engine.updateState` |
|
||||
| `wiki:datamodel` script slow / hangs | `mathjs` cold-start ~13 s; instantiation depends on it transitively. See known-limitations row 1. | `kinetics/baseEngine.js` |
|
||||
### Aeration: internal `kla` vs external `data.otr`
|
||||
|
||||
## 13. When you would NOT use this node
|
||||
`reactor.kla > 0` enables internal mass-transfer: `OTR = kla × (sat(T) − S_O)`. Set `kla = NaN` to fall through to the externally-pushed `data.otr` value (the path a `diffuser` Equipment node uses).
|
||||
|
||||
- Use reactor for **ASM3 biological treatment** modelling (activated sludge, nitrification, denitrification). For aerobic-only or simpler kinetics, the ASM3 species vector is overkill.
|
||||
- Don't use reactor for a passive equalisation tank — the kinetics engines assume reactions are happening.
|
||||
- Skip reactor when you only need a residence-time delay; a simple buffer node is lighter and doesn't require `mathjs`.
|
||||
### `X_A` footgun
|
||||
|
||||
## 14. Known limitations / current issues
|
||||
The HTML editor form's default initial autotroph biomass is `0.001` mg/L — effectively zero, so nitrification never starts. The JSON schema default is `200` mg/L. Always check the deployed node's form value before expecting `S_NH` to drop. See [Reference — Limitations](Reference-Limitations#x_a-initial-default-footgun).
|
||||
|
||||
| # | Issue | Tracked in |
|
||||
|---|---|---|
|
||||
| 1 | `mathjs` cold-start adds ~13 s to first `require()` — `wiki:datamodel` auto-gen may time out on the 60 s wrapper. Falls back to the hand-curated `concrete sample` block. Two remedies tracked: tree-shake mathjs to used ops only; cache the instance. | `.claude/refactor/OPEN_QUESTIONS.md` — "mathjs slow load" |
|
||||
| 2 | `initialState.X_A` HTML default is `0.001` mg/L (silently disabling nitrification) but the schema default is `200` mg/L. Always check the deployed node's form value before expecting nitrification. | `reactor.html` line 38 vs `generalFunctions/src/configs/reactor.json` |
|
||||
| 3 | `getEffluent` shape historically varied (array vs single envelope) — settler's `_connectReactor` tolerates both. Don't break the contract without updating settler. | `nodes/settler/src/specificClass.js → _connectReactor` |
|
||||
| 4 | `additional_nodes/recirculation-pump` and `settling-basin` are legacy companions — not yet refactored to BaseDomain. | P6.5 follow-up |
|
||||
| 5 | `reaction_modules/` is a legacy plug-in directory not consumed by the current engines. Removal pending. | P6.5 follow-up |
|
||||
| 6 | `reactor_type` enum casing: the JSON schema validator lowercases the user-supplied value (`'PFR'` → `'pfr'`). `Reactor._buildEngine` calls `.toUpperCase()` to work around this until Phase 7 decides the platform-wide canonical casing. If the guard is removed prematurely, PFR config silently falls back to CSTR. | `.claude/refactor/OPEN_QUESTIONS.md` — "reactor schema enum lowercases reactor_type" |
|
||||
| 7 | `timeStep` unit mismatch: the HTML form label says "Time step [s]" but `reactor.json` declares `unit: "h"`. `baseEngine.js` converts `config.timeStep` by `÷ 86 400` (seconds → days), suggesting the true input unit is seconds. Audited in OPEN_QUESTIONS.md Phase 5/6 cleanup list. | `baseEngine.js` line 40; `reactor.json` `timeStep.rules.unit`; `reactor.html` time-step label |
|
||||
---
|
||||
|
||||
## Need more?
|
||||
|
||||
| Page | What you'll find |
|
||||
|:---|:---|
|
||||
| [Reference — Contracts](Reference-Contracts) | Full topic contract, config schema, child registration filters |
|
||||
| [Reference — Architecture](Reference-Architecture) | Code map, integration sequence, kinetics layout, output ports |
|
||||
| [Reference — Examples](Reference-Examples) | Shipped example flows + debug recipes |
|
||||
| [Reference — Limitations](Reference-Limitations) | When not to use, known limitations, open questions |
|
||||
|
||||
[EVOLV master wiki](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Home) · [Topology Patterns](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topology-Patterns) · [Topic Conventions](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topic-Conventions)
|
||||
|
||||
293
wiki/Reference-Architecture.md
Normal file
293
wiki/Reference-Architecture.md
Normal file
@@ -0,0 +1,293 @@
|
||||
# Reference — Architecture
|
||||
|
||||
|
||||
|
||||
> [!NOTE]
|
||||
> Code structure for `reactor`: the three-tier sandwich, the `src/` layout, the ASM3 kinetics engines (CSTR + PFR), the integration sequence, child registration, and the output-port pipeline. For an intuitive overview, return to [Home](Home).
|
||||
>
|
||||
> Pending full node review (2026-05). Content reflects `CONTRACT.md` and current source only.
|
||||
|
||||
---
|
||||
|
||||
## Three-tier code layout
|
||||
|
||||
```
|
||||
nodes/reactor/
|
||||
|
|
||||
+-- reactor.js entry: RED.nodes.registerType('reactor', NodeClass)
|
||||
|
|
||||
+-- src/
|
||||
| nodeClass.js extends BaseNodeAdapter (Node-RED bridge)
|
||||
| specificClass.js extends BaseDomain (orchestration only)
|
||||
| utils.js assertNoNaN + small helpers
|
||||
| |
|
||||
| +-- commands/
|
||||
| | index.js 6 topic descriptors
|
||||
| | handlers.js pure handler functions
|
||||
| |
|
||||
| +-- kinetics/
|
||||
| | baseEngine.js BaseReactorEngine (influent / OTR / T / child wiring / updateState)
|
||||
| | cstr.js Reactor_CSTR extends BaseReactorEngine (0-D Forward Euler)
|
||||
| | pfr.js Reactor_PFR extends BaseReactorEngine (axial FD + Danckwerts BC)
|
||||
| |
|
||||
| +-- reaction_modules/
|
||||
| | asm3_class.js ASM3 stoichiometry + rate vector + species list
|
||||
| | asm3_class Koch.js legacy variant (not consumed by current engines)
|
||||
| |
|
||||
| +-- io/ reserved (currently empty)
|
||||
|
|
||||
+-- additional_nodes/
|
||||
| recirculation-pump.{js,html} legacy companion node shipped from this repo
|
||||
| settling-basin.{js,html} legacy companion node shipped from this repo
|
||||
```
|
||||
|
||||
### Tier responsibilities
|
||||
|
||||
| Tier | File | What it owns | Touches `RED.*` |
|
||||
|:---|:---|:---|:---:|
|
||||
| entry | `reactor.js` | Type registration | Yes |
|
||||
| nodeClass | `src/nodeClass.js` | Tick loop (`tickInterval = 1000` ms), status badge (`statusInterval = 1000` ms), `buildDomainConfig` mapping editor fields to nested config, `_emitOutputs` override that preserves the `Fluent` + `GridProfile` envelope (BaseNodeAdapter's default delta-compressed payload doesn't fit). | Yes |
|
||||
| specificClass | `src/specificClass.js` | `_flattenEngineConfig` translates nested schema to engine shape; `_buildEngine` selects CSTR or PFR; wires ChildRouter (`measurement` → `engine._connectMeasurement`, `reactor` → `engine._connectReactor`); re-emits engine `stateChange` on the BaseDomain emitter; surfaces `getOutput()`, `getStatusBadge()`. | No |
|
||||
| kinetics | `src/kinetics/*.js` | Pure ASM3 integration. `BaseReactorEngine` owns influent state, OTR, temperature, child-registration utils, and `updateState`. `Reactor_CSTR` adds the 0-D Forward-Euler tick. `Reactor_PFR` adds spatial discretization + boundary conditions + grid-profile emission. | No |
|
||||
|
||||
`specificClass` is thin stitching. All the real work lives in the kinetics engines.
|
||||
|
||||
---
|
||||
|
||||
## No FSM — continuous-state integration
|
||||
|
||||
reactor has **no finite-state machine, no mode, no setpoint**. The engine runs continuous ODE / PDE integration in process time. The only stateful event is `stateChange`, emitted by `BaseReactorEngine.updateState` after every successful advance (`n_iter > 0` internal steps completed).
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
clk[data.clock<br/>or tick(dt)]:::input --> us[updateState(newTime)]
|
||||
us --> ni{n_iter = floor(<br/>speedUpFactor × Δt / timeStep)}
|
||||
ni -->|0| skip[no-op]
|
||||
ni -->|>0| loop[for each step:<br/>tick(timeStep)]
|
||||
loop --> emit[emit stateChange(currentTime)]
|
||||
classDef input fill:#a9daee,color:#000
|
||||
```
|
||||
|
||||
`stateChange` is the trigger downstream Units (settlers, chained reactors) use to pull effluent.
|
||||
|
||||
---
|
||||
|
||||
## Kinetics engines — CSTR vs PFR
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph base["BaseReactorEngine"]
|
||||
bs["Fs[], Cs_in[][13]<br/>OTR, temperature, kla<br/>upstreamReactor link<br/>updateState(newTime)<br/>_connectMeasurement / _connectReactor"]
|
||||
end
|
||||
subgraph cstr["Reactor_CSTR"]
|
||||
cs["state = number[13]<br/>tick(dt):<br/> inflow + outflow + reaction + transfer<br/> Forward Euler<br/> _capDissolvedOxygen / _arrayClip2Zero"]
|
||||
end
|
||||
subgraph pfr["Reactor_PFR"]
|
||||
ps["state = number[n_x][13]<br/>length, n_x, d_x, A, alpha, D<br/>D_op / D2_op finite-difference operators<br/>tick(dt):<br/> dispersion + advection + reaction + transfer<br/> Explicit FD<br/> Danckwerts inlet / Neumann outlet BC<br/> Peclet / Courant guard warnings"]
|
||||
end
|
||||
bs --> cs
|
||||
bs --> ps
|
||||
```
|
||||
|
||||
### Forward Euler (CSTR)
|
||||
|
||||
`Reactor_CSTR.tick(time_step)` adds four contributions per step:
|
||||
|
||||
| Term | Formula | Notes |
|
||||
|:---|:---|:---|
|
||||
| Inflow | `Fs · Cs_in / volume` | Per inlet, summed into a single concentration delta. |
|
||||
| Outflow | `−sum(Fs) / volume · state` | Mass leaves at the current tank concentration. |
|
||||
| Reaction | `asm.compute_dC(state, T)` | ASM3 rate vector applied at current temperature. |
|
||||
| Transfer | `OTR or kla · (sat(T) − S_O)` on the `S_O` index only | All other species: zero transfer. |
|
||||
|
||||
After integration, `_capDissolvedOxygen` caps `S_O` to saturation and `_arrayClip2Zero` floors negative concentrations.
|
||||
|
||||
### Explicit FD (PFR)
|
||||
|
||||
`Reactor_PFR.tick(time_step)` operates per grid cell:
|
||||
|
||||
| Term | Notes |
|
||||
|:---|:---|
|
||||
| Dispersion | `(D / d_x²) · D2_op · state` — central-difference second-derivative operator. |
|
||||
| Advection | `(−sum(Fs) / (A · d_x)) · D_op · state` — first-derivative operator (central or upwind per config). |
|
||||
| Reaction | Per-cell `asm.compute_dC(slice, T)`. |
|
||||
| Transfer | OTR / `kla` on the `S_O` index, scaled by `n_x / (n_x − 2)` for interior cells only. |
|
||||
|
||||
Boundary conditions: **Danckwerts** at the inlet when `sum(Fs) > 0` (mixes inlet concentration with diffusive back-mix governed by `alpha`); **Neumann** (no-flux) at the outlet and at the inlet when there is no flow. After integration, the same `_capDissolvedOxygen` / `_arrayClip2Zero` post-processing applies cell-by-cell.
|
||||
|
||||
`updateState` extends `BaseReactorEngine.updateState` with two stability checks:
|
||||
|
||||
| Check | Threshold | Warning |
|
||||
|:---|:---|:---|
|
||||
| Local Peclet `Pe = d_x · sum(Fs) / (D · A)` | `≥ 2` | `Local Peclet number (…) is too high! Increase reactor resolution.` |
|
||||
| Courant `Co_D = D · timeStep / d_x²` | `≥ 0.5` | `Courant number (…) is too high! Reduce time step size.` |
|
||||
|
||||
---
|
||||
|
||||
## Lifecycle — what one `data.clock` advance does
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant clock as data.clock injector
|
||||
participant rx as reactor (specificClass)
|
||||
participant engine as kinetics engine (CSTR / PFR)
|
||||
participant downstream as settler / next reactor
|
||||
participant out as Port 0 / 1
|
||||
|
||||
clock->>rx: data.clock { timestamp }
|
||||
rx->>engine: updateState(timestamp)
|
||||
Note over engine: n_iter = floor(speedUpFactor × Δt / timeStep)
|
||||
alt upstreamReactor present
|
||||
engine->>engine: setInfluent = upstream.getEffluent
|
||||
end
|
||||
loop n_iter times
|
||||
engine->>engine: tick(timeStep) — integrate ASM3 rates
|
||||
engine->>engine: cap S_O to saturation, clip negatives
|
||||
end
|
||||
engine->>rx: emit 'stateChange' (currentTime)
|
||||
rx->>rx: re-emit 'stateChange' on BaseDomain emitter
|
||||
rx->>rx: notifyOutputChanged
|
||||
alt PFR engine
|
||||
rx->>out: Port 0 — GridProfile { grid, n_x, d_x, length, species }
|
||||
end
|
||||
rx->>out: Port 0 — Fluent { inlet=0, F, C[13] }
|
||||
rx->>out: Port 1 — InfluxDB scalars { flow_total, temperature, S_O…X_TS }
|
||||
downstream-->>rx: subscribes to stateChange via _connectReactor
|
||||
downstream->>downstream: pulls getEffluent on each stateChange
|
||||
```
|
||||
|
||||
The tick loop is opt-in (`static tickInterval = 1000`) because the integrator advances **process time** in steps that have no fixed wall-clock mapping. Without ticks the engine simply doesn't advance. `nodeClass._emitOutputs` is overridden so the `Fluent` / `GridProfile` envelope shape survives the BaseNodeAdapter pipeline.
|
||||
|
||||
---
|
||||
|
||||
## Child registration
|
||||
|
||||
Source: `src/specificClass.js` `configure()` wires the ChildRouter; `BaseReactorEngine._connectMeasurement` and `_connectReactor` do the actual subscription.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph kids["accepted children (softwareType)"]
|
||||
m_t["measurement<br/>asset.type=temperature<br/>positionVsParent=atEquipment"]:::ctrl
|
||||
m_o["measurement<br/>asset.type=quantity (oxygen)<br/>positionVsParent=numeric distance (PFR)"]:::ctrl
|
||||
r_up["reactor<br/>positionVsParent=upstream"]:::unit
|
||||
end
|
||||
m_t -->|temperature.measured.atEquipment| h_meas["engine._connectMeasurement<br/>(baseEngine.js)"]
|
||||
m_o -->|quantity(oxygen).measured.<distance>| h_meas
|
||||
r_up -.stateChange.-> h_react["engine._connectReactor<br/>(baseEngine.js)"]
|
||||
h_meas --> reconcile["reconcile T → engine.temperature<br/>reconcile O2 → state grid cell (PFR only)"]
|
||||
h_react --> pull["pull upstream getEffluent<br/>→ Fs[0] / Cs_in[0] before next tick"]
|
||||
classDef ctrl fill:#a9daee,color:#000
|
||||
classDef unit fill:#50a8d9,color:#000
|
||||
```
|
||||
|
||||
### `_connectMeasurement` event wiring
|
||||
|
||||
`measurement.measurements.emitter` fires `<measurementType>.measured.<position>` on every published value. The reactor subscribes:
|
||||
|
||||
```js
|
||||
const eventName = `${measurementType}.measured.${position}`;
|
||||
measurement.measurements.emitter.on(eventName, (eventData) => {
|
||||
this.measurements
|
||||
.type(measurementType).variant('measured').position(position)
|
||||
.value(eventData.value, eventData.timestamp, eventData.unit);
|
||||
this._updateMeasurement(measurementType, eventData.value, position, eventData);
|
||||
});
|
||||
```
|
||||
|
||||
`_updateMeasurement` (CSTR base): only `temperature` at `POSITIONS.AT_EQUIPMENT` is honoured — writes `engine.temperature`. Any other type logs `Type '<x>' not recognized for measured update.`
|
||||
|
||||
`_updateMeasurement` (PFR override): additionally handles `quantity (oxygen)` at a **numeric** position. Position is interpreted as metres along `length`; the value is written to grid cell `clamp(round(pos / length × n_x), 0, n_x − 1)`. Non-finite position / value, or `length ≤ 0`, logs a warn and the update is dropped.
|
||||
|
||||
### `_connectReactor` — upstream chain
|
||||
|
||||
Setting `positionVsParent: 'upstream'` on the upstream reactor's child-register makes this reactor subscribe to the upstream's `stateChange`. On every event the downstream's `updateState` runs, which first pulls the upstream's `getEffluent` into `Fs[0]` / `Cs_in[0]` then integrates.
|
||||
|
||||
> [!NOTE]
|
||||
> `diffuser` is **not** a registered child. It feeds aeration via the `data.otr` topic on Port 0 (handled in `commands/handlers.js` `dataOTR`). No child-registration handshake.
|
||||
|
||||
---
|
||||
|
||||
## Output ports
|
||||
|
||||
| Port | Carries | Sample shape |
|
||||
|:---|:---|:---|
|
||||
| 0 (process) | `Fluent` envelope every advance. For PFR: an additional `GridProfile` message sent **before** the `Fluent`. | `{topic: 'Fluent', payload: {inlet: 0, F, C: [...13...]}, timestamp}` |
|
||||
| 1 (telemetry) | InfluxDB line-protocol payload built from `getOutput()` via `outputUtils.formatMsg`. Fields: `flow_total`, `temperature`, and one per species. | `reactor,id=rx_a flow_total=1000,temperature=20,S_O=2.1,S_NH=0.8,...` |
|
||||
| 2 (registration) | `child.register` upward at init | `{topic: 'child.register', payload: <node.id>, positionVsParent, distance}` |
|
||||
|
||||
<!-- BEGIN AUTOGEN: data-model — populate via wiki-gen tool (TODO) -->
|
||||
|
||||
> [!NOTE]
|
||||
> Pending full node review (2026-05). The flat Port-1 telemetry shape (one field per species, plus `flow_total` + `temperature`) reflects the current `getOutput()` in `src/specificClass.js`.
|
||||
|
||||
| Key | Type | Unit | Source |
|
||||
|:---|:---|:---|:---|
|
||||
| `flow_total` | number | m³/d | `sum(Fs)` from the engine's effluent envelope |
|
||||
| `temperature` | number | °C | `engine.temperature` |
|
||||
| `S_O` | number | mg/L | effluent `C[0]` — dissolved oxygen, capped to saturation |
|
||||
| `S_I` | number | mg/L | effluent `C[1]` — inert soluble COD |
|
||||
| `S_S` | number | mg/L | effluent `C[2]` — readily biodegradable substrate |
|
||||
| `S_NH` | number | mg/L | effluent `C[3]` — ammonium nitrogen |
|
||||
| `S_N2` | number | mg/L | effluent `C[4]` — dinitrogen |
|
||||
| `S_NO` | number | mg/L | effluent `C[5]` — nitrate / nitrite |
|
||||
| `S_HCO` | number | mmol/L | effluent `C[6]` — alkalinity |
|
||||
| `X_I` | number | mg/L | effluent `C[7]` — inert particulate COD |
|
||||
| `X_S` | number | mg/L | effluent `C[8]` — slowly biodegradable substrate |
|
||||
| `X_H` | number | mg/L | effluent `C[9]` — heterotrophic biomass |
|
||||
| `X_STO` | number | mg/L | effluent `C[10]` — stored COD in biomass |
|
||||
| `X_A` | number | mg/L | effluent `C[11]` — autotrophic biomass |
|
||||
| `X_TS` | number | mg/L | effluent `C[12]` — total suspended solids |
|
||||
|
||||
<!-- END AUTOGEN: data-model -->
|
||||
|
||||
### Status badge
|
||||
|
||||
Composed by `getStatusBadge()` in `src/specificClass.js`:
|
||||
|
||||
```
|
||||
<EngineType> T=<temperature> C F=<flow> m³/d S_O=<S_O> mg/L
|
||||
```
|
||||
|
||||
Engine type is `CSTR` or `PFR` (derived from the constructor name). Fill is green by default; the badge is purely informational — no shape / colour transitions tied to plant state, since reactor has no FSM.
|
||||
|
||||
---
|
||||
|
||||
## Event sources
|
||||
|
||||
| Source | Where it fires | What it triggers |
|
||||
|:---|:---|:---|
|
||||
| `engine.emitter` `'stateChange'` | `BaseReactorEngine.updateState` after `n_iter > 0` integration steps | `specificClass` re-emits on `this.emitter`; BaseNodeAdapter `_emitOutputs` runs (Port 0 + Port 1) |
|
||||
| Child measurement emitter | `measurement.measurements.emitter` per `<type>.measured.<position>` | `engine._connectMeasurement` callback → writes into MeasurementContainer + `_updateMeasurement` reconcile |
|
||||
| Upstream reactor `'stateChange'` | Upstream reactor's `BaseDomain` emitter | `engine._connectReactor` callback → downstream `updateState(t)` runs, pulling upstream effluent first |
|
||||
| Inbound `msg.topic` | Node-RED input wire | `commandRegistry` dispatch |
|
||||
| `setInterval(tickInterval = 1000)` | `BaseNodeAdapter` periodic tick | `nodeClass._emitOutputs` → `source.updateState(Date.now())` + send |
|
||||
| `setInterval(statusInterval = 1000)` | `BaseNodeAdapter` | Status badge re-render |
|
||||
|
||||
---
|
||||
|
||||
## Where to start reading
|
||||
|
||||
| If you're changing… | Read first |
|
||||
|:---|:---|
|
||||
| ASM3 stoichiometry / kinetic constants | `src/reaction_modules/asm3_class.js` |
|
||||
| Mixed-tank integration, child wiring, influent / OTR / T setters | `src/kinetics/baseEngine.js`, `src/kinetics/cstr.js` |
|
||||
| Plug-flow discretization, dispersion, grid profile | `src/kinetics/pfr.js` |
|
||||
| Topic registration, alias deprecation | `src/commands/index.js`, `src/commands/handlers.js` |
|
||||
| Editor-field ↔ engine-config mapping | `src/nodeClass.js` `buildDomainConfig`, `src/specificClass.js` `_flattenEngineConfig` |
|
||||
| Port-0 envelope shape (`Fluent` + `GridProfile`) | `src/nodeClass.js` `_emitOutputs` |
|
||||
| Schema defaults, types, units | `generalFunctions/src/configs/reactor.json` |
|
||||
|
||||
---
|
||||
|
||||
## Related pages
|
||||
|
||||
| Page | Why |
|
||||
|:---|:---|
|
||||
| [Home](Home) | Intuitive overview |
|
||||
| [Reference — Contracts](Reference-Contracts) | Topic + config + child filters |
|
||||
| [Reference — Examples](Reference-Examples) | Shipped flows + debug recipes |
|
||||
| [Reference — Limitations](Reference-Limitations) | Known issues and open questions |
|
||||
| [settler wiki](https://gitea.wbd-rd.nl/RnD/settler/wiki/Home) | The typical downstream Unit that subscribes to reactor `stateChange` |
|
||||
| [diffuser wiki](https://gitea.wbd-rd.nl/RnD/diffuser/wiki/Home) | The Equipment node that pushes `data.otr` |
|
||||
| [EVOLV — Architecture](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Architecture) | Platform-wide three-tier pattern |
|
||||
227
wiki/Reference-Contracts.md
Normal file
227
wiki/Reference-Contracts.md
Normal file
@@ -0,0 +1,227 @@
|
||||
# Reference — Contracts
|
||||
|
||||
|
||||
|
||||
> [!NOTE]
|
||||
> Full topic contract, configuration schema, and child-registration filters for `reactor`. Source of truth: `src/commands/index.js`, `src/specificClass.js` `configure()`, and the schema at `generalFunctions/src/configs/reactor.json`.
|
||||
>
|
||||
> Pending full node review (2026-05). Content reflects `CONTRACT.md` and current source only.
|
||||
>
|
||||
> For an intuitive overview, return to the [Home](Home).
|
||||
|
||||
---
|
||||
|
||||
## Topic contract
|
||||
|
||||
The registry lives in `src/commands/index.js`. Each descriptor maps a canonical `msg.topic` to its handler; aliases emit a one-time deprecation warning the first time they fire.
|
||||
|
||||
<!-- BEGIN AUTOGEN: topic-contract — populate via wiki-gen tool (TODO) -->
|
||||
|
||||
| Canonical topic | Aliases | Payload | Unit | Effect |
|
||||
|:---|:---|:---|:---|:---|
|
||||
| `data.clock` | `clock` | `{timestamp: number}` (ms since epoch). If absent, handler falls back to `Date.now()`. | ms | Calls `source.updateState(timestamp)` — advances the ASM kinetics integrator by `n_iter = floor(speedUpFactor × Δt / timeStep_days)` steps that fit between `currentTime` and the supplied timestamp. Emits `stateChange` on completion. |
|
||||
| `data.fluent` | `Fluent` | `{inlet: number, F: number, C: number[13]}` | F in m³/d (canonical); C in mg/L (S_HCO in mmol/L) | Writes the per-inlet flow rate into `engine.Fs[inlet]` and concentration vector into `engine.Cs_in[inlet]`. Registry-level unit normalisation is skipped; the handler stores values as supplied. |
|
||||
| `data.otr` | `OTR` | numeric (`msg.payload` is the OTR scalar) | mg O₂ / L / d | Sets the externally-supplied oxygen transfer rate. Used by the kinetics engine **only when `kla` is `NaN`**; if `kla` is a finite number the internal mass-transfer formula `kla × (sat(T) − S_O)` is used and `data.otr` is ignored. |
|
||||
| `data.temperature` | `Temperature` | numeric or `{value: number}` | °C | Sets `engine.temperature`. Non-numeric / non-finite payloads log a warn (`Invalid temperature input: <raw>`) and are dropped. |
|
||||
| `data.dispersion` | `Dispersion` | numeric | m²/d | **PFR only.** Sets axial dispersion coefficient `D`. The next `updateState` warns if local Peclet ≥ 2 or Courant ≥ 0.5. On CSTR the setter is a no-op (`if (this.engine instanceof Reactor_PFR)` guard in `specificClass`). |
|
||||
| `child.register` | `registerChild` | child node id (string) | — | Looks up the sibling via `RED.nodes.getNode(id)` and delegates to `source.childRegistrationUtils.registerChild` with `msg.positionVsParent`. Missing child / source logs a warn and short-circuits. |
|
||||
|
||||
<!-- END AUTOGEN: topic-contract -->
|
||||
|
||||
### Modes / sources / actions
|
||||
|
||||
reactor has **no mode, no action allow-lists, no source gating**. All topics are accepted as long as the payload shape is valid. (Contrast with `rotatingMachine`, which gates every input through a mode × source matrix.)
|
||||
|
||||
---
|
||||
|
||||
## Data model — `getOutput()` shape
|
||||
|
||||
Composed each tick by `src/specificClass.js` `getOutput()`. Used to build the Port-1 InfluxDB payload; Port 0 carries the engine's `getEffluent` envelope directly.
|
||||
|
||||
### Port-0 process payload
|
||||
|
||||
The engine's effluent envelope, emitted on every successful `updateState` advance:
|
||||
|
||||
```json
|
||||
{
|
||||
"topic": "Fluent",
|
||||
"payload": { "inlet": 0, "F": <m³/d>, "C": [<13 species, mg/L>] },
|
||||
"timestamp": <ms since epoch>
|
||||
}
|
||||
```
|
||||
|
||||
For a PFR an additional message is sent **before** the `Fluent` on the same port each advance:
|
||||
|
||||
```json
|
||||
{
|
||||
"topic": "GridProfile",
|
||||
"payload": {
|
||||
"grid": [[<13 cells of n_x>]],
|
||||
"n_x": <int>,
|
||||
"d_x": <m>,
|
||||
"length": <m>,
|
||||
"species": ["S_O","S_I","S_S","S_NH","S_N2","S_NO","S_HCO","X_I","X_S","X_H","X_STO","X_A","X_TS"],
|
||||
"timestamp": <ms since epoch>
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Port-1 telemetry — scalar keys
|
||||
|
||||
| Key | Type | Unit | Source |
|
||||
|:---|:---|:---|:---|
|
||||
| `flow_total` | number | m³/d | `sum(Fs)` from effluent envelope |
|
||||
| `temperature` | number | °C | `engine.temperature` |
|
||||
| `S_O` | number | mg/L | effluent `C[0]` — capped to saturation by `_capDissolvedOxygen` |
|
||||
| `S_I` | number | mg/L | effluent `C[1]` |
|
||||
| `S_S` | number | mg/L | effluent `C[2]` |
|
||||
| `S_NH` | number | mg/L | effluent `C[3]` |
|
||||
| `S_N2` | number | mg/L | effluent `C[4]` |
|
||||
| `S_NO` | number | mg/L | effluent `C[5]` |
|
||||
| `S_HCO` | number | mmol/L | effluent `C[6]` — alkalinity |
|
||||
| `X_I` | number | mg/L | effluent `C[7]` |
|
||||
| `X_S` | number | mg/L | effluent `C[8]` |
|
||||
| `X_H` | number | mg/L | effluent `C[9]` |
|
||||
| `X_STO` | number | mg/L | effluent `C[10]` |
|
||||
| `X_A` | number | mg/L | effluent `C[11]` |
|
||||
| `X_TS` | number | mg/L | effluent `C[12]` |
|
||||
|
||||
Non-finite species values are **omitted** from the output (the `Number.isFinite` guard in `getOutput`); they are not emitted as `null`. Pick one convention per consumer (absent vs null) and document it — see `.claude/rules/output-coverage.md`.
|
||||
|
||||
### Species ordering
|
||||
|
||||
The 13-species vector is **fixed**:
|
||||
|
||||
| Index | Key | Group |
|
||||
|:---:|:---|:---|
|
||||
| 0 | `S_O` | soluble |
|
||||
| 1 | `S_I` | soluble |
|
||||
| 2 | `S_S` | soluble |
|
||||
| 3 | `S_NH` | soluble |
|
||||
| 4 | `S_N2` | soluble |
|
||||
| 5 | `S_NO` | soluble |
|
||||
| 6 | `S_HCO` | soluble |
|
||||
| 7 | `X_I` | particulate |
|
||||
| 8 | `X_S` | particulate |
|
||||
| 9 | `X_H` | particulate |
|
||||
| 10 | `X_STO` | particulate |
|
||||
| 11 | `X_A` | particulate |
|
||||
| 12 | `X_TS` | particulate |
|
||||
|
||||
Don't reshuffle — `getOutput()` and `_flattenEngineConfig()` both depend on this exact order, as does `additional_nodes/settling-basin` and the downstream `settler` node.
|
||||
|
||||
### Status badge
|
||||
|
||||
`getStatusBadge()` in `src/specificClass.js`:
|
||||
|
||||
```
|
||||
<EngineType> T=<°C>.X C F=<m³/d>.XX m³/d S_O=<mg/L>.XX mg/L
|
||||
```
|
||||
|
||||
Engine type is the constructor name with `Reactor_` stripped (so `CSTR` or `PFR`). Badge is always green-dot (no FSM-driven state).
|
||||
|
||||
---
|
||||
|
||||
## Configuration schema — editor form to config keys
|
||||
|
||||
Source of truth: `generalFunctions/src/configs/reactor.json` plus `nodeClass.buildDomainConfig` (`src/nodeClass.js`).
|
||||
|
||||
### General (`config.general`)
|
||||
|
||||
| Form field | Config key | Default | Notes |
|
||||
|:---|:---|:---|:---|
|
||||
| Name | `general.name` | `Reactor` | Human-readable. |
|
||||
| (auto-assigned) | `general.id` | `null` | Node-RED node id. |
|
||||
| Default unit | `general.unit` | `null` | Unused by the reactor's own logic (the engines pick up units from the schema's `rules.unit` strings); kept for parent compatibility. |
|
||||
| Log enabled | `general.logging.enabled` | `true` | Master switch. |
|
||||
| Log level | `general.logging.logLevel` | `info` | `debug` / `info` / `warn` / `error`. |
|
||||
|
||||
### Functionality (`config.functionality`)
|
||||
|
||||
| Form field | Config key | Default | Notes |
|
||||
|:---|:---|:---|:---|
|
||||
| Position vs parent | `functionality.positionVsParent` | `atEquipment` | Used in the child-register payload that goes UP to whatever parent registers this reactor. Enum: `upstream` / `atEquipment` / `downstream`. |
|
||||
| (hidden) | `functionality.softwareType` | `reactor` | Constant. |
|
||||
| (hidden) | `functionality.role` | `Biological reactor for wastewater treatment` | Constant. |
|
||||
|
||||
### Reactor (`config.reactor`)
|
||||
|
||||
| Form field | Config key | Schema default | Range / unit | Notes |
|
||||
|:---|:---|:---|:---|:---|
|
||||
| Reactor type | `reactor.reactor_type` | `CSTR` | enum: `CSTR` / `PFR` | Selected once at `configure()`. `_buildEngine` calls `.toUpperCase()` so `pfr` and `PFR` both resolve. |
|
||||
| Volume | `reactor.volume` | `1000` | m³, `> 0` | Used by mass balance and (PFR) surface-area derivation. |
|
||||
| Length | `reactor.length` | `10` | m, `> 0` | **PFR only.** Sets axial extent and grid pitch (`d_x = length / n_x`). |
|
||||
| Resolution | `reactor.resolution_L` | `10` | integer `≥ 1` | **PFR only.** Grid cell count `n_x`. |
|
||||
| Alpha | `reactor.alpha` | `0.5` | `0..1` | **PFR only.** Inlet boundary blend: `0` = pure Danckwerts, `1` = fully mixed inlet. |
|
||||
| Inlets | `reactor.n_inlets` | `1` | integer `≥ 1` | `Fs[]` / `Cs_in[]` array size. |
|
||||
| kLa | `reactor.kla` | `0` | 1/h, `≥ 0`; set `NaN` to disable | Enables internal aeration `OTR = kla · (sat(T) − S_O)`. When `NaN`, `data.otr` is honoured instead. |
|
||||
| Time step | `reactor.timeStep` | `0.001` | `≥ 0.0001` | Schema declares unit `h`; `baseEngine.js` converts by `÷ 86400` (treating it as seconds). See [Limitations — timeStep unit mismatch](Reference-Limitations#timestep-unit-mismatch). |
|
||||
| Speed-up factor | `reactor.speedUpFactor` | `1` | `≥ 1` | Multiplies wall-clock Δt when computing `n_iter`. `2` means twice as many internal steps per second. |
|
||||
|
||||
### Initial state (`config.initialState`)
|
||||
|
||||
13 starting concentrations, all written into the engine's `state` (CSTR: single row; PFR: replicated across all `n_x` grid cells at construction).
|
||||
|
||||
| Form field | Config key | Schema default | HTML default | Unit | Notes |
|
||||
|:---|:---|:---|:---|:---|:---|
|
||||
| Initial S_O | `initialState.S_O` | `0` | check editor | mg/L | Capped to saturation on the first tick. |
|
||||
| Initial S_I | `initialState.S_I` | `30` | check editor | mg/L | Inert soluble COD. |
|
||||
| Initial S_S | `initialState.S_S` | `70` | check editor | mg/L | Readily biodegradable substrate. |
|
||||
| Initial S_NH | `initialState.S_NH` | `25` | check editor | mg/L | Ammonium — declines with nitrification. |
|
||||
| Initial S_N2 | `initialState.S_N2` | `0` | check editor | mg/L | Dinitrogen. |
|
||||
| Initial S_NO | `initialState.S_NO` | `0` | check editor | mg/L | Nitrate / nitrite. |
|
||||
| Initial S_HCO | `initialState.S_HCO` | `5` | check editor | mmol/L | Alkalinity. |
|
||||
| Initial X_I | `initialState.X_I` | `1000` | check editor | mg/L | Inert particulate COD. |
|
||||
| Initial X_S | `initialState.X_S` | `100` | check editor | mg/L | Slowly biodegradable substrate. |
|
||||
| Initial X_H | `initialState.X_H` | `2000` | check editor | mg/L | Heterotrophic biomass. |
|
||||
| Initial X_STO | `initialState.X_STO` | `0` | check editor | mg/L | Stored COD in biomass. |
|
||||
| Initial X_A | `initialState.X_A` | `200` | **`0.001`** | mg/L | **Footgun.** HTML default in `reactor.html` (per `CONTRACT.md`) is effectively zero, disabling nitrification. Always verify the deployed form value. |
|
||||
| Initial X_TS | `initialState.X_TS` | `3500` | check editor | mg/L | Total suspended solids — drives downstream settler split. |
|
||||
|
||||
> [!WARNING]
|
||||
> The HTML form supplies its own defaults; for fields where they differ from the schema (notably `X_A`), the HTML wins at deploy time. Either match the schema in the HTML or audit every deployed flow.
|
||||
|
||||
### Unit policy
|
||||
|
||||
reactor does **not** declare a UnitPolicy in `specificClass`. Units are carried in the schema's `rules.unit` strings (m³, m, 1/h, mg/L, mmol/L) and consumed by the engines without normalisation through MeasurementContainer's canonical-unit rule. Notable internal conversions:
|
||||
|
||||
| Quantity | What the engine uses internally | Where converted |
|
||||
|:---|:---|:---|
|
||||
| `timeStep` | days | `baseEngine.js` line ~40: `timeStep = config.timeStep / 86400` |
|
||||
| `Fs` | m³/d (assumed by mass-balance formulas) | not converted — the caller is expected to push m³/d on `data.fluent` |
|
||||
| `temperature` | °C | stored as supplied (Celsius); `_calcOxygenSaturation(T)` expects °C |
|
||||
|
||||
This is a known divergence from the platform-wide canonical-unit rule (`Pa` / `m³/s` / `W` / `K`). Tracked.
|
||||
|
||||
---
|
||||
|
||||
## Child registration
|
||||
|
||||
Source: `src/specificClass.js` `configure()` (ChildRouter wiring) + `BaseReactorEngine._connectMeasurement` / `_connectReactor`.
|
||||
|
||||
| Software type | Filter | Wired to | Side-effect |
|
||||
|:---|:---|:---|:---|
|
||||
| `measurement` | `asset.type = 'temperature'`, `positionVsParent = atEquipment` | `engine._connectMeasurement` → `_updateMeasurement` | Writes `engine.temperature`. CSTR only honours this. |
|
||||
| `measurement` | `asset.type = 'quantity (oxygen)'`, `positionVsParent = <numeric distance>` | `engine._connectMeasurement` → `Reactor_PFR._updateMeasurement` | **PFR only.** Maps measurement to nearest grid cell by `clamp(round(pos / length × n_x), 0, n_x − 1)`. Writes into `state[cell][S_O_INDEX]`. |
|
||||
| `reactor` | `positionVsParent = 'upstream'` | `engine._connectReactor` | Subscribes to upstream reactor's `stateChange`. Each event triggers downstream `updateState`, which pulls upstream `getEffluent` into `Fs[0]` / `Cs_in[0]` before integrating. |
|
||||
|
||||
### Not a child: `diffuser`
|
||||
|
||||
`diffuser` (Equipment Module) is **not** registered as a reactor child. It feeds aeration via the `data.otr` topic on Port 0. No child-registration handshake is involved. If you want the diffuser's OTR to drive the reactor, wire the diffuser's process output to the reactor's input directly.
|
||||
|
||||
### Unrecognised softwareType
|
||||
|
||||
`BaseReactorEngine.registerChild` logs `Unrecognized softwareType: <x>` and drops the registration. There is no `valve`, `rotatingMachine`, etc. acceptance path.
|
||||
|
||||
---
|
||||
|
||||
## Related pages
|
||||
|
||||
| Page | Why |
|
||||
|:---|:---|
|
||||
| [Home](Home) | Intuitive overview |
|
||||
| [Reference — Architecture](Reference-Architecture) | Code map, integration sequence, kinetics |
|
||||
| [Reference — Examples](Reference-Examples) | Shipped flows + debug recipes |
|
||||
| [Reference — Limitations](Reference-Limitations) | Known issues and open questions |
|
||||
| [EVOLV — Topic Conventions](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topic-Conventions) | Platform-wide topic rules |
|
||||
| [EVOLV — Telemetry](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Telemetry) | Port 0 / 1 / 2 InfluxDB layout |
|
||||
160
wiki/Reference-Examples.md
Normal file
160
wiki/Reference-Examples.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# Reference — Examples
|
||||
|
||||
|
||||
|
||||
> [!NOTE]
|
||||
> Every example flow shipped under `nodes/reactor/examples/`, plus how to load them, what they show, and the debug recipes that go with them. Live source: `nodes/reactor/examples/`.
|
||||
>
|
||||
> Pending full node review (2026-05). The current flows predate the standard 3-tier example-flow rework that `rotatingMachine` has completed; planned upgrade is tracked in the EVOLV superproject memory ("Example Flows" TODO).
|
||||
|
||||
---
|
||||
|
||||
## Shipped examples
|
||||
|
||||
| File | Tier | Dependencies | What it shows |
|
||||
|:---|:---:|:---|:---|
|
||||
| `basic.flow.json` | 1 | EVOLV only | Single CSTR with one inlet. Inject `data.fluent` to set influent, `data.clock` to advance the integrator; watch `Fluent` effluent on Port 0 and InfluxDB scalars on Port 1. |
|
||||
| `integration.flow.json` | 2 | EVOLV only | Upstream `reactor` → `reactor` → `settler` chain. The downstream reactor registers the upstream via `child.register positionVsParent=upstream`; on each upstream `stateChange` the downstream pulls effluent and advances. |
|
||||
| `edge.flow.json` | 3 | EVOLV only | PFR with axial dispersion (`data.dispersion`) and multi-inlet (`n_inlets > 1`). Emits both `GridProfile` and `Fluent` per advance. |
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Screenshots needed.** Editor capture of each example flow. Save as `wiki/_partial-screenshots/reactor/{01-basic-cstr,02-chain,03-pfr-edge}.png`. Replace these callouts with image links once captured.
|
||||
|
||||
The legacy `additional_nodes/recirculation-pump` and `additional_nodes/settling-basin` Node-RED nodes are shipped from this repo but are not yet refactored to BaseDomain — they aren't part of these examples.
|
||||
|
||||
---
|
||||
|
||||
## Loading a flow
|
||||
|
||||
### Via the editor
|
||||
|
||||
1. Open the Node-RED editor at `http://localhost:1880`.
|
||||
2. Menu → Import → drag the JSON file.
|
||||
3. Click Deploy.
|
||||
|
||||
### Via the Admin API
|
||||
|
||||
```bash
|
||||
curl -X POST -H 'Content-Type: application/json' \
|
||||
--data @nodes/reactor/examples/basic.flow.json \
|
||||
http://localhost:1880/flows
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example — Basic CSTR
|
||||
|
||||
Single-reactor flow with one inlet and the minimum set of inputs needed to drive nitrification.
|
||||
|
||||
### What to do after deploy
|
||||
|
||||
1. Inject `data.temperature` with `payload: 15` (or whatever process T you want). Optional — default is 20 °C.
|
||||
2. Inject `data.fluent` with:
|
||||
```json
|
||||
{
|
||||
"topic": "data.fluent",
|
||||
"payload": {
|
||||
"inlet": 0,
|
||||
"F": 1000,
|
||||
"C": [0, 30, 70, 25, 0, 0, 5, 1000, 100, 2000, 0, 200, 3500]
|
||||
}
|
||||
}
|
||||
```
|
||||
Note `C[11] = 200` (X_A — autotroph biomass). If you copy the HTML default of `0.001`, nitrification never starts.
|
||||
3. If `kla > 0` is configured, you can skip OTR injection; the engine aerates internally. Otherwise inject `data.otr` with a positive scalar.
|
||||
4. Inject `data.clock` repeatedly (or rely on the periodic tick — `tickInterval = 1000` ms wall-clock). Each advance integrates `n_iter = floor(speedUpFactor · Δt / timeStep_days)` internal steps.
|
||||
5. Watch the debug tap on Port 0: `Fluent` envelopes with the 13-species effluent. `S_NH` should fall, `S_NO` should rise — nitrification is proceeding.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **GIF needed.** Demo recording of `S_NH` ↓ / `S_NO` ↑ over 30 simulated days. Save as `wiki/_partial-gifs/reactor/01-basic-cstr.gif`.
|
||||
|
||||
---
|
||||
|
||||
## Example — Reactor chain
|
||||
|
||||
Upstream → downstream coupling demo. The downstream reactor registers the upstream via:
|
||||
|
||||
```json
|
||||
{
|
||||
"topic": "child.register",
|
||||
"payload": "<upstream-reactor-node-id>",
|
||||
"positionVsParent": "upstream"
|
||||
}
|
||||
```
|
||||
|
||||
On every upstream `stateChange`, `engine._connectReactor` triggers downstream `updateState`. That call first reads `upstream.getEffluent` into the downstream's `Fs[0]` / `Cs_in[0]`, then integrates. So one `data.clock` to the upstream advances the whole chain.
|
||||
|
||||
> [!NOTE]
|
||||
> Pending full node review (2026-05). The flow currently in `integration.flow.json` may not yet conform to the multi-tab layout standard (Process Plant / Dashboard UI / Demo Drivers / Setup) described in `.claude/rules/node-red-flow-layout.md` — planned upgrade tracked in the EVOLV "Example Flows" TODO.
|
||||
|
||||
---
|
||||
|
||||
## Example — PFR edge
|
||||
|
||||
Plug-flow reactor with axial discretization. After deploy:
|
||||
|
||||
1. Inject `data.dispersion` with `payload: <m²/d>` to set the axial dispersion coefficient `D`.
|
||||
2. Inject one or more `data.fluent` messages with distinct `inlet` indices (0..`n_inlets − 1`).
|
||||
3. Drive with `data.clock` as usual.
|
||||
4. Watch Port 0: each advance emits a `GridProfile` **before** the `Fluent`. The grid has `n_x` rows, 13 columns each.
|
||||
5. Add a `measurement` child with `asset.type = 'quantity (oxygen)'` and a numeric `positionVsParent` (e.g. `5` for 5 m from the inlet). On each measurement event the PFR engine writes the value into the nearest grid cell's `S_O`.
|
||||
|
||||
Stability tips:
|
||||
|
||||
- `Pe_local = d_x · sum(Fs) / (D · A)` must be `< 2` — if you see `Local Peclet number ... is too high!`, either increase `resolution_L` (more cells, smaller `d_x`) or raise `D`.
|
||||
- `Co_D = D · timeStep / d_x²` must be `< 0.5` for the explicit FD scheme — if you see `Courant number ... is too high!`, decrease `timeStep`.
|
||||
|
||||
---
|
||||
|
||||
## Debug recipes
|
||||
|
||||
| Symptom | First thing to check | Where to look |
|
||||
|:---|:---|:---|
|
||||
| `S_NH` stays at its initial value — nitrification not proceeding | `initialState.X_A` is effectively zero (HTML default is `0.001` mg/L). Set to `~50` or higher to seed autotrophs. | `reactor.html` ↔ `generalFunctions/src/configs/reactor.json` `initialState.X_A` |
|
||||
| `Fluent` payload `F = 0` | No `data.fluent` arrived, or `Fs[0]` is still 0 (no inlet flow). Check the message payload shape: `{inlet, F, C}`. | `src/commands/handlers.js` `dataFluent`, engine `setInfluent` |
|
||||
| `Fluent` payload appears, but `C` array is all zeros / unchanged | `data.clock` not arriving, or `n_iter = 0` (timestamp delta too small for the configured `timeStep`). Bump `speedUpFactor` or check that clock injects are firing. | `engine.updateState` in `baseEngine.js` |
|
||||
| PFR `GridProfile` not emitted | `reactor.reactor_type` is `CSTR` — only PFR has a grid profile. | `nodeClass._emitOutputs`, `pfr.getGridProfile` |
|
||||
| `temperature` ignored | Payload is non-numeric, or wrapped as `{value: ...}` with `value` non-finite. Look for `Invalid temperature input: <raw>` in the log. | `baseEngine.js` `setTemperature` setter |
|
||||
| Temperature child measurement not reconciling | The child's `asset.type` must be exactly `'temperature'` and `positionVsParent = atEquipment`. Anything else logs `Type '<x>' not recognized for measured update.` | `baseEngine.js` `_updateMeasurement` |
|
||||
| `Local Peclet number ... is too high!` warning on every PFR `updateState` | Either `D` is too small, or `d_x` is too large. Increase `resolution_L` or set a larger dispersion. | `pfr.updateState` Peclet guard |
|
||||
| `Courant number ... is too high!` warning | `timeStep` is too large for the configured `D`. Reduce it. | `pfr.updateState` Courant guard |
|
||||
| Settler downstream not updating | Settler must subscribe to the **reactor's `emitter`**, not `reactor.measurements.emitter`. Historical bug in `settler/src/specificClass.js` `_connectReactor` (fixed 2026-03-02). | upstream chain wiring, `settler._connectReactor` |
|
||||
| `wiki:datamodel` autogen script slow / timing out | `mathjs` cold-start is ~13 s. The current 60 s wrapper sometimes times out. | known limitation; fall back to the hand-curated Concrete sample in `CONTRACT.md` `Home.md` |
|
||||
| `reactor_type: 'pfr'` (lowercase) silently runs CSTR | Schema validator lowercases the enum; `_buildEngine` calls `.toUpperCase()` to compensate. If you stripped that guard, lowercase `pfr` falls through to the default branch (CSTR). | `src/specificClass.js` `_buildEngine` |
|
||||
| `data.otr` value ignored | `reactor.kla > 0`. The engine prefers internal `kla · (sat − S_O)` over external OTR. Set `kla = NaN` to enable external OTR. | `cstr.tick` / `pfr.tick` `klaIsNaN` branch |
|
||||
|
||||
> Never ship `enableLog: 'debug'` in a demo — the kinetics engines log per-step on debug, which fills the container log within seconds.
|
||||
|
||||
---
|
||||
|
||||
## Docker compose snippet
|
||||
|
||||
To bring up Node-RED + InfluxDB with EVOLV nodes pre-loaded:
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml (extract)
|
||||
services:
|
||||
nodered:
|
||||
build: ./docker/nodered
|
||||
ports: ['1880:1880']
|
||||
volumes:
|
||||
- ./docker/nodered/data:/data/evolv
|
||||
influxdb:
|
||||
image: influxdb:2.7
|
||||
ports: ['8086:8086']
|
||||
```
|
||||
|
||||
Full file: [EVOLV/docker-compose.yml](https://gitea.wbd-rd.nl/RnD/EVOLV/src/branch/development/docker-compose.yml).
|
||||
|
||||
---
|
||||
|
||||
## Related pages
|
||||
|
||||
| Page | Why |
|
||||
|:---|:---|
|
||||
| [Home](Home) | Intuitive overview |
|
||||
| [Reference — Contracts](Reference-Contracts) | Topic + config + child filters |
|
||||
| [Reference — Architecture](Reference-Architecture) | Code map, kinetics engines, integration sequence |
|
||||
| [Reference — Limitations](Reference-Limitations) | Known issues and open questions |
|
||||
| [settler — Examples](https://gitea.wbd-rd.nl/RnD/settler/wiki/Reference-Examples) | The typical downstream Unit |
|
||||
| [EVOLV — Topology Patterns](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topology-Patterns) | Where reactor fits in a larger plant |
|
||||
132
wiki/Reference-Limitations.md
Normal file
132
wiki/Reference-Limitations.md
Normal file
@@ -0,0 +1,132 @@
|
||||
# Reference — Limitations
|
||||
|
||||
|
||||
|
||||
> [!NOTE]
|
||||
> What `reactor` does not do, current rough edges, and open questions. Open items live in `.agents/improvements/IMPROVEMENTS_BACKLOG.md` and `.claude/refactor/OPEN_QUESTIONS.md` in the superproject.
|
||||
>
|
||||
> Pending full node review (2026-05). Content reflects `CONTRACT.md`, the current source, and a partial walkthrough of `src/kinetics/` — not a full audit.
|
||||
|
||||
---
|
||||
|
||||
## When you would not use this node
|
||||
|
||||
| Scenario | Use instead |
|
||||
|:---|:---|
|
||||
| A passive equalisation tank (no biological reactions, just buffering) | A simple Node-RED buffer / function node — the kinetics engines assume reactions are happening. |
|
||||
| A residence-time delay (plug-flow without ASM) | A delay node or custom buffer; the ASM3 13-species machinery + `mathjs` cold-start are overkill. |
|
||||
| Aerobic-only contactors where you only need oxygen mass-transfer | An OTR-only model is lighter; ASM3 brings 13 species you'll ignore. |
|
||||
| A clarifier / settler | `settler` — reactor has no settling, no sludge thickening, no underflow / overflow split. |
|
||||
| A pump / blower / valve | `rotatingMachine` / `valve` — reactor is a process-tank model, not an actuator. |
|
||||
| Anaerobic digestion | ASM3 is calibrated for activated sludge under aerobic / anoxic conditions. ADM1 (a separate model family) is the right tool for digesters. |
|
||||
|
||||
---
|
||||
|
||||
## Known limitations
|
||||
|
||||
### `X_A` initial default footgun
|
||||
|
||||
The HTML editor form's default for initial autotroph biomass is **`0.001` mg/L** (effectively zero). The JSON schema default is `200` mg/L. The HTML wins at deploy time. With `X_A ≈ 0` nitrification never starts — `S_NH` stays at the influent value forever, no `S_NO` is produced.
|
||||
|
||||
> [!WARNING]
|
||||
> Always open every deployed reactor node and confirm `Initial X_A` is `≥ ~50` mg/L before expecting nitrification. Tracked in `CONTRACT.md` `## 14` row 2 and in EVOLV memory `MEMORY.md` "Key Integration Gotchas".
|
||||
|
||||
### `mathjs` cold-start ~13 s
|
||||
|
||||
`baseEngine.js` requires `mathjs`. The first `require('mathjs')` in a Node.js process takes ~13 s wall-clock to initialise. This delays first `data.clock` advance after a fresh deploy, and can time out the `wiki:datamodel` autogen wrapper (60 s budget). Two remedies tracked:
|
||||
|
||||
1. Tree-shake `mathjs` to only the operations actually used (`add`, `multiply`, `diag`, `resize`, `sum`, `divide`).
|
||||
2. Lazy-initialise / cache the instance.
|
||||
|
||||
Tracked in `.claude/refactor/OPEN_QUESTIONS.md` — "mathjs slow load".
|
||||
|
||||
### `timeStep` unit mismatch
|
||||
|
||||
- HTML form label: `Time step [s]`.
|
||||
- Schema (`generalFunctions/src/configs/reactor.json` line ~144): `unit: "h"`.
|
||||
- `baseEngine.js` line ~40 converts by `÷ 86400` (seconds → days) before using it.
|
||||
|
||||
The conversion suggests the **true** unit is seconds. Schema is wrong. Until reconciled, treat the form field as seconds. Tracked in `CONTRACT.md` `## 14` row 7 and in `OPEN_QUESTIONS.md` (Phase 5/6 cleanup list).
|
||||
|
||||
### `reactor_type` enum casing
|
||||
|
||||
The JSON schema validator lowercases `reactor_type` (so `'PFR'` → `'pfr'`). `Reactor._buildEngine` calls `.toUpperCase()` to compensate. If that guard is ever removed prematurely (before the platform-wide canonical casing rule is decided in Phase 7), PFR configs silently fall back to the default branch — which constructs a CSTR. Tracked in `OPEN_QUESTIONS.md`.
|
||||
|
||||
### `getEffluent` shape historically varied
|
||||
|
||||
Earlier versions of `BaseReactorEngine.getEffluent` returned either an envelope object or an array of envelopes (multi-outlet PFR). The current code emits a single `{topic, payload, timestamp}` envelope, but the downstream `settler._connectReactor` tolerates **both** shapes. Don't break this contract without coordinating with the settler node. EVOLV memory records a 2026-03-02 fix in settler for the array-vs-envelope assumption.
|
||||
|
||||
### No FSM — no mode / setpoint / startup-shutdown sequencing
|
||||
|
||||
reactor has no startup, no shutdown, no e-stop, no mode, no setpoint. It runs continuous-state ODE / PDE integration unconditionally as long as `data.clock` advances (or the tick loop fires). A downstream consumer that expects a `state` field on Port 0 will get nothing of the sort. This is by design — biological reactors don't have meaningful FSM states — but it's a divergence from `rotatingMachine` / `pumpingStation` patterns that callers should know about.
|
||||
|
||||
### No mode / source / action allow-list gating
|
||||
|
||||
All incoming topics are accepted as long as the payload validates. There is no `parent` / `GUI` / `fysical` source-gating, no `auto` / `virtualControl` / `fysicalControl` mode-gating. If you want to lock down a deployed reactor (e.g. ignore manual `data.fluent` injections while a real flow sensor is wired), you must do it externally.
|
||||
|
||||
### `additional_nodes/` legacy companions not refactored
|
||||
|
||||
`additional_nodes/recirculation-pump.js` and `additional_nodes/settling-basin.js` are sibling Node-RED nodes shipped from the reactor repo (because they share the same package context). They are **not yet refactored to BaseDomain**. Tracked as P6.5 follow-up.
|
||||
|
||||
### `reaction_modules/` legacy directory
|
||||
|
||||
`src/reaction_modules/asm3_class.js` is consumed by the current engines. `src/reaction_modules/asm3_class Koch.js` is a legacy plug-in variant **not consumed by anything in the current codebase**. Removal pending. Tracked as P6.5 follow-up.
|
||||
|
||||
### Units don't follow EVOLV canonical-unit rule
|
||||
|
||||
The platform-wide MeasurementContainer canonical units are `Pa` / `m³/s` / `W` / `K`. reactor uses m³/d for flow, °C for temperature, mg/L (or mmol/L for alkalinity) for concentrations. No conversion at the system boundary. Calling code that expects canonical units must convert.
|
||||
|
||||
### `data.dispersion` is silently a no-op on CSTR
|
||||
|
||||
`specificClass.set setDispersion` checks `if (this.engine instanceof Reactor_PFR)` before forwarding. On a CSTR the setter just drops the payload — no warn, no error. If you deploy a flow that injects `data.dispersion` and switch the reactor type to CSTR, the injection is silently ignored.
|
||||
|
||||
### Single output-shape convention not documented per-key
|
||||
|
||||
The `getOutput()` implementation **omits** non-finite species values (`Number.isFinite` guard) rather than emitting them as `null`. Per `.claude/rules/output-coverage.md`, every node should pick one convention and document it. reactor's is "absent" — downstream consumers should treat a missing species key as "not produced this tick", never as zero.
|
||||
|
||||
### `output-coverage` manifest not yet present
|
||||
|
||||
`test/_output-manifest.md` (required by the platform-wide output-coverage rule, 2026-05-14) is not yet checked in for reactor. The Port-0 envelope shape, Port-1 InfluxDB fields, and `GridProfile` payload all need enumeration with populated + degraded test coverage. Tracked in `.agents/improvements/IMPROVEMENTS_BACKLOG.md`.
|
||||
|
||||
---
|
||||
|
||||
## Open questions (tracked)
|
||||
|
||||
| Question | Where it lives |
|
||||
|:---|:---|
|
||||
| `mathjs` slow load — tree-shake or lazy-init | `.claude/refactor/OPEN_QUESTIONS.md` — "mathjs slow load" |
|
||||
| `reactor_type` enum casing — platform-wide canonical | `.claude/refactor/OPEN_QUESTIONS.md` — "reactor schema enum lowercases reactor_type" |
|
||||
| `timeStep` unit reconciliation (HTML `s` vs schema `h` vs engine `d`) | `OPEN_QUESTIONS.md` Phase 5/6 cleanup list |
|
||||
| Removal of `reaction_modules/asm3_class Koch.js` and `additional_nodes/*` | P6.5 follow-up |
|
||||
| Output-coverage manifest + populated / degraded tests | `.agents/improvements/IMPROVEMENTS_BACKLOG.md` |
|
||||
| Should reactor adopt a canonical-unit boundary like the rest of EVOLV? | Internal — not yet ticketed |
|
||||
| Multi-outlet PFR (separate effluent streams per spatial point) | Internal — long-term |
|
||||
|
||||
---
|
||||
|
||||
## Migration notes
|
||||
|
||||
### From the pre-`BaseDomain` reactor
|
||||
|
||||
The current `specificClass` extends `BaseDomain` and uses ChildRouter to dispatch `measurement` / `reactor` registrations. Older flows that pre-date this refactor may have hand-wired child handlers; redeploying after `npm install` should pick up the new path automatically — no schema migration is required.
|
||||
|
||||
### From legacy topic names
|
||||
|
||||
The five `data.*` topics replace the pre-canonical PascalCase aliases (`Fluent`, `OTR`, `Temperature`, `Dispersion`, `clock`). The aliases are still accepted and emit a one-time deprecation warning on first use, but will be removed in Phase 7. Migrate flows by renaming the topic string on each inject.
|
||||
|
||||
### From hand-counted internal steps
|
||||
|
||||
Before the `speedUpFactor` field, simulation acceleration required adjusting `timeStep`. The current path is to leave `timeStep` at its physically-meaningful value (~1 s) and crank `speedUpFactor` to advance more process-time per wall-clock second. Old flows with abnormally large `timeStep` should be re-saved with the new field.
|
||||
|
||||
---
|
||||
|
||||
## Related pages
|
||||
|
||||
| Page | Why |
|
||||
|:---|:---|
|
||||
| [Home](Home) | Intuitive overview |
|
||||
| [Reference — Contracts](Reference-Contracts) | Topic + config + child filters |
|
||||
| [Reference — Architecture](Reference-Architecture) | Code map, kinetics engines, integration sequence |
|
||||
| [Reference — Examples](Reference-Examples) | Shipped flows + debug recipes |
|
||||
| [settler — Limitations](https://gitea.wbd-rd.nl/RnD/settler/wiki/Reference-Limitations) | The downstream Unit's quirks (incl. the historical `getEffluent` shape tolerance) |
|
||||
| [diffuser wiki](https://gitea.wbd-rd.nl/RnD/diffuser/wiki/Home) | The Equipment node that pushes `data.otr` — not a registered child |
|
||||
20
wiki/_Sidebar.md
Normal file
20
wiki/_Sidebar.md
Normal file
@@ -0,0 +1,20 @@
|
||||
### reactor
|
||||
|
||||
- [Home](Home)
|
||||
|
||||
**Reference**
|
||||
|
||||
- [Contracts](Reference-Contracts)
|
||||
- [Architecture](Reference-Architecture)
|
||||
- [Examples](Reference-Examples)
|
||||
- [Limitations](Reference-Limitations)
|
||||
|
||||
**Related**
|
||||
|
||||
- [EVOLV master wiki](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Home)
|
||||
- [settler wiki](https://gitea.wbd-rd.nl/RnD/settler/wiki/Home)
|
||||
- [diffuser wiki](https://gitea.wbd-rd.nl/RnD/diffuser/wiki/Home)
|
||||
- [measurement wiki](https://gitea.wbd-rd.nl/RnD/measurement/wiki/Home)
|
||||
- [Topology Patterns](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topology-Patterns)
|
||||
- [Topic Conventions](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topic-Conventions)
|
||||
- [Telemetry](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Telemetry)
|
||||
Reference in New Issue
Block a user