skip to main content
Dispatching
Unlike basic simulation, an object in rulebased simulation may dispatch with different dispatch methods in a single timestep. The complication for the objects is determining which dispatch method to use whenever it gets a new slot value. Until an object dispatches for the first time during a timestep, it checks its knowns and unknowns against the dispatch conditions of its dispatch methods. This is the same process used in basic simulation. When the required knowns and unknowns are met, the object dispatches for the first time.
After the object has dispatched once at a given timestep, all of its dispatch slots should be known. If a new value is later set on a dispatch slot, the object must redispatch. But checking required knowns and unknowns is no longer a useful mechanism for determining the method with which to redispatch. In basic simulation, because slot values at a timestep are always set from the same source, the object simply redispatches with the same dispatch method used in the first dispatch.
In rulebased simulation, however, values may be set from different sources. The priorities of the dispatching slots must be used to determine the dispatch method. The dispatch method used for redispatches is the one who’s required knowns have the highest priority slot values.
Governing Slots
The slots in a dispatch method’s required knowns list are divided into potential governing slots and non-governing slots. Potential governing slots may determine with which dispatch method an object can solve. Non-governing slots are simply a requirement for every dispatch method. For example: Inflow and Outflow are potential governing slots, Diversion is not. Let’s explore the reasons why. A river Reach object may solve upstream or downstream, depending on whether Inflow or Outflow are known. Inflow and Outflow are potential governing slots. If the object solves upstream in response to a known Outflow, the governing slot is Outflow. If, however, the object solves downstream in response to a known Inflow, the governing slot is Inflow. While both Inflow and Outflow are potential governing slots in this scenario, only one can be the actual governing slot. Diversion is a non-governing slot. A Storage Reservoir object may solve for its Inflow, Outflow, Storage, or Pool Elevation. In all cases, Diversion must be known for the Reservoir to mass balance. If Diversion is known, this only means that the Reservoir can dispatch, it tells us nothing about which of the dispatch methods the object can solve with. In general, the Governing slots are the slots which uniquely determine the dispatch method an object can solve with. The governing slots determine in which “direction” an object solves.
 
Potential governing slot
A potential governing slot is a slot which, by virtue of being known or unknown, will influence with which dispatch method an object can solve.
The potential governing slots for each object are listed below. All other dispatch slots are considered non-governing slots.
 
Table 2.4   
Object
Potential Governing Slots
Aggregate Distribution Canal
Downstream Delivery Request
Aggregate Diversion Site
Total Available Water,
Total Diversion Requested
Total Diversion
Total Depletion
Total Unused Water
Aggregate Reach
Inflow,
Outflow
Bifurcation
Inflow,
Outflow1
Outflow2
Canal
Elevation 1,
Elevation 2
Confluence
Inflow1,
Inflow2,
Outflow
Distribution Canal
Inflow
Diversion Object
Diversion Request,
Diversion Intake Elevation
Ground Water Storage
Inflow
Inline Power Plant
Inflow,
Outflow
Level Power Reservoir
Inflow,
Outflow,
Turbine Release,
Pool Elevation,
Storage,
Hydrologic Inflow,
Energy
Pumped Storage Reservoir
Inflow,
Outflow,
Pool Elevation,
Storage,
Energy,
Pumps Used,
Pump Power,
PumpEnergy
Reach
Inflow,
Outflow,
Local Inflow
Slope Power Reservoir
Inflow,
Outflow,
Turbine Release,
Pool Elevation,
Storage,
Energy
Storage Reservoir
Inflow,
Outflow,
Release,
Pool Elevation,
Storage,
Hydrologic Inflow
Stream Gage
None
Water User
Incoming Available Water
Diversion Requested
Diversion
Depletion
Outgoing Available Water
Once the knowns and unknowns of an object have uniquely identified a dispatch method, the actual governing slots can be identified. The actual governing slot(s) is (are) the slots which are in the potential governing slots list and are a required known for the dispatch method. The actual governing slot(s) may be one or two, depending on the object. For Reservoir objects, there are two governing slots, selected from the list of potential governing slots. For Reach objects, there can be only one governing slot.
 
