skip to main content
Canal
Objects and Methods
Canal
The canal object models gravity flow through a canal connected to two Reservoirs. The set of allowable dispatch methods for the linked reservoirs is limited. See “Allowable Dispatch Methods for Linked Reservoirs” for details about which dispatch methods are allowed.
General Slots
Elevation 1
Type: AggSeriesSlot
Units: LENGTH
Description: Pool Elevation of reservoir 1
Information: If the Barkley Canal Flow method is selected, Reservoir 1 must be Barkley, and this slot must be connected to the Pool Elevation on that Reservoir.
I/O: Set through a link
Elevation 2
Type: AggSeriesSlot
Units: LENGTH
Description: Pool Elevation of reservoir 2
Information: Set through a link
I/O: Must be linked to the Pool Elevation slot on a reservoir.
Flow 1
Type: AggSeriesSlot
Units: FLOW
Description: flow to or from the canal end connected to Reservoir 1
Information: If the Barkley Canal Flow method is selected, Reservoir 1 must be Barkley, and this slot must be connected to the Canal Flow slot on that Reservoir.
I/O: Output only
Flow 2
Type: AggSeriesSlot
Units: FLOW
Description: flow to or from the canal end connected to Reservoir 2
Information: Must be connected to the Canal Flow slot on a reservoir.
I/O: Output only
User Methods
Canal Flow
This category controls how the flow through the canal is calculated. Two of the user methods in this category are implementations of canal flow equations used by TVA. The Canal Flow Table method is the only generic method that can be used for canals other than the Tellico and Barkley Canals in the TVA system.
* None
This method is the default for this category. It will result in an error if it is selected and a run is begun.
There are no slots specifically associated with this method.
* Canal Flow Table
This method is a general method that can be used to solve any canal whose flow can be described using the Canal Flow Table. This method takes the average pool elevation of the lower Reservoir and the difference in average elevation between the two Reservoirs and uses linear interpolation to determine Canal Flow from the Canal Flow Table.
Slots Specific to This Method
Delta Elevation
Type: AggSeriesSlot
Units: Length
Description: The average elevation difference between the two reservoirs for the current timestep
I/O: Output only
Lower Elevation
Type: SeriesSlot
Units: Length
Description: The average elevation of the lower reservoir for the current timestep
Information: This slot is necessary because the height of the water in the canal effects the flow rate.
I/O: Output Only
Canal Flow Table
Type: TableSlot
Units: Length, Length, Flow
Description: 3-D table used to find canal flow by interpolation
Information: 1st column is Lower Elevation (can have several entries with the same lower elevation), 2nd column is Delta Elevation, 3rd column is Canal Flow. This table provides information regarding several possible Lower Elevation and Delta Elevation values and the corresponding Canal Flow at these operating points.
I/O: Input Only
Elevation 1 Adjustment
Type: ScalarSlot
Units: Length
Description: Adjusts the Elevation 1 value by a user specified amount.
Information: Automatically set to zero if not input. This slot was added to handle the Barkley Canal calculations. This slot will not be necessary for most users.
I/O: Optional; defaults to zero if not input.
Note:  The canal flow solution requires that the slot minimum and maximum be set in the Pool Elevation slot configuration on both linked reservoirs. Also the quality of the solution for Canal Flow is sensitive to the slot convergence values in the slot configuration for all series slots on the Canal object. It is recommended that the slot convergence be set to 0.00001 Percent for all Canal series slots.
First, the method checks to see if an Elevation 1 Adjustment value is given. If no value is input, Elevation 1 Adjustment is set to zero. Otherwise, the Elevation 1 value is adjusted by the given amount.
Then Delta Elevation is computed as follows.
abs(average elevation 1 - average elevation 2)
Lower Elevation is then set to the lower value of either average elevation 1 or average elevation 2.
Once Delta Elevation and Lower Elevation are known, the Canal Flow can be found directly from the Canal Flow Table. The appropriate direction of flow will be determined based on the average elevation of the two reservoirs. A negative flow implies flow out of the Reservoir. Flow will obviously be from the reservoir with the higher average elevation to the reservoir with the lower average elevation.
* Tellico Canal Equation
There are no slots specifically associated with this method.
Note:  The canal flow solution requires that the slot minimum and maximum be set in the Pool Elevation slot configuration on both linked reservoirs. Also the quality of the solution for Canal Flow is sensitive to the slot convergence values in the slot configuration for all series slots on the Canal object. It is recommended that the slot convergence be set to 0.00001 Percent for all Canal series slots.
The basic equation for this method is in user units:
• FlowLower
Flow into the reservoir with the lower pool elevation (in cfs).
• hlower
Pool Elevation of the lower reservoir (in feet).
• hdiff
Absolute value of difference in Pool Elevation between the two reservoirs (in feet).
If the difference in Pool Elevation is smaller than 0.01 feet, a linearized version of this equation is used.
* Barkley Canal Equation
There are no slots specifically associated with this method.
Note:  The canal flow solution requires that the slot minimum and maximum be set in the Pool Elevation slot configuration on both linked reservoirs. Also the quality of the solution for Canal Flow is sensitive to the slot convergence values in the slot configuration for all series slots on the Canal object. It is recommended that the slot convergence be set to 0.00001 Percent for all Canal series slots.
The basic equation for this method is in user units.
• FlowLower: Flow into the reservoir with the lower pool elevation (in cfs).
• hlower: Pool Elevation of the lower reservoir (in feet).
• hdiff: Absolute value of difference in Pool Elevation between the two reservoirs (in feet).
If the difference in Pool Elevation is smaller than 0.01 feet, a linearized version of this equation is used.
Barkley must be connected to the Reservoir 1 slots, Flow 1 and Elevation 1. This requirement is due to an adjustment of -0.08 feet made to Elevation 1 because of physical considerations.
Dispatch Methods
* solveFlow
This dispatch method finds the flow through the canal.
In order for the canal to dispatch correctly, the linked reservoirs must solve with one of a limited set of dispatch methods. Table 7.1 lists which dispatch methods are allowed for reservoirs linked to a canal and which are not. If a reservoir linked to a canal tries to dispatch with a method that is not allowed, the run will abort with an error message.
 
Table 7.1  Allowable Dispatch Methods for Linked Reservoirs
Dispatch Methods Allowed for Reservoirs Linked to a Canal
Dispatch Methods NOT Allowed for Reservoirs Linked to a Canal
solveMB_givenInflowHW
solveMB_givenEnergyInflow
solveMB_givenOutflowHW
solveMB_givenInflowRelease
solveMB_givenInflowStorage
solveMB_givenEnergyStorage
solveMB_givenOutflowStorage
solveMB_givenEnergyHW
(Slope Power Reservoir)
solveMB_givenInflowOutflow
solveMB_givenInflowOutflowHW (Storage Reservoir)
solveMB_givenInflowOutflowHW (Level Power Reservoir only)
solveMB_givenInflowOutflowStorage (Storage Reservoir)
solveMB_givenInflowOutflowStorage (Level Power Reservoir only)
 
solveMB_givenEnergyHW (Level Power Reservoir only)
 
Required Knowns
Required Unknowns
• Flow 1
• Flow 2
The dispatch method of the canal object is unique, because the canal solves the reservoirs and the canal at the same time. The usual dispatching pattern is unstable when three objects are iterating with each other. If the Pool Elevations or Storages on both Reservoirs are input, the canal flow can be immediately found. If the reservoirs are solving for Storage/Pool Elevation, the canal performs a modified bisection algorithm to solve for Canal Flow.
Method Details
Following is a description of how these objects interact and how the method solves.
Note:  The canal flow solution requires that the slot minimum and maximum be set in the Pool Elevation slot configuration on both linked reservoirs. Also the quality of the solution for Canal Flow is sensitive to the slot convergence values in the slot configuration for all series slots on the Canal object. It is recommended that the slot convergence be set to 0.00001 Percent for all Canal series slots.
When a reservoir dispatches to solve for Pool Elevation, if it is linked to a canal, it sets its Pool Elevation slot with a seed value (previous value) and exits its dispatch method. It will wait for the canal to solve and set the Canal Flow; then it will dispatch again. When both reservoirs have set their Pool Elevation slots, the canal’s solveFlow dispatch method goes on the queue and executes. The result is the flow in the canal. When the flow is set on Flow1 and its negative value is set on Flow2, the values propagate to each reservoir. Each reservoir re-dispatches and solves mass balance to set the Storage and Pool Elevation.
Note:  The seed values in the Pool Elevation slots are only used to cause the canal to dispatch. They are not actually used in the calculation.
The canal flow algorithm begins by summing side inflows to both reservoirs. These include Hydrologic Inflow, Diversion, Return Flow, Inflow Forecast and Pumped Storage Flow. Any of these that are not in use default to zero. The side inflows do not change based on the Canal Flow and thus are treated as a constant in the canal flow algorithm.
Note:  Bank Storage, Evaporation, and Seepage are not included in the Canal Flow solution as they can be a function of Pool Elevation. Any non-default method selection in these three categories will result in an error at the start of the run.
Then Canal Flow is set to an initial estimate of zero. With an estimate for Canal Flow, an estimate can be calculated for the remaining eight variables (Outflow, Inflow, Storage and Pool Elevation on both reservoirs) in the following order.
Note:  The following description uses the syntax ObjVariable to indicate that these values are the intermediate values used in the calculation, not the values on the slots. If a variable is known, then ObjVariable is set equal to Object.Slot. Otherwise, it must be computed within the iterative bisection algorithm. Also, a positive canal flow represents flow from Res1 to Res2 and a negative canal flow represents flow from Res2 to Res1.
Variables
Res1Outflow
If not known, then Res1.Inflow must be known, and the outflow is either a function of maximum outflow or mass balance. If Res1.Outflow is flagged Max Capacity (M), then Res1Outflow is:
The function getMaxOutGivenIn uses the known Inflow, either input or propagated across a link from an upstream object, to compute the maximum outflow using the specified spill and power methods.
If Res1.Outflow is not flagged max capacity, then Res1.Storage must be input (or Res1.Pool Elevation is input and thus storage is known). Then Res1.Outflow is calculated from the mass balance:
Res1Inflow
If not known, then Res1.Outflow must be known and Res1.Storage must be input (or Res1.Pool Elevation is input and thus storage is known). Then Res1.Inflow is calculated from the mass balance:
Res1Storage
If not known, the Storage is a calculated from the mass balance:
Res1Pool Elevation
If not input, the pool elevation depends on the type of reservoir. For sloped reservoirs, the selected slope storage calculation is executed. It is a function of inflow, outflow and storage:
If it is not a sloped reservoir, the Pool Elevation is looked up on the Elevation Volume table:
Then the same variables are calculated for Reservoir 2 with the one difference being that a positive canal flow represents a flow out of the reservoir.
Res2Outflow
If not known, then Res2.Inflow must be known, and the outflow is either a function of maximum outflow or mass balance. If Res2.Outflow is flagged Max Capacity (M), then Res2Outflow is:
The function getMaxOutGivenIn uses the known Inflow, either input or propagated across a link from an upstream object, to compute the maximum outflow using the specified spill and power methods.
If Res2.Outflow is not flagged max capacity, then Res2.Storage must be input (or Res2.Pool Elevation is input and thus storage is known). Then Res2.Outflow is calculated from the mass balance:
Res2Inflow
If not known, then Res2.Outflow must be known and Res2.Storage must be input (or Res2.Pool Elevation is input and thus storage is known). Then Res2.Inflow is calculated from the mass balance:
Res2Storage
If not known, the Storage is a calculated from the mass balance:
Res2Pool Elevation
If not input, the pool elevation depends on the type of reservoir. For sloped reservoirs, the selected slope storage calculation is executed. It is a function of inflow, outflow and storage:
If it is not a sloped reservoir, the Pool Elevation is looked up on the Elevation Volume table:
With two new pool elevations, a new Canal Flow can be calculated based on the user-selected Canal Flow method.
For the first iteration, with an estimate of zero canal flow, the resulting pool elevations represent the maximum possible elevation difference and thus produce a canalFlowUpdated that is the maximum possible canal flow (absolute value). This represents an upper bound on the magnitude of canal flow, with the initial estimate of zero as the lower bound. These two bounds are then bisected to give a new estimate:
Then the process of calculating updated values for all variables is repeated. Each iteration provides two new bounds for canal flow, which move toward convergence with each iteration. In some cases, canalFlowUpdated can fall outside of the current bounds. In these cases, the algorithm can determine whether canalFlowEst for that iteration was too low or too high. It then replaces canalFlowUpdated with the appropriate existing bound when bisecting to calculate a new estimate. In other words, the solution will never allow the bounds to expand from one iteration to the next. They will always be converging.
Convergence and Max Iterations Within Canal Solution
Following are the convergence criteria used in the canal flow algorithm. That is, after each iteration, the new value is compared to the previous computed value. The iteration is stopped when the difference between old and new are within the indicated criteria. The iterations will also stop the run with an error if max iterations has been exceeded.
 
Item
Stopping Criteria
Canal Flow
10 m3/s
Reservoir Storage
1000 m3
Reservoir Inflows and Outflows
10 m3/s
Reservoir Pool Elevations
0.01 m
Max Iterations
100
The quality of the canal flow solution is dependent on the quality of data in the Canal Flow Table and the reservoir tables. Inaccurate data in these tables or insufficient precision in these data may cause the solution to have difficulty converging.
 
Revised: 06/03/2019