When building and executing RPL policy, there are three situations when debugging and analysis is required:

Within this section is an overview of each situation. Then, in the remainder of the document, are the tools that can be used for debugging including the RPL Debugger, Diagnostics, Run Analysis, and RPL Analysis.

There are several errors (non-evaluation errors) which may be encountered when building or validating RPL sets. These messages do not immediately affect a model run, but will likely result in a run failure if not addressed. Messages may appear in the Diagnostics Output Window or in an error notification window which appears at the time of the error.

When an unspecified expression is filled in by entering text into its text field, the entry is parsed to ensure that it meets the requirements of the desired type. If the entry is not valid, a diagnostic message is generated. For example, entering @“t” into an unspecified <numeric expr> would generate the following message shown in Figure 4.1 and revert the expression to its prior, unspecified, state.

Another kind of parsing error can occur when the correct expression data type is improperly entered. For example, typing @“Octobre” into an unspecified <datetime expr> would generate the message shown in Figure 4.2 and revert the expression to its prior, unspecified, state.

In both of these cases, the entered expression was incorrect. Examination of the expression and the diagnostics message should point out the flaw.

RPL sets are validated at several stages prior to a run. Validation ensures that a RPL set meets a minimum level of accuracy for its intended use. There are different levels of validity required for different stages of RPL set opening, editing, and running. The validity levels are as follows.

Given those definitions for the various results of validating a RPL set, the following actions can lead to validation errors.

When a RPL set is opened, its functions and blocks are parsed from the file and the set is validated to the printable level. The printable validation ensures that the RPL set can be displayed in the RPL set editor’s graphical user interface. RPL sets are also validated to the same level when they are saved to ensure that they can be reloaded at a later time. Some older RPL sets which contain critical errors, and corrupted RPL set files may fail to load. In these cases, the window shown in Figure 4.3 appears, indicating the location within the file where the error was detected.

A message will also appear in the Diagnostics Output Window indicating that the “RPL set loading failed” and provide the path and name of the RPL set. The Diagnostics Output Window will display the line number in which the parsing error occurred. If this should occur, first verify that the file you are attempting to load is indeed a RPL set, then contact RiverWare technical support.

When a RPL set is loaded by selecting the RPL Set Not Loaded button in the RPL set editor or Check Validity is selected from the RPL set menu, the RPL set is validated to the evaluatable level. This means that all of the rule and function expressions are syntactically correct, have consistent expression data types, are fully specified, and reference objects and slots which exist on the workspace. If any of these criteria are not met, the RPL set is not validated and it cannot be loaded into the model. In this case, a window appears indicating one of the two messages shown in Figure 4.4.

Another message appears in the Diagnostics Output Window describing the validation errors. Loaded RPL sets are also validated to the evaluatable level when a run is begun. This is to validate any changes which were made to the RPL set since it was successfully loaded. If any errors are detected, the run is stopped, and the appropriate diagnostic messages are displayed.

Several types of errors can be generated when evaluating RPL expressions. Some errors stop the run execution immediately, while others cause the current block to end with an early termination, but do not stop the run. The approach to debugging these errors varies depending on the error type. The error types are:

These are errors which occur within the evaluation of a rule. Most often, these errors are produced when an engineering predefined function fails because it is attempting to model something physically impossible. These errors are often the result of the object state; i.e., the values in the object’s slots. It is entirely possible for an engineering predefined function to fail during one rule evaluation, then succeed during another. The result of the engineering predefined function is almost always related to the state of the object at the time that the function evaluates.

For example, attempting to solve for the ending elevation of a reservoir given a starting elevation and flows which would cause overtopping of the reservoir would generate this kind of error. Some predefined functions can also fail in this way if they are attempting to access missing data or attempting to access data with incorrect arguments. Attempting to lookup values which do not exist in a tableslot would also generate a non-fatal evaluation error.

When the Rule Processor encounters a non-fatal rule evaluation error, it cannot continue evaluating the rule and must terminate early. Since the rule does not complete, no slots are set in the model. All existing slot values and priorities are still correct, and it is not necessary to stop the run.

When a non-fatal evaluation error is encountered, the error message is posted to the Diagnostics Output Window and immediately aborts the RPL statement. The block’s dependencies are preserved, such that the block may be re-evaluated if any of its dependent slots change.

Non-fatal RPL evaluation errors do not always indicate a problem with a RPL set. Although a red error message is displayed in the Diagnostics Output Window, the failure of the RPL expression may be a desired action. This may initially confuse users who are accustomed to seeing error messages only when the run has been aborted. Error messages which are generated for non-fatal rule evaluation errors are intended to give the modeler an indication of the failed functions even though the evaluation continues. These error messages should be investigated to determine whether the function failure really was desired.

When examining non-fatal error messages, keep in mind that the failing function does not know whether its failure is critical or not. In a simulation dispatching context, a failed Elevation Volume Table interpolation is critical because it means the physical limit of the reservoir has been exceeded. In a rule evaluation context, a failed Elevation Volume Table interpolation is not very critical because it only means that a what-if calculation has exceeded the physical limit. In both cases, the table interpolation error is posted as soon as it is encountered. In the simulation dispatch case, the controller should immediately stop the run. In the rule evaluation case, the Rule Processor only needs to abort this rule and can then fire the next rule on the agenda.

Fatal RPL evaluation errors immediately abort execution. Unlike non-fatal RPL evaluation errors, these errors indicate a major problem with the RPL logic. These errors also occur within the evaluation of a RPL logic. Unlike non-fatal RPL evaluation errors, however, these errors are not dependent on the state of the system; they cannot be fixed by having different values in slots. These errors may be caused by missing arguments, arguments of the wrong data type, inconsistent unit types, invalid slot configurations, and/or missing objects and slots. These errors require intervention by the user if the run is ever to succeed. When the Rule Processor encounters a fatal rule evaluation error, the rule is aborted, the error message is posted to the Diagnostics Output Window, and the run is immediately stopped.

The number of arguments and data types of arguments to predefined functions are fixed. Each function checks the validity of its arguments when it is evaluated. The argument requirements for each predefined function are listed in RPL Predefined Functions section of the RiverWare help. If incorrect arguments are supplied to a predefined function, or the function fails to evaluate for other reasons, it may cause a fatal error. In this case, a message is posted in the Diagnostics Output Window and the run is immediately aborted.

The RPL processor automatically converts numeric values to the proper units for mathematical operations during RPL evaluation. As long as the unit type of a value is correct, its units can be converted without affecting the expression. If the dimensional analysis is incorrect, however, the RPL processor stops the run.

RPL unit type errors are only detected during evaluation.

RPL requires that an expression evaluating to a particular data type be present where that data type is expected. This is enforced during the building of RPL expressions by only enabling expressions of the correct type in the Palette and by generating a parse error if an incorrect expression is directly typed into the text field. The error message, previously discussed, would read, “The entered expression cannot replace the selected expression”.

Expressions of data type LIST are not verified during the building of RPL expressions. This is because a list may contain elements of any data type and because the number and type of list elements may change during the evaluation. As a result, inconsistent data types originating in lists will not be caught until the RPL expression or function is evaluated. These errors will stop evaluation immediately with an error.

If an object or slot which is referenced in a RPL expression does not exist on the workspace when the RPL expression is evaluated, a fatal RPL evaluation is produced. This can occur when the slot or object name was improperly entered in the RPL expression, when a RPL set is being used with the wrong model, or when object or data object slot names were changed after the RPL expression was created.

Names of objects and slots in a RPL set must exactly match an object and/or slot name on the workspace, including capitalization, spaces, and any underscores. Missing object or slot errors can be minimized by always using the Object Selector and Slot Selector to specify objects and slots in RPL expressions. Typing object or slot names directly into an expression textfield is not recommended due to the possibility of a syntax error.

