skip to main content
Diversion Object
Objects and Methods
Diversion Object
A Diversion Object diverts water from either a Reach or a Reservoir. The diverted water flows through the Diversion Object and into either an AggDistributionCanal, a WaterUser, a Reach, or a Reservoir. If either a WaterUser or an AggDistributionCanal is used, the values in the Diversion (or Delivery) Requested slot should be linked to the Diversion Request slot on the Diversion Object. If either a Reach or Reservoir is linked to the downstream end of the Diversion Object, the Diversion Request slot must be input on the Diversion Object itself.
General Slots
Slots that always appear for this object
Available For Diversion
Type: SeriesSlot
Units: FLOW
Description: amount of flow that can be diverted from an upstream Reach or Reservoir
Information:  
I/O: Optional; can be calculated or set by propagation across a link
Diversion
Type: SeriesSlot
Units: FLOW
Description: amount diverted from the Reach or Reservoir
Information:  
I/O: Output only
Diversion Request
Type: SeriesSlot
Units: FLOW
Description: diversion requested from an upstream Reach or Reservoir
Information: Can be set as an input, particularly if there is a Reach or Reservoir linked to the downstream end of the Diversion Object. If there is an AggDistributionCanal or WaterUser linked to the downstream end, the Diversion Request slot on the Diversion Object should be linked to either the Total Delivery Request slot on the AggDistributionCanal or the Diversion Request slot on the WaterUser.
I/O: Optional; may be input, calculated or set by propagation across a link.
Diversion Shortage
Type: Series Slot
Units: flow
Description: The amount that the Diversion Request is shorted
Information: Computed as the Diversion Request minus the Diversion
I/O: Output only
User Methods
Diversion Object Solution Direction
The methods in this category are used to add slots and control the available dispatch methods. They perform no calculations themselves.
* Solve for Outflow
If this method is selected, the Diversion object will solve for its Outflow given Diversion or Diversion Requested.
Slots Specific to This Method
Outflow
Type: Series Slot
Units: FLOW
Description: outflow from the Diversion Object
Information:  
I/O: Output only
* Solve Given Outflow
If this method is selected, the Diversion Object will solve for Diversion when Outflow is known. In this configuration, the Diversion Object can have multiple outflows using links to the Multi Outflow slot.
Slots Specific to This Method
Multi Outflow
Type: Multi Slot
Units: flow
Description: outflow from the Diversion Object
I/O: Can be input or set via link
Available Flow
This category contains the calculations necessary to set Available for Diversion based on either available flow in the Reach/Reservoir or on head/elevation data.
* None
This is the default user method for the Available Flow category. It performs no calculations. If it is selected an error will be posted when the model is run. The user must select either Available Flow Diversion, Gravity Diversion, or Pumped Diversion for the model to run.
* Available Flow Diversion
Available for Diversion is set through a link to the Available for Diversion slot on the Reach or Reservoir. The user can also input Available for Diversion if needed.
Slots Specific to This Method
Max Diversion
Type: TableSlot
Units: FLOW
Description: The maximum amount of water that can pass through the Diversion Object
Information:  
I/O: Optional
Min Diversion
Type: TableSlot
Units: FLOW
Description: The lower limit on the amount of water that can be requested.
Information: Can be used if the Diversion Requests are very small and a particular flow rate is required for water to pass through the Diversion Object.
I/O: Optional
The values in Available for Diversion either propagate across a link from the Reach or Reservoir or are input by the user. Therefore, no calculations are performed in this method.
* Gravity Diversion
The Gravity Diversion method calculates Available for Diversion based on the Diversion Intake Elevation, Diversion Base Elevation, and Gravity Head Flow Table.
Slots Specific to This Method
Diversion Base Elevation
Type: TableSlot
Units: LENGTH
Description: elevation of the bottom of the intake of the Diversion Object
Information:  
I/O: Required input
Diversion Intake Elevation
Type: SeriesSlot
Units: LENGTH
Description: water surface elevation at the intake of the Diversion Object
Information:  
I/O: Required
Gravity Head Flow Table
Type: TableSlot
Units: LENGTH vs. FLOW
Description: defines the relationship between Diversion Head and Max Flow into the Diversion Object
Information: Values must be input to define the relationship between Effective Diversion Head and Flow into the Diversion Object if the Gravity Diversion method is selected.
I/O: Required input
The calculations used to determine Available for Diversion are as follows:
The value of Diversion Head is then used in an interpolation method to find the corresponding flow rate from the Gravity Head Flow Table. Available for Diversion is then set to the value returned from the interpolation method.
* Pumped Diversion
The Pumped Diversion method calculates Available for Diversion based on the Diversion Intake Elevation, Diversion Base Elevation, and Pumped Head Flow Table.
Slots Specific to This Method
Diversion Base Elevation
Type: TableSlot
Units: LENGTH
Description: elevation of the bottom of the intake of the Diversion Object
Information:  
I/O: Required input
Diversion Intake Elevation
Type: SeriesSlot
Units: LENGTH
Description: water surface elevation at the intake of the Diversion Object
Information:  
I/O: Required
Pumped Head Flow Table
Type: TableSlot
Units: LENGTH vs. FLOW
Description: defines the relationship between Diversion Head and Max Flow into the Diversion Object
Information:  
I/O: Required input
The calculations used to determine Available for Diversion are as follows:
The value of Diversion Head is then used in an interpolation method to find the corresponding flow rate from the Pumped Head Flow Table. Available for Diversion is then set to the value returned from the interpolation method.
Diversion Request
Used to specify how Diversion Request is calculated.
* Input Diversion Request
This method is used if the user wishes to input the Diversion Request. No calculations are performed in this method and there are no slots specifically associated with this method.
Slots Specific to This Method
None
* Percent of Available
Used to calculate Diversion Request as a percentage of the available water.
Slots Specific to This Method
Percent of Available to Divert
Type: SeriesSlot
Units: fraction
Description: the percentage of the available water to be diverted
Information: Must be between 0% and 100%
I/O: Required input
* Periodic Diversion Request
This method is used to specify the Diversion Request as a function of date/season using a periodic slot.
Slots Specific to This Method
Periodic Diversion Request
Type: Periodic Slot
Units: flow
Description: The diversion request as a function of date/season
Information: The Diversion Request is computed at the beginning of each timestep using the current date to look up the value from this slot.
I/O: Required input
The Periodic Diversion Request method executes at the beginning of the run. Each timestep in the run is used to look up a value in the Periodic Diversion Request slot. The computed value is set in the Diversion Request slot.
* Reservoir Level Lookup
The Reservoir Level Lookup method is used to compute the Diversion Request as a function of the date/season and the operating level of a specified reservoir.
Slots Specific to This Method
Level vs Diversion Request
Type: Periodic Slot
Units: flow
Description: The diversion request as a function of reservoir level and date/season
Information: Each column corresponds to a reservoir’s operating level. For each operating level, the diversion request is specified for each date range in the periodic slot.
I/O: Required input
Diversion Request Reservoir
Type: List Slot
Units: none
Description: The reservoir used to compute the diversion request
Information: The previous timestep operating level of this reservoir is used to look up the diversion request in the Level vs Diversion Request slot.
I/O: Required input
Forecast Period
Type: Scalar
Units: none
Description: The forecast period is a number of timesteps, including the current simulation timestep, that is used in the algorithms for calculating forecasted hydrology, regulation discharge and flood releases. This can be propagated from a computational subbasin of which the control point is a member.
Information: This slot must be input and greater than or equal to 1. If a Forecast Period is not necessary and you wish to only consider the current timestep, input a value of 1.
Information: Required Input
Note:  If the specified reservoir is disabled and is set to Pass Inflows, no request lookup is possible. See “Diversions Based on Disabled Reservoirs” in USACE‑SWD Modeling Techniques for details on the behavior in this situation.
The Reservoir Level Lookup method will execute at the beginning of each timestep. For each timestep (t) in the forecast period, the Diversion Request Reservoir’s previous timestep’s (current timestep - 1) operating level and the forecast timestep’s date (t) will be used to look up the diversion request value in the Level vs Diversion Request slot. This value is set on the Diversion Request slot. The Diversion is limited by the Maximum Diversion value. Because the method uses the same operating level (from the previous timestep) for all timesteps in the forecast period, it is only an approximation but allows the object to solve throughout the forecast period.
Diversion Pump Energy
The Diversion Pump Energy category is used to determine the Energy and Total Energy Cost based on the Diversion Intake Elevation, Outflow Elevation, Diversion, Pump Efficiency, and cost per Unit Energy. This method category is only available if Pumped Diversion is selected in the Available Flow category.
* None
This is the default method. It performs no energy calculations.
* Energy Equation and Cost
The Energy Equation and Cost method calculates Energy Consumption and Total Energy Cost. This method is only available when Pumped Diversion is selected in the Available Flow category.
Slots Specific to This Method
Cost per Unit Energy
Type: TableSlot
Units: $per ENERGY
Description: cost of each unit (MWH) of energy generated or consumed by the Diversion Object
Information: Used to determine the monetary value of the energy consumed by the Diversion Object.
I/O: Required input
Energy Consumption
Type: SeriesSlot
Units: ENERGY
Description: energy consumed by the Diversion Object
Information:  
I/O: Output only
Outflow Elevation
Type: TableSlot
Units: LENGTH
Description: water surface elevation at the outflow of the Diversion Object
Information:  
I/O: Required input
Pump Efficiency
Type: TableSlot
Units: DECIMAL
Description: efficiency of the pump in the Diversion Object
Information: Used in the calculation of the amount of energy consumed by the Diversion Object.
I/O: Required input
Total Energy Cost
Type: SeriesSlot
Units: $
Description: the monetary value of the energy consumed by the Diversion Object
Information:  
I/O:  
The engineering algorithm used in this method is described below.
Dispatch Methods
Used to solve for Diversion and call the user method functions. The active dispatch method(s) are dependent upon the user method selected in the Diversion Object Solution Direction category, the Available Flow category, and the Diversion Request category.
* solveMB_givenDivHead
Solves for Diversion when Gravity Diversion or Pumped Diversion is selected in the Available Flow category and Input Diversion Request is selected in the Diversion Request category. The Solve for Outflow method must also be selected.
Required Knowns
Required Unknowns
• None
If the Diversion Intake Elevation is less than or equal to Diversion Base Elevation, Available For Diversion, Diversion, and Outflow are set to zero. In this case, the water surface is at or below the Diversion Base Elevation so it is impossible for water to enter the Diversion Object.
If the Diversion Intake Elevation is greater than the Diversion Base Elevation, Available for Diversion is calculated based on the method selected in the Available Flow category. Then, if Available for Diversion is less than Diversion Request, Diversion is set equal to Available for Diversion. Otherwise, Diversion is set equal to Diversion Request. Outflow is then set equal to Diversion. Finally, the Diversion Pump Energy method, if selected, is executed.
* solveMB_givenAvailForDiv
Solves for Diversion when Available Flow Diversion is selected in the Available Flow category and Input Diversion Request is selected in the Diversion Request category. The Solve for Outflow method must also be selected.
Required Knowns
Required Unknowns
• None
First, the user method selected in the Available Flow category is executed. Then a temporary variable, tempRequest, is assigned the value of Diversion Request or, if Diversion Request is less than the Min Diversion Request, it is assigned the value of Min Diversion. Diversion is then set as the minimum value of tempRequest, Available For Diversion, and Max Diversion.
Outflow is set equal to Diversion.
* solveMB_givenDivHeadPercent
Solves for Diversion when Gravity Diversion or Pumped Diversion is selected in the Available Flow category and Percent of Available is selected in the Diversion Request category. The Solve for Outflow method must also be selected.
Required Knowns
Required Unknowns
If the Diversion Intake Elevation is less than or equal to Diversion Base Elevation, Available For Diversion, Diversion, and Outflow are set to zero. In this case, the water surface is at or below the Diversion Base Elevation so it is impossible for water to enter the Diversion Object.
If the Diversion Intake Elevation is greater than the Diversion Base Elevation, Available for Diversion is calculated based on the method selected in the Available Flow category. Then, if Available for Diversion is less than Diversion Request, Diversion is set equal to Available for Diversion. Otherwise, Diversion is set equal to Diversion Request. Outflow is then set equal to Diversion. Finally, the Diversion Pump Energy method, if selected, is executed.
* solveMB_givenAvailablePercent
Solves for Diversion when Available Flow Diversion is selected in the Available Flow category and Percent of Available is selected in the Diversion Request category. The Solve for Outflow method must also be selected.
Required Knowns
Required Unknowns
First, the user method selected in the Available Flow category is executed. Then Diversion Request is calculated according to the selected Diversion Request method. Then a temporary variable, tempRequest, is assigned the value of Diversion Request or, if Diversion Request is less than the Min Diversion Request, it is assigned the value of Min Diversion. Diversion is then set as the minimum value of tempRequest, Available For Diversion, and Max Diversion.
Outflow is set equal to Diversion.
* solveMB_givenOutflow
This method solves for Diversion and Diversion Request when Outflow is known. This dispatch method is only available when the user has selected the Solve Given Outflow method in the Diversion Object Solution Direction category. Also, the Input Diversion Request method must be selected in the Diversion Request category and the Available Flow Diversion method must be selected in the Available Flow category.
Required Knowns
Required Unknowns
This dispatch method sets Diversion and Diversion Request equal to the known Multi Outflow value. The Diversion is also constrained by the Min Diversion and Max Diversion values.
 
Revised: 06/03/2019