skip to main content
Objects and Methods : Water User : User Methods : Diversion and Depletion Request
Diversion and Depletion Request
This user method category is common to all three linking structures. The methods available in this category are used to calculate the Water User’s Diversion Requested and Depletion Requested. These slots are either set by user input or calculated based on the methods described below.
Note:  These methods are executed at different times depending on the method, as follows:
• Reservoir Level Lookup is executed at the beginning of the timestep.
• Irrigation Requests with Soil Moisture is executed partially at the beginning of the timestep and partially in the dispatch method.
• All other methods are executed at beginning of run. As a result, any input data is used in the calculations as described. If you plan to use a rule to set either Diversion Requested or Depletion Requested, the other one will not be calculated using these methods as it will not be known at the beginning of the run. In this situation, the rule must set Diversion Requested to allow the water user to dispatch and solve. Depletion Requested, if not specified, is set equal to Diversion Requested for internal calculations but will not be set on the slot.
* Input Requests
This method is common for all linking structures. It is used when the user wants to manually set the values of Diversion Requested and/or Depletion Requested. This is the default method for the Diversion and Depletion Request category.
Slots Specific to This Method
 Minimum Diversion Request
Type: Table Slot
Units: Flow
Description: Minimum possible flow rate needed to meet depletion requests
Information: The Minimum Diversion Request can be based on either physical, legal, or environmental restrictions, and so on. This is only used if the Depletion Request is non-zero.
I/O: Optional.
Method Details  
No calculations are performed with this method. The user can specify either Diversion Request or Depletion Requested or both. If only Diversion Requested is known, Depletion Requested is set equal to Diversion Requested. If only Depletion Requested is known, Diversion Requested is set equal to Depletion Requested. If Depletion Requested and Minimum Diversion Request are known and Diversion Requested is not, Diversion Requested is set equal to the maximum of Depletion Requested and Minimum Diversion Requested.
See the note in Diversion and Depletion Request for details on how this method behaves in Rulebased Simulation.
* Input Diversion Requests
The Input Diversion Requests method computes Depletion Requested based on an input Diversion Requested.
Slots Specific to This Method
 Minimum Efficiency
Type: Series Slot
Units: Fraction
Description: Minimum amount of consumed flow per unit diverted flow
Information: Expressed as a fraction
I/O: Required input
Method Details  
When Diversion Requested is input, Depletion Requested is computed as follows:
    
See the note in Diversion and Depletion Request for information on how this method behaves in Rulebased Simulation.
* Input Depletion Requests
The Input Depletion Requests method computes Diversion Requested based on an input Depletion Requested.
Slots Specific to This Method
 Minimum Efficiency
Type: Series Slot
Units: Fraction
Description: Minimum amount of consumed flow per unit diverted flow
Information: Expressed as a fraction
I/O: Required input
 Maximum Flow Capacity
Type: Table Slot
Units: Flow
Description: Maximum possible flow rate through the distribution system
Information: The Maximum Flow Capacity can be based on either physical, legal, or environmental restrictions, and so on.
I/O: Required input
Method Details  
When Depletion Requested is input, Diversion Requested is computed as follows:
    
See the note in Diversion and Depletion Request for information on how this method behaves in Rulebased Simulation.
* Irrigation Requests
This user method uses irrigation data to determine Depletion Requested and/or Diversion Requested if they are not input. Depletion Requested is based on the area to be irrigated, evapotranspiration rate, and incidental rate loss. Diversion Requested is then calculated from the Depletion Requested and the Minimum Efficiency.
Slots Specific to This Method
 Evapotranspiration Rate
Type: Series Slot
Units: Length Vs Time
Description: Rate of water loss due to evaporation and transpiration
Information:  
I/O: Optional; required if Depletion Requested is not input.
 Incidental Loss Rate
Type: Table Slot
Units: Fraction
Description: Losses in the water distribution system
Information: Expressed as a fraction of the flow.
I/O: Optional; required if Depletion Requested is not input.
 Irrigated Area
