The importance of diagnostics in debugging Rulebased Simulation models cannot be overstated. Diagnostics allow the user to examine rule firing, rule success/failure, slot assignments, and dispatching in the chronological order in which these events take place. It is the only way to verify that the intended interaction between rules and object dispatching is being carried out exactly as expected. Becoming familiar with configuring and reading diagnostics will save you hours and hours of speculation when your model does not behave the way you planned. See RPL Debugging and Analysis for details on debugging Rules and other RPL logic using diagnostics. See Types of RPL Debugging and Analysis for a general discussion on debugging RPL logic.

The Rulebased Simulation Diagnostics Configuration dialog allows you to select from fifteen diagnostics groups and four context filters which are relevant during a Rulebased Simulation run. This dialog’s settings are only valid when the Rulebased Simulation controller is selected. It is accessed from the Rulebased Simulation button on the Diagnostics Manager.

Table 3.3 summarizes the types of messages that are displayed when a Diagnostic Group is selected.

In the Rulebased Simulation Diagnostics Configuration, you are able to select rules for which you wish to see diagnostics. This is done by selecting the Select button from the Show Rules Diagnostics for: section. If you have both a RBS ruleset and a non-empty Initialization ruleset, you must choose from which set’s rules you would like to choose. The Rule Selector then opens. See RPL Printing and Formatting in RiverWare Policy Language (RPL) for details on using this dialog.

Also, all rules can be added from the Rulebased Simulation Diagnostics Configuration, Select All, then Rules menu. Selecting OK confirms and closes the dialog or selecting Cancel, cancel the selection.

There are six ways to post a user-generated message to the Diagnostics Output Window from within RPL:

For all six of these statements or expression types, you can define the message that is displayed in the diagnostics output. The unspecified <expr> of the statement or expression can be any concatenation of the different RPL expression types. All of the elements in the expression are interpreted as strings and formatted into the message.

A Print statement can be added to any rule or goal as a top level statement. From the Statement menu in the rule or goal, select Add Print. In order for the message to appear in the Diagnostics Output Window, you must enable Informational Diagnostics in the Diagnostics Manager, and you must enable the Print Statements diagnostics group in the Rulebased Simulation or Optimization Diagnostics Configuration and select the appropriate rules or goals for which to display diagnostics. Print statements are shown in the Diagnostics Output Window as blue text.

Notice, Warning, and Alert messages post messages with different colors; see Figure 3.8. The three statement types allow you to post messages with different levels of severity. You can post messages of any of the three types as either statements or expressions.

Unlike Print statements, Notice, Warning, and Alert messages are always shown in the Diagnostic Output Window, regardless of diagnostics settings.

A Notice, Warning, or Alert statement can be added to any rule or goal as a top level statement. From the Statement menu in the rule or goal, select Add Notice, Add Warning or Add Alert menu

A Notice, Warning, or Alert expression is added from the RPL palette as shown in Figure 3.9.

The first argument of the operator becomes the content of the diagnostic message and the second argument is returned as the value of the expression. Thus, the expressions always return a value of the same datatype as the second expression.

These expressions can be used to post a message from any rule, goal, function or expression and pass another expression to the calling expression. For example, when the following expression is evaluated, if the estimated flow is negative, a warning is posted to diagnostics and the expression evaluates to the estimated flow, a NUMERIC:

A Stop Run statement can be added to any rule or goal as a top level statement. From the Statement menu in the rule or goal, select Add Stop Run. The statement will cause the run to abort, post the specified message with red text, and bring the Diagnostics Output Window to the front. Typically a Stop Run statement will be inside of an If statement so that it only stops the run under specific conditions.

A Stop Run expression has the same behavior as a Stop Run statement, but it is selected off of the RPL Palette as an expression within the RPL logic rather than at the statement level. Because it is added at the expression level, a Stop Run expression can be added on the right-hand-side of a rule assignment, within a function, or within any other RPL expression. The Stop Run expression will cause the run to abort, post the specified message with red text, and bring the Diagnostics Output Window to the front. Typically a Stop Run expression will be inside of an If/Else expression so that it only stops the run under specific conditions.

To understand more about a rulebased simulation, it is sometimes useful to know more about function execution. RiverWare provides two types of diagnostic messages related to function execution:

To receive diagnostics for a function, you must do the following:

To enable or disable function diagnostics for many functions at once, from the RPL set editor select Ruleset, then Function Diagnostics. This will display a sub-menu which allows the following options: