Section 8 Boundaries and Initial Conditions

8.1 Introduction

Boundary conditions are a crucial part of hydrodynamic modelling, providing the inputs where fluids can enter or leave the hydrodynamic model area. This chapter of the manual discusses the available boundary conditions and the boundary condition database, where constant and time-series of boundary elements are specified. 1D and 2D boundaries are discussed together in this chapter as both access the same boundary database (see Section 8.6), although separate databases can be set up if desired.

The options for applying initial conditions to the 1D and 2D domains of the model are also discussed.

8.2 Recommended BC Arrangements

This section discusses the recommended boundary condition arrangements for downstream, inflow and internal boundaries, summarised in Table 8.1.

The recommended arrangements of downstream boundaries are:

Where the downstream boundary is a well-defined water level (e.g. the ocean or a large lake), water level boundaries are typically specified using 1D or 2D HT (water level vs time) boundaries. Note that both outflow and inflow may occur with water level boundaries.
Where the downstream boundary is intended to represent a “reasonable continuation” of a river, a stage-discharge relationship may be specified using a 1D or 2D HQ (water level vs flow, also commonly referred to as a stage-discharge) boundary. Note that real rivers may exhibit a hysteresis in the stage-discharge relationship (sometimes termed a “looped rating curve”). When this occurs the discharge at a particular water level may be different at different stages in the flood, for example a higher flow may occur on the rising limb compared to the same gauge level on the falling limb. A single height-flow (HQ) curve is therefore an approximation of flood behaviour. Sensitivity testing of any downstream HQ boundaries is recommended, if results in the area of interest are sensitive to changes in HQ curve, consider moving the downstream boundary further from the area of interest.
In some situations, a hydraulic structure that is inlet controlled acts as the downstream control, in which case, the boundary specified downstream of the structure will have no influence on the results upstream of the structure. For such cases, a downstream water level (HT) boundary may be used with a water level defined below the ground level. In TUFLOW Classic, with a downstream boundary where a water level has been specified below the ground level, for a positive bed slope (based on slope from upstream cell centre to cell face), upstream friction based flow (which may be supercritical) is assumed based on the bed slope, whilst for negative (adverse) slope, weir flow is assumed. For TUFLOW HPC, with a downstream boundary with a defined water level below ground level, it becomes a ‘weir’ calculation - similar to a broad-crested weir. It is possible that subcritical flow just upstream of the boundary may become critical or supercritical at the face where the weir is. Flow that is already supercritical will remain supercritical.

The recommended arrangements of inflow/internal boundaries are:

For fluvial flood (river/streams breaking bank) models it is common to use an inflow boundary (flow vs time or QT). However, in some situations upstream levels may be known more accurately than flows (level gauges are common whereas cross-section integrated flow measurements are rare) and a water level boundary (HT) may be used instead - particularly during model calibration.
For 2D pluvial (rainfall exceeding drainage capacity) flood models, inflows may also be defined using 2D flow sources and sinks such as a Rainfall (RF) or SA boundaries.
For models where the rate of inflow changes dramatically, such as in a dam-break scenario, a QT boundary may have instability issues, in which case the flow vs time inflow may be defined using a area based Source-Area (SA) boundary. SA boundaries are typically more stable than QT boundaries. Alternatively the dam break can be modelled via representation of the storage upstream of the dam within the model with the failure being represented via either a dynamic 1D dambreak channel (DF or PF type channel - refer Section 5.10.8) or 2D via variable geometry (variable 2D z shape) - refer Section 7.3.5.3.

For both 1D and 2D models, it is critically important that the inflow and downstream boundary placement location does not affect the model results within the primary area of interest. It is an essential step during the early stages of model creation to sensitivity check the location of the boundary to confirm its location does not cause a material difference in water levels within the region of interest for the modelling. If a difference in result does occur, greater distance between the area of interest and the boundary location should be considered.

With regard to 2D boundaries, particular attention should be given to the placement of water level (HQ and HT) and flow (QT) boundaries. They should be:

Digitised as line objects approximately perpendicular to the flow direction. The boundary can be digitised at any orientation to the 2D grid (i.e. does not need to be parallel to the grid) and can be defined using a line with multiple vertices and segments (i.e. it does not have to be a straight line). The reason these boundaries should be digitised perpendicular to flow is that the boundary, depending on type and options (refer Section 8.5.1), may force a uniform water level along the boundary cells. Spurious circulations can occur along the boundary if it is digitised along (as opposed to across) a waterway. This is often noticed by viewing the flow velocity vectors in the vicinity of the boundary or by an oscillating delta volume (dV) value in the output window (refer to Section 14.2).
Placed at the edge of the model active area boundary. To achieve this, snap the line vertices to those of the code polygon that defines the model active area. If the boundary is placed inside of the active area, bi-directional and/or recirculating flows are likely to occur. If the boundary line is significantly outside the active code polygon, then flow may not be able to reach the boundary and leave the model.
Have end points at sufficient elevation so that water levels at the boundary never reach the ends of the line.
Specifically for the stage-discharge (HQ) boundary, the boundary should only span one primary flow path. If the stage-discharge relationship is to be auto-calculated, the boundary end points should have elevations that are only just a bit above the highest expected water level, alternative the ‘d’ attribute can be used to set the maximum depth, see Table 8.6. This is to ensure that the digitised stage-discharge table has sufficient resolution over the actual working range of the boundary. Further, HQ curves generated for very shallow surface elevation slopes may cause model stability challenges.

A good check for the boundary locations is to compare peak flood extent (e.g. maximum water level grid) after a simulation with the active model area and associated boundary locations; typically water should not touch the edge of the model unless a boundary is defined. If water does occur at the edge of the domain, a process called ‘Glass-Walling’, boundaries of the active model area may need to be reviewed and added as appropriate.

Table 8.1 provides an overview of the boundary types typically used for different locations.

Table 8.1: **Recommended BC Arrangements**
Type of Boundary	1D	2D
Ocean or Estuary	HT	HT
Lake	HT	HT
River/Creek Outflow	HQ or HT	HQ or HT
River/Creek Inflow	QT as point on inflow node.	QT line (preferred) or SA region
Local Catchment Inflows around the edge of model or within model.	QT as regions (flow is distributed between nodes within a region)	SA. Use SA with PITS option for directing inflows directly to 1d pits (also referred to as gully traps).
Direct Rainfall (No Hydrology Inflows)	No option at present	RF or possibly SA (with RF option).
Dambreak Hydrograph	QT	SA or QT. SA may offer greater stability and better mass error if mass errors occur using QT.
Pumps	P (Pump) channel	1D linked via SX preferred. SH possible
Infiltration	No option at present other than specifying a negative QT.	Specify rainfall losses on a materail basis (Section 7.3.6.4) or use the soil infiltration feature (Section 7.3.7). Alternatively, RF can be used by specifying negative values.
Groundwater Level	HT	2D HT if on the surface or specify a GT level when using Interflow functionality for sub-surface groundwater level.

8.3 Solver Specific Considerations

8.3.1 Classic Specific Boundaries / Options

There are a number of boundary types that are considered legacy types, are not commonly used, nor recommended to be used. These boundary types are not supported in HPC/Quadtree and are not currently planned to be supported. These include:

ST - Flow vs Time. For an alternative, use the 2d_sa layer (Section 8.5.2).
QH - Flow vs Water Level.
VG - Variable Geometry. For an alternative, use Variable Z Shapes (Section 7.3.5.3).
WT - Wind Stresses. For an alternative, use either an external stress boundary (Section 8.8) or cyclone boundary (Section 8.7).
HS - Sinusoidal Water Level. In TUFLOW Classic these were initially a fixed field boundary where a number of tidal constituents (phase, amplitude and period) could be specified instead of a time-series. This was done initially in TUFLOW Classic in th 1990’s to be more memory efficient, however, memory (in particular time-series data) is typically no longer a limiting factor, so this approach has not been adopted for HPC. In TUFLOW Classic, HS and HT boundaries can be applied simultaneously to represent the different components of the boundary - for example a sinusoidal tide (HS) and a storm surge component (applied as HT), with the summation giving the overall storm tide. If multiple boundaries are to be applied to the same cells (e.g. to apply a storm surge on top of an ocean tide), these must be in separate GIS layers. In contrast, TUFLOW HPC does not support HS boundaries, or the combining of multiple water level boundaries on the same cells. Instead the tidal and surge components must be combined into a single HT time series.

8.3.2 HPC Specific Boundaries / Options

8.3.2.1 HPC Energy Options for 2D HT, HQ and QT Boundaries

Enforcing a uniform water level along the length of a boundary is not always realistic, and in some situations can lead to recirculating flow around the boundary (high velocity flow into the model towards one end of the boundary only for much of this flow to leave the model near the other end of the boundary). Historically, this could sometimes be remedied by increasing the viscosity applied along the boundary. For the TUFLOW HPC scheme we have however found a better approach (drawn from CFD modelling), to utilise a uniform total energy level along the boundary.

Consider the height vs time (HT) boundary, the approach is to utilise the user defined elevation as a total energy, and then apply a negative elevation correction to elevation on in-flowing cells (it is also permissible to apply an energy correction as a positive elevation adjustment on out-flowing cells, but generally this is not necessary for stabilising the boundary). This approach works well, however, it also means that for fast flowing inflow boundaries, a significant discrepancy will occur between the user-specified water elevation and the realised elevation in the model. This discrepancy is addressed by redefining the user-defined elevation as the water surface elevation corresponding to the Root Mean Squared (RMS) inflow velocity:

\[\begin{equation} h_{i} = H(t) + \frac{\bar{v^{2}} - v_{i}^{2}}{2g} \tag{8.1} \end{equation}\]

Where:

\(H(t)\) is the user define height vs time boundary data
\(\bar{v^{2}}\) is the mean square flow velocity averaged over boundary cells that are inflowing
\(v_{i}^{2}\) is the magnitude squared of flow velocity at the boundary cells
\(h_{i}\) is the applied water level at the boundary cells

Note, that this energy correction is only applied on in-flowing cells. In practice this approach means that for an out-flowing boundary the water level is constant over the length of the boundary line, but for an inflowing boundary some variation in water level will be observed along the length of the boundary with slower flowing regions being slightly above the defined elevation and faster flowing regions being slightly below the defined elevation.

For a QT boundary, the user specifies the flow rate as a function of time, not an elevation. However, internal to the software a fixed elevation boundary is utilised (it is a HX boundary connected to 1D storage node – refer Section 10.2.1 for a more detailed description of HX boundaries). Recirculation may also occur on the QT boundary (more so when it is digitised oblique to the flow path or digitised over highly irregular terrain), which again is addressed using the same energy correction described above.

Two new approaches have been introduced in the 2023-03 release and are available for HPC only (including Quadtree). The original approach (Method A) is the default for TUFLOW Classic, while Method B and Method C are new options for HPC. The extent of the energy corrections for the different approaches are detailed in Table 8.2. Note that Method C, which does not apply the correction to HX channel end boundaries is the default.

HPC Boundary Approach == Method A | Method B | {Method C}

Table 8.2: **HPC Boundary Approach Descriptions**
Method	Description
Method A	No energy corrections applied (backward compatible)
Method B	Energy correction applied for: HT and HQ boundaries QT boundaries HX boundaries connected to a single 1D node (refer Section 10.2.1)
Method C (default)	Energy correction applied for: HT and HQ boundaries QT boundaries

8.3.2.2 HPC HQ Boundary Approach

The HQ boundary computes the flux across the entire boundary line and uses a rating curve to apply a water level to the model. Each line is treated as a separate boundary and has a stage-discharge relationship, this is consistent with the TUFLOW Classic approach to HQ boundaries. Earlier versions of TUFLOW HPC applied the water surface slope on a cell by cell basis. It is possible to revert to all model HQ boundaries using a cell by cell approach by specifying ‘Cell’ within the .tcf command:

