Appendix E TOC Commands

The TUFLOW Operations Control (.toc) contains operating rules for structures, it is read into the .tcf using the Read Operating Control File command. For more information on the .toc see Section 4.2.10. Using operated structures is discussed in Section 5.10. The available TOC commands are listed below and are detailed in Table E.1.


Table E.1: TUFLOW Classic/HPC TOC Commands
Command Solver Description
Breach Opening ==
 [ {CLOSE}  |  OPEN  |  NO CHANGE ]
Classic and HPC The breach status of a Dam Failure Channel. CLOSE will keep the breach fully closed, while OPEN will start the breaching process. NO CHANGE means that the DF channel operation remains unchanged. The default status is CLOSE. See Section 5.10.8.2.
Cd ==
 [ {0.75 or 0.6} |  \(\langle\) Cd \(\rangle\) ]
Classic and HPC

For RO culverts, sets the discharge coefficient used in the (Ansar M. and Nair S., 2003) equation. The default value is 0.75 for RO culverts. See Section 5.10.4.

For PF channels, sets the discharge coefficient used in the orifice flow equation (5.22). The default value is 0.6 for PF channels.
Cd Gate ==
 [ {0.6 or 0.75} |  \(\langle\) Cd \(\rangle\) ]
Classic and HPC Sets the discharge coefficient of the gate. For sluice gates the default value is 0.6 (see Section 5.10.5). For gated spillways the default is set to the default for Cd Spillway, which is 0.75 (see Section 5.10.6).
Cd Gate Submerged ==
 [ {0.8} |  \(\langle\) Cd \(\rangle\) ]
Classic and HPC Sets the discharge coefficient of the gate when fully submerged. The default value is 0.8. See Section 5.10.5.
Cd Failed ==
 \(\langle\) Cd \(\rangle\)  ]
Classic and HPC Cd Intact sets the weir coefficient (Cd) for the un-breached section of the DF channel, while Cd Failed sets Cd for the breached section of the DF channel. This command overwrites the default Cd values set by the Weir Type Intact/Failed command. See Table 5.23.
Cd Intact ==
 \(\langle\) Cd \(\rangle\)  ]
Classic and HPC Cd Intact sets the weir coefficient (Cd) for the un-breached section of the DF channel, while Cd Failed sets Cd for the breached section of the DF channel. This command overwrites the default Cd values set by the Weir Type Intact/Failed command. See Table 5.23.
Cd Spillway ==
 [ {0.75} ]
Classic and HPC Sets the discharge coefficient of the spillway. Default = 0.75. Prior to the 2016-03 release the default was 0.5 due to a different version of the weir equation being used. See Section 5.10.6.
Cf ==
 [ {1.0} |  \(\langle\) Cf \(\rangle\) ]
Classic and HPC Weir calibration factor. The default value is 1.0. See Section 5.10.7.
Cf Failed ==
 [ {1.0} |  \(\langle\) Cf \(\rangle\) ]
Classic and HPC Sets the weir calibration factor for DF channels. The default values are 1.0. See Table 5.23.
Cf Intact ==
 [ {1.0} |  \(\langle\) Cf \(\rangle\) ]
Classic and HPC Sets the weir calibration factor for DF channels. The default values are 1.0. See Table 5.23.
Define [\(\langle\)structure_type\(\rangle\)]  Control ==
 \(\langle\) control_id \(\rangle\) ]
Classic and HPC

Available structure types (\(\langle\)structure_type\(\rangle\)) include: “Culvert”, “Pump”, “Q Channel”, “Sluice”, “Spillway”, “Weir”, “Pipe Failure” or “Dambreak”.

Each Define Control block consists of three sections:

  • The default settings for the control’s commands, which are usually placed at the top of the definition and prior to the logical rules. The default settings are the values used for a command in the event the command is not used within the logic rules.
  • User defined variables – see Section 5.10.1.2
  • One or more logical rules – see Section 5.10.1.3

Within the control definition, commands specific to the type of structure/device can be used to adjust the structure/device’s operation. Further information can be found in Section 5.10.1.1.

