skip to main content
RPL
RPL Set Comparison Tool
The new RPL Set Comparison Tool compares two RPL sets and shows you the differences between the sets. This allows you to see where items are different, what the specific differences are, and allows you to easily access the RPL set dialogs so that you can change one or both sets.
This tool is very useful in the RPL set development processes over time and across multiple developers. It allows the comparison and understanding of development of a RPL set. In addition, it helps assist with merging of changes by providing quick access to the RPL editors and copy/paste functionality.
A screenshot of the tool is shown below. For more information, see Comparing RPL Sets in RiverWare Policy Language (RPL).
RPL Set Name vs Path
All RPL sets now maintain both a name and a file path (if saved as a separate file). Previously, these two concepts were intermixed. This allows you additional flexibility as follows:
• Sets saved to a separate file can have a meaningful name that describes the set, like “Operations Ruleset”. The path can then be used strictly as a file name, C:\Operations\OpsSet.v1.2.rls.gz
• Sets saved within the model file have a name that can be used for improved nomenclature. For example an Initialization ruleset could be named “Operations Initialization Set”.
Locations in RiverWare that refer to a set, now uses the set name. For example, in a Model Report, in the RPL Set item, you now choose the name of the set, not the path or location.
RPL Search and Replace Utility
The RPL Search and Replace utility, RPL Search and Replace Dialog in RiverWare Policy Language (RPL), allows you to search for and replace items within a RPL set. The following enhancements were made:
Next / Previous buttons
Buttons were added for advancing forwards or backwards through the search results. These can also be activated using keyboard short cuts:
• Next Item: F3
• Previous Item: Shift +F3
Scroll To and Select Match
When a match is opened (by double-clicking on that row or by using the next/previous item operation), the relevant dialog is now scrolled so the match is in view and the item is selected.
Expression Slot Descriptions are Searched
Expression slot descriptions are now included in searches when the RPL Expression Slot Functions set is searched and when the Descriptions options is checked.
RPL Editing
Auto-correct of Typed Values
When you double-click on a RPL expression (i.e., on a RPL value or an empty expression in a panel for displaying and editing RPL statements and expressions), a small, in-line editor window is opened at that location, allowing you to type in a value with which to replace the existing expression. If the value provided is not a valid replacement for the expression, RiverWare now attempts to coerce the input string into one that is valid.
This auto-correction process is guided by the types that can legally replace the existing expression. It tries a series of variations on the specified values, where each variation is an attempt to coerce the input into a different value type. Types are considered in the following order: DATETIME, OBJECT, SLOT, STRING, and LIST. If a valid auto-correction is found, it is used to replace the existing expression; if not, an error notification is presented, describing the problem with the input.
For example, consider the statement
WITH (STRING val = <string expr>) DO
PRINT "value: " CONCAT <expr>
END WITH
If the text 't + 1' is entered as the variable value in the With expression, it is interpreted as the String “t + 1” because that is the only legal type for that expression; whereas the same text entered as the right-hand side of the CONCAT expression is interpreted as the DATETIME @“t + 1", because all types are valid in that location and a DATETIME conversion is considered first.
Common Values
Two new operations were added to provide common values when editing RPL expressions.
• A new “Values” button group was added to the palette to support insertion of common values and Flag Values.
• A right-click context menu on any selected RPL expression provides a Common Values menu.
Copy and Paste from Variable and Argument Declaration
A RPL variable declaration name can now be copied and pasted into expressions as appropriate.
Within the function editor, you can copy an argument name and paste it into an expression. This works slightly differently. To copy an argument select the argument name by double-clicking on it in the arguments panel, then perform the copy operation using either the right-click context menu or by typing Control + C. You can then paste this argument into an expression in the function using the Control+V keys or right-click menus. Note that the Edit->Copy menu does not work to copy the function argument.
Improved History
When you double-click on a literal value or an empty expression, a small, in-line editor window is opened at that location, allowing you to type in a value or select a value from the menu of items previously entered in the frame. Previously, this history menu was sometimes missing entries (especially those that were not a valid value to insert). Now, the history includes all previous entries (except empty strings).
Improved Pasting of Statements with Variables
RPL statements that define a variable (i.e., WITH and FOR statements), now allow better copy and pasting. For example, consider the following logic:
WITH (OBJECT res = % "res1") DO
IF (res & "Inflow" [] == 0.0) THEN
WITH (NUMERIC flow = 0.0) DO
PRINT res
END WITH
END IF
END WITH
Pasting the If statement onto itself previously caused the inner WITH statement to have an validity issue where the reference to “res” within the new Print statement would be reported as invalid. This has been improved so that copy and paste of these types or statements works as expected.
RPL Item Delete Confirmation
Deleting an item from a RPL editor tree view now presents a confirmation dialog.
Stop on NaN for Initialization Rules
The existing Stop on NaN property of a rule (Stop On NaN in RiverWare Policy Language (RPL)) allows you to specify that the run should abort instead of having the rule terminate early when a NaN is found in a slot value. This can be used to stop the run when missing data is expected but not found.
If an invalid value (NaN) is encountered while executing an initialization rule with the “Stop on NaN” property enabled (and the RPL debugger is not enabled), the run no longer immediately aborts, but rather posts an error and continues to execute any subsequent statements in the initialization rule and any subsequent rules in the initialization rules set. After all initialization rules have executed, the run is aborted with the message:
Aborting the run because one or more initialization rules with the “Stop On NaN” property set encountered an invalid value (NaN).
If multiple statements access data which are missing, the new behavior allows a single RiverWare run to identify all of these statements. Previously, you would need to resolve the first issue and conduct another run in order to be alerted to the next issue. But, the new behavior can report invalid values that are not in fact independent data issues (i.e., report false negatives), but are rather later rules accessing a value set by an earlier rule that has missing data.
If the RPL Debugger is enabled when an invalid value is encountered by an initialization rule with the “Stop on NaN” property set, RPL execution is paused just before the run is aborted, and the RPL debugger is presented, displaying the error message that is about to be posted.
Note that this represents a change in behavior for existing models, though not for runs that currently complete successfully.
RPL Predefined Functions - New IntegerWithUnitsToString function
A new RPL Predefined function, IntegerWithUnitsToString, was added. This function allows you to convert the integer portion of a NUMERIC value with the specified units into a string. This provides more flexibility than the existing IntegerToString function that only uses internal units.
For more information on IntegerWithUnitsToString, see IntegerWithUnitsToString in RiverWare Policy Language (RPL).
RPL WHILE Expression Maximum Iterations
The RPL WHILE expression (added from the palette) is now limited to loop no more than the maximum number of iterations. The maximum iterations is a model specific parameter saved in the RPL Parameters. The default maximum iterations is 10,000 but may be changed using the Policy RPL Parameters... menu on the workspace. If maximum iterations are exceeded, the run is aborted. See Conditional and Iterative Operations Buttons in RiverWare Policy Language (RPL) for more information on the WHILE expression.
Revised: 01/05/2024