skip to main content
Aggregate Diversion Site
Objects and Methods
Aggregate Diversion Site
The Aggregate Diversion Site (Agg Diversion Site) object contains Water User objects as elements. The aggregate object allows many Water Users with separate diversions, return flows, and consumptive uses to be combined on the RiverWareTM Workspace to simplify model representation.
There are three possible “structures” defined on the Agg Diversion Site: the Sequential Structure, the Lumped Structure, and the No Structure (default). The linking structures define how the Water User objects behave relative to each other and their containing Agg Diversion Site. Links between the Agg Diversion Site object and the reach or reservoir object to which it is connected are made by the user. Links among the Water Users and between the Agg Diversion Site and the Water Users are done automatically according to the linking structure that the user has selected. The User Method section explains how to select the different linking structures.
User Methods
Link Structure
The Link Structure category, unlike most User Method Categories, is selected from the menu bar at the top of the Open Object dialog for the Agg Diversion Site. As described previously, there are three User Methods in the Link Structure category which define how the Water User objects behave relative to each other and their containing Agg Diversion Site object. Following is a description of each user method or “structure” and the associated slots and engineering calculations.
* No Structure
The No Structure method is commonly referred to as the Stand-Alone or Default structure. This method treats the Agg Diversion Site object as a container for separate, stand-alone, Water Users. Each Water User is linked, by the user, directly to the reach or reservoir from which it is diverting water. However, each reach or reservoir Diversion slot or Available for Diversion slot should have only one link, meaning that a reach or reservoir may be linked to one and only one Water User for the No Structure method. This approach is good for highly diverted, highly regulated rivers where each individual diversion and return must be kept track of in the river reaches.
Since the Water Users are directly linked to a reach or reservoir, the Agg Diversion Site never dispatches. Therefore, there are no input slots. Figure 3.1 shows the linking structure.
Figure 3.1  Standalone links
Slots Specific to This Method
Total Depletion Requested
Type: Multislot
Units: FLOW
Description: a multislot showing the Depletion Requested for each Water User as well as the sum of all requested depletions.
Information: Used for all linking structures.
I/O: Optional; Can be input when there are no Water User elements and it is not linked.
Total Diversion Requested
Type: MultiSlot
Units: FLOW
Description: a multislot showing the Diversion Requested for each Water User as well as the sum of all requested diversions.
Information: Used for all linking structures.
I/O: Optional; Can be input when there are no Water User elements and it is not linked.
* Sequential Structure
The Sequential Structure models a group of Water Users based on an order of allocation (perhaps by senior water right, etc.). The Agg Diversion Site diverts a bulk amount of water (from a reach or reservoir) and passes it to the first Water User, who will take its requested amount, if possible, and “pass” the remaining water on to the next user. In this way the “junior” users may get only part or none of their requested amount. Excess is returned to the Agg Diversion Site, via the Total Unused Water slot. Each water user processes its delivered amount, and all return flows are handled on a per Water User basis (i.e. each Water User links its returns back to the river individually). It is optional for the user to create a link between Return Flow and the reach or reservoir. If no link is specified, the Return Flow is included in the Incoming Available Water for the next Water User. The Outgoing Available Water from the last Water User (including Return Flow if it is not linked) is linked to the Total Unused Water slot.
Figure 3.2  Sequential links
Slots Specific to This Method
Total Available Water
Type: Series Slot
Units: FLOW
Description: signifies the water available for diversion from the reservoir or reach to which the diversion is connected.
Information: Set by link propagation from the diverted object. The user is responsible for linking this slot with the object from which the water is diverted.
I/O: Optional; Can be input when it is not linked.
Total Depletion
Type: Series Slot
Units: FLOW
Description: sum of the Depletion slots for all Water Users
Information:  
I/O: Output only
Total Depletion Requested
Type: Multislot
Units: FLOW
Description: a multislot showing the Depletion Requested for each Water User as well as the sum of all requested depletions.
Information: Used for all linking structures.
I/O: Optional; Can be input when there are no Water User elements and it is not linked.
Total Depletion Shortage
Type: Series Slot
Units: FLOW
Description: sum of the Depletion Shortage Slots for all Water Users
Information:  
I/O: Output only
Total Diversion
Type: Series Slot
Units: FLOW
Description: denotes the total water diverted to the Water Users.
Information: Must be linked, by the user, to the Diversion slot on the reach/reservoir being diverted from.
I/O: Optional; Must be input if Total Diversion Requested is not given.
Total Diversion Requested
Type: MultiSlot
Units: FLOW
Description: a multislot showing the Diversion Requested for each Water User as well as the sum of all requested diversions.
Information: Used for all linking structures.
I/O: Optional; Can be input when there are no Water User elements and it is not linked.
Total Diversion Shortage
Type: Series Slot
Units: FLOW
Description: sum of the Diversion Shortage slots for all Water Users
Information:  
I/O: Output only
Total Unused Water
Type: Series Slot
Units: FLOW
Description: represents the unused water (surface return flow plus any non-diverted water) after all Water Users have processed their requests.
Information: Set by engineering methods after the Water Users dispatch. It is linked, by RiverWare to the Outgoing Available Water from the last Water User.
I/O: Output only
Total Surface Return Flow
Type: Series Slot
Units: Flow
Description: represents the surface water return flow. It is set equal to the Surface Return Flow of the last element on the aggregate. This is not necessarily the same as the Total Unused Water.
Information: When a Return Flow method is selected, and a Return Flow Split method is selected, and the Link to MODFLOW method are selected the value on the Total Surface Return Flow slot may be transferred through the computational subbasin structure to an external MODFLOW model.
I/O: Output only
* Lumped Structure
The Lumped Structure models a group of Water User’s requests as a single lumped sum. The individual requests are summed in the Total Diversion Requested slot on the Agg Diversion Site, and a comparison is made with the Total Available for Diversion slot. If the total request can be met, the Diversion slot is set to that amount; if not, the Diversion slot is set to the Total Available for Diversion amount. In this scheme, the Return Flow is also lumped. The Total Depletion Requested slot tracks the sum of the individual Water User’s consumption requests. If a total deficit occurs in the Diversion, the Return Flows are recalculated based on the ratio of the Total Depletion Requested to the Total Diversion Requested. The Total Depletion Shortage is computed as the difference between Total Depletion Request and Depletion. The Total Depletion Shortage is then used to allocate the shortage to the member elements proportional to their depletion request.
It is not necessary to use Water User elements with this linking structure. If desired, Total Diversion Requested and Total Depletion Requested can be input directly by the user. However, it is often desirable to use one or more Water User objects for this purpose.
Figure 3.3  Lumped links
Slots Specific to This Method
Total Available Water
Type: Series Slot
Units: FLOW
Description: signifies the water available for diversion from the reservoir or reach to which the diversion is connected
Information: Set by link propagation from the diverted object. The user is responsible for linking this slot with the object from which the water is diverted.
I/O: Optional; Could be input if not set from link.
Total Depletion
Type: Series Slot
Units: FLOW
Description: The total amount consumed by the agg.
Information: Computed typically as Total Diversion minus Total Return Flow
I/O: Output only
Total Depletion Requested
Type: Multislot
Units: FLOW
Description: a multislot showing the Depletion Requested for each Water User as well as the sum of all requested depletions.
Information: Used for all linking structures.
I/O: Optional; Can be input when there are no Water User elements and it is not linked.
Total Diversion
Type: Series Slot
Units: FLOW
Description: denotes the total water diverted to the Water Users
Information:  
I/O: Optional; must be input if Total Diversion Requested is not given.
Total Diversion Requested
Type: MultiSlot
Units: FLOW
Description: a multislot showing the Diversion Requested for each Water User as well as the sum of all requested diversions.
Information: Used for all linking structures.
I/O: Optional; Can be input when there are no Water User elements and it is not linked.
Total Return Flow
Type: Series Slot
Units: FLOW
Description: represents the portion of the water diverted to water users which is not consumed
Information: It is the user’s responsibility to specify what is done with this data. If it is not linked to another object (i.e. back to the reach/reservoir Return Flow slot), it is lost from the system.
I/O: Output only
Total Depletion Shortage
Type: Series Slot
Units: Flow
Description: Represents the difference between Total Depletion Requested and Total Depletion.
Information: Computed as Total Depletion Requested - Total Depletion
I/O: Output Only
Aggregate Conjunctive Use
The Aggregate Conjunctive Use category exists as a user selectable method category only when Lumped Structure is selected as the linking structure. It is used to model supplemental diversions from groundwater. Conjunctive Use calculations also exist for the Sequential Structure and the No Structure, however, the method is selected on the Water User elements for those cases.
* None
This is the default method. It performs no calculations and there are no slots specifically associated with it.
* Supplement Diversion Lumped
This method is used to supplement surface water diversions with groundwater. The associated slots are given below.
Slots Specific to This Method
Available Supplemental Water
Type: Series Slot
Units: FLOW
Description: represents the amount of water available to supplement surface water diversion
Information:  
I/O: Optional; Input if not linked to the Available For Pumping slot in the Groundwater Storage object.
Supplemental Diversion
Type: Series Slot
Units: FLOW
Description: the amount of water diverted from groundwater for supplemental use
Information:  
I/O: Output only
Total Supplement Return Flow
Type: Series Slot
Units: FLOW
Description: return flow from the supplemental water
Information:  
I/O: Output only
Total Supplemental Use Request
Type: Series Slot
Units: FLOW
Description: the amount of water requested from groundwater for supplemental use
Information: If not input, it is calculated as the difference between Diversion Requested and Diversion.
I/O: Optional
If Available Supplemental Water is known, the following conjunctive use calculations are performed.
If Total Supplemental Use Request is not input, it is calculated as follows.
(The Maximum Total Supplement Request slot is instantiated when an Aggregate Max Supplemental Request method is selected.)
Supplemental Diversion is then calculated as follows.
Total Supplement Return Flow is as follows.
* Supplement Diversion Sequential
This is not a visible, user-selectable method on the Agg Diversion Site object. It is activated when Supplement Diversion is selected in the Conjunctive Use method category on one or more Water User elements. The slots and calculations associated with this method are given below.
Slots Specific to This Method
Available Supplemental Water
Type: Series Slot
Units: FLOW
Description: represents the amount of water available to supplement surface water diversion
Information:  
I/O: Optional; Input if not linked to the Available For Pumping slot in the Groundwater Storage object.
Supplemental Diversion
Type: Series Slot
Units: FLOW
Description: the amount of water diverted from groundwater for supplemental use
Information: Should be linked to the Pumped Flow slot on the Groundwater Storage object.
I/O: Output only
Total Consumption
Type: MultiSlot
Units: FLOW
Description: sum of the Consumption slots of all Water User elements performing conjunctive use calculations
Information: This slot does not consider consumption by Water User elements that do not have Supplement Diversion selected in the Conjunctive Use category.
I/O: Output only
Total Consumption Shortage
Type: MultiSlot
Units: FLOW
Description: sum of the Consumption Shortage slots of all Water User elements performing conjunctive use calculations
Information: This slot does not consider consumption shortages of Water User elements that do not have Supplement Diversion selected in the Conjunctive Use category.
I/O: Output only
Total Supplemental Use Request
Type: Series Slot
Units: FLOW
Description: sum of the Supplemental Use Request slots on all Water User elements performing conjunctive use calculations
Information:  
I/O: Output only
Supplemental Diversion is set as the lower value of either Total Supplemental Use Request or Available Supplemental Water. This represents the amount of water that is available to supplement all the Water User elements’ requests. However, there may not be enough water to meet the Supplemental Use Requests of all the elements. In this case, the Agg Diversion Site allocates the supplemental water to the elements based on their Supplemental Diversion Priority (a slot on each element which has Supplement Diversion selected). The element with the highest priority (lowest integer value) is allotted the total amount requested (if possible). If there is supplemental water remaining, it is allotted to the element of second highest priority. This is continued until no supplemental water remains.
Aggregate Max Supplemental Request
This method category is dependent on the Supplement Diversion Lumped method in the Conjunctive Use category. It provides the option of using groundwater storage elevation to determine the maximum supplement request. Values for the Maximum Total Supplement Request slot are then used in Conjunctive Use calculations.
* None
This is the default method. It performs no calculations and there are no slots specifically associated with it.
* Input Max Request
When selected, this method instantiates the Maximum Total Supplement Request series slot for user input.
Slots Specific to This Method
Maximum Total Supplement Request
Type: Series Slot
Units: FLOW
Description: user input maximum supplemental request
Information:  
I/O: Required input
* GW Elevation Max Request
This method determines the Maximum Total Supplement Request based upon the groundwater elevation at the previous timestep. Values are propagated across a link from the Previous Groundwater Elevation slot on a Groundwater object to the Previous Groundwater Elevation slot on the Agg Diversion Site. An interpolation of these values, using the Max Request Table, provides the Maximum Total Supplement Request.
Slots Specific to This Method
Previous Groundwater Elevation
Type: Series Slot
Units: Length
Description: previous groundwater elevation propagated across a link from a Groundwater object
Information:  
I/O: Optional; usually set by a link.
Max Request Table
Type: TableSlot
Units: Length vs. flow
Description: user input related groundwater elevation and maximum supplemental request
Information:  
I/O: Required input
Maximum Total Supplement Request
Type: Series Slot
Units: Flow
Description: maximum supplemental request based on the Max Request Table
Information: Maximum Total Supplement Request is calculated through table interpolation of the Max Request Table using the Previous Groundwater Elevation value.
I/O: Output only
MODFLOW Link Category AggDiv
The MODFLOW Link Category AggDiv category is used to specify whether the Agg Diversion Site is linked with an external MODFLOW model.
* No Link to MODFLOW AggDiv
No computations or slots are associated with the No Link to MODFLOW AggDiv method. This is the default method for the MODFLOW Link Category AggDiv. See “MODFLOW Link Category AggDiv” for details.
* Link to MODFLOW WU
Note:  RiverWare’s connection with MODFLOW is currently not functional. This method has been disabled and cannot be selected. An error will be posted at model load if this method was previously selected. Contact CADSWES for help.
The Link to MODFLOW WU method allows the AggDiversion Site object to be linked with MODFLOW. No computations or slots are associated with the Link to MODFLOW WU method. A surface water body represented in MODFLOW may receive a surface return flow from a RiverWare AggDiversion Site object. That is, the value of the Total Surface Return Flow slot may be transferred through the computational subbasin structure to MODFLOW. This will only have a non-zero value when a Return Flow method, a Return Flow Split method, and the Link to MODFLOW method are selected on member elements.
See “Computational Subbasin Functionality Guide” for a description of the AggDiversion Site-specific data configuration.
Dispatch Methods
* No Structure
When the No Structure method is selected, the Agg Diversion Site object only acts as a container for Water User objects. All calculations are performed within the Water Users and links are made directly to the diverted objects. Therefore, the Agg Diversion Site object never dispatches when the user selects No Structure. It does, however, show the Total Diversion Requested and Total Depletion Requested by the Water Users contained within.
Sequential Structure
* Process Sequential given Diversion Requested
Required Known Slots
Required Unknown Slots
A general description of the interaction among the Agg Diversion Site, Water Users, and Reach/Reservoir is given below.
1. Reach/Reservoir “Available For Diversion” is set.
2. Value propagates to Agg Diversion Site: “Total Available Water.”
3. Process Sequential given Diversion Requested on Agg Diversion Site object dispatches. “Total Diversion” is calculated as the lower value of “Total Available Water” and the amount of water needed to satisfy the Diversion Requested on all Water User elements.
Note:  Because the return flows may be available to downstream elements, this value may be less than the Total Diversion Requested.
4. “Total Diversion” propagates to “Incoming Available Water” on the first Water User.
5. The Water User solves for “Diversion”, “Outgoing Available Water” and “Return Flow”.
6. “Return Flow” is propagated to reach/reservoir (if link has been established) or it is sent to the next Water User via the “Outgoing Available Water” slot.
7. “Outgoing Available Water” value propagates to “Incoming Available Water” of second Water User.
8. “Outgoing Available Water” from last Water User propagates to Agg Diversion Site: “Total Unused Water” (including “Return Flow” from the last Water User if it is not linked to the Reach/Reservoir).
9. “Total Surface Return Flow” is set equal to the “Surface Return Flow” on the last element.
10. Process Sequential given Diversion Requested on Agg Diversion Site object re-dispatches.
11. “Total Depletion”, “Total Diversion Shortage”, and “Total Depletion Shortage” are calculated.
12. “Total Unused Water” is propagated to the “Return Flow” on the Reach/Reservoir.
13. Conjunctive Use calculations are performed if selected.
* Process Sequential given Diversion
This method is executed when Total Diversion is specified by the user. The value of Total Diversion cannot be greater than the Total Available Water.
Required Known Slots
Required Unknown Slots
A general description of the interaction among the Agg Diversion Site, Water Users, and Reach/Reservoir is given below.
1. The input value of “Total Diversion” propagates to “Incoming Available Water” on the first Water User.
2. The Water User solves for “Diversion”, “Outgoing Available Water” and “Return Flow”.
3. “Return Flow” is propagated to reach/reservoir (if link has been established) or it is sent to the next Water User via the “Outgoing Available Water” slot.
4. “Outgoing Available Water” value propagates to “Incoming Available Water” of second Water User.
5. “Outgoing Available Water” from last Water User propagates to Agg Diversion Site: “Total Unused Water” (including “Return Flow” from the last Water User if it is not linked to the Reach/Reservoir).
6. “Total Surface Return Flow” is set equal to the “Surface Return Flow” on the last element.
7. Process Sequential given Diversion on the Agg Diversion Site object dispatches.
8. “Total Depletion”, “Total Diversion Shortage”, and “Total Depletion Shortage” are calculated.
9. “Total Unused Water” is propagated to the “Return Flow” on the Reach/Reservoir.
10. Conjunctive Use calculations are performed if selected.
* Process Sequential given Depletion Requested
This method is only used when all of the member elements are modeling Soil Moisture to compute the requests (see “Irrigation Requests with Soil Moisture”). The member water users compute the Depletion Requested at the beginning of the timestep for the current timestep and some number of future timesteps; see “Irrigation Requests with Soil Moisture”. These Depletion Requested values propagate to the aggregate and together with Total Available Water, cause this dispatch method to be used.
Required Known Slots
Required Unknown Slots
Method Details
A general description of the interaction among the Agg Diversion Site, Water Users, and Reach/Reservoir is given below.
1. At the beginning of the timestep, Depletion Requested is set on the member element’s slots and is then propagated to the Agg Diversion Site.Total Depletion Requested.
2. Reach/Reservoir “Available For Diversion” is set and the value propagates to Agg Diversion Site.Total Available Water.
3. Process Sequential given Depletion Requested on the Agg Diversion Site object dispatches. Total Diversion Requested is computed by solving each water user element without setting any slots. If the previous soil moisture is unknown because it is solving at future timesteps, the soil moisture is assumed to be full so that only Depletion Requests for Crops will be met. (This will iterate once the soil moisture is known) On the aggregate, the “Total Diversion” is calculated as the lower value of “Total Available Water” and the amount of water needed to satisfy the Diversion Requested on all water user elements.
Note:  Because the return flows may be available to downstream elements, this value may be less than the Total Diversion Requested.
4. “Total Diversion” propagates to “Incoming Available Water” on the first Water User.
5. The Water User solves for “Diversion”, “Outgoing Available Water” and “Return Flow”.
6. “Return Flow” is propagated to reach/reservoir (if link has been established) or it is sent to the next Water User via the “Outgoing Available Water” slot.
7. “Outgoing Available Water” value propagates to “Incoming Available Water” of second Water User.
8. “Outgoing Available Water” from last Water User propagates to Agg Diversion Site: “Total Unused Water” (including “Return Flow” from the last Water User if it is not linked to the Reach/Reservoir).
9. “Total Surface Return Flow” is set equal to the “Surface Return Flow” on the last element.
10. Process Sequential given Depletion Requested on the Agg Diversion Site object re-dispatches.
11. “Total Depletion”, “Total Diversion Shortage”, and “Total Depletion Shortage” are calculated.
12. “Total Unused Water” is propagated to the “Return Flow” on the Reach/Reservoir.
13. Conjunctive Use calculations are performed if selected.
Lumped Structure
* Process Lumped given Diversion Requested
Required Known Slots
Required Unknown Slots
Method Details
A general description of the interaction among the Agg Diversion Site, Water Users, and Reach/Reservoir is given below.
1. Reach/Reservoir “Available For Diversion” is set.
2. This value propagates to Agg Diversion Site: “Total Available Water.”
3. Process Lumped given Diversion Requested dispatches on the Agg Diversion Site object.
4. Within the dispatch method, “Total Diversion” and “Total Return Flow” are calculated.
5. The values propagate to the reach or reservoir.
6. Conjunctive Use and Aggregate Max Supplemental Request calculations are performed if selected.
If Total Depletion Requested is not specified, it is set equal to the Total Diversion Requested.
If Total Diversion Requested is greater than the Total Available Water:
Total Diversion = Total Available Water
If the Total Diversion Requested is less than Total Available Water:
Total Diversion = Total Diversion Requested
Total Return Flow = Total Diversion - Total Depletion Requested
Then, Total Depletion is set as the difference between Total Diversion and Total Return Flow.
Total Depletion Shortage is computed as Total Depletion Requested minus Total Depletion.
The totalDepletionFraction is computed as Total Depletion divided by Total Depletion Requested. This value is not shown to the user. The agg then loops over each member water user (WU) and computes and sets the element’s Depletion Shortage. It is computed as
Essentially, any shortage is shared by each water user element proportional to its Depletion Requested. See “Depletion Shortage” for more information.
When Specify Scheduled Requests (see “Specify Scheduled Requests”) is selected on the element, additional shortage terms are computed as follows:
* Process Lumped given Diversion
Required Known Slots
Required Unknown Slots
Method Details
A general description of the interaction among the Agg Diversion Site, Water Users, and Reach/Reservoir is given below.
1. Process Lumped given Diversion dispatches on the Agg Diversion Site object.
2. Within the dispatch method, “Total Depletion” and “Total Return Flow” are calculated.
3. The values propagate to the reach or reservoir.
4. Conjunctive Use and Aggregate Max Supplemental Request calculations are performed if selected.
If Total Depletion Requested is not specified, it is set equal to the Total Diversion Requested.
If Total Diversion is less than the Total Diversion Requested:
If the Total Diversion is equal to the Total Diversion Requested:
Total Return Flow = Total Diversion - Total Depletion Requested
Then, Total Depletion is set as the difference between Total Diversion and Total Return Flow.
Total Depletion Shortage is computed as Total Depletion Requested minus Total Depletion.
The totalDepletionFraction is computed as Total Depletion divided by Total Depletion Requested. This value is not shown to the user. The agg then loops over each member water user element and computes and sets the element’s Depletion Shortage. It is computed as follows.
Essentially, any shortage is shared by each water user element proportional to its Depletion Requested. See “Depletion Shortage” for more information.
When Specify Scheduled Requests (see “Specify Scheduled Requests”) is selected on the element, additional shortage terms are computed as follows:
 
Revised: 06/03/2019