Type: Series Slot
Units: Area
Description: Surface area of the land to be irrigated
Information:  
I/O: Optional; required if Depletion Requested is not input.
 Maximum Efficiency
Type: Table Slot
Units: Fraction
Description: Maximum consumed flow per unit diverted flow
Information: Expressed as a fraction.
I/O: Required input
 Maximum Flow Capacity
Type: Table Slot
Units: Flow
Description: Maximum possible flow rate through the distribution system
Information: The Maximum Flow Capacity can be based on either physical, legal, or environmental restrictions, and so on.
I/O: Required input
 Minimum Diversion Request
Type: Table Slot
Units: Flow
Description: Minimum possible flow rate needed to meet depletion requests
Information: The Minimum Diversion Request can be based on either physical, legal, or environmental restrictions, and so on. This is only used if the Depletion Request is non-zero.
I/O: Optional.
 Minimum Efficiency
Type: Series Slot
Units: Fraction
Description: Minimum consumed flow per unit diverted flow
Information: Expressed as a fraction.
I/O: Required input
Method Details  
If not input, the Depletion Requested is calculated as follows:
    
Then, Diversion Requested (if it is not specified by the user) is calculated as follows:
    
After the Diversion Requested and Depletion Requested are initially calculated, Diversion Requested must be checked against the Maximum Flow Capacity. If the calculated value for Diversion Requested is less than the Maximum Flow Capacity, the Diversion Requested slot is set to the calculated value. If the calculated Diversion Requested is greater than the Max Flow Capacity, it is set to the Maximum Flow Capacity.
Note:  User input overrides all calculated values. If the user specifies a Diversion Requested which is greater than the Maximum Flow Capacity, an error is posted and the run terminates.
Diversion Requested must also be checked against the Minimum Diversion Request (if specified by user) If the calculated value for Diversion Requested is greater than the Minimum Diversion Request, the Diversion Requested slot is set to the calculated value. If the calculated Diversion Requested is less than the Minimum Diversion Request, it is set to the Minimum Diversion Request.
Note:  User input overrides all calculated values. If the user specifies a Diversion Requested which is less than the Minimum Diversion Request (if specified), an error is posted and the run terminates.
The Depletion Requested divided by the Diversion Requested (i. e. the Water User’s efficiency) is compared to the Maximum Efficiency allowed on the Water User. If the calculated value is less than the Maximum Efficiency, Depletion Requested is unchanged. If the calculated efficiency (Depletion Requested/Diversion requested) is greater than the Maximum Efficiency (and Depletion Requested is not input by the user), Depletion Requested is reset to the value of Diversion Requested multiplied by the Maximum Efficiency. If the calculated efficiency is greater than the Maximum Efficiency and Depletion Requested is input, an error is posted and the run terminates.
See the note in Diversion and Depletion Request for information on how this method behaves in Rulebased Simulation.
* Irrigation Requests with Soil Moisture
This method uses irrigation data to determine Diversion and Depletion Requests based on the irrigated acreage, evapotranspiration rate, and soil moisture. The Soil Moisture Demand and available soil moisture is also computed. This method is available for all Agg Diversion Site linking structure and for standalone water users.
Note:  You must also select the Proportional Shortage with Soil Moisture, Proportional Shortage with Soil Moisture, or Variable Efficiency with Soil Moisture method. See Variable Efficiency with Soil Moisture for details.
In addition, when this method is selected, the following dispatch methods are available based on the link structure:
• Standalone Water User or Water User in a No Structure Agg Diversion Site:
– Solve Standalone given Depletion Requested
– Solve Standalone given Diversion
– Water User in a Sequential Agg Diversion Site:
– Solve Sequential given Depletion Requested
– Solve Sequential given Diversion
• Water User in a Lumped Agg Diversion Site: This method cannot be selected. The Water user doesn’t dispatch in a Lumped Agg Diversion Site.
Figure 28.1 is a conceptual diagram of all of the components possible to model Soil Moisture on the Water User.
• Items in blue are default flow values.
• Pink indicates optional gains/losses.
• Green is supplemental water. See Supplement Diversion including Soil Moisture for details on supplemental flow.
• Brown indicates how the return flows can be split and/or routed.
Note:  Not all values shown are separate slot values.
Figure 28.1   
Slots Specific to This Method
 Evapotranspiration Rate
