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 or show the button, use the View, then Show RPL Debugging button. Once shown, you can use this button to enable/disable the debugger.

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.

When RPL execution pauses at a breakpoint, the associated row in the Breakpoints Panel is scrolled into view. While execution is paused at a breakpoint, the breakpoint indicator contains a yellow arrow (the debug cursor) .

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, 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, a yellow arrow called the debug cursor , is shown in the RPL dialog margin to the left of the statement or expression at which execution is paused. Typically this indicates that the indicated statement/expression is just about to be evaluated.

When RPL execution is paused in the debugger, you 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 set by assignment statements. Select the expression in the RPL editor. Once selected, there are two ways to look at the value of the selected RPL expression:

Within the RPL Debugger, Value of Selected Expression panel, most values are displayed as a single value, as shown above. Lists are different as they can contain multiple items and can be very long. Instead, lists are shown in a tree view:

This display shows the levels of the list. Collapsing the list at any level shows the containing list on a single line. For example, this list shows the three sub lists collapsed.

Click the icon to show the list as a flat view. For example:

The icon returns it to a tree view.

The icon pops out the display into a resizable dialog showing the tree view. This is particularly handy for large lists as you can make the dialog box much larger.

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:

The only action possible through the debugger when the run has been aborted is to continue execution, which will post the error diagnostic and abort the run as usual.

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.