skip to main content
RPL User Interface
RiverWare Policy Language (RPL)
RPL User Interface
RPL Sets
This document describes basic rule, function, method, or constraint construction with the RPL Set Editor. The RPL Set Editor is the main window through which policy is managed. From this window:
• Rules, functions, or methods, may be added, deleted, opened, named, prioritized and turned off or on.
• Entire RPL sets may be opened, closed, saved, loaded, exported, imported and unloaded.
Types of RPL Sets
This document refers to all of the RPL sets in RiverWare as follows. Table 2.1 shows information about each set that will be referred to later
 
Table 2.1   
RPL Set
Set Color
Save Location
Link to More information
Expression Slot Set
Orange
In model file
Global Function Set
Brown
Separate file OR in model file
Initialization Rules
Teal
In model file
Iterative MRM Ruleset
Navy Blue
In model file
Object Level Accounting Method Set
Green
In model file
Optimization Goal Set
Purple
Separate file OR in model file
Rulebased Simulation (RBS) Ruleset
Red
Separate file OR in model file
When dealing with specific menus, this document will use the terminology set in place of any type of set. Each set has a unique menu name and should be used accordingly.
Set Name
Each set can have a user-specified name that is separate from the file path. The default for a newly created set is RPL Set N. Enter your desired name in the field shown in Figure 2.1.
Figure 2.1   
Note:  Prior to RiverWare 7.0, the name and the file name were the same. When loading an old set into 7.0, the name defaults to the file name. You can change the name if desired.
Save Location
Based on the type, the set is saved in one of two locations, as shown in the Table 2.1.
• In the model file or
• In an external file
Four of the sets (expression slot set, initialization rules, iterative MRM rulesets, and accounting method set) are always saved in the model file. Global functions sets, Rulesets and Goal sets may be saved in either location as specified in the Run Parameter for the appropriate controller. This is accessed from the Run Control dialog. When the Rulebased Simulation or Optimization controller is selected, then the View, then Optimization/Rulebased Simulation Run Parameters menu opens the parameter dialog.
The Save Loaded RPL Set with Model checkbox controls where the set is saved. By default, this option is disabled, meaning the set is saved in a file external to the model. Enabling it will save the Loaded set with the model file.
Note:  This toggle only applies to the loaded set. Any other opened sets will not be saved with the model file.
All of the Run Parameter dialogs contain an option to Save All Global Functions Sets with Model toggle. By default, this option is disabled, meaning that all global functions sets are saved in files external to the model. Enabling it will save all open global functions sets with the model file.
Once a set is saved with the model file, there is some risk that it may be lost if:
• The toggle above is unchecked and the model is saved.
• The set is unloaded and the model is saved.
• Another set is loaded and the model is saved.
• Closing the set and the model is saved.
In each case, a warning message is presented to allow you to confirm that the action is intended. A set saved with the model is automatically loaded when the model is opened. The set is then minimized. You can bring it to the front at anytime using the workspace Policy menu or the buttons on the bottom of the workspace.
Further, for any set that is saved with the model, a model file icon is displayed at the top right of the dialog.
Sets that are saved in an external file have the path shown below the set Name.
Managing RPL Sets
Following is a description of managing RPL sets. Much of this information is specific to the RPL set in question.
Actions Specific to Rulesets, Optimization Goal Sets, and Global Function Sets
The following actions are specific to managing a set (either Ruleset, Optimization Goal Set, or Global Function Set) and are performed on an entire set. Figure 2.2 illustrates.
Figure 2.2   
• New. A new RPL set is created by selecting Policy, then Set, then New from the main RiverWare workspace or File, then New Set from an already opened set.
• Open. An existing RPL set (saved as a file) is opened by selecting Policy, then Set, then Open from the main RiverWare workspace or File, then Open Set from an already opened set. Either of these commands invokes a file chooser in which the desired set is selected. Each set is saved in a separate file. Several sets may be opened at once. Each opened set and any windows opened from these sets are identified by a unique color band across the top of their windows.
• Reopen. An existing RPL set (saved as a file) can be reopened by selecting Policy, then Set, then Reopen from the main RiverWare workspace or File, then Reopen Set from an already opened set. Either option then presents a cascading menu of recently opened sets and folders.
• Reopen and Load. An existing RPL set (saved as a file) can be reopened and loaded by selecting Policy, then Set, then Reopen and Load from the main RiverWare workspace. Then, a cascading menu of recently opened sets and folders is presented.
• Show RPL set. When a set is opened, the name of the set is added to the workspace Policy menu as shown in Figure 2.3. Only the short name is shown in the menu, but the full path is shown in the workspace status bar. Use this menu to raise/show the desired set. When the set is saved with the model file, the menu will show it as RPL Set.
Note:  The expression slot, initialization rules, MRM and accounting methods sets (saved with the model) are always shown too. Also, the workspace has buttons to show the loaded RBS ruleset or optimization goal set . The bar is colored when there is a loaded set, grey when there isn’t. Select one of the buttons (when a set is loaded) to raise that set to the top.The workspace also shows color coded buttons for all the opened sets. Tooltips indicate their names, as shown in Figure 2.4.
Figure 2.3   
Figure 2.4   
• Save. The RPL set is saved to a file by selecting File, then Save Set in the Set Editor menu bar. The name and directory of the file to which the RPL set is saved is that from which it was last loaded or to which it was last saved.
• Save As. A new RPL set must be given a name and saved for the first time by selecting File, then Save Set As in the Set Editor menu bar. This command is also used to save an open RPL set to a different filename and/or directory from which it was last loaded or saved. The Save Set As command invokes a file chooser in which the RPL set’s new path and filename must be specified.
• Load. A ruleset or goal set is loaded into a model for use during a run by selecting the RPL Set Not Loaded button on the right side of the Set Editor menu bar. When the set is loaded, the button text changes to RPL Set Loaded and the colored bar along the top of the Set Editor becomes red. Only one ruleset at a time may be loaded for use by a model. Loading a set when another is already loaded will unload the first ruleset. Global Function Sets are not loaded, any open set applies to all other sets.
• Unload. A loaded set is unloaded from a model by selecting the RPL Set Loaded button on the right side of the Set Editor menu bar. When the set is unloaded, the button text changes to RPL Set Not Loaded, and the red bar along the top of the Set Editor reverts to its original color (blue, green, yellow, purple, etc.).
• Close Window (Ctrl+W). An opened RPL set is closed but not removed by selecting File, then Close Window in the Set Editor menu bar. It can be re-shown using the Policy menu on the workspace.
• Close (and Unload) Set. An opened RPL set is closed by selecting File, then Close (and Unload) Set in the Set Editor menu bar. Closing a loaded set automatically unloads the set from the model. Closing does not automatically save changes to the set since the last save. This option is not available for those sets always saved with the model file.
Actions specific to Accounting Method Set, Expression Slot Set, Initialization Rules, and Iterative MRM Sets
The following actions are specific to the Object Level Accounting Method set, the Expression Slot set, Initialization Rules, and the Iterative MRM set. Each of these RPL sets is saved with the model so they do not need to be opened or saved separately.
To show the Object Level Accounting Method set (when accounting is enabled):
• From the Workspace choose the Policy, then Accounting Methods RPL Set or choose Accounting, then Open Accounting Methods RPL Set
To show the Expression Slot RPL set:
• From the Workspace choose the Policy, then Expression Slot RPL Set
To show the Initialization Rules RPL set:
• From the Workspace choose the Policy, then Initialization Rules Set
To show the Iterative MRM RPL set:
• From the Workspace choose the Policy, then MRM RPL Set. The MRM RPL set can also be opened from the MRM run control dialog. See “Iterative Runs” in Solution Approaches for details.
These sets are always active in their respective context so it is not necessary to load or unload the sets. The dialog for the sets can be closed using the File, then Close Set menu. Again, each of these sets is saved with the model file so do not need to be separately saved.
The Initialization Rules Set Editor dialog does have a File, then Save Initialization Rules Set As menu item to save the initialization rules to a file. A File, then Replace Initialization Rules Set from File menu item allows the initialization rules set to be replaced by the contents of a specified file. These menu items allow an initialization rules set to be moved between models via a file. However there is only a single instance of initialization rules in a model and this set is still saved and loaded with the model file. See “Initialization Rules” in Solution Approaches for details on Initialization Rules.
Tour of a RPL Set
In RPL sets there is an upper level construct specific to the RPL set. For example, in a ruleset, a rule is the construct; in an object level accounting method set, a method is the upper level construct. In this document, a block refers to the upper level construct for each of these sets and will be used in all descriptions. Table 2.2 lists the block for each type of set.
 
Table 2.2   
 
RPL Set
Upper-level Block
Expression Slot Set
N/A
Global Function Set
N/A
Initialization Rules Set
Rule
Iterative MRM Ruleset
Rule
Object Level Accounting Method Set
Method
Optimization Goal Set
Goal
RBS Ruleset
Rule
Note:  Expression Slot and Global Function Sets do not have the paradigm of a block. For Expression Slot Sets, the analogous upper level construct is the expression slot itself. Global Function Sets do not have the concept of a block as they contain only global utility groups and functions.
This remainder of this section describes the components of a RPL set when using the RPL set editor.
Elements
A RPL set includes the following general elements:
• Policy Groups: Policy groups are containers for blocks and functions. The functions within a policy group are available only to blocks and functions within that policy group.
• Utility Groups: Utility groups are containers for functions. The functions within a utility group are available to blocks and functions within any policy group.
• Blocks: Blocks (Rules/Goals/Methods) are prioritized expressions of policy which assign slots and/or generate diagnostic messages.
• Functions: Functions are subroutines called from blocks or other functions, which evaluate to a value in one of the expression data types.
• Report Groups: Report groups provide an organizational grouping of related RPL and workspace objects.
• Report Items: Report items refer to blocks or functions in the RPL set or to workspace objects.
Table 2.3 shows all the RPL elements and their icons. The icons are shown in grey, but each set has its own color that is used for the letter.
 
Table 2.3   
Letter
Icon
Item
 
Letter
Icon
Item
G
Goal
 
R
Rule
M
Method
 
S
Set
P
Policy Group
 
=
Statement
 
Report Group
 
F
User-defined Function
 
Report Item
 
