Appearance
Adding Controllers to a Flowsheet
How to put a control loop on your simulation, configure it, and read what it did
Where controllers live
Open a simulation and go to Stage 3 — Plantwide Tools. The Controllers section is where a flowsheet's control layer is built. Everything the simulation engine can control is offered here: six base PID loops and seven advanced controller types.
| Category | Types |
|---|---|
| Base loops | DO, SRT, RAS, WAS, Flow, pH |
| Advanced controllers | Cascade, Deadband, Switch, Time on/off, Ratio, Continuous P, Feedforward |
The picker is grouped by category and searchable — type "casc" to find the cascade controller.
Adding one
- Add the process units first. A controller has to be bound to a node, so the Add button stays disabled until the flowsheet has at least one unit.
- Pick a type and press Add. The new controller opens with every value the engine has a default for already filled in, bound to the first unit on the flowsheet.
- Fill in the fields marked as needed. A parameter with no engine default is left blank on purpose — a setpoint of 0 is a setpoint, and the editor will not pretend you asked for one. A badge on the card counts how many fields still need attention.
The fields
Every field, unit and range you see comes from the simulation engine itself, so the editor cannot offer a setting the engine ignores or hide one it needs.
| Field kind | What you get |
|---|---|
| A quantity | A number box with its unit in the label, e.g. Minimum on time (d). Out-of-range values are flagged with the reason. |
| A node | A searchable picker over the units on your flowsheet. |
| A variable | A searchable picker over the measurements the engine publishes (DO, MLSS, TSS, flow, HRT, SRT, pH, level, temperature…) or, for the commanded variable, over what the engine can drive (airflow, wasFlow, rasRatio, pumpFlow, chemicalDose…). You can type a name that is not listed — a controller may read a value another controller wrote. |
| A choice | Direct/reverse action, auto/manual/tracking mode. |
| A switch | Bumpless transfer, trim enabled, repeat cycle. |
| Phases | The time on/off controller's cycle: add, remove and edit named phases with a duration in days and an output. |
Clearing a number box removes the value rather than setting it to zero, and the engine's own default applies again.
Controllers with more than one loop
A cascade has a Master loop and a Slave loop; a feedforward has a Lead-lag compensator and an optional Feedback PID; a ratio controller has a PID trim. These appear as separate labelled blocks so it is always clear which gain belongs to which loop.
For a cascade, the master's output becomes the slave's setpoint, so:
- Point the master at the slow, important measurement (dissolved oxygen).
- Point the slave at the fast one it commands (airflow).
- The Target node and Manipulated variable on the slave block are what actually moves.
Ranges
Some fields carry a range — a derivative filter must be between 0 and 1, a dwell time cannot be negative. These are guidance at the point of entry, not a lock: they exist because the quantity's meaning fixes them. Most fields (gains, setpoints, output limits) have no range, because a value that looks unusual is not necessarily wrong.
Running and reading the result
Run the simulation, then open the Controllers tab in the bottom panel. The tab is addressable: appending ?tab=controllers to the editor's URL opens straight to it, which is a convenient way to send someone to the loop you want them to look at.
What you see depends on where the run happened:
| Run | What the tab shows |
|---|---|
| Server run | A trajectory per controller — measurement against setpoint, and the manipulated variable it commanded — with a saturation badge. |
| Local run | One sample per controller: where each loop settled at the operating point, plus a note that trajectories come from a server run. The local engine evaluates the control layer once; it does not integrate a curve. |
| No controllers | A note that the run had no control layer. |
The controller cards in the Tools panel also show the last sample inline: measurement, error and commanded output for a base loop; output and the type's own diagnostics for an advanced one. A SAT badge means the output hit its limit — the loop is asking for more than it is allowed to give, which usually means the output limits or the equipment sizing need a look, not the tuning.
If only the base loops are offered
A warning appears reading "Only the base PID loops are available — the controller catalogue could not be loaded". The advanced types are described by the server, so the editor cannot offer them while it cannot reach it. The six base loops keep working. Check that you are signed in and that the API is reachable, then reload.
Something a controller commands has no effect
A commanded variable only changes the run if a model reads it. Aeration (airflow/kLa), flow, volume and temperature are read live; a command written to a parameter no model consumes is recorded faithfully and changes nothing downstream. If a loop looks like it is working but the plant does not respond, check that the manipulated variable is one the target unit's model actually uses.
Related
- Controllers overview — what each controller type does and when to use it
- Cascade Controller, Deadband, Switch, Time on/off, Ratio, Continuous P, Feedforward
- DO Control, SRT Control, RAS/WAS Control
- Dynamic Simulation — where control loops matter most