skip to main content
RiverWare Policy Language
Comments within Expression
Support for inline comments within expressions was extended in several ways:
• Comments can now be shown or hidden within all dialogs displaying RPL expressions using the View Show Comments menu or the new checkbox described Display of Optional Items.
• Deletion of the selected comment is now supported from the Edit menu and using the Del key.
Display of Optional Items
RPL editors have panels which are optionally displayed. The display of these optional dialog items are controlled via checkboxes in the View or Expression menu. For example, the Rule Editor dialog allows the user to optionally show or hide the text description associated with that rule.
An additional row of checkboxes was added to these dialogs to provide more convenient control over the display of the most commonly viewed optional items. In addition, frames around each of these checkboxes provides a visual indication of whether or not the hidden item contains non-default content.
Initialization Rules
Initialization rules were added to RiverWare to allow you to execute logic to “set up” a run, set default values, or set initial conditions. Initialization rules are saved in the model file in a separate set that can be accessed from the workspace Policy Initialization Rules. These rules have the following properties:
• For simulation and rulebased simulation runs, they are executed once at the beginning of the run after inputs are registered but before beginning of run data checking.
• Values set by initialization rules are given either the initialization flag “i” or the DMI input flag “Z”, based on user specification for each rule.
• There is one set per model and the set is saved in the model file.
Button Labels and Reorganization
The palette button labels were simplified and made more consistent. The palette is shown to the right. Full documentation of the palette is provided RPL Palette in RiverWare Policy Language (RPL).
Equality Operators Support All Data Types
In the RiverWare Policy Language, the equality and inequality operators (== and !=) were extended to all data types including BOOLEAN, SLOT, OBJECT, and LIST. Previously, only DATETIME, NUMERIC, and STRING were supported. Expressions can now be written more efficiently. For example, the following expression checks if the looping variable res (of type OBJECT) is the object named BigRes. Previously, you would have written:
IF ( ( STRINGIFY res ) == "BigRes" )...
Now, it should be re-written:
If ( res == %"BigRes" ) ...
This change improves the performance and readability of the expression.
List Access
The RPL language provides seven operators for accessing list items, one for each type which might be returned, i.e GET NUMERIC @ INDEX <num> FROM <list>, GET BOOLEAN @ INDEX <num> FROM <list>, etc... These operators were replaced with a single operator for which the type of the item being accessed remains unspecified. The new operator has the following syntax:
An example is shown to the right. In this screenshot, triplet is a LIST containing three items: {slot, datetime, numeric}.
This new operator has the following advantages:
• Improved readability of policy: the display of expressions involving list item access is simpler and more compact. It now more closely resembles the syntax commonly used by other programming languages for accessing sequential data.
• Improved RPL palette: the RPL palette is smaller and simpler because the seven GET buttons have been replaced by a single button. See the next section for a screenshot.
The runtime performance of the RPL Debugger was improved; in the sample model the time decreased by an order of magnitude. Although enabling the RPL Debugger will slow down most models, this improvement makes the RPL debugger much easier to use for many real applications.
General RPL performance was improved by modifying the processing of numeric values, list values and units.
Predefined functions
ElevationToAreaAtDate, StorageToAreaAtDate, and StorageToElevationAtDate
New predefined functions called ElevationToAreaAtDate, StorageToAreaAtDate, and StorageToElevationAtDate were added for use with the changing Elevation Volume and Elevation Area methods described Changing Elevation Volume and Elevation Area Methods. These functions behave identically to the non “AtDate” versions but allow you to specify at which date the conversions should be performed. This datetime is required only when the Changing Elevation Volume / Area methods are selected.
Certain Date Functions no Longer Require Fully Specified Datetimes
The following predefined functions no longer require a fully specified datetime:
• GetMonth
• GetMonthAsString
• GetDayOfMonth
• GetYear
They evaluate correctly as long as they have the required information. For example, GetMonth will work if the month is specified. Thus, you can now successfully call GetMonth(@“Current Month”).
Iterative Hypothetical Simulation
Additional checking and warning messages were added to the hypothetical simulation predefined functions which iterate over individual hypothetical simulations to achieve a desired result. These warnings make it easier to identify when algorithmic assumptions have been violated which might affect the integrity of the results. Documentation for the group of hypothetical simulation functions was also improved.
PercentRank and Percentile functions added
Functions to compute the "PercentRank", PercentRank in RiverWare Policy Language (RPL), and "Percentile", Percentile in RiverWare Policy Language (RPL), were added to the RiverWare Policy Language (RPL) predefined functions.
Predefined Function Automatic Dependent Slots
Previous Storage is no longer registered as a dependency by getMaxOutflowGivenHW, getMaxOutflowGivenInflow, getMaxOutflowGivenStorage, getMaxReleaseGivenInflow, and getMinSpillGivenInflowRelease.
Rule Execution
When a rule encounters an invalid value during rule execution, rule execution is halted, the rule finishes ineffectively, and the rule will execute again only after one of its dependencies changes. As an alternative, a property was added to rules which allows the user to change this behavior for rules that are not expected to encounter an invalid value. When the Stop On NaN property has been set for a rule (using the Rule Stop on NaN menu), invalid values cause the simulation to halt with an error message, allowing the user to investigate the cause of the unexpected invalid value.
See Stop On NaN in RiverWare Policy Language (RPL) for additional information.
Close Dialog Versus Close Set
For RPL Set Editor dialogs, RiverWare now makes a distinction between closing the window (dialog) versus closing the set. For previous versions of RiverWare, closing a RPL set editor window also closed the set. Following is a description of the two behaviors:
Close Window
Closing a RPL Set Editor window closes the editor for the RPL set, but does not close the set itself. Closing a set window is easily reversible: selecting the appropriate item in the Workspace Policy menu will reopen the editor.
From within RiverWare, this action is initiated from the main menu of a RPL set editor by selecting File Close Window (Ctrl+W). This closes that window without affecting any other window.
In addition, the set editor can be closed using whatever mechanisms are provided by the operating system's window manager for closing windows. For example, Windows operating systems support closing a window when the user selects on the red X button in the window's upper right corner.
Close Set:
Closing a set removes that set from RiverWare's internal memory, and so is not easily reversible. This action is initiated from the set editor's menu by selecting File Close (and Unload) Set. The user is then presented with a confirmation dialog pointing out that unsaved changes to the set will be lost and giving them the option to cancel the operation. This behavior has not changed, though the "Ctrl+W" shortcut for this action has been removed.
Sets that are saved within the model file can not be closed directly; to remove these sets from memory the user must clear the workspace or load a new model. Thus the only types of RPL sets which may be deleted via the RPL Set Editor's File menu are:
• RBS Rulesets (not loaded or loaded but not saved in the model)
• Optimization Goal Sets (not loaded or loaded but not saved in the model)
• Global Function Sets
Note that clearing the workspace or loading a model implicitly closes any existing sets, and in this case the user is presented with a confirmation dialog analogous to the one described above.
Modified Colors Of RPL Sets and Icons
Each application of RPL now has a unique color associated with it. For those sets always saved with the model file, the icons and color bar is always the same. For RBS, Optimization and Global RPL sets, the editors associated with a single set will have the same color, but that color is different for each set. The line color for loaded RBS sets remains red (to match the icons). For the loaded optimization set's editors, the line is purple, to match the goal set icons.
Expression Slot Set
Global Function Set
Initialization Rules
Iterative MRM Ruleset
Navy Blue
Object Level Accounting Method Set
Optimization Goal Set
Rulebased Simulation (RBS) Ruleset
RPL Display Settings and Display Of User-defined Function Calls
The RPL Layout Editor was renamed the RPL Display Settings dialog and was re-implemented to more intuitive and easier to use. The dialog can be accessed from the Set Display Settings menu on any RPL dialog. See Formatting: Display Settings in RiverWare Policy Language (RPL) for more information.
Further, within expressions, calls to user-defined RPL functions can now be shown in a user-settable color. The color is configured in the display settings dialog shown to the right.
Sets Saved with Model Now Have Indicator Icon
RPL sets that are saved in the model file now have a model file icon displayed next to the title bar.
When a RPL expression accesses a value on a slot, there are now several options for how the slot value is represented internally:
--rplslotvalunits argument
The slot's user scale and standard units. This was the original representation, the only possibility until now, and is the current default.
A scale of 1.0 and the slot's standard units
The slot's user scale and user units, unless the units are time-varying (e.g., acre-feet/month), in which case a scale of 1.0 and standard unit is used.
The RPL slot value representation scheme has two primary impacts:
• Numerical accuracy of the computation - the representation scheme affects the magnitude of the RPL values and so impacts numerical accuracy. Generally speaking the greatest accuracy is expected when using values of moderate magnitude. For many models, this consideration favors the "user" representation.
• Diagnostics - Sometimes diagnostics present values in a form related to their internal representation. In most cases, this consideration favors the "user" representation.
A command line argument was added to control the RPL slot unit representation. the argument is "--rplslotvalunits" and it requires an argument as listed in the above table
Using the default “mixed” units will reproduce results in your model but you may consider using the “user” option for diagnostic and/or accuracy purposes.
The RPL unit grammar was also extended to allow parsing of the caret character to indicate "raised to the power of". This brings the input and display syntax into agreement. For example, in the past a value was displayed as"m^2" but that was not legal input; now it is.
Revised: 08/02/2021