Diagnostics are a powerful and helpful feature which provide you with the ability to gather useful messages during the course of a run or while building a model. User-selected diagnostic messages are displayed in the Diagnostics Output Window where Error and Warning messages also appear. Diagnostics may be filtered according to their context or turned off altogether. Errors and Warnings may not. Unlike Errors or Warnings, the Diagnostics Output Window will not be forced to the front by diagnostics. It is up to you to open the window.

Following is a quick guide to using diagnostics.

See RPL Debugging and Analysis for details on debugging RPL logic using diagnostics or other tools.

The Diagnostics Manager is used to enable informational diagnostics. Informational diagnostics are any messages which, although helpful in debugging, are not indicators of problems which would stop a modeling run. Informational diagnostics should not be confused with RiverWare warnings and errors. Whereas informational diagnostics may be filtered by context and turned off altogether, warnings and errors may not. Warnings and errors are always displayed in the Diagnostics Output window, and errors always force this window to come to the front of other open windows.

The diagnostics Manager can be accessed as follows:

RiverWare is initially started with the diagnostic capability disabled primarily for efficiency. Posting, filtering, and outputting unnecessary diagnostic messages may take up a significant portion of the run time. This should be kept in mind when activating diagnostic categories and filters. An excessive amount of diagnostic messages produced at run time may considerably slow down the execution.

Use the following steps to enable informational diagnostics.

Diagnostics are divided into categories which appear in the upper portion of the Diagnostics Manager. Each category is a button which opens up the Diagnostics Configuration dialog for that category:

The first three categories are associated with the controllers of the same name. Accounting diagnostics are enabled only if the Accounting is enabled. For Simulation and Rulebased Simulation, diagnostic messages are generated and filtered during a run according to the settings specified for the currently active controller only. The Workspace category, however, is independent of the current controller. It is active before and after a model run. For example, diagnostics for expression slots that are configured to execute at the end of a timestep must be set up in either the Simulation or Rulebased Simulation category. Diagnostics for expression slots that are evaluated manually must be configured from the Workspace category.

The Diagnostics Output Window will always open and come to the front whenever an error message is posted. This includes messages from RPL Stop Run statements and expressions, which are handled as error messages. The Diagnostics Manager also provides the option to automatically open the Diagnostics Output Window and bring it to the front for messages posted from RPL Notice, RPL Warning, and RPL Alert statements and expressions (see RPL Statements in RiverWare Policy Language (RPL) for information on these statement types). Select the checkbox for each statement type if you want it to automatically raise the Diagnostics Output Window. The default is that these items are not selected, and thus, these messages will not automatically raise the Diagnostics Output Window.

Once you have configured the diagnostics settings, these settings can be saved to a file and loaded at a later time. This allows you to configure and save various combinations of diagnostics configurations and context filters. Settings are loaded and saved by selecting File, then Load Settings or File, then Save Settings in the Diagnostics Manager dialog.

Each of the diagnostics configuration dialogs contains a group of diagnostics to enable or disable, and a set of context filters. The available groups are shown below the title “Show diagnostics for” in the upper left section of the dialog window. Each of these diagnostics groups can be toggled on or off by selecting the checkbox located to the left of the group name. Multiple groups can be turned on at once. Some diagnostics groups are only visible by toggling a tree view triangle.

The mechanism which allows you to narrow down the number of diagnostics that will appear is called context. The various contexts are: object, slot, timestep, and rule. Not all of these contexts are valid for every configurations dialog. For example, generating diagnostics about the dispatching of objects is independent of any Slot context. The Simulation Diagnostics Configuration dialog only allows filtering of messages by Object, Slot, and/or Timestep. Selecting a limited set of a particular context, restricts diagnostic generation to that set. For instance, the <ALL OBJECTS> value within the Show O diagnostics for field means that object-related diagnostics will be generated for every object that exists on the RiverWare workspace. If, however, a limited set of objects is listed within the field, then object-related diagnostics will only be generated for that select set of objects.

For any average size model, enabling this many diagnostics is dangerous. The time spent posting, processing, and displaying diagnostic messages may “freeze” model execution. For a small model, the effect is limited to a noticeable slowdown. In general, diagnostics should never be enabled without considerable context filtering. See Context Filtering for proper use of context filtering.

Following is a description of the Diagnostics Groups and the Context filtering available in the Diagnostics Manager.

A diagnostics group is a category of diagnostic messages that pertain to similar events within a run. They include such things as object dispatching information, rules firing information, rules agenda information, slot value information, etc. A complete list of the types of messages issued by each diagnostics group is presented in subsequent sections.

Figure 3.1 shows the Diagnostic Configuration dialog. Diagnostics groups are selected in the upper left portion of the dialog, in the window below the “Show diagnostics for” label. The diagnostics groups are turned on by selecting the checkbox to the left of the group name. When a diagnostics group is enabled, a check mark is shown to the left of the group’s name.

Some of the items in the list are actually groups of diagnostics groups. These super-groups are purely for organization and generate no diagnostics. The subgroups within a super-group may be viewed by selecting the tree-view plus or arrow symbol to the left of the name. This action will be shown in this manual as Super-Group, then Sub-Group. When any of the diagnostic subgroups in a super-group are enabled, a check mark is shown to the left of the super-group name, in addition to the check mark to the left of each sub-group name. Any number of diagnostics groups may be enabled at the same time. When you select a Super-Group check mark, it uses a tri-state: All On, All off, previous sub-group selection.