These errors occur during the dispatching phase of a Rulebased Simulation run and only apply to Rulebased Simulation rulesets. These errors are produced when the controller priority and the priorities of slot values are such that objects cannot solve the model. These errors are usually caused by objects dispatching with an unintended dispatch method, excessive redispatching of an object, and/or an overdetermined multislot. When these occur, the Rulebased Simulation Controller cannot determine how to continue, and the run is aborted with an error.

Fatal Simulation errors are often the most complex errors to understand and debug. These errors occur during the simulation dispatching which takes place after a rule successfully sets a slot value. In order to simulate the effects of the new slot value, many objects may need to redispatch. The dispatch method with which each object redispatches is determined from the object’s slot priorities. Occasionally, the priorities of the slots are such that a unique dispatch method cannot be identified. When this happens, the object will attempt to redispatch with the same method as it dispatched with the last time. One of two error situations may result.

If the slot which was just set by a rule is solved for during this dispatch, the slot priority conflict will cause the run to abort with an error. The error often indicates:

Attempting to set senior slot (priority) with a junior priority (same priority).

Assignment attempted within the dispatch triggered by rule #same priority.

The object probably did not dispatch with the intended method.

When this error occurs, the rule at the indicated priority is usually to blame. Often, this rule has set a slot value at a priority which confuses the simulation into choosing the wrong dispatch method.

Another error situation which can result from incorrect dispatching is an infinite loop. This can occur between two objects which are both solving for the same slot. Each object successfully solves for a new value on the slot, overwriting the previous value. Each new slot assignment triggers the other object to redispatch, during which it also solves for a new value on the slot. This continues until the maximum iterations are reached on one of the objects’ slots or the modeler terminates the RiverWare session.

Slot maximum iteration checking is turned on by default and cannot be turned off when performing Rulebased Simulation, though the number of maximum iterations can be changed by the user. This iteration default can be viewed as a dimmed box for Check Iterations in the Rulebased Simulation Run Parameters dialog. From the View menu of the Run Control dialog, select Rulebased Simulation Run Parameters... to open the dialog. Within this dialog, the user can change the number of maximum iterations (the default number of maximum iterations is 40). For more complex models, the user may be required to increase the number of maximum iterations.

These errors occur when a rule is fired too many times within any timestep. Rules may not be evaluated more than the Maximum Rule Executions Per Timestep specified in the Rulebased Simulation Run Parameters dialog. The default maximum executions is 50. From the View menu of the Run Control dialog, select Rulebased Simulation Run Parameters... to open the dialog to change this value. A rule firing more than 50 times is usually an indicator of a circularity in the rule logic. Excessive rule firing and redispatching is an indication of a circularity in the ruleset design; one or more rules are dependent on the slots which they are setting. Even in the most complex rulesets, individual rules should not fire more than a few times in any given timestep. Unchecked, circularities would continue indefinitely, or until the user terminates the executable. But, when a rule is fired more than the maximum executions, the Rulebased Simulation Controller stops the run and posts this error to the Diagnostics Output Window, “Max rule executions exceeded for timestep.” Luckily, these types of circularities are rare.

RiverWare provides the following tools for helping the user to understand RPL evaluation and its consequences in rules, goals, methods, and expression slots:

With these tools it is possible to examine RPL behavior and make changes if that behavior is deemed to be unintended. For complex policies this process of policy debugging can be very time consuming. This document describes Debugging and the RPL Set Analysis Tool and provides links to documentation on diagnostics and the model run analysis tool.

RPL sets can be very large and complicated, and consequently it can be difficult to determine why a set is doing what it is doing. The RPL debugger is designed to help understand the behavior of RPL sets; with this tool the user can pause RPL execution, look at the values of RPL expressions as they are evaluated, and step through RPL execution. The following sections describe the RPL debugger including an overview, how to enable debugging, a tour of the debugger dialog, and suggested ways of using the debugger.

The RPL Debugger utility provides the following functionality:

RPL is used in several contexts within RiverWare; currently they are:

