Rules

Data

Theory and Guidance

The RULES unit represents a generalised logical controller, where output variables are set according to user-defined logical rules.

The unit allows the user to set a control signal directly according to rules defined within the datafile entry. The rules can include conditions that depend on arithmetic or logical conditions and/or the status of certain hydraulic variables within the hydraulic network.

The RULES unit can be used within an Flood Modeller hydraulic datafile as a set of logical rules for a vertical or radial sluice (SLUICE VERTICAL and SLUICE RADIAL), a gated weir unit (GATED WEIR), a pump (OCPUMP) or an ABSTRACTION unit in `logical' operation mode.

The data for the RULES unit are usually contained in the main Flood Modeller data file immediately after the hydraulic unit it is controlling; this unit should be in `logical' mode. However, if the Flood Modeller Control module has been purchased, then the RULES data block can be located in the control datafile (*.ctl).

Typical uses of this unit in the control module include the following: controlling the gate opening of a sluice according to conditions within the remainder of the network; turning a pump on or off according to levels and flows at local or remote nodes; and directly setting the abstraction of an ABSTRACTION unit depending on hydraulic conditions of remote nodes

The datafile entry for this unit should include some logical rules with associated identifying keywords. These rules should be of the form:

IF ( ... ) - (Conditional statement)

THEN ( ... ) = ( ... ) - (Setting statement)

ALSO ( ... ) = ( ... ) - (Optional additional setting statement, repeatable up to 9 times)

END

where the dots indicate valid logical/arithmetical constructions that can be recognised by the RULES unit.

The conditional statement should be a valid logical expression that can be evaluated by the unit as true or false for each control time step. If a currently operational rule is evaluated as true, the unit's output value will then be set to the value of the expression in the second set of parentheses: this should therefore be an arithmetic expression.

If multiple setting statements are used, these cannot apply to the same variable; a pump cannot be on and also off, for instance. Note that for operation of gates, this means MOVE and POSITION cannot be used in the same rule, e.g. the combination

THEN MOVE = 1

ALSO POSITION = 0

is not allowed.

Following 1 or more of the IF rules, an ELSE condition can be optionally provided to cover all other eventualities. An ELSE rule must be located as the final rule in the list.

ELSE ( ... ) = ( ... ) - (Setting statement)

END

When this unit is used within an Flood Modeller hydraulic datafile in association with a sluice or gated weir, the setting statement must be of the form:

THEN MOVE = (...) or

THEN POSITION = (...)

In the former case the instruction is interpreted by the sluice/gated weir as an instruction to move by the amount (in metres) specified on the right-hand side of the equality. The latter instruction gives the target position of the sluice/gated weir directly. In both case the specified move is accomplished by the hydraulic unit as quickly as it is able, depending on the restrictions of the maximum movement rate and opening/setting specified in the hydraulic unit's datafile entry.

Target gate positions can either be given directly, or be any valid logical or arithmetical expression, as defined below.

