Global variables
    • 02 Aug 2023
    • 3 Minutes to read

    Global variables


    Article summary

    Global variables can be defined to be controlled by, and referenced in, logical rules.

    This enables a user to, for instance, create a timer to start when a certain condition is met, and for multiple gates, pumps, and/or abstraction units to then be controlled by this global timer.

    Theory and Guidance

    General

    Five types of global variable are available: TIMER, INTEGER, FLOAT, BOOLEAN (synonym BINARY) or TERNARY. Each defined variable must be given a unique name, the use of which may appear within an existing RULES block.

    • A BOOLEAN variable can have the value 1 (synonym: TRUE) or 0 (synonym: FALSE)
    • A TERNARY variable can have the value RISING (synonyms: 1, UP), NEUTRAL (synonyms: NORMAL, 0) or FALLING (synonyms: -1, DOWN)
    • A TIMER variable has two properties to access – value (type=float, denoting the time (s)) and status (type=semi-Boolean, i.e., can take value 0 or 2), e.g., MyTimer.status and MyTimer.value. Further details on using timer variables are provided at the end of this section.

    Important:

    The name of your global variable (max width 20 characters) must satisfy the following:

    1. Consists of alphanumeric and underscore (“_”) characters only, and does not begin with a number
    2. Is unique (please note the name is case insensitive), and does not conflict with existing node name or other rules keyword

    The use of variable names may appear within an existing RULES block (i.e. associated with a moveable structure – Sluice or Gated Weir) on either:

    1. A condition statement (e.g. “IF variable.GE.10”)
    2. An instruction statement [LHS] (e.g. “THEN variable=1”)
    3. An instruction statement [RHS] (e.g. “THEN MOVE=variable/2”)

    Example usage:

    IF (PenstockWaitTime.GE.5400.and.LEVEL(MyNode).GE.6.7)
    THEN…
    
    IF (MyIntegerVariable.EQ.30)
    THEN…
    
    IF (LEVEL(MyNode).GT.2*MyIntegerVariable)
    THEN…
    
    IF (…)
    THEN MOVE=MyIntegerVariable/2
    
    IF (…)
    THEN MyIntegerVariable=10
    
    IF (…)
    THEN PenstockWaitTime=ON
    
    IF (…)
    THEN PenstockWaitTime.RESTART
    
    IF (…)
    THEN MyTernaryVariable=FALLING
    

    The following keywords may be used to substitute for numeric values.

    KeywordValueIntent (not enforced)
    ON2Timer
    OFF0Timer
    TRUE1Boolean
    FALSE0Boolean
    RISING1Ternary
    FALLING-1Ternary
    NEUTRAL0Ternary
    UP1Ternary
    DOWN-1Ternary
    NORMAL0Ternary

    Timer Variables

    A timer variable, tVariable, is allowed the following operations. In such cases, no “=” sign is permitted, nor may anything else appear in that instruction.

    • tVariable.RESET
    • tVariable.RESTART
    • tVariable.TOGGLE

    tVariable.RESET will reset a timer’s value (time) to zero but not change its status.

    tVariable.RESTART will reset a timer’s value (time) to zero and ensure its status is ON.

    tbVariable.TOGGLE will reverse a timer’s status.

    The following should also be noted regarding timer variables:

    • When setting a timer variable via the “=” sign, this applies to its status, and therefore may only take the values ON or OFF.
    • One cannot explicitly set a timer’s time (value), only its status [ON or OFF]. A timer’s value is only changed (by the simulation time increment) when its status is ON.
    • One cannot refer to a timer’s status in the condition or the RHS of an instruction; any reference to a timer will use its value (time). 

    Data

    Field in data entry formDescriptionName in datafile
    Comment_1 (above table)Optional comment for the set of global variables
    NameName of the variable, up to 20 characters. Mandatory.name
    Variable type
    Type of variable; TIMER, INTEGER, FLOAT, BOOLEAN (synonym BINARY) or TERNARY only. Mandatory. 
    type
    Initial value
    Initial value of variable; can be any value allowed by the relevant data type (for TIMER, this is TIMER.value – a floating point number), default=0; absent is interpreted as 0. Optional.
    initial value
    Initial status
    For TIMER type only (else blank/ignored) – initial status of TIMER: OFF (synonym 0) or ON (synonym 2). Optional.
    initial status
    Comment_n+1 (within table)
    Optional comment for the n individual global variable(s)

    Datafile format

    General

    Line 1 : keyword ‘VARIABLES’ [comment_1]

    Line 2 to Line n1+1 : name, type, [initial value], [initial status], [comment_n1+1]

    Line n1+2 : END VARIABLES (fixed keyword)

    where n1 is the number of user-defined variables, items in square brackets are optional, and other parameters are as defined in the data section.

    Note:

    The definition of global variables is located within the network .dat file in a block beginning with the keyword VARIABLES. This block must be placed immediately following the INITIAL CONDITIONS block (including the specification of the initial conditions themselves [i.e. the table]) and before any GISINFO block.

    Example

    INITIAL CONDITIONS
    label   ?      flow     stage froude no  velocity     umode    ustate         z
    Lostock      y     2.930     4.915     0.000     0.000     0.000     0.000     0.000
    ResGauge     y     0.000     0.000     0.000     0.000     0.000     0.000     0.000
    …
    Black_Brk    y     1.000    72.557 -9999.990     0.000     0.000    28.000     0.000
    VARIABLES MyGlobalVariablesComment
    PenstockWaitTime    Timer               OFF       ACommentAboutMyTimerVariable
    MyIntegerVariable   integer   15                  ACommentAboutMyIntegerVariable
    MyTernaryVariable   ternary   NEUTRAL             ACommentAboutMyTernaryVariable
    END VARIABLES
    GISINFO
    RIVER MUSK-XSEC YARR04_10900 0 0 0 0 0
    RIVER MUSK-XSEC YARR04_05410 0 0 0 0 0
    …
    

    Was this article helpful?

    What's Next
    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.
    ESC

    Eddy AI, facilitating knowledge discovery through conversational intelligence