Type: Series Slot
Units: Length Vs Time
Description: Rate of water loss due to evaporation and transpiration
Information:  
I/O: Specified according to the selected method in the Irrigation Acreage and Evapotranspiration Rates category. See Irrigation Acreage and Evapotranspiration Rates.
 Incidental Loss Rate
Type: Table Slot
Units: Fraction
Description: Losses in the water distribution system.
Information: Expressed as a fraction of the flow.
I/O: Optional; if not specified, zero is assumed.
 Irrigated Area
Type: Series Slot
Units: Area
Description: Surface area of the land to be irrigated
Information:  
I/O: Specified according to the selected method in the Irrigation Acreage and Evapotranspiration Rates category. See Irrigation Acreage and Evapotranspiration Rates.
 Maximum Flow Capacity
Type: Table Slot
Units: Flow
Description: Maximum possible flow rate through the distribution system
Information: The Maximum Flow Capacity can be based on either physical, legal, or environmental restrictions, and so on.
I/O: Required input
 Minimum Diversion Request
Type: Table Slot
Units: Flow
Description: Minimum possible flow rate needed to meet depletion requests
Information: The Minimum Diversion Request can be based on either physical, legal, or environmental restrictions, and so on. This is only used if the Depletion Request is non-zero.
I/O: Optional.
 Minimum Efficiency
Type: Series Slot
Units: Fraction
Description: Minimum amount of consumed flow per unit diverted flow
Information: Expressed as a fraction.
I/O: Required input
 Diversion Request for Soil Moisture
Type: Series Slot
Units: Flow
Description: Requested diversion explicitly to refill the soil moisture.
Information:  
I/O: Output only
 Diversion Request for Crops
Type: Series Slot
Units: Flow
Description: The requested diversion to meet crop depletion
Information:  
I/O: Output only
 Soil Moisture Future Timesteps
Type: Scalar
Units: No units
Description: Number of timesteps past the current timestep for the calculations should be performed
Information: This must be an integer greater than 0.
I/O: If not specified, the value is set to 1, which indicates that only the current timestep is computed
 Maximum Soil Moisture
Type: Scalar
Units: Length
Description: Effective depth of water that the soil can hold. Conceptually it is the actual depth multiplied by the effective porosity.
Information:  
I/O: Required input
 Maximum Infiltration Rate
Type: Scalar
Units: Velocity (Length per Time)
Description: Maximum depth of water per time (that is, an absorption rate) that can be absorbed by the soil
Information: A valid value must be specified or an error will occur at the beginning of run.
I/O: Required input
 Soil Moisture
Type: Series Slot
Units: Volume
Description: This slot tracks the volume of soil moisture water in the soil at each timestep in the run.
Information: For the initial timestep, this slot must be valid. If this slot is not input, it is computed as the Maximum Soil Moisture times the Irrigated Area at the initial timestep. That is, the soil moisture starts full.
I/O: Typically output for run timesteps.
 Soil Moisture Demand Factor
Type: Series Slot with Periodic Input
Units: Fraction
Description: This slot is used to limit the soil moisture demand
Information:  
I/O: Optional input as either a series or a periodic relationship. If not specified, it is assumed to be 1.
 Soil Moisture Fill Efficiency
Type: Series Slot with Periodic Input
Units: Fraction
Description: Fraction of the flow applied for soil moisture refill that is not absorbed.
Information: For example, if you are only refilling the soil moisture, you may apply 100cfs, but 5cfs is not absorbed, even though max infiltration indicated it could absorb 200cfs. The Soil Moisture Fill Efficiency would be 0.95.
I/O: Optional input, if not input, it is assumed to be 1.0.
 Soil Moisture Demand
Type: Series Slot
Units: Flow
Description: Flow necessary to refill the soil moisture to capacity.
Information:  
I/O: Output only
 Soil Moisture Stress Coefficient
Type: Series Slot
Units: Fraction
Description: This coefficient represents a stress term that can be used to reduce the depletion request when in shortage.
Information:  
I/O: Optional input or set by a rule. If not specified, the value is assumed to be 1.0, but no value is set on the slot. Since this method is executed at the beginning of the timestep, if you wish to set this slot with a rule, the rule must set it at the previous timestep.
 Soil Moisture Gain Loss
Type: Series Slot
Units: Volume
Description: Miscellaneous gain or loss of soil moisture volume during the timestep.
Information: This slot represents and gains (positive) or loss (negative) from the soil moisture. It is used to track the soil moisture volume lost when the irrigated acreage is reduced from the previous timestep. In this case it is a computed output. If the irrigated acreage increases, you may wish to have the new acreage start with some soil moisture (perhaps due to precipitation). In this case, you can input a positive volume that will be added to the Soil Moisture.
I/O: Typically output but can be input
Method Details 
The Irrigation Requests with Soil Moisture method is executed in two parts, the first occurs at the beginning of each controller timestep and then the rest is executed from the dispatch method.
Beginning of Timestep  
Compute the Depletion Requested for all timesteps from the current timestep through the number of Soil Moisture Future Timesteps. This represents the crop demand for each of these timesteps.
    
At the Start of the Dispatch Method  
Recompute the Depletion Requested if any of the pieces have changed (by a rule).
    
Compute the maximum infiltration flow intermediate variable, as follows:
    
Compute the Soil Moisture Gain Loss (if not input or set by a rule)
If the current Irrigated Area is less than the Irrigated Area(t-1), compute as follows:
    
This loss will keep the new irrigated area at its same relatively fullness (at the start of the timestep), the lost water only comes from the area no longer irrigated.
Note:  Soil Moisture Gain Loss can also be input and will be used in the following equation.
Compute the flow necessary to refill the soil moisture back to the maximum (intermediate), as follows:
    
Compute the soil moisture demand, representing the physical constraints on refilling the soil moisture from diverted surface water, as follows:
    
The Depletion Requested (crop demand) is subtracted from the maxInfiltrationFlow as all water applied to the fields must adhere to the max infiltration rate.
Compute the Diversion Request for Soil Moisture as follows:
    
Compute the Diversion Request for Crops as follows:
    
Compute the total Diversion Requested (if not input or set by a rule) as follows:
    
After the Diversion Requested and Depletion Requested are initially calculated, Diversion Requested is checked against the Maximum Flow Capacity. If the calculated value for Diversion Requested is less than the Maximum Flow Capacity, the Diversion Requested slot is set to the calculated value. If the calculated Diversion Requested is greater than the Max Flow Capacity, it is set to the Maximum Flow Capacity.
Note:  User input overrides all calculated values. If the user specifies a Diversion Requested which is greater than the Maximum Flow Capacity, an error is posted and the run terminates.
Diversion Requested must also be checked against the Minimum Diversion Request (if specified by user) If the calculated value for Diversion Requested is greater than the Minimum Diversion Request, the Diversion Requested slot is set to the calculated value. If the calculated Diversion Requested is less than the Minimum Diversion Request, it is set to the Minimum Diversion Request.
Note:  User input overrides all calculated values. If the user specifies a Diversion Requested which is less than the Minimum Diversion Request (if specified), an error is posted and the run terminates.
* Head Gate Sprinkler Requests
Caution:  This method is specific to the San Juan Basin and may not be physically valid in other situations. Take care when using this method.
The Head Gate Sprinkler Requests method uses agricultural data along with data on sprinkler evaporation to determine Depletion Requested and Diversion Requested. The method is very similar to the Irrigation Requests method except that a sprinkler evaporation rate is included in calculating Depletion Requested.
Slots Specific to This Method
 Evapotranspiration Rate
Type: Series Slot
Units: LENGTH/TIME
Description: Rate of water loss due to evaporation and transpiration
Information:  
I/O: Optional; required if Depletion Requested is not input.
 Incidental Loss Rate
Type: Table Slot
Units: Fraction
Description: Losses in the water distribution system
Information: Expressed as a fraction of the flow.
I/O: Optional; required if Depletion Requested is not input.
 Irrigated Area
Type: Series Slot
Units: Area
Description: Surface area of the land to be irrigated
Information:  
I/O: Optional; required if Depletion Requested is not input.
 Maximum Efficiency
Type: Table Slot
Units: Fraction
Description: Maximum amount of consumed flow per unit diverted flow
Information: Expressed as a fraction.
I/O: Required input
 Maximum Flow Capacity
Type: Table Slot
Units: Flow
Description: Maximum possible flow rate through the distribution system
Information: The Maximum Capacity can be based on either physical, legal, or environmental, restrictions, and so on.
I/O: Required input
 Minimum Diversion Request
Type: Table Slot
Units: Flow
Description: Minimum possible flow rate required to meet depletion requests
Information: The Minimum Diversion Request can be based on either physical, legal, or environmental restrictions, and so on. This is only used if the Depletion Request is non-zero.
I/O: Optional.
 Minimum Efficiency
Type: Series Slot
Units: Fraction
Description: Minimum amount of consumed flow per unit diverted flow
Information:  
I/O: Required input
 Sprinkler Evaporation Rate
Type: Table Slot
Units: Fraction
Description: Evaporative losses in the sprinkler mechanism
Information: Expressed as a fraction of the diversion.
I/O: Required input
Method Details  
Initially, the Depletion Requested is calculated as follows (if it is not input):
    
Then, Diversion Requested (if it is not specified by the user) is calculated as follows:
    
After the Diversion Requested and Depletion Requested are initially calculated, the Diversion Requested must be checked against the Maximum Flow Capacity. If the calculated Diversion Requested is greater than the Max Flow Capacity, it is set to the Maximum Flow Capacity. If the calculated value for Diversion Requested is less than the Maximum Flow Capacity, the Diversion Requested slot is set with the calculated value.
Note:  User input overrides all calculated values. If the user specifies a Diversion Requested which is greater than the Maximum Flow Capacity, an error is be posted and the run terminates.
Diversion Requested must also be checked against the Minimum Diversion Request (if specified by user) If the calculated value for Diversion Requested is greater than the Minimum Diversion Request, the Diversion Requested slot is set to the calculated value. If the calculated Diversion Requested is less than the Minimum Diversion Request, it is set to the Minimum Diversion Request.
Note:  User input overrides all calculated values. If the user specifies a Diversion Requested which is less than the Minimum Diversion Request (if specified), an error is posted and the run terminates.
The sprinkler evaporation is applied to the Depletion Requested after the Diversion Requested slot has been set. The initial Depletion Requested is adjusted as follows:
    
The Depletion Requested divided by the Diversion Requested (that is, the Water User’s Efficiency) is compared to the Maximum Efficiency allowed on the water User. If the calculated Water User’s efficiency is less than the Maximum Efficiency, the Depletion Requested Slot is set equal to the calculated value for Depletion Requested. If the calculated efficiency of the water user (Depletion Requested/Diversion requested) is greater than the Maximum Efficiency (and Depletion Requested is not input by the user), Depletion Requested is set to the product of the Diversion Requested and the Maximum Efficiency. If the calculated efficiency is greater than the Maximum Efficiency and Depletion Requested is input by the user, an error is posted and the run terminates.
See the note in Diversion and Depletion Request for information on how this method behaves in Rulebased Simulation.
* Population Requests
This user method uses population data to determine Depletion Requested and Diversion Requested if they are not input. Depletion Requested is based on the water user population, water use per individual, and incidental rate loss. Diversion Requested is then calculated from the Depletion Requested and the Minimum Efficiency.
Slots Specific to This Method
 Use Rate Per Individual