When used to control an open channel pump unit (`OCPUMP') in Flood Modeller, the setting instruction should be of the form:

THEN PUMP = ON or

THEN PUMP = OFF or

THEN PUMP = STOPPED

These are all instructions to the OCPUMP unit to change (or remain in the current) operating mode; these instructions are acted on immediately.

When used to control an ABSTRACTION unit the setting instruction should be of the form:

THEN ABS = (...)

This allows the user to directly set the flow at the ABSTRACTION unit. Abstractions can be positive or negative numbers (or valid combinations of recognised functions that return a number); the flow direction will be determined by the Flood Modeller sign convention for flows.

Rules are evaluated and instructions updated every polling time interval, `tsampl'.

It should be noted that when used with a hydraulic unit, all rules should be mutually exclusive. A runtime error will be generated if anytime during the run more than one logically valid rule is in operation.

Both conditional statements and setting statements can be split over up to 30 lines, without specific continuation indicators. Each line, however must be 600 characters long, at most. Up to 60 different rules are allowed for each hydraulic unit.

The data entry for this unit also includes time switch data where the user can stipulate which operating rules are currently active by specifying the appropriate rule keyword(s) for particular model times; when this model time is reached, the unit will switch to the associated operating rule(s).

When used as a standalone control unit, if more than one operating rule is evaluated as valid for a particular model time, the unit will set its output equal to the minimum of all the `right-hand side' values of currently valid rules.

Node labels referred to within individual rules should not be able to be interpreted as numerical values by a FORTRAN read statement as well. This will cause the RULES unit to misinterpret the operational instructions, and will cause erroneous results. Thus node labels such as `0.2', `103', `11E4' and `D4' should be avoided if these will form part of a rule statement.

Valid logical or arithmetic expressions are composed of FORTRAN-type operators with the appropriate syntax, number of operands, etc. Recognised operators, with their associated operator precedence, number of operands and example usage, are shown in the following table:

Mathematical functions (see note 6)

In the table above the dots refer to valid operands or expressions.

Notes

1. The UMODE (or PUMP) operation provides the numerical code of the current operating mode of a pump when its argument is the upstream node label (i.e. label 1) of that pump unit.
2. The USTATE (or OPENING) operation provides the gate opening (in metres) when its argument is the upstream node label (i.e. label 1) for a sluice unit.
3. The `RATING' operation takes two node labels as its arguments; each of these node labels must have a RATING CURVE unit associated with them in the hydraulic datafile. The unit will use the rating curve and the current flow form the first node label to obtain the corresponding head value. This head value is then used to find the corresponding flow at the second node label via its rating curve; it is this flow that is the return value of the operation.
4. The first operand for the OLDF, OLDH, OLDM, and OLDS functions should be a valid node label. The second operand should be the number of seconds back from the current model time at which the RULES unit extracts the hydraulic data required.
5. The unit state variable is used to store sluice gate openings and pump speeds.
6. Regarding the mathematical library
   1. To avoid possible conflicts in old models with node labels named similarly to the above functions, this feature is only available if the "Logical rules math library" option is selected on the Miscellany tab of the run forms menu (Mathrules=1 in the ief file). This option is selected by default.
   2. Functions such as MABS, LOGE, ARCSN, etc. are named differently from the more conventional (e.g. ABS, LOG/LN, ARCSIN/ASIN) to prevent a conflict with other functions when parsing the rules string.

Operations in parentheses are always evaluated first in an expression, and within a set of parentheses the lowest precedence operation will be evaluated first. If two or more operations have the same precedence the `left-most' operation is evaluated first. (These rules follow normal FORTRAN-type precedence requirements.)

General

If at any stage during a run the conditions in the network are such that there is no restriction on the RULES unit output, the output is set to a nominal value of -9999.99, for a standalone RULES control unit. For a RULES data block within a hydraulic datafile, the last valid output value is maintained.

Datafile Format

Line 1 - Keyword `RULES' [comment]

Line 1a - Label1, Label2 (Line1a is only entered if the RULES are in a Flood Modeller Control file - .ctl)

Line 2 - nrules, tsampl, t_m, repeat

Line 3 - rulkey

Line 4 - condst

Line 5 - keyword `THEN', setst

Line 7 - keyword `END'

(These last 4 lines are repeated nrules times. Both condst and setst can be split between up to 5 lines if long logical/arithmetic statements are required)

Line n - Keywords 'TIME RULE DATA SET'

Line n+1 - ndat

Line n+1 to n+1+ndat - time , rules

Examples

Example 1: Upstream level control for a Sluice unit

RULES
4                   HOURS     5
RULE1
IF(LEVEL(A2).GT.12.2.AND.LEVEL(A2).LE.13.0)
THEN MOVE=0.1
END
RULE2
IF(LEVEL(A2).LE.12.2.AND.LEVEL(A2).GE.12.0)
THEN MOVE=0.0
END
RULE3
IF(LEVEL(A2).LT.12.0)
THEN MOVE=-0.1
END
RULE4
IF(LEVEL(A2).GT.13.0)
THEN POSITION=1.0
END
TIME RULE DATA SET
5
0.0       RULE1,RULE2,RULE3
1.5       RULE1,RULE2,RULE3
4.0       ALL
30.0      ALL
60.0      ALL

These rules will have the overall effect of attempting to maintain the level at the upstream node of a sluice (A2 in the example) between 12.0 and 12.2 m AD. If the level goes above this band the sluice gate will be opened by 0.1m (thus letting more water pass through), whilst the level falling below this band causes the sluice to close by 0.1m (and retain more water). A level within this band means that the sluice will remain in it's current position (the MOVE=0.0 command).

The last rule represents an `emergency' option, where the sluice gate will be moved to the fixed position of 1.0m opening (which might be the fully open position) when the water level upstream is higher than 13.0m AD.

Some experimentation with the band widths and movement amounts defined by the rules (and with the movement rate of the sluice gate) is usually necessary to optimise the performance of the sluice gate, and ensure that control is effected sufficiently rapidly, whilst avoiding unnecessary oscillations of the gate.

It should always be born in mind in these type of control situations that there is in general a trade-off between speed of control and stability, and it may be quite difficult to achieve both at the same time. For example, speed of control will be increased by increasing the movement rate of the gate and/or increasing the MOVE amounts in the rules. However these changes will also tend to make the gate control more unstable, and force it into oscillatory behaviour.

It should also be noted that a control set-up that works adequately for one model scenario - say, a 1:20 year flood event - may prove inadequate when used in another model run - one that simulates a more severe flood, for example, such as a 1:100 year event.

Example 2: Abstraction restrictions

RULES
lrule1    abstr1
3
RULE1
IF(FLOW(S2).GE.80)
THEN ABS=FLOW(S2)-80
END
RULE2
IF (FLOW(S2).LT.80)
THEN ABS=0
END
RULE3
IF(SUM(FLOW(ABS1),DAY).GT.8e5)
THEN ABS=0
END
TIME RULE DATA SET
2
0.0       ALL
1e20      ALL

These rules represent restrictions on the amount that can be abstracted from a channel, depending on flow conditions. The rules allow no ABSTRACTION (ABS=0) when flow at node S2 is less than 80 m3/s. However if the flow at S2 is greater than or equal to 80 m3/s, the ABSTRACTION unit extracts the excess over this amount. This will have the effect of retaining a residual flow equal to 80 m3/s in the channel connected to S2, when sufficient water is available.

The last rule allows no abstraction to take place if at any time the total amount of water that has passed through node ABS1 in one day is greater than 800000 cubic metres. This might be useful to restrict the total amount of water extracted by the ABSTRACTION unit itself, for example, when ABS1 would be the ABSTRACTION unit's node. In this example the SUM function's counter will be reset every day of model time during the run.

This set of rules demonstrates how Value Statements can be a function of hydraulic variables within the model.

Example 3: Land drainage using an Open Channel Pump unit

RULES
lrule1    qpump1
4
RULE 1
IF(LEVEL(bpump1).GT.1.5)
THEN PUMP=ON
END
RULE2
IF(LEVEL(bpump1).LT.1.2)
THEN PUMP=STOPPED
END
RULE3
IF(LEVEL(bpump1).LE.1.5.AND.
LEVEL(bpump1).GE.1.2.
AND.PUMP(bpump1).EQ.STOPPED)
THEN PUMP=STOPPED
END
RULE4
IF(LEVEL(bpump1).LE.1.5.
AND.LEVEL(bpump1).GE.1.2.
AND.PUMP(bpump1).EQ.ON)
THEN PUMP=ON
END

The main purpose of these rules is to ensure that the level at node bpump1 does not rise above 1.5m AD; when this happens the pump at bpump1 will be turned on. (It is assumed that the OCPUMP unit at bpump1 is set up such that bpump1 is the node at the suction side of the pump.)

Usually in these situations there will be a minimum safe head that the pump unit can operate at; this is assumed to be 1.2m AD in the above set up. Thus, when the suction head at the pump falls below this value, the pump is turned off by putting it into STOPPED mode.

The situation for intermediate level values is somewhat more complicated. Basically the pump will remain in it's current operating mode (i.e. STOPPED or ON) when the suction head is between 1.2m and 1.5m AD. This ensures that small oscillations in the suction head brought about by the pump turning off or on does not itself trigger another change in mode . For example, it is likely that when the pump turns on from STOPPED mode, the suction head will fall slightly. It is important that the rules are set up so that this fall does not cause the pump to subsequently switch back to STOPPED mode, otherwise it is likely that the pump will be switching rapidly between ON and STOPPED modes in this situation.