skip to main content
Rulebased Simulation
Performance Improvements
The performance of models using RPL sets (rule based simulations and some accounting simulations) has been improved. Briefly, the changes responsible for the improvements were:
• RiverWare now caches a reference to the function accessed by each function call, saving the time required to look up the function by name.
• Some function argument error checking in done only once at the beginning of a run instead of every time the function call is evaluated.
• When diagnostics are disabled, we more thoroughly avoid spending time processing certain rule diagnostics.
• Symbols (references to variables and functions) are managed more efficiently during validation and execution.
On several large benchmark models these changes improved the overall runtime by an average of greater than 30%.
New Palette Expression
Following is a brief description of a new rules palette expression available for use in the RiverWare Policy Language for writing rules.
MAP LIST
The MAP LIST expression. This expression can replace the FOR expression in some situations and is typically much more efficient. In particular, the following pattern involving a FOR expression:
FOR ( <type/name pair> IN <list expression> )
WITH LIST result = { } DO
APPEND <expression not involving result> ONTO result
ENDFOR
may be replaced with the following pattern involving a MAP LIST expression:
MAPLIST ( <type/name pair> IN <list expression> ) DO
<expression not involving result>
ENDMAPLIST
Example:
MAPLIST ( NUMERIC x IN {1, 2} ) DO
x + 10
ENDMAPLIST
Evaluates to the list:
{ 11, 12 }
New Palette Functions
Following is a brief description of the new rules palette functions (Predefined Functions) available for use in the RiverWare Policy Language for writing rules. Details on the use of these functions and the syntax involved are available in the Rulebased Simulation documentation in the online help.
RowLabel, ColumnLabel
The RowLabel and ColumnLabel functions get the label associated with the row or column of a table slot.
AccountNamesFromObjReleaseDestinationIntra
The AccountNamesFromObjReleaseDestinationIntra function is the same as AccountNamesFromObjReleaseDestination function except that it only looks at transfer supplies, as opposed to outflow supplies.
DatesInPeriod
Given a periodic slot and a date, the DatesInPeriod function returns an ordered list of dates representing the beginning time of each interval which begins in the specific period containing the input (reference) date.
Every periodic slot has a period associated with it, and this period is divided into intervals. Intervals are either regular (e.g., Days) or irregular (e.g., 8:00 July 3). One can map a period (divided into intervals) onto a timeline, leading to several specific periods (divided into specific intervals). For example, the period "Year" maps onto specific periods corresponding to each year, such as the specific period which is the year 2003.
Providing a reference date serves to indicate a specific period, and this function returns the dates corresponding to the beginning of each time interval which begins in that specific period.
Split
The Split function takes two strings as argument, a primary and separator string, and returns a list of strings formed by representing the substrings of the primary string which are separated by the separator string. This function is case sensitive.
Exp
The Exp function takes two numeric arguments, an operand and an exponent, and returns the result of exponentiating the operand to the power given by the exponent. The return value is dimensionless (has no units).
The exponent is not restricted to being an integer (as with the "^" operator), but it is an error for the operand to have units.
SumSlotSkipNaN, SumFlowsToVolumeSkipNaN
The SumSlotSkipNaN and SumFlowsToVolumeSkipNaN are variations of the SumSlot and SumFlowsToVolume which treat NaN’s as zeroes.
FlattenList
The FlattenList function takes a list and replaces any lists contained within that list with the individual items in those lists.
ToCelsius, ToFahrenheit, ToKelvin
The ToCelsius, ToFahrenheit, and ToKelvin functions convert a value in one temperature scale to another scale.
Changes to Temperature Units
The RplUnit temperature dimension has been expanded to three dimensions, corresponding to the following three temperature scales: Kelvin, Celsius, and Fahrenheit. Up until now we had a single temperature dimension, but this was not adequate for representing units such as "m/F". However, more work remains to be done to fully support operations involving temperature. In particular, we need to provide a more convenient mechanism for allowing users to guarantee that values read from the workspace have units with a particular scale.
New Rulebased Simulation Diagnostics Settings Categories
Hypothetical Simulation
A new diagnostics category “Hypothetical Simulation” has been created to issue informative diagnostics during the execution of a RPL hypothetical simulation function. The category can be toggled on within the Rulebased Simulation Diagnostics Settings dialog box. Diagnostic messages are posted during the execution of any one of the five hypothetical simulation function methods. Among other messages, the diagnostics indicate the range over which a hypothetical simulation is occurring. All Hypothetical Simulation diagnostics messages are prepended with the string “HypSim”.
Function Execution
A new function diagnostics category, Function Execution, has been added to the Rulebased Simulation Diagnostic Settings. This diagnostic category allows function diagnostics to be toggled on and off independent of rule execution diagnostics.
Rules Analysis List Dialog
A Rules Analysis dialog was added to RiverWare. The analysis dialog provides a list of Rpl objects (Rules, Functions, Groups) of ruleset and provides a mechanism to view various characteristics of those Rpl Objects. For example, the analysis dialog can be used to examine static features like the orphaned functions of a ruleset. The analysis dialog can also be used examine dynamic features like the evaluation time of the each Rpl object.
Rules Performance Analysis
The ability to instrument the evaluation time of functions and rules has been added to Rulebased Simulation. By selecting the "Enable Rules Performance Analysis" toggle in the Simulation Run Parameters dialog, which accessed through the Run Control dialog, the rule-based evaluation instrumentation is enabled. This instrumentation will track the CPU time spent during evaluation/execution and number of evaluations of each function and rule. This instrumentation itself does consume CPU time, so it should only be used for debugging purposes. The results of instrumentation can be viewed in the new Rules Analysis List dialog.
Function Diagnostics Menu Items
New menu options have been added to the Ruleset Editor and the Group Editor to enable/disable pre/post diagnostics in all functions in the ruleset/group.
Revised: 07/05/2022