> **Reflects code as of `b8247fc` · 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
**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.
| `reactor` | upstream | `engine._connectReactor` | Subscribes to upstream reactor's `stateChange`; pulls effluent into `Fs[0]` / `Cs_in[0]` before next integration step. |
## 7. Lifecycle — what one `data.clock` advance does
```mermaid
sequenceDiagram
participant clock as clock injector
participant reactor as reactor
participant engine as kinetics engine
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 steps,<br/>each timeStep × speedUpFactor
engine->>engine: integrate ASM3 rates
engine->>engine: emit 'stateChange'
reactor->>reactor: notifyOutputChanged
reactor->>out: Fluent { inlet=0, F, C[13] }
alt PFR
reactor->>out: GridProfile { grid, n_x, d_x, … }
end
out->>downstream: Fluent envelope
```
`stateChange` re-emits on `reactor.emitter` (BaseDomain emitter) so downstream reactors / settlers can listen. The effluent emission goes through the BaseNodeAdapter tick pipeline.
## 8. Data model — `getOutput()`
Port-0 process payload is the `Fluent` envelope (+ optional `GridProfile` for PFR). Port-1 telemetry is the scalar snapshot below.
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.
## 9. Configuration — editor form ↔ config keys
```mermaid
flowchart TB
subgraph editor["Node-RED editor form"]
f1[Reactor type CSTR / PFR]
f2[Volume m3]
f3[Length m + resolution]
f4[Alpha dispersion]
f5[KLa 1/h]
f6[Time step + speed-up]
f7[Initial state 13 species]
end
subgraph config["Domain config slice"]
c1[reactor.reactor_type]
c2[reactor.volume]
c3[reactor.length<br/>reactor.resolution_L]
c4[reactor.alpha]
c5[reactor.kla]
c6[reactor.timeStep<br/>reactor.speedUpFactor]
c7[initialState.* ASM3 keys]
end
f1 --> c1
f2 --> c2
f3 --> c3
f4 --> c4
f5 --> c5
f6 --> c6
f7 --> c7
```
| Form field | Config key | Default | Range | Where used |
|---|---|---|---|---|
| Reactor type | `reactor.reactor_type` | `CSTR` | enum: `CSTR` / `PFR` | engine selection in `_buildEngine` |
| Volume (m³) | `reactor.volume` | `1000` | > 0 | residence time, mass balance |
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.
## 11. Examples
| Tier | File | What it shows | Status |
|---|---|---|---|
| Basic | `examples/basic.flow.json` | CSTR with one inlet, watch `Fluent` effluent | ✅ 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 |
One screenshot per tier where helpful. PNG ≤ 200 KB under `wiki/_partial-screenshots/reactor/`.
## 12. Debug recipes
| 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` |
## 13. When you would NOT use this node
- 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`.
## 14. Known limitations / current issues
| # | 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. | `.claude/refactor/OPEN_QUESTIONS.md` — "mathjs slow load" |
| 2 | `initialState.X_A` default of `200` mg/L is correct; older config snapshots used `0.001` which silently disabled nitrification. Verify on every new deploy. | `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 |
