Control Rules Format (SWMM)
Control rules can be used to control ancillary regulatory structures, such as pumps and weirs in a SWMM network, and are specified in the Control Rules Editor.
Examples of control rules displayed in the editor are shown below.
Each control rule may consists of one or more of the following:
- a keyword (RULE, IF, AND, OR, THEN, ELSE, PRIORITY)
- an identifier (used with RULE keyword only). No spaces should be included in the identifier.
- a condition clause (used with the IF, THEN, ELSE, AND, OR keywords). See the Condition Clauses section for further information.
- an action clause (used with IF, THEN, ELSE, AND, OR keywords). See the Action Clauses section for further information.
- a priority value (PRIORITY keyword only). See the Priority section for further information.
Each control rule consists of a series of statements, where each line starts with a keyword, and takes the form:
RULE ruleID
IF condition_1
AND condition_2
OR condition_3
AND condition_4
etc.
THEN action_1
AND action_2
etc.
ELSE action_3
AND action_4
etc.
PRIORITY value
where ruleID is the name or identifier for the rule, condition_n is a condition clause, action_n is an action clause, and value is a priority value.
The following 'rules' apply when adding or editing a control rule:
- The first line of each statement must start with the RULE keyword.
- Only the RULE, IF and THEN portions of a rule are required; the ELSE and PRIORITY portions are optional.
- Blank lines between clauses are allowed, and any text to the right of a semicolon is considered a comment.
- When mixing AND and OR clauses, the OR operator has higher precedence than AND, i.e.
IF A or B and C is equivalent to
IF (A or B) and C.
If the interpretation was meant to be
IF A or (B and C),
then this can be expressed using the following two rules:
IF A THEN ...
IF B and C THEN ...
Priority
The PRIORITY keyword, and the value assigned to it, are used to determine which rule applies when two or more rules require that conflicting actions be performed on a link. A conflicting rule with a higher priority value has precedence over one with a lower value (for example, PRIORITY 4 outranks PRIORITY 2). A rule without a priority value always has a lower priority than one with a value. For two rules with the same priority value, the rule that appears first is given the higher priority.
Condition clauses
Condition clauses are used with the IF, THEN, ELSE, AND, OR keywords.
Each condition clause of a control rule has the following format:
object id attribute relation value object id attribute relation object id attribute
where:
object is the type of object (see the following table)
id is the name or identifier assigned to the object
attribute is the attribute of the object (see the following table)
relation is a relational operator (=, <>, <, <=, >, >=)
value is an attribute value (see the following table)
The objects and attributes that can be included in a condition clause, and the type of attribute value required, are listed in the following table:
|
Object type |
Attribute |
Type of value |
|---|---|---|
| Node |
DEPTH |
Numeral |
|
HEAD |
||
|
VOLUME |
||
| INFLOW | ||
| Link | FLOW | Numerical |
| DEPTH | Numerical | |
| TIMEOPEN | Decimal hours or hr:min | |
| TIMECLOSED | Decimal hours or hr:min | |
| Conduit | STATUS | OPEN or CLOSED |
| TIMEOPEN | Decimal hours or hr:min | |
| TIMECLOSED | Decimal hours or hr:min | |
| Pump | STATUS | ON or OFF |
| SETTING | Pump curve multiplier | |
| FLOW | Numerical | |
| TIMEOPEN | Decimal hours or hr:min | |
| TIMECLOSED | Decimal hours or hr:min | |
| Orifice | SETTING | Fraction open |
| TIMEOPEN | Decimal hours or hr:min | |
| TIMECLOSED | Decimal hours or hr:min | |
| Weir | SETTING | Fraction open |
| TIMEOPEN | Decimal hours or hr:min | |
| TIMECLOSED | Decimal hours or hr:min | |
| Outlet | SETTING | Fraction open |
| TIMEOPEN | Decimal hours or hr:min | |
| TIMECLOSED | Decimal hours or hr:min | |
| Simulation | TIME | Elapsed time in decimal hours or hr:min |
| DATE | Month/Day/Year | |
| MONTH | Numerical month of year (January = 1) | |
| DAY | Numerical day of the week (Sunday = 1) | |
| CLOCKTIME | Time of day in hr:min:sec |
TIMEOPEN is the duration a link object has been in an OPEN or ON state or has had its SETTING be greater than zero; TIMECLOSED is the duration it has remained in a CLOSED or OFF state or has had its SETTING be zero.
Action clauses
An action clause is used with the IF, THEN, ELSE, AND, OR keywords in a control rule, and can have one of the following formats:
PUMP id STATUS = ON/OFF (only applicable to pumps)
PUMP/ORIFICE/WEIR/OUTLET id SETTING = value (applicable to any ancillary object)
where the meaning of SETTING depends on the object being controlled:
- for pumps it is a multiplier applied to the flow computed from the pump curve
- for orifices it is the fractional amount that the orifice is fully open
- for weirs it is the fractional amount of the original freeboard that exists (i.e., weir control is accomplished by moving the crest height up or down)
- for outlets it is a multiplier applied to the flow computed from the outlet's rating curve
Modulated controls
Modulated controls are control rules that provide for a continuous degree of control applied to a pump or flow regulator as determined by the value of some controller variable, such as water depth at a node, or by time. The functional relationship between the control setting and the controller variable can be specified by using a Control Curve or a time series in an event or TVD connector.
In the example, a modified form of the action clause is used to specify the name of the control curve, the regulator reference for the applicable times series event profile, and the name of the PID parameter set that defines the degree of control. The PID parameter set contains three values; a proportional gain coefficient, an integral time (in minutes), and a derivative time (in minutes).
By convention the controller variable used in a control curve or PID controller will always be the object and attribute named in the last condition clause of the rule. For example, in rule MC1, Curve C25 would define how the fractional setting at Weir 025 varied with the water depth at Node 002. In rule MC3, the PID controller adjusts the opening of Orifice 014 to maintain a flow of 1.6 in Link 033.
PID controllers
A PID (Proportional, Integral and Derivative) controller is a generic closed-loop control scheme that tries to maintain a desired setpoint on some process variable by computing and applying a corrective action that adjusts the process accordingly. A PID controller, for example, could be used to adjust the opening on a gated orifice to maintain a target flow rate in a specific conduit or to adjust a variable speed pump to maintain a desired depth in a storage unit.
A PID controller has the form:
|
|
where: m(t) is the controller output Kp is the proportional coefficient (gain) e(t) is the error (difference between setpoint and observed variable value) T iis integral time T d is derivative time t is time |
The performance of a PID controller is determined by the values assigned to the coefficients Kp, Ti, and Td.
The controller output m(t) has the same meaning as a link setting used in a rule's action clause while dt is the current flow routing time step in minutes. Because link settings are relative values (with respect to either a pump's standard operating curve or to the full opening height of an orifice or weir) the error e(t) used by the controller is also a relative value. It is defined as the difference between the control variable setpoint x* and its value at time t, x(t), normalised to the setpoint value: e(t) = (x* - x(t)) / x*.
For direct action control, where an increase in the link setting causes an increase in the controlled variable, the sign of Kp must be positive. For reverse action control, where the controlled variable decreases as the link setting increases, the sign of Kp must be negative. It is therefore import to recognise whether the control is direct or reverse action and ensure that the correct sign on is used for Kp. For example, adjusting an orifice opening to maintain a desired downstream flow is direct action, so Kp must be positive. Adjusting it to maintain an upstream water level is reverse action, so Kp must be negative. Controlling a pump to maintain a fixed wet well water level would be reverse action (negative Kp) while using it to maintain a fixed downstream flow is direct action (positive Kp).
