Rulebased Simulation
Documentation is now available for the pre-defined functions used in Rulebased Simulation. The documentation is reached by selecting Browse Rulebased Simulation Documentation from the online help menu.
Closing a Ruleset
A loaded ruleset is no longer allowed to be closed while remaining loaded. If a loaded ruleset is closed, the ruleset is automatically unloaded. The user will be asked to confirm this action upon closing the ruleset.
Print Statements
PRINT statements now always execute when their containing rule executes, regardless of whether or not any other statements within that rule succeed or not. Also, PRINT statements failing will not cause the containing rule to fail. E.g., if a PRINT statement encounters a NaN, a diagnostic is issued noting this fact, but the rule containing that print statement continues execution (as if nothing had happened).
When a RuleExpr is printed out by a PRINT statement or by a diagnostic, the RuleExpr’s text should be more readable, but could be different from what the user would see if they looked in a model file containing the same expression.
Units
All NumericValues now have units. If none are specified then units of NONE are added. Textual representations of NumericValues with units of NONE do not have any unit string.
For the user this means they no longer need to type in units if there aren’t any. Units will now default to NONE, and units of NONE will never show up. This means that users now need to be a bit more careful about units because we aren’t as likely to notice when they forget and leave off units.
Name Checking
Checking was added to prevent the same name from being used multiple times in the same namespace. This was done to prevent the user from accidentally “hiding” a variable in an outer scope by declaring a variable of the same name in an inner scope.
An example of what is not allowed:
WITH (x = 1.0) DO
WITH (x = 2.0) DO
x
ENDWITH
ENDWITH
Did the writer really intend to refer to the innermost x? Maybe not. This problem can be corrected by changing either variable name:
WITH (x = 1.0) DO
WITH (y = 2.0) DO
x
ENDWITH
ENDWITH
This problem will be detected and reported by RiverWare whenever a ruleset is validated (to the CONSISTENT level), i.e., when the user explicitly asks to validate a rule or when the ruleset is executed.
Note that this change actually applies to all named objects, meaning variables as well as functions. If a function is accessible (may be called) from an expression, then its name may not be used as the name of a variable.
Division By Zero
There is now a check for division by zero; both normal division and integer division (==- “/” and “DIV”). If the divisor is zero, then an error is issued (at evaluation time) and the rule fails.
Rule Language Functions
IsNaN
IsNaN is now a built-in function of the Rule Language and not a predefined function (i.e. it is now represented by a button on the palette). It returns true if a NaN is encountered anywhere in the evaluation of the operand expression, false otherwise. Before it only returned true if the operand was a simple expression involving only an object/slot lookup. If it was more complicated and a NaN was encountered, then the execution failed (reporting that a NaN was encountered).
REMOVE
Returns a list which is identical to the given list except the item at the given position has been removed (positions begin with index 0).
SUB
Returns a list which is identical to the given list except the item at the given position has been replaced with the specified expression.
WITH = DO, ENDWITH
This defines variable, binds it to the value resulting from the evaluation of the “variable expression”, then returns the result of evaluating the “body expression” within the scope of this value.
Predefined Functions
Two predefined functions have been added to the Rulebased Simulation Palette. The new functions, as well as all of the existing functions, are described in the Simulation Objects Documentation online. Following is a list of new predefined functions:
DATETIME OffsetDate (DATETIME, NUMERIC, STRING)
where the string specifies a timestep (as with the predefined function GetDates()), which is added to the DATETIME argument an integral number of times given by the NUMERIC argument (rounded down, units must be “NONE”). The resulting DATETIME is returned.
OBJECT GetObject (STRING objectName)
Given the name of an object, finds and returns the object of with that name.
Net Subbasin Diversion Requirement
The pre-defined function NetSubbasinDiversionRequirement now uses the MinBypass slot on the reach (if it exists and is known) as the minimum flow. Detailed documentation of this method may be found in the Rulebased Simulation Documentation online.
Diversion Object with Rules
The NetSubbasinDiversionRequirement and NonShortDiversionRequirement functions now work with the Diversion Object as well as AggDiversionSites.
Revised: 07/03/2024