Type: Series Slot
Units: Flow
Description: Water use as flow per individual
Information:  
I/O: Optional; required if Depletion Requested is not input.
 Incidental Loss Rate
Type: Table Slot
Units: Fraction
Description: Losses in the water distribution system
Information: Expressed as a fraction of the flow.
I/O: Optional; required if Depletion Requested is not input.
 Population
Type: Series Slot
Units: NoUnits
Description: Number of individuals in the water user population
Information:  
I/O: Optional; required if Depletion Requested is not input.
 Maximum Efficiency
Type: Table Slot
Units: Fraction
Description: Maximum consumed flow per unit diverted flow
Information: Expressed as a fraction.
I/O: Required input
 Maximum Flow Capacity
Type: Table Slot
Units: Flow
Description: Maximum possible flow rate through the distribution system
Information: The Maximum Flow Capacity can be based on either physical, legal, or environmental restrictions, and so on.
I/O: Required input
 Minimum Diversion Request
Type: Table Slot
Units: Flow
Description: Minimum possible flow rate required to meet depletion requests
Information: The Minimum Diversion Request can be based on either physical, legal, or environmental restrictions, and so on. This is only used if the Depletion Request is non-zero.
I/O: Optional.
 Minimum Efficiency
Type: Series Slot
Units: Fraction
Description: Minimum consumed flow per unit diverted flow
Information: Expressed as a fraction.
I/O: Required input
Method Details  
If not input, the Depletion Requested is calculated as follows:
    
Then, Diversion Requested (if it is not specified by the user) is calculated as follows:
    
After the Diversion Requested and Depletion Requested are initially calculated, Diversion Requested must be checked against the Maximum Flow Capacity. If the calculated value for Diversion Requested is less than the Maximum Flow Capacity, the Diversion Requested slot is set to the calculated value. If the calculated Diversion Requested is greater than the Max Flow Capacity, it is set to the Maximum Flow Capacity.
Note:  User input overrides all calculated values. If the user specifies a Diversion Requested which is greater than the Maximum Flow Capacity, an error is posted and the run terminates.
Diversion Requested must also be checked against the Minimum Diversion Request (if specified by user) If the calculated value for Diversion Requested is greater than the Minimum Diversion Request, the Diversion Requested slot is set to the calculated value. If the calculated Diversion Requested is less than the Minimum Diversion Request, it is set to the Minimum Diversion Request.
Note:  User input overrides all calculated values. If the user specifies a Diversion Requested which is less than the Minimum Diversion Request (if specified), an error is posted and the run terminates.
The Depletion Requested divided by the Diversion Requested (i. e. the Water User’s efficiency) is compared to the Maximum Efficiency allowed on the Water User. If the calculated value is less than the Maximum Efficiency, Depletion Requested is unchanged. If the calculated efficiency (Depletion Requested/Diversion requested) is greater than the Maximum Efficiency (and Depletion Requested is not input by the user), Depletion Requested is reset to the value of Diversion Requested multiplied by the Maximum Efficiency. If the calculated efficiency is greater than the Maximum Efficiency and Depletion Requested is input, an error is posted and the run terminates.
See the note in Diversion and Depletion Request for information on how this method behaves in Rulebased Simulation.
* Regional Requests
This user method uses regional data to determine Depletion Requested and Diversion Requested if they are not input. Depletion Requested is based on the regional water use, the fraction of the region that the water user represents, and incidental rate loss. Diversion Requested is then calculated from the Depletion Requested and the Minimum Efficiency.
Slots Specific to This Method
 Regional Use Rate