\(\langle\) control_id \(\rangle\) is a unique control definition name. For a 1d_nwk channel to use the control, \(\langle\) control_id \(\rangle\) must be entered into the 1d_nwk Inlet_Type attribute. As mentioned above, more than one channel can reference the same control. For example, several pumps may utilise the same operational control logic.

Use End Define to terminate the block. An ERROR occurs if End Define is not specified.
Depth Collapse ==
 \(\langle\) depth_collapse \(\rangle\) ]
Classic and HPC Sets the depth that the dam crest collapse during the Period Collapse at the beginning of the dam break. The default value is zero (0). See Section 5.10.8.2.
Depth Fully Breached ==
 \(\langle\) depth_fully_breached \(\rangle\) ]
Classic and HPC Sets the height (not elevation) of the dam failure opening when fully breached. The default value is zero (0). See Section 5.10.8.2.
End Define Classic and HPC Ends a Define Control block of .toc commands for the operating rules applied to hydraulic structures, pumps and other controllable devices. See Section 5.10.1.1.
Ex Failed ==
 \(\langle\) Ex \(\rangle\) ]
Classic and HPC Sets Ex for the breached section of the DF channel. See Section 5.10.8.2. This command overwrites the default Ex values set by the Weir Type Intact/Failed command. See Table 5.23.
Ex Intact ==
 \(\langle\) Ex \(\rangle\) ]
Classic and HPC Ex Intact sets Ex (the weir flow equation exponent) for the un-breached section of the DF channel. See Section 5.10.8.2. This command overwrites the default Ex values set by the Weir Type Intact/Failed command. See Table 5.23.
Gate Height Fully Open ==
 \(\langle\) height \(\rangle\) ]
Classic and HPC For vertically moving gates the height (not elevation) of the gate when fully open above the gate’s seat. If not set, the 1d_nwk “Height” attribute is used. Metric units (default) are metres. Using Units == US Customary, the units are feet.
Gate Opening [ {} | (%) ]  ==
 [ [ ++| –| {}]  | \(\langle\) opening \(\rangle\) |  {CLOSE} |  OPEN |  NO CHANGE ]
Classic and HPC The position the gate is to be operated towards. A “++” or “–” before \(\langle\) opening \(\rangle\) will incrementally open or close the gate by the value of \(\langle\) opening \(\rangle\), otherwise \(\langle\) opening \(\rangle\) is taken as the absolute position. The units of \(\langle\) opening \(\rangle\) are in m or ft, unless “(%)” is specified, where it is the percentage of the fully gate open position. CLOSE will start moving the gate to the fully closed position, while OPEN will start moving the gate to the fully open position. NO CHANGE means that the gate operation remains unchanged. The default setting is CLOSE.
Gate Seat Vertical Offset ==
 \(\langle\) offset \(\rangle\) ]
Classic and HPC The difference in height in metres (or feet if Units == US Customary) between the spillway crest and the seat of the gate.
Gate Speed [ {} | (min) ]  ==
 \(\langle\) speed \(\rangle\) ]
Classic and HPC The speed at which the gate moves. Units are m/s or ft/s or if “(min)” is specified in m/min or ft/min. See Sections 5.10.3, 5.10.4, 5.10.5 and 5.10.6.
Gate Type ==
 [ VERTICAL UNDERFLOW |  VERTICAL OVERFLOW |  HORIZONTAL SINGLE |  HORIZONTAL DOUBLE ]
Classic and HPC Sets the type of gate arrangement. VERTICAL/HORIZONTAL indicates the direction of the gate movement. SINGLE is a single gate, while DOUBLE are two gates that move in/out from either side. See Section 5.10.4.
Gate Width Fully Open ==
 \(\langle\) width \(\rangle\) ]
Classic and HPC For horizontally moving gates the width of the gate(s) when fully open. Units are m or ft. If not set, the 1d_nwk “Width_or_Dia” attribute is used. See Section 5.10.4.
Method ==
 \(\langle\) method \(\rangle\) ]
Classic and HPC Sets which method to use for the hydraulic calculations. As of the 2013-12 release this command does not need to be applied, as it is intended for use should alternative equations become available for a structure in future releases.
Operation ==
 [ NO CHANGE ]
Classic and HPC Keep the operation of the structure unchanged. UNCHANGED can also be used instead of NO CHANGE. This function can be applied to all operational structures types.
Orifice Height Fully Open ==
 \(\langle\) height \(\rangle\) ]
