skip to main content
Dispatch Methods
The dispatch method used to solve the Level Power Reservoir, is dependent upon the selection made in the Hydrologic Inflow category and Disable Reservoir Processes categories.
* solveMB_givenInflowHW
Solves the mass balance equation when Inflow and headwater (Pool Elevation) are known.
Required Known Slots
• Inflow
• Hydrologic Inflow, unless None is selected in the Hydrologic Inflow category.
Required Unknown Slots
• Storage
• Outflow
• Energy
Method Details 
First the dispatch method finds the Storage associated with the known Pool Elevation using the Elevation Volume Table. Then, if Pool Elevation is flagged as a TARGET, the method performs the appropriate target calculations. Next, the method checks for a linked Canal Object. If a Canal object is linked and has not yet solved, the dispatch method exits and waits for the Canal to solve before continuing.
If the above checks pass, the mass balance equation is solved as follows:
The mass balance equation may include the effects of evaporation, bank storage, seepage, or precipitation depending on the selected user methods. Inflow in the mass balance equation is the net inflow to the reservoir, including hydrologic inflows, return flows, and diversions if appropriate.
The spill calculation method is then executed followed by the power calculation method. If there are excess outflows from the power calculation method, the spill method is executed again to distribute the excess.
Energy in storage, spilled energy and future value calculations are performed if the user has selected them.
* solveMB_givenOutflowHW
Solves the mass balance equation when Outflow and headwater (Pool Elevation) are known.
Required Known Slots
• Outflow
• Hydrologic Inflow, unless None is selected.
Required Unknown Slots
• Storage
• Inflow
Method Details 
1. First the dispatch method calculates the Storage using the Elevation Volume Table and the known Pool Elevation. Then it performs the appropriate target calculations if Pool Elevation is flagged as a TARGET
Note:  If Outflow is flagged MAX CAPACITY a target operation cannot be performed.
2. Next, the method checks for a linked Canal Object. If a Canal Object is linked and has not yet solved, the dispatch method waits for the Canal to solve before continuing. If Outflow is flagged MAX CAPACITY, it is set as the sum of the maximum spill and maximum turbine release.
3. The mass balance is carried out as follows:
The mass balance equation may include the effects of evaporation, bank storage, seepage, or precipitation depending on the selected user methods. Inflow calculated by the mass balance equation includes the effects of hydrologic inflow, diversion and return flow. The Inflow slot is adjusted accordingly to account for these additional terms.
4. The spill method is then executed. Next, the Energy is checked. If Energy is input, the power release method is executed instead of the power calculation method. Regardless of whether or not Energy is input, the Tailwater Base Value is checked. If the Tailwater Base Value (from a downstream reservoir) is not yet known, the method is exited and waits until the Tailwater Base Value is known. Next, the power calculation method is executed. Then the Turbine Release is calculated. After Turbine Release has been calculated, the spill method may be executed again if there are excess outflows. If the calculated Inflow is less than zero, and the Hydrologic Inflow And Loss method is selected, Inflow is set to 0.0 and Hydrologic Inflow Adjust is calculated.
5. Energy in storage, spilled energy and future value calculations are performed if the user has selected them. The dispatch method is then completed.
* solveMB_givenInflowStorage
Solves the mass balance equation when Inflow and Storage are given.
Required Known Slots
• Inflow
• Storage
• Hydrologic Inflow, unless None is selected.
Required Unknown Slots
• Outflow
• Energy
Method Details 
First, the method solves for Pool Elevation using the known Storage and the Elevation Volume Table. Then, if Storage is flagged as a TARGET, the appropriate target calculations are performed. If either the previous timestep’s Pool Elevation or the previous timestep’s Storage is not known, it is calculated. If both the previous timestep’s Pool Elevation and the previous timestep’s Storage are unknown, the dispatch method is exited. Next, the method checks for a linked Canal Object. If a Canal Object is linked and has not yet solved, the dispatch method waits for the Canal to solve before continuing.
The mass balance is carried out as follows:
The mass balance equation may include the effects of evaporation, bank storage, seepage, or precipitation depending on the selected user methods. Inflow in the mass balance equation is the net inflow to the reservoir, including hydrologic inflows, return flows, and diversions if appropriate.
The spill calculation method is then executed followed by the power calculation method. If there are excess outflows from the power calculation method, the spill method is executed again to distribute the excess.
Energy in storage, spilled energy and future value calculations are performed if the user has selected them. The dispatch method is then completed.
* solveMB_givenOutflowStorage
Solves the mass balance equation when Outflow and Storage are known.
Required Known Slots
• Outflow
• Storage
• Hydrologic Inflow, unless None is selected.
Required Unknown Slots
• Inflow
Method Details 
First the dispatch method calculates the Pool Elevation using the Elevation Volume Table and the known Storage. Then the appropriate target calculations are performed if Storage is flagged as a TARGET (if Outflow is flagged MAX CAPACITY a target operation cannot be performed on Storage). If either the previous timestep’s Pool Elevation or the previous timestep’s Storage is not known, it is calculated. If both the previous timestep’s Pool Elevation and the previous timestep’s Storage are unknown, the dispatch method is exited. Next the method checks for a linked Canal Object. If a Canal Object is linked and has not yet solved, the dispatch method waits for it to solve before continuing. If Outflow is flagged MAX CAPACITY, it is set as the sum of the maximum spill and maximum turbine release.
The mass balance is carried out as follows:
The mass balance equation may include the effects of evaporation, bank storage, seepage, or precipitation depending on the selected user methods. The Inflow calculated by the mass balance equation includes the effects of hydrologic inflow, diversion and return flow. The Inflow slot is adjusted accordingly to account for these additional terms.
The spill method is then executed followed by the power calculation method. If Energy is input, the power release method is executed instead of the power calculation method. After Turbine Release has been calculated, the spill method may be executed again if there are excess outflows.
Energy in storage, spilled energy and future value calculations are performed if the user has selected them. The dispatch method is then completed.
* solveMB_givenInflowOutflow
Solves the mass balance equation when Inflow and Outflow are known.
Required Known Slots
• Inflow
• Outflow
• Hydrologic Inflow, unless None is selected.
Required Unknown Slots
• Storage
Method Details 
First, the previous timestep’s Pool Elevation and Storage are checked. If either the previous timestep’s Pool Elevation or the previous timestep’s Storage is not known, it is calculated. If both the previous timestep’s Pool Elevation and the previous timestep’s Storage are unknown, the dispatch method is exited. If the Canal object is linked to the reservoir and has not yet solved, the dispatch method is exited and waits for the Canal to solve before continuing.
If Outflow is flagged MAX CAPACITY, it is solved for by the function getMaxOutGivenIn(). This function uses a convergence algorithm; see “Reservoir Convergence” for details. The Outflow slot is set equal to the computed maximum outflow value.
If the Outflow slot is set by the Surcharge Release flag, the surcharge release is computed and the Outflow slot is set equal to surcharge release for all timesteps in the forecast period (the surcharge release methods compute a surcharge release forecast). See “Description of Logic” in USACE‑SWD Modeling Techniques for additional information on dispatching when using the Surcharge Release Flag.
The mass balance is then carried out as follows:
The mass balance equation may include the effects of evaporation, bank storage, seepage, or precipitation depending on the selected user methods. The inflow term includes the effects of hydrologic inflow, diversion and return flow. Since the evaporation, bank storage, seepage and precipitation terms depend upon the Storage value, the mass balance solution is an iterative process; see the following Note. Pool Elevation is calculated using the Elevation Volume Table and the calculated Storage value.
If the Outflow is less than zero, the method is exited.
The spill method is then executed followed by the power calculation method. If Energy is input, the power release method is executed instead of the power calculation method. After Turbine Release has been calculated, the spill method may be executed again if there are excess outflows.
Energy in storage, spilled energy and future value calculations are performed if the user has selected them. The dispatch method is then completed.
Note:  In specific cases when Storage is very close to zero, the iterative mass balance solution will follow one of two possible processes. The first process allows the loop to iterate in the negative storage range before final convergence. Convergence in this situation is typically quite rapid, and in instances when the final storage is, in fact, negative, an error is posted stating that the outflow is too large to be physically possible. This process is invoked if an additional row is appended to the Elevation Volume Table specifying a negative storage value within which the loop can iterate. If specifying and allowing negative storage values in the iteration is not desired, no negative storage value should be appended to the Elevation Volume Table. In this second process, the algorithm uses storage equals zero whenever it is in the negative storage range. If the outflow is really too great to be physically possible, the algorithm will keep iterating until it reaches maximum iterations. If this happens, RiverWare does a final mass balance check at the storage equals zero point and posts an error stating that the outflow is too large.
* solveMB_givenEnergyInflow
Solves the mass balance equation when Energy and Inflow are given.
Required Known Slots
• Inflow
• Energy
• Hydrologic Inflow, unless None is selected.
Required Unknown Slots
• Storage
Method Details 
First, the previous timestep’s Pool Elevation and Storage are checked. If either the previous timestep’s Pool Elevation or the previous timestep’s Storage is not known, it is calculated. If both the previous timestep’s Pool Elevation and the previous timestep’s Storage are unknown, the dispatch method is exited. If the Canal object is linked and has not yet solved, the dispatch method is exited and waits for the Canal to solve before continuing. Then the selected spill and tailwater methods are executed. The selected power release method is executed and Outflow is set as Turbine Release plus Spill.
The mass balance equation used to solve for Storage is as follows:
The mass balance equation may include the effects of evaporation, bank storage, seepage, or precipitation depending on the selected user methods. The inflow term includes the effects of hydrologic inflow, diversion and return flow. Since the evaporation, bank storage, seepage and precipitation terms depend upon the Storage value, the mass balance solution is an iterative process; see the following Note. Pool Elevation is then calculated using the Elevation Volume Table and the calculated Storage value.
An iterative process is then executed in which the storage solution described above iterates within another iterative loop which solve for Outflow. When a new Storage value is calculated it is used to recompute Spill, Operating Head, and Turbine Release. Outflow is then set as the sum of Spill and Turbine Release. The iteration process continues until the solution stabilizes. When the iterations are complete, the power calculation method is executed.
Energy in storage, spilled energy and future value calculations are performed if the user has selected them. The dispatch method is then completed.
Note:  In specific cases when Storage is very close to zero, the iterative solution for Storage will follow one of two possible processes. The first process allows the loop to iterate in the negative storage range before final convergence. Convergence in this situation is typically quite rapid, and in instances when the final storage is, in fact, negative, an error is posted stating that the outflow is too large to be physically possible. This process is invoked if an additional row is appended to the Elevation Volume Table specifying a negative storage value within which the loop can iterate. If specifying and allowing negative storage values in the iteration is not desired, no negative storage value should be appended to the Elevation Volume Table. In this second process, the algorithm uses storage equals zero whenever it is in the negative storage range. If the outflow is really too great to be physically possible, the algorithm will keep iterating until it reaches maximum iterations. If this happens, RiverWare does a final mass balance check at the storage equals zero point and posts an error stating that the outflow is too large.
* solveMB_givenEnergyStorage
Solves the mass balance equation when Energy and Storage are known.
Required Known Slots
• Energy
• Storage
• Hydrologic Inflow, unless None is selected.
Required Unknown Slots
• Inflow
Method Details 
First, the method calculates Pool Elevation using the Elevation Volume Table and the known Storage value. If Storage is flagged as a TARGET, the reservoir is overdetermined and a RiverWare error is posted and the run terminates. If either the previous timestep’s Pool Elevation or the previous timestep’s Storage is not known, it is calculated. If both the previous timestep’s Pool Elevation and the previous timestep’s Storage are unknown, the dispatch method is exited. If the Canal object is linked and has not yet solved, the dispatch method is exited and waits for the Canal to solve before continuing. Spill is then calculated according to the user specified method. The evaporation, bank storage, and seepage calculations are then performed.
An iterative process is then used to calculate Outflow. The Tailwater method is executed to solve for operating head. The value of operating head is used to determine the Turbine Release from the user selected power release method. Outflow is then set as the sum of Turbine Release and Spill. This process is then repeated until the value of Outflow converges.
Inflow is then calculated from the mass balance equation as follows:
The mass balance equation may include the effects of evaporation, bank storage, seepage, or precipitation depending on the selected user methods. The inflow term calculated by the mass balance equation includes the effects of hydrologic inflow, diversion and return flow. The Inflow slot is adjusted accordingly to account for these additional terms.
Power, Energy in storage, spilled energy and future value calculations are performed if the user has selected them.
* solveMB_givenEnergyHW
Solves the mass balance equation when Energy and headwater (Pool Elevation) are known.
Required Known Slots
• Energy
• Hydrologic Inflow, unless None is selected.
Required Unknown Slots
• Storage
• Inflow
Method Details 
First the Storage is computed using the Elevation Volume Table and the known Pool Elevation. If Pool Elevation is flagged as a TARGET, the reservoir is overdetermined and a RiverWare error is posted and the run terminates. If either the previous timestep’s Pool Elevation or the previous timestep’s Storage is not known, it is calculated. If both the previous timestep’s Pool Elevation and the previous timestep’s Storage are unknown, the dispatch method is exited. If the Canal object is linked and has not yet solved, the dispatch method is exited and waits for the Canal to solve before continuing. Spill, evaporation, bank storage and seepage are then calculated according to the user specified methods.
An iterative process is used to calculate Outflow. The Tailwater method is executed to solve for operating head. The value of operating head is used to determine the Turbine Release from the user selected poser release method. Outflow is then set as the sum of Turbine Release and Spill. This process is then repeated until the value of Outflow converges.
Inflow is then calculated from the mass balance equation as follows:
The mass balance equation may include the effects of evaporation, bank storage, seepage, or precipitation depending on the selected user methods. The inflow term calculated by the mass balance equation includes the effects of hydrologic inflow, diversion and return flow. The Inflow slot is adjusted accordingly to account for these additional terms.
Power, Energy in storage, spilled energy and future value calculations are performed if the user has selected them. The dispatch method is then completed.
* solveMB_givenInflowRelease
This dispatch method executes when the following dispatch conditions are met.
Required Known Slots
• Inflow
• Hydrologic Inflow, unless None is selected.
Required Unknown Slots
• Energy
• Storage
• Outflow
Method Details 
First, the previous timestep’s Pool Elevation and Storage are checked. If either the previous timestep’s Pool Elevation or the previous timestep’s Storage is not known, it is calculated. If both the previous timestep’s Pool Elevation and the previous timestep’s Storage are unknown, the dispatch method is exited. The dispatch method then checks if a Canal Object is linked. If it is linked, a RiverWare error is flagged and the run terminates. The Canal object cannot be solved with this dispatch method. A check is also performed to see if Spill is input. If Spill is input, a RiverWare error is posted and the run terminates. Only Regulated Spill and Bypass may be input for this method.
If the Turbine Release is flagged Unit Values (U), the Unit Turbine Release subslots are summed to calculate and set the Turbine Release slot. If all the Unit Turbine Release slots are NaN, an error is issued. If the Unit Turbine Release slot is not visible because the Unit Power Table method is not selected, an error is issued.
If there is an unregulated spillway crest (because an unregulated spill method is selected) the method computes the upper limit for unregulated spill to prevent spilling too much water to drop the reservoir below the crest. Typically, this limit is computed as the volume of water above the crest converted to a flow. See the Unregulated Spill method for details.
Then mass balance occurs. The Outflow is computed as the sum of turbine release and spill inputs (if any) according to the user selected methods and the following equation:
Storage is solved as follows:
The mass balance equation may include the effects of evaporation, bank storage, seepage, or precipitation depending on the selected user methods. The inflow term includes the effects of hydrologic inflow, diversion and return flow. Since the evaporation, bank storage, seepage and precipitation terms depend upon the Storage value, the mass balance solution is an iterative process. (See note below.) Pool Elevation is calculated using the Elevation Volume Table and the calculated Storage value.
After the Storage is computed, mass balance process is compete, the spill calculation method is executed. Unregulated Spill takes up any error in the solution process. For this reason, it may not conform to the Unregulated Spill Table.
Power, Energy in Storage, spilled energy and future value calculations are performed if the user has selected them. The dispatch method is then completed.
Note:  In special cases when Storage is very close to zero, the iterative mass balance solution will follow one of two possible processes. The first process allows the loop to iterate in the negative storage range before final convergence. Convergence in this situation is typically quite rapid, and in instances when the final storage is, in fact, negative, an error is posted stating that the outflow is too large to be physically possible. This process is invoked if an additional row is appended to the Elevation Volume Table specifying a negative storage value within which the loop can iterate. If specifying and allowing negative storage values in the iteration is not desired, no negative storage value should be appended to the Elevation Volume Table. In this second process, the algorithm uses storage equals zero whenever it is in the negative storage range. If the outflow is really too great to be physically possible, the algorithm will keep iterating until it reaches maximum iterations. If this happens, RiverWare does a final mass balance check at the storage equals zero point and posts an error stating that the outflow is too large.
* solveMB_givenInflowOutflowStorage
Solves for Hydrologic Inflow when the Solve Hydrologic Inflow method is selected. Inflow, Outflow, and Storage must be known for this method to solve.
Required Known Slots
• Outflow
• Storage
• Inflow
Required Unknown Slots
Method Details 
First the method checks if Outflow is flagged MAX CAPACITY. The MAX CAPACITY flag cannot be used when both Inflow and Storage are known. Pool Elevation is then calculated using the Elevation Volume Table and the known Storage value. If either the previous timestep’s Pool Elevation or the previous timestep’s Storage is not known, it is calculated. If both the previous timestep’s Pool Elevation and the previous timestep’s Storage are unknown, the dispatch method is exited. If the Storage slot is flagged TARGET a RiverWare error is posted and the run terminates. If the Canal object is linked and has not yet solved, the dispatch method is exited and waits for the Canal to solve before continuing. The user selected evaporation, bank storage, and seepage methods are then executed.
The the hydrologic inflow is found with the following equation (all values are converted to flows):
This equation may or may not contain other elements reflecting the user method choices (these include Evaporation (+), Precipitation(-), Seepage(+), Bank storage(+), Return Flow(‑), Diversion (+), and Flow TO/FROM Pumped Storage). Spill and release are then found according to the user selected methods.
If Outflow is determined to be less than zero, the method is exited.
The spill method is then executed followed by the power calculation method. If Energy is input, the power release method is executed instead of the power calculation method. After Turbine Release has been calculated, the spill method may be executed again if there are excess outflows.
Energy in storage, spilled energy and future value calculations are performed if the user has selected them.
* solveMB_givenInflowOutflowHW
Solves for Hydrologic Inflow when the Solve Hydrologic Inflow method is selected. Inflow, Outflow, and headwater (Pool Elevation) must be known for this method to solve.
Required Known Slots
• Outflow
• Inflow
Required Unknown Slots
• Storage
Method Details 
First the method checks if Outflow is flagged MAX CAPACITY. The MAX CAPACITY flag cannot be used when both Inflow and Storage are known. Storage is then calculated using the Elevation Volume Table and the known Pool Elevation value. If either the previous timestep’s Pool Elevation or the previous timestep’s Storage is not known, it is calculated. If both the previous timestep’s Pool Elevation and the previous timestep’s Storage are unknown, the dispatch method is exited. If the Pool Elevation slot is flagged TARGET, a RiverWare error is posted and the run terminates. If a Canal Object is linked and has not yet solved, the dispatch method is exited and waits for the Canal to solve before continuing. The user selected evaporation, bank storage, and seepage methods are then executed.
The hydrologic inflow is found with the following equation (all values are converted to flows):
This equation may or may not contain other elements reflecting the user method choices (these include Evaporation (+), Precipitation(-), Seepage(+), Bank storage(+), Return Flow(‑), Diversion (+), and Flow TO/FROM Pumped Storage).
If Outflow is determined to be less than zero, the method is exited.
The spill method is then executed followed by the power calculation method. If Energy is input, the power release method is executed instead of the power calculation method. After Turbine Release has been calculated, the spill method may be executed again if there are excess outflows.
Energy in storage, spilled energy and future value calculations are performed if the user has selected them. The dispatch method is then completed.
* Outflow Equals Sum of Inflows
This dispatch method is only available when the Pass Inflows method is selected (see “Pass Inflows”). It has the following dispatch conditions.
Required Known Slots
• Inflow
Required Unknown Slots
• Outflow
Method Details 
This method uses the following process.
1. An error is issued if any of the following are linked, specified as inputs, and/or are not zero:
– Canal Flow,
– Diversion,
– Flow TO Pumped Storage,
– Flow FROM Pumped Storage
– Seepage
2. An error is issued if:
– Any flags are set on Outflow (an over-determination error will be issued).
– Water Quality is enabled on this reservoir
3. Inflow Sum and Total Inflows are computed as usual; see “Total Inflows” for details.
4. The following equation is solved.
5. Then the dispatch method finishes successfully and exits.
Note:  Hydrologic Inflow disaggregation and forecasting are performed at the beginning of the run or the timestep. Therefore, these inflows to the reservoir are included in the outflow. See “Incremental Hydrologic Inflows on Subbasin” and “Generate Forecast Hydrology” for details.
None of the other physical process methods are executed, however, even though they may have method selections and slots visible. These include the following:
– Precipitation and Evaporation
– Spill
– Energy in Storage
– Seepage
– Bank Storage
– Tailwater
– Operating Level
– Power
 
Revised: 11/11/2019