U
Utility Group
Predefined functions use the F icon but always have the light blue color.
RPL Set Editor View
Information about a RPL set is displayed in the RPL Set Editor dialog. Each policy group, utility group, block, and function is represented in the RPL Set Editor on a different line. Figure 2.5 illustrates.
Figure 2.5   
Each line includes the following information:
• Name: The name column contains an icon representing the type of the element and its name. All elements are assigned a default name when created.
• Priority: A priority is shown to the right of an element name, when appropriate. Policy groups, utility groups, and functions do not have priorities but policy groups display the range of priorities of its member rules. Priorities number indicates the relative importance of the block.
• Index: For Initialization Rulesets, Object Level Accounting Method Sets, and MRM Rulesets, the Index column is shown. The priority column may not be shown. Rules or methods have a unique Index which is how the rules and methods are referenced.
• Flags: Initialization Rules allow you to specify the flag that is set. For initialization Rulesets, a Flags column is shown.
• On/Off Status: All elements may be turned on or off independently by selecting the green check mark or red X in their line, unless mouse editing has been disabled. If mouse editing has been disabled, a block or function can be enabled or disabled by right-clicking. This will bring up a menu to enable or disable the element. A green check mark indicates that an element is enabled. A red X indicates that an element has been disabled. An element that is disabled cannot be used during the model run. Disabling a policy group or utility group disables all of the blocks and functions within that group. Selecting a group’s red X now enables the entire group without making any changes. This prevents you from inadvertently changing the status of an item in a group that is disabled, only to find that it is now different when the entire group is re-enabled. If all items in a group are disabled (red X), then the entire group is considered disabled and the group will also have a red X. If you select the group’s red X, a warning message will appear to indicate that at least one item in the group should be enabled. An orange check mark on a policy or utility groups specifies that one or more items in that group is disabled, as shown in Figure 2.6. As before, you can select the orange check to disable the entire group. Selecting it again, restores the previous state thus showing an orange check.
Figure 2.6   
• Type: The type of each item in a set is shown in the Type column.
There are several additional pieces of information that can optionally be shown from a RPL set as accessed from the View menu.
Expand or Collapse All Groups
A RPL set’s contents may be viewed with all groups expanded, some groups expanded, or all groups collapsed. Use one of the following methods to expand or collapse all groups simultaneously:
• Select View, then Expand All Groups or Collapse All Groups item in the RPL Set Editor menu bar.
• To expand or collapse a single group, select the triangle next to the group name.
Note:  The following four items can be shown using the View menu or selecting the toggle in the Show: row. If there is an entry in these panels (or a non-default value) the text is bold. For example, in the following screenshot, the Set Description and Set Notes have a non-default entry.
Show RPL Set Description
A description of the RPL set may be typed into the RPL Set Description: text frame and saved in the RPL set file. The description may contain any combination of letters, numbers, spaces and punctuation, except double-quotes (“ ”). The area is opened and closed by toggling the View, then Show RPLSet Description in the menu bar or using the Set Description toggle at the bottom of the window.
Show Selected Description
A special expanded area of the RPL set is used to enter a description of any specific block. The area is opened and closed by toggling the View, then Show Selected Description in the menu bar of the RPL Set Editor dialog or using the Selected Description toggle at the bottom of the window. Select a block name to view the description of that specific block.
Show Set Notes
Notes about the RPL set may be typed into the Set Notes text frame and saved in the RPL set file. The Notes may contain any combination of letters, numbers, spaces and punctuation, except double-quotes (“ ”). The area is opened and closed by toggling the View, then Show Set Notes in the menu bar or using the Set Notes toggle at the bottom of the window. Notes are often used for commenting on development practices; they provide a place to annotate when/why/who changed the set.
Show Advanced Properties
The Advanced Properties are accessed from the View, then Show Advanced Properties menu or using the Adv. Properties toggle at the bottom of the window The Advanced Properties area has the following components.
• Agenda Order. Rulesets can be configured to execute in either ascending or descending Priority/(it called Index in Initialization Rulesets) order. Descending order executes the highest priority block first, then each of the lower priority blocks (1,2,3,...). Ascending order executes the lowest priority block first, then each of the higher priority blocks (...,3,2,1). Ascending Priority (...3,2,1) is the default selection and the recommended priority order. The agenda order is only applicable and shown for RBS rulesets, initialization rules, iterative MRM rulesets and optimization goal sets. Also, optimization goal sets always must execute in the 1,2,3... order and cannot be changed.
• Precision. The precision spinner determines the number of digits after the decimal which are displayed for numbers in blocks and functions. 8 is the default value. The displayed precision has no effect on the 17 significant figures of internal precision used for calculations.
Show Predefined Groups
In the View, then Show Predefined Groups menu, you can choose to show the groups for the predefined functions. When you also show Selected Description above, the documentation for that predefined function is shown in the description panel.
Show Statements
In the View, then Show Statements menu, you can choose to show statements (assign, print, etc) as another level in the RPL dialog tree-view. You can also change the name of statements once shown. To do this, right-selects that item to show the context-sensitive menu. Then, selecting Rename will open an inline name editor and you can enter a new name. In addition to the RPL Set view, this statement name will be shown in the RPL debugger and RPL Analysis Tool.
Show Export Columns
The View, then Show Export Column menu allows you to specify if the selected row should be exported. See “Exporting and Importing RPL Sets” for details on Import and Export of RPL sets.
Disable Mouse Edits
It is easy to rename a group, block or function, change the priority of a block, and turn a block on or off. To prevent accidental changing of a block priority or turning the block on or off in the Set Editor as a result of mouse clicks, select View, then Disable Mouse Edits. This will prevent editing with mouse clicks in the RPL Set Editor. To edit a block or group after mouse editing is disabled, double-click or right-click the block, function, or group name to bring up an editor dialog. We highly recommend disabling mouse editing to prevent accidental changes to a RPL set.
External Documentation
View, edit, or configure the external documentation; see “RPL External Documentation” for details.
Editing RPL Sets
Following is a description of how to manage and edit RPL sets once they are open. This includes creating, naming, and editing blocks/groups, adding statements, and validating blocks or the entire set. See “Editing a RPL Expression” for details on editing individual expressions.
When a RPL set dialog opens, the Policy & Utility Groups tab is initially selected, presenting a comprehensive high-level view of the policy. Switching to the Report Groups tab provides a more selective, user-defined view.
Note:  Many actions described below are appropriate only for one or the other main tabs (e.g., adding a new Report Group), and these actions are disabled when they do not apply.
Blocks and Groups
Naming Groups
To name a block or group, right-click or double-click the Name field of the block or group. Right-clicking will bring up a menu from which the editor dialog can be opened. Double-clicking will bring up an editor dialog directly. Type the name in the name field.
Name Color
The color of each name in the set can be specified by right-clicking an item and choosing Change Text Color. The selected color is then used by the RPL set editor, the RPL set analysis tool, and the RPL object selector dialogs for the name of the selected object. For groups, the color is changed for the group name and all members of the group that have the default black color.
Adding Groups
Groups (of type Policy, Utility, Global Utility, or Report) are added to a RPL set by selecting the appropriate item from the RPL set Set menu (e.g., Set, then Add Policy Group, Set, then Add Utility Group, Set, then Add Report Group, or Set, then Add Global Utility Group, for global function sets). New policy and utility groups are added to a set directly below the currently highlighted group of that type.
Add Blocks and Functions
Blocks and functions are added to a RPL set by highlighting the group they are to be placed in and selecting Set, then Add Block, Set, then Add User-Defined Function, or Set, then Add Global User-Defined Function (for global function sets) from the RPL set menu bar. New blocks and functions are added to a RPL set directly below the currently highlighted element of that type or at the bottom of a highlighted policy or utility group.
Add Report Items
The Report Groups tab, shown in Figure 2.7, provides a more selective, user-defined view of the policy/slots and object. Items are added to a RPL report group (visible in the Report Groups tab) by highlighting the group they are to be placed in and selecting the desired action from the Set, then Add Report Items menu, which contains an option to open a selector for each of the following types of objects.
• RPL Object Items Blocks and functions in the current set. See “RPL Printing and Formatting” for details on using the RPL Object selector.
• Object Items objects on the workspace.
• Slot Items slots on objects or accounts.
• Subbasin Item a single subbasin (automatic or user-defined).
Selecting the Ok button in the selection dialog will append the items for the selected objects to the end of the selected report group, but can be moved to any position by using the drag/drop technique.
Figure 2.7   
You can also right-click any RPL item (rule, function, etc), and choose Add to Report Group and select an existing Report Group. This will append the selected RPL item to the Report Group, as shown in Figure 2.8.
See “Report Layout Area” in Output Utilities and Data Visualization for details on including a Report Group in a model report.
Figure 2.8   
Change Priorities
Blocks and functions may be rearranged in a set. By changing the relative priority of blocks, the order of firing, success of slot assignments, and order of dispatching is altered. Changing of priorities is often used to evaluate the effectiveness of different operational policies. Rearranging blocks and functions in a set is simple. To move a block in the list, select its icon and drag the block to the new desired location within the set. If you place it on another block, it will append after that block. Then, simply release the mouse button to drop the block in its new location. A dialog will ask you to confirm that you wish to complete the move. Select OK to confirm the move. All other blocks will be shifted to comply with the new priority structure. There is no need to reload a loaded set when rearranging blocks. Moving a block or a function is done in an identical manner. Predefined functions cannot be moved.
Delete Groups, Blocks and Functions
Groups, blocks and functions are deleted from a RPL set by highlighting them and selecting Edit, then Delete. Deleting a policy or utility group deletes the contents of the group as well. A confirmation dialog is shown.
Open and close Policy, Utility, and Report Groups.
Policy and utility groups which contain at least one block or function can be opened in a separate window by double-clicking their , , or icon or highlighting them and selecting Set, then Open Editor They may also be expanded within the RPL Set Editor window by selecting the white tree-view triangle to the left of their icon or selecting View, then Expand. An expanded policy or utility group can be collapsed by selecting the white tree-view triangle again or selecting View, then Collapse.
Open and close Rules, Functions, Methods, Goals, and Report Items.
Blocks and functions are opened in a RPL Viewer by double-clicking the icon or highlighting the item and selecting Set, then Open Editor. An opened block or function in the RPL Viewer may be closed by selecting red X on the tab or by selecting File, then Close Window from an individual RPL Editor.
Copy and Paste Groups, Blocks, and Functions
Groups, blocks and functions may be copied and pasted within a set or between open sets. An item is copied into memory by highlighting it and selecting Edit, then Copy. An item in memory is pasted just below any highlighted item in a RPL set by selecting Edit, then Append. An item may also be copied and pasted just below the item by selecting Edit, then Duplicate. Copy/Paste/Duplicate is only available within a single model; you cannot copy/paste items from RPL sets that are opened in separate instances of RiverWare. See “Exporting and Importing RPL Sets” for details on Import and Export to perform this task.
Note:  A copied group/block/function can be pasted (or dragged and dropped) as a text representation into any text editor such as a word processor (Word), text editor (notepad), or email program (thunderbird). This includes all information about that group, block, function including the logic, description, active state, etc.
Exporting and Importing Groups and Blocks
In addition to copy and paste operations, it is also possible to export and import all or part of a RPL set. This is useful to share user-defined functions between two RPL sets. Using the export and import utility, you can share groups, blocks, and functions amongst these sets. See “Exporting and Importing RPL Sets” for details on the dialogs.
Validity
Before loading a newly built set into a model (or running with one of the other types of sets), the validity of the set must be checked. This can be done manually or is automatically done at run start. Manually validating a RPL set, however, allows you to perform these checks without having to bring up the Run Control dialog, start the run, and stop the run or wait for it to finish. Validating a RPL set checks for unspecified expressions, illegal object and slot names, conflicting expression types, and syntax errors. It does not check the consistency of unit types in mathematical expressions. Unit consistency is done while the block is evaluated during the run.
• To check the entire set, in the RPL Set Editor, select Set, then Check Validity.
• To check a single block or user defined function, select Block, then Check Validity.
If the block or set is valid, a confirmation window appears. Select OK and continue. Otherwise, a validation error dialog appears and the diagnostic window posts the location of the invalid expression. You then must fix the block.
Comparing RPL Sets
When developing RPL sets, it is often desirable and/or necessary to compare two RPL sets and see what is different between the sets. Following are some examples of when you might want to compare two RPL sets:
• You have multiple copies of similar RPL sets that represent different policy alternatives. You need to determine what is different to make sure they represent the correct policy alternative.
• Your co-worker has made changes to the RPL set and you want to know what changes have been made. Perhaps then you will incorporate the changes into a master version.
• You need to identify all of the changes that have been made to the set since some previous version.
The 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. Although this tool doesn’t support automatic merging, it provides quick access to the RPL dialogs and the ability to copy and paste from the utility to the RPL editors.
Accessing the Comparison Tool
From the RiverWare workspace, use the menu: Policy, then RPL Set Comparison Tool
Or from any RPL set editor dialog select Set, then Compare Set
Selecting RPL Sets to Compare
The tool opens and shows a dialog where you specify the two sets to compare. The two sets are referred to as Set A and Set B. For both sets, choose one of the following:
• Currently Open Set: Choose any of the sets that are open in the current model.
• Read Set from File: Choose a RPL Set on the file system.
• Read Set from Model: Choose a RPL Set that is embedded in another model file on the file system.
Next, choose the set.
For the Currently Open Set option, select the name of the RPL set. For the Read Set from File option, choose the type and file path. Use the More button to open a file chooser. For the Read Set from Model option, first select the model file. Then select the name of the set.
Note:  If reading the set from another model file that was last saved with a RiverWare version prior to 7.0, you will get a notification that you must specify the type of the RPL set.
When finished, select OK. The main RPL Set Comparison Tool opens.
Tour of the RPL Set Comparison Tool
The RPL Set Comparison Tool contains three main areas, as shown in Figure 2.9.
• The Sets panel shows the names, locations and type of the selected Sets.
• The Comparison Results area shows a hierarchical view of the sets and the comparison results. This shows where there are differences between the two sets
• The Selected Property panel shows the values for the selected row for both Set A and Set B. This shows the differences for the selected item.
The following sections describe these areas and how to use the tool.
Figure 2.9   
Sets Panel
The Sets panel shows the sets that are being compared. It shows the set Name, Location, and type. Use the Select Sets button to choose alternative sets. See “Selecting RPL Sets to Compare” for details on the dialog that is displayed.
Comparison Results Panel
The Comparison Results panel shows a hierarchical view of the results of the comparison. The hierarchy is based on the structures of the two set. Columns include the Name, Priority/Index, Status and Type. The Set, Groups, and Rules/Goals/Methods show their particular icon. The Status column shows the results of the comparison. Table 2.4 lists the possible statuses and their meanings.
 