Type: Series Slot
Units: Flow
Description: Water loss due to regional use
Information:  
I/O: Optional; required if Depletion Requested is not input.
 Incidental Loss Rate
Type: Table Slot
Units: Fraction
Description: Losses in the water distribution system
Information: Expressed as a fraction of the flow.
I/O: Optional; required if Depletion Requested is not input.
 Fraction of Region
Type: Series Slot
Units: Fraction
Description: Fraction of the region using water at the regional rate
Information:  
I/O: Optional; required if Depletion Requested is not input.
 Maximum Efficiency
Type: Table Slot
Units: Fraction
Description: Maximum amount of consumed flow per unit diverted flow
Information: Expressed as a fraction.
I/O: Required input
 Maximum Flow Capacity
Type: Table Slot
Units: Flow
Description: Maximum possible flow rate through the distribution system
Information: The Maximum Flow Capacity can be based on either physical, legal, or environmental restrictions, and so on.
I/O: Required input
 Minimum Diversion Request
Type: Table Slot
Units: Flow
Description: Minimum possible flow rate required to meet depletion requests
Information: The Minimum Diversion Request can be based on either physical, legal, or environmental restrictions, and so on. This is only used if the Depletion Request is non-zero.
I/O: Optional.
 Minimum Efficiency
Type: Series Slot
Units: Fraction
Description: Minimum amount of consumed flow per unit diverted flow
Information: Expressed as a fraction.
I/O: Required input
Method Details  
If not input, the Depletion Requested is calculated as follows:
    
Then, Diversion Requested (if it is not specified by the user) is calculated as follows:
    
After the Diversion Requested and Depletion Requested are initially calculated, Diversion Requested must be checked against the Maximum Flow Capacity. If the calculated value for Diversion Requested is less than the Maximum Flow Capacity, the Diversion Requested slot is set to the calculated value. If the calculated Diversion Requested is greater than the Max Flow Capacity, it is set to the Maximum Flow Capacity.
Note:  User input overrides all calculated values. If the user specifies a Diversion Requested which is greater than the Maximum Flow Capacity, an error is posted and the run terminates.
Diversion Requested must also be checked against the Minimum Diversion Request (if specified by user) If the calculated value for Diversion Requested is greater than the Minimum Diversion Request, the Diversion Requested slot is set to the calculated value. If the calculated Diversion Requested is less than the Minimum Diversion Request, it is set to the Minimum Diversion Request.
Note:  User input overrides all calculated values. If the user specifies a Diversion Requested which is less than the Minimum Diversion Request (if specified), an error is posted and the run terminates.
The Depletion Requested divided by the Diversion Requested (i. e. the Water User’s efficiency) is compared to the Maximum Efficiency allowed on the Water User. If the calculated value is less than the Maximum Efficiency, Depletion Requested is unchanged. If the calculated efficiency (Depletion Requested/Diversion requested) is greater than the Maximum Efficiency (and Depletion Requested is not input by the user), Depletion Requested is reset to the value of Diversion Requested multiplied by the Maximum Efficiency. If the calculated efficiency is greater than the Maximum Efficiency and Depletion Requested is input, an error is posted and the run terminates.
See the note in Diversion and Depletion Request for information on how this method behaves in Rulebased Simulation.
* Periodic Diversion Request
This method is used to specify the Diversion Requested as a function of date/season using a periodic slot.
Slots Specific to This Method
 Periodic Diversion Request
Type: Periodic Slot
Units: Flow
Description: Diversion requested as a function of date/season
Information: The Diversion Requested is computed at the beginning of each timestep using the current date to look up the value from this slot.
I/O: Required input
Method Details  
The Periodic Diversion Request method executes at the beginning of the run. Each timestep is used to look up a value in the Periodic Diversion Request slot. The computed value is set in the Diversion Requested and Depletion Requested slots.
* Reservoir Level Lookup
The Reservoir Level Lookup method is used to compute the Diversion Requested 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: Diversion requested 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 requested is specified for each date range in the periodic slot.
I/O: Required input
 Diversion Request Reservoir
