Simulation Controller
The Simulation Controller is responsible for maintaining the order of execution at the highest level of simulation. The steps, in order, are as follows.
1. Initialization for simulation
a. Clear all output and values from previous runs for all timesteps in all series slots.
b. Set user inputs.
c. Propagate user inputs across link.
d. Determine first dispatch timestep. See Initialization for details.
2. Execute rules in the Initialization Rules RPL set. See Initialization Rules for details.
3. Simulation Beginning of Run
a. Execute Beginning of Run methods for all objects.
b. Evaluate Beginning of run expression slots for all timesteps.
4. For each timestep:
a. Set the controller clock to the timestep time.
b. Execute Beginning of Timestep methods for all objects.
c. Evaluate Beginning of timestep, current timestep only expression slots
d. Dispatch objects until the queue is empty, simulating the effects of the user inputs and default values.
e. Execute End of Timestep methods on all objects.
f. Evaluate end of timestep, current timestep only Expression slots
5. Execute End of Run Simulation methods on all objects.
6. Evaluate End of Run expression slots.
Initialization
During Initialization of the run, the controller first resets all output slots to NaN, registers input values, and propagates values across links. Then, it finds the first dispatch timestep for each object.It then executes Initialization rules.
First Dispatch Timestep
Next, the controller determines the first timestep at which an object is allowed to dispatch. For the majority of objects, this is the start timestep. For Reaches, Control Points, and Confluences objects, it is sometimes necessary to allow dispatching to take place during prerun timesteps. This enables prerun inputs to route downstream thus allowing the system to solve on the start timestep.
Finding Earliest Upstream Inputs
For Reaches, Control Points, Confluences, Inline Power Plants, and Stream Gages, the first dispatch timestep is determined by looking for the earliest Input value on the Inflow slot (Inflow1 or Inflow2 on the Confluence). Then, the method travels upstream to the linked object (or objects in the case of a confluence) and looks for the earliest input value. This search process continues until either the top of the basin is met or a non-Reach, Control Point, Confluence, Inline Power Plant, or Stream Gage object is met.
Note: The search stops if it finds a reach with either the Kinematic, Kinematic Improved, Muskingum, Muskingum Cunge, or MacCormack routing method selected. The first dispatch timestep is the earliest at which the object is able to dispatch; dispatching is still controlled by the object’s dispatch conditions.
Note: The search only looks for input values (“I” or “Z”) that are known before the start button is pressed. Initialization rules are executed later, so values set by those rules are not recognized as inputs.
Initialize Flow Slots for Routing
In addition to the search for earliest upstream inputs, methods in the Initialize Flow Slots for Routing category on the Computational Subbasin can be used to determine and set the number of prerun timesteps necessary for downstream lagging. See Initialize Flow Slots for Routing in Objects and Methods for details.
When these methods are selected, the earliest dispatch timestep is determined by also searching downstream to add up the required number of timesteps based on the selected Reach routing methods. See Initialize Flow Slots for Routing in Objects and Methods for details on these methods.
Initialization Rules
Initialization Rules are a set of RPL rules associated with the model which can be executed as part of run initialization to set up data for the run. Initialization Rules provide a complement to user inputs and execution of DMIs.
See Initialization Rules Set in RiverWare Policy Language (RPL) for details on Initialization Rules.
Time Horizon Simulation
Each object has its own clock. The controller clock, which is shown in the Run Status dialog, is not necessarily an indication of the timestep at which the objects are dispatching. Simulation proceeds without regard to the controller clock, except for executing the next Beginning of Timestep when the dispatch queue is empty.
Time horizon dispatching allows the system to solve over several timesteps, depending on which values are known. Due to time lags between reach Inflows and Outflows, objects may not have enough information to dispatch at a given timestep until later in the simulation. Over an entire river basin simulation, this can result in dispatching of linked objects at different timesteps.
When a model’s objects have enough information to dispatch later timesteps at the start of the simulation, they will. In such models, most of the dispatching can take place while the controller clock is still on the first timestep. In these cases, the Run Status dialog shows the controller clock on the first simulation timestep for most of the execution time. Since most of the timesteps solve, the simulation proceeds very rapidly through the other timesteps.
Note: The last timestep at which objects dispatch is typically the Finish Timestep but can be specified by the user; see Simulation Run Parameters in User Interface for details. This allows models that lag or forecast to correctly compute values near the end of the run.
Underdetermination
When objects do not dispatch during the run, no warning or error is generated. Lack of sufficient data to force dispatching is not considered an error. The Dispatch Information dialog should be reviewed after each run to verify that all objects dispatched for all timesteps.
Revised: 07/05/2022