Table 2.4   
Status
Meaning
A = B
The item is identical in Sets A and B.
A ≠ B
The item is different in Sets A and B.
A
The item exists in set A but not in Set B.
B
The item exists in Set B but not in Set A.
A ->
The item exists here in Set A and elsewhere in Set B and/or the item has been renamed.
<- B
The item exists here is Set B and elsewhere in Set A and/or the item has been renamed..
The Type column lists the type of that row, either a Set, Group, Rule, or Property. The comparison tool ultimately compares Properties of the items, not the items themselves. In the Status column, the color indicates the following meaning, This is also shown in Figure 2.10:
• Yellow indicates that the item contains properties and that within the item there are differences in properties.
• A light orange shading indicates the item’s Name property has changed; that is, the item has been renamed. When an item has been renamed (not copied/pasted or moved), the item will show up twice in the list, once with the name used in set A (the status shows “A ->”) and once with the name used in B (the status shows “<- B”).
• The darker orange color indicates that the value of the property is different.
Figure 2.10  Color legend for the Status column
Table 2.5 lists the navigation and control buttons on the top of the Comparison Results panel.
 
Table 2.5   
Button
Text
Meaning
Next Difference
Select the next property that has a difference
Previous Difference
Select the previous property that has a difference
Recompute Differences
Recompute the differences between the two sets. This is useful if you make changes to Set A or B
Show only items that differ
Show only items that are different in the results panel. This is the default behavior.
Double-click a row in the Comparison Results to open the RPL dialogs for that item.
Note:  If the set was loaded from a RPL set file or another model file, the dialogs cannot be opened. If both sets are opened in the model file, then double-clicking a row will open two dialogs, one for each set.
Note:  The RPL Set Comparison Tool compares internal copies of the specified sets. If you make changes to one of the chosen sets, it is not immediately reflected in the comparison tool. Use the Recompute Differences button to update the status in the tool.
Selected Property
The Selected Property panel shows the values for the selected row. If a yellow row (Rule, Set, Group, etc) is selected, a note is shown that “No Property Selected”. Only properties are shown in these views. When an orange Property row is selected, the panel shows the values for that property. The information shown is based on the property type and can include text, colors, true/false, and RPL expressions. When a statement, function body, or execution constraint is selected, the RPL expression is shown for both sets A and B. For example, in Figure 2.11, a statement is selected and the RPL statements are shown. You can see that Set A has a Max function while Set B has a Min function. The total number of differences found is listed above each Selected Property panel. Multiple differences are highlighted whenever possible.
Figure 2.11   
Following are known limitations related to the highlighting of differences:
• When two statements or expression differ only by comment, the tool highlights the entire statement/expression, not just the comment. Ideally the tool would highlight the individual differences in the comment text.
• The tool does not highlight differences in symbol declarations (E.g. NUMERIC num), either in the type or name, but the entire expression is highlighted
• Adding, deleting, or moving a statement within a block (or an item in a list expression) will usually lead the tool to overestimate the number of changes (i.e., every statement after the first difference will be considered different). This is not the case for insertions and deletions within textual properties.
Example of Using the RPL Set Comparison Tool
Following is one use case example where the RPL Set Comparison Tool is very useful.
We have been developing a model and ruleset of our basin and need to add some proposed policy changes to the set. I am busy with other things, so I asked my co-worker to help implement the policy in the ruleset. She did this and sent me the new ruleset on her way out the door for vacation. She left the note that “I added the new rule and had to update a couple other things” but didn’t describe what she changed. I also have been working on the model and now it is time to see what she did and merge it into my work. I use the following procedure.
1. I open my model and load my ruleset. In this case, my ruleset is embedded in the model file; it is called Basin Ruleset.
2. I open (but don’t load) my co-worker’s modified ruleset. This is called Ruleset with Min Flow at Pella.
3. I use the menu: Policy, then RPL Set Comparison Tool
4. I then choose my embedded ruleset, Basin Ruleset, as Set A and my coworker’s modified ruleset as Set B. I then select OK.
5. The RPL Set Comparison Tool opens and shows that there are differences between the two sets. I can use the Next and Previous to step through the differences. I can also uncheck the Show only items that differ to get a sense of where in the set the differences occur. I usually only like to see the differences, so I reselect the Show only items that differ. Figure 2.12 shows the results.
Figure 2.12   
6. It looks like there are five areas of differences. We’ll go through all of the differences in Table 2.6. I select each row to see the property difference in the right hand panel.
 
