User Interface
Run Control
The Run Control dialog controls the execution of a run, as well as providing the interface for selecting the solution type, timestep, and run times.
Controllers
There are three basic solution techniques, or controllers: Simulation, Optimization, and Rulebased Simulation, Rulebased Simulation and Optimization both require the construction of a Simulation model; therefore, all models need a basic simulation component. For this reason, the Simulation controller is the default selection when the Run Control dialog is first opened. To select a different controller, click on the Controller Option menu to view the other controller choices.
A large number of slots are associated with each controller. When an object is created, it is initialized with the slots belonging to the selected controller. When a new controller is selected after the objects have been constructed, the original slots remain in memory and new slots are allocated for the new controller. This situation may leave many unnecessary slots which affect memory and model size. When building the initial simulation model, the Simulation controller must be selected.
Controller-specific Parameters
Each controller has specific parameters which are set through an extension of the Run Control dialog. The additional dialog is invoked using the View, then <Controller> Run Parameters menu, depending on the selected controller.
Simulation Run Parameters
Max Iterations(EngrObj Slots)
This value represents the maximum number of times a slot can be reset or recalculated on a given timestep.
Series Extension Increment
RiverWare allocates space for the entire run length of each series. If, during the run, timesteps beyond the run are given values, RiverWare has to extend the series and copy over all the existing values, because RiverWare requires that the series values be stored in contiguous memory. This is a time consuming operation, so it is in the users' interest to avoid this operation. Thus, this parameter allows the users to allocate a little extra space if they know that their models will be solving for timesteps beyond the end of the run. This is particularly important where reach routing causes timesteps beyond then end of the run to acquire values. For example, if a reach has a routing coefficient vector of 40 elements, the series extension increment should be at least 40. A second example is if the model solves into the future throughout a defined forecast period. Set the Series Extension Increment equal to the forecast period as that many timestep will be required at the end of the run.
Warn when Values are out of Bounds
Series slots have upper and lower bounds that are used as part of an optimization solution. Using this parameter, you can show a warning message when values set in Simulation or Rulebased Simulation are outside these bounds. See “Configure Slot Dialog Functionality” for details.
Water Quality
Also in this dialog, Water Quality calculations may be enabled and configured. See “Water Quality Overview” in Water Quality for details.
Number of Post-Run Dispatch Timesteps
Sometimes, computations are required past the end of the run. This is particularly true for models with lags and forecasting algorithms. For example, if you are trying to determine how much water to release on the run’s finish timestep and you have a two timestep lag to the controlling location, you need the downstream reaches to dispatch two timesteps past the end of the run.
The Number of Post-Run Dispatch Timesteps parameter represents the number of timesteps past the run finish timestep for which object dispatching will be allowed. Whether an object dispatches or not still depends on the knowns and unknowns, i.e. the dispatch conditions. Also, additional data may be required for the objects to correctly dispatch and solve. Data defaults (like reservoir diversion) will be set past the end of the run, too. Note, the Number of Post-Run Dispatch Timesteps is controller specific, that is, it can be different for the Simulation and Rulebased Simulation controllers.
Water Year Start Month
This is the start month of the water year. This is currently only used by the Time Aggregation Series Slot computation. See “Annual Aggregation Support for Non-calendar Water Years” for details.
Save All Global Functions Sets with Model
This checkmark specifies that any open Global Functions RPL sets should be saved with the model file. See “Save Location” in RiverWare Policy Language (RPL) for details.
Rulebased Simulation Run Parameters
Water Quality
Water Quality calculations may be enabled and configured. See “Water Quality Overview” in Water Quality for details.
Max Iterations(EngrObj Slots)
Represents the maximum number of times a slot can be reset or recalculated on a given timestep.
Series Extension Increment
RiverWare allocates space for the entire run length of each series. If, during the run, timesteps beyond the run are given values, RiverWare has to extend the series and copy over all the existing values, because RiverWare requires that the series values be stored in contiguous memory. This is a time consuming operation, so it is in the users' interest to avoid this operation. Thus, this parameter allows the users to allocate a little extra space if they know that their models will be solving for timesteps beyond the end of the run. This is particularly important where reach routing causes timesteps beyond then end of the run to acquire values. For example, if a reach has a routing coefficient vector of 40 elements, the series extension increment should be at least 40. A second example is if the model solves into the future throughout a defined forecast period. Set the Series Extension Increment equal to the forecast period as that many timestep will be required at the end of the run.
Warn when Values are out of Bounds
Series slots have upper and lower bounds that are used as part of an optimization solution. Using this setting, you can show a warning message when values set in Simulation or Rulebased Simulation are outside these bounds. See “Configure Slot Dialog Functionality” for details.
Save Loaded RPL Set with Model
This checkmark specifies that the loaded RBS ruleset should be saved with the model file. See “Save Location” in RiverWare Policy Language (RPL) for details.
Save All Global Functions Sets with Model
This checkmark specifies that any open Global Functions RPL sets should be saved with the model file. See “Save Location” in RiverWare Policy Language (RPL) for details.
Number of Run Cycles
This integer value controls how many times the rulebased simulation controller will cycle through the timesteps. See “Run Cycles” in Solution Approaches for details.
Number of Post-Run Dispatch Timesteps
Sometimes, computations are required past the end of the run. This is particularly true for models with lags and forecasting algorithms. For example, if you are trying to determine how much water to release on the run’s finish timestep and you have a two timestep lag to the controlling location, you need the downstream reaches to dispatch two timesteps past the end of the run.
The Number of Post-Run Dispatch Timesteps parameter represents the number of timesteps past the run finish timestep for which object dispatching will be allowed. Whether an object dispatches or not still depends on the knowns and unknowns, i.e. the dispatch conditions. Also, additional data may be required for the objects to correctly dispatch and solve. Data defaults (like reservoir diversion) will be set past the end of the run, too. Note, the Number of Post-Run Dispatch Timesteps is controller specific, that is, it can be different for the Simulation and Rulebased Simulation controllers.
In RPL, you can access the timestep represented by the function using the DispatchEndDate function; see “DispatchCount” in RiverWare Policy Language (RPL) for details.
Maximum Rule Executions Per Timestep
This value indicates how many times a single rule can execute on each timestep.
Water Year Start Month
This is the start month of the water year. This is currently only used by the Time Aggregation Series Slot computation. See “Annual Aggregation Support for Non-calendar Water Years” for details.
Accounting
If Accounting is enabled, the following parameters are added to either the Simulation or Rulebased Simulation parameters described above:
Max Iterations (Account Slots)
This parameters represents the maximum number of times an account slots can be reset or recalculated.
Timestep
Many different timesteps are available for simulation. The currently selected timestep is shown on the Timestep menu (see Figure 6.1). When the Run Control dialog is invoked on an empty workspace, it has the default timestep value of 6 Hour. You must select the desired timestep before building a model. This facilitates data entry by initializing new objects to the desired run times.
Figure 6.1 Run Control showing Timestep menu
Run Times
The initial time, end time, and duration of the run are set through text fields on the Run Control panel. RiverWare’s time management system requires that times for data and for the run be given in actual time (hour, day, month and year), rather than relative time, as is seen in many other modeling systems. Figure 6.2 illustrates runtime term definitions.
Figure 6.2
The Initial time is the time at which the simulation begins and the beginning of the first timestep. Initial condition data are required at this timestep. Solutions are reported at the end of each timestep. The Start time is the end of the first timestep and is the first time at which output is given. The Finish time is the end of the last timestep of the run. The Timesteps field contains the number of timesteps in the run. For 1, 6, or 12 hour timesteps, the time of day is displayed. RiverWare denotes midnight as 24:00 hours instead of 0:00 in the next day. For all other timesteps, the time of day is not displayed.
Changing the Initial time changes the Finish time accordingly; run Timesteps remain the same.
Valid dates in RiverWare are from 24:00 December 31, 1799 to 23:00 December 31, 3799.
Making a Run
The dialog is invoked by selecting Control, then Run Control Panel from the workspace menu bar or by clicking on the Run Control toolbar button.
The buttons are used to control the execution of a model. They are as follows.
• 
Confirm. Confirm run control changes (i.e., changes to number of timesteps, run parameters, or simulation type).
Confirm. Confirm run control changes (i.e., changes to number of timesteps, run parameters, or simulation type).• 
. Reject. Reject run control changes.
. Reject. Reject run control changes.• 
Enabled or Disabled. Optionally shown, RPL Debugging is enabled or disabled. See “Enabling RPL Debugging” in Debugging and Analysis for details.
Enabled or Disabled. Optionally shown, RPL Debugging is enabled or disabled. See “Enabling RPL Debugging” in Debugging and Analysis for details. • Start. Execute a run.
• Init. Execute initialization or the next timestep only. (If no run is in progress, execute initialization. The second click of the Step button executes the first timestep)
• Pause. Interrupt execution after the current timestep.
• Continue. Continue execution from the current timestep. (When the run is started the start button becomes the continue button)
• Stop. Abort execution after the current timestep.
• Pause Before Timestep. Pause the run before the specified timestep. This is particularly useful when debugging a model run.
• Execute Initialization Rules. Specify whether to execute Initialization Rules. The checkbox is only available when Initialization Rules are defined. See “Types of RPL Sets” in RiverWare Policy Language (RPL) for details.
When a run is not in progress, only the Start and Step buttons are available. If changes are made to the run dates, the timesteps, or other Run Control parameters, the Check button 
must be clicked to enable all the other Run Control buttons. The Continue, Step and Pause buttons are then enabled after the Initializing period has ended.
must be clicked to enable all the other Run Control buttons. The Continue, Step and Pause buttons are then enabled after the Initializing period has ended.When a run is started, the Run Status area is updated. You can see a separate version of this dialog using the View, then Run Status menu.
The indicator bar moves from left (start) to right (finish), indicating the progress of the run. The Execution State: also indicates the state of the run with a status description. The possible Execution States are: Initializing, Running, Finished, Stopped, Waiting, Paused, and Aborted.
The Controller Clock (date and time of the currently executing timestep expressed in units of the selected timestep size) is displayed under the Execution State. Due to time horizon dispatching, the Controller Clock may not represent the timesteps of all objects being solved. See “Time Horizon Simulation” in Solution Approaches for details.
Note: When there is more than one Run Cycle, the Run Cycle is listed in the Timestep and there are controls for the Run Cycle in the Pause Before Timestep line. See “Run Cycles” in Solution Approaches for details.
Aborted Run
If a run cannot continue because of errors, a RiverWare Notice window will be shown and error messages will be posted to the diagnostic output window; see “Diagnostic Output Window” in Debugging and Analysis for details. The user has the following options from the confirmation window:
• Time Scroll. Scroll all time-scrollable windows to the context time. The user can select to scroll all time windows, like the Open Slot dialog, SCTs and the Plot window to this date. This saves the user time when debugging the model.
• Cancel. Close the dialog, but do not Time Scroll.
• Do not show this notice again. Request that the dialog not be shown again. If this box is selected, then subsequent aborts will use the same selection (Time Scroll or Cancel) and the dialog will not be shown. This applies only to the current RiverWare session.
Synchronization
There are two ways to synchronize all or selected objects to the either the run control or a specified period: by changing the run control and applying the changes through its child dialogs, or by using the Synchronization Control dialog. These two methods are described below
Synchronize From Run Control
On the Run Control, after making changes to the run range, the user is presented with the green check and red X to either apply the changes or cancel the changes. Also, the Synchronize Slots with Run Parameters checkbox is enabled. If checked, when the green check is clicked, the Synchronize Slots dialog is opened. This dialog allows the user to configure how the slots should be resized. The default Begin, End and number of Timesteps is taken from the Run Control. The user can optionally synchronize accounting slots with the simulations slots or enter a different time range.
If changes are made to the timestep size, the Synchronize Slots with Run Parameters checkbox is not available, rather the Synchronize Timestep Change dialog is opened when the green check is clicked to apply run parameter changes. This dialog allows the user to optionally synchronize objects with the new timestep. An option allows for exclusion of slots with timesteps different than the original timestep. If the timestep change represents a valid aggregation, options are presented to aggregate input data in slots to the new timestep. Valid aggregations are as follows:
• 1 Hour, 6 Hour, 12 Hour, or 1 Day aggregating to 1 Month
• 1 Hour, 6 Hour, 12 Hour, 1 Day, or 1 Month aggregating to 1 Year
The following options are available for how to treat NaNs when aggregating input data:
• Ignore NaN/Output values. NaNs or Output values do not contribute to the aggregated values. Intervals with some inputs and some outputs or NaNs will become inputs at the larger timestep.
• Do not aggregate intervals having NaN/Output values. Any interval with NaNs or an output value is not aggregated. Intervals with some inputs and some outputs or NaNs will be NaN at the larger timestep.
Note: For the Last aggregation function, only the Last timestep is considered. Other timesteps do not matter in their NaN/Output status.
• Error on NaN (excluding pre-simulation timesteps). An error is issued.
The method by which input data is aggregated is controlled by a slot’s unit type. Table 6.1 provides detail. Inputs in slots with unit types not listed are not aggregated. An information dialog will indicate slots that were not aggregated.
Unit Types | Aggregation Method |
|---|---|
Area | Last |
Concentration | Average |
Energy | Sum |
Flow | Average |
Fraction | Average |
Length | Last |
LengthPerTemperature | Average |
Mass | Sum |
No Units | Last |
Power | Average |
PowerCost | Average |
PowerPerFlow | Average |
Temperature | Average |
TemperatureInF | Average |
ValuePerFlow | Average |
ValuePerVolume | Average |
Velocity | Average |
VelocityPerTemperature_F | Average |
Volume | Last |
Synchronization Control Dialog
The Synchronization Control dialog allows the user to synchronize slots without changing the run control. To access this dialog, use the Workspace, then Objects, then Synchronize Objects. The user is able to synchronize all or selected objects to be synchronized to the Run Control or a separate specified time interval.
The new time interval must encompass the run control time interval. A checkbox allows users to Include Accounting Object in the synchronization action. A second checkbox allows the user to Exclude Slots with Different Timestep from the synchronization. This option may be useful, in particular, to retain data stored in data objects.
Revised: 11/11/2019