HPC HQ Boundary Approach == {Total} | Cell

8.3.2.3 HPC HQ Boundary Stability

For cross-sections with a very low longitudinal slope, the stage vs flow (HQ) relationship can become unstable - a small change in flow causes a change in level that causes a similar but opposite change in flow. This manifests as high frequency noise on the HQ boundary levels and flows, but unless the model has fine temporal output resolution it can go unnoticed. Starting with release 2023-03-AD, the flow at all HQ boundaries is monitored for stability during the simulation. A stability warning message will be printed if at any timestep the flow at a given HQ boundary is (1) greater than 0.1% of the maximum flow defined in the HQ table for that boundary, and (2) less than 80% of the flow at that boundary in the previous timestep. The instabilities are easily addressed by calculating time-filtered flows and using these instead for the HQ table lookup and interpolation:

\[\begin{equation} Q_{f,i} = \frac{(F - 1)Q_{f,i-1} + Q_i}{F} \end{equation}\]

Where:

\(Q_{f,i}\) is the filtered boundary flow at timestep \(i\) (initialised as zero)
\(Q_i\) is the instantaneous boundary flow
\(F\) is the filtering factor (must be greater than or equal to 1.)

Starting with release 2023-03-AD, the user may specify the global HQ boundary filter constant \(F\) using the command below. The default value is 1, which means no filtering (for backward compatibility).

HPC HQ Boundary Filter Constant == <float> | {1}

8.3.2.4 HPC Additional Boundary Options

A number of other commands are available for controlling the behaviour of boundaries which are specific to the HPC solver. In most instances, these can be left at the default value. Refer to the following Appendix links for further details on each of these commands:

HPC Infiltration Drying Approach == Method A | Method B
HPC SX Momentum Approach == Method A | {Method B}

8.3.2.5 Quadtree BC Parallel Inertia Approach

Inflow boundaries should be perpendicular to inflow direction, but sometimes this is not possible and a slightly oblique boundary is required. For a momentum conserving scheme is it important that the incoming flow brings with it the correct amount of transverse momentum. With the 2023-03-AA release, the handling of transverse momentum, or parallel inertia, for Quadtree simulations (“QT”, “HT” and “HX” type 2d_bc layers) has been changed to “Method B” to provide better consistency with TUFLOW Classic and HPC. To revert to the 2020 release method, use “Method A” with the following command:

Quadtree BC Parallel Inertia Approach == Method A | {Method B}

8.4 1D Boundaries (1d_bc Layers)

Boundary conditions for 1D domains are defined using one or more 1d_bc GIS layers. The different types of boundaries and links are described in Table 8.3.

GIS 1d_bc layer(s) generally contain points that are snapped to the 1D node in a 1d_nwk layer. Each point has several attributes, as described in Table 8.4.

In addition to point GIS objects, regions can be specified for 1D QT boundaries. If a region is used, the QT hydrograph is equally distributed to all nodes falling within the region that are not assigned a water level (H) boundary (this includes nodes connected to the 2D domain via a 2D SX). If no suitable nodes are found within a QT region an ERROR occurs.

Note: It is not possible to assign both a flow type boundary and water level type boundary to the same 1D node. For example, a HT and QT boundary on the same node.

Table 8.3: **1D Boundary Condition and Link Types**
Type	Description	Comments
Water Level
HQ	Water Level (Head) versus Flow (m)	Assigns a water level to the node based on the flow entering the node. This boundary is normally applied at the downstream end of a model. The water level versus flow (HQ) curve can be: Manually assigned using the 1d_bc GIS layer ““Name”” attribute (Table 8.4) and the boundary database (Section 8.6). An automatically generated HQ curve based on the cross-sectional properties and a specified friction slope. Specify “slope=friction_slope” (e.g. slope=0.01) for the “Name” attribute in the 1d_bc point layer (Table 8.4) defining the HQ boundary. As long as your boundary is sufficiently far from your area of interest, the friction slope can be estimated from the two nearest cross-sections to the downstream boundary. This feature requires a single channel connected to the node and does not work with channels using HW cross-sections with varying roughness. This functionality was added in the 2023-03-AD release.
HT	Water Level (Head) versus Time (m)	Assigns a water level to the node based on a water level versus time curve using the 1d_bc GIS layer ““Name”” attribute (Table 8.4) and the boundary database (Section 8.6). If other HT or HS boundaries are applied to the node, the water level is set to the sum of the water level boundaries.
Treatment		1D nodes can be wet or dry. If the water level is below the bed, computationally the bed level is assigned as the water level to the node. As the water level in the node is defined by the boundary, the node’s storage has no bearing on the results.
Combinations		Any number of 1D water level boundaries can be assigned to the same node. The sum of the water levels is assigned as the boundary. For example, a storm tide may be specified as a combination of a tidal HS boundary, a HT boundary of the storm surge and another HT boundary of the wave set up. The HS boundary would be water elevations and the two HT boundaries water depths. If you have a 2D SX boundary connected to a node and also have a HT and/or HS boundary at the same node, the 2D SX boundary prevails and no warning is given.
Flow
QH	Flow vs Water Level (Head) (m³/s)	Assigns a flow to the node based on the water level of the node at the previous half timestep using the 1d_bc GIS layer ““Name”” attribute (Table 8.4) and the boundary database (Section 8.6).
QT	Flow versus Time (m³/s)	Assigns a flow into the node based on a flow versus time curve using the 1d_bc GIS layer ““Name”” attribute (Table 8.4) and the boundary database (Section 8.6). A negative flow extracts water from the node. A region (polygon) can be used to equally distribute the flow hydrograph to all nodes that fall within the region. Any nodes that are an H boundary or are connected to a 2D SX cell are not included. Where pits are connected to the 2D domain, flow is applied to the bottom of the pit (bottom 1D node). The limit on the number of 1D QT regions assigned to a 1D node is ten (10).
Treatment		The 1D node can be wet or dry. The storage of the 1D node influences the results. If the node storage is made excessively large, the flow hydrograph is attenuated. Conversely, if it is under-sized the node is likely to be unstable.
Combinations		Any number of 1D flow boundaries can be assigned to the same node. The final flow is the sum of the flows assigned. A connection to a 2D HX boundary (automatically sets as a QX boundary at the node) can be applied in conjunction with other 1D Q boundaries.

Table 8.4: **1D Boundary Conditions (1d_bc) Attribute Descriptions**
No.	Default GIS Attribute Name	Description	Type
1	Type	The type of BC using one of the two letter flags described in Table 8.3.	Char(2)
2	Flags	Available flags are: S Apply a cubic spline fit to the boundary values (HT, QT, HQ and QH only). Useful for simulating tidal HT boundaries. The flags below are available for QT regions. Any combination of C, O and P can be used. If C, O or P are not specified, the flow is distributed to all non-H boundaries (1D H boundaries are any boundary starting with H or any 2D SX connections). Note, specifying CO is the same as specifying no flags. QT regions only: C Only direct flow into closed nodes. Closed nodes are those that only have culverts/pipes (C, R or I channels) connected. Pits may or may not be connected to a closed node. O Only direct flow into nodes that have at least one open channel connected. An open channel is any channel besides C, R or I channels. P Only direct flow into the bottom of pits, i.e. all nodes with a pit connected.	Char(6)
3	Name	The name of the BC in the BC Database (see Section 8.6). An error will be generated if no name is specified. Note for automatic calculation of HQ boundary a slope can be specified with keyword “slope=slope in m/m”. Refer to Table 8.3.	Char(50)
4	Description	Optional field for entering comments. Not used.	Char(250)

8.5 2D Boundaries (2d_bc, 2d_sa and 2d_rf Layers)

2D boundary conditions and linkages between the 1D and 2D domains are defined using a combination of one or more 2d_bc, 2d_sa or 2d_rf GIS layers. The different types of boundaries and links are described in Table 8.5.

Conditions have been built into TUFLOW to ensure a cell can only be assigned one boundary from a single GIS layer (except for: pit SX connections; sink/source points or lines with two vertices only; and polygon boundaries such as SA and RF).

Error checks have been incorporated into TUFLOW during the input pre-processing of 2D boundary conditions, TUFLOW stops with an error if a cell is:

Assigned a HT or HS that is already a QT, SX, ST or HX cell;
Assigned a 2D or HX that is already any other boundary;
Assigned a QT that is already a SX or H boundary; and
Assigned a ST or SX that is already an QT of H boundary.

Table 8.5: **2D Boundary Condition and Link Types**
Type	Description	Comments
Water Level Boundaries
HQ	Water Level (Head) versus Flow (Q)	Assigns a water level to the cell(s) based on a water level versus flow (stage-discharge) curve. Alternatively, TUFLOW can automatically generate the HQ curve if a slope is specified using the 2d_bc GIS layer “b” attribute (see Table 8.6). The variation in Manning’s n with depth feature is taken into account if automatically calculating the stage-discharge curve.
HT	Water Level (Head) versus Time	Assigns a water level to the cell(s) based on a water level versus time curve. Uses the 2d_bc GIS layer (See Section 8.5.1).
HX	Water Level (Head) from an eXternal Source (i.e. a 1D model)	For linking 1D and 2D domains. One or two 1D nodes provide a water level to the 2D every half timestep. TUFLOW automatically creates 1D QX boundaries at the 1D node(s) (see Table 8.3), which also receives flow from the 2D domain every half timestep. 2D HX boundaries are linked to 1D nodes using CN connections (see below and Figure 10.4). Uses the 2d_bc GIS layer (See Section 8.5.1).
2D	Links two 2D domains	Multiple domain boundary only available for TUFLOW Classic. Refer to Section 10.7.2. Uses the 2d_bc GIS layer (See Section 8.5.1).
HS	Sinusoidal (Tidal) Water Level (m)	Legacy boundary condition, available for Classic solver only. HT boundary is the recommended alternative. Refer to the 2018 TUFLOW Manual for further details.
Treatment		Cell(s) can be wet or dry. It is not a requirement that at least one cell is wet. All H line types can be oblique to the X-Y axes. The water level can vary in height along a line of cells. Tip: A common cause of instabilities at or near head boundaries at the start of a simulation is the initial water level specified at the adjacent cells is different to the head value. If your model immediately goes unstable or requires a very low timestep at the boundary, check your initial water levels. If it is a 2D HX boundary, the water levels in the 1D node and the 2D cells should be similar.
Combinations		Multiple water level boundaries that select the same cell are not recommended. For TUFLOW Classic, multiple HT or HS boundaries can be applied and the water level used is the sum of the water levels assigned. This is not recommended, and is not supported in TUFLOW HPC.
Groundwater Boundaries
GT	Groundwater Level versus Time	Assigns a groundwater level to the cell(s) based on a groundwater level versus time curve. The same groundwater level boundary applies to all vertical soil layers. If the specified groundwater level is below the elevation at the bottom of the layer, it is dry. If the specified groundwater level is above the elevation at the top of the layer, it is fully saturated. Uses the 2d_bc GIS layer (See Section 8.5.1).
Flow Boundaries	(Directional)
QT	Flow versus Time (m³/s)	Unused HX and SX Connections
Flow Boundaries	(non-Directional)
RF	Rainfall versus Time (mm) Infiltration versus Time (mm)	Applies a rainfall hyetograph. The rainfall time-series data must be in mm depth per timestep. It is converted to a hydrograph to smooth the transition from one rainfall period to another (the converted hydrograph appears in the .tlf file for cross-checking). Note: the input curve is not mm/h versus timestep, but mm vs timestep (i.e. each rainfall value is the amount of rain that fell in mm between the previous time and the current time). Uses the 2d_rf GIS layer (see Section 8.5.3).
SA	Flow versus Time (m³/s) over an area, or Rainfall versus Time (mm)	Applies the flow directly onto the cells within the polygon as a source. Negative values remove water directly from the cell(s). Most commonly used to model rainfall-runoff directly onto 2D domains with each polygon representing the sub-catchment of a hydrology model. SA boundaries have their own command, Read GIS SA, and own GIS layer, 2D_SA. Uses the 2d_sa GIS layer (see Section 8.5.2).
SD SH	Flow versus Depth or Head (m³/s)	Extracts the flow directly from the cells based on the depth (SD) or water level (SH) of the cell. Used for modelling pumps or other water extraction. Flow values must not be negative. SD or SH boundaries can be connected to another 2D cell or a 1D node, to model the discharge of a pump from one location in a model to another. The connection is made using a “SC” line (see below). In the boundary condition database, the Column 1 data would be depth (SD) or water level (SH) values and the Column 2 data would be flow. The flow value is the rate per 2D cell. If the 2D cell becomes dry, no flow occurs. Uses the 2d_bc GIS layer (see Section 8.5.1). An example 2D pump model is available in the Example Model Dataset on the TUFLOW Wiki. This boundary is not supported when using Quadtree and ERROR 2815 will be reported.
ST	Flow versus Time (m³/s)	Applies the flow directly to the cells as a source. Negative values remove water directly from the cell(s). Can be used to model concentrated inflows, pumps, springs, evaporation, etc. The flow specified in the boundary file is applied to each cell to which the boundary is connected. For example, if the boundary file specifies 2 m³/s and the ST is applied over four cells, then the total flow applied to the model would be 8 m³/s. If the total flow required is 2 m³/s, then an f attribute of 0.25 could be applied so that only 0.5 m³/s is applied to each cell. Uses the 2d_bc GIS layer (see Section 8.5.1). Alternatively, the Read GIS SA ALL could be used to distribute a flow equally over a number of cells.
SX	Source of flow from a 1D model.	For linking 1D and 2D domains. 2D SX cell(s) are connected to a 1D node using a single CN connection (see below). The net flow into/out of the 1D node is applied as a source to the 2D cells. For example, a 1D pipe in the 2D domain “sucks” water out of the upstream cell(s) and “pours” water back out at the downstream cell(s) using 2D SX boundaries. Uses the 2d_bc GIS layer (see Section 8.5.1). If an SX cell falls on an inactive cell (Code -1 or 0), the cell is set as active (Code 1).
Treatment		Sources are applied to all the specified cell(s) whether they are wet or dry, except for SA and SX, which apply only to wet cells, or the lowest dry cell if all the SA or SX cells are dry. Uses the 2d_bc GIS layer (see Section 8.5.1).
Combinations		Any number of source boundaries can be assigned to the same cell(s) whether they are SA, SD, SH, ST or SX. The source rate applied is the sum of the individual sources.
Connections
CN	Connection of 2D HX and 2D SX boundaries to 1D nodes	Used in GIS 2d_bc layers (see Section 8.5.1) to connect 2D HX and 2D SX boundaries to 1D nodes. A line is digitised that snaps the 2D HX or SX object to the 1D node. The direction or digitised length of the line is not important. The 1D node would be in a 1d_nwk layer. Note that if the 2D SX object is snapped to the 1D node, no CN object is required. However, 2D HX objects always require a CN object to connect to the 1D node. Alternatively, a CN point object can also be used instead of a line. An ERROR occurs if a CN object is not snapped to a 2D HX or 2D SX object, or is redundant (i.e. not needed). For backward compatibility, use Unused HX and SX Connections (.tcf file) or Unused HX and SX Connections (.tbc file) to change the ERROR to a WARNING. Note that for connections to 2D SX objects only one (1) CN object is required. Whereas 2D HX objects must have a minimum of two (2) CN objects – one at each end – with intermediate CN objects as needed to connect to any 1D nodes. The same node can be connected to each end of a HX line if the water level should not vary along the line.
SC	Connection of 2D SD and SH boundaries	Used for connecting 2D SD and SH boundaries to another 2D cell or 1D node (e.g. modelling the pumping of water from one location to another). The direction of the line is important and should be digitised from the SH/SD pump towards the 2D cell or node which the water is to be transferred to. Uses the 2d_bc GIS layer (see Section 8.5.1). An example 2D pump model is available in the Example Model Dataset on the TUFLOW Wiki. This boundary is not supported when using Quadtree and ERROR 2815 will be reported.
Wind
WT	Modelling Wind Stresses as a force on the water column	Legacy boundary condition and not recommended for use. Suggest use of the cyclone/hurricane (See Section 8.7) or external stress boundary (See Section 8.8) instead. Refer to the 2018 TUFLOW Manual for details on WT boundary.
Variable Geometry
VG	Modelling of breaches, etc.	Supported in TUFLOW Classic only. Not supported in TUFLOW HPC (including Quadtree). Used for varying cell elevations over time. Each cell, or line of cells, needs to be assigned a time series of elevations in the same manner that other boundaries are applied. Also see Section 7.3.5.3 on Variable Z Shape layers as a simpler alternative. Note: If varying the elevations of a HX cell, the elevation must not fall below the 1D bed value (see the attributes of the 1d_to_2d_check file for that cell). No run-time checks are made in this regard. Also see VG Z Adjustment.
Other
CD	Code Polygon	Objects in a GIS 2d_bc layer (see Section 8.5.1) used to define the grid’s cell codes using Read GIS Code BC as an alternative to Read GIS Code. The code value is set using the f attribute (see Table 8.6). The boundary lines are snapped to “CD” regions so that if the boundary location is adjusted, the boundary line and code region can move together. See Read GIS Code [{} \| BC], note that this must be read into the TGC file for setting the cell code.
IG	Ignore	An object in a GIS 2d_bc layer (see Section 8.5.1) can be elected to be ignored by using the “IG” type.
ZP	Elevation Point	Point objects that are used for setting elevations along HX lines. Only used by Read GIS Z HX Line which is specified in the geometry control file. See Section 8.5.1.

8.5.1 Boundary Conditions (2d_bc)

All boundary types listed in Table 8.5 apart from SA and RF are digitised within a 2d_bc GIS layer. The SA and RF boundaries have their own GIS layer and commands, as discussed in Section 8.5.2 and Section 8.5.3.

The attributes of the 2d_bc layers are described in Table 8.6. 2d_bc layers are referenced in the .tbc file using the command Read GIS BC. The GIS layer for a 2d_bc format file may contain points, lines and regions. The method for selecting cells for each is described below:

Points - When point objects are specified, this will select the cell that the point lies within. Snapping points to the cell sides or corners should be avoided as the selection may be unpredictable.

Lines - A “cross-hair” approach shown in Figure 8.1 is the method for selecting boundary or link cells when line objects are used. Cells are only selected if the boundary or link line intersects the cell cross-hairs that extend from the cell’s mid-sides. As such, if a boundary or link line starts inside a cell, and does not intersect with the cross-hairs, that cell will not be selected.

Regions - Region objects select all cells where the cell centroid lies within the region.

Figure 8.1: Cell Cross-hair Selection Approach

Up to 10 GIS layers are accepted in a single line for the Read GIS BC command. This is needed for where points and lines are both used (for example, if using HX lines and CN points), requiring multiple layers for the one command. The format is similar to the Read GIS Z Shape command with the different GIS layers separated by the “|” character. For example:

Read GIS BC == gis\2d_bc_hx_L.shp | gis\2d_bc_hx_P.shp

Also note that Blank BC Type can be used to set the default BC type to apply when no BC type is specified for an object in the 2d_bc GIS layer. This command may be repeated throughout the .tbc file to change the default setting for different 2d_bc layers. See Blank BC Type for more details.

Table 8.6: **2D Boundary Conditions (2d_bc) Attribute Descriptions**
No.	Default GIS Attribute Name	Description	Type
1	Type	The type of BC using one of the two letter flags described in Table 8.5. Also see Blank BC Type.	Char(2)
2	Flags	Optional flags as follows: HT, QT, SD, SH, VG: “S” – Fit a cubic spline curve to the data. Note, the “S” flag is only supported by TUFLOW Classic. HX: “A” – Used to override the RIDGE, MAX or RAISE option in Read GIS Z HX Line “L” – Sets the ZU and ZV elevations to be the same as the ZC value only if they are lower. This can improve instabilities where the ZU and ZV values are significantly lower in elevation, and can cause a sudden increase in transfer of water to/from the cell when the cell wets. “2” – TUFLOW Classic only. Can offer improved performance along HX lines by attempting to more smartly allocate water levels along a HX line when there is a dry section (“hump”) between 1D nodes. “R” – Applies the RIDGE option when setting elevations along HX lines using Read GIS Z HX Line. “S” – The “S” flag is a legacy and is not recommended unless Adjust Head at ESTRY Interface has been set to ON. Note, the “S” flag is only supported by TUFLOW Classic. “Z” – Adjust the ZC elevation at each cell at/along the 2D HX object to slightly above the 1D node bed elevation where the 2D HX ZC value is lower. The ZC elevation is set to 1mm above the interpolated 1D node bed less the Cell Wet/Dry Depth. An error occurs if the 2D cell ZC elevation is not above the interpolated 1D node bed. Also see HX ZC Check. It is not recommended to use the Z flag without first checking that the reason for the discrepancy in elevations between 1D and 2D domains is appropriate. QT: “A” – Do not use – not recommended or supported. Applies the original QT boundary, which required flow volume and direction inputs. SX: “Z” – Adjust the ZC elevation at each cell at/along/within the 2D SX object to below the 1D node bed elevation where ZC is higher. The ZC elevation is set to the Cell Wet/Dry Depth below the 1D node bed. An error occurs if the minimum ZC elevation plus the Cell Wet/Dry Depth at/along a SX object is not below the connected 1D node bed. Also see SX ZC Check permits the user to define a maximum change in ZC elevation. It is not recommended to use the Z flag without first checking that the reason for the discrepancy in elevations between 1D and 2D domains is appropriate. For SGS model, the minimum elevation inside a 2D cell is used to judge whether the 2D cell needs to be lowered or not. SX: “U” – No longer recommended or supported – replaced by the SD and SH boundary options. Was originally used to indicate that the 2D domain receives the flow (in or out) from the 1D domain, but does not set the water level at the 1D node. This allows pumps (modelled as a 1d_bc “QH” or other Q boundary at the 1D node) to discharge into or extract water from the 2D domain. CD, CN, HS, QC, RF, VC, WT, ZP, GT: Not used.	Char(3)
3	Name	HS, HT, QT, RF, SD, SH, ST, VG, WT, GT: The name of the BC in the BC Database (see Section 8.6). HQ: As per above, however, if using the HQ automatic stage-discharge curve generation (i.e. b attribute is greater than zero), this attribute is ignored. CD, CN, HX, QC, SX, VC, ZP: Not used.	Char(100)
4	f	HT, QT, RF, ST, VG: Multiplication factor applied to the boundary values. f is assigned a value of one (1) (which has no effect) if the absolute value is less than 0.0001. The values may also be factored using the ValueMult keyword (see Table 8.12). HS: Multiplication factor applied to the amplitude. A value of one (1) is applied if the field is left blank. CN: When used in conjunction (snapped) with a 2D HX object, sets the proportion or weighting to be applied in distributing the water level from the 1D node to the 2D cell. One or two 1D nodes can be connected to the same point on a 2D HX object. Checks are made that the sum of all CN f values connected to a 2D HX point or 2D HX line node equals one (1). If only one 1D node is connected, set f to one (1). An f value of zero (less than 0.001) is set to one (1). CD: The code value (see Table 7.2) to be assigned to cells falling on or within the object. SX: An offset for determining cell invert levels for distributing flows. ZP: Used to set the elevation of the 2D cells selected by the HX line. To adjust the height of the HX cells (usually to represent the levee crest or overtopping height) use ZP points snapped to the vertices of the HX line. If there are no points snapped to the HX line a CHECK is issued and the Zpt elevations of the HX cells are unchanged. ZP points are only used by Read GIS Z HX Line. HX, QC, VC, HQ, GT: Not used.	Float
5	d	2D: The minimum distance between 2D2D water level control points between vertices along the 2D line. If set to zero, only the vertices along the 2D line are used. This value should not be less than the larger of the two 2D domains’ cell sizes. HT, QT, RF, ST, VG: Amount added to the boundary values after the multiplication factor f above. Values may also be adjusted using the ValueAdd keyword (see Table 8.12). HX, ZP: Used to adjust the elevations up or down by the amount of the d attribute. Performs a similar function to the dZ attribute for 2d_zsh layers (see Table 7.5). For example, to raise the 2D HX cells by 0.2 metres set d to 0.2 (note this only applies if ZP points are snapped to the HX line). Only used by Read GIS Z HX Line. HQ: Used to specify the max depth to be used for generating the curve (if less than 1m it is set to 1m). QC, VC: The value of constant velocity or flow. SX: Reserved – set to zero. CD, CN, GT: Not used.	Float
6	td	HT, QT, RF, ST, VG: Incremental amount added per cell to the boundary’s time values. Time values may also be adjusted using the TimeAdd keyword (see Table 8.12). HS: Incremental phase lead or lag in degrees per cell along the boundary. SX: Reserved – set to zero. CD, CN, HX, QC, VC, ZP, GT: Not used.	Float
7	a	2D: Increasing this value from the default of 2 may improve stability, though may unacceptably attenuate results. HT, VG: Incremental adjustment of the multiplication factor per cell along the boundary. For the nth cell along the boundary the water level or cell elevation (h_n) is adjusted according to: \[h_{n} = h_{1}\:(1\:+\:a\:(n-1))+b\:(n-1)\] where h1 is the water level at the first cell. HS: Incremental adjustment of the amplitude per cell along the boundary. For the n^th cell along the boundary the amplitude (\(A\)) is adjusted according to: \[A_{n} = A_{n-1}+a\] HX: Used to add FLC value to all HX cells along the HX line. This can be useful for 1D/2D models where additional energy losses are needed to model the flow between a river (1D) and the floodplain (2D). Set to zero for backward compatibility. Alternatively, Read GIS FLC can be used. QT: Can be used to stabilise the boundary if needed by adding more “storage”. The default value is 5. Note: increasing this number by excessive amounts can unacceptably attenuate the hydrograph. QC, QT (with A Flag), VC: Angle of flow direction in degrees relative to the X-axis, (the X-axis left to right is 0°, Y-axis bottom to top is 90°). SX: Storage of the SX boundaries is based on the storage of the associated 1D node. The “a” attribute is a storage multiplier for the SX (but does not modify the associate 1D node storage). For example setting the value to 2 will double the storage. Note that an “a” value of 0.0 assumes a multiplier of 1.0. CD, CN, RF ST, ZP, GT: Not used.	Float
8	b	HT, QT (with A Flag), RF, ST, VG: Incremental amount added per cell to the boundary values after any incremental multiplication factor. Values may also be adjusted using the ValueAdd keyword (see Table 8.12). HQ: Water surface slope in m/m for automatic calculation of the stage-discharge relationship. If b is greater than zero, the automatic approach is adopted irrespective of whether the Name attribute is blank or not. Also see Blank HQ Slope. HS: Incremental amount added per cell to the mean water level. CD, CN, QC, SX, VC, ZP, GT: Not used. HX: Adjusts the WrF value along HX lines to adjust or calibrate the flow rate across a 1D/2D HX link when upstream controlled weir flow occurs. This is compatible with TUFLOW Classic only. This field similar to using the “a” attribute for applying additional energy (form) loss along the HX line which is valid for TUFLOW Classic and HPC models.	Float