Table 2.6   
Difference
Description
A
The ruleset name and precision are different.
B
Rule 1 and 2 have changed priority.In Set B, Sehujwane is priority 1. In Set A, Sehujwane is priority 2. Since it is strictly the priority order that has changed, there are no property differences, so the right panel doesn’t show any differences.
C.
Rule 4 is in Set B but not in Set A. The right panel shows the logic in Set B and lists that the property is not in Set A.
D.
Rule 10 is in Set A but not in Set B.
E.
The ExcessStorage function has differences. It looks like my co-worker added a 100 m3 tolerance for the comparison. It would be nice if she had documented why she did this.
7. Now I need to combine or merge her differences into my ruleset. First I’ll select the SetOutflows row to open the policy group for both sets.
8. The priority order of the first two rules is correct in my set, so I’ll leave it as is, with no changes.
9. I need to get the new rule that my coworker developed. Since the desired rule is in Set B, I open that set and right-click the Pella Min Rule and Copy. Then append it to that same group in Set A. I’ll rearrange to make it rule 4.
10. The RPL Set Comparison tool hasn’t changed even though I am editing the set. The comparison tool uses copies of both sets so the originals aren’t affected. I must select the Recompute button to get the changes. As shown in Figure 2.13, I see that both sets have 12 rules in the SetOutflows group.
Figure 2.13   
11. Now I’ll update the function that was changed. I double-click the ExcessStorage function Body row to open both function editors.
12. I copy the entire expression from Set B and paste it over the expression from Set A. Now they are the same.
In this way, I’ve looked at the differences and decided which ones I want to apply to my set. Although I had to manually merge the two sets, the RPL Set Comparison Tool really helped me to identify where there are differences and then present those differences in an organized fashion.
Exporting and Importing RPL Sets
In this section we describe how to export all or a portion of a RPL set to a separate RPL set file, as well as how to import an existing RPL set file. The export and import mechanisms provide a way to incorporate all or some of one policy into another policy, and it is available for all application of RPL within RiverWare, including the following:
• Rule sets. Collections of rules and functions organized into policy and utility groups.
• Optimization goal sets. Collections of optimization goals and functions organized into policy and utility groups.
• The object-level accounting method set. A collection of methods and functions organized into predefined category groups and utility groups.
• The Expression Slot set. A collection of functions organized into utility groups. These functions may be called from an expression defining an expression slot.
• Initialization Rules. Collections of rules and functions organized into policy and utility groups.
• Iterative MRM RPL sets. Collections of rules and functions organized into policy and utility groups.
• Global Function Sets. Collections of functions organized into Global Utility Groups.
There are many situations in which export and import functionality is useful. For example, assume that you are writing a policy which could make use of some functions written as part of an existing policy. To avoid having to rewrite all these functions, you could open both sets and use the Copy/Paste mechanism to copy the functions in question from the existing policy to the new one. However, if you then modify the original functions, you might want to do the copy again to keep the functions identical, but you would have to first remove the copies of the functions before doing this. Furthermore, in the context of the object-level accounting method set it is not possible to have two such sets open simultaneously, so this mechanism would not work. The RPL set export and import functionality provides a simpler and more flexible method to implement sharing of policy elements. Alternatively, you could use Global Utility Groups; see “Global RPL Functions” for details.
Export
The RPL set export mechanism allows you to save a portion of a RPL set as a separate RPL set file. The first step is to show the Export column of the RPL set editor. If this column is not currently shown (between the columns labeled Priority and On), then it can be shown by selecting View, then Show Export Column. Initially no item is selected for export, this is indicated by a red X in the Export column for each item.
Select the Export column of the items that you would like to export. This will convert the red X in that cell to a green check mark.
Note:  Selecting a block or function for export automatically selects the containing group, and unselecting a group will clear all of its members.
Tip:  To select multiple items, right-click and choose Select Export For All in Group or Select Export For All in Set.
Once the items to be exported have been identified in this way, the export operation is initiated by selecting File, then Export Selected Items. You will then be presented with a confirmation dialog summarizing the items to be exported If you choose to continue the export operation, a file chooser dialog appears, allowing you to specify the file to which the items will be exported. Once a file name has been selected, the file is created and a RPL set containing only the selected export items is written to that file.
Import
RPL set import allows you to incorporate all or some aspects of an existing RPL set policy into a set that you are editing. To initiate an import, select File, then Import Set. You will be presented with a file chooser dialog for specifying the name of a RPL set file. Once you have selected a file and selected the Open button, you are presented with the RPL Import Confirmation Dialog.
This dialog presents a listing of the import set. This layout is similar to the RPL set editor’s presentation of the set, but each item being imported is classified as having one of the following statuses:
• New. The group, block, or function being imported does not appear to exist in the set into which it is being imported (the destination set).
• Existing. The group, block, or function being imported appears to exist in the set into which it is being imported (the destination set). In the case of a group, there is a group of the same type with the same name in the destination set. In the case of a block (or object-level accounting method), there is a block with the same name in a group which is of the same type and has the same name as the block parent group. Similarly, in the case of a function, there is a function with the same name in a group which is of the same type and has the same name as the function’s parent group.
• Can’t Import. The group, block, or function begin imported can not be imported. There are several reason why this might be the case and a warning is posted to the Diagnostic Output Dialog for each item that can not be imported, explaining the problem. Possibilities include an attempt to import a TCL function (not supported) or an attempt to import a function into a policy group when there is already an item of the same name in the global name space, e.g., a function of the same name exists in a utility group.
Before continuing with the import operation you should review the items being imported and indicate which items should in fact be imported. To select an item for import select the box to the left of its name in the list. Importing a new group will append it to the list of groups; importing a new function or block into an existing group will append it to the groups of functions which already exist. Importing an already existing group will copy its description to the existing group and copying an existing block or function will replace the existing block or function with the imported block or function. Initially new items are selected for import and existing items are not, but these selections can be modified. To complete the import select the Continue Import button. Selecting the Cancel button at any point will cancel the import operation and leave the RPL set unchanged.
Creating, Editing, and Viewing RPL Sets
This section describes the editor dialogs used to build RPL Rules, Functions, Goals, and other expressions. There are two ways to view the RPL editor dialogs, either in the RPL Viewer or in the single RPL Editor.
RPL Viewer and RPL Editor
When you open a function, rule, method, goal or any other block, the item will open as a new tab in the RPL Viewer. Opening subsequent RPL Items will add tabs to this RPL Viewer. This allows you to have one dialog where all RPL editors are shown. But, you can undock any item into its own RPL Editor. Figure 2.14 shows the RPL Viewer and the RPL Editor with the same rule shown. Notice the tabs in the viewer.
Figure 2.14   
Note:  The menu bar options will be the same. They are dynamically updated in the viewer based on the tab selected.
The RPL Viewer is the default dialog used to look at a RPL editor. It is convenient as all RPL editors open in the one dialog. Select the tabs to switch between items. Or use the RPL Editor List menu on the right of the tabs. This is particularly useful if you have many items in the viewer. Tooltips on the tabs give the full name and priority, or index, where relevant.
Arranging Tabs
Drag the tabs left and right to rearrange. Use the left and right arrows to scroll to tabs that are not shown.
Undocking RPL Editors
To look at two editors at once, drag the tab off of the viewer to create a RPL Editor dialog for that item. Or use the File, then Undock menu.
Redocking RPL Editors
To move a RPL Editor dialog back onto the viewer, grab the R, F, G, Icon and drag it anywhere onto the viewer. A new tab will be created. Or use the File, then Dock In RPL Viewer menu. Also, from the viewer, you can use the File, then Redock All to move all RPL Editors to the viewer.
Closing a RPL Editor tab
Use the red X on the tab to close a tab that is on the viewer.
Note:  The RPL Viewer is transient; once it is closed, the configuration of items shown and their order is not saved.
Working With RPL Dialogs
Whether you are looking at the editor or the viewer, the RPL dialogs consist of menus, name and buttons, the expression, and optional additional panels. Figure 2.15 illustrates, and these items are described in this section.
Figure 2.15   
• Type of Set. The icon indicates the type of set to which this editor belongs.
• Name. The name field is where you specify the name.
• External Documentation. The button, when configured, opens the external documentation; see “RPL External Documentation” for details.
• Close All. The button invokes a dialog in which you can close all open RPL dialogs except the top level editor.
• Set Button. Icon buttons allow you to show the containing set for each RPL dialog.
• Expression: This area contains the expression.
• Element Numbers: This column shows the first element shown on that line. See “Element Numbers” for details.
• Optional Information: Optional information can be shown for various types of RPL dialogs. These are described in the following sections. If there is an entry in these panels (or a non-default value) a box is drawn around the toggle.
Execution Constraint / Execute Block Only When
A block can be set up to execute only when a given condition is true. This functionality can be used to increase performance or it may be necessary to implement your RPL set correctly.
• From a RPL editor, select View, then Show Execution Constraints or select the Execution Constraint toggle.
An area is added to the bottom of the window. By default, the block executes only when TRUE. This means that the block will always execute when it comes up on the agenda. You may want this block to execute only when some other condition is true. The TRUE expression can be replaced with any logical structure that can be constructed from the palette
Note:  If you enter a boolean expression to replace the default TRUE, then clear this expression, an unspecified expression will remain. This unspecified expression will invalidate the rule. To prevent this, if you clear out this boolean, make sure you re-type TRUE to get the default behavior.
Descriptions
A special expanded area of the RPL dialog is used to enter a description of the block. The area is opened and closed by toggling the View, then Show Description in the menu bar or selecting the Description toggle at the bottom of the window.
Note:  If there is any description entered, the Description toggle will have bold text. Mouse over the word Description to see up to 140 characters of the description as a tooltip. Descriptions can be optionally included in Model Reports.
Description can be included in Model Report RPL items (RPL Group, RPL Rule/Goal, RPL Set) with the Show Descriptions settings. See “RPL Group” in Output Utilities and Data Visualization for details.
Notes
Notes, like Descriptions, can be entered in a panel at the bottom of the dialog. Notes can be used when you have information that you want to enter that doesn’t belong in the Description field. For example, development notes or change logs could be entered in the Notes panel.
The area is opened and closed by toggling View, then Show Notes in the menu bar or selecting the Notes toggle at the bottom of the window.
Note:  If there is any note entered, the Notes toggle will have bold text. Hover over the word Notes to see up to 140 characters of the note as a tool tip.
Notes can be included in Model Report RPL items (RPL Group, RPL Rule/Goal, RPL Set) with the Show Notes settings. See “RPL Group” in Output Utilities and Data Visualization for details.
Comments
Inline Comments are added from the palette using the Add Comment button. A separate dialog is opened that allows you to type in a comment. In the RPL editor, the comment is displayed with # characters on the left, lines are wrapped as they were in the comment editor dialog. Double-clicking the comment reopens the edit dialog.
Inline RPL comments can be optionally shown/hidden using the View, then Show Comments menu or the Comments toggle.
Note:  If there are any comments defined, the Comments toggle will have bold text. Also, Comments are shown by default; if you do not want to see them, you must explicitly hide them. Figure 2.16 illustrates.
Figure 2.16   
Executing DMIs From Blocks
RPL blocks can be used to execute DMIs or DMI groups. See “DMI User Interface” in Data Management Interface (DMI) for details.
To add a DMI, Select Rule/Method, then Add Pre-execution DMI or Rule/Method, then Add Post-execution DMI. Then, select the name of a DMI or DMI group that is defined in the model.
To remove a DMI, use the Rule/Method, then Remove Pre/Post-execution DMI menu.
A pre-execution DMI is executed as the first step of the execution, a post-execution DMI is executed as the last step of execution. Values imported by the pre-execution DMI are available for use by the statements. The order of execution for a rule is as follows:
1. If the Execution Constraint evaluates to TRUE, continue. Otherwise terminate the rule early.
2. Run the Pre-execution DMI.
3. Evaluate the body of the rule.
4. If the rule evaluation is successful, run the Post-execution DMI. If the rule is empty, terminates early, or is ineffective, the Post-execution DMI is not run.
To prevent unexpected solving of objects and/or conflicts between values, input DMIs executed from RPL blocks can only import values to unlinked series slots on data objects. Furthermore, values imported from a DMI executed from a RPL block are given the following flags:
• Control File-Executable DMIs. Imported values are given the INPUT (I) flag (priority zero).
• Database DMIs. Imported values are given the OUTPUT (O) flag and the priority of the rule executing the DMI.
An example application of this feature is executing an external water quality model at each timestep. In this example, the water quality model might take as input RiverWare values which reflect the current state of the system and return a recommended reservoir release value. At each timestep the block would first execute an output DMI to export current values from relevant RiverWare slot(s), e.g., inflow on a reach. An input DMI then runs the external water quality model (which reads the data from the output DMI) and then imports the resulting recommended reservoir release values.
Note:  You can turn on Diagnostics to see when rules and Rule DMIs execute. Use the Rule Execution and DMI, then Rule DMI diagnostic categories; see “Rulebased Simulation Diagnostic Groups” in Debugging and Analysis for details.
Stop On NaN
Typically, when a RPL block accesses a slot but the slot is NaN, the block terminates early but the run continues. Under certain conditions, you may wish to specify that a block does not terminate early but instead stops the run when a NaN is encountered. This could be useful for data checking rules; if the referenced slot value has not been specified, then you wish to stop the run and fix the data error.
To specify that a block should Stop On NaN, use the Block, then Stop On NaN menu. When enabled, a check mark is added next to the menu. Any time a slot expression accesses a NaN, the run will stop and a diagnostic will be posted that explains which block referenced a NaN.
Note:  In the context of initialization rules the run is not stopped immediately when an invalid value is encountered, but rather it is stopped only after all of the rules have executed. This allows RiverWare to report on all missing data with a single run.
Statements
Blocks are the upper-level construct of a RPL set. For example, rules and accounting methods are blocks. Blocks are made up of statements which are different structures depending on the desired result. See “Types of RPL Sets” for details
In the RPL set editor, open a block by double-clicking or right-clicking its icon. This will bring up the <block> Editor dialog. Rename the block by typing in a new name in the Name text field.
Blocks are constructed from statements at the top level, and statements are constructed from expressions. The following statements are available for RBS, Initialization and MRM rules and accounting methods. They can be selected from the Statement menu in the RPL Viewer or the individual rule or accounting method dialog.
Assignment
An assignment statement assigns to the slot on the left-hand side (LHS) of the equality the numeric value evaluated on the right-hand side (RHS) of the equality. The basic assignment is:
<numeric expr> = <numeric expr>
where the LHS <numeric expr> is a slot and the RHS <numeric expr> is any expression which evaluates to a value in the unit type of the LHS slot.
Note:  RBS rules, MRM rules, and accounting methods can assign values on series slots only. Initialization Rules can assign values on series slots, table slots, and scalar slots; see “Initialization Rules” in Solution Approaches for details.
For
Iterative loops can be very useful for computations and multiple assignments. For loops are available to make multiple slot assignments from similar logic and calculations. An index variable is assigned a new value for each iteration of the loop. The inside of the loop is one or more regular assignment statements which should use the index variable to perform a different assignments for each iteration of the loop. This variable may be used in both the LHS slot assignment and the RHS evaluation to affect slightly different behavior within each pass. The default For loop is:
FOR (NUMERIC index IN <list expr>) DO
<numeric expr> = <numeric expr>
END FOR
where the number of loops/assignments is determined by the number of elements in the <list expr>, the NUMERIC label indicates the expression data type of the elements in the <list expr>, and the index is the variable name which will take on the value of each element for use inside the loop. All of these parts of the for statement may be modified.
Note:  There is also a For expression on the palette; see “Conditional and Iterative Operations Buttons” for details.
With
A With statement evaluates an expression and sets the result to a local variable with the given name and type. It then evaluates the contained statements, which may reference the variable. The default WITH syntax is
WITH (NUMERIC val = <numeric expr>) DO
<numeric expr> = <numeric expr>
END WITH
Note:  There is also a WITH expression on the palette; see “Conditional and Iterative Operations Buttons” for details.
If
An If statement makes a statement conditional on a boolean expression without an ELSE.
IF(<boolean expr>) THEN
<statement>
END IF
Note:  There is also an IF expression on the palette; see “Conditional and Iterative Operations Buttons” for details.
If Else
An If Else statement makes a statement conditional on a boolean expression with an ELSE.
IF(<boolean expr>) THEN
<statement
ELSE
<statement>
END IF
Note:  There is also a IF ELSE expression on the palette; see “Conditional and Iterative Operations Buttons” for details.
Else If Branch
Although not a statement by itself, you can add one or more ELSE IF branches to an IF or IF ELSE statement. The ELSE IF is available when the boolean condition or a consequence statement is selected (except when an ELSE consequence statement is selected). An ELSE IF branch is added after the selected branch.
IF(<boolean expr>) THEN
<statement>
ELSE IF(<boolean expr>) THEN
<statement>
END IF
Note:  There is also a ELSE IF expression on the palette; see “Conditional and Iterative Operations Buttons” for details.
Else Branch
Although not a statement by itself, you can add a single ELSE branch to an IF Statement or ELSE IF statement. This part of the statement will be evaluated when none of the other IF or ELSE IF boolean conditions are true.
IF(<boolean expr>) THEN
<statement
ELSE
<statement>
END IF
Note:  There is also a ELSE expression on the palette; see “Conditional and Iterative Operations Buttons” for details.
Print
A Print statement evaluates its expression and formats the result into a message. The blue message is displayed in the Diagnostics Output Window only when the Print Statements diagnostics group is enabled.
Print <expr>
where the <expr> is any expression or concatenated expressions which can be fully evaluated and represented as a string. See “Print Statements” in Debugging and Analysis for details.
Notice
A Notice statement posts a purple message to the Diagnostics Output Window regardless of diagnostics settings.
NOTICE <expr>
where the <expr> is any expression or concatenated expressions which can be fully evaluated and represented as a string. See “Notice, Warning, and Alert Statements” in Debugging and Analysis for details.
Warning
A Warning statement posts a message with a pink background to the Diagnostics Output Window regardless of diagnostics settings.
WARNING <expr>
where the <expr> is any expression or concatenated expressions which can be fully evaluated and represented as a string. See “Notice, Warning, and Alert Statements” in Debugging and Analysis for details.
Alert
An Alert statement posts a message with an orange background to the Diagnostics Output Window regardless of diagnostics settings.
ALERT <expr>
where the <expr> is any expression or concatenated expressions which can be fully evaluated and represented as a string. See “Notice, Warning, and Alert Statements” in Debugging and Analysis for details.
Note:  The Notice, Warning and Alert statements all have the same behavior. They simply post messages with different colors. This allows you to define messages with three different levels of severity.
Stop Run
A Stop Run statement aborts the run and posts the provided message as a diagnostic error message in red text. When executed from within an iterative MRM rule, this statement aborts the MRM run.
STOP RUN <expr>
where the <expr> is any expression or concatenated expressions which can be fully evaluated and represented as a string. See “Stop Run Statements” in Debugging and Analysis for details.
Execute Script
Available for Iterative MRM Rules only, an Execute Script statement executes the named script.
Caution:  This statement should be used with extreme caution as scripts can modify many parts of your model.
EXECUTE SCRIPT <string expr>
where <string expr> is the name of the script to be executed. See “Script Management” in Automation Tools for details about scripts.
Editing a RPL Expression
Expressions in the RPL editor are displayed as <expr>, <numeric expr>, <boolean expr>, <list expr>, <string expr>, <object expr>, <slot expr> or <datetime expr>. The type of the expression indicates the valid values that can go in that expression. See “Expression Data Types” for details on each data type.
There are two ways to enter data into an unspecified expression, typing and using the palette. Any expression can by typed by first double-clicking then typing in the expression. There are many problems with this approach. First, you must know the exact syntax to be typed. Second, you must type all strings perfectly as typos in strings may not be caught on validation. A better approach is to use the palette to build expressions. You only need to type when they are specifying the inner most expression like exact numbers (100 cfs), boolean (true, false), datetimes (@“t”), or strings (“Entering Runoff season”). Following is a description of using the palette.
Using the Palette
See “RPL Palette” for descriptions of the Palette buttons. Each of the buttons in the RPL Palette represents an expression. These expressions are convenient operations which evaluate to one of the expression data types just mentioned. Buttons on the RPL Palette are enabled and disabled dynamically. When an expression is highlighted in the Editor, the Palette buttons that satisfy the expected data type are enabled. Thus, you create expressions in the following manner: select an unspecified expression, select a palette button or function. Select another unspecified expression and select a palette button or function. Repeat this process until the expression is created. Then, if necessary, double-click any remaining unspecified expressions that cannot be created from the palette (like entering numbers) and type in the value.
Entering Values
To replace an unspecified expression with a literal value (like 10 “cfs” or TRUE) double-click the expression and type in the value. For NUMERIC data types, you may also enter a unit. If the unit has a “-” or “/” in it, you must include the quotes when typing the unit, like “acre-feet”. Without these special characters, you can type the units and no quotes. Here are some examples of correctly specified units: 10 cms, 100 “acre-ft”, 50. Illegal entries include 100 acre-ft/day (no quotes) and 100 “cfx” (no unit of that type). See “NUMERIC” for details on entering units.
Another illegal entry is 1,000 “acre-ft”. This is because the comma (a thousands separator) is not allowed as an input. Instead, RiverWare gives the option of whether or not to display a comma as a thousands separator for all values throughout the model and RPL set. This option is selected or deselected by selecting the main Workspace, then Show Commas in Numbers option; see “Show Commas in Numbers” in User Interface for details.
Note:  After typing a literal value, you do not need to hit Enter to commit the change. Pressing Enter or any selection outside of the editor will signal completion of the editing.
Auto-Correct
When typing values, if the value you provide is not a valid replacement for the expression, RiverWare attempts to coerce the specified string into one that is valid. This auto-correction process is guided by the types which can legally replace the existing expression. RiverWare tries a series of variations on input, 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, SRING, and LIST. If a valid auto-correction is found, it is used to replace the existing expression; if no valid auto-correction is found, 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 a 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
Common values are also available by right-clicking the selected expression and choosing the Common Values menu. These include common DATETIME values and list expressions.
• @“t” - Current Timestep
• @“t-1” - Previous Timestep
• @“t+1” - Next Timestep
• @“Start Timestep” - First timestep in the run period
• @“Start Timestep - 1” - Initial timestep
• @“Finish Timestep” - Final Timestep in the run period
• { } - Empty list expression
• { <expr> } - List containing one empty expression.
Undo and Redo
When editing RPL expressions, undo and redo are available as follows:
• Edit menu on RPL dialogs
• Right-click context menu
• Keyboard shortcuts
– Undo is ctrl-z
– Redo is ctrl-shift-z
• Expression menu on Expression slots.
Any action that edits a RPL expressions can be undone or redone, including the following:
• Replacing the selected expression with a new expression by selecting a palette button
• Cutting or deleting the selected expression.
• Pasting an expression in the place of the selected expression.
• Adding or removing a statement from a block.
• Adding or removing a constraint from a function.
• Double-clicking an expression and changing it via an inline editor.
Undo and redo are on a per-dialog basis; the dialog must be selected before the undo/redo operation is performed. Also, the history of changes is preserved if a RPL dialog is closed and re-opened, but is not preserved if the set is closed. On expression slots, the history of changes is lost when the slot is closed.
The number of undos/redos is only limited to take you back to the original expression; there is no artificial limit imposed.
Finally, edits on the RPL set level cannot be undone including adding or deleting rules and re-arranging rule priorities.
Using the History
When you double-click an unspecified expression or literal value, a menu appears to the right of the inline editor. This menu tracks the history of past edits that have been used in this dialog you can then use the menu to choose a value from the list. The arrow keys can also be used to scroll through the list.
The history can also be used as a starting point if you type in an invalid expression. It provides an opportunity to correct the entry and try again without having to type it from scratch. For example, you wish to enter “Flood Season” into a string, but when you type, you only enter the string “Flood S” and hit Enter before finishing typing Season. RiverWare will not issue an error as “Flood S” is valid. You can then select “Flood S” from the pull-down history, and complete the desired text.
Note:  The saved history it is a per-dialog history only but does persist when the dialog is closed and reopened. It does not persist if the RPL set is closed.
Data Types for Looping Variables
In the looping expressions, FOR, WHILE, WITH, SUM, AVE and in the FOR and WITH statements, you specify the data type of the looping variable. See “Expression Data Types” for details on data types.
For example, the first line of a default FOR statement looks as follows:
FOR (NUMERIC val IN <list>) WITH NUMERIC result = <numeric> DO
You can change the type of the looping variable NUMERIC and the name of the variable. Menus provide an easy way to do this. You double-click the NUMERIC and are provided with a menu listing the 7 data types in RPL. A second menu is provided for the looping variable; this provides a history of all string values that have been previously entered in the dialog, similar to the history described in the previous section.
Renaming Looping Variables and Function Arguments
When a looping variable or function argument is selected, you can right-click and choose to Rename all of the occurrences of that variable or argument within the expression and the definition.
Note:  Variable names can be associated with statements (FOR and WITH), expressions (FOR, WITH, SUM and AVE), or functions (argument names).
To initiate a rename, use the right-click context menu and choose Rename. A dialog displays the number of occurrences of the name to be replaced, and allows you to type in the new name. Selecting Rename then makes the replacements.
In Figure 2.17, three occurrences of the looping variable reservoir will be renamed RES.
Figure 2.17   
RPL Short Cuts
If part of an expression can be used in another assignment, rule, or function, rather than repeating the above process for each new expression, highlight the portion of the expression that can be used elsewhere. From the menu bar, select Edit, then Copy or type <Ctrl C> to copy the highlighted portion. Right-clicking the highlighted portion will bring up a menu with the option to copy. In the location in which the expression is to be pasted, highlight the <expr> and select Edit, then Paste <Ctrl V>, or right-click and select Paste from the menu. This will paste the expression into the new location.
Also, expressions can be deleted using the Cut <Ctrl X> or Delete <delete> operations. The Cut operation, puts the expression in the copy buffer, the Delete operation does not.
Note:  There is one exception to the cut/delete behavior. When deleting an item in a list, the first cut or delete operation removes the expression but leaves a blank expression. A second cut/delete removes the item from the list. Figure 2.18 shows an example.
Figure 2.18   
Statements may be cut, copied, pasted from the menu bar of the RPL Editor, using <Ctrl C>, or right-clicking and selecting Copy from the menu. Select Paste to paste over an existing statement, Insert to add it above the currently selected statement, or Append to add below the last statement.
Disabling an Item in a List or a Statement
On the RPL set editor, functions and RPL blocks can be disabled by selecting the green check mark turning it into a red X. Within a block, it is also possible to disable an individual item in a list or an entire statement.
• In the RPL editor, highlight the statement or item in the list that you wish to disable.
• Right-click the selected expression. Notice that there is a check mark next to the word Enabled indicating that the item is enabled.
• Select Enabled to toggle off the check mark thereby disabling the item. The disabled variable now shows up with cross hatching. The crosshatch color is defined in the set layout dialog; see “Colors” for details. When the expression executes, it will skip the disabled item(s).
In general, disabling an assignment or an item in a list should only be used in the debugging and model building process. For example, you might want to have two assignment statements in one block. While debugging the model, it may be necessary to disable one assignment to ensure the other assignment is working correctly.
Open Slots and Objects From RPL Dialogs
When the selected RPL expressions is a valid OBJECT or SLOT, the following right-click context menu selections open that object or slot dialog.
• Open Object
• Open Slot
Note:  This only works for expressions for which the workspace object can be determined without evaluation.
RPL Search and Replace Dialog
The RPL search and replace dialog supports flexible replacement of strings within a single RPL set or all RPL sets. Within this dialog, you can search for all occurrences of a string and replace all or some of them with another string.
Accessing the Dialog
The RPL search and replace dialog is accessible in the following ways:
• From the main workspace, select Policy, then RPL Search and Replace
• Selecting Search and Replace from the Edit menu of the RPL editor and its children dialogs (the RPL Set, Function, and Rule/Method editors) or from the RPL Set analysis dialog.
• Pressing the F4 key from any of the RPL editors or the analysis dialog.
• Right-clicking when editing any RPL expression and selecting Search and Replace from the resulting popup menu.
Searching for Occurrences of a String
To search for occurrences of a string, begin by typing the search string into Search for: field and then either hit Enter or select the Search button.
When you initiate a search, the search string is added to a history of searches. To re-select a previous string, select the triangle just to the right of the search string. This will present a menu containing previous search strings, allowing you to select one as the current search string.
Exactly where and how a search is conducted can be controlled by selecting various options.
• Case sensitive. When checked, RiverWare searches for strings which match the search string exactly, otherwise it will ignore case.
• Look in Names. When checked, RiverWare tries to match occurrences of the string within the names of RPL items in the set. This includes the names of the RPL set and its contained groups, rules/methods, and functions.
• Look in Expressions. When checked, RiverWare tries to match occurrences of the string within all expressions in the RPL set. Eligible sub-expressions within an expression include values of type DATETIME, NUMERIC, BOOLEAN, STRING, OBJECT, and SLOT, as well as function calls (the name of the function being called is eligible for a match)
• Look in Descriptions. When checked, the contents of all descriptions (set, group, and rule/method) are searched for matching strings.
• Look in Notes. When checked, the contents of all notes (set, group, and rule/method) are searched for matching strings.
• Search in. If the dialog is accessed from the workspace Policy menu, it starts with All RPL Sets selected. Otherwise it will be configured to search in the RPL set corresponding to the dialog through which it was accessed. The name of the set selected will be displayed in a box to the right of the Search button. You may switch from this set to any other open set or to all sets by selecting the set name and choosing a new set (or all sets) from the menu.
Note:  When you search in the Expression Slot Functions Set (or All RPL Sets), the expression slot expressions (i.e. the RPL expressions shown on the expression slot dialog) are searched along with the functions in the Expression Slot Functions Set. In this case, the parent is the object containing the expression slot.
The results of the search are displayed in the Search results table which contains one row for each string that matches the search string. Each row displays the name of the item containing the string (a set, function, group, rule/method, or expression slot) as well as where within that item the matching string was found (the object name, description, or one of its expressions). In the case of a match within an expression, the actually matching sub expression is also displayed.
Note:  A search string can match multiple times within a given item. For example, when searching for the string “res”, a rule named “Forrest Reservoir Flood” will match twice.
Double-clicking a row of the Search results table will open an editor for the item containing the matching string corresponding to that row. If the match is within an expression, the matching sub-expression will be the selected expression in the editor and the dialog will be scrolled to that expression. Use the Previous Item and Next Item buttons to step through matches and opening/scrolling the dialog containing the match.
Tip:  If you want to change the name of a function argument or looping variable (within a FOR or WITH), select the variable and use the right-click Rename menu. This utility will rename all instances of that variable within the expression or function. See “Renaming Looping Variables and Function Arguments” for details on this utility.
Replacing Matching Strings With Another String
Once a search has been conducted, one can replace all or some of the matching strings with another string. First, type the replacement string into the field labeled Replace with:. To replace all of the occurrences then select the Replace All button. To replace only some of the matching strings, select those that you wish to replace in the Search results list (click selects a single row, Ctrl-click allows multiple independent selections, Shift-click selects a range of contiguous rows), then select the Replace Selected Occurrences button.
Functions
Following is a description of functions and their use in RPL sets.
Predefined Functions
Predefined functions are also useful in constructing rules, methods, and functions. Predefined functions are a set of mathematical, look-up, and mass balance routines that may be accessed from within any other expression. Predefined functions are coded into the RiverWare source code. Because of this, predefined functions cannot be modified. All predefined functions return their results in one of the standard data expression types; they can be substituted for any unspecified expression of that type. Predefined functions are accessed in the RPL Palette, “RPL Palette”, under the Predefined Functions tab at the top of the Palette dialog. Once added to a RPL expression, double-click the function to gets its editor. The documentation for the function is shown to help you specify the arguments and understand the evaluation.
See “RPL Predefined Functions” for details on the predefined functions.
Figure 2.19   
Writing a User-defined Function
Functions are constructed in much the same way that blocks are constructed, using the RPL Palette. Expressions are simplified by using functions to perform logical and computational operations. To make a function flexible so that it may be used in a variety of situations, arguments are added to the function. Arguments permit the same function to behave differently, depending on from where it is called or by which object. For example, an internal function could be created which forecasts the evaporation from a reservoir based on the reservoir’s surface area. This function could be of use at several reservoirs, but would have to know at which reservoir data to look. The reservoir for which the function should compute the evaporation could be an argument to the function.
Arguments to functions can be of any data expression type. There is no limit to the number of arguments a function may take, but the number of arguments is not dynamic with respect to block execution. The exact number and type of argument(s) is fixed in the function definition. Dynamic argument lists and default argument values are prohibited.
• Add a function to the desired Policy or Utility Group by selecting Set, then Add Function.
• Name the function and press <Enter> after naming.
Note:  If you are renaming a function that is called by other RPL expressions, a dialog asks if you want to rename calls to this function in the applicable RPL sets. Answering yes will update existing calls to the function with the new name. For the Expression Slot set, the Initialization Rules set, the Iterative MRM sets, the Object Level Accounting Method set, Optimization Goal sets, and Rulebased Simulation sets only function calls within the set are affected. For Global Function sets, calls in any of the above sets will be affected. Calls to a global function from DMIs, scripts, or other places outside of RPL sets are not renamed. Answering No continues the name edit but does not update any calls to the function. Answering Cancel stops the name change all together.
• In the field Return Type, select the data expression type you wish the function to return. For example, if NUMERIC is selected the function will return a numeric value to the block in which the function is called.
If the function is going to be general to other functions or blocks, adding an argument might be useful depending on the return type of the function. In the above graphic, the Arguments: OBJECT res allows the variable res to be used inside of the function anywhere an <object expr> is allowed. This will allow the function to look at different reservoirs’ data without creating a separate function for each reservoir. If the function is going to be used only in a limited manner, arguments are not necessary.
Arguments to functions can be entered in two ways, using the editor and by typing. The editor is accessed from the Arguments button to the right of the Arguments line as shown to the right: Initially, the dialog is blank. You add arguments by selecting the green check button. The red minus is used to remove arguments and the arrows are used to re-order arguments. The default type of an argument is NUMERIC. To change this, use the menu and select a different type. To change the name of the argument, double-click the name and type a new name. Select OK when finished. Figure 2.20 results in the argument shown below.
Figure 2.20   
Typing was the original way to enter arguments. You type into the Arguments line using the syntax TYPE argument. Multiple arguments are separated by commas. For example, NUMERIC flow, LIST elevations, OBJECT res. The syntax, spelling, and capitalization must be exact or an error will be issued.
Note:  To change the name of a function argument, select the argument in the expression and use the right-click Rename option. This utility will rename all instances of that argument within the function’s expression and definition. See “Renaming Looping Variables and Function Arguments” for details on this utility.
Functions are constructed like blocks and use the RPL Palette to build arguments. Figure 2.21 shows a sample function constructed using predefined functions and RPL Palette buttons.
Figure 2.21   
The same short cut copy and paste abilities seen in blocks apply to functions as well. Any time an expression is used multiple times, whether within a function or between functions, time can be saved by copying and pasting that expression into the other locations in which it is used. As with blocks, it is wise to check the validity of an individual function after it is built and fix it rather than wait until the beginning of a run to check the validity of all blocks and functions.
Constraints on Functions
Functions can be constrained to evaluate to either a minimum or maximum value. Or they can be configured to flag an error if a minimum or maximum constraint has been violated.
• From the Function Editor, Select View, then Show Post-Execution Checks or select the Post-Exec Checks toggle.
A constraint can be added using the Function menu item.
• Select Function, then Add Min Constraint or Add Max Constraint (as shown in the screenshot). The palette is then used to set up the conditions of the selected constraint.
Time Invariant Functions and Function Value Caching
The function editor Edit menu provides a toggle control labeled Set Time Varying which is set to on by default. Toggling this property 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. 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:  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.
Note:  Incorrect application of caching to a time varying function will lead to incorrect results, so we 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.
Note:  During block evaluation (e.g. within a rule or accounting method), 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 block. RPL does this automatically for all functions without arguments; multiple evaluations of such a function within the same block execution will cause the function to evaluate only once.
Selecting RPL Items
The RPL Item selector dialog is used whenever groups, rules, or functions (i.e. RPL items) are to be selected. For example, in diagnostics, you may select the rules for which you want to print messages.
Figure 2.22   
This dialog initially shows the groups and rules in a tree view. Also shown are the rule priority and rule status. In this dialog, you select the RPL items by selecting the boxes to add check marks next to one or more items. Depending on the context from which this dialog is called, you may be able to select one or many items. Items that have been previously selected for display are shown in grey and cannot be deselected. They can only be removed from the dialog from which this dialog was called.
Tip:  All items can be selected by right-clicking and choosing Select All.
You can also select the Filter check box to show a flattened list of the rules. Then you can sort by column heading or filter by entering a text string at the top. Use the green arrow to refresh, red X to clear the filter, and the Ignore Case check box to do a case insensitive filter. Select RPL items by checking the boxes as described above.
Developing Efficient RPL Expressions
RPL expressions are built using the Palette; see “RPL Palette” for details. Together with user and predefined functions, these provide all of the pieces necessary to create a simple or complex RPL expression; see “RPL Predefined Functions Reference” for details. Typically, an analysis of your RPL set performance is necessary to locate slow or inefficient items. See “RPL Analysis Tool” in Debugging and Analysis for details on the tools, particularly the RPL Analysis Tool.
Following are some suggestions to writing efficient RPL sets in terms of performance.
• Use predefined functions or operators when available. In general, always prefer a built-in operator or predefined function to a user-defined function (or complex expression) which performs the same computation.
• Move complex logic to user defined functions. This not only makes the logic more readable and easier to debug, but it makes performance analysis easier. This is because the RPL set analysis tool reports the times for function calls but not for other parts of expressions (i.e., the granularity of the performance information is per function).
• Use WITH expressions to avoid re-evaluating expensive expressions.
• Make sure there is no unnecessary LIST processing or STRING manipulation.
• OBJECT and SLOT representations of workspace objects and slots are generally more efficient than string representations of them. For example, the expression
GetSlot( (STRINGIFY reservoir) CONCAT “^” CONCAT account CONCAT “.Storage” )
probably takes significantly longer to evaluate (and is more complex) than
reservoir ^ ( account CONCAT “.Storage” )
• For a large model, it is computationally expensive to obtain a SLOT given the full slot name (i.e., a STRING representation of the slot) because RiverWare must first break the string into its components, then look for an object with the appropriate name. Once the object is found, then for accounting slots RiverWare must search through the accounts. Finally a search is conducted for a slot on the object/account with the given slot name. Thus when referencing slots, one should take special care to apply the suggestions mentioned above.
• Make sure that time consuming functions like FloodControl() or the hypothetical simulation functions are not being called more than necessary.
• Use functions with no arguments to cache values. If a function has no arguments, then the first time it is executed in a block (a rule, accounting method, optimization goal, initialization rule, MRM rule or expression slot), the return value is cached. For the remainder of the block execution, the function need not be evaluated again, the cached value is used. Thus, if you have multiple assignments within one rule that call the same argument-less function, the function will be evaluated once and the value will be used for all function calls.
• If you are sure that a function with no arguments is always going to return the same value regardless of the timestep, set the Set Time Varying toggle to be off. This will lead to the function’s first return value being reused throughout the run. See “Time Invariant Functions and Function Value Caching” for details.
• MAPLIST is an efficient expression which operates on a list and returns a list, but if one wants to operate on a list and compute a single value, FOR expressions (or a variation of FOR, like SUM or AVE) are more efficient. E.g.
Sum( MAPLIST (...))
is slower than
FOR ( ... ) SUM
...
END FOR
 
Example: Creating a New RBS Ruleset
This section presents an example of how to build a new Rulebased Simulation (RBS) ruleset. Similar actions can be used to build any of the other types of RPL sets.
1. Select Policy, then Ruleset, then New from the main menu bar. This will bring up a blank RPL Set Editor dialog.
2. Enter the desired Ruleset Name.
3. Save the ruleset to the desired directory by selecting File, then Save or File, then Save As from the menu bar of the Ruleset Editor dialog.
Adding Groups, Rules, and Functions
To begin the ruleset, use the following steps to add the desired number of policy groups and utility groups.
1. From the Set menu in the RPL Set Editor’s main menu bar, select either Add Policy Group or Add Utility Group.
2. Name the Policy or utility Group by double-clicking its icon to open the Policy Group Editor or Utility Group Editor and replace the default name at the top with the desired name.
Policy groups are used to organize rules and functions. Utility groups are used to organize functions. Although an entire set can be created entirely within a single policy group, it is not recommended. Rules should be split up into different policy groups according to object, geography of the model, operation type, and/or priority of operations. Supporting functions which are common to several rules should be placed in utility groups. Functions within a policy group are only available to rules and functions within that policy group.
Use the following steps to add a rule or function.
1. Select the Policy or Utility Group so that it is highlighted.
2. From the Set menu, select Add Rule or Add Function.
To view the elements in the policy or utility group, select the tree-view triangle left of the group name.
Unspecified expressions are portions of the rule that have not yet been set when building a rule. These expressions are represented as the expression data type.
To add an Assignment, from the Statement menu, select Add Assignment.
Expressions are built using the RPL Palette. The RPL Palette contains most of the expression elements needed to build a block, including logical operators, slot and object access expressions, flow operators, list operators, predefined and user made functions. See “RPL Palette” for details. Depending on the data type of the expression highlighted in a block, the RPL Palette only enables buttons for expressions of that data type. See “Expression Data Types” for details on the data types.
To open the RPL Palette, select Rule, then Palette from the menu bar of the Rule Editor dialog.
Use the following steps to finish building the rule.
1. Highlight the left <numeric expr>. This will be the slot to which the rule will assign a value.
2. In the Objects/Slots section of the RPL Palette, select the Slot[] button. This replaces the unspecified numeric expression with a series slot expression.
The square braces following a slot expression refer to the timestep or the row and column of the slot. There are three slot expression possibilities:
– Slot [ E ] A series slot at the timestep indicated by E.
– Slot [ E, E ] A table slot at the row and column indicated by E and E, respectively. Table slot column references are zero based, i.e. the first column is referred to as column 0.
– Slot [ ] A series slot at the current controller timestep or a scalar slot value
3. Highlight the unspecified portion of the series slot expression, <expr>, and select the Slot Selector button in the Objects/Slots section of the RPL Palette. This will bring up the slot selector dialog.
4. In the Single Slot Selector, select the appropriate Object Type, Object, and Slot. Then select OK.
5. Finish building the rule by building the right-hand side of the rule. The RHS should return a numeric value and units that are to be set on the slot specified on the left-hand side.
Initialization Rules Set
Initialization Rules are a set of RPL rules associated with the model which can be executed as part of run initialization to set up data for the run. Initialization Rules provide a complement to user inputs and execution of DMIs.
Unlike other rules which can only set series slots, initialization rules can be used to set Table Slots and Scalar Slots.
This section describes the applicability and use of Initialization Rules. See “RPL Sets” for details on the user interface for Initialization Rules and other RPL sets.
Applicability (When to Use Initialization Rules)
Each method for providing data to a simulation is suited to different modeling scenarios. For situations in which there are a small number of inputs that don’t change frequently, interactive setting of input values is often the simplest approach. However, when this process would be time-consuming or error-prone, it is preferable to automate the setting of user inputs. Input DMIs provide a flexible way of accomplishing this by providing mechanisms for communication between RiverWare and external programs (usually databases). If there is computational logic involved in this process, e.g., if the data need to be massaged to remove outliers, then this logic must somehow be embedded in the external DMI program. On the other hand, using initialization rules to accomplish the same task allows this logic to be viewed and edited from within RiverWare, often improving the clarity and ease of maintenance of the model.
Initialization Rules also differ from DMIs in that in the context of a RBS simulation, they can be used to provide default values which the policy can then override. To illustrate a scenario in which this might be useful, consider a run in which some quantity is generally assumed to be zero, but which can take on non-zero values under some conditions. One strategy for modeling this situation is to set the relevant values to zero using low priority rules with execution constraints that cause them to execute only on the first timestep. Alternatively, Initialization Rules accomplish this same behavior with less user effort (no execution constraints are necessary) and with the additional advantage that these rules are organized separately from the policy (if there is one). In fact, most RBS rules which are constrained to execute only on the first timestep are likely to be more appropriately included with the Initialization Rules.
Another important distinction between Initialization Rules and policy (rules) is that the former are executed before data checking at the beginning of the run. Thus, Initialization Rules can be used to set values such as initial Storage or Pool Elevation on a reservoir, whereas RBS rules execute only after data checking and so could not be used to give these slots reasonable values. Further, unlike other rules which can only set series slots, initialization rules can be used to set table and scalar slots.
How to Use Initialization Rules
This topic describes how to use initialization rules.
How do I access the Initialization Rule Set?
From the workspace, use the Policy, then Initialization Rules RPL Set menu.
Where are they saved?
The set is saved in the model file. The Initialization Rules Set Editor dialog does have a File, then Save Initialization Rules Set As menu item to save the initialization rules to a file. A File, then Replace Initialization Rules Set from File menu item allows the initialization rules set to be replaced by the contents of a specified file. These menu items allow an initialization rules set to be moved between models via a file. However there is only a single instance of initialization rules in a model and this set is still saved and loaded with the model file
When are they executed?
The rules are executed during the initialization phase of all Simulation and Rulebased simulation runs (including accounting) after values are cleared and inputs are registered but before beginning of run checks on all objects. See “Simulation Controller” in Solution Approaches for details on the ordering for simulation; see “Simulation/Rules Interaction” in Solution Approaches for rulebased simulation; see “How the Accounting System Solves” in Accounting for accounting.
In what order are they executed?
The Initialization Rules are executed in Index order based on the specified Agenda Order. To see the order, select View, then Show Advanced Properties.
What do Initialization Rules set?
Initialization rules can set series slots, table slots, and scalar slots. For series slots, the current timestep is the start timestep. For table slots, specify the rows and columns using labels or a zero based index. For Scalar slots, use the Object.ScalarSlot[ ] syntax on the left side of the assignment statement.
Do Initialization rules re-execute when dependent slots change?
No, initialization rules execute once and do not re-execute even if dependencies change.
Do Initialization Rules have Individual Priorities.
No, the Initialization rules are organized by Index as shown on the RPL set editor.
What Flag/Priority are the values given?
Series values set by Initialization Rules are given one of the following flags/priorities as configured through the Set Value Flag menu on each Initialization Rule:
• Rule (R). Set the value with the R flag. In RBS, all values set this way are given a very low priority (It is a very large number) and the letters IR are shown indicating the Initialization Rule priority. R flagged values set by Initialization rules can be overwritten like other R flagged values.
• DMI Input (Z). Set the value with the Z flag and give it a priority of zero (0) (in RBS). When simulating, this flag behaves identically to the INPUT (I) flag.
Note:  An Initialization Rule setting a value with the Z flag can overwrite an I or Z flagged value.
Note:  The values set by initialization rules are given the priority as described above. If these values are propagated or provide enough information for an object to dispatch, any subsequent values set will be given the controller priority, which would be zero (0) if they solve before any rules execute.
Note:  Table and Scalar slot values set by initialization rules are not give a priority or a flag. Choosing the R or Z flag from the menu shown above results in identical behavior for these types of slots.
Can I disable the Initialization Rules?
When the Initialization Rules set contains at least one rule and the current controller has the possibility of executing the Initialization Rules, then the Run Control Dialog displays a check box labeled Execute Initialization Rules, which controls whether or not to execute the Initialization runs during the initialization phase of runs. Clear this checkbox to disable the Initialization Rules.
How do I know which Initialization rule set a slot value?
Tooltips on the series slot values display which Initialization Rule (or RBS rule or DMI) set that value. See the screenshot to the right. See “Series Slots” in User Interface for details on these tooltips.To open that rule, right-click and choose Open Init Rule #.
How do I debug Initialization Rules?
The RPL debugger can be used with Initialization Rules. Also, the following diagnostic categories in the Rulebased Simulation and Simulation settings dialog control diagnostics for the Initialization Rules:
• Init. Rules Print Statements
• Init. Rules Rule Execution
• Init. Rules Function Execution
See “Types of RPL Debugging and Analysis” in Debugging and Analysis for details on debugging and analysis of RPL sets.
Global RPL Functions
Global functions allow you to define a function in one location and then use it in any of the RPL applications including Rulesets, Optimization Goal Sets, Object Level Accounting Method Set, Initialization Rules, MRM Rules, and RPL Expressions Slots.
Global RPL Functions exist within Global Functions Sets, organized in Global Utility Groups. Multiple Global Function Sets can be opened within a RiverWare session.
A RPL set is considered global when it is opened as a Global Set and any RPL Set file can be loaded as a Global Function RPL Set. Only the RPL Set’s Utility Groups—and not its Policy Groups—are relevant in Global Function Sets.
Global RPL Functions can be called from RPL Functions and Rules (and other forms of RPL Blocks) in any open RPL Set. Global Functions can call other Global Functions, either in the same Global Function Set, or a different Global Function Set.
Creating a New Global RPL Function Set
A new Global RPL Function Set can be created from the RiverWare Workspace menu, with the following menu selection:
 Policy, then Global Function Set, then New
