skip to main content
Distribution Canal
Objects and Methods
Distribution Canal
The Distribution Canal is an element within an AggDistributionCanal object. It routes its Delivery Requests and any downstream delivery requests to the upstream end of the element.
Links among Distribution Canal elements and between Distribution Canal elements and the AggDistributionCanal object are maintained by RiverWare. Following are automatic links created by RiverWare:
• The Total Inflow slot on the AggDistributionCanal object is linked to the Inflow slot on the first Distribution Canal element.
• The Outflow slot of all but the last canal element is linked to the Inflow slot of the next canal element.
• The last distribution canal element’s Outflow slot is linked to the Total Outflow slot on the AggDistributionCanal object.
• The Routed Delivery Request slot on all but the first Distribution Canal element is linked to the DS Delivery Request slot of the preceding Canal element.
• The Routed Delivery Request slot of the first Distribution Canal element is linked to the Total Delivery Request slot of the AggDistributionCanal object.
• The Downstream Delivery Request slot on the AggDistributionCanal object is linked to the DS Delivery Request slot on the last Distribution Canal element.
Figure 12.1 shows the linking structure just described. The automatic links are represented by a solid line while optional user-specified links are shown with a dashed line. The example shows how two AggDistributionCanal objects can interact with each other and how they each interact with separate WaterUsers. WaterUsers can be elements on the Agg Diversion Site when the No Structure linking structure is used, or they can exist as separate objects on the workspace.
Figure 12.1  Diversion object or AggDiversionSite
General Slots
Slots that always appear for this object
Available Flow
Type: SeriesSlot
Units: FLOW
Description: flow at the downstream end of the Distribution Canal element
Information: Available Flow is the flow that may be diverted. It is calculated by the routing method, and takes into account any gain/loss or lag time that occurs in the Distribution Canal element.
I/O: Output only
Delivered Flow
Type: SeriesSlot
Units: FLOW
Description: flow delivered to the WaterUser
Information: This slot is usually linked to the Diversion slot in a WaterUser. If there is no link, all non-input values are set to zero.
I/O: Optional; usually set from a link
Inflow
Type: SeriesSlot
Units: FLOW
Description: inflow to the Distribution Canal element
Information:  
I/O: Output only
Outflow
Type: SeriesSlot
Units: FLOW
Description: outflow from the Distribution Canal element
Information: Outflow is calculated by the dispatch method.
I/O: Output only
Return Flow
Type: SeriesSlot
Units: FLOW
Description: return flow to downstream end of the Distribution Canal element
Information: Usually linked to the Return Flow slot of the Water User. If it is not linked, any non-input values will be set to 0.
I/O: Optional; usually set by propagation across a link
User Methods
Canal Max Capacity
The Canal Max Capacity category is used to limit the amount of flow at the top of the Distribution Canal element. This category simply turns the application of maximum capacity on and off.
* None
This method does not limit the flow through the canal. It performs no calculations. There are no slots specifically associated with this method.
* Input Max Capacity
This method limits the flow into the top of the canal to a user specified amount. Any flow that exceeds the Maximum Capacity is spilled from the canal.
Slots Specific to This Method
Canal Spillover
Type: SeriesSlot
Units: FLOW
Description: flow spilled from the canal because the maximum capacity was exceeded.
Information: Any inflow into the canal that exceeds the maximum capacity will be placed in the slot, and the maximum capacity of the canal will then be routed.
I/O: Output only
Maximum Capacity
Type: ScalarSlot
Units: FLOW
Description: maximum amount of flow that can enter the upstream end of the canal
Information:  
I/O: Required input
When flow is being routed downstream, Canal Spillover is calculated as follows (if Inflow is greater than Maximum Capacity).
The Maximum Capacity is then routed downstream.
When the requests are being routed upstream, this method ensures that the requests do not exceed the Maximum Capacity.
Canal Seepage
The Canal Seepage method category is used to model seepage from the canal. This category controls how to apply the seepage.
* None
This is the default method. It performs no calculations. There are no slots specifically associated with this method.
* Input Seepage
This method allows users to directly input values into the Seepage slot by hand or to set the slot with a rule.
Canal Seepage
Type: SeriesSlot
Units: FLOW
Description: the calculated amount of flow lost as seepage
Information:  
I/O: Input only
* Proportional Seepage
This method uses constant parameters to model seepage. Seepage is lost from the canal after any flow that exceeds the Maximum Capacity is spilled, but before the flow is routed.
Slots Specific to This Method
Canal Seepage
Type: SeriesSlot
Units: FLOW
Description: the calculated amount of flow lost as seepage
Information:  
I/O: Output only
Maximum Seepage
Type: SeriesSlot
Units: FLOW
Description: represents the maximum amount of flow that can be lost as seepage
Information:  
I/O: Optional; this slot is not used if it is not input.
Seepage Flow Fraction
Type: ScalarSlot
Units: NO UNITS
Description: represents the fraction of Inflow that is lost as seepage
Information: Entered as a decimal value which is greater that or equal to zero but less than one.
I/O: Optional; set to zero if not input.
Canal Seepage is calculated as follows:
Canal Seepage is then subtracted from the Inflow before the flow is routed.
Canal Seepage is accounted for when routing requests upstream (it is added it to the request).
* Variable Seepage
This method uses variable parameters to model seepage. Seepage is lost from the canal after any flow that exceeds the Maximum Capacity is spilled, but before the flow is routed.
Slots Specific to This Method
Canal Seepage
Type: SeriesSlot
Units: FLOW
Description: the calculated amount of flow lost as seepage
Information:  
I/O: Output only
Maximum Seepage
Type: SeriesSlot
Units: FLOW
Description: represents the maximum amount of flow that can be lost as seepage
Information:  
I/O: Optional; this slot is not used if its not input.
Variable Seepage Flow Fraction
Type: SeriesSlot
Units: NO UNITS
Description: a time series of values representing the fraction of Inflow that is lost as seepage
Information: Entered as a decimal value which is greater than or equal to zero but less than one.
I/O: Optional; set to zero if not input.
Canal Seepage is calculated as follows:
Canal Seepage is then subtracted from the Inflow before the flow is routed.
Canal Seepage is accounted for when routing requests upstream (it is added it to the request).
* Head Based Seepage
The Head Based Seepage method, based on the method of the same name for the reach object, calculates seepage based on the elevation of the canal water relative to the groundwater elevation. If the groundwater head is below the canal bed elevation then the seepage will be based on the difference between the canal water surface elevation and the canal bed elevation.
Note:  All elevations should share the same datum.
Slots Specific to This Method
Canal Water Surface Elevation
Type: TableSlot
Units: LENGTH
Description: Average elevation of the water in the canal
Information: Should have the same datum as stage and the previous water table elevation
I/O: Required input
Seepage
Type: Series Slot
Units: flow
Description: The canal loss to groundwater
Information: A positive number represents a losing reach while a negative number represents a gaining reach
I/O: Output only
Previous Water Table Elevation
Type: Series Slot
Units: length
Description: The previous elevation value computed by the connected groundwater object
Information: Seepage is computed based on the difference between the current canal water surface elevation and the previous water table elevation
I/O: Output only
Conductance
Type: Scalar slot
Units: area per time
Description: The riverbed conductance
Information: The conductance is defined as the hydraulic conductivity of the streambed material, multiplied by the width of the streambed bottom, multiplied by the length of the stream segment, divided by the streambed thickness (Conductance = KwL/m).
I/O: Input or computed; see “Canal Conductance Specification”.
Canal Bed Elevation
Information: Scalar Slot
Units: length
Description: The elevation of the canal bed at the center of the canal segment (i.e. average canal bed elevation)
Information: Should have the same datum as Canal Water Surface Elevation and the Previous Water Table Elevation
I/O: Required input
The method will compute the seepage to groundwater as follows:
• If the Previous Water Table Elevation is greater than the Canal Bed Elevation:
• If the water table elevation at the previous timestep is below the Streambed Elevation:
Note:  The equations above use the water table elevation at the previous timestep. This simplification is done to avoid iteration problems that would result if the current groundwater elevation was used. A positive seepage is limited to be less than or equal to the Inflow to the canal.
Canal Seepage Routing
The option to route seepage becomes visible after a method to calculate seepage is chosen. In general, a seepage routing method makes visible a Prerouted seepage slot. This slot contains the values for seepage that have not been routed. The routed values are contained in the Canal Seepage slot. If a link exists that links seepage to another object and a seepage routing method is chosen, the link will propagate the values of the routed seepage.
* No Routing
This is the default method which will not route seepage. The values for seepage are calculated depending on the user method chosen for Canal Seepage. These values are contained in the Canal Seepage slot.
* Impulse Response
This method will calculate the routed seepage based on the impulse response method of routing.
Slots Specific to This Method
Number of Coefficients
Type: TableSlot
Units: NONE
Description: The integer number of lag coefficients to be used in the method.
I/O: Required input
Lag Coefficients
Type: TableSlot
Units: NONE
Description: The impulse response lag coefficients
Information: The number of lag coefficients must be the same as the value in the Number of Coefficients slot. The input will be in rows.
I/O: Required input.
PreRouted Seepage
Type: SeriesSlot
Units: FLOW
Description: The seepage values before routing.
Information: This slot contains the values of seepage that have not been routed. The routed values will be contained in the Canal Seepage slot. If the user-method for Canal Seepage is Input Seepage, the values are to be inputted in this slot.
I/O: Output/Input (see Information)
The Routed Seepage will be calculated as follows:
where C is a lag coefficient and ncoeff is the number of lag coefficients.
Canal Conductance Specification
Methods in this category allow you to choose how you wish to specify conductance. You can either give values for Conductance or give values for Hydraulic Conductivity and the geometry of the reach and the Conductance will be computed.
* Specify Conductance
This is the default method and does not instantiate any new slots.
* Compute Conductance
This method allows you to specify hydraulic conductivity and the geometry.
Slots Specific to This Method
Hydraulic Conductivity
Type: Scalar
Units: Velocity
Description: Hydraulic conductivity of the bed material
Information:  
I/O: Required Input
Canal Seepage Thickness
Type: Scalar
Units: Length
Description: Thickness associated with the conductance calculation.
Information:  
I/O: Required Input
Seepage Area
Type: Scalar
Units: Area
Description: Area of the river that contributes to seepage
Information:  
I/O: Required Input
At the start of the run, the information in these slots is used to compute the Conductance value as follows:
If there are missing values in the above slots, an error will be issued and the run initialization will be stopped.
The resulting value is set on the scalar Conductance slot. If there are values already in the slot, they will be overwritten.
Note:  The Conductance slot is registered as having a Source slot. When a slot has a source slot, it becomes read-only and displays a cross hatch over the data. It also provides a note indicating the source used to compute the data. This attribute is set at the start of the run, so you must initialize the model to see the display of this slot change. If you deselect this method, you must initialize the run again to clear the source slot.
Flow Routing
The Flow Routing method category is used to route the flow through the Distribution Canal element. If Time Lag Request Routing is selected on the containing AggDistributionCanal, only Time Lag Routing will be available in this category.
* No Routing
This method sets the available flow to equal the inflow after subtracting Canal Spillover and/or Canal Seepage if applicable. There are no slots specifically associated with this method.
Requests cannot be routed upstream when this method is selected. Therefore, this method is only available if No Routing is selected in the Request Routing category on the containing AggDistributionCanal.
* Time Lag
Routes flow through the Distribution Canal element using a time lagged approach. Canal Spillover and/or Canal Seepage are subtracted from the Inflow before routing. Requests can be routed upstream when this method is selected only if Time Lag routing is selected in the Request Routing category on the containing AggDistributionCanal.
Slots Specific to This Method
Delivery Request
Type: SeriesSlot
Units: FLOW
Description: delivery request at the downstream end of the Canal element
Information:  
I/O: Optional; Only used if routing requests.
Ds Delivery Request
Type: SeriesSlot
Units: FLOW
Description: delivery requests from any downstream objects
Information: The DS Delivery Request is added to the Delivery Request and the sum is routed to the upstream end of the Distribution Canal element. Only used if routing requests.
I/O: Optional; usually set by propagation across a link
Lag Time
Type: TableSlot
Units: TIME
Description: lag time of the flow through the Distribution Canal element
Information: This must be an integer number of timesteps.
I/O: Optional; if not input, it is set to zero.
Routed Delivery Request
Type: SeriesSlot
Units: FLOW
Description: routed delivery request at the upstream end of the Distribution Canal element
Information: The Routed Delivery Request is the sum of the DS Delivery Request and the Delivery Request, routed to the upstream end of the element. This slot is automatically linked, to either the DS Delivery Request of the upstream Canal element or to the Total Delivery Request on the AggDistributionCanal if there is no upstream element. Only used if routing requests. The Routed Delivery Request is always zero when the canal is draining (this only applies when a method is selected in the Canal Storage category).
I/O: Output only
The Time Lag method is used to compute Available Flow. The necessary calculations are as follows:
The value of Available Flow is the Inflow, after subtracting Canal Spillover and/or Canal Seepage. It is set at the timestep, t + Lag Integer, where t is the current timestep.
* Storage Time Routing
This method is a simple storage method that solves for Available Flow given current and previous Inflow values. The reach is broken up into a user-specified number of linked segments and flows are calculated for each segment. This method is almost identical to the Storage Routing method on the Reach object.
Slots Specific to This Method
Number of Segments in Reach
Type: ScalarSlot
Units: NOUNITS
Description: number of segments upstream to downstream
Information: This will determine the number of columns in the Segment Outflow table as well.
I/O: Required input
Segment Outflow
Type: TableSeriesSlot
Units: FLOW
Description: segment outflow
Information: Available Flow is set as the outflow the last segment. The columns in this table will be resized to the number of segments input by the user, and the number of rows will be the number of timesteps in the run.
I/O: Output only
Storage Time Coefficient
Type: ScalarSlot
Units: NOUNITS
Description: value that is divided by the result of the average flow and exponent to arrive at time in storage
Information: The units of this slot should be Volumeexponent (a value should be used that is in (ft3)exponent). This coefficient may be determined by trial and error, and should not be negative. The value must correspond to a flow value in cfs and storage time in hours, regardless of the user units on other slots.
I/O: Required input
Storage Time Exponent
Type: ScalarSlot
Units: NOUNITS
Description: exponent of mean flow value.
Information: Usually between -1 and 1. The value must correspond to a flow value in cfs and storage time in hours, regardless of the user units on other slots.
I/O: Required input
The algorithm proceeds as follows:
1. If the previous Inflow value is not known, the method exits.
2. The outflow value for each segment from the previous timestep is checked for validity. There are then three possible scenarios:
– If the segment outflows are not valid and previous Available Flow is not valid, Available Flow is set equal to Inflow plus gain loss and the method exits.
– If the segment outflows are not valid, and previous Available Flow is valid, set all segment outflows equal to previous Inflow, and continue the routing method.
– If the segment outflows are valid, continue the method.
3. Find the mean interior flow from the previous timestep as the average of all segment outflows.
4. Find the time of storage in the reach based on the following empirical formula (in cfs):
where storagetime is the time of storage in hours, coefficient and exponent are user input constants in the slots above, and meanfl is the average interior flow of the previous timestep.
Note:  The storagetime calculation is always made with meanfl in units of cfs regardless of the user units on any flow slots. The values for Storage Time Coefficient and Storage Time Exponent should be set accordingly.)
The time in storage can be used as a conversion from storage to outflow.
5. Find the number of routing phases, n. If the time of storage is greater than half of the simulation timestep, n is 1. Otherwise, n is calculated as follows:
If n is greater than 48 from this equation, n is set to 6.
6. The inflow into the first segment for each routing phase is as follows:
– For each routing phase, the outflow from each segment is as follows:
– This routing equation is based on the storage-outflow relation, storagetime, from above, and the continuity equation, as follows:
– The inflow into the next segment is the average of the segments previous and current outflows.
– The current timestep’s Available Flow for the object is equal to the last segment’s outflow.
* Variable Time Storage Routing
This method is a simple storage method that solves for Available Flow given current and previous Inflow values. The reach is broken up into a user-specified number of linked segments and flows are calculated for each segment. This method differs from the Storage Routing method only in the determination of the storagetime value. In this method, the storage time exponent and coefficient are found from a table lookup based on flow instead of constant values. This method is almost identical to the Variable Storage Routing method on the Reach object.
Slots Specific to This Method
Flow Range
Type: TableSlot
Units: FLOW
Description: the ranges of flow rates corresponding to the Variable Storage Time Tables
Information: The number of flow ranges allowed in this table is currently limited to 10. The columns of this table represent, in ascending order, the maximum flow rate for a specific flow range starting with 0 as the base. These columns are labeled Flow Range 1 - 10. Therefore, the first column represents a range of flows from 0 to the value input by the user in the Flow Range 1 column. The last flow range entered by the user should be a flow rate greater than any anticipated for the simulation. Otherwise, a value of 0.0 will be used for the Variable Storage Time slots for flows outside of this range. It is not necessary to utilize all 10 columns of this table. Use only the columns needed to designate the desired flow ranges.
I/O: Required input
Number of Segments in Reach
Type: ScalarSlot
Units: NOUNITS
Description: number of segments upstream to downstream
Information: This will determine the number of columns in the Segment Outflow table as well.
I/O: Required input
Segment Outflow
Type: TableSeriesSlot
Units: FLOW
Description: segment outflow
Information: Available Flow is set as the outflow from the last segment. The columns in this table will be resized to the number of segments input by the user, and the number of rows will be the number of timesteps in the run.
I/O: Output only
Variable Storage Time Coefficient
Type: SeriesSlot
Units: NOUNITS
Description: value that is divided by the result of the average flow and exponent to arrive at time in storage
Information: The units of this slot should be Volumeexponent (a value should be used that is in (ft3)exponent).
I/O: Output only
Variable Storage Time Coefficient Table
Type: Tableslot
Units: NOUNITS
Description: Variable Storage Time Coefficient for each specific Flow Range
Information: The columns of the table correspond to the flow ranges defined in Flow Range. The values must correspond to a flow value in cfs and storage time in hours, regardless of the user units on other slots.
I/O: Required input
Variable Storage Time Exponent
Type: SeriesSlot
Units: NOUNITS
Description: exponent of mean flow value.
Information: Usually between -1 and 1.
I/O: Output only
Variable Storage Time Exponent Table
Type: Tableslot
Units: NOUNITS
Description: Lag times for each specific Flow Range
Information: The columns of the table correspond to the flow ranges defined in Flow Range. The values must correspond to a flow value in cfs and storage time in hours, regardless of the user units on other slots.
I/O: Required input
The algorithm proceeds as follows:
1. If the previous Inflow value is not known, the method exits.
2. The outflow value for each segment from the previous timestep is checked for validity. There are then three possible scenarios:
– If the segment outflows are not valid and previous Available Flow is not valid, Available Flow is set equal to Inflow plus gain loss and the method exits.
– If the segment outflows are not valid, and previous Available Flow is valid, set all segment outflows equal to previous Inflow, and continue the routing method.
– If the segment outflows are valid, continue the method.
3. Find the mean interior flow from the previous timestep as the average of all segment outflows.
4. Find the time of storage in the reach based on the following empirical formula (in cfs):
where storagetime is the time of storage in hours, coefficient and exponent are user input constants in the slots above, and meanfl is the average interior flow of the previous timestep.
Note:  The storagetime calculation is always made with meanfl in units of cfs regardless of the user units on any flow slots. The values in the Variable Storage Time Coefficient Table and Variable Storage Time Exponent Table should be set accordingly.)
The time in storage can be used as a conversion from storage to outflow:
5. Find the number of routing phases, n. If the time of storage is greater than half of the simulation timestep, n is 1. Otherwise, n is calculated as:
If n is greater than 48 from this equation, n is set to 6.
6. The inflow into the first segment for each routing phase is as follows:
– For each routing phase, the outflow from each segment is as follows:
– This routing equation is based on the storage-outflow relation, storagetime, from above, and the continuity equation, as follows:
– The inflow into the next segment is the average of the segments previous and current outflows
– The current timestep’s Available Flow for the object is equal to the last segment’s outflow.
Canal Storage
This category is used to track canal storage.
* None
This is the default method. It performs no calculations. There are no slots specifically associated with this method.
* Input Change in Storage
This method allows the user to in put the change is storage as a function of time. In this way, the user controls the fill and drain dates as well as how quickly the canal fills or drains.
Slots Specific to This Method
Change in Storage Per Timestep
Type: Periodic Slot
Units: volume
Description: The user specified change in storage that should take place per timestep.
Information: This slot is used in the Outflow calculation and the Storage calculation. The user specifies when the canal starts filling/draining and the amount by which the canal is filled/drained per timestep. A positive value means the canal is filling and a negative value means the canal is draining.
I/O: Required input
Calculated Change In Storage
Type: Series Slot
Units: volume
Description: The value compute for change in storage from the Change In Storage Per Timestep periodic slot.
Information: Usually this slot just shows the change in storage value retrieved/calculated from the periodic slot. However, if a value is input on this slot, it will be used to compute Storage instead of the Change in Storage Per Timestep slot.
I/O: Output; optional input
Storage
Type: Series
Units: volume
Description: The amount of storage in the canal
Information: This slot is solved for based on the Change in Storage Per Timestep
I/O: Output
When the Input Change in Storage method is selected, the Storage slot is computed and the Outflow calculation changes as follows:
The Change in Storage is also considered when routing requests upstream.
Note:  When routing requests upstream, the Routed Delivery Request is always zero for timesteps where the canal is draining. In other words, if the canal is draining, there can be no downstream or delivery requests routed upstream.
Note:  If a value is input on the Calculated Change In Storage slot, it is used instead of the value determined from the Change in Storage Per Timestep periodic slot.
Evaporation from Storage
The Evaporation from Storage category is only available if a method is selected in the Canal Storage category. While this method is used to model evaporation from storage, the storage calculation is not affected by evaporation. Instead, evaporation is accounted for in the Outflow calculation.
* None
This is the default method. It performs no calculations. There are no slots specifically associated with this method.
* Input Evaporation
Slots Specific to This Method
Evaporation from Storage
Type: Periodic Slot
Units: flow
Description: The volume of evaporation per unit time
Information: This periodic slot should be set up so that there is a non-zero (positive) value only on the dates where there will be a non-zero (positive) storage.
I/O: Required input
When the Input Evaporation method is selected, the Outflow calculation changes as follows:
If there is a non-zero (positive) value for Evaporation from Storage when the Storage is zero, a warning is posted.
The Evaporation from Storage is also considered when routing requests upstream.
Note:  Neither Evaporation from Storage (nor any other gain/loss components) affect the Storage directly. The Storage slot changes only when there is a non-zero value in the Change in Storage Per Timestep slot. All gain/loss terms are handled in the Outflow calculation.
Dispatch Methods
Used to solve for Outflow and Available Flow given Inflow.
* solveMB_givenInflow
Required Knowns
• Inflow
Required Unknowns
• None
The Canal Max Capacity and Seepage user methods are applied to the Inflow. Then Available Flow is calculated from the Flow Routing user method. Outflow is calculated as follows:
If a method is selected in the Canal Storage category, the change in storage is also removed from in the Outflow calculation, as follows:
If a method is selected in the Evaporation from Storage category, the evaporation is also removed from the Outflow, as follows:
Note:  Time Lag Routing sets Available Flow at some future timestep. Therefore, the dispatch method may not solve for Outflow at the current timestep unless Available Flow has been set at the current timestep from dispatching at a previous timestep.
Revised: 06/03/2019