8.5.1.1 Sloping Water Level Boundaries

Temporally and spatially varied 2D water level boundary can be defined by combining some of the boundary types listed in Table 8.5. This feature is particularly useful for coastal models where the tidal boundary varies in height and phase along the boundary. To do this, digitise a 2d_bc HX line along the boundary. At the ends of the boundary, and at any vertices in between, digitise 1d_bc HT (or HS) boundaries (ensure they are snapped to the 2d_bc HX line). At each 1D HT boundary specify the water level versus time hydrograph at that location (or use a HS curve). The water levels along the 2D HX line are based on a linear interpolation of the 1D HT/HS hydrographs. An example of this set up is shown in Figure 8.2.

Figure 8.2: Sloping Water Level Boundaries

8.5.1.2 Groundwater Boundaries

At the edges of the active model area, two boundary conditions are currently supported for the groundwater layers:

Sealed boundary, no inflow or outflow (default in absence of defined boundary); and
Groundwater level vs time (type “GT”) as detailed in Table 8.5.

To specify a groundwater level vs time boundary, a “GT” type boundary line can be digitised in the 2d_bc file format. The same groundwater level boundary applies to all vertical layers. If the specified groundwater level is below the elevation at the bottom of the layer, it is dry. If the specified groundwater level is above the elevation at the top of the layer, the layer is fully saturated.

8.5.2 Source Area Boundaries

A 2d_sa layer is used to define a Source – Area boundary (flow or rainfall vs time), applying the flow directly onto the cells within the digitised polygon. Negative values remove water directly from the cell(s). There are multiple options regarding these boundaries:

Source - Area boundary (2d_sa) - see Section 8.5.2.1.
Source - Area Rainfall boundary (2d_sa_rf) - see Section 8.5.2.2.
Source - Area Trigger option (2d_sa_tr) - see Section 8.5.2.3.
Source - Area Flow option (2d_sa_po) - see Section 8.5.2.4.

8.5.2.1 Source Area Options (2d_sa)

There are a number of options for distributing flows to cells within a SA region, these are:

Distributed firstly to the lowest cell and then distributing between wet cells (Read GIS SA). This is the default option.
Distributed to 2D cells connected to 1D pits (Read GIS SA PITS).
Distributed to all cells equally (Read GIS SA ALL).
Distributed using to streamlines (Read GIS SA STREAM ONLY).

The cells that the SA polygons are applying flow to can be checked using the _sac_check layer.

When distributing the water between the cells there are two options that can be specified in the .tcf. These are:

SA Minimum Depth, this sets a minimum depth below which flow will not be distributed to the cell (apart from the lowest cell). The default minimum depth is -99999 (i.e. 0 depth, representing a dry cell).
SA Proportion to Depth, this command proportions the SA inflows according to the depth of water. The default is ON, which proportions the flow according to the depth of water in the cells with deeper cells getting more flow.

The PITS option directs the inflow 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.

The ALL option is available to apply the flow/rainfall to all active cells (either wet or dry cells) within the region. Not including any inactive or cells that have a water level boundary or HX 1D/2D linkage applied. If using the ALL option the double precision (see Section 13.4.2) version may be needed when using TUFLOW Classic as this is a similar approach to direct rainfall modelling.

The STREAMS ONLY option is used in combination with the Read GIS Streams command. It 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). This is discussed further in Section 8.5.2.1.1.

Table 8.7 lists the attributes for 2d_sa layers which are referenced in the .tbc file using the command Read GIS SA to read in flow hydrographs

Table 8.7: **2D Source over Area (2d_sa) Attribute Descriptions**
No.	Default GIS Attribute Name	Description	Type
1	Name	The name of the BC in the BC Database (see Section 8.6). The 2023-03 release changes the behaviour of HPC and Classic models that use multiple SA polygons with the same boundary name. In the 2023-03 release or newer, these boundaries are treated separately; as if they were different boundary names with the same hydrograph. Previously, these SA boundaries would be treated as a single boundary and the cells selected by each polygon would be grouped together. If duplicate SA boundary names are encountered, TUFLOW will issue CHECK 2492 in the 2023-03 Release.	Char(100)

8.5.2.1.1 Streamlines

Streamlines allow the user to apply SA inflows along the waterways rather than to the lowest cell (when all cells are dry within the SA region). This approach can be useful to apply baseflows to a river channel for instance. If streamlines have been specified using the .tbc Read GIS Streams command, SA inflows are distributed along the 2D cells selected by the stream lines within each SA region.

Read GIS Streams can be used one or more times in the .tbc file to define streamline cells. Streamlines are line objects, usually representing the path of the waterways. One attribute is required, which is the Stream Order as an integer type. Only objects with a Stream Order greater than zero (0) are used by TUFLOW. Therefore, streams that are not to be used for applying SA inflows can be assigned a stream order of 0 (or deleted from the layer). The 2D cells along a streamline are selected as a series of continuous cells in the same manner as any other boundary line.

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 specified stream order.

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

The _sac_check layer will show those cells selected as streamline cells.

8.5.2.2 Rainfall Option (2d_sa_rf)

Read GIS SA RF (rainfall) option calculates flow from an input rainfall hyetograph based on catchment area, initial loss and continuing loss information specified in the 2d_sa_rf GIS file. Boundary condition inputs are specified as a rainfall hyetograph (mm versus hours) instead of flow hydrographs, which is required for the other Read GIS SA options.

Initial and continuing loss values applied through the Materials Definition file (.tmf or .csv format) are ignored when using the Read GIS SA RF (rainfall) option.

Table 8.8: **2D Source over Area Rainfall (2d_sa_rf) Attribute Descriptions**
No.	Default GIS Attribute Name	Description	Type
1	Name	The name of the BC in the BC Database (see Section 8.6). The 2023-03 release changes the behaviour of HPC and Classic models that use multiple SA polygons with the same boundary name. In the 2023-03 release or newer, these boundaries are treated separately; as if they were different boundary names with the same hydrograph. Previously, these SA boundaries would be treated as a single boundary and the cells selected by each polygon would be grouped together. If duplicate SA boundary names are encountered, TUFLOW will issue CHECK 2492 in the 2023-03 Release.	Char(100)
2	Catchment_Area	Additional attribute for the RF Option (Read GIS SA RF Command). The contributing catchment area in m² (if using SI units) or miles² (if using Units == US Customary). Note: This attribute is required as the polygon area is not used as the sub-catchment area because the rainfall area may be different to the polygon extent. A value of zero will trigger ERROR 2460.	Float
3	Rain_Gauge_Factor	A multiplier that allows for adjusting the rainfall due to spatial variations in the total rainfall. A value of zero will cause ERROR 2460 and the simulation will halt, see also Zero Rainfall Check command.	Float
4	IL	The Initial Loss amount in mm on inches (if using Units == US Customary).	Float
5	CL	The Continuing Loss rate in mm/hr or inches/hr (if using Units == US Customary).	Float

8.5.2.3 Trigger Option (2d_sa_tr)

Read GIS SA TRIGGER option allows the initiation of inflow hydrographs based on a flow or water level trigger. For example, reservoir failures can be initiated based on when the flood wave reaches the reservoir. An example of this option is:

Read GIS SA Trigger == gis\2d_sa_tr_dambreaks.shp

The 2d_sa_tr layer is a 2d_sa layer (with one attribute, Name), to which three additional attributes are added, as listed in Table 8.9. These are:

Trigger_Type
Trigger_Location
Trigger_Value

Every timestep during the simulation, the flow (Q_) or water level (H_) of the 2d_po object referenced by Trigger_Location is monitored. When the 2d_po exceeds the Trigger_Value value the SA hydrograph commences.

If applying the hydrograph as a dam break, when digitising the SA trigger polygon, it should preferably be on the downstream side of the dam wall, extending the width of the dam wall and possibly be several cells thick (in the direction of flow). If there are stability issues, enlarging the SA polygon will help, however applications have indicated the feature typically performs well with the SA polygon a few cells thick.

The 2d_po line (flow) or point (water level) referred to by Trigger_Location can be located anywhere in the model. For cascade reservoir failure modelling it would usually be modelled using a 2d_po flow line, or for a 2d_po water level point just upstream of the dam.