Every diagnostic message is generated within a specific context. Contexts are details about the source of a diagnostic message. The contexts for a message may include the Object, Slot, Timestep, and/or Rule within which it originated.

All messages which are part of the same diagnostics group will have the same types of contexts. The contexts which are part of each diagnostics group are indicated by a symbol(s) to the right of the diagnostics group name. Following are the icons representing each context type.

Each of the icons contains a letter abbreviation of the type of context, O for object, S for slot, T for timestep, R for rule, A for account, and G for optimization goal. Not all Diagnostics Configuration dialogs contain the same contexts. Table 3.1 summarizes the contexts available to all of the Diagnostics Configuration dialogs.

Exactly how many icons are displayed depends on the Diagnostics Configuration dialog invoked, as indicated in the table above.

Context filters are important for reducing the number of messages produced by a diagnostics group. Context filters allow you to specify the only sources from which a diagnostic message will be displayed. Any messages originating from a different source are ignored.

Most diagnostic groups are affected by context(s). To the right of every diagnostic group listed in the Show diagnostics for field, there are zero or more context icons indicating whether or not those particular types of diagnostics are generated within the depicted context types. For example, the posting of diagnostic group Dispatch Management, then Slot messages is affected by the Slot and Timestep context. Both the Slot and Timestep context icons appear to the right of the listed diagnostic group. In this way, you can determine whether selecting a limited set of items within a context type will affect the frequency of messages of a particular diagnostic group. Choosing a limited set of slot names, for example, only affects the frequency of diagnostics groups depicting the slot context icon S.

The summary context icons above the diagnostic group list box indicate whether or not diagnostic groups affected by the specific context are turned on. If none of the diagnostic groups are turned on, then diagnostics are not generated from any of the existing contexts. As a result, each of the summary context icons above the list box is turned OFF, and each has a red line through it. As soon as a single diagnostic group is turned ON and is related to a specific context, the corresponding summary context icon is turned ON (the red line is removed.)

These three menu options are available within each of the diagnostics configuration dialogs, depending on whether or not they exist in the specific Configuration dialog. Each of these options can be applied to diagnostics groups, the object list, the slot list, the rule list, and the timestep text fields.

The Diagnostics Output Window displays the diagnostics during a RiverWare run. Error and Warning messages are also displayed in this window, regardless of user settings, and automatically force the window to the top of any other windows. The object and timestep for which a message is generated are listed under the Context bar. The message containing the diagnostic information is listed under the Diagnostic Message bar on the same line. When the Auto Scroll checkbox is selected, the window will continually scroll down as messages are output. In a large model where many diagnostics are generated, the continuous scrolling can add significantly to the run time. In these cases, Auto Scroll can be disabled by clearing the checkbox.

You can scroll vertically and horizontally in both the context and message fields. In addition to scrolling in the fields, you may wish to resize the entire Diagnostics Output Window. This is useful when many long messages and/or contexts need to be read. To move the divider between the fields, position the mouse over the space between the heading bars, press the left mouse button, and drag the divider to the desired width.

Long diagnostic messages are shown as a wrapped tooltip when you hover over a message.

If you wish to read a diagnostic in a wrapped window, right-click the line of text and choose Show Message in Popup Window.

This opens a dialog that shows the full diagnostics text, including the context, in a wrapped window. If you highlight the name of an Object, Slot, Account, RPL item (Set, Group, Rule, Function), you can select the Open Selected Named Item menu to open the corresponding dialog.

The same right-click context menus listed in the bullets above are available in this dialog too. The keyboard accelerators Ctrl-A for Select All and Ctrl-C for Copy are also available on the text in the dialog.

There are two approaches used to find messages: Search and Filter. Search to look for a specific text string row by row. Filter to show all rows that match the text string. (You can also search on filtered results) The two approaches share the text entry field. Following are descriptions of the controls and options:

The Search controls include: the following:

Filtering allows you to show only those lines that match the specified text. The Filter controls include the following buttons:

The only direct indication that messages are being filtered is the Clear Filter (red “X”) button being enabled and discontinuous line numbers in the message list.

When applying or clearing a filter, the view is re-scrolled to the currently selected item (when that item remains non-hidden). So, it is possible to use filtering to locate a diagnostic message (and select that message), and then view that message in the context of all generated messages by turning filtering off.

Enter your desired search/filter text pattern in the text box. This is an editable “combo box” to support a history of recently applied patterns, as shown in Figure 3.5.

When typing in the entry field, hitting Enter is equivalent to selecting Search Forward, and pressing Shift-Enter is equivalent to selecting Search Backward.

The following options apply to both the Search and Filter functions.

A given message line matches the pattern if the line text contains the pattern. (This is different from the pattern matching the entire line of text). Application of the pattern match concatenates the “context” and “message” parts of the message row, rather than independently looking into those two parts. This makes possible, for example, a wildcarded expression which matches pieces from both the context and message parts of the message line, as follows:

The following is the definition for wild card pattern matching (i.e. not RegEx):

Regular Expression (“RegEx”, “regex” or “regexp”) pattern syntax is an advanced, potentially complex pattern matching format developed originally with Unix-based tools. It’s not described further in this document but is widely referenced online.

The File menu includes the following selections:

The Edit menu the following selections:

The Settings menu includes the following selections: