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

Links: Must be linked to the Pool Elevation slot on a reservoir.

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

Links: Must be linked to the Canal Flow slot on a reservoir.

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

Links: Must be linked to the Canal Flow slot on a reservoir.

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

Links: Not Linkable

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

Links: Not Linkable

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

Links: Not Linkable

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.

Links: Not Linkable

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.

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.

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