Global variables

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.

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.

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

Datafile format

General

Line 1 : keyword ‘VARIABLES’ [comment_1]

Line 2 to Line n₁+1 : name, type, [initial value], [initial status], [comment_n₁+1]

Line n₁+2 : END VARIABLES (fixed keyword)

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

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
…