Appendix D — TBC Commands

The TUFLOW Boundary Control File (.tbc) includes commands and data inputs to set boundaries and initial conditions, it is read into the .tcf using the BC Control File command. For more information on the .tbc see Section 4.1.7. Boundaries and initial conditions are discussed in Chapter 8. The available TBC commands are listed below. For an explanation of the command syntax, see Commands.

D.1 TBC Commands

BC Database == <.csv_file>

Sets the active BC Database file as described in Section 8.5. The file is usually created using spreadsheet software such as Microsoft Excel.

If the BC Database is specified in the TUFLOW .tcf file, it is set as the active database for both 2D and 1D models. However, the active database can be changed at any stage in the .tbc and .ecf files by repeating the command with the new database set as the <.csv_file>.

A BC Database must be specified before any of the other BC commands are used.

BC Event Name == <bc_event_name>

Legacy command - expand to find out more

Sets the active BC name to be substituted where <bc_event_text> (see BC Event Text) occurs in the BC Database. See Section 7.5.2 of the 2018 TUFLOW Manual for details on this legacy feature.

This command is normally specified in the .tcf file, and only used in the .tbc file if the event boundaries vary by event within the model. For example, it may be set to “Q100” to read in the 100 year catchment inflows, then set as “H010” to read in the 10 year ocean levels for the downstream boundary. Note that, in this case, the locations of the catchment inflows and downstream boundaries would have to be placed in two separate GIS layers, with each layer read using Read GIS BC after the relevant BC Event Name command as shown below:

BC Event Name == H010
Read GIS BC == gis\2d_bc_head_boundaries.shp
BC Event Name == Q100
Read GIS BC == gis\2d_bc_flow_boundaries.shp

BC Event Source == <bc_event_text> | <bc_event_name>

This command is normally specified in the .tcf file. It is only used in the .tbc if the event boundaries vary by event within the model or if the <bc_event_text> value needs to change (this should be very unlikely unless wanted to split different boundaries into groups). Also see BC Event Source for the .tcf file.

ERROR 2313 occurs if <bc_event_text> is not unique for a simulation.

Combines BC Event Name and BC Event Text into one command, and can occur up to 100 times to allow multiple events within the one simulation. Cannot be used in conjunction with BC Event Text.

BC Event Text == <bc_event_text>

Legacy command - expand to find out more

Sets the text in the BC Database that is to be substituted by the BC Event Name command value. See Section 7.5.2 of the 2018 TUFLOW Manual for details on this legacy feature.

This command is normally specified in the .tcf file, and only used in the .tbc file if for some reason the <bc_event_text> value needs to change (this should be very unlikely unless wanting to split the different boundaries into groups). Also see BC Event Text for the .tcf file.

Blank BC Type == <bc_type> | {NONE}

If a blank BC type occurs the value entered is used. If NONE (the default) is specified, a BC type must be assigned to every object in 2d_bc layers.

This command can be repeated within the .tbc file as per the example lines below.

BLANK BC TYPE == SX
Read GIS BC == gis\2d_bc_M02_culverts_TD15006.shp
BLANK BC TYPE == NONE     ! will revert back to an error

Blank HQ Slope == <slope>

A default HQ slope can be specified directly in the .tbc, and can be repeated prior to reading different HQ boundaries (in separate layers). Note, <slope> will only be used if no boundary name is specified for the 2d_bc HQ boundary (as a specified for the HQ boundary slope is given preference over the name).

Global Rainfall Area Factor == {1.0} | <area_factor>

Sets the factor applied to the global rainfall after the initial loss and continuing losses have been applied. This is useful if increasing the rainfall within the area covered by the active (Code 1) cells to compensate for areas that contribute to the runoff that are not included in the active model area.

Global Rainfall BC == <bc_name>

Sets the BC name in the BC database that defines the global rainfall.

Using metric units (default), the rainfall is specified as mm versus time in hours. This is converted to m\(^{3}\)/s and applied as a source versus time (ST). Using Units == US Customary, the units are inches verses time. TUFLOW converts it to ft\(^{3}\)/s

This command applies rainfall to all active cells. If the rainfall being applied is the same for all cells, this command negates the need to use a 2d_rf layer.

