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.

Important:

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

Consists of alphanumeric and underscore (“_”) characters only, and does not begin with a number
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:

A condition statement (e.g. “IF variable.GE.10”)
An instruction statement [LHS] (e.g. “THEN variable=1”)
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.

Keyword	Value	Intent (not enforced)
ON	2	Timer
OFF	0	Timer
TRUE	1	Boolean
FALSE	0	Boolean
RISING	1	Ternary
FALLING	-1	Ternary
NEUTRAL	0	Ternary
UP	1	Ternary
DOWN	-1	Ternary
NORMAL	0	Ternary

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 form	Description	Name in datafile
Comment_1 (above table)	Optional comment for the set of global variables
Name	Name 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 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.

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
…