Classic and HPC Optional command to set the height of the piping orifice when fully breached. If omitted, the value set by 1d_nwk Height_or_WF attribute is used. See Section 5.10.8.1.
Orifice Opening ==
 [ {CLOSE} |  OPEN |  NO CHANGE ]
Classic and HPC The breach status of a Pipe Failure Channel. CLOSE will keep the breach to the fully closed, while OPEN will start the breaching process. NO CHANGE means that the DF channel operation remains unchanged. The default status is CLOSE. See Section 5.10.8.1.
Orifice Width Fully Open ==
 \(\langle\) width \(\rangle\) ]
Classic and HPC Optional command to set the width of the piping orifice when fully breached. If omitted, the value set by 1d_nwk Width_or_Dia attribute is used. See Section 5.10.8.1.
Period Collapse [ {} | (min) | (s) ]  ==
 [ {0.0} |  \(\langle\) period \(\rangle\) ]
Classic and HPC

For PF channels, sets the time in hour taken to ‘shut close’ the piping failure channel after it reaches the full extend. The default value is 0 (i.e. no collapsing at the end of pipe failure). See Section 5.10.8.1.

For DF channels, sets the time in hour taken to rapidly change the dam breach opening at the beginning of the dam break. The default value for DF channels is 0 (i.e. no collapsing at the beginning dam failure). See Section 5.10.8.2.

Units are in hours by default, but minutes or seconds can be used if “(min)” or “(s)” is specified.
Period Failure [ {} | (min) | (s)  ==
 [ {0.0167} |  \(\langle\) period \(\rangle\) ]
Classic and HPC

For PF channels, Sets the time in hours taken to reach the full size of piping failure. The default value is 0.0166667 (i.e. 60 seconds). See Section 5.10.8.1.

For DF channels, Sets the time in hours taken to reach the full size of dam failure. The default value is 0.0166667 (i.e. 60 seconds). See Section 5.10.8.2.

Units are in hours by default, but minutes or seconds can be used if “(min)” or “(s)” is specified.
Period Opening/Closing [ {} | (min) | (s) ] ==
 [ {0.167} |  \(\langle\) period \(\rangle\) ]
Classic and HPC

The time taken to fully open a closed gate or to fully close an open gate or the time taken to start the pump up or shut it down. Units are in hours by default, but minutes or seconds can be used if “(min)” or “(s)” is specified. For example, specifying either of the commands below will set the time taken to open/close the gate to half an hour:

Period Opening/Closing == 0.5
Period Opening/Closing (min) == 30
Period Opening/Closing (s) == 1800

If this command is omitted the default opening/closing period is 0.167hrs.

This command is identical to Period Startup/Shutdown and the two can be used interchangeably.
Period Startup/Shutdown [ {} | (min) | (s) ] ==
 [ {0.167} |  \(\langle\) period \(\rangle\) ]
Classic and HPC

The time taken to fully open a closed gate or to fully close an open gate or the time taken to start the pump up or shut it down. Units are in hours by default, but minutes or seconds can be used if “(min)” or “(s)” is specified. For example, specifying either of the commands below will set the time taken to open/close the gate to half an hour:

Period Opening/Closing == 0.5
Period Opening/Closing (min) == 30
Period Opening/Closing (s) == 1800

If this command is omitted the default opening/closing period is 0.167hrs.

This command is identical to Period Opening/Closing and the two can be used interchangeably.
Pump Capacity ==
 \(\langle\) flow \(\rangle\) |  \(\langle\) discharge_curve \(\rangle\) ]
Classic and HPC The flow capacity of the pump either as a constant flow or reference to a dep. If a constant flow rate, specify \(\langle\) flow \(\rangle\). If a head-discharge curve specify the name of the curve in the Depth Discharge Database.
Pump Number ==
 \(\langle\) no_pumps \(\rangle\) ]
Classic and HPC Number of pumps in parallel.
Pump Operation ==
 [ ON |  OFF |  NO CHANGE ]
Classic and HPC Turns the operation of the pump on or off, or keeps the current operation unchanged.
Sa Failed ==
 \(\langle\) Sa \(\rangle\) ]
Classic and HPC Sets Sa (the Villemonte equation coefficient a) for the breached section of the DF channel. See Section 5.10.8.2. This command overwrites the default Sa values set by the Weir Type Intact/Failed command.
Sa Intact ==
 \(\langle\) Sa \(\rangle\) ]
Classic and HPC Sets Sa (the Villemonte equation coefficient a) for the un-breached section of the DF channel. See Section 5.10.8.2. This command overwrites the default Sa values set by the Weir Type Intact/Failed command.
Sb Failed ==
 \(\langle\) Sb \(\rangle\) ]
Classic and HPC Sets Sb (the Villemonte equation coefficient b) for the breached section of the DF channel. See Section 5.10.8.2. This command overwrites the default Ex values set by the Weir Type Intact/Failed command.
Sb Intact ==
 \(\langle\) Sb \(\rangle\) ]
Classic and HPC Sb Intact sets Sb (the Villemonte equation coefficient b) for the un-breached section of the DF channel. See Section 5.10.8.2. This command overwrites the default Ex values set by the Weir Type Intact/Failed command. See Table 5.23.
Side Slope (degree) ==
 [ 90 |  \(\langle\) slope_in_degree \(\rangle\) ]
Classic and HPC Sets the angle of side slope in degree. This is used for bottom width and flow area calculation. The default value is 90°, i.e. vertical side walls. See Section 5.10.8.2.
Top Width Collapse ==
 \(\langle\) top_width \(\rangle\) ]
Classic and HPC Sets the top width that opens up during the Period Collapse. This command is optional. If not defined, the collapse width is set proportionally as Top Width Fully Breached* Depth Collapse / Depth Fully Breached. See Section 5.10.8.2.
Top Width Fully Breached ==
 \(\langle\) top_width \(\rangle\) ]
Classic and HPC Sets the top width of the dam failure channel opening when fully breached. Note that the total flow with of the DF channel is set by the 1d_nwk Width_or_Dia attribute. This value can be set smaller than the Width_or_Dia if the maximum breach width does not reach the total width of the dam crest. See Section 5.10.8.2.
Weir Height [ {} | % ]  ==
 [ [++| –|**| //] | \(\langle\) weir_height \(\rangle\) ]
Classic and HPC

The height (not elevation) of the weir above its fully down (open) state to operate towards. The % option allows the specification of the percentage of the weir height that is up (0% would indicate completely lowered and 100% completely raised).

Note that the height of the weir above the crest when fully up is set by the 1d_nwk Height_or_WF attribute.
Weir Height Speed [ {} | (min)  ==
 \(\langle\) speed \(\rangle\) ]
Classic and HPC The speed at which the weir moves in the vertical. Units are m/s or ft/s or if “(min)” is specified in m/min or ft/min.
Weir Type Failed ==
 \(\langle\) weir_type \(\rangle\)  ]
Classic and HPC Sets the weir parameters for the DF channel based on Table 5.14. The default Weir Type Intact is “WB”, and the default Weir Type Failed is “WW”. See Table 5.23.
Weir Type Intact ==
 \(\langle\) weir_type \(\rangle\)  ]
Classic and HPC Sets the weir parameters for the DF channel based on Table 5.14. The default Weir Type Intact is “WB”, and the default Weir Type Failed is “WW”. See Table 5.23.
Weir Width [ {} | % ]  ==
 \(\langle\) weir_width \(\rangle\) ]
Classic and HPC

The width (not elevation) of the weir to operate towards. The % option allows the specification of the percentage of the weir width that is open (0% would indicate completely closed and 100% completely open). See Section 5.10.7.

Note that the full width of the weir is set by the 1d_nwk Width_or_Dia attribute.
Weir Width Speed [ {} | (min) ]  ==
 \(\langle\) speed \(\rangle\) ]
Classic and HPC The speed at which the weir moves in the horizontal. Units are m/s or ft/s or if “(min)” is specified in m/min or ft/min. See Section 5.10.7.
Orifice Shape ==
 [ {Rectangular} | Circular ]
Classic and HPC Sets the shape of the orifice, the default shape is rectangular. See Section 5.10.8.1.
Number of Piers ==
 [ {0} ]
