skip to main content
RiverWare Policy Language
RPL User Interface
RPL Statements
In RPL set editors, the Rule/Method menu option was improved to only show the types of statements relevant to the given set. In a Ruleset or Object-level Accounting Method set, the following statements can be added: Print, Assignment, ForEach, If, If Else, and Stop Run. The last three statements are new, see IF and IF ELSE Statements for more information. In a RPL based Optimization set, the following statements can be added: Soft Constraint, Constraint, Objective, Freeze, If, and If Else.
RPL Palette
Re-use of expressions in sub-expression:
When the user selects a non-empty RPL expression, and then clicks a palette button, RiverWare now does a better job, where applicable, of re-using the existing expression in the first sub-expression. In general, the existing expression becomes the first part in the new expression. So if you have an expression 10 [“cfs”] and you select the <N>+<N> button, the expression becomes 10 [“cfs”] + <N>. In the WITH and GET operators, the selected expression becomes the body of the expression.
Available Palette Buttons:
The palette was improved to better show which buttons are available for a selected expression. In particular, all buttons are disabled when a type/name pair is selected. For example, in a ForEach statement, if the “NUMERIC result” is selected, all palette buttons become disabled. Also, when a binary expression is selected, the correct palette buttons are now enabled.
On the palette, the functions are now either shown as available or unavailable to replace the selected expression based on expression type and the function’s return type. Available functions (either predefined or user defined) are shown in dark text, while unavailable functions are shown in a light grey text. The screenshot above shows that the functions that return a NUMERIC are available and the functions that return a LIST are not available. The user can still single click on a function to select it and show the description (user-defined functions only). Double-clicking an unavailable function will give a Paste Error and ask if you would like to continue using this function.
Operations in RPL set editor dialogs
Orange Check Mark:
In the RPL dialogs, an orange check mark was added to policy and utility groups to specify that one or more items in that group is “off” as shown in the following figure. As before, the user can select the orange check to turn “off” the entire group, resulting in a red X. To turn it on again, restoring the previous state and showing an orange check, simply click the red X.
Selecting Red X:
Also, selecting an item’s X in a group that is turned “off” now turns the entire group “on” without making any changes. This prevents the user from inadvertently changing the status of an item in a group that is off only to find that it is now different when the entire group in turned back “on”.
If all individual items in a group are turned off (red X), then the entire group is considered off and the group will also have a red X. If the user clicks on the group’s red X, a warning message will appear to indicate that at least one item in the group should be turned on.
Deselecting a Row:
In the RPL set editor, left-clicking on a row in the listview that was previously selected by left-clicking causes the row to become de-selected. Previously, selecting a selected row had no special significance. Also, there was no reliable and easy way to de-select a row.
RPL Parameters Dialog
A new “RPL Parameters” dialog was added to the Policy menu on the workspace. This dialog allows the users to provide settings and values which affect all applications of RPL. These parameter settings are saved with the model file.
Currently, there are two parameters:
• Collect RPL Set Performance Information: This switch is not new. It has been moved from the Simulation and Rulebased Simulation run parameters dialogs. (Previously, this was accessed from the Run Control View Simulation Run Parameters or Rulebased Simulation Run Parameters.)
• Numeric Comparison Tolerance: This parameter specifies whether or not to use a tolerance value for numeric comparisons in RPL and allows the user to specify the tolerance value.
IF and IF ELSE Statements
It is now possible to add an IF or IF ELSE statement as the uppermost statement in a rule. This is similar to adding an assignment statement. Care should be exercised when using these statements as the left-hand side of the expression can quickly be hidden under multiple layers of logic.
Stop Run Statement
A new Stop Run statement was added to RPL for use as the uppermost statement in a rule. This STOP RUN <expr> statement is accessible from the Rule Add Stop Run menu. When executed, this statement will abort the run and post an error message contained in the specified <expr>. The new Stop Run statement provides functionality allowing a rule to stop a run at the uppermost level. Using the Stop Run statement with the new IF and IF ELSE statement allows a rule to evaluate an expression and stop the run if necessary as shown in the following figure:
The existing STOP_RUN button is still available on the palette. This button should be used within a rule when it is desirable to stop the run inside another statement. The difficulty with this approach is that the expression has to be within an assignment or Print statement. If using a Print statement, then diagnostics have to be turned on to evaluate the Print. This is not the intended use of either the assignment or print statement. The new Stop Run statement avoids having to place the STOP_RUN expression within a Print statement that only evaluates if the user has diagnostics enabled.
Time Invariant Functions
It is now possible to designate a user defined function as being “time invariant”. To indicate that a function does not vary with time, the function editor's Function menu provides a toggle control labelled “Set Time Varying”.
A check mark (on, by default) indicates the function does vary with time. No check mark (off) indicates the function does NOT vary with time. Toggling the check mark off communicates to RiverWare that the function is guaranteed to evaluate to the same value each time it is evaluated, i.e., it is time invariant. Note that functions with arguments will almost certainly not be time invariant; if a function has an argument, then presumably there are some argument values for which the function will evaluate to different values. If a function with no arguments is time invariant, then the first time the function is called within a run the body will be evaluated and the result saved internally. For all subsequent calls of that function within the run, the cached value will be returned without further computation, reducing computation time.
Note that incorrect application of caching to a time varying function will lead to incorrect results, so it is recommend that the time varying property be toggled off for a function only when it is definitely time invariant, run time is critical, and RPL set analysis has indicated that a significant portion of the run is spent evaluating the function. When the function does not vary with time a warning message is added to the bottom of the function editor.
Note:  During rule evaluation, the workspace remains unchanged (because RPL expressions evaluate without side effects), so it is safe to cache values for functions without arguments within a single rule. RPL does this automatically for all functions without arguments. Multiple evaluations of such a function within the same rule execution will cause the function to evaluate only once.
RPL Diagnostics
FOREACH diagnostics
A diagnostic was added to the “Rule Execution” category. This message is posted when a FOREACH statement is called. The diagnostic prints the list of values over which the FOREACH statement is iterating.
Modified Predefined Functions
In the HydropowerRelease predefined function, a call is made to determine the maximum proposed power release. This call was modified such that RiverWare does not abort with an error if the Elevation Volume table is exceeded during the mass balance iteration. Instead, the limits of the table are used in the iteration scheme.
The predefined function SolveOutflowGivenEnergyInflow was modified such that RiverWare does not abort with an error if the Elevation Volume table is exceeded during the mass balance iteration. Instead, the limits of the table are used in the iteration scheme.
The MeetLowFlowRequirement predefined function was incorrectly accessing the current slot values before returning the result to the calling rule. The function was fixed to now add the calculated flow to the current values in the Low Flow Release and Outflow slots.
New General Predefined Functions
DateToNumber and NumberToDate
Two new predefined functions were added that convert between RPL date/times and numeric values which are used to encode those dates in a way appropriate for slots that have the new DateTime unit type.
New Accounting Predefined Functions
AccountAttributes(STRING -- “object^account”) returns a list containing the account's attributes, i.e., the account's water type, water owner, and account type of the form {STRING, STRING, STRING}.
ObjAcctSupplyByWaterTypeRelTypeDestType(STRING -- subbasin, STRING -- water type, STRING -- release type, STRING -- destination) returns a list of lists each containing an {Object, Account, and Supply}. The function is provided a subbasin (argument 1), a water type (argument 2), a release type (arguments 3) and a destination type (argument 4). The function searches the specified subbasin and finds all of the {Object, Account, Supply} triplets which match the following conditions: the object is in the given subbasin, the returned object^account is served by the supply, and the supplying account (upstream end of the supply) has the given water type, release type, and destination.
ObjectsFromAccountName(STRING -- account name, STRING -- account type) returns a list of the objects that contain an account with the given name and type.
ObjectsFromWaterType(STRING -- water type, STRING -- account type) returns a list of the objects that have an account with the indicated water type and account type.
SourceAccountAndObject(STRING -- supply name) returns a list containing the indicated supplies’ source (upstream) account and object of the form {STRING, OBJECT}.
SupplyAttributes(STRING -- supply) returns a list containing the supply's attributes, i.e., the supply's release type and destination of the form {STRING, STRING}.
Revised: 01/05/2024