This opens up a Global Function Set editor. This is a RPL Set Editor for Global Function Sets, distinguished with a green globe icon in the upper-left area of the editor dialog.
As with all RPL Sets, a Global Utility Group must first be added before new user-defined RPL Functions can be defined. In a Global RPL Function Set, this is done from the RPL Set Editor’s menu item, as follows:
Set, then Add Global Utility Group
Any function added to the new Global Utility Group is, by definition, a Global Function. A Global Function can be created in any of the following ways (not illustrated):
• From the RPL Set editor, with the desired Global Utility Group selected, using the Set, then Add Global Function (Ctrl+F) menu item.
• From the RPL Set editor, using the Context menu (right-click) on the desired Global Utility Group item, Add, then Global Function.
• From the Global Utility Group Editor, using the Group, then Add Global Function (Ctrl+F) menu item.
• From the Global Utility Group Editor, using the Context Menu (right-click) anywhere within the function list, Add, then Global Function.
• By Copying a Function from another RPL Group or RPL Set, and Appending into the Global Utility Group, using Context Menu operations.
• By Dragging a Function from another RPL Group or RPL Set into the Global Utility Group.
Note:  The Drag-and-drop functionality currently implemented in the RPL Set and RPL Group editors has some limitations, including the availability of that operation only if the target function list already has at least one function.
• By importing Utility Groups from a RPL Set file. This is done from the RPL Set editor, File, then Import Set menu item.
Only one instance of a function can occur within all loaded RPL sets and Global Function Sets. For example, you cannot have a function named GetMinimumFlow in a utility group in your ruleset and another named GetMinimumFlow in an open Global Function Set. An error will occur in this case.
Opening an Existing Global Function Set
The RiverWare Workspace Policy menu supports the opening of a RPL Set as a Global Function Set in ways similar to opening other RPL Set files.
Figure 2.23   
Any RPL Set file can be loaded as a Global Function Set, however only the Utility Groups within the RPL Sets loaded as Global Function RPL Sets are usable; rules (or other forms of RPL Blocks) within the set’s Policy Groups are not. If a RPL Set file containing Policy Groups is opened as a Global Function Set, the warning dialog shown in Figure 2.24 appears, and a similar warning message is written to the RiverWare diagnostics output.
Figure 2.24   
Note:  It is important to open any Global Function Sets before trying to load a ruleset that uses functions in a global set.
Using Global RPL Functions
When editing a RPL Expression, any Global Function in any open Global RPL Set can be called. The standard way of adding a call to any user defined function is with the RPL Palette User-Defined Functions tab.
Within the User-Defined Function list, global functions are indicated with one of two globe icons:
• White globe. Indicates an external Global Function i.e. a global function in a RPL Set other than the set containing the RPL expression being edited.
• Green globe. Indicates a local Global Function i.e. a global function within the same RPL Set as the one containing the RPL expression being edited.
During evaluation of a Global RPL Function, the specific behavior is consistent with the caller’s RPL Application. For example, “@t” (the current timestep) represents the Rulebased Simulation Controller’s current timestep when the function is called from an Rule. But when called from a Series Slot with RPL Expression, “@t” (current timestep) represents a particular series timestep date/time.
RPL Printing and Formatting
Blocks written in the RiverWare Policy Language can be complex, and with lengthy verbose object, slot, and function names, blocks can have very long lengths. RiverWare provides a mechanism to print blocks and dynamically format blocks to fit the width of desktop window or a printer page.
Printing
Rules and user defined accounting methods written in the RiverWare Policy Language can now be printed. A Printing dialog is available at each editor level from the File, then Print X menu. This provides you with the means to print an individual block from the Editor, an individual function from the Function Editor, an individual group from the Group Editor, or the entire RPL Set from the RPL Set Editor.
Using the print dialog, the block, function, group, or RPL set can be sent directly to the printer or to a file. You may select landscape or portrait printing. You may choose to include or exclude inactive items, descriptions, execution constraints, and value constraints. You may also choose the print font. A note on font selection. The font selection dialog presents a list of fonts that are available on computer console, these fonts may or may not all be available on the printer. If the font is not available on the printer, a default font will be chosen by the printer and the printout may be misaligned—formatting will be corrupted. Some experimentation may be necessary to determine which fonts an individual printer supports.
Formatting—Display Settings
Expressions written in the RiverWare Policy Language can be complex and very long. RiverWare provides a RPL Display Settings dialog to control the fonts, colors, showing element numbers, and a dynamic formatting algorithm. This algorithm formats the blocks to fit the width of desktop window or a printer’s page. The dialog is accessed through the Display Settings button in the editor Set menu. These settings will be automatically saved in the model file. This allows RPL logic to look the same from one user to the next.
Display settings may be imported and exported to/from a file through the File menu. Following are the options:
• Import File. Import the settings from a file that was exported from a RiverWare session.
• Export File. Export all of the settings to a file.
• Save as User Defaults. Export the settings as user settings that are stored in the machine’s registry. These settings will be used for new models.
• Load User Defaults. Load the settings from the user settings defined in the machine registry. This allows you to override a model’s settings with your personal settings.
• Load RiverWare Default Colors. Load the RiverWare default colors. This allows you to get back to the base starting colors.
• Load RiverWare Default Line Breaks. Load the RiverWare default line breaks. This allows you to get back to the base line breaks.
There are three areas to this Display Settings dialog, Font, Colors, Line Breaks, and Element Numbers, shown in Figure 2.25 and described in the following sections.
Figure 2.25   
Font
The fonts used in RPL expressions can be changed by selecting the More button, then select the desired font, style, size, and effects.
Colors
The colors used in RPL set editors can be changed to fit your needs. You are able to specify the colors for items shown in Table 2.7. To change, select the More button, , then select the desired color from the color chooser.
 
Table 2.7   
Item
Description
Background
The background color for statements and other areas (except expressions) that are not contained within the current selection.
Default Foreground
The color used to draw items in expressions or statements whose color is not governed by another color setting. For the current selection, this color is used for all items; outside of the current selection, this color is used to draw mathematical symbols, operators, and delimiters.
Note: The selected expression’s foreground text is either white or black (dynamically computed) to contrast with the configured background color.
Expressions
The color for key words in expressions.
Expressions Background
The color used for the background of the bounding rectangle for expressions.
Types, Names, & Values
The color of types (e.g., NUMERIC), names of variables, and literal values.
Comments
The color of in-line comments.
User-Defined Functions
The names of user-defined functions.
Predefined Functions
The names of predefined functions.
Disabled Functions
The names of user-defined functions which are disabled (i.e., functions for which the red X appears in the On column of the functions RPL Set and Group editors).
Disabled Objects (Crosshatch)
The color of the crosshatching superimposed on disabled statements or expressions.
Selection Background
The background color for statements and expressions that are contained within the current selection.
Line Breaks
The formatting algorithm is designed to provide you with control over the formatting process. The formatting algorithm is a multi-pass algorithm. Each pass will attempt to find a position in the block where a line break can be placed to fit the block to the device width. The algorithm will cease, once the block can be rendered in the desired width, or no more positions where the block is allowed to be broken exist. You can define, through the RPL Display Settings dialog, the tokens (i.e., block positions) a line break can appear before or after, the indentation following the line break, and the priority (the pass) at which the line break should be inserted. Line breaks with a priority of zero will always be broken, while the maximum value will indicate that a line break at the token should never occur. Figure 2.26 illustrates.
Figure 2.26   
A block is formatted using the following algorithm:
1. The formatting algorithm makes an initial pass, breaking the block at priority 0 tokens. All line break defined with priority 0 (i.e., Always) in the RPL Display Settings dialog will be formatted in this initial pass. This pass always occurs.
2. Next the formatting algorithm checks the length of block. If the block will fit in the width of device, the formatting terminates. If the block will not fit the width of the device, the priority is incremented, and line breaks are made at all tokens defined with priority 1.
3. Repeat step 2 through all priorities until the block fits in the device.
If the block exceeds the screen width after all line break positions have been exhausted, the window will be made scrollable. If the block exceeds the printer’s page width after all line break positions have been exhausted, the excess will be printed on adjacent pages.
To edit any number in the dialog, select the number and then type in a new value. You can enter either “Always” or “0” for very high priority values. Enter “Never” or a large number (greater than about 40) for those items with low priority.
Example 2.1   
Given the following line break settings
 