Classic and HPC Sets the number of piers over a weir. For operational weirs, see Section 5.10.7. For dam failure modelling, applying the USBR (1987) approach, see Section 5.10.8.2. The default value is 0.
Kp ==
 [ {0} | \(\langle\) value \(\rangle\) ]
Classic and HPC

Sets the pier contraction coefficient. See Section 5.10.7.

The default value is set to zero (0) for backward compatibility. The following values for the pier contraction coefficient Kp are recommended by USBR (1987):

  • Square-nosed piers with corners rounded on a radius equal to approximately 0.1 of the pier thickness: Kp = 0.02.
  • Round-nosed piers: Kp = 0.01.
  • Pointed-nose piers: Kp = 0.0.
Ka ==
 [ {0} | \(\langle\) value \(\rangle\) ]
Classic and HPC Sets the abutment contraction coefficient. See Section 5.10.7.

The default value is set to zero (0) for backward compatibility. The recommended values, by USBR (1987), for the abutment contraction coefficient Ka are:

  • Square abutments with headwall at 90° to direction of flow: Ka = 0.20.
  • Rounded abutments with headwall at 90° to direction of flow, when 0.15H0≤ r≤ 0.5H0: Ka = 0.10.
  • Rounded abutments where r \(\rangle\) 0.5H0, and headwall is placed not more than 45° to direction of flow: Ka = 0.0.
Kp Intact ==
 [ {0} | \(\langle\) value \(\rangle\) ]
Classic and HPC Sets the pier contraction coefficient. See Section 5.10.8.2 for details.

The default value is set to zero (0) for backward compatibility. The following values for the pier contraction coefficient Kp are recommended by USBR (1987).

  • Square-nosed piers with corners rounded on a radius equal to approximately 0.1 of the pier thickness: Kp = 0.02
  • Round-nosed piers: Kp = 0.01
  • Pointed-nose piers: Kp = 0.0
Ka Intact ==
 [ {0} | \(\langle\) value \(\rangle\) ]
Classic and HPC Sets the abutment contraction coefficient. See Section 5.10.8.2 for details.

The default value is set to zero (0) for backward compatibility. The recommended values, by USBR (1987), for the abutment contraction coefficient Ka are:

  • Square abutments with headwall at 90° to direction of flow: Ka = 0.20.

  • Rounded abutments with headwall at 90° to direction of flow, when 0.15H0≤ r≤ 0.5H0: Ka = 0.10.

  • Rounded abutments where r \(\rangle\) 0.5H0, and headwall is placed not more than 45° to direction of flow: Ka = 0.0.

Discharge Curve Type ==
 [ {Upstream Depth}  |  Head Difference  |  Pump ]

Classic and HPC

Used to specify how the depth/head discharge curves are calculated in QO channels. See Section 5.10.3.

  • Upstream Depth: (default) Uses the upstream depth above the channel invert for the depth discharge curve regardless of the downstream water level.
  • Head Difference: Uses the difference in upstream and downstream water levels to calculate flow rates from head discharge curves. This option is more appropriate for hydraulic structures that experience downstream controlled flow regimes.
  • Pump: Similar to a 1D pump channel, this option uses the pumping head (i.e., downstream water level minus upstream water level to calculate flow rates from head discharge curves). The flow is always in the direction the channel is digitised. Typically, the curve has decreasing flows with increasing pumping head.
Depth Breached ==
 \(\langle\) initial breach depth \(\rangle\) ]
Classic and HPC Sets the initial breach status of the DF channel. Metric units (default) are metres. Using Units == US Customary, the units are feet. See Section 5.10.8.2.
Top Width Breached ==
 \(\langle\) initial breach depth \(\rangle\) ]
Classic and HPC Sets the initial breach status of the DF channel. Metric units (default) are metres. Using Units == US Customary, the units are feet. See Section 5.10.8.2.

References

Ansar M. and Nair S. (2003). Flow Computations at STA-1 West Gated Spillways. South Florida Water Management District.
USBR. (1987). Design of Small Dams [Technology & Engineering]. U.S. Dept. of the Interior, Bureau of Reclamation, 1987-. https://www.usbr.gov/tsc/techreferences/mands/mands-pdfs/SmallDams.pdf