Note: 2d_po flow lines MUST be digitised from LEFT to RIGHT looking downstream (if not, the flow across the 2d_po line will be negative and the trigger value will never be reached).

Table 8.9: **2D Source over Area Trigger (2d_sa_tr) Attribute Descriptions**
No.	Default GIS Attribute Name	Description	Type
1	Name	The name of the BC in the BC Database (see Section 8.6). The 2023-03 release changes the behaviour of HPC and Classic models that use multiple SA polygons with the same boundary name. In the 2023-03 release or newer, these boundaries are treated separately; as if they were different boundary names with the same hydrograph. Previously, these SA boundaries would be treated as a single boundary and the cells selected by each polygon would be grouped together. If duplicate SA boundary names are encountered, TUFLOW will issue CHECK 2492 in the 2023-03 Release.	Char(100)
2	Trigger_Type	Trigger_Type must be set to “Q_” or “Flow” for a trigger based on a flow rate, or “H_” or “Level” for a trigger based on a water level.	Char(40)
3	Trigger_Location	Trigger_Location is the PO Label in a 2d_po layer (see Section 11.3.2.1). The 2d_po Type attribute must also be compatible with the Trigger_Type (i.e. it must include Q_ or H_ as appropriate).	Char(40)
4	Trigger_Value	Trigger_Value is the flow or water level value that triggers the start of the SA hydrograph.	Float

8.5.2.4 Flow Feature (2d_sa_po)

The Read GIS SA PO option models seepage or infiltration based on a varying water level or flow rate elsewhere in the model. This functionality is available when using TUFLOW Classic only. For example, modelling the seepage of groundwater into a coastal lagoon that is dependent on the water level in the lagoon.

The feature is set up as follows:

Create a 2d_po point object of Type “H_” at the water level location.
Add “Read GIS PO == …” to the .tcf file if not already there.
Create a new 2d_sa_po layer, as listed in Table 8.10. As of the 2023-03-AF release this layer is automatically created when using the Write Empty GIS Files command, previously this layer had to be created manually by adding the two following attributes to a 2d_sa layer:
1. PO_Type: Char of length 16
2. PO_Label: Char of max length 40
Digitise the SA polygon(s) covering the area of seepage or infiltration and for the attributes:
1. Set the Name attribute to the name of the water level vs flow curve in the BC database.
2. Set PO_Type to “H_”.
3. Set PO_Label to the PO Label of the relevant 2d_po “H_” point to be used to determine the flow from the h vs Q curve.
Add “Read GIS SA PO == …” to the .tbc file.

Alternatively, to base the SA flow on the flow elsewhere in the model, use a 2d_po line object of Type “Q_”. To check the SA in/outflow:

View the _MB.csv files. The SA in/outflow from the seepage or infiltration will be part/all of the SS columns.
Add “SS” to the Map Output Data Types command. This outputs the net in/outflow from all source flows (ST, SA, SX and rainfalls) over time.

Table 8.10: **2D Source over Area Flow Feature (2d_sa_po) Attribute Descriptions**
No.	Default GIS Attribute Name	Description	Type
1	Name	The name of the BC in the BC Database (see Section 8.6). The 2023-03 release changes the behaviour of HPC and Classic models that use multiple SA polygons with the same boundary name. In the 2023-03 release or newer, these boundaries are treated separately; as if they were different boundary names with the same hydrograph. Previously, these SA boundaries would be treated as a single boundary and the cells selected by each polygon would be grouped together. If duplicate SA boundary names are encountered, TUFLOW will issue CHECK 2492 in the 2023-03 Release.	Char(100)
2	PO_Type	PO_Type must be set to “Q_” to set the SA flow in/out of a model based on a flow rate, or “H_” to base it on a water level.	Char(16)
3	PO_Label	PO_Label is the Label attribute in a 2d_po layer (see Section 11.3.2.1). The 2d_po Type attribute must also be compatible with the PO_Type (i.e. it must include Q_ or H_ as appropriate).	Char(40)

8.5.2.5 Overlapping 2d_sa regions

SA regions may overlap and their respective source terms apply cumulatively on a cell by cell basis. With the TUFLOW Classic solution scheme there is no limit to the number of regions that stack up (i.e. overlap) at a given location. However, for the TUFLOW HPC scheme, the number of 2d_sa regions that apply at a given cell is limited to 4. If the model also utilises 2d_rf rainfall regions (Section 8.5.3), then these are also included in this limit (i.e. the maximum stacking depth of 2d_sa and 2d_rf regions is limited to 4). For HPC and Quadtree, the stack depth is checked at each cell and ERROR 2443 will result if the limit is exceeded.

8.5.3 Rainfall Boundaries

8.5.3.1 Rainfall Overview

Four approaches are available for applying rainfall directly to the 2D cells. These are listed below and described in the following sections.

Global rainfall: the same rainfall applies spatially over the model.
2d_rf layers: polygons are assigned a rainfall gauge and spatial and temporal adjustment factors.
Gridded rainfall: rainfall distribution over time as a series of grid files (.tif, .flt, .asc) or in a NetCDF file.
A rainfall control (.trfc) file: allows the user to specify rainfall gauges/points over the model and a series of commands to control how the rainfall is interpolated. This approach generates a series of rainfall grids available to the user for display or checking.

8.5.3.2 Considerations for Rainfall Modelling

When using rainfall as a principal source of the water within a model the following considerations should be made:

The entire catchment area should be included in the active code area.
It is highly recommended to use HPC, and sub-grid sampling (SGS), when modelling using direct rainfall. SGS has been found to significantly improve direct rainfall modelling by low flow transmission of water with minimal retention or blocking of flows (Ryan et al., 2022) plus significantly reduced sensitivity to cell size (Kitts et al., 2020).
TUFLOW supports a range of rainfall loss and soil infiltration options, for a comparison of these approaches, see the TUFLOW Wiki. These are split into two broad categories, defined by their respective calculation methods:
- Rainfall Excess Losses: This initial and continuing loss approach is a simplistic calculation method comparable to the rainfall excess loss methods included in traditional hydrology models.
- Soil Infiltration Losses: This approach is a more realistic representation of the actual physics associated with water infiltration into the soil and is recommended when using direct rainfall modelling.
Evaporation is typically implemented with a global negative rainfall. The 2023-03 release allows for negative rainfall to draw from the topmost groundwater layer under surface layer cells that are dry, thus mimicking evapotranspiration. See Section 7.4.5.2. Prior to the 2023-03 release this would only decrement the water in wet cells - until they dry – and would not draw from the cumulative infiltration layer.
Choice of wet-dry depth threshold. For models with intense rainfall, the water depths usually quickly exceed the default Cell Wet/Dry Depth of 0.002 m (SI units), but for models with long periods of light to moderate rates of rainfall or steap slopes, the water depths may be close to the threshold causing the the cells to alternate between wet and dry status as the “sheet flow” moves in waves over the terrain. This behaviour is not desirable, and is avoided by reducing the wet-dry depth threshold. For models with rainfall, a Cell Wet/Dry Depth of 0.0002 m (or 0.0007ft if using Units == US Customary) is recommended for both Classic and HPC solution schemes, unless using SGS. For HPC models with SGS enabled, lowering the Cell Wet/Dry Depth is not necessary, as the wetting/drying occurs in the SGS storage curve.
Model Precision: TUFLOW Classic uses an implicit finite difference solver for which the primary state variable is the water elevation. The use of water elevation as the primary variable can have limitations when run in single precision. When computing differences in water elevations between adjoining cells, numerical precision errors arise when the model has high altitude DEM data, or very thin sheet flow (i.e. rainfall models). When using TUFLOW Classic for models with high altitude and/or rainfall, it is therefore advisable to run the model with the double precision executable, see Section 13.4.2.The .tcf command Model Precision == Double can be used to ensure that only a double precision version of TUFLOW is used. TUFLOW HPC (including Quadtree) uses an explicit finite volume scheme based on water depth, and the single precision executable generally works well for models with high altitude and/or rainfall. If in doubt, or even just curious, the user may re-run the same model in double precision and compare the results.

8.5.3.3 Global Rainfall

To apply a uniform rainfall to all active cells, the .tbc command Global Rainfall BC may be used. The Global Rainfall BC command applies a rainfall depth to every active cell within the 2d_code layer based on the input hyetograph. The input hyetograph must be in mm versus time (or inches versus time if using Units == US Customary), and is applied using a stepped approach. The stepped approach holds the rainfall constant for the time interval (i.e. the rainfall has a histogram stair-step shape). This means, for example, the second rainfall value in the time-series is applied as a constant rainfall from the first time value to the second time value. As with all rainfall boundaries, the first and last rainfall entries should be set to zero, otherwise these rainfall values are applied as a constant rainfall if the simulation starts before or extends beyond the first and last time values in the rainfall time-series. The hyetograph information is converted to a flow, and the flow then applied at each cell. The histogram conversion takes into account any losses and can be found in the TLF file (search ‘Global Rainfall histogram’).

As of the 2020-10 release, for TUFLOW Classic models, if rainfall losses have been applied in a materials file (see Section 7.3.6.3) they will be applied to the global rainfall. Prior to the 2020-10 release, for TUFLOW Classic, they weren’t applied. In TUFLOW HPC models they were already applied in releases prior to 2020-10. In both solvers, if rainfall losses have been specified in the materials file (.csv or .tmf) in conjunction with the Global Rainfall Initial Loss or Global Rainfall Continuing Loss commands, the losses in the materials file are applied and the global rainfall loss commands ignored (and WARNING 2244 reported). Alternatively, Soil infiltration losses can be used (see Section 7.3.7).

The Map Output Data Types RFR and RFC may be used to view the rainfall rate (mm/hr or inch/hr) and cumulative rainfall (mm or inch) over time respectively (see Table 11.4).

An example of global direct rainfall model is provided in Module 6 - Part 1.

8.5.3.4 Rainfall Polygons (2d_rf)

The 2d_rf GIS layer applies a rainfall depth to every active cell within the digitised polygon, based on an input rainfall hyetograph. Table 8.11 lists the attributes in 2d_rf layers which are referenced in the .tbc file using the Read GIS RF command. The rainfall time-series data must be in mm versus time in hours (or inches versus time if using Units == US Customary). It is applied using a STEPPED approach. The STEPPED approach holds the rainfall constant for the time interval (i.e. the rainfall has a histogram stair-step shape). This means, for example, the second rainfall value in the time-series is applied as a constant rainfall from the first time value to the second time value. As with all rainfall boundaries, the first and last rainfall entries should be set to zero (otherwise these rainfall values are applied as a constant rainfall if the simulation starts before or extends beyond the first and last time values in the rainfall time-series).

The Map Output Data Types RFR and RFC may be used to view the rainfall rate (mm/hr or inch/hr) and cumulative rainfall (mm or inch) over time respectively (see Table 11.4).

Initial and continuing losses can be applied on a material-by-material basis (see Section 7.3.6.4). Initial and continuing losses are not applied to negative rainfall values (to model infiltration/evaporation). Alternatively, Soil infiltration losses can be used (see Section 7.3.7)

If the same rainfall is to be applied to all active cells in the model, the .tbc command Global Rainfall BC may be used in lieu of digitising a 2d_rf layer (see Section 8.5.3.3).

RF regions may overlap and their respective source terms apply cumulatively on a cell by cell basis. For TUFLOW Classic there is no limit to the number of regions that stack up (i.e. overlap) at a given location. However, for TUFLOW HPC (both uniform grid and Quadtree grid), the number of 2d_rf regions that apply at a given cell is limited to 4. If the model also utilises 2d_sa source regions (Section 8.5.2), then these are also included in this limit (i.e. the maximum stacking count of 2d_sa and 2d_rf regions is limited to 4). For HPC and Quadtree, the stack depth is checked at each cell and ERROR 2443 will result if the limit is exceeded.

An example direct rainfall model using rainfall polygons is provided in Module 6 - Part 2.

Table 8.11: **2D Direct Rainfall over Area (2d_rf) Attribute Descriptions**
No.	Default GIS Attribute Name	Description	Type
1	Name	The name of the rainfall1 BC in the BC Database (see Section 8.6). Note: If two or more RF inflows of the same Name cover the same cell, only the first RF inflow is used. It is recommended that each polygon has a unique Name and they do not overlap.	Char(100)
2	f1	A multiplier that allows for adjusting the rainfall due to spatial variations in the total rainfall. To vary the rainfall spatially, either apply different f1 and/or f2 attribute values to each polygon. Values of f1 greater than 1 are permitted when using 2d_rf polygons or points in a Rainfall Control File (.trfc). A value of zero will cause ERROR 2460 and the simulation will halt, see also Zero Rainfall Check command.	Float
3	f2	A second multiplier that allows for adjusting the rainfall spatially. A value of zero will cause zero rainfall to be applied. Values of f2 greater than 1 are permitted when using 2d_rf polygons or points in a Rainfall Control File (.trfc). A value of zero will cause ERROR 2460 and the simulation will halt, see also Zero Rainfall Check command.	Float

8.5.3.5 Gridded Rainfall

Rainfall may also be applied to the model using the .tcf command Read Grid RF. The command references a .csv index containing links to rainfall grids or a NetCDF file containing the time-varying data. This allows the applied rainfall to vary spatially across the model without the need to digitise multiple polygons within a 2d_rf GIS layer. If using the .csv file index the rainfall grids may be in any TUFLOW supported grid format (.tif, .flt, .asc), noting that .tif and .flt are much faster for TUFLOW to process than .asc.

For the .csv format the rainfall database contains two columns, the first being time (in simulation hours) and the second being the rainfall grid. There is no interpolation between times, so a stepped approach is applied. Each rainfall grid applies from the time of the previous rainfall grid in the .csv file up to the current time . Time increments do not have to be a constant interval. An example of a rainfall database is shown in Figure 8.3. The values within rainfall grid should be the rainfall depth in mm (or inches if using Units == US Customary) that have fallen over the previous period. In the example below the values in the 2^nd rainfall grid should be the total rainfall depths from time 0 to time 3 hours (i.e. not the rainfall intensity in mm/h or inch/h).

Figure 8.3: Example Rainfall Database

An example direct rainfall model using rainfall grids is provided in Tutorial Module 6 - Optional.

8.5.3.6 Rainfall Control File (.trfc file)

Rainfall can be temporally and spatially controlled, including interpolation of rainfall gauges over time, using a series of commands in a Rainfall Control File (.trfc).

The .trfc commands generate rainfall grids based on point rainfall gauges, with three methods available for spatial interpolation of the rainfall distribution. The rainfall distribution varies over time according to the rainfall at the gauges. The three methods for spatially interpolating the rainfall are:

IDW (Inverse Distance Weighting)
Polygons
TIN (Triangulation)

When the rainfall control file is processed during model initialisation a series of rainfall grids are output, which are then used by the simulation to vary the rainfall over the 2D domain(s). This feature may also be useful simply to generate the series of rainfall grids for other purposes or display. The rainfall grids are pre-processed to reduce memory usage whilst TUFLOW is running.

Note, only one .trfc file per 2D domain can be specified in the .tcf file using the Rainfall Control File command.

An example of a total rainfall depth grid, output when using the .trfc IDW approach and four rainfall gauges, is shown in Figure 8.4.

Figure 8.4: Example Depth Total Grid

Of note is that the polygon approach is similar to using a series of rainfall polygons read in via the .tbc Read GIS RF command. However, the .trfc file approach is significantly more memory efficient.

Whilst there isn’t a specific check file for the rainfall distribution when using generated rainfall grids, another advantage of the pre-processing of rainfall grids using this feature is that the grids it produces can be interrogated prior to the end of the simulation for checking purposes. Note, the generated rainfall grids are inclusive of adjustments made in the BC Database (e.g. multiplication factors used for climate change) and of adjustment factors in the input GIS layer’s attributes, but not inclusive of rainfall losses that may be specified in a materials file. The generated grids, together with a csv file for non NETcdf formats, can be utilised as gridded rainfall as per section 8.5.3.5 for subsequent simulations.

Map Output Data Types RFR or RFC can also be specified (see Table 11.4), these are inclusive of rainfall losses, however these results are output as the simulation progresses.

Example .trfc files are available in the TUFLOW Wiki Example Models and in Tutorial Module 6 - Part 3.

Appendix F lists and describes the available .trfc commands.

8.6 Boundary Condition (BC) Database

A boundary condition (BC) database is created using spreadsheet software such as Microsoft Excel. Two types of files are required:

A database or list of BC events, including information on where to find the BC data.
One or more files containing the boundary data (e.g. flow, level, rainfall data).

The database file must be .csv (comma delimited) formatted, or HEC-DSS (see Section 8.6.5). It must contain a row with the pre-defined keywords ‘Name’ and ‘Source’, as listed in Table 8.12. Other keywords control how data is extracted from the Source.

The BC data files can be in a variety of formats, as described for the ‘Source’ keyword in Table 8.12. Additional formats can be incorporated upon request. It is recommended that all .csv files originate from one spreadsheet with a worksheet dedicated to each .csv file. The Excel TUFLOW Tools.xlm macros can be used to export the worksheets to .csv format, see Section 17.3.5.

The active BC database is specified using the BC Database (.tcf file), BC Database (.ecf file) and/or BC Database (.tbc file) commands. Note, specifying BC Database in the .tcf file automatically applies to both 1D and 2D domains (i.e. there is no need to specify the command in the .ecf or .tbc files). The active database can be changed at any point by repeating the command in any of these files.

The maximum line length (i.e. number of characters including spaces and tabs) in a single line of a source file is 100,000 characters. If the keyword is not found in the “Name, Source” line, the default column is used to define the column of data for that keyword.

Table 8.12: **BC Database Keyword Descriptions**
Keyword	Description	Default Column
Name	The name of a BC data location. The name must be the same name as used in the GIS 1d_bc, 2d_bc, 2d_sa, 2d_sa_rf or 2d_rf layers. It may contain spaces and other characters, though must not contain any commas. It is not case sensitive. The name of a group of boundaries can be used for RAFTS (.loc and .tot files) and WBNM (via the .ts1 file format) hydrographs. For example, if “N1\|Local” is the boundary Name in a 1d_bc or 2d_bc layer, then the group is interpreted as the text to the right of the “\|” symbol (i.e. Local), and the text to the left is the ID (i.e. N1) of the time-series data in the file containing the hydrographs. In this example, TUFLOW: Searches for an entry “Local” in the Name column of the BC database. Opens the file in the Source column, say Q100.ts1. Extracts the hydrograph for node N1 from Q100.ts1. Using this approach, the size of the BC Database .csv file can be reduced from several hundred lines for large hydrologic models to a couple of lines.	N/A
Source	The file from which to extract the BC data. Acceptable formats are: Blank – if left blank, the BC data is assumed constant over time at the value specified under the Column 2 (Value) column (see Column 2 keyword below). Comma delimited (.csv) files. Must have a .csv extension. RAFTS-XP .tot and .loc files. 12, 16 and 20 field output is supported. TUFLOW .ts1 time-series boundary data format. This format is fast to process and should be used for input of large numbers of hydrographs. See the convert_to_ts1.exe utility (Section 17.3.1) for converting output from RAFTS, RORB, URBS and WBNM to .ts1 format). The ts1 is a comma separated file, which has additional header data to increase its read efficiency. The .ts1 file format is outlined on the TUFLOW Wiki on the TS1 file format page should you wish to use a script to write data using this format. FEWS files (.csv and .xml) for FEWS boundaries the source column should contain the keyword “FEWS” to indicate the .csv file format is a FEWS file and not a standard .csv file, followed by a vertical bar “\|” and then the filename. For example: WBNM _Meta.out files. The flow data is read from the 9^th data column in the hydrographs section of the _Meta.out file, this is the Qout_OS column. XP .int and .ext interface formats. Other file formats are included upon request. Note, the type of file is determined by the extension, therefore, ensure the file has the correct extension.	N/A
Column 1 or Time	For .csv files, the name of the first column of data (usually time values in simulation hours) in the .csv Source File. Other examples besides Time are Flow for a HQ (stage-discharge) boundary, or Mean Water Level for each wave component in a 2D HS (sinusoidal wave) boundary. For all other types of Source entry (including FEWS .csv), leave this field blank.	3
Column 2 or Value or ID	For .csv files, the name of the second column of data in the .csv Source File. For example, water levels in a HT boundary, flows for a QT boundary or water levels for a HQ boundary. For a Blank Source entry, the constant value to be applied. For example, to apply a mean water level to a HT boundary the source can be left blank and the water level entered in this column. For RAFTS-XP (.tot or .loc), WBNM _Meta.out and TUFLOW/ESTRY .ts1 files, the name of the hydrograph location to extract. For FEWS .csv and .xml boundaries the Location ID and Parameter ID need to be defined, separated by a vertical bar. The FEWS .csv file also supports event ensembles. For this an optional 3^rd argument can be specified defining the ensemble ID. In the 1^st boundary database entries below a FEWS .csv file is specified with the location ID “Location1” and the parameter ID “Q.sim.hist”. The 2^nd boundary entry includes a boundary ensemble number 1. For external wind stress boundaries (.tesf), used to define the wind speed (m/s) Note: it is NOT possible to combine the Value and ID keywords in the column label, for example “Value or ID”. If they are combined, the default column number of 4 is used.	4
Add Col 1 or TimeAdd	An amount to add to all Column 1 (normally time) values (e.g. a time shift) for the BC data event. If left blank or zero, there is no change to the time values. For external wind stress boundaries (.tesf), used to define the wind direction (degrees relative to East, ie. East = 0º, North = 90º, etc.). This field is ignored for Blank Source entries.	5
Mult Col 2 or ValueMult	A multiplication factor to apply to the Column 2 values. If left blank or one (1), there is no change to the values. Note, Mult Col 2 is applied before Add Col 2 below. This field is ignored for Blank Source entries.	6
Add Col 2 or ValueAdd	An amount to add to Column 2 values. If left blank or zero, there is no change to the values. Note, Add Col 2 is applied after Mult Col 2. For example, this could be used to add a base flow to a QT boundary or sea level rise allowance for a HT boundary. This field is ignored for Blank Source entries.	7
Column 3	For .csv files, the name of the third column of data when a third column of data is required. For example, the phase difference for each wave component in a 2D HS (sinusoidal wave) boundary. For all other types of Source entries, leave this field blank.	8
Column 4	For .csv files, the name of the fourth column of data when a fourth column of data is required. For example, the period for each wave component in a 2D HS (sinusoidal wave) boundary. For all other types of Source entries, leave this field blank.	9

8.6.1 BC Database Example

Figure 8.5 shows a simple example of a BC database setup in a worksheet that is exported as a .csv file for use by TUFLOW.

TUFLOW searches through the file until a row is found with the two keywords Name and Source. Name and Source do not have to be located in Columns 1 and 2 (although this is recommended).

Table 8.12 describes the purpose of each keyword and the default column where applicable. At present a range of formats are accepted, and other formats can be incorporated upon request.

The example above is interpreted as follows:

A boundary condition data location named “Level” is found in a boundary condition GIS file (eg. 2d_bc, 2d_sa, 2d_rf etc.). The boundary condition time-series data associated with it are found in the file heads.csv. Within the csv file, the time values are located under a column called “Time” and the BC values are located under a column “Lake Level”.
As an alternative to “Level” above, a boundary condition data location “Level (alternative)” is set a constant value of 2.
A boundary condition data location named “River Inflow” is found in a boundary condition GIS file. The time-series data associated with it is availabl in flows.csv. Within flows.csv, time details are found in the column titled “Time 1”. Boundary condition values are found in the column titled “River Flow”. Similarly, “Creek Inflow” and “Base Flow” are also located in flows.csv.
A boundary condition data location named “RAFTS Inflow” extracts the hydrograph from a RAFTS-XP .tot file named “rafts.tot” for RAFTS node “IN”.

