skip to main content
Debugging and Analysis : Diagnostics : Rulebased Simulation Diagnostics
Rulebased Simulation Diagnostics
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.
Figure 3.8   
Rulebased Simulation Diagnostic Groups
Table 3.3 summarizes the types of messages that are displayed when a Diagnostic Group is selected.
 
Table 3.3    
Super Group
Diagnostics Group
Type of diagnostics issued
Run Management:
 
Controller
Beginning/End of Run/Timestep for each time.
Examples:
Initializing model run.
Beginning of Run.
Begin Timestep.
Execute timestep.
End of run.
 
Object
Beginning/End of Run/Timestep for each Object and time.
Examples:
Clear state.
Propagating user input.
Beginning of run.
Begin timestep.
End timestep.
End of run.
 
Slot
Beginning of Run for each Slot and time.
Examples:
Clear state.
Propagating user input.
Dispatch Management:
 
Controller
Beginning of a dispatch for each object and time.
Example:
Executing dispatch method (Solve given Inflow Outflow) at Priority 7.
 
Object
Dispatch readiness for each object and time.
Examples:
Slot (“Inflow”) added to known set.
Ready for dispatch method (“Solve given Inflow, No Routing”).
Slot (“Inflow”) is already in known set.
Re-dispatching using slot priorities.
Priority 3R:Inflow
Priority 7:Outflow
Priority 7:Total Diversion
Priority 7:Total Return Flow
Priority 7:Total Local Inflow
Conflicting slot values:(“Inflow” “Outflow” “Total Diversion” “Total Return Flow” “Total Local Inflow”).
 
Slot
Value assignments and propagation for each slot and time.
Examples:
Set value =453.003351 *1000.0 acre-feet/month =208.621343 *1.0cms.
Propagate value to slot (“Total Available Water”).
Rule Management:
 
Dependencies
Dependencies for each rule and time.
Example:
After execution, rule #4 has the following dependencies: Mead.Storage, Mead.Inflow.
 
Agenda
Additions and status of the agenda for each rule and time.
Examples:
The following rules are currently on the agenda: 3, 4, 8.
Changing dependency (Mead.Outflow) caused rule #3 to be put on the agenda.
 
Assignments
Value assignments for each rule, time and slot.
Example:
Result of sending values to controller:
- Priorities permitted setting of Mead.Storage[24:00 January 31, 1993] to 676194743.34m3
Independent Groups:
 