Except for this last application (Expression slots), RPL policy is organized at the RPL group level into functions and blocks of RPL statements, variously called rules, goals, or methods. Statements can be nested and contain expressions, which might contain function calls. Expression slots and functions are defined by a single RPL expression.

Thus, for blocks of statements, the basic unit of execution in RPL is the statement; whereas, for functions and expression slots, it is the single defining expression.

This RPL policy organization is reflected in the locations at which execution can be paused:

When execution is paused, the debugger allows the user to view the values to which expressions have evaluated up to that point. Each time a block of statements or an expression slot is executed, results from any previous evaluations are cleared, so one must pause after a statement’s execution to see the values to which its expressions last evaluated.

To enable this feature, use one of the following approaches:

This is a workspace-level toggle and applies to the execution of all RPL policy associated with the current model. This setting is saved with the model.

When debugging is first enabled, a button is added to the Run Control dialog to indicate the state of the RPL Debugger. Select the button to select or clear the state. Shift-Click the button to open the RPL Debugger. This button remains in place for that RiverWare session. To hide the button, use the View, then Show RPL Debugging button.

There are two distinct performance impacts of debugging:

Since both of these impacts can be significant, by default RiverWare does not enable these processes. Rather the user only incurs the additional overhead of debugging when they have indicated that they would like interactive debugging as described above.

See “RPL Debugger Scenario 1” for a scenario in which the user might want to disable and then enable debugging temporarily.

The RPL Debugger dialog is accessible as follows:

This dialog displays information about RPL execution and allows the user to control RPL execution. Figure 4.6 shows the principle components of this dialog.

Table 4.1 describes the functionality available through the File and Breakpoints menus. See “Control Toolbar and Debug Menu” for details about Debug menu.

In addition to the existing mechanisms for controlling a run (e.g., the pause button of the run control dialog), through the debugger the user can control RPL execution. Table 4.2 describes the button controls in the control toolbar and Debug menu of the Debugger dialog.

The control toolbar can be repositioned within the dialog or detached and displayed outside of the dialog. By default, the buttons are unlabeled, but text labels can be displayed by selecting Debug, then Show Button Labels. All of the control actions are also available via the Debug menu or by keyboard shortcuts. For the most part, the shortcuts are the same as those used by Microsoft Visual Studio for the comparable action.

When RPL execution is paused in the debugger, the Call Stack panel describes the current execution location. The display is a treeview list of the items which have are currently executing. Double-clicking an item in a row in this list opens the associated editor. For each item in the call chain, its Caller, Group, and Set are listed. For functions, the argument types, names, and values are displayed as optionally displayed children of that row. Figure 4.7 illustrates.

The Breakpoints panel lists locations at which the user has requested that execution regularly pause. Double-clicking a row opens the editor for that item. For each breakpoint, the panel displays the following:

The list may be sorted based on any column; initially it is sorted based on the name of the item containing the breakpoint. Also the columns may be rearranged by dragging the column label.

Breakpoints can be created and deleted within the RPL editor for the corresponding item; see “Sample Use Scenarios” for details. Within the RPL Debugger dialog, they can be deleted and/or temporarily disabled/enabled using the Breakpoints menu. Also, selecting the stop sign indicator will enable/disable the breakpoint. Breakpoints are persistent (saved with the RPL item which contains the breakpoint).

When paused or after a run, the Value of Selected Expression panel displays the value of the selected RPL expression. See “Displaying Data Values” for details.

The Run Status panel at the bottom of the debugger shows the overall status of the run. This information is also shown on the Run Control / Run Status dialog. The panel in the debugger provides easy access to the current controller timestep.

Following is a description of how to use the RPL Debugger. In general, the approach is: add breakpoints, start execution, execute to the breakpoint and pause, investigate values at that breakpoint, continue or step to the next location of interest, and continue looking at values and stepping/continue until satisfied. The process becomes more complicated when you wish to investigate the values at one timestep or location within a long run. See “Sample Use Scenarios” for a description of this scenario.

As discussed earlier, RPL execution can be paused at the following locations:

Setting a breakpoint at a particular location will cause execution to pause each time that location is reached. When debugging is enabled, RPL dialogs displaying a location at which RPL execution might pause (rule, function and expression slot dialogs) display a margin on the left in which debugging indicators are drawn. RPL frames in which it is not possible to pause RPL execution (e.g., rule execution constraint frames) never show a margin for debugging indicators.

Selecting the margin adds a breakpoint (break before) at that location if there is not one already; disables it if there is an enabled one, and deletes it if there is a disabled breakpoint. That is, selecting the margin cycles through three states, enabled, disabled, and deleted. If the select location is below the statement or functions, then a break after breakpoint is added at that location.

Breakpoints may also be added/removed from the selected expression using the Rule/Methods/Goal(block), then Break Before/After Execution menu actions. When a RPL expression is selected, it is only possible to add a break point before that selection. In this case, RiverWare adds the breakpoint before the statement (assignment, if, ForEach, etc.) containing the selection. Otherwise, for the entire block, Break Before applies to the first statement and Break After applies to the last statement. The Break Before/After Execution menu items of the RPL editor dialogs are enabled and toggled based upon the RPL selection and contents of the dialog (as well as whether or not debugging is enabled).

If there is a breakpoint associated with a given location, a solid red octagon is drawn in the debugging margin (unfilled red octagon for disabled breakpoints). For blocks, the breakpoint indicator is associated with a specific statement or appears just below the last statement (indicating a breakpoint which is activated after the last statement has executed). Figure 4.8 illustrates.

For functions, the breakpoint indicator appears in the function editor and appears at the top of the expression body for a before execution breakpoint and just below the body for an after execution breakpoint. Figure 4.9 illustrates.

To start the debugger, initiate execution in the standard way depending on the set to be debugged. That is:

The RPL execution will begin and the RPL debugger will pause when it hits a breakpoint or is paused.

When RPL execution is paused in the debugger, the user can interact with most RiverWare dialogs to examine the current state of the system. The values of interest during a run are the values to which expressions (including sub-expressions, i.e., expressions within expressions) have evaluated, as well as the values assigned by assignment statements. In many debuggers, the user enters the variable for which they want to see the value. Since RPL expressions are not named, the user can not pick an expression for display by entering its name or by selecting it in a list of expression names; rather the most straightforward method is to select the expression in the RPL editor in which it is displayed. Once selected, there are two ways to look at the value of the selected RPL expression:

The value displayed uses the settings in the Unit Schemes; see “Unit Schemes” in User Interface for details. Whenever a RPL value is displayed in the debugger or in tooltips, RiverWare uses the units defined in the scheme. But, for monthly and annual values, it is sometimes not known within the debugger for which timestep the value is associated. In that case, monthly values assume there are 31days in the month. Annual values assume 365 days in the year.

Once paused, the user can investigate the values of expressions and then continue on to other breakpoints, step, step into, step out, or continue to selection. These actions are available on the RPL debugger toolbar, menu choices, and keyboard accelerators; see “Control Toolbar and Debug Menu” for details.

Also remember that within a run, there are two types of stepping and pausing:

For example, within a rulebased simulation run, you select Step on the Run Control to advance the timestep, use the RPL debugger to break in a rule, step through that rule in the RPL debugger and then select Continue on the RPL debugger. The timestep then finishes and the Run Control will pause before the next timestep.

There are a few limitations that are imposed by the debugger:

If an error occurs during RPL evaluation with debugging enabled, the user is presented with an informational dialog and execution is paused in the debugger. The RPL editor containing the location of the error is raised and the debugging cursor indicates the location of the error. This could be one of the following:

RPL execution is paused as soon as the error occurs, and an informational dialog is presented to the user. This happens even before an error has been posted to diagnostics, however all of the relevant information concerning the error is displayed within the debugging dialog:

In this section we present a few example scenarios that illustrate different ways to make use of the RPL debugger.

The Run Control dialog allows user to specify a timestep/goal at which to pause the run. This is useful for longer model runs when you wish to look at execution on a specific timestep. The following is a possible debugging scenario:

Because the debugger catches RPL errors and displays the exact location of the error, it can be used in the RPL development process to catch run time errors. For example, when running a model where you just made a lot of RPL changes and you wish to catch runtime errors, use the following steps.

When intermediate information is required to debug a RPL execution error, Diagnostics can be used. Following are links to the Diagnostics section to describe how to set up these diagnostics for various sets.

Whenever a RPL value is displayed in the diagnostics or in tooltips, RiverWare tries to use the values from the Unit Scheme, Unit Type Rule. See “Unit Schemes” in User Interface for details. For monthly and annual values, however, it is sometimes not known within the diagnostics for which timestep the value is associated. In that case, monthly values assume there are 31days in the month. Annual values assume 365days in the year.

Some diagnostics groups are more useful in debugging errors than others. The diagnostics groups are listed below, ordered from the most frequently used to the least frequently used. This text was written for debugging Rulebased Simulation rulesets but can be applied to many of the other RPL sets as well.

The Rulebased Simulation Analysis Dialog is a great tool for identifying the source of fatal runtime errors. The Rulebased Simulation Analysis Dialog provides a snapshot of the last known state of the objects at each timestep. Its detail dialog shows the priorities of each dispatching slot and the last dispatch method used. This information can be used to identify priority conflicts which are the source of many errors.

See “Rulebased Simulation” for a description of the rulebased simulation Model Run Analysis tool.

The RPL analysis tool assists the user in analyzing and documenting a RPL set. For this section, items refers to rules, groups, assignments, statements, predefined functions and user defined functions. In particular, this dialog displays two general types of information on items in the RPL set:

This information is useful for a number of common user tasks.

The RPL Analysis Dialog is available for each of the RPL sets in RiverWare including rulesets, object level accounting method sets, expression slot RPL sets, iterative MRM rulesets, and RPL based optimization sets. In this document, a block refers to the upper level expression for each of these sets and will be used in all descriptions. A block is analogous to such items as a rule, method, or expression slot assignment.

The RPL analysis dialog allows the user to examine a wide range of information about any of the items in the RPL set. The user can customize the information that is displayed for all the items in the dialog. Among the list of information to possibly display (from the Window, then Columns menu) is: name, description, active, return-type, num arguments, argument list, item-type, priority, out-degree, in-degree, time, evaluation, and orphan.

In addition to the set, groups, functions, and blocks, the dialog provides access to other items. This is useful for examining performance information and relationships amongst predefined functions, blocks, and functions.

The dialog also displays RPL statement items inside rules or blocks, such as assignments, for-each statements, and print statements. These statements are assigned names based on the left-hand-side of the statement, such as “ASSIGN TO Reservoir.Inflow[]”.

The complete list of items which can be displayed or filtered (from the Window, then Objects menu) is: sets, groups, blocks (rules), print statements, statements, user functions, and predefined functions.

The second major component of the RPL analysis dialog is its three expandable treeviews. These treeviews display different relationships between items in the RPL set. These are all static relationships, i.e. relationships based on the definition of the RPL set not based on any specific model run.

By default these treeviews are linked, so that selecting an item in one of the treeviews selects and scrolls to this object in the other two views. Thus, the three treeviews can be thought of as different views on the same focused object. The user can quickly examine the selected object from the different perspectives of these three treeviews:

The descending and ascending views both provide views onto the static call graph of the entire RPL set. By selecting an item in either of these views, the user can examine the entire portion of the call graph containing the selected item; the descending view shows the call graph below the item and the ascending view shows the call graph above the item.

The RPL Analysis Tool is automatically enabled for all RPL sets to view the relationship amongst items in the RPL set.

The RPL Analysis dialog can be opened from any of the RPL editor dialogs. Each editor dialog has a menu item for Analysis (i.e. depending on the type of RPL set, the menu is called Ruleset, Set, Methods, etc). For example, from the ruleset:

When the RPL analysis dialog is opened from a RPL editor, the editor’s item will be the currently selected item, e.g. opening the RPL analysis dialog from a function editor will force the function to be the currently selected item in the analysis dialog.

The RPL analysis dialog can also be opened using the key-command Ctrl+Y on Windows.

As the three listviews provide different views on the same set of RPL items, it is often helpful to switch between these different views during a session. As long as the Window, then Sync Views is active by default), the three listviews will focus on the same selected item in all three views.

The user can switch between views by selecting the desired tab: Groups, Descending, or Ascending. In addition, the View menu provides menu items and key-commands for rapidly switching between views: View, then Groups View or Ctrl+G, View, then Descending View or Ctrl+D, View, then Ascending View or Ctrl+A.

The listviews provide several ways of navigating up and down.

As with many other listviews in RiverWare, each listview can be sorted by a specific column. Selecting the column header in either the Descending or Ascending view will sort the top-level items by that column. An arrow next to the column’s name indicates the sorting column and the direction.

Sorting can be useful to quickly group together common items, such as all orphans (sort by Orphans column) or the most computationally expensive items (sort by Time). To eliminate confusion, the classic Groups view only allows sorting by priority number.

The user can quickly navigate to an item by typing in the name in the Search toolbar. This toolbar is activated by right-clicking the main menu bar and selecting Search Toolbar.

The search will stop on the next item that contains the entire search string. It is not required that the item name exactly match the search string, only that the name contains the search string.

The Search text box will preserve all the typed search text strings. These past searches can be accessed by selecting the drop down arrow next to the text box.

A search is initiated by pressing the Find Next button. By pressing the arrow to the right of the button, the user can select an ascending or descending order. The button will honor the last search order.

Pressing a letter on the keyboard will navigate to the next item that begins with the given letter; see “Navigating Within a Treeview” for details.

It is often useful to examine the RPL editor dialog for an item. An editor dialog can be opened several ways:

For cases when the user is opening a large number of editor dialogs, the Window, then Replace Existing Editor option can be useful. With this option enabled, each new editor dialog opened will close the previous editor dialog so only a single editor is visible at one time. This eliminates the need to close each editor before opening a new one to eliminate screen clutter.

The RPL analysis dialog has been designed to be user-customizable. With a few menu selections, the user can show only the items and information that is useful for the given task.

As shown in Figure 4.12, the dialog can display a large amount of information. For most tasks, however, only a subset of that information is useful. The Window menu allows the user to quickly specify which types of items and information to display in the current views.

All user settings are saved with the user’s RiverWare preferences file. So settings made in the current session will be preserved for future RiverWare sessions run from the same login, regardless of the model or RPL set loaded.

The Window, then Columns menu contains a list of all available columns.

A newly activated column will be placed at the right-side of all the listviews. The order of columns can be modified by dragging the column’s header at the top of the listview to a different location in the header. The same size, position, and set of columns is displayed in all three listviews.

The Window, then Objects menu contains a list of all available items. Selecting an item-type will show/hide all items of this type. Hiding a container item such as a set or group, does not hide its children.

A major goal of the RPL analysis dialog is to support documentation of RPL sets. To assist with documentation, the user is able to print or export to a tab-delimited file for importing into a third-party tool such as Excel.

Both printing and export generate output for the currently visible treeview. The user can generate output of the entire treeview or just the selected portion of the treeview. In both cases, the output will contain only the expanded rows in the treeview. If a row is not expanded in the treeview, its children will not be expanded in the output. In both cases, only the currently selected columns will be included in the output.

File, then Print, then All and File, then Export, then All generates an output of all the expanded rows in the currently visible treeview.

File, then Print, then Selected and File, then Export, then Selected generates an output of the currently selected rows in the currently visible treeview. Rows can be selected by: dragging a set of rows using the left-mouse button, adding a set of items by holding down the Shift key, or adding or removing specific rows by holding down the Ctrl key.

In addition to the customizations for columns and item types, several other behaviors can be customized by the user. As with all customizations, these settings are saved as part of the user’s RiverWare preferences which are recalled with each new RiverWare session.