The heads.csv and flows.csv files are created by saving the worksheets “heads.csv” and “flows.csv” as .csv files (see Figure 8.6 and Figure 8.7).

Figure 8.5: Simple BC Database Example (bc_dbase.csv)

Figure 8.6: Example BC Database Source Files (heads.csv)

Figure 8.7: Example BC Database Source Files (flows.csv)

8.6.2 BC Event Name Command

The ability to model multiple events using an Event File (.tef) file offers even more power and flexibility to using BC Event Text and BC Event Name, as discussed below. This avoids the need to have a separate .tcf file for each simulation. See Section 13.3.1 for details on using an event file. The BC Event Name will continue to be supported although users are encouraged to use the event file instead.

The BC Event Text and BC Event Name commands (.tcf file) minimise data repetition by removing the need to create a separate BC database .csv file for each event. These commands are also available in the .ecf file for 1D only models (BC Event Text and BC Event Name) and .tbc file (BC Event Text and BC Event Name). The commands allow a wildcard to be set in the BC database and the text to replace the wildcard. How the commands work is illustrated in the example below.

A BC database file worksheet is created, as illustrated in Figure 8.8, and the following lines are included in all .tcf files.

BC Database == ..\bcdbase\PR_bc_dbase.csv
BC Event Text == __event__

These lines can be specified in a separate file. The file can be read using the Read File command in all the .tcf files, see Section 4.2.15. This saves repeating these lines, and other common commands to all .tcf files.

The above commands set the active BC Database to ..\bcdbase\PR_bc_dbase.csv, and defines the text “__event__” as a wildcard to be replaced by the BC Event Name. The following command is added to the .tcf file for the 100-year flood simulation:

BC Event Name == Q100

TUFLOW replaces every occurrence of “__event__” with “Q100” in each line of the BC database. If “__event__” does not occur the line remains unchanged. In the example below, the following occurs:

For the BC event “Oxley Ck Inflow”, the BC data is read from file “Q100.csv” rather than “__event__.csv” as indicated in the spreadsheet.
Similarly, the same applies for “h Downstream” and “Paradise Ck Inflow” BC events.

Figure 8.8: Example BC Database Using Event Text

The file Q100.csv is created from the worksheet “Q100.csv” as shown below.

Figure 8.9: Example BC Database Source Files Using Event Text

To create other simulations, for example a five year flood simulation, it is simply a process of creating the Q005.csv file, saving a copy of the “Q100.tcf” file as “Q005.tcf” and changing BC Event Name to “Q005”:

BC Event Name == Q005

There is no need to create another BC database file. As discussed earlier, the newer Event File option eliminates the need for a separate control file (.tcf) and is the preferred approach, see Section 13.3.1 for details on using the event file approach.

8.6.3 TUFLOW Boundary Generators

The development of boundary conditions is usually model specific, although there are some common regional approaches to flow and rainfall generation. To assist with this, a number of boundary generator tools have been created within QGIS which allow the modeller to semi-automate the production of the BC Database, boundary data files for different events, patterns and storm duration and also an associated TUFLOW Event File. Currently, these exists for 3 regional hydrological approaches. For a description of each, the reader is referred to the relevant Wiki page:

Australian Rainfall and Runoff 2019 Tool (ARR to TUFLOW tool): The ARR to TUFLOW tool interacts with the Australian Bureau of Meteorology website, in conjunction with ARR input parameters, to generate rainfall hyetographs together with optional soil loss files depending on the method (tsoilf or material.csv).
UK Revitalised Flood Estimation Handbook 2 (ReFH2 to TUFLOW tool): This allows both flow hydrographs and rainfall hyetographs to be developed for a TUFLOW simulation for a range of events and storm durations based on imported FEH Catchment or point descriptors.
Auckland Region SCS to TUFLOW tool. This tool allows flow hydrographs to be developed for the Auckland, New Zealand region using the U.S. Soil Conservation Service (SCS) (now known as the Natural Resources Conservation Service, part of the U.S. Department of Agriculture) rainfall-runoff model. The implemented approach complies with Auckland City Council’s TP108 policy.

Please let support@tuflow.com know if you have suggestions for a boundary conditions generators

8.6.4 Delft FEWS Boundaries

Boundary timeseries in the Delft FEWS boundary format are supported, as shown in Table 8.12.

Delft FEWS .csv and .xml files are TUFLOW compatible. In both cases the keyword “FEWS” is required in the ‘Source’ field of the BC Database followed by a vertical bar “|” and then the Delft FEWS filename (for example FEWS | <sourcefile.csv>). Following ‘Source’ in the BC Database:

‘Column 1’ is not required. This is due to TUFLOW sourcing time information directly from the Delft FEWS file.
‘Column 2’ is needed to define the Location ID, Parameter ID, and when using the .csv format, the Ensemble ID. Each parameter is separated by a vertical bar. For example:

Note, ensemble ID information is only possible using the Delft FEWS .csv format. It is not possible using Delft FEWS xml format.

The header section for an input .xml is shown below. Any data in the timeseries with the value equal to that defined by the <missVal> in the header are ignored. Additional header tags are ignored by TUFLOW.

The FEWS Input File command can be used to set the duration of the TUFLOW simulation and the NetCDF Output Start Date based on information within the FEWS boundary file. FEWS Input File can refer to either a FEWS .csv or FEWS .xml file. Using this command, the duration and End Time value of the TUFLOW simulation is determined from the Delft FEWS input file. If using this approach, no End Time command should be included in the .tcf file. The start date defined in the FEWS input file is used to set the NetCDF output start date (e.g. NetCDF Output Start Date).

8.6.5 HEC-DSS Boundaries

The 2023-03 release introduced support for time-series data from HEC-DSS files within a boundary condition database. HEC-DSS is a database system for time series, curve, gridded data and more, developed by the U.S. Army Corps of Engineers Hydrologic Engineering Center (HEC). See their website at https://www.hec.usace.army.mil/software/hec-dss/ for more information. It is used by the HEC developed models for data input and output. Rather than convert HEC-DSS time-series curves for use in TUFLOW, this data can be accessed directly. HEC-DSS files organise data into paths with six parts (Part A – Part F) that resemble how files are organised on disk. Figure 8.10 shows an example DSS file with a single path, with the curve plotted below.

Figure 8.10: Example DSS File

To use a HEC-DSS time-series curve within a TUFLOW boundary condition database:

Provide the filename in the “Source” column.
Leave “Column 1”, which is used for time, blank (DSS files store the time with the curve values).
Identify the pathname in “Column 2.” Event placeholders such as event can be used as part of the pathname. Wildcards (*) can be used for parts of the path, however, ensure the wildcards will not select more than one path within the file.
The “Add” and “Mult” columns can be used to offset or scale the time-series values, the same as non-DSS time-series curves.

Figure 8.11 shows how the time-series curve above could be included in a boundary condition database. A wildcard is used for Part D of the pathname (date range). Note that the pathname must start with a forward slash (/).

Figure 8.11: Time-series Curve Example

By default, TUFLOW uses the first point in the time-series curve as TUFLOW time-zero. This can be changed using the new command “HEC-DSS Start Date” to identify the date/time that should be used for time-zero. The date should be in the isodate format: yyyy-mm-dd hh:mm:ss, where the time portions are optional. For example:

HEC-DSS Start Date == 2022-01-01

Note: Non-time series data such as gridded data from a HEC-DSS file is not supported.

8.7 Cyclones / Hurricanes / Typhoons

Wind and pressure fields created by severe storms can affected flooding and inundation in coastal areas. It is possible to apply a cyclone / hurricane / typhoon boundary within TUFLOW to capture these affects. Cyclone / hurricane / typhoon wind and pressure fields with the Holland parametric model (Holland, 1980) can be read in with either of the .tcf commands below (which are treated identically):

Read GIS Cyclone == \(\langle\)gis layer\(\rangle\)
Read GIS Hurricane == \(\langle\)gis layer\(\rangle\)

This command can be used to read a cyclone, hurricane or typhoon track. The attributes of the GIS layer are listed in Table 8.13 and are all float values. Only the first line in the layer is read and used for the track. Points are snapped to the line wherever attribute data are to be assigned. It is not necessary to have points snapped to every vertex of the line – values will be interpolated between the digitised points. There must be points with attribute data snapped to the start and end of the polyline track.

The optional No Pressure and No Wind options deactivate the pressure/wind fields respectively. E.g. Read GIS Cyclone No Wind == \(\langle\)gis layer\(\rangle\) will only apply the pressure field and ignore the wind.

Table 8.13: **GIS Attribute Details for Cyclone (2d_cyc) layer**
No.	Default GIS Attribute Name	Description	Type
1	Time	Time in hours.	Float
2	p0	Pressure at the eye (hPa).	Float
3	pn	Pressure of surrounds (hPa).	Float
4	R	Radius to maximum winds (m) (or ft if using Units == US Customary).	Float
5	B	See Queensland Government (2001).	Float
6	\(\rho_{air}\)	Density of Air (kg/m³) (or lb/ft³ if using Units == US Customary). If zero, Density of Air is used.	Float
7	km	Density of Air (kg/m³) (or lb/ft³ if using Units == US Customary). If zero, Density of Air is used.	Float
8	ThetaMax	See Queensland Government (2001).	Float
9	DeltaFM	See Queensland Government (2001).	Float
10	bw_speed	Background wind speed in m/s (or ft/s if using Units == US Customary). Ignored if less than or equal to zero.	Float
11	bw_dirn	Background wind direction in degrees relative to East (0°), North (90°), etc..	Float

The generation of the wind and pressure fields are based on Appendix C of “Queensland Climate Change and Community Vulnerability to Tropical Cyclones – Ocean Hazards Assessment – Stage 1” (Queensland Government, 2001).

The wind and pressure fields can be output using the WI10 and AP options for Map Output Data Types. The background wind is applied outside R (the radius of maximum winds), if it exceeds the cyclone/hurricane wind speed.

Note: that Latitude must be specified (via .tcf command “Latitude == \(\langle\)latitude value\(\rangle\)”).

8.8 External Stress Boundaries

The external stress control file (.tesf) allows the definition of time varying global or spatially varying external forcing such as wind or wave radiation stresses. This allows the user to specify one of the following types of wind / stress boundary:

Global wind (i.e. temporally but not spatially varying wind field is applied).
Grid Interpolation. Point winds are applied at locations within / near the model, these point winds are interpolated to gridded stresses across the model.
User specified time varying gridded datasets.

The wind time-series curve is entered as three columns of data (using Column 1, 2 and 3 labels in the bc_dbase). The three columns are:

Time (h)
Wind (m/s)
Direction (degrees relative to East, i.e. East = 0º, North = 90º, etc.).

Prior to the simulation the wind boundaries are converted into a shear stress boundary and this shear stress is applied to the model. The shear stress is calculated based on equation (8.2).

\[\begin{equation} \tau = C_{10}\ \rho_{air}\ U_{10} \tag{8.2} \end{equation}\]

Where:

\(\tau\) = shear stress in N/m².
\(ρ_{air}\) = density of air in kg/m³.
\(U_{10}\) = wind velocity at 10m above the mean water surface in m/s.
\(C_{10}\) = wind stress coefficient and is calculated using equation (8.3) based on J. Wu (1980) and J. Wu (1982).

\[\begin{equation} C_{10} = \left( 0.8 + 0.065\ U_{10} \right)\ \times 10^{- 3} \tag{8.3} \end{equation}\]

For US Customary units, wind velocity (\(U_{10}\)) is specified in ft/s, density (\(ρ_{air}\)) is specified in lb/ft³ and shear stress (\(\tau\) ) is calculated / output in lbf/ft².

