EVOLV/wiki/Glossary.md

Glossary

Reflects code as of 9ab9f6b · regenerated 2026-05-11

Terms and abbreviations used across the EVOLV codebase, wikis, and dashboards.

S88 (ISA-88 batch control)

flowchart TB
    enterprise["Enterprise"]:::neutral
    site["Site"]:::neutral
    area["Area"]:::area
    pc["Process Cell"]:::pc
    unit["Unit"]:::unit
    em["Equipment Module"]:::equip
    cm["Control Module"]:::ctrl

    enterprise --> site --> area --> pc --> unit --> em --> cm

    classDef neutral fill:#dddddd
    classDef area fill:#0f52a5,color:#fff
    classDef pc fill:#0c99d9,color:#fff
    classDef unit fill:#50a8d9,color:#000
    classDef equip fill:#86bbdd,color:#000
    classDef ctrl fill:#a9daee,color:#000

Term	Meaning in EVOLV
Area	Plant section. Reserved, no node implements it yet.
Process Cell (PC)	Self-contained sub-process. pumpingStation is the only PC-level node.
Unit (UN)	One major piece of equipment or a coordinator over equipment. MGC, VGC, reactor, settler, monster.
Equipment Module (EM)	A single piece of equipment. rotatingMachine, valve, diffuser.
Control Module (CM)	Single sensor / actuator. measurement.
softwareType	The node's S88 type — used by ChildRouter to match child.register calls.

EVOLV runtime concepts

Term	Meaning
BaseDomain	Base class for every specificClass. Owns measurements, router, emitter, logger.
BaseNodeAdapter	Base class for every nodeClass. Bridges Node-RED ↔ specificClass via commandRegistry.
specificClass	Pure-JS domain logic. No RED.* imports. Unit-testable in isolation.
nodeClass	Node-RED adapter — owns input routing, tick loop, port wiring, status badge.
ChildRouter	Declarative matcher for child.register events. router.onRegister(swType, handler).
commandRegistry	Inbound-msg dispatcher. Topic → handler descriptor map; resolves aliases and coerces units.
UnitPolicy	Per-node declaration of canonical (internal) and output units.
MeasurementContainer	Chainable measurement store. Keys: <type>.<variant>.<position>.<childId>.
statusBadge	Composes node.status({fill,shape,text}) from a HealthStatus.
HealthStatus	{level: 0..3, flags, message, source} — standardised health summary.
LatestWinsGate	Mutex with supersede semantics — superseded calls resolve with {superseded: true}.
outputUtils	Single point for Port-0 delta compression + Port-1 line-protocol formatting.
tick	The 1 Hz update loop. Domain runs tick() for time-based concerns (integrators, FSM timers).
getOutput()	Domain method returning the current snapshot — fed to outputUtils for diff/format.
getFlattenedOutput()	Returns measurements with dot-flattened keys (4-segment: type.variant.position.childId).

Topic prefixes

(See Topic-Conventions for the full table.)

Prefix	Direction	Idempotent?
set.	inbound	yes
cmd.	inbound	no — has side-effects
data.	bidirectional	n/a
evt.	outbound	n/a
child.	inbound (parent receives)	yes — id-keyed

Wastewater treatment terms

Term	Meaning
WWTP	Wastewater Treatment Plant.
Influent / Effluent	Inlet / outlet stream of a process unit.
Activated Sludge	Biological process where bacteria consume organic matter under aeration. Modelled by ASM (ASM1, ASM3, …).
MLSS	Mixed Liquor Suspended Solids — biomass concentration in the reactor.
RAS	Return Activated Sludge — settled sludge pumped back from settler to reactor.
WAS	Waste Activated Sludge — excess sludge removed from the system.
TSS	Total Suspended Solids.
COD / BOD	Chemical / Biological Oxygen Demand — organic load metrics.
NH₄ / NO₃	Ammonium / Nitrate — N species, key for nitrification/denitrification.
DO	Dissolved Oxygen, mg/L. Setpoint typically ~2 mg/L in aerated zones.
K_La	Volumetric mass-transfer coefficient (oxygen transfer rate / driving force).
OTR	Oxygen Transfer Rate — diffuser's output to the reactor.
HRT / SRT	Hydraulic / Sludge Retention Time.
F/M ratio	Food-to-microorganism ratio.
Composite sample	A sample built up over time, often proportional to flow — what monster simulates.

Pump / hydraulics terms

Term	Meaning
BEP	Best Efficiency Point — operating point where the pump consumes the least energy per unit flow.
NPSH	Net Positive Suction Head — pressure margin to avoid cavitation.
Affinity laws	Q ∝ N, H ∝ N², P ∝ N³ — how flow/head/power scale with pump speed.
Characteristic curve	Q ↔ H (or Q ↔ P, Q ↔ η) graph supplied by the pump manufacturer.
NCog	Normalised cost-of-going metric used by MGC for switching stability.
Wet-well basin	The buffer volume on a lift station — what pumpingStation models.
Setpoint	The commanded value (e.g., flow setpoint = 12 m³/h).
Demand	The integrated requirement (e.g., the parent's "need this much flow now").

Control / signal-processing terms

Term	Meaning
PID	Proportional-Integral-Derivative controller.
Anti-windup	Prevents integral term from growing unboundedly when actuator saturates.
Hysteresis	Switching threshold with a deadband (e.g., start at 80%, stop at 30%).
Schmitt trigger	Hysteresis-based binary switch (used for stopLevel in pumpingStation).
Smoothing	Filtering noise (moving average, exponential, Savitzky-Golay).
Outlier detection	Identifying readings that fall outside expected variance.
FSM	Finite State Machine — discrete states + transitions.

Project terms

Term	Meaning
Tier 1–4	Refactor phases (see Home project status).
Wave A / B / C	Sub-batches of submodule pointer bumps during the refactor.
OPEN_QUESTIONS.md	Live decisions log at .claude/refactor/OPEN_QUESTIONS.md.
CONTRACTS.md	API shapes at .claude/refactor/CONTRACTS.md.
MODULE_SPLIT.md	Per-node concern layout at .claude/refactor/MODULE_SPLIT.md.
WIKI_TEMPLATE.md	14-section per-node wiki template at .claude/refactor/WIKI_TEMPLATE.md.
AUTOGEN block	Sections of a wiki regenerated by npm run wiki:all — do not hand-edit between markers.

Related pages

• Home
• Architecture
• Topic-Conventions
• Topology-Patterns