Type: List Slot
Units: None
Description: Reservoir used to compute the diversion requested
Information: The previous timestep operating level of this reservoir is used to look up the diversion requested 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, input a value of 1.
I/O: Required input
Note:  If the specified reservoir is disabled and is set to Pass Inflows, no diversion request lookup is possible. See Diversions Based on Disabled Reservoirs in USACE‑SWD Modeling Techniques for details on the behavior in this situation.
Method Details  
The Reservoir Level Lookup method executes 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 Requested and Depletion Requested slot. Because the method uses the same operating level (from the previous timestep) for all timesteps in the forecast period, it is an approximation but allows the object to solve throughout the forecast period.
* Specify Scheduled Requests
The Specify Scheduled Requests method sets the Diversion Requested and Depletion Requested slots at the beginning of the run to the scheduled values. When the water user solves, it computes the amount of the depletion schedule that was cutback and the amount of the depletion schedule that couldn’t be met. This allows you to track both an initial scheduled amount (as either a series or periodic relationship) and then reduce the schedule to the requests. Typically this reduction is performed using rules. The water user then computes the various depletion shortage computations.
Slots Specific to This Method
 Diversion Schedule
Type: Series Slot with Periodic Input
Units: Flow
Description: Desired diversion before any cutback, curtailment or adjustments are made.
I/O: Input as either a Series or a Periodic relationship
 Depletion Schedule
Type: Series Slot with Periodic Input
Units: Flow
Description: Desired diversion before any cutback, curtailment or adjustments are made.
I/O: Input as either a Series or a Periodic relationship
 Depletion Schedule Cutback
Type: Series Slot
Units: Flow
Description: Difference between the Depletion Schedule and the Depletion Requested. This represents the amount that the schedule was adjusted to get to the request.
Information:
I/O: Output only
 Depletion Schedule Shortage
Type: Series Slot
Units: Flow
Description: Difference between the Depletion Schedule and the Depletion. A positive number indicates shortage, while a negative number indicates surplus.
Information:
I/O: Output only
Method Details  
The Specify Scheduled Requests method executes once at the beginning of the run for all timesteps in the run. The values in the Diversion Schedule and Depletion Schedule are copied to the Diversion Requested and Depletion Requested slots, respectively. Since these values are set at the beginning of the run, they are set when the controller is at priority 0 (in RBS) and the O flag. Therefore any rule executed later in the run can overwrite the values.
Shortage Computations  
When the Specify Scheduled Requests is selected, additional shortage terms are computed as follows.
• Standalone or part of a Sequential Agg Diversion Site: At the end of the dispatch method the following are computed (see Solve given Diversion Requested or Solve Sequential given Diversion Requested).
    
    
• Part of a Lumped Agg Diversion Site: When the aggregate dispatches, it computes the following on each water user (see Solve Lumped given Total Diversion Requested for details):
    
    
Table 28.1 provides sample numbers, which help to illustrate these complex computations. The variables in Bold text are part of this method. “NA” indicates it is not a slot on that object.
 
Table 28.1  Example shortage calculation numbers
 
 
Lumped Agg Diversion Site with one water user element
Variable
WU Standalone / Sequential
Agg
WU element
Diversion Schedule
1000
NA
1000
Depletion Schedule
800
NA
800
Diversion Request
(rule) 900
900
(rule) 900
Depletion Request
(rule) 720
720
(rule) 720
Diversion (due to available)
850
850
NA
Depletion
680
680
NA
Depletion Shortage
40
40
40
Depletion Schedule Cutback
80
NA
80
Depletion Schedule Shortage
120
NA
120
Revised: 08/02/2021