Governing slot
A governing slot is a slot which is:
1) in the potential governing slots list and
2) is a required known in the selected dispatch method. Governing slots provide insight into the direction in which the solution is propagating.
Example 2.6   
A Storage Reservoir may solve downstream due to Inflow and Storage or Inflow and Elevation, upstream due to Outflow and Storage or Outflow and Elevation, or it may solve for its own Storage and Pool Elevation due to Inflow and Outflow. The intersection of the required knowns of the dispatch method and the potential governing slot(s) of the object, determine the actual governing slot(s).
• Question: What are the governing slots if a Storage Reservoir solves for its Release and Outflow?
• Answer: There are two dispatch methods which will result in a Storage Reservoir solving for both Release and Outflow:
Solve given Inflow, Storage
and Solve fiven Inflow, Pool Elevation
The intersection of the required knowns for these dispatch method with the potential governing slots for the Storage Reservoir yields the following solutions:
Case 1: Inflow and Storage
Case 2: Inflow and Pool Elevation
Determination of Dispatch Method
The determination of a dispatch method for redispatching is based on the priorities of the slots. Once the object has dispatched once, all dispatch slots will be known, so checking knowns and unknowns is ineffectual. To determine the dispatch method, it is necessary to construct an alternate known slot list using the highest priority slots. RiverWare begins with an empty known slot list, then adds slots in priority order until a set of dispatch conditions is met. Since the non-governing slots are all known and they do not influence the choice of which dispatch method to solve, there is no point in prioritizing them; all non-governing slots are added to this list first. Then, the governing slots are added to the known list in priority order to determine the dispatch method.
The algorithm to determine the correct dispatch method for redispatching is as follows.
1. Begin with an empty set of known slots (pretend nothing is known).
2. Add all non-governing slots to the known slot set.
3. Add all of the object’s potential governing slots with priority 0 to the known slot set.
a. Check the known set against the required knowns of each dispatch method. If a match is found, put the object on the queue with this dispatch method, and exit the algorithm.
b. Check the known set against the conflict list.If the known set contains all of the slots of a conflict, put the object on the queue with the same dispatch method as the last time it dispatched, and exit the algorithm.
4. Loop through all priority levels starting with the highest priority (1,2,3...) until a dispatch method is determined. For each priority level:
a. If there are any potential governing slots at the priority level that have an R flag, add the R-flagged slots to the known set and defer the other slots.
b. If no potential governing slots at the priority level have an R flag, add all potential governing slots at that priority to the known set.
c. Check the known set against the required knowns of each dispatch method. If a match is found, put the object on the queue with this dispatch method and exit the algorithm.
d. Check the known set against the conflict list. If the known set contains all the slots of a conflict, put the object on the queue with the same dispatch method as the last time it dispatched and exit the algorithm.
5. Loop through all priority levels again in order (1,2,3...), and for each:
a. Add any non-R-flagged slots that were deferred in Step 4. to the known set.
b. Check the known set against the required knowns of each dispatch method. If a match is found, put the object on the queue with this dispatch method and exit the algorithm.
c. Check the known set against the conflict list. If the known set contains all the slots of a conflict, put the object on the queue with the same dispatch method as the last time it dispatched and exit the loop.
This algorithm always results in the identification of a dispatch method or an error and terminated run.
 
Example 2.7   
A Level Power Reservoir, named ResA, has no diversions and a user input Hydrologic Inflow. The following sequence of events take place.
1. A low priority rule (#4) sets an Outflow on a reservoir directly upstream of the ResA. The value and the R flag propagate across the link to this ResA’s Inflow slot.
2. A higher priority rule (#3) sets the ResA’s Storage.
3. ResA can now dispatch for the first time with the Solve given Inflow, Storage dispatch method at a priority of 3.
After the dispatch, all of the reservoir’s dispatch slots are known at the following priorities.
 
Slot
Priority
Inflow
4R
Hydrologic Inflow
0
Storage
3R
Pool Elevation
3
Diversion
0
Return Flow
0
Outflow
3
Now suppose that the highest priority flood control rule (#1) has to overwrite the ResA’s Outflow to prevent flooding downstream. The reservoir must redispatch.
• Question: What slots does the ResA’s known set contain after each step of the logic to determine the dispatch method? Do any of these known sets match a dispatch method? Which one?
Answer: The logic is as follows:
1. Start with an empty known set.
2. Add all of the non-governing slots to the known set.
 
Slot
Priority
Diversion
0
Return Flow
0
3. Hydrologic Inflow (a potential governing slot) was user input and has a priority of 0. Add this slot to the known set.
 
Slot
Priority
Diversion
0
Return Flow
0
Hydrologic Inflow
0
These three slots alone do not satisfy any of the dispatch conditions. Continue.
These three slots alone are not a conflict. Continue.
4. Loop through the priorities:
• Priority 1: Outflow is known at priority 1R. Add it to the known set. Hydrologic Inflow, Diversion, Return Flow, and Outflow do not satisfy any dispatch conditions. Hydrologic Inflow, Diversion, Return Flow, and Outflow are not a conflict. Continue.
 
Slot
Priority
Diversion
0
Return Flow
0
Hydrologic Inflow
0
Outflow
1R
• Priority 2: There are no slots at this priority.
No changes are made to the known set. Continue.
 
Slot
Priority
Diversion
0
Return Flow
0
Hydrologic Inflow
0
Outflow
1R
• Priority 3:
Both Storage and Pool Elevation are at priority 3, but Storage has an R flag. Add Storage to the known set and defer Pool Elevation.
Diversion, Return Flow, Hydrologic Inflow, Outflow, and Storage satisfy the conditions for the Solve given Outflow, Storage dispatch method. Add this object to the queue with this dispatch method, and exit.
 
Slot
Priority
Diversion
0
Return Flow
0
Hydrologic Inflow
0
Outflow
1R
Storage
3R
Note:  The Pool Elevation and Inflow slots are never added to the known set. It is not necessary to consider them because we satisfied a dispatch method’s conditions with higher priority slots and R flags.
• Question: Once the object redispatches, a new value will be computed for two of the slots. Which slots? What will their priorities be after the dispatch completes?
Answer: The object will redispatch using the solveMB_givenOutflowStorage dispatch method at a controller priority of 1 (because the last rule to succeed was rule #1). During the dispatch, the object will solve for new Inflow and Pool Elevation values. These values will be set on the Inflow and Pool Elevation slots at a priority of 1 and 3, respectively. (The Pool Elevation slot is an equivalent slot to Storage which has a priority of 3R.)
 
Revised: 07/05/2022