Rule Execution
Rule execution details for each rule, time and slot.
Examples:
Executing rule (#3)
Assignment initiated (the left-hand side is “Mohave.Storage”[])
Evaluation of Assignment statement successful; will attempt assignment
Mohave.Storage[July, 1998] = 1590800.00 [1.00 acre-ft]
Rule successfully finished
Early termination: NaN encountered.
The problem was encountered at the following location within the expression: “FC Space Violation”().
RHS of assignment evaluated to NaN.
Unable to set slot (Outflow at 00:00 February 1, 1999) Rule’s priority (4) junior to slot’s (2).
 
Function Execution
Diagnostics messages for function execution (both user defined and predefined). “Before Execution” function diagnostics show the function being called and the arguments passed into the function. “After Execution” function diagnostics show the value that the function evaluated to and whether or not the value was constrained.
Note: Function diagnostics also need to be enabled on the functions themselves. This can be done through the Function Editor dialog (for enabling diagnostics on individual functions) or by selecting Ruleset, then Ruleset Function Diagnostics from the main Ruleset Editor (for enabling or disabling function diagnostics for all functions in the ruleset). See Function Diagnostics for details.
Examples:
GetMaxReleaseGivenInflow (% “WattsBar”, 0.634 [“1000 * cms”], @”Current Timestep”)
“GetMaxReleaseGivenInflow” evaluated to: 1299.413 [“cms”]
“GetMaxReleaseGivenInflow” constrained to: 1200.00 [“cms”]
 
Hypothetical Simulation
Diagnostics messages for hypothetical simulation. This includes information about the start and end of hypothetical simulation, the iteration information (if using a target hypothetical simulation function), and any information regarding the hypothetical simulation solution.
Examples:
HypSim: Hypothetical limit simulation starting for specified SubBasin.
Hypothetical simulation occurring within the time range [12:00 November 23, 1995 - 00:00 December 5, 1995].
HypSim: For iteration 1, control slot interval is [0.000000 “cms”, 75.000000 “cms”], range of interval is [1768.684936 “m”, 1763.270439 “m”].
HypSim: For target value 1768.297200 “m”, result is control value 19.628906 “cms”, leading to the simulated target value 1768.296428 “m” (error = 0.000772 “m”).
HypSim: Hypothetical limit simulation ending for specified SubBasin.
 
Print Statements
User defined messages within rules for each rule and time.
Example:
Entering rule curve routine for January - July
 
User Methods
Execution of User Methods for each object and time.
Example:
Executing the user method “Daily Evaporation” in the category “Evaporation and Precipitation”.
 
Interpolation
TableSlot table interpolation lookups for each slot.
Examples:
Table Interpolation 2 (3D) Specified z value (960.6579) falls between row ranges (556-572) and (573-589). (1->2) rows (556-572) x=195.804788, y=198.503173 (1->2) rows (573-589) x=195.804788, y=198.585469 (fixed 0 at 960.657920, 1->2) (in=195.804788) (out=198.579323 slope=.656000 intercept=70.131382)
 
Expr. Slot Execution
Expression slot execution diagnostics are printed for expression slots that are configured to evaluate during a run (evaluation time of beginning or end of timestep, or beginning or end of run).
Example:
Expression evaluated to 624.00 [1000 acre-ft]
 
Expr. Slot Function Execution
Evaluation of RPL functions called by expression slots evaluated during a run. Diagnostics messages are printed for function execution (both user defined and pre-defined). “Before Execution” function diagnostics show the function being called and the arguments passed into the function. “After Execution” function diagnostics show the value that the function evaluated to and whether or not the value was constrained.
Note: Function diagnostics also need to be enabled on the functions themselves. This can be done through the Function Editor dialog (for enabling diagnostics on individual functions) or by selecting Set, then Function Diagnostics from the main Set Editor (for enabling or disabling function diagnostics for all functions in the set). The Expression Slot Set editor is accessed from the Workspace Policy, then Open Expression Slot RPL Set. See Function Diagnostics for details on configuring the diagnostics. See Series Slots With Expression in User Interface for details on expression slots.
Example:
SumFlowsToVolume($”Mountain Storage.Inflow”, @”Start Timestep”, @”t”)
“SumFlowsToVolume” evaluated to: 274839.74 [“m3”].
 
Init. Rules Rule Execution
Initialization Rules rule execution diagnostics are printed for each rule.
Examples:
Executing rule (#3)
Assignment initiated (the left-hand side is “Mohave.Storage”[])
Evaluation of Assignment statement successful; will attempt assignment
Mohave.Storage[July, 1998] = 1590800.00 [1.00 acre-ft]
Rule successfully finished
Early termination: NaN encountered.
The problem was encountered at the following location within the expression: “FC Violation”().
RHS of assignment evaluated to NaN.
 
Init. Rules Function Execution
Diagnostics messages for function execution (both user defined and pre-defined) from initialization rules. “Before Execution” function diagnostics show the function being called and the arguments passed into the function. “After Execution” function diagnostics show the value that the function evaluated to and whether or not the value was constrained.
Note: Function diagnostics also need to be enabled on the functions themselves. This can be done through the Function Editor dialog (for enabling diagnostics on individual functions) or by selecting Ruleset, then Ruleset Function Diagnostics from the main Ruleset Editor (for enabling or disabling function diagnostics for all functions in the ruleset). See Function Diagnostics for details.
Examples:
GetMaxReleaseGivenInflow (% “WattsBar”, 0.634 [“1000 * cms”], @”Current Timestep”)
“GetMaxReleaseGivenInflow” evaluated to: 1299.413 [“cms”]
“GetMaxReleaseGivenInflow” constrained to: 1200.00 [“cms”]
 
Init. Rules Print Statements
User defined messages for each initialization rule.
Example:
Entering rule curve routine for January - July
Data Management
Rule DMI
Execution of rule DMI’s for each specified rule.
Selecting Rules
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.
Posting User Messages to Diagnostics
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.
Print Statements
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
Notice, Warning, and Alert messages post messages with different colors; see Figure 3.9. 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.
• Notices are displayed as purple text with a white background.
• Warnings are displayed as black text with a pink background.
• Alerts are displayed as black text with an orange background.
Figure 3.9  Examples of Notice, Warning and Alert messages shown in diagnostics output
Notice Warning, and Alert Statements
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
Notice, Warning, and Alert Expressions
A Notice, Warning, or Alert expression is added from the RPL palette as shown in Figure 3.10.
Figure 3.10  Miscellaneous buttons showing the Warning, Notice and Alert buttons.
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:
Figure 3.11  Sample RPL expression using a Notice expression.
Stop Run Statements
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.
Stop Run Expressions
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.
Function Diagnostics
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:
• Before Execution diagnostic: The diagnostic is issued just before a function is executed and gives the name of the function and the values passed in as arguments.
• After Execution diagnostic: This diagnostic is issued after the function has completed execution and gives the name of the function and the value to which it evaluated.
To receive diagnostics for a function, you must do the following:
• Open the Diagnostic Manager (accessible, for example, through the Run Control View menu), enable informational diagnostics and select whether they should go to the Output Window or a file.
Note:  This step is required to receive any informational diagnostics.
• Open the Rulebased Simulation Diagnostics Configuration window and toggle on the Function Execution category.
Note:  This category can be filtered by timestep and rule, if desired.
• Open the Function Editor for the function for which you would like to see diagnostics. Select View, then Show Diagnostic Settings or select the Diagnostic Settings toggle. This will add a panel to the Function Editor which allows you to toggle on or off either type of diagnostic (Before Execution or After Execution) for that particular function (see graphic). If the return type of the function is NUMERIC and you would like to see After Execution diagnostics for that function, then you may enter the scale and units in which you would like the function’s return value to appear within the diagnostic. Examples include 1000 cfs and ft. No quotes are required.
Figure 3.12   
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:
• Enable Before Execution diagnostics for all user defined functions
• Enable After Execution diagnostics for all user defined functions
• Enable Before Execution diagnostics for all predefined functions
• Enable After Execution diagnostics for all predefined functions
• Disable Before Execution diagnostics for all user defined functions
• Disable After Execution diagnostics for all user defined functions
• Disable Before Execution diagnostics for all predefined functions
• Disable After Execution diagnostics for all predefined functions
Revised: 01/10/2022