For the interpolated stress grids, these are output to disk at model start-up and then loaded in during the model simulation as required. The grids can be used as a “check” file as they are written prior to the simulation starting. For each time in the specified boundary series two stress grids are produced, shear stress in the x direction (\(\tau_x\)) and shear stress in the Y direction (\(\tau_y\)). When interpolating grids from point data the wind boundary at each point is converted to \(\tau_x\) and \(\tau_y\) and these x and y component stresses are interpolated using the selected method (as described below).

Alternatively, a series of \(\tau_x\) and \(\tau_y\) grids can be directly read into the simulation. The input grids must be in a format TUFLOW supports for reading (see Section 4.4.1). For all formats except NetCDF, an index .csv file is input containing the time data in Column 1, and the filenames for the x and y component stresses in Columns 2 and 3 respectively. For the NetCDF format, time, \(\tau_x\) and \(\tau_y\) must all be variables in the same NetCDF file. The format of the user specified external grids is the same as produced by TUFLOW when interpolating from points to grids.

As the user specified gridded stresses are applied as a stress term (rather than a wind boundary) these could potentially be used for external stress forcing other than winds, for example wave radiation stresses.

All stress related commands (see Appendix G) are specified in the External Stress File (.tesf), which is referred to in the .tcf using the command, External Stress File. If this command is included TUFLOW automatically invokes the external stress functionality. Other .tcf commands relevant to the wind stress functionality are Density of Air, Density of Water, Wind/Wave Shallow Depths.

In the .tesf one of the following commands is required to apply global, interpolated from point or gridded stresses.

Global Wind BC: Used to invokes a global wind boundary.
Read GIS Wind Point and Read GIS Wind Poly invokes grid interpolation.
Read Gridded Tau invokes the use of a user specified grid.

If applying a global wind boundary, no additional .tesf file commands are required.

For the grid interpolation the following commands are applicable:

The GIS attribute format associated with the inputs called by the Read GIS Wind Point and Read GIS Wind Poly commands is provided in Table 8.14.

Table 8.14: **2D External Wind Stress (2d_ws) Attribute Descriptions**
No	Default GIS Attribute Name	Description	Type
1	Name	The name of the BC in the BC Database (see Section 8.6).	Char(100)

8.9 Initial Conditions

Two options are available for setting initial conditions in the model. Initial Water Levels (IWLs) can be defined in the 1D and 2D domains to set a global constant or spatially-varying water level. Alternatively, the use of restart files sets initial water levels, flow velocities and flow regime based on a previous simulation of the model.

8.9.1 Initial Water Levels (IWL)

8.9.1.1 1D Domains

For 1D domains, initial water levels (IWL) can be set globally as a constant using the .ecf command Set IWL. IWLs can also be set to vary spatially using one or more GIS layers. The default initial water level at 1D nodes is zero metres above datum (0 mAD).

To set up a GIS IWL layer for the 1D domains:

Create a 1d_iwl layer using an empty layer created by Write Empty GIS Files.
Digitise points snapped to nodes and assign each point an initial water level value, alternatively points can be copied from the _nwk_N_check files and assigned an IWL.
Save the GIS layer.
Use the Read GIS IWL command to read in the IWL values.

Any number of IWL layers may be used, noting that if a node’s IWL occurs more than once, the last occurrence prevails (i.e. TUFLOW or ESTRY overwrites any previous IWL already set).

Differences in initial water levels for related features in the 1D and 2D domain can cause model instabilities at the start of a model simulation. If your model becomes unstable in the first few timesteps, review the initial water level values to ensure they are consistent in both domains and also match the water level of any head boundaries that they are be connected to.

Table 8.15: **1D Initial Water Level (1d_iwl) Attribute Descriptions**
No	Default GIS Attribute Name	Description	Type
1	IWL	Initial water level of object relative to model datum (m).	Float

8.9.1.2 2D Domains

2D IWLs can be set globally as a constant using the Set IWL (.tcf file) or Set IWL (.tgc file) commands. The default initial water level is zero metres above the model datum (or 0ft if Units == US Customary). IWLs can also vary spatially using one or more GIS and/or grid layers. The (Read GIS IWL can be read into both the .tcf or the .tgc, shown in Example Model EG06_001. The Read Grid IWL) can be read into the .tgc file, shown in Example Model EG06_002. This is particularly useful for setting initial water levels in lakes, dams, etc.

The easiest way to set up a GIS IWL layer is to:

Create a 2d_iwl layer using an empty layer created by Write Empty GIS Files.
Digitise regions or points and assign each object an initial water level value.
Save the GIS layer.
Use the .tcf Read GIS IWL command or tgc Read GIS IWL command to read in the IWL values.

The Read Grid IWL .tgc command is used to read the IWL from a grid (.tif, .flt or .asc). This can be used to set the IWL based on the water level in a previous simulation, if TIF, FLT or ASC is specified in the Map Output Format. The results from one simulation can be directly read by another.

Any number of IWL layers may be used, noting that if a cell’s IWL occurs more than once, the last occurrence prevails (i.e. TUFLOW overwrites any previous IWL already set).

Table 8.16: **2D Initial Water Level (2d_iwl) Attribute Descriptions**
No	Default GIS Attribute Name	Description	Type
1	IWL	Initial water level of object relative to model datum (m).	Float

8.9.1.3 Automatic Initial Water Level

It is possible to automatically set the model’s initial water level to the downstream boundary water level using Set IWL == AUTO. This command is very useful when performing a Monte Carlo assessment that requires a large number of simulations with each simulation having a unique initial water level!

8.9.2 Initial Groundwater Levels

This section discusses available commands to set initial conditions in groundwater layers. As of the 2023-03 release, when using TUFLOW HPC, it is possible to have numerous groundwater layers in the vertical (see Section 7.4.5). If using this functionality the initial water levels can also be set per layer by using ‘Layer N’. If using only one layer, the syntax may be either ‘Set IGW Depth’ or Set IGW Depth Layer 1’.

The initial water level in the groundwater layer(s) can be set globally in the .tgc using the following commands:

They can also be set on a spatial basis using:

“IGW Depth” is assumed to be the depth of water in the soil (water content divided by porosity). “IGW Level” is assumed to be the level of the water table in each layer. If both methods are specified for a given grid cell, the highest initial condition will be adopted. The input units should be in meters or feet (if using Units == US Customary). Note, the initial conditions do not automatically cascade into layers below (i.e. setting the initial water level in the top layer will not automatically set the layers below to be 100% saturated).

Setting the initial conditions in the .tgc for any given grid cell will override the “Initial Moisture” parameter set in the .tsoilf. The difference between the methods is that the .tsoilf sets the initial moisture by soil type, whereas setting the initial conditions in the .tgc allows spatial distribution. If no initial conditions are set in the .tgc for a given grid cell, the initial conditions will be determined by the “Initial Moisture” defined in the .tsoilf.

In previous releases, the groundwater initial conditions could be set using the following commands. For backward compatibility, it is still possible to use these commands, though only if using one groundwater (soil) layer in the vertical:

If the above commands are used with the multiple vertical layers (Convective layers), ERROR 2588 will be produced.

The groundwater feature may only be used in conjunction with at least one of the soils infiltration methods described in Section 7.3.7. Consequently, the .tgc commands used to define the groundwater depth / level must be read in following (below) at least one of the commands used to define the soil type: Set Soil, Read GIS Soil or Read Grid Soil.

Table 8.17: **2D Groundwater (2d_gw) GIS Attribute Descriptions**
No.	Default GIS Attribute Name	Description	Type
1	Groundwater	The ground water level in metres above datum (if using the command Read GIS GWL) or depth below ground surface in metres (if using the command Read GIS GWD) of the groundwater table at the start of the model simulation. The units are feet if using Units == US Customary.	Float

8.9.3 Restart Files

Gradually varying water surface initial water level conditions are best defined using a restart file. This is achieved by running the model for a warm-up period prior to the main event to create a restart file which establishes the initial water levels and flow velocities. This is achieved using the following commands:

Write Restart File at Time: Sets when to write the restart file in hours.
Write Restart File Interval: Sets the interval in hours between writing the restart file.
Read Restart File: Reads a restart file written from a previous simulation.
Write Restart Filename: Controls whether restart files are overwritten or are time-stamped.

The 1D and 2D restart files use a .erf and .trf extension respectively and are written to the results folder.

The restart file contains information on the water levels, velocities and flow regimes for the 1D and 2D parts of the model. Therefore, the number of 2D cells and 1D channels must be the same between the original model and the model using the restart file. Permitted changes between runs could include different boundary conditions, cell elevation increases (cell elevation decreases may cause issue) and roughness values.

An example of writing and reading restart files is provided in Example Models EG02_009 and EG06_004 respectively.

The 2023-03-AD build added functionality to allow restart data fields to be ignored. To specify which fields to ignore the command “Restart File Ignore Fields ==” can be set in the .tcf where the fields are any combination of:

Geometry (elevations and Manning’s n values)
Groundwater (groundwater depths and groundwater tracer concentrations)
Maximum (scalar and vector maximums; both values and times, minimum timestep)
Rainfall (cumulative rainfall, cumulative rainfall material losses and cumulative cell wet time)
TimeOutputCutoff (Time Output Cutoff; time of first inundation and cumulative time inundated)
Tracer (surface and groundwater tracer concentrations)
Velocity (velocity and turbulence values)
WaterLevel (water level)

For example: “Restart File Ignore Fields == Geometry Groundwater” will ignore the geometry and groundwater information in the restart file (for these, the values set in the control files are used).

By default (without the command above) the geometry information in the restart file is ignored and the .tgc information is used instead. See also HPC Restart Geometry == Restart File | {TGC} command. If the “Restart File Ignore Fields ==” command is included, but does not include geometry then message “WARNING 2902 -‘Restart File Ignore Field’ does not include geometry, overwriting geometry in .tgc with restart file” is issued.

Note: Only one of “Restart File Ignore Fields” or “HPC Restart Geometry” should be used, an error is given if both commands are present in a control file.

References

Holland, G. J. (1980). An Analytic Model of the Wind and Pressure Profiles in Hurricanes. Monthly Weather Review, 108(8), 1212–1218. https://doi.org/10.1175/1520-0493(1980)108<1212:AAMOTW>2.0.CO;2

Kitts, D., Syme, W., Gao, S., Collecutt, G., & Ryan, P. (2020). Mesh Orientation and Cell Size Sensitivity in 2D SWE Solvers. IAHR River Flow Conference. https://tuflow.com/media/5022/2020-mesh-orientation-and-cell-size-sensitivity-in-2d-swe-solvers-kitts-et-al-iahr-river-flow-delft.pdf

Queensland Government. (2001). Queensland Climate Change and Community Vulnerability to Tropical Cyclones - Ocean Hazrds Assessment. https://www.systemsengineeringaustralia.com.au/download/Ocean_Hazards_Assess_Stage1A_revised.pdf

Ryan, P., Syme, W., Gao, S., & Collecutt, G. (2022). Irect Rainfall Hydraulic Model Validation. Hydrology & Water Resources Symposium. https://www.tuflow.com/media/7545/2022-direct-rainfall-hydraulic-model-validation-ryan-et-al-hwrs.pdf

Wu, J. (1980). Wind-Stress Coefficients over Sea Surface Near Neutral Conditions—a Revisit. Journal of Physical Oceanography, Vol. 10(5), pp. 727–740. https://doi.org/https://doi.org/10.1175/1520-0485(1980)010<0727:WSCOSS>2.0.CO;2

Wu, J. (1982). Wind-Stress Coefficients over Sea Surface from Breeze to Hurricane. Journal of Geophysical Research, Vol. 87(C12), pp. 9704–9706. https://doi.org/https://doi.org/10.1029/JC087iC12p09704