Rules
    • 06 Jul 2023
    • 12 Minutes to read
    • Dark
      Light

    Rules

    • Dark
      Light

    Article summary

    Data


    Description

    Name in Datafile

    Controller Label

    Label of RULES unit (required when in Control module)

    Label1

    n/a

    Number of defined rules

    nrules

    Sample time

    Polling time of RULES unit (same units as defined by tm, below)

    tsampl

    Units of time

    Optional keyword or value for units of time in the following data set. Can be any numerical multiplier or one of the following: seconds (the default), minutes, hours, days, weeks, fortnight, lunar (month - i.e. 28 days), month (of 30 days), quarter, year or decade

    tm

    Data Extending Method

    Policy for extending data if the run finishes after the end of the data. Options are:

    • REPEAT - if the data are to be repeated from the beginning
    • EXTEND - if the data are to be fixed at the last given values
    • NOEXTEND - for no extension

    If NOEXTEND is used (or the field is left blank) then the program will stop with an error message if there are insufficient data for the length of the run

    repeat

    Rule Name

    Rule keyword identifier: first rule should be RULE1, second rule RULE2 etc

    rulkey

    Rule Text Components

    Valid logical conditional statement

    condst

     

    Valid arithmetic setting statement of form (...) = (...)

    setst

    n/a

    Number of time/rules switch data sets

    ndat

    Time

    Model time

    time

    Operating Rules

    Current operating rule keywords of form rulkey1,rulkey2,... where each rulkey is a valid rule keyword identifier as defined above, separated by commas

    rules

    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:

    Operator

    Code

    Precedence

    No. of Operands

    Type of Operand

    Return type

    Example Usage

    Multiplication

    *

    3

    2

    Real

    Real

    6*3.2

    Division

    /

    3

    2

    Real

    Real

    FLOW(l1)/2

    Addition

    +

    4

    2

    Real

    Real

    5.0+HEAD(l1)

    Subtraction

    -

    4

    2

    Real

    Real

    5.4-1

    Logical `and'

    .AND.

    7

    1

    Logical

    Logical

    (...).AND.(...)

    Logical `or'

    .OR.

    8

    2

    Logical

    Logical

    (...).OR.(...)

    Logical `not'

    .NOT.

    6

    2

    Logical

    Logical

    .NOT.(3.GT.2)

    Equal to

    .EQ.

    5

    2

    Real

    Logical

    (...).EQ.(...)

    Not Equal to

    .NE.

    5

    2

    Real

    Logical

    (...).NE.(...)

    Less Than or Equal To

    .LE.

    5

    2

    Real

    Logical

    (...).LT.(...)

    Greater Than or Equal To

    .GE.

    5

    2

    Real

    Logical

    (...).GT.(...)

    Less Than

    .LT.

    5

    2

    Real

    Logical

    (...).LE.(...)

    Greater Than

    .GT.

    5

    2

    Real

    Logical

    (...).GE.(...)

    Flow

    FLOW(.)

    2

    1

    Node Label

    Real

    FLOW(l1)

    Head

    HEAD(.) or LEVEL(.)

    2

    1

    Node Label

    Real

    HEAD(l2)

    Pump Operating Mode

    UMODE(.) or PUMP(.)

    2

    1

    see Note 1

    Real

    PUMP(l1)

    Gate Opening

    USTATE(.) or OPENING(.)

    2

    1

    see Note 2

    Real

    OPENING(l1)

    Rating Curve

    RATING(.,.)

    2

    2

    see Note 3

    Real

    RATING(l1,l2)

    Parentheses

    ( ... )

    -

    -

    -

    -

     -

    Previous Flow

    OLDF(.)

    1

    2

    see Note 4

    Real

    OLDF(l1,100)

    Previous Head

    OLDH(.)

    1

    2

    see Note 4

    Real

    OLDH(l1,100)

    Previous Unit Mode

    OLDM(.)

    1

    2

    see Note 4

    Real

    OLDM(l1,100)

    Previous Unit State

    OLDS(.)

    1

    2

    see Notes 4 and 5

    Real

    OLDS(n1,100)

    Mathematical functions (see note 6)

    Absolute value, |x|

    MABS(.)

    2

    1

    Real

    Real

    MABS(FLOW(A1))

    Square root

    SQRT(.)

    2

    1

    Real

    Real

    SQRT(FLOW(A1))

    Exponential (ex)

    EXP(.)

    2

    1

    Real

    Real

    EXP(FLOW(A1))

    Natural logarithm (ln, loge)

    LOGE(.)

    2

    1

    Real

    Real

    LOGE(FLOW(A1))

    Base 10 logarithm (log10)

    LOG10(.)

    2

    1

    Real

    Real

    LOG10(FLOW(A1))

    Sine

    SIN(.)

    2

    1

    Real (rads)

    Real

    SIN(USTATE(A1))

    Cosine

    COS(.)

    2

    1

    Real (rads)

    Real

    COS(USTATE(A1))

    Tangent

    TAN(.)

    2

    1

    Real (rads)

    Real

    TAN(USTATE(A1))

    Inverse sine

    ARCSN(.)

    2

    1

    Real

    Real (rads, range [-½p, ½p])

    ARCSN(USTATE(A1)/5.0)

    Inverse cosine

    ARCCS(.)

    2

    1

    Real

    Real (rads, range [0,p])

    ARCCS(USTATE(A1)/5.0)

    Inverse tangent

    ARCTN(.)

    2

    1

    Real

    Real (rads, range [-½p, ½p])

    ARCTN(USTATE(A1)/5.0)

    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, tm, 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.


    Was this article helpful?

    Changing your password will log you out immediately. Use the new password to log back in.
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.