Token
Break Before
Break After
Priority
THEN
no
yes
Always (0)
END IF
yes
yes
Always (0)
+
yes
no
1
AND
yes
no
2
The block being fitted to the box
Notice that with this naive algorithm, had the object slot names been small, they would have still been broken at the “+” symbol, since, the “+” had a higher priority (1) than the AND and the block did not yet fit the box.
Element Numbers
RPL Expressions can be long and it is sometimes hard to tell where you are within the RPL expression. To help with this, you can show RPL Element Numbers along the left hand side of the RPL frame. Notice in Figure 2.27, the column of numbers from 1 to 33.
Figure 2.27   
Element numbers are shown for the statements and expressions with which rules and functions are composed. As a result, they are neither continuous nor a constant increment, but are reflective of the number of elements on that line.
One can think of these like line numbers, but they are not line numbers as lines associated with a rule/goal/function vary with the formatting, which is adjusted to reflect the RPL display settings and the width of the display.
The display of Element Numbers is controlled by a check box in the Set/Rule/Function/Goal, then RPL Display Settings dialog. When display of the element numbers is enabled, a new column is shown along the left side of each RPL frame which displays, for each line, the number of the lowest numbered token beginning on that line.
In addition, when this feature is enabled and there is a selection in a RPL frame, the right-click context menu displays the Element Number of the selected element.
 
Revised: 06/03/2019