See Section 8.4.3.1.2 for further information.

If used in conjunction with the commands Global Rainfall Initial Loss and Global Rainfall Continuing Loss to apply initial and continuing losses, The Global Rainfall BC command must occur after the two preceding commands as shown in the example below else no losses will be applied:

Global Rainfall Initial Loss == 10
Global Rainfall Continuing Loss == 2
Global Rainfall BC == rainfall

See also the command Global Rainfall Area Factor.

Global Rainfall Continuing Loss == {0} | <CL>

Sets the continuing loss rate for any global rainfall. See Section 8.4.3.1.6.

Note that this rate does not apply to rainfall set via Read GIS RF, Rainfall Control File or Read Grid RF.

Using metric units (default) the rate is mm/h. Using Units == US Customary, the rate is inch/h.

This command must occur prior to the command Global Rainfall BC else no losses will be applied.

Note that prior to the 2020-10-AA release, rainfall losses in the materials files were not applied to global rainfall boundaries for TUFLOW Classic, and were cumulatively applied with global losses for TUFLOW HPC. From the 2020-10-AA release onwards, global rainfall loss commands are ignored if losses are also set in the materials file for both Classic and HPC.

Global Rainfall Initial Loss == {0} | <IL>

Sets the initial loss rate for any global rainfall. See Section 8.4.3.1.6.

Note that this rate does not apply to rainfall set via Read GIS RF, Rainfall Control File or Read Grid RF.

Using metric units (default) the value is in mm. Using Units == US Customary, the value is in inches.

This command must occur prior to the command Global Rainfall BC else no losses will be applied.

If Event == <e1> | <e2> | <e3> | …

Controls which commands to process for different events (see Appendix A).

If Scenario == <s1> | <s2> | <s3> | …

Controls which commands to process for different scenarios (see Appendix A).

Read GIS BC == <gis_layer>

Reads the location and attributes of 2D model boundary conditions as described in Section 8.4.1. Uses 2d_bc GIS layers, as described in Table 8.6.

Read GIS RF == <gis_layer>

Reads the polygons for applying rainfall directly to 2D cells, as described by RF in Table 8.5. Uses 2d_rf GIS layers, as described in Table 8.12.

Also refer to the .tbc command Read RowCol RF and the .tcf command Read Grid RF.

Negative rainfall values when using Read GIS RF are treated as a loss (e.g. evaporation). No IL/CL values that apply to positive rainfall are applied to negative values. Previously negative values were treated as zero.

2d_rf Rainfall Polygons with unique names may overlap and their respective source terms apply cumulatively on a cell by cell basis. If they overlap and have the same Name attribute, only the first is used.

Read GIS SA [ {} | <option> ] == <gis_layer>

Available <option> are: “ALL”, “PITS”, “STREAM ONLY”, “STREAM IGNORE”, “RF”, “PO” and “TRIGGER”.

Reads the polygons for distributing source flows over the 2D domain(s) as described in Section 8.4.2. Usually used for specifying rainfall runoff (flow) directly onto the 2D domain(s).

Any of the options for spatially distributing flow (“ALL”, “PITS”, or the defaults “STREAM ONLY” and “STREAM IGNORE” when used in conjunction with Read GIS Streams) can be used in combination with any of the special options “RF”, “PO”, and “TRIGGER”.

The “ALL” option is available to apply the flow or rainfall to all Code 1 cells (wet or dry active cells) within the polygon. Not applied to any inactive or water level boundary condition or HX 1D/2D linkage cells. If using the “ALL” option the double precision version may be needed as this is a similar approach to direct rainfall modelling.

The “PITS” option directs the inflow only to 2D cells that are connected to a 1D pit or node connected to the 2D domain using “SX” for the Conn_1D_2D (previously Topo_ID) 1d_nwk attribute. The inflow is spread equally over the applicable 2D cells. An ERROR occurs if no 2D cells are found within the region.

When Read GIS Streams is active, SA region flow is by default distributed to streamline cells and any non-streamline wet cells within the SA region. Two options are available to further control the distribution to streamlines, as described in Section 8.4.2.1.1:

The “STREAM ONLY” option will only apply the SA inflows to the streamline cells (i.e. no non-streamline wet cells in the SA region will receive an inflow). Note, this is the default approach adopted by the original, and no longer supported, TUFLOW GPU (not HPC) solver.
The “STREAM IGNORE” option will ignore all streamline cells within the SA region(s) and distribute the inflows using the standard approach for SA inflows (i.e. lowest cell if all wet, otherwise distributed over the wet cells).

The “RF” (rainfall) option is available to specify rainfall hyetographs (mm versus hours: metric units / inches versus hours: US customary units) instead of flow hydrographs. See Section 8.4.2.2 for more information. Negative rainfall values when using Read GIS SA RF are treated as a loss (e.g. evaporation). No IL/CL values that apply to positive rainfall are applied to negative values. Previously negative values were treated as zero.

The “TRIGGER” option allows the initiation of inflow hydrographs based on a flow or water level trigger so that, for example, reservoir failures can be initiated based on when the flood wave reaches the reservoir rather than at a fixed time. See Section 8.4.2.3 for more details.

The “PO” option models seepage or infiltration based on a varying water level or flow rate elsewhere in the model. This feature is used to model the seepage of groundwater into a coastal lagoon that was dependent on the water level in the lagoon as observed from long-term historical measurements. See Section 8.4.2.4 for more details.

2d_sa polygons may overlap and their respective source terms apply cumulatively on a cell by cell basis.

Read GIS Streams == <gis_layer>

Streamlines, as described in Section 8.4.2.1.1, allow the user to apply SA inflows (via Read GIS SA) along the waterways rather than to the lowest cell when all cells within the SA region are dry.

The Read GIS Streams command can be used one or more times in the .tbc file to define streamline cells. Streamlines are typically line objects, usually representing the path of the waterways. One attribute is required, being the Stream Order as an integer. GIS and other software have the ability to generate streamlines from DEMs, and usually assign a stream order to each stream line. If needed, rearrange (or copy) the attributes so that the first attribute is the stream order one.

Point and region objects are also recognised, for a point object the cell in which the point falls is designated as a stream cell. For a region object, all cells with the cell centre (ZC) within the polygon are assigned as stream cells. The stream cells within SA regions are output in the SAC Check file.

Note only streams with a stream order greater than zero (0) are used by TUFLOW. Streams that are not to be used for applying SA inflows can be assigned a stream order of 0 or deleted from the layer.

If SA Proportion to Depth == ON (default setting), the distribution of SA inflows according to depth only applies to wet non-streamline cells. The approach adopted is as follows:

The total inflow assigned to streamline cells within a SA region is proportioned according to the number of streamline cells versus wet non-streamline cells.
The distribution of the inflow allocated to streamline cells is weighted equally between cells.
The distribution of the inflow allocated to wet non-streamline cells is weighted according to the depth of water in the cells.

By default, any wet cells that are not streamline cells are also included in the distribution of the SA inflow. See Read GIS SA STREAM ONLY and Read GIS SA STREAM IGNORE options for controlling streamline inflows.

Read RowCol RF == <mid_file>

Legacy command - expand to find out more

Reads the rainfall cell by cell using just the .mid file (in a similar manner to other Read RowCol commands). The first two attributes of the .mid file must be the row and column of the 2D cell and the next three attributes must be as described in Table 7‑7 of the 2018 TUFLOW Manual. To create this layer, select all ZC points from a 2d_zpt layer, save the selection as another layer, restructure the attributes so that row (n) and column (m) remain as the first two, remove the other attributes, and add the attributes as described in Table 7‑7 of the 2018 TUFLOW Manual. Update the Name attribute to one or more rainfall boundaries. Different proportions of different rainfall hyetographs can be applied by duplicating the layer and having one layer for each rainfall boundary.

Also refer to the .tbc command Read GIS RF and the .tcf command Read Grid RF.

Spatial Database == OFF | TCF

This is an optional command when using the GeoPackage input format. It sets the GeoPackage database to use for subsequent GIS inputs.

Unused HX and SX Connections == {ERROR} | WARNING

See Unused HX and SX Connections under .tcf file commands. The command can be used several times in a .tbc file to change from ERROR to WARNING and vice versa if a different level of checking is required for different 2d_bc layers. When reading and checking a 2d_bc layer, the latest occurrence of this command applies.