TUFLOW HPC

User Manual
Version 2025.0
 @4

@5
TUFLOW Classic/HPC User Manual 2025.0
Updated on 22 Jan 2025

@6

www.tuflow.com How to Use This Manual .tcf Commands

TUFLOW Wiki List of Figures .ecf Commands
TUFLOW Tutorial Models List of Tables .tgc Commands
[email protected] Changelog .tbc Commands

TUFLOW Classic/HPC User Manual 2025.0 - 1 / 1 Page 1 / 1094

 @12

@13
Overview

@14
How to use this Manual

This PDF document was automatically created, based on the original online document. Hyperlinks
in this PDF version work within the document, but have been decorated with a symbol, as have
section headings. These symbols link back to the corresponding online original. The section you
are currently reading is a replacement for some instructions on how to use the online document in
the original. We recommend you visit the online original and take a look at those instructions
before following other links from this PDF document.

Please note that any links in this PDF that are not decorated with a symbol will always take you
to a browser, and are recognisable by their different colour. This includes links like those to the
TUFLOW Wiki.

The online content for this manual was last updated on 22 Jan 2025 and this PDF document copy
was generated and published on 22 Jan 2025.

@15
About this Manual

This document is the User Manual for the 2025 release of the TUFLOW Classic and TUFLOW
HPC hydrodynamic computational engines. Of particular note for users of earlier manual versions
is that a new TUFLOW User Manual will now accompany every major TUFLOW release.
Additionally, from the 2025 TUFLOW release and onwards, a concise overview of new features
and changes between TUFLOW versions are provided in the TUFLOW Classic/HPC Changelog,
rather than a set of release notes.

For changes in defaults between releases, refer to Chapter 18 .

If simulating models using prior TUFLOW builds, reference may need to be made to the
documentation relevant for that particular build. These can be downloaded from the TUFLOW
Classic/HPC Downloads page or requested via [email protected].

Overview - 1 / 9 Page 2 / 1094

 @16
Glossary and Notation

@17
Term Description

@20
_messages ERROR, WARNING, CHECK and other useful messages
that are output to the Console Window and log file are also
output to GIS file provided the message can be
geographically located within the model domains. The
messages and other information are written to a file called
_messages which is located in the same folder as the .tcf
file or in the “Log” folder.

_run_stats.txt This file contains a summary of the amount of time that

TUFLOW spends in the 1D and 2D computations.

_start_stats.txt This file contains information summarising the total time and
the time elapsed for each stage of model initialisation. This
can be used to identify the stages causing slow simulation
start-up.

ADI Alternating Direction Implicit. The TUFLOW Classic solver is

a 2D ADI 2nd order spatial finite difference CPU solver.

Advection-Dispersion A process in fluid dynamics that describes the movement

(advection) and spread (dispersion) of substances (such as
pollutants, nutrients, or sediments) in a fluid (usually water
or air).

ArcGIS Pro Toolbar The ArcGIS Pro Toolbar, helps with streamlining the process
of creating and editing a TUFLOW model in the GIS
software ArcGIS Pro.

ArcMap Toolbox The toolbox helps with streamlining the process of creating
and editing a TUFLOW model in the GIS software ArcMap.

ArcMap/ArcGIS ArcMap and ArcGIS Pro are distributed by ESRI

(https://www.esri.com/). They are GIS software packages
that can be used to develop the georeferenced input data
for TUFLOW. TUFLOW writes result and check files which
are compatible with ArcMap and ArcGIS Pro also.

attribute Data associated with/or attached to a GIS object. For

example, an elevation is attached to a point using a column
of data named “Height”. The “Height” of the point is an
attribute of the point.

Overview - 2 / 9 Page 3 / 1094

 Term Description

Build The TUFLOW Build number is in the format of

year.minor.patch convention. The year corresponds to the
major version number. Throughout the year, additional minor
releases (releases containing new features and bug fixes,
but no breaking changes) would increment the minor
version number and bug fix only releases would increment
the patch version number. The Build number is written to the
first line in the .tlf log file so that it is clear what version of
the software was used to simulate the model. A example
build number is: 2025.0.0.

cell Square shaped computational element in a 2D domain.

centroid The centre of a region or polygon.

channel Flow/velocity computational point in a 1D model. Channels

convey the water through 1D domains. They vary in
characteristics from open channels to a wide range of
structures and conduits.

Classic TUFLOW’s “Classic” solver is a 2D ADI (Alternating

Direction Implicit) 2nd order spatial finite difference CPU
(Central Processing Unit) solver. TUFLOW Classic was the
original TUFLOW 2D solver, which started development in
1989.

CnM CnM is a Chezy C, Manning’s n or Manning’s M bed

resistance value.

code Code refers to the value assigned to cells to indicate a cell’s

active or inactive status.

command Instruction syntax in a TUFLOW control file.

control file Text file containing a series of commands (instructions) that

control how a TUFLOW simulation domain is built and how
a simulation shall execute.

CPU Central Processing Unit. TUFLOW can run on either CPU or

GPU hardware.

DEM Digital Elevation Model. Interchangeable with DTM.

Double Precision (DP) Double precision numbers use 8 bytes.

DTM Digital Terrain Model. Interchangeable with DEM.

element A discrete feature in a 1D domain model, for example, a

node or channel. For TUFLOW Classic and HPC, “element”
refers to a square shaped computational element in a 2D
domain, and is interchangeable with “cell”.

Overview - 3 / 9 Page 4 / 1094

 Term Description

ESTRY ESTRY is original name given to the primary 1D solver built

into TUFLOW. The terms ESTRY and TUFLOW 1D may be
used interchangeably throughout this Manual.

fixed field Lines of text in a text file that are formatted to strict rules
regarding which columns values are entered into. This
format was used for old versions of ESTRY and TUFLOW,
and is no longer supported. If using an older version of
TUFLOW, which uses this format, please refer to previous
manuals for the full documentation.

flushing assessment An evaluation process used to assess the effectiveness of

water movement (flushing) in a water body (such as a river,
lake, or reservoir). It determines how well the water body
can remove or dilute pollutants, sediments, or nutrients.

fluvial flooding Fluvial flooding refers to riverine flooding (excessive rainfall

causing a river to exceed its capacity).

Fric The field used to store bed friction information. This may be
the material type or ripple height.

GIS Geographic Information System. For use in TUFLOW

modelling it will need to be able to import/export files in
supported formats as documented in this manual. Common
GIS Software used for TUFLOW modelling includes ArcMap,
ArcGIS Pro, QGIS or MapInfo.

GPU Graphics Processor Unit. TUFLOW HPC has been

specifically designed for compute using NVIDIA architecture
Graphics Processor Unit (GPU) hardware. HPC is the
premier and recommended 2D TUFLOW fixed grid solver.

Grid The mesh of square cells that make up a TUFLOW Classic

or HPC model.

HPC TUFLOW’s “HPC” (Heavily Parallelised Compute) solver is

a 2D explicit, 1st or 2nd order spatial and 4th order
temporal, parallelised finite volume solver. TUFLOW HPC
has been specifically designed for compute using NVIDIA
architecture Graphics Processor Unit (GPU) hardware. HPC
is the premier and recommended 2D TUFLOW fixed grid
solver.

hydraulic jump A phenomenon in fluid dynamics where there is a sudden

transition from supercritical to subcritical flow. This abrupt
change in flow conditions results in a significant rise in the
water surface. It is commonly seen below weirs and sluice
gates where a smooth stream of water suddenly rises at a
foaming front.

Overview - 4 / 9 Page 5 / 1094

 Term Description

Integrated Urban Drainage An approach to planning or managing an urban drainage

system. Integrated Urban Drainage (IUD) takes into account
all aspects of an urban drainage system that contribute to
water quality and flooding problems.

invert The elevation of the base (bottom) of a culvert, structure or

channel.

IWL Initial Water Level.

land cell A land cell is one that will never wet (i.e. an inactive cell).

layer A GIS data layer containing the shapes of the

geographically located objects and the attribute data
associated with each object.

LIDs Low-impact developments (LIDs) features for modelling

green infrastructure.

line A GIS object defining a straight line defined by two points.

See also, polyline (Pline). Throughout this document, ‘lines’
refer to both lines (2 vertices) and polylines (more than 2
vertices).

M2D The Multiple 2D Domain (M2D) module is an add on module

for the TUFLOW Classic Solver. It allows for a number of 2D
domains of different cell sizes and orientations to exist
within a single model.

Manning’s n A coefficient which represents the roughness or friction

applied to the flow by the channel. For example, a closed
finished concrete conduit flowing partly full has a Manning’s
n of 0.012.

MapInfo MapInfo is distributed by Precisely

(https://www.precisely.com/product/precisely-
mapinfo/mapinfo-pro). MapInfo is a GIS software package
that can be used to develop the georeferenced input data
for TUFLOW. TUFLOW can also write result and check files,
which are compatible with MapInfo.

Mat An integer defining the Material (land-use) type in a look-up

table.

material Term used to describe a bed resistance category or land-

use. Examples of different materials are: river, river bank,
mangroves, roads, grazing land, sugar cane, parks, etc.

miTools MapInfo and TUFLOW Productivity Utilities (miTools) were

developed to improve the efficiency of setting up and
reviewing TUFLOW models, as well as improving the day to
day ease of using MapInfo Professional.

Overview - 5 / 9 Page 6 / 1094

 Term Description

Morphology A particular form, shape, or structure. For example, coastal

morphology typically refers to the movable sand bedform
shape of the coastal system.

Nc Wave Celerity Number.

Nd Diffusion Number.

node One of:

⋅ A junction/end of one or more channels where the water
level (if an open channel is connected) or pressure head
(e.g. closed pipe junction) is computed in a 1D domain.
⋅ Node in a model mesh used for viewing 2D results in SMS.
The nodes are located at the cell corners.
⋅ Node is also used by MapInfo to refer to vertices along a
line or a region (polygon).

Non-Newtonian Flow Non-Newtonian Flow refers to the flow of fluids that do not
follow Newton’s law of viscosity. An example of Non-
Newtonian flow is flows originating from a failed slurry mine
tailings dam.

Notepad++ Notepad++ is a free text editor available

from https://notepad-plus-plus.org/downloads/.
The Notepad++ functionality listed below makes it well
suited as an editor for creating and updating TUFLOW
control files.

Nu Courant Number.

null cell A null cell is an inactive 2D cell used for defining the inactive
side of an external boundary.

obvert The elevation of the underside (soffit) of a culvert or other

structure.

Override File Override Files allow the user to apply .tcf commands after
TUFLOW has finished processing the commands which are
referenced within the .tcf file.

Particle Tracking The TUFLOW Particle Tracking Module (PTM) enables the
2D or 3D simulation of discrete Lagrangian particles as they
are transported by a flow field and/or other forcing terms
(e.g. wind drift).

peer to peer access Some models of NVidia GPUs allow for a direct
communications link between them, either via a specific
hardware connector or via the PCI bus controller. This is
known as ‘peer to peer’ access.

Overview - 6 / 9 Page 7 / 1094

 Term Description

pit A point object with attributes that are used to define a pit
channel for modelling flow into urban stormwater inlets/gully
traps/drains/pits, then into a manhole.

pit channel A small channel inserted at a pit, typically used to convey

water from overland 2D domains to 1D pipe networks.

pit inlet The entrance to a pit channel (e.g. a gully trap).

pluvial flooding Pluvial flooding refers to surface water flooding that is

driven by local rainfall excess and is unrelated to river
rising.

point GIS object representing a point on the earth’s surface. A

point has no length or area.

polygon See region.

polyline (or Pline) A GIS object representing one or more lines connected
together. A polyline has a length but no area. Throughout
this document, ‘lines’ refer to both lines (2 vertices) and
polylines (more than 2 vertices).

polyline segment One of the straight line (2 vertices) segments that make up
a polyline (more than 2 vertices).

PyTUFLOW PyTUFLOW is a package of Python tools for extracting

TUFLOW time series results. It can be used to automate
output tasks such as checking model health, goodness-of-fit
for model calibration, viewing on-the-fly model output (used
in conjunction with Write PO Online == ON), and high-
volume output plotting from production runs.

QGIS QGIS is free open source software (https://qgis.org/en/site/)

that can be used to develop the georeferenced input data
for TUFLOW models, and view results via the TUFLOW
Viewer Plugin also available for free. TUFLOW writes result
and check files that are compatible with QGIS.

QGIS TUFLOW Plugin The QGIS TUFLOW Plugin provides a range of pre- and
post- processing tools, and dynamic viewing of 1D and 2D
results in TUFLOW Viewer.

Quadtree A feature of the TUFLOW HPC 2D solver that allows the use
of a quadtree mesh (dividing one 2D cell into four cells).

radial gate A radial gate (also called tainter gate) is a type of floodgate
used to control water flow.

raster Gridded GIS raster data layers: GeoTIFF (.tif), GeoPackage

(.gpkg), Float (.flt) and ASCII (.asc) formats.

Overview - 7 / 9 Page 8 / 1094

 Term Description

Read File A file that is included inside another file using the Read File
command in .tcf, .tgc and .ecf files. Minimises repetitive
specification of commands common to a group of files.

region A GIS object representing an enclosed area (i.e. a polygon).

A region has a centroid, perimeter and area. Regions or
polygons can have internal holes.

SGS Sub-Grid Sampling. A feature built into the HPC 2D solver

that more accurately defines a 2D cell’s geometry using the
(finer) resolution of the underlying terrain/bathymetric data.
Using SGS can considerably improve the accuracy of the
2D modelling.

Single Precision (SP) Single precision numbers use 4 bytes.

sluice gate A moveable gate that can be raised to allow water to flow
under it. When a sluice gate is lowered, it can act as a weir
as water may spill over the top.

snap When geographic objects are connected exactly at a point

or vertex of a line or region. ArcMap, ArcGIS Pro, QGIS and
MapInfo all have a “snap” feature, which ensures the
features have the same coordinates. The snap tolerance
can be changed in TUFLOW using the Snap Tolerance
command.

soffit The elevation of the underside of a bridge deck or the inner

top of a culvert. Same as obvert. Note this manual uses the
term obvert.

stage-discharge curve A curve (graph) that shows the relationship between the
water level (stage) in a body of water (e.g. river) and the
corresponding flow rate (discharge) at that stage.

Sub-grid-scale turbulence Horizontal turbulent diffusion of momentum or eddy

viscosity.

subcritical flow A flow condition or behaviour where the fluid velocity is

slower then the wave velocity.

supercritical flow A flow condition or behaviour where the fluid velocity is

higher than the wave velocity.

SWMM EPA Storm Water Management Model (SWMM).

TIN Triangulated Irregular Network.

TUFLOW 1D See ESTRY.

vertex Digitised point on a line or region (polygon).

vertices Plural of vertex.

Overview - 8 / 9 Page 9 / 1094

 Term Description

VS Code Visual Studio Code (commonly referred to as VS Code) is a

free source code editor developed by Microsoft. It supports
a variety of file types and can be used to work with
TUFLOW control files. Thousands of free plugins exist for
VS Code and some of them are useful when working with
TUFLOW models.

XF XF files are a binary echo of selected input files

automatically created by TUFLOW to vastly speed up the
model initialisation process next time a simulation is carried
out.

ZC The “ZC” point is located at cell centers. This is a

computational point where the mass balance equation is
calculated. located in the centre of a 2D cell. The model
elevation is also sampled here.

ZH The “ZH” point is located at cell corners. This point plays no

role computationally but is used as an elevation point and
for some output formats.

Zpt or Zpts Points where ground/bathymetry elevations are defined.

These are located at the cell centres, mid-sides and
corners.

ZU The “ZU” point is located midway along the right hand face
of the 2D cell. This is a computational point, where the
velocity in the X-direction is calculated. The cell’s left hand
face also has a u-point belonging to the neighbouring cell to
the left. The model elevation is also sampled here.

ZV The “ZV” point is located midway along the top face of the
2D cell. This is a computational point, where the velocity in
the Y-direction is calculated. The cell’s bottom face also has
a v-point belonging to the neighbouring cell to the bottom.
The model elevation is also sampled here.

Overview - 9 / 9 Page 10 / 1094

 @32

@33
Contents

The Navigation Panel to the left of the page functions as a live interactive Table of Contents for the
manual chapters and associated sections. A list of the figures and tables within the manual is
provided below.

@34
List of Figures

Figure 1.1 TUFLOW Quadtree Structure

Figure 2.1 TUFLOW Modelling Concept

Figure 2.2 NotePad++ TUFLOW Syntax Highlighting

Figure 2.3 QGIS with TUFLOW Viewer

Figure 3.1 1D Pipe Network and Embankment Culvert Linked to 2D

Figure 3.2 1D Open Channel Linked to 2D

Figure 3.3 TUFLOW HPC Quadtree Grid (3 Level Refinement)

Figure 3.4 20m grid size shown against the 1m DTM

Figure 3.5 2D Topography Sampling Concept and DEM Interpretation (Traditional vs SGS)

Figure 3.6 Model Convergence with and without SGS

Figure 3.7 Longitudinal Profile without SGS

Figure 3.8 Longitudinal Profile with SGS

Figure 3.9 Cell Size Convergence Concept Example

Figure 3.10 Example of zeroth order interpolation

Figure 3.11 Example of first order interpolation

Figure 3.12 Example of second order interpolation

Figure 3.13 TUFLOW HPC 1D/2D Timestep Synchronisation

Figure 4.1 Example of a Simple TCF

Figure 4.2 Example of a Simple ECF

Figure 4.3 Example of a Simple TGC

Figure 4.4 Reduction of Control Files using Event Management

Figure 5.1 1D Channels, Structures and Nodes

Contents - 1 / 12 Page 11 / 1094

 Figure 5.2 ‘All Parallel’ Conveyance Calculation Method

Figure 5.3 ‘Change in Resistance’ Conveyance Calculation Method

Figure 5.4 1D Inlet Control Culvert Flow Regimes

Figure 5.5 1D Outlet Control Culvert Flow Regimes

Figure 5.6 Arch Bridge Editor Tool

Figure 5.7 Bradley Weir Submergence Curve (Bradley, 1978 )

Figure 5.8 Ogee Spillway Discharge Coefficient, based on Figure 9-23 (USBR, 1987 )

Figure 5.9 Adjustment of Discharge Coefficient based on /

He H0 , Figure 9-24 (USBR, 1987 )

Figure 5.10 Weir Submergence Curves from the Literature

Figure 5.11 Weir Submergence Curves using Villemonte Equation

Figure 5.12 Schematisation of 1D Piping Failure

Figure 5.13 Schematisation of 1D Dam Failure

Figure 5.14 Example of Pit Inlet Database

Figure 5.15 Road Crossfall Option

Figure 5.16 Flow Expansion/Contraction at a Manhole

Figure 5.17 Change in Flow Direction at a Manhole

Figure 5.18 Change in Inlet/Outlet Height at a Manhole

Figure 5.19 Engelund Energy Loss Approach at Manholes

Figure 5.20 Virtual Pipe Lag Methods

Figure 5.21 Nodal Storage in Open Channel & Pipe Networks

Figure 7.1 TUFLOW HPC 2D SWE Finite Volume Scheme Approach

Figure 7.2 Location of Zpts and Computation Points

Figure 7.3 Effect of Enhanced Dry Boundary Viscosity Term Treatment

Figure 7.4 Redundant Perimeter Sections Reported in the TLF

Figure 7.5 Visual Representation of Data Layering in TUFLOW

Figure 7.6 2D Cell Topography - Traditional Approach

Figure 7.7 Example of Log Law Variation of Manning’s n with Depth

Figure 7.8 Example of Log Law versus Constant Manning’s n with Depth

Figure 7.9 Example of Materials .csv File Format

Figure 7.10 Example of the Grass.csv file read into the Materials.csv

Figure 7.11 Example of the Trees.csv file read into the Materials.csv

Figure 7.12 Green-Ampt Model Concept1

Contents - 2 / 12 Page 12 / 1094

 Figure 7.13 Example of Horton Infiltration Rate over Time
@37

Figure 7.14 Example Soils .tsoilf File Format

Figure 7.15 Flow patterns using 2D FC cells (i.e. a fully 2D solution)

Figure 7.16 Flow patterns using a 1D element connected to 2D SX links

Figure 7.17 Flow patterns using a 1D element connected to 2D HX links

Figure 7.18 2D BG Shape Attributes and Vertical Distribution of Form Loss Coefficient

Figure 7.19 Depth Averaged FLC Applied Using Four Adjustment Approaches

Figure 7.20 CFD benchmarking study of FLC vs /

DP ier TSuperS ratio (hB /T in the original paper)

Figure 7.21 TUFLOW HPC Quadtree Grid

Figure 7.22 Example of Quadtree Nesting Level Polygons

Figure 7.23 Examples of Automatic Quadtree Refinement

Figure 7.24 Example Showing Removal of Inactive Cells

Figure 7.25 Traditional (non-SGS) Approach

Figure 7.26 SGS Approach

Figure 7.27 SGS Breakline Detection Delta Output

Figure 7.28 Diagram of SGS Z Shape Line Approach Options

Figure 7.29 Diagram of SGS SX Z Flag Approach Options

Figure 7.30 SCS Infiltration for Curve Number 50, Ia = 0.2

Figure 7.31 Illustration of soil layers and flows in adjoining cells

Figure 7.32 Non-Newtonian Shear Stress and Velocity Profile

Figure 7.33 Setting FC Parameters for a Bridge Structure

Figure 7.34 Setting FCSH Parameters for a Bridge Structure

Figure 8.1 Cell Cross-hair Selection Approach

Figure 8.2 Sloping Water Level Boundaries

Figure 8.3 Example Rainfall Database

Figure 8.4 Example Depth Total Grid

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)

Figure 8.8 Example BC Database Using Event Text

Figure 8.9 Example BC Database Source Files Using Event Text

Figure 8.10 Example DSS File

Contents - 3 / 12 Page 13 / 1094

 Figure 8.11 Time-series Curve Example

Figure 9.1 1D Channel Advection

Figure 10.1 1D/2D Linking Configurations

Figure 10.2 HX Connection: Nested 1D Open Channel – Plan View

Figure 10.3 HX Connection: Example of Momentum Preservation across HX Lines

Figure 10.4 HX Connection: Nested 1D Open Channel – Section View

Figure 10.5 HX Connection: External 1D Network Boundary Connection

Figure 10.6 SX Connection Options

Figure 10.7 SX Connection: Pipe Network – Plan View

Figure 10.8 SX Connection: Pipe Network -Section View

Figure 10.9 SWMM 1D Connection: Culvert

Figure 10.10 SWMM 1D Connection: Pipe Network

Figure 10.11 SWMM 1D / TUFLOW 1D Connection

Figure 10.12 Compatibility of Recent Flood Modeller and TUFLOW versions

Figure 10.13 Schematic of a Multiple Domain Model linked via a 1D Domain

Figure 10.14 Schematic of a Multiple 2D Domain Model using the 2d_bc “2D” Link

Figure 10.15 Multiple 2D Domain Model “2D” Link Check Files

Figure 11.1 Regular Grid Depth Output (Left) and HR Grid Depth Output (Right)

Figure 11.2 Example Hazard File for User Defined Hazard

Figure 11.3 Adding Triangles into 1d_WLL Layer to Infill Areas

Figure 11.4 Interpretation of PO Objects and Map Output

Figure 11.5 Example of the QGIS TUFLOW Plugin for a Reporting Location

Figure 11.6 Example Use of Gauge Data Output Layer

Figure 13.1 TUFLOW Engine Files

Figure 13.2 Accessing NVIDIA Control Panel from the Desktop

Figure 13.3 NVIDIA GPU Model

Figure 13.4 Check the Website for your NVIDIA Card

Figure 13.5 NVIDIA System Information

Figure 13.6 Accessing Driver Updates from the NVIDIA Control Panel

Figure 13.7 Flood Modeller Settings

Figure 13.8 12D 2D Quick Setting

Figure 13.9 12D TUFLOW Project Editor

Contents - 4 / 12 Page 14 / 1094

 Figure 13.10 SMS Settings

Figure 14.1 Example TUFLOW Classic Console (DOS) Display Window

Figure 14.2 Example TUFLOW HPC Console (DOS) Display Windows

Figure 14.3 Filter by Code Number

Figure 15.1 Maximum and Minimum Water Level and Flow Output

Figure 15.2 Example of the ccA GIS Layer Highlighting Culvert Performance

Figure 15.3 Example of the _TS Layer Flow Output

Figure 15.4 Example of the _TS Layer Stability Styling

Figure 15.5 Impact Mapping

Figure 16.1 TUFLOW HPC Minimum Timestep (dt) Map Output

Figure 16.2 TUFLOW HPC.TLF Repeating Timesteps

Figure 16.3 Timestep and Control Numbers plotted from the .hpc.dt.csv

Figure 16.4 TUFLOW Warning 2551 Messages in QGIS

Figure 16.5 TUFLOW RAM Error

Figure 16.6 Influence of 2D Domain Size on RAM Allocation

Figure 17.1 ArcGIS Pro TUFLOW Toolbar

@42
List of Tables

Table 1.1 TUFLOW Modelling Environment

Table 2.1 Supporting Software Options

Table 2.2 Recommended Sub-Folder Structure

Table 2.3 List of Most Commonly Used File Types - Control Files

Table 2.4 List of Most Commonly Used File Types - Input, Output and Check File Types

Table 2.5 GIS Input Data Layers and Recommended Prefixes - 2D Domain

Table 2.6 GIS Input Data Layers and Recommended Prefixes - 1D Domain

Table 2.7 TUFLOW Tips and Tricks

Table 3.1 Recommended 2D Cell Size

Table 3.2 HPC 2D Adaptive Timestep Controlling Numbers

Table 4.1 List of Available Control Files

Table 4.2 Reserved Characters – Text Files

Table 4.3 Notation Used in Command Documentation – Text Files

Table 4.4 Model Units - Inputs

Contents - 5 / 12 Page 15 / 1094

 Table 4.5 List of Available Databases

Table 4.6 TUFLOW Interpretation of Supported GIS Objects

Table 4.7 TUFLOW Interpretation of Unsupported GIS Objects

Table 5.1 1D Channel (Line) Types

Table 5.2 1D Channel (Line) Types - Additional/Optional Channel Flags

Table 5.3 Open Channels: 1D Model Network (1d_nwk) Attribute Descriptions

Table 5.4 1D Cross-Section Table Link (1d_xs) Attribute Descriptions

Table 5.5 Culverts and Pipes: 1D Model Network (1d_nwk) Attribute Descriptions

Table 5.6 1D Culvert Flow Regime Flags

Table 5.7 Computed Values of Modified Energy Loss Coefficient

Table 5.8 Commands for the Blockage Matrix Method

Table 5.9 Example Blockage Matrix File

Table 5.10 Bridges: 1D Model Network (1d_nwk) Attribute Descriptions

Table 5.11 1D Bridge Geometry Table Link (1d_bg) Attribute Descriptions

Table 5.12 Arch Bridges 1D Model Network (1d_nwk) Attribute Descriptions

Table 5.13 Arch Bridge Properties .csv

Table 5.14 Weir Types

Table 5.15 Default Attribute Values for the Weir Equation for Different Weir Flows

Table 5.16 Weirs: 1D Model Network (1d_nwk) Attribute Descriptions

Table 5.17 1D Model Network (1d_nwke) OPTIONAL Attribute Descriptions

Table 5.18 Special Channels: 1D Model Network (1d_nwk) Attribute Descriptions

Table 5.19 Variable Value Types

Table 5.20 Keywords Returned by “Status” Variable

Table 5.21 Values Returned by ‘Operational Variables’.

Table 5.22 Piping & Dam Failure Channels: 1D Model Network (1d_nwk) Attribute Descriptions

Table 5.23 .toc Commands to Set Weir Flow Equation Parameters in DF Channel

Table 5.24 Pits: 1D Model Network (1d_nwk) Attribute Descriptions

Table 5.25 Pits: 1D Model Network (1d_pit) Attribute Descriptions

Table 5.26 Pit Inlet Database Format

Table 5.27 Q Pit Flow Regime Flags

Table 5.28 1D Manhole (1d_mh) Attribute Descriptions

Table 5.29 1d_nwk Point Object Types

Contents - 6 / 12 Page 16 / 1094

 Table 5.30 Nodes: 1D Model Network (1d_nwk) Attribute Descriptions

Table 5.31 1D Model Network (1d_nd) Attribute Descriptions for Nodes

Table 5.32 1D Nodal Area Table Link (1d_na) Attribute Descriptions

Table 6.1 SWMM Option Table Keywords and Descriptions

Table 7.1 Location (2d_loc) Attribute Descriptions

Table 7.2 Cell Codes

Table 7.3 2D Code (2d_code) Attribute Descriptions

Table 7.4 2D Zpt Commands

Table 7.5 2D Z-Shape (2d_zsh) Attribute Descriptions

Table 7.6 2D Variable Z-Shape (2d_vzsh) Attribute Descriptions

Table 7.7 2D Tin (2d_ztin) Attribute Descriptions

Table 7.8 2D Z (2d_z_) Attribute Descriptions

Table 7.9 2D Materials (2d_mat) Attribute Descriptions

Table 7.10 Materials .csv File Format

Table 7.11 Materials .tmf File Format

Table 7.12 USDA Soil types for the Green-Ampt Infiltration Method

Table 7.13 Soil File (.tsoilf) Parameters

Table 7.14 2D Soil (2d_soil) GIS Attribute Descriptions

Table 7.15 Hydraulic Structure Modelling Approaches

Table 7.16 2D Bridge Shape (2d_bg) Attribute Descriptions

Table 7.17 2D Bridge Shape Points (2d_bg_pts) Attribute Descriptions

Table 7.18 Layered Flow Constriction Shape (2d_lfcsh) Attribute Descriptions

Table 7.19 Layered Flow Constriction Shape Point (2d_lfcsh…_pts) Attribute Descriptions

Table 7.20 2D Quadtree (2d_qnl) Attribute Descriptions

Table 7.21 HPC .tsoilf Parameters

Table 7.22 Flow Constriction Shape (2d_fcsh) Attribute Descriptions

Table 7.23 Flow Constriction (2d_fc) Attribute Descriptions

Table 8.1 Recommended BC Arrangements

Table 8.2 HPC Boundary Approach Descriptions

Table 8.3 1D Boundary Condition and Link Types

Table 8.4 1D Boundary Conditions (1d_bc) Attribute Descriptions

Table 8.5 2D Boundary Condition and Link Types

Contents - 7 / 12 Page 17 / 1094

 Table 8.6 2D Boundary Conditions (2d_bc) Attribute Descriptions

Table 8.7 2D Source over Area (2d_sa) Attribute Descriptions

Table 8.8 Streamlines (2d_strm) Attribute Descriptions

Table 8.9 2D Source over Area Rainfall (2d_sa_rf) Attribute Descriptions

Table 8.10 2D Source over Area Trigger (2d_sa_tr) Attribute Descriptions

Table 8.11 2D Source over Area Flow Feature (2d_sa_po) Attribute Descriptions

Table 8.12 2D Direct Rainfall over Area (2d_rf) Attribute Descriptions

Table 8.13 BC Database Keyword Descriptions

Table 8.14 GIS Attribute Details for Cyclone (2d_cyc) layer

Table 8.15 2D External Wind Stress (2d_ws) Attribute Descriptions

Table 8.16 1D Initial Water Level (1d_iwl) Attribute Descriptions

Table 8.17 2D Initial Water Level (2d_iwl) Attribute Descriptions

Table 8.18 2D Groundwater (2d_gw) GIS Attribute Descriptions

Table 9.1 GIS Input Data Layers and Recommended Prefixes

Table 9.2 Global Database Keyword Descriptions

Table 9.3 AD BC Database Keyword Descriptions

Table 9.4 2D Initial Conditions (2d_ad_ic) Attribute Descriptions

Table 9.5 2D Minimum Dispersion Coefficient (2d_ad_md) Attribute Descriptions

Table 9.6 _ADcfl.csv File Columns

Table 9.7 _ADmass.csv File Columns

Table 10.1 SWMM Inlet Usage (swmm_iu) Attribute Descriptions

Table 11.1 Map Output Format Options - Mesh Based Output Formats

Table 11.2 Map Output Format Options - Options for XMDF Format

Table 11.3 Map Output Format Options - Grid Based Output Formats

Table 11.4 Map Output Types (Excluding Hazard (Z) Types)

Table 11.5 Map Output Hazard (Z) Types

Table 11.6 1D Water Level Line (1d_wll) Attribute Descriptions

Table 11.7 1D Water Level Line Point (1d_wllp) Attribute Descriptions

Table 11.8 2D Gauge Level Output (2d_glo) Attribute Descriptions

Table 11.9 Time-Series (PO) Data Types - Point, Line or Region

Table 11.10 2D Plot Output (2d_po) Attribute Descriptions

Table 11.11 2D Longitudinal Profiles (2d_lp) Attribute Descriptions

Contents - 8 / 12 Page 18 / 1094

 Table 11.12 0d_RL Reporting Location Attributes

Table 11.13 2d_GDO_ Gauge Data Output Attributes

Table 11.14 2D Z-Shape Route (2d_zshr) Attribute Descriptions

Table 11.15 RCP Output (2d_zshr) Attribute Description

Table 11.16 Commands used to Control TUFLOW Outputs

Table 13.1 TUFLOW Versions (iSP, iDP, w64)

Table 13.2 TUFLOW.exe Options (Switches)

Table 13.3 TCF commands (apart from Timestep) specific to the TUFLOW HPC solver

Table 14.1 TUFLOW Summary File Example

Table 14.2 Channel and Node Flow Regime Flags (.eof File)

Table 14.3 Types of Check Files

Table 14.4 MB.csv File Columns

Table 14.5 MB1D.csv File Columns

Table 14.6 MB2D.csv File Columns

Table 14.7 TSMB GIS Layer Attributes

Table 14.8 TSMB1d2d GIS Layer Attributes

Table 14.9 MB_HPC.csv File Columns

Table 15.1 Plot Folder File Descriptions

Table 15.2 _TS GIS Layer Descriptions

Table 16.1 Simulation Summary Healthy Model Indicators

Table 16.2 Quality Control Check List

Table 17.1 QGIS TUFLOW Plugin - Tools

Table 18.1 Default Changes in the 2025.0 Release and Backward Compatibility to 2023-03

Table 18.2 Default Changes in the 2023-03 Release and Backward Compatibility to 2020-10

Table 18.3 Default Changes in the 2020-10 Release and Backward Compatibility to 2020-01

Table 18.4 Default Changes in the 2020-01 Release and Backward Compatibility to 2018-03

Table 18.5 Default Changes in the 2018-03 Release and Backward Compatibility to 2017-09

Table 18.6 Default Changes in the 2017-09 Release and Backward Compatibility to 2016-03

Table 18.7 Default Changes in the 2016-03 Release and Backward Compatibility to 2013-12

Table 18.8 Default Changes in the 2013-12 Release and Backward Compatibility to 2012-05

Table 18.9 Default Changes in the 2012-05 Release and Backward Compatibility to 2011-09

Table 18.10 Default Changes in the 2011-09 Release and Backward Compatibility to 2010-10

Contents - 9 / 12 Page 19 / 1094

 Table 18.11 Default Changes in the 2010-10 Release and Backward Compatibility to 2009-07

Table 18.12 Default Changes in the 2008-08 Release and Backward Compatibility to 2007-07

Table 18.13 Default Changes in the 2007-07 Release and Backward Compatibility to 2006-06

Table 18.14 Default Changes in the 2006-06 Release and Backward Compatibility to 2005-05

Table A.1 TUFLOW Classic/HPC TCF Commands

Table B.1 TUFLOW Classic/HPC ECF Commands

Table C.1 TUFLOW Classic/HPC TGC Commands

Table D.1 TUFLOW Classic/HPC TBC Commands

Table E.1 TUFLOW Classic/HPC TOC Commands

Table F.1 TUFLOW Classic/HPC TRFC Commands

Table G.1 TUFLOW Classic/HPC TESF Commands

Table H.1 TUFLOW HPC QCF Commands

Table I.1 TUFLOW Classic/HPC TSCF Commands

Table J.1 TUFLOW Classic/HPC ADCF Commands

Table K.1 TUFLOW Classic/HPC TEF Commands

Table L.1 SWMM Input layers

Table L.2 Inflows

Table L.3 Curves

Table L.4 Timeseries

Table L.5 Aquifers

Table L.6 Groundwater

Table L.7 GWF

Table L.8 Adjustments

Table L.9 Evaporation

Table L.10 Hydrographs

Table L.11 Patterns

Table L.12 Raingages

Table L.13 RDII

Table L.14 Snowpacks

Table L.15 Temperature

Table L.16 Inlet Usage

Table L.17 Inlets

Contents - 10 / 12 Page 20 / 1094

 Table L.18 LID Controls

Table L.19 LID Usage

Table L.20 Conduits

Table L.21 Controls

Table L.22 Orifices

Table L.23 Outlets

Table L.24 Pumps

Table L.25 Streets

Table L.26 Transects

Table L.27 Transects Coordinates

Table L.28 Weirs

Table L.29 Dividers

Table L.30 DWF

Table L.31 Junctions

Table L.32 Outfalls

Table L.33 Storage

Table L.34 Files

Table L.35 Options

Table L.36 Report

Table L.37 Title

Table L.38 Subcatchments

Table L.39 Buildup

Table L.40 Coverages

Table L.41 Landuses

Table L.42 Loadings

Table L.43 Pollutants

Table L.44 Treatment

Table L.45 Washoff

References

@44
@43
Bradley, J. (1978). Hydraulics of Bridge Waterways (HDS 1, FIWA). Bridge Division.
https://www.fhwa.dot.gov/engineering/hydraulics/pubs/hds1.pdf

Contents - 11 / 12 Page 21 / 1094

 @45 (1987). Design of Small Dams [Technology & Engineering]. U.S. Dept. of the Interior,
USBR.
Bureau of Reclamation, 1987-. https://www.usbr.gov/tsc/techreferences/mands/mands-
pdfs/SmallDams.pdf

1. Figure
@46 courtesy of University of Texas
https://www.caee.utexas.edu/prof/mckinney/ce374k/Overheads/10-Infiltration.pdf#page=20↩︎

Contents - 12 / 12 Page 22 / 1094

 @51

@52
Section 1 Introduction

@53
1.1 TUFLOW Products

TUFLOW Products includes a suite of hydraulic modelling software for the numerical simulation of
urban drainage, catchment runoff, flooding, pollutant export, as well as estuarine, lacustrine and
coastal hydrodynamics and associated environmental processes. Developed through close
collaboration with universities and our users, TUFLOW software is known for its high scientific
standard, accuracy, rigorous benchmarking, and workflow efficiency.

The TUFLOW suite includes two primary pieces of software:

1. TUFLOW Classic/HPC which uses a fixed grid of square two-dimensional (2D) cells with
optional one-dimensional (1D) elements and networks as the computational structure.
TUFLOW Classic/HPC presently includes two 2D computational solver options, coupled to
several 1D solvers:

TUFLOW’s “Classic” solver is a 2D ADI (Alternating Direction Implicit) 2nd order spatial
finite difference CPU (Central Processing Unit) solver. TUFLOW Classic was the original
TUFLOW 2D solver, which started development in 1989.
TUFLOW’s “HPC” (Heavily Parallelised Compute) solver is a 2D explicit, 1st or 2nd order
spatial and 4th order temporal, parallelised finite volume solver. TUFLOW HPC can use
either CPU and Graphics Processor Unit (GPU) hardware for its compute. GPU hardware
acceleration enables TUFLOW HPC to run simulations up to 100 times faster than
Classic. TUFLOW HPC was originally added to the TUFLOW suite in 2011 initially as a
1st order spatial solver known as TUFLOW GPU, then in 2018 as a more accurate 2nd
order spatial solver. In addition to offering much faster run-times, TUFLOW HPC offers
industry leading accuracy that is the same or better than Classic, shock-capturing and
excellent stability with zero mass error.
TUFLOW 1D (ESTRY) is an explicit finite difference 1D solver. TUFLOW 1D is a powerful
open channel and underground pipe network solver, which started development in 1972
and has continued to be enhanced to the present day. TUFLOW 1D is dynamically linked
to both the Classic and HPC 2D solvers.
EPA SWMM 1D (SWMM) is a widely used 1D program for simulating urban and non-
urban watersheds’ hydrologic and hydraulic behaviour. Initially developed in the early
1970s by the US Environmental Protection Agency (EPA), the model has since
undergone numerous updates and enhancements to become one of the most used 1D
stormwater runoff tools in North America. SWMM is dynamically linked to the TUFLOW
HPC 2D solver.
Several third-party 1D solvers are also linked to TUFLOW Classic/HPC/TUFLOW 1D –
see www.tuflow.com/products/gui-options/.

Section 1 Introduction - 1 / 13 Page 23 / 1094

 TUFLOW Classic/HPC is well suited to simulating integrated urban drainage (surface
inundation and sub-surface pipe flows), distributed hydrology direct rainfall (rain-on-grid)
catchment runoff, flooding, tides, storm tides and tsunami inundation.

Additional functionality is available via several modules including GPU acceleration, varying
grid cell sizes, and advection-dispersion (see Section 1.1.5.1 ).

This manual provides user guidance for applying the above solvers. All references to
“TUFLOW” in this manual refer to the combination of the above solvers (TUFLOW Classic,
HPC and 1D/ESTRY).

2. TUFLOW FV is a 1st or 2nd order spatial flexible mesh finite volume solver, supporting both
triangular and quadrilateral cells in the computational domain. TUFLOW FV has 1D, 2D and
3D capabilities. It includes numerous advanced add-on modules, such as Advection
Dispersion (AD), Sediment Transport and Morphology (ST), Particle Tracking (PT) and Water
Quality (WQ). TUFLOW FV is primarily suited to simulating tide, estuarine, storm tide,
tsunamis and coastal hydraulics and environmental processes. It is also well suited to
modelling complex 3D hydrodynamic flows in rivers and around structures.

This manual DOES NOT provide user guidance for TUFLOW FV. The TUFLOW FV manual is
available for download from the TUFLOW website.

Linkage between TUFLOW HPC and TUFLOW FV is available using the TUFLOW CATCH Module
.

@54
1.1.1 TUFLOW Classic – 2D Semi-Implicit Solver

TUFLOW’s ADI 2D solver, branded TUFLOW Classic, is based on the scheme of Stelling (1984 ),
and is documented in Syme (1991 ). It solves the full two-dimensional, depth-averaged,
momentum and continuity equations for free-surface flow using a 2nd order semi-implicit matrix
solver. The scheme includes all the key physics including representation of inertia and sub-grid-
scale turbulence (horizontal diffusion of momentum or eddy viscosity).

The initial development of TUFLOW Classic was carried out as a joint research and development
project between WBM Oceanics Australia (now BMT) and the University of Queensland in 1989.
The project successfully developed a 1D/2D dynamically linked modelling system (Syme, 1991 ).
Since the initial research project, TUFLOW Classic has seen continuous year on year research
and development. Notable improvements from then to today include the ability to accommodate
both sub and supercritical flow regimes, inclusion of various 2D hydraulic structure options,
catchment flood and urban inundation modelling and risk assessment features, advanced 1D/2D
and 2D/2D linking, and workflow efficient GIS data management.

For legacy reasons, TUFLOW Classic is the default 2D fixed grid solver, however, since the
2020‑01 release, the TUFLOW HPC solver with GPU acceleration is typically preferred by industry
over TUFLOW Classic due to its superior speed, unconditional stability, zero mass error, and
benchmarked accuracy at all physical scales (flume models to major rivers).

Section 1 Introduction - 2 / 13 Page 24 / 1094

 @55
1.1.2 TUFLOW HPC – 2D GPU Accelerated Solver

TUFLOW’s explicit 2D solver, branded TUFLOW HPC (Heavily Parallelised Compute), started its
development in 2011, with a focus on harnessing the power of heavily parallelised processing
units found in Graphical Processing Unit (GPU)) devices (also known as a video or graphics card).
TUFLOW HPC uses a different solution scheme to TUFLOW Classic. A different solution scheme
was necessary because TUFLOW Classic’s 2D implicit solver is not as well suited to
parallelisation due to dependencies within numerical loops.

TUFLOW HPC solves the full 2D free-surface equations including the inertia and sub-grid
turbulence (eddy viscosity) terms. The scheme is volume and momentum conserving finite
volume, 2nd order in space and 4th order in time. TUFLOW HPC has the same advanced 1D/2D
link functionality as TUFLOW Classic, and is equally well suited to integrated urban drainage
assessments, where overland flow is represented in 2D and the sub-surface pipe network in 1D,
or for catchment studies using nested 1D open channels within a broader 2D domain.

Prior to 2017, TUFLOW HPC was preceded by TUFLOW GPU, which was a more simplistic 1st
order spatial solution. TUFLOW GPU had numerous constraints due its 1st order accuracy, cell-
centred configuration and no connectivity to TUFLOW’s 1D solver. Use of TUFLOW GPU is not
recommended where reasonable accuracy is required, hence documentation specific to TUFLOW
GPU has been largely removed from this manual. For legacy reasons TUFLOW GPU is still
supported; for documentation on the superseded solver, please refer to the 2016‑03‑AE TUFLOW
User Manual.

TUFLOW HPC’s solution scheme has undergone extensive, advanced development since 2017,
arguably making TUFLOW HPC the fastest and most accurate 2D solver in the industry. Key
features of TUFLOW HPC include:

A solution scheme design targeting GPU hardware technology to maximise simulation

speeds. TUFLOW HPC using GPU hardware can run simulations over 100 times faster than
TUFLOW Classic using CPU hardware, noting that Classic is one of the fastest single core
CPU solvers (Neelz & Pender, 2013 ). This exceptional speed means very large models
(>100 2D million cells) with fine grids can now be run within a sensible timeframe yielding a
reliable and accurate solution.
TUFLOW HPC uses an advanced multi-criteria adaptive time-stepping approach. It includes
the ability to revert back in time should a numerical inconsistency occur, thereby providing
excellent numerical stability.
The solution scheme includes all the key physics, including representation of inertia and sub-
grid turbulence. Comprehensive benchmarking against theoretical solutions, flume scale
measurements, and high quality real-world calibration data, demonstrates superior accuracy
across all scales from small flumes to major rivers using default physical coefficients and
industry standard Manning’s n values. A summary of TUFLOW HPC’s solution is:
Finite volume solution scheme that demonstrates 100% volume conservation.
2nd order spatial scheme that avoids numerical diffusion issues experienced by other
mainstream software that typically use 1st order spatial approximations.
New grid size insensitive sub-grid turbulence (eddy viscosity) solution. Default sub-grid
turbulence parameters produce reliable results at any model 2D grid scale (centimetres
for flume benchmarking to over 100 metres for large scale catchment simulations). This
advanced feature is not available in TUFLOW Classic or other hydraulic modelling
software.

Section 1 Introduction - 3 / 13 Page 25 / 1094

 Sub Grid Sampling (SGS) of ground elevations at sub-cell resolutions for defining cell
storage and cell face conveyance produces more accurate cell volume estimates and
flow exchange between neighbouring cells at resolutions finer than the 2D grid resolution.
This advanced feature, which is not available in TUFLOW Classic, offers substantial
benefits including exceptional cell size results convergence for large cells allowing
models to be run with equivalent accuracy in terms of runoff and water levels on much
larger cell sizes than is possible using the traditional approach of one elevation per cell.
The solver includes exceptional shock capturing capabilities for highly transient flow
conditions such as hydraulic jumps and dam breaks. It accommodates both subcritical and
supercritical flow regimes.
Supports quadtree fixed grid refinement. This allows the replacement of one computational
cell with four finer resolution cells, subsequently allowing the modeller to represent features at
a finer resolution when a detailed velocity field is desired, especially in areas of complex
hydraulics. The quadtree feature is extremely easy to implement, can utilise the SGS feature
described above, and demonstrates industry leading numerical stability. The add-on Quadtree
Module (Section 1.1.5.4 ) is required to access this feature.

The CPU version of TUFLOW HPC is provided with the standard TUFLOW Classic/HPC licence,
noting that when run on a single CPU, TUFLOW HPC typically demonstrates slower simulation
speed performance than TUFLOW Classic due to Classic’s implicit (large timestepping) solution.
As such, TUFLOW HPC is rarely used in CPU mode except for small models. To achieve the
impressive simulation speeds mentioned above, the add-on GPU Module (Section 1.1.5.3 ) is
required for TUFLOW HPC simulations utilising NVIDIA GPU hardware.

For legacy reasons, TUFLOW Classic is the default 2D fixed grid solver. The TUFLOW HPC solver
is activated by specifying the command, Solution Scheme == HPC. To instruct TUFLOW
HPC to use GPU hardware use the command, Hardware == GPU.

@56
1.1.3 TUFLOW 1D (ESTRY) – 1D Solver

TUFLOW 1D (also known as ESTRY) solves the full one-dimensional (1D) free-surface St Venant
flow equations using a Runge-Kutta explicit solver. TUFLOW 1D has seen continuous
development and application use since 1972 and is today one of the leading 1D solvers of open
channels and pipe networks.

The network schematisation technique used by TUFLOW 1D allows realistic simulation of a wide
variety of 1D and quasi-2D situations including complex river geometries, associated floodplains
and estuaries and urban channel and pipe network systems. There is a considerable amount of
flexibility in the way network elements can be interconnected, allowing the representation of a river
and floodplain by many parallel channels with different resistance characteristics and the
simulation of braided streams and rivers with complex branching, or pipe networks with tens of
thousands of conduits, manholes and inlet pits. This flexibility allows for a variable resolution
within the network so that areas of particular interest can be modelled in fine detail, with a coarser
network representation being used elsewhere.

In addition to the traditional open channel flow cross-section channels, a wide range of additional
1D channel types are available including:

Circular, rectangular (box), and irregular (various shapes or user-defined) shaped culverts
Pit inlets and manholes

Section 1 Introduction - 4 / 13 Page 26 / 1094

 Bridges
Weirs (including broad-crested, sharp edged, V-notch, ogee, crump and user defined)
Spillways, radial gates, sluice gates
Pumps
User defined structures (stage-discharge curve; discharge matrix)
Operational controls on most structures (weirs, gates, pumps, etc)

All channel types can be specified as uni-directional, which allows flow in only one direction (using
the digitised direction). Most can also be operated via user defined logical controls. The solver can
handle both subcritical and supercritical flow regimes.

TUFLOW 1D is documented in Section 5 . 1D/2D domain linking is discussed in Section 10 .

@57
1.1.4 EPA SWMM – 1D Solver

TUFLOW has supported 1D/2D dynamic coupling since its initial 2D solver development in 1989.
Traditionally, 1D linking and associated modeling has been applied using the TUFLOW 1D
(ESTRY) solver (see Section 1.1.3 ). New in the 2023-03-AF release, TUFLOW’s 1D linking and
solver options have been expanded to support the US EPA Storm Water Management Model
(referred to herein as SWMM). As such, 1D pipe networks can now be modelled using either the
TUFLOW 1D, SWMM, or a combination of the two 1D solvers. In addition to this, extra
functionality, such as SWMM hydrology and SWMM Low-impact developments (LIDs) features,
can now be used in TUFLOW.

SWMM 1D is documented in Section 6 . 1D/2D domain linking is discussed in Section 10 .

@58
1.1.5 Add-on Modules

The add-on modules require the relevant module licence in order to use the requested module
functionality. Should you not currently have the required module licence, please contact
[email protected].

The add-on modules are:

Advection Dispersion (AD)

CATCH
GPU Hardware
Quadtree or Mutiple 2D Domain

From the 2025.0 release and onwards it is possible to share the GPU Hardware and AD add-on
module licences between TUFLOW and TUFLOW-FV. This must be the same lock type (Hardware
(USB-2), Software (Digital File) or Cloud (Digital File)) and licence type (Local or Network) as the
TUFLOW engine licence of the simulation. If the licence type is Local, it must also reside on the
same lock. For more information on licence types see TUFLOW Licencing.

@59
1.1.5.1 Advection Dispersion (AD) Module

TUFLOW’s AD (Advection Dispersion) module is available for TUFLOW Classic and HPC. It
provides the capability to simulate constituent fate and transport in receiving waters. It is
applicable to:

Section 1 Introduction - 5 / 13 Page 27 / 1094

 Mixing in inland waterways
Fate of dissolved constituent plumes
Flushing assessments
Advanced atmospheric heat exchange routines simulating thermal mixing and plumes

TUFLOW’s AD User Manual, previously a separate document, has been integrated into this
manual, see Chapter 9 .

@60
1.1.5.2 TUFLOW CATCH Module

The TUFLOW CATCH module facilitates seamless simulation of whole-of-catchment hydrologic,

hydraulic, pollutant export and receiving waterway processes. It supports 1D, 2D and 3D
simulation of these process from the very top of catchment to the receiving waterway outlet via
accurate numerical simulation of the key physics that drive catchment / receiving water
hydrodynamics.

A TUFLOW CATCH module licence enables both the pollutant generation features in TUFLOW
HPC, and TUFLOW HPC to TUFLOW FV automated boundary condition information transfer
functionally. It also provides an option for coordinated execution of linked TUFLOW HPC and
TUFLOW FV models.

Documentation for the TUFLOW CATCH module is available in the TUFLOW CATCH User
Manual.

@61
1.1.5.3 GPU Hardware (GPU) Module

TUFLOW’s GPU module provides TUFLOW HPC access to NVIDIA GPU hardware (cards).
Modern GPU cards have large numbers of processing cores (at the time of writing a single card
may have in excess of 10,000 cores). By utilising multiple GPU cores, substantial reductions in run
time can be achieved, with the benefits most pronounced for large models (>1,000,000 2D cells).

TUFLOW HPC was linked with TUFLOW’s 1D solver in 2017. This update means simulations
including TUFLOW’s world-leading 1D/2D link functionality can be run with the TUFLOW HPC 2D
calculations utilising GPU hardware. Prior to the 2017 release the GPU hardware module was
limited to 2D only applications.

The runtime benefits of the GPU hardware module make it extremely powerful for modelling
situations with millions of cells. Models of this size may have otherwise been too computationally
intensive for a CPU based solution. As such, TUFLOW HPC run using GPU hardware is well-
suited to accurate assessment of:

Large-scale overland flow situations, using direct rainfall applied to the hydraulic model or via
external inflows sourced from a hydrologic model;
Integrated urban drainage assessments, where high resolution detail is required to depict the
urban topography and it’s interaction with 1D features representing the underground pipe
network; and
Fine-scale (high resolution) modelling.

Section 1 Introduction - 6 / 13 Page 28 / 1094

 @62
1.1.5.4 Quadtree or Multiple 2D Domain (M2D) Module

TUFLOW’s Quadtree or M2D (Multiple 2D Domain) Module allows 2D cell sizes to vary across the
2D model. The Quadtree feature is available using TUFLOW HPC, whilst the M2D feature is
available using TUFLOW Classic. Access to a single licence of the Quadtree/M2D Module allows
the user to apply either feature, depending on whether the TUFLOW Classic or TUFLOW HPC
solver is specified.

TUFLOW HPC Quadtree Module

For TUFLOW HPC, the Quadtree Module allows variable 2D cell sizes using a quadtree grid. A
quadtree grid is constructed by dividing a single cell into four cells, with these cells able to be
divided into four, and so on, enabling modellers to use larger cells in areas of uniform terrain (eg.
large flat floodplains, parks) and smaller cells where the terrain is variable or along primary flow
paths (eg. river channels, roads, open channels). The benefits include:

Much improved hydraulic computational delineation where most needed, particularly where
higher resolution velocity based calculations and outputs are required.
Smaller memory footprint on the CPU or GPU as a flexible grid structure is used rather than
bounding rectangles, which include a large percentage of inactive cells that consume memory.
Often a much reduced total cell count typically leading to faster simulations by a factor of
2 to 5.

@63

Figure 1.1: TUFLOW Quadtree Structure

TUFLOW Classic Multiple 2D Domain (M2D) Module

For TUFLOW Classic, the M2D Module provides the capability to nest areas of finer mesh
resolution within a coarser resolution fixed grid domain. A key feature of the TUFLOW M2D
Module is the ability to have multiple domains at different orientations to each other. TUFLOW also
provides full flexibility regarding the nesting extent. Multiple 2D domain modelling is discussed in
Section 10.7.2 .

@64
1.2 TUFLOW Webinars

The TUFLOW team run regular educational webinars online that aim to teach modellers, TUFLOW
or otherwise, the fundamentals of hydraulic modelling. The webinars are free to watch live and can
be viewed afterwards at no cost. Visit the TUFLOW Website Webinar Page to register for
upcoming events, or to watch recordings of past webinars. At the time of writing, the following
webinars have been recorded and are available for viewing. New topics and recordings will
continue to be added as they are produced.

Section 1 Introduction - 7 / 13 Page 29 / 1094

 December 2024: Applications of Groundwater Modelling in TUFLOW

August 2024: Improving SWMM Modeling with GIS Tools

July 2024: Efficient Model Running With Automation

April 2024: Water Quality Model Validation / Mass Balance Analysis

March 2024: How to Benchmark your Hydraulic Solver

November 2023: Real-time Flood Forecasting

October 2023: Integrated Catchment & Receiving Water Modelling

August 2023: Sediment Transport Modelling Applications

June 2023: Computer Hardware Purchase Advice for Hydraulic Modelling

April 2023: Water Quality Modelling - Part 2

February 2023: Flood Modelling 101

November 2022: 1D, 2D, 3D Hydraulic Modelling of Bridges

October 2022: Flood Modelling Quality Control

September 2022: Applied Hydrodynamic Modelling - Part 2

July 2022: Applied Hydrodynamic Modelling - Part 1

June 2022: Flood Risk Management

May 2022: Coastal Water Quality Modelling

April 2022: Operational Structure Modelling

March, 2022: 3D Coastal Modelling

February 2022: Urban Pipe Network Modelling

November 2021: Modelling Water Quality in Lakes

October 2021: Modelling Energy Losses at Structures

September 2021: Tsunami, Dam Failure and Non-Newtonian Modelling

July 2021: Next Generation 2D Hydraulic Modelling

June 2021: Maximising Hydraulic Model Accuracy

May 2021: Coastal Modelling 101

April 2021: Hydraulic Model Calibration to Historic Events

March 2021: The Future of Water Quality Modelling

February 2021: Is Direct Rainfall (Rain-on-Grid) Accurate?

December 2020: 2D and 3D Sediment Transport Modelling

November 2020: 2D Cell Size Selection for Accurate Hydraulic Modelling

October 2020: Hardware Selection and Trends in Hydraulic Modelling

Section 1 Introduction - 8 / 13 Page 30 / 1094

 More…

@65
1.3 Modelling Environment

TUFLOW offers a very powerful and workflow efficient approach to modelling. The approach
combines simple and easy to produce control files or scripts together with the power of GIS
software.

The fundamental software for building TUFLOW models and viewing results are a text editor,
spreadsheet software and GIS software, as shown in Table 1.1 . The free‑to‑use TUFLOW
Viewer QGIS Plugin greatly enhances a modeller’s ability to quickly view time-series and map
outputs, animate results and compare different simulations. The TUFLOW Viewer is documented
on the TUFLOW Wiki.

TUFLOW’s implementation of this GIS based modelling environment approach offers major
benefits, including:

TUFLOW scripts (control files) allow modellers to readily and easily setup, modify and run
numerous simulations, whether it be different calibration events, a batch of design events or
various what-if scenarios investigating flood mitigation options.
The modelling framework avoids the duplication of input datasets during the versioning of
models. For example, the base DEM might be used by hundreds or thousands of simulations
during a study, but it only needs to exist once; there is no need to copy the DEM for each
simulation as is the case for GUI-based software.
TUFLOW benefits from the unparalleled power of GIS as a “work environment”. GIS software
are industry leaders at efficiently managing large, complex and numerous spatial datasets.
GIS includes a suite of excellent data management, manipulation and presentation tools. The
QGIS TUFLOW Viewer Plugin greatly enhances modellers’ ability to setup and view models
and results.
Working directly in GIS means model input data is geographically referenced, not 2D grid
referenced, this supports workflow efficient model updates (such as changes to the model 2D
cell size specification or boundary condition locations).
Model results are written to non-proprietary open data formats compatible with most GIS
software. This facilitates the efficient production of high-quality GIS based mapping for
reports, brochures, plans and displays.
TUFLOW is compatible with numerous different GIS packages (e.g. ArcGIS, QGIS and
MapInfo). Modellers can chose to use the GIS software package of their choice.
Seamless handover of model inputs and results to clients requiring data in GIS format. Clients
are not required to purchase a TUFLOW licence to view results.
Superior data and modelling quality control.

Section 2.1 outlines a variety of software packages available for constructing TUFLOW models
and visualising simulation results. It lists a range of GIS software and also third party Graphical
User Interface (GUI)’s options from TUFLOW’s partner organisations. This manual focuses on
TUFLOW’s modelling within the GIS environment. For documentation relating to third-party
TUFLOW GUIs, please refer to the third party’s product manual.

Section 1 Introduction - 9 / 13 Page 31 / 1094

 @66 Table 1.1: TUFLOW Modelling Environment

Software

A Text Editor is used to

create and edit TUFLOW
simulation control files.
The control files list all
the simulation
commands and file path
references to the above
mentioned GIS and
tabular datasets.

Spreadsheet Software
is used to tabulate time-
series and other non-
geographically located
data.

GIS Software is used to

set up, modify,
thematically map and
manage all geographic
inputs and to view
simulation results.

QGIS’s TUFLOW Viewer

Plugin greatly enhances
the modelling
experience.

Section 1 Introduction - 10 / 13 Page 32 / 1094

 @67
1.4 Limitations and Recommendations

TUFLOW is designed to model free-surface flow in coastal waters, estuaries, rivers, creeks,
floodplains and urban drainage systems using the 1D St Venant Equations (all physical terms) and
the 2D form of the free surface Navier-Stokes equations (all physical terms) often referred to as
the Shallow Water Equations (SWE). Flow regimes through structures are handled using standard
structure equations covering all flow regimes, and supercritical upstream controlled flow is
supported in the 1D and 2D solvers. The 2nd order spatial solutions produce negligible numerical
diffusion. TUFLOW HPC also supports non-Newtonian flow and mixed flow (Newtonian and non-
Newtonian).

However, all solutions are approximations to reality. Whilst TUFLOW’s solvers have industry
leading accuracy and have been comprehensively benchmarked to known solutions or
measurements, they have their limitations, with the key ones discussed below.

All models, irrespective of the software, require a sufficiently fine computational resolution to
not limit the model’s accuracy. Demonstrating results convergence, that is that the results do
not demonstrably change when the computational interval (timestep) or 2D cell size is
reduced, is an important quality control test. TUFLOW’s solvers have been extensively
benchmarked for results convergence and new features such as TUFLOW HPC’s Sub-Grid
Sampling (SGS) can greatly assist with improving results convergence. However, no matter
the solution or software, results convergence testing during the model design phase should
be a standard test.

Where super-critical flow occurs the results should be treated with caution, particularly if they
are in key areas of interest. Hydraulic jumps and surcharging against obstructions are
complex 3D flow phenomena. For example, for hydraulic jumps, 1D solutions simply show a
change from supercritical to subcritical flow from one computational point to the next. Both
TUFLOW Classic and TUFLOW HPC 2D solvers will handle the transition and provide higher
resolution output than 1D. However, TUFLOW HPC will produce a more accurate solution due
to its shock capturing formulation. Where vertical acceleration is important, such as flow down
a dam spillway face, both the 1D and 2D equations are not suited to modelling the flow in
detail, however, the quantity of flow passing through such a structure can be well represented
by using a spillway structure in 1D or for TUFLOW HPC varying the weir flow parameters
introduced for the 2023‑03 release.

The TUFLOW HPC Wu turbulence model, as of the 2020‑01 release, is recommended over
the Smagorinsky eddy viscosity formulation, which in turn is preferred over the constant
viscosity formulation to model sub-cell turbulence (Barton, 2001 ; Collecutt et al., 2020 ). As
of the 2020-01 release, the default approach for TUFLOW HPC is the Wu turbulence model
and for TUFLOW Classic the Smagorinsky approach (as the Wu model has not yet been built
into the Classic solver). It is always good practice to carry out sensitivity tests to ascertain the
importance of the sub-cell turbulence coefficient(s) and formulation, which will be most
influential where the bed friction is low (e.g. in tidal reaches and coastal waters) and where
there are significant changes in velocity direction and magnitude, causing sub-grid shear
effects (e.g. downstream of a constriction).

If using the Smagorinsky formulation, caution is needed when using 2D cell sizes where the
flow depth is larger than the cell width (Barton, 2001 ; Collecutt et al., 2020 ). Modelling on
a fine resolution where water depths are greater than the cell size will likely not produce

Section 1 Introduction - 11 / 13 Page 33 / 1094

 converging results with decreasing cell size. For this reason, the default in TUFLOW Classic
since the 2000s is the combination of the Smagorinsky formulation with a constant eddy
viscosity. This is because the Smagorinsky formulation tends to a no turbulence state with
reducing cell size, with the small addition of constant eddy viscosity offsetting this trend.

Collecutt et al. (2020 ) demonstrates that the constant coefficient is heavily dependent on the
2D cell size and needs to be calibrated. The default Smagorinsky and constant coefficients in
TUFLOW Classic can be considered suitable for most real-world applications where the cell
size is similar or greater than the depths in the main flowpaths.

The Wu turbulence model (default setting in TUFLOW HPC from the 2020‑01 release)
resolves the above issues with benchmarking demonstrating 2D models can confidently be
constructed and utilised across a wide range of cell sizes (flume scale to major rivers), even
when much less than the depth (Collecutt et al., 2020 ).
Modelling of hydraulic structures should always be cross-checked with desktop calculations or
other software, especially if calibration data is unavailable and/or the structures are located in
key areas. All 1D and 2D schemes are only an approximation of the complex 3D flows that
can occur through a structure, and regardless of the software used, the modeller should
check model performance (Syme et al., 1998 ; Syme, 2001a ).

There is no momentum transfer between 1D and 2D connections when using the sink/source
connection approach (SX link). The HX link does preserve momentum in the sense that the
velocity field is assumed to be undisturbed across the link, but the velocity direction is not
influenced by the direction of the linked 1D channel. In most situations these assumptions are
not of significant concern, however, they may influence results where a large structure
(relative to the 2D cell size) is modelled as a 1D element. Under such circumstances,
TUFLOW has a range of options for modelling large structures in the 2D solution scheme.
Modelling fully in 2D will preserve the momentum transfer.

References

@69
@68
Barton, C. (2001). Flow Through an Abrupt Constriction – 2D Hydrodynamic Model Performance
and Influence of Spatial Resolution (C. Barton, Ed.) [M.Eng.Sc Master Thesis].
https://tuflow.com/media/4983/2001-flow-through-an-abrupt-constriction-2d-hydrodynamic-
performance-and-influence-of-spatial-resolution-barton-thesis.pdf

@70
Collecutt, G., Gao, S., & Syme, W. (2020). Mesh-Size Insensitive Turbulence Modelling for the 2D
Shallow Water Equations. River Flow 2020, pp. 1–9. https://tuflow.com/media/5023/2020-
mesh-size-insensitive-turbulence-modelling-for-the-2d-shallow-water-equations-collecutt-et-al-
iahr-river-flow-delft.pdf

@71 S., & Pender, G. (2013). Benchmarking the Latest Generation of 2D Hydaulic Modeling
Neelz,
Packages. Environment Agency. https://doi.org/SC120002/R

@72
Stelling, G. (1984). On the Construction of Computational Methods for Shallow Water Flow
Problems. Rijkswaterstaat Communications.

@73 W. (1991). Dynamically Linked Two Dimensional / One-Dimensional Hydrodynamic

Syme,
Modelling Program for Rivers, Estuaries and Coastal Waters (W. Syme, Ed.) [M.Eng.Sc(100%

Section 1 Introduction - 12 / 13 Page 34 / 1094

 Research) Thesis]. Dept of Civil Engineering. https://tuflow.com/media/4982/1991-tuflow-
dynamically-linked-2d-and-1d-hydrodynamic-modelling-syme-thesis.pdf

@74 W. (2001a). Modelling of Bends and Hydraulic Structures in a Two-Dimensional Scheme.

Syme,
The Institution of Engineers, Australia Conference on Hydraulics in Civil Engineering.
https://tuflow.com/media/4984/2001-modelling-of-bends-and-hydraulic-structures-in-a-2d-
scheme-syme.pdf

@75 W., Nielsen, C., & Charteris, A. (1998). Comparison of Two-Dimensional Hydrodynamic
Syme,
Modelling Systems Part One - Flow Through a Constriction. International Conference on
Hydraulics in Civil Engineering.

Section 1 Introduction - 13 / 13 Page 35 / 1094

 @80

@81
Section 2 Getting Started

@82
2.1 How to Build Your First Model

TUFLOW includes a wide range of self-education resources to aid new users. Available options
include online tutorials, example models, demonstration models and eLearning modules. All
models included or constructed when completing these self-education options have been
designed using a licence-free mode. As such, there is no need to purchase a software licence to
learn TUFLOW.

All TUFLOW self-education resources are fully supported via the TUFLOW Support Services, and
[email protected] can be contacted for support.

As an alternative to self-education, paid online and in-person training classes are also available
for learning under the guided instruction of a TUFLOW expert. Courses are advertised via the
TUFLOW Website Training Catalogue. For further information on paid training options please
contact [email protected].

@83
2.1.1 Tutorial Models

A number of free Tutorial Models are available for download and are documented in the TUFLOW
Wiki. Current tutorials include:

Module 1 - 2D Base Model

Module 2 - Topography Updates
Module 3 - 1D Culverts
Module 4 - 2D Bridges
Module 5 - Integrated Urban Drainage
Module 6 - Direct Rainfall
Module 7 - Quadtree
Module 8 - Scenario Management
Module 9 - Event Management
Module 10 - Dam Break
Module 11 - 1D Open Channel

The tutorials have been created using QGIS as the model development environment. It is strongly
recommended that new users complete our free Introduction to QGIS for TUFLOW eLearning
beforehand.

Section 2 Getting Started - 1 / 25 Page 36 / 1094

 @84
2.1.2 Example Models

Free Example Models are documented and are available for download via the TUFLOW Wiki. The
example model dataset includes over 150 standalone models demonstrating the most commonly
used TUFLOW features. This education resource is intended for experienced modellers wishing to
further develop their skills following completion of the Tutorial Models. Unlike the tutorials, this
dataset does not include step-by-step instructions. Users of this dataset are expected to have a
basic knowledge TUFLOW, and have suitable skills to open the model files by referencing the
TUFLOW Control File (TCF) referenced in the example model catalogue list. The catalogue list on
the TUFLOW Wiki has been separated into the following sub-sections:

Project initiation
Model units
Solver options
Output options
Boundary condition options (inflows, outflows and losses)
Topography features (static and dynamic topography changes, sub-grid sampling options)
Structures (bridges, weirs, culverts, operational controls)
Multiple domain model design (1D/2D and 2D/2D)
Bulk simulation
Advection dispersion.

@85
2.1.3 Demonstration Models

A series of demonstration models were developed as part of three “challenges” issued prior to the
2012 Flood Managers Association (FMA) Conference in Sacramento, USA. The objective was to
establish the variation in flood extents using different 2D software and modellers. Anyone could
submit results, and the results were presented anonymously at the 2D Modelling Symposium held
on the first day of the conference.

The three Challenge Models were:

Challenge 1: An urban environment with a concrete lined main channel and numerous
structures.
Challenge 2: A coastal floodplain with two river entrances to the ocean during a flood.
Challenge 3: A levied river within an alluvial fan in an arid, irrigated area.

The models developed using TUFLOW were created within a week and run for various scenarios.
Positive feedback was received on TUFLOW’s accuracy, and on the impressively short turnaround
time required to build the models and run the simulations. The Free Demonstration Models are
documented and are available for download from the TUFLOW Wiki.

@86
2.1.4 Licence Free Demo Mode

As of the 2016-03 release, setting Demo Model == ON within the TCF allows users to set up
and simulate small-scale test models using their own datasets, but without a licence. The limits
associated with the licence-free demo mode are:

Section 2 Getting Started - 2 / 25 Page 37 / 1094

 The total number of 2D cells may not exceed 100,000 – this is the number of cells within the
bounding rectangle.
The total number of active 2D cells may not exceed 30,000.
The total number of 1D channels may not exceed 100.
There is only one (1) 2D domain.
Simulation clock time cannot exceed 10 minutes.

@87
2.1.5 eLearning Modules

TUFLOW eLearning is a suite of online guided training modules available on-demand. The
eLearning includes step-by-step lessons comprising a combination of written notes, background
content videos, demonstration videos and hands-on exercises. The list of available eLearning
modules is growing year-on-year. The current available catalogue includes:

Introduction to QGIS for TUFLOW

Introduction to 2D Modelling TUFLOW
Introduction to Python for TUFLOW
Introduction to GDAL for TUFLOW
2D Topography and Modification Options
1D Culvert and 2D Bridge Modelling
Bulk Simulation Management

Access the eLearning via the TUFLOW Website Training Catalogue.

@88
2.1.6 Instructor Led TUFLOW Training Courses

As an alternative to self-education, paid online and in-person training classes are also available to
learn under the guided instruction of a TUFLOW expert. Scheduled courses are advertised via the
TUFLOW Website Training Catalogue. For further information on paid training options please
contact [email protected].

@89
2.2 The TUFLOW Modelling Concept

The fundamental software necessary for building a TUFLOW model and viewing simulation results
are:

Text editor. Used to create and edit TUFLOW simulation control files. The control files list all
the simulation commands and file path references to the above mentioned GIS and tabular
datasets.
Spreadsheet software. Used for time-series and other non-geographically located data.
GIS software. Used to create, modify and manage all geographic inputs and to view
simulation results.

@90

Section 2 Getting Started - 3 / 25 Page 38 / 1094

 Figure 2.1: TUFLOW Modelling Concept
User survey results consistently indicate that the majority of TUFLOW modellers globally use the
text editor / spreadsheet / GIS working environment approach. Within that framework, the most
popular supporting software combination is Notepad++, Excel and QGIS (with the free QGIS
TUFLOW Plugin). Due to the dominant usage of these supporting software packages, detailed
information for Notepad++ and QGIS is provided in Sections 2.2.1 and 2.2.2 . Please note,
modellers are not required to use Notepad++, Excel and QGIS. Other alternative supporting
software may be used instead. A complete list of commonly used options is outlined in Table 2.1 .

Section 2 Getting Started - 4 / 25 Page 39 / 1094

 @92 Table 2.1: Supporting Software Options

Software
Suggested Software
Type

UltraEdit / TUFLOW Wiki UltraEdit Tips

Notepad++ / TUFLOW Wiki Notepad++ Tips

Textpad / TUFLOW Wiki Textpad Tips

Visual Studio Code

Text Editor
Other: Any text editor can be used for creating TUFLOW control files,
including the Microsoft Windows default, Notepad. However, the above
listed editors are recommended. They allow for advanced options, such as
syntax highlighting of TUFLOW control files and launching TUFLOW
simulations from the text editor.

Spreadsheet Microsoft Excel / TUFLOW Wiki Excel Tips

Software Libre Office

QGIS (TUFLOW Wiki QGIS Tips) with QGIS TUFLOW Plugin. The QGIS
TUFLOW Plugin provides a range of pre- and post- processing tools, and
dynamic viewing of 1D and 2D results in TUFLOW Viewer.

ArcGIS Pro (TUFLOW Wiki ArcGIS Tips) with Spatial Analyst for the creation
of model inputs and viewing of static results. Dynamic viewing of 1D and 2D

GIS Platforms results is not available in ArcGIS.

MapInfo Professional (TUFLOW Wiki MapInfo Tips) for the creation of model
inputs and viewing of static results.

Dynamic viewing of 1D and 2D results is not available in ArcGIS or MapInfo.

QGIS (TUFLOW Wiki QGIS Tips), SMS (TUFLOW Wiki SMS Tips) or
WaterRIDE are recommended to address these limitations.

Scalgo (TUFLOW Wiki Scalgo Tips)

SMS (TUFLOW Wiki SMS Tips)

Other
WaterRIDE
Software
Blue Kenue

FEWS

For modellers preferring to work predominantly within a Graphical User Interface (GUI)
environment instead of GIS, the following TUFLOW GUI options are also available:

SMS TUFLOW Interface

12D TUFLOW Model Interface
Flood Modeller Pro
XPSWMM

Section 2 Getting Started - 5 / 25 Page 40 / 1094

 @93
2.2.1 Notepad++

Notepad++ is a free text editor available from https://notepad-plus-plus.org/downloads/. The

Notepad++ functionality listed below makes it well suited as an editor for creating and updating
TUFLOW control files. Click on the respective links in each bullet point for more information:

Syntax Highlighting: Colour coding of TUFLOW control files, shown in Figure 2.2 .
Simulation Execution: The ability to start a TUFLOW simulation directly from Notepad++.
File Navigation: The ability to open files based on the relative reference provided in a
TUFLOW control file. For example a geometry control file (.tgc) can be opened directly from
the TUFLOW control file (.tcf) without having to locate it in Windows Explorer.

@94

Figure 2.2: NotePad++ TUFLOW Syntax Highlighting

@95
2.2.2 QGIS / TUFLOW Viewer

QGIS is free, open source GIS software available from https://www.qgis.org/. It is an official
project of the Open Source Geospatial Foundation (OSGeo). It runs on Linux, Unix, Mac OSX,
Windows and Android and supports numerous vector, raster, and database formats and related
functionalities.

For users wishing to adopt QGIS as the model development or result viewing environment, we
strongly recommend completing our free Introduction to QGIS for TUFLOW eLearning. It teaches
how to configure QGIS for TUFLOW modelling and provides an entry level overview on how to use
the software.

Section 2 Getting Started - 6 / 25 Page 41 / 1094

 We also recommend installing the free QGIS TUFLOW Plugin. The QGIS TUFLOW Plugin
includes a suite of tools built to increase TUFLOW workflow efficiency. Installation and use
instructions are provided in the QGIS Tips and Tricks section of the TUFLOW Wiki.

TUFLOW Viewer is included in the QGIS TUFLOW Plugin. As the name suggests, TUFLOW
Viewer upgrades the QGIS Map Window to become a complete dynamic interactive TUFLOW
simulation result viewer. This addition to QGIS makes the the programme’s functionality
comparable to commercial GUI software. Documentation of the TUFLOW Viewer is located on the
TUFLOW Wiki.

@96

Figure 2.3: QGIS with TUFLOW Viewer

@97
2.3 Installing and Running TUFLOW

@98
2.3.1 TUFLOW Downloads and Installation

TUFLOW does not require an installer, but instead simply requires the user to copy or unzip the
downloaded files into a folder. This approach allows the modeller to have as many releases or
versions of TUFLOW available as required. This is beneficial, as there is often a need to run or re-
run legacy models using older TUFLOW versions. The current TUFLOW release version, Manual
and Release Notes are available via the TUFLOW website Downloads page. All past TUFLOW
versions are available from the Downloads Archive.

Section 13.4.1 provides more information on downloading and installing TUFLOW. Detailed step-
by-step instructions for new users are also provided on the TUFLOW Wiki.

@99
2.3.2 TUFLOW Licencing

A TUFLOW licence is required to run TUFLOW, but is not required when using third-party software
such as a GIS, text editor or GUI. Licences are hosted on hardware locks (e.g. USB-2 lock),
software locks (e.g. via a configuration file housed on a particular computer, server or cloud virtual
machine), or from a TUFLOW Cloud Server. Email [email protected] for a quote to purchase a
TUFLOW licence. For further licencing information refer to Section 13.5.1 and the TUFLOW
installation instructions on the TUFLOW Wiki.

TUFLOW can be used licence free for the TUFLOW Tutorials (Section 2.1.1 ), Example models
(Section 2.1.2 ) or when running TUFLOW using Demo Mode (Section 2.1.4 ).

Section 2 Getting Started - 7 / 25 Page 42 / 1094

 All TUFLOW use is governed by the TUFLOW Products End User Licence Agreement. By
installing and/or using a TUFLOW Product you agree to the terms of the TUFLOW Products End
User Licence Agreement.

@100
2.3.2.1 3rd Party Software Libraries

TUFLOW and its utilities rely on several 3rd party software libraries which are either open source
or have permissive licences. These libraries, with links to their respective licence agreements, are
listed below:

CDT
HDF5
hec-dss
lzw
NetCDF
OWA SWMM
Sqlite
XMDF
zlib

@101
2.3.3 Performing Simulations

TUFLOW simulations are started by running the TUFLOW executable and passing the input
TUFLOW control file (.tcf). There are a number of ways of initiating simulations:

Running a batch file. Batch files can be used to run single TUFLOW simulations but also can
be set up to loop through events and scenarios to run a multitude of simulations or to push
simulations to different processors.
From the text editor – ideal for one off simulations, especially whilst constructing a model.
Directly from GIS software.
Using Microsoft Explorer to right click and run.
Via a GUI, such as the SMS TUFLOW Interface or 12D.
From a Command (Console) Window.

Detailed descriptions on running TUFLOW from the above methods are provided on the TUFLOW
Wiki.

@102
2.4 Folders, File Types and File Naming

@103
2.4.1 Folder Structure

Table 2.2 presents the recommended set of sub-folders to be set up for a TUFLOW model. Any
folder structure may be used; however, it is strongly recommended that a system similar to that
below be adopted. For large modelling jobs with many scenarios and simulations, a more complex
folder structure may be warranted, though should be based on that shown below.

Section 2 Getting Started - 8 / 25 Page 43 / 1094

 @104 Table 2.2: Recommended Sub-Folder Structure

Sub-
Description
Folder

Contains boundary condition database(s) and time-series data

bc_dbase
for 1D and 2D domains.

Contains the GIS and other check files to carry out quality
check
control checks (use Write Check Files command).

Contains the .tgc, .tbc and other model data files, except for
the GIS layers and grid inputs which are located in the
model
model\gis folder and model\grid folder respectively (see
below).

Contains the GIS vector layers that are inputs to the 2D and
model\gis
1D model domains.

Contains the GIS raster layers that are inputs to the 2D model
model\grid
domains.

results Contains the result files (use Output Folder command).

runs Contains the .tcf and .ecf simulation control files.

Contains the log files (e.g. .tlf) and _messages.shp files (use
runs\log
Log Folder command)

Note:

Files can be located relative to the file they are referred from. For example, the path and
filename of a file referred to in a .tgc file is sourced relative to the .tgc file (not the .tcf file).
See also Section 4.2.2 for a discussion on absolute and relative file paths.
Whilst TUFLOW readily accepts spaces and special characters (such as ! or #) in filenames
and paths, other software may have issues with these. It is therefore recommended that
spaces and other special characters not be used in the simulation path and filename without
prior testing.
Filenames and extensions are not case sensitive in any TUFLOW control files.

@105
2.4.2 File Types

The most common file types and their extensions are listed in Table 2.4 . These files are
classified into the following use categories:

Control Files: used for directing inputs to the simulation and setting parameters. The style of
input is very simple, free form commands, similar to writing down a series of instructions. This
offers the most flexible and efficient system for experienced modellers. It is also easy for
inexperienced users to learn.
Data Input Files: primarily GIS layers defining the spatial inputs and comma-delimited files
generated using spreadsheet software for tabular data, such as boundary condition time-
series entries.
Data Output Files: containing the 2D and 1D hydraulic simulation result outputs.

Section 2 Getting Started - 9 / 25 Page 44 / 1094

 Check Files: are produced at the beginning of a TUFLOW simulation so modellers and
reviewers can readily check that the constructed model is as intended. Advanced models
draw upon a wide variety of data sources. The check files represent the final model dataset
which is used for the simulation calculations. For more details, see the TUFLOW Check Files
section of the TUFLOW Wiki.

Section 2 Getting Started - 10 / 25 Page 45 / 1094

 @106 Table 2.3: List of Most Commonly Used File Types - Control Files

Use
File Extension Description Format
Category

Controls the data input and output for

TUFLOW
2D or 1D/2D simulations. The Control
Simulation .tcf Text
filename (without extension) is used File
Control File
for naming all 2D domain files.

TUFLOW
Boundary Controls the 2D boundary condition Control
.tbc Text
Conditions data input. File
Control File

TUFLOW Database of .tcf and .ecf file Control

.tef Text
Event File commands for different events. File

TUFLOW
Controls the 2D geometric or Control
Geometry .tgc Text
topographic data input. File
Control File

TUFLOW
Controls the construction of a Control
Quadtree .qcf Text
Quadtree grid. File
Control File

Controls the data input and output for

ESTRY
1D domains. The filename (without Control
Simulation .ecf Text
extension) is used for naming all 1D File
Control File
output files.

Contains operating rules that can be

applied to hydraulic structures, pumps
and other controllable devices
TUFLOW
modelled as 1D elements. Each set of Control
Operating .toc Text
operating rules is contained within a File
Controls File
Control definition. More than one
structure/device can use the same
control definition.

Contains the input data to temporally

TUFLOW
and spatially apply rainfall including Control
Rainfall .trfc Text
the interpolation of rainfall gauge data File
Control File
over time.

Contains reference to the two

TUFLOW AD mandatory files required for the Control
.adcf Text
Control File advection-dispersion (AD) model File
execution.

Controls the input data for time-

TUFLOW
varying global or spatially-varying Control
External .tesf Text
external forcing such as wind or wave File
Stress File
radiation stresses.

Section 2 Getting Started - 11 / 25 Page 46 / 1094

 Use
File Extension Description Format
Category

A file that is included inside another

file using the Read File command
.trd in .tcf, .tgc and .ecf files. Minimises
Control
Read Files .erd repetitive specification of commands Text
File
.rdf common to a group of files. The file
extension can be anything; .trd, .erd
and .rdf are most commonly used.

Section 2 Getting Started - 12 / 25 Page 47 / 1094

 @107
Table 2.4: List of Most Commonly Used File Types - Input, Output and Check File Types

Use
File Extension Description Format
Category

Sets the Manning’s n values for

TUFLOW .tmf
different bed material categories in Input File Text
Materials File .csv
the 1D and 2D domains.

Sets the infiltration method and

TUFLOW
.tsoilf infiltration parameters for different Input File Text
Soils File
soil types in the 2D domains.

New models do not require or support

any fixed field input. However, older
models (prior to the 2010-10 release)
could utilise these formats. As the Input File
Fixed Field variety of
commands are no longer supported Output Text
Files extensions
the fixed field documentation has File
been removed from this manual – see
manuals prior to 2007 downloadable
from TUFLOW Website.

A snapshot of 2D domain
Input File
TUFLOW computational results at an instant in
.trf Output Binary
Restart File time, used for hot-restart of
File
simulations.

A snapshot of 1D domain
Input File
ESTRY computational results at an instant in
.erf Output Text
Restart File time, used for hot-restart of
File
simulations.

These files are used for boundary

Input File
condition databases, boundary
Comma Output
condition tables, 1D cross-sections,
Delimited .csv File Text
1D storage tables, etc. They are
Files Check
opened and saved using spreadsheet
File
software such as Microsoft Excel.

ArcGIS’s industry standard for GIS

layers. The .shp file contains Input File
.shp
ArcGIS information on the GIS objects Output
.dbf
Shapefile coordinates. The .dbf file contains the File Binary
.shx
Layers attribute data information associated Check
.prj
with the objects. Refer to the .tcf File
command GIS Format .

Section 2 Getting Started - 13 / 25 Page 48 / 1094

 Use
File Extension Description Format
Category

MapInfo’s industry standard GIS data

exchange format. The .mif file
contains the attribute data definitions
and the geographic data of the Input File
MapInfo objects. The .mid file contains the Output
.mif
MIF/MID attribute data. The .mid files are of File Text
.mid
Files similar format to .csv files, so they Check
can be opened by Excel or other File
spreadsheet software. The files are
text based and can be scripted by
advanced users.

Input File
GeoPackage is a spatial database file
Output
format, natively used in QGIS, that
Geopackage .gpkg File Binary
supports the efficient storage of GIS
Check
vector and raster data.
File

Input File
Gridded data in the widely used ESRI
Output
ESRI Ascii Ascii grid format. This can be read in
.asc File Text
raster grid the majority of GIS platforms
Check
including ArcMap, QGIS and MapInfo.
File

Gridded data in the binary versions of Input File

the .asc format (see above). This Output
Binary Float
.flt data is recognised by most GIS File Binary
Grid
packages and is much faster to Check
read/write than the .asc format. File

Input File
Compressed Raster Grid data. This
Output
data is recognised by most GIS
GeoTIFF .tif File Binary
packages and is faster to read/write
Check
than the .asc and .flt format files.
File

NetCDF is a database file format for Input File

NetCDF .nc raster inputs. TUFLOW’s supported Output Binary
format uses NetCDF CF Convention. File

SMS super file containing the various

files and other commands that make
SMS Super up the output from a single Output
.sup Text
File simulation. Opening this file in SMS File
opens the .2dm file and the primary
.xmdf file.

Section 2 Getting Started - 14 / 25 Page 49 / 1094

 Use
File Extension Description Format
Category

SMS 2D mesh file containing the

SMS Mesh 1D/2D model mesh and elevations. It Output
.2dm Text
File also contains information on File
materials and 2D grid codes.

Legacy format, recommended to use

XMDF instead. DAT is a SMS generic
SMS Data formatted simulation results file. Output
.dat Binary
File TUFLOW output can be written using File
the .dat format. See Section 11.2.3
for the different .dat file outputs.

XMDF (.xmdf) files are much faster to

access and can contain all TUFLOW
map output within a single file (rather
SMS XMDF than one file per output type as for Output
.xmdf Binary
File the .dat format). This is the File
recommended mesh output format.
See Section 11.2.3 for the different
.xmdf file data sets available.

WaterRIDE triangulated results file

.wrb
(.wrb) and/or grid based output (.wrr). Output
WaterRIDE .wrc Binary
The .wrc is a master file used when File
.wrr
there are multiple file outputs.

BlueKenue (National Research

.t3s Council Canada) output format. The Output
BlueKenue Binary
.t3v .t3s contains scalar data and the .t3v File
contains vector data.

12D Civil Format used by 12D for their Output

.tmo .tgo Binary
Solutions TUFLOW interface. File

A log file containing information about

TUFLOW Check
.tlf the 1D/2D data input process and a Text
Log File File
log of the 2D simulation.

A log file containing a concise

TUFLOW
summary of the simulation which can Check
Summary .tsf Text
be regularly updated during the File
File
simulation.

Original ESTRY output file containing

all 1D input data and results. This file
ESTRY Check
.eof is useful for checking 1D input data Text
Output File File
and reviewing flow regimes in 1D
channels.

Section 2 Getting Started - 15 / 25 Page 50 / 1094

 @108
2.4.3 Naming Conventions

As the bulk of the data input is via GIS data layers, efficient management of these datasets is
essential. For detailed modelling investigations, the number of TUFLOW GIS data layers has been
known to reach over a hundred for large complex models, although the majority of models would
utilise five to twenty layers. Good data management also caters for the many other GIS layers
being used (aerial photos, cadastre, etc.).

Different TUFLOW input files require different GIS attributes, for example an initial water level
input file only requires a single attribute (with the attribute – initial water level), whereas, a 1D
channel has a greater number of attributes (channel type, inverts etc.). Each of these file types is
described in Table 2.5 to Table 2.6 . It is strongly recommended that the prefixes described in
Table 2.5 to Table 2.6 be adhered to for all 1D and 2D GIS layers. This greatly enhances the
data management efficiency and, importantly, makes it much easier for another modeller or
reviewer to quickly interpret the model. The .tcf command Write Empty GIS Files can be
used to automate the creation of template files which use the recommended GIS data naming
convention. A detailed description on this topic and an example is provided on the TUFLOW Wiki.

Data input is structured so that there is no limit on the number of data sources. Commands can be
repeated indefinitely in the text files to build a model from a variety of sources. For example, a
model’s topography may be built from more than one source. A DTM may be used to define the
general topography, updated with locallised survey data, while several 3D elevation lines
(breaklines) define the crests of levees or roads. The sequential approach to reading datasets
offers unlimited flexibility and increased efficiency. This layered approach also offers good
traceability and quality control.

Refer also to Section 13.2 and 13.3 which provide further guidance on model naming
conventions and methods in which the same control files may be used to simulate multiple flood
events and scenarios, thereby reducing the potential number of files created.

Section 2 Getting Started - 16 / 25 Page 51 / 1094

 @109 Table 2.5: GIS Input Data Layers and Recommended Prefixes - 2D Domain

Suggested Refer to
GIS Data Type Description
File Prefix Section

Combined 1D/2D
This file contains lines and points defining
Time-Series
0d_rl Reporting Location(s) (RL) for 1D and 2D 11.3.3
Reporting
result time series graphs in Excel.
Location outputs

The 2d_ad_ic file type defines the

advection dispersion initial concentration.
2d_ac_ic Advection
The 2d_ad_md file type defines the 9.5.1.2
2d_ad_md Dispersion
advection dispersion minimum dispersion
coefficient.

2D Auto
Terminate This file contains points defining locations
2d_at 13.6.7
Tracking where auto terminate tracking is desired.
Locations

Used to define the locations of 2D

boundaries and 1D/2D dynamic links. For
large models it may be wise to separate
2d_bc_ 8.5
2D Boundaries the boundary conditions from the 1D/2D
(2d_hx_) 10.2.1
and 1D/2D Links links, in which case the 2d_bc prefix can
(2d_sx_) 10.2.2
be substituted with 2d_hx_ and 2d_sx_.
Cell code values may also be defined in
this layer.

Used for 2D flow constrictions to

represent additional losses associated
2d_bg
2D Bridge with bridges or box culverts. This input 7.3.8.2
2d_bg_pts
includes accounts for flow above and
below the bridge obvert (soffit).

GIS layer(s) containing objects, typically

2d_code_ 2D Cell Codes 7.3.2
polygons that define the cell codes.

2D Cell Width Used to define locations to reduce 2D cell

2d_cwf_ 7.3.9.2
Factor flow width.

Layer(s) defining the adjustment of 2D

cells to model structures such as bridges,
2D Flow
2d_fc_ box culverts, etc. Whilst this is still 7.5.6.1
Constrictions
supported the newer and more flexible
2d_fcsh_ and 2d_lfcsh_ are preferred.

Points, lines and polygons that modify the

Flow Constriction
2D cell sides flow width, place a lid
2d_fcsh_ 2D and 3D 7.5.6.1
(obvert or soffit) on a 2D cell, additional
Shapes
energy losses, and other modifications.

Section 2 Getting Started - 17 / 25 Page 52 / 1094

 Suggested Refer to
GIS Data Type Description
File Prefix Section

Used to apply an additional energy loss at

the 2D cell side (in the same manner as
Form Loss for 2D flow constrictions). The form or
2d_flc 7.3.9.3
Coefficient energy loss can be applied as fixed
values or on a form loss per unit length
basis.

Layer used to define the location of the

Gauge Level gauge for output based on water level
2d_glo_ 11.2.6
Output Location rather than time intervals. See Read GIS
GLO .

Layer(s) used to define groundwater

2d_gw_ 2D Groundwater 8.9.2
inputs.

Layer(s) used to define the spatial

2D Initial Water
2d_iwl_ variation in 2D domain initial water levels 8.9.1.2
Levels
at the start of the model simulation.

Points, lines and polygons that allow the

user to modify the 2D cell sides, flow
Layered Flow width, percentage blockage, and
2d_lfcsh_
Constriction 2D additional energy losses, for up to three 7.3.8.3
2d_lfcsh_pts
and 3D Shapes vertical layers. Designed for modelling 2D
flow under and over bridges, pipes and
other obstructions across the waterway.

GIS layer defining the origin and

orientation of the 2D grid. This layer is
2d_loc_ 2D Grid Location optional, however, is the preferred method 7.3.1
for defining the origin and orientation of
2D domains.

2D Longitudinal Layer(s) defining the locations

2d_lp_ Profile Output longitudinal profile output from the 2D 11.3.2.2
Locations model domain

2D Land-Use
Layers to define or change the land-use
2d_mat_ (Materials) 7.3.6
(material) types on a cell-by-cell basis.
Categories

Layer(s) defining receptors (eg.

buildings). TUFLOW records the flood
2d_obj_ 2D Receptor level and simulation time at one or more
11.4.1
2d_rec_ Objects gauge(s) when receptors are first
inundated above their trigger inundation
levels.

Layer(s) containing one or more polygons

2d_oz_ 2D Output Zones 11.2.5
defining the 2D regions to be output.

Section 2 Getting Started - 18 / 25 Page 53 / 1094

 Suggested Refer to
GIS Data Type Description
File Prefix Section

2D Plot (Time- Layer(s) defining the locations and types

2d_po_ Series) Output of time-series output from the 2D 11.3.2
Locations domains.

2D Quadtree Layer defining polygons of grid refinement

2d_qnl_ 7.4.1
Nest Levels for quadtree implementation.

Layer(s) defining the polygons of sub-

2d_rf_ Direct Rainfall catchment areas for applying rainfall 8.5.3
directly onto 2D domains or rainfall grids.

Layer(s) defining the polygons of sub-

catchment areas for applying a source
2d_sa_ (flow) (2d_sa) or rainfall directly onto 2D
2d_sa_rf 2D Source over domains (2d_sa_rf). 2d_sa_tr includes
8.5.2
2d_sa_tr Area additional attributes required for the SA
2d_sa_po trigger option. 2d_sa_po includes
additional attributes required for the SA
flow feature.

2D Soil Layer(s) that define the soil types on a

2d_soil_ 7.3.7
Infiltration cell-by-cell basis.

Layer used to distribute flow to, read in

2d_strm SA streamlines 8.5.2.1.1
with the Read GIS Streams command.

TUFLOW
HPC 7.4.4
2D Weir Layer used to adjust the weir factor
2d_wrf Adjustment locally, e.g. faces along a road
TUFLOW
Factor embankment.
Classic
7.5.2

Points, lines and polygons defining the

Variable (over
final geometry of a breach or other
time) 2D and 3D
2d_vzsh_ variation in model topography over time. 7.3.5.3
Elevations
Also includes points defining trigger
Shapes
locations.

Layer(s) that define areas (polygons) of

2D Elevations elevations at a constant height. This file is
2d_za_ 7.3.5.6
over an area typically created by renaming the
2d_z__empty file.

Section 2 Getting Started - 19 / 25 Page 54 / 1094

 Suggested Refer to
GIS Data Type Description
File Prefix Section

Optional 2D or 3D breaklines defining the

crest of ridges (e.g. levees,
embankments) or thalweg of gullies

2d_zln_ (e.g. drains, creeks). Ridges and gullies

2D Elevation cannot occur in the same layer so 2d_zlr_
(2d_zlr_) 7.3.5.5
Lines is often used for ridges and 2d_zlg_ for
(2d_zlg_)
gullies.

These files are typically created by

renaming the 2d_z__empty file.

2D Elevations as Layer(s) that define the elevations at the

2d_zpt_ 7.3.5.6
points 2D cells mid-sides, corners and centres.

Points, lines and polygons defining 2D

2D and 3D and 3D shapes for changing the
2d_zsh_ Shapes for elevations. Lines can be specified with a 7.3.5.2
2d_ztin_ (Points, Lines, width (thickness), and polygons are used 7.3.5.4
Polygons) as the boundaries for creating TINs
(triangulations).

Layer(s) used to provide define output

2D Evacuation
2d_zshr_ locations reporting the time and degree of 11.4.2
Route
inundation along evacuation routes.

Section 2 Getting Started - 20 / 25 Page 55 / 1094

 @110 Table 2.6: GIS Input Data Layers and Recommended Prefixes - 1D Domain

Suggested Refer to
GIS Data Type Description
File Prefix Section

Layer(s) defining the locations of 1D

domain boundaries.
1d_bc_ 1D Boundaries Note: Any links to the 2D domain are 8.4
automatically determined via the 2d_bc
layer(s).

Optional layer(s) that provide links to

tabular data of loss versus height
coefficients at a structure. The BG stands
for Bridge Geometry and the alternative LC
for Loss Coefficients.
1d_bg_
1D Bridge Losses For larger models, create a folder called 5.8.2
1d_lc_
‘BG’ under the ‘Model’ folder and place the
1d_bg_ tables in this folder along with all
the linked .csv files.
These files are typically created by
renaming the 1d_tab_empty file.

Optional layer(s) defining the spatial

1D Initial Water
1d_iwl_ variation in initial water levels at 1D nodes 8.9.1.1
Levels
at the start of the model simulation.

Optional layer(s) defining the location and 5.11.4.2

1d_mh_ 1D Manholes
parameters of manholes.

Optional layer(s) that provide links to

tabular data of storage surface area versus
height at nodes.
5.13.2.1
1d_na_ 1D Nodal Storage For larger models, create a folder called
‘NA’ under the ‘Model’ folder and place the
1d_na_ tables in this folder along with all
the linked .csv files.

Optional layer(s) used to define 1D node 5.13.2.1

1d_nd 1D Node
locations and attributes.

Layer(s) that define the 1D or quasi 2D

domain network of flow paths (channels),
1d_nwk_
1D Domain storage areas (nodes) and pit inlets (pits).
1d_nwke 5.4
Network The 1d_nwkb file uses a character field for
1d_nwkb
the “pBlockage” attribute instead of a
numeric field.

Optional layer(s) used to define the location

5.11.2.2
1d_pit 1D Virtual Pit and attributes associated with virtual pipes
and pits.

Section 2 Getting Started - 21 / 25 Page 56 / 1094

 Suggested Refer to
GIS Data Type Description
File Prefix Section

Lines of horizontal water level (as judged

1D Water Level by the modeller). These lines are used to
Lines for Mapping generate 3D surfaces or water level, 11.2.4.1
1d_wll_
of 1D results into velocity and other output of 1D domains.
2D formats This allows the combined viewing and
animation of 2D and 1D domains together.

Points that define the elevations (usually

from a DTM) and material values across 11.2.4.2
1d_wllp_ 1D WLL Points
the WLLs. This offers high quality viewing
and mapping of the 1D domains.

Optional layer(s) that provide links to

tabular data of cross-sectional XZ
(chainage-elevation) values or HW (height-
1d_xs_ width) values.
1D Tabular Input 5.7
1d_tab_ For larger models, create a folder called
‘XS’ under the ‘Model’ folder and place the
1d_xs_ tables in this folder along with all
the linked .csv files.

@111
2.5 Tips and Tricks

The TUFLOW Wiki is the primary location where the TUFLOW software team share useful
modelling tips and tricks. The Wiki covers an extremely wide range of subjects. A list of the main
subject matter topics are summarised in Table 2.7 .

New content is added to the Wiki regularly. Please join the LinkedIn TUFLOW User Group to be
informed of updates when they are published.

Section 2 Getting Started - 22 / 25 Page 57 / 1094

 @112 Table 2.7: TUFLOW Tips and Tricks

Tips and Tricks

Description
(Link)

A TUFLOW licence is required to run TUFLOW. This section of the Wiki

Licencing Tips
outlines the user steps required to request and import licence updates.

All TUFLOW self-education resources function using a licence-free mode.

Self-teach As such, there is no need to purchase a software licence to learn
Tutorial Modules TUFLOW. User documentation for the Self-teach Tutorial Modules are
hosted on the Wiki.

Every TUFLOW model initialisation and simulation error is assigned a

TUFLOW Error
unique error number, reported in the TUFLOW Log File. Tips outlining the
Message
description of the error message, why it may be occurring and suggestions
Database
on how to resolve the error are outlined in the Wiki.

User tips for the following support software: Excel, Notepad ++, TextPad,
Supporting
UltraEdit, 12D, ArcGIS, Ensight, Google Earth, MapInfo, QGIS, SCALGO
Software Tips
Live, SMS.

TUFLOW Viewer is a free 1D and 2D dynamic result viewing interface

included in the QGIS TUFLOW Plugin. It enables QGIS with added
functionality, upgrading the GIS software with features akin to traditional
Graphic User Interface software.

TUFLOW
Viewer User
Manual

A range of tools have been developed to support the conversion of other

Model
hydraulic modelling software models to TUFLOW: EPA SWMM to
Conversion
TUFLOW, FLO2D to TUFLOW, HEC-RAS to TUFLOW, InfoWorks ICM to
Tools
TUFLOW, MIKE Flood to TUFLOW and Flood_Modeller to TUFLOW.

The TUFLOW Utilities are a set of tools that have been developed to help
TUFLOW
users convert input data from one format to another for use in a TUFLOW
Utilities
model, or to post-process simulation results.

Section 2 Getting Started - 23 / 25 Page 58 / 1094

 Tips and Tricks
Description
(Link)

This is an expansive page of the Wiki covering a wide range of topics,

including:

Project Management:
Estimating Simulation Run Times, TUFLOW Naming Convention,
Modelling Log, Quality Assurance Reviewer Spreadsheet Download.

Hydrology:
Australian Rainfall and Runoff 2019, UK ReFH2 Processing, U.S. Soil
Conservation Service (SCS) Method, Convert to TS1 Utility (RORB,
URBS, WBNM, XP RAFTS).

TUFLOW Modelling:
General Discussion, TUFLOW Check Files, TUFLOW Template GIS
General (empty) Files, 1D Channels and Hydraulic Structures, 2D Hydraulic
Modelling Structures, 2D Cell Size Selection, TUFLOW Topography Guidance,
Guidance Boundary Condition Advice, Direct Rainfall (Rain on Grid) Modelling, HPC
Modelling, TUFLOW Stability Troubleshooting, TUFLOW Simulation
Speed and RAM Optimisation, TUFLOW Modelling Webinars, TUFLOW
Executable Version Change Log.

TUFLOW Results:
General Simulation Output Discussion (Time Series, Grid and Binary
Format), TUFLOW QGIS Plugin, TUFLOW Remapping Tool, Australian
Rainfall and Runoff (ARR) 2019 Guideline Result Ensemble Processing.

Other:
Hardware Selection Advice, Installation Guide for New Users, Industry
Guidelines, Modelling Accuracy, Uncertainties and Flood Impact Mapping
Tolerances.

Hardware This Wiki page provides guidance for modellers who are purchasing
Selection Advide computer hardware for TUFLOW modelling.

TUFLOW seamlessly integrates with GIS software. Any GIS or Computer

Aided Design (CAD) package can be used provided load or import and
GIS Software
save or export options are available for the GIS formats TUFLOW
TUFLOW
currently supports. The most commonly used GIS software are ArcGIS,
Plugins (ArcGIS,
ArcPro, MapInfo and QGIS. Due to their widespread use, customised
ArcPro, MapInfo
toolkits and plugins have been specifically designed for these GIS
and QGIS)
packages to improve TUFLOW model build and result viewing workflow
efficiency.

Section 2 Getting Started - 24 / 25 Page 59 / 1094

 Tips and Tricks
Description
(Link)

The open file formats used by TUFLOW for its input and output make it
well suited to automation via scripting as a means to improve workflow
efficiency. Many modellers develop their own tools to assist in their use of
GitLab TUFLOW TUFLOW and to automate many tasks. These tools cover a wide range of
User Group use cases, such as data preparation, advanced simulation control, model
quality assurance and result post-processing. A GitLab TUFLOW User
Group has been established to support the sharing and collaborative
development of these tools by the broader TUFLOW community.

PyTUFLOW is a package of Python tools for extracting TUFLOW Classic

and HPC time-series results. It can be used to automate output tasks such
as checking model health, goodness-of-fit for model calibration, viewing
PyTUFLOW on-the-fly model output (used in conjunction with Write PO Online
== ON), and high-volume output plotting from production runs. Unlike the
scripts available in the GitLab TUFLOW User Group, this package is
maintained by the TUFLOW Development Team.

Section 2 Getting Started - 25 / 25 Page 60 / 1094

 @117

@118
Section 3 Hydraulic Modelling Fundamentals

@119
3.1 Introduction

This chapter of the Manual discusses key considerations that should be addressed during the
design phase of a hydraulic modelling study, prior to the commencement of the model build.
Consideration of how the model is to be schematised and selection of key model parameters may
have a significant influence on the accuracy, stability and simulation time of the model, and may
avoid redundant work later in the study.

@120
3.2 Schematisation

@121
3.2.1 General Guidance

General guidance on model schematisation and best practice procedures is freely available from
numerous industry sources. These typically include discussion on data requirements, model
conceptualisation, calibrating / sensitivity testing, etc. Examples of such guidance documents are:

Two Dimensional Modelling in Urban and Rural Floodplains Stage 1 & 2 Report (Babister &
Barton, 2012 );
Fluvial Design Guide (Environment Agency, 2010 );
Integrated Urban Drainage Modelling (CIWEM, 2009 ).

Specific TUFLOW guidance relating to model schematisation, model resolution, timestep and
simulation time are discussed in the following sections.

@122
3.2.2 Model Dimensions: 1D, 2D or 3D?

Hydraulic calculations can be performed in one, two, or three spatial dimensions. A brief
description of each of these approaches is provided in this section, along with a summary of
strengths and limitations.

@123
3.2.2.1 One Dimensional (1D)

One dimensional (1D) models confine the water flow to a single dimension, specifically forwards or
backwards along a defined path. The path can be a river or drainage channel, an underground
stormwater pipe or other similar settings. It is possible to have a network of 1D paths with
junctions, representing a network of tributaries and rivers, or an underground stormwater system.

Section 3 Hydraulic Modelling Fundamentals - 1 / 24 Page 61 / 1094

 A 1D network is comprised of links (or channels/paths/conduits) and nodes. Water volumes are
associated to nodes, and velocities/flows/conveyance are associated with the links. Velocities are
cross-section average velocities, i.e. flux (or flow) divided by the effective flow area. Nodes have
known storage geometries, from which water elevation can be calculated from the nodal water
volume. Links have known cross-sections (bed elevation and bed friction data discretised across
the section) or a shape (such as a circular pipe), from which flow area and conveyance can be
calculated from water levels and longitudinal slopes.

TUFLOW 1D (ESTRY) and EPA SWMM are included within the TUFLOW Classic and HPC
executable download as available 1D solution scheme options. Other third party 1D schemes are
also dynamically linked with TUFLOW Classic and HPC.

Strengths

The models generally have a very small number of computational elements (links and nodes),
and require little computational effort to run. Results usually take a matter of seconds or
minutes to generate. This allows for rapid iterative development, automated optimisation or
calibration, and large numbers of scenarios to be modelled.

1D models are naturally suited to pipe networks. There is little to no benefit in attempting to
model pipe networks in two or more dimensions.

Limitations

Significant effort is required to develop the input data required for 1d model domains. The
nodal area tables and path cross-sections must be defined for each element, meaning a
model of even 100 elements requires much effort to construct compared with 2D or 3D
domains.

1D models are not well suited for situations where surface channels break out onto
floodplains. While it is possible to define nodal area tables to allow for storage on floodplains,
along with links defining interconnecting flow paths, the model is reliant on the user having
correctly identified the topology of the flow network on the floodplain, a priori. The flow paths
in a flood model are also assumed to remain fixed or constant in terms of flow direction during
a flood event, which may not be the case.

1D models do not inherently compute energy loss mechanisms beyond bed friction. Energy
losses caused by turbulent interaction within a cross-section (tight bends, confluences,
spurs/dykes etc) must be manually accounted for with loss factors estimated by the user.

Energy loss caused by structures must be manually accounted for with loss factors or models
specified by the user.

The model does not capture inertial effects such as super-elevation, which in some situations
can change lateral flood levels by half a meter or more across a river bend.

Flow path velocities are cross-section averages. 1D schematisations are unable to represent
variations in velocity across the width of a cross-section, nor any depth dependent properties.

@124
3.2.2.2 Two Dimensional (2D)

Two dimensional (2D) models allow water to move in two lateral dimensions. A 2D model is
discretised into cells that have a defined geographic area, and faces which connect one cell to the
next. Cells are typically triangular (three sided) or quadrilateral (four sided) and are well suited to

Section 3 Hydraulic Modelling Fundamentals - 2 / 24 Page 62 / 1094

 modelling surface water such as flows in rivers/creeks, floodplain inundation, urban surface water,
and estuarine and coastal waters.

In the 2D modelling framework water volumes are associated with 2D cells, and velocities are
calculated at cell faces. Velocities are depth averaged. Cells have known storage geometries,
from which water elevation can be calculated from water volume. Faces have known cross-
sections (bed elevation and bed friction data discretised across the face), from which flow area
and conveyance can be calculated from water levels.

TUFLOW Classic and HPC are 2D solution schemes, and their models bare schematised using a
grid of square cells. They are not compatible with a flexible mesh design that constructs a network
of irregular shaped cells. Classic and HPC do allow different 2D cell sizes to be incorporated
within a single model, however, the cells are always square. HPC’s Sub-Grid Sampling (SGS)
feature significantly reduces the negative side effects of using a fixed grid of cells.

Strengths

2D models are generally much easier to construct than 1D models. Usually high quality digital
elevation data are available for the study area, and once the 2D grid extent is defined the
process of deriving the cell storage data and face conveyance data is fully automated.

Because velocity is resolved in both transverse and longitudinal dimensions, energy loss
mechanisms such as turbulent interaction within a cross-section (tight bends, confluences,
spurs/dykes, etc) are automatically accounted for with a turbulence (eddy viscosity) model.

Limitations

Accurate computation of flow along a primary flow path requires resolution of cross-sections
within the grid. For schemes that utilise a uniform grid, this requirement can cause the entire
model to have a large cell count and an associated computational burden.

Sub-cell energy losses caused by obstructions (e.g. bridge piers), flow expansion
(e.g. downstream of a vena-contracta), or in the third (vertical) dimension must be manually
accounted for with loss factors or models specified by the user.

Face velocities are depth averaged. The model is unable to represent variations in velocity (or
other properties) with depth.

@125
3.2.2.3 Three Dimensional (3D)

Three dimensional (3D) models calculate the water motion in all three spatial dimensions.
Computational Fluid Dynamics (CFD) is often used for 3D modelling of flow through complex
geometries. CFD software can be extremely computationally intensive, typically solving the full
unsteady non-hydrostatic Reynolds-averaged Navier-Stokes equations that describe the flow
physics.

Alternatively, the accelerations in vertical dimension can be assumed to be negligible compared to

the horizontal dimensions, also known as the hydrostatic assumption. Making this assumption
enables a pancake style 3D mesh to be used (i.e. high aspect ratio cells) with a split-operator
solution method. This 3D approach significantly improves solution speed compared to traditional
CFD. TUFLOW FV is an example of such a 3D model.

Section 3 Hydraulic Modelling Fundamentals - 3 / 24 Page 63 / 1094

 Similar to 2D, 3D models also use a network of cells and faces. Volume and velocity data are also
associated with cells, with complex numerical schemes available for interpolation between cell and
face data. 3D models make the fewest assumptions about water flow, and are therefore suited to
situations where there is significant variation of water velocity (or other properties such as
temperature and salinity) in all three dimensions. This is particularly relevant for estuarine and
ocean environments where density differences in the horizontal plane can affect the flow
behaviour.

TUFLOW Classic and HPC are not available in a 3D form. TUFLOW FV supports 3D simulation.

Strengths

Fewest assumptions or sub-models required from the user.

Depth dependent properties accounted for - particularly relevant for modelling flow around
bridge piers, complex culverts, tight river bends, estuaries and the coastal ocean.

Limitations

Computational solve time can become long.

Not always practical for catchment wide studies.

@126
3.2.3 Coupled 1D-2D

TUFLOW allows hydraulic modelling projects to adopt a schematisation that couples 1D and 2D
within a single model, such that often:

1D is used for cross-drainage structures (e.g. culverts under an embankment) and

underground stormwater pipe networks. The 1D is coupled or dynamically linked to the 2D
domain, which represents the surface flows. An example of this configuration is shown in
Figure 3.1 . TUFLOW Wiki Tutorial Module 3 and Module 5 provide working demonstrations
of both configurations.

@127

Figure 3.1: 1D Pipe Network and Embankment Culvert Linked to 2D

1D is used for open channel modelling where the 2D resolution is too coarse to represent the
open channel shape. The 1D open channels are linked to a 2D domain covering the surface
inundation of adjacent floodplain areas. An example of this configuration is shown in Figure
3.2 . Refer to TUFLOW Wiki Tutorial Module 11 for a model demonstration.

@128

Section 3 Hydraulic Modelling Fundamentals - 4 / 24 Page 64 / 1094

 Figure 3.2: 1D Open Channel Linked to 2D
Despite the above, the advent of faster computers, GPU acceleration and Sub-Grid Sampling
(SGS) has seen open channels increasingly represented in the 2D domain in TUFLOW models.
The key drivers for this are:

Computing power increases, combined with TUFLOW HPC’s GPU acceleration, have enabled
models built today to be over 100 times larger than pre 2018 models (in terms of cell count).
The increased computing power means modellers can model at a finer resolution and over
larger areas with no simulation time penalties.
The development of HPC’s 2D Sub-Grid Sampling (see Section 3.3.3 ), which creates more
accurate storage curves for cells and flux area curves for faces, has vastly improved the
ability of a 2D model to reasonably predict the hydraulic conveyance of surface channels.
SGS is built into all of the TUFLOW Tutorials.
The development of HPC’s 2D quadtree grid refinement permits use of finer resolution 2D
cells in discrete regions (see Section 3.2.4 ), such as within the open channel areas.

Section 10 provides a detailed description of how to implement 1D-2D linking and exploit the
above within the TUFLOW suite of products.

@129
3.2.4 Quadtree Grid

By default TUFLOW Classic and HPC use a single 2D cell resolution over an entire model domain.
This type of configuration is referred to as a fixed grid configuration. To support 2D modelling at a
range of spatial resolutions (which is often a project requirement), TUFLOW HPC models can use
a quadtree grid or mesh. The quadtree grid refinement feature supports the recursive division of
square TUFLOW cells into four smaller square cells. Up to nine levels of cell size refinement are
permitted. All cells in all levels of refinement share a common orientation and the hydraulic
computations are a full 2D solution across the entire quadtree grid.

An example quadtree grid is presented in Figure 3.3 and detailed documentation is provided in
Sections 7.4.1 and 10.7.1 . TUFLOW Wiki Tutorial Module 7 provides a demonstration of this
model configuration feature.

@130

Section 3 Hydraulic Modelling Fundamentals - 5 / 24 Page 65 / 1094

 Figure 3.3: TUFLOW HPC Quadtree Grid (3 Level Refinement)

@131
3.3 Model Resolution (Discretisation)

@132
3.3.1 1D Networks

The veracity of a 1D model domain is primarily dependent on the resolution with which on ground
conditions are represented. The nature of this representation is typically a result of a balance
between required resolution and the commensurate manual setup effort, the latter of which can be
significant. Some approaches that can be used in establishing this balance include:

Carefully determining where and to what extent 1D networks are required in order to address
study goals, and
Combining multiple 1D channels or structures into single model elements where appropriate

@133
3.3.2 2D Cell Sizes

The 2D cell size defines the resolution of the 2D hydraulic calculations. As for 1D simulation, this
cell size needs to be sufficiently small so as to reproduce required hydraulic behaviours, but not
so small that simulation times are impractical. In order to assist with this cell size selection, Table
3.1 lists general recommendations for minimum cell count (size) relative to primary flow path
widths (e.g. creeks or streets), for different TUFLOW solvers.

Section 3 Hydraulic Modelling Fundamentals - 6 / 24 Page 66 / 1094

 @134 Table 3.1: Recommended 2D Cell Size

Minimum recommended
Sensitivity of results to flow path
Solver number of cells across flow
orientation
paths

TUFLOW
4-6 Low
Classic

TUFLOW HPC
6-8 Medium
without SGS

Very Low (assumes terrain data is a

TUFLOW HPC
3-4 finer resolution by a factor of 2 or
with SGS
more)

Resolution may vary from these recommendations if:

1. 1D is used for primary flow path definition and 2D only for floodplains: 2D cell size can
increase.
2. Using HPC’s SGS feature (refer Sections 3.3.3 and 7.4.3 ): 2D cell size can increase.
3. Using HPC’s Quadtree feature: 2D cell size can increase outside areas of interest.
4. Small cells are contained within deep water flow paths. These settings will slow down models
considerably and should be avoided through use of SGS.

More broadly, cell size result convergence sensitivity testing (see Section 3.3.4 ) is the most
robust way to verify 2D cell size selection. It should be completed early in the model development
process.

@135
3.3.3 Sub-Grid Sampling (SGS)

Without SGS, TUFLOW samples an underlying DTM only at cell centres and faces when assigning
bathymetry to a computational grid. Cells and faces are then effectively flat-bottomed storage
boxes and conveyance channels, respectively. This approach therefore discards any higher spatial
resolution DTM data that may have been available. As an example, Figure 3.4 presents a 20m
hydraulic model grid, overlaying a 1m DTM. In this case only 2 to 3 grid cells span the river
channel, and fewer in some of the floodplain channels and road embankments. As such, the sub-
grid (sub-cell) scale topography available in the DTM is underutilised and a poor representation of
bathymetry is likely. Traditional solutions to this problem would typically have involved specifying
smaller cell sizes, at considerable computational penalty.

@136

Section 3 Hydraulic Modelling Fundamentals - 7 / 24 Page 67 / 1094

 Figure 3.4: 20m grid size shown against the 1m DTM
Rather than using a single elevation value for the grid cell storage calculations, Sub-Grid
Sampling (SGS) topography sampling extracts sub-grid data from an underlying DTM to develop a
non-linear relationship between water surface elevation and cell volume (i.e. storage capacity).
SGS also generates a non-linear relationship between water surface elevation and cell face area
and width (i.e. wetted perimeter) to improve the representation of fluxes and conveyance across
cell faces. As such, whilst the SGS approach still computes a single water level for each cell,
higher resolution terrain data than the grid cell size is utilised within the 2D hydraulic modelling,
which improves simulated results. The conceptual difference between traditional and SGS
topography sampling approaches is presented in Figure 3.5 .

@137

Figure 3.5: 2D Topography Sampling Concept and DEM Interpretation (Traditional vs SGS)

Section 3 Hydraulic Modelling Fundamentals - 8 / 24 Page 68 / 1094

 SGS is a feature of TUFLOW HPC - it is not available in TUFLOW Classic. If using TUFLOW HPC,
SGS is recommended when the available DTM data is finer than the model resolution. SGS is
discussed further in Section 7.4.3 .

@138
3.3.3.1 Benefits of SGS

Benchmarking has shown the benefits to be substantial for at least the following situations:

Catchment scale models flow much more effectively with water not being “trapped” by a
coarse cell resolution, and, importantly, excellent cell size convergence (i.e. demonstrating
that by reducing the cell size(s) the model results do not demonstrably change) at much
coarser cell sizes. Figure 3.6 shows the flow hydrographs for a Quadtree direct rainfall whole
of catchment model using two base cell size resolutions. The Hi-Res Quadtree grid has a
base cell size half that of the Lo-Res grid. The grey and yellow hydrographs show results from
models without SGS enabled and their marked difference in peak flow, shape and timing
demonstrate significantly different results between the two resolutions, and therefore a cell
size convergence test failure and the need for further refinement of the cell sizes (and much
longer run times). In contrast, the blue and orange hydrographs are from the same model,
however with SGS turned on and show very similar results between the two resolutions,
thereby demonstrating excellent cell size convergence and the ability to use the faster running
Lo-Res model for day-to-day modelling.

@139

Figure 3.6: Model Convergence with and without SGS

The sensitivity of results to mesh size is greatly reduced and the sensitivity to mesh
orientation is almost eliminated. With SGS a 2D regular mesh model can be rotated or have a
change in cell size without impacting the accuracy of the results compared with much greater
and sometimes unacceptable changes in results for the traditional elevation per cell approach
(Kitts et al., 2020 ).
Disturbed flow fields that can be apparent along a “saw-tooth” regular grid wet-dry boundary
completely disappear, with no spurious additional head losses generated and the results
consistent with a well-designed flexible mesh. This has major benefits in that open channels
can now be accurately modelled using TUFLOW HPC using coarse cell sizes at any
orientation to the channel, removing the need to utilise 1D open channels carved through the
2D domain. The images and charts below show benchmarking to a U-Bend flume test for
without SGS and with SGS. SGS causes a much smoother flow field to occur and importantly
the head drop around the bend is correctly modelled with SGS on. The red highlighted cells
indicate those cells that are partially wet with SGS on. The charts show the longitudinal profile

Section 3 Hydraulic Modelling Fundamentals - 9 / 24 Page 69 / 1094

 on the outside (orange), centre (blue) and inside (grey) of the bend with lines being modelled
and points measured – as shown, with SGS off the upstream water level is over predicted as
shown by the red circle.

@140

Figure 3.7: Longitudinal Profile without SGS

@141

Figure 3.8: Longitudinal Profile with SGS

In summary, utilising SGS means:

The storage and conveyance of the model is more accurately represented.

Cell Size Result Convergence, discussed in the following section, can typically be achieved
using a larger cell size when using SGS, compared to when not using SGS.
Faster simulation times.

Section 3 Hydraulic Modelling Fundamentals - 10 / 24 Page 70 / 1094

 @142
3.3.4 Cell Size Results Convergence

Solution convergence to cell size refers to the tendency for model simulation results to trend
towards a common answer as cell size decreases. This behaviour occurs due to the discretisation
of topographic features at a finer and finer resolution and should trend towards a closer and closer
reproduction of reality. Conversely, by using too coarse a cell size, the results can become
affected by the inaccuracies introduced by trying to emulate reality with a poor (i.e. coarse)
representation of the topography.

The practical test required to complete cell size convergence involves progressively reducing a
model’s cell resolution and comparing the results. The process aims to identify the largest cell size
possible to achieve a consistent simulation result (i.e. a simulation result that does not introduce
inaccuracies caused by using an excessively large cell size). Identifying this optimum cell size will
avoid the situation where an unnecessarily small cell size is chosen, which subsequently
translates to longer than necessary simulation times with no significant improvement in simulation
result. Figure 3.9 demonstrates this concept. The 40m cell resolution model produces a result at
the reporting location that is consistent with the finer cell sizes, whereas for larger cell sizes (60m
and higher) the results are not consistent demonstrating they are too coarse to accurately
reproduce the hydraulics. As the 40m resolution simulation time is significantly less than smaller
cell sizes, it represents the optimum cell size value to achieve reliable results in the shortest run
time.

@143

Figure 3.9: Cell Size Convergence Concept Example

The decision as to whether or not the model results are “converged” is subjective and will depend
on the purpose of the modelling and specifically what the “essential results” are. For some studies
they may be water surface elevation in a region of interest (e.g. a town), and for another study the
essential result may be the peak flow at a particular location. The exact approach taken to
establish cell size convergence is up to the user, but we present a selection of methods below that

Section 3 Hydraulic Modelling Fundamentals - 11 / 24 Page 71 / 1094

 may be useful. Whether one of the following methods are used, or another method, it is important
to document all testing and if necessary engage stakeholders in the decision-making making
process.

Comparing flood extent. This simple approach may be performed by overlaying 2D maps of
flood extent from sets of results calculated at different cell sizes. The user might start with a
relatively large cell size and then keep halving the cell size until the results become
acceptably similar. The 2nd to last (i.e. penultimate) cell size is then the one that may be
considered as sufficiently converged.
Comparing flow response. Another approach, well suited to highly transient models, is to
place flow lines across a primary path at important locations, and plot the flow as a function of
time for the different sets of results. Again the user may start with a large cell size and refine
until the results become acceptably similar.
Creating a result vs cell size plot. This method is more useful when there is a specific result of
interest (e.g. the peak water level at a particular location such as used in the example above).
With this method the result of interest is plotted as a function of cell size. This method allows
the user to estimate the error between the model result (at a given cell size) and their
estimate for the “perfectly converged” result. The largest cell size for which the error is within
some defined tolerance may then be considered sufficiently converged. If the resulting plot is
“noisy”, then this can indicate a possible error with the modelling setup (e.g. an embankment
not being resolved at larger cell sizes, or possibly a model instability). Note, this approach
may hide poor convergence elsewhere and is therefore rarely used unless multiple
sites are compared and convergence sought for all of them.
Histogram of variation. This approach involves comparing large lists of results (e.g. water
levels at say 100 or more locations) and generating a histogram of differences between the
results at the test cell size and the results at the finest feasible cell size. The user may then
define, for example, a criterion such that 95% of the results must be within +/- <some
tolerance> of the results from the finest feasible cell size. The user determines the largest cell
size that satisfies the criterion, and deems that as sufficiently converged.

SGS (see Section 3.3.3 ) has a significant beneficial impact on cell size convergence. In many
situations, a model using SGS may meet the required convergence criteria with a cell size that is
much larger than when SGS is not used (Huxley et al., 2022 ).

Finally, the cell size convergence testing maybe affected by the viscosity formulation (Section
7.2.4 ). In particular, the Smagorinsky viscosity formulation can cause results to be more
sensitive to cell size, and can allow the model results to diverge with decreasing cell size once the
cell face width becomes less than the depth. The Wu viscosity formation (default for TUFLOW
HPC) has proven to be superior to Smagorinsky in terms of reduced sensitivity to cell size and
convergence of results.

@144
3.4 Solution Accuracy

Solving the shallow water equations in one or two dimensions is necessarily an approximation and
therefore there are numerous solutions and different assumptions to be made. The following
sections discuss various forms of the shallow water equations. Of these, TUFLOW adopts the full
dynamic wave form in its 1D and 2D solutions. The full dynamic wave solution is the most
accurate option compared to the other mentioned alternative solution schemes.

Section 3 Hydraulic Modelling Fundamentals - 12 / 24 Page 72 / 1094

 @145
3.4.1 Fluid Flow Physical Terms

The equations solved by TUFLOW are:

Conservation of mass (also known as the continuity equation)

Conservation of momentum

These equations are presented and discussed in 1D and 2D forms in the subsections below.

@146
3.4.1.1 1D Continuity Equation

For water flow within a 1D channel the continuity equation per unit length is:

@147 ∂h ∂(Au)
w + = S(x)
∂t ∂x
(3.1)

rate + divergence = source

Where

w is the channel width at the water surface

h is the water depth in the channel
A is the cross-sectional flow area (up to the water surface)
u is the cross-sectional flow area averaged water velocity
S(x) is the lineal water source term (volume per unit time per unit length), usually lateral
inflow/outflow
x and t are channel flow dimension and time respectively

@156
3.4.1.2 1D Momentum Equation

For water flow within a 1D channel the momentum equation is as follows, noting the eddy viscosity
(diffusion of momentum or turbulence) term can not be included in the 1D form.
2

@157 ∂u
+
1 ∂(Auu)
+ g
∂(z+h)
+ g
n |u|
u = Su (x)
4
∂t A ∂x ∂x
R 3 (3.2)

rate + divergence + slope + friction = source

Where

z is the channel bed elevation

n is the Manning’s coefficient for bed friction (units time per cube-root(unit length))
R is the hydraulic radius
g is acceleration due to gravity
Su (x) is the lineal momentum source term (force per unit volume per unit fluid density),
typically used for local energy losses unable to be represented by the 1D form

Note the hydraulic radius R is normally considered to be cross-sectional flow area divided by
wetted perimeter, or A/P . However, in some software it may be specified as ‘resistance radius’,
which is just the water depth over the channel invert.

@166
3.4.1.3 2D Continuity Equation

For water flow over a 2D surface the continuity equation is:

Section 3 Hydraulic Modelling Fundamentals - 13 / 24 Page 73 / 1094

 @167 ∂h
+
∂(hu)
+
∂(hv)
= S(x, y)
∂t ∂x ∂y
(3.3)

rate + divergence + divergence = source

Where

h is the water depth in the 2D cell

u and v are the velocity components in the x and y spatial dimensions, respectively
S(x, y) is the total area water source term (volume per unit time per unit area), usually rain
and infiltration

@175
3.4.1.4 2D Momentum Equation

For water flow over a 2D surface the momentum equations, including eddy viscosity (diffusion of
momentum or turbulence) but omitting Coriolis acceleration Ω , are:
∂u

@177
∂u
∂(hνt ) ∂(hνt ) 2 2 2
∂(hu) ∂(huu) ∂(hvu) ∂x ∂y ∂(z+h) n √u +v
+ + − − + gh + gh 4
u
∂t ∂x ∂y ∂x ∂y ∂x
3
h

∂v ∂v
∂(hνt ) ∂(hνt ) 2 2 2
∂(hv) ∂(huv) ∂(hvv) ∂x ∂y ∂(z+h) n √u +v
+ + − − + gh + gh 4
v
∂t ∂x ∂y ∂x ∂y ∂y
3
h

rate + divergence − diffusion + slope + friction

Where

νt is the (kinematic) turbulent eddy viscosity

Su (x, y) and Sv (x, y) are the areal momentum source terms (force per unit area per unit fluid
density), used for local energy losses and atmospheric pressure gradient

@182
3.4.2 Forms of the Equations

Equations (3.1) and (3.2) are the 1D Dynamic Wave Equations, or Saint-Venant Equations.
They represent a system of equations that is effectively second order in both space and time, and
therefore admit travelling wave solutions (speed c = √gh ). Similarly Equations (3.3) and (3.4)
are the 2D Dynamic Wave Equations also known as the Shallow Water Equations (SWE).

As described in the following subsections, the Dynamic form of the equations can be simplified to
the Diffusive and Kinematic forms. However, given the available computing power today in
personal computers, there is no need or defence for calculating diffusive wave or kinematic wave
solutions except for very specific simplified situations. TUFLOW Classic and HPC are strictly
dynamic wave solvers, in both 1D and 2D forms. Therefore, TUFLOW does not experience the
inaccuracies and limitations associated with solving the diffusive wave or kinematic wave
equations.

@184
3.4.2.1 Diffusive Wave Equation

In the case of 1D, the two prognostic variables, depth h and velocity u co-evolve with time.
However, in days past when computers were far less powerful, the Dynamic Wave Equation
solution was computationally too much work to solve efficiently. At that time in history
mathematicians looked to simplify the problem. The first step was to assume that the velocity field
∂u
is a “slowing evolving steady state solution” (i.e. the time derivative ∂t
is considered small and

Section 3 Hydraulic Modelling Fundamentals - 14 / 24 Page 74 / 1094

 the velocity field is no longer independently evolved); it becomes a diagnostic field that is able to
be computed from the depth field. Further, by assuming that solution is “gentle” (i.e. the
∂(Auu)
divergence term 1
is also small), the velocity field can be defined as:
A ∂x

@189 R3 ∂(z + h)
|u|u = − (3.5)
2
n ∂x

Equation (3.1) , with the velocity field computed diagnostically from (3.5) is the 1D Diffusive
Wave Equation. The equation is second order in space but only first order in time, therefore it
does not admit travelling wave solutions, but solutions that diffuse while they advect, hence the
name. It requires less memory, less computational effort per timestep, and a larger timestep can
be used to progress forward in time compared to the dynamic wave solution.

In situations where the velocity field is gentle and slowly evolving, the Diffusive Wave solution is
almost correct. However, as the modeller cannot know in advance just how large the difference
between the diffusive and dynamic wave solutions might be, sensitivity testing by comparing
results using the two forms is recommended, or the Diffusive form is simply not used.

Diffusive wave solutions are also not shock capturing, and do not accurately predict the location of
hydraulic jumps. In 2D the diffusive wave solution is even more incorrect. As the divergence of
momentum in both x and y is neglected, the solution cannot estimate super-elevation.

For the reasons above, TUFLOW’s solvers do not offer a Diffusive Wave solution.

@193
3.4.2.2 Kinematic Wave Equation

From the diffusive wave equation solution, there are further simplifications that are possible and
sometimes used by other software. For shallow flows over steeper ground it is possible to assume
that ∂h/∂x << ∂z/∂x , in which case the velocity field becomes a function of depth and channel
bed slope, but not a function of ∂h/∂x . The equation then becomes first order in both space and
time:
2

@197 ∂h ∂(ABR 3 )
w + = S(x) (3.6)
∂t ∂x
1

1 ∣ ∂z ∣ 2 ∂z
B = ∣ ∣ sgn ( )
n ∣ ∂x ∣ ∂x

Equation (3.6) is the 1D Kinematic Wave Equation. It is a non-linear advection equation. It is

suitable for computing steady state flows (and slowly evolving steady state flows) in steep
channels or over steep terrain (i.e. water surface slope is much the same as bed slope), but is not
suitable for flows in low-lying channels/rivers.

For the reasons above, TUFLOW’s solvers also do not offer a Kinematic Wave solution.

@199
3.4.3 Numerical Accuracy

When computing the divergence and diffusion terms in a finite difference or finite volume scheme,
it is necessary to calculate the field values at spatial locations that are between the locations
where the field data are defined. For example, depth data is considered a node or cell property,
and is therefore nominally defined at a node (1D) or cell centre (2D). When calculating the flow

Section 3 Hydraulic Modelling Fundamentals - 15 / 24 Page 75 / 1094

 through a cross-section (1D) or a face (2D), the depth of water must be estimated at the cross-
section (or face), which is located between the nodes (or cells). This process is not straight
forward, the methods for doing so broadly fall into three categories:

Zeroth order interpolation: The field value used at the cross-section or a face is a constant
fixed value. This means that the error between the field value used and the “real” solution is
constant regardless of cell size - it is a function of cell size to the power of zero, hence the
term “zeroth order”. This method is generally not used.
@200

Figure 3.10: Example of zeroth order interpolation

First order interpolation: The field value used at the cross-section or a face is usually that of
the upwind (upstream) node or cell, but in rare cases can be that of the downwind
(downstream) node/cell. This means that the error between the field value used and the real
solution is proportional to the 1D element length or 2D cell size - it is a function of element
length or cell size to the power of one, hence the term “first order”. This method is
computationally simple and is very stable, but has the tendency to cause any sudden changes
(high spatial gradients) in solution to diffuse (smooth out) over time - the same effect as if the
model had a high diffusion rate applied. Therefore, the method introduces an artefact diffusion
that isn’t real. In the case of 2D and 3D modelling, any swirls or eddies in the velocity field
tend to decay (or simply do not form in the first place).

@201

Figure 3.11: Example of first order interpolation

Second order interpolation: The field value used at the cross-section or a face is usually
linearly interpolated between the upwind node/cell and the downwind one. This means that
the error between the field value used and the real solution is proportional to element length
or cell size squared - it is a function of cell size to the power of two, hence the term “second
order”. Pure linear interpolation on its own is known to be unstable - the solution tends to
develop oscillations in locations with high gradients. To prevent these, it is common to blend
between first and second order interpolation depending on the spatial gradients relative to the
grid/mesh size - this is known as rate limiting, or a Total Variation Diminishing (TVD) method.
When implemented correctly, the level of artefact numerical diffusion is very small, and swirls
and eddies in the velocity field (2D and 3D) form easily unless real diffusion (such as a
turbulence model) is explicitly added.
@202

Section 3 Hydraulic Modelling Fundamentals - 16 / 24 Page 76 / 1094

 Figure 3.12: Example of second order interpolation

TUFLOW Classic uses second order interpolation, and TUFLOW HPC defaults to second order
interpolation, but does offer the user the choice to switch to first order (see Solution Scheme ).
However, for the reasons above using a first order interpolation solution is not recommend.
Second order interpolation is significantly more accurate than first order, and this shows in cell-
size sensitivity testing. The TVD scheme implemented in TUFLOW HPC is very stable, and the
user should not need to change to first order interpolation in order to stabilise a model.

@203
3.5 Timestep

Appropriate computational timestep selection is critically important for the successful stable
simulation of a model. In hydraulic modelling the timestep represents the interval at which the
hydraulic calculations proceed forward in time. From a model design perspective it influences both
the simulation stability and overall runtime considerations.

Depending on the numerical construct and solution scheme there are critical control number
criterion that must not be exceeded to maintain solution stability. Additionally, the simulation run
time is directly proportional to the number of timesteps required to calculate model behaviour for
the simulation period. Selecting a timestep that is too large, exceeding the relevant control number
criterion, may cause computations to become unstable. Conversely, selecting a timestep that is
excessively small will unnecessarily slow a simulation down. The following sections provides
timestep selection guidance.

@204
3.5.1 Fixed versus Adaptive Timestepping

There are typically two approaches to how a model’s timestep is applied:

Fixed Timestepping: The timestep is determined and input as a fixed value by the user. For
TUFLOW modelling, this approach applies to TUFLOW Classic.
Adaptive Timestepping: The timestep is automatically determined by the solution scheme and
varies in value throughout the simulation depending on the hydraulic conditions at the time.
TUFLOW HPC uses adaptive timestepping.

Note: TUFLOW’s in-built 1D solutions, TUFLOW 1D (ESTRY) and EPA SWMM, use a variety of
fixed and adaptive timestepping, depending on the 2D solution it is linked to (TUFLOW Classic or
HPC).

Section 3 Hydraulic Modelling Fundamentals - 17 / 24 Page 77 / 1094

 @205
3.5.2 TUFLOW 1D (ESTRY) and EPA SWMM

TUFLOW 1D (ESTRY) and EPA SWMM both use an explicit solution scheme. For the 1D channels
using either of these solvers the stability criterion, expressed by the following wave celerity (3.7)
and courant number (3.8) equations, should not exceed 1.

@206 Δt√gh
Cc = (3.7)
Δx

@208 Δt ⋅ U
Cu = (3.8)
Δx

Where:

Cc = Wave celerity
Cu = Courant number
Δt = Timestep
Δx = Distance
g = Gravity
h = Water depth
U = Magnitude of velocity

The ESTRY Control File Timestep command is used to set the fixed TUFLOW 1D (ESTRY)
timestep, or when linked with HPC, the maximum 1D timestep.

The TUFLOW SWMM Control File SWMM Iterations command sets the EPA SWMM timestep
relative to the linked 2D solution timestep.

A fixed TUFLOW 1D (ESTRY) timestep is recommended for 1D/2D linked TUFLOW Classic
models. The timestep selected should not be greater than the minimum value for any channel
(except non-inertial channels such as bridges, culverts, etc.). Typical timestep values are 10 or 60
seconds for a model with a minimum channel length of 100 to 500 metres, down to 1 second for
1D network with small pipes. The occurrence of mass errors may indicate the use of too high a
timestep.

Tip: Where a few TUFLOW 1D (ESTRY) channels must be significantly shorter than the rest, it
may be economical to specify them as non-inertial channels. The timestep can then be chosen on
the requirements of the shortest remaining channel. Care should however be exercised when
specifying non-inertial channels to ensure that errors are not introduced by the non-inertial
representation, particularly if these channels are in a region of interest. Any approximations can
usually be assessed by a few selected runs without the non-inertial approximation and with the
necessary shorter timestep.

In 1D/2D linked TUFLOW Classic models a TUFLOW 1D (ESTRY) Timestep value that is smaller
and also equally divisible into the 2D Timestep is recommended. If the 1D timestep is not equally
divisible into the smallest 2D timestep, the 1D timestep is reduced automatically so that it meets
this criteria. For example, if the specified 2D timestep is 10 seconds and the 1D timestep is 3
seconds, the 1D timestep will be reduced to 2.5 seconds (this is reported in the simulation log file).

A fixed timestep is also required as the model input for 1D/2D linked TUFLOW HPC models,
though functionally during simulation, timestep adjustment is applied to enable synchronised
communication between TUFLOW 1D (ESTRY) and TUFLOW HPC’s adaptive timestep. In this

Section 3 Hydraulic Modelling Fundamentals - 18 / 24 Page 78 / 1094

 situation the TUFLOW 1D (ESTRY) Timestep represents a “Maximum 1D Timestep”. The
timestep synchronisation is shown Figure 3.13 , and functions as follows:

If the Target TUFLOW HPC 2D Timestep is less than the Maximum TUFLOW 1D (ESTRY)
Timestep: The 2D timestep is reduced below the target value to be an integer division of the
maximum TUFLOW 1D (ESTRY) timestep. For example, if the HPC target 2D timestep is 0.7
s, and the ESTRY/SWMM maximum 1D timestep is 1.0 s, then HPC will use 0.5 s for its
timestep and run two steps within ESTRY’s single step.
If the Target TUFLOW HPC 2D Timestep is greater than the Maximum TUFLOW 1D (ESTRY)
Timestep: the 1D timestep is reduced to an even integer division of the target 2D timestep.
For example, if the HPC target 2D timestep is 2.1 s, and the ESTRY/SWMM 1D maximum
timestep is 1.0 s, then ESTRY will use 0.7 s for its timestep and run three steps to HPC’s
single step.

@217

Figure 3.13: TUFLOW HPC 1D/2D Timestep Synchronisation

@218
3.5.3 TUFLOW Classic 2D

TUFLOW Classic is a 2D implicit scheme. It can generally maintain a stable solution for a Courant
Number (equation (3.9) ) less than 10. For real-world applications a value of 5 or less is however
more common (Syme, 1991 ).

@219 Δt√2gH
Cr = (3.9)
Δx

Where:

Δt = Timestep (s)
Δx = Length of model element (m)
1

g = Acceleration due to gravity (ms− ) 2

H = Depth of water (m)

As a general rule for 2D TUFLOW Classic models, the Timestep (in seconds) is typically in the
range of to of the cell size (in metres). For example, for a 10m model the timestep will typical
1 1

2 5

be in the range 2 to 5 seconds. For steep gradient models with high Froude numbers and
supercritical flow, smaller timesteps may be required.

Section 3 Hydraulic Modelling Fundamentals - 19 / 24 Page 79 / 1094

 If a model is operating at high Courant numbers (>10), sensitivity testing with smaller timesteps to
demonstrate no measurable change in result is recommended. The occurrence of high 2D mass
error can be an indicator that the 2D timestep is too high.

Tip: If during initial model development a model becomes unstable, it is strongly advised to not
simply reduce the timestep. Instead establish why the model is unstable and if the cause relates to
poor model design or one of the model input error (e.g topography, boundary conditions, initial
water level, 1D/2D linking etc.). If it is, correct that first before considering lowering the timestep.
Doing so will create a healthy model that can operate at a higher timestep, and subsequently run
faster. Section 16.4 includes guidance focused on resolving model instabilities.

@228
3.5.4 TUFLOW HPC 2D

TUFLOW HPC is a 2D explicit scheme. It uses adaptive timestepping to progress through a

simulation. The timestep is automatically dynamically adjusted during a simulation so the
numerical solution complies with three mathematical stability criteria, shown in Table 3.2 .

@229 Table 3.2: HPC 2D Adaptive Timestep Controlling Numbers

Control Expression and Control Limit

Description
Number Maximum

This condition ensures that water

entering one side of a 2D cell does not
Courant pass through the other side within one
|υ|Δt |ν|Δt
Number timestep. For this to be satisfied, the max( , ) = 1.0
Δx Δy
(Nu) product of the water velocity (υ, ν ) and
model timestep (Δt) must be less than
the cell size (Δx, Δy ).

This numerical condition relates to the

shallow water wave celerity (wave
speed) and is derived from the fluid flow
Shallow equations to represent long waves
Wave (i.e. wave length is substantially longer
√2ghΔt √2ghΔt
Celerity than the water depth). The product of max( , ) = 1.0
Δx Δy
Number the model timestep (Δt) and the long
(Nc) wave speed (square root of the gravity (
g ) and water depth(h)) must be less
than the cell size (Δx, Δy ), for the
condition to be satisfied.

This numerical condition relates to the

sub-grid scale eddy viscosity term
which causes diffusion of momentum.
Diffusion
To maintain stability the product of the vτ Δt vτ Δt
Number max( , ) = 0.3
eddy viscosity coefficient (vτ ) and the Δx
2
Δy
2

(Nd)
timestep (Δt) divided by the square of
the grid spacing (Δx, Δy ) must remain
below 0.3.

Section 3 Hydraulic Modelling Fundamentals - 20 / 24 Page 80 / 1094

 TUFLOW HPC will use the highest timestep possible without exceeding the limits associated with
each of the above control numbers. The method TUFLOW HPC uses to calculate a timestep and
achieve unconditional stability is as follows:

A TUFLOW Control File (TCF) Timestep command is required. It is however only used for
the first calculation timestep. The specified value should be consistent with what would be
1 1
appropriate for a TUFLOW Classic model (i.e. 2
to 5
the 2D cell size in metric units).
Internally, TUFLOW HPC divides this value by 10 to apply a value that is suitable for an
explicit solution scheme. All subsequent calculations are completed using the adaptive
timestep approach outlined in the following bullet points.
The HPC timestep is calculated using the hydraulic conditions from the end of the previous
timestep.
If the hydraulic conditions have changed significantly it is possible for one or more of the Nu,
Nc, Nd control number criteria to be violated at one or more locations within the model. For
example, a sudden change in rainfall from one timestep to the next (which occurs with
stepped rainfall boundaries) would potentially cause this. The HPC solver, by default, treats a
20% exceedance of a control number as a violation and will implement a repeat timestep
feature in this situation in order to maintain unconditional stability. Should a control number
anywhere within the model be exceeded by more than 20%, the solution reverts to the
complete hydraulic solution from the previous (good) timestep, then the timestep is reduced
and next calculation repeated.
Each timestep is also tested for the occurrence of NaNs. A NaN is “Not a Number” and occurs
due to undefined mathematical calculations such as a divide by zero or square root of a
negative number. The occurrence of a NaN is also indicative of a sudden instability. Should a
NaN occur, the repeat timestep feature is implemented.
Should a timestep need to be repeated more than ten times consecutively, the solution stops.
The simulation will also stop if the default minimum permissible timestep of 0.1 seconds has
been reached. This value can be manually adjusted using Timestep Minimum . Repeated
timesteps are displayed to the Console Window and the number of them for a time interval
are provided in the nRS_NaNs and nRS_HCNs columns in the _HPC.csv file output in the
results folder. They are also reported to the _messages layer.

Internally, HPC multiplies the Nu, Nc, Nd control number limits by a dynamic control factor. This
factor starts at 1.0 at the beginning of a simulation, and normally will stay at 1.0, unless a repeat
timestep occurs. If a repeat timestep occurs, this factor is reduced to 90% of its previous value,
thereby decreasing all of the control number limits. The dynamic factor very slowly increases
again with each good timestep, up to a maximum value of 1.0. HPC offers two methods, via the
HPC Timestep Approach command, for the calculation of whether a “high control number” event
has occurred. ‘Method A’ considers that a high control number step has occurred if any of Nu, Nc,
Nd has exceeded the dynamic control number limits (i.e. after the dynamic control factor has been
applied) by the 20% margin. Whereas ‘Method B’ (introduced in the 2025 release and set as the
new default) applies the test using the original static limits (i.e. before the dynamic control factor
has been applied). Method B is more tolerant in models that have rapid wetting and drying.

Repeated timesteps may be an indication the solution is numerically “on-the-edge”. Models that
have a high number of repeated timesteps should be sensitivity tested by reducing the control
number limits using Control Number Factor . For example, repeat the simulation using Control

Section 3 Hydraulic Modelling Fundamentals - 21 / 24 Page 81 / 1094

 Number Factor == 0.8 and compare the results. If there are acceptably immeasurable
changes in the results, then running at the default control number limits can be considered
satisfactory.

Tip: Reviewing the TUFLOW HPC minimum timestep output is a useful way to assess HPC model
health. Models that reduce to an excessively small 2D timestep in order to remain stable may be
symptomatic of an unhealthy model. Identifying what the limiting control number is that is causing
the timestep requirement can provide clues to the model feature to review for errors. For example:

Celerity Control (Nc) number relates to water depth relative to cell size. Energy can pass
through deeper water faster than shallow water, as such deep water will trigger this control.
Review whether the water depth is realistic, or the result of an error in the model topography.
Courant number (Nu) relates to velocity relative to the cell size. High velocities will trigger this
as the control. Investigate whether the feature causing the high velocity is realistic.
Diffusion control (Nd) relates diffusion of momentum relating to the sub grid viscosity. Small
cells in deep water will trigger this one. Models controlled by the diffusion number tend to
require a timestep significantly smaller than those controlled by the shallow wave celerity or
courant numbers. If a model is predominantly diffusion controlled it may be that equivalent
solution accuracy can be achieved by selecting a larger cell size. This is worth testing, as it
will most likely increase the simulation speed with no loss of result fidelity.

Section 16.4 includes guidance focused on reviewing model health and resolving issues.

@255
3.5.4.1 Timestep Efficiency Output

A timestep efficiency result is output for HPC simulations, reported to the console window, HPC
log file (.hpc.tlf) and the timestep history file (.dt.csv). A value of 100% indicates that the HPC
timesteps are perfectly aligned with the minimum stability timestep for complying with the three
control numbers listed in Table 3.2 . Factors that reduce the timestepping efficiency can be:

Lower initial timestep than required. This will be evident by low values at the start, then
steadily increasing towards 100% as the timestep approaches the optimum value – see
example further below.
Synchronisation with a 1D scheme. The 1D/2D linking with TUFLOW’s 1D solver (ESTRY) is
designed to synchronise exactly using the larger of the 1D or 2D timesteps. For external 1D
schemes, the timestepping is similarly synchronised, with some external 1D schemes also
offering an unsynchronised option. In all cases, the HPC 2D timestepping will be below
optimum by varying degrees, with the inefficiency shown in the timestepping efficiency output.
Frequent map or time-series output. The HPC timestepping is configured to align exactly with
map and time-series output intervals, therefore, timesteps nearly always need to be reduced
as an output interval is approached. These reduced timesteps can be found in the “dt” column
of the hpc.dt.csv file. The ideal timestep without the output interval reductions is reported in
the “dtStar” column.

For example, in the output window below, the efficiency is initially poor (~40%) due to the initial
timestep in the model being too low, however the efficiency rapidly increases as the HPC timestep
increases.

Section 3 Hydraulic Modelling Fundamentals - 22 / 24 Page 82 / 1094

 Note: Should a model exhibit low overall timestepping efficiency (i.e. values less than around 70 to
90%), please let us know via [email protected], and attach the .tlf, .hpc.tlf and dt.csv files.

@256
3.6 Simulation Times

The simulation time of a model is dependent on several factors including:

The area to be modelled

The cell size of the model
The number of cells that are wet
The duration of the simulation
The solution scheme (TUFLOW Classic or TUFLOW HPC)
Computer Hardware (CPU or GPU)

Each of the factors listed above should be considered during the development of a model.

A simple spreadsheet has been created to estimate TUFLOW Classic simulation times based on
the cell size, catchment area and model run time (i.e. event duration). The spreadsheet can be
downloaded from the TUFLOW Wiki. This spreadsheet is a basic guide, as it has several
simplified assumptions, including the timestep, number of calculations per second the computer
can run and fraction of wet cells (this will change throughout the simulation). Acknowledging these
assumptions, it is still a useful guide. further consideration of the model design is recommended if
the spreadsheet is estimating excessively long simulation times.

The speed at which TUFLOW simulations will run is dependent on the hardware used. Newer and
higher CPU frequency computers will run faster than older lower CPU frequency computers. A
hardware benchmark model is available from the TUFLOW Wiki. This page also contains the
simulation times for the same model on a large range of computers and GPU devices.

TUFLOW Hardware Benchmark CPU Results

TUFLOW Hardware Benchmark GPU Results

There are several other secondary factors that can affect the speed performance of TUFLOW
simulations, including:

Section 3 Hydraulic Modelling Fundamentals - 23 / 24 Page 83 / 1094

 The latency to the location where results are being written. For fastest speed, write results
directly to a local computer hard drive. Lower latency associated with writing to an external
hard drive can slow a simulation down significantly.
How frequently output is written, with more frequent output slowing the simulation.
The output format(s) selected. XMDF and DAT formats are quicker to write than grid raster
output types (TIF, FLT and ASC). Use XMDF format for temporal Map Output. Reserve grid
raster output formats for maximum results.
Whether the single or double precision version of TUFLOW is used - the single precision
version will be faster. This is discussed in Section 13.4.2 .

These factors are typically less significant than the primary factors listed at the start of this section
(model size, cell count etc.).

As outlined in Section 12 , the GPU Module may be utilised to increase simulation speed using
TUFLOW HPC. The speed up ratio compared to CPU varies depending on model particulars and
the hardware used. Nevertheless, the typical range in performance increase experienced using
current technology (at the time of writing) is a 10x to 50x increase in simulation speed.

References

@258
@257
Babister, M., & Barton, C. (2012). Two Dimensional Modelling in Urban and Rural Floodplains
Stage 1 & 2 Report.
https://arr.ga.gov.au/__data/assets/pdf_file/0019/40573/ARR_Project15_TwoDimensional_Mod
elling_DraftReport.pdf

@259 (2009). Integrated Urban Drainage Modelling Guide. CIWEM.

CIWEM.

@260
Environment Agency. (2010). The Fluvial Design Guide. Environment Agency.

@261 C., Syme, W., Ryan, P., & Collecutt, G. (2022). Hydraulic Modelling 2D Cell Size Result
Huxley,
Convergence – Comparing the Performance of Different Shallow Water Equation Solution
Schemes. Hydrology and Water Resources Symposium, Engineers Australia.
https://www.tuflow.com/media/7555/2022-hydraulic-modelling-2d-cell-size-result-convergence-
huxley-et-al-hwrs.pdf

@262D., Syme, W., Gao, S., Collecutt, G., & Ryan, P. (2020). Mesh Orientation and Cell Size
Kitts,
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

@263 W. (1991). Dynamically Linked Two Dimensional / One-Dimensional Hydrodynamic

Syme,
Modelling Program for Rivers, Estuaries and Coastal Waters (W. Syme, Ed.) [M.Eng.Sc(100%
Research) Thesis]. Dept of Civil Engineering. https://tuflow.com/media/4982/1991-tuflow-
dynamically-linked-2d-and-1d-hydrodynamic-modelling-syme-thesis.pdf

Section 3 Hydraulic Modelling Fundamentals - 24 / 24 Page 84 / 1094

 @268

@269
Section 4 Control Files and Input Layers

@270
4.1 Introduction

This chapter discusses TUFLOW model inputs, which include the TUFLOW Control Files (text-
based, easy to script, input files) and GIS layers (.shp, .gpkg or .mif formatted files). The different
control files will be discussed along with how different objects within the GIS layers are treated by
TUFLOW.

@271
4.2 Control Files

The TUFLOW Control files are text files containing a series of commands (instructions) that
control how a model is constructed and how a simulation proceeds. They are easily scripted and
interpreted, typically short in length, and very powerful for enabling efficient workflows.

This overview chapter discusses:

Rules and notation in regards to control files (Section 4.2.1 ),

Absolute and relative file paths (Section 4.2.2 ),
The available units (e.g. Metric or Imperial) (Section 4.2.3 ), and
The control files (Section 4.2.4 to Section 4.2.16 ).

Table 4.1 lists the available control files, provides a brief description and a link to the respective
section of this Chapter that discusses the individual control file.

Section 4 Control Files and Input Layers - 1 / 19 Page 85 / 1094

 @272 Table 4.1: List of Available Control Files

Control
Description Section
File

The TUFLOW Control File (.tcf) file sets simulation parameters and
directs input from other data sources. It is the top of the tree, with all Section
TCF
input files accessed via the .tcf file or files referred to from the .tcf 4.2.4
file. Each TUFLOW simulation must have a .tcf file.

The ESTRY Control File (.ecf) includes all of the 1D files and
Section
ECF commands. 1D commands can also be embedded into the .tcf file
4.2.5
should the modeller prefer.

The TUFLOW BoundaryControl File (.tbc) includes commands Section

TBC
related to internal and external boundaries and linking of 1D/2D. 4.2.6

The TUFLOW GeometryControl File (.tgc) includes commands and Section

TGC
geometric / topographic data inputs to build the 2D domain. 4.2.7

The Quadtree Control File (.qcf) includes the commands required to Section
QCF
build a quadtree mesh. 4.2.8

The TUFLOW Event File (.tef) includes a database of .tcf and/or .ecf Section
TEF
commands related to specific events. 4.2.9

The TUFLOW Operational Control File (.toc) includes operating rules

Section
TOC that can be applied to hydraulic structures, pumps and other
4.2.10
controllable devices modelled as 1D elements.

The TUFLOW Rainfall Control File (.trfc) includes commands to Section

TRFC
generate rainfall grids based on point rainfall gauges. 4.2.11

The TUFLOW External Stress File (.tesf) includes commands to

Section
TESF define time varying global or spatially varying external forces such as
4.2.12
wind or wave radiation stresses.

The Advection Dispersion Control File (.adcf) includes the Section

ADCF
commands required for AD model execution. 4.2.13

The TUFLOW SWMM Control File contains the relevant commands Section
TSCF
needed to manage the SWMM simulation. 4.2.14

A TUFLOW Read File is a file included inside another file. Any file
extension be used, with .trd traditionally used for 2D commands and
Read .erd for 1D. Read files are useful for commands that are common to Section
File multiple simulations or for commands that are rarely or never 4.2.15
changed and can be placed into another file to reduce the size of the
parent file. Up to 9 levels of read files can be nested.

Override Files allow the user to apply .tcf commands after TUFLOW
Override Section
has finished processing the commands which are referenced within
File 4.2.16
the .tcf file.

Section 4 Control Files and Input Layers - 2 / 19 Page 86 / 1094

 @273
4.2.1 Rules and Notation

Control files, such as the TUFLOW Control File (TCF), TUFLOW Boundary Control (TBC) and
TUFLOW Geometry Control (TGC), are command or keyword driven text or script files. The
commands are entered free form, based on the rules described below. Comments may be entered
at any line or after a command. The commands are listed in Appendix A to Appendix I .

Note: TUFLOW control files and commands are NOT case sensitive.

An example of a command is:

Start Time == 10 ! Simulation starts at 10:00am on 2/9/1962

This command sets the simulation start time to 10 hours. The text to the right of the “!” is treated
as a comment and not used by TUFLOW when interpreting the line.

Automatic colour coding (as shown in the above example) of files for easy interpretation is
available, with download links and installation instructions, for the following text editors:
Notepad++, UltraEdit and TextPad.

Commands can be repeated as often as needed. This offers significant flexibility and effectiveness
when modelling, particularly in building 1D and 2D model topography. Note that a repeat
occurrence of a command may override the effect of previous occurrence(s) of the same
command.

The style of input is flexible bar a few rules. The rules are:

A few characters are reserved for special purposes as described in Table 4.2 ;
Command syntax is not case sensitive;
Only one command can occur on a single line; and
A few commands rely on another command being previously specified. These are
documented where appropriate.

Additional text can be placed before and/or after a command. For example, a line containing the
command Start Time to set the start time of a simulation to 10 hours can be written as:

Start Time == 10, or

Start Time (h) == 10

The (h) text is not a requirement but is useful to indicate that the units are hours. Alternatively, the
following would also be acceptable, noting the use of the comment delimiter “!”:

Start Time == 10 ! hours

Blank lines are ignored. Spaces or indentations can occur at the start of the line. This is
recommended when using the logic control, as outlined in Section 13.3 . The second line in the
following example is not required to be indented, however, it is strongly recommended to facilitate
easy interpretation:

If Scenario == GPU
GPU Solver == ON
End If

The notation used to document commands and valid parameter values in Appendix A to Appendix
I are presented in Table 4.3 .

Section 4 Control Files and Input Layers - 3 / 19 Page 87 / 1094

 @274 Table 4.2: Reserved Characters – Text Files

Reserved
Description
Character(s)

A “#” or “!” causes the rest of the line from that point on to be ignored.
“#” or “!” Useful for “commenting-out” unwanted commands, and for all that
modelling documentation.

A “==” following a command indicates the start of the parameter(s) for the
command. Where there is more than one parameter, the parameter values
are read as free-field formatted, i.e. are space or comma delimited.

When processing command line syntax within the control files (.tcf, .tgc,
==
.ecf etc.), if a “==” is not present in the command line syntax TUFLOW will
produce an ERROR 0060.

For example “If Scenario = Exg” will produce an error as the correct
syntax is “If Scenario == Exg”.

@275 Table 4.3: Notation Used in Command Documentation – Text Files

Documentation
Description
Notation

Greater than and less than symbols are used to indicate a variable
<…> parameter. For example, the commonly used <file> example is
described below.

A filename (can include an absolute or relative path, or a UNC path).

<file>
See Section 4.2.2 for a more detailed description.

The square brackets “[” and “]” surround parameter options.

The “|” symbol separates the options.

The “{” and “}” brackets indicate the default option. This option is
applied if the command is not used.

[ {Op1} | Op2 ] For example, the options for the Maximums and Minimums command
are:

[ ON | {ON MAXIMUMS ONLY} | OFF ]

Where the default is ON MAXIMUMS ONLY (which stores the

maximums, but not the minimums).

Spaces can occur in commands and parameter options. If a space

occurs in a command, it is only one (1) space, not two or more spaces
in succession.

spaces Spaces can occur in file and path names; however, third party software
may not allow this and as such is not recommended. If using spaces in
filenames, batch files will require that the filename is enclosed in
quotes.

Section 4 Control Files and Input Layers - 4 / 19 Page 88 / 1094

 @276
4.2.2 File Paths

TUFLOW control files reference additional files, for example GIS files. The three methods that can
be used are absolute file path, relative file path and UNC file path referencing. A model can use
any or all these methods. However, relative file paths are typically preferred.

Note: Depending on the operating system, file paths may be case sensitive.

Take an example of reading a GIS layer containing initial water levels, the command is Read GIS
IWL == <filepath>. The following are all valid:

Absolute file path: Read GIS IWL == L:\2d_IWL_001_R.shp

Relative file path: Read GIS IWL == ..\2d_IWL_001_R.shp
UNC file path: Read GIS IWL == \server1\2d_IWL_001_R.shp

For the relative file path, the path is relative to the file that is referring to it. In the case above, if
the command occurred in the .tcf file, which is in the TUFLOW\runs\ folder, the ..\ indicates to go
up one level (from TUFLOW\runs\ to TUFLOW\ the model\ navigates into the TUFLOW\model\
folder, gis\ navigates from TUFLOW\model\ into TUFLOW\model\gis\). To go up more than one
level simply use ..\ multiple times (e.g. ..\..\ would navigate up two folders). If the file sits under the
same folder, then the filename can be specified. In the below example the Model_Events.tef would
need to sit in the same location as the .tcf.

Event File == Model_Events.tef

The paths are relative to the current control file, a command in the geometry control file
(TUFLOW\model\) would be relative to the .tgc location, not the .tcf location.

Using relative file paths has the advantage that the model can be moved or provided to another
user and the control files do not need to be updated, if the model uses an absolute or UNC file
path, all references will need to be updated if the model is moved.

Some large files may still use an absolute or UNC file path particularly where large datasets are
shared across models. This avoids the need to copy the dataset into multiple projects. An example
is:

Read GIS IWL == \\server1_Coast_5m.flt

If using LINUX at any point during the modelling tasks or pre/post processing, it is recommended
to set Use Forward Slash == ON.

@277
4.2.3 Units

The default unit settings for all inputs in a TUFLOW model are metric, however, it is possible to
create models using US Customary units (also known as Imperial or English units) by specifying
the .tcf command Units == US Customary. “Imperial” or “English” are also accepted and
are treated identically.

This manual uses the metric term for documentation purposes. If your model uses US Customary
Units any user defined values must also be specified in US Customary units. The metric unit and
the equivalent US Customary unit are listed in Table 4.4 , unless otherwise stated within this
Manual. Model units can be checked by searching for the relevant parameter in the .tlf file (refer to
Section 14.4 ).

Section 4 Control Files and Input Layers - 5 / 19 Page 89 / 1094

 Output units are listed in Table 11.4 .

@278 Table 4.4: Model Units - Inputs

Metric US Customary

m ft

mm inches

km2 miles2

kg pound

@279
4.2.4 TCF

The TUFLOW Control File (.tcf) file sets simulation parameters and directs input from other data
sources. It is the top of the tree, with all input files accessed via the .tcf file or files referred to from
the .tcf file. Each TUFLOW simulation must have a .tcf file. An example of a simple .tcf file is
shown in Figure 4.1 .

The .tcf file must reference the following items as a minimum requirement (TUFLOW won’t run
without them):

Geometry Control File (Section 4.2.7 )

BC Control File (Section 4.2.6 )
Start Time
End Time
Map Output Interval

Recommended or most commonly used .tcf commands are:

Read Materials File

BC Database
Solution Scheme
ESTRY Control File (Section 4.2.5 )
Quadtree Control File (Section 4.2.8 )
SHP Projection /GPKG Projection /MI Projection
Timestep
Output Folder
Map Output Data Types
Time Series Output Interval
Write Check Files and
Write Empty GIS Files .

Commonly used or useful .tcf commands are: BC Event Name ; BC Event Text ; Event File ,
Read File , Cell Wet/Dry Depth ; Instability Water Level ; Read GIS FC ; Read GIS IWL ;
Read GIS PO ; Screen/Log Display Interval ; Set IWL ; Start Map Output ;
Start Time Series Output .

@280

Section 4 Control Files and Input Layers - 6 / 19 Page 90 / 1094

 Figure 4.1: Example of a Simple TCF
Appendix A lists and describes .tcf commands and their parameters.

Note that it is possible to incorporate 1D (.ecf) commands into the .tcf file. 1D (.ecf) commands
can be included in the .tcf file between Start 1D Domain and End 1D Domain block(s). For the
.tef file, 1D (.ecf) commands must be prefixed by “1D”. Also note that ESTRY Control File
command is recognised every time if specified more than once.

@281
4.2.5 ECF

Commands specific to TUFLOW (ESTRY) 1D domains are detailed in Appendix B , and can be
placed either in the .tcf file (or in a Read File ), or in their own file traditionally called an .ecf file.
1D commands can be located:

Within an .ecf file and referenced within the .tcf file using the command ESTRY Control File .
The command ESTRY Control File Auto can be used to force the .ecf file to have the same
name as the .tcf file.
Placed within a 1D domain block in the .tcf using Start 1D Domain and End 1D Domain
commands.
Placed anywhere in the .tcf file and preceded by “1D”, for example, 1D Manhole Default Type
. “1D” must be the first two characters.
Any combination of the above, however, it is strongly recommended in the interests of
manageability that a logical approach be adopted (that agrees with your colleagues!).

The .ecf file method is typically used if the 1D domain is large and complex, whereas the 1D
domain block or preceding “1D” may be used where the 1D/2D linked model requires only a few
1D commands or they are placed in another file and referenced using Read File .

The 1D commands set simulation parameters and directs input from other data sources for all 1D
domains. An example of some 1D commands are shown in Figure 4.2 .

@282

Figure 4.2: Example of a Simple ECF

Appendix B lists and describes the 1D commands and their parameters. Commands that are only
relevant for 1D only models are indicated with a “1D Only” underneath the command in Appendix
B .

Section 4 Control Files and Input Layers - 7 / 19 Page 91 / 1094

 Note: At present it is not an option to truly have a 1D only model. For 1D only models, a
single 2D model, which can be made up of a single inactive 2D cell, is still required.

@283
4.2.6 TBC

The .tbc file or TUFLOW Boundary Conditions Control File (TBC) contains information regarding
the location and type of boundaries within the model. These include (but are not limited to)
upstream and downstream boundaries as well as 1D/2D or 2D/2D links. The GIS layers read into
the .tbc file reference the Boundary Condition (BC) Database (see Section 8.6 ). The BC
Database associates the GIS layers with a boundary condition such as a hydrograph or a depth-
discharge curve.

Only one .tbc file per 2D domain can be specified in the .tcf file using the BC Control File
command. A .tbc file must be specified, if no external boundaries are to be applied a blank file may
be specified. This is rarely done but can be used for models based only on initial water levels.

Appendix D lists and describes .tbc commands and their parameters.

@284
4.2.7 TGC

2D domains are defined through a series of commands contained in TUFLOW Geometry Control
(.tgc) files. The .tgc file contains, or accesses from other files, information on the size and
orientation of the grid, grid cell codes (whether cells are active or inactive), bed/ground elevations,
bed material type or flow resistance value, and optional data such as soil type.

A 2D domain is automatically generated as a grid of square cells. Each cell is given characteristics
relating to the topography such as ground/bathymetry elevation, bed resistance value and initial
water level, etc.

A .tgc file is specified in the .tcf file using Geometry Control File . For a TUFLOW Classic Multiple
2D Domain model, a separate .tgc file is required for each of the 2D domains, see Section 10.7.2
.

Rather than contain all the 2D grid information in one file, the .tgc file is a series of commands that
builds the model. The commands are applied in sequential order; therefore, it is possible to
override previous information with new data to modify the model in selected areas. This is
extremely useful where a base dataset exists, over which areas need to be modified to represent
other scenarios such as a proposed development. This eliminates or minimises data duplication.

The commands can occur in any order (as long as it is a logical one).

If an unrecognisable command occurs, TUFLOW stops and displays the unrecognisable text.

Notes & Tips:

1. Commands can be repeated any number of times.

2. Commands are executed in the order they occur. If the data for a 2D cell or Zpt is supplied
more than once, the last data that is read is used (i.e. the latter data for a cell overrides any
previous data for that cell).
3. Each data layer does not have to cover the entire model – only the 2D cells influenced by the
objects in the layer (e.g. a 3D breakline) are affected.

Section 4 Control Files and Input Layers - 8 / 19 Page 92 / 1094

 4. Use Write Check Files commands to cross-check and carry out quality control checks on the
final 2D grid, elevations, material or land-use categories, etc.

@285

Figure 4.3: Example of a Simple TGC

Appendix C lists and describes .tgc commands and their parameters. An example of a .tgc file is
shown in Figure 4.3 .

@286
4.2.8 QCF

For a quadtree grid, the Quadtree Control File (.qcf) is used to define the grid refinement areas
and optionally the model location and extent, see Section7.4.1 . A .qcf file is specified in the .tcf
file using the Quadtree Control File command.

For a quadtree grid, only one .tgc file can be specified that covers all the 2D cell resolutions. The
.qcf file primarily controls the nesting levels of different 2D cell resolutions, but may also control
the overall grid orientation and location instead of the .tgc file. An example of setting up a model to
use a quadtree grid is provided in TUFLOW Tutorial Module 7.

Appendix H lists and describes .qcf commands and their parameters.

@287
4.2.9 TEF

The TUFLOW Events File (.tef) contains a database of .tcf and .ecf file commands for different
events. A .tef file is specified in the .tcf file using the Event File command. Events are set up
using a define event block, for example:

Define Event
BC Event Source == ~AEP~ | 05p
End Define

Event management is a powerful functionality that allows running multiple event combinations
(e.g. magnitude, duration, temporal patterns, climate change) using a single set of control files
rather than creating a new set of control files for every simulation. This makes the management of
the model easier, ensures consistency between the simulations, and better quality control. An
example of the number of .tcf and bc_database files required for a model with and without event
management is shown in Figure 4.4 .

@288

Section 4 Control Files and Input Layers - 9 / 19 Page 93 / 1094

 Figure 4.4: Reduction of Control Files using Event Management
Event management is detailed in Section 13.3.1 . An example of setting up a model to use event
management is provided in TUFLOW Tutorial Module 9.

@289
4.2.10 TOC

The TUFLOW Operations Control (.toc) contains operating rules for structures. A .toc file is
specified in the .ecf file using the Read Operating Controls File command, or in the .tcf file within
a Start 1D Domain block. Operational Channels are detailed in Section 5.10 . An example of its
use is provided in TUFLOW Tutorial Module 10 Part 3.

Appendix E lists and describes .toc commands and their parameters.

@290
4.2.11 TRFC

The TUFLOW Rainfall Control File (.trfc) contains commands used to generate rainfall grids based
on point rainfall gauges. This approach generates a series of rainfall grids available to the user for
display or checking. A .trfc file is specified in the .tcf using the Rainfall Control File command. An
example of its use is provided in TUFLOW Tutorial Module 6 Part 3.

Appendix F lists and describes .trfc commands and their parameters.

@291
4.2.12 TESF

The External Stress File (.tesf) allows the definition of time varying global or spatially varying
external forcing such as wind or wave radiation stresses. A .tesf file is specified in the .tcf using
the External Stress File command. External stress boundaries are discussed in Section 8.8 .

Appendix G lists and describes .tesf commands and their parameters.

@292
4.2.13 ADCF

The TUFLOW Advection Dispersion Control File contains commands related to the TUFLOW
Advection Dispersion (AD) Module for simulating depth-averaged, constituent fate and transport.
The .adcf is specified in the .tcf using the AD Control File command. The Advection Dispersion
module is discussed in Chapter 9 .

Appendix J lists and describes .adcf commands and their parameters.

Section 4 Control Files and Input Layers - 10 / 19 Page 94 / 1094

 @293
4.2.14 TSCF

TUFLOW 2D domains can be dynamically linked to SWMM’s 1D solution scheme. The TUFLOW
SWMM Control File (.tscf) contains the SWMM input commands. The .tscf file is specified in the
.tcf using the SWMM Control File command. Section 10.4 provides information on linking to the
1D scheme, and examples are given in the TUFLOW SWMM Tutorials.

Appendix I lists and describes .tscf commands and their parameters.

@294
4.2.15 Read File

The Read File command is extremely useful for placing commands that remain unchanged or are
common for a group of simulations in another file (e.g. the SHP Projection command will be the
same for all runs within the same study area). This reduces the size/clutter of .tcf files and allows
easy global changes to a group of simulations to be made.

The file extensions most commonly used are .trd (2D commands), .erd (ESTRY 1D commands)
and .rdf.

@295
4.2.16 Override Files

These optional override files allow the user to apply .tcf commands after TUFLOW has finished
processing the commands referenced within the .tcf file. This can be useful where you wish to
change a parameter for all simulations that are started from a common folder. For example, you
could turn off check files, or change the output drive.

Two override file types are possible, one which is computer specific and one which is processed
by all computers. If either or both are present, they are processed after all the .tcf file commands
have been processed so that the override commands prevail.

The first override file that TUFLOW checks for is named “_TUFLOW_Override.tcf”. If this file exists
within the same folder as the .tcf file, .tcf commands that are listed within the
“_TUFLOW_Override.tcf” file overwrite the commands in the .tcf file.

The second one TUFLOW looks for must be named “_TUFLOW_Override_<computer_name>.tcf”,

where <computer_name> is the name of the computer running the simulation. If this file exists
TUFLOW will process any commands within it after any commands from the
“_TUFLOW_Override.tcf” file (if it exists). If you are unsure of your computer name, this is
displayed in the computer’s properties or in a TUFLOW Log File (.tlf) that has been processed on
that computer, this is typically at the top of the .tlf (line 6). For example:

Computer Name: COMP1234

With the computer name above the computer specific override file would be named
“_TUFLOW_Override_COMP1234.tcf”.

An override file specific to a particular computer can be particularly useful where, for example,
different output drives or results folders, are to be used for runs using different computers. This will
allow you to run TUFLOW simulations on different computers without having to change the .tcf file.

Section 4 Control Files and Input Layers - 11 / 19 Page 95 / 1094

 For example, if a run is started on one machine that only has a C drive, output can be directed to
the C drive just for that computer by using the command Output Drive == C.

Another example is if using the GPU solver and one machine only has a single GPU, while
another has four GPUs. The command GPU Device IDs == 0, 1, 2, 3 can be specified in
the override file specific to the machine with four GPUs.

Nearly all .tcf commands can be placed within the override files except for “Read GIS” and some
other similar commands that involve processing of data layers. It is recommended that the
override files are only used for global changes to settings, similar to the examples above.

@296
4.3 Databases

Databases are organised collections of structured data in comma delimited (.csv) or text based
formats that can be read into TUFLOW Control files. Table 4.1 lists the available databases,
provides a brief description and a link to the respective section that discusses the specific
database.

@297 Table 4.5: List of Available Databases

Database Description Section

The boundary condition (BC) database can be in either .csv (comma

delimited) format, or HEC-DSS (see Section 8.6.5 ). It must contain
Section
bc_dbase a row with the pre-defined keywords ‘Name’ and ‘Source’, as listed
8.6
in Table 8.13 . Other keywords control how data is extracted from
the source.

The materials database can be in either a text based format (.tmf) or

comma delimited format (.csv). It contains the Manning’s n value
Section
materials and other information for different materials (e.g. land-uses). The
7.3.6.3
format of the materials .tmf file is described in Table 7.11 . The
format of the materials .csv file is described in Table 7.10 .

For pit channels specified as a Q Type, the flow through the pit is
controlled by a depth-discharge curve defined within the Pit Inlet
Section
pit_dbase Database . The database file sources depth-discharge curves in
5.11.3
other .csv files. The format of the Pit Inlet Database is described in
Table 5.26 .

Soils infiltration is applied to the model by defining a soils (.tsoilf) file

which is read into the .tcf using the command Read Soils File . An
integer ID to each soil, define the infiltration method followed by the
Section
soils soil parameters as the remaining values. Table 7.13 presents the
7.3.7.2
parameters of the .tsoilf file available for TUFLOW Classic, the
additional options available for TUFLOW HPC are presented in
Table 7.21 .

Section 4 Control Files and Input Layers - 12 / 19 Page 96 / 1094

 @298
4.4 Input Layers

@299
4.4.1 Input Formats

The main types of GIS Inputs are vectors, rasters and TINs. The following formats are supported
as inputs in TUFLOW:

GIS vector data layers: GeoPackage (.gpkg) (recommended), Shapefile (.shp) and MapInfo
(.mif) (default) formats.
GIS raster data layers: GeoTIFF (.tif) (recommended & default), GeoPackage (.gpkg), Float
(.flt) and ASCII (.asc) formats. NetCDF formats are supported for some inputs such as time-
varying rainfall grids.
GIS TIN data layers: Land XML (.xml), 12d tin (.12da) formats (including super TINs) and
SMS (.tin).

Most mainstream CAD/GIS platforms recognise these formats.

The format of input layers is solely controlled by the file extension. For example, for the vector
formats, “.gpkg” for the GPKG format database (noting that no extension is used for a layer within
a database), “.shp” for the SHP format and “.mif” for the MIF format. Prior to the 2023-03 release,
if no file extension was specified TUFLOW assumed the input layer was in .mif format. To support
the new GeoPackage format (the recommended vector format), TUFLOW will produce ERROR
0631 for inputs with no extension.

TUFLOW requires that all GIS layers imported or exported by TUFLOW must be in the same
geographic projection. The model projection is initialised using the GPKG Projection , SHP
Projection and MI Projection commands. Multiple input formats can be used (e.g. a mix of all
format types within one model is allowed). If a model uses a mixture of format types as inputs, a
projection command should be specified for each format.

The default output format for GIS check layers and GIS outputs depends on the Projection setting
as mentioned above. If more than one Projection setting is specified, or to force the GIS output
format, use the GIS Format command. The GeoPackage format is that recommended due to
superior file/data management storage, data compression, and far greater viewing and querying
speeds.

The default raster format is the GeoTIFF (.tif) format. Although a check is not done on the
projection of .tif inputs, a projection can be assigned to .tif output rasters using the TIF Projection
command.

@300
4.4.2 GIS Commands

Commands containing “GIS” read and/or write a GIS vector layer. GIS commands read the
geometry, attribute data, and projection data of the input layer. The available formats of input
vector and raster layers are listed in Section 4.4.1 . The geographic location of objects for GIS
commands is important as the geographic position of the object controls the part of the TUFLOW
model they affect.

When digitising objects, it is preferable that they do not snap to the 2D cell sides or corners as this
may produce indeterminate effects.

Section 4 Control Files and Input Layers - 13 / 19 Page 97 / 1094

 @301
4.4.2.1 GIS Attribute Interpretation

TUFLOW expects certain attributes, in a specific order for input layers. For example an initial
water level layer (2d_iwl) layer only requires a single attribute (which is the initial water level
value), whilst a 1d channel layer (1d_nwk) has a number of attributes including channel type,
channel roughness, upstream and downstream elevation. The attributes required for each input
layer are detailed in their respective sections throughout this manual. Any additional attributes
appended to the layer will be ignored by TUFLOW (with the exception of the 1d_nwk layer as
TUFLOW will treat it as a 1d_nwke layer).

The .tcf command Write Empty GIS Files can be used to automate the creation of template files
with attribute structures that TUFLOW expects and with the recommended GIS data naming
convention. They also can be automatically created using the TUFLOW Plugin Import Empty Tool.

A list of the TUFLOW template files is available on the TUFLOW Wiki.

The names of GIS attributes as documented or produced by Write Empty GIS Files may change
from previous TUFLOW releases to reflect new features and changes. The name of the attribute is
irrelevant as far as TUFLOW is concerned as TUFLOW only requires that attributes are in the
correct order and of the correct type (i.e. Character, Float, Integer, etc.). In all TUFLOW layers, the
attributes can be named as the modeller wishes, so older layers that do not have the same
attribute names as documented in this manual will still work correctly.

@302
4.4.2.2 GIS Object Interpretation

Table 4.6 and Table 4.7 outline the compatible GIS objects and how they are interpreted by
TUFLOW.

Object snapping is often used to relate point data with line and region data, for example with the
Read GIS Z Shape or Read GIS BC command. TUFLOW supports point, end and vertex
snapping. It does not support edge snapping. Objects that are linked (for example a 2d_bc “SX”
type region and 2d_bc “CN” type line layer), must be snapped and also read in to TUFLOW on the
same command line separated by a vertical bar “|”. For example:

Read GIS BC == 2d_bc_culvert_R.shp | 2d_bc_culvert_L.shp

Section 4 Control Files and Input Layers - 14 / 19 Page 98 / 1094

 @303 Table 4.6: TUFLOW Interpretation of Supported GIS Objects

Object Type TUFLOW Interpretation

Refers to the 2D cell that the point falls within or a 1D object such as a node
Point or boundary location. Points snapped to the sides or corners of a 2D cell
may give uncertain outcomes as to which cell the point refers to.

Variety of uses including defining a continuous line of 2D cells, 1D channels,

Line (straight
to connect objects, alignment of a 3D breakline, linking 1D and 2D
line)
elements.

Pline
(line with one
As for Line above.
or more
segments)

For 2D cells either:

Modifies any 2D cell or cell mid-side/corner (e.g. Zpt) that falls within
the region. If the command is modifying a whole 2D cell, it uses the
cell’s centre to determine whether the cell falls inside or outside of the
region. If the cell’s centre, mid-side or corner lies exactly on the region
perimeter, uncertain outcomes may occur. Holes within a region are
Region accepted except for polygon objects in shape layers used for TIN
(polygon) boundaries.
Or, only uses the region’s centroid. Examples are the original flow
constriction layers (2d_fc) and time-series output locations for some
output data types.

For 1D:
1D nodes within the region are selected. If the 1D node falls exactly on the
region perimeter uncertain outcomes may occur.

Multiple In later versions of TUFLOW, multiple point, line and region objects are
(Combined) generally accepted (ERROR or WARNING messages are given if not the
Objects case).

Section 4 Control Files and Input Layers - 15 / 19 Page 99 / 1094

 @304 Table 4.7: TUFLOW Interpretation of Unsupported GIS Objects

Object Type TUFLOW Interpretation

Arc Ignored (do not use).

Collections Not supported. Collections are groups of objects of differing type.

Ellipse Ignored (do not use).

These objects are ignored and most commonly occur when a line of
attribute data is added that is not associated with an object. In MapInfo,
none
this occurs when a line of data is added directly to a Browser Window
(i.e. no object was digitised).

Roundrect
(Rounded Ignored (do not use).
Rectangle)

Rect (Rectangle) Ignored (do not use).

Text Ignored.

@305
4.4.3 GeoPackage Commands

GeoPackage is a widely supported, open format, built upon an SQLite database (this is stored as
a single file with the extension .gpkg). The benefits of GeoPackage compared to the MapInfo
(MIF/MID) and ESRI/QGIS Shapefile formats include:

More than one layer can be stored in a single file. For example, all model inputs can be stored
in a single GeoPackage database.
It supports spatial indexing, making it much faster to work with in GIS packages.
Significantly faster write speed from TUFLOW compared to the Shapefile format.

For tips on using GeoPackages, see the GeoPackage Tips TUFLOW Wiki page. Additionally, the
TUFLOW Tutorials are set up using the GeoPackage format and can be used as an introduction to
using GeoPackages.

@306
4.4.3.1 GPKG Input Commands

Since a GeoPackage database can have more than one layer, when reading data into TUFLOW, a
GeoPackage file and table may both need to be specified. There are a variety of different options
available. The following are possible:

1. To specify a table in a .gpkg directly use “>>”:

Read GIS Z Shape == gis\2d_zsh.gpkg >> 2d_zsh_L

2. If a .gpkg file path is only specified, with no table reference, it will be assumed that the table
name is the same as the .gpkg database name. For example, the following two commands
are equivalent to one another:

Read GIS Z Shape == gis\2d_zsh_L.gpkg

Read GIS Z Shape == gis\2d_zsh_L.gpkg >> 2d_zsh_L

Section 4 Control Files and Input Layers - 16 / 19 Page 100 / 1094

 3. To specify more than one table in a database in the same command line use “&&”. This is
similar to “|” however there is no need to reference the database multiple times:

Read GIS Z Shape == gis\2d_zsh.gpkg >> 2d_zsh_L && 2d_zsh_P

“&&” can be used in conjunction with “|”:
Read GIS Z Shape == gis\2d_zsh_R.gpkg | gis\2d_zsh.gpkg >> 2d_zsh_L &&
2d_zsh_P

4. Use the command “USE ALL” with “>>” to tell TUFLOW to use all tables in the database:

Read GIS Z Shape == gis\2d_zsh.gpkg >> USE ALL

5. Use the Spatial Database command to specify a database to use for subsequent table
inputs. This command can be used multiple times in a control file to change the target .gpkg
file. For example:

Spatial Database == gis\2d_EXG.gpkg

Read GIS Z Shape == 2d_zsh_R | 2d_zsh_L | 2d_zsh_P
Read GIS Mat == 2d_mat_R
Spatial Database == gis\2d_DEV.gpkg
Read GIS Mat == 2d_mat_R

Spatial Database can be used in the .tcf, .ecf, .tbc, .tgc, .qcf, .tef. Commands are localised to
their relevant control file with the exception of the .tcf which acts as a global command. If local
spatial database are specified, they will take precedence over the global .tcf spatial database.
The spatial database can be turned off or reverted to the .tcf database with the same
command. Turning the spatial database off is a global command even when used in a control
file other than the .tcf.

Spatial Database == OFF | TCF

Prior to TUFLOW’s implementation of GeoPackage, if a file reference did not have an

extension listed in the TUFLOW command syntax it was assumed the file was a MapInfo “mif”
format. That rule no longer applies. If there is an open spatial database TUFLOW will not
append “.mif” to the end of the table name.

@307
4.4.3.2 GPKG Output Commands

The GIS outputs from TUFLOW can be set to GPKG by using the following command:

GIS Format == GPKG

Outputs can be written into separate databases or grouped:

Spatial Database Output == SEPARATE | {GROUPED}

Grouped databases will group by output folder location. Separate databases will still group
geometries together e.g., PLOT_P, PLOT_L, PLOT_R will be written to one database.

Section 4 Control Files and Input Layers - 17 / 19 Page 101 / 1094

 @308
4.4.4 Grid Commands

Commands containing “Grid” read and/or write a GIS raster layer. The format is controlled by the
file extension (e.g. .tif, .gpkg, .flt or .asc). The available formats of input raster layers are listed in
Section 4.4.1 .

For real (float) inputs the value is interpolated from the grid. For integer inputs (such as Code), the
value applied is the integer value of the grid cell that the TUFLOW point falls within.

The Read Grid Zpts command permits a second argument to specify a GIS layer containing one
or more polygons to clip the area of Zpts to be inspected. Elevations will only be assigned to Zpts
lying inside polygons within the GIS layer. See Section 7.3.5.1 for more details.

@309
4.4.5 TIN Commands

Commands containing “TIN” (triangulation file) read and/or write a TIN file. The format is controlled
by the file extension (e.g. .tin, .xml or .12da). From the 2020-10-AB release, TUFLOW also
supports super TINs in the .12da format. The same syntax is used for “TIN” layers as “GRID”.

TUFLOW can also be used to create a TIN (see Create TIN Zpts ).

The Read TIN Zpts command permits a second argument, specifying a GIS layer containing one
or more polygons to clip the area of Zpts to be inspected. Elevations will only be assigned to Zpts
lying inside polygons within the GIS layer. See Section 7.3.5.1 for more details.

@310
4.4.6 RowCol Commands (Legacy)

Commands containing “RowCol” or “MID” (e.g. Read RowCol Zpts ) only read the attribute data
file (i.e. .mid or .dbf file). This is a legacy feature and is not recommended for use. The row and
column numbering in the TUFLOW model will change if the model cell size, orientation or origin
change, this feature is therefore not supported when using quadtree grids or the GeoPackage
format.

For details on this legacy feature see Section 4.9.2 of the 2018 TUFLOW Manual.

@311
4.5 Layering Data

One of TUFLOW’s most powerful features is the ability to layer and prioritise data layers of the
same data type. This means that TUFLOW constructs the model from the data layers with no need
to copy or duplicate input data for the thousands of simulations that may ensue. Data layering has
considerable benefits in terms of quality control and workflow efficiencies. Section 4.2.7 further
details data layering.

@312
4.6 XF Files

XF Files are a binary echo of selected input files automatically created by TUFLOW to vastly
speed up the model initialisation process next time a simulation is carried out. If the original input
data has a save date later than its corresponding XF file, the original data is read and the XF file

Section 4 Control Files and Input Layers - 18 / 19 Page 102 / 1094

 re-created. If the XF file is newer, it is used in preference to the original data.

XF files are always written to a folder named “xf” underneath where the original data resides. If the
“xf” folder or a XF file is deleted, the XF files will be recreated next time a simulation is started.
The name of the XF file generated is that of the source file plus additional info. Two extensions are
used: .xf4 and .xf8. .xf4 refers to iSP (single precision) runs and .xf8 to iDP (double precision)
runs. It is not possible to mix these (i.e. to read an .xf4 single precision file into a double precision
model).

To globally switch XF files off use XF Files == OFF. They can also be switched off for
individual inputs using “XF OFF” in the command (for example, see Read GIS Z Shape ).

For the various commands that generate XF files (e.g. Read Grid Zpts , it is possible to refer
directly to the .xf file instead of referring to the GIS layer, for example:

Read Grid Zpts == ..\2d_zpt_DTM.dbf.xf4.

If different models utilise the same DEM(s), the DEM .xf file is reprocessed each time a different
model is run. This can slow the model initialisation. To prevent this, the .tcf command XF Files
Include in Filename adds unique text to the end of the .xf filenames for each model.

For example, if two models use the same DEMs for setting Zpt values, use this command as per
below.

In Model 1’s .tcf file:

XF Files Include in Filename == M1

In Model 2’s .tcf file:

XF Files Include in Filename == M2

If the same .tcf file is being used to run both models, use the scenario name as follows.

XF Files Include in Filename == <<~s1~>>

TUFLOW will add the ~s1~ value to the end of any .xf filenames (refer to Section 13.3.2 on the
automatic setting of scenarios and events as variables). Thus, when ~s1~ changes from one
simulation to the next, the .xf filenames are unique to that scenario and will not need reprocessing.

Section 4 Control Files and Input Layers - 19 / 19 Page 103 / 1094

 @318

@319
Section 5 1D Network Domains - ESTRY

@320
5.1 Introduction

This chapter of the Manual discusses features specifically related to the construction of 1D
domains or networks. 2D domain features are discussed separately in Chapter 7 and 1D/2D
linking is discussed in Chapter 10 . Customising output from 1D domains is discussed in Section
11 and viewing 1D output is discussed in Chapter 15 .

@321
5.2 Schematisation

1D domains are made up of a network of channels and nodes, shown in Figure 5.1 , where:

Channels represent the conveyance of the flow paths. The channels are flow and velocity
computation points in the 1D model. Channels could refer to 1D open channels, where the
flow and velocity are calculated based on the 1D unsteady St Venant fluid flow equations (see
Section 5.6 ); and 1D structures (such as pipes, culverts, bridges, weirs, gates, etc.), where
the flow and velocity are computed based on empirical flow equations (see Section 5.8 ).
Nodes represent the junctions of channels and the storage capacity of the network (see
Section 5.13 ). These are water level computation points in the 1D solution.

@322

Figure 5.1: 1D Channels, Structures and Nodes

Both channels and nodes are created using one or more GIS layers (primarily using the generic
1d_nwk layer, but other speciality layers can be used such as 1d_pit for inlets and 1d_mh for
manholes). There are no constraints on the complexity of the network with any number of
channels being able to connect to a single node. Each channel is connected to two nodes; one at
the channel’s upstream end the other at its downstream end. The digitising of nodes is
optional. In most models these are automatically created.

Section 5 1D Network Domains - ESTRY - 1 / 130 Page 104 / 1094

 Multiple GIS layers can be specified. Subsequent layers are used to modify the network at
individual objects. For example, if a culvert is to be upgraded in size, rather than making a copy of
the whole 1d_nwk layer, select the culvert channel, save the culvert as another 1d_nwk layer and
modify the channel to represent the upgraded culvert. Use Read GIS Network twice to first read
in the base 1d_nwk layer, then the 1d_nwk layer with the single channel representing the
upgraded culvert. Provided the channel has the same ID and is snapped to the same nodes, it will
override the original culvert channel. Using this approach minimises data duplication and, if
executed logically and in a well-documented manner, is a very effective approach to modelling.

The attributes required in the 1d_nwk layer depend on the channel or node type. Table 5.1 and
Table 5.29 present the available channel and node types respectively. Section 5.4 presents links
to all tables of attributes within the 1d_nwk layer for all channel and node types.

If using more than 100,000 channels see Maximum 1D Channels .

@323
5.3 Solution Scheme

The scheme for modelling 1D open channels is based on a numerical solution of the 1D unsteady
St Venant fluid flow equations (momentum and continuity) including the inertia terms. The 1D
solution uses an explicit finite difference, second-order, Runge-Kutta solution technique (Morrison
& Smith, 1978 ) for the 1D SWE of continuity and momentum as given by the equations below.
The equations contain the essential terms for modelling periodic long waves in estuaries and
rivers, that is: wave propagation; advection of momentum (inertia terms) and bed friction
(Manning’s equation).

1D Continuity:

@324 ∂h ∂(Au)
w + = S (5.1)
∂t ∂x

1D Momentum:

2
@326 ∂u 1 ∂(Auu) ∂(z + h) n |u| 1
+ + g + g 4
u = Su − k|u|u (5.2)
∂t A ∂x ∂x 2
R3

Where

w is the channel width at the water surface

h is the water depth in the channel
x and t are channel flow dimension and time respectively
z is the channel bed elevation
A is the cross-sectional flow area (up to the water surface)
u is the cross-sectional flow area averaged water velocity
n is the Manning coefficient for bed friction (units time per cube-root(unit length))
R is the hydraulic radius
S is the lineal water source term (volume per unit time per unit length), usually lateral
inflow/outflow
Su is the lineal momentum source term (force per unit volume per unit fluid density)
k is an energy loss coefficient, used for local energy losses

Section 5 1D Network Domains - ESTRY - 2 / 130 Page 105 / 1094

 Note: For 1D structures, velocities are computed based on empirical equations instead of using
the 1D momentum equation (see Section 5.8 for more details). Also note that as bed-friction and
energy losses are explicitly stated, the additional momemtum source Su is typically not used.

@341
5.4 1d_nwk Attributes

The 1d_nwk tables have been provided as individual tables for each type of channel and node.
Links to these tables are provided below.

Open Channels (S, G, Blank) 1d_nwk Attributes

Culverts and Pipes (C, I, R) 1d_nwk Attributes

Bridges (B, BB) 1d_nwk Attributes

Arch Bridges (BArch) 1d_nwk Attributes

Weirs (W, W*) 1d_nwk Attributes

Special Channels (M, P, Q, SG, SP) 1d_nwk Attributes

Dam Failure and Piping Channels (DF, PF) 1d_nwk Attributes

Nodes 1d_nwk Attributes

Pits 1d_nwk Attributes

1d_nwke (Extended 1d_nwk) Attributes

The names of 1d_nwk attributes may have changed from previous TUFLOW releases to reflect
new features and changes. The name of the attribute is irrelevant as far as TUFLOW is
concerned, as TUFLOW only requires that attributes (of any layer) are in the correct order and of
the correct type (i.e. Character, Float, Integer, etc.). In all TUFLOW layers, the attributes can be
named as the modeller wishes, so older layers that do not have the same attribute names as
documented in this manual will still work correctly.

@342
5.5 Channels Overview

1d_nwk channels can represent open channels, hydraulic structures such as bridges,
culverts/pipes, weirs, and operational structures (e.g. pumps and gates), and other flow controls
such as a user defined flow matrix.

A channel is digitised as a line. To connect channels the ends of the channels must be snapped.
Channel flow direction is positive in the direction the line is digitised. This is best visualised in the
GIS using a line style that has arrows or other symbolism indicating the line direction.

A channel is defined by a length, a Manning’s n value, a table of hydraulic properties (wetted

perimeter, flow area, hydraulic radius) versus elevation and other parameters depending on the
type of channel. Table 5.1 below lists the available channel types and Table 5.2 lists the
additional options that may be appended to selected channel types.

Section 5 1D Network Domains - ESTRY - 3 / 130 Page 106 / 1094

 The hydraulic properties table for channels can be defined at a cross section positioned midway
along the channel (for some structures and open channels) or can be derived from cross-sections
located at the channel ends (for open channels only). The exceptions are:

For culverts (C and R types) the attribute information supplied within a 1d_nwk layer
(i.e. diameter, width, etc.) is sufficient to define the hydraulic properties (i.e. no cross-section
properties table is required).
For weirs (W), if no cross-section or hydraulic properties table is specified, and a
Diameter_or_Width attribute value greater than 0.01 is specified, the weir is defined as being
a rectangular section 10 metres high based on the invert and width values.

Tables of cross-section profiles, cross-section hydraulic properties and bridge loss coefficients are
accessed using links within 1d_xs and 1d_bg GIS layers. Tables can also be used to define nodal
surface areas (refer to Section 5.13.2.1 ). This allows these data to be entered in a comma
delimited format using .csv files that can be managed and edited in spreadsheet software such as
Microsoft Excel.

Modellers often keep the different data sets separate as numerous .csv files are often needed.
Separate folders underneath the model folder (same level as the gis folder) are often used to store
all the .csv files and the GIS layer. For example:

1d_xs for XZ cross-section profiles in a model\xs folder

1d_bg for bridge loss coefficient tables in a model\bg folder

The Read GIS Table Links command is used for linking tabular data to channels. The method for
linking cross-sectional and bridge losses is as follows:

Lines are linked to channels. The method depends on whether the object has two or more
vertices. The logic is:
For lines with two points (the start and end – no intermediate vertices) the line only needs
to cross a channel – it does not have to snap to a vertex on the channel line. If the two-
point line crosses more than one channel, the channel that is closest to the mid-point of
the line is selected.
Lines with three or more vertices must have one of the vertices snap to a vertice on the
channel line. If both types are specified, the snapped sections are given preference over
any two-point line that crosses the channel line.
Other objects (regions and points) are not used.

The attributes and the method for determining the data to extract from the source file is outlined in
Table 5.4 for 1d_xs and Table 5.11 for 1d_bg. Using the Column_1 attribute, several tables can
be located in the one source file if desired.

Section 5 1D Network Domains - ESTRY - 4 / 130 Page 107 / 1094

 @343 Table 5.1: 1D Channel (Line) Types

Channel/Node Type Description

Open Channels

Open channel that incorporates all flow regimes. Supercedes

Normal (Blank) and Gradient (G) channels, as S channels
switch into upstream controlled, friction only mode (i.e. no
inertia terms) for higher Froude numbers (see Froude Check).
This allows steep flow regimes such as super-critical flow to be
represented. See also Froude Depth Adjustment.

Open Channel S This is the preferred open channel type as it incorporates all
flow regimes, therefore, use this channel in preference to
Normal (Blank) and G channels.

Upstream and downstream bed invert attributes must be

specified to define the slope of the channel, or the inverts can
be taken from the channel’s cross-sections by specifying
-99999 for the inverts.

Structures

Bridge Bridge structure – energy loss coefficients supplied by the

B
Section 5.8.2 user.

Bridge structure (introduced for Build 2016-03-AA) – only pier

loss and submerged deck loss coefficients required (all other
BB losses automatically calculated). In the future BB bridges will
also recognise bridge definition inputs in a similar manner to
BArch bridges to automatically generate loss coefficients.

Arch Bridge structure (Build 2023-03-AA and onwards). Allows

Arch Bridge
BArch users to specify a .csv defining the properties of the arch
Section 5.8.3
bridge.

Culverts
C Pipe or Circular culvert.
Section 5.8.1

I Irregular shaped culvert.

R Box or Rectangular culvert.

Gates
SG Sluice Gate.
Section 5.8.6

Pump
P Pump.
Section 5.10.2

Spillways
Section 5.8.5 SP Gated or ungated spillways.
and 5.10.6

Weirs
W Weir structure (original weir channel).
Section 5.8.4

Section 5 1D Network Domains - ESTRY - 5 / 130 Page 108 / 1094

 Channel/Node Type Description

WB Broad-crested weir.

WC Crump weir

WD User-defined weir.

WO Ogee-crested weir.

WR Rectangular weir (sharp-crested).

WT Trapezoidal / Cippoletti weir.

WV V-notch weir

Similar to the original W weir channel, but with more user

WW
options.

Special
Channels

Normal flow channel defined by its length, bed resistance and

hydraulic properties. The channel can wet and dry, however,
for overbank areas (e.g. tidal flats or floodplains) gradient (G)
(leave or S channels should be used. For steep channels that may
Normal
blank) experience supercritical flow, use S channels.

Note: For all open channels it is recommended to use the

S Type.

Similar to a Normal channel, except when the water level at

one end of the channel falls below the channel bed, the
channel invokes a free-overfall algorithm that keeps water
flowing without using negative depths. The algorithm takes into
account both the channel’s bed resistance and upstream
controlled weir flow at the downstream end.
Gradient G
Gradient channels are designed for overbank areas such as
tidal flats and floodplains. The upstream and downstream bed
invert attributes must be specified to define the slope of the
channel.

Note: For all open channels it is recommended to use the

S Type.

User defined flow channel using a flow matrix. The flow

Matrix Flow
M through the structure is dependent on the water levels
Channel
upstream and downstream.

User-defined stage discharge channel. The flow through the

Depth-
structure is only dependent on the upstream conditions, such
Discharge Q
as user defined spillways. If downstream levels are influential
Channel
then an M channel (see above) may be required.

Section 5 1D Network Domains - ESTRY - 6 / 130 Page 109 / 1094

 Channel/Node Type Description

Connects the end of one channel to another. This is particularly

useful for connecting a side tributary or pipe into the main flow
path. It also allows a different end cross-section or WLL to be
specified for the side channel, rather than using the end cross-
section on the main channel. The direction of the connector
line is important.
Connector X
Note: The line must start at the side channel and end at
the main channel.

If two or more connectors are used at the same location (i.e. to

connect two or more side channels to a main channel) their
ends must all snap to the same main channel.

Operational
Channels

Operational channel to model the “pipe failure” process (when

water seepages through an embankment forming a small flow
Piping Failure PF
path), see Section 5.10.8 . Introduced in the 2020-10-AA
build.

Operational channel to model a “dam failure” process (when a

Dam Failure DF dam/levee breaks), see Section 5.10.8 . Introduced in the
2020-10-AA build.

Section 5 1D Network Domains - ESTRY - 7 / 130 Page 110 / 1094

 @344 Table 5.2: 1D Channel (Line) Types - Additional/Optional Channel Flags

Applicable
Options Flag Description
Channel Types

Forces the adjust losses approach using the

equations and methodology in Section 5.8.7
to adjust the inlet and outlet losses of a culvert
Adjust
or bridge channel according to the approach
Structure A Culverts (R, C, I)
and departure velocities. This flag overrides
Losses
Structure Losses if set to FIX. For example, to
adjust the losses for a rectangular culvert
specify a Type attribute of “RA”.

Forces the fix losses approach so as not to

adjust the inlet and outlet losses of a culvert or
bridge channel according to the approach and

Fix Structure departure velocities. This flag overrides the

F Structure Losses setting if set to ADJUST (the Culverts (R, C, I)
Losses
default). See Section 5.8.7 .

For example, to fix the losses for a circular

culvert specify a Type attribute of “CF”.

For culverts, limits the flow regimes to the

Downstream downstream controlled ones (see Table 5.6 ),
D Culverts (R, C, I)
Controlled unless it is a zero length channel (i.e. channel
length less than 0.01m).

If a “W” is specified in conjunction with a B, C

or R channel (e.g. BW, CW or RW), a weir
channel is automatically inserted to represent
the flow overtopping the structure. This saves
Weir over the Culverts (R, C)
W having to digitise the weir separately. To use
Top and Bridges (B)
this option requires adding the 10 optional
attributes to the 1d_nwk layer as detailed in
Table 5.17 . Some of these attributes are
used to specify the weir parameters.

For structures specifies the use of energy level All Weirs except
for the flow calculations. The default is to use for ‘W’ type,
energy (E), unless the global .ecf command Spillways (SP),
Energy E
Structure Flow Levels == WATER is Gates (SG) and
used, in which case the default is to use water Dam Failure
level (H). See H below. Channels (DF).

Section 5 1D Network Domains - ESTRY - 8 / 130 Page 111 / 1094

 Applicable
Options Flag Description
Channel Types

Introduced in the 2023-03-AC build, uses the

All Weirs except
energy level at the upstream node and water
for ‘W’ type,
level at the downstream node of 1D structures
Energy Spillways (SP),
EH for flux calculation. This option can also be
Upstream Gates (SG) and
applied globally using the .ecf command
Dam Failure
Structure Flow Levels == ENERGY
Channels (DF).
UPSTREAM.

For structures specifies use of water level for

the flow calculations. The default is to use
All Weirs except
energy level unless Structure Flow
for ‘W’ type,
Water Levels == WATER has been specified. Spillways (SP),
H
Surface Gates (SG) and
For example, if a broad-crested weir is to use
Dam Failure
water surface levels rather than energy levels,
specify WBH (a space can be used so “WB H” Channels (DF).

may be preferred for clarity).

Open Channel (S), Normal (blank) Gradient

(G) and channels can be specified as non-
Non-inertial inertial by including an “N” in the Type Open Channel (S,
N
channel attribute. A non-inertial channel has the inertia G ,blank)
term suppressed from the momentum
equation.

Normal and gradient channel cross-sections

can vary over time by using a variable channel
definition. Include a “V” in the Type attribute
and see Section 5.8.4.6 for more details.
Open Channel (S,
Variable Note that prior to the 2013-12 release, a
V G ,blank) and W
Geometry variable weir channel was specified as a WV type Weir
channel type. As of the 2013-12 release, WV
channels are processed as a V-notch weir.
Variable weir channels must be specified as
type “VW”.

“O” flag is required for structures that are to be

operated using an operating control definition
Operational
O (see Section 5.9 ). For example, an operated see Section 5.9
Control
pump would have a Type attribute of “PO” (or
“OP”)

Section 5 1D Network Domains - ESTRY - 9 / 130 Page 112 / 1094

 Applicable
Options Flag Description
Channel Types

Any channel can be defined as uni-directional

by including a “U” in the Type attribute. Water
Uni-
will only flow in the positive direction of the
directional (all U All channel types
channel (from upstream to downstream). For
channels)
example a “RU” channel could be used to
represent a flap gated rectangular culvert.

@345
5.6 Open Channels

@346
5.6.1 Inertial Channels

An open channel that includes the inertia term is specified as a series of lines in one or more
1d_nwk GIS layers with an attribute type of ‘S’, S signifying a sloping channel that can handle
steep, super-critical flows. S channels are typically all natural channels and artificial channels such
as concrete lined open drains. They automatically test for the occurrence of upstream controlled
flow and automatically switch between the two regimes, and is the preferred type for all open
channels. Other open channel types, Normal (type “blank”) and Gradient (type “G”) are kept for
backward compatibility and discussed in Section 5.9.4 . Table 5.3 lists the 1d_nwk attributes that
are required for open channels.

The hydraulic properties table for open channels is typically provided in the form of cross-sectional
data referenced within a 1d_xs GIS layer and using the command Read GIS Table Links but can
also specified from external sources (see Section 5.7 ).

Lines within the 1d_xs GIS layer may be digitised midway along the channel or snapped to the
channel ends. The treatment of the cross-sectional data is different depending on the digitisation.
It is also possible to automatically create interpolated cross-sections. The attributes of the 1d_xs
GIS layer is described in Table 5.4 and further information on cross-sections is provided in
Section 5.7 .

@347
5.6.2 Non-Inertial Channels

To bypass the Courant stability condition, a special channel flag (N) is included, known as non-
inertial channel or a friction-controlled channel. This is valid for the S (open channel) and the
superseded blank and G gradient channels. To apply this to an S type channel the channel type is
SN.

For a non-inertial channel, the inertia terms are ignored (eliminating inertial effects) and the
stability control procedure is automatically applied. Although rarely required, the suppression of
the inertia terms can be useful for stabilising very short S channels with high velocities.

Section 5 1D Network Domains - ESTRY - 10 / 130 Page 113 / 1094

 @348 Table 5.3: Open Channels: 1D Model Network (1d_nwk) Attribute Descriptions

Default GIS
No. Description Type
Attribute Name

Unique identifier up to 12 characters in length. It

may contain any character except for quotes and
commas, and cannot be blank. As a general rule,
1 ID spaces and special characters (e.g. “\”) should be Char(12)
avoided, although they are accepted. The same ID
can be used for a channel and a node, but no two
nodes and no two channels can have the same ID.

As described in Table 5.1 .

2 Type S: Steep Channel Char(4)

G: Gradient Channel
Blank: Normal Channel

If a “T”, “t”, “Y” or “y” is specified, the object will be

3 Ignore ignored (T for True and Y for Yes). Any other entry, Char(1)
including a blank field, will treat the object as active.

If left blank or set to Yes (“Y” or “y”) or True (“T” or

“t”), the storage based on the width of the channel
UCS over half the channel length is assigned to the
(Use Channel upstream and downstream nodes connected to the
4 Char(1)
Storage at channel. If set to No (“N” or “n”) or False (“F” or “f”),
nodes). the channel width and length does not contribute to
the node’s storage. See Section 5.13.1.1 for further
discussion.

If greater than zero, sets the length of the channel in

metres. If the length is less than zero, except for the

5 Len_or_ANA special values below, the length of the line is used. Float

Note, not used to specify the length of a pit channel

(which is assumed to have zero length).

The Manning’s n or Manning’s n multiplier for the

channel.

If not using materials or Manning’s values in the

cross-section the Manning’s n value is specified
using this attribute.

6 n_nF_Cd If using materials or Manning’s n to define the bed Float

resistance from XZ tables (see Sections 5.7.1.1.2
and Section 5.7.1.1.3 ), n_nF_Cd is a multiplier and
is typically set to one (1) as it becomes a
multiplication factor of the materials’ Manning’s n
values. It may be adjusted as part of the calibration
process.

Section 5 1D Network Domains - ESTRY - 11 / 130 Page 114 / 1094

 Default GIS
No. Description Type
Attribute Name

G, S Channel Type:
The upstream bed or invert elevation of the channel
in metres. The bed of the channel cross-section is
used if -99999 is specified for G and S channels.
If a manually created node exists at the upstream
end of the channel, and -99999 is specified, the
upstream invert is set to the DS_Invert value of the
7 US_Invert node (or pit), provided this value is greater than Float

-99999 – for example, see Table 5.30 .

Blank Channel Type:

Sets the upstream and downstream inverts. Note
that the invert is taken as the maximum of the
US_Invert and the DS_Invert attributes. Use -99999
to use the bed of the cross-section as the invert.

Sets the downstream invert of the channel using the

8 DS_Invert same rules as described for the US_Invert attribute Float
above.

Additional form losses (factor of dynamic head) due

to bends, bridge piers, etc.

9 Form_Loss This method is preferred instead of increasing Float

Manning’s n to account for losses. For S channels,
this only applies when not in upstream controlled
friction mode.

10 pBlockage Not used. Float

Not used unless using the legacy feature that

11 Inlet_Type accesses MIKE 11 cross-section data - see the 2018 Char
TUFLOW Manual for details.

If using Flood Modeller .dat files, the cross-section

ID. This is used to link to the cross-section details
within the cross-section database (specified via the
XS Database command).
12 Conn_1D_2D Char
If using the legacy feature that accesses MIKE 11
cross-section data - see the 2018 TUFLOW Manual
for details.

Otherwise, not used.

Not used unless using the legacy feature that

13 Conn_No accesses MIKE 11 cross-section data - see the 2018 Integer
TUFLOW Manual for details.

14 Width_or_Dia Not used. Float

Section 5 1D Network Domains - ESTRY - 12 / 130 Page 115 / 1094

 Default GIS
No. Description Type
Attribute Name

15 Height_or_WF Not used. Float

16 Number_of Not used. Integer

17 HConF_or_WC Not used. Float

18 WConF_or_WEx Not used. Float

19 EntryC_or_WSa Not used. Float

Can be used to apply a form loss coefficient per unit

length of channel for an S type channel. For
example, a value of 0.0001 v2/g / metre or (0.1 per
km) for a 200m channel, the extra form loss would
20 ExitC_or_WSb be 0.0001 x 200 or 0.02 v2/2g. This can be used to Float
account for irregularities in the bed form not
accounted for by Manning’s n value (eg. submerged
rock ledges and obstructions, or large boulders). If
using it is recommended that this is calibrated.

@349
5.7 Cross-Sections

Cross-section hydraulic properties tables may come from several sources:

Calculated using a cross-section profile in a .csv or similar formatted file.

A hydraulic properties table in a .csv or similar formatted file.
Flood Modeller .dat files (external source). The cross-section ID within the external file is
specified in the Conn_1D_2D field in a 1d_nwk layer (see Table 5.3 ). This is used to link to
the cross-section details within an external sources file specified via the XS Database
command. Cross-sections are applied using the mid cross-section approach (Section 5.7.5 ).
External sources such as MIKE 11 processed data .txt files or Flood Modeller .pro files, see
the 2018 TUFLOW Manual for details of this legacy feature.

Cross-section profile and hydraulic properties data are accessed using a 1d_xs GIS layer and the
.ecf command, Read GIS Table Links . Type “XZ” is specified if accessing a cross-section profile
(distance versus elevation) and a type “CS” or “HW” is used if accessing a hydraulic properties
table (elevation versus width). Table 5.4 presents the attributes required for the 1d_xs GIS layer.
A number of optional flags are available for both “XZ” and “CS” or “HW” and are explained in more
detail in Sections 5.7.1 and 5.7.2 .

It is possible to let the water level at a cross-section to extend above the highest elevation in the
hydraulic properties table. The default is to allow the water level to exceed ten times the depth of
the CS or NA table before an instability is triggered. See Depth Limit Factor for further details.

When the water level exceeds the top of a cross-section, the conveyance properties are
calculated based on glass walling the cross-section above the top. This is carried out by taking the
effective flow area and using the effective flow width to calculate the conveyance properties
assuming no side wall friction applies above the cross-section top.

Section 5 1D Network Domains - ESTRY - 13 / 130 Page 116 / 1094

 @350 Table 5.4: 1D Cross-Section Table Link (1d_xs) Attribute Descriptions

Default GIS
No. Attribute Description Type
Name

Filename (and path if needed) of the file containing the

1 Source tabular data. Must be a comma or space delimited text Char(50)
file such as a .csv file.

Two characters defining the type of table link.

“XZ”: Cross-section XZ profile (can include horizontal

variations in resistance). The first column is the distance
column, and the second the elevation column. Other
optional columns are described under the Flags attribute
2 Type Char(2)
below.

“CS” or “HW”: Cross-section hydraulic properties

table. The first two columns must be elevation and
width. Optional flags are described under the Flags
attribute below

Optional flags are as follows:

XZ Tables:

“R”, “M” or “N”: The relative resistance (Column 3) is

used to vary the bed resistance value (Manning’s n)
across the section. Specify an “R” flag for relative
resistance factor, an “M” flag to use a material number
or an “N” flag for a Manning’s n value.
“P”: The position values (Column 4) are used to
indicate whether an XZ point is left bank (1),
mainstream (2) or right bank (3). P values must be
entered as 1, 2 or 3. See Section 5.7.1.1.4 .
“A”: The addition values (Column 5) are used to raise

3 Flags or lower the Z value – this is useful, for example, for Char(8)
modelling siltation or erosion of a cross-section, raising,
or adding blocked rails to, a weir cross-section of an
embankment, etc.
“E” or “T”: Specify an “E” to use effective area or a “T”
to use total area when calculating the flow area (see
Section 5.7.2.4 and Flow Area ). If neither is specified,
the global value set using Flow Area is used.

CS or HW Tables: “A”: Flow area (Column 3)

“P”: Wetted perimeter (Column 4)
“F” or “N”: Vertical change in resistance (Column 5).
Use “F” for a multiplication factor and “N” for a
Manning’s n value.
“E”: Effective flow width (Column 6)

Section 5 1D Network Domains - ESTRY - 14 / 130 Page 117 / 1094

 Default GIS
No. Attribute Description Type
Name

Optional. Identifies a label in the Source file that is the

header for the first column of data. Values are read from
the first number encountered below the label until a
4 Column_1 non-number value, blank line or end of the file is Char(20)
encountered.
If this field is left blank, the first column of data in the
Source file is used.

Optional. Identifies a label in the Source file that is in

the header for the second column of data.
5 Column_2 Char(20)
If this field is left blank, the next column of data after
Column_1 is used.

Optional. Identifies a label in the Source file that is in

the header for the third column of data.
6 Column_3 Char(20)
If this field is left blank, the second column of data after
Column_1 is used.

7 Column_4 Optional. Defines the fourth column of data. Char(20)

8 Column_5 Optional. Defines the fifth column of data. Char(20)

9 Column_6 Optional. Defines the sixth column of data. Char(20)

Optional. Sets the height increment in metres to be used

for calculating hydraulic properties from a XZ cross-
10 Z_Increment section profile. If less than 0.01, the increment is Float
determined automatically. Only used for XZ cross-
section data.

Optional. Sets the maximum elevation in metres to be

used for calculating hydraulic properties from a XZ
cross-section profile. If less than the lowest point in the
11 Z_Maximum Float
cross-section profile, Z_Maximum is taken as the
highest elevation in the profile. Only used for XZ cross-
section data.

Optional. Adjusts the cross-section properties for XZ

and CS/HW data according to the skew angle. Useful
where the cross-section line is surveyed oblique to the
Skew
12 flow direction. The skew angle is zero degrees in the Float
(in degrees)
direction of flow and 90 degrees if surveyed at a right
angle to the direction of flow. For example, a value of 45
adjusts the horizontal dimensions by dividing by the √2.

Section 5 1D Network Domains - ESTRY - 15 / 130 Page 118 / 1094

 @351
5.7.1 Type “XZ” Optional Flags

@352
5.7.1.1 Relative Resistance

Varying the resistance across an XZ (offset-elevation) cross-section is possible by using either a

relative resistance factor (R flag), different material ID values (M flag) or different Manning’s n
values (N flag). These are discussed further in the sections below.

The relative resistance value applies midway to either side of the X-value (except the first and last
X-values where it only applies to midway to the single neighbouring X-value). The reason for this
is that material or n values can be correctly sampled from a GIS layer at the survey points. This is
slightly different from some other 1D hydraulic modelling software that apply relative resistance
values from the previous X-value to the current X-value or from the current to the next.

Sections of a cross-section can be “removed” by entering ‑1 (negative one) for a resistance value.
This feature is particularly useful when developing a linked 1D/2D model where the 1D cross-
sections are typically trimmed to the top of bank to avoid double counting of floodplain conveyance
and storage. For more information on how negative “M”, “N” and “R” differ, please refer to the
TUFLOW Wiki.

@353
5.7.1.1.1 Relative Resistance Factor (R)

The relative resistance factor (R) is a multiplication factor applied to the primary Manning’s n value
of the channel. Wherever the R value changes across the cross-section, a new parallel sub-
channel is created. The total conveyance for the whole cross-section is determined by carrying out
a parallel channel analysis of all the sub-channels. This approach allows the variation in bed
resistance across a cross-section to be accounted for, and to force a parallel channel analyses so
that conveyance does not decrease with height when the wetted perimeter suddenly increases
(e.g. when overbank areas just become wet).

If using effective area (see Section 5.7.4 ), an R of 1.0 must occur at some point in the profile to
indicate the primary sub-channel. If a value of 1.0 is not found an ERROR 1070 occurs, as grossly
incorrect channel velocities can occur when using effective area with an inappropriate primary
sub-channel. The Manning’s n value of the primary sub-channel is that specified in the 1d_nwk
layer for the channel. The primary sub-channel does not have to be the lowest part of the cross-
section.

@354
5.7.1.1.2 Material Values (M)

If using material values (M), the Manning’s n value to be applied is taken from a Materials
Definition File (see Read Materials File ). If the Position “P” flag is not used, the material at the
lowest Z value (cross-section bed) is used as the primary material, which then corresponds to a
relative resistance factor of 1.0. If no material values are specified, a material value of one (1) is
applied over the whole cross-section. If the P flag and values are used, the primary material is
determined as that at the lowest Z value in the mainstream channel (see Section 5.7.1.1.3 ).

When using materials, the n_nF_Cd value in the 1d_nwk layer becomes a multiplier and
should be set to one (1.0). If justified, it can be adjusted for calibration or sensitivity testing. For
example, if a slightly higher resistance is desired along a channel, rather than setting different
material values, change the n_nF_Cd value in the 1d_nwk layer to, say, 1.1 to increase all
Manning’s n values across the cross-section by 10%.

Section 5 1D Network Domains - ESTRY - 16 / 130 Page 119 / 1094

 A negative material value in the M column of a XZM cross-section table can now be specified to
disable (i.e. block out or remove) sections of a cross-section. The negative value must be the
negative of a valid Material ID in the Materials Definition File (see Read Materials File and
Section 7.3.6 ). For more information on how negative “M”, “N” and “R” differ, please refer to the
TUFLOW Wiki.

Example

In the following example, the TUFLOW Tutorial Model (discussed in Section 2.1.1 ) will be
modified to demonstrate how Manning’s n values may be assigned to cross-sections based on
values within the Materials Definition File.

An “M” flag is added to the 1d_xs layer referencing the cross-sectional data of the open channel.

An additional third column is then added to the .csv source file, containing one or more Material ID
values from within the Materials Definition File. In the figure below, a Material ID of 10 has been
assigned to the whole cross-section.

This correlates to a Manning’s n value of 0.08 as shown in the Materials Definition File.

When using the “M” flag to define material values, the “n_nF_Cd” attribute in the 1d_nwk becomes
a multiplier (refer to Table 5.3 ). In most cases, this should be set to 1, as has been carried out
for this example.

Once the model has been compiled, a check of the Manning’s n values applied to each cross-
section may be viewed in the _ta_tables_check.csv.

Section 5 1D Network Domains - ESTRY - 17 / 130 Page 120 / 1094

 @355
5.7.1.1.3 Manning’s n Values (N)

If using Manning’s n values (N), the n value is specified directly, noting that the n_or_n_Cd value
in the 1d_nwk layer becomes a multiplier and should be set to one (1.0). See discussion above for
using material values. A value of ‑1 ignores that section of the profile. For information on how
negative “M”, “N” and “R” differ, please refer to the TUFLOW Wiki.

@356
5.7.1.1.4 Position Flag (P)

The position values are used to indicate whether an XZ point is left bank (1), mainstream (2) or
right bank (3). The P value is used to indicate where the mainstream sub-channel is located. If the
materials (M flag) is used, the primary material is taken as that at the lowest Z value in the
mainstream sub-channel. If the P flag and values are not specified, the primary material is that at
the lowest Z value across the whole section.

@357
5.7.2 Type “HW” Optional Flags

@358
5.7.2.1 Flow Area (A)

The effective flow area in m2 or ft2 (depending on the model’s units). If omitted, the area is
calculated based on the elevations and widths starting at an area of zero at the lowest elevation.

@359
5.7.2.2 Wetted Perimeter (P)

The wetted perimeter in metres or feet (depending on the model’s units). If omitted, the area is
calculated based on the elevations and widths assuming a symmetrical channel.

@360
5.7.2.3 Manning’s n Values (N)

If using Manning’s n values (N), the n value is specified directly, noting that the n_or_n_Cd value
in the 1d_nwk layer becomes a multiplier and should be set to one (1.0). See discussion above for
using material values. A value less than zero is set to 0.001.

@361
5.7.2.4 Manning’s n Values (F)

If using Manning’s n value mulipliers (F), the n value specified in the “n_or_n_Cd” value in the
1d_nwk layer is multiplied by the specified factor. A value less than zero is set to 0.001.

Section 5 1D Network Domains - ESTRY - 18 / 130 Page 121 / 1094

 @362
5.7.3 Parallel Channel Analysis

To calculate total conveyance, a cross-section needs to be sub-divided into panels for which the
velocity is uniformly distributed. Conveyance for each panel is calculated using the Manning’s
equation:

@363 K =
1.0 2

AR 3 (5.3)
n

Where:

K = conveyance of panel
n = Manning’s n roughness coefficient
A = Flow Area (m2)
R = Hydraulic Radius (m) – area / wetted perimeter

The conveyance of a cross-section may reduce with height where there is a sudden increase in
the wetted perimeter compared with a relatively small increase in flow area, causing the hydraulic
radius to reduce despite the water level increasing. A WARNING is issued if this occurs and it is
strongly recommended that the cross-section be reviewed and corrected.

The most common cause for the reduction in conveyance with height occurs when the extent of
inundation across the cross-section increases markedly during the transition from in-bank to out-
of-bank flow. The reducing conveyance with height problem is usually resolved by forcing a
parallel channel analysis by specifying a change in resistance using the R, M or N flag discussed
in the sections above.

Conveyance Calculation == ALL PARALLEL is the default setting. This forces a parallel
channel analysis based on splitting the cross-section into parallel channels at every distance X-
value. This approach generally ensures that conveyance does not reduce with height. Using this
approach to calculate the hydraulic properties tends to produce a slightly more efficient cross-
section (higher conveyance), similar to the resistance radius formulation used by some schemes.
Therefore, a slightly higher Manning’s n value (by ~10%) may be needed to achieve similar
results.

Figure 5.2 illustrates the ALL PARALLEL method of conveyance calculation.

@369

Figure 5.2: ‘All Parallel’ Conveyance Calculation Method

Conveyance Calculation == CHANGE IN RESISTANCE may be used as an alternative to

the default ALL PARALLEL approach. In this case, the parallel channel analysis splits the cross-
section into separate parallel channels based on wherever there is a change in resistance (due to

Section 5 1D Network Domains - ESTRY - 19 / 130 Page 122 / 1094

 different relative resistance (R flag), material type (M flag) or Manning’s n values (N flag)). This is
illustrated in Figure 5.3 :

@370

Figure 5.3: ‘Change in Resistance’ Conveyance Calculation Method

It should be noted that differences in results are expected between the two methods of
conveyance calculation. The total number of panels for each calculation method will be different
as demonstrated, thereby influencing the total conveyance.

The ALL PARALLEL approach has been chosen as the current default conveyance calculation
method for ESTRY. This is not to imply that this method produces the more accurate result, rather
it has been chosen as it generally does not cause conveyance reducing with height warnings.

@371
5.7.4 Effective Area versus Total Area

For XZ (offset elevation) Cross-Sections, the flow area is calculated as an effective area (E flag) or
a total area (T flag). Use of the flag will override the global setting set by Flow Area where the
default approach is to use the effective area.

If there is no variation in relative resistance across the cross-section there is no difference

between effective and total areas. This is dependent on the relative resistance being 1.0 across
the whole section. ERROR 1070 is produced if the relative resistance is not 1.0 somewhere along
the cross-section when using effective area.

For an open channel, the total conveyance of a cross-section is not affected by whether effective
or total area is used. In the case of effective area the wetted perimeter is adjusted to compensate
for the change in flow area so as to produce the same conveyance as would occur for total area.
For special channels that use cross-sections such as bridges, weirs and irregular culverts, the flow
area used is the effective or total area as specified. This can be useful if the effects of blockage or
congestion within the section needs to be modelled.

The primary differences between using effective and total area are:

The channel velocity calculated is the depth and width average of the primary (normally
mainstream) parallel sub-channel if using effective area, and the averaged depth and width of
the whole cross-section if using total area.
Where the effective and total areas are significantly different, the channel velocities used in
the 1D momentum equation will be significantly different. If the channel velocity is sufficiently
high and different depending on whether effective or total area is used, the inertia terms in the
1D momentum equation may affect the results. Note the frictional (bed resistance) term in the
momentum equation is NOT affected as the hydraulic properties for the cross-section are

Section 5 1D Network Domains - ESTRY - 20 / 130 Page 123 / 1094

 adjusted so that the total conveyance is the same irrespective of whether effective or total
area is used.
Effective area gives a more reliable calculation of the mainstream velocity, and therefore, a
more accurate estimate of approach and exit velocities of structures, and more appropriate
velocities for advection-dispersion and sediment transport calculations. Where velocities are
not high or significantly changed when using effective or total area, the water level and flow
results are usually identical or very similar.

@372
5.7.5 Mid Cross-Sections

Cross-sections may be specified using lines digitised within a 1d_xs layer partway along the
channel. The upstream and downstream invert levels of the channel are both assigned the invert
level of the cross-section if a value of -99999 has been specified within the 1d_nwk channel (refer
to Table 5.3 ). If either of these attributes is greater than ‑99999, the invert of the channel is set to
the GIS attribute value rather than that of the cross-section bed elevation.

The mid cross-section approach is the only approach available for structures such as bridges,
weirs and irregular shaped culverts. It can also be used for open channels, however the
digitisation of cross-section lines within a 1d_xs layer that have been snapped to the channel ends
(as described in Section 5.7.6 below) has added advantages and is recommended.

If using a mid cross-section 1d_xs line with more than two vertices, a intermediate vertex must be
snapped to the 1d_nwk channel.

@373
5.7.6 End Cross-Sections

Cross-sections for open channels (S channels and the superseded G channels) can be specified
using lines digitised within a 1d_xs layer at the channel ends, rather than a single cross-section
midway along the channel as described above. This approach has the following benefits:

The upstream and downstream inverts can be based on the beds of the cross-sections,
thereby saving some effort to enter this information within the 1d_nwk file. To do this, set the
US_Invert and DS_Invert attributes in the 1d_nwk layer to ‑99999. If either of these attributes
is greater than ‑99999, the invert is set to the attribute value rather than that of the cross-
section bed.
Cross-section surveys from some other 1D models often have the cross-sections at the
channel ends, therefore, this makes it easier to use these external data sources.

There are a few rules on how end cross-sections are interpreted and applied, as follows:

The 1d_xs cross-section lines must have a vertex snapped to the channel end.
If a 1d_xs cross-section line occurs elsewhere along an open channel with end cross-
sections, the midway cross-section prevails. This is particularly useful where two channels’
ends are snapped to an end cross-section, but the end cross-section is to be applied to only
one of the channels (e.g. one channel is a river channel using end cross-sections, and the
other is an overbank channel). For the overbank channel, specify a cross-section line
somewhere along the channel, and preference will be given to this cross-section rather than
the end cross-section. Alternatively, an X connector can be used if end cross-sections are
required for both channels. See Section 5.9.3 .

Section 5 1D Network Domains - ESTRY - 21 / 130 Page 124 / 1094

 End cross-sections cannot be used to override previously defined cross-section properties for
a G or S channel. You can override the end cross-sections using a midway cross-section.
For channels other than S and G channels, end cross-sections are ignored.

@374
5.7.7 Interpolated Cross-Section Protocols

Cross-sections may be interpolated for channels (excluding C and R culvert channels) that have
not been assigned a cross-section. A series of channels may now be digitised between two cross-
sections, and the cross-section properties at each channel are linearly interpolated between the
two cross-sections. The protocols applied when interpolating cross-sections and setting Manning’s
n values are:

If a channel has a cross-section at each end, the processed data of these cross-sections is
averaged.
If a channel has a cross-section midway, this cross-section takes priority over any end cross-
sections.
If a channel only has one end cross-section, TUFLOW traverses upstream/downstream to find
the next available cross-section, and uses this to interpolate the cross-section properties for
that channel. The next available cross-section can be a midway or end cross-section.
If a channel has no cross-sections attached to it, TUFLOW traverses upstream and
downstream to find the nearest cross-sections and interpolates the channel properties based
on these cross-sections.
When traversing upstream/downstream to find a cross-section:
If a junction (three or more channels snapped together) is reached (excluding pits and
connectors), an ERROR is issued as it is not possible to determine which branch to
follow. Note, channels connected to a junction using a connector (Type “X”) are not used
for traversing, therefore use connectors to connect side channels to the main branch to
avoid interpolating sections from side channels
The digitised direction of the channel is important and controls the direction used to
traverse upstream and downstream. Ensure the channels are digitised in a consistent
direction (usually from upstream to downstream).
If a channel has an end cross-section only at one end, and no cross-section is found when
traversing, this end cross-section is used at both ends for that channel only.
The inverts are also interpolated using the cross-section beds (unless the inverts have been
manually entered into the 1d_nwk attributes). Specify -99999 for the 1d_nwk channel inverts
to be interpolated from the cross-sections.
Cross-sections that are interpolated can be of any format, including CS or HW 1d_xs formats
(see Table 5.4 ).
The Manning’s n value assigned to the channel’s cross-section is as follows:
If the cross-sections used for interpolation have no Manning’s n values (i.e. for XZ cross-
sections, M or N was not specified, or for CS/HW cross-sections, N was not specified),
the 1d_nwk Manning’s n attribute of the channel is used.
If the cross-sections used for interpolation have Manning’s n values, the value is
interpolated from the cross-section n values (at the bed) and multiplied by the 1d_nwk
Manning’s n attribute of the channel. In this case the 1d_nwk n_or_n_F attribute is a
multiplier that can be used to calibrate the model.
If one of the two cross-sections used for interpolation has a Manning’s n value, and the
other does not, the n value used is interpolated using the channel’s 1d_nwk Manning’s n

Section 5 1D Network Domains - ESTRY - 22 / 130 Page 125 / 1094

 value and the cross-section’s n value. Ideally, the model should be set up using the same
approach everywhere so that this situation does not arise as it may cause undesirable
results. A WARNING is issued if this occurs.

The interpolation of cross-sections is the default. Interpolate Cross-Sections can also be used to
switch this feature ON or OFF.

@375
5.8 Structures

Hydraulic structures in the 1D domain are modelled by replacing the momentum equation with
standard equations describing the flow through the structure. The structures available are
described in the following sections. A discussion on the choice of a 1D or 2D representation of the
structure is presented in Section 7.3.9.1 .

A channel is flagged as a hydraulic structure using the Type attribute as described in Table 5.1 .
Except for culverts, a structure has zero length, i.e. there is no bed resistance. If a non-zero length
is applied to a “zero length” structure, this is only used in the calculation of the storage (nodal
area).

@376
5.8.1 Culverts and Pipes

Culvert or pipe channels can be either rectangular, circular (pipe) or irregular in shape. A range of
different flow regimes is simulated with flow in either direction. Adverse slopes are accounted for
and flow may be subcritical or supercritical. Figure 5.4 , Figure 5.5 and Table 5.6 present the
different flow regimes which can be modelled. The regimes that occur during a simulation are
output to the .eof file next to the velocity and flow output values, and to the _TSF GIS layer (see
Sections 14.6 and 15.3.4 ), and can be displayed on time-series plots in the QGIS TUFLOW
Viewer plugin.

For all culvert types the length, upstream and downstream inverts, Manning’s n, bend loss,
entrance and exit losses, and number of barrels are entered using the 1d_nwk attributes (see
Table 5.5 ). For type “C” circular or type “R” rectangular culverts, the dimensions are also
specified within the 1d_nwk attributes. For an “I” irregular shaped culvert, the cross-sectional
shape is specified in the same manner as for open channels using a 1d_xs GIS layer (refer to
Section 5.7 and Table 5.4 ) and the command Read GIS Table Links . The line is digitised
across the 1d_nwk channel line.

The four culvert coefficients are as follows:

The height contraction coefficient for box culverts. Usually 0.6 for square edged entrances to
0.8 for rounded edges. This factor is not used for circular culverts.
The width contraction coefficient for box culverts. Typically values from 0.9 for sharp edges to
1.0 for rounded edges. This factor is normally set to 1.0 for circular culverts.
The entry loss coefficient. The standard value for this coefficient is 0.5. Variations to this value
may be applied based on manufacturer specifications.
The exit loss coefficient, normally recommended as 1.0.

The calculations of culvert flow and losses are carried out using techniques from “Hydraulic Charts
for the Selection of Highway Culverts” and “Capacity Charts for the Hydraulic Design of Highway
Culverts”, together with additional information provided in Henderson (1966 ). The calculations

Section 5 1D Network Domains - ESTRY - 23 / 130 Page 126 / 1094

 have been compared and shown to be consistent with manufacturer’s data provided by both
“Rocla” and “Armco”.

Note: By default, the entrance and exit losses above are adjusted every timestep according
to the approach and departure velocities based on the equations in Section 5.8.7 .

For benchmarking of culvert flow to the literature, see “TUFLOW Validation and Testing” (Huxley,
2004 ).

Section 5 1D Network Domains - ESTRY - 24 / 130 Page 127 / 1094

 @377Table 5.5: Culverts and Pipes: 1D Model Network (1d_nwk) Attribute Descriptions

Default GIS
No. Description Type
Attribute Name

Unique identifier up to 12 characters in length. It

may contain any character except for quotes and
commas, and cannot be blank. As a general rule,
spaces and special characters (e.g. “\”) should be
avoided, although they are accepted. The same ID
can be used for a channel and a node, but no two
1 ID nodes and no two channels can have the same ID. Char(12)
When automatically creating nodes (default) “.1”
and “.2” are added to the channel names for the
upstream and downstream node names
respectively. IDs over 10 characters long are not
recommended as the appending of .1 and .2 can
cause duplicate node ID’s to be created.

The culvert type:

“C” for a circular culvert;

“R” for a rectangular culvert;
“I” for an irregular shaped culvert
2 Type Char(4)
Optional type flags may also be used to implement
additional flow controls such as unidirectional flow
(“U”) or operated flow conditions (“O”). Culvert type
details are outlined in Table 5.1 and optional flags
in Table 5.2 .

If a “T”, “t”, “Y” or “y” is specified, the object will be

3 Ignore ignored (T for True and Y for Yes). Any other entry, Char(1)
including a blank field, will treat the object as active.

If left blank or set to Yes (“Y” or “y”) or True (“T” or

“t”), the storage based on the width of the channel
UCS
over half the channel length is assigned to both of
(Use Channel
4 the two nodes connected to the channel. If set to Char(1)
Storage at
No (“N” or “n”) or False (“F” or “f”), the channel
nodes)
width does not contribute to the node’s storage.
See Section 5.13 for further discussion.

The length of the culvert in metres. If the length is

5 Len_or_ANA less than zero, except for the special values below, Float
the length of the line is used.

Section 5 1D Network Domains - ESTRY - 25 / 130 Page 128 / 1094

 Default GIS
No. Description Type
Attribute Name

The Manning’s n value of the culvert.

If using materials to define the bed resistance from

XZ tables (only for Irregular culvert, see Section
6 n_nF_Cd 5.7.1.1.2 ), n_nF_Cd should be set to one (1) as it Float

becomes a multiplication factor of the materials’

Manning’s n values. It may be adjusted as part of
the calibration process.

The upstream bed or invert elevation of the culvert

in metres.

If a culvert invert has a value of 99999 (after any

application of node/pit DS_Invert values), the invert
7 US_Invert is interpolated by searching upstream and Float

downstream for the nearest specified inverts, and

the invert is linearly interpolated. Interpolate Culvert
Inverts can also be used to switch this feature ON
or OFF.

Sets the downstream invert of the culvert using the

8 DS_Invert same rules as for described for the US_Invert Float
attribute above.

Specifies an additional dynamic head loss

coefficient that is applied when the culvert flow is
not critical at the inlet. Note, this loss coefficient is
9 Form_Loss Float
not subject to adjustment when using Structure
Losses == ADJUST, and is ideally used to model
additional energy losses such as bend losses.

C, R Channel Type:
The percentage blockage (for 10%, enter 10) of the
culvert. For R culverts, the culvert width is reduced
by the % Blockage, while for C culverts the pipe
diameter is reduced by the square root of the %

10 pBlockage Blockage. Note that when applying a % Blockage to Float

C culverts, the invert level remains unchanged and
only the soffit level is reduced by the calculated
decrease in diameter.

I Channel Type:
Not used.

11 Inlet_Type Not used. Char(256)

12 Conn_1D_2D Not used. Char(4)

13 Conn_No Not used. Integer

Section 5 1D Network Domains - ESTRY - 26 / 130 Page 129 / 1094

 Default GIS
No. Description Type
Attribute Name

C Channel Type:
The pipe diameter in metres.

R Channel Type:
14 Width_or_Dia Float
The box culvert width in metres.

I Channel Type:
Not used.

R Channel Type:
The box culvert height in metres.
15 Height_or_WF Float
C, I, Channel Type:
Not used.

The number of culvert barrels. If set to zero, one

16 Number_of Integer
barrel is assumed.

I, R Channel Type:
The height contraction coefficient for orifice flow at
the inlet. Usually 0.6 for square edged entrances to
0.8 for rounded edges. If value exceeds 1.0 or is

17 HConF_or_WC less than or equal to zero, it is set to 1.0. Float

Not used for unsubmerged inlet flow conditions or
outlet controlled flow regimes.

C Channel Type:
Not used.

The width contraction coefficient for inlet-controlled

flow. Usually 0.9 for sharp edges to 1.0 for rounded
edges for R culverts. Normally set to 1.0 for C

18 WConF_or_WEx culverts. If value exceeds 1.0 or is less than or Float

equal to zero, it is set to 1.0 for C and 0.9 for R
culverts.

Not used for outlet controlled flow regimes.

Section 5 1D Network Domains - ESTRY - 27 / 130 Page 130 / 1094

 Default GIS
No. Description Type
Attribute Name

The entry loss coefficient for outlet controlled flow

(recommended value of 0.5). If value exceeds 1.0, it
is set to 1.0. If value is less than zero (0), it is set to
zero (0). If Structure Losses == ADJUST (the
default) or the A flag is used (see Table 5.29 ), this
value is adjusted according to the approach flow
velocity (see Section 5.8.7 ). If the culvert is
19 EntryC_or_WSa discharging out of a manhole, this attribute is Float
ignored and the entry loss used is that determined
by the upstream manhole based on the manhole
energy losses formulation (see Section 5.11.4 ).
The entry loss value used in the computation can
be viewed over time using the _TSL output layer
(see Section 15.3.4 ) or the QGIS TUFLOW
Viewer plugin.

The exit loss coefficient for outlet controlled flow

(recommended value of 1.0). If value exceeds 1.0, it
is set to 1.0. If value is less than zero (0), it is set to
zero (0). If Structure Losses == ADJUST (the
default) or the A flag is used (see Table 5.29 ), this
value is adjusted according to the departure velocity
(see Section 5.8.7 ). If the culvert is discharging
20 ExitC_or_WSb Float
into a manhole, this attribute is ignored and the exit
loss used is that determined by the downstream
manhole based on the manhole energy losses
formulation (see Section 5.11.4 ). The exit loss
value used in the computation can be viewed over
time using the _TSL output layer (see Section
15.3.4 ) or the QGIS TUFLOW Viewer plugin.

Section 5 1D Network Domains - ESTRY - 28 / 130 Page 131 / 1094

 @378 Table 5.6: 1D Culvert Flow Regime Flags

Regime Description

Unsubmerged entrance and exit. Critical flow at entrance. Upstream controlled with
A
the flow control at the inlet.

Submerged entrance and unsubmerged exit. Orifice flow at entrance. Upstream

B controlled with the flow control at the inlet. For circular culverts, not available for
Culvert Flow == Method A.

Unsubmerged entrance and exit. Critical flow at exit. Upstream controlled with the
C
flow control at the culvert outlet.

D Unsubmerged entrance and exit. Sub-critical flow at exit. Downstream controlled.

Submerged entrance and unsubmerged exit. Full pipe flow. Upstream controlled
E
with the flow control at the culvert outlet.

F Submerged entrance and exit. Full pipe flow. Downstream controlled.

G No flow. Dry or flap-gate active.

Submerged entrance and unsubmerged exit. Adverse slope. Downstream

H
controlled.

J Unsubmerged entrance and exit. Adverse slope. Downstream controlled.

Unsubmerged entrance and submerged exit. Critical flow at entrance. Upstream

K controlled with flow control at the inlet. Hydraulic jump along culvert. Not available
for Culvert Flow == Method A.

Submerged entrance and exit. Orifice flow at entrance. Upstream controlled with
L the flow control at the inlet. Hydraulic jump along culvert. Not available for
Culvert Flow == Method A.

@379

Figure 5.4: 1D Inlet Control Culvert Flow Regimes

@380

Section 5 1D Network Domains - ESTRY - 29 / 130 Page 132 / 1094

 Figure 5.5: 1D Outlet Control Culvert Flow Regimes

@381
5.8.1.1 Blockage Matrix

This feature allows for blockage of culverts to be varied based on the Average Recurrence Interval
(ARI) of the flood simulation. This applies to C (circular) and R (rectangular) type culverts. For
Australian users, this hydraulic structure blockage option is consistent with Project 11 of Australian
Rainfall & Runoff (Weeks et al., 2013 ).

Two different blockage methods are available:

1. The first method reduces the area in the culvert;

2. The second applies a modified energy loss value to account for the blockage.

Please refer to Ollett & Syme (2016 ) for background information on the loss approaches.

Each culvert can be assigned a blockage category, which is defined in the 1d_nwk pBlockage
attribute as a character field. A matrix of blockage category and percentage blockage for a range
of ARIs is defined. Please see Section 5.8.1.1.4 for guidance on implementation.

@382
5.8.1.1.1 Reduced Area Method

For the reduced area method, the culvert area is reduced to match the specified blockage in the
same manner as varying the pBlockage attribute on the 1d_nwk layer (refer to Table 5.5 ). For
example, with a blockage value of 10 the culvert area is reduced by 10%.

@383
5.8.1.1.2 Energy Loss Method

For this method the area of the culvert is not modified, however, an increased entrance energy
loss is applied. The modified energy loss is based on the specified culvert entry loss and the
blockage ratio as per equation (5.4) (Witheridge, 2009 ):

Section 5 1D Network Domains - ESTRY - 30 / 130 Page 133 / 1094

 2
@384 1 + √CELC
CELC_modif ied = ( − 1) (5.4)
BR

Where:

CELC_modif ied = Modified culvert entry loss value

CELC = Specified culvert entry loss value
BR = Blockage ratio (area of blocked culvert / area unblocked culvert)

When BR is 1 (unblocked), the modified entry loss coefficient becomes the specified entry loss
coefficient. The modified coefficients for a range of blockages are provided in Table 5.7 .

@389 Table 5.7: Computed Values of Modified Energy Loss Coefficient

CELC

0.3 0.5 0.7

Specified % BR CELC_modified
Blockage

0 1 0.3 0.5 0.7

10 0.9 0.5 0.8 1.1

25 0.75 1.1 1.6 2.1

50 0.5 4.4 5.8 7.1

75 0.25 27 34 40

90 0.1 210 260 300

95 0.05 900 1100 1280

100 0 ∞ ∞ ∞

Whilst loss values of greater than 1.0 may appear counter-intuitive, it is appropriate in this
situation. In conduit hydraulics there are two types of loss coefficients that are used to represent
constrictions, one type being applied to the velocity at the constriction itself (these are always
<=1), and the other type which are applied to the full-barrel velocity downstream of the blockage
where the loss coefficient may approach infinity. The second type is convenient as the velocity
downstream of the blockage is readily available and requires no manipulation of culvert geometry,
and follows in principle the same application of valve coefficients. The equation above simply
gives the conversion between these two types of loss coefficients.

Note: The minimum blockage ratio is set to 0.001 or 0.1%. This is required to avoid a divide by
zero error in the calculations. This loss method only applies when the culvert is operating
under outlet control. For an inlet control flow regime no energy loss is applied, the reduced area
method is used instead.

@390
5.8.1.1.3 Blockage Matrix Commands

The commands available for the Blockage Matrix method are listed in Table 5.8 .

Section 5 1D Network Domains - ESTRY - 31 / 130 Page 134 / 1094

 @391 Table 5.8: Commands for the Blockage Matrix Method

Command Description

Blockage Turns on or off the blockage matrix functionality outlined in this section. The
Matrix default is for this feature to be off.

Blockage Specifies a blockage file containing the blockage values for the various
Matrix File blockage categories and ARI values.

Specifies whether to use RAM (Reduced Area Method) or ELM (Energy

Blockage
Loss Method). No default approach is applied. This command must be
Method
specified if using the blockage matrix functionality.

Blockage ARI Specifies the ARI for the current simulation. This would typically be defined
in an event file (.tef).

Blockage Sets the blockage for all culverts with the specified blockage category. This
Override option is useful for running simulations under an “all clear” case.

Blockage Sets the blockage category for culverts that do not have a blockage type
Default specified (including those that have a numeric pBlockage defined)

If PMF has been specified in the ARI column of the blockage matrix, this
Blockage PMF
command sets an ARI to be used for the PMF. This allows for interpolation
ARI
of blockages for ARI values up to the PMF.

@392
5.8.1.1.4 Implementation

To make use of this feature the pBlockage attribute of the 1d_nwk GIS layer needs to be changed
from a float (numeric) type to a character field, with maximum width of 50. This has not been made
the default field type in the empty (template) files that TUFLOW produces, for two main reasons:

A character field is bigger and less efficient to read, this could slow down simulation start-up
for models not using the blockage categories; and
A numeric field (in almost all GIS packages) defaults to 0.0, i.e. no blockage. This is not the
case for a character field.

Instructions on how to change the GIS layer attribute type in QGIS, ArcMap and MapInfo are
provided in the TUFLOW Wiki as per the links below:

QGIS
ArcMap
MapInfo

For each culvert the pBlockage attribute can be set to either; a numeric value (in which case this
is used as per the standard simulation), a blockage category name (as a character string e.g. “A”),
or left blank (in which case the Blockage Default would apply). In the example below, the
pBlockage attribute has been set to a category named “B”.

Section 5 1D Network Domains - ESTRY - 32 / 130 Page 135 / 1094

 Each blockage category must be defined in the Blockage Matrix File. The first column should
contain the Average Recurrence Interval (ARI) for a range of events, any additional columns
contain percentage blockages for each of the ARIs. An example blockage matrix file is provided in
Table 5.9 containing 5 different blockage categories (A, B, C, D, E). For blockage category A the
culvert is unblocked for all ARIs, for category E the culvert is fully blocked for all ARIs. For the
categories B, C, and D the blockage varies by ARI.

If the specified ARI sits between the defined ARI values in the blockage matrix file a linear
interpolation is used. For example, in the table below for a 50-year ARI, blockage category “C” will
have a blockage of 13.75%.

@393 Table 5.9: Example Blockage Matrix File

ARI A B C D E

1 0 10 10 10 100

20 0 10 10 20 100

100 0 10 20 50 100

2000 0 20 50 70 100

10000 0 50 70 100 100

The ARI values for the blockage matrix file should be in ascending order. “PMF” can be defined in
the ARI column, if this is done, an ARI must be assigned to the PMF using the command Blockage
PMF ARI .

Example TUFLOW commands

.tcf file commands

Blockage Matrix == On
Blockage Matrix File == Matrix_Blockages.csv
Blockage Method == RAM
Blockage Default == C

.tef file commands

Section 5 1D Network Domains - ESTRY - 33 / 130 Page 136 / 1094

 Define Event == Q010
Blockage ARI == 10
BC Event Source == __ARI__ | Q010
End Define
Define Event == Q100
Blockage ARI == 100
BC Event Source == __ARI__ | Q100
End Define
Define Event == QPMF
Blockage ARI == 100000
BC Event Source == __ARI__ | PMF
End Define

A working example of a blockage matrix model is provided in the example models on the TUFLOW
Wiki.

@394
5.8.1.2 Limitations

For the energy loss method, the loss value only applies to the culverts when flowing in outlet
control flow regimes. When the flow conditions are inlet controlled TUFLOW reverts to using the
reduced area method. This is required, as there is no guidance how to adjust the contraction
coefficients or otherwise as used by the inlet controlled culvert equations.

@395
5.8.2 Bridges

@396
5.8.2.1 Bridges Overview

Bridge channels do not require data for length, Manning’s n, divergence or bed slope (they are
effectively zero-length channels, although the length is used for automatically determining nodal
storages – see Section 5.13.1.1 ). The bridge opening cross-section is described in the same
manner to a normal channel.

Two types of bridge channels can be specified:

“B” bridges require the user to specify an energy loss versus elevation table, usually derived
from loss coefficients in the literature such as “Hydraulics of Bridge Waterways” (Bradley,
1978 ) or “Guide to Bridge Technology Part 8, Hydraulic Design of Waterway Structures”
(Austroads, 2018 ). The energy loss table can be generated automatically via the 1d_nwk
Form_Loss attribute if the energy loss coefficient is constant up to the underside of the bridge
deck.
“BB” bridges automatically calculate the form (energy) losses associated with the approach
and departure flows as the water constricts and expands. It also automatically applies bridge
deck losses associated with pressure flow. The only user specified loss coefficients required
for BB bridges are the pier losses and the deck losses once fully submerged. If the pier loss
coefficient is constant through the vertical the coefficient can simply be specified via the
1d_nwk Form_Loss attribute as described further below.

Section 5 1D Network Domains - ESTRY - 34 / 130 Page 137 / 1094

 For B bridges, two bridge flow approaches are offered using Bridge Flow . Method B is an
enhancement on Method A by providing better stability at shallow depths or when wetting and
drying. There are also some subtle differences between the methods in how the loss coefficients
are applied at the bridge deck. This is discussed further below. Method B is the approach
recommended with Method A provided for legacy models. For Bridge Flow == Method A,
the underside of the bridge deck (the obvert or soffit) is taken as the elevation when the flow area
stops increasing, or the highest elevation in the bridge’s cross-section data, whichever occurs first.
For Bridge Flow == Method B, the highest (last) elevation in the cross-section table is
always assumed to be the underside of the bridge deck.

@397
5.8.2.2 Bridge Cross-Section and Loss Tables

The cross-sectional shape of the bridge is specified in the same manner as for open channels
using a 1d_xs GIS layer (refer to Section 5.7 and Table 5.4 ) and the command Read GIS Table
Links . The line is digitised midway across the 1d_nwk channel line (do not specify as an end
cross-section, i.e. a cross-section line snapped to an end of the bridge channel). As per the open
channel, the cross-section data can be in offset-elevation (XZ) or height-width (HW) format.

Bridge structures are modelled using a height varying form or energy loss coefficient. A table
(referred to as a Bridge Geometry “BG” or Loss Coefficient “LC” Table) of backwater or form loss
coefficient versus height is required. The interpretation of loss coefficients provided by the user
differs depending on whether the bridge channel is of a B or BB type as discussed in the following
sections.

BG Tables can be entered using .csv files via a 1d_bg GIS layer (see Table 5.11 ) using the
command Read GIS Table Links . A line is digitised crossing the 1d_nwk channel in the same
manner as for the 1d_xs GIS layer used to define the cross-sectional shape of the bridge. The line
does not have to be identical to the cross-section line.

Where the loss coefficient is constant through to the bridge deck (e.g. no losses such as a clear
spanning bridge, or pier losses only – see BB bridges), the BG table can automatically be created
by specifying a positive non-zero value for the Form_Loss attribute in the 1d_nwk layer (see Table
5.10 ). How the Form_Loss attribute is interpreted differs between B and BB bridge channels as
discussed in the following sections.

Any wetted perimeter or Manning’s n inputs in the hydraulic properties table are ignored. If the
flow is expected to overtop the bridge, a parallel weir channel should be included to represent the
flow over the bridge deck, or a BW or BBW channel can be specified (see Section 5.8.4.5 ).

@398
5.8.2.3 B Bridge Losses Approach

The coefficients for B bridges are usually obtained from publications such as “Hydraulics of Bridge
Waterways” (Bradley, 1978 ) or “Guide to Bridge Technology Part 8, Hydraulic Design of
Waterway Structures” (Austroads, 2018 ), through the following procedure.

The bridge opening ratio (stream constriction ratio), defined in Equations 1 and 2 of
“Hydraulics of Bridge Waterways” (Bradley, 1978 ), is estimated for various water levels from
the local geometry. Alternatively, the bridge opening ratio is estimated with the help of a trial
modelling run in which the stream crossed by the bridge is represented by a number of
parallel channels, providing a more quantitative basis for estimating the proportion of flow
obstructed by the bridge abutments.

Section 5 1D Network Domains - ESTRY - 35 / 130 Page 138 / 1094

 For each level this enables the value of Kb to be obtained from Figure 6 of “Hydraulics of
Bridge Waterways” (Bradley, 1978 ). Additional factors, for piers (Kp from Figure 7),
eccentricity (Ke from Figure 8) and for skew (Ks from Figure 10) make up the primary
contributors to Kb.
The backwater coefficient Kb input into the LC table is the sum of the relevant coefficients at
each elevation. The velocity through the bridge structure used for determining the head loss is
based on the flow area calculated using the water level at the downstream node.

Backwater coefficients derived in this manner have usually taken into account the effects of
approach and departure velocities (via consideration of the upstream and downstream cross-
section areas), in which case the losses for the B channel should be fixed. This is the default
setting or can be manually specified using the “F” flag (i.e. a “BF” channel) in the 1d_nwk Type
attribute, or use Structure Losses == ADJUST EXCEPT BG TABLES (the default).

For Bridge Flow == Method A, once the downstream water level is within 10% of the flow
depth under the bridge, a bridge deck submergence factor is phased in by applying a correction
for submerged decking using a minimum value of 1.5625 (if the specified loss coefficient is greater
than 1.5625, this value is applied). Bridge Flow == Method B does not use the 10% of the
flow depth phasing in nor applies a minimum loss coefficient once the bridge deck is submerged
(i.e. it applies the value as per the specified loss coefficients (BG) table). Method B relies on the
user to provide appropriate values at all flow heights.

The value of 1.5625 is derived from the following equation (5.5) presented in Waterway Design -
A Guide to the Hydraulic Design of Bridges, Culverts and Floodways (Austroads, 1994 ):

@399 Q = Cd bN Z√2gdH (5.5)

Where:

Q = Total discharge (m3/s)

Cd = Coefficient of discharge (0.8 for a surcharged bridge deck)
bN = Net width of waterway (m)
Z = Vertical distance under bridge to mean river bed (m)
dH = Upstream energy (or water surface) level minus downstream water surface level (m)
2
Q V
, where a Cd value
1
Assuming V =
bN Z
and dh = K
2g
, the equation rearranges to give K = 2
C
d

of 0.8 equates to a K energy loss value of 1.5625.

@404
5.8.2.4 BB Bridge Losses Approach

BB bridges break down the energy losses into the following categories:

Bridge pier losses;

Losses due to flow contraction and expansion;
Bridge deck losses when the bridge is submerged but not under pressure flow condition; and
If under pressure flow, the pressure flow equation is applied as described further below.

BB bridges differ from B bridges in that the losses due to flow contraction and expansion, and the
occurrence of pressure flow are handled automatically. The only loss coefficient required to be
specified is that due to piers (via the Form_Loss attribute value or a LC table). Other loss
parameters can be either set based on the default parameters, or can be specified by users. The
parameters used by the BB bridge routine are:

Section 5 1D Network Domains - ESTRY - 36 / 130 Page 139 / 1094

 Cd = the Bridge Deck surcharge coefficient (Default = 0.8).
DLC = the Deck loss coefficient (Default = 0.5) and only applies when no LC table exists and
an automatically generated table using the 1d_nwk Form_Loss attribute is created.
ELC = the unadjusted entry loss coefficient (Default = 0.5).
XLC = the unadjusted exit loss coefficient (Default = 1.0).

The .ecf command “Bridge Zero Coefficients == <CD>, <DLC>, <ELC>, <XLC>” can
be used to change the above default values to the user’s own default values.

The above values can also be changed for an individual bridge using the following 1d_nwk
attributes. If the attribute value is zero then the default value or the value specified by Bridge Zero
Coefficients is used.

CD = HConF_or_WC
DLC = WConF_or_WEx
ELC = EntryC_or_WSa
XLC = ExitC_or_WSb

The entrance and exit losses are adjusted every timestep according to the approach and
departure velocities based on the equations below from Section 5.8.7 . This approach yields
similar results to the approach for determining contraction and expansion losses in publications
such as “Hydraulics of Bridge Waterways” (Bradley, 1978 ) or “Guide to Bridge Technology Part
8, Hydraulic Design of Waterway Structures” (Austroads, 2018 ).

@405 Vapproach
CELC_adjusted = CELC [1 − ] (5.6)
Vstructure

2
@407 Vdeparture
CXLC_adjusted = CXLC [1 − ] (5.7)
Vstructure

Where:

V = Velocity (m/s)
C = Energy Loss Coefficient

Pressure flow is handled by transitioning from the equation described in the previous section (to
derive the K value of 1.5625 from a coefficient of discharge value of 0.8) to a fully submerged
situation where a deck energy loss is applied. The flux is calculated based on both the fully
submerged situation and the pressure flow situation, and the lesser of the two fluxes is applied.
The 1d_nwk HConF_or_WC attribute can be used to vary Cd (default value is 0.8) and the
WConF_or_WEx attribute to set the submerged deck loss coefficient. When pressure flow results
the “P” flag will appear in the .eof file and _TSF layer.

Optionally, LC tables can be specified for BB bridges. If a LC table exists, the Deck loss coefficient
(DLC) will be ignored, while the other 3 parameters (CD, ELC and XLC) are not affected. The LC
tables for BB bridges should therefore only be the losses due to piers and bridge decks. The LC
table should not include any losses for contraction, expansion and pressure flow. Note the
Form_Loss value is added to the LC table loss values.

If no LC table exists for the BB bridge, and the 1d_nwk Form_Loss attribute is greater than
0.0001, a LC table is automatically generated using Form_Loss for the pier losses and the
WConF_or_WEx for the Deck Loss coefficient (DLC).

Other notes are:

Section 5 1D Network Domains - ESTRY - 37 / 130 Page 140 / 1094

 BB bridges are only available if Structure Routines == 2013 (the default).
The unadjusted entry and exist losses (ELS and XLC) cannot be below 0 or greater than 1,
and will be automatically limited to these values.
_TSF and _TSL layers contain the following flags/values for BB bridges:
For normal flow (“ ” or “D” if drowned out): fixed / adjusted components
For Pressure (“P”) flow: Deck surcharge Coefficient / 0.0
Other flags:
“U” for upstream controlled flow – only occurs when downstream water level is below
the bridge bed level.
“Z” for zero or nearly zero flow.

Section 5 1D Network Domains - ESTRY - 38 / 130 Page 141 / 1094

 @409 Table 5.10: Bridges: 1D Model Network (1d_nwk) Attribute Descriptions

Default GIS
No. Description Type
Attribute Name

Unique identifier up to 12 characters in length. It

may contain any character except for quotes and
commas, and cannot be blank. As a general rule,
1 ID spaces and special characters (e.g. “\”) should be Char(12)
avoided, although they are accepted. The same ID
can be used for a channel and a node, but no two
nodes and no two channels can have the same ID.

2 Type “B” or “BB” as specified in Table 5.1 . Char(4)

If a “T”, “t”, “Y” or “y” is specified, the object will be

3 Ignore ignored (T for True and Y for Yes). Any other entry, Char(1)
including a blank field, will treat the object as active.

If left blank or set to Yes (“Y” or “y”) or True (“T” or

“t”), the storage based on the width of the channel
UCS
over half the channel length is assigned to both of
(Use Channel
4 the two nodes connected to the channel. If set to Char(1)
Storage at
No (“N” or “n”) or False (“F” or “f”), the channel
nodes).
width does not contribute to the node’s storage.
See Section 5.13 for further discussion.

Only used in determining nodal storages if the UCS

5 Len_or_ANA attribute is set to “Y” or “T”. Not used in conveyance Float
calculations.

6 n_nF_Cd Not used. Float

Sets the upstream and downstream inverts. Note

that the invert is taken as the maximum of the
7 US_Invert Float
US_Invert and the DS_Invert attributes. Use -99999
to use the bed of the cross-section as the invert.

Sets the downstream invert of the channel using

8 DS_Invert the same rules as for described for the US_Invert Float
attribute above.

Section 5 1D Network Domains - ESTRY - 39 / 130 Page 142 / 1094

 Default GIS
No. Description Type
Attribute Name

If a LC table exists, for BB bridges adds the value

specified to the loss coefficients in the LC table. Not
added to LC tables for B bridges.

If no LC table exists, and the value is greater than

zero, TUFLOW automatically generates a LC table
of constant loss coefficient up until the bridge deck
(i.e. the top of the cross-section). The interpretation
of the LC table generated from the Form_Loss
value differs depending on whether a B or a BB
bridge as follows:

For B bridges (with no LC table):

The Form_Loss (LC value) is not subject to

adjustment when using Structure Losses
== ADJUST.
Above the underside of the bridge deck (the
top of the cross-section) a value of 1.5625 is
used, with the 1.5625 less the Form_Loss
value is subject to adjustment when using
Structure Losses == ADJUST.
9 Form_Loss Float
For BB bridges (with no LC table):

The Form_Loss (LC value) is only used to

apply pier losses. Contraction/expansion
losses and bridge deck pressure flow losses
are automatically calculated.
Once the bridge deck is fully submerged (and
no longer under pressure flow) the
WConF_or_WEx attribute is used to set the
additional losses due to the bridge deck.

Note: Due to the potential for a divide by zero, a

zero loss value cannot be specified with no LC
table. A loss value of 0 will return ERROR 1422. A
minimum loss value of 0.01 for B bridges or 0.001
for BB bridges is required by TUFLOW to ensure a
divide by zero does not occur. Specifying a loss
value equal to or less than these minimums (but not
0) will apply these minimum losses, i.e. to apply
these minimum losses specify a value of 0.001 for
either B or BB bridges.

Section 5 1D Network Domains - ESTRY - 40 / 130 Page 143 / 1094

 Default GIS
No. Description Type
Attribute Name

Not used. Reserved for future builds to fully or

partially block B channels. The 1d_xs Skew
10 pBlockage Float
attribute can be used to partially block cross-
sections of these channels – see Table 5.4 .

Leave blank unless using the legacy MIKE 11 1D

11 Inlet_Type Char(256)
cross-section data feature.

Leave blank unless using the legacy MIKE 11 1D

cross-section data feature, or if accessing a Flood
12 Conn_1D_2D Char(4)
Modeller cross-section database (.pro file), enter
the label in the .pro file.

Leave blank unless using the legacy MIKE 11 1D

13 Conn_No Integer
cross-section data feature.

14 Width_or_Dia Not used. Float

15 Height_or_WF Not used. Float

16 Number_of Not used. Integer

B bridges: Not used.

17 HConF_or_WC BB bridges: Bridge deck pressure flow contraction Float

coefficient (Cd). If set to zero the default of 0.8 or
that specified by Bridge Zero Coefficients is used.

B bridges: Not used.

BB bridges: Bridge deck energy loss coefficient

18 WConF_or_WEx (DLC) for fully submerged flow. If set to zero the Float

default of 0.5 or that specified by Bridge Zero

Coefficients is used.

B bridges: Not used.

19 EntryC_or_WSa BB bridges: Unadjusted entrance energy loss Float

coefficient (ELC). If set to zero the default of 0.5 or
that specified by Bridge Zero Coefficients is used.

B bridges: Not used.

20 ExitC_or_WSb BB bridges: Unadjusted exit energy loss coefficient Float

(XLC). If set to zero the default of 1.0 or that
specified by Bridge Zero Coefficients is used.

Section 5 1D Network Domains - ESTRY - 41 / 130 Page 144 / 1094

 @410 Table 5.11: 1D Bridge Geometry Table Link (1d_bg) Attribute Descriptions

Default GIS
No. Attribute Description Type
Name

Filename (and path or relative path if needed) of the

1 Source file containing the tabular data. Must be a comma or Char(50)
space delimited text file such as a .csv file.

“BG” or “LC”: Bridge energy loss coefficients (second

2 Type column) versus elevation (first column) for bridge Char(2)
structures.

3 Flags No optional flags. Char(8)

Optional. Identifies a label in the Source file that is the

header for the first column of data (ie. elevation).
Values are read from the first number encountered

4 Column_1 below the label until a non-number value, blank line or Char(20)
end of the file is encountered.

If this field is left blank, the first column of data in the

Source file is used.

Optional. Identifies a label in the Source file that is in

the header for the second column of data (ie. loss

5 Column_2 coefficient). Char(20)

If this field is left blank, the next column of data after

Column_1 is used.

6 Column_3 Not used. Char(20)

7 Column_4 Not used. Char(20)

8 Column_5 Not used. Char(20)

9 Column_6 Not used. Char(20)

10 Z_Increment Not used. Float

11 Z_Maximum Not used. Float

Skew
12 Not used. Float
(in degrees)

@411
5.8.3 Arch Bridge

The 2023-03 release introduced support for arch bridges as 1D channels. The approach is based
on the ‘Afflux at Arch Bridges’ (HR Wallingford, 1988 ). Arch bridges are defined in the 1d_nwk
layer as a “BArch” type. The 1d_nwk attributes specific to an arch bridge are outlined below in
Table 5.12 .

Section 5 1D Network Domains - ESTRY - 42 / 130 Page 145 / 1094

 @412 Table 5.12: Arch Bridges 1D Model Network (1d_nwk) Attribute Descriptions

Default GIS
No. Description Type
Attribute Name

Unique identifier up to 12 characters in length. It

may contain any character except for quotes and
commas, and cannot be blank. As a general rule,
1 ID spaces and special characters (e.g. “\”) should be Char(12)
avoided, although they are accepted. The same ID
can be used for a channel and a node, but no two
nodes and no two channels can have the same ID.

2 Type “BArch” as specified in Table 5.1 . Char(4)

If a “T”, “t”, “Y” or “y” is specified, the object will be

ignored (T for True and Y for Yes). Any other entry,
3 Ignore Char(1)
including a blank field, will treat the object as
active.

If left blank or set to Yes (“Y” or “y”) or True (“T” or

“t”), the storage based on the width of the channel
UCS over half the channel length is assigned to both of
4 (Use Channel the two nodes connected to the channel. If set to Char(1)
Storage at nodes). No (“N” or “n”) or False (“F” or “f”), the channel
width does not contribute to the node’s storage.
See Section 5.13 for further discussion.

Only used in determining nodal storages if the

5 Len_or_ANA UCS attribute is set to “Y” or “T”. Not used in Float
conveyance calculations.

6 n_nF_Cd Not used. Float

Sets the upstream and downstream inverts. Note

that the invert is taken as the maximum of the
7 US_Invert US_Invert and the DS_Invert attributes. Use Float
-99999 to use the bed of the cross-section as the
invert.

Sets the downstream invert of the channel using

8 DS_Invert the same rules as for described for the US_Invert Float
attribute above.

9 Form_Loss Not used. Float

10 pBlockage Not used. Float

The relative path to the arch properties file (must

11 Inlet_Type Char(256)
be a .csv file). See Section 5.9.1 .

12 Conn_1D_2D Not used. Char(4)

13 Conn_No Not used. Integer

14 Width_or_Dia Optional skew parameter. Float

Section 5 1D Network Domains - ESTRY - 43 / 130 Page 146 / 1094

 Default GIS
No. Description Type
Attribute Name

15 Height_or_WF Optional calibration coefficient. Float

16 Number_of Not used. Integer

Discharge coefficient for orifice flow - use negative

17 HConF_or_WC Float
value to switch on.

18 WConF_or_WEx Not used. Float

19 EntryC_or_WSa Lower transition distance for orifice flow. Float

20 ExitC_or_WSb Upper transition distance for orifice flow. Float

The .csv for the arch properties should contain the columns outlined in Table 5.13 .

@413 Table 5.13: Arch Bridge Properties .csv

Column Description

1 Start chainage for arch opening.

2 End chainage for arch opening.

3 Springing level.

4 Start chainage for arch opening.

@414
5.8.3.1 Arch Bridge Editor

An arch bridge creator and editor tool has been developed for the QGIS TUFLOW Plugin. This tool
is available from the TUFLOW Plugin Version 3.7 or later. The documentation and examples for
this tool can be found on the TUFLOW Wiki.

@415

Figure 5.6: Arch Bridge Editor Tool

Section 5 1D Network Domains - ESTRY - 44 / 130 Page 147 / 1094

 @416
5.8.3.2 Arch Minimum Blockage

The flume experiments in the ‘Afflux at Arch Bridges’ (HR Wallingford, 1988 ) were done using
medium to high bridge blockages (20%~70%), and this approach can generate extremely high
velocity when the bridge blockage is close to zero percent. The 2023-03-AF release introduced a
minimum blockage of 5% to stabilise the flow. This default value can be changed using the
following command:

Arch Bridge Minimum Blockage (%) == <min_pblockage>

@417
5.8.4 Weirs

@418
5.8.4.1 Weirs Overview

A range of weir types are available as listed in Table 5.14 . Weir channels do not require data for
length, Manning’s n, divergence or bed slope (they are effectively zero-length channels, although
the length is used for automatically determining nodal storages – see Section 5.13.1.1 ).

All weirs have three flow regimes of zero flow (dry), upstream controlled flow (unsubmerged) and
downstream controlled flow (submerged).

@419 Table 5.14: Weir Types

Weir
Description
Type

The original ESTRY weir based on the broad-crested weir formula with the Bradley
W submergence approach (see Weir Approach == METHOD A). The weir shape is
defined either as a rectangle using the 1d_nwk Width attribute or as a cross-section.

WB Broad-crested weir. A rectangular section shape is assumed.

WC Crump weir.

WD User-defined weir.

WO Ogee-crested weir.

WR Rectangular weir (sharp crested).

WT Trapezoidal weir or Cippoletti weir.

WV V-notch weir.

Similar to the original W weir channel, but has more options allowing the user to
WW customise the weir sub-mergence curve and other parameters. Can be based on
either a rectangular shape using the 1d_nwk Width attribute or on a cross-section.

@420
5.8.4.2 Original Weirs (W)

For a “W” type weir, a standard weir flow formula is used as per the equation below. The weir is
assumed to be broad-crested. Weirs with different characteristics should be modelled using one of
the other weir types listed in Table 5.14 and discussed in Section 5.8.4.3 .

Section 5 1D Network Domains - ESTRY - 45 / 130 Page 148 / 1094

 @421 2 2g 3

Qweir = CW √ H 2
(5.8)
3 Cf

@423 2 2gH
Vapproach = C√ (5.9)
3 Cf

Where:

Qweir = Unsubmerged flow over the weir (m3/s)

Vapproach = Velocity approaching the weir (m/s)
C = Broad-crested weir coefficient of 0.57
W = Flow width (m)
Cf = Weir calibration factor (default of 1.0 – refer to 1d_nwk “Height_or_WF” attribute)
H = Depth of water approaching the weir relative to the weir invert (m)

The calibration factor Cf, is available for modifying the flow. For a given approach velocity the
backwater (head increment) of the weir channel is proportional to the inverse of the factor. It is
normally set to 1.0 by default and modified if required for calibration or other adjustment. Note, this
factor is not the weir coefficient, rather a calibration factor to adjust the standard broad-crested
weir equation. The factor can be used to model other types of weirs through adjustment of the
broad-crested weir equation, although use of the other weir types listed in Table 5.14 is
recommended.

Huxley (2004 ) contains benchmarking of unsubmerged and submerged weir flow to the
literature.

Note that the velocity output for a weir is the approach velocity, Vapproach, in the above equations,
not the velocity at critical depth (when the flow is unsubmerged).

For submergence of W weir channels, it is recommended that Weir Approach is set to METHOD
A or METHOD C. Both METHOD A and METHOD C utilises the Bradley submergence approach
(METHOD C is a slight enhancement that only affects WW weir channels). The Bradley
Submergence approach (Bradley, 1978 ), Figure 24, is handled by fitting the equation below to
Bradley’s submergence curve reproduced in Figure 5.7 and applying the submergence factor to
the weir equation above.

Once the percentage of submergence exceeds 70%, the submergence factor applied is given by
the equation below (5.10) . The Bradley curve (as digitised) and the resulting curve from the
equation below are shown alongside the submergence curves used for other weir types. The
submergence factor transitions the flow from weir flow to zero flow as the water level difference
(dH) approaches zero.

20
@431 dH
Csf = 1 − (1 − ) (5.10)
H

Weir Approach == METHOD B was introduced to provide additional stability for 1D flow over
roadways connected to 2D domains, however, it can cause excessive head drops under drowned
flow conditions and is therefore not recommended or to be used with caution. METHOD B only
applies to the W weir.

@433

Section 5 1D Network Domains - ESTRY - 46 / 130 Page 149 / 1094

 Figure 5.7: Bradley Weir Submergence Curve (Bradley, 1978 )

@434
5.8.4.3 Advanced Weirs (WB, WC, WD, WO, WR, WT, WV, WW)

The advanced weirs, as listed in Table 5.14 , offer greater variety, flexibility and can be
customised by the user. Most of these weirs can also be operated, see Section 5.10 .

The weir flow is determined by the following equation.

@435 Q =
2
Cf C C d W √2g H
Ex
(5.11)
3 sf

Where:

Q = Flow over the weir (m3/s)

Cd = Weir coefficient
Csf = Weir submergence factor
Cf = Weir calibration factor (default of 1.0 – refer to 1d_nwk “Height_or_WF” attribute)
W = Flow width (m)
H = Upstream water surface or energy depth relative to the weir invert (m) – see note 5
below
Ex = Weir flow equation exponent

Notes

1. The default values for Cd are provided in Table 5.15 , and documented further below for
weirs where Cd is recalculated each timestep.

Section 5 1D Network Domains - ESTRY - 47 / 130 Page 150 / 1094

 2. The approach taken for calculating the weir submergence factor Csf each timestep is
documented below.
3. The weir calibration factor, Cf, is by default 1.0 and should only be changed should there be a
good justification.
4. For weirs where the flow width (W) varies (e.g. a V-notch WV weir) the formula for that weir
takes into account the varying width.
5. Whether water surface depth or the energy level is used for H depends on the Structure Flow
Levels setting, which can be changed on a structure by structure case using the E or H flag
(see Table 5.2 ).
6. The default values for Ex are provided in Table 5.15 .

Table 5.15 presents the weir coefficient Cd and weir flow exponent Ex used for each weir. Some
of these values are derived from dimensional forms of the weir equations. Values other than the
default values shown in Table 5.15 may be used by altering the attributes of the 1d_nwk layer.
Refer to Table 5.16 for further information.

Note that Cd for WO and WV weirs is recalculated every timestep as described in the following
sections. It is possible to override this by specifying a non-zero positive value for the
“HConF_or_WC” attribute in the 1d_nwk layer. For WD weirs the user must specify a non-zero
positive value.

The value for Cf × Cd and Csf is written to the TSL_P output (see Section 15.3.4 ) at each
timestep.

Section 5 1D Network Domains - ESTRY - 48 / 130 Page 151 / 1094

 @450 Table 5.15: Default Attribute Values for the Weir Equation for Different Weir Flow

D
S

Channel Cd Ex a b C

Type (HConF_or_WC) (WConF_or_WEx) (EntryC_or_WSa) (ExitC_or_WSb) (

a
5

O
(
SP 0.75 1.5 6.992 0.648
U
)

B
f
S
WB 0.577 1.5 8.550 0.556
Q
1
1

C
WC 0.508 1.5 17.870 0.590 H
(

U
WD User Defined 1.5 3.000 0.500 d
s

O
Recalculated (
WO 1.5 6.992 0.648
every timestep U
)

S
T
WR 0.62 1.5 2.205 0.483 f
1
1

S
T
WT 0.63 1.5 2.205 0.483 f
1
1

S
T
Recalculated
WV 2.5 2.205 0.483 f
every timestep
1
1

Section 5 1D Network Domains - ESTRY - 49 / 130 Page 152 / 1094

 D
S

Channel Cd Ex a b C

Type (HConF_or_WC) (WConF_or_WEx) (EntryC_or_WSa) (ExitC_or_WSb) (

a
5

B
B
WW 0.542 1.5 21.150 0.627
(

@451
5.8.4.3.1 Ogee Crest Weir (WO)

For WO (Ogee crest) weirs, the charts developed in USBR (1987 ) are used by fitting the
relationship presented and plotted on the USBR curve below (Figure 5.8 ). The relationship falls
within ±0.5% of the curve. Note that the relationship below is for US Customary Units, which is
converted to metric if running the simulation in metric units. The USBR (1987 ) method consists
of two steps:

The ogee crest coefficient C0 (i.e. the discharge coefficient when the actual upstream head
He = design head H0 ) is set based on H0 and the height of the weir above its sill (P ) as per
Figure 9-23 of USBR (1987 ). Note that for setting the value of P the absolute difference in
height between the US_Invert and DS_Invert attributes is used.

@458

Figure 5.8: Ogee Spillway Discharge Coefficient, based on Figure 9-23 (USBR, 1987 )

When the actual head (He ) is different from the design head (H0 ) during the simulation, the
discharge coefficient differs from that shown on Figure 5.8 . At each simulation timestep, the
discharge coefficient is adjusted based on /
He H0 as per the chart below. The final discharge
coefficient applied is C0 × /
C C0 in this chart.

Section 5 1D Network Domains - ESTRY - 50 / 130 Page 153 / 1094

 @466

Figure 5.9: Adjustment of Discharge Coefficient based on /

He H0 , Figure 9-24 (USBR, 1987
)

Three options to calculate the final discharge coefficient are offered based on the input value of
the 1d_nwk HConF_or_WC attribute:

If the discharge coefficient has already been obtained by hand calculation, a positive
HConF_or_WC value can be used to apply a constant discharge coefficient, i.e. C = C0 =
HConF_or_WC.
If the design head (H0 ) is known for an ogee crest weir, a negative HConF_or_WC value can
be used to specify H0 . The two-step USBR (1987 ) method stated above will be applied to
estimate the final discharge coefficient. Note this option is only available in the 2023-03-AB
build or later.
If HConF_or_WC is zero (0) or left as blank (the default), the actual head He at each
simulation timestep will be used to estimate C from Figure 9-23 of USBR (1987 ), with no
further adjustment based on Figure 9-24 of USBR (1987 ). This approach should be used
when the design head (H0 ) is unknown.

@476
5.8.4.3.2 V-Notch Weir (WV)

For WV (V-notch) weirs, the approach taken is to use the formulae derived by LMNO Engineering
as shown below. For metric models the flow is calculated in ft3/s and converted to m3/s. The top
height of a V-notch weir cannot be specified, the angle continues with the increasing water level.

Section 5 1D Network Domains - ESTRY - 51 / 130 Page 154 / 1094

 @477
5.8.4.4 Advanced Weir Submergence Curves

Weir submergence factors Csf were sought from two sources: “Discharge Characteristics” (Miller,
1994 ) and “Discharge Measurement Structures” (Bos, 1989 ). The submergence charts for
each weir type, relating the weir submergence factor to the ratio between downstream and
upstream water level were reproduced from the literature in Excel and are shown in Figure 5.11 .

Two methods were utilised to fit equations to these curves. These are:

The Rational Function expressed as:

@479 a + b(
Hd
)
Hu

Csf = (5.12)
2
Hd Hd
1 + c( ) + d( )
Hu Hu

The Villemonte equation, expressed as:

@481 a b
Hd
Csf = (1 − ( ) ) (5.13)
Hu

Where:

Hu = Upstream energy or water level above the weir crest (m or ft)

Hd = Downstream energy or water level above the weir crest (m or ft)
a, b = Model coefficients

“Discharge Measurement Structures” (Bos, 1989 ) applies upstream energy and downstream
water level to calculate Csf . This can be specified globally using the Structure Flow Levels
== ENERGY UPSTREAM command (the default option is “ENERGY”, which uses energy level
both upstream and downstream). It can also be changed for individual weirs using the “EH” flag in
the 1d_nwk “Type” attribute, e.g. “WB EH”.

For each submergence curve, the above equations were solved to obtain values for each of the
variables that produced the best fit with the curves provided in the literature. After a comparison of
the results, the equation from Villemonte was chosen for several reasons:

The Rational Function was found to be sensitive to variables and therefore required a greater
number of decimal places. Villemonte was found to provide accurate results with variables
requiring only 2 decimal places.
The Villemonte equation contains only two variables, compared to four used in the Rational
Function, making it simpler and less susceptible to error.
The Villemonte equation may be solved exactly at the extremities of the curves (i.e. where
Hd Hd

Hu
= 1 and Csf = 0 , and when Hu
= 0 and Csf = 1 ). The Rational Function required
further manipulation through inclusion of additional points to achieve this outcome.

The default variables a and b used to determine the submergence factor Csf for each weir type
are presented in Table 5.15 . Figure 5.11 shows the submergence curves produced using the
default values in Table 5.15 to calculate C sf .

@493

Section 5 1D Network Domains - ESTRY - 52 / 130 Page 155 / 1094

 Figure 5.10: Weir Submergence Curves from the Literature
@494

Figure 5.11: Weir Submergence Curves using Villemonte Equation

Section 5 1D Network Domains - ESTRY - 53 / 130 Page 156 / 1094

 @495 Table 5.16: Weirs: 1D Model Network (1d_nwk) Attribute Descriptions

Default GIS
No. Description Type
Attribute Name

Unique identifier up to 12 characters in length. It

may contain any character except for quotes and
commas, and cannot be blank. As a general rule,
1 ID spaces and special characters (e.g. “\”) should be Char(12)
avoided, although they are accepted. The same ID
can be used for a channel and a node, but no two
nodes and no two channels can have the same ID.

The weir channel type as specified using the flags

2 Type in Table 5.1 and 5.14 . For example, a V-notch Char(4)
weir would be entered as “WV”.

If a “T”, “t”, “Y” or “y” is specified, the object will be

ignored (T for True and Y for Yes). Any other entry,
3 Ignore Char(1)
including a blank field, will treat the object as
active.

If left blank or set to Yes (“Y” or “y”) or True (“T” or

“t”), the storage based on the width of the channel
UCS over half the channel length is assigned to both of
4 (Use Channel the two nodes connected to the channel. If set to Char(1)
Storage at nodes) No (“N” or “n”) or False (“F” or “f”), the channel
width does not contribute to the node’s storage.
See Section 5.13.1.1 for further discussion.

The length of the weir channel, not the weir crest.

Only used for automatically determining the
storage at the nodes if the UCS attribute is set to
5 Len_or_ANA Float
“Y” or “T”. Not used in the conveyance calculations.
If a no attribute is specified, the length of the
digitised line is used.

6 n_nF_Cd Not used. Float

Section 5 1D Network Domains - ESTRY - 54 / 130 Page 157 / 1094

 Default GIS
No. Description Type
Attribute Name

All Weir (excluding WO) Channel Types:

Sets the weir invert. Note that the invert is taken as
the maximum of the US_Invert and the DS_Invert
attributes. For W and WW weirs use -99999 to use
the bed of the cross-section (if one exists) as the
invert or weir crest.

WO Channel Type:
7 US_Invert The absolute difference in height between the Float

US_Invert and DS_Invert is used to set the height

of the weir above its sill (usually denoted as P),
which is used for recalculating the weir’s discharge
coefficient each timestep. If the US_Invert and
DS_Invert are the same value the primary
upstream channel bed will be used to set the value
of P.

8 DS_Invert See comments above for US_Invert. Float

9 Form_Loss Not used. Float

W Channel Type:
Not used. Reserved for future builds to fully or
partially block W channels. The 1d_xs Skew
attribute can be used to partially block cross-
sections of these channels - see Table 5.4 .

WB, WC, WD, WO, WR, and WS Channel Type:

The weir width is adjusted proportionally by the %
10 pBlockage blockage. Float

WT Channel Type:
The base width of the weir is adjusted
proportionally by the % blockage.

WV Channel Type:
The V-notch angle is adjusted proportionally by the
% blockage.

Leave blank unless using the legacy MIKE 11 1D

11 Inlet_Type Char(256)
cross-section data feature.

Leave blank unless using the legacy MIKE 11 1D

cross-section data feature, or if accessing a Flood
12 Conn_1D_2D Char(4)
Modeller cross-section database (.pro file), enter
the label in the .pro file.

Leave blank unless using the legacy MIKE 11 1D

13 Conn_No Integer
cross-section data feature.

Section 5 1D Network Domains - ESTRY - 55 / 130 Page 158 / 1094

 Default GIS
No. Description Type
Attribute Name

All Weir (excluding WT and WV) Channel Types:

The weir width in metres. The maximum of
US_Invert and DS_Invert is used in conjunction
with the Width_or_Dia attribute to define a
rectangular section 5m (16.4ft) high. The automatic
height given to the weir of 5m (16.4ft) so that the
generation of node storage areas from channel
widths are within a realistic range of elevations.
Use Depth Limit Factor to allow water levels to
exceed the 5m (16.4ft) range if required.

Note: For W and WW weirs if a cross-section for

14 Width_or_Dia the channel exists, the cross-section profile will Float

prevail over the automatic rectangular shape. Note:

For operational weirs, the width of the weir when
fully open.

WT Channel Type:
The width at the base of the trapezoidal weir. WT
weirs are Cippoletti weirs that have side slopes of 1
horizontal to 4 vertical.

WV Channel Type:
Angle of the V-notch in degrees. Must be between
20º and 100º.

For non-operated weirs, this value can be used

as a weir coefficient adjustment factor to be
primarily used for model calibration or sensitivity
testing. The weir coefficient is multiplied by this
value. The resulting weir coefficient can be viewed
15 Height_or_WF in the .eof file and over time in the _TSL GIS layer. Float

If zero or negative an adjustment factor of 1.0

(i.e. no adjustment) is applied.

For operational weirs, the height of the weir

above the crest when fully up.

16 Number_of Not used. Integer

Section 5 1D Network Domains - ESTRY - 56 / 130 Page 159 / 1094

 Default GIS
No. Description Type
Attribute Name

W Channel Type:
Not used.

All Weir (excluding W) Channel Types:

Weir coefficient, Cd, in its dimensionless form. If
less than or equal to zero the default value for the
weir type in Table 5.15 is used.

Note that for WV weirs the default is to recalculate

Cd every timestep. Entering a value greater than
zero (0) will override this and apply a fixed Cd.

For WO weirs, the default is to recalculate Cd

every timestep based on the actual head, while

17 HConF_or_WC entering a value less than zero (0) will specify a Float
design head for Cd calulation. Entering a value
greater than zero (0) will apply a fixed Cd. Please
see Section 5.8.4.3.1 for the detailed ogee crest
weir approach.

For WD weirs the user must specify a non-zero

positive value.

Note that published weir coefficients may be based

on other non-dimensional or dimensional forms of
the weir equation, therefore care should be taken
in ensuring the coefficient is compatible with the
form of the weir flow equation presented in Section
5.8.4.3 .

W Channel Type:
Not used.

All Weir (excluding W) Channel Types:

18 WConF_or_WEx Weir flow equation exponent Ex in the weir flow Float

equation presented in Section 5.8.4.3 . If less than
or equal to zero the default value for the weir type
in Table 5.15 is used. The default value is 1.5 for
all weir types except for WV which is 2.5.

W Channel Type:
Not used.

All Weir (excluding W) Channel Types:

Sets the submergence factor “a” exponent in the
19 EntryC_or_WSa Villemonte Equation for calculating the weir Float

submergence factor Csf (refer to equations in

Section 5.8.4.3 and 5.8.4.4 ). If less than or
equal to zero the default value for the weir type in
Table 5.15 is used.

Section 5 1D Network Domains - ESTRY - 57 / 130 Page 160 / 1094

 Default GIS
No. Description Type
Attribute Name

W Channel Type:
Not used.

All Weir (excluding W) Channel Types:

Sets the submergence factor “b” exponent in the
20 ExitC_or_WSb Villemonte Equation for calculating the weir Float

submergence factor Csf (refer to equations in

Section 5.8.4.3 and 5.8.4.4 ). If less than or
equal to zero the default value for the weir type in
Table 5.15 is used.

@496
5.8.4.5 Automatically Created Weirs

Weirs representing overtopping of structures such as culverts and bridges may be automatically
created without the need to digitise a separate line within a 1d_nwk layer. The structure must be
digitised within a 1d_nwke layer (as opposed to a 1d_nwk layer) and a “W” specified alongside the
original structure type. For example, to model a bridge and a weir representing overtopping of the
road deck, specify type “BW”. The weir crest level and dimensions are specified within the
additional attributes contained within a 1d_nwke layer and are explained in Table 5.17 . The
original W weir approach is adopted for calculating the flow (see Section 5.8.4.2 ).

The weir’s shape is assumed to be two rectangles on top of each other. The lower rectangle is
reduced in width according to the percent blockage applied to the rail (i.e. the EN4 attribute in
Table 5.17 ), and its height is the EN3 attribute. The upper rectangle is the full flow width and
extends indefinitely in the vertical.

Alternatively, the flow over a structure can be manually digitised as a separate 1d_nwk weir
channel parallel to the original bridge or culvert structure (i.e. the weir is connected to the ends of
the bridge/culvert). Any of the available weir types can be used in this instance.

Section 5 1D Network Domains - ESTRY - 58 / 130 Page 161 / 1094

 @497 Table 5.17: 1D Model Network (1d_nwke) OPTIONAL Attribute Descriptions

Default GIS
No. Attribute Description Type
Name

21 ES1 Not yet used (leave blank). Char(50)

22 ES2 Not yet used (leave blank). Char(50)

For BW, CW and RW channels, the flow width of weir (m)

over the top of the B, C or R structure. If < 0.001, uses
23 EN1 Float
width multiplied by the number of culverts attribute for C
and R channels.

For BW, CW and RW channels, the depth (m) of the

bridge deck or culvert overlay. The weir level is set using
24 EN2 the average of the upstream and downstream obverts Float
plus the EN2 value. The level can be confirmed using the
inverts_check file.

For BW, CW and RW channels, the depth of the hand rail

25 EN3 (m). If < 0.001 assumes solid or no rail, depending on the Float
EN4 attribute entry.

For BW, CW and RW channels, % blockage of the rail

26 EN4 (e.g. 100 for solid rail, 50 for partially blocked, 0 for no Float
rail).

For BW, CW and RW channels, the weir calibration

27 EN5 Float
factor. Is set to 1.0 if < 0.001 is specified.

28 EN6 Not yet used (leave as zero). Float

29 EN7 Not yet used (leave as zero). Float

30 EN8 Not yet used (leave as zero). Float

@498
5.8.4.6 VW Channels (Variable Geometry Weir)

The VW (variable weir) channel allows the modeller to vary the cross-section geometry of a W
weir over time using a trapezoidal shape. To set up a VW channel follow the steps below.

In the 1d_nwk layer, the following attributes are required:

ID = ID of the channel;
Type = “VW”;
Len_or_ANA = Nominal length in m (only used for calculating nodal storage if UCS is on);
US_Invert = -99999 (the invert level is specified in the .csv file discussed below);
DS_Invert = -99999 (the invert level is specified in the .csv file discussed below);
Inlet_Type = relative path to a .csv file containing information on how the weir geometry
varies; and
Height_Cont = Trigger Value (the upstream water level to trigger the start of the failure;
upstream water level is determined as the higher water level of the upstream and downstream
nodes).

Section 5 1D Network Domains - ESTRY - 59 / 130 Page 162 / 1094

 The .csv file must be structured as follows (also see example below):

1. TUFLOW searches through the sheet until more than 4 numbers are found at the beginning of
a row (Row 2 in the example below).
2. Each row of values is read until the end of the file or a row with no or less than four numbers
is found. There is no limit on the number of rows of data.
3. The four columns must be as follows and in this order. The labels for the columns are
optional.
i. Time from start of breach in hours.
ii. Weir bed level in metres.
iii. Weir bed width in metres.
iv. Side slope (enter as the vertical distance in metres for one metre horizontal). For
example, a value of 0.5 means a slope of two horizontal to one vertical.

In the example below, the weir once triggered will erode from a bed level of 270m to 254m, widen
from a bed width of 0 to 20m and the side slope will remain constant at 0.5. The period of time for
the erosion is 0.5hours.

Although in most cases the weir is eroded, the weir can also be raised/accreted as well or a
combination of the two. Simply enter the change over time using as many rows as needed.

The original W weir approach is adopted for calculating the flow (see Section 5.8.4.2 ).

@499
5.8.5 Spillways (SP)

Spillways (‘SP’) were introduced for the TUFLOW 2013-12 release and may also be used in
operational mode as a gated spillway (see Section 5.10 ). Spillways may also be simulated and
operated as Q or QO channels where the user provides the stage discharge relationships (see
Section 5.9.2 and Section 5.10.3 ). The 1d_nwk attributes are presented in Table 5.18 .

Spillways use the same equation as for advanced weirs (Section 5.8.4.3 ). For ungated spillways
(i.e. SP, non-operated spillways) the same parameters as for Ogee Weirs are the default (see
Table 5.15 ), except for Cd, which is fixed with the default value of 0.75. For Ogee Weirs, Cd is
recalculated every timestep (see Section 5.8.4.3.1 ). The 1d_nwk attributes in Table 5.15 can be
used to modify the flow equation parameters for SP channels in a similar manner for advanced
weirs.

SPO channels also use the same equation when the gate is not affecting the flow (for more
information on SPO channels refer to Section 5.10.6 ).

SP and SPO channels can also drown out as per the submergence curves for advanced weirs.

Section 5 1D Network Domains - ESTRY - 60 / 130 Page 163 / 1094

 @500
5.8.6 Sluice Gates (SG)

For sluice gates refer to Section 5.10.5 . The same approach applies as for SGO operated gates,
except that the gate is assumed to be in a fixed position based on the 1d_nwk Height_or_WF
attribute value. The 1d_nwk attributes are presented in Table 5.18 .

@501
5.8.7 Adjustment of Contraction and Expansion Losses

The energy losses associated with the contraction and expansion of flow lines into and out of a
structure, can be automatically adjusted according to the approach and departure velocities in the
upstream and downstream channels. This is particularly important where:

There is no change in velocity magnitude and direction as water flows through a structure. In
this situation, there is effectively no entrance (contraction) or exit (expansion) losses and the
losses need to be reduced to zero. Examples are:
A clear spanning bridge over a stormwater channel where there are no losses due to any
obstruction to flow until the bridge deck becomes surcharged.
Flow from one pipe to another where the pipe size remains unchanged and there is no
significant bend or change in grade.
There is a change in velocity, but the change does not warrant application of the full entrance
and exit loss. This is the most common case where the application of the full entrance and
exit loss coefficients (typically 0.5 and 1.0) will overestimate the energy loss through the
structure. The full values are only representative of the situation where the approach and
departure velocities are close to zero, for example, a culvert discharging from a lake into
another lake where the velocity transitions from still water to fast flowing and to still water.

The entrance and exit losses are adjusted according to the equations below to take into account
the change in velocity caused by the structure. The first equation is empirical, while the second
equation to adjust exit losses can be derived from first principles.

@502 Vapproach
Centrance_adjusted = Centrance [1 − ] (5.14)
Vstructure

2
@504 Vdeparture
Cexit_adjusted = Cexit [1 − ] (5.15)
Vstructure

Where:

V = Velocity (m/s)
C = Energy Loss Coefficient

As the structure velocity approaches the incoming and/or outgoing velocities, the loss coefficient
approaches zero. When the incoming and/or outgoing velocity approaches zero (i.e. water is
leaving/entering a large body of water), the loss coefficients approach their full value.

Tullis & Robinson (2008 ) provide an excellent proof for the need to adjust losses for different
flow regimes using the exit loss equation above. The paper benchmarks different exit loss
equations used within the industry methods against experimental flume test results.

The adjustment of losses feature is available to structures that require entrance and exit loss
coefficients, namely culverts and bridges. For culverts, the adjusted entrance loss coefficient only
applies where the flow is not inlet controlled (i.e. Regimes C, D, E, F, H and J in Table 5.6 ), and

Section 5 1D Network Domains - ESTRY - 61 / 130 Page 164 / 1094

 the adjusted exit loss is only influential where the flow is downstream controlled (i.e. Regimes D,
F, H and J (subcritical at exit) in Table 5.6 ). For bridges, the application varies as discussed
below.

If Structure Losses == ADJUST EXCEPT BG TABLES (default), the adjustment of the

losses is only applied to culverts and B bridges with automatically generated loss tables using the
1d_nwk Form_Loss attribute (see Table 5.10 ). There is no adjustment for B bridges with a user
specified BG or LC energy loss table, because bridge energy losses are most often based on
coefficients from publications such as “Hydraulics of Bridge Waterways” (Bradley, 1978 ) or
“Guide to Bridge Technology Part 8, Hydraulic Design of Waterway Structures” (Austroads, 2018
) that have already taken into account the effects of contraction and expansion.

For BB bridges, the LC table should only represent the pier and submerged deck losses (see
Section 5.8.4.4 ), as the adjustment of entrance and exit losses every timestep as per the
equations above is always applied irrespective of the Structure Losses setting. The equations
above conform with the approach for determining contraction and expansion losses in publications
such as Hydraulics of Bridge Waterways.

For B bridges and culverts, if Structure Losses is set to “ADJUST”, or “A” has been specified in
the 1d_nwk Type attribute (e.g. BA, CA, IA or RA), the entrance and exit losses are adjusted
according to the equations above. For B bridges, because the entrance and exit losses are
combined as one loss coefficient, the entrance and exit loss components are proportioned one-
third / two-thirds respectively when applying the above equations. For the new BB bridge,
entrance and exit losses are always adjusted as per the equations above and the Structure
Losses setting is not relevant (also see Section 5.8.4.4 ).

The selection of the upstream and downstream channels on which to base the approach and
departure velocities is as follows:

The upstream channel is determined as the channel which has a positive flow direction into
the structure whose invert is closest to that of the upstream invert of the structure. If no
channel exists, no adjustment of losses is made (this includes structures connected to a 2D
domain). Note that the upstream channel must be digitised so that it has the same positive
flow direction to that of the structure.
The downstream channel is selected on a similar basis to that for the upstream channel.
The selected upstream and downstream channels are listed in the .eof file for cross-checking
(search for “Primary Channel”).
X channels can be used to connect additional channels and ensure that these are not
considered the primary channel.

TUFLOW has no requirement of a minimum loss coefficient value for stability, and therefore allows
the adjusted coefficient to approach zero allowing this feature to correctly model the structure
losses when the structure causes no disturbance to flow, or when one pipe discharges into
another of identical size, grade and alignment.

The adjustment of loss coefficients does not apply to:

Any bend or additional loss for a culvert entered using the Form_Loss attribute in the 1d_nwk
layer. This coefficient can be used to apply additional losses (e.g. pit or bend losses) that are
not affected by changes in the relativity of the approach/departure and structure velocities.
Any additional loss coefficient component for BB bridges entered using the Form_Loss
attribute in the 1d_nwk layer. This coefficient can be used to apply additional losses (e.g. pier

Section 5 1D Network Domains - ESTRY - 62 / 130 Page 165 / 1094

 losses) that are not affected by changes in the relativity of the approach/departure and
structure velocities.
The ends of culverts and bridges that are connected to 2D SX or HX cells as the approach or
departure velocity needs to be derived in some manner from the 2D velocity field. It is
important not to be duplicating energy losses by applying exit losses to a 1D structure and
simulating the same energy losses due to the flow expansion in the 2D domain – for further
information see the Modelling Energy Losses at Structures AWS Webinar.

If Structure Losses is set to FIX, or “F” has been specified in the 1d_nwk Type attribute (e.g. BF,
CF, IF or RF), the loss coefficients for B bridges and culverts are not adjusted. Fixing the entrance
and exit losses for BB bridges is not available – use a B bridge instead.

The variation in time of the loss coefficients can be viewed using the _TSL output layer (see
Section 15.3.4 ) or charted in the QGIS TUFLOW Viewer plugin.

If there is a manhole at the culvert end, a manhole energy loss approach (see Section 5.11.4 ) is
used instead of the culvert’s contraction/expansion loss, and the above description does not apply.

@506
5.9 Special Channels

@507
5.9.1 M Channels (User Defined Flow Matrix)

M channels allow the modeller to define the flow through a channel (usually a structure) based on
a user specified flow matrix. To set up M channels follow the steps below:

1. In the 1d_nwk layer, populate the required attributes as shown in Table 5.18
2. Create the flow matrix as shown in the image below and save the file as a .csv. The .csv file is
referenced in the 1d_nwk Inlet_Type attribute. Notes using the example in the below image
are:
1. TUFLOW searches through the sheet until more than 3 numbers are found at the
beginning of a row (Row 3 in the example).
2. This first row contains a multiplication factor (in Cell A3) followed by upstream depth
values (in the direction that the channel is digitised). The depth values are added to the
channel invert to set the water level.
3. The next rows have the downstream depth in Column A. Flows are listed in the adjacent
columns relating to the above upstream depth value (Row 3).
4. Note: at present the matrix must be square and that the u/s and d/s depths must be the
same values. The flows along the diagonal must be zero, and to the left of the diagonal
negative (or zero) and to the right positive (or zero).
3. Optionally create a flow area matrix of the same dimensions and depth values as for the flow
matrix. Note:
1. The path to the area.csv file is specified after the flow.csv file in the Inlet_Type attribute
(separate the two filenames using a “|”; eg. “..\UD_Q.csv | ..\UD_A.csv”).
2. The factor value in the A3 cell is not used in the flow area matrix (the value in the flow
matrix is used to factor the areas).
3. The area values are only used for outputting the channel velocity (they are not used for
the hydraulic computations other than when the channel velocity is used for other
channels, eg. adjusting structure losses).

Section 5 1D Network Domains - ESTRY - 63 / 130 Page 166 / 1094

 4. If an area matrix is not provided, TUFLOW will calculate the area based on the channel
width multiplied by the pBlockage and the average of the upstream and downstream
depths.

@508
5.9.2 Q Channels (Upstream Depth-Discharge Relationship)

Q channels are used to model flow through a channel using an .ecf Depth Discharge Database .
The Depth Discharge Database is the same as the Pit Inlet Database used for Q pits, with the
same database used for both Q channels and Q pits. Refer to Section 5.11.3 .

In the 1d_nwk layer, the following attributes can be used to set up a Q channel (also see Table
5.18 ).

ID = Unique Channel ID.

Type = “Q”.
US_Invert = Elevation corresponding to zero depth in the depth-discharge curve.
Inlet_Type = The depth discharge curve in the Depth Discharge Database or Pit Inlet
Database . This is analogous to a Q pit (see Section 5.11.3 ). Note that the flow is
automatically adjusted for being drowned out using the Bradley relationship for weirs (see
Section 5.8.4.2 or Figure 5.7 ), and if the flow reverses the same depth discharge curve is
used.
Width_or_Dia = For Q channels can be used as a flow multiplier – this is useful if the depth-
discharge curve is a unit flow (i.e. flow per unit width). Therefore, if the discharge is unit flow
specify the width of the flow, otherwise specify a value of 1.0 (noting that a zero value is
treated as 1.0).
Number_of = The number of parallel Q channels (a zero value is interpreted as one channel).

@509
5.9.3 X Connectors

X connectors are used for connecting a side tributary or pipe into the main flow path. They are
digitised as a line within a 1d_nwk GIS layer with type “X”. No other attributes are required.

Use of an X connector has the advantage of allowing different end cross-sections (see Section
5.7.6 ) or WLLs (see Section 11.2.4 ) to be specified for the side channel, rather than using the
end cross-section on the main channel.

Section 5 1D Network Domains - ESTRY - 64 / 130 Page 167 / 1094

 They can also be used in pipe networks to ensure that the angle of the inlet and outlet culverts
has been digitised appropriately as this influences the manhole losses calculated when using the
Engelund loss approach (see Section 5.11.4.4 ). The angle of the pipe channel line is used for
determining manhole losses, not that of the X connector.

The direction of the X Connector must be digitised starting from the side channel and ending at
the main channel. If two or more connectors are used at the same location (i.e. to connect two or
more side channels to a main channel) their ends must all snap to the same main channel.

@510
5.9.4 Legacy Channels

For backwards compatibility, gradient (type ‘G’) and normal (type ‘blank’) channels remain
supported in the current release of TUFLOW. Sloping (type ‘S’) open channels are the preferred
method of modelling open channels as it incorporates the flow regimes covered by normal and G
channels and include the additional ability of handling super-critical flow. Refer to Section 5.6 for
further information.

A normal flow channel is defined by its length, bed resistance and hydraulic properties. The
channel can wet and dry, however, for overbank areas (e.g. tidal flats or floodplains) G or S
channels should be used. Note: For open channels it is recommended to use the S Type for
the reasons given above.

Gradient channels were designed for overbank areas such as tidal flats and floodplains. The
upstream and downstream bed invert attributes must be specified to define the slope of the
channel. They are like normal channels, except when the water level at one end of the channel
falls below the channel bed, the channel invokes a free-overfall algorithm that keeps water flowing
without using negative depths. The algorithm takes into account both the channel’s bed resistance
and upstream controlled weir flow at the downstream end. Note: For overbank areas it is
recommended to use the S Type for the reasons given above.

@511
5.9.5 1d_nwk Attributes (M, P, Q, SG, SP Channels)

The table below covers the 1d_nwk attributes for all channels not covered in other 1d_nwk
attribute tables.

Section 5 1D Network Domains - ESTRY - 65 / 130 Page 168 / 1094

 @512Table 5.18: Special Channels: 1D Model Network (1d_nwk) Attribute Descriptions

Default GIS
No. Description Type
Attribute Name

Unique identifier up to 12 characters in length. It may

contain any character except for quotes and commas
and cannot be blank. As a rule, spaces and special
1 ID characters (e.g. “\”) should be avoided, although they Char(12)
are accepted. The same ID can be used for a
channel and a node, but no two nodes and no two
channels can have the same ID.

The channel type as specified using the flags in

2 Type Table 5.1 . Char(4)

For X (connectors), no other attributes are required.

If a “T”, “t”, “Y” or “y” is specified, the object will be

3 Ignore ignored (T for True and Y for Yes). Any other entry, Char(1)
including a blank field, will treat the object as active.

M, P, Q Channel Type:
Not used.

SG, SP Channel Type:

UCS If left blank or set to Yes (“Y” or “y”) or True (“T” or
(Use Channel “t”), the storage based on the width of the channel
4 Char(1)
Storage at over half the channel length is assigned to both of
nodes). the two nodes connected to the channel. If set to No
(“N” or “n”) or False (“F” or “f”), the channel width
does not contribute to the node’s storage. See
Section 5.13.1.1 for further discussion.

M, P, Q Channel Type:
Not used.

5 Len_or_ANA SG, SP Channel Type: Float

Only used in determining nodal storages if the UCS
attribute is set to “Y” or “T”. Not used in conveyance
calculations.

M, P, Q Channel Type:
Not used.

SG, SP Channel Type:

6 n_ nF_Cd Discharge coefficient for the structure if using a fixed Float

coefficient. If the value is less than or equal to zero,

the default Cd value of 0.6 for SG and 0.75 for SP is
used.

Section 5 1D Network Domains - ESTRY - 66 / 130 Page 169 / 1094

 Default GIS
No. Description Type
Attribute Name

M Channel Type:
Invert level of channel.

P Channel Type:
Intake elevation of the pump.

Q Channel Type: US_Invert sets the level from

which the upstream depth is to be calculated for
7 US_Invert Float
interpolation into the depth-discharge curve.

SG Channel Type:
The higher of US_Invert and DS_Invert is used to set
the structure crest or invert.

SP Channel Type:
Sets the spillway crest

M Channel Type:
Invert level of channel is taken as the maximum of
US_Invert and DS_Invert.

P Channel Type:
Outlet elevation of the receptor.

Q Channel Type:
8 DS_Invert Float
Not used.

SG Channel Type:
See comments above for US_Invert.

SP Channel Type:
Sets the level of the gate seat (if SP is operated,
i.e. a SPO channel).

M, P, Q, SP Channel Type:
Not used.

SG Channel Type:
If no weir is specified in the Type attribute, it is
9 Form_Loss assumed that the gate seats on to the bottom of the Float

channel. For this case the flow calculations where

the gate is not surcharged uses the Form_Loss
attribute to apply an energy loss to the structure to
represent contraction/expansion losses.

Section 5 1D Network Domains - ESTRY - 67 / 130 Page 170 / 1094

 Default GIS
No. Description Type
Attribute Name

Q Channel Type:
Not used.

M Channel Type:
Percentage blockage of channel (only used if no flow
10 pBlockage area matrix is provided). Refer to Inlet_Type attribute Float
below.

P, SG, SP Channel Type:

The channel’s dimensions and flow capacity are
reduced as per the pBlockage value.

M Channel Type:
The relative path to the flow matrix file (must be a
.csv file), and optionally flow area matrix file. See
Section 5.9.1 .

P, SG, SP Channel Type:

Only used for operational versions of these channels
(i.e. type “PO”, “RGO”, SGO” or “SPO”) to specify the
name of the . The is referenced within the .toc file
and specifies the rules used to operate the channel.
More than one channel can point to the same . Refer
to Section 5.9.1 .

Q Channel Type (for QO see further below):

For non-operated Q channels the name of the depth-
discharge curve in a depth discharge database Char
11 Inlet_Type (identical approach to inlet Q pits). A Q channel is (max
distinguished from a Q pit, in that a Q channel is a 256)
line in the 1d_nwk layer and a Q pit is a point object.
A depth-discharge database is the same as a pit inlet
database as used for Q pits, and the same database
file can be used for both Q channels and Q pits. The
.ecf command Depth Discharge Database and the
existing command Pit Inlet Database perform the
same function.
Note that the depth discharge curve is depth (not
water elevation) and the depth is taken as the
upstream water level less the Q channel’s invert.

QO Channel Type:
For operated Q channels the filename of a .csv file
containing a flow matrix table in the same format as
used for M channels. See Section 5.9.1 .

12 Conn_1D_2D Not used. Char

13 Conn_No Not used. Integer

Section 5 1D Network Domains - ESTRY - 68 / 130 Page 171 / 1094

 Default GIS
No. Description Type
Attribute Name

P Channel Type:
The diameter of the pump offtake. Only used for
outputting a velocity - it does not affect the hydraulic
calculations.

M Channel Type:
Width of channel (only used if no flow area matrix is
provided). Refer to Inlet_Type attribute above.

Q Channel Type (for QO see further below):

A multiplier applied to the flow interpolated from the
depth-discharge curve. Particularly useful if the
14 Width_or_Dia discharge values are per unit width (i.e. m2/s or Float
2
ft /s). If set to zero (0), the multiplier is set to one (1).

QO Channel Type:
Used to determine the flow area at different stages
by multiplying by the upstream depth. The area is
used to determine the velocity that is output,
otherwise, it does not play a role in the hydraulic
calculations.

SG, SP Channel Type:

The width of the gate/spillway. The flow area is
assumed to be rectangular in shape.

Section 5 1D Network Domains - ESTRY - 69 / 130 Page 172 / 1094

 Default GIS
No. Description Type
Attribute Name

M, Q Channel Type:
Not used.

P Channel Type:
Can be used to set the pump flow capacity for
operated pumps (i.e. a PO channel). The pump
capacity can also be set and changed during the
simulation using the .toc file operating control
commands. Useful where the operating control
definition is generic (i.e. pump control is used for
more than one pump of different flow capacities).

SG Channel Type:

15 Height_or_WF The vertical height of the gate in its fully open Float
position. If an underlying weir is specified, the weir is
assigned a coefficient adjustment factor of 1.0, which
cannot be modified using this attribute.

SPO Channel Type:

For an operated (gated) spillway (SPO), sets the
vertical height of the gate in its fully open position.
The fully open height can also be changed during the
simulation using the .toc file operating control
commands. This is useful where the operating
control definition is generic (i.e. non-structure
specific). Not used if channel is non-operational
(i.e. a SP channel).

P, SG, SP Channel Type:

The number of parallel (duplicate) channels. If set to
zero, one channel is assumed.
16 Number_of Integer
M, Q Channel Type:
Number of parallel channels (flow and area matrices
are multiplied by this value). If zero is set to one.

Section 5 1D Network Domains - ESTRY - 70 / 130 Page 173 / 1094

 Default GIS
No. Description Type
Attribute Name

M, Q Channel Type:
Not used.

SP Channel Type:
Weir flow coefficient, Cd, in its dimensionless form as
in the equation below. If less than or equal to zero
the default value for spillways in Table 5.15 is used.
Entering a value greater than zero (0) will override
this and apply a fixed Cd.
Note that published coefficients may be based on
17 HConF_or_WC Float
other non-dimensional or dimensional forms of the
equation below, therefore care should be taken in
ensuring the coefficient is converted to comply with
the form below if this is the case.

2
Ex
Q = Csf Cd B √2g H
3

SG Channel Type:
As for the weir channel in Table 5.16 if a weir has
been specified (e.g. a “SG WB” channel).

M, Q Channel Type:
Not used.

SP Channel Type:
Weir flow equation exponent Ex in the equation for
HConF_or_WC. If less than or equal to zero the
18 WConF_or_WEx Float
default value for spillways in Table 5.15 is used
(i.e. 1.5).

SG Channel Type:
As for the weir channel in Table 5.16 if a weir has
been specified (e.g. a “SG WB” channel).

M, Q, SPO Channel Type:

Not used.

SP Channel Type:
Sets the submergence factor “a” exponent in the
equation below for calculating the submergence
factor Csf. If less than or equal to zero the default
19 EntryC_or_WSa value for spillways in Table 5.15 is used. Float

a b
Hd
Csf = (1 − ( ) )
Hu

SG Channel Type:
As for the weir channel in Table 5.16 if a weir has
been specified (e.g. a “SG WB” channel).

Section 5 1D Network Domains - ESTRY - 71 / 130 Page 174 / 1094

 Default GIS
No. Description Type
Attribute Name

M, Q, SPO Channel Type:

Not used.

SP Channel Type:
Sets the submergence factor “b” exponent in the weir
flow equation above for calculating the weir
20 ExitC_or_WSb Float
submergence factor Csf. If less than or equal to zero
the default value for spillways in Table 5.15 is used.

SG Channel Type:
As for the weir channel in Table 5.16 if a weir has
been specified (e.g. a “SG WB” channel).

@515
5.10 Operational Channels

Gated rectangular culverts, pumps, sluice gates, gated spillways, weirs and Q channels can be
operated using logical scripts. An “O” Type flag is required within the 1d_nwk layer for structures
that are to be operated using an operating control definition. For example, an operated pump
would have a Type attribute of “PO” or “OP”.

Operating rules are contained within a .toc file (TUFLOW Operations Control) with each set of
rules contained within a control definition. More than one structure/device can use the same
control definition. The .toc file is referenced using Read Operating Controls File via the .ecf file,
or via the .tcf file within a Start 1D Domain block or by preceding the command with “1D”.

The operating rules for a control can only occur within a .toc file. More than one .toc file can be set
up and accessed should there be a need to break the control definitions into several files (for
example, all pump controls could be placed in one file and sluice gate controls in another).

Operational structure time-series data are output to the _1d_O.csv file. The file reports the time
varying status of the structure and the resulting flow rate. Values of user defined variables and
other information are also output to this file. This is discussed in greater detail within Section
15.3.4 .

@516
5.10.1 .toc File Commands and Logic

@517
5.10.1.1 Define Control Command

A .toc file can only contain Define Control and End Define blocks.

Each Define Control must include a keyword indicating the type of structure/device as per below:

Define [ Culvert | Pump | Q Channel | Sluice | Spillway | Weir ] Control

== <control_id>
…
End Define

Section 5 1D Network Domains - ESTRY - 72 / 130 Page 175 / 1094

 Where <control_id> is a unique control definition name, noting that more than one structure
can refer to the same operational control definition. For example, several pumps of different
capacities may utilise the same operational control logic. The 1d_nwk Inlet_Type attribute is used
to link a control definition with the structure.

Within the control definition, commands specific to the type of structure/device can be used to
adjust the structure/device’s operation. The commands available for each type of control are
described below.

Each Define Control block consists of three sections:

1. The default settings for the control’s commands. These are usually placed at the top of the
definition and prior to the logical rules. These default settings are used at the start of the
simulation/operation and during the operation unless changed by the logical rules.
2. User defined variables as described further below.
3. One or more logical rules as described further below.

An example of a definition control with the three sections is provided below.

@518
5.10.1.2 User Defined Variables

If a line in the control definition cannot be processed as one of the commands described above,
and it is not within an If…End If block, it is treated as a variable definition using the syntax:

<variable> == <variable_value>

Where <variable> is the variable name, while <variable_value> must conform to one of the
options in Table 5.19 . Any characters can be used for the variable name, but it is recommended
to use only letters, numbers and underscores and to avoid spaces. Note that variables can be
redefined at any point within the control definition. Also note that these variables only apply to the
control. For global variables, use the Set Variable feature.

Section 5 1D Network Domains - ESTRY - 73 / 130 Page 176 / 1094

 @519 Table 5.19: Variable Value Types

Variable Value Description

constant Sets the variable to the value of <constant>. Must be a number.

Time of Model Sets the variable to the simulation time in hours.

Sets the variable to the simulation time in hours on a 24-hour clock (i.e. will
Time in 24H always be between 0 and 24 hours). A simulation time of zero is equivalent
to midnight.

Sets the variable to the current simulation time and keep the variable
Time Stamp constant until the variable is changed by a repeat execution of “Time
Stamp”.

Sets the variable to the day of the week where Sunday is 1 and Saturday is
Day of Week 7. The keywords “Sun”, “Mon”, “Tue”, “Wed”, “Thu”, “Fri” and “Sat” can also
be used when using the variable in a logic rule.

Period No Sets the variable to the time in hours since there was last a change in
Change operation.

H1D
Sets the variable to the water level at the 1D node named <node_id>.
<node_id>

Q1D
Sets the variable to the flow in the 1D channel named <channel_id>.
<channel_id>

Sets the variable to the water level at the 2D cell located at the XY
H2D <x>,<y>
coordinates <x>,<y>

H2D Sets the variable to the water level at the 2D plot output location given by
<2d_po_ID> the plot output ID.

Sets the variable to the 1D water level at the upstream node of the channel,
HU
based on the digitised direction of the channel.

Sets the variable to the 1D water level at the downstream node of the
HD
channel based on the digitised direction of the channel.

Sets the variable to the difference in water level between the upstream and
dHUD downstream nodes based on the digitised direction of the channel. Will be
negative if flow is in opposite direction to digitised direction.

Sets the variable to the upstream water level of the channel based on the
H1
flow direction.

Sets the variable to the downstream water level of the channel based on the
H2
flow direction.

Sets the variable to the difference in water level between the upstream and
dH12 downstream nodes based on the flow direction of the channel. Will always
be positive.

Sets the variable to the depth above the structure invert of the upstream
YU
node based on the digitised direction of the channel.

Section 5 1D Network Domains - ESTRY - 74 / 130 Page 177 / 1094

 Variable Value Description

Sets the variable to the depth above the structure invert of the downstream
YD
node based on the digitised direction of the channel.

Sets the variable to the upstream depth relative to the structure invert
Y1
based on the flow direction.

Sets the variable to the downstream depth relative to the structure invert
Y2
based on the flow direction.

The 2020-10 release introduced a feature to allow operational control channels to refer to the
status/variables from other operational control channels. This makes coordinated operations
possible between multiple operational structures. The supported status/variables include:

“Period No Change” returns the time in hours since there was a change in operation in
another operational channel.
“Status” returns the operational status keywords in text format for different types of
operational channels. The full list of keywords is summarised in Table 5.20 .
“Operational Variables” returns the numeric values of operational variables from other
operational channels, such as “Gate Height”, “Weir Width”, etc. The full list of keywords is
summarised in Table 5.21 .

The operational control channel ID (1d_nwk attribute) must be added at the end of user defined
variable commands listed above to refer to the “Period of No Change”, “Status” or “Operational
Variable” from other operational channels, e.g.:

<variable> == Weir Height <channel_ID>

@520 Table 5.20: Keywords Returned by “Status” Variable

Operational Channels Status Strings

“Off”, “Dry”, “Below Soffit”, “Starting”, “Stopping”,

Pumps (PO)
“Constant”, “Pump Curve”

Gated Drowned Rectangular

Culverts (RO)
Sluice Gates (SGO)
Spillways with Gates (SPO)
“Opening”, “Closing”, “Steady”, “Closed”, “Fully Open”
Weirs (WBO, WCO, WDO, WOO,
WRO, WTO)
Dam failure (DF)
Pipe failure (PF)

Section 5 1D Network Domains - ESTRY - 75 / 130 Page 178 / 1094

 @521 Table 5.21: Values Returned by ‘Operational Variables’.

Operational Channels Operational Variables

Pumps (PO) Pump Flow

Q channel (QO) Q Opening, Q Fully Open

Gated Drowned Rectangular Culverts (RO) Gate Height, Gate Width

Sluice Gates (SGO) Gate Opening

Spillways with Gates (SPO) Gate Opening

Weirs (WBO, WCO, WDO, WOO, WRO, WTO) Weir Height, Weir Width

Dam failure (DF) Breach Depth, Top Width

Pipe failure (PF) Orifice Height, Orifice Width

In the example below, the model has an operational sluice gate (“SGate1”) and an operational
pump (“Pump1”). Pump1 calls the “status” of SGate1 and operates only if SGate1’s status is
“Closed”.

@522
5.10.1.3 Logic Rules

The logic rules consist of using If…End If blocks using the construct below.

If <condition_1> [ [ and | or ] <condition_2> ] [ [ and | or ]

<condition_3> ]…
…enter one or more commands or variable definition lines
[ Else If <condition_1> [ [ and | or ] <condition_2> ] [ [and | or ]
<condition_3> ]…
…enter one or more commands or variable definition lines
[ Else If…repeat as needed]
…enter one or more commands or variable definition lines
[ Else
…enter one or more commands or variable definition lines
End If

<condition_1> must be a conditional operation that includes one of the symbols “=”, “>”, “>=”,
“<” or “<=”. The left and right sides of the condition must be a single value or a variable name.
Optionally the variable may be operated on by the following:

Section 5 1D Network Domains - ESTRY - 76 / 130 Page 179 / 1094

 A “+”, “-“, “*” or “/” and a constant value. For example, a condition could be “x + 2 < 3”; or
Specifying “HIGHER” or “LOWER” to compare the current value of the variable to its value at
the start of the current period of no change in operation. For example, “x == LOWER” will be
true if the current value of ‘x’ is less than its value at the last time there was a change in
operation.

If more than one condition is to be applied, the conditions must be separated by either an “and” or
“or”. <condition_2>, <condition_3>, etc. have the same format as for <condition_1> above.

If…End If blocks can be nested inside other If…End If blocks. Indenting is strongly recommended
to make the control file easier to read.

@523
5.10.1.4 Incremental Operators

For the majority of the parameters / variables within a control block these can be manipulated
using simple arithmetic. For example, within a control block, rather than opening a gate to a set
opening height or percentage it is possible to open by a set amount:

Gate Opening % == 50 will open the gate to 50% open

Gate Opening % == ++ 10 will open the gate by 10% from its previous position

Four incremental / arithmetic operators are available, these are:

++ increment up
-- increment down
** multiply
// divide

These can be used with or without the percentage operator. Gate Opening % == ++10 will open a
gated structure by 10%, Gate Opening == ++ 1.0 will open a gated structure by a height of 1m.

The example below shows the control definition for a pump that operates between 6am and 6pm
Monday to Friday and 10am and 4pm on the weekends.

The example below shows the control definitions for a gravity released discharge to a power
station (modelled as a pump) and the gated discharge through the reservoir (courtesy of Natural
Resources Department, Wales).

Section 5 1D Network Domains - ESTRY - 77 / 130 Page 180 / 1094

 @524
5.10.2 Pumps (P and PO)

Pumps can be modelled as a “P” or “PO” type channel. In non-operational mode (P channel), the
pump flow is interpolated from a head discharge curve in the Depth Discharge Database defined
via a head difference versus flow relationship – see Section 5.11.3 . In operational mode, PO, the
pump flow can be varied using functions such as: switching on and off over a start-up and
shutdown period; and changing the pump capacity and/or discharge curve according to time, day
of the week, hydraulic conditions and other variables. Pumps do not contribute to any model
storage.

In the 1d_nwk layer, the following attributes can be used to set up the pump (also see Table 5.18
).

ID = Unique Channel ID.

Type = “P” or “PO”.
US_Invert = Intake elevation of the pump.
DS_Invert = Outlet elevation of the receptor.
Inlet_Type = For non-operated (P) pumps the pump discharge curve in the Depth Discharge
Database . This curve is a head difference versus discharge curve, therefore, for a pump this
curve would usually have greater flows for smaller head differences. If the head difference is
negative (i.e. the receptor water level is below the intake water level) the discharge used is
that for a zero head difference. For operational (PO) pumps Inlet_Type refers to the Pump
operational control definition (see Define Control ).
Width_or_Dia = Diameter of the pump’s outlet pipe/hose. Used to trigger dry conditions (see
below) and for calculating the velocity.

Section 5 1D Network Domains - ESTRY - 78 / 130 Page 181 / 1094

 Height_or_WF = For PO pumps the initial operating pump capacity for fixed (constant) flow
pumps (subject to not being overridden by an operational control command).
Number_of = Number of (identical) pumps represented by the channel.

P and PO pumps are simulated as dry (zero flow) if the upstream (intake) node is dry or the
upstream water level is below the intake elevation plus the output pipe diameter (i.e. the upstream
(intake) water level is below the intake soffit, which equals the US_Invert + Width_or_Dia).

P pumps always produce a flow in the direction the P channel is digitised based on that
interpolated from the pump discharge curve; the exception being when dry as described above.

PO pumps are typically operated on a time basis or based on hydraulic conditions elsewhere in
the model. Operational control commands specific to the Define Pump Control command are
provided below. Subject to not being overridden by an operational control command, PO pumps
are assumed to be OFF at the start of the simulation.

Pump Operation turns the pump on or off.

Period Startup/Shutdown sets the time taken to start the pump up or shut it down.
Pump Capacity sets the flow capacity of the pump. It is possible to set a constant flow rate or
a head-discharge curve referenced within the Depth Discharge Database .
Pump Number sets the number of pumps in parallel.

The operational status of each pump is reported over time in the _O.csv output (see Section
15.3.4 ). Possible status conditions include:

“Off” is the pump is switched off.

“Dry” if the upstream (intake) node is dry.
“Below Soffit” if the upstream (intake) water level is below the intake soffit.
“Starting” and “Stopping” indicate the pump is starting up or stopping within Period
Startup/Shutdown .
“Constant” indicates the pump has reached full flow capacity after starting up and is operating
at its constant (fixed) flow rate, or “Pump Curve”, which indicates the pump is operating at a
flow rate based on interpolating into its head discharge curve.

@525
5.10.3 QO Channels

For QO channels, depth discharge curves for different structure openings are used to vary and
control the discharge. The relationships are contained in a csv file in a similar format as used for
M channels (see Section 5.9.1 ). The vertical axis is the depth above the channel’s invert and the
horizontal axis is the percentage opening as shown in the example below. In the example, Column
A contains the depth above invert values and Row 2 the % opening values. Note that the value in
cell A2 is a flow multiplier. If this value is empty, negative or set to zero (0), a multiplier of one (1)
is used. The flow through the channel is interpolated from this table at each timestep based on the
structure’s opening and upstream depth above the invert.

Section 5 1D Network Domains - ESTRY - 79 / 130 Page 182 / 1094

 In the 1d_nwk layer, the following attributes can be used to set up a QO channel.

ID = Unique Channel ID.

Type = “QO”.
US_Invert = Elevation corresponding to zero depth in the depth-discharge curve.
Inlet_Type = Contains both the control_ID and the link to the csv file containing the matrix of
flows for different openings and upstream water level as per discussion above. For example,
“DS_Gate | QChannel.csv”.
The default field width for the inlet_type attribute is 12 characters, this may need to be
increased to allow longer names to be used. Instructions on how to change the GIS layer
attribute type in ArcMap, QGIS and MapInfo are provided on the TUFLOW Wiki as per the
links below:
ArcMap
MapInfo
QGIS
Width_or_Dia = Not used other than to estimate the velocity and contribute to nodal storage.

The following commands are specific to the Define Q Channel Control command used for QO
channels.

Gate Speed sets the speed the gate moves.

Period Opening/Closing sets the time taken to transition from zero to 100% opening or vice
versa.
Gate Opening sets the position of the opening to be operated towards. This can be specified
incrementally or as an absolute value.
Discharge Curve Type sets how the depth/head discharge curves are calculated.

An example of the GIS attributes and .toc commands for a QO channel are provided below.

Section 5 1D Network Domains - ESTRY - 80 / 130 Page 183 / 1094

 @526
5.10.4 Gated Drowned Rectangular Culverts (RO)

Rectangular culverts with a gate on the exit can be operated using the .toc commands below for a
Define Culvert Control block. The command is applicable for operated rectangular (RO) culverts
only, and uses the equation below as implemented into TUFLOW for a project based in Florida.
The equation below is for US Customary Units, but RO culverts can be used in metric or US
Customary units. Note that the equation is for submerged culverts only, therefore the user must
ensure that the culvert is drowned at all times.

Gate Type sets the type of gate arrangement.

Gate Speed sets the speed at which the gate moves.
Period Opening/Closing sets the time taken to fully open a closed gate or to fully close an
open gate.
Gate Height Fully Open sets the height (not elevation) of the gate when fully open above the
gate’s seat for vertically moving gates. If not set, the 1d_nwk “Height” attribute is used.
Gate Width Fully Open sets the width of the gate(s) when fully open for horizontally moving
gates. If not set, the 1d_nwk “Width_or_Dia” attribute is used.

Section 5 1D Network Domains - ESTRY - 81 / 130 Page 184 / 1094

 Gate Opening sets the position the gate is to be operated towards. This can be specified
incrementally or as an absolute value.
Cd sets the discharge coefficient Cd in the equation above.

@527
5.10.5 Sluice Gates (SG and SGO)

Sluice gates can be operated using the .toc commands further below for a Define Sluice Control
block. The approach to calculating the flow through the gate is based on that documented in the
HEC-RAS 4.0 Reference Manual as described below. For non-operated sluice gates (SG) the gate
is assumed to be in a fixed position based on the 1d_nwk Height_or_WF attribute value.

For a free-flowing sluice gate (i.e. upstream controlled) Q is calculated using:

@528
Q = Cd W B√2gH1 (5.16)

Where:

Q = Discharge
Cd = Discharge coefficient upstream controlled flow (default = 0.6)
W = Width
B = Height of gate opening above crest level
H1 = Upstream energy level – Crest level

For downstream controlled flow:

@535 Q = Cs W B√2gΔH (5.17)

Where:

Cs = Submerged discharge coefficient (default = 0.8)

ΔH = Upstream energy level – Downstream level

For the transition between upstream controlled and full submergence downstream controlled flow:

@539 Q = Cd W B√2g3ΔH (5.18)

The transition between downstream and upstream controlled flow equations is based on the
degree of submergence calculated as the tailwater depth above the spill crest divided by the
upstream energy depth. For a ratio below 0.67 upstream controlled flow applies, above 0.8
downstream controlled flow and in between the transition equation applies.

Note that by default the energy level is used for calculating H1 and ΔH , however, this can be
changed as follows:

Setting the global default to water surface level using Structure Flow Levels ==
WATER or by using the “H” flag for the Type attribute (see Table 5.2 ).
Setting the global default to energy at the upstream node and water level at the downstream
node using Structure Flow Levels == ENERGY UPSTREAM or by using the “EH” flag
for the Type attribute (see Table 5.2 ). This option was introduced in the 2023-03-AC build.

When the flow is not in contact with the gate one of the following options apply:

One of the advanced weir types (see Section 5.8.4.3 ) can be specified for the sill by adding
the weir type to the 1d_nwk Type attribute (e.g. “SGWB” or “SG WB” are accepted). The weir

Section 5 1D Network Domains - ESTRY - 82 / 130 Page 185 / 1094

 equation for the weir type is applied when the gate is not controlling the flow. It is
recommended that one of the rectangular weir shapes is used (i.e. WB, WD, WO or WR).
If no weir is associated with the SG channel, the flow is calculated using a zero length
rectangular culvert channel with adjusted entrance and exit losses as per a zero length
culvert. Note the total of the entrance and exit losses is defined by the ‘Form_Loss’ attribute
(see Table 5.18 ), where 1/3 and 2/3 of the ‘Form_Loss’ value are assigned as entrance and
exit losses, respectively (typically 0.5 and 1.0).

In the 1d_nwk layer, the following attributes can be used to set up the SG or SGO channel.

ID = Unique Channel ID.

Type = “SG” or “SGO”.
US_Invert and DS_Invert: The higher value is used for the sill crest.
Width_or_Dia = Width of the gate.
Height_or_WF = The height above the sill crest of the gate when fully opened (subject to not
being overridden by an operational control command).
Number_of = Number of (identical) parallel gates.

The following commands can be used within the Define Sluice Control block.

Gate Speed sets the speed the gate moves.

Period Opening/Closing sets the time taken to fully open a closed gate or to fully close an
open gate.
Gate Height Fully Open sets the height (not elevation) of the gate when fully open above the
gate’s seat for vertically moving gates. If not set, the 1d_nwk “Height” attribute is used.
Gate Opening sets the position the gate is to be operated towards. This can be specified
incrementally or as an absolute value.
Cd Gate sets the discharge coefficient of the gate, Cd.
Cd Gate Submerged sets the submerged discharge coefficient, Cs.

@542
5.10.6 Spillways with Gates (SPO)

Gated spillways can be operated using the approach documented in the USACE Hydraulic Design
Criteria Sheet 312 (USACE, 1977 ) for Vertical Lift Gates on Spillways.

For flow over the spillway unaffected by a gate the following equation applies:

@543 2
Q = C W H √2gH (5.19)
3 d

Where:

Q = Discharge
Cd = Discharge coefficient (default = 0.75)
W = Width of the spillway (rectangular cross-section assumed)
H = Upstream energy level – Crest level

NOTE: Cd prior to the 2016-03 release was based on Q =Cd WH√2gH (as per Sheet
312), with a default Cd value of 0.5. As of the 2016-03 release, SPO channels now use the
same formula as SP and weir channels and use a default value of 0.75.

The ratio of the gated discharge to the ungated discharge is derived as:

Section 5 1D Network Domains - ESTRY - 83 / 130 Page 186 / 1094

 3 3

@550 ⎛ H 2
− H
2
⎞
QG CG 2 1
= ⎜ ⎟ (5.20)
3
Q Cd
⎝ H 2 ⎠

Where:

CG = Discharge coefficient (default = Cd )

H1 and H2 = See diagram below from Sheet 312

If QG is less than Q, QG is used for the flow through the structure. The structure is also tested for
submergence using the same setting as for Ogee Weirs (see Section 5.8.4.4 ).

Note that by default the energy level is used for calculating H1 and ΔH , however, this can be
changed as follows:

Setting the global default to water surface level, using Structure Flow Levels ==
WATER, or by using the “H” flag for the Type attribute (see Table 5.2 ).
Setting the global default to energy at the upstream node and water level at the downstream
node, using Structure Flow Levels == ENERGY UPSTREAM, or by using the “EH” flag
for the Type attribute (see Table 5.2 ). This option was introduced in the 2023-03-AC build.

In the 1d_nwk layer, the following attributes can be used to set up a SPO channel. Note that the
1d_nwk values can be overridden by their equivalent operational control command.

ID = Unique Channel ID.

Type = “SPO”.
US_Invert = Spillway crest level.
DS_Invert = Gate seat level (see GATE SEAT EL in diagram from Sheet 312). If DS_Invert is
higher than US_Invert ERROR 1050 results.
Width_or_Dia = Width of the gate.
Height_or_WF = The height of the gate above the gate seat when fully opened.
Number_of = Number of (identical) parallel spillways.

The following section lists commands specific to the Define Spillway Control commands.

Gate Speed : sets the speed the gate moves.

Period Opening/Closing : sets the time taken to fully open a closed gate or to fully close an
open gate.
Gate Height Fully Open : sets the height (not elevation) of the gate when fully open above
the gate’s seat for vertically moving gates. If not set, the 1d_nwk “Height” attribute is used.

Section 5 1D Network Domains - ESTRY - 84 / 130 Page 187 / 1094

 Gate Seat Vertical Offset : sets the difference in height between the spillway crest and the
seat of the gate (i.e. the CREST EL minus GATE SEAT EL in the diagram above from Sheet
312).
Gate Opening : sets the position the gate is to be operated towards. This can be specified
incrementally or as an absolute value. This value is GO in the diagram above from Sheet 312.
Cd Spillway : sets the discharge coefficient of the spillway, Cd. Default value is 0.75.
Cd Gate : sets the discharge coefficient of the gate, CG. By default assumed to be the same
as Cd Spillway see Sheet 312.

@557
5.10.7 Weirs (WBO, WCO, WDO, WOO, WRO, WTO)

Weirs can be operated to simulate structures such as fabri (inflatable) dams for the WB, WC, WD,
WO, WR and WT weir types.

In addition to the 1d_nwk attributes for non-operated weirs (see Section 5.8.4.3 ) the following
criteria is used to set the limiting dimensions via the 1d_nwk attributes as follows:

Width_or_Dia = The width of the weir when fully open, or if the width remains unchanged
throughout.
Height_or_WF = The maximum height the weir can be raised above the weir invert during
operation. The weir invert level is defined by the maximum of the US_Invert and DS_Invert
attributes and represents the elevation of the weir when fully lowered. Note that for
operational weirs the Height_or_WF attribute cannot be used to set the Weir Calibration
Factor, for which a value of 1.0 is used. For example, if we wish to operate a weir up to an
elevation of 15m for a structure with 1d_nwk attributes US_Invert = 9.9m and
DS_Invert = 10m the following would apply:
The weir invert would be at an elevation of 10m (which corresponds to a weir height of
zero (0) m).
The Height_of_WF attribute would be 5m (i.e. a height of 5m above the weir invert).

The following are the commands specific to Define Weir Control blocks for operating weirs.

Weir Height : sets the height above the weir crest to operate towards.
Weir Width : sets the width of the weir to operate towards.
Weir Height Speed : sets the speed of the weir in the vertical.
Weir Width Speed : sets the speed of the weir in the horizontal.
The generic commands Operation and Period Opening/Closing also apply.
Cf sets the weir calibration factor (default = 1.0). Note the “Height_or_WF” attribute is used to
define the height of the operational weir above the crest level. This .toc command was added
in the 2020-10 release to specify the weir calibration factor (Cf) for an operational weir.

Note the default values of Weir Height and Weir Width are both zero (0). To set the initial
position of the weir, specify these commands before the if logic block in the .toc file.

The 2023-03-AB build introduced three new commands, based on Section 9.11 of USBR (1987 ),
which includes an allowance for side or horizontal flow contraction caused by piers and abutments
that contract the flow and reduces the flow width over the weir (W ) to an effective flow width (W ′ )
using:

′
@560 W = W − 2(N Kp + Ka )He (5.21)

Where:

Section 5 1D Network Domains - ESTRY - 85 / 130 Page 188 / 1094

 He = Upstream energy or water level (see Structure Flow Levels command).
N = Number of piers.
Kp = Pier contraction coefficient.
Ka = Abutment contraction coefficient.

The new .toc file commands to specify the parameters are:

Number of Piers : Sets the number of piers over a weir (the default is zero, 2023-03-AB build
and onwards).
Kp : Sets the pier contraction coefficient (the default is zero, 2023-03-AB build and onwards).
Ka : Sets the abutment contraction coefficient (the default is zero, 2023-03-AB build and
onwards).

Section 9.11 of USBR (1987 ) recommends the following values for the pier contraction
coefficient Kp :

Square-nosed piers with corners rounded on a radius equal to about 0.1 of the pier thickness:
Kp = 0.02
Round-nosed piers: Kp = 0.01
Pointed-nose piers: Kp = 0.0

The recommended values for the abutment contraction coefficient Ka depends on the shape of
the abutment, the design head (H0 ) and the radius of abutment rounding:

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

Rounded abutments with headwall at 90° to direction of flow, when 0.15H0 ≤ r ≤ 0.5H0 : Ka =
0.10
Rounded abutments where r > 0.5H0 , and headwall is placed not more than 45° to direction
of flow: Ka = 0.0

Note that in the relationship above, the effective flow width (W ′ ) reduces linearly as the upstream
head (He ) increases. The ratio of contraction calculated by this equation is usually small relative
to the actual width of weir (W ). But to avoid unreasonable contraction ratios, a lower limit of 0.6W
is applied.

@584
5.10.8 Piping and Dam Failure

The 2020-10-AB build introduced two new operational channels for piping and dam failure:

1. “PF” type: can be used to model the pipe failure process, as discussed in Section 5.10.8.1 ;
and
2. “DF” type: can be used to model a dam/levee break, as discussed in Section 5.10.8.2 .

In the 1d_nwk layer, the attributes in Table 5.22 can be used to set up the channel parameters.

Section 5 1D Network Domains - ESTRY - 86 / 130 Page 189 / 1094

 @585Table 5.22: Piping & Dam Failure Channels: 1D Model Network (1d_nwk) Attribute
Descriptions

Default GIS
No. Description Type
Attribute Name

Unique identifier up to 12 characters in length. It

may contain any character except for quotes and
1 ID commas and cannot be blank. As a rule, spaces Char(12)
and special characters (e.g. “\”) should be
avoided, although they are accepted.

“PF”: Piping Failure

2 Type Char(4)
“DF”: Dam Failure

If a “T”, “t”, “Y” or “y” is specified, the object will be

ignored (T for True and Y for Yes). Any other entry,
3 Ignore Char(1)
including a blank field, will treat the object as
active.

4 UCS Not used. Char(1)

5 Len_or_ANA Not used. Float

6 n_nF_Cd Not used. Float

“PF”: Inlet elevation of the piping.

7 US_Invert “DF”: Elevation of the dam crest level before Float

failure.

“PF”: Outlet elevation of the piping.

8 DS_Invert Float
“DF”: Not Used.

9 Form_Loss Not used. Float

10 pBlockage Not used. Float

“PF”: Refers to the Piping Failure operational

control definition in .toc file.
11 Inlet_Type Char(256)
“DF”: Refers to the Dam Failure operational
control definition in .toc file.

12 Conn_1D_2D Not used. Char(4)

13 Conn_No Not used. Integer

“PF”: Width of the piping orifice when fully

14 Width_or_Dia breached. Float

“DF”: Top width of the dam failure channel.

“PF”: Height of the piping orifice when fully

15 Height_or_WF breached. Float

“DF”: Weir coefficient Cd of the intact part.

Section 5 1D Network Domains - ESTRY - 87 / 130 Page 190 / 1094

 Default GIS
No. Description Type
Attribute Name

16 Number_of Not used. Integer

17 HConF_or_WC Not used. Float

18 WConF_or_WEx Not used. Float

19 EntryC_or_WSa Not used. Float

20 ExitC_or_WSb Not used. Float

@586
5.10.8.1 Piping Failure (PF)

Dam/levee breaks can be initiated by flow overtopping, or by internal erosion (often called “piping”
or “piping failure”) when water seeps through the embankment forming a tiny flow path. This “pipe
failure” process can be modelled using a “PF” type 1D operational channel. In the 1d_nwk layer,
the attributes in Table 5.22 can be used to set up the channel parameters.

@587

Figure 5.12: Schematisation of 1D Piping Failure

Operational control commands (.toc file) specific to the Piping Failure channel are provided below:

Period Failure : sets the time taken to reach the full size of piping failure.
Orifice Width Fully Open : sets the width or the diameter of the piping orifice when fully
breached. If omitted, the value set by the 1d_nwk Width_or_Dia attribute is used.
Orifice Height Fully Open : sets the height of the piping orifice when fully breached. If
omitted, the value set by the 1d_nwk Height_or_WF attribute is used.
Period Collapse : sets the time taken to ‘shut down’ the piping failure channel after it reaches
the full extent due to the channel collapsing.
Orifice Opening : sets the piping failure status.
Cd : sets the discharge coefficient in the orifice flow equation below.

The flow rate through a piping failure channel is calculated using the orifice flow equation as
provided below. Note that zero flow is assumed should the upstream water level fall below the
orifice obvert, i.e. no partial flow of the orifice is assumed to occur.

@588 Q = Cd A√2g (Hup − Hdown ) (5.22)

Where

Cd is the discharge coefficient set by Cd command

A is the cross-sectional area of the orifice
Hup is the upstream water level
Hdown is the higher of the downstream obvert or downstream water level

It is assumed the orifice shape is rectangular, and the orifice size increases linearly with time. The
expansion of the orifice is assumed to be centrally around the upstream and downstream inverts.

Section 5 1D Network Domains - ESTRY - 88 / 130 Page 191 / 1094

 An example of a .toc file Define Pipe Failure Control block is provided below:

@594
5.10.8.2 Dam Failure (DF)

The dam failure “DF” type 1D operational channel can be used to model dam/levee breaks in 1D.
This channel can commence independently, or be triggered by a 1D pipe failure using “PF” type
trigger. The flow rate is calculated based on the advanced weir flow equation (Section 5.8.4.3 ).
Either a rectangular or trapezoidal cross-section can be applied, and the opening size is assumed
to increase linearly with time. In the 1d_nwk layer, the attributes in Table 5.22 can be used to set
up the channel parameters.

@595

Figure 5.13: Schematisation of 1D Dam Failure

Operational control commands specific to the Dam Failure channel are provided below:

Period Failure : sets the time taken to reach the full size of the dam failure.
Top Width Fully Breached : Same as the “Height_or_WF” attribute.
Depth Fully Breached : Same as the “Width_or_Dia” attribute.
Side Slope (degree) : Sets the angle of the side slopes. This is used for calculating the
bottom width and flow area.
Period Collapse : Defines the time taken to form the dam breach opening at the start of the
dam break.
Depth Collapse : defines the depth of the dam crest collapse during Period Collapse at the
beginning of the dam break.
Breach Opening : Sets the dam failure status.

During any period of the dam failure, the Side Slope is set as constant. If the bottom width
calculated from the width, depth and the side slope becomes negative, a V shaped cross-section
is assumed based on the width and the side slope. A DF channel can be subject to one of the
following three flow phases, depending on the upstream water level and state of the breach:

Flow overtopping above the crest level can occur before the dam break. At this stage, all the
water is flowing through the “Intact” section of the dam crest.

Section 5 1D Network Domains - ESTRY - 89 / 130 Page 192 / 1094

 After the dam break commences, the water can flow through both the “Intact” section of the
dam crest (provided the upstream water level is greater than the invert of the intact section),
and the “failed” section. The total flow is reported in the .eof file and the _1d_Q.csv output file,
while the flow rate for each section is reported separately in the _1d_O.csv output file.

Once the maximum breach width is reached or there is no flow over any remaining intact
sections, the flow is confined entirely within the “Failed” section.

The flow calculation through a 1D dam break channel is computed for both the intact and failed
sections, with the user able to set the weir flow equation parameters separately for both sections
as per the table below.

Section 5 1D Network Domains - ESTRY - 90 / 130 Page 193 / 1094

 @596 Table 5.23: .toc Commands to Set Weir Flow Equation Parameters in DF Channel

“Intact” “Failed”
Description
Section Section

Sets the weir channel type using the flags in Table 5.14 . If this
command is not specified, the defaults are “WB” for the Intact
Weir Type Weir Type
section and “WW” for the failed section. Note that the “Side Slope”
Intact Failed
is not considered in the cross-section calculation for non-WW type
weirs.

Cd Intact Cd Failed
Sets the weir coefficient, Cd, in its dimensionless form.

Cf Intact Cf Failed Sets the weir coefficient adjustment factor Cf.

Ex Failed
Ex Intact Sets the weir flow equation exponent Ex.

Sa Intact Sa Failed Sets the submergence factor “a” exponent in the Villemonte
Equation for calculating the weir submergence factor Csf.

Sb Intact Sb Failed Sets the submergence factor “b” exponent in the Villemonte
Equation for calculating the weir submergence factor Csf.

An example of a Define Dam Failure Control block is provided below:

The USBR (1987 ) approach to include an allowance for side or horizontal flow contraction
caused by piers and abutments can be optionally applied for the “Intact” part of a DF channel (see
Section 5.10.7 ). The 2023-03-AB build introduced the following three new commands:

Number of Piers : Sets the number of piers over the weir (the default is zero, 2023-03-AB
build and onwards).
Kp Intact : Sets the pier contraction coefficient (the default is zero, 2023-03-AB build and
onwards).
Ka Intact : Sets the abutment contraction coefficient (the default is zero, 2023-03-AB build
and onwards).

Section 5 1D Network Domains - ESTRY - 91 / 130 Page 194 / 1094

 @597
5.11 Pipe Networks

Pipe networks can be modelled using two different approaches, or a combination of these
approaches:

1. Detailed modelling by defining the physical features of the pipe network using 1d_nwk
channels to represent pipes, 1d_pit or 1d_nwk nodes to represent pits, and 1d_mh nodes to
represent manholes, as discussed within this Section.
2. An approximate approach termed Virtual Pipes is also available if the pipe details are
unknown though inlet and outlet information is available. A Virtual Pipe network can be
modelled using 1d_pit or 1d_nwk nodes to represent inlets and outlets between which flow is
instantaneously transferred or exits the model (i.e. no physical routing is calculated). Virtual
pipes are discussed in Section 5.12 .

Complete 1D pipe networks and Virtual pipe pits can coexist in the same model. From the 2020-10
release and onwards, in TUFLOW HPC, virtual pipe outputs can connect to, and discharge into,
the upstream or downstream end of a channel.

TUFLOW 1D produces a true HGL, with all losses accounted for. Different methods are available
to quantify the losses at junctions and manholes, with the default setting being the Englehund
approach, which automatically adjusts losses every timestep according to the
expansion/contraction of flow, and changes in pipe direction, slope, inverts, etc.

Note that care should be taken in interpreting the HGL profile as the water level output currently
only supports one level, which is the level in the manhole chamber (ie. after expansion losses into
the chamber have been accounted for, or after a free-overfalling pipe outlet discharges into the
manhole). Therefore, especially where upstream controlled flow regimes occur (eg. free outflow),
the profile may appear to intersect the pipe invert profile.

@598
5.11.1 Pipes

Culverts within a pipe network are created by digitising lines within one or more 1d_nwk GIS
layers and assigning a type C, R or I (refer to Section 5.8.1 ). The culverts are considered linked
when the channel ends are snapped to one another or they are connected by a connector (“X”
channel). Connectivity between the underground pipe with the surface above is defined using pits
(see Section 5.11.2 ). Pipe junctions are referred to as manholes in TUFLOW terminology and
can occur with or without pits (see Section 5.11.4 ). TUFLOW includes a range of energy
dissipation options at junctions. These are also discussed in Section 5.11.4 .

@599
5.11.2 Pits

Pits are used for two purposes.

1. In pipe network models (Section 5.11.1 ), pits transfer water between the 2D domain on the
surface and a 1D pipe network underground.
2. In virtual pipe networks (Section 5.12 ), pits define inlet and outlet locations.

Pits are defined by digitising points within one or more 1d_pit or 1d_nwk layers. Of these two
alternatives the 1d_pit layer is the most efficient option. It excludes superfluous attributes included
in the 1d_nwk format that are required for other uses (such as 1D pipe or open channel details).

Section 5 1D Network Domains - ESTRY - 92 / 130 Page 195 / 1094

 Both options are described in the following sections.

The following notes apply to pits:

For pits connected to a channel start or end (usually a pipe), either by snapping or via an “X”
channel, or are within the Pit Search Distance , the pit calculations are carried out by ESTRY
and it is assumed a pipe network is being modelled.
Under this scenario TUFLOW/ESTRY will automatically create a short channel called a
“pit channel” to connect the 2D domain (surface) to the underground 1D pipe network.
The pit channel is computationally “zero length” and does not contribute to any storage in
the system (noting that the Len_or_ANA attribute is used to specify the surface area or
storage of the pit chamber).
The pit inlet capacities curves are specified in a Pit Inlet Database (see Section 5.11.3 )
for “Q” type pits in Table 5.24 .
Unconnected pits, (i.e. pits not snapped/connected to a channel end or within the Pit Search
Distance of a channel end), or VPI and VPO pits, are used for virtual pipe modelling and the
following logic applies:
The virtual pipe pit inlet capacity curves are specified in a Pit Inlet Database (see
Section 5.11.3 ) for a “VPI” or “Q” type pit in Table 5.25 .
VPI and VPO type pits are always treated as disconnected (i.e. virtual pipe inlets or
outlets), even if snapped or within a Pit Search Distance .
For Classic, all unconnected pits and VPI pits are treated as being connected to a
virtual pipe. The pit’s discharge is extracted from the model on the assumption there
are no backwater or surcharging effects at that pit. For example, free flow into the
ocean. Note: VPO pits are not supported in Classic and will show zero flow.
For HPC, all VPI and VPO discharges are calculated by the HPC solver as per the
virtual pipe feature. For all other unconnected pits, their discharges are calculated by
the TUFLOW 1D solver (ESTRY) in the same manner as for Classic above.
A CHECK 1626 message is issued for unconnected pits (excluding VPI and VPO pits),
alerting the modeller to the possibility of a pit possibly being inadvertently not snapped or
within the Pit Search Distance . If all the pits should be connected (excluding VPI and VPO
pits), the user can specify the .ecf command Pit No 1D Connection to force an ERROR 1626
in the case of a pit not being connected by snapping or within the Pit Search Distance .
If a pit cannot be connected to an overland 2D domain (because, for example, it does not fall
on an active cell), a WARNING is issued and the pit channel will remain unconnected.
In the various 1D output and the 1d_nwk check files, the pit channels that are snapped to a
channel end are displayed as a small channel orientated in the north-south axis, not a node
(point). The display length of the channel is, by default, set to 10 m, however, this can be
changed using Pit Channel Offset . For pits connected using Pit Search Distance , the pit is
displayed as extending from its connected node.
Flow through unconnected pits will appear in the mass balance reporting as follows:
Within the _MB2D.csv or _HPC.csv “As SX V In” and “Es SX V Out” SX in and out flow
columns.
For unconnected pits calculated by ESTRY the discharge exiting the model is included in
the _MB1d.csv or _MB.csv “H Vol Out” column.
For HPC VPI and VPO pits the volumes exiting or entering the model are included in the
SX Volumes.
The downstream node of an unconnected pit channel will have a boundary type “V” in the .eof
file as shown below.

Section 5 1D Network Domains - ESTRY - 93 / 130 Page 196 / 1094

 For an unconnected pit, which must have an ID, the upstream and downstream nodes are
assigned .1 and .2 extensions respectively.
If a connected pit’s node ID is left blank the pit channel ID is given a “.P” extension based on
the pit node’s automatically assigned ID (see Section 5.13 ). The upstream (ground) node ID
of the pit channel is given the pit channel’s ID with a “.0” extension.
Minimum NA Pit sets the minimum NA (Nodal Area) of the upstream (ground) nodes for all pit
channels. This command was introduced to differentiate upstream pit channel nodes from the
Minimum NA setting.

@600
5.11.2.1 1d_nwk Pits

Pits are created by digitising points within one or more 1d_nwk GIS layers and setting the “Type”
attribute to C, Q, R or W (refer to Table 5.29 ). Table 5.24 describes the 1d_nwk attributes
required for pits defined in the 1d_nwk format.

Section 5 1D Network Domains - ESTRY - 94 / 130 Page 197 / 1094

 @601 Table 5.24: Pits: 1D Model Network (1d_nwk) Attribute Descriptions

Default GIS
No. Description Type
Attribute Name

Unique identifier up to 12 characters in length. For

pits connected to a 1d_nwk channel, either by being
snapped or connected using Pit Search Distance ,
if ID is blank the pit channel’s ID is automatically
assigned based on one of the connecting channel
IDs. For pits not connected to a channel, ID cannot

1 ID be blank and must be unique. Char(12)

ID may contain any character except for quotes and

commas. As a general rule, spaces and special
characters (e.g. “\”) should be avoided, although
they are accepted. The same ID can be used for a
channel and a node, but no two nodes and no two
channels can have the same ID.

Used to specify a Pit Channel as one of C, Q, R or

2 Type Char(4)
W as per Table 5.29 .

If a “T”, “t”, “Y” or “y” is specified, the object will be

3 Ignore ignored (T for True and Y for Yes). Any other entry, Char(1)
including a blank field, will treat the object as active.

UCS
(Use Channel
4 Not used. Char(1)
Storage at
nodes).

Adds the value specified as additional nodal area

(surface area in m2). If no nodal area data exists for
the node, either via the UCS attribute from the
connected 1d_nwk channels, or via a NA table,
TUFLOW automatically creates an NA table of
constant surface area.

If a negative value is specified, this value is used as

5 Len_or_ANA a multiplier of the node storage. For example, a Float

value of -1.5 increases the nodal storage table (NA
table) by 50% (or to reduce storage use a value
between -1 and 0). Increasing storage can be useful
to stabilise problematic 1D nodes, provided that the
added storage does not adversely distort the
results. This multiplication is applied after any effect
of Minimum Channel Storage Length . Minimum
NA is applied after the multiplication.

6 n_nF_Cd Not used. Float

Section 5 1D Network Domains - ESTRY - 95 / 130 Page 198 / 1094

 Default GIS
No. Description Type
Attribute Name

Used to specify the ground elevation of the pit. This

is used to set the upstream and downstream
elevation of the pit channel. If set to -99999, the
ground elevation is set to the ZC elevation of the 2D
cell that the pit falls within, or the lowest elevation
7 US_Invert sampled if using SGS (provided there is a 2D SX Float

connection – see Conn_1D_2D attribute below).

If Conn_1D_2D is set to “SXL”, US_Invert is used

as the amount by which to lower the 2D cell and the
pit channel invert is set to this level.

The bottom elevation of the pit. Can also be used to

set the upstream and downstream inverts of
8 DS_Invert Float
connected channels – see discussion for US_Invert
for channels above. If set to -99999, not used.

The Form_Loss value is applied as an energy loss

to all outgoing culverts (i.e. culverts that are
digitised as leaving the pit/node), so the Form_Loss
value should be based on the outgoing pipe velocity
(e.g. the K values). Note, it may be necessary to
9 Form_Loss zero or reduce the Entry_Loss and/or Exit_Loss Float
attributes of culverts connected to the pit/node so
that duplication of losses does not occur. This loss
coefficient is not adjusted according to the approach
and departure velocities as documented in
Section 5.8.7 .

The percentage blockage (%) of the pits. Reduces

10 pBlockage the flow capacity through the pit by the specified Float
amount.

For Q pit channels, the name of a pit inlet type in

11 Inlet_Type the Pit Inlet Database (see Section 5.11.3 ). Char(256)
Otherwise not used.

Section 5 1D Network Domains - ESTRY - 96 / 130 Page 199 / 1094

 Default GIS
No. Description Type
Attribute Name

Used to specify a “SX” flag that automatically

creates a 2D SX cell and 1D/2D connection where
the 1D pit occurs. This negates the need to create
SX objects in a 2d_bc layer.

The following options/changes are available:

“SX” can also be used to automatically connect

1D nodes as well as pits to the 2D domain.
“SXL” can be specified to connect the 1D pit to
the 2D domain and lower the 2D cell by the
amount of the US_Invert attribute. The invert of
the pit channel is set to the lowered 2D cell
level. This is useful to help trap the water into
the pit as it flows overland in the 2D domain.
This feature works well in combination with the
Read GIS SA PITS option. If using the SGS
functionality (Section 7.4.3 ), the “L” flag
lowers the minumum cell elevation by the
12 Conn_1D_2D amount of the US_Invert attribute, but retains Char(4)

the original cell volume versus depth curve.

The lowered cell can be made flat as per the
traditional sampling (non-SGS) approach, using
the SGS SX Z Flag Approach command.
However, if the underlying DEM has good
representation of the pit inlet elevation, it is not
recommended to use the “L” flag.
By default, if more than one 2D cell is
automatically connected, pits are assumed to
be connected using the Grade (G) approach
and nodes the Sag (S) approach (see Section
5.11.2.3 ). To override these default
approaches, specify either “SXG” or “SXS”.

Pit Default 2D Connection can be used to set a

global default value for Conn_1D_2D, and up to
four characters is now accepted. “NO” can also be
used to not connect the node or pit to a 2D domain.

Section 5 1D Network Domains - ESTRY - 97 / 130 Page 200 / 1094

 Default GIS
No. Description Type
Attribute Name

If “SX” is specified for Conn_1D_2D, can be used to

control the number of 2D cells connected. See
Section 5.11.2.3 for a discussion on how the 2D
cells are selected.

A positive value increases the number of

automatically selected 2D cells by the value of

13 Conn_No Conn_No. Integer

If negative, this ignores the automatic approach

and fixes the number of 2D cells connected to
the absolute value of Conn_No. For example, a
value of -1 would only connect the pit or node
to one (1) 2D cell irrespective of the connection
width.

C, R, W Pit Type:
For C pits, sets the diameter of the pit inlet cross-
section in the vertical plane. For R and W pits, sets
the width of the pit inlet section in the vertical plane.

14 Width_or_Dia Q Pit Type: Float

Used as a multiplier of the flow derived from the
depth-discharge curve. For example, if
Width_or_Dia equals 2, the flow is doubled. If set to
zero (0), a value of 1.0 is used (i.e. the discharge
curve remains unchanged).

Sets the height of an R pit inlet channel. Not used

15 Height_or_WF Float
for other pit types.

C, R, W Pit Type:
Sets the number of pits (of same dimension) within
the one pit channel.

Q Pit Type:
Used as a multiplier of the flow derived from the
depth-discharge curve. For example, if Number_of
equals 3, this assumes there are three pits lumped
16 Number_of Integer
together and the flow is tripled. If set to zero (0) a
value of 1 is used (i.e. a single inlet pit is assumed).
Multiplies the flow only, additional storage defined
by the Len_or_ANA attribute is not multiplied.
Where a pit is connected to a manhole, increasing
the Number_of attribute will not increase the
number of manholes, or its dimensions; the pits
remain connected to only one manhole.

Section 5 1D Network Domains - ESTRY - 98 / 130 Page 201 / 1094

 Default GIS
No. Description Type
Attribute Name

R Pit Type: Sets the height contraction coefficient,

otherwise not used for other pit types. Usually 0.6
17 HConF_or_WC for square edged entrances to 0.8 for rounded Float
edges. If value exceeds 1.0 or is less than or equal
to zero, it is set to 0.6.

C, R Pit Type: Sets the width contraction

coefficient, otherwise not used for other pit types.
Usually 0.9 for sharp edges to 1.0 for rounded
18 WConF_or_WEx Float
edges for R culverts. Normally set to 1.0 for C pits.
If value exceeds 1.0 or is less than or equal to zero,
it is set to 1.0 for C and 0.9 for R pits.

C, R Pit Type: Sets the entry loss coefficient,

19 EntryC_or_WSa Float
otherwise not used for other pit types.

C, R Pit Type: Sets the exit loss coefficient,

20 ExitC_or_WSb Float
otherwise not used for other pit types.

@602
5.11.2.2 1d_pit Pits

The 1d_pit layer can be used for all types of pits in Classic and HPC, whether connected to a
1d_nwk or a virtual pipe system. Table 5.25 presents the attributes associated with 1d_pit GIS
layer. The 1d_pits attribute table excludes superfluous attibutes included in the 1d_nwk format that
are required for other uses (e.g. pipes and open channels).

Section 5 1D Network Domains - ESTRY - 99 / 130 Page 202 / 1094

 @603 Table 5.25: Pits: 1D Model Network (1d_pit) Attribute Descriptions

Default GIS
No. Description Type
Attribute Name

Unique identifier up to 12 characters in length. For

pits that connect to a 1d_nwk channel, either by
being snapped or connected using Pit Search
Distance , if ID is blank the pit channel’s ID is
automatically assigned based on one of the
connecting channel IDs.

Note VPI and VPO pits are never connected to a

1d_nwk channel, therefore, they always require
Char
1 ID unique IDs. For any pit not connected to a channel,
(12)
ID cannot be blank and must be a unique (channel)
ID.

ID may contain any character except for quotes and

commas. Generally, spaces and special characters
(e.g. “\”) should be avoided, although they are
accepted. The same ID can be used for a pit (which
is converted to a channel) and a node, but no two
nodes and no two channels can have the same ID.

Section 5 1D Network Domains - ESTRY - 100 / 130 Page 203 / 1094

 Default GIS
No. Description Type
Attribute Name

“VPI” or “I” (Virtual Pipe Inlet):

VPI pits are Q pits treated as being disconnected
from all 1d_nwk channels (even if they are snapped
to a channel). For the HPC solver VPIs can optionally
be associated with a VPO (Virtual Pipe Outlet) to
discharge flow back into the 2D domain. For the
Classic 2D solver as of Build 2018-03-AA, all VPI pit
discharges are irretrievably extracted from the 2D
domain. Prior to Build 2018-03-AA a VPI pit could
only be denoted as “I” and would not extract or
surcharge virtual pipe flow unless there was an outlet
(“O”) pit with the same VP_Network_ID. As of Build
2018-03-AA if there is no VPO pit with the same
VP_Network_ID the VPI pit discharge is extracted
from the 2D domain. “VPI” is the preferred notation.

“VPO” or “O” (Virtual Pipe Outlet):

HPC 2D solver only (not used by the Classic 2D
solver). VPOs are treated as being disconnected from
all 1d_nwk channels (even if they are snapped to a
2 Type Char (4)
channel). They act as a discharge of the total or
proportion of VPI inflows on the same
VP_Network_ID back into the 2D domain. Prior to
Build 2018-03-AA a VPO pit could only be denoted as
“O”, however, “VPO” is now the preferred notation.
More than one VPO pit can exist for the same
VP_Network_ID.

“C”, “Q”, “R” and “W”:

As of Build 2018-03-AA, the standard C, Q, R and W
pits can be specified via a 1d_pit layer, and can be
connected, or disconnected, to a 1d_nwk. If a C, Q, R
or W pit is not connected to a 1d_nwk channel, either
by snapping or using Pit Search Distance , the
discharge through the pit is permanently extracted
from the 2D domain. Alternatively, unconnected C, Q,
R or W pits can be treated as an ERROR. For C, R
and W pits, the default width, contraction and weir
coefficients are used – to vary from these use a
1d_nwk layer for the pits.

VP_Network ID (as an integer) used to determine

which outlet(s) the flow into the inlet pits discharges
from (if any). Separate or independent networks (Positive)
3 VP_Network_ID
should have a different network ID. VP_Network_ID Integer
should be a positive integer as some negative integer
numbers are reserved for special purposes.

Section 5 1D Network Domains - ESTRY - 101 / 130 Page 204 / 1094

 Default GIS
No. Description Type
Attribute Name

For a VPI or Q pit, the name of a pit inlet type in the

Char
4 Inlet_Type Pit Inlet Database (see Section 5.11.2 ). Not used
(32)
for other pits.

Only used for VPI pits if using the HPC solver (not
used by the Classic solver). If the total flow into the
VPIs on the same VP_Network_ID exceeds the
maximum outflow capacity of the VPOs of that
VP_Network_ID (see Qmax below), one or more of
the VPI flow rates must be modified. The surcharge
index is used to determine how VPI flows are
adjusted. The VPIs with the lowest surcharge index
are given priority.

When the total inflow of all VPIs exceeds the total

capacity of all VPOs for a VP_Network_ID, the VPI
inflow with the lowest surcharge index is reduced. If
this VPI’s inflow is reduced to zero, this VPI is
permitted to become an outlet (i.e. surcharge) with
the flow rate up to but not exceeding its maximum
outflow (see QMax below). If the total inflow of all
5 VP_Sur_Index remaining VPIs exceeds the maximum outflow plus Float
the maximum outflow of this VPI, then the VPI with
the next highest surcharge index is adjusted using
the same methodology. To prevent a VPI from
surcharging, set QMax to zero.

For example, the ground level at the VPI could be

used for the surcharge index, in which case the
lowest VPIs surcharge first. However, if you have
reliable data for the order in which they tend to
surcharge this could be used. The virtual pipe
network is flow conserving, but not necessarily
energy conserving. The highest VPI could be
incorrectly specified with the lowest surcharge index
in which case water would be flowing uphill!

VPI for the Classic solver: Not used.

VPO, C, Q and W: Not used.

Section 5 1D Network Domains - ESTRY - 102 / 130 Page 205 / 1094

 Default GIS
No. Description Type
Attribute Name

VPI and VPO if using the HPC solver:

For VPOs the maximum flow that can discharge back
into the 2D domain. For VPIs the maximum
surcharge capacity or flow back on to the 2D domain.
To prevent a VPI from surcharging enter a QMax of
0.0 (zero).

If the total flow capacity (sum of QMax values for

VPOs on the same VP_Network_ID) of the VPOs is
6 VP_QMax Float
reached, the inflow to VPIs is restricted and/or
surcharged at the VPIs using VP_Sur_Index value
above.

R pits: Sets the height of the pit section in the vertical

plane.

VPI and VPO for the Classic solver: Not used.

C, Q and W: Not used.

For C pits the diameter of the pit inlet cross-section in

the vertical plane. For R and W pits, the width of the
pit inlet section in the vertical plane.

7 Width For Q and VPI pits the multiplier of width in Pit Inlet Float
Database.

For all pits the width is also used to determine the

number of 2D cells to connect.

Used to control the connection type. For pits this field

must be blank or set to “SX”. If set to blank, is treated
8 Conn_2D as a SX connection. Char (8)

Other options may be provided in the future.

Overwrite the automatically determined number of

connected 2D cells (see Width attribute above).

A positive value increases the number of

automatically selected 2D cells by the value of
Conn_No.
9 Conn_No Integer
If negative, this ignores the automatic approach
and fixes the number of 2D cells connected to
the absolute value of Conn_No. For example, a
value of -1 would only connect the pit or node to
one (1) 2D cell irrespective of the width.

Section 5 1D Network Domains - ESTRY - 103 / 130 Page 206 / 1094

 Default GIS
No. Description Type
Attribute Name

The percentage blockage (%) of the pits. Reduces

the flow capacity through the pit by the specified
amount. For VPI and VPO pits this feature was
10 pBlockage introduced for Build 2016-03-AB, and for C, Q, R and Float
W pits it was introduced for Build 2018-03-AA. Prior
to these builds the pBlockage attribute was reserved
and not used.

Number of (same type of) pits represented by the pit

channel. This optional attribute was introduced for
Build 2018-03-AA. This value will also affect the width
11 Number_of Integer
value used to determine how many 2D cells to
connect to. For example, a value of 2 will double the
connection width.

Sets the lag approach, as described in Section 5.12

:

“None” or Blank - no lag is applied.

12 Lag_Approach “Shift” - Shift method applied. Char (8)
“Decay” - Decay method applied.

This optional attribute was introduced for Build 2023-

03-AB.

Lag value in hours. This optional attribute was

13 Lag_Value Float
introduced for Build 2023-03-AB.

@604
5.11.2.3 Connecting Pits and Nodes to 2D Domains

Both pits and nodes can be automatically connected to 2D domains using the 1d_nwk
Conn_1D_2D attribute (see Table 5.25 and Table 5.24 ). If Conn_1D_2D is set to “SX”,
TUFLOW automatically connects the upstream end of the pit channel or node to the 2D domain.
The 2D cell must be active (Code = 1). If no active 2D cells are found a WARNING 2122 or 2123
is issued. For Classic M2D models WARNING 2037 is given if there is overlapping 2D domains
and more than one 2D cell is active.

The command Pit Default 2D Connection can be used to set the global default value for the
1d_nwk Conn_1D_2D attribute.

By default TUFLOW will connect the 1D pit channel or node to one or more 2D cells at pit
connections. The number of 2D cells selected is a function of the flow (connection) width of the pit
inlet (including the effects of the Number_of and Width_or_Dia 1d_nwk attributes), or the total flow
width of the channels connected to the node. The total width of the 2D cells selected is always
more than the pit inlet width or width of channels. For example, a width of 3.6m on a 2m grid
selects two cells. The advantage of selecting more than one 2D cell is to provide enhanced
stability at the 1D/2D connection when the 1D flow width exceeds the 2D cell size. The number of
2D connection cells is limited to 10 per pit inlet.

Section 5 1D Network Domains - ESTRY - 104 / 130 Page 207 / 1094

 The 1d_nwk Conn_No attribute can be used to change the number of 2D cells connected as
follows.

A positive value adds that number of 2D cells to the automatic number. In the example above,
if Conn_No is set to 1, three (2 + 1) 2D cells are connected. The upper limit is 10 connected
cells.
If Conn_No is negative, this ignores the automatic approach and fixes the number of 2D cells
connected to the absolute value of Conn_No. For example, a value of -1 would only connect
the pit or node to one (1) 2D cell irrespective of the connection width.

If more than one 2D cell is being connected, there are two approaches available for how the 2D
cells are selected.

For pits, the default is the G (on Grade) option that selects the 2nd, 3rd, etc… cells by
traversing to the next highest 2D cell that neighbours the 2D cell(s) already selected (this
includes diagonal cells, i.e. all 8 cells around a cell are considered). These cells are also
automatically lowered to the same height as the first cell so that their ZC value is at or below
the pit inlet.
For nodes, the default is the S (Sag) option that selects the 2nd, 3rd, etc… cells by traversing
to the next lowest 2D cell. The ZC values of these cells are not changed as they are already
at or below the node invert.
The above approaches can be changed using the G (Grade) and S (Sag) flags for the 1d_nwk
Conn_1D_2D attribute. The G approach is that adopted by default for pits and S for nodes. To
override the default approach, specify G or S as appropriate. For example, if the S approach
is preferred for a pit that is draining a depression, specify an S flag for the Conn_1D_2D
attribute (i.e. “SXS”). Note SX must come first before an optional flag is specified.
Note: If Defaults == PRE 2008-08 is specified, the original approach of only selecting one 2D
cell is used, irrespective of the Conn_1D_2D and Conn_No values.
If using SGS, the on Grade and Sag approaches are applied based on the minimum SGS
elevations of the cells.

Note that the conventional approach of using 2d_bc SX points or lines can still be used to connect
1D channel ends. This gives the user complete control over which 2D cells are selected and is
often preferred in situations where large 1D structures are being connected to 2D cells.

@605
5.11.3 Pit Inlet and Depth/Stage vs Discharge Databases

Pit channels can be specified as a Q Type, where flow through the pit is controlled by a depth-
discharge curve defined within the Pit Inlet Database . The database is similar to the BC
Database and is described below. The alternative naming convention Depth Discharge Database
performs the exact same function and can be used instead of Pit Inlet Database . Only a single
Depth Discharge or Pit Inlet Database should be used.

The database is a .csv file usually set up and managed in a Microsoft Excel spreadsheet. The
database file sources depth-discharge curves in other .csv files that are also usually set up and
managed within the same Excel spreadsheet. The TUFLOW Microsoft Excel macro can be used to
export these csv files from the parent spreadsheet. It is available to download at no cost from
www.tuflow.com. The format of the Pit Inlet Database is described in Table 5.26 .

Section 5 1D Network Domains - ESTRY - 105 / 130 Page 208 / 1094

 @606 Table 5.26: Pit Inlet Database Format

Column
Description
No.

Contains the pit inlet type as referenced by the 1d_nwk Inlet_Type attribute (see
1
Table 5.24 ).

Contains the name of the source .csv file that contains the depth-discharge
2
curve.

3 The heading label of the column containing depth within the source .csv file.

4 The heading label of the column containing flow within the source .csv file.

The pit inlet’s nominated full flow area in m2 . Note that the flow area is only used
5 to output a velocity for the pit channel (i.e. it does not have any influence over
the hydraulic calculations).

The pit inlet’s nominated flow width in m. The width is used for the automatic
selection of 2D cells when connecting to a 2D domain (see Section 5.11.2.3 )

6 and for extending the depth discharge curve.

Note: When width is set in 1d_nwk or 1d_pit layer for Q and VPI pits the width
will multiply width in the Pit Inlet Database.

Figure 5.14 shows an example of a Pit Inlet Database .csv file. For the example, if the 1d_nwk
Inlet_Type attribute is set to “M”, TUFLOW searches the first column (Name) until it finds “M” as
highlighted in green in the image below. The source .csv file, pit_inlet_curves.csv is opened and
the occurrence of the labels “Depth” (shaded yellow) and “Type M” (orange) on the same line in
pit_inlet_curves.csv are searched for. The numeric values for these two columns, as shown in the
second image below in yellow and orange, are read and applied as the depth-discharge
relationship for the Q pit channel.

@607

Section 5 1D Network Domains - ESTRY - 106 / 130 Page 209 / 1094

 Figure 5.14: Example of Pit Inlet Database
The depth-discharge curve is applied and extrapolated as follows:

The first coordinate on the curve must be 0, 0 (i.e. zero flow at zero depth).
The depth and flow must be in metres and m3/s or feet and ft3/s if the model is running in US
Customary Units (see Units ).
The depth and flow data entries should be specified as positive values.
The depth value used to derive the discharge through the pit channel is taken as the water
level in the 2D domain less the pit invert (usually the ground/2D level). If the downstream
water level of the pit channel rises above the pit invert, the depth value used for deriving the
pit channel flow is the difference in water level. This provides a smooth transition from
upstream controlled flow to drowned flow. If the pit channel starts to be surcharged (i.e. flow is
reversed), the flow is extracted from the depth-discharge curve using the downstream water
level less the upstream water level (pit invert if dry) as the depth value, and is applied as a
negative discharge so that flow surcharges from the pipe network onto the 2D domain.
If required the curve is extrapolated. An “effective” flow width of the pit inlet is calculated that
gives the same flow at the top of the curve as would orifice flow. The orifice flow equation is
then used to extend the curve indefinitely, using the equation:

@608 2 2
Q = 0.6 ytop wef f ective √2g(y − 0.6 ytop) (5.22)
3 3

Table 5.27 presents the different Q pit flow regimes. These are output to the .eof file next to the
velocity and flow values, and to the _TSF and _TSL output layers (see Sections 14.6 and 15.3.4
).

@610 Table 5.27: Q Pit Flow Regime Flags

Regime Description

N The depth-discharge point is within the bounds of the Q pit curve provided.

The depth is over (exceeds) the highest depth in the Q pit curve and the
O
extrapolated orifice flow equation is being used.

R Reverse (negative) flow is occurring.

Section 5 1D Network Domains - ESTRY - 107 / 130 Page 210 / 1094

 @611
5.11.3.1 Road Crossfall Options

The command Pit Default Road Crossfall increases the depth at Q pits based on the crossfall
slope of the road cross-section. This approach aims to account for changes in ground elevation
that occur at a finer scale than the 2D cell resolution. TUFLOW calculates the water depth that is
used by the Pit Inlet Database using an adjacent side triangle depth approach, instead of the
actual cell flow depth. This is shown in Figure 5.15 . The resulting triangle has the same area as
the vertical flow area in the 2D cell the pit is connected to (i.e. the triangle’s area is the depth in
the 2D cell times the width of the cell).

@612

Figure 5.15: Road Crossfall Option

Use of this command can improve the ability to capture water from 2D cells into pits feeding the
pipe network. Especially for larger cell sizes, the shallow depth that can occur in the cell can be
unrepresentative of the depth at the entrance to the pit, therefore restricting the amount of flow
entering the pit. The larger depth using an equivalent triangle will push more water into the pit
providing a more realistic representation of the pit’s capture.

Note: If using the Sub-Grid Sampling (SGS), and the underlying DEM has good
representation of the road cross-profile, this feature is not needed and should not be used.

@613
5.11.4 Manholes

Manholes are used at pipe junctions for maintenance access and where there is a change in pipe
configuration and/or inlet pit flow entry. Flow energy is dissipated due to:

Expansion/contraction of flow within the manhole chamber and outlet culverts, see Figure
5.16 .
Change in direction of the culverts (e.g. at a bend), see Figure 5.17 .
Change in height and/or invert level of the adjoining culverts, see Figure 5.18 .

@614

Figure 5.16: Flow Expansion/Contraction at a Manhole

@615

Section 5 1D Network Domains - ESTRY - 108 / 130 Page 211 / 1094

 Figure 5.17: Change in Flow Direction at a Manhole
@616

Figure 5.18: Change in Inlet/Outlet Height at a Manhole

The presence of a manhole will override the exit loss of any culvert discharging into the manhole
and the entrance loss of any culvert taking flow out of the manhole. Therefore, the corresponding
Entry_Loss and Exit_Loss attributes of the culverts in the 1d_nwk layer are not used (see Section
5.11.4.4 and the notes on these attributes in Table 5.5 for more information).

There are three different types of manholes:

“C” for circular chambers.

“R” for rectangular chambers.
“J” for culvert junctions without a chamber.

And three different energy loss approaches:

“NO” no special manhole losses (the standard entry/exit losses of the connected culverts
apply).
“EN” for the Engelund loss approach (this is the default approach).
“FX” for the Fixed loss approach.

The manhole loss approach can be selected globally using the command, Manhole Default Loss
Approach .

The manhole types, loss methods and dimensions are output in the _mhc_check file.

@617
5.11.4.1 Automatically Assigned Manholes

By default, manholes are automatically created at all culvert junctions (nodes) where the following
conditions are met.

There is at least one incoming and one outgoing culvert – a culvert is a C, I or R channel.
There are no open channels connected (i.e. no bridges, weirs or any other channel that is not
a culvert/pipe).
Pit channels can be connected, but are not included in any of the calculations for determining
manhole energy losses. Note, however, that the connection of a pit to a manhole (or multiple
pits via the Number_of 1d_nwk pits attribute) may influence the default Engelund losses
indirectly via the introduction of additional flow to the pipe network.

Three different approaches to the sizing of automatic manholes and the application of losses are
available through the .ecf command Manhole Approach . The current default is Method C. This is
the preferred approach unless backward compatibility is required for legacy reasons. Further
details on Methods A and B may be found by referring to the 2018 Manual, Release Notes of
previous TUFLOW builds, or by contacting [email protected].

Section 5 1D Network Domains - ESTRY - 109 / 130 Page 212 / 1094

 The type of manhole assigned is set using Manhole Default Type . If Manhole Default Type is
not specified the default is to assign a C, R or J types based on the size and configuration of
culverts connected to the manhole (see Manhole Default Type for more information).

The minimum diameter/width of a manhole chamber is controlled by Manhole Minimum Dimension

, and the default side clearance and clearance between culverts is set using
Manhole Default Side Clearance .

The default energy loss approach is controlled by Manhole Default Loss Approach .

@618
5.11.4.2 Manually Assigned Manholes (1d_mh Layer)

Manholes are manually assigned at channel ends (nodes) using a 1d_mh layer and Read GIS
Manhole . Any number of 1d_mh layers can be specified. The attributes of a 1d_mh layer are
described below in Table 5.28 .

A manhole in a 1d_mh layer will override any automatically created manhole. If a manually
specified manhole occurs at the same location more than once, the last occurrence will
prevail (i.e. the last manhole at a node will override any previously specified manholes at
the same node).

To remove an automatically created manhole, digitise a point at the node in a 1d_mh layer and set
the Loss_Approach to “NO” (i.e. no manhole energy losses). Note that culvert inlet/outlet losses
will apply instead in accordance with Section 5.8.1 .

Section 5 1D Network Domains - ESTRY - 110 / 130 Page 213 / 1094

 @619 Table 5.28: 1D Manhole (1d_mh) Attribute Descriptions

Default GIS
No. Description Type
Attribute Name

Unique identifier up to 12 characters in length (see ID

for 1d_nwk layers). The ID is used to label the node
that is created at the location of the manhole. If left
1 ID Char(12)
blank, then the ID will be automatically assigned
according to the rules for an automatically created
node as discussed in Section 5.13 .

“C” for circular shaped chamber.

“J” for a junction, but no manhole chamber.

2 Type “R” for rectangular shaped. Char(4)

If left blank, the global default type set by Manhole

Default Type is used.

“NO” for no manhole loss approach (the standard

entry/exit losses of the connected culverts apply).

“EN” for the Engelund loss approach.

3 Loss_Approach Char(4)
“FX” for the Fixed loss approach.

If left blank, the global default type set by Manhole

Default Loss Approach is used.

If set to true (i.e. “T”), the manhole is ignored and

4 Ignore makes no contribution to the final network. Otherwise Char(1)
set to “F”.

The bottom or bed elevation of the manhole. This

attribute is also used to set the upstream and
5 Invert_Level downstream inverts of connected culverts if the Float
culverts have not been assigned an invert. If set to
-99999, not used.

The flow width in metres of the manhole (i.e. the

width of the manhole perpendicular to the dominant
6 Flow_Width direction of flow). For a C manhole this would be the Float
diameter. Used to calculate the manhole flow area
and velocity through the manhole.

The flow length in metres of the manhole (i.e. the

length of the manhole in the dominant direction of
flow). For a C manhole this attribute is not used and
7 Flow_Length Float
the diameter (Flow_Width attribute) is used. Only
used to calculate the storage of the node at the
manhole.

Section 5 1D Network Domains - ESTRY - 111 / 130 Page 214 / 1094

 Default GIS
No. Description Type
Attribute Name

Additional storage surface area in m2 for the node at

8 ANA the manhole. Float
Usually set to zero.

Fixed component of the calculated manhole loss

9 K_fixed coefficient. If using the Fixed approach, this is the Float
only coefficient applied.

Manhole exit coefficient used by the Engelund

approach.

10 Km If set to zero (0), for C manholes the Manhole Default Float

C Exit Coefficient is applied, and for R manholes

Manhole Default R Exit Coefficient is used.

The upper limit of the combination of KƟ and Kdrop in

the Engelund approach.
11 K_Bend_Max Float
If set to zero (0), Manhole K Maximum Bend/Drop is
applied.

12 C_reserved Reserved for future use – leave blank. Char(12)

13 N1_reserved Reserved for future use – leave as zero (0). Float

14 N2_reserved Reserved for future use – leave as zero (0). Float

14 N3_reserved Reserved for future use – leave as zero (0). Float

@620
5.11.4.3 Digitising Culverts Connected to Manholes

During the simulation, a culvert is determined to be an inlet or outlet culvert based on the flow
direction, not the digitised direction of the 1d_nwk object. Therefore, if reverse flow occurs this is
taken into account in determining the appropriate loss coefficients. However, the pre-processing of
the model assumes that the culverts have been digitised in the predominant direction of flow. A
variety of checks are made such as whether both an inlet and an outlet culvert are connected to a
manhole, and ERRORs or WARNINGs and CHECKs are issued if there is an incompatibility.
Therefore, it is strongly recommended that the culverts are digitised consistently in the
downstream direction (i.e. from upstream to downstream).

@621
5.11.4.4 Engelund Manhole Loss Approach

The Engelund energy loss approach at manholes is based on the work of F.A. Engelund, and used
by the MOUSE software (DHI, 2009 ). The adopted approach has been further enhanced through
advice from, and discussions with, staff from Technical Services Branch of the Gold Coast City
Council, Queensland, Australia. This is the default manhole loss approach.

The Engelund approach provides an automatic method for determining the energy loss
coefficients presented below. Of note is that the coefficients are recalculated every timestep, and
therefore vary depending on the flow distribution between inlet and outlet culverts and the depth of

Section 5 1D Network Domains - ESTRY - 112 / 130 Page 215 / 1094

 water within the manhole. The calculated values are output to the _TSL layer so they can be
reviewed/checked over time.

@622

Figure 5.19: Engelund Energy Loss Approach at Manholes

Kentry covers the expansion of flow within the manhole at the outlet of an inlet culvert. The
coefficient overrides the exit loss of the inlet culvert. Its time varying value is shown as the
third value for inlet culvert in the _TSL output layer.
KƟ represents the losses due to a change in direction (i.e. a bend) between inlet and outlet
culverts. KƟ is based on the angle of the digitised lines of the culverts. For the inlet culvert the
last two vertices of the line are used and for the outlet culvert the first two vertices. If the
culvert line is digitised so that it has an unrepresentative first/last segment angle (this may
occur where two parallel culverts have been digitised apart to make it easier to visualise), a
1d_nwk connector (X Type) can be used to connect the start/end of the culvert to the node, so
that the first/last segment is a correct representation of the culvert angle relative to the other
culverts. Refer to Section 5.9.3 for further information.
Kdrop is the loss coefficient due to a change in invert level and culvert height between inlet
and outlet culverts.
KƟ and Kdrop are added and applied as an energy loss for each outlet culvert. The calculated
value is reported as the middle value for outlet culverts in the _TSL output layer. Any
Form_Loss value assigned to the outlet culvert via the 1d_nwk layer is also applied and will
also be included in the _TSL middle value.
Kexit covers the contraction from the manhole and re-expansion of flow within the entrance of
an outlet culvert. It overrides the entrance loss of the outlet culvert and is the first value for
outlet culverts in the _TSL output layer.
Km is the manhole exit coefficient used to calculate Kexit. The default value for Km is
dependent on whether the manhole is of a C or R type, and is set using Manhole Default C
Exit Coefficient or Manhole Default R Exit Coefficient .

The equations used for the Engelund loss approach are provided below.

Qp = Flow in culvert
Qim = Total flow in to manhole
Qom = Total flow out of manhole
yi = Height of inlet culvert
yo = Height of outlet culvert
hi = Inlet culvert invert
ho = Outlet culvert invert
θ = Angle in degrees of inlet culvert relative to outlet culvert
(θ = 0
∘
when the culverts are in line, θ = 90
∘
when the outlet culvert is at right angles)
Qp = Flow in outlet culvert
Wm = Flow width in manhole = 1d_mh width attribute

Section 5 1D Network Domains - ESTRY - 113 / 130 Page 216 / 1094

 ym = Depth of water in manhole
Am = Flow area in manhole
′

Am = Effective flow area in manhole

Ap = Flow area of culvert
Km = Km 1d_mh attribute
Kb = Bend loss coefficient (1d_nwk Form_Loss attribute)
Kf = Fixed loss (1d_mh K_Fixed attribute)
KBend_M ax = Upper limit to sum of Kθ and Kdrop (1d_mh K_Bend_Max attribute)

Qom
Vm =
Am

Qp
Qf = min ( , 1.0)
Qom

′ Wm ym Qom
A m =
Qim

2
Vm
Kentry = [1 − min ( , 1)]
Vp

(applied as an exit loss on the inlet culvert)

2
θ
Kθ = ∑ [Qf min ( 2
, 4)]
inletpipes
90

Qf (ho −hi )(ho +yo −hi −yi )

Kdrop = ∑ [min (max ( , 0) , 2)]
inletpipes yo yi

Ap
Kexit = Km (1 − min ( ′
, 1))
A m

(applied as inlet loss on the outlet culvert)

Koutlet pipe = min (Kθ + Kdrop , KBend ) + Kb + Kf
M ax

(applied as loss using outlet culvert velocity)

@653
5.11.4.5 Fixed Manhole Loss Approach

The Fixed loss approach applies the 1d_mh K_fixed coefficient as an energy loss on the outlet
culvert(s). This is in accordance with publications that quote K values for different manholes based
on the velocity in the outlet culvert.

The energy loss is applied as an inlet loss to the outlet culvert if K_fixed is 0.5 or less. If K_fixed
exceeds 0.5, 0.5 is applied as an inlet loss, and the remainder is applied as a form or bend loss.
The inlet loss component is shown as the first value in the _TSL output layer, and any remainder
as the second (middle) value. Any Form_Loss value assigned to the outlet culvert via the 1d_nwk
layer is also applied and will be included in the _TSL middle value.

By default, K_fixed is set to zero. Therefore, to assign a K_fixed value to any manhole using the
Fixed loss approach will require using a 1d_mh layer.

Note that K_fixed is also used by the Engelund loss approach as an additional (calibration) energy
loss if required.

@654
5.11.4.6 Discussion on Approaches to Modelling Pipe Junction Losses

The approach taken to modelling junctions and manhole losses affects the pipe network’s energy
losses and overland flood levels, especially if a large proportion of the flow is within the pipe
network. As a general guide, the following approaches available in TUFLOW will produce the
following outcomes:

Section 5 1D Network Domains - ESTRY - 114 / 130 Page 217 / 1094

 1. Ideal Scenario: If you are fortunate to have the details and budget to include manholes using
1d_mh layers, this will produce the most reliable results. Either the Engelund approach or
application of fixed losses based on guidance within the literature, or a combination of these,
is recommended. However, in the absence of manhole details, one of the following
approaches, or a combination, needs to be adopted.
2. Least Conservative (flatter hydraulic grade lines along pipes with lower flood levels overall):
No manholes (Manholes at All Culvert Junctions is set to “OFF” and no 1d_mh layers are
specified) and adjustment of structure losses (the default) applies. In this case there will be
minor losses at pipe junctions, because the Structure Losses by default will adjust the
entrance and exit losses at pipe connections down according to the approach/departure
velocities (see equations in Section 5.8.7 ). As the velocities are usually similar from one
pipe to the next the entrance and exit losses are reduced downwards, often close to zero (as
would be expected for a junction of two pipes with no manhole, no change in direction and no
change in invert level).
3. Middle Ground: Automatically create and size manholes and apply the Engelund approach
(the default setting). The automatic creation of manholes may be slightly conservative as a
manhole (including junctions) is created at every closed node (a closed node occurs where
only culverts/pipes and pits are connected). If there are many short pipes in the network an
excess of manholes may result in causing greater energy losses. However, if single very long
culvert channels are used to represent lengths of same sized pipes, any manholes along the
long pipes will not be modelled and losses will be underestimated. In this case it is generally
good practice to split the long culvert channels into several channels (this will also produce an
improved hydraulic grade line along the pipe).
4. Most Conservative (steeper hydraulic grade lines along pipes with higher flood levels
overall): No manholes (Manholes at All Culvert Junctions set to “OFF” and no 1d_mh layers
specified); fixed structure losses on all culverts (Structure Losses set to “FIX” is specified or
1d_nwk “F” flag is used); and the entrance and exit loss coefficients are not adjusted. For
example if 0.5 and 1.0 are used, this will apply the full (e.g. 0.5 and 1.0) entrance and exit
loss coefficients at the pipe junctions. It typically produces the greatest energy losses along
pipe networks, and therefore, produces higher flood levels in upper areas.

@655
5.12 Virtual Pipes

Virtual pipes can be used to simulate flows in drainage networks without full linking to a 1D model
network. A depth flow relationship is applied at inlet locations and the flow is instantaneously
transferred to the outlet location or out of the model (eg. to the ocean). No pipe details are
entered, all model inputs are defined using points defining the pit locations (refer to Section 5.11.2
below) and references to depth flow curves:

The inlet depth discharge capacity curves are specified in a Pit Inlet Database (see Section
5.11.3 ) as per a “VPI” or “Q” type pit in Table 5.25 .
Using virtual pipes, the flows at the inlet and outlet can be limited. If the outlet becomes
limited, the inlet capacity is reduced and pits can surcharge. The order in which pits are
limited / surcharge is discussed in Section 5.11.2.2 ).
The flows and water levels for each inlet and outlet are output to .csv files and _TS GIS
layers. Note that the downstream pit level is not known nor is needed for the calculations as
the pit is always assumed to have no downstream influence, therefore, the downstream levels
are output as 10m below the upstream level.

Section 5 1D Network Domains - ESTRY - 115 / 130 Page 218 / 1094

 Virtual Pipes were introduced to TUFLOW Classic and HPC in the 2018-03-AA release. Prior to
build 2018-03-AA virtual pipes were only available in TUFLOW HPC / GPU.

From build 2023-03-AB or later it is possible to lag virtual pipe flows from the inlet to the outlet.
Two additional attributes are required, and these are output in empty files written with the 2023-
03-AB or later build of TUFLOW. These additional 1d_pit attributes are described in Table 5.25
below. These data are input on the inlets (VPI).

Two approaches are available for lagging flows, these are “Shift” and “Decay”. For the shift
method, the outflow is lagged (shifted) by the lag value time, but is otherwise unchanged.

The decay method is based on exponential filtering of the inflow. A “current internal volume” is
tracked:

T
@656
Q(T ) = ∫ [Q̇ (t) − Q̇ (t)]dt (5.23)
in out
0

The outflow rate is computed from the internal volume and the time constant (the Lag_Value
attribute):

@658 ˙
Q(t)
Qout (t) = (5.24)
Lag_V alue

Figure 5.20 below shows the lag approaches applied with a lag value of 60 seconds which is
input as 0.0167 hours. All pits with the same VP Network ID (i.e. form a local network) must use
the same approach and Lag_Value.

@660 @661 @669

6

0
0
30
60
90
120
150
180

Figure 5.20: Virtual Pipe Lag Methods

Section 5 1D Network Domains - ESTRY - 116 / 130 Page 219 / 1094

 @670
5.13 Nodes Inflow
Outflow: Shift Method
Outflow: Decay Method
Nodes must be defined (either automatically or manually) at the ends of channel elements. They
provide storage information, and the 1D water level (the mass balance equation) is calculated at
the nodes. Nodes are created in several ways:

Automatically, at channel ends (Section 5.13.1 ).

Flow (m​3​/s)
Manually, as digitised points in a 1d_nd or 1d_nwk layer (Section 5.13.2 ).
From a pit in a 1d_pit or 1d_nwk layer (Section 5.11.2 ).
From a manhole in a 1d_mh layer (Section 5.11.4 ).

Note: The use of the term “node” in this manual refers to both manually digitised nodes
and nodes that are automatically created at the ends of channels where no digitised nodes
exist.

Table 5.29 below lists the available node types.

@671 Table 5.29: 1d_nwk Point Object Types

Channel/Node Type Time (s)

Description

Node
Node (or leave Used for manually assigning nodal storage or invert levels.
blank)

Circular (in the vertical) pit channel inlet (see Section

Circular Culvert C
5.11.2.2 ).

Depth-Discharge A pit channel whose flow is defined by a depth-discharge

Q
Pit or Channel curve from a database of curves (see Section 5.26 ).

Rectangular A rectangular (in the vertical) pit channel inlet (see Section
R
Culvert 5.11.2.2 ).

A weir (in the vertical) pit channel inlet (see Section

Weir W
5.11.2.2 ).

Storage at a node is defined either:

automatically via:
the widths and lengths of the connected channels (see Section 5.13.1 );
manually via:
a user defined storage table of elevation versus surface area (NA tables – see Section
5.13.2.1 ); or
a manually defined Node type 1d_nd or 1d_nwk point objects (see Section 5.13.2 ).
a combination of the above using the Len_or_ANA attribute to add additional storage to the
automatic storage.

All nodes must have their storage defined by one of these approaches.

Note that checks are also made for the following.

The lowest elevation of a node must be below the lowest channel connected to the node.
The highest elevation of a node is used to detect instabilities. Therefore, the highest elevation
should be above the highest expected water level, unless Depth Limit Factor is used to

Section 5 1D Network Domains - ESTRY - 117 / 130 Page 220 / 1094

 extend storage properties above the highest elevation.
The storage (surface area) of a node must not be zero at any level.

It is important to note the logic in assigning node storage:

1. User defined NA tables take precedence (see Section 5.13.2.1 ). The overwrite principle
applies, so that if a NA table has been previously defined, the latter NA table prevails.
2. Nodes without any NA tables assigned as for Step 1 above, and which have one or more
connected channels that have the UCS attribute left blank or set to “Y” or “T”, have their NA
table automatically calculated from the channel widths (see Section 5.13.1.1 ).
3. The Len_or_ANA attribute of a node (or pit) in a 1d_nwk layer can be used to add additional
surface area to the NA table. If no NA table exists after the above steps, and the Len_or_ANA
attribute is greater than zero, a NA table of constant surface area is created.
4. If there are any nodes remaining without a NA table, an ERROR occurs.

@672
5.13.1 Automatically Defined Nodes

If a node has not been digitised at the end of a channel a new node is automatically created. The
ID of the automatic node is the first ten characters of the Channel ID with a “.1” or “.2” extension.
“.1” is used if the node is at the start of the channel and “.2” if at the end in the direction digitised.
If more than one channel is connected to the created node, the Channel ID that occurs first
alphanumerically is used. The automatic creation of nodes can be switched off using Create
Nodes . If automatic creation of Nodes is turned off, a manually defined node must be specified
at the ends of each channel in the model.

The automatic node approach is used in Tutorial Module 5.

The nodal storage for the automatically created nodes consists of 3 parts:

Storage calculated from channel/pipe widths;

Storage added from the len_or_ANA attribute of the connected pits/nodes/manholes; and
Storage above the top of channels (Section 5.13.3 ).

@673
5.13.1.1 Storage Calculated Automatically from Channel Widths

The channel storage is, by default, automatically assigned to the nodes at the channel’s ends. The
channel storage approach is invoked using the 1d_nwk UCS attribute, see Table 5.18 . If the
attribute is left blank or set to “Y” (yes) or “T” (true), the channel storage is assigned to the two
nodes at the channel’s ends, with the storage split equally between the nodes. For each node the
surface area at different elevations is calculated as the product of the channel width by half the
channel length. The channel slope is taken into account when distributing the storage. This
approach applies for both 1D open channel networks and 1D pipe networks.

@674

Section 5 1D Network Domains - ESTRY - 118 / 130 Page 221 / 1094

 Figure 5.21: Nodal Storage in Open Channel & Pipe Networks
This approach does not require any specification of a NA table and is therefore the easiest to
implement. It is suited to open channel or pipe network nodes where the storage is accurately
defined using the channel widths. For example, nodes connecting channels that model the in-bank
flow paths of a river. It may not be suited to, for example, floodplain areas where the storage may
differ significantly from that calculated using the widths of the floodplain channels.

Care should be taken using this option for G or S channels that have very steep slopes – check
that the resulting calculated NA table in the .eof file is satisfactory.

Some structures such as pits, weirs, gates and etc., are treated as ‘zero-length’ channel. These
channels do not add storage to the connected nodes, unless a non-zero ‘Len_or_ANA’ value is
specified (See Section 5.13.1.2 ).

Nodal storage is not automatically calculated based on the channel width and length if the 1d_nwk
UCS attribute is set to “N” (no) or “F” (false). This would require manual specification of an NA
table (see Section 5.13.2.1 ).

@675
5.13.1.2 Additional Storage Added from Len_or_ANA Attribute

The Len_or_ANA attribute can be used to add extra storage to the connected nodes. For example,
the Len_or_ANA attribute of a 1D_nwk pit layer can be used to specify the additional nodal
storage of a manhole chamber. Similarly, the Len_or_ANA attribute of a 1D_nwk weir layer can be
used to set the additional nodal storages of a broad crest weir. This extra storage may also be
useful for stabilising a 1D node provided relatively negligible additional amounts of storage are
added. Below is the summary of 1D layers that support the Len_or_ANA attribute:

1D_nwk pit or node layer;

1d_nd and 1d_mh layer;
1d_nwk weir, gate, spillway and etc.; and
1d_bg layer.

Please see the attribute table of each layer for more details.

Note that a minimum storage area of 1 m2 applies to all nodes (except for the upstream (ground)
nodes of pit channels) for simulation stability. If any ‘Len_or_ANA’ value is less than 1 m2 it might
not be reflected in the NA table. This minimum value can be adjusted using the Minimum NA and
the Minimum NA Pit commands.

Section 5 1D Network Domains - ESTRY - 119 / 130 Page 222 / 1094

 @676
5.13.2 Manually Defined Nodes

Table 5.30 lists the attributes required for manually created nodes in the 1d_nwk layer format,
used with the Read GIS Network command. Table 5.31 lists the attributes required for manually
created nodes in the 1d_nd format with the Read GIS Node command – essentially an updated,
cutdown version of the 1d_nwk format that removes unnecessary input fields. Both formats remain
supported.

These attribute descriptions are for basic “Node” type 1d_nwk point objects. These may be used
for assigning storage and invert levels to channels. They can also be used to automatically link 1D
nodes to the 2D domains (without the need to digitise objects within a 2d_bc layer). The 1D/2D
link functionality is discussed in detail within Section 10.3.3 .

If an ID is specified it must be unique amongst all nodes, and up to 12 characters in length. It may
contain any character except for quotes and commas. As a rule, spaces and special characters
(e.g. “\”), should be avoided although they are accepted. A node ID can be used for a channel
(i.e. a channel and node can have the same ID), but not for another node. The Ignore attribute can
be used to ignore a node. It is recommended for the 1d_nwk Type attribute that “Node” is entered
to easily distinguish nodes from channels when querying objects in the GIS, or alternatively place
the nodes and pits in separate 1d_nwk layers.

This section does not provide information on pit type nodes (C, Q, R or W) that also use the
1d_nwk file format. Refer to Section 5.11.2 for information about pit type nodes.

Section 5 1D Network Domains - ESTRY - 120 / 130 Page 223 / 1094

 @677 Table 5.30: Nodes: 1D Model Network (1d_nwk) Attribute Descriptions

Default GIS
No. Description Type
Attribute Name

Unique identifier up to 12 characters in length. It

may contain any character except for quotes and
commas and cannot be blank. As a rule, spaces
and special characters (e.g. “\”) should be avoided,

1 ID although they are accepted. The same ID can be Char(12)

used for a channel and a node, but no two nodes
and no two channels can have the same ID.

Digitised nodes can have their ID left blank and

TUFLOW will assign an ID.

Leaving this attribute blank or specifying “Node” will

2 Type define the point feature as a Node type. “Node” is Char(4)
recommended for easy identification.

If a “T”, “t”, “Y” or “y” is specified, the object will be

3 Ignore ignored (T for True and Y for Yes). Any other entry, Char(1)
including a blank field, will treat the object as active.

4 UCS Not used. Char(1)

Adds the value specified as additional nodal area

(surface area in m2). If no nodal area data exists for
the node, either via the UCS attribute from the
connected 1d_nwk channels, or via NA table,
TUFLOW automatically creates an NA table of
constant surface area set to this value with an
elevation range based on the US_Invert and
DS_Invert values.

If a negative value is specified, the absolute of this

5 Len_or_ANA value is used as a multiplier of the node storage. Float

For example, a value of -1.5 increases the nodal

storage table (NA table) by 50% (or to reduce
storage use a value between -1 and 0). Increasing
storage can be useful to stabilise problematic 1D
nodes, provided that the added storage does not
adversely distort the results. This multiplication is
applied after any effect of Minimum Channel
Storage Length . Minimum NA is applied after the
multiplication.

6 n_nF_Cd Not used. Float

Section 5 1D Network Domains - ESTRY - 121 / 130 Page 224 / 1094

 Default GIS
No. Description Type
Attribute Name

If no NA table exists and Len_or_ANA is greater

than zero, used to set the upper elevation of the NA
7 US_Invert table. Note that in this case if US_Invert is less than Float
DS_Invert, US_Invert is set to the DS_Invert plus 5
metres.

If no NA table exists and Len_or_ANA is greater

than zero, used to set the bottom elevation of the
NA table.

Also used to set the upstream and downstream

8 DS_Invert inverts of connected open channels, culverts/pipes Float
and other channel types – as an example see
discussion for US_Invert in Table 5.3 . Also see
Section 5.13.2.2 .

If set to -99999, not used.

9 Form_Loss Not used. Float

10 pBlockage Not used. Float

11 Inlet_Type Not used. Char(256)

Section 5 1D Network Domains - ESTRY - 122 / 130 Page 225 / 1094

 Default GIS
No. Description Type
Attribute Name

Used to specify a “SX” or “SXZ” flag that

automatically creates a 2D SX cell and connection
at the 2D cell within which the 1D node occurs. This
negates the need to create SX objects in a 2d_bc
layer (see Flags attribute in Table 8.6 ). Notes:

“SXZ” flag lowers the 2D cell centre elevation to

match the invert of the 1D node (i.e. channel or
pipe end). If using the SGS functionality
(Section 7.4.3 ), the lowered 2D cell retains
the original cell volume versus depth curve, but
the minumum cell elevation is lowered to match
the invert of the 1D node. The lowered cell can
be made flat as per the traditional sampling
(non-SGS) approach, using the SGS SX Z Flag
12 Conn_1D_2D Char(4)
Approach command. However, if the
underlying DEM has good representation the
ground elevation of the structure inlet/outlet, it
is not recommended to use the “Z” flag.
By default, if more than one 2D cell is
automatically connected, nodes are assumed
to be connected using the Sag (S) approach
(see Section 5.11.2.3 ). To override the default
approach, specify “SXG” for an on-grade
connection.
From 2017 onwards, the SXL option is no
longer supported for Nodes (Type = Node or
blank). SXL is only available for Pit objects
(Type = C, Q, R, W).

Section 5 1D Network Domains - ESTRY - 123 / 130 Page 226 / 1094

 Default GIS
No. Description Type
Attribute Name

If “SX” is specified for Conn_1D_2D, can be used to

control the number of 2D cells connected. See
Section 5.11.2.3 for a discussion on how the 2D
cells are selected.
The number of 2D cells connected can be
controlled by using:

A positive value increases the number of

automatically selected 2D cells by the value of
Conn_No.
13 Conn_No A negative value, this ignores the automatic Integer
approach and fixes the number of 2D cells
connected to the absolute value of
Conn_No. For example, a value of -1 would
only connect the pit or node to one (1) 2D cell
irrespective of the width.

Note that if a culvert with more than one barrel is

connected to the node, the number of barrels is
used to set the width, which controls the number of
automatically selected SX cells.

If “SX” is specified for Conn_1D_2D, can be used to

control the number of 2D cells connected. For
14 Width_or_Dia example, if a width of 3.6m is entered on a 2m grid, Float
two boundary cells are automatically created and
connected.

15 Height_or_WF Not used. Float

16 Number_of Not used. Integer

17 HConF_or_WC Not used. Float

18 WConF_or_WEx Not used. Float

19 EntryC_or_WSa Not used. Float

20 ExitC_or_WSb Not used. Float

Section 5 1D Network Domains - ESTRY - 124 / 130 Page 227 / 1094

 @678 Table 5.31: 1D Model Network (1d_nd) Attribute Descriptions for Nodes

Default GIS
No. Attribute Description Type
Name

Unique identifier up to 12 characters in length. It may

contain any character except for quotes and commas
and cannot be blank. As a rule, spaces and special
characters (e.g. “\”) should be avoided, although they

1 ID are accepted. The same ID can be used for a channel Char(12)

and a node, but no two nodes and no two channels can
have the same ID.

Digitised nodes can have their ID left blank and

TUFLOW will assign an ID.

Not used for Nodes although it can be recommended to

2 Type Char(4)
type in “Node” for easy identification.

If a “T”, “t”, “Y” or “y” is specified, the object will be

3 Ignore ignored (T for True and Y for Yes). Any other entry, Logical
including a blank field, will treat the object as active.

If no NA table exists and Len_or_ANA is greater than

zero, used to set the bottom elevation of the NA table.

Also used to set the upstream and downstream inverts

4 Bed_Level of connected open channels, culverts/pipes and other Float
channel types – as an example see discussion for
US_Invert in Table 5.3 . Also see Section 5.13.2.2 .

If set to -99999, not used.

Adds the value specified as additional nodal area

(surface area in m2). If no nodal area data exists for the
node TUFLOW automatically creates an NA table of
constant surface area using this value.

If a negative value is specified, the absolute of this

value is used as a multiplier of the node storage. For

5 ANA example, a value of 1.5 increases the nodal storage Float

table (NA table) by 50% (or to reduce storage use a
value between -1 and 0). Increasing storage can be
useful to stabilise problematic 1D nodes, provided that
the added storage does not adversely distort the results.
This multiplication is applied after any effect of Minimum
Channel Storage Length . Minimum NA is applied
after the multiplication.

Section 5 1D Network Domains - ESTRY - 125 / 130 Page 228 / 1094

 Default GIS
No. Attribute Description Type
Name

Used to specify a “SX” or “SXZ” flag that automatically

creates a 2D SX cell and connection at the 2D cell
within which the 1D node occurs. This negates the need
to create SX objects in a 2d_bc layer (see Flags
attribute in Table 8.6 ).

Notes:

“SXZ” flag lowers the 2D cell centre elevation to

match the invert of the 1D node (i.e. channel or
pipe end). If using the SGS functionality (Section
7.4.3 ), the lowered 2D cell retains the original cell
volume versus depth curve, but the minumum cell
elevation is lowered to match the invert of the 1D

6 Conn_1D_2D node. The lowered cell can be made flat as per the Char(4)
traditional sampling (non-SGS) approach, using the
SGS SX Z Flag Approach command. However, if
the underlying DEM has good representation the
ground elevation of the structure inlet/outlet, it is not
recommended to use the “Z” flag.
By default, if more than one 2D cell is automatically
connected, nodes are assumed to be connected
using the Sag (S) approach (see Section 5.11.2.3
). To override the default approach, specify “SXG”
for an on-grade connection.
From 2017 onwards, the SXL option is no longer
supported for Nodes (Type = Node or blank). SXL is
only available for Pit objects (Type = C, Q, R, W).

Section 5 1D Network Domains - ESTRY - 126 / 130 Page 229 / 1094

 Default GIS
No. Attribute Description Type
Name

If “SX” is specified for Conn_1D_2D, can be used to

control the number of 2D cells connected as follows.
See Section 5.11.2.3 for a discussion on how the 2D
cells are selected.
The number of 2D cells connected can be controlled by
using:

A positive value increases the number of

automatically selected 2D cells by the value of
Conn_No.
7 Conn_Width Float
If negative, this ignores the automatic approach and
fixes the number of 2D cells connected to the
absolute value of Conn_No. For example, a value
of -1 would only connect the pit or node to one (1)
2D cell irrespective of the width.

Note that if a culvert with more than one barrel is

connected to the node, the number of barrels is used to
set the width, which controls the number of
automatically selected SX cells.

8 R1 Reserved for future use Float

9 R2 Reserved for future use Float

10 R3 Reserved for future use Float

@679
5.13.2.1 Storage Nodes (User Defined NA Tables)

Storage at an existing node can be manually defined using an elevation versus surface area table
(NA table – NA stands for Nodal surface Area). This provides the opportunity to accurately define
the storage of the floodplain including any backwater areas that do not act as flow paths.

The NA table must be in a comma delimited file (.csv). By default, unique NA table csv files should
be defined for each individual location where desired. Within the NA table csv file the first column
lists the elevation (m or ft) information and the second column lists the corresponding surface area
(m2 or ft2). TUFLOW uses these inputs to define storage volume variation with height.

The NA table is associated with a spatial location with the model via a 1d_na layer using the ECF
command Read GIS Table Links . Similar to the other table link GIS layers (1d_xs and 1d_bg),
1d_na GIS layers and .csv files are often stored in a separate folder underneath the model folder
(i.e. same level as the gis folder):

1d_na for nodal surface area tables in TUFLOW\model\na

1d_xs for cross-section tables in TUFLOW\model\xs
1d_bg for bridge loss tables in TUFLOW\model\bg

Unlike the other table link GIS layers (1d_xs and 1d_bg) the 1d_na layer must be digitised as a
point, not a line. Table 5.32 presents the attributes of a 1d_na GIS layer.

Section 5 1D Network Domains - ESTRY - 127 / 130 Page 230 / 1094

 1d_na point objects do not create a 1d_nwk node, but they do assign additional storage where
nodes already exist. As such, 1d_na point objects must be snapped to a 1d_nwk node point
object, or the end of a channel (where automatic nodes are created).

Minimum NA is useful for stabilising 1D nodes that have small surface areas, particularly at
shallow depths or when wetting and drying. The Minimum NA value is not applied to
automatically created NA tables for any node with a 1d_nwk Length_or_ANA value that is greater
than 0.001m2, provided there is no NA table that has been manually specified or created from
channel storages. See also Minimum NA Pit .

Minimum Channel Storage Length can be useful to add additional storage for stability reasons to
nodes at the ends of very short channels.

@680 Table 5.32: 1D Nodal Area Table Link (1d_na) Attribute Descriptions

Default GIS
No. Attribute Description Type
Name

Filename (and path if needed) of the file containing the

1 Source tabular data. Must be a comma or space delimited text Char(50)
file such as a .csv file.

“NA”: Nodal surface area versus height table. The first

2 Type Char(2)
column is elevation and the second surface area in m2.

3 Flags No optional flags available Char(8)

Optional. Identifies a label in the Source file that is the

header for the first column of data. Values are read
from the first number encountered below the label until

4 Column_1 a non-number value, blank line or end of the file is Char(20)

encountered.

If this field is left blank, the first column of data in the

Source file is used.

Optional. Identifies a label in the Source file that is in

the header for the second column of data.
5 Column_2 Char(20)
If this field is left blank, the next column of data after
Column_1 is used.

6 Column_3 Not used. Char(20)

7 Column_4 Not used. Char(20)

8 Column_5 Not used. Char(20)

9 Column_6 Not used. Char(20)

10 Z_Increment Not used. Float

11 Z_Maximum Not used. Float

Skew
12 Not used. Float
(in degrees)

Section 5 1D Network Domains - ESTRY - 128 / 130 Page 231 / 1094

 @681
5.13.2.2 Using Nodes to Define Channel Inverts

1D nodes can be used to set the inverts of connected channels. Channel inverts are sourced from
either, end cross-sections (see Section 5.7.6 ) or nodes if an upstream or downstream channel
invert of -99999 is specified within the 1d_nwk file.

For this option, the basic “Node” type point objects (see Table 5.30 and Table 5.31 ) can be
used to set the upstream and downstream inverts of any connected channels via the “DS_Invert”
attribute in the 1d_nwk format, or “Bed_Level” attribute in the 1d_nd format. If both nodes and
cross-sections are specified the cross-section is given higher priority (refer to Section 5.7.5 ).
This feature is useful during pipe network modelling, where cross-sections are not required (the
shape is defined by the culvert type). The downstream inverts (of incoming channels) and
upstream invert (of outgoing channels) will be set to the node elevation. In order to model different
incoming and outgoing inverts (for manhole drop losses) these need to be specified on the
channels.

@682
5.13.2.3 Automatically Connecting Nodes to 2D domains

1D nodes may be automatically connected to 2D domains using the Conn_1D_2D attribute in

either the 1d_nwk (see Table 5.30 ) or 1d_nd (see Table 5.31 ) layers. The approach is similar to
the connection of 1D pits to a 2D domain and further discussion may be found in Section 5.11.2.3
.

@683
5.13.3 Storage Above Top of Channels

For 1D open channels, the storage area above the highest elevation in the CS or NA table is
extended by 10 times the depth the CS or NA table. If the water level exceeds that limit, TUFLOW
will exit with an ‘UNSTABLE’ 1D water level error. This limit can be adjusted using the Depth Limit
Factor command (the default value is 10).

For 1D pipes/culverts, the storage above the structure obvert is extended by 5m. By default, it
applies 5% of the maximum surface area of the node. This small nodal area is needed to simulate
the pressurised flow through pipes/culverts, noting it does not affect the conveyance of the
pipe/culvert. For models where the storage contributed by culverts and bridges is significant
(e.g. an urban pipe model), use Storage above Structure Obvert to minimise the storage
contributed by these channels above their obvert (note that some storage is necessary to prevent
a divide by zero in the equations). Note that this additional storage rarely has any demonstrable
affect on the hydraulics as pipe systems tend to be conveyance dominated and the conveyance is
not affected by this feature. This is easily checked by running a sensitivity test that, for example,
halves (or doubles) the additional storage by changing the Storage above Structure Obvert value.

References

@685
@684
Austroads. (1994). Waterway Design - a Guide to the Hydraulic Design of Bridges, Culverts and
Floodways. https://austroads.com.au/

Section 5 1D Network Domains - ESTRY - 129 / 130 Page 232 / 1094

 @686
Austroads. (2018). Guide to Bridge Technology Part 8, Hydraulic Design of Waterway Structures.
https://austroads.com.au/

@687M. (1989). Discharge Measurement Structures (3rd revised edition.). International Institute
Bos,
for Land Reclamation; Improvement. https://www.samsamwater.com/library/pub20.pdf

@688
Bradley, J. (1978). Hydraulics of Bridge Waterways (HDS 1, FIWA). Bridge Division.
https://www.fhwa.dot.gov/engineering/hydraulics/pubs/hds1.pdf

@689 (2009).
DHI. MOUSE PIPE FLOW – Reference Manual. Danish Hydraulic Institute.
https://manuals.mikepoweredbydhi.help/2017/Cities/MOUSEPipeFlowReference.pdf

@690
Henderson, F. (1966). Open Channel Flow. Macmillan.

@691
HR Wallingford. (1988). Afflux at Arch Bridges. https://eprints.hrwallingford.com/219/1/SR182-
Afflux-arch-bridges-HRWallingford.pdf

@692 C. (2004). TUFLOW Testing and Validation (B. ENG. Christopher Dylan Huxley, Ed.)
Huxley,
[Thesis].
https://www.tuflow.com/Download/Publications/TUFLOW%20Validation%20and%20Testing,%2
0Huxley,%202004.pdf

@693 D. (1994). Discharge Characteristics IAHR Hydraulic Structures Design Manual (No. No.8;
Miller,
pp. 249 pages). Hydraulic Design Considerations, Balkema Publ.

@694
Morrison, W., & Smith, P. (1978). A Practical Application of a Network Model Numerical Simulation
of Fluid Motion. North Holland Publishing Company.

@695 P., & Syme, B. (2016). ARR blockage: Numerical implementation and three case studies.
Ollett,
http://www.hydralinc.com/wp-content/uploads/Ollett-Syme-2016-ARR-Blockage.pdf

@696 B., & Robinson, S. (2008). Quantifying Culvert Exit Loss. Journal of Irrigation and Drainage
Tullis,
Engineering, Vol. 134(No. 2), pp. 263–266.

@697
USACE. (1977). Hydraulic Design Criteria-Sheets 312. US Army Corp of Engineers.
https://apps.dtic.mil/sti/tr/pdf/ADA092238.pdf

@698 (1987). Design of Small Dams [Technology & Engineering]. U.S. Dept. of the Interior,
USBR.
Bureau of Reclamation, 1987-. https://www.usbr.gov/tsc/techreferences/mands/mands-
pdfs/SmallDams.pdf

@699 W., Witheridge, G., Rigby, E., Barthelmess, A., & O’Loughlin, G. (2013). Australian Rainfall
Weeks,
and Runoff Revision Project 11: Blockage of Hydraulic Structures. Austalian Institute of
Engineers. https://doi.org/P11/S2/021

@700
Witheridge, G. (2009). Hydraulic Analysis of the Debris Blockage of Culvert Inlets. Catchments &
Creek Pty Ltd.

Section 5 1D Network Domains - ESTRY - 130 / 130 Page 233 / 1094

 @705

@706
Section 6 1D Network Domains - EPA SWMM

@707
6.1 Introduction

This chapter of the manual is written in USA English for the predominantly USA centered SWMM
user base.

TUFLOW has supported 1D/2D dynamic coupling since its initial 2D solver development in 1989.
Traditionally, 1D (1 Dimensional) linking and associated modeling has been applied using the
ESTRY 1D solver (see Section 5.1 ). New in the 2023-03-AF release, TUFLOW’s 1D linking and
solver options have been expanded to support the EPA Storm Water Management Model (referred
to herein as SWMM). As such, 1D pipe networks can now be modeled using either the ESTRY,
SWMM, or a combination of the two 1D solvers. In addition to this, extra functionality, such as
SWMM hydrology and SWMM Low-impact developments (LIDs) features, can now be used in
TUFLOW.

SWMM is a widely used software program for simulating urban and non-urban watersheds’
hydrologic and hydraulic behavior. Developed in the early 1970s by the Environmental Protection
Agency (EPA), the model has since undergone numerous updates and enhancements to become
one of the most used 1D stormwater runoff and water quality analysis tools globally, particularly in
North America.

The primary uses of SWMM include designing and evaluating stormwater management practices,
planning, and assessing low-impact development techniques, and developing models for
floodplain mapping and emergency response planning. The software allows users to simulate a
wide range of storm events and analyze the impact of a range of factors, such as land use
changes, climate variability, and water quality control measures, on the performance of stormwater
management systems. More information about SWMM can be found on the EPA website.

@708
6.1.1 TUFLOW-SWMM Capabilities

Combined TUFLOW (2D) and SWMM (1D) models have a variety of applications and capabilities.
Features built into TUFLOW-SWMM include:

1D/2D SWMM/TUFLOW linkage through direct connections (TUFLOW HX and SX).

All inbuilt SWMM stormwater inlet types are supported, including a wide variety of shapes.
Both on-sag and on-grade stormwater inlet connections are also supported.
SWMM Inlets can surcharge into the TUFLOW 2D domain if the 1D pressure head exceeds
the 2D water level.

Section 6 1D Network Domains - EPA SWMM - 1 / 16 Page 234 / 1094

 SWMM 1D inflows can be sourced from: external boundary conditions specified in SWMM,
rainfall routed through SWMM subcatchments, or via 2D linkages from TUFLOW to SWMM.
SWMM hydrology subcatchment routing, including allowance for infiltration, groundwater
levels, evaporation, and snow melt.
Low-impact developments (LIDs) features for modeling green infrastructure.
Scenario support through the ability to combine multiple SWMM project files (inp) in a single
TUFLOW model. This feature is a powerful way to explore multiple setup options without
duplicating information.

The TUFLOW QGIS Plugin has been expanded to assist with building SWMM models, linking
TUFLOW-SWMM models, and viewing SWMM outputs in a GIS environment. The SWMM GIS
tools are discussed in Section 6.3 .

Currently, TUFLOW does not connect the AD (advection-diffusion) module or the TUFLOW
groundwater (interflow) capability to the SWMM network.

@709
6.1.2 Additional SWMM User Resources

This manual documentation does not duplicate SWMM information available elsewhere. Useful
additional SWMM resources are listed below:

TUFLOW-SWMM Tutorials: Topics covered by the free tutorials include:

TUFLOW-SWMM Module 1 - 1D SWMM Culverts.
TUFLOW-SWMM Module 2 - 1D SWMM Pipe Network / 2D TUFLOW Direct Rainfall
Hydrology.
TUFLOW-SWMM Module 3 - 1D SWMM Pipe Network / 1D SWMM Urban Hydrology.
TUFLOW-SWMM Module 4 - 1D SWMM Pipe Network / 1D SWMM Urban Hydrology:
Executing multiple different event simulations from a single model control file.
XPSWMM to TUFLOW-SWMM - How to convert an XPSWMM model to TUFLOW
SWMM.
SWMM Manuals: The following documents may be useful:
SWMM5 Reference Manual - Volume 1 (Hydrology)
SWMM5 Reference Manual - Volume 2 (Hydraulics)
SWMM5 Reference Manual - Volume 2 (Hydraulics Addendum)
SWMM5 Reference Manual - Volume 3 (Water Quality)
SWMM5 User’s Manual

@710
6.2 Model Setup

@711
6.2.1 SWMM Model

The SWMM portion of a TUFLOW-SWMM model is read from one or more SWMM project files
(inp). These files can be created within the EPA SWMM GUI, the TUFLOW GIS tools described in
Section 6.3 , or other tools (for example, exported from other software that have adopted SWMM
5 as their 1D solver).

Section 6 1D Network Domains - EPA SWMM - 2 / 16 Page 235 / 1094

 The EPA Website provides documentation on SWMM model theory and setup. This manual does
not contain a description of how to build SWMM models or the SWMM file formats since this
information is readily available from the resources provided in Section 6.1.2 . The TUFLOW-
SWMM Tutorials demonstrate how to build TUFLOW-SWMM models using the TUFLOW GIS
tools.

@712
6.2.2 TUFLOW-SWMM Model Simulation

When running a TUFLOW-SWMM model, TUFLOW controls the execution of the simulation.
SWMM input commands are specified within a SWMM Control File (*.tscf), documented in
Appendix I . The SWMM Control File is referenced in the TUFLOW Control File (*.tcf) using the
“SWMM Control File ==” command, documented in Appendix A .

The SWMM Control File can reference one or more SWMM input inp files using the “Read SWMM
==” command. If multiple input inp files are used, TUFLOW merges the files into a single input
inp before simulation. During the merger, if there are SWMM objects that are duplicate in terms of
location and “Name” the item that was defined lower in the SWMM Control File (*.tscf) takes
precedence. This merger approach has been adopted to allow modellers to override existing
objects easily for options assessments (such as, to assess the upgrade of a section of pipe
network). After the input files are merged, the final SWMM model in inp format is placed in the
TUFLOW output folder. The SWMM model runs from the output folder. The SWMM report and
output files are also written to the TUFLOW output folder.

@713
6.2.3 Linking SWMM to TUFLOW 2D and ESTRY

For information relating to the linking of SWMM 1D with TUFLOW 2D, and the linking of SWMM
1D to TUFLOW 1D (ESTRY), see Section 10.4 .

@714
6.2.4 SWMM Simulation Option Settings

The SWMM model settings are primarily dependent on the settings defined in the Project–Options
section of the SWMM inp file. However, some settings are controlled by TUFLOW when running a
TUFLOW-SWMM model, including:

END_DATE/END_TIME: Set based upon the SWMM START_DATE/START_TIME and the

TUFLOW simulation duration.
FLOW_UNITS: the flow units are set to match the TUFLOW simulation, either to CFS for US
Customary units or CMS for metric units.
FLOW_ROUTING: Flow routing is set to DYNWAVE.
ALLOW_PONDING: Allow ponding is set to YES. Ponding can be prevented by setting a high
Junction attribute value for “YSur” (higher than the maximum water elevation) or setting a
Junction “Apond” value to 0.0. Note, it is recommended that only Junctions with TUFLOw
1D/2D HX or SX boundaries should have the Apond attribute set to 0.0, which will create
flooding in the 2D domain when the Junction is surcharged.
END_DATE/END_TIME: These are set based on the TUFLOW end time and the SWMM start
time (simulation duration + start date/time = specified end date/time).
VARIABLE_STEP: This is turned off (0). TUFLOW will control the timestep based on the HPC
(Heavily Parallelised Compute) timestep and the SWMM Iterations command.

Section 6 1D Network Domains - EPA SWMM - 3 / 16 Page 236 / 1094

 @715
6.2.5 Using the TUFLOW BC Database in SWMM

The fixed structure of SWMM restricts it to the simulation of a single event per SWMM inp file.
Manual definition of SWMM boundary condition inputs would become an onerous task during the
execution of a project requiring simulation of multiple events. TUFLOW-SWMM has overcome this
SWMM limitation by enabling the communication of boundary condition timeseries data from the
TUFLOW Boundary Condition Database to SWMM. This feature upgrades SWMM to use
TUFLOW’s powerful and flexible event management options. Any number of event simulations can
now be executed from a single SWMM inp input file. TUFLOW automatically assigns the chosen
boundary condition inputs.

The connection between the TUFLOW Boundary Condition Database and the SWMM model is
established by using the SWMM Control File (*.tscf) command, “Read BC <curve_type> ==”. The
“SourceType” in the SWMM inp file also needs to be set to TIMESERIES for time varying data,
such as rainfall depth vs time or discharge vs time to be passed seamlessly to SWMM from
TUFLOW. The SWMM Timeseries name must also be specified (matching the TUFLOW Boundary
Condition Database Name). TUFLOW writes the event specific information to the SWMM inp file it
creates, prior to its simulation.TUFLOW-SWMM Tutorial 4 is a demonstration of this TUFLOW-
SWMM boundary condition model configuration.

@716
6.3 SWMM GIS Tools

SWMM tools have been added to the TUFLOW QGIS Plugin to provide users with the ability to
build TUFLOW-SWMM models in a GIS environment. The tools assist with building SWMM
models, linking TUFLOW-SWMM models, and viewing SWMM outputs.Three major items within
the TUFLOW QGIS Plugin that are specifically relevant to SWMM include the TUFLOW QGIS
plugin SWMM Processing Tools, 1D Pipe Integrity Tools, and TUFLOW Viewer.

The TUFLOW QGIS Plugin SWMM Processing Tools have been created to support workflow
efficient model building. Tools available within the SWMM Processing Toolbox can be used for
the following:

Conversion of SWMM input files (inp) to and from SWMM GeoPackage file format. These
converters are central to all the SWMM processing tools. They enable the conversion of
SWMM inp text files into a visual GIS GeoPackage format for spatial and tabular editing.
Also, the GeoPackage files can be exported to SWMM inp text file format, for use as
inputs into the TUFLOW-SWMM model. The Geopackage format representation of the
SWMM inp file is discussed in Section 6.3.1
Creation of SWMM Template GeoPackage GIS files. These files include all the data
required by a SWMM model, if building a model from scratch.
Setting of unique SWMM Junction parameters based on Junction usage and location.
Setting unique SWMM conduit losses, dependent on location of the object in the network
and whether the conduit is connected directly to the 2D, another pipe or a stormwater
inlet.
Semi-automatic creation of TUFLOW-SWMM 1D/2D linkages.
Tools to assist in the conversion of XPSWMM models to TUFLOW-SWMM.
Conversion of ESTRY layers to SWMM.

Section 6 1D Network Domains - EPA SWMM - 4 / 16 Page 237 / 1094

 The TUFLOW QGIS plugin 1D Pipe Integrity Tools are a suite of tools that help modelers find
and fix potential errors in 1D networks prior to running TUFLOW. The 1D integrity tool can be
used for ESTRY or SWMM pipe networks.

The TUFLOW Viewer enables GIS viewing of SWMM time-series results. The following are
supported.

Time-series plotting of 1D SWMM results.

Long-profile plotting of 1D SWMM network results.
Dynamic plan view symbology. This feature enables the object symbology to change
based on the result magnitude at the current simulation output time.
The above result display options can be used within animations created by TUFLOW
Viewer.

@717
6.3.1 GeoPackage File Format

The SWMM GeoPackage representation is mostly a simple conversion of the table oriented
SWMM input file (inp).

@718
6.3.1.1 GeoPackage File Table Overview

Some GeoPackage tables are modified versions of the SWMM input file, often combining multiple
inp sections into a single GeoPackage table to streamline editing features. Some of the
GeoPackage tables have spatial components (points, lines, and polygons) and others are tables
of data with no geometry attributes.

Generally, modified tables are a “wide” form of the tables to represent distinct categories of
options without using the same column for multiple input parameters. For example, the
“[XSECTIONS]” table has a variety of inputs depending upon whether the shape is from a list of
shapes, a custom shape (a closed shape with a Height vs Width table), irregular shape (cross-
section-based open channel), or a street cross-section. In the SWMM input file, attributes from
multiple types use the same columns while the GeoPackage representation creates a column for
each input field. There are separate columns for specified shapes and irregular culvert curves.
Depending upon the option selected, many of the fields will not be used.

To make things simpler, the subcatchment and subarea SWMM table columns are combined into
the subcatchment table. The subarea columns use the prefix “subarea_” and are written to a
separate table when exported to the SWMM inp file.

SWMM inp files can be converted to a GeoPackage format using the processing tool SWMM >>
GeoPackage - Create from SWMM inp. GeoPackage format files can be exported to SWMM inp
files using the processing tool SWMM >> GeoPackage - Write to SWMM inp. When a
GeoPackage file is read into QGIS, by default a folder will be created for all of the loaded layers.
Right-clicking on this folder will bring-up a menu item to export the GeoPackage file as a SWMM
inp file.

A full description of the layers that can be included in SWMM GeoPackage files can be found in
Appendix L .

Section 6 1D Network Domains - EPA SWMM - 5 / 16 Page 238 / 1094

 @719
6.3.1.2 GeoPackage Options Table

The SWMM Options Table (Table mirrors the options in the “Options” section of the SWMM inp file
where each entry has a keyword and a value. The table is used for model parameters controlling
the computations, timing parameters, and other project level settings. The options and values for
this table are provided in Table 6.1 .

Section 6 1D Network Domains - EPA SWMM - 6 / 16 Page 239 / 1094

 @720 Table 6.1: SWMM Option Table Keywords and Descriptions

Option Description Values

FLOW_UNITS makes a choice

of flow units. Selecting a US
flow unit means that all other
quantities will be expressed in
US customary units, while
choosing a metric flow unit will [{CFS} | GPM | MGD | CMS
FLOW_UNITS
force all quantities to be | LPS | MLD ]
expressed in SI metric units.
(Exceptions are pollutant
concentration and Manning’s
roughness coefficient (n) which
are always in metric units).

INFILTRATION selects a model [{HORTON} | MODIFIED

for computing infiltration of HORTON | GREEN_AMPT |
INFILTRATION
rainfall into the upper soil zone MODIFIED_GREEN_AMPT
of subcatchments. | CURVE_NUMBER]

FLOW_ROUTING determines
which method is used to route
flows through the drainage
system. STEADY refers to
sequential steady state routing
(i.e. hydrograph translation),
[STEADY | KINWAVE |
FLOW_ROUTING KINWAVE to kinematic wave
{DYNWAVE}]
routing, DYNWAVE to dynamic
wave routing. While you can
store any option in the SWMM
GeoPackage file, TUFLOW-
SWMM requires (and will force)
the dynamic wave solver.

LINK_OFFSETS determines
the convention used to specify
the position of a link offset
above the invert of its
connecting node. DEPTH
LINK_OFFSETS indicates that offsets are [{DEPTH} | ELEVATION]
expressed as the distance
between the node invert and
the link while ELEVATION
indicates that the absolute
elevation of the offset is used.

Section 6 1D Network Domains - EPA SWMM - 7 / 16 Page 240 / 1094

 Option Description Values

FORCE_MAIN_EQUATION
establishes whether the
Hazen-Williams (H-W) or the
Darcy-Weisbach (D-W)
equation will be used to
FORCE_MAIN_EQUATION [{H-W} | D-W]
compute friction losses for
pressurized flow in conduits
that have been assigned a
Circular Force Main cross-
section shape.

IGNORE_RAINFALL is set to
YES if all rainfall data and
runoff calculations should be
ignored. In this case SWMM
IGNORE_RAINFALL [YES | {NO}]
only performs flow and
pollutant routing based on
user-supplied direct and dry
weather inflows.

IGNORE_SNOWMELT is set to
YES if snowmelt calculations
IGNORE_SNOWMELT should be ignored when a [YES | {NO}]
project file contains snow pack
objects.

IGNORE_GROUNDWATER is
set to YES if groundwater
IGNORE_GROUNDWATER calculations should be ignored [YES | {NO}]
when a project file contains
aquifer objects.

IGNORE_RDII is set to YES if

rainfall dependent
inflow/infiltration should be
IGNORE_RDII ignored when RDII unit [YES | {NO}]
hydrographs and RDII inflows
have been supplied to a project
file.

IGNORE_ROUTING is set to
YES if only runoff should be
IGNORE_ROUTING computed even if the project [YES | {NO}]
contains drainage system links
and nodes.

Section 6 1D Network Domains - EPA SWMM - 8 / 16 Page 241 / 1094

 Option Description Values

IGNORE_QUALITY is set to
YES if pollutant washoff,
IGNORE_QUALITY routing, and treatment should [YES | {NO}]
be ignored in a project that has
pollutants defined.

ALLOW_PONDING determines
whether excess water is
allowed to collect atop nodes
and be re-introduced into the
system as conditions permit.
ALLOW_PONDING [YES | {NO}]
The default is NO ponding. In
order for ponding to actually
occur at a particular node, a
non-zero value for its Ponded
Area attribute must be used.

SKIP_STEADY_STATE should
be set to YES if flow routing
computations should be
skipped during steady state
periods of a simulation during
which the last set of computed
flows will be used. A time step
is considered to be in steady
SKIP_STEADY_STATE [YES | {NO}]
state if the percent difference
between total system inflow
and total system outflow is
below the SYS_FLOW_TOL
and the percent difference
between current and previous
lateral inflows are below the
LAT_FLOW_TOL.

SYS_FLOW_TOL is the
maximum percent difference
between total system inflow
SYS_FLOW_TOL and total system outflow which {5}
can occur in order for the
SKIP_STEADY_STATE option
to take effect.

Section 6 1D Network Domains - EPA SWMM - 9 / 16 Page 242 / 1094

 Option Description Values

LAT_FLOW_TOL is the
maximum percent difference
between the current and
previous lateral inflow at all
LAT_FLOW_TOL {5}
nodes in the conveyance
system in order for the
SKIP_STEADY_STATE option
to take effect.

START_DATE is the date when

START_DATE {2024-01-01}
the simulation begins.

START_TIME is the time of day

START_TIME on the starting date when the {0:00:00}
simulation begins.

END_DATE is the date when

the simulation is to end. The
default is the start date.
TUFLOW-SWMM models will
END_DATE {2024-01-01}
change this value to match the
START_DATE and
START_TIME + simulation run
time.

END_TIME is the time of day

on the ending date when the
simulation will end. TUFLOW-
SWMM models will change this
END_TIME {24:00:00}
value to match the
START_DATE and
START_TIME + simulation run
time.

REPORT_START_DATE is the
date when reporting of results
REPORT_START_DATE {2024-01-01}
is to begin. The default is the
simulation start date.

REPORT_START_TIME is the
time of day on the report
REPORT_START_TIME starting date when reporting is {0:00:00}
to begin. The default is the
simulation start time of day.

SWEEP_START is the day of

the year (month/day) when
SWEEP_START {1/1}
street sweeping operations
begin.

Section 6 1D Network Domains - EPA SWMM - 10 / 16 Page 243 / 1094

 Option Description Values

SWEEP_END is the day of the

SWEEP_END year (month/day) when street {12/31}
sweeping operations end.

DRY_DAYS is the number of

DRY_DAYS days with no rainfall prior to the {0}
start of the simulation.

REPORT_STEP is the time

REPORT_STEP interval for reporting of {0:15:00}
computed results.

WET_STEP is the time step

length used to compute runoff
from subcatchments during
WET_STEP {0:05:00}
periods of rainfall or when
ponded water still remains on
the surface.

DRY_STEP is the time step

length used for runoff
computations (consisting
DRY_STEP {1:00:00}
essentially of pollutant buildup)
during periods when there is no
rainfall and no ponded water.

ROUTING_STEP is the time

step length in seconds used for
routing flows and water quality
constituents through the
conveyance system. This can
be increased if dynamic wave
routing is not used. Fractional
ROUTING_STEP {20}
values (e.g., 2.5) are
permissible as are values
entered in
hours:minutes:seconds format.
TUFLOW-SWMM models will
match the (potentially variable)
TUFLOW timestep.

Section 6 1D Network Domains - EPA SWMM - 11 / 16 Page 244 / 1094

 Option Description Values

LENGTHENING_STEP is a
time step, in seconds, used to
lengthen conduits under
dynamic wave routing, so that
they meet the Courant stability
criterion under full-flow
conditions (i.e., the travel time
LENGTHENING_STEP of a wave will not be smaller {0}
than the specified conduit
lengthening time step). As this
value is decreased, fewer
conduits will require
lengthening. A value of 0 (the
default) means that no conduits
will be lengthened.

VARIABLE_STEP is a safety
factor applied to a variable time
step computed for each time
period under dynamic wave
flow routing. The variable time
step is computed so as to
satisfy the Courant stability
VARIABLE_STEP {0}
criterion for each conduit and
yet not exceed the
ROUTING_STEP value. If the
safety factor is 0 (the default),
then no variable time step is
used. This value is not used in
TUFLOW-SWMM simulations.

MINIMUM_STEP is the
smallest time step allowed
MINIMUM_STEP when variable time steps are {0.5}
used for dynamic wave flow
routing.

Section 6 1D Network Domains - EPA SWMM - 12 / 16 Page 245 / 1094

 Option Description Values

INERTIAL_DAMPING indicates
how the inertial terms in the
Saint Venant momentum
equation will be handled under
dynamic wave flow routing.
Choosing NONE maintains
INTERTIAL_DAMPING these terms at their full value [None | {Partial} | Full]
under all conditions. Selecting
PARTIAL (the default) will
reduce the terms as flow
comes closer to being critical
(and ignores them when flow is
supercritical).

NORMAL_FLOW_LIMITED
specifies which condition is
checked to determine if flow in
a conduit is supercritical and
should thus be limited to the
normal flow. Use SLOPE to
NORMAL_FLOW_LIMITED check if the water surface [Slope | Froude | {Both}]
slope is greater than the
conduit slope, FROUDE to
check if the Froude number is
greater than 1.0, BOTH to
check both conditions or NONE
if no checks are made.

SURCHARGE_METHOD
selects which method will be
used to handle surcharge
conditions. The EXTRAN
option uses a variation of the
Surcharge Algorithm from
previous versions of SWMM to
update nodal heads when all
SURCHARGE_METHOD connecting links become full. [{EXTRAN} | SLOT]
The SLOT option uses a
Preissmann Slot to add a small
amount of virtual top surface
width to full flowing pipes so
that SWMM’s normal
procedure for updating nodal
heads can continue to be used.
The default is EXTRAN.

Section 6 1D Network Domains - EPA SWMM - 13 / 16 Page 246 / 1094

 Option Description Values

MIN_SURFAREA is a minimum
surface area used at nodes
when computing changes in
water depth under dynamic
MIN_SURFAREA wave routing. If 0 is entered, {0}
then the default value of
12.566 ft2 (1.167 m2) (i.e., the
area of a 4-ft diameter
manhole) is used.

MIN_SLOPE is the minimum

value allowed for a conduit’s
slope (%). If zero (the default)
then no minimum is imposed
MIN_SLOPE {0}
(although SWMM uses a lower
limit on elevation drop of 0.001
ft (0.00035 m) when computing
a conduit slope).

MAX_TRIALS is the maximum

number of trials allowed during
a time step to reach
MAX_TRIALS {8}
convergence when updating
hydraulic heads at the
conveyance system’s nodes.

HEAD_TOLERANCE is the
difference in computed head at
each node between successive
trials below which the flow
HEAD_TOLERANCE solution for the current time {0.005}
step is assumed to have
converged. The default
tolerance is 0.005 ft (0.0015
m).

THREADS is the number of

parallel computing threads to
THREADS use for dynamic wave flow {1}
routing on machines equipped
with multi-core processors.

@721
6.4 SWMM Outputs

Model outputs are written by both SWMM and TUFLOW, which can be used to visualize model
results. SWMM writes a report file (rpt) and an output file (out) in the TUFLOW results folder with
the simulation prefix followed by “_swmm.” The report file can be viewed with a text editor. The

Section 6 1D Network Domains - EPA SWMM - 14 / 16 Page 247 / 1094

 output file can be viewed in EPA SWMM or 3rd party tools that support this format, such as
PySWMM.

TUFLOW-SWMM models also output a GeoPackage time-series output file. The file is written with
the other result files in the results folder, and ends with “_ts.gpkg.” This file can be read into the
QGIS TUFLOW Viewer using the Load Results - Time series option from the File menu of the
QGIS TUFLOW Viewer. When this file is loaded, point and line layers will be loaded, representing
the node and channel results. The layer symbology can be modified to dynamically represent the
model result magnitude for the current QGIS time. Profiles can be also be generated for the 1D
network. Animations can be created from these results (in combination with 2D results if desired).
These layers can also be used to select channels or nodes to display time series results in the
TUFLOW Viewer plot windows, and can be combined with ESTRY or PO outputs. Documentation
for the QGIS TUFLOW Plugin and TUFLOW Viewer are available in the TUFLOW Wiki.

The GeoPackage time-series file contains all of the SWMM output for nodes and links (polylines).
For nodes this includes, “Depth”, “Water Level”, and more. For Conduits this includes, “Flow”,
“Channel Depth”, “Velocity”, “Channel Capacity” and more. Descriptions of these datasets are in
the SWMM documentation. In addition, TUFLOW writes two datasets, “Flow from 2D” and
“Cumulative Volume from 2D”, for nodes that describe flow between the 1D and 2D domains.
“Flow from 2D” represents the inflow from the 2D model to the node where negative values
represent flows from the 1D domain to the 2D. “Cumulative Volume from 2D” represents the total
volume that goes into (positive) or out of the 1D domain from the 2D.

@722
6.5 SWMM Inclusion in TUFLOW

@723
6.5.1 SWMM Library Version

TUFLOW runs SWMM as a library, passing data between SWMM 1D and the TUFLOW 2D
domains. The SWMM version used for the hydraulic calculations was created by Open Water
Analytics (McDonnell et al., 2021 ), which is a modified version of the SWMM code.

@724
6.5.2 Embedded SWMM Code in TUFLOW

TUFLOW has modified SWMM code (not from Open Water Analytics) primarily to enable
calculation of pit (inlet) discharges and to include additional TUFLOW functionality for linking
SWMM 1D to TUFLOW 2D. Details are provided below.

Changes were made to how inlets are handled to better correspond to how “rating curve”
based pits are treated in ESTRY and provide better handling when the water level is above
the inlet invert. Pit rating curves use a depth vs discharge relationship to determine the
volume of flow that passes from the 2D domain into the 1D domain. If the pipe water level is
above the inlet invert, but the 2D water level is higher the discharge will be based on the 2D
water level minus the 1D water level in the pipe. If the 1D pipe water level is higher, a
surcharging discharge is computed using the same curve based on the 1D pipe water level
minus the 2D water level. This matches the ESTRY implementation and ensures a smooth
transition between inflow and surcharging.
The discharge for On-Grade inlets was modified to use a velocity passed from the 2D domain
rather than calculating a velocity based on the SWMM 1D street cross-section and slope at

Section 6 1D Network Domains - EPA SWMM - 15 / 16 Page 248 / 1094

 the inlet.
The methodology for assigning On-Grade or On-Sag handling of pits (inlets) was modified in
the embedded code. In SWMM, a pit (inlet) placement defined as “AUTOMATIC” determines
whether a pit should be On-Sag or On-Grade based upon the topography of the SWMM 1D
street layout. In a combined TUFLOW-SWMM model 1D streets may not be fully described
because only the cross-section information at inlets is required because 2D flows are
modeled in TUFLOW. When running SWMM inside of TUFLOW, whether to treat an automatic
placement as On-Sag or On-Grade is determined dynamically based on the inflows to the
connected 2D cells. The 2D model provides the approach discharge (along the street) and
total discharge for the connected cells. If the approach discharge is over 85% of the total
discharge, the pit is modeled as an On-Grade inlet. Otherwise, it is modeled as On-Sag. Note:
This approach is currently being tested and is subject to change. For production models it is
recommended that users assign inlets as On-Grade or On-Sag.

References

@726
@725
McDonnell, B., Wu, J. X., Ratliff, K., Mullapudi, A., & Tryby, M. (2021). Open Water Analytics
Stormwater Management Model (Version 5.1.13). Zenodo.
https://doi.org/10.5281/zenodo.5484299

Section 6 1D Network Domains - EPA SWMM - 16 / 16 Page 249 / 1094

 @733

@734
Section 7 2D Domains

@735
7.1 Introduction

This chapter of the Manual discusses features specifically related to 2D model domains. 1D
domain features are discussed separately in Chapter 5 and 1D/2D linking is discussed in Chapter
10 .

@736
7.2 Solvers

TUFLOW solves the depth averaged 2D Shallow Water Equations (SWE). The SWE are the
equations of fluid motion used for modelling long waves such as floods, urban stormwater
inundation, dam failure hydraulics, ocean tides and storm surges. They are derived using the
assumption of vertically uniform horizontal velocity and negligible vertical acceleration (i.e. a
hydrostatic pressure distribution). These assumptions are valid where the wave length is much
greater than the depth of water. In the case of the ocean tide, the wavelength is long, and even at
the deepest parts of the ocean the SWE are applicable.

The 2D SWE in the horizontal plane are described by the following partial differential equations of
mass continuity and momentum conservation in the X and Y directions for an in-plan Cartesian
coordinate frame of reference. The equations are:

2D Continuity:

@737 ∂h ∂(hu) ∂(hv)

+ + = S (7.1)
∂t ∂x ∂y

X Momentum:

@739 ∂ (hνt
∂u
) ∂ (hνt
∂u
) 2 2
∂(hu) ∂(huu) ∂(hvu) ∂x ∂y ∂(z + h) n √u
+ + − − + gh + gh
4
∂t ∂x ∂y ∂x ∂y ∂x
h3

Y Momentum:

@741 ∂ (hνt
∂v
) ∂ (hνt
∂v
) 2 2
∂(hv) ∂(huv) ∂(hvv) ∂x ∂y ∂(z + h) n √u +
+ + − − + gh + gh
4
∂t ∂x ∂y ∂x ∂y ∂y
h3

Where:

h = Depth of water
u and v = Depth averaged velocity components in X and Y directions
t = Time
x and y = Distance in X and Y directions

Section 7 2D Domains - 1 / 116 Page 250 / 1094

 z = Bed elevation
n = Manning’s bed friction coefficient
cf = Coriolis force coefficient (available for TUFLOW Classic only)
νt = Turbulent kinematic viscosity
Pa = Atmospheric pressure
ρ = Density of water
S = Areal volume source (volume per unit time per unit area), used for rain and infiltration
Su and Sv = Areal momentum source terms (force per unit area per unit fluid density), used
for local energy losses

The terms of the SWE can be attributed to different physical phenomena. These are:

Propagation of the wave due to gravitational forces.

Transport of momentum by advection.
Horizontal diffusion of momentum or sub-grid scale turbulence (see Section 7.2.4 ).
External forces such as bed friction, rotation of the earth, wind, wave radiation stresses, and
barometric pressure.

For further discussion relating to the SWE, please see Section 3.4.1 .

TUFLOW Classic and TUFLOW HPC use different solution schemes to solve the SWE. Both
approaches are discussed in the following Sections.

@758
7.2.1 TUFLOW HPC 2D Solver

TUFLOW HPC is an explicit solver using a finite volume method. It computes the volume flow
across cell boundaries. Volume cannot leave one cell without being placed in its neighbour. As a
result, 2D volume is conserved and 2D mass error is 0%. The transfer of momentum across cell
boundaries is computed in the same way and once external forces are considered (bed slope,
bottom friction, and wet perimeters of non-uniform depth) momentum is conserved.

The explicit finite volume scheme applies the conservation of mass over the cell for calculating the
rate of change of cell depth. In Figure 7.1 , the cell centre (for the cell in question) is given the
notation cc, while the surrounding neighbours are given the notation n1..n4. The u velocity at the
left and right faces are notated u1 and u2, and the v velocities at the bottom and top faces are
notated v3 and v4. The cell width and height are Δx and Δy respectively.

TUFLOW HPC uses an automatic adaptive timestep to achieve unconditional stability, as

mentioned in Section 3.5.4 . It solves the 2D SWE on a uniform Cartesian grid. Water depth/level
is calculated at the cell centres, and velocity components at the cell mid-sides or faces in the
same manner as TUFLOW Classic.

@759

Section 7 2D Domains - 2 / 116 Page 251 / 1094

 Figure 7.1: TUFLOW HPC 2D SWE Finite Volume Scheme Approach
The time rate of change for the cell averaged depth is shown in Equation (7.4) .

@760 A∂h
= Φ1 − Φ2 + Φ3 − Φ4 + S Q (7.4)
∂t

Where:

A = cell area
h = depth
t = time
Φ1 to Φ4 = the four face fluxes
SQ = sources (rain and infiltration)

The volume fluxes across the four cell sides and the net volume from source boundaries
determine the rate of volume change and the change in depth. Source boundaries include SA, ST
and RF boundaries, soil infiltration, evaporation, and any flow linkages to 1D elements via SX
links. By computing the face fluxes for all model faces, and referencing these when computing the
depth derivative for each cell, volume conservation is guaranteed to numerical precision. At
“Head” boundaries, the above equation does not apply. Rather, the defined head (level) is directly
used to calculate the water volume and associated depth in the cell.

The calculation of the cell side volume fluxes is available in either 1st or 2nd order spatially. For
the 1st order scheme, this uses depth of the upstream cell (often referred to as upwinding),
bounded to be greater than or equal to 0, and less than or equal to the surface elevation of the
upstream cell less the bed elevation at the cell side mid-point. For the 2nd order scheme the depth
at the face is computed as the average of the two cell averaged depths, however, this method in
its simplest form is not total variation diminishing (TVD) and is known to be unstable. A hybrid
method is implemented in which the depth at the cell face transitions from interpolated depth to
the upstream depth (1st order upwinding) when the solution shows short scale reversal or
upstream controlled supercritical flow.

The solution of the cell side fluxes includes the inertia and sub-grid scale turbulence (eddy or
kinematic turbulent viscosity) term. Turbulence is detailed further in Section 7.2.4 . The cell side
fluxes may also be factored down by flow constriction factors where sub-grid-scale obstructions

Section 7 2D Domains - 3 / 116 Page 252 / 1094

 exist.

Due to the explicit scheme, the calculation of flux for one cell face may be performed
independently of the other faces, and likewise the summation of flux for each cell volume may be
performed independently of the other cell volumes. Applying the same algorithm to millions of data
elements is well suited to modern multi-core CPUs, and particularly suited to GPU hardware
acceleration.

The 1st order approach can experience numerical diffusion, like all 1st order schemes, and does
not resolve strongly two-dimensional hydraulics (e.g. flow expansion downstream of a constriction)
as well as a 2nd order solution. The 2nd order solution demonstrates no discernible numerical
diffusion, and resolves complex 2D hydraulics, including hydraulic jumps as demonstrated using
the UK EA Benchmark Flume Test 6A Collecutt & Syme (2017 ). When running HPC solver the
2nd order spatial scheme is the default and recommended approach.

For further details on the scheme, refer to Collecutt & Syme (2017 ). Note that at the time this
paper was written, the scheme utilised cell centre definitions for velocity, which was prone to a
zero-energy ‘checker-board’ mode in the solution. Subsequent to the paper, cell mid-side points
were adopted for the definition of u and v velocities which has eliminated the checker-board mode
with only very minor changes to the results.

@768
7.2.2 TUFLOW Classic 2D Solver

The scheme is unlike the TUFLOW HPC solution in that it solves the same shallow water
equations implicitly using matrices, allowing much larger timesteps (hence why it is important to
monitor mass error in implicit schemes such as TUFLOW Classic to check that the solution is
converging).

An Alternating Direction Semi-Implicit (ADI) finite difference method is used for TUFLOW Classic’s
computational procedure. It was originally based on the work of Stelling (1984 ). The method
involves two stages per timestep, each having two steps, giving four steps overall. Two of the
steps sweeps through the model domain solving tri-diagonal matrices, hence the “semi-implicit”.
Due to the implicit solution, TUFLOW Classic is not suited to being parallelised for multi-core
CPUs or for GPU acceleration.

Step 1 solves the momentum equation in the Y-direction for the Y-velocities. The equation is
solved using a predictor/corrector method, which involves two sweeps. For the first sweep, the
calculation proceeds column by column in the Y-direction. If the signs of all velocities in the X-
direction are the same the second sweep is not necessary, otherwise the calculation is repeated
sweeping in the opposite direction.

The second step of Stage 1 solves for the water levels and X-direction velocities by solving the
equations of mass continuity and of momentum in the X-direction. Tri-diagonal equations are
generated and solved across the 2D domain by substituting the momentum equation into the mass
equation and eliminating the X-velocity. The water levels are calculated and back substituted into
the momentum equation to calculate the X-velocities. This process is repeated for a recommended
two iterations. Testing on a number of models showed there to be little benefit in using more than
two iterations unless there are rapid changes in the hydraulic conditions per timestep as may
occur with modelling inundation from a dam break.

Section 7 2D Domains - 4 / 116 Page 253 / 1094

 Stage 2 proceeds in a similar manner to Stage 1 with the first step using the X-direction
momentum equation and the second step using the mass equation and the Y-direction momentum
equation.

The solution as formulated by Stelling has been enhanced and improved to provide much more
robust wetting and drying of elements, upstream controlled flow regimes (e.g. supercritical flow
and upstream controlled weir flow), modifications to cells to model structure obverts (e.g. bridge
decks) and additional energy losses due to fine-scale features such as bridge piers.

TUFLOW Classic solves the 2D SWE on the same uniform Cartesian grid as used by TUFLOW
HPC. Water depth/level is calculated at the cell centres, and velocity components at the cell mid-
sides or faces.

@769
7.2.3 Cell Schematisation

TUFLOW 2D models discretise the real world as a grid of connected square cells. A fixed grid 2D
domain is defined by a bounding rectangle in the same manner a computer screen or digital photo
is made up of a grid of pixels.

The physical properties (i.e. ground elevations, surface roughness, etc) of a 2D cell are defined as
a minimum at the cell’s centre, mid-sides and corners as described in Section 7.3.1 . High
resolution topographic detail for the cell’s storage and conveyance across the cell sides (faces)
can be incorporated by using the Sub-Grid Sampling (SGS) feature available in TUFLOW HPC, as
documented in Section 7.4.3 . SGS has substantial accuracy benefits. It enables the use of much
larger cell sizes without loss of hydraulic conveyance accuracy. It also results in less output
sensitivity to the grid orientation.

@770
7.2.3.1 Computational Points

To fully understand how TUFLOW functions, understanding of the computational role of the 2D cell
and its four sides (also referred to as faces) is important. In the following sections, these model
components are referred to as the ZC, ZU, ZV and ZH points, as shown in Figure 7.2 . The
description of these points are:

ZC – the cell centre with ZC being the elevation used computationally within the cell.
ZU – middle of the cell side of the Y-axis face with ZU being the elevation used
computationally along the cell side.
ZV – middle of the cell side of the X-axis face with ZV being the elevation used
computationally along the cell side.
ZH – corner of the cell. The ZH point plays no role in the computational hydraulics but is used
for some output formats that require output at the cell corners.

@771

Section 7 2D Domains - 5 / 116 Page 254 / 1094

 Figure 7.2: Location of Zpts and Computation Points

@772
7.2.3.1.1 ZC Point

The cell centre or ZC point:

Defines the location where water levels are computed based on mass balance equation.
Simply put, the net volume of water entering (or leaving) the cell across the four cell sides (or
faces) must equal the change in volume of the cell over a timestep.
The volume of a cell can either be simply based on the depth of water multiplied by the cell
area or, if Sub-Grid Sampling (SGS) (Section 7.4.3 ) has been applied, a curve of volume
versus depth.
The ZC value is typically the elevation at the cell centre or, if using SGS, elevations are
sampled across the cell, as outlined in Section 7.4.3 . The ZC value plus the Cell Wet/Dry
Depth is the water surface elevation that controls when a cell becomes wet or dry (note that
cell sides can also wet and dry).
The ZC value also determines the bed slope when testing for the upstream controlled flow
regime in TUFLOW Classic (see Section 7.5.2 ) and TUFLOW HPC (Section 7.4.4 ).

@773
7.2.3.1.2 ZU and ZV Points

The cell sides or faces:

Control how water is conveyed from one cell to another using the momentum equation, or
when upstream controlled flow occurs, the relevant flow equation (eg. weir equation).
Are deactivated if the whole of the cell has dried based on the ZC elevation as described
above.
Can wet and dry when the whole cell is wet (see Cell Wet/Dry Depth ). This allows for the
modelling of “thin” obstructions such as fences and thin embankments relative to the cell size
(e.g. a concrete levee).

Section 7 2D Domains - 6 / 116 Page 255 / 1094

 Surface roughness information (e.g. Manning’s n) is inspected at the ZU and ZV points. See
Bed Resistance Cell Sides

@774
7.2.3.1.3 ZH Point

The cell corners:

Play no role in the computational hydraulic calculations.

Are used by the more common map output formats to map results due to mesh based outputs
requiring elevations and results at the element (cell) vertices.

@775
7.2.4 Turbulence

Turbulence within rivers plays a significant role in determining the mean flow velocity field and is
integral to the overall energy loss mechanism. During a significant flood event, the majority of the
flow is carried within, or near to, the river or open channel system (the primary flow path), and the
water levels on the surrounding floodplains are principally determined by the energy losses along
this flow path. Manning’s equation is accurate for straight or slowly varying channels but does not
calculate energy losses due to sudden changes in flow direction or velocity, and it does not
capture super-elevation at bends. To automatically and accurately capture these additional energy
losses, a scheme must be physics based with a turbulence closure model. The turbulence closure
model must be thoroughly bench-marked against appropriate test cases at a range of resolution
scales. It is important that the turbulence closure model is cell size and timestep independent
(i.e. the turbulence closure model parameters do not need to be adjusted if cell size or timestep
changes). Collecutt et al. (2020 ) provides benchmarking of the TUFLOW turbulence schemes.

There are three approaches available to model losses associated with turbulence when using
TUFLOW HPC, these are discussed in Section 7.4.2 . The default scheme for TUFLOW HPC is
the Wu approach (Section 7.4.2.4 ). There are two approaches available to model turbulence
when using TUFLOW Classic, these are discussed in Section 7.5.1 . The default scheme for
TUFLOW Classic is a hybrid approach that includes elements of both the Constant and
Smagorinsky approaches (Section 7.5.1.2 ).

@776
7.2.4.1 Dry Wall Treatment

All of TUFLOW’s viscosity approaches feature an enhanced treatment of the viscosity term at dry
boundaries. The enhanced boundary treatment corrects for unrealistic flow separation that would
otherwise occur at the wet/dry interface. Figure 7.3 presents a example of a benchmark model
test with and without the enhanced boundary treatment. The top image is the result without the
enhanced boundary treatment. Non-physical flow separation is observed along the oblique wet/dry
boundary.The enhanced approach is shown in the bottom image. It does not suffer from the flow
separation, and the velocity increases gradually from left to right as the water depth gradually
shallows (the model has a horizontal bed). The correct water surface slope is produced when
compared with theory.

All of the viscosity approaches are cell-centred. This guarantees symmetry is achieved in
hydraulic results when using a symmetrical model.

The top image in Figure 7.3 shows flow separation along a dry oblique boundary without
enhanced treatment of viscosity term. The bottom image shows a correct velocity distribution
using enhanced treatment of viscosity term at dry boundaries.

Section 7 2D Domains - 7 / 116 Page 256 / 1094

 @777

Figure 7.3: Effect of Enhanced Dry Boundary Viscosity Term Treatment

@778
7.3 Common Functionality

The following sections are the same (or mostly so) between TUFLOW HPC and TUFLOW Classic.

@779
7.3.1 Defining the Domain

Each fixed grid 2D domain is treated as a rectangle at any orientation. The orientation and
dimensions of each 2D domain are defined using .tgc file commands. For the orientation it is
recommended that the X-axis falls between 90° and –90° of East due to some post-processing
software only operating within this range.

Several options are available for setting the 2D domains grid location and orientation. The options
are:

Using a four-sided polygon in a GIS layer to define the 2D grid orientation and dimensions
(see Read GIS Location ).
Using a line (two vertices only) in a 2d_loc GIS layer (attributes shown in Table 7.1 ) to
define the origin (first point of line) and orientation (based on the second point of the line) of
the X-axis (see Read GIS Location ), and Grid Size (N,M) or Grid Size (X,Y) to set the 2D
grid X and Y dimensions.
Using Origin , Orientation or Orientation Angle , and Grid Size (N,M) or Grid Size (X,Y) .
No GIS layers are required for this option. This option is used in Tutorial 1 of the TUFLOW
Wiki Tutorials.
Using a DEM to set the size and location of a 2D domain (see Read Grid Location ). This
option is useful where the model extent is the same as the DEM.

It is recommended during the initial model build process, to view the _dom_check file to ensure
that the model domain is set up as intended.

Note, if using the TUFLOW HPC Quadtree functionality, the 2D domain is set up in the Quadtree
Control File (.qcf), see Section 7.4.1.2 .

Section 7 2D Domains - 8 / 116 Page 257 / 1094

 @780 Table 7.1: Location (2d_loc) Attribute Descriptions

Default GIS Attribute

No Description Type
Name

Optional field for entering comments. Not

1 Comment Char(250)
used.

After establishing the domain’s origin, orientation and extent, the .tgc command Cell Size is used
to define the domain’s fixed grid resolution. For example, the below command in the .tgc sets the
cell size to 10m (or 10ft is using Units == US Customary:

Cell Size == 10

Note, it is not necessary to specify domain dimensions that are an exact multiple of the domain’s
Cell Size (e.g. when using the Grid Size (X,Y) command).

Within this computational domain, 2D cells can be set to be active or inactive, as described in
Section 7.3.2 . The redundant (inactive) areas around the edges of the domain’s bounding
rectangle are automatically removed from the computation. However, when allocating memory for
processing of the arrays this is still accounted for. To determine the redundant area, search the
TUFLOW log file (.tlf) for “redundant”, as shown in Figure 7.4 . If the redundant value is large,
revising the model domain dimensions will reduce the memory usage during startup.

@781

Figure 7.4: Redundant Perimeter Sections Reported in the TLF

@782
7.3.2 Active / Inactive Cells

Each 2D cell is assigned a code to indicate its role. The available code types are listed in Table
7.2 . The default value is one (1) for active (i.e. the cell can be wet or dry during a simulation).

Commands used to modify the cell codes are:

Set Code in the .tgc file. This option sets the cell codes for the entire domain.
Read GIS Code in the .tgc file. This option sets the cell codes based on the value in 2d_code
input polygons, see Table 7.3 .
Read Grid Code in the .tgc file. This option sets the cell codes based on the values of an
input raster grid.
Read GIS Code BC in the .tgc file. This option sets the cell codes from the 2d_bc input
polygon. The Type attribute must be set to “CD” and the code value is taken from the 2d_bc f
attribute, see Table 8.6 .

Note when using the Read GIS Code command, code values are extracted from objects in
a 2d_code layer (see Table 7.3 ). When using the Read GIS Code BC , code values are
extracted from objects in a 2d_bc layer (see Table 8.6 ). Confusing the two GIS layer types
and commands will result in WARNING 2320 message being issued.

Section 7 2D Domains - 9 / 116 Page 258 / 1094

 A typical approach is to set all the cells to be inactive using Set Code == 0 and then read a
GIS layer defining the active cells with Read GIS Code == <layer>. The GIS layer regions
would have the attribute set to 1 for active. For example:

Set Code == 0 ! Set all cells to inactive (i.e. Code 0)

Read GIS Code == ..\model\gis\2d_code_M01_002.shp ! Reads in a polygon
that sets cells to active (i.e. Code 1)

Boundary Cells are automatically set to 2 along external boundaries and links (e.g. HX, HS, HT,
QT boundaries). This code value of 2 (see Table 7.2 ), is output in the TUFLOW grid check file
and a value of 2 should not be used in input commands. The _grd_check file can be used to view
the active cells (and their code values e.g. 1, 2 or -1) within the domain.

For TUFLOW Classic models containing multiple 2D domains (see Section 10.7.2 ), a useful
option for setting the cell codes is the INVERT flag (see Read GIS Code Invert or Read GIS
Code BC Invert ), which allows the same code layer/polygons to be used for activate and
deactivate regions in multiple 2D domains using a single GIS input.

TUFLOW automatically strips any redundant rows and columns around the active area of the
model to reduce simulation times. This is described in Section 7.3.1 .

Section 7 2D Domains - 10 / 116 Page 259 / 1094

 @783 Table 7.2: Cell Codes

Type Code Description

Inactive cells are cells that are totally removed from the computation.
Maximising the area of inactive cells reduces computation time and
output file sizes.

For a fixed grid 2D domain, inactive cells still consume memory during
Inactive
0 a simulation, as these domains are stored on a row column rectangular
Cells
grid.

For a quadtree grid, inactive cells will consume temporary memory

(CPU RAM) during model startup, but do not consume memory (CPU or
GPU) during the simulation.

Active
1 Active cells are cells that can wet and dry during a simulation.
Cells

Boundary cells indicate cells that are an external boundary (including

some types of 1D/2D dynamic links). There should be an active cell on
one side and an inactive or null cell on the other at an external
boundary. If an external boundary is digitised inside an active area
(i.e. not along the active area boundary), water can flow in both
Boundary directions either side of the boundary line (only in rare situations would
2
Cells the modeller require this).

Note: It is not necessary to manually specify boundary cells. Boundary

lines are digitised in GIS layer(s) and TUFLOW automatically assigns
the boundary code to the cells (see Section 8.5.1 and Read GIS BC
).

Inactive cells used to deactivate cells within the active domain. Null
cells may be preferred to inactive cells as they are not excluded from
the output mesh structure (eg. not excluded from the XMDF mesh). For
two simulations to be compared in some post-processers (eg. SMS),
they must have exactly the same mesh. For example, if an area in a
Null Cells -1 model is removed (e.g. filling part of a floodplain), use null cells or raise
the ground elevations in preference to using inactive cells so that the
two simulations can be compared.

Setting null cells is not supported when using the TUFLOW HPC
Quadtree (see Section 7.4.1 ) functionality.

@784 Table 7.3: 2D Code (2d_code) Attribute Descriptions

Default GIS
No Description Type
Attribute Name

The code value (see Table 7.2 ) to be assigned to

1 Code Integer
cells falling on or within the object.

Section 7 2D Domains - 11 / 116 Page 260 / 1094

 @785
7.3.3 Data Layering

TUFLOW models are set up using data layering. This is an important, and very useful concept.

Commands are applied in sequential order; therefore, it is possible to override previous

information with new data to modify the model in selected areas. For topography modifications,
this is extremely useful where a base dataset exists, over which areas need to be modified to
represent other scenarios such as a proposed development. This eliminates or minimises data
duplication. This concept of layering datasets may also be applied to other GIS , including (but not
limited to) 2d_mat, 2d_code and 2d_soil layers. For example, setting all cell codes inactive, then
reading in a GIS polygon covering the active cells (as discussed in Section 7.3.2 ).

Figure 7.5 shows a visual representation of how TUFLOW interprets the following set of .tgc
commands:

Read Grid Zpts == grid\DEM_5m.tif

Read Grid Zpts == grid\Bathy_1m.tif
Read GIS Z Shape == gis\2d_zsh_building.shp
The command lower in the TGC will take precedence over a command above where data overlaps
and the command has the same functional purpose (eg. topography definition). The DEM_5m
layer is read in first. The elevations are then replaced by the overlapping Bathy_1m layer. A 2D Z
Shape (2d_zsh_buildings) is then read in which raises all elevations inside the polygon by 5m.
The result is shown in the DEM_Z. The DEM_Z is a check file representing the elevation data that
TUFLOW has used for the hydraulic calculations. For more information on check files see Section
14.7 .

@786

Figure 7.5: Visual Representation of Data Layering in TUFLOW

Data layering is discussed in further detail for elevation updates in Section 7.3.5 .

@787
7.3.4 Sampling of Data Sets

To setup the boundary of the 2D grid and assign data values to the cells from DEMs, TINs, land-
use polygons, soil polygons and so forth, these data layers need to sampled, interrogated or
interpolated. There are two approaches to sampling datasets in TUFLOW:

Traditional approach (Section 7.3.4.1 )

Sub-Grid Sampling (SGS) approach - recommended (Section 7.4.3 )

The traditional approach by 2D solvers is to sample a single value at the 2D cell centre (ZC).
TUFLOW also supports sampling values, for some data types, at the centre of each cell side (ZV
and ZU) and the corner of the cell (ZH). The cell side sampling for example, enables a cell side to

Section 7 2D Domains - 12 / 116 Page 261 / 1094

 be set to the height of a levee that is narrower in width than the 2D cell. Subsequently controlling
when water can move from adjacent cells depending on the water level relative to the levee crest
elevation. The traditional sampling approach is explained in Section 7.3.4.1 .

As of the 2020-01 TUFLOW release, TUFLOW HPC supports the sampling of elevations at sub-
grid locations, referred to as Sub-Grid Sampling (SGS). The TUFLOW Classic solver does not
support SGS due to the nature of the implicit solution and preferred use of a fixed timestep. The
many benefits of using SGS are detailed in Section 3.3.3 , implementing the SGS approach is
described in Section 7.4.3 .

@788
7.3.4.1 Traditional Sampling Approach

Topographically, the cell is treated as having a flat horizontal bed at a height set to the cell centre
(ZC) elevation, and the cell faces as having flat, rectangular shaped sides at a height set to the
cell mid-side (ZU and ZV) sampled elevations as illustrated in Figure 7.6 . Using the traditional
sampling approach, the topography of a cell is treated as follows:

The cell volume is represented as a square bucket with a flat horizontal bed, and simply
calculated as the cell centre depth times the cell area.
The flow area across a cell face used for the momentum and mass balance equations is
simply represented as a rectangular section (i.e. cell side centre depth times the cell width).
The bed resistance term in the momentum equation (e.g. Manning’s equation) uses the
Resistance Radius approach (i.e. the cell face radius value as used in Manning’s equation is
set to the depth and the cell width or cell size is used for the wetted perimeter).

@789

Figure 7.6: 2D Cell Topography - Traditional Approach

@790
7.3.5 Elevations

2D domain elevations are defined in the .tgc file. As mentioned in Section 7.3.3 , a powerful
feature of TUFLOW is its capacity to build the 2D elevations from any number of GIS layers and/or
TINs. The typical approach adopted is as follows:

1. All elevations in the model start with an un-initialised value of 99999. TUFLOW will output an
error if any elevations of 99999 (or higher) occur after the processing of the elevations. This is
to indicate that elevations in active cells have not been initialised or set.

Section 7 2D Domains - 13 / 116 Page 262 / 1094

 2. A default elevation is specified first in the .tgc file using Set Zpt . An inundation free elevation
is usually specified. If your elevation data sets are intended to cover your entire active area
this step can be omitted so as to trigger the error described above in case elevation data are
unintentionally missing (e.g. unintended null areas in a DEM or accidental omission of a
layer).
3. The elevations read directly from a DEM using Read Grid Zpts , or read from TIN in the
SMS, 12D or LandXML TIN formats (see Read TIN Zpts ).
4. If there are areas where data is either missing or erroneous, these can easily be corrected via
interpolation using Read GIS Z Shape regions or polygons. This is achieved by digitising a
polygon around the missing or erroneous data. TUFLOW interpolates elevations across the
region based on the existing Zpts around the perimeter of the polygon. An example is shown
in Section 7.3.5.2 . Missing or erroneous data often occurs with aerial surveys where the
sampling is in areas of thick vegetation, water or where post processing has poorly filtered the
removal of elevated objects (e.g. buildings).
5. Sometimes there is a need to remove cut and fill works from the topography. For example,
model calibration often requires the removal of infrastructure, such as levees, road
embankments and developments that may not have existed at the time of the historic event to
back date the topography within the model. This is easily done using Read GIS Z Shape by
simply digitising polygons around the various features.
6. The base elevations set up in the previous step(s) can be modified to represent hydraulic
controls, proposed works, failure of a flood defence wall, etc. Some examples are:
The crests of road/rail embankments, levees, fences and other solid obstructions are
easily inserted using Read GIS Z Line , Read GIS Z Shape or Read GIS Z HX Line .
Read GIS Z Shape is particularly powerful as 3D lines can be given a thickness making
it very easy to quickly raise, or lower, elevations along a road alignment or a diversion
channel where the width of the embankment/channel is wider than the 2D cell size.
The proposed cut and fill for a development or other works can be incorporated using
Read GIS Zpts , Read GIS Z Shape , Read TIN Zpts or Create TIN Zpts . These
powerful commands can set elevations based on regions. Within regions TINs can be
generated from points and lines, and the perimeter of the TIN can be automatically
merged with the existing Zpts. A TIN of the cut and fill produced by SMS or 12D can be
read directly into TUFLOW using Read GIS Zpts .
7. If there is a need to simulate the failure of a flood defence wall or road/rail embankment, or
the collapse of fences, Read GIS Variable Z Shape can be used to control the collapse of the
embankment or fences over time. The collapse can be triggered to occur at a specified time,
when a water level reached somewhere within the model, or based on the water level
difference between two locations.

A 2D domain’s Zpts are built up using one or more of the commands shown in Table 7.4 and
discussed in the following sections.

Section 7 2D Domains - 14 / 116 Page 263 / 1094

 @791 Table 7.4: 2D Zpt Commands

Command Description

Sets all Zpts over the whole 2D domain to the same value. Useful for
providing an initial elevation prior to other commands as some Zpts in
Set Zpt inactive (land) parts of the model may not receive a value. The default value
for all Zpts is 99999. Every Zpt must be assigned a value, essentially
making this command mandatory.

Directly interrogates a raster grid (e.g. tif, .flt or .asc) to define Zpt
Read Grid
elevations. This command is similar to Read TIN Zpts but works on a grid
Zpts
rather than a TIN.

Read TIN Zpts

Reading of a TIN to set the Zpt values within the TIN.

Powerful command to modify Zpt values using points, lines and polygons.
Lines can vary in width from just the cell sides (thin), whole cells (thick) or
be assigned a width (thickness). TINs are created within the polygons and
incorporate elevations from points and lines that fall within the polygon. The
Read GIS Z perimeter of the polygon can be merged with the current Zpt values in part,
Shape or in its entirety.

Read GIS Z Shape and Create TIN Zpts are excellent for removing bad
data areas and for filling in null areas where the aerial survey has provided
poor or no data. Another example is to remove buildings from a DEM.

Allows the user to define the eroded 3D shape of a section of the 2D

domain, specify the period for collapse, and how the collapse is triggered
Read GIS
(i.e. at a specified time or when a water level is reached or when a water
Variable Z
level difference is exceeded). Raising of the Zpts over time is also permitted
Shape
(e.g. to model the influence of flood defences during an event or a landslide
filling a river).

Useful for having TUFLOW create a TIN using polygons for TIN boundaries
and points and lines within the polygons to create the TIN. If no points are
Create TIN
snapped to the perimeter vertices of a polygon, the elevations around the
Zpts
polygon’s perimeter are merged with the current Zpt values. The resulting
TIN can optionally be exported to SMS and 12D TIN formats.

Read GIS Z This is a legacy feature and it is recommended to use the Z Shape
Line functionality (Section 7.3.5.2 ) instead.

Read GIS Z Similar to Read GIS Z Line , but uses HX lines and ZP points in a 2d_bc
HX Line layer (see Table 8.6 ) to adjust the 2D cell elevations along HX lines.

Typically used for simple modifications of sections of the topography.

Examples are filling an area (defined by a region or polygon object) to the

Read GIS Zpts same elevation or dredging (lowering) a section of river using Read GIS
Zpts ADD .

Read GIS Z Shape offers greater functionality and may be preferable to

using Read GIS Zpts to modify Zpts.

Section 7 2D Domains - 15 / 116 Page 264 / 1094

 Command Description

Maximum
Points Use these commands to increase the maximum number of elevation points
Maximum or maximum number of vertices in a single line or polygon.
Vertices

Default Land Z
Now rarely used in lieu of Set Zpt .

Interpolate ZC Allows the interpolation of Zpts from other types of Zpts. Now rarely used as
nearly all models assign values directly to all the Zpts. The original
Interpolate TUFLOW code only required input of ZH points, and Interpolate ZUVC
ZHC provided a tool for interpolating the other Zpts.
Interpolate
Models with “bumpy” terrain, such as that from airborne laser surveys, might
ZUV
benefit from using Interpolate ZHC or Interpolate ZUV.
Interpolate
ZUVC Models through urban areas where the DTM includes the buildings may
Interpolate benefit from using Interpolate ZC ALL LOWER, which reduces the amount of
ZUVH cells that become blocked out due to high ZC elevations from buildings.

ZC == Rarely used. Sets the ZC (cell centre elevation) to the lower of the ZU and
MIN(ZU,ZV) ZV (cell sides).

@792
7.3.5.1 Direct Reading of DEM Grids

The use of the .tgc command Read Grid Zpts allows TUFLOW to directly interrogate (point
inspect) a DEM to set the Zpt elevations. This command is similar to Read TIN Zpts but works on
a grid rather than a TIN.

Grid formats currently supported are:

GeoTIFF (.tif)
Geopackage raster (.gpkg)
Binary grid format (.flt/.hdr)
ESRI ASCII Grid format (.asc)

Nearly all GIS software will support one of the above grid formats.

The GeoTIFF format is the default output format and preferred input format. It is faster to read and
write compared to the .flt and .asc formats, and also supports compression. The format of grids
can be converted (e.g. from .flt to .tif), the Raster Format Conversion TUFLOW Wiki page details
how to do this.

Like other .tgc commands, the command Read Grid Zpts can be specified multiple times. An
option to specify ADD, MIN or MAX in the same way as for other similar commands is also
available.

Clip regions can be specified as a second argument in the command Read Grid Zpts (and also
Read TIN Zpts ) by reading in a GIS layer containing one or more polygons to clip the area of
Zpts to be inspected. For example, the command below will only assign elevations to Zpts that lie
inside polygons within the 2d_clip_DEM layer:

Section 7 2D Domains - 16 / 116 Page 265 / 1094

 Read Grid Zpts == grid\DEM_M01.tif | DEM\2d_clip_DEM.shp

The attributes of the clip layer are not used, and only polygons are processed. As such, any of the
TUFLOW empty files can be used as the template for this layer. Polygons can have holes in them
if required.

This is particularly useful for clipping out a TIN or DEM due to unwanted or irregular triangulation
around the periphery, especially for secondary TINs/DEMs of proposed developments lying within
the primary TIN/DEM.

Note: For your base Zpts from the primary DEM or TIN, do not clip this with your active
2d_code layer as this will cause problems with Zpts along any external 2d_bc boundaries. If
no clip layer is specified, the Read Grid Zpts or Read TIN Zpts commands assign all Zpts
falling within the Grid / TIN an elevation irrespective of whether a cell is active or inactive.

When reading grids into TUFLOW, the same interpolation approach occurs for all formats. The
procedure TUFLOW follows is:

The DEM elevation is assumed to be in the centre of the DEM grid cell (pixel), as shown by
the four red circles in the picture below.
A midpoint vertex (green circle) is defined in the middle of the four DEM elevations.
The elevation of the midpoint vertex (green circle) is equal to the average of the four DEM
elevations (red circles).
The DEM grid cell centre points (red circles) and midpoint vertex (green circle) are used to
create a TIN.
Elevations within the TIN are interpolated from the associated TIN points. For example, a Zpt
is included in the image below as a yellow point. The elevation assigned to that Zpt is the
planar (linear) interpolation of the surrounding three elevation points associated with the top
TIN triangle in the image.

@793
7.3.5.2 Z Shape Layers (2d_zsh)

Read GIS Z Shape offers a wide range of options for manipulating and modifying the Zpt values.
These include 3D breaklines and TINs. Table 7.5 provides a description of the different 2d_zsh
GIS layer attributes.

When a mixture of different shapes and shape options occur within the same layer the following
protocols are used to control how Zpt values are modified.

1. The order in which objects are processed is:

1. Polygons: All polygons are triangulated according to the process described for
Create TIN Zpts in Section 7.3.5.4 . The only difference to note is that if a line is to be

Section 7 2D Domains - 17 / 116 Page 266 / 1094

 used for the TIN generation, the Shape_Options attribute for the line must include the
keyword “TIN”.
2. Wide Lines: Wide lines are lines that have a Shape_Width_or_dMax attribute value
greater than 1.5 times the 2D Cell Size . A buffer polygon is created along the line, and
all Zpts falling within the buffer polygon are assigned elevations based on a perpendicular
intersection with the line. Note that wide lines are processed in the order that they occur
in the GIS layer, so if the buffer polygons of two wide lines overlap each other, the latter
one prevails. In this situation it would be wise to separate the two lines into two different
layers. Buffer polygons can be viewed in the _sh_obj_check layer.
3. Thin and Thick Lines: Thin lines have a Shape_Width_or_dMax value of zero and Thick
lines a value less than or equal to 1.5 times the 2D Cell Size . For a more detailed
description of Thin and Thick lines see Read GIS Z Line . Thin and Thick lines are
applied depending on the Shape_Options attribute setting as follows:
1. All ADD lines are applied first.
2. Followed by lines without any option (these will modify all Zpts affected by the line).
3. Followed by GULLY, LOWER or MIN lines.
4. And finally, any RIDGE, RAISE or MAX lines.
2. The priority can of course be further controlled by using different layers and controlling the
order which layers are listed and subsequently processed in the .tgc file.

Some examples of using Read GIS Z Shape are given below. Models set up using these
topography update features are provided in the Topography Features Example Model Dataset

Example 1: Triangulating Elevations over a Null Area

The image below shows an example of a DEM that is missing data over a small area within the 2D
domain. Gaps in DEM coverage can sometimes occur over water bodies and occasionally
between the tiles of ALS or LiDAR data received from a third-party provider. An example of using
the MERGE topography update feature is provided in the TUFLOW Tutorial Module 2

Section 7 2D Domains - 18 / 116 Page 267 / 1094

 The .tgc command Set Zpt may be used to quickly and
easily assign elevations to Zpts falling within these
areas, however the limitations of the command mean
the same elevation will be assigned to all null Zpts
across the entire 2D domain. This may not be suitable
in situations where there are multiple gaps in coverage
or where the gap is located on steep terrain.

Read GIS Z Shape with 2d_zsh polygons may instead

be used to triangulate Zpt values based on the Zpt
elevations of the polygon perimeter.

Import in an empty 2d_zsh GIS layer, and digitise a

polygon around the gap in coverage as shown. Ensure
there is a reasonable buffer around the null area. The
attributes of the polygon may be left blank. Alternatively,
a value may be entered in the “Shape_Width_or_dMax”
attribute to control the maximum distance between
intermediate points inserted around the polygon’s
perimeter to interpolate elevations. When left blank, this
distance is half the 2D cell’s size.

This image shows the resulting _DEM_Z.flt check file.

The _zsh_zpt_check layer can be used to view the final
Zpt elevation assigned

Example 2: Use of the NO MERGE and ADD Shape Options

The 2d_zsh NO MERGE option can be used to assign a single elevation to all Zpts falling within
the 2d_zsh polygon (read by the Read GIS Z Shape command). An example of using the NO
MERGE topography update feature is provided in TUFLOW Tutorial Module 2. This may be useful
to set the elevation of a polygon to a known finished floor level of a proposed development.
Digitise a polygon within an empty 2d_zsh GIS layer, and populate the “Z” attribute of each object
with the desired elevation. Set the “Shape_Options” attribute to NO MERGE. The example below
will assign an elevation of 42.1mAHD to all Zpts located within the 2d_zsh polygon.

Section 7 2D Domains - 19 / 116 Page 268 / 1094

 Note that if the NO MERGE option is omitted and no points are snapped to the perimeter of the
polygon, the Z attribute will be ignored and the Zpt elevations will be triangulated based on the Zpt
elevations of the polygon perimeter.

Alternatively, to raise the polygon by a fixed value (i.e. to represent the slab height of a building)
enter this value in the Z attribute and set the “Shape_Options” to ADD. An example of using the
ADD topography update feature is also provided in TUFLOW Tutorial Module 2.

TUFLOW will add the value entered in the Z attribute to the existing Zpt elevations within the
polygon. The entry within the figure to the left will raise Zpt elevations by 0.15m. The use of a
negative value will lower the Zpt elevations by the value of the “Z” attribute. The _zsh_zpt_check
layer can be used to view the elevation points (Zpts) that have been modified.

Example 3: Raising an Embankment

The ADD option may also be used when the 2d_zsh object has been digitised as a line. An
example of using the ADD topography update feature is provided in TUFLOW Tutorial Module 2.
Populate the Z attribute with the amount the embankment is to be raised by. Populate the
“Shape_Options” attribute with ADD as shown in the second figure of Example 2 above. This will
raise the existing Zpt elevations by the value of the Z attribute. By default, TUFLOW will assume a
thin line, and only alter the ZH, ZU and ZV Zpt elevations of a cell. The “Shape_Width_or_dMax”
attribute may be optionally specified to represent a THICK or a WIDE line (refer to Section 7.3.5.2
).

Alternatively, if a 3D breakline has been digitised, the dZ attribute on the snapped points may be
used to raise or lower the embankment. The dZ attribute increases or decreases the elevation of
the point’s Z attribute by the amount of dZ. In the example below, a 3D breakline has been created
by snapping points to either end of the line. The elevations along the line are determined by a
linear interpolation of the Z attribute of the points. Entering a positive dZ value at each point will
raise the elevations at the points by the amount of dZ at each point (0.2m for one of the points in
the figure below). The elevations along the line are then interpolated based on these revised
values. The _zsh_zpt_check layer can be used to view the final Zpt elevation assigned.

Section 7 2D Domains - 20 / 116 Page 269 / 1094

 Example 4: Removing ridges from a poorly triangulated DEM.

Section 7 2D Domains - 21 / 116 Page 270 / 1094

 The image shows two false ridges indicated by the H
letters. These were caused by a poor triangulation by
the TIN software used to create the DEM. These ridges
caused unrealistic flow patterns, as shown by the
velocity vectors.

Note, The blue cells at the bottom are the downstream

boundary cells.

This image is of the DEM_Z and _zpt_check check file

layers from the TUFLOW simulation. This is how
TUFLOW interprets the DEM data. The false ridges are
clearly shown.

To remove the ridges, import an empty 2d_zsh layer,

and digitise a polygon around the ridges as shown. By
default (i.e. using the default attribute values), the
elevations assigned around the perimeter of the
polygon are interpolated from the current Zpt values.

One problem with this approach is that the elevations

along the right-hand side (i.e. along the edge of the
floodplain between Locations A and B) are interpolated
from the high Zpts along this boundary.

To solve this problem, digitise points either into the

2d_zsh layer or into a 2d_zsh…_pts layer that snap to
the vertices of the polygon where the high elevations
occur. Assign a Z attribute of -99999 to each point, as
shown in the image. The -99999 indicates to not
interpolate an elevation from the existing Zpts. Instead,
the elevations at Locations A and B are used to
interpolate elevations at vertices where -99999 has
been assigned.

Section 7 2D Domains - 22 / 116 Page 271 / 1094

 Use Read GIS Z Shape to process the polygon and
points and generate the TIN as shown in the image.
The TIN can be viewed by importing the _sh_obj_check
GIS layer.

This image shows the new DEM_Z check file after the
above 2d_zsh layer has been applied. As can be seen,
the ridges have been removed and the flow patterns are
now realistic.

Example 5: Highway Embankment Removal Example

The figures below present another example where a new highway, which exists in the DEM,
needed to be removed because the calibration flood events occurred before the highway was
built. Removal of the highway only required the digitising of a 2d_zsh polygon around the highway.
All attributes were left as their defaults, and there was no need to specify any elevation points.
This example then used an additional Z shape line and point feature to reflect the existing
highways topography (using the method discussed in Example 3). Either Read GIS Z Shape or
Create TIN Zpts can be used for this purpose.

Section 7 2D Domains - 23 / 116 Page 272 / 1094

 @794 Table 7.5: 2D Z-Shape (2d_zsh) Attribute Descriptions

Default GIS Attribute

No. Description Type
Name

Point:
Elevation of the point. Points are only used to
assign elevations along lines and polygon
perimeters, or for the creation of TINs within
polygons. They do not modify Zpts directly.

An elevation of -99999 has a special meaning

when the point is snapped to a vertex of a
polygon. The -99999 indicates to ignore the
elevation at that vertex and of any
automatically inserted vertices between that
vertex and the two neighbouring vertices.
Instead the elevations are based on the
elevations of the neighbouring vertices. If a
neighbouring vertex also has a -99999 point
snapped to it, the next vertex is used, and so
on. This feature is very useful, as illustrated in
the example above.

Line:

1 Z Elevation of the line if no points are snapped to Float

the line.

If the ADD option is specified, the value

entered is used to increase (positive ‘Z’ values)
or decrease (negative ‘Z’ values) the elevation
of the Zpt values by the amount specified
(i.e. a value of 0.5 will raise existing Zpt values
by 0.5m).

Otherwise ignored.

Polygon:
If the NO MERGE option is specified, used to
set the elevation of the polygon perimeter if
there are no points snapped to the perimeter.

If the ADD option is specified, the value

entered is used to increase (positive ‘Z’ values)
or decrease (negative ‘Z’ values) the elevation
of the Zpt values by the amount specified.

Otherwise ignored.

Section 7 2D Domains - 24 / 116 Page 273 / 1094

 Default GIS Attribute
No. Description Type
Name

Point:
Change in elevation of the ‘Z’ attribute of the z-
shape object at the point. To leave ‘Z’
unchanged, set to zero. Useful for easily
adjusting the height of the shape object without
having to change the original ‘Z’ value. For
example, if the Z attribute has been set to
2 dZ Float
5mAHD, a dZ value of 0.1m will raise the
point’s Z elevation to 5.1mAHD.

Line:
Not used. Recommend setting to zero.

Polygon:
Not used. Recommend setting to zero.

Point: Not used.

Line (no TIN):

Provided “TIN” is not specified for the
Shape_Options attribute, this attribute
specifies the width (thickness) of the breakline
in metres. If equal to zero, only the elevations
along the cell sides and corners are adjusted
(i.e. a thin breakline). If less than or equal to
1.5 times the 2D Cell Size , a line of whole
cells is adjusted (i.e. a thick line). Otherwise all
Zpts within a distance of half
Shape_Width_or_dMax are adjusted.

Line (TIN):
If “TIN” is specified for the Shape_Options
3 Shape_Width_or_dMax Float
attribute, this attribute controls the maximum
distance between automatically added
intermediate vertices. If set to zero, half the 2D
domain’s Cell Size is used. If less than zero
no intermediate vertices are inserted.

Polygon:
The maximum distance between intermediate
points inserted around the polygon’s perimeter
to interpolate elevations from the current Zpts.
If set to zero, half the 2D Cell Size is used. If
less than zero no intermediate vertices are
inserted.

Not used if the NO MERGE or ADD options are

specified.

Section 7 2D Domains - 25 / 116 Page 274 / 1094

 Default GIS Attribute
No. Description Type
Name

Point: Not used.

Line or Polygon:
ADD: Add the shape’s ‘Z’ attribute value to the
current Zpts. If ADD is specified, any automatic
merging around the region perimeter is ignored
(to merge the perimeter with existing Zpts
when using the ADD option, specify a value of
zero for the Z and dZ attributes for the region).

MAX, RIDGE or RAISE: Only changes a Zpt

elevation if the Z Shape elevation at the Zpt is
higher.

MIN, GULLY or LOWER: Only changes a Zpt

elevation if the Z Shape elevation at the Zpt is
lower.

4 Shape_Options Line Only: Char(20)

TIN: Indicates the line is only to be used for of
generation of TINS from polygons (therefore,
only sections of TIN lines that fall within the
polygon(s) are used).

Polygon Only:
If none of the options below are specified, the
elevations at perimeter vertices that do not
have an elevation point snapped to them are
merged with the current Zpt values.

MERGE ALL: Ignores elevations from any

points snapped to the perimeter and merges
all perimeter vertices with the current Zpt
values.

NO MERGE: Does not merge the perimeter

elevations with the current Zpt values.

@795
7.3.5.3 Variable Z Shape Layer (2d_vzsh)

TUFLOW 2D model topography can be varied over time to simulate breaching of embankments,
raising of flood defences during an event, or the filling of a river due to a landslide, by using Read
GIS Variable Z Shape . The 2d_vzsh layer is used to define the final topographic shape at the
end of the topography change period. As summary of the GIS layer attributes is provided in Table
7.6 . The first four attributes of 2d_vzsh are the same as the 2d_zsh layer. They are used to
define the finished state of the variable geometry. Additional attributes have been added to allow
the user to define how/when the breach commences and for how long. The breach/fill can be
triggered using a number of methods:

Section 7 2D Domains - 26 / 116 Page 275 / 1094

 At a specified time (example provided in TUFLOW Tutorial Module 10 - Part 1);
When the water level reaches a specified height at a specified (trigger) location (example
provided in TUFLOW Tutorial Module 10 - Part 2); or
When the water level difference between two triggers exceeds a specified amount.

Variable Z Shapes can be restored once or repeatedly. Examples would be a breach of a flood
defence wall or levee that is reinstated 6 hours later, or a sand bar of a creek entrance that
repeatedly opens and closes. To use the restore feature, two additional attributes Restore_Interval
and Restore_Period are required as described below in Table 7.6 . For a single restoration event,
only these two additional attributes are required. To restore repeatedly, “REPEAT” must be
specified in the Shape Options in column 4. Repeated restoration is only possible for the water
level and water level difference trigger methods, as a time trigger will not be able to be reached on
a second occasion.

Note, this variable geometry feature should be used instead of the 2d_bc VG option (unless the
rate of change of the erosion/fill is non-linear) as 2d_vzsh layers are easier to define and manage.

Section 7 2D Domains - 27 / 116 Page 276 / 1094

 @796 Table 7.6: 2D Variable Z-Shape (2d_vzsh) Attribute Descriptions

Default GIS Attribute

No. Description Type
Name

1 Z Same as for Table 7.5 . Float

Same as for Table 7.5 .

The exception is for a thin line, for which the
final elevations along the line can be set to dZ
metres above the current Zpt values.

2 dZ For example, if a thin line represents a fence Float

that is being collapsed, and the finished height
of the collapsed fence is to be 0.2m above
existing ground levels, specify a dZ value of
0.2. Note this only applies if the NO MERGE
Shape_Options has not been specified.

3 Shape_Width_or_dMax Same as for Table 7.5 . Float

Point:

TRIGGER or TRIGGER 1D: Indicates the point

is not an elevation point, but a trigger location.
The trigger must be given a name using the
Trigger_1 attribute. TRIGGER 1D is required if
a 1D node water level is used to trigger a 2D
variable Z-Shape. The trigger point must be
snapped to the 1D node or channel end in the
2d_vzsh layer to achieve this.

Line or Polygon: Same as for Table 7.5 .

Except the ADD option is not supported.

REPEAT: Specify this option for the variable Z

4 Shape_Options Char(20)
shape to repeatedly function indefinitely based
on the below trigger and restore attributes.

Thin Line:

NO MERGE: For thin lines

(Shape_Width_or_dMax = 0), the final
elevations along the line are as specified. If
NO MERGE is not specified for a thin line, the
final elevations are set to be the same as the
current Zpt values plus the dZ value.

REPEAT: Specify this option for the variable Z

shape to repeatedly function indefinitely based
on the below trigger and restore attributes.

Section 7 2D Domains - 28 / 116 Page 277 / 1094

 Default GIS Attribute
No. Description Type
Name

Point: If Shape_Options is set to TRIGGER or

TRIGGER 1D, enter the name of the trigger
location. The name can contain any characters
and can include spaces. Otherwise not used.

Line or Polygon: To commence the failure at

a specified time leave blank.

To commence failure based on reaching a

water level elsewhere in the model, enter the

5 Trigger_1 name of the trigger location. Char(20)

Thin Line: For thin lines there are two special

options as follows. Specify DEPTH to have the
failure commence once the depth of water
adjacent to the cell side exceeds the amount
specified for Trigger_Value. Specify DEPTH
DIFF to have the failure commence once the
difference in water level across the cell side
exceeds the amount specified for
Trigger_Value.

Point: Not used.

Line or Polygon: The name of a second

6 Trigger_2 trigger location (only needed if the breach is to Char(20)

be initiated on a water level difference between

two trigger locations).

Section 7 2D Domains - 29 / 116 Page 278 / 1094

 Default GIS Attribute
No. Description Type
Name

Point: Not used.

Line or Polygon: If Trigger_1 is blank, the

simulation time in hours that the breach is to
commence.

If Trigger_1 is specified and Trigger_2 is left

blank, the water level at Trigger_1 that needs
to be reached to trigger the failure.

If both Trigger_1 and Trigger_2 are specified,

the water level difference between Trigger_1
and Trigger_2 that needs to be exceeded to
trigger the failure. The water level difference is
taken as the absolute of the difference
between Trigger_1 and Trigger_2, so there is
7 Trigger_Value no need to specify a negative value. Float

Thin Line:

If “DEPTH” is specified for Trigger_1, the depth

in metres adjacent to the cell side that needs
to be exceeded to trigger the failure at the cell
side.

If “DEPTH DIFF” is specified for Trigger_1, the

water level difference in metres across the cell
side that needs to be exceeded to trigger the
failure.

For all of the above options the length units

are metres if modelling in SI units, or feet, if
using Units == US Customary.

Point: Not used.

8 Period Line or Polygon: Time in hours over which Float

the variation in Zpt elevations occurs.

The time in hours between when the variable Z

shape has finished altering the geometry and
when to start restoring the Zpts back to their
original values.

9 Restore_Interval Note: “REPEAT” must be specified in Column Float

4 to allow repeated triggering and restoration

of the Variable Z Shape (for the water level
and water level difference options), otherwise
restoration will only occur once.

Section 7 2D Domains - 30 / 116 Page 279 / 1094

 Default GIS Attribute
No. Description Type
Name

Time in hours over which the variation in Zpt

10 Restore_Period elevations occurs to restore the Zpts back to Float
their original values.

Example 1: Variable Z Shape Example: Breaching of an Embankment

The image below shows an example of a 2d_vzsh layer. The solid magenta line is the polygon, the
magenta dashed lines are lines used to enforce TIN breaklines, and the four magenta points all
have an elevation of 41.0m. The Shape_Options attribute for the polygon was set to MIN (this
means that the Zpt elevation can only be lowered (i.e. eroded), and the dashed lines have
Shape_Options of TIN (to indicate that they are to be used for TIN generation, and not for Z lines).
The vertices of the polygon that do not have a point snapped to them will be automatically
assigned an elevation based on the existing Zpt values. The polygon vertices with the points
snapped to them are assigned the elevation of the point (in this case, all at 41.0m). The elevation
of the dashed lines will be constant at 41m as they are snapped to the 41m points.

The only other object in the layer is the yellow pin point labelled A. This is a trigger point. Its only
attribute values are: TRIGGER for the Shape_Options attribute; and A for the Trigger_1 attribute.
This sets the point as a trigger point and the “A” is the name of the trigger point. The magenta
polygon also has attribute values of: A for Trigger_1 (this indicates that the erosion trigger is based
on the water level at Trigger Location A); a Trigger_Value of 42.0 (i.e. when the water level at
location A reaches 42m, start the erosion); and a Period value of 1.0 indicating that the erosion
takes one hour to complete.

The final eroded Zpt values are based on the TIN created by TUFLOW (the grey triangles in the
image below). The central section will be horizontal at 41m, sloping up either end to elevations
based on the road level. The _vzsh_zpt_check layer is useful to view the Zpts affected by the
variable Z shape. This layer is also shown in the image below. The green triangles indicate that
the Zpt level is to be eroded, and the crosses indicate no change (this is because of the MIN
Shape_Options). The final eroded Zpt values are labelled in the image below. Other useful
attributes are also available in this layer.

Section 7 2D Domains - 31 / 116 Page 280 / 1094

 The images below show the modelled breach which occurs using the example above. Each image
is in half hour intervals. The colour shading is of the elevations (specify ZH as a Map Output Data
Types to view the changes in ground level over time).

@797
7.3.5.4 3D TIN Layers (2d_ztin)

TINs (triangulations) of elevation points and 3D lines within a polygon can be carried out using
Create TIN Zpts . This is particularly useful for modifying the Zpt elevations where there have
been, or are proposed, changes to the base DEM Zpt values.

Note, for large datasets it is likely to be much more efficient to use GIS or 3D surface modelling
software to triangulate the data, and read triangulated data in a supported format (see Read TIN
Zpts ) or to convert to raster (see Read Grid Zpts ).

The protocols applied to the Create TIN Zpts command are:

1. A TIN is created for each polygon in the 2d_ztin layer.

2. Any points found within a polygon are used when generating the TIN.
3. Any lines are converted to points, and those points falling within the polygon are used for the
TIN creation. Lines are converted to points as follows:
1. All vertices (nodes) of the line are converted to points.
2. The dMax attribute is used to insert additional vertices between the line’s vertices. For
example, if dMax is set to 10, then additional intermediate vertices are inserted at least

Section 7 2D Domains - 32 / 116 Page 281 / 1094

 every 10 metres (or feet if using Units == US Customary) between the existing
vertices where the distance between the existing vertices exceeds this value. If the dMax
attribute does not exist or is zero, half the 2D domain’s Cell Size is used as the dMax
value.
3. If there are any points snapped to the line’s vertices, the elevations of these points are
used to set the elevations at all the vertices generated along the line. In this way, a 3D
breakline effect can be produced within the TIN. If there are no points snapped to the line,
the line’s Z attribute elevation is used giving the effect of a horizontal line.
4. The perimeter of the polygon/TIN can either be merged with the current Zpt values or have its
own values as follows:
1. If there are no points snapped to the perimeter of the polygon, the elevations of the
polygon’s perimeter vertices, and of any automatically inserted vertices, are based on the
current Zpt values (i.e. the Zpt values assigned by any prior commands).
2. If there are one or more points snapped to the polygon’s perimeter vertices, the perimeter
is not merged with the Zpt values, and the elevations of the snapped points are used to
assign elevations to the perimeter vertices and any automatically inserted vertices.
3. The frequency of any automatically inserted points around the perimeter is controlled by
the dMax attribute. If the dMax attribute does not exist or is zero, half the 2D domain’s
Cell Size is used.

The 2025 release introduced a new method “Method B” as beta functionality for triangulating TINs
that applies to any of the commands that build a TIN, such as Create TIN Zpts and Read GIS Z
Shape commands. The new method can be applied using the TIN Triangulation Approach
command. “Method A” is the original triangulation approach. Method B uses the same inputs as
Method A and creates the same input points and elevations, however, creates the triangles
differently. While Method A adds additional vertices to lines to encourage edges to follow
breaklines, these are strongly enforced using Method B. Method B also generates more balanced
triangles avoiding long skinny triangles or clumps of triangles.

Models using the Create TIN Zpts functionality are provided in the Static Topography Updates
Example Model Dataset on the TUFLOW Wiki.

A useful quality control option of Create TIN Zpts is the WRITE TIN option. This will write a TIN to
either the SMS TIN or SMS 2DM format depending on the setting of TIN Output Format . If this
option is specified, a SMS .tin or .2dm file is written for each TIN generated, and the triangles are
written to the _sh_obj_check layer. This means that the TIN can be cross-checked, viewed, and
edited and modified in SMS (tin or 2dm) or QGIS (2dm). Read TIN Zpts can be used to assign
Zpt elevations from the modified SMS TIN.

A second argument to specify a GIS layer containing one or more polygons to clip the area of Zpts
to be inspected can be used with the Read TIN Zpts command. Refer to Section 7.3.5.1 for
more information.

Section 7 2D Domains - 33 / 116 Page 282 / 1094

 @798 Table 7.7: 2D Tin (2d_ztin) Attribute Descriptions

Default GIS
No. Attribute Description Type
Name

Point: Elevation of the point.

Line: Elevation of the line. Ignored if there are any points

1 Z Float
snapped to the line’s vertices.

Polygon: Not used.

Point: Not used.

Line: Maximum distance between automatically created

dMax intermediate vertices. If set to zero or this attribute does not
2 Float
(optional) exist, half the 2D domain’s Cell Size is used. If less than
zero no intermediate vertices are inserted.

Polygon: Same as for Line above.

@799
7.3.5.5 3D Breakline Layers (2d_zln)

This is a legacy feature and it is recommended to use the Z Shape functionality (Section 7.3.5.2 )
instead. For details on this feature see Read GIS Z Line in Appendix C .

@800
7.3.5.6 Zpt Layers (2d_zpt)

This is a legacy feature, to define base elevations it is recommended to use the Read Grid Zpts
functionality (Section 7.3.5.1 ) instead. For details on this legacy feature see Read RowCol Zpts
in Appendix C .

Similarly, Read GIS Zpts is also a legacy command. It is recommended to use the Z Shape
functionality (Section 7.3.5.2 ) instead of it.

@801
7.3.5.7 Using Multiple Layers and Points Layers

GIS layers used for Read GIS Z Shape , Read GIS Variable Z Shape , Create TIN Zpts , Read
GIS Layered FC Shape , Read GIS Z Line (legacy), Read GIS Z HX Line (legacy) and Read
GIS FC Shape (legacy) can be split into more than one layer to better manage the variety of data
these commands sometimes require.

For example, one layer may contain the elevation points, another the TIN lines and polygons and
another the 3D Z lines. This is useful in terms of managing the data, and especially when
interrogating and/or viewing the data in GIS. It is a requirement of the shapefile format that the
different geometries (points, lines and regions) are in separate shapefiles. The TUFLOW empty
template files include the following filename suffixes to differentiate which files are suitable for
point, line or region features.

_P for point features (e.g. 2d_zsh_M03_002_P.shp)

_L for line features (e.g. 2d_zsh_M03_002_L.shp)
_R for region or polygon features (e.g. 2d_zsh_M03_002_R.shp)

Section 7 2D Domains - 34 / 116 Page 283 / 1094

 This is optional for MapInfo users; the different geometries can occur in the same MapInfo file or
can be separated if preferred.

A maximum of nine (9) layers per command line is allowed, and each layer is separated by a
vertical bar (“|”). For example, to read a Z Shape layer which has both line and points, the
command may be:

Read GIS Z Shape == gis\2d_zsh_M03_002_L.shp | gis\2d_zsh_M03_002_P.shp

If using the GeoPackage format && is also used to specify more than one layer from a common
database in the same command line. An example is provided below. See Section 4.4.3 for further
details.

Read GIS Z Shape == gis\2d_zsh_R.gpkg | gis\2d_zsh_002.gpkg >> 2d_zsh_L

&& 2d_zsh_P

@802
7.3.5.7.1 Point Only Layers

To minimise the number of attributes, some/all points may optionally be placed into a separate
layer with less attributes as discussed below. This simplifies the datasets making them easier to
manage and interrogate.

A layer is treated as a separate points layer if:

1. It has less attributes than the minimum required for the command. For most commands there
is only one attribute for the points layer (i.e. Elevation or Z) as described in Table 7.8 . The
exception is Read GIS FC Shape , which requires the first two attributes. This option
requires that the points layer be defined within the command line syntax. For example:
Read GIS Z Shape == gis\2d_zsh_M03_002_L.shp |
gis\2d_zsh_M03_002_P.shp
2. The points file uses the same filename as the associated line or region file with the addition of
“_pts” as a suffix to its filename (for example 2d_zsh_M03_002_pts.shp will be automatically
associated with the line file 2d_zsh_M03_002.shp). This option is supported for backward
compatibility; however, it’s recommended that this option not be used (it is preferable to enter
the filename of the second layer so that it is clear as to which layers are being used).
Read GIS Z Shape == gis\2d_zsh_M03_002.shp

The data processing logic for points layers is outlined below:

1. The specified layer, 2d_zsh_M03_002.shp, is opened. This layer may or may not contain
elevation points. If any elevation points exist they are used.
2. A separate points layer can optionally be used to specify additional points or all of the points.
The layer can be specified in one of two ways:
1. Entering the pathname of the points layer after the main layer. A “|” must be used to
separate the two layers. The points layer must be the second layer specified. For
example:
Read GIS Z Shape == gis\2d_zsh_M03_002_L.shp |
gis\2d_zsh_M03_002_P.shp
2. Alternatively, name the points layer the same as the main layer, but with a “_pts”
extension. If a layer exists with the “_pts” extension, TUFLOW automatically assumes this
layer is associated with the main layer and includes all points within this layer when

Section 7 2D Domains - 35 / 116 Page 284 / 1094

 applying the above commands. For this example, the layer would be named
2d_zsh_M03_002_L_pts.shp.
3. The first approach (i) above prevails over the second (ii) if both apply.
4. If neither (i) or (ii) apply, TUFLOW assumes there is no separate points layer.

Multiple points layers can be specified. The points layer can be referenced in any location except
for the first layer within the command line entry. For example, the below syntax will produce an
error due to the points file being the first entry.

Incorrect:
Read GIS Z Shape == gis\2d_zsh_M03_002_P.shp | gis\2d_zsh_M03_002_L.shp

Correct:
Read GIS Z Shape == gis\2d_zsh_M03_002_L.shp | gis\2d_zsh_M03_002_P.shp

@803 Table 7.8: 2D Z (2d_z_) Attribute Descriptions

Default GIS Attribute

No. Description Type
Name

Elevation (or change in elevation for ADD option)

1 Z Float
of the point.

@804
7.3.6 Land Use (Materials)

@805
7.3.6.1 Bed Resistance

The bed resistance values for 2D domains are created by using GIS layer polygons or rasters of
different bed resistance zones. The default and recommended bed resistance formulation is
Manning’s n. Manning’s n values can be varied with depth (as user specified curve or using the
Log Law formula (see Section 7.3.6.3.1 )) or varied with velocity-depth product (VxD).

For TUFLOW Classic, bed resistance can also be set to use either Manning’s M values (1/n) or
Chezy coefficients using the Bed Resistance Values command in the .tcf file. As this is a
TUFLOW Classic feature only, it is further discussed in Section 7.5.3 .

The recommended approach is to use materials to define how the bed roughness varies over the
model. Each material is defined by a positive integer ID which represents a different roughness
category. GIS layers of land-use or vegetation often make excellent material layers. Examples of
different material categories are river in-bank, bank vegetation, pasture, maintained grass, roads,
buildings, forest, mangroves, etc. Each material is assigned a constant Manning’s n value, depth
or VxD varying Manning’s n. The material layer can also be used to set rainfall losses (if using
direct rainfall - see Section 8.5.3 ), fraction impervious, storage area and land-use hazard
categories (see Section 7.3.6.3.1 ).

Material/roughness values are used by TUFLOW during conveyance calculations at the cell mid-
sides (refer to Section 7.2 and 7.2.3 ). However, rainfall losses and fraction impervious are
applied to the cell and not cell sides, therefore, materials ID values are sampled at both cell mid-
sides and cell centres.

Section 7 2D Domains - 36 / 116 Page 285 / 1094

 The most common approach is to digitise one or more 2d_mat materials layers (see Table 7.9 )
and assign Manning’s n values to the materials using Read Materials File . This approach allows
the easy adjustment of Manning’s n values, for example during model calibration or sensitivity
testing.

When creating the base 2d_mat layer, it is common practice to not digitise the most common or
the most difficult to digitise material, and instead use the following data layering of commands in
the .tgc file (see Section 4.2.7 ).

Use Set Mat to set the most common material to all cells in a 2D domain.
Use Read GIS Mat or Read Grid Mat to allocate the remaining material values.

The Read GIS Mat and Read Grid Mat commands may be used as many times as required to
further modify the materials in parts of a 2D domain. Each subsequent dataset will overwrite the
preceding assigned material value, as described in Section 7.3.3 .

The default material value is zero. As a material value of zero is not allowed, every cell and cell-
side must be assigned a material value using Set Mat , Read GIS Mat and/or Read Grid Mat in
the .tgc file (it is good practice to always set a default materials value using the Set Mat as the
first material command in the .tgc file). The assigned material ID values do not need to be
contiguous but must be within the range 1 to 32,767.

@806 Table 7.9: 2D Materials (2d_mat) Attribute Descriptions

Default GIS
No. Description Type
Attribute Name

The material ID value referenced within a Materials

1 Material Integer
File (see Section 7.3.6.3 ).

@807
7.3.6.2 Log Law Depth Varying Bed Resistance

At very shallow depths the Manning’s n value and/or equation may not be a reliable estimate of
bed resistance. The Log Law or “Law of the Wall” approach offers a theoretically based derivation
of resistance based on a bed shear analysis. This relationship along with benchmarking against
flume test results was used by Boyte (2014 ) to derive the following equation that varies
Manning’s n with depth based on the roughness height of the surface:
1

@808 κy 6

n = (7.5)
y
g [ln( ) − 1]
√ z0

@810 ks 0.11ν
z0 = + (7.6)
30 Uf

Where:

ks is the roughness height in m

κ is typically in the range 0.38 to 0.42 (recommend 0.4)
y is depth
ν is the kinematic viscosity and is set to 10-6 m2/s
Uf is the friction velocity defined as √Sgy where y approximates A/P and S is the water
surface slope

Section 7 2D Domains - 37 / 116 Page 286 / 1094

 y
Equation (7.5) becomes singular as ln(
z0
) approaches 1, and asymptotes to zero as depth

becomes large. It is therefore necessary to apply sensible limits for the resulting n under these
y
circumstances. For depths such that ln(
z0
) < 1.000001 the Manning’s n is set to n = 10 . For

all other cases, the resulting value for n is bounded to be in range nlimit < n < 10.

Figure 7.7 illustrates how the equivalent Manning’s n varies with depth using the log law for a
roughness height of 10mm (0.01m) that would be applicable to a small pebble bed. The different
series are the variations in the slope, S , where 0.001 is 0.1% slope, 0.02 is 2% slope and 0.1 is a
10% slope. As can be seen there is a significant variation in Manning’s n below 2cm (0.02m) and a
trend to a n value of around 0.018, with only a minor variation due to slope.

In terms of applying a limiting n value, if, for example, nlimit was set to 0.02, then the Manning’s n
value would not fall below 0.02.

Figure 7.8 shows a comparison using the Log Law versus a constant Manning’s n value (Boyte,
2014 ). The thesis investigated the use of the Law of the Wall for direct rainfall modelling using
TUFLOW. The flow depths in this example range from 4 to 20cm and the roughness height, ks ,
was 3cm.

The Log Law Depth Varying Bed Resistance is activated by entering special characters in the 2nd
column of the Materials File. See Section 7.3.6.3 and Table 7.10 .

@830

Figure 7.7: Example of Log Law Variation of Manning’s n with Depth

@831

Figure 7.8: Example of Log Law versus Constant Manning’s n with Depth

Section 7 2D Domains - 38 / 116 Page 287 / 1094

 @832
7.3.6.3 Materials File

Materials file(s) contain information on a material’s roughness and, optionally, rainfall losses if
using direct rainfall. The file is referenced within the .tcf file using Read Materials File and can be
in one of two formats (.csv or .tmf). The .csv format is the recommended of the two options. It
supports all functionality. The .tmf format does not. For example, the log law bed resistance option
is only available via the .csv format. The .csv format also supports curves of Manning’s n versus
depth.

More than one materials file may be specified by repeat occurrences of the command
Read Materials File however, most models will use only a single materials file. Any combination
of .tmf and .csv files can be used and up to 1,000 materials are allowed in total.

If a second argument is provided with Read Materials File , this value is used to factor all
Manning’s n values. For example, the following command increasing all Manning’s n values by
10%:

Read Materials File == My_Materials.tmf | 1.1

@833
7.3.6.3.1 .csv Format

The .csv format materials file is a comma delimited text file containing Manning’s n and other
information for different materials (e.g. land-uses). The format is intended to be generated from an
Excel file database of materials and associated data in a similar manner to BC databases (with the
option of using the Excel TUFLOW Macro .xlam macros to export to the .csv format - the Excel
TUFLOW Tools.xlam can be downloaded from here). The .csv can also be written from text editor
if preferred.

The format of the materials.csv file is described in Table 7.10 .

Note: The .csv format offers access to all materials features, whereas the .tmf format does not.

Section 7 2D Domains - 39 / 116 Page 288 / 1094

 @834 Table 7.10: Materials .csv File Format

No. Description

1 Mat (Material ID) number, which must be an integer.

Contains information on the bed resistance values (usually Manning’s n). The options
available are:

Single n value (the n value is assumed constant at all water depths).

Two pairs of depth and n values (see the y1, n1, y2, n2 option described in Table
7.11 for the .tmf format (i.e. Columns 5 to 8). The values must be separated by
commas.
A .csv file containing n vs depth values. By default, when the n vs depth values are
read they are assumed to be in the first two columns of the .csv file containing the
curve’s data. However, you can specify the columns to be used by placing the
column label after the .csv filename using a vertical bar “|” to separate the column
label from the .csv filename. If only one column label is given, this is assumed to
be the depth column and the next column must contain the Manning’s n values. As
for boundary data, TUFLOW searches down the rows until it finds the first numeric
values and will start reading from this row until a row is found with no more
numeric values. To view how the n values vary with depth over time, use the “n”
option for Map Output Data Types .
2
If the first four characters are “VxD:” the Manning’s n values for the material will be
varied according the velocity times depth product, rather than depth. The VxD
versus n values are provided in the same manner as for depths described above.
Note that the Manning’s n value never increases during the simulation, it can only
remain the same or decrease. This feature was provided to allow the user to
reduce Manning’s n with increasing VxD to represent the “stripping” of river banks
in high VxD areas, and then keeping the reduced Manning’s n as the flood
recedes, hence why the n value cannot increase once decreased during the
simulation. VxD was used in preference for simply V to avoid reducing n values at
very shallow depths (but high velocities) when the flood first inundates the 2D
cells.
If the first four characters are “Log:” the bed resistance as defined by the
theoretically derived log law for shallow flows is applied. Three numbers are
required after the “Log:” in space or comma delimited format. These are: Ks
(roughness height), Kappa (0.3 to 0.4) and the limiting Manning’s n value. See
Section 7.3.6.2 for more information.

Sets the rainfall loss parameters using the initial loss/continuing loss option. The
initial/continuing loss is entered as two comma delimited numbers in a similar manner
3
to the third and fourth column values in the .tmf format. See Table 7.11 . Refer to
Section 7.3.6.4 .

4 Reserved.

Defines the Storage Reduction Factor (SRF) value. If no fifth column entry exists, no
5 SRF is applied. The default is an SRF of 0 (i.e. no change in storage). See Section
7.3.9.1 for more information.

Section 7 2D Domains - 40 / 116 Page 289 / 1094

 No. Description

Defines the Fraction Impervious of the overlying material type. The value entered
should be a number from 0.0 to 1.0 where 0.0 is fully pervious and 1.0 is fully
impervious. The default is a value of 0.0, assuming that the overlying material is 100%
pervious. This feature is used to influence the amount of water that is infiltrated into the
6
ground with the soil infiltration feature. Refer to Section 7.3.7 for more information.
Note: This option works with the Soli Infiltration feature (see Section 7.3.7 ). It
does not apply to materials rainfall losses (Column No 3 above) when applying
direct rainfall (see Section 8.5.3 ).

An example of a materials.csv is provided in Figure 7.9 . To give a description of the material, this
must be done after all inputs for that material and must be preceded by a “!” or “#”.

In the example shown in Figure 7.9 :

Material 1 has a constant n value of 0.03 and no rainfall loss parameters.

Material 5 varies n with depth using the four y1, n1, y2, n2 values (as per .tmf format
approach) and no rainfall loss parameters.
Materials 11 and 12 use depth vaying n sourced from a file called Grass.csv. As only one
column label has been specified, the y values must occur under that label and the n values
must occur in the next adjoining column (see Figure 7.10 ). An IL of 10mm and CL of 2mm/h
for both materials will be used for any direct rainfall.
Materials 21 and 22 use depth vaying n sourced from a file called Trees.csv. As two column
labels have been specified, the y and n values must occur under the specified labels (see
7.10 ). An IL of 20mm and CL of 2mm/h for Material 21, and 25 and 2 for Material 22, will be
used.
Material 31 uses the log law approach (Section 7.3.6.2 ) with a roughness height of 0.01m,
Kappa value of 0.4 and limiting Manning’s n of 0.02. IL = 0mm and CL = 0mm. The fraction
impervious value is set to 1.0 (fully impervious).
Material 32 use depth vaying n sourced from a file called Buildings.csv. In Buildings.csv
Column A is used for y values and Column B for n values. IL = 0 and CL = 0. The storage
reduction factor is set to 0.3 (30% reduction in storage) and the fraction impervious value is
set to 1 (fully impervious).

@835

Figure 7.9: Example of Materials .csv File Format

@836

Section 7 2D Domains - 41 / 116 Page 290 / 1094

 Figure 7.10: Example of the Grass.csv file read into the Materials.csv
@837

Figure 7.11: Example of the Trees.csv file read into the Materials.csv

@838
7.3.6.3.2 .tmf Format

The .tmf format is a text file containing Manning’s n and other information for different materials
(e.g. land-uses). The file can contain comments using the “#” and/or “!” comment characters at
any location. When comment characters are specified, the remainder of the line is ignored. The
format of the materials .tmf file is described in Table 7.11 . The first two columns are mandatory
and must be specified. All other columns are optional. A maximum of 100 different materials can
be specified in this format.

Note: The .tmf format does not offer all materials functionality, whereas the .csv format in the
above section does.

Section 7 2D Domains - 42 / 116 Page 291 / 1094

 @839 Table 7.11: Materials .tmf File Format

No. Description

1 Mat (Material ID) number, which must be an integer.

Manning’s n value.

2 Note, if the four values in columns 5 to 8 are specified, the Manning’s n value in
this column is ignored and not used.

Sets the initial loss if using a direct rainfall boundary (via Read GIS RF or Rainfall
3 Control File ). Refer to Section 7.3.6.4 . This does not apply to Global Rainfall BC .
The units are mm, or if Units == US Customary inches.

Sets the continuing loss rate if using a direct rainfall boundary (via Read GIS RF or
4 Rainfall Control File ). Refer to Section 7.3.6.4 . This does not apply to Global
Rainfall BC . The units are mm/hr, or if Units == US Customary inches/hr.

5 y1 – The depth below which the Manning’s n value n1 (column 6) is applied.

6 n1 –The Manning’s n value applied below depth y1 (column 5).

7 y2 – The depth above which the Manning’s n value n2 (column 8) is applied.

n2 –The Manning’s n value applied above depth y2 (column 7).

Between y1 and y2, the Manning’s n value is interpolated between n1 and n2 according
8 to Bed Resistance Depth Interpolation . When specifying values for columns 5 to 8,
initial and continuing loss values must be specified in columns 3 and 4 as described
above (use zero values if not using direct rainfall).

9 Reserved.

Defines the Storage Reduction Factor (SRF) value. The default is an SRF of 0. Enter 0
10 to ensure there is no change in 2D cell storage for the material type. See Section
7.3.9.1 for more information.

Defines the fraction impervious of the overlying material type. The value entered
should be a number from 0.0 to 1.0 where 0.0 is fully pervious and 1.0 is fully
impervious. The default is a value of 0.0, assuming that the overlying material is 100%
pervious. This feature is used to influence the amount of water that is infiltrated into the
11 ground with the soil infiltration feature. Refer to Section 7.3.7 for more information.

Note: This option works with the Soli Infiltration feature (see Section 7.3.7 ). It
does not apply to materials rainfall losses (Column No 3 above) when applying
direct rainfall (see Section 8.5.3 ).

The .tmf file format is shown in the examples below. See Set Mat , Read GIS Mat and Read
Grid Mat for assigning the material IDs to the 2D domains. These material values may also be
used to define bed resistance values across 1D XZ cross-sections (see Section 5.7.1.1.2 ).

! Comments and blank lines are allowed in this file

! First value is the Mat value, Second is the Manning’s n value
1, 0.03! waterways
2, 0.08! river banks

Section 7 2D Domains - 43 / 116 Page 292 / 1094

 11, 0.06! grazing land
12, 0.04! parks and gardens
13, 0.15! sugar cane
14, 0.12! natural forest
15, 0.02! roads

To include the initial loss (mm) and the continuing loss rate (mm/h) optionally enter a third and
fourth value as shown below. If an IL is specified, a CL must also be specified otherwise an
ERROR occurs. Both can be omitted, in which case, they are both set to zero.

1, 0.03! waterways
2, 0.08, 20, 2! river banks
11, 0.06, 20, 2! grazing land
12, 0.04, 5, 1.5! parks and gardens
13, 0.15, 10, 2! sugar cane
14, 0.12, 30, 2.5! natural forest
15, 0.02, 2, 0! roads

To vary n values with depth (m) using two pairs of values optionally enter values in the fifth to
eighth columns as shown below in lines 2 and 3 (Materials 2 and 11) below. IL and CL values must
be entered (use zero if not relevant). If depth varying manning’s n is not used, column 5 to 8
should be left blank, not set to zero.

1, 0.03! waterways
2, 0.08, 20, 2, 0.3, 0.15, 0.5, 0.08! river banks with long grass
0.3m high
11, 0.06, 20, 2, 0.1, 0.1, 0.15, 0.06! grazing land
12, 0.04, 5, 1.5! parks and gardens
13, 0.15, 10, 2! sugar cane
14, 0.12, 30, 2.5! natural forest
15, 0.02, 2, 0! roads

To reduce the storage of cells, enter a SRF value in the tenth column as shown in line 7 for
Material 15 below. The example shown reduces the storage of all cells with Material ID of 15 by
20%. Note that a value of -1 has been entered for the ninth column as this field has been
reserved. If not used, specify 0 to ensure no change in storage for the material.

1, 0.03! waterways
2, 0.08, 20, 2, 0.3, 0.15, 0.5, 0.08! river banks with long grass
0.3m high
11, 0.06, 20, 2, 0.1, 0.1, 0.15, 0.06! grazing land
12, 0.04, 5, 1.5! parks and gardens
13, 0.15, 10, 2! sugar cane
14, 0.12, 30, 2.5! natural forest
15, 0.02, 2, 0, , , , , -1, 0.2! roads with width reduced by 20%

To specify a fraction impervious, enter a value between 0.0 and 1.0 in the eleventh column as
shown in line 4 for Material 12 below. The example shown partially restricts the rate of infiltration
by applying a fraction impervious of 0.1 or 10%.

Section 7 2D Domains - 44 / 116 Page 293 / 1094

 1, 0.03! waterways
2, 0.08, 20, 2, 0.3, 0.15, 0.5, 0.08! river banks with long grass
0.3m high
11, 0.06, 20, 2, 0.1, 0.1, 0.15, 0.06! grazing land
12, 0.04, 5, 1.5, , , , , -1, 0, 0.1! parks and gardens (10%
impervious)
13, 0.15, 10, 2! sugar cane
14, 0.12, 30, 2.5! natural forest
15, 0.02, 2, 0, , , , , -1, 0.2! roads with width reduced by 20%

@840
7.3.6.4 Rainfall Losses

Rainfall losses applied through the Materials file (.tmf or .csv format) remove the loss depth from
the rainfall before it is applied as a boundary on the 2D cells. Rainfall losses are ideal for
modelling situations in which water is prevented from reaching the ground, such as through the
interception by trees.

Note that the ILCL rainfall losses are different to the ILCL infiltration losses that can be
applied using the .tsoilf file (refer to Section 7.3.7.2 ). The ILCL soil infiltration losses will
infiltrate ponded water into the ground. It is possible to use both methods in the same simulation –
for example, rainfall that doesn’t reach the ground would be modelled as a material IL/CL (applied
as a loss to the rainfall) and infiltration into the ground as IL/CL via soil types. The log file (see
Section 14.5.1 ) will report the material and soil properties separately as shown in the example
below:

Example Material Properties:

#4 - Material 4:
Fixed Manning’s n = 0.030
IL = 1.0mm, CL = 0.0mm/h
Landuse Hazard ID not set.
SRF (Storage Reduction Factor) = 0.
Fraction Impervious = 0.

Example Soil Properties:

#1 - Soil 1 [based on pre-defined soil type SAND]:

Suction = 49.5 mm
HydCond = 117.8 mm/hr
Porosity = 0.417
Initial Moisture = 0.2
Soil Capacity = 0.217

Specifying the “fraction impervious” on the material allows the materials and the soils to be
independent (i.e. the same soil can be present under both road and forest). This fraction
impervious only applies to the infiltration into the soil, not to the Materials file rainfall
losses.

Section 7 2D Domains - 45 / 116 Page 294 / 1094

 @841
7.3.7 Infiltration

Four methods are available to infiltrate water from the surface into the ground:

Green-Ampt (GA) - Section 7.3.7.1.1 ;

Horton (HO) - Section 7.3.7.1.2 ;
Initial Loss/Continuing Loss (ILCL) - Section 7.3.7.1.3 ; and
SCS Curve Number (SCS) (HPC only) - see Section 7.4.5.1.1 .

When using TUFLOW HPC, it is possible to model multiple vertical groundwater layers, as well as
enable horizontal flow of groundwater. As these features are only available in TUFLOW HPC, they
are discussed in Section 7.4.5.2 .

The first three methods mentioned above (GA, HO, and ILCL) monitor the amount of water
infiltrated and if the ground becomes saturated, infiltration ceases. With these methods the
amount of water that can be infiltrated depends on:

The infiltration approach and soil parameters used for the top most (infiltration) soil layer.
The number, thickness, porosities, and initial moisture of the groundwater layers.
The fraction impervious value of the overlying material layer.

The cumulative infiltration data is stored and computed at cell centres. As such all soil data and
groundwater layer geometry is sampled from the GIS / Grid layers at cell centres. Likewise the
material “fraction impervious” data is sampled at cell centres (unlike the Manning’s values which
are sampled at face centres).

The following .tgc commands are used to set the ID for the soil type referenced in the TUFLOW
soils file (.tsoilf) (Section 7.3.7.2 ):

Set Soil ;
Read GIS Soil ; and
Read Grid Soil .

Each of these commands has the option of specifying which soil layer(s) the command applies to.
Note that 2D infiltration is activated by the occurrence of one of these commands. If none of the
commands exists for a 2D domain, soil infiltration does not occur for that domain.

If soils are specified, the soil ID for each cell are written to the _grd_check layer. The .tlf file
contains the parameters for each Soil ID.

@842
7.3.7.1 Infiltration Layer

Only wet 2D cells can infiltrate water into the ground. If using soil infiltration with a single
groundwater layer, the default groundwater depth is infinite. The depth (thickness) of the
groundwater layer can be set globally using the following commands:

Set Soil Thickness

Set Soil Base Elevation

They can also be set spatially with the following GIS and Grid commands:

Read GIS Soil Thickness

Read GIS Soil Base Elevation
Read Grid Soil Thickness

Section 7 2D Domains - 46 / 116 Page 295 / 1094

 Read Grid Soil Base Elevation

The soil thickness sets the layer depth from the surface elevation. The soil base elevation sets the
absolute elevation of the bottom of the layer. If both methods are specified for a given grid cell, the
highest of the two will be adopted. The input units should be in metres or feet. To set an initial
groundwater level within the soil layer, see Section 8.9.2 .

In releases prior to 2023-03, the groundwater level (or depth) was set to represent a water table.
For backward compatibility, it is still possible to the set a water table, using these commands:

Set GWD or Set GWL

Read GIS GWD or Read GIS GWL
Read Grid GWD or Read Grid GWL

The amount of water that enters the soil is also dependent on the fraction impervious value of the
overlying material layer. The default is that the overlying material is 100% pervious (i.e. 0%
impervious). However, if, for example, a concrete parking lot overlies a sandy soil, the
imperviousness of the parking lot can be specified as 100% (i.e. totally), or 90% (i.e. partially)
restrict the rate of infiltration. This is described in the materials file in Section 7.3.6 .

If using TUFLOW HPC’s SGS functionality (Section 7.4.3 ), cells can be considered “partially
wet”. This necessitated options for factoring down the rate of infiltration into the topmost
groundwater layer, the methods are discussed in Section 7.4.3.1.2 .

@843
7.3.7.1.1 Green-Ampt (GA)

The Green-Ampt approach varies the rate of infiltration over time based on the soil’s hydraulic
conductivity, suction, porosity and initial moisture content. The method assumes that as water
begins to infiltrate into the soil, a line develops differentiating between the “dry” soil (with moisture
content θi ) and the “wet” soil (with moisture content equal to the porosity of the soil η). As the
infiltrated water continues to move through the soil profile in a vertical direction, the soil moisture
changes instantly from the initial content to a saturated state. This concept is presented in Figure
7.12 .

@845

Section 7 2D Domains - 47 / 116 Page 296 / 1094

 Figure 7.12: Green-Ampt Model Concept2
@846
The basic form of the Green-Ampt equation is expressed as follows:

@847 Δθ (φ + h0 )
f (t) = K (1 + ) (7.7)
F (t)

Where:

t = time
K = saturated hydraulic conductivity
Δθ = defined as the soil capacity (the difference between the saturated and initial moisture
content)
φ = soil suction head
h0 = depth of ponded water
F (t) = cumulative infiltration calculated from:

F (t)
F (t) − Δθ (φ + h0 ) ln(1 + ) = Kt
Δθ (φ + h0 )

The TUFLOW Wiki provides a detail description of the various Green-Ampt parameters, including
how each influences the soil infiltration behaviour.

United States Department of Agriculture (USDA) soil types have been hardwired into TUFLOW
and are presented in Table 7.12 , along with the soil parameters. Alternatively, it is possible to
define a customised soil type by specifying user defined values as shown in Table 7.13 .

Section 7 2D Domains - 48 / 116 Page 297 / 1094

 @856 Table 7.12: USDA Soil types for the Green-Ampt Infiltration Method

USDA Hydraulic Hydraulic

Suction Suction Porosity
Soil Conductivity Conductivity
(mm) (inches) (Fraction)
Type (mm/hr) (in/hr)

Clay 316.3 12.453 0.3 0.012 0.385

Silty
292.2 11.504 0.5 0.020 0.423
Clay

Sandy
239.0 9.409 0.6 0.024 0.321
Clay

Clay
208.8 8.220 1.0 0.039 0.309
Loam

Silty
Clay 273.0 10.748 1.0 0.039 0.432
Loam

Sandy
Clay 218.5 8.602 1.5 0.059 0.330
Loam

Silt
166.8 6.567 3.4 0.134 0.486
Loam

Loam 88.9 3.500 7.6 0.299 0.434

Sandy
110.1 4.335 10.9 0.429 0.412
Loam

Loamy
61.3 2.413 29.9 1.177 0.401
Sand

Sand 49.5 1.949 117.8 4.638 0.417

The 2023-03 release introduces a slight change to the soil moisture initialisation which impacts the
computation of the Green-Ampt infiltration rate. In previous TUFLOW releases, the initial moisture
was used to revise the soil porosity downwards, and the cumulative infiltration was initialised to
zero. In the 2023-03 release the soil porosity is not modified, and the cumulative infiltration is
initialised as the lesser of the initial moisture fraction and the soil porosity, times the thickness of
the layer. These two approaches produce slightly different results for the infiltration rate with the
Green-Ampt method. The new approach is perhaps more logical, and was necessary for the
purpose of initialising to a groundwater table. If the previous approach is required, and the model
has only one soil layer and no horizontal advection, then it can be selected by using the
Defaults == Pre 2023 command.

@857
7.3.7.1.2 Horton (HO)

The Horton approach to infiltration uses the following equation:

−kt
@858 f = f
c
+ (f0 − fc ) e (7.8)

Where:

Section 7 2D Domains - 49 / 116 Page 298 / 1094

 f0 is the initial infiltration rate in mm/hr or inches/hr (if using Units == US Customary)
fc is the final (indefinite) infiltration rate
t is time in hours (period of time that the cell is wet)
k is the Horton decay rate.

If an initial loss (IL) is specified, the initial loss is applied first, followed by the Horton infiltration.
Figure 7.13 shows an example of how the infiltration rate varies over time for f0 equal to 3, fc

equal to 1 and k equal to 0.1.

@867

Figure 7.13: Example of Horton Infiltration Rate over Time

@868
7.3.7.1.3 Initial Loss/Continuing Loss (ILCL)

The Initial Loss/Continuing Loss (IL/CL) method is a more simplistic approach compared to the
Green-Ampt and Horton infiltration methods. The IL/CL method infiltrates water based on an initial
volume (at any rate) then transitions to a constant rate after the initial loss volume is exceeded.

Note that the IL/CL infiltration is separate to the IL/CL materials values used to generate
excess rainfall for direct rainfall simulations (refer to Section 7.3.6.4 for further
information).

@869
7.3.7.2 Soils File (.tsoilf)

Soils infiltration is applied to the model by defining a soils (.tsoilf) file, which is read into the .tcf
using the Read Soils File command. Table 7.13 presents the parameters of the .tsoilf file and
Figure 7.14 shows an example of a completed file. A number of example models demonstrating
the various soil options are available on the TUFLOW Wiki - Soil Options. The soils (.tsoilf) file is
similar to the materials file where you assign a positive integer ID to each soil, define the
infiltration method (options are “NONE”, “GA”, “HO” and “ILCL”) followed by the soil parameters as
the remaining values. The Porosity (saturated moisture content), Initial Moisture (fraction of the
soil that is initially wet), Max Ponding Depth and Horizontal Hydraulic Conductivity are all optional
with default values of 1.0, 0.0, 0.0 and 0.0 respectively.

Section 7 2D Domains - 50 / 116 Page 299 / 1094

 Note: Table 7.13 does not include the additional attributes in regards to horizontal
advection or the two addiitonal soil types available if using TUFLOW HPC (SCS and
convection). For these attributes, refer to Table 7.21 instead.

@870 Table 7.13: Soil File (.tsoilf) Parameters

Column No Green- Green- Initial/Continuing

Horton
No. Intriltration Ampt Ampt Loss

1 Soil ID Soil ID Soil ID Soil ID Soil ID

2 NONE GA GA HO ILCL

USDA Soil
Initial Loss
Type (see Suction (mm Initial Loss (mm or
(mm or
3 Table 7.12 or inches) inches)
inches)
) (mandatory) (mandatory)
(mandatory)
(mandatory)

Hydraulic Initial Loss

Initial
Conductivity Rate (f0 ) Continuing Loss
Moisture
4 (mm/h or (mm/h or (mm/h or in/h)
(Fraction)
in/h) in/h) (mandatory)
(optional)
(mandatory) (mandatory)

Final Loss
Max
Porosity Rate (fc )
Ponding Porosity (Fraction)
5 (Fraction) (mm/h or
Depth (m or (optional)
(mandatory) in/h)
ft) (optional)
(mandatory)

Initial Exponential
Initial Moisture
Moisture Decay Rate
6 (Fraction)
(Fraction) (k) (h-1 )
(optional)
(optional) (mandatory)

Max
Porosity
Ponding
7 (Fraction)
Depth (m or
(optional)
ft) (optional)

Initial
Moisture
8
(Fraction)
(optional)

Note for the Green-Ampt method:

the initial moisture and porosity values in Table 7.13 above are fractions. The soil capacity is
defined as the difference between the saturated moisture content (porosity) and the initial
moisture content, hence the initial moisture should not exceed the porosity otherwise the soil
capacity is set to zero and no infiltration will occur for that soil type. A WARNING 2508 is
issued if this occurs.

Section 7 2D Domains - 51 / 116 Page 300 / 1094

 the max ponding depth value is an optional value that can be used, if desired, to set a limit for
the depth of ponded water (h0 ) value used in the Green-Ampt equation (7.7) . The minimum
of the water depth and the max ponding depth value is used as the h0 value. The default max
ponding depth value is 0, to be consistent with the basic form of the Green-Ampt equation, as
hydrology models do not necessarily have a depth calculated at cells.

@875

Figure 7.14: Example Soils .tsoilf File Format

One or more soils need to be specified globally and/or via GIS layers/raster grids to activate the
infiltration feature. The first attribute of the GIS layer/s must be the Soil ID referenced within the
.tsoilf file, in the same way that a 2d_mat layer references a Material ID stored within the materials
.tmf or .csv file.

@876 Table 7.14: 2D Soil (2d_soil) GIS Attribute Descriptions

Default GIS Attribute

No. Description Type
Name

The soil ID value referenced within a Soils File

1 Soil Integer
(see Table 7.13 ).

Each soil type can have a different infiltration method and infiltration parameters assigned to it,
including a no infiltration option, as shown in Table 7.13 . Other parameters that can optionally be
set are:

The imperviousness of the surface (see Fraction Impervious parameter within the materials
definition in Table 7.11 or Table 7.10 ); and
Groundwater or impervious level beneath the ground surface (refer to Section 8.9.2 ).

The current limit to the number of soils types is 1,000 for TUFLOW classic simulations and 255 for
TUFLOW HPC simulations.

Section 7 2D Domains - 52 / 116 Page 301 / 1094

 @877
7.3.8 Hydraulic Structures

@878
7.3.8.1 Introduction

Bridges, box culverts and other structures that constrict flow can be modelled in 2D directly, rather
than using 1D elements, provided the flow width of the structure is of a similar or larger size than
the 2D cell size. Cells are modified in their height (invert and obvert) and width. For bridges,
additional losses associated with piers and flow reaching the underside of the deck are specified.
For box culverts, the additional resistance for vertical walls is specified. Additional form losses
(energy head losses) can be specified for all flow constrictions.

Weir flow (across levees and other embankments) is modelled in 2D domains by default, this is
handled differently between TUFLOW Classic and TUFLOW HPC. Refer to Sections 7.5.2 and
7.4.4 respectively.

Modelling hydraulic structures in 2D domains must be carried out with a good understanding of the
limitations of different approaches and the different flow regimes possible. The modeller must
understand why and where the energy losses occur when assigning form losses to a 2D cell or
contraction and expansion losses to a 1D element (Syme, 2001b ).

It is important to note that contraction and expansion losses associated with structures are
modelled differently in 1D and 2D schemes. 1D schemes rely on applying form loss coefficients,
as they cannot simulate the horizontal or vertical changes in velocity direction and speed. 2D
schemes model these horizontal changes and, therefore, do not require the introduction of form
losses to the same extent as that required for 1D schemes. 2D schemes still however require the
introduction of additional form losses since they do not model losses in the vertical or fine-scale
horizontal effects (such as around a bridge pier). See Syme (2001b ) for further details.

The following webinars by Bill Syme and Greg Collecutt (two TUFLOW Developers) discuss the
theory behind the energy losses and affluxes modelling associated with hydraulic structures.

Modelling Energy Losses at Structures

1D, 2D & 3D Hydraulic Modelling of Bridges

Additionally, the 2D Hydralic Structures Wiki Page contains information regarding 2D hydraulic
structures, including theory, setup and Frequently Asked Questions (FAQs).

It is recommended that the losses through a structure be validated through:

Calibration to recorded information (if available).

Cross-checked using desktop calculations based on theory and/or standard publications
(e.g. “Hydraulics of Bridge Waterways” (Bradley, 1978 ) or “Guide to Bridge Technology Part
8, Hydraulic Design of Waterway Structures” (Austroads, 2018 ).
Crosschecked with results using other hydraulic software.

To validate structure flows and energy losses:

Specify time-series output (PO) lines of flow (Q_) and flow area (QA) across the structure
(see Section 11.3.2 ). Upstream and downstream water levels may also be specified using
PO points or extracted from the map (e.g. XMDF) output.
Using the upstream and downstream water levels, determine whether flow is upstream or
downstream controlled and estimate the flow using theoretical equations or other methods.

Section 7 2D Domains - 53 / 116 Page 302 / 1094

 Using publications such as “Hydraulics of Bridge Waterways” (Bradley, 1978 ) or “Guide to
Bridge Technology Part 8, Hydraulic Design of Waterway Structures” (Austroads, 2018 ),
determine the energy loss coefficient and compare this with the total energy loss calculated in
the model. The total energy loss is given below. Clearly, any energy losses associated with
bed resistance (e.g. Manning’s equation) need to be allowed for by subtracting this term from
the calculated head difference (h
1
− h2 ) .

2g
ζtotal = (h − h2 )
1 2
V

Where:
ζtotal = total energy loss
h1 = upstream head
h2 = downstream head
Q_
V = depth and width averaged velocity (i.e. QA
)

Table 7.15 lists the recommended approaches for modelling 1D and 2D structures using
TUFLOW. This is discussed further in the following paragraphs.

@886 Table 7.15: Hydraulic Structure Modelling Approaches

Structure 1D Approach 2D Approach

Box Culvert
OK OK
(For culverts with a steep slope, use a 1D element)

Circular Culvert OK N/A

Bridge OK OK

Weirs OK OK

1D Approach

1D structures are discussed in Section 5.8 . 1D modelling is the preferred approach where the
total structure width is less than one or two 2D cells. Entry and/or exit losses are defined for each
structure. Testing has shown that these losses may need to be reduced where the structure width
is significant compared with the cell size (Syme, 2001b ).

1D structures can be linked to the 2D domain using either an SX or HX connection, as outlined in

(see Section 10.2 ). The influence of these connection types on the modelled flow behaviour is
shown in Figure 7.17 .

SX Link: Momentum is not transferred into or out of the 1D element to/from the 2D domain.
“Suppressed” flow patterns in the 2D domain occur at the structure outlet when using 1D
elements, especially if the structure width is significant compared with the cell size. The water
tends to spread, rather than jet out, as there is no inertia across the link. The effect of this is
illustrated in Figure 7.16 , which shows the effect on flow patterns and the preservation of inertia
across 1D/2D links when modelling a structure. Figure 7.16 (red velocity arrows) is that using SX
links, whilst Figure 7.15 (green arrows) is that using a fully 2D solution. As can be seen, using a
SX link the water tends to spread from the structure outlet, as opposed to forming a jet as in the
fully 2D solution which is conserving momentum. When using the SX link, a jet like effect can be

Section 7 2D Domains - 54 / 116 Page 303 / 1094

 created using “wing walls” in the 2D domain at the structure outlet by assigning flood free
elevations to the ZU and ZV Zpts either side of where the 1D element discharges into the 2D
domain.

HX Link: Momentum is not transferred into or out of the 1D element to/from the 2D domain,
however the velocity field across the HX link is assumed to be undisturbed. Provided the HX link is
appropriately located (i.e. perpendicular to the flow field) this produces the effect of preserving
momentum, as illustrated by the dark blue arrows (Figure 7.17 ). Use of HX links at a structure
may require a smaller 1D timestep than that required by a SX link.

2D Approach

2D representation of structures is preferred where the total structure width is greater than one or
two 2D cells. The flow area must be adequately represented by the 2D Zpts and any adjustments
to cell widths (see Section 7.3.8.3 and 7.3.8.2 . The head drop across the structure during
different flow regimes should be validated against other methods and/or literature. Some
additional form losses are normally required to achieve correct head drop (see Syme (2001b )).
Momentum is transferred through the structure as shown in the top image (green arrows) in Figure
7.15 , providing more realistic flow patterns than using a 1D element with a SX link, as illustrated
by the middle image (red arrows) in Figure 7.16 .

@887

Figure 7.15: Flow patterns using 2D FC cells (i.e. a fully 2D solution)

@888

Figure 7.16: Flow patterns using a 1D element connected to 2D SX links

@889

Section 7 2D Domains - 55 / 116 Page 304 / 1094

 Figure 7.17: Flow patterns using a 1D element connected to 2D HX links

@890
7.3.8.2 2D Bridge Structures (2d_bg)

Modelling bridge structures in the 2D domain is possible using the BG Shape input layer (2d_bg).
The 2d_bg layer facilitates the modelling of bridge structures based on research on energy losses
(Collecutt et al., 2022 ). This method is similar to the Layered Flow Constrictions (described
below in Section 7.3.8.3 ), however, some key updates have been made. The layers in a 2d_bg
are called the “pier layer” and the “super structure layer”, which consists of the “deck layer” and
the “rail layer”.

Bridges can be defined as either a line or polygon GIS feature using the .tgc command Read GIS
BG Shape . The layer attribute description is provided in Figure 7.18 and Table 7.16 .

Points can be used to spatially vary the bridge soffit, deck depth and rail depth, with the BG Shape
points input layer (2d_bg_pts). The layer attribute description is provided in Table 7.17 . This can
be used to model an arch bridge or sloping deck. The point objects can be placed in a separate
layer to the line or polygon GIS features.

The 2d_bg layer adjusts the FLC value in the vertical as follows:

ySuperS (ypier + ySuperS )

ζtotal = (ζpier + ζSuperS )
DI P ytotal

Where:

ζpier = FLC of the pier layer.

ζSuperS = FLC to the superstructure layer.
ySuperS = depth of water in the superstructure layer (cannot exceed
DI P ).
DI P = depth to the inflection point from the bridge soffit.
ypier = depth of water in the pier layer (cannot exceed
Dpier ).
Dpier = depth of the pier layer, i.e. from the bed elevation to the bridge soffit.
ζtotal = overall form loss coefficient applied

The vertical distribution of the form loss coefficient has the following characteristics:

Water level below the deck layer: The same result as the 2d_lfcsh approaches, i.e. a constant
form loss based on that specified for the pier layer (ζpier ) is applied.
Water level between the deck soffit and the inflection point: The FLC value is linearly
increased from ζpier to ζpier + ζSuperS . The observations from the CFD and the field

Section 7 2D Domains - 56 / 116 Page 305 / 1094

 measurement indicate the inflection point is located around 1.6 times the bridge deck depth
above the bridge soffit. The “Inflection Depth” (DI P ) is assumed as:

DI P = I P f (Ddeck ϕDeck + DRail ϕRail )

SuperS

Where:
IP f
SuperS
= A factor to set the elevation of the inflection point (IP).
Ddeck = depth of the bridg deck layer.
ϕDeck = blockage of the deck layer.
DRail = depth of the rail layer.
ϕRail = blockage of the rail layer.
Note that the effect of partial blockage at the rail layer is considered by adding the rail layer
depth (DRail ) to the inflection depth proportionally based on the rail layer blockage (ϕDeck ).
Above the inflection point the FLC gradually reduces with increasing depth (in a similar
manner to the 2D Layered Flow Constrictions METHOD B and METHOD C approaches). This
is to simulate the transition to drowned flow and tendency to zero energy losses with
increasing depth over the bridge deck.

@913

Figure 7.18: 2D BG Shape Attributes and Vertical Distribution of Form Loss Coefficient

The 2023-03-AD build implemented three extra approaches to adjust the FLC value between in
the deck soffit and the inflection point:

BG FLC Default Approach == {LINEAR} | LINEAR-CONSTANT | PARABOLIC |

INVERTED-PARABOLIC

LINEAR: the default option introduced above. The depth averaged FLC value is linearly
increased from the bottom of the bridge deck to the inflection point. After the inflection point it
gradually reduces.
LINEAR-CONSTANT: the depth averaged FLC is linearly increased from the bottom of the
bridge deck to the top of the bridge deck. Between the top of the bridge deck and the
inflection point, the FLC is kept constant. After the inflection point it gradually reduces.
PARABOLIC: the depth averaged FLC is increased using a parabolic function from the bottom
of the bridge deck to the inflection point. After the inflection point it gradually reduces.

Section 7 2D Domains - 57 / 116 Page 306 / 1094

 INVERTED-PARABOLIC: the depth averaged FLC is increased using an inverted parabolic
function from the bottom of the bridge deck to the inflection point. After the inflection point it
gradually reduces.

This approach can be changed for individual BG structure using the Options attribute (see Table
7.16 ). The vertical profiles of the depth averaged FLC values applied by the four methods are
illustrated in the figure below:

@914 @915 @923

5

0
0 0.2 0.4 0.6

Figure 7.19: Depth Averaged FLC Applied Using Four Adjustment Approaches

Other key features of the BG layer that are different from the Layered Flow Constriction are:

The BG layer does not apply geometry updates. This not only offers simplicity, but also is a
desirable option considering that the size of TIN polygons used to modify the bridge bed
elevations are often different from the size of polygon used to select BG cell faces.
For a line layer a “Deck_Width” value of zero sets the layer as a thin line. It selects one row of
faces in the direction of flow, and the FLC value is applied to the faces unchanged. A
“Deck_Width” value larger than zero sets the layer as a thick line that selects a whole cell,
i.e. two faces in the direction of flow. The FLC values at the faces are divided by two. The
wide line feature is not supported by the BG layer. BG polygon shapes are recommended if
more than 3 rows of faces must be selected.
For a polygon layer, the “Deck_Width” defines the bridge width in the predominant direction of
flow. This value is used to distribute the total FLC value to the selected faces, i.e.:

ζf ace = ζtotal × Deck_W idth × CellSize

This means users no longer need to convert the FLC value to “form loss per metre”, which is
required by the Layered Flow Constrictions polygons.

The overall blockage of the face is calculated using the same method as the Layered Flow
Constriction:

(y ϕpier + ydeck ϕdeck + yrail ϕrail )

pier
ϕtotal =
ytotal

Section 7 2D Domains - 58 / 116 Page 307 / 1094

 Where:
LINEAR
ϕn = layer n blockage. LINEAR-CONSTANT
yn
PARABOLIC
= layer n water depth (set to zero if dry and cannot exceed depth of layer).
INVERTED-PARABOLIC
ϕtotal = overall cell face blockage applied.

The FLC value applies an energy loss across 2D cell faces as:

2
V
Δh = ζtotal

Depth
2g

where V is the 2D cell face velocity in the presence of the blockage. When setting the blockage
values, considerations need to be taken into account whether the source of the FLC value is
based on the approach velocity (the velocity in the absence of piers blockage) or structure velocity
(the velocity with area blocked out by the piers). For example, Hydraulics of Bridge Waterways
(Bradley, 1978 ) or Guide to Bridge Technology (Austroads, 2018 ) derives FLC value based on
the cross-sectional averaged velocity in the absence of piers, and thus it is recommended to set
the Layer 1 blockage value as zero (0). For more information, please see the 2D Hydraulic
Structures TUFLOW Wiki page.
Depth Averaged FLC

Section 7 2D Domains - 59 / 116 Page 308 / 1094

 @931 Table 7.16: 2D Bridge Shape (2d_bg) Attribute Descriptions

Default GIS
No. Description Type
Attribute Name

Unique identifier up to 32 characters in length. It

may contain any character except for quotes and
1 ID commas, and cannot be blank. As a general rule, Char(32)
spaces and special characters (e.g. “\”) should be
avoided, although they are accepted.

This attribute can be used to overwrite the global

setting specified with the .tcf command BG FLC
2 Options Char(32)
Default Approach to change FLC calulation method
individually.

The percentage blockage of the pier Layer. For

example, enter ‘5’ for a blockage of 5%.

Note: there is no need to apply a blockage value if

3 Pier_pBlockage the FLC is estimated based on the approach Float

velocity (the velocity in the absence of piers). For

more discussion, please see the TUFLOW Wiki
page on the 2D Hydraulic Structures.

4 Pier_FLC Pier layer form loss coefficient. Float

5 Deck_Soffit The elevation of the bridge soffit (m or ft). Float

6 Deck_Depth The thickness of the bridge deck (m or ft). Float

Line:

If equal to zero, sets the layer as a thin line and

selects one row of faces in the direction of flow. The
FLC value is applied to the faces unchanged. If
larger than zero, sets the layer as a thick line that
selects a whole cell, i.e. two faces in the direction of
7 Deck_Width flow. The FLC values at the faces are divided by Float

two.

Polygon:

Defines the bridge width in the predominant

direction of flow (m or ft). This value is used to
distribute the total FLC value to the selected faces.

The percentage blockage of the deck layer. Enter

8 Deck_pBlockage Float
‘100’ for a solid bridge deck obstruction.

9 Rail_Depth The depth of the rail layer (m or ft). Float

10 Rail_pBlockage The percentage blockage of the rail layer. Float

Section 7 2D Domains - 60 / 116 Page 309 / 1094

 Default GIS
No. Description Type
Attribute Name

A postiive SuperS_FLC specifes the combined form

loss coefficient for the deck and the rail layers. Two
layers are treated as a single “superstructure” layer
in this new bridge method.

If the SuperS_FLC attribute is left blank, and Blank

BG FLC Approach is set to Method A or B,
superstructure FLC is generated automatically. See
11 SuperS_FLC Float
Section 7.3.8.2.1 .

If a negative SuperS_FLC value is specified, the

absolute value of SuperS_FLC is taken as a
calibration factor, and is applied as a multiplier to
the automatically generated superstructure FLC. If
the SuperS_FLC attribute is blank, a multiplier of
one is used.

A factor to set the elevation of the inflection point

12 SuperS_Ipf (IP) at which the transition from pressure flow to Char(64)
drowned flow commences. The default value is 1.6.

@932 Table 7.17: 2D Bridge Shape Points (2d_bg_pts) Attribute Descriptions

No. Default GIS Attribute Name Description Type

1 Deck_Soffit The elevation of the bridge soffit (m or ft). Float

2 Deck_Depth The thickness of the bridge deck (m or ft). Float

3 Rail_Depth The depth of the rail layer (m or ft). Float

4 R1 Reserved for future use. Float

5 R2 Reserved for future use. Float

6 R3 Reserved for future use. Float

@933
7.3.8.2.1 Automatic Generation of Superstructure FLC

The 2023-03-AD build implemented a feature to automatically generate the superstructure FLC
value based on the CFD benchmarking study (Collecutt et al., 2022 ) if the SuperS_FLC attribute
is left blank and Blank BG FLC Approach is set to Method A or B.

Blank BG FLC Approach == {NONE} | METHOD A | METHOD B

NONE: The default approach, i.e. the superstructure FLC must be specified manually.
METHOD A: The blank superstructure FLC values will be calculated based on the ratio of the
depth of the pier layer (DP ier in the equations above) and the thickness of the super structure
layer:

TSuperS = DDeck Blockage + DRail Blockage

Deck Rail

Section 7 2D Domains - 61 / 116 Page 310 / 1094

 METHOD B: The blank superstructure FLC values will be calculated based on the ratio of the
depth of the pier layer (DP ier ) and the thickness of the deck layer:

TSuperS = DDeck Blockage

Deck

With Method A and B, the superstructure FLC value is linearly interpolated within the DP ier /
TSuperS range of 1~10 and capped at 0.6 and 0.16 outside this range, as shown in the Figure 7.20
.

If a negative SuperS_FLC value is specified, the absolute value of SuperS_FLC is taken as a

calibration factor, and is applied as a multiplier to the automatically generated superstructure FLC.
If the SuperS_FLC attribute is blank, a multiplier of one is used.

@940 @941 @948

0.7

0.6

0.5

0.4

0.3

0.2

0.1

0
0 5 10

Figure 7.20: CFD benchmarking study of FLC vs /

DP ier TSuperS ratio (hB /T in the original
paper)

@953
7.3.8.3 Layered Flow Constrictions (2d_lfcsh Layers)

Layered flow constrictions allow losses and blockages to be varied with water depth. This provides
the opportunity to model the flow under and over a bridge deck, or a pipeline crossing a waterway.

Note: The 2023-03-AA release introduced the 2d_bg layer, see 2D Bridge Structures . It is
recommended that it be used for representation of bridges. Prior to this, bridges were
commonly modelled using a 2d_lfcsh.

Four vertical layers within a layered flow constriction (not GIS layers) are represented. The lower
three layers each have their own attributes. Each layer is assigned its own percentage blockage
and form loss coefficient. The top (fourth) layer assumes the flow in Layer 4 is unimpeded. Within
the same shape, the invert of the bed, and thickness of each layer can vary in 3D.

For example, the layers of a bridge structure could be defined as follows.

Layer 1: Beneath the bridge deck. Might be 5% blocked due to the bridge piers and have a
small form loss for the energy losses associated with the piers.

Section 7 2D Domains - 62 / 116 Page 311 / 1094

 Layer 2: The bridge deck. This would be 100% blocked and the form loss coefficient would
increase due to the additional energy losses associated with flow surcharging the deck.
Layer 3: The bridge rails. These might be anything from 100% blocked (solid concrete rails)
to 10% blocked (very open rails). Some form losses would be specified depending on the type
of rails.
Layer 4: Flow over the top of the rails - flow is assumed to be unimpeded.

Layered flow constrictions function by adjusting the flow width of the 2D cell so as to represent the
combination of blockages of the four layers. When the flow is only within Layer 1, only the

FLC
attributes of Layer 1 are applied. As the water level rises into Layer 2, the influence of the Layer 2
attributes increase as the water continues to rise. Similarly, for Layer 3 and Layer 4.

The cell side flow width is calculated by summing the flow areas of each layer (including the
effects of layer blockages) and dividing by the water depth.

As of the 2020-10 release three options are available to specify the method in which form losses
are applied:

METHOD A (CUMULATE in releases prior to 2020-10): Accumulates losses through each of

D​Pier​/increases.
the layers in the 2d_lfcsh as the depth of water T​SuperS​

METHOD B (PORTION in releases prior to 2020-10) – the default: Proportions the losses
through each of the layers in the 2d_lfcsh based on the depth of water.
METHOD C: Combines the METHOD A and METHOD B approaches by utilising METHOD A
through to the top of Layer 3 and METHOD B above Layer 3.

The following .tcf command can be used to set the default method to be applied to all structures in
the model:

Layered FLC Default Approach == [ METHOD A | {METHOD B} | METHOD C ]

To specify the method on a structure by structure basis, populate the Shape_Options attribute
(refer to Table 7.18 ) with either “Method A”, “Method B” (the default) or “Method C”.

Whilst the default approach of using METHOD B is unchanged for backward compatibility
purposes, it is recommended the new approaches of METHOD C or the TUFLOW HPC’s 2d_bg
layer approach be considered as they are shown to emulate behaviour from CFD modelling more
closely for pressurised flow conditions (Collecutt et al., 2022 ).

Detailed explanation outlining how the losses are applied is provided in the following sections.

METHOD A

If the form loss method has been set to METHOD A (CUMULATE), the losses are accumulated as
the water level rises through the layers according to the following equation. This approach was
replaced as the default setting for the 2016-03 release due to it producing inconsistent results
where the bridge is substantially overtopped (drowned out) with a large percentage of the flow
occurring through Layer 4, and the overall energy loss reducing with increasing water depth once
the structure is submerged.

y2 y3
ζtotal = ζ1 + ζ2 + ζ3
D2 D3

Where:

ζn = layer n FLC

Section 7 2D Domains - 63 / 116 Page 312 / 1094

 Dn = depth of layer n
yn = layer n water depth (set to zero if dry and cannot exceed depth of layer)
ζtotal = overall form loss coefficient applied

METHOD B

If the form loss method has been set to METHOD B (PORTION), the losses are applied pro-rata
according to the depth of water in each layer using the equation below. Note that Layer 4
(e.g. above the bridge deck rails) is always assumed to contribute a zero FLC. If a layer is not
flooded the depth for that layer, yn, is set to zero.

(y ζ1 + y2 ζ2 + y3 ζ3 )
1
ζtotal =
ytotal

ytotal = y1 + y2 + y3 + y4

Where:

ζn = layer n FLC
yn = layer n water depth (set to zero if dry and cannot exceed depth of layer)
ζtotal = overall form loss coefficient applied

METHOD C

METHOD C effectively combines the METHOD A (CUMULATE) and METHOD B (PORTION)

approaches by utilising METHOD A through to the top of Layer 3 and METHOD B above Layer 3.
METHOD C adjusts the FLC value in the vertical as follows.

Water level below Layer 2: The same result as for all other approaches (i.e. a form loss based
on that specified for Layer 1 is applied). This is typically used for the energy losses associated
with bridge piers.
Water level below top of Layer 3: Same approach as for METHOD A.
Water level above Layer 3: Gradually reduces the energy loss with increasing depth by
proportioning with depth. The energy loss is calculated as that accumulated from Layers 1 to
3 pro-rated by the depth of Layers 1 to 3, plus no losses pro-rated by the depth above the
Layer 3.

y2 y3 (y + y2 + y3 )
1
ζtotal = (ζ1 + ζ2 + ζ3 )
D2 D3 ytotal

ytotal = y1 + y2 + y3 + y4

Where:
ζn = layer n FLC
yn = layer n water depth (set to zero if dry and cannot exceed depth of layer)
ζtotal = overall form loss coefficient applied
Dn = layer n thickness

Regardless of the FLC approach, the FLC value applies an energy loss across 2D cell faces as:

2
V
Δh = ζtotal
2g

Section 7 2D Domains - 64 / 116 Page 313 / 1094

 where V is the 2D cell face velocity in the presence of the blockage. When setting the blockage
values, considerations need to be taken into account whether the source of the FLC value is
based on the approach velocity (the velocity in the absence of piers blockage) or structure velocity
(the velocity with area blocked out by the piers). For example, Hydraulics of Bridge Waterways
(Bradley, 1978 ) or Guide to Bridge Technology (Austroads, 2018 ) derives FLC values based on
the cross-sectional averaged velocity in the absence of piers, and thus it is recommended to set
the Layer 1 blockage value as zero (0). For more information, please see the 2D Hydraulic
Structures TUFLOW Wiki page.

Layered FC shapes are defined as either a line or polygon GIS objects using the .tgc command
Read GIS Layered FC Shape . The file attribute description is provided in Table 7.18 .

Points can be used to vary the invert of the bed, and thickness of each layer in 3D. In this case,
four attributes are required as outlined in Table 7.19 . This can for example be used to model an
arched bridge or sloping deck. The point objects can be placed in a separate layer to the line or
polygon GIS features.

Please note, overlapping flow constriction inputs is not supported.

Section 7 2D Domains - 65 / 116 Page 314 / 1094

 @971 Table 7.18: Layered Flow Constriction Shape (2d_lfcsh) Attribute Descriptions

Default GIS Attribute

No. Description Type
Name

Performs same function as described for the Z

attribute in Table 7.5 and is applied to the
Invert elevation values. To leave the Zpt levels
unchanged (i.e. use the existing Zpt
elevations), enter a value of 99999.

Point or Line:
Invert of constriction (m above datum).
1 Invert Float
Polygon: Used to set the elevation of the
polygon perimeter only if NO MERGE option is
specified and there are no points snapped to
the perimeter. Otherwise ignored and the Zpt
elevations within the polygon will be adjusted
by triangulated around the perimeter at every
half-cell size.

Performs same function as described for dZ in

2 dZ Table 7.5 and is applied to the Invert Float
elevation values.

3 Shape_Width_or_dMax Same as for the same attribute in Table 7.5 . Float

Section 7 2D Domains - 66 / 116 Page 315 / 1094

 Default GIS Attribute
No. Description Type
Name

4 Shape_Options Point: Not used. Char(20)

Line or Polygon:

ADD: Add the shape’s ‘Z’ attribute value to the

current Zpts. If ADD is specified, any automatic
merging around the region perimeter is
ignored.

MAX, RIDGE or RAISE: Only changes a Zpt

(Invert) elevation if the Z Shape elevation at
the Zpt is higher.

MIN, GULLY or LOWER: Only changes a Zpt

(Invert) elevation if the Z Shape elevation at
the Zpt is lower.

METHOD A (CUMULATE in releases prior to

2020-10): Accumulates losses through each of
the layers in the 2d_lfcsh as the depth of water
increases. This will overwrite the global setting
specified with the .tcf command Layered FLC
Default Approach.

METHOD B (PORTION in releases prior to

2020-10): Proportions the losses through each
of the layers in the 2d_lfcsh based on the
depth of water. This will overwrite the global
setting specified with the .tcf command
Layered FLC Default Approach.

METHOD C: Combines the METHOD A and

METHOD B approaches by utilising METHOD
A through to the top of Layer 3 and METHOD
B above Layer 3. This will overwrite the global
setting specified with the .tcf command
Layered FLC Default Approach.

Line:

NO MERGE: For thin lines

(Shape_Width_or_dMax = 0), the final
elevations along the line are as specified. If
NO MERGE is not specified for a thin line, the
final elevations are set to be the same as the
current Zpt values plus the dZ value.

TIN: Indicates the line is to only be used for

generation of TINs within polygons (only
sections of TIN lines that fall within polygons

Section 7 2D Domains - 67 / 116 Page 316 / 1094

 Default GIS Attribute
No. Description Type
Name

are used).

Polygon: If none of the options below are

specified, the Invert elevations at perimeter
vertices that do not have an elevation point
snapped to them are merged with the current
Zpt values (provided Invert does not equal
99999).

MERGE ALL: Ignores invert elevations from

any points snapped to the perimeter and
merges all perimeter vertices with the current
Zpt values.

NO MERGE: Does not merge the perimeter

elevations with the current Zpt values.

5 L1_Obvert The obvert (soffit) of Layer 1. Float

The percentage blockage of Layer 1. For

6 L1_pBlockage Float
example, enter 5 for a blockage of 5%.

Section 7 2D Domains - 68 / 116 Page 317 / 1094

 Default GIS Attribute
No. Description Type
Name

Layer 1 form loss coefficient. Used for

modelling fine-scale “micro”
contraction/expansion losses not picked up by
the change in the 2D domain’s velocity
patterns (e.g. bridge pier losses, vena-
contracta losses, 3rd (vertical) dimension etc.).

This parameter should be used as a calibration

parameter.

Note: So that this attribute is independent

of 2D cell size it has different treatment
depending on the object it is attached to as
follows:

Line: For thin lines, the FLC value is

applied to the cell sides unchanged. For
thick (whole cell) lines, the FLC value is
divided by two (two cell sides in the
direction of flow). For wide lines the FLC
value is divided by the number of cells
across the line (i.e. the line’s width divided
by the cell size) and applied to all cell-
7 L1_FLC Float
sides.
Polygon: FLC is the form loss per unit
length (in the predominant direction of
flow). FLC values are not dependent on
the flow width, but are on the length of
travel in the direction of flow. The unit of
length is metres, or feet if using Units
== US Customary.

However, if a negative FLC value is

specified, the absolute value is taken and
applied unadjusted to all cell-sides affected
by the shape.
Note, this is not cell size independent,
therefore if the 2D cell size is changed, this
attribute also needs to be changed.

The form loss coefficient is applied as an

energy loss based on the dynamic head
equation below where ζa is the FLC vlaue.

2
V
Δh = ζa
2g

Section 7 2D Domains - 69 / 116 Page 318 / 1094

 Default GIS Attribute
No. Description Type
Name

The depth of Layer 2. Depth units are in

8 L2_Depth metres, or feet if using Units == US Float
Customary.

The percentage blockage of Layer 2. For

9 L2_pBlockage example, enter 100 for a solid obstruction such Float
as a bridge deck or pipe.

Layer 2 form loss coefficient. See notes for

10 L2_FLC Float
L1_FLC

The depth of Layer 3. Depth units are in

11 L3_Depth metres, or feet if using Units == US Float
Customary.

12 L3_pBlockage The percentage blockage of Layer 3. Float

Layer 3 form loss coefficient. See notes for

13 L3_FLC Float
L1_FLC

Optional field for entering comments. Not

14 Notes Char(40)
used.

@974
Table 7.19: Layered Flow Constriction Shape Point (2d_lfcsh…_pts) Attribute Descriptions

Default GIS
No. Description Type
Attribute Name

Invert of constriction (metres above datum, or feet

above datum if using Units == US Customary).
1 Invert Float
To leave the Zpt levels unchanged (i.e. use the existing
Zpt elevations), enter a value of 99999.

2 L1_Obvert The obvert (soffit) of Layer 1. Float

The depth of Layer 2. Depth units are in metres, or feet

3 L2_Depth Float
if using Units == US Customary.

The depth of Layer 3. Depth units are in metres, or feet

4 L3_Depth Float
if using Units == US Customary.

@975
7.3.9 Cell Modification

@976
7.3.9.1 Storage Reduction (2d_srf)

The storage of 2D cells may be reduced (e.g. to model hypothetical filling, or reduced storage from
buildings), or increased (e.g. for stability). For example, if a cell has a Storage Reduction Factor
(SRF) value of 0.1, then its storage (surface area) is reduced by 10%. If the SRF value is less
than zero, the storage is increased. The default SRF value is zero (i.e. no change in storage).

Section 7 2D Domains - 70 / 116 Page 319 / 1094

 SRF values are assigned to cells in one or both of the following ways:

1. Using the Set SRF and Read GIS SRF .tgc commands. The 2d_srf layer has only one
attribute, a float or real value nominally called SRF.
2. Assigned to materials .csv/.tmf files as the 5th and 10th column values respectively (refer to
Table 7.10 and Table 7.11 ).
3. Using the .tgc command Read Grid SRF to assign SRF values from a raster input grid.
4. Via SX connections to 1D. The default approach increases the storage in the 2D cells by the
average associated 1D node storage. Refer to Section 10.2.2 and .tcf command SX Storage
Approach .
The applied SRF value is reported in the SRF attribute of the _grd_check layer.

Note that a user can apply a combination of material SRF values and Read GIS SRF layers.
The item that is used by the simulation depends on the order of commands in the .tgc file.
The last read input takes precedence. For example, if a cell’s storage is adjusted by layers
read in using both the Read GIS SRF and Read GIS Mat commands, though Read GIS Mat
is lower in the .tgc file, it will prevail.

If a large reduction in cell storage is applied, for stability reasons it may be necessary to also
reduce the cell conveyance using a higher roughness or cell flow width (see Section 7.3.9.2 ).
For example, if a 10m cell size model has a SRF value of 0.99, without any SRF the cell area is
100m2 (10m x 10m), with a SRF of 0.99 this would be reduced to 1m2. If no reduction in
conveyance for flow entering or leaving the cell is made, a significant volume of flow may enter the
cell between timesteps, this would cause the water level in the cell to jump a large amount,
potentially leading to oscillations in water levels.

@977
7.3.9.2 Cell Width Factor (CWF)

The .tgc commands Set CWF , Read GIS CWF and Read Grid CWF can be used to adjust the
2D cell flow widths (in the same manner as for 2D flow constrictions (refer to Section 7.3.8.3 ).
The CWF is a factor, for example 0.1 will limit the flow width to 10%. The changed flow width
applies to all depths. When reading from a polygon object in GIS format, any cell sides that fall
within the polygon will have the width factor applied. These factors can be reviewed within the
uvpt_check file.

@978
7.3.9.3 Form Loss Coefficient (FLC)

Form loss coefficients can be applied in the .tgc to add an additional energy loss at the 2D cell
side (in the same manner as for 2D flow constrictions, see Section 7.3.8.3 and 7.3.8.2 ). Unlike
flow constrictions, the FLC applied using this approach does not vary with depth. The form or
energy loss can be applied as fixed values with the .tgc commands Set FLC , Read GIS FLC
and Read Grid FLC or on a form loss per unit length basis with the .tgc commands Set FLC/L ,
Read GIS FLC/L and Read Grid FLC/L . The advantage to applying the FLC on a per unit length
basis is that it makes these inputs independent of the 2D cell size when using regions (polygons).
As such, if the 2D cell size is changed, the same energy loss will be applied to both models over
the area of the region.

Any cell sides that fall within the polygon will have the additional form loss These loss can be
reviewed within the uvpt_check file.

Section 7.3.8 provides a detailed discussion about the application of additional form losses.

Section 7 2D Domains - 71 / 116 Page 320 / 1094

 @979
7.3.9.4 Modify Conveyance

The. tgc command Read GIS Zpts Modify Conveyance can be used to modify the elevation of a
series of cells based on an increase or decrease in conveyance. Three inputs are required for this
operation. These are:

1. A GIS layer containing a region / polygon object within which the modification will apply;
2. A conveyance multiplication factor; and
3. A water level grid.

The command syntax is:

Read GIS Zpts Modify Conveyance == <gis layer> | <K_factor> |

<Water_Level_Grid>

The terrain levels are adjusted based on the depth of water relative to the water surface provided.
3

The elevations are modified by depth (1 − f 5

) , which is effectively a change in conveyance of

K × f where K is conveyance and f is the multiplication factor. For example, f = 1.2 would be a
20% increase in conveyance resulting in a deepening of the waterway. The specified base water
level grid is a grid surface in a supported input raster format. The grid does not need to be in the
same resolution as the 2D domains, but is typically the _h_Max grid output by TUFLOW from a
previous simulation (see Section 11.2.2.2 ).

This feature is useful for sensitivity testing the changes in flood behaviour due to a deepening or
accretion of a river’s bed based on a change in conveyance.

This command would normally be applied in the .tgc, after all elevation (Zpt) commands as the Zpt
adjustment is based on the Zpt elevations processed up until the location of this command in the
.tgc file. An example is provided below:

Read GIS Zpts Modify Conveyance == gis\2d_mod_river.shp | 0.9 |

base_h_Max.tif

Where:

2d_mod_river.shp contains polygons of the areas to be modified, in this case along the river.
This can be in any supported vector format (.gpkg, .shp or .mif).
0.9 is the factor change in conveyance compared to a base case (i.e. 10% decrease in
conveyance).
base_h_Max.tif is a raster grid of the peak water level grid from a base case simulation. It is
recommended to copy this grid layer from the results folder and place it somewhere under
model\grid\. If this grid layer varies with AEP, it is recommended to use the one .tcf with a
Variable to define the AEP, or alternatively a Scenario variable.

@984
7.3.10 Modelling Urban Areas

The modelling of urbanised floodplains presents many more challenges to hydraulic modellers
than those of rural floodplains. It requires careful consideration of the representation of buildings,
walls and fences to accurately replicate the overland flow routes. With the advancement of
modern computing hardware and software, 2D solutions are increasingly being used over 1D
solutions to represent urban areas.

Section 7 2D Domains - 72 / 116 Page 321 / 1094

 This section of the manual discusses the various methods available in TUFLOW to represent the
features within an urban area. It does not aim to identify the most appropriate method, however,
discusses the pros and cons to provide the modeller with guidance on selecting the most suitable
method for their study.

Syme (2008 ) explores modelling approaches for buildings and fences, it can be found along with
other publications in the TUFLOW Library.

@985
7.3.10.1 Buildings

A number of methods can be used for representing buildings in a TUFLOW 2D model. These are:

Utilising a higher bed resistance (roughness);

Raising the elevation of 2D cells where buildings exist;
Deactivating the 2D cells (code = 0) where buildings exist;
Reducing the cell storage;
Restricting the flow using a cell width reduction or additional form loss; or
Applying a breakline along the upstream faces of buildings.

Utilising a high bed resistance parameter for buildings is a commonly used method to encourage
the development of preferential flow paths around buildings during urban flooding scenarios. This
method is commonly used and preferred over others as it accounts for the storage that the
building provides once it becomes inundated (Syme, 2008 ). Depth varying roughness is
recommended if using this approach in combination with direct rainfall modelling. A low roughness
value is recommended at shallow depths, representing the rapid run-off response associated with
rainfall on building roofs. High bed roughness is recommended for deeper flows when the building
structure impedes overland flow. The application of depth varying roughness is described in
Section 7.3.6 .

Buildings may also be “removed” from the 2D domain by categorising the buildings as “Land” cells
(see Section 7.3.2 ) or raising the Zpt elevations above the predicted flood level (see Section
7.3.5.2 ). This method may be appropriate when the building/s have been designed to not flood.
In this case, care should be taken to ensure the chosen cell size is able to appropriately represent
the area of the building and therefore the storage ‘removed’ from the floodplain. Representing
buildings in this fashion will not take into account any below ground storage, such as that provided
by underground car parks or basement properties. If using a direct rainfall approach (rain on grid),
this method is most likely not suitable. Any land (inactive) cells will have no rainfall applied,
meaning the flow volume will be incorrect, artificially high cells (e.g. 10m above ground levels)
may cause stability issues as flows exit the building.

Flood studies often require the simulation of extreme flood events, where a great number of
buildings are expected to become inundated. It may not be appropriate in these cases to “remove”
the building entirely from the 2D domain. A more suitable approach may be to raise the Zpt
elevations (see Section 7.3.5.2 ) of the building polygons to match the finished floor level,
thereby specifying the elevation at which the building is able to flood. This may allow for direct
rainfall simulations using a modification of the cell elevations.

The use of a thin breakline around the edges of the building can be used to prevent the building
becoming a flow path, whilst not removing the storage volume (see Section 7.3.5.2 ). For
example, three sides of the building could be blocked, this will still allow water to enter the building
but not flow through it.

Section 7 2D Domains - 73 / 116 Page 322 / 1094

 Layered flow constrictions (see Section 7.3.8.3 ) or Cell Width Factor (see Section 7.3.9.2 ) may
be used to impede the flow of water as it passes through the building. The sides of 2D cells may
be partially blocked to represent obstructions such as internal or external walls. Additionally, a
form loss can be applied using form loss coefficients (see Section 7.3.9.3 ).

A storage reduction factor can also be used to reduce the area in the cell available for water using
the SRF options (see Section 7.3.9.1 ). This can be used in conjunction with the other methods,
for example, a building may have the storage reduced by 20% by applying a SRF of 0.2, this could
be combined with a Cell Width Factor of 0.8 (20% reduction in flow area through the building).

In the absence of guidelines in the literature it is recommend that the approaches for modelling
buildings be sensitivity tested or calibrated, if possible.

@986
7.3.10.2 Roads

Roads typically represent the main flow routes through urban areas. The chosen cell size of the
2D domain is a key factor in ensuring an appropriate number of cells have been used to represent
the width of the roads, as previously discussed in Section 3.3.2 . Choosing too coarse a
resolution may result in the roads not being accurately represented and minor flow routes not
being represented at all. An unnecessarily fine resolution may translate to excessively long
simulation times and stability problems if the Courant condition is exceeded. Ideally, it is
recommended that the main flow routes be represented with a width of approximately 3-4 cells
across. Note, when using the TUFLOW HPC SGS functionality (see Section 7.4.3 ) identification
of locations where a breakline should be used to represent a flow control crest may be important.
The SGS Breakline Detection Delta tool (see Section 7.4.3.1.2 ) can assist modellers in
identifying where breaklines may need to be added.

For overland flood studies where a high proportion of sheet flow is predicted, differentiation
between the road and pavement elevations may influence the predicted areas of inundation. A
DTM based on LiDAR or ALS data, may not necessarily pick up this detail, therefore requiring
manual modification of the topography using breaklines.

It is possible to apply the Log Law rule for very shallow flow through automatically varying
Manning’s n. This is of particularly interest for modelling flow over smooth surfaces such as roads
and concrete (see Section 7.3.6.2 ).

@987
7.3.10.3 Fences and Walls

Fences and walls can cause significant blockages during a flood event, influencing the direction
that flood waters take. Walls act to deflect the path of flood waters and if overtopped, may act as
weirs. Fences may partially impede the flow of water and can be prone to becoming blocked with
debris. There is also the potential for both walls and fences to collapse during a flood event.

Fences and walls are typically included within a TUFLOW model by digitising a series of
breaklines. The 2d_zsh GIS layer permits the width of the breakline to be specified (see Section
7.3.5.2 ). A “thin” line modifying only the ZU and ZV (cell side) elevations may be preferred to
represent fences, in situations where the width of the cell size is notably greater than the width of
the obstruction. A “thin” line does not modify the ZC (cell centre) elevations hence has no impact
on the cell storage. A “thick” line on the other hand, modifies the ZU, ZV and ZC Zpt elevations
and may be more appropriate to represent wider obstructions such as railway embankments.

Section 7 2D Domains - 74 / 116 Page 323 / 1094

 The 2d_vzsh GIS layer (see Section 7.3.5.3 ) may be used to represent an embankment that
collapses during the simulation. The breach may be triggered at a specified time, by the water
level at a defined location or the water level difference between two locations exceeding a
specified amount.

@988
7.4 TUFLOW HPC Specific

This section describes 2D domain functionality that is unique to TUFLOW HPC.

@989
7.4.1 Quadtree

Quadtree grid refinement functionality enables the user to vary the 2D cell resolution within a
TUFLOW HPC model. Quadtree refinement allows for recursive division of square TUFLOW cells
into four smaller square cells. Up to 9 levels of cell size refinement are permitted. All cells for all
levels of refinement share a common orientation. Bill Syme, one of the TUFLOW author’s,
discusses the benefits and implementation of Quadtree within the Future of 2D Hydraulic
Modelling AWS Video. The How to Implement Quadtree video also useful. An example quadtree
mesh is presented in Figure 7.21 .

@990

Figure 7.21: TUFLOW HPC Quadtree Grid

The Quadtree solver uses a modified version of the HPC solver. It uses an explicit finite volume
solution that is 2nd order in space and 4th order in time, however there are some subtle
differences between the HPC single grid and Quadtree solvers that mean they produce near
identical, though not identical results if both run are over the same single grid (same cell size) grid
– see Section 3.2.4 for further discussion.

TUFLOW Wiki Tutorial Module 7 provides a demonstration of quadtree. The followings Sections
outline how to use the feature.

Section 7 2D Domains - 75 / 116 Page 324 / 1094

 @991
7.4.1.1 Quadtree .tcf Commands

To use a Quadtree grid, the solution scheme should be set to HPC and a Quadtree Control file
specified using the command Quadtree Control File . GPU Hardware is also recommended. For
example:

If Scenario == HPC
Solution Scheme == HPC
Hardware == GPU
Else If Scenario == Quadtree
Solution Scheme == HPC
Quadtree Control File == ..\model\quadtree_001.qcf
Hardware == GPU
End If

Note, the keyword “Single Level” can be used instead of a control file (e.g. “Quadtree Control
File == Single Level”), to run the Quadtree module as a single 2D domain fixed grid model
(ie. a fixed cell size). A simulation run in this manner will likely run slower than HPC, though may
require a smaller memory footprint. This is due to quadtree only storing a grid of active cells
compared with single fixed grid models that use the bounding rectangle to allocate memory, which
may include large areas of inactive (redundant) cells and therefore consuming memory.

The Quadtree Control File (.qcf) is described in the next section.

@992
7.4.1.2 Quadtree Control File (.qcf) – Mandatory Commands

The Quadtree Control File (.qcf) is used to define the grid refinement areas and optionally the
model location and extent for a Quadtree grid. Appendix H lists and describes the available .qcf
commands.

The following commands are mandatory in a .qcf file.

Model Origin and Extent == AUTO | TGC

If set to “AUTO” the extents of the Level 1 GIS polygon are used to define the model origin and
extents. If set to “TGC”, the model is located as per the commands in the .tgc file. Note, the angle
of the model is defined in the .qcf file using the Orientation Angle command below. Also, if set to
“AUTO” the GIS nesting polygons must have a Level 1 polygon defined, otherwise an ERROR is
generated.

Read GIS Nesting == <gis_file>

The Read GIS Nesting command can be used to define polygons of grid refinement (different
levels) in the 2d_qnl format file, as described in Section 7.4.1.4 .

@993
7.4.1.3 Quadtree Control File (.qcf) – Optional Commands

The following commands are optional in the Quadtree Control File:

Base Cell Size == <cell size in m/ft> | {TGC}

Section 7 2D Domains - 76 / 116 Page 325 / 1094

 Base Cell Size sets the Level 1 (parent) cell size. This will be the largest cell size in the Quadtree
grid. If set to a numerical value this will override the cell size command in the .tgc file. If this
command is not specified or is set to “TGC”, the cell size defined in the .tgc file is used.

Orientation Angle == <angle in degrees> | OPTIMISE | {TGC}

If set to a numerical value this defines the grid orientation angle and overrides any angle / location
.tgc commands. If set to “OPTIMISE” the parent Level 1 polygon is used to optimise the angle of
the grid to minimise the area of the bounding rectangle, thereby minimising temporary memory
requirements during the simulation startup (the memory footprint during the simulation is not
affected). As such the GIS nesting polygon must have a Level 1 polygon defined. If the command
is not specified or is set to “TGC”, the orientation angle in the .tgc is used.

When pre-processing the Quadtree grid, a hidden 2D domain is used for areas of refinement to
allow fast processing of geometry on a regular grid. The default approach is that each nesting
level is treated as a 2D rectangular domain, therefore, for example, with three levels of nesting the
geometry control file is processed three times. To reduce initialisation memory demands it is
possible to treat each GIS polygon in the 2d_qnl layer as a separate domain for the processing of
geometry inputs. This is set using the optional .qcf control file command:

Quadtree Mesh Processing Method == {FAST} | Memory Efficient

This allows changing to a more memory efficient approach to process each polygon in the 2d_qnl
layer. However, whilst being more memory efficient during grid creation, the model startup may be
slower. How the grid is processed has no effect on the speed of the hydraulic computations or the
memory demand during the hydraulic calculations.

@994
7.4.1.4 Defining Grid Refinement Polygons

A 2d_qnl (Quadtree Nesting Level) GIS layer (see Table 7.20 ) is used to define the location and
levels of grid refinement. The 2d_qnl layers should only contain polygon / region objects, with all
other GIS object types (lines, points, etc.) ignored.

The nesting level attribute must be in the range 1 to 9. A value of:

1: indicates that the cell size to be used for that polygon is the Level 1 or base cell size (see
Base Cell Size ).
2: indicates the cell size within the polygon would be at Level 2 (i.e. half the base cell size).
3: indicates the cell size within the polygon would be at Level 3 (i.e. 1/4th of the base cell
size).
4: indicates the cell size within the polygon would be at Level 4 (i.e. 1/8th of the base cell
size).
…
9: so on up to a maximum of Level 9 (1/256th of the base cell size).

There should only be one Level 1 polygon defined in the 2d_qnl layer, but for all other levels there
is no limit on the number of polygons. For numerical precision reasons when running single
precision, the maximum nesting level of 9 or 1/256 of the base cell size has been adopted, but can
be increased for double precision mode should there be a demand from users.

Note, it is not recommended to have Z shape merge polygons (Section 7.3.5.2 ) extending
across multiple quadtree nested layers. If this happens CHECK/WARNING 2934 will be
written.

Section 7 2D Domains - 77 / 116 Page 326 / 1094

 @995 Table 7.20: 2D Quadtree (2d_qnl) Attribute Descriptions

Default GIS
No. Description Type
Attribute Name

The value of the quadtree nested level used for grid

refinement.

The nesting level attribute must be in the range 1 to 9.

For example:

1: indicates that the cell size to be used for that

polygon is the Level 1 or base cell size (see Base
Cell Size .

1 Nest_Level 2: indicates the cell size within the polygon would Integer
be at Level 2 (i.e. half the base cell size).
3: indicates the cell size within the polygon would
be at Level 3 (i.e. 1/4th of the base cell size).
4: indicates the cell size within the polygon would
be at Level 4 (i.e. 1/8th of the base cell size).
…
9: so on up to a maximum of Level 9 (1/256th of
the base cell size).

When refining grid areas, if a refinement polygon sits within a polygon of the next higher level
(e.g. a Level 3 polygon is defined within a Level 2), as per Figure 7.22 , no automatic grid refining
is required.

@996

Figure 7.22: Example of Quadtree Nesting Level Polygons

Section 7 2D Domains - 78 / 116 Page 327 / 1094

 However, if a nesting level polygon does not sit within a polygon of the next higher level (e.g. a
Level 4 polygon is defined within a Level 1 or Level 2 polygon), intermediate areas of refinement
are automatically generated by TUFLOW. For example, Figure 7.23 show the grid generated
when transitioning from a Level 1 to Level 3 and a Level 1 to Level 5.

@997

Figure 7.23: Examples of Automatic Quadtree Refinement

No Level 1 polygon is required if the model origin and extent are defined in the .tgc file. In this
situation the rectangle representing the .tgc computational domain is used as the Level 1 polygon.
For example, if the .qcf file includes the following commands and the only 2d_qnl polygon is
Level 3 (red polygon in Figure 7.26 . The grid created is based on the rectangular computational
domain in the .tgc file (as shown by the thick dashed black line) with inactive cells removed from
the grid to reduce memory.

Base Cell Size == TGC

Model Origin and Extent == TGC
Orientation Angle == TGC
Read GIS Nesting == gis\2d_qnl_999_R.shp

@998

Section 7 2D Domains - 79 / 116 Page 328 / 1094

 Figure 7.24: Example Showing Removal of Inactive Cells

@999
7.4.2 HPC Turbulence

This section contains information relating to sub-grid-scale turbulence options for TUFLOW HPC.

@1000
7.4.2.1 Overview

For TUFLOW HPC, three options exist (Constant, Smagorinsky and Wu) for specifying eddy
viscosity for the 2D domains to approximate the effect of sub-grid-scale turbulence. Collecutt et al.
(2020 ) discusses the turbulence models in respect to model cell size sensitivity, resulting in the
Wu approach (Section 7.4.2.4 ) becoming the default for TUFLOW HPC from the 2020-01
release and onwards. Discussion on the change in defaults is available in the HPC Turbulence
FAQ TUFLOW Wiki Page.

The Viscosity Formulation and Viscosity Coefficient commands are used to set the formulation
and coefficients. Note that these commands may also be used to select the non-Newtonian
module, which is discussed in Section 7.4.6 since it is not a sub-grid turbulence model.

@1001
7.4.2.2 Constant Eddy Viscosity

The Constant approach (Viscosity Formulation == CONSTANT) applies a constant value

throughout the model, irrespective of velocity gradients and variations. This is generally
satisfactory when the bed resistance is dominant or when modelling large ocean basins (in which
case the recommended coefficient for the constant formulation is 1 m2/s), but is not recommended
for riverine flow paths.

@1002
7.4.2.3 Smagorinsky Approach

TUFLOW’s Smagorinsky approach (Viscosity Formulation == SMAGORINSKY) applies a

hybrid method that includes elements of both the Constant and Smagorinsky approaches, as
given by the equation below. This formulation is better than the CONSTANT option, as the eddy

Section 7 2D Domains - 80 / 116 Page 329 / 1094

 viscosity is recalculated every timestep at every cell mid-side according to the change in velocity
magnitude and direction. This results in higher coefficients being applied where there is greater
turbulence.

However, this approach has two known limitations:

1. It assumes that all turbulent kinetic energy with length scales greater than the cell size is
resolved within the velocity field. This assumption is reasonable when the 2D cell size is
larger than the physical depth of the flow, but becomes incorrect when the 2D cell size is
smaller than the depth of the flow – turbulence in the vertical direction contributes significantly
to viscosity but is not resolved in the 2D velocity field. As a result, once the 2D cell size
becomes smaller than the flow depth this approach can underpredict the viscosity, and
therefore can underpredict momentum coupling from river to flood plain.
2. It assumes that the physical length scales of the sub-grid turbulence scale with the 2D cell
size. This is reasonable when the 2D cell size is similar to the depth of the flow, but becomes
incorrect when the 2D cell size becomes significantly larger than the depth of the flow – the
bed resistance and the finite depth of the flow prevent large scale turbulence. As a result,
once the 2D cell size becomes much larger than the depth of the flow, the Smagorinsky
turbulence model can overpredict the viscosity, and therefore can overpredict the momentum
coupling from river to flood plain.

The result of these two limitations, is that model results display some sensitivity to the 2D cell size.
The Wu formulation (Section 7.4.2.4 ) has proven to be more capable in its ability to provide “out
of the box” calibration and reduced sensitivity of model results to 2D cell size.

Note, if the formulation is changed, the user must also reset the coefficient using the command
Viscosity Coefficient .

The Smagorinsky option remains the default when using TUFLOW Classic. The default viscosity
coefficients are a Smagorinsky value of 0.5 plus a constant value of 0.05 m2/s. The 0.5
Smagorinsky coefficient is dimensionless. The viscosity coefficient can be output using the Map
Output Data Types command.

The hybrid Smagorinsky formulation used by TUFLOW is:

@1003 ∂u
2
∂v
2
1 |∂u| |∂v|
2

υ = C c + C s A c √( ) + ( ) + ( + ) (7.9)
∂x ∂y 2 ∂y ∂x

Where:

u and v = Depth averaged velocity components in the X and Y directions

x and y = Distance in the X and Y direction
ν = Horizontal diffusion of momentum (viscosity) coefficient, m2/s or ft2/s
Ac = Area of Cell
C c = Constant Coefficient (default = 0.05 m2/s)
Cs = Smagorinsky Coefficient (dimensionless, default = 0.5)

@1011 Wu Approach
7.4.2.4

The Wu approach (Viscosity Formulation == WU) is the default method for TUFLOW HPC
from release 2020-01 and onwards. It is not available for TUFLOW Classic. This eddy viscosity
(turbulence) model combines both 2D and 3D turbulence effects, and is a slightly adapted version

Section 7 2D Domains - 81 / 116 Page 330 / 1094

 of that described in W. Wu et al. (2005 ).

Like the Smagorinsky eddy viscosity model, it is a zero-equation model whereby the eddy
viscosity coefficient can be diagnostically computed from the mean depth and velocity fields.
However, unlike the Smagorinsky model, where the turbulent length scale is related to cell size,
the length scales used in the Wu model are related to water depth, and hence the computed eddy
viscosity is not related to or dependent on cell size. This has been shown to significantly improve
the cell size convergence of the results compared to the Smagorinsky model (i.e. the results are
nearly independent of the cell size provided there are enough cells across the waterways to
adequately define the flows).

The computed eddy viscosity is the Pythagorean sum of 3D and 2D contributions:

@1012 νT = √ν
2
+ ν
2
(7.10)
3D 2D

∗
υ3D = C3D U Lm

√g
∗
U = |U |n
1

d 6

2
υ2D = C2D Lm |∇U |

2 2 2
∂u ∂v 1 ∂u ∂v
|∇U | = √( ) + ( ) + ( + )
∂x ∂y 2 ∂y ∂x

Where:

νT is the final total 2D viscosity

ν3D is the vertical 3D viscosity contribution
ν2D is the horizontal 2D viscosity contribution
C3D coefficient for 3D viscosity contribution
C2D coefficient for 2D viscosity contribution
τbed
U
∗
is the friction velocity (is √
ρ
)

Lm is the turbulent length scale (is lesser of flow depth or distance to wet/dry boundary)
n is Manning’s bed friction (see note below on treatment of high Manning’s n materials)
g is gravity
d is water depth
|∇U | is the magnitude of the 2D velocity strain tensor

The computed viscosity νT can be output using the Map Output Data Types command. In our
testing to date, we have found C3D = 7 and C2D = 0 to yield results that agree well with
benchmark tests and that are not significantly dissimilar from those of the previous Smagorinsky
method with its default coefficients for situations where the depth is not significantly greater than
the cell-size. The values of C3D = 7 and C2D = 0 are the default values but can be changed
using the Viscosity Coefficient command. This effectively ignores the 2D component in the Wu
model. Alternatively, to use only the 2D component of the model (and ignore the 3D component),
we have found C3D = 0 and C2D = 4 to be a suitable starting point. As always, calibration
remains an essential step. If quality calibration data is available and all Manning’s values are
within industry standard ranges, then we encourage the user to adjust the coefficients as
necessary to achieve calibration. We anticipate that calibration should be possible with either C2D

or C3D in the range 1 to 7. If values outside this range are required then this may indicate other
errors (eg. boundary values or schematisation, poor input data, etc). As always, sensitivity testing
of changes in parameters on the model results should also be performed.

Section 7 2D Domains - 82 / 116 Page 331 / 1094

 It is a common practice to represent buildings in a model as roughness (i.e. cells with high
Manning’s bed friction), see discussion on modelling buildings in Section 7.3.10 . As the friction
velocity includes the Manning’s value, this results in a very high viscosity value at those cells. This
is not unreasonable, but for TUFLOW HPC, which handles the viscosity explicitly, this can drive
the timestep down to small values. We have found that limiting the Manning’s values used in the
Wu 3D model to a sensible maximum (for example 0.1) makes very little difference to the model
results but can vastly improve solution time. This upper limit is included as an optional third value
to the Viscosity Coefficient when using the Wu approach. Note that the original high Manning’s
value, as defined in the materials database, is used in the momentum equation where its primary
influence is effected.

@1035
7.4.3 Sub-Grid Sampling (SGS)

Sub-grid sampling (SGS) stores elevation points sampled at a finer resolution than the 2D cell to
more accurately represent the variations in terrain inside the cell, as shown in Figure 7.26 . SGS
functionality is introduced in Section 3.3.3 . Benchmark testing has shown the benefits of using
SGS to be substantial, as discussed in Section 3.3.3.1 .

SGS translates the high resolution sampled elevation data into cell curve functions for its hydraulic
calculations.

The cell volume is stored as a non-linear function of elevation (i.e. a curve of cell volume
versus elevation based on the wetted surface area versus depth measured from the lowest
sampled elevation within the 2D cell).
Across each cell side the flow area and flow width are calculated based on sampled
elevations to produce a non-linear function of conveyance versus elevation (i.e. a curve of
conveyance versus elevation. For determining the depth and width averaged velocity across
each cell face the flow area is also retained as a curve of area versus elevation).

The elevation dataset sample resolution can be defined by the user. For example, using a 8m cell
size and a 2m SGS Sample Target Distance the DEM is sampled at 5 points across each face.
Shown in Figure 7.26 this translates to 25 elevation points being used to define the volume vs
elevation relationship within the 2D cell, and 5 points along each cell side for defining the
conveyance-elevation relationship of each face.

@1036 @1037

Figure 7.25: Traditional (non-SGS) Approach Figure 7.26: SGS Approach

The flow or conveyance of water through 2D cells is determined through a full 2D solution of the
momentum equation (see Section 7.2 ). The bed resistance term (e.g. Manning’s equation) and
the determination of the 2D velocities are controlled by the conveyance properties of each cell
face. If there are considerable variations in bed topography across the cell faces, SGS will provide
a significantly more accurate representation of these variations, compared to a traditional 2D cell
with a single elevation value per cell face.

Section 7 2D Domains - 83 / 116 Page 332 / 1094

 If the resolution of the DEM data layer is coarser or similar to the 2D cell size, the use of SGS will
have little or no benefit. For example, if the DEM resolution is 2m and the cell size is 2m there is
little benefit in using SGS, although a slight improvement would result as the slope of the terrain
across the cell would be picked up if using SGS. In contrast, if the cell size is 20m there would be
considerable benefit in using SGS as the variations in terrain across the 2D cell will be
represented. TUFLOW requires an odd number of sample locations across a cell face to ensure
the cell mid-face and cell corners are sampled. The number of sample locations across a cell face
is referred to as the SGS Sample Frequency .

Note, if the elevation input data has a reasonable representation of the channels, Read GIS Z
Shape or Read GIS Z Line “MIN, GULLY or LOWER” lines are not required, or recommended,
when using SGS. Including gully lines can overestimate conveyance in these channels.

The following section will focus on implementing SGS and options regarding SGS outputs.

@1038 SGS Methodology and Commands

7.4.3.1

To implement SGS the only additional command required in the .tcf is “SGS == ON”.

By default, using this command will set:

the SGS Approach to Method C. Prior to 2023 release the default was Method B. The default
Method C is the recommended approach and older versions are considered legacy though
are still provided for backward compatibility.
the SGS Sample Frequency to sample at the minimum grid elevation resolution that can be
found from grids read in to the .tgc.

@1039 SGS Sample Distance

7.4.3.1.1

To manually set the SGS distance, the recommended approach is to use the .tcf SGS Sample
Target Distance command. TUFLOW requires an odd number of sample locations across a cell
face, the number of sample points is calculated from Equation (7.11)

@1040 TUFLOW Cell Size

Sample Frequency = + 1 (7.11)
Target Distance

For example, using a cell size of 10m and a sample target distance of 1m, TUFLOW will use 11
sample points along the cell face. If the target distance specified gives an even number, TUFLOW
will round up to the next odd number. For example, using a cell size of 5m and a sample target
distance of 1m, TUFLOW will use 7 sample points instead of 6 points along the cell face. The
adopted sampling frequency is reported in the .tlf.

It is also possible to specify the SGS Sample Frequency directly instead of the target distance.
However, changing the cell size of the model would require a changing to the sample frequency to
maintain the same sample distance. When using a target sample distance the same value can be
used across all cell sizes.

To obtain the maximum resolution, the sampling frequency can be calculated as the TUFLOW cell
size divided by the DEM resolution. If this yields an even number, then it should be rounded up as
per Equation (7.11) . Note, there is no benefit to specify an SGS target distance smaller than the
DEM resolution.

Section 7 2D Domains - 84 / 116 Page 333 / 1094

 If neither the SGS Sample Target Distance or SGS Sample Frequency commands are specified,
a scan of the Geometry Control File (.tgc) is performed to find the minimum raster grid resolution
used in any Read Grid Zpt commands, and this is used as the sampling target distance to
compute the sampling frequency. If there are no gridded elevation datasets, a default sampling
frequency of 11 is used. In summary, there are four ways for the SGS Sample Frequency to be
defined; in decreasing order of priority they are:

1. “SGS Sample Frequency ==” command.

2. “SGS Sample Target Distance ==” command.
3. Target distance automatically based on the minimum grid elevation resolution in the .tgc.
4. Default Sampling Frequency of 11 per face / 121 per cell.

Note: the sampling frequency per face is capped at 31 by default to avoid long pre-processing
times and high memory usage. In general, a sampling frequency of between 11 and 31 is sufficient
for most natural water ways or artificial structures, and users may not benefit from applying a
super fine sample distance against the model cell size. However, if required, high sampling
resolution is possible and the set upper limit can be increased by using the following tcf command:

SGS Max Sample Frequency == ⟨maximum frequency⟩

Note, a hard limit of 127 per face (16,129 samples per cell) still applies.

@1044 Advanced SGS Commands

7.4.3.1.2

As noted above, the only command required to implement SGS is “SGS == ON”. One of the
above commands to set the SGS sample distance or frequency is also recommended. The
following section lists advanced commands related to SGS.

SGS Breakline Detection Delta == [ <maximum_delta_value> ]

When the SGS elevations are being processed, every cell face will store a curve of elevation
versus flow width / flow area. Likewise, each cell has a curve defining the relationship of elevation
versus cell volume. To make this memory efficient TUFLOW does not store information defining
the specific locations within the cell or along the cell face where the low or high points in the
topography occur. As a result, without breaklines, SGS will be more likely to allow “leaks” through
a levee or embankment compared with running the model without SGS. For example, if a 2D cell
straddles a levee, SGS will sample the low elevations on either side of the levee and will flow at a
lower level than if SGS was not applied and the 2D cell centre was located on top of the levee,
causing the 2D cell to block flow until the levee is overtopped. Therefore, whilst the need to have
breaklines is paramount, regardless of whether SGS is used, it is even more important for SGS
models to accurately represent hydraulic controls such as levees (artificial or natural), road/rail
embankments, fences, etc.

SGS Breakline Detection Delta is designed to identify locations where ridge lines may be
required. As noted in Section 7.4.3 , Read GIS Z Shape or Read GIS Z Line “MIN, GULLY or
LOWER” lines are not recommended for use.

The SGS breakline detection check processes each 2D cell to identify the minimum water surface
elevation needed for a continuous wet connection through the cell traversing between left to right
and top to bottom. The maximum invert elevation of the left and right faces is subtracted from the
left-right minimum water level and reports it as “uDelta”. Similarly, the top to bottom value is

Section 7 2D Domains - 85 / 116 Page 334 / 1094

 reported as “vDelta”. uDelta and vDelta represent the depth of water over the cell face inverts by
which a natural ridge (break) line would block any flow. The maximum of uDelta and vDelta is
output to the _grd_check file in the SGS_Delta_Z attribute. If either uDelta or vDelta exceeds the a
spatial (GIS) CHECK 3543 message is issued at the cell location.

This command can add significant time to the initialisation process, it is recommended to perform
this check during model set up only, and to turn it off once the creation of breaklines is complete.

Figure 7.27 shows an example of where CHECK 3543 indicates where the uDelta or vDelta has
exceeded the (in this example, a value of 1m).

@1045

Figure 7.27: SGS Breakline Detection Delta Output

SGS Z Shape Line Approach == Method A | {Method B}

If set to Method A, cell faces modified by Read GIS Z Shape line are assumed flat (i.e. SGS is
not applied and a rectangular section / flat cell is used). The default, Method B, applies a gradient
along the face based on the cell corners and cell side Zpt values and for thick lines uses the ZC,
ZU, ZV and ZH values to apply a sloping cell area for the cell volume.

@1046

Figure 7.28: Diagram of SGS Z Shape Line Approach Options

SGS SX Z Flag Approach == Method A | {Method B}

If set to Method A, cells that are lowered by the “Z” flag on 2d_bc SX connections are assumed flat
(i.e. as per the approach for no SGS). The default Method B retains the SGS information, but
shifts it all to match the lowered elevation, as per Figure 7.29 .

@1047

Section 7 2D Domains - 86 / 116 Page 335 / 1094

 Figure 7.29: Diagram of SGS SX Z Flag Approach Options

SGS Infiltration Approach == {AUTO} | TOTAL AREA | WETTED AREA

It is possible to control the cell area used when infiltration is applied with SGS, using the SGS
Infiltration Approach command. The three available options are:

AUTO (the default): uses total area if there is a rainfall boundary and wetted area if no rainfall
boundaries are present.
TOTAL AREA: uses the whole cell area, regardless of the portion of the cell that is wet.
WETTED AREA: uses only the wetted portion of the cell, for direct rainfall boundaries this
may under predict the infiltration.

SGS Negative Rainfall Approach == TOTAL AREA | {WETTED AREA}

It is also possible to control the cell area used when negative rainfall is applied in conjunction with
SGS, using the SGS Negative Rainfall Approach command. The two options available are:

TOTAL AREA: uses the whole cell area, regardless of the portion of the cell that is wet.
WETTED AREA (the default): uses only the wetted portion of the cell.

With SGS enabled, for cells that are partially wet the treatment of infiltration and direct rainfall is:

For positive rainfall (i.e. rainfall on to the 2D cell), the volume source for each cell is the total
cell area times the rainfall irrespective of whether the cell is partially wet or not.
For negative rainfall (evaporation), the volume of evaporation is factored by the wet area
fraction of the cell. That is, if the cell is only 10% wet, only one tenth of the cell’s total area
contributes to the negative source term.
For models with soil infiltration the infiltration rate is proportional to the wet area fraction of the
cell. However, initial infiltration losses are based on the total area of the cell (i.e. infiltration will
proceed at the maximum possible rate until the cumulative infiltration – also based on total
cell area - equals the initial loss value) even if the infiltration occurs with the cell partially wet.
This approach is adopted to conform with that required for direct rainfall, which assumes the
rainfall is applied over the entire cell irrespective of whether the cell is partially wet or not.
Likewise, soil capacity is based on the total cell area (i.e. infiltration will cease once the
cumulative infiltration equals soil capacity), and the cumulative wet time for the Horton model
will also increment for cells that are partially wet.

@1048 SGS Output Options

7.4.3.2

@1049 Check Files

7.4.3.2.1

When running a model with SGS enabled there are additional attributes inserted into the _zpt
check layer and an additional raster check file, the _DEM_Zmin.

Section 7 2D Domains - 87 / 116 Page 336 / 1094

 If the _zpt check layer is output, with SGS turned on, the following additional attribute information
is provided:

The “Zmin” attribute for ZC points, previously called “Elevation”, now represents the minimum
elevation within the cell. The “Zmin” for ZU/ZV points is the minimum along the cell face. Note,
these points are still located at the centre of the cell or cell face, but the minimum value is not
necessarily at this location.
“ZExact” is the elevation at the exact location of cell centre, face mid-point, or cell corner.
“ZAvg” is the average (mean) elevation of the sampled values.
“ZMed” is the median elevation of the sampled values.
The “ZMax” attribute is the maximum elevation (i.e. the elevation at which the cell area or cell
face flow width is fully wet).
“ZOut” is the elevation used for the SGS Depth Output (Section 7.4.3.2.2 ).

If the _DEM_Z layer is output, with SGS turned on, an additional raster output is produced, the
_DEM_Z_min. The _DEM_Zmin contains a raster based on the minimum SGS elevations. When
using SGS, the _DEM_Z contains a raster based on the SGS elevations used for the depth output
interpolation (based on the SGS Depth Output command.)

@1050 Map Outputs

7.4.3.2.2

The following .tcf commands can be used to control the value of depth (d) map output when SGS
is used.

SGS Depth Output == EXACT | {CELL AVERAGE} | MEAN | MEDIAN | MINIMUM |

PERCENTILE

CELL AVERAGE (default): calculates the depth by dividing the cell volume by cell area.
EXACT: the output depth is the water level minus the exact ZC and ZH elevations (i.e. the
elevations that would be sampled exactly at the cell centre (ZC) and cell corner (ZH) locations
if SGS was not applied).
MEAN: the output depth is the water level minus the mean elevations of the cells and the cell
corners from the SGS sampling. Note the MEAN depth output differs from the CELL
AVERAGE depth for partially wet cells. For example, if the water level is smaller than the
MEAN cell elevation, the MEAN depth output becomes negative (trimmed as zero), while the
CELL AVERAGE depth (water volume / cell area) is still positive.
MEDIAN: the output depth is the water level minus the median (50th percentile) elevation for
the cells and the cell corners from the SGS sampling.
MINIMUM: the output depth is the water level minus the minimum elevation for the cells and
the cell corners from the SGS sampling (i.e. the map output shows the maximum depth within
a cell / around a cell corner).
PERCENTILE: the output depth is water level minus an elevation based on the specified set
percentile. This requires a second argument, separated by vertical bar “|”, which is the
percentile to use. For example, “SGS Depth Output == Percentile | 25” will use the
25th percentile of the SGS elevations sampled within the cell / around the cell corner.

The elevations used for the SGS Depth Output are output in the _zpt_check file as the “ZOut”
attribute, see Section 7.4.3.2.1 .

Note that the water level (h) output is not affected by this command.

Section 7 2D Domains - 88 / 116 Page 337 / 1094

 For the EXACT, MEAN, MEDIAN, MINIMUM, PERCENTILE approaches, the depth output is
trimmed if the modelled water level is lower than the output elevations. Meanwhile, the water level
output is not trimmed even if the output depth is below the output elevations, and this can produce
different output extents for the water level and other outputs. For this reason, the CELL AVERAGE
option is recommended for the consistency of the output extent. But if using the other options, the
default trimming option can be changed using the SGS Map Extent command.

For the MEAN, MEDIAN, MINIMUM, PERCENTILE approaches, the corner output elevations
depend on the size of the SGS sampling area around the cell corners. By default, cell corner
elevations are sampled within a square that has the same size as the 2D cell. The size be
manually adjusted using the SGS ZH Sample Ratio command.

By default the CELL AVERAGE depth is used to calculate the depth/velocity based map outputs,
such as unit flow (q), bed shear stress (BSS), stream power (SP) and hazards, regardless of the
SGS Depth Output setting. However, if desired, the depth used to calculate these map outputs
can be changed using the following command:

SGS Velocity Based Outputs == {CELL AVERAGE DEPTH} | SGS DEPTH OUTPUT

If set to the “SGS DEPTH OUTPUT” option, the output depth specified by the SGS Depth Output
command above is used. Note that the velocity (v) output is not affected by these commands.

@1051 High-Resolution Outputs

7.4.3.2.3

When using the default sub-grid sampling (SGS) approach the sampled elevations are retained,
including topography modifiers such as breaklines, for result post processing. This allows a high-
resolution grid to be written (for either depth (d) or water level (h)) and used for high resolution
map outputs and also check grids such as the DEM_Z. High-resolution outputs, made available
when using SGS Method C, are discussed in Section 11.2.2.3 .

The following commands can be used to alter the high resolution output and are discussed further
in Appendix A .

HR Interpolation Approach : can be used to control how the cell centre / corner data is
interpolated across the cell.
HR Thin Z Line Output Adjustment : for models with thin breaklines, the presence of
breaklines can be used to alter the High Resolution output interpolation.

@1052
7.4.4 2D Upstream Controlled Flow (Weirs and Supercritical
Flow)

The original weir flow approximation in TUFLOW HPC was to adjust the water level gradient
where flow in the 2D domain becomes upstream controlled. The 2023-03 release (and onwards)
defaults to applying the full weir equation in the 2D domain along thin and thick breaklines based
on the advanced weir equation (Section 5.8.4.3 ). However, users can revert to the original
approach using the command:

HPC Weir Approach == Method A | Method B | {Method B Energy}

Where:

“Method A” is the pre 2023-03 method that applies the water level gradient limiter only.

Section 7 2D Domains - 89 / 116 Page 338 / 1094

 “Method B” applies the weir equation and uses the upstream water level above the weir invert
as Hu, and downstream water level above the weir invert as Hd.
“Method B Energy” is the default approach. It applies the weir equation and uses the
upstream energy level above the weir invert as Hu, and downstream water level above the
weir invert as Hd.

The default weir parameters (Cd, Ex, a and b) are based on the parameters used for a broad crest
weir, see Table 5.15 (i.e. 0.577, 1.5, 8.55 and 0.556, respectively). The following .tcf commands
can be used to change the coefficients globally.

For a thin breakline:

HPC Thin Weir Parameters == <Cd>, <Ex>, <a>, <b>

For a thick breakline:

HPC Thick Weir Parameters == <Cd>, <Ex>, <a>, <b>

In addition, the weir calibration factor, Cf ,can be adjusted globally using the using the Set WrF
command, or adjusted locally using the Read GIS WrF command. The default value of Cf is 1.0.

@1053
7.4.5 Infiltration and Groundwater Flow

This section contains information relating to soil infiltration and groundwater flow options for
TUFLOW HPC.

@1054
7.4.5.1 Infiltration

@1055 SCS Curve Number (SCS)

7.4.5.1.1

The SCS method, added in the 2025 release, uses a “curve number” (USDA, 1986 ) (ranging
from 100 for impervious rock down to approximately 30 for deep porous soils) to define the
maximum infiltration that can soak into the ground. An initial loss for the soil can be defined,
typically as a fraction (termed the “initial abstraction ratio”) of the maximum infiltration. The initial
loss is not considered an extra loss - the remaining soil capacity after the initial loss is filled is
equal to total soil capacity (as defined in equation (7.12) ) less the initial loss. The SCS method is
only available in the HPC solver - it is not available in Classic. For the soil infiltration methods
supported by both Classic and HPC, see Section 7.3.7.1 .

SCS infiltration differs from the alternative methods (e.g. Green-Ampt, Horton and ILCL - see
Section 7.3.7.1 ) in the following ways:

1. The maximum infiltration and the rate of infiltration are both defined by the curve number, and
the initial loss by the abstraction ratio. As a result the soil capacity cannot be defined
independently of the soil type, and similarly, initial water content of the soil cannot be defined
independently of the soil type. Therefore reading soil depth, porosity, and initial moisture as
spatial layers are all disallowed with this method, and SCS soil types cannot be used in
conjunction with any of the other soil types within the same model.
2. The infiltration is defined as a fraction of the applied rainfall, which is dependent only on the
curve number and the cumulative rainfall at the location in question. Infiltration does not occur
if there is no rain, and the amount that occurs is defined as a fraction of the rainfall,
regardless of whether or not the soil has surface water over it. The SCS method is really a

Section 7 2D Domains - 90 / 116 Page 339 / 1094

 rainfall loss method defined according to soil type, rather rather than physics-based
infiltration.
3. The SCS method is a rainfall loss method, therefore it can only be used with single layer soil
files with groundwater depth unspecified, i.e. interflow (Section 7.4.5.2.2 ) is not allowed. The
SCS method is not recommended for continuous simulations especially when sub surface
flows may be of concern.

The parameters used in the tsoilf by the SCS method are shown in Table 7.21 .

The maximum infiltration is defined (in inches) as

@1056 S =
1000 − 10CN
(7.12)
CN

Where:

S is the maximum infiltration in inches (which is converted for models in SI units)

CN is the curve number

The initial loss is defined as a fraction of the maximum infiltration:

@1060 I L = Ia S (7.13)

Where:

IL is the initial loss

Ia is the “initial abstraction ratio”

For the duration where the cumulative rainfall is less than the initial loss, the cumulative infiltration
must match the cumulative rainfall. After this time, the cumulative infiltration is defined as a
fraction of the cumulative rainfall according to:

2
@1064 (RF C − I L)
CI = RF C − (7.14)
RF C + S − I L

Where:

CI is the cumulative infiltration

RF C is the cumulative rainfall

Once the cumulative infiltration matches the maximum, S , no further infiltration occurs. This
occurs at a cumulative rainfall of

@1069 1 − Ia + Ia
2

RF Cs = S ( ) (7.15)
Ia

This process is shown in Figure 7.30 for SCS curve number 50 with initial abstraction ratio 0.2. In
this example the maximum infiltration, S , is 10 inches, and is reached at 42 inches cumulation
rainfall (marked as RF CS ).

@1073

Section 7 2D Domains - 91 / 116 Page 340 / 1094

 Figure 7.30: SCS Infiltration for Curve Number 50, Ia = 0.2
The instantaneous infiltration rate, during the period I L < RF C < RF Cs , can then be found to
be:

2
@1075 S
IR = ( ) RF (7.16)
S − I L + RF C

Where:

IR is the current infiltration rate

RF is the current rainfall rate

For the SCS method, the infiltration rate is based on the rainfall as applied at ground level,
i.e. after the material based initial loss and continuing losses have been applied. It is worth
considering that the SCS method allows for an instantaneous absorption of rain up to the initial
loss (initial abstraction ratio times maximum infiltration). In this case, any materials based initial
loss and continuing loss should be thought of as interception losses only. With forested areas
these may be large enough that they should be included, but in open grasslands they are probably
insignificant. The infiltration losses are then also reduced according to the material fraction
impervious, which effectively means that:

1. The soils based initial loss as defined by the initial abstraction ratio is reduced by the material
fraction impervious, and
2. The total loss (i.e. equivalent to soil capacity) is also reduced by the material fraction
impervious. When using sub-grid sampling, the wet area fraction method selected is not used
as the losses apply to rainfall, not ponded water.

@1079
7.4.5.2 Groundwater Flow

Infiltration of the surface water into the ground/soil has been supported in previous releases,
however, as discussed in Section 7.3.7 , this functionality was limited to vertical movement of
water, and one vertical soil layer (the soil type could vary spatially across the model).

Section 7 2D Domains - 92 / 116 Page 341 / 1094

 From the 2023-03 release and onwards, horizontal flow (advection) of water (Section 7.4.5.2.1 )
and multiple vertical groundwater layers (Section 7.4.5.2.2 ) when using TUFLOW HPC are
supported. Up to 10 vertical layers are supported, each with horizontal advection within the layer
possible, and vertical fluid movement between groundwater soil layers. Movement of water within
the ground in the real world is complex. The functionality introduced in the 2023-03 release is not
intended to replace detailed groundwater modelling, but provides a functional mechanism by
which:

Catchment response for 2D direct rainfall (“rain on grid”) models can be better calibrated to
available river flow data.
Long-term catchment models can be constructed that offer some prediction of stream-flows
long after rainfall events.
The accuracy of real-time flood forecasts can be improved by taking into account the drying
and draining of catchments that has occurred since the last rainfall event.
Groundwater seepage can cause inundation, such as seepage under a levee bank through a
porous layer (e.g., old gravel river course), resulting in flooding on the protected side of the
levee.

The basic groundwater modelling approach is conceptualised by dividing the ground into vertical
layers, each with a defined thickness (alternatively a z elevation for the bottom of each layer), soil
type, and cumulative infiltration of water within the layer. The cumulative infiltration, combined with
the porosity defined by the soil type, allows a theoretical “groundwater elevation” (also known as a
“water table”) to be computed within the layer. Figure 7.31 illustrates the soil layers in adjoining
cells with convective and advective fluxes.

@1080

Figure 7.31: Illustration of soil layers and flows in adjoining cells

The horizontal movement of water, Q

h
, is governed by the horizontal hydraulic conductivity value
set in the tsoilf file (see Table 7.21 ). All groundwater layers allow for horizontal advection of the
water within the layer. Horizontal advection is disabled if all horizontal hydraulic conductivities are
set to zero (which is the default if they are not specified). An example of a model using horizontal
hydraulic conductivity, is provided in the TUFLOW Example Model Dataset.

Section 7 2D Domains - 93 / 116 Page 342 / 1094

 The vertical flow of water, Q
z
, from the surface water layer into the first (or top) groundwater layer
is governed by the soil infiltration model. The infiltration into the top soil can use any of the Green-
Ampt (GA), Horton (HO) and Initial/Continuing Loss (IlCL) infiltration methods, as listed in Table
7.21 . For layers below the top vertical soil layer then the Convective (CO) type must be used,
see Section 7.4.5.2.2 . An example of a model using two vertical soil layers (i.e. the “CO” type), is
provided in the TUFLOW Example Model Dataset.

The cumulative infiltration data and the vertical movement of water are stored and computed at
cell centres. As such, all soil data and groundwater layer geometry is sampled from the GIS / Grid
layers at cell centres. Likewise the material “fraction impervious” data is sampled at cell centres
(unlike the mannings values which are sampled at face centres). For the horizontal advection
calculation, which is performed at cell faces, the horizontal hydraulic conductivity used is the
average of the cell centre values for the adjoining cells.

@1083 Horizontal Advection

7.4.5.2.1

For all layers, the horizontal advection of water from one cell to the next, Q
h
, is computed using
the horizontal hydraulic conductivity of the soil and the horizontal gradient of a variable called the
“groundwater pressure level”:

@1085 h
de
Q = −kh hp dy (7.17)
dx

Where:

kh is the horizontal hydraulic conductivity of the soil (average of the adjoining cells used)
h is the groundwater elevation less the layer bottom elevation
p is the soil porosity
de
is the gradient of the “groundwater pressure level”
dx

dy the width of the face.

Note, if advection of groundwater is not required, then the advection calculation may be disabled
by setting kh to zero for all soils. This is the default behaviour if kh is not specified in the soil
parameters.

For cells that are “unsaturated” the “groundwater pressure level” is exactly the groundwater
elevation within that layer. For cells that are fully saturated, the groundwater pressure level is that
of the cell in the next layer above (or the water surface elevation when considering the topmost
groundwater layer). For cells that are “nearly saturated” the groundwater pressure level is
transitioned between these two options. The threshold at which the transition begins is called the
“groundwater blending threshold”, ϕ .

@1095 hi
− ϕ
dz
ξ = (7.18)
(1 − ϕ)

ei = (1 − ξ) (zi + hi ) + ξei−1

e0 = W SE surf ace

Where:

hi is the depth of groundwater in the cell

dz the vertical thickness of the layer
zi the layer bottom elevation

Section 7 2D Domains - 94 / 116 Page 343 / 1094

 ei−1 the groundwater pressure level for the layer above (or surface layer) - ei the resulting
groundwater pressure level for this layer.

The layer ordering is such that the surface water is layer “0”, the highest groundwater layer is “1”,
and any subsequent groundwater layers range from 2 to N (i.e. from top to bottom).

The groundwater blending threshold, ϕ , defaults to a value of 0.9 but can be overridden by the
user in the .tcf using the command:

Groundwater Blend Threshold == <float> | {0.9}

If the sum of flows into a layer cell causes it to exceed its soil capacity, the excess is pushed
upwards to the next layer. If this happens for the top-most groundwater layer, the excess is
pushed into the surface water as “return flow”. This is to be expected in the creek beds but may
also happen at the bottom of steep hills where the slope transitions from steep to shallow.

@1103 Convective Flow Layers (CO)

7.4.5.2.2

For layers below the top groundwater layer, the vertical flow of water, Q
z
, is computed using a
“convective” hydraulic conductivity (effectively the same concept as continuing loss):

z
@1105 Q = − kdxdy (7.19)

Where:

Q
z
is the convective vertical flux
k is the convective hydraulic conductivity
dxdy is the cell area.

Note that Q
z
is limited to the available cumulative infiltration stored in the groundwater layer
above, and also limited to the remaining capacity of the groundwater layer below.

@1111 Implementation
7.4.5.2.3

Although the theory appears complex, the implementation within the TUFLOW model files is
straight forward. The essential steps are:

Read a soils (.tsoilf) data file from within the .tcf (see Section 7.4.5.3 ).
Define the soil types in the .tgc (see Section 7.4.5.2.4 ).
Define the soil layer thickness in the .tgc (see Section 7.4.5.2.4 ).
Specify locations of groundwater boundaries in the .tbc (see Section 8.5.1.2 ).
Specify initial water levels within the soil layers (optional) (see Section 8.9.2 ).
Add any additional output data types in the .tcf. For example the Map Output Data Types:
dGW, GWd, GWh, GWm, GWq, GWv in Table 11.4 , or Time Series Output Data Types:
GWd, GWh, GWm, GWq, GWqa, GWqu, GWqv, GWVol in Table 11.9 .

@1112 Soil Type

7.4.5.2.4

Setting the soil type for the groundwater layers activates the given layer. The Green-Ampt, Horton
and Initial/Continuing Loss infiltration methods can be used for Layer 1. Any layers beneath Layer
1 (e.g. Layer 2, Layer 3) must be the Convective Type. For example, setting the soil type for layers
1 and 2 will activate 2 vertical groundwater layers:

Set Soil Layer 1 == 1 ! soil ID of infiltration layer e.g. GA type

Set Soil Layer 2 == 5 ! soil ID of a convective layer e.g. CO type

Section 7 2D Domains - 95 / 116 Page 344 / 1094

 Multiple layers can be set simultaneously (the below will activate 3 interflow layers):

Set Soil Layer 1 == 1

Set Soil Layer 2,3 == 5 ! sets both layers 2 and 3 to Soil ID 5

This method also works for read GIS and Grid commands:

Read GIS Soil Layer 1 == ⟨ gis_layer ⟩

Read Grid Soil Layer 2 == ⟨ gis_layer ⟩

A maximum of 10 vertical layers is permitted and a soil ID should be assigned for each active
layer. For example, if groundwater layer 2 is active, then soil IDs for layer 1 should be assigned.
Note, if the layer number is not specified in a .tgc command (e.g. Set Soil), it is assumed to be
layer 1.

@1117 Soil Thickness

7.4.5.2.5

The depth (thickness) of each vertical interflow layer can be set using the following commands:

[Set | Read GIS | Read Grid ] Soil Thickness Layer N == [value | ⟨

gis_layer ⟩ ]
[Set | Read GIS | Read Grid ] Soil Base Elevation Layer N == [value | ⟨

gis_layer ⟩ ]

If the soil layer thickness or base elevation is not set for a given layer, it is assumed to be infinite.
The soil thickness sets the layer depth from the layer above and soil base elevation sets the
absolute elevation of the bottom of the layer. If both methods are specified for a given grid cell, the
highest of the two will be adopted. The input units should be in metres or feet (if using Units ==
US Customary).

@1122 Drying of Top Groundwater Layer

7.4.5.2.6

Evaporation is typically implemented with a global negative rainfall. Prior to the 2023-03 release
this would only remove water in wet cells until they dry. It would not draw from the cumulative
infiltration layer. The 2023-03 release and onwards allows for negative rainfall to draw from the
topmost groundwater layer under surface layer cells that are dry, thus mimicking
evapotranspiration. Currently only one approach is implemented, called “factor”, which applies the
defined negative rainfall, though at a (globally) factored rate. To select this approach use the Soil
Negative Rainfall Approach .tcf command.

The default approach is to not apply any negative rainfall to the topmost groundwater layer. If the
“factor” method is selected, then the factor can be set using the Soil Negative Rainfall Factor .tcf
command. The default factor is 1, meaning that the full value of the negative rainfall is applied. If
the topmost groundwater layer is dry, then no negative rainfall is applied, and the approach does
not look any further than the topmost layer. No water is drawn from subsequent ground water
layers.

@1123
7.4.5.3 HPC Soils File (.tsoilf)

The .tsoilf is the same file mentioned in Section 7.3.7.2 . However, when using TUFLOW HPC
there are additional parameters available which can be used to enable horizontal advection, as
well as two additional soil types: convective (CO) and SCS. These additional parameters are bold
in Table 7.21 .

Section 7 2D Domains - 96 / 116 Page 345 / 1094

 @1124 Table 7.21: HPC .tsoilf Parameters

Column No Initial/Continuing
Green-Ampt Green-Ampt Horton
No. Intriltration Loss

1 Soil ID Soil ID Soil ID Soil ID Soil ID

2 NONE GA GA HO ILCL

USDA Soil Initial Loss

Suction (mm Initial Loss (mm
Type (see (mm or
3 or inches) or inches)
Table 7.12 ) inches)
(mandatory) (mandatory)
(mandatory) (mandatory)

Hydraulic Initial Loss

Initial
Conductivity Rate (f0 ) Continuing Loss
Moisture
4 (mm/h or (mm/h or (mm/h or in/h)
(Fraction)
in/h) in/h) (mandatory)
(optional)
(mandatory) (mandatory)

Final Loss
Max Ponding Porosity Rate (fc ) Porosity
5 Depth (m or (Fraction) (mm/h or (Fraction)
ft) (optional) (mandatory) in/h) (optional)
(mandatory)

Horizontal
Hydraulic Initial Exponential
Initial Moisture
Conductivity Moisture Decay Rate
6 (Fraction)
(mm/h or (Fraction) (k) (h-1 )
(optional)
in/h) (optional) (mandatory)
(optional)

Horizontal
Max Ponding Porosity Hydraulic
7 Depth (m or (Fraction) Conductivity
ft) (optional) (optional) (mm/h or in/h)
(optional)

Horizontal
Hydraulic Initial
Conductivity Moisture
8
(mm/h or (Fraction)
in/h) (optional)
(optional)

Horizontal
Hydraulic
Conductivity
9
(mm/h or
in/h)
(optional)

Section 7 2D Domains - 97 / 116 Page 346 / 1094

 @1127
7.4.6 Non-Newtonian Flow

TUFLOW HPC supports modelling of non-Newtonian fluids. The non-Newtonian flow theory, and
an example of its use in TUFLOW is discussed in the Tsunami and Dam Failure and non-
Newtonian Modelling AWS Webinar. This feature was introduced in the 2020-01 release. It is not
supported in TUFLOW Classic. High-fidelity modelling of non-Newtonian fluids is complex and 3D
in nature. However, with some assumptions, it is possible to model non-Newtonian fluids
reasonably well in 2D. The assumptions are:

1. The 2D (horizontal) viscosity can be represented as a summation of laminar (derivative of

non-Newtonian shear stress model) and turbulent (from Wu eddy viscosity model)
contributions.
2. Acceleration effects are small and the laminar fluid shear stress is linear with depth.
3. The bed shear stress can be represented as a summation of laminar (from non-Newtonian
shear stress model) and turbulent (from Manning’s equation) contributions.

The laminar fluid shear stress (for flow that is shearing), is assumed to follow the Hershel-Bulkley
power law model:
n
@1128 τ = τ0 + kγ̇ (7.20)

Where:

τ0 = Yield shear stress of the fluid.

k = Viscosity parameter (units Pa.sn)
γ̇ = Shear strain rate of the fluid
n = Power law exponent (1 = Newtonian, <1 is shear thinning, >1 is shear thickening)

For flows where the bed shear stress exceeds the yield stress, a ‘plug flow’ velocity profile is
computed, as shown in Figure 7.32 . For flows where the bed shear stress does not exceed the
yield stress, the fluid is considered locked to the bed and does not flow. Within TUFLOW HPC, at
the start of each timestep, a bed stress is calculated for each cell such that the predicted velocity
profile (for the given bed shear stress) has a depth averaged mean velocity that matches the
current model velocity.

@1134

Figure 7.32: Non-Newtonian Shear Stress and Velocity Profile

Section 7 2D Domains - 98 / 116 Page 347 / 1094

 Note that for fluids with a low viscosity parameter, or for deep and/or faster flows, the bed friction
that would arise through the use of Manning’s equation (which is based on turbulent water flow)
can be equal to or greater than that from the Hershel-Bulkley equation. In this situation the
mathematics is stating that the non-Newtonian flow is likely to be turbulent and behaving more like
water, and the bed shear stress as computed by the Hershel-Bulkley powerlaw model is likely to
be lower than what is occurring in reality. To account for this transition in a simple manner, the
actual bed friction used is the sum of both non-Newtonian and Manning’s contributions (note the n
in the final term on the righthand side of the following equation is Manning’s n, not the Hershel-
Bulkley power law exponent):

2
@1135 n
2
ρgn |U |
τ = τ0 + kγ̇ + (7.21)
1

d 3

This provides a very stable and smooth transition from non-Newtonian bed shear stress to
turbulent water-like bed shear stress as and when needed. The total shear stress is then utilised in
the momentum equation to evolve the flow velocity. The momentum equation also considers the
possibility that the fluid yield stress is sufficient to hold the fluid against the net momentum flux, in
which case the fluid velocity is zeroed.

For the computation of 2D shear stresses, the yield shear stress is not used and the fluid is
allowed to continue shearing down to low shear strain rates and correspondingly low shear
stresses. The effective Non-Newtonian 2D viscosity is computed using the derivative of the
Hershel-Bulkley equation:

@1137 μ2D = kn|γ̇|

n−1
(7.22)

2 2 2
⎛ 2|U | du dv 1 du dv ⎞
|γ̇| = max , √( ) + ( ) + ( + )
⎝ d dx dy 2 dy dx ⎠

Where:

|γ̇| = Magnitude of shear strain rate

Since the n − 1 exponent can cause the viscosity to diverge to infinity at low strain rates for shear
thinning fluids, it necessary to bound the resulting viscosity to a user defined upper limit, μhigh .
For completeness a user defined lower limit, μlow , is also applied.

Finally, for deeper and high velocity flows it is possible that the effective 2D viscosity of turbulent
water, as computed by the Wu turbulence model, is greater than the value computed from the
Hershel-Bulkey powerlaw model. Again, in this situation the mathematics is stating the non-
Newtonian flow is likely to be turbulent and behaving more like water. To account for this transition
the actual 2D viscosity used is the sum of both non-Newtonian and Wu turbulence model
contributions:

μ2D
@1143 νT = + 7U
∗
d (7.23)
ρ

Where:

√g n|U |
U
∗
= Friction velocity = 1

6
d

This provides a very stable and smooth transition from non-Newtonian 2D viscosity to turbulent
water-2D viscosity as and when needed. The value of 7 is the default Wu viscosity parameter and
is not user-definable for the non-Newtonian module.

Section 7 2D Domains - 99 / 116 Page 348 / 1094

 @1147
7.4.6.1 Implementation

The non-Newtonian flow model is invoked with the Viscosity Formulation command in the .tcf. If
invoked there are no default values for the required coefficients (k, n , μlow , μhigh , τ0 ). These must
be supplied with the Viscosity Coefficient command, where:

k : viscosity coefficient (Pa.s^n)

n : shear thickening exponent, must be non zero and positive (shear thinning fluids exhibit n <
1, shear thickening n > 1, and Newtonian fluids n = 1)
μlow : lower viscosity limit (Pa.s)
μhigh : higher viscosity limit (Pa.s)
τ0 : shear yield stress (Pa)

A step-by-step example of how to set up a non-Newtonian model is provided in Tutorial 5 on the

TUFLOW Wiki. Additionally, an example model is provided in the non-Newtonian section of the
TUFLOW Wiki Example Models.

Note: In TUFLOW HPC the 2D momentum diffusion is handled explicitly and therefore can drive
the model timestep to small values when the viscosity becomes large. Therefore, for shear
thinning models, it is important to define an upper limit, μhigh , that is only as large as necessary.
We suggest starting with 1,000 Pa.s and adjusting lower if the model is being strongly controlled
by the diffusion control number (Nd). Sensitivity testing should be done to test whether the upper
viscosity limit is influencing results in the region of interest. The lower viscosity limit, μlow , may be
set to zero if desired.

@1163
7.4.6.2 Non-Newtonian Mixing

It is possible to consider mixing of the non-Newtonian fluid with water, for example a tailings dam
failure into a flowing river. To implement this, a passive AD tracer must be included in the model,
note that this requires a licence for the Advection-Dispersion (AD) Module . The AD setup is the
same as detailed in Chapter 9 . More than one tracer field is permissible, but the non-Newtonian
mixing calculation will assume that the first tracer represents the fraction of non-Newtonian fluid, in
the range 0 to 1. Care must be taken to ensure that boundary data and initialisation commands
strictly adhere to this range. Where the tracer value is 1, the properties of the fluid will be exactly
the non-Newtonian properties, as specified with Viscosity Coefficient command, where the tracer
value is 0 the fluid will behave as water. For tracer values between 0 and 1, the non-Newtonian
properties are blended with those of water using a power-law equation.
m
ξ = a
@1164 (7.24)
′
ρ = (1 − a)ρw + aρN N

′ m m
K = (1 − a )νw + a KN N

′ o o
n = (1 − a )1.0 + a nN N

′ p
τ = a τ0,N N
0

Where:

a = the tracer value (0~1)

m = the non-Newtonian mixing exponent for the viscosity parameter
o = the non-Newtonian mixing exponent for the power law parameter
p = the non-Newtonian mixing exponent for the yield stress

Section 7 2D Domains - 100 / 116 Page 349 / 1094

 ρ = density of fluid (kg/m3)
ν = kinematic viscosity (m2/s)
K = the Hershel-Bulkley viscosity parameter (Pa sn)
n = the Hershel-Bulkley power law exponent
τ0 = the material yield stress (Pa)
subscripts w denotes water, NN denotes undiluted non-Newtonian fluid
superscript ‘ denotes blended value to use in the Hershel-Bulkley powerlaw model

The bed friction and 2D viscosity are computed using the non-Newtonian method with the blended
parameters. To turn on the mixing calculation, the mixing exponents, m , o and p can be specified
with the HPC Non-Newtonian Mixing Exponent command. The values must be within the range 1
to 10. It is the user’s responsibility to source the non-Newtonian parameters that represent the
undiluted mud, and also to source an appropriate values for the non-Newtonian mixing exponents.

To utilise non-Newtonian mixing in a model, the following is required:

1. Select the non-Newtonian viscosity formulation and specify the coefficients for pure non-
Newtonian fluid:
Viscosity Formulation == Non-Newtonian
Viscosity Coefficient == k, n, muLow, muHigh, tau0
2. Include a passive tracer as per standard AD setup (Chapter 9 ), making sure boundary data
and initialisation are scaled in range 0 to 1.
3. Specify the mixing exponents, m, o, and p to be used:
HPC Non-Newtonian Mixing Exponent == <float> | {0} ! used for all
three of m, o, p exponents
or
HPC Non-Newtonian Mixing Exponent == <float>, <float>, <float> | {0,
0, 0} ! m, o, p exponents

Note that if the non-Newtonian mixing exponent is not specified it defaults to zero which turns the
mixing formulation off, and all fluid in the model will be treated as non-Newtonian regardless of
tracer value.

An example non-Newtonian mixing model is provided in the non-Newtonian section of the

TUFLOW Wiki Example Models.

@1181
7.4.7 Unsupported Features in TUFLOW HPC

The following features are not supported in TUFLOW HPC:

Multiple 2D Domain (Section 7.5.4 ): This feature has been superseded by the TUFLOW
HPC Quadtree functionality (Section 7.4.1 ).
2D Flow Constrictions (2d_fcsh and 2d_fc) (Section 7.5.6.1 ): This feature has been
superseded by the 2d Bridge (2d_bg) (Section 7.3.8.2 ) and Layered Flow Constriction
(2d_lfcsh) (Section 7.3.8.3 ) features.
Coriolis Force (Section 7.5.5 ): The inclusion of the Coriolis term in the shallow water
equations is possible with TUFLOW Classic only.
Chézy and Fric options: TUFLOW HPC only supports Manning’s n bed resistance values
(Section 7.5.3 ).

Section 7 2D Domains - 101 / 116 Page 350 / 1094

 @1182
7.5 TUFLOW Classic Specific

This section describes functionality unique to TUFLOW Classic.

@1183
7.5.1 Classic Turbulence

For TUFLOW Classic, two options exist (Constant and Smagorinsky) for specifying eddy viscosity
for the 2D domains to approximate the effect of sub-grid-scale turbulence. For TUFLOW Classic,
the Smagorinsky approach (Section 7.5.1.2 ) is the default approach.

@1184 Constant
7.5.1.1

The Constant approach (Viscosity Formulation == CONSTANT) applies a constant value

throughout the model, irrespective of velocity gradients and variations. This is generally
satisfactory when the bed resistance is dominant or when modelling large ocean basins (in which
case the recommended coefficient for the constant formulation is 1 m2/s), but is not recommended
for riverine flow paths.

@1185
7.5.1.2 Smagorinsky

TUFLOW’s Smagorinsky approach (Viscosity Formulation == SMAGORINSKY) applies a

hybrid method that includes elements of both the Constant and Smagorinsky approaches, as
given by the equation below. This formulation is better than the CONSTANT option, as the eddy
viscosity is recalculated every timestep at every cell mid-side according to the change in velocity
magnitude and direction. This results in higher coefficients being applied where there is greater
turbulence.

However, this approach has two known limitations:

1. It assumes that all turbulent kinetic energy with length scales greater than the cell size is
resolved within the velocity field. This assumption is reasonable when the 2D cell size is
larger than the physical depth of the flow, but becomes incorrect when the 2D cell size is
smaller than the depth of the flow – turbulence in the vertical direction contributes significantly
to viscosity but is not resolved in the 2D velocity field. As a result, once the 2D cell size
becomes smaller than the flow depth this approach can underpredict the viscosity, and
therefore can underpredict momentum coupling from river to flood plain.
2. It assumes that the physical length scales of the sub-grid turbulence scale with the 2D cell
size. This is reasonable when the 2D cell size is similar to the depth of the flow, but becomes
incorrect when the 2D cell size becomes significantly larger than the depth of the flow – the
bed resistance and the finite depth of the flow prevent large scale turbulence. As a result,
once the 2D cell size becomes much larger than the depth of the flow, the Smagorinsky
turbulence model can overpredict the viscosity, and therefore can overpredict the momentum
coupling from river to flood plain.

The result of these two limitations, is that model results display some sensitivity to the 2D cell size.
The Wu formulation (Section 7.4.2.4 ) has proven to be more capable in its ability to provide “out
of the box” calibration and reduced sensitivity of model results to 2D cell size.

Section 7 2D Domains - 102 / 116 Page 351 / 1094

 Note, if the formulation is changed, the user must also reset the coefficient using the command
Viscosity Coefficient .

The Smagorinsky option remains the default when using TUFLOW Classic. The default viscosity
coefficients are a Smagorinsky value of 0.5 plus a constant value of 0.05 m2/s. The 0.5
Smagorinsky coefficient is dimensionless. The viscosity coefficient can be output using the Map
Output Data Types command.

The hybrid Smagorinsky formulation used by TUFLOW is:

@1186 ∂u
2
∂v
2
1 |∂u| |∂v|
2

υ = C c + C s A c √( ) + ( ) + ( + ) (7.9)
∂x ∂y 2 ∂y ∂x

Where:

u and v = Depth averaged velocity components in the X and Y directions

x and y = Distance in the X and Y direction
ν = Horizontal diffusion of momentum (viscosity) coefficient, m2/s or ft2/s
Ac = Area of Cell
C c = Constant Coefficient (default = 0.05 m2/s)
Cs = Smagorinsky Coefficient (dimensionless, default = 0.5)

@1194
7.5.2 2D Upstream Controlled Flow (Weirs and Supercritical
Flow)

Where flow in the 2D domain becomes upstream controlled, TUFLOW Classic automatically
switches between either weir flow or upstream controlled friction flow.

If Supercritical is set to ON (the default), the following rules apply.

Where the bed slope at a ZU or ZV point is in the same direction as the water surface slope,
tests are carried out to determine whether the flow is upstream controlled or downstream
controlled. The adopted flow regime is determined by comparing the upstream and
downstream controlled regime flows (preference to the lower flow) and whether the Froude
number exceeds 1 (unless changed by Froude Check ). The equation used for upstream
controlled flow is the Manning equation, with the water surface slope set to the bed slope.
This check can be disabled for backward compatibility using Froude Depth Adjustment .
Weir flow only occurs if the bed slope is adverse (different direction) to the water surface
slope. Weir flow across 2D cell sides is modelled by first testing whether the flow is upstream
or downstream controlled. If upstream controlled, the broad-crested weir flow equation is used
to replace the calculations for downstream controlled (sub-critical) flow conditions. Weir flow
can be switched off using the Free Overfall options.

Note: the bed slope at ZU and ZV points is determined as the slope from the upstream ZC point to
the ZU or ZV point in the direction of positive flow.

TUFLOW produces an increase in water level at transitions from supercritical flow to subcritical
flow, as occurs with a hydraulic jump. It does not, however, model the complex 3D flow patterns
that occur at a hydraulic jump, as it uses a 2D horizontal plane solution. Results in areas of
transition should be interpreted with caution. It is also important to be careful presenting results in

Section 7 2D Domains - 103 / 116 Page 352 / 1094

 areas of supercritical flow, as complex localised flow interactions may occur that would yield
higher localised water levels (such as supercritical flow surcharging against a building) – it is good
practice to also view the energy levels when providing advice on flood planning levels.

If Supercritical is set to OFF, and Free Overfall is set to ON (the default), weir flow may occur on
both adverse and normal bed slopes.

The weir flow switch may be adjusted globally using the .tcf command Global Weir Factor . It can
also be varied spatially over the grid by setting a weir factor of zero where there is to be no
automatic weir calculations using Read GIS WrF . The weir factor also allows calibration or
adjustment where the broad-crested weir equation is applied. The weir factor is not the broad-
crested weir coefficient. The broad-crested weir equation is divided by the weir factor. Therefore, a
factor of 1.0 represents no adjustment, while a factor greater than one will decrease the flow
efficiency. Refer to Syme (2001b ) for further information.

Note, the global weir factor and the spatially varying value are multiplied together (i.e. one
does not replace the other).

The .tcf command HX Force Weir Equation can be used to force the weir flow equation to be
applied across all active HX cell sides when the flow is upstream controlled. Note, the default
approach uses either weir flow or super-critical flow when the flow is upstream controlled,
depending on whether the ground surface gradient from HX cell centre to cell side is adverse (weir
flow) or not adverse (super-critical flow). When the flow is downstream controlled, regardless of
the ground surface slope, the full 2D equations are applied, including allowance for momentum
across the HX 1D/2D link.

@1195
7.5.3 Land Use (Materials)

For TUFLOW Classic, bed resistance can be set to Manning’s n, Manning’s M (1/n) or Chezy
using the Bed Resistance Values command in the .tcf file. Chezy can be specified as a direct
value or by bed ripple heights (using the Set FRIC , Read GIS FRIC or Read Grid FRIC
commands). The default and recommended bed resistance formulation is Manning’s n. Manning’s
n values can also be varied with depth, the VxD product or varied with depth using the Log Law
formula (see Section 7.3.6 ).

If using the Chezy formula, a number of commands have been setup to provide backward
compatibility. These are Depth/Ripple Height Factor Limit and Recalculate Chezy Interval .

@1196
7.5.4 Multiple 2D Domain

When using TUFLOW Classic with the Multiple 2D Domain Module (see Section 1.1.5.4 ), any
number of 2D domains of different cell size and orientation can be combined to form one model.
This TUFLOW Classic feature is discussed in Section 10.7.2 .

@1197
7.5.5 Coriolis Term

When using TUFLOW Classic, it is possible to include the Coriolis term in the shallow water
equations (equations (7.2) and (7.3) ). To enable this functionality, use the Latitude command.

Section 7 2D Domains - 104 / 116 Page 353 / 1094

 @1198
7.5.6 Legacy Structures

The following features are considered legacy structures and are supported by TUFLOW Classic
only. It is recommended, and preferred, to use the layered flow constriction shape (Section 7.3.8.3
) instead, which is supported by both TUFLOW Classic and TUFLOW HPC. To convert from the
flow constriction (2d_fc or 2d_fcsh) to the layered flow constriction (2d_lfcsh), refer to the
discussion published in the TUFLOW Wiki.

@1199
7.5.6.1 2D Flow Constrictions (2d_fcsh and 2d_fc)

Flow Constriction (FC) attributes allow the user to constrict the flow across a 2D cell side as a way
to define hydraulic structures, such as bridges and banks of box culverts, within a model. 2D cell
sides can be modified in the following ways:

Placing a lid (obvert or soffit) on the cell side.

Changing the flow width of the cell side.
Adding additional form (energy) losses.
Including side wall friction (“BC” FC_Type only).

Flow constrictions can be digitised within GIS layers and read into the .tgc file using the command
Read GIS FC Shape . This command is recommended over the previous (and now outdated)
Read GIS FC .

Table 7.22 describes the different 2d_fcsh layer attributes as used by Read GIS FC Shape . If
Write Check Files is set in the .tcf then the _fcsh_uvpt_check file will be created to allow you to
cross-check that the changes to the cell-sides are as intended. The _fcsh_uvpt_check file contains
information on the cell sides modified by the Read GIS FC Shape command. Details on the
properties at ALL cell sides can be found in the _uvpt_check file.

Point objects associated with the 2d_fcsh layer can be placed in a separate layer. In this case,
only the first two attributes are required. This is discussed in Section 7.3.5.7.1 .

The original Read GIS FC feature continues to be supported and its attributes are documented in
Table 7.23 . Floating pontoons should always be modelled using 2d_fc layers. If any 2d_fc inputs
are included in the model and Write Check Files is set, then the _fc_check file will be created.

Please note, overlapping flow constriction inputs are not supported.

Section 7 2D Domains - 105 / 116 Page 354 / 1094

 @1200 Table 7.22: Flow Constriction Shape (2d_fcsh) Attribute Descriptions

Default GIS Attribute

No. Description Type
Name

Invert of constriction. Using metric units

(default) the value is metres above the
elevation datum . Using Units == US
Customary, the value is feet above the
1 Invert elevation datum. Float

To leave the Zpt levels unchanged

(i.e. use the existing Zpt elevations), enter
a value of 99999.

FC_Type:

Blank or “BD”: Obvert (soffit) of

constriction in m above datum.
“BC”: Height of box culvert (m).
2 Obvert_or_BC_Height “FD”: Floating depth (m) of the deck Float
(i.e. depth below the water line).

Enter a sufficiently high value

(e.g. 99999) if there is no obvert
constriction.

Point: Not used.

Line: See same attribute in Table 7.5 for

3 Shape_Width_or_dMax Float
2d_zsh layers.

Polygon: Not used.

Point: Not used.

Line or Polygon:

MAX, RIDGE or RAISE: Only

changes a Zpt (Invert) elevation if the
Z Shape elevation at the Zpt is
higher.
MIN, GULLY or LOWER: Only
4 Shape_Options changes a Zpt (Invert) elevation if the Char(20)

Z Shape elevation at the Zpt is lower.

Line:

TIN: Indicates the line is to only be

used for generation of TINs within
polygons (only sections of TIN lines
that fall within polygons are used).

Section 7 2D Domains - 106 / 116 Page 355 / 1094

 Default GIS Attribute
No. Description Type
Name

The FC_Type.
Where:

Blank for general (does not include

allowances for any vertical walls or
friction from underside of deck).
5 FC_Type Char(2)
“BC” for Box Culverts (BC is only
available if Manning’s n option is
specified in Bed Resistance Values).
“BD” for Bridge Deck.
“FD” for Floating Bridge Deck.

The percentage blockage of the cells. For

example, if 40 is entered (i.e. 40%), the
6 pBlockage cell sides are reduced in flow width by Float
40% (i.e. is set to 0.6 times the full flow
width).

Section 7 2D Domains - 107 / 116 Page 356 / 1094

 Default GIS Attribute
No. Description Type
Name

Form Loss Coefficient (FLC) to be applied

below the FC obvert. Used for modelling
fine-scale “micro” contraction/expansion
losses not picked up by the change in the
2D domain’s velocity patterns (e.g. bridge
pier losses, vena-contracta losses, 3rd
(vertical) dimension etc.).
This parameter should be used as a
calibration parameter.

Note: So that this attribute is

independent of 2D cell size it has
different treatment depending on the
object it is attached to as follows:

Line: For thin lines, the FLC value is

applied to the cell sides unchanged.
For thick (whole cell) lines, the FLC
value is divided by two (two cell sides
in the direction of flow). For wide
lines the FLC value is divided by the
number of cells across the line
(i.e. the line’s width divided by the
7 FLC_or_FLCpm_below_Obv Float
cell size) and applied to all cell-sides.
Polygon: FLC is the form loss per
metre length (in the predominant
direction of flow). FLC values are not
dependent on the flow width, but are
on the length of travel in the direction
of flow.

However, if a negative FLC value is

specified, the absolute value is taken
and applied unadjusted to all cell-sides
affected by the shape. Note, this is not
cell size independent, therefore if the
2D cell size is changed, this attribute
also needs to be changed.

The form loss coefficient is applied as an

energy loss based on the dynamic head
equation below where ζa is the FLC
value.

2
V
Δh = ζa
2g

Section 7 2D Domains - 108 / 116 Page 357 / 1094

 Default GIS Attribute
No. Description Type
Name

Form Loss Coefficient (FLC) to be applied

above the FC obvert. See
8 FLC_or_FLCpm_above_Obv Float
FLC_below_Obvert attribute above for
more information.

For box culverts (BC), the Manning’s n of

the culverts (typically 0.011 to 0.015)
should be specified. This value prevails
over any other bed resistance values
irrespective of where in the .tgc file they
occur (the exception is if another FC BC
object overrides this one). If set to less
than 0.001, a default value of 0.013 is
used.

For bridge decks (BD), can be used to

introduce additional flow resistance once
the upstream water level reaches the
bridge deck obvert (or soffit).

For floating decks (FD) this is always the

9 Mannings_n case as the deck soffit is permanently Float

submerged. The additional flow

resistance is modelled as an increase in
bed resistance by increasing the wetted
perimeter at the cell mid-side by a factor
equal to (2.*Bed_n)/FC_n. For example, if
the FC Manning’s n and the bed
Manning’s n values are the same, the
wetted perimeter is doubled, thereby
reducing the conveyance and increasing
the resistance to flow. This parameter can
be used as a calibration parameter to
fine-tune the energy losses across a
bridge or floating structure.

Ignored for blank FC_Type.

The width of one BC culvert barrel in

metres. For example, if there are 10 x
1.8metre wide culverts in a bank, enter a
value of 1.8. Using metric units (default)
10 BC_Width the value is in metres. Using Units == Float

US Customary, the value is in feet.

Applicable to BC FC_Type only. Not used

by other types of FCs.

Section 7 2D Domains - 109 / 116 Page 358 / 1094

 @1203 Table 7.23: Flow Constriction (2d_fc) Attribute Descriptions

Default GIS Attribute

No. Description Type
Name

Secondary flag identifier where:

Blank for general (does not include

allowances for any vertical walls or
friction from underside of deck).
1 Type “BC” for Box Culverts (BC is only Char(2)
available if Manning’s n option is
specified in Bed Resistance Values).
“BD” for Bridge Deck.
“FD” for Floating Bridge Deck.

Invert of constriction (m above datum).

Mandatory for box culverts (type = “BC”).

2 Invert If not a box culvert, and you wish to leave the Float
Zpt levels unchanged (i.e. use the existing
Zpt elevations), enter a value greater than
the obvert level (see next attribute).

Type:

Blank or “BD”: Obvert of constriction (m

above datum)
“BC”: Height of box culvert (m). Values
less than 0.01 are set to 0.01.

3 Obvert_or_BC_height “FD”: Floating depth (m) of the deck Float

(i.e. depth below the water line).

Enter a sufficiently high value (e.g. 99999) if

there is no obvert constriction.

If using Units == US Customary, the

height unit is in feet.

Flow width constriction factor in the X-

direction (i.e. the flow width perpendicular to
the X-direction). For example, a value of 0.6
sets the flow width at the left hand and right-
4 u_width_factor hand sides of the cell to 60% of the cell Float
width. Values less than 0.001 are set to 1.
Use a value of 1.0 to leave the flow width
unchanged. Values greater than 1 can be
specified.

Width constriction factor in the Y-direction.

5 v_width_factor Float
See description above for u_width_factor.

Section 7 2D Domains - 110 / 116 Page 359 / 1094

 Default GIS Attribute
No. Description Type
Name

Form loss coefficient. Used for modelling

fine-scale “micro” contraction/expansion
losses not picked up by the change in the 2D
domain’s velocity patterns (e.g. bridge pier
losses, vena-contracta losses, 3rd (vertical)
dimension etc.).

Can be used as a calibration parameter.

The form loss coefficient is applied as an

6 Add_form_loss Float
energy loss based on the dynamic head
equation below where ζa is the
add_form_loss value. The form loss
coefficient is applied 50/50 to the right and
left sides (u-points) of the cell, and similarly
to the v-points.

2
V
Δh = ζa
2g

For box culverts (BC), the Manning’s n of the

culverts (typically 0.011 to 0.015) should be
specified. This overwrites any previously
specified Manning’s n values at the cell’s
mid-sides. If set to less than 0.001, a default
value of 0.013 is used.

For bridge decks (BD), can be used to

introduce additional flow resistance once the
upstream water level reaches the bridge deck
obvert or soffit. For floating decks (FD) this is
always the case as the deck soffit is
permanently submerged. The additional flow
7 Mannings_n Float
resistance is modelled as an increase in bed
resistance by increasing the wetted perimeter
at the cell’s mid-sides by a factor equal to
(2.*Bed_n)/FC_n. For example, if the FC
Manning’s n and the bed Manning’s n values
are the same, the wetted perimeter is
doubled, thereby reducing the conveyance
and increasing the resistance to flow. To be
used as a calibration parameter to fine-tune
the energy losses across a bridge or floating
structure.

Ignored for “Blank” type FC.

Section 7 2D Domains - 111 / 116 Page 360 / 1094

 Default GIS Attribute
No. Description Type
Name

Number of vertical walls per grid cell. If set to

zero (between 0.001 and 0.001) one vertical
wall per cell is used. A non-integer value can
be specified.

Alternatively, and more easily, specify the

width of one culvert in metres by using a
8 No_walls_or_neg_width Float
negative value. For example, if the culverts
are 1.8m wide, enter a value of 1.8 and the
number of vertical walls per cell is
automatically calculated.

Applicable to Box Culverts only. Not used by

other types of FCs.

Indicates whether any of the walls of the

constricted cell(s) are blocked off (i.e. no flow
across/through the side wall). Specify one or
more of the following letters in any order with
in the field to indicated which wall(s) are
blocked:
9 Blocked_sides Char(10)
“R” – block right hand side wall
“L” – block left hand side wall
“T” – block top side wall
“B” – block bottom side wall

Note: the quotes should be omitted.

10 Invert_2 leave blank (not used as yet) Char(10)

11 Obvert_2 leave blank (not used as yet) Char(10)

Optional field for entering comments. Not

12 Comment Char(250)
used.

@1206
7.5.6.2 Applying Form (Energy) Loss in 2D FC and FCSH Layers

The following should be noted when adapting structure loss coefficients from a 1D model or from
coefficients that apply across the entire waterway, for example, from “Hydraulics of Bridge
Waterways” (Bradley, 1978 ) or “Guide to Bridge Technology Part 8, Hydraulic Design of
Waterway Structures” (Austroads, 2018 ):

The TUFLOW 2D solution automatically predicts the majority of “macro” losses due to the
expansion and contraction of water through a constriction, or around a bend, provided the
resolution of the grid is sufficiently fine (Barton, 2001 ; Syme, 2001b ).
Where the 2D model is not of fine enough resolution to simulate the “micro” losses (e.g. from
bridge piers, vena contracta, losses in the vertical (3rd) dimension), additional form loss
coefficients and/or modifications to the cells widths and flow height need to be added. This

Section 7 2D Domains - 112 / 116 Page 361 / 1094

 can be done by using flow constrictions (FC cells). Additional form loss can also be added
using Read GIS FLC or the command Read Grid FLC .
The additional or “micro” losses, which may be derived from information in publications, such
as Hydraulics of Bridge Waterways, need to be either:
Distributed evenly over the FC cells across the waterway by dividing the overall additional
loss coefficient by the number of cells (in the direction of flow); or
Assigned unevenly (e.g. more at the cells with the bridge piers), however, the total of the
loss coefficients should be equivalent to the required overall additional loss coefficient.
The head loss across key structures should be reviewed, and if necessary, benchmarked
against other methods. Note that a well-designed 2D model will be more accurate than a 1D
model, provided that any “micro” losses are incorporated.
Ultimately the best approach is to calibrate the structure through adjustment of the additional
“micro” losses – but this, of course, requires good calibration data!

An example of how to apply 2D FCs and a 2D FCSH to a bridge structure is shown in Figure 7.33
and Figure 7.34 . The loss coefficient quoted in the figure is an example. Every structure
is invariably different, and as such require structure specific parameters!

When applying FCs, the best approach is to view the structure as a collection of 2D cells
representing the whole structure, rather than being too specific about the representation of each
individual cell. A good approach is to use a 2d_po layer to extract time histories of the water levels
upstream and downstream of the structure and of the flow and flow area upstream, downstream
and through the structure (see Section 11.3.2 ).

Of particular importance is to check that the correct flow area through the structure is being
modelled. Digitise a 2d_po QA line through the structure from bank to bank and use this output to
cross-check the flow area of the 2D FC cells is appropriate (the QA line will take into account any
adjustments to the 2D cells due to FC obverts and changes to the cell side flow widths). If the
overall structure flow area is not correct, then the velocities within the structure will not be correct
and therefore the energy losses due to the changes in velocity direction and magnitude and
additional form losses will not be well modelled.

@1207

Section 7 2D Domains - 113 / 116 Page 362 / 1094

 Figure 7.33: Setting FC Parameters for a Bridge Structure
@1208

Figure 7.34: Setting FCSH Parameters for a Bridge Structure

Section 7 2D Domains - 114 / 116 Page 363 / 1094

 @1209
7.5.7 Unsupported Features in TUFLOW Classic

The following features are not supported in TUFLOW Classic. TUFLOW HPC is required to access
these features:

Parallelisation / utilising GPU Hardware (Section 1.1.5.3 )

Wu turbulence approach (Section 7.4.2.4 )
Topography Sub-grid Sampling (Section 7.4.3 )
Quadtree grid refinement (Section 7.4.1 )
Groundwater with multiple sub-surface layers and horizontal hydraulic conductivity (Section
7.4.5.2 )
Non-Newtonian Flow (Section 7.4.6 )

References

@1211
@1210
Austroads. (2018). Guide to Bridge Technology Part 8, Hydraulic Design of Waterway Structures.
https://austroads.com.au/

@1212 C. (2001). Flow Through an Abrupt Constriction – 2D Hydrodynamic Model Performance

Barton,
and Influence of Spatial Resolution (C. Barton, Ed.) [M.Eng.Sc Master Thesis].
https://tuflow.com/media/4983/2001-flow-through-an-abrupt-constriction-2d-hydrodynamic-
performance-and-influence-of-spatial-resolution-barton-thesis.pdf

@1213 C. (2014). The Application of Direct Rainfall Models as Hydrologic Models Incorporating
Boyte,
Hydraulic Resistance at Shallow Depths [B.Eng Thesis]. https://tuflow.com/media/5009/2014-
the-application-of-direct-rainfall-models-as-hydrologic-models-incorporating-hydraulic-
resistance-at-shallow-depths-boyte-thesis.pdf

@1214 J. (1978). Hydraulics of Bridge Waterways (HDS 1, FIWA). Bridge Division.

Bradley,
https://www.fhwa.dot.gov/engineering/hydraulics/pubs/hds1.pdf

@1215
Collecutt, G., Baeumer, U., Gao, S., & Syme, W. (2022). Bridge Deck Afflux Modelling –
Benchmarking of CFD and SWE Codes to Real-World Data. Hydrology & Water Resources
Symposium. https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-
of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf

@1216 G., Gao, S., & Syme, W. (2020). Mesh-Size Insensitive Turbulence Modelling for the 2D
Collecutt,
Shallow Water Equations. River Flow 2020, pp. 1–9. https://tuflow.com/media/5023/2020-
mesh-size-insensitive-turbulence-modelling-for-the-2d-shallow-water-equations-collecutt-et-al-
iahr-river-flow-delft.pdf

@1217
Collecutt, G., & Syme, B. (2017). Experimental Benchmarking of Mesh Size and Time-Step
Convergence for a 1st and 2nd Order SWE Finite Volume Scheme. Proceedings of the 37th
IAHR World Congress.
@1218 G. (1984). On the Construction of Computational Methods for Shallow Water Flow
Stelling,
Problems. Rijkswaterstaat Communications.

Section 7 2D Domains - 115 / 116 Page 364 / 1094

 @1219 W. (2001b). TUFLOW – Two & One-Dimensional Unsteady FLOW Software for Rivers,
Syme,
Estuaries and Coastal Waters. The Institution of Engineers, Australia 2D Seminar.
https://tuflow.com/media/4985/2001-tuflow-two-and-one-dimensional-unsteady-flow-software-
for-rivers-estuaries-and-coastal-waters-syme.pdf

@1220W. (2008). Flooding in Urban Areas - 2D Modelling Approaches for Buildings and Fences.
Syme,
Engineers Australia, 9th National COnference on Hydraulics in Water Enginnering.
https://tuflow.com/media/4997/2008-flooding-in-urban-areas-2d-modelling-approaches-for-
buildings-and-fences-syme-hwe-aus.pdf

@1221 (1986). Urban Hydrology for Small Watersheds Technical Release 55 (TR-55).
USDA.
https://nationalstormwater.com/wp/wp-content/uploads/2020/07/Urban-Hydrology-for-Small-
Watersheds-TR-55.pdf

@1222
Wu, W., Shields Jr., F. D., Bennett, S. J., & Wang, S. S. Y. (2005). A Depth-Averaged Two-
Dimensional Model for Flow, Sediment Transport, and Bed Topography in Curved Channels
with Riparian Vegetation. Water Resources Research, 41(3).
https://doi.org/https://doi.org/10.1029/2004WR003730

@1223
Figure
2. courtesy of University of Texas
https://www.caee.utexas.edu/prof/mckinney/ce374k/Overheads/10-
Infiltration.pdf#page=20↩︎

Section 7 2D Domains - 116 / 116 Page 365 / 1094

 @1228

@1229
Section 8 Boundaries and Initial Conditions

@1230
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.

@1231
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

Section 8 Boundaries and Initial Conditions - 1 / 55 Page 366 / 1094

 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.

Section 8 Boundaries and Initial Conditions - 2 / 55 Page 367 / 1094

 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.

@1232 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

QT as point on
River/Creek Inflow QT line (preferred) or SA region
inflow node.

Local Catchment QT as regions (flow SA.

Inflows around the is distributed Use SA with PITS option for directing
edge of model or between nodes inflows directly to 1d pits (also referred to as
within model. within a region) gully traps).

Direct Rainfall
No option at present RF or possibly SA (with RF option).
(No Hydrology Inflows)

SA or QT. SA may offer greater stability and

Dambreak Hydrograph QT better mass error if mass errors occur using
QT.

1D linked via SX preferred.

Pumps P (Pump) channel
SH possible

No option at present Specify rainfall losses on a materail basis

other than (Section 7.3.6.4 ) or use the soil infiltration
Infiltration
specifying a feature (Section 7.3.7 ). Alternatively, RF
negative QT. can be used by specifying negative values.

2D HT if on the surface or specify a GT

Groundwater Level HT level when using Interflow functionality for
sub-surface groundwater level.

Section 8 Boundaries and Initial Conditions - 3 / 55 Page 368 / 1094

 @1233
8.3 Solver Specific Considerations

@1234
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.

@1235
8.3.2 HPC Specific Boundaries / Options

@1236
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:

Section 8 Boundaries and Initial Conditions - 4 / 55 Page 369 / 1094

 ¯2
@1237 v − v
2
i
hi = H (t) + (8.1)
2g

Where:

H (t) is the user define height vs time boundary data

¯2
v is the mean square flow velocity averaged over boundary cells that are inflowing
v
2
i
is the magnitude squared of flow velocity at the boundary cells
hi 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}

@1243 Table 8.2: HPC Boundary Approach Descriptions

Method Description

Method A No energy corrections applied (backward compatible)

Energy correction applied for:

HT and HQ boundaries
Method B QT boundaries
HX boundaries connected to a single 1D node (refer Section 10.2.1
)

Energy correction applied for:

Method C
HT and HQ boundaries
(default)
QT boundaries

@1244
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.

Section 8 Boundaries and Initial Conditions - 5 / 55 Page 370 / 1094

 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

@1245
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:

(F − 1)Qf ,i−1 + Qi
Qf ,i =
F

Where:

Qf ,i is the filtered boundary flow at timestep i (initialised as zero)

Qi 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 from the 2025.0.0 release is 5, prior to this it was 1
(meaning no filtering).

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

@1252
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}

@1253
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:

Section 8 Boundaries and Initial Conditions - 6 / 55 Page 371 / 1094

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

@1254
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.

Section 8 Boundaries and Initial Conditions - 7 / 55 Page 372 / 1094

 @1255 Table 8.3: 1D Boundary Condition and Link Types

Type Description Comments

Water Level

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 ).

Water Level An automatically generated HQ curve based on the

(Head) cross-sectional properties and a specified friction slope.

HQ Specify “slope=friction_slope” (e.g. slope=0.01) for the
versus Flow
(m) “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.

Assigns a water level to the node based on a water level

Water Level versus time curve using the 1d_bc GIS layer ““Name””
(Head) attribute (Table 8.4 ) and the boundary database (Section
HT
versus Time 8.6 ). If other HT or HS boundaries are applied to the
(m) node, the water level is set to the sum of the water level
boundaries.

1D nodes can be wet or dry. If the water level is below the

bed, computationally the bed level is assigned as the water
Treatment 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.

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
Combinations 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.

Section 8 Boundaries and Initial Conditions - 8 / 55 Page 373 / 1094

 Type Description Comments

Flow

Assigns a flow to the node based on the water level of the

Flow vs
node at the previous half timestep using the 1d_bc GIS
QH Water Level
layer ““Name”” attribute (Table 8.4 ) and the boundary
(Head) (m3/s)
database (Section 8.6 ).

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.

Flow versus A region (polygon) can be used to equally distribute the flow
QT hydrograph to all nodes that fall within the region. Any
Time (m3/s)
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).

The 1D node can be wet or dry.

The storage of the 1D node influences the results. If the

Treatment node storage is made excessively large, the flow
hydrograph is attenuated. Conversely, if it is under-sized the
node is likely to be unstable.

Any number of 1D flow boundaries can be assigned to the

same node. The final flow is the sum of the flows assigned.

Combinations 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.

Section 8 Boundaries and Initial Conditions - 9 / 55 Page 374 / 1094

 @1256 Table 8.4: 1D Boundary Conditions (1d_bc) Attribute Descriptions

Default GIS
No. Attribute Description Type
Name

The type of BC using one of the two letter flags

1 Type Char(2)
described in Table 8.3 .

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.
2 Flags Char(6)
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.

The name of the BC in the BC Database (see Section

8.6 ). An error will be generated if no name is
specified.
3 Name Char(50)
Note for automatic calculation of HQ boundary a slope
can be specified with keyword “slope=slope in m/m”.
Refer to Table 8.3 .

4 Description Optional field for entering comments. Not used. Char(250)

@1257
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 .

Section 8 Boundaries and Initial Conditions - 10 / 55 Page 375 / 1094

 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 a QT or H boundary.

Section 8 Boundaries and Initial Conditions - 11 / 55 Page 376 / 1094

 @1258 Table 8.5: 2D Boundary Condition and Link Types

Type Description Comments

Water Level
Boundaries

Assigns a water level to the cell(s) based on a water

level versus flow (stage-discharge) curve. Alternatively,
Water Level TUFLOW can automatically generate the HQ curve if a
HQ (Head) versus slope is specified using the 2d_bc GIS layer “b” attribute
Flow (Q) (see Table 8.6 ). The variation in Manning’s n with
depth feature is taken into account if automatically
calculating the stage-discharge curve.

Water Level Assigns a water level to the cell(s) based on a water

HT (Head) versus level versus time curve. Uses the 2d_bc GIS layer (See
Time Section 8.5.1 ).

For linking 1D and 2D domains. One or two 1D nodes

provide a water level to the 2D every half timestep.
Water Level
TUFLOW automatically creates 1D QX boundaries at the
(Head) from an
1D node(s) (see Table 8.3 ), which also receives flow
HX eXternal
from the 2D domain every half timestep. 2D HX
Source (i.e. a
boundaries are linked to 1D nodes using CN
1D model)
connections (see below and Figure 10.4 ). Uses the
2d_bc GIS layer (See Section 8.5.1 ).

Multiple domain boundary only available for TUFLOW

Links two 2D
2D Classic. Refer to Section 10.7.2 . Uses the 2d_bc GIS
domains
layer (See Section 8.5.1 ).

Sinusoidal Legacy boundary condition, available for Classic solver

HS (Tidal) Water only. HT boundary is the recommended alternative.
Level (m) Refer to the 2018 TUFLOW Manual for further details.

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.

Treatment 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.

Section 8 Boundaries and Initial Conditions - 12 / 55 Page 377 / 1094

 Type Description Comments

Multiple water level boundaries that select the same cell

are not recommended. For TUFLOW Classic, multiple
Combinations 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

Assigns a groundwater level to the cell(s) based on a

groundwater level versus time curve.

Groundwater The same groundwater level boundary applies to all

GT Level versus vertical soil layers. If the specified groundwater level is

Time 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
(Directional)
Boundaries

Distributes flow in quantity and direction across the

cell(s) based on their topography, bed roughness and
whether upstream or downstream controlled flow. The
limiting assumption is that the water level along the line
is constant, therefore, the line must be digitised roughly
Flow versus
QT perpendicular to the flow and should avoid areas where
Time (m3/s)
significant super-elevation or other similar effects occur.

Cells can wet and dry, the line can be oblique to the grid.

Multiple QT boundaries should not be applied to the

same cell.

Flow (non-
Boundaries Directional)

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
Rainfall versus period to another (the converted hydrograph appears in
Time (mm) the .tlf file for cross-checking). Note: the input curve is
RF Infiltration not mm/h versus timestep, but mm vs timestep
versus Time (i.e. each rainfall value is the amount of rain that fell
(mm) in mm between the previous time and the current
time).

Uses the 2d_rf GIS layer (see Section 8.5.3 ).

Section 8 Boundaries and Initial Conditions - 13 / 55 Page 378 / 1094

 Type Description Comments

Applies the flow directly onto the cells within the polygon

Flow versus as a source. Negative values remove water directly from

Time (m3/s) the cell(s). Most commonly used to model rainfall-runoff

over an area, directly onto 2D domains with each polygon representing

SA the sub-catchment of a hydrology model. SA boundaries
or
Rainfall versus have their own command, Read GIS SA , and own GIS

Time (mm) layer, 2d_sa.

Uses the 2d_sa GIS layer (see Section 8.5.2 ).

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
Flow versus below). In the boundary condition database, the Column
SD
Depth or Head 1 data would be depth (SD) or water level (SH) values
SH 3
(m /s) 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.

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
Flow versus
ST specifies 2 m3/s and the ST is applied over four cells,
Time (m3/s)
then the total flow applied to the model would be 8 m3/s.
If the total flow required is 2 m3/s, then an f attribute of
0.25 could be applied so that only 0.5 m3/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.

Section 8 Boundaries and Initial Conditions - 14 / 55 Page 379 / 1094

 Type Description Comments

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
Source of flow pipe in the 2D domain “sucks” water out of the upstream
SX from a 1D cell(s) and “pours” water back out at the downstream
model. 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).

Sources are applied to all the specified cell(s) whether

they are wet or dry, except for SA and SX, which apply
Treatment 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 ).

Any number of source boundaries can be assigned to

the same cell(s) whether they are SA, SD, SH, ST or SX.
Combinations
The source rate applied is the sum of the individual
sources.

Connections

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.
Connection of
An ERROR occurs if a CN object is not snapped to a 2D
2D HX and 2D
CN HX or 2D SX object, or is redundant (i.e. not needed).
SX boundaries
For backward compatibility, use Unused HX and SX
to 1D nodes
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.

Section 8 Boundaries and Initial Conditions - 15 / 55 Page 380 / 1094

 Type Description Comments

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
Connection of
water is to be transferred to. Uses the 2d_bc GIS layer
SC 2D SD and SH
(see Section 8.5.1 ).
boundaries
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

Legacy boundary condition and not recommended for

Modelling Wind use. Suggest use of the cyclone/hurricane (See Section

Stresses as a 8.7 ) or external stress boundary (See Section 8.8 )

WT instead.
force on the
water column Refer to the 2018 TUFLOW Manual for details on WT
boundary.

Variable
Geometry

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.
Modelling of
VG Also see Section 7.3.5.3 on Variable Z Shape layers as
breaches, etc.
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

Section 8 Boundaries and Initial Conditions - 16 / 55 Page 381 / 1094

 Type Description Comments

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 ).

CD Code Polygon 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.

An object in a GIS 2d_bc layer (see Section 8.5.1 ) can

IG Ignore
be elected to be ignored by using the “IG” type.

Point objects that are used for setting elevations along

HX lines. Only used by Read GIS Z HX Line which is
ZP Elevation Point
specified in the geometry control file. See Section 8.5.1
.

@1259
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.

@1260

Figure 8.1: Cell Cross-hair Selection Approach

Section 8 Boundaries and Initial Conditions - 17 / 55 Page 382 / 1094

 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.

Section 8 Boundaries and Initial Conditions - 18 / 55 Page 383 / 1094

 @1261 Table 8.6: 2D Boundary Conditions (2d_bc) Attribute Descriptions

Default
GIS
No. Description Type
Attribute
Name

The type of BC using one of the two letter flags described

1 Type Char(2)
in Table 8.5 . Also see Blank BC Type .

Section 8 Boundaries and Initial Conditions - 19 / 55 Page 384 / 1094

 Default
GIS
No. Description Type
Attribute
Name

2 Flags Optional flags as follows: Char(3)

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

Section 8 Boundaries and Initial Conditions - 20 / 55 Page 385 / 1094

 Default
GIS
No. Description Type
Attribute
Name

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.

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

3 Name Char(100)
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.

Section 8 Boundaries and Initial Conditions - 21 / 55 Page 386 / 1094

 Default
GIS
No. Description Type
Attribute
Name

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.13 ).

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,
4 f set f to one (1). An f value of zero (less than 0.001) is set to Float
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.

Section 8 Boundaries and Initial Conditions - 22 / 55 Page 387 / 1094

 Default
GIS
No. Description Type
Attribute
Name

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.13 ).

HX, ZP: Used to adjust the elevations up or down by the

amount of the d attribute. Performs a similar function to the
5 d Float
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.

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.13 ).

6 td HS: Incremental phase lead or lag in degrees per cell along Float
the boundary.

SX: Reserved – set to zero.

CD, CN, HX, QC, VC, ZP, GT: Not used.

Section 8 Boundaries and Initial Conditions - 23 / 55 Page 388 / 1094

 Default
GIS
No. Description Type
Attribute
Name

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 (hn) is adjusted
according to:

hn = h1 (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 nth cell along the boundary the
amplitude (A) is adjusted according to:

An = An−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
7 a Float
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.

Section 8 Boundaries and Initial Conditions - 24 / 55 Page 389 / 1094

 Default
GIS
No. Description Type
Attribute
Name

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.13 ).

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.

8 b HS: Incremental amount added per cell to the mean water Float
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.

@1265
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 .

@1266

Section 8 Boundaries and Initial Conditions - 25 / 55 Page 390 / 1094

 Figure 8.2: Sloping Water Level Boundaries

@1267
8.5.1.2 Groundwater Boundaries

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

1. Sealed boundary, no inflow or outflow (default in absence of defined boundary); and

2. 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.

@1268
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 .

@1269 Source Area Options (2d_sa)

8.5.2.1

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 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.

Section 8 Boundaries and Initial Conditions - 26 / 55 Page 391 / 1094

 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

@1270 Table 8.7: 2D Source over Area (2d_sa) Attribute Descriptions

Default
GIS
No. Description Type
Attribute
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,

1 Name these boundaries are treated separately; as if they were Char(100)

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.

@1271 Streamlines
8.5.2.1.1

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

Section 8 Boundaries and Initial Conditions - 27 / 55 Page 392 / 1094

 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, as shown in Table 8.8 . 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. Alternatively, use the ‘Insert TUFLOW Attributes to existing
GIS layer’ tool within the QGIS TUFLOW Plugin.

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.

@1272 Table 8.8: Streamlines (2d_strm) Attribute Descriptions

Default GIS Attribute

No. Description Type
Name

The stream order. Objects with a stream order

1 Stream Order Integer
greater than 0 are used.

@1273 Rainfall Option (2d_sa_rf)

8.5.2.2

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.

Section 8 Boundaries and Initial Conditions - 28 / 55 Page 393 / 1094

 @1274 Table 8.9: 2D Source over Area Rainfall (2d_sa_rf) Attribute Descriptions

Default GIS
No. Description Type
Attribute 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

1 Name treated separately; as if they were different Char(100)

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.

Additional attribute for the RF Option (Read GIS

SA RF Command).

The contributing catchment area in m2 (if using

SI units) or miles2 (if using Units == US
Customary).
2 Catchment_Area Float
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.

A multiplier that allows for adjusting the rainfall

due to spatial variations in the total rainfall.

3 Rain_Gauge_Factor A value of zero will cause ERROR 2460 and the Float

simulation will halt, see also Zero Rainfall Check

command.

The Initial Loss amount in mm on inches (if

4 IL Float
using Units == US Customary).

The Continuing Loss rate in mm/hr or inches/hr

5 CL Float
(if using Units == US Customary).

@1275
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

Section 8 Boundaries and Initial Conditions - 29 / 55 Page 394 / 1094

 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.10 . 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).

Section 8 Boundaries and Initial Conditions - 30 / 55 Page 395 / 1094

 @1276 Table 8.10: 2D Source over Area Trigger (2d_sa_tr) Attribute Descriptions

Default GIS
No. Description Type
Attribute 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
1 Name treated separately; as if they were different Char(100)

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.

Trigger_Type must be set to “Q_” or “Flow” for a

2 Trigger_Type trigger based on a flow rate, or “H_” or “Level” for a Char(40)
trigger based on a water level.

Trigger_Location is the PO Label in a 2d_po layer

(see Section 11.3.2.1 ). The 2d_po Type attribute
3 Trigger_Location Char(40)
must also be compatible with the Trigger_Type
(i.e. it must include Q_ or H_ as appropriate).

Trigger_Value is the flow or water level value that

4 Trigger_Value Float
triggers the start of the SA hydrograph.

@1277
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:

1. Create a 2d_po point object of Type “H_” at the water level location.
2. Add “Read GIS PO == …” to the .tcf file if not already there.
3. Create a new 2d_sa_po layer, as listed in Table 8.11 . 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
4. 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_”.

Section 8 Boundaries and Initial Conditions - 31 / 55 Page 396 / 1094

 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.
5. 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:

1. View the _MB.csv files. The SA in/outflow from the seepage or infiltration will be part/all of the
SS columns.
2. 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.

@1278Table 8.11: 2D Source over Area Flow Feature (2d_sa_po) Attribute Descriptions

Default
GIS
No. Description Type
Attribute
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,

1 Name these boundaries are treated separately; as if they were Char(100)

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.

PO_Type must be set to “Q_” to set the SA flow in/out of a

2 PO_Type model based on a flow rate, or “H_” to base it on a water Char(16)
level.

PO_Label is the Label attribute in a 2d_po layer (see

Section 11.3.2.1 ). The 2d_po Type attribute must also
3 PO_Label Char(40)
be compatible with the PO_Type (i.e. it must include Q_
or H_ as appropriate).

@1279
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.

Section 8 Boundaries and Initial Conditions - 32 / 55 Page 397 / 1094

 @1280
8.5.3 Rainfall Boundaries

@1281
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.

@1282
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.6 . 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.

Section 8 Boundaries and Initial Conditions - 33 / 55 Page 398 / 1094

 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.

@1283
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.

@1284 Rainfall Polygons (2d_rf)

8.5.3.4

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.12 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

Section 8 Boundaries and Initial Conditions - 34 / 55 Page 399 / 1094

 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.

Section 8 Boundaries and Initial Conditions - 35 / 55 Page 400 / 1094

 @1285 Table 8.12: 2D Direct Rainfall over Area (2d_rf) Attribute Descriptions

Default GIS
No. Attribute Description Type
Name

The name of the rainfall1 BC in the BC Database (see

Section 8.6 ).

1 Name Note: If two or more RF inflows of the same Name Char(100)

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.

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

2 f1 Float
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.

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

3 f2 2d_rf polygons or points in a Rainfall Control File Float
(.trfc).

A value of zero will cause ERROR 2460 and the

simulation will halt, see also Zero Rainfall Check
command.

@1286
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

Section 8 Boundaries and Initial Conditions - 36 / 55 Page 401 / 1094

 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 2nd rainfall grid should be the total rainfall
depths from time 0 to time 0.17 hours (i.e. not the rainfall intensity in mm/h or inch/h).

@1287

Figure 8.3: Example Rainfall Database

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

@1288
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 .

@1289

Section 8 Boundaries and Initial Conditions - 37 / 55 Page 402 / 1094

 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.

@1290
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:

1. A database or list of BC events, including information on where to find the BC data.

2. One or more files containing the boundary data (e.g. flow, level, rainfall data).

Section 8 Boundaries and Initial Conditions - 38 / 55 Page 403 / 1094

 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.13 .
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.13 . 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.

Section 8 Boundaries and Initial Conditions - 39 / 55 Page 404 / 1094

 @1291 Table 8.13: BC Database Keyword Descriptions

Default
Keyword Description
Column

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
Name time-series data in the file containing the hydrographs. In this N/A

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.

Section 8 Boundaries and Initial Conditions - 40 / 55 Page 405 / 1094

 Default
Keyword Description
Column

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
Source write data using this format. N/A
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 9th 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.

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
Column 1 Mean Water Level for each wave component in a 2D HS 3
or Time (sinusoidal wave) boundary.

For all other types of Source entry (including FEWS .csv), leave
this field blank.

Section 8 Boundaries and Initial Conditions - 41 / 55 Page 406 / 1094

 Default
Keyword Description
Column

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
Column 2
file also supports event ensembles. For this an optional 3rd
or Value or 4
argument can be specified defining the ensemble ID. In the 1st
ID
boundary database entries below a FEWS .csv file is specified with
the location ID “Location1” and the parameter ID “Q.sim.hist”. The
2nd 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.

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
Add Col 1 change to the time values.
or 5
For external wind stress boundaries (.tesf), used to define the wind
TimeAdd
direction (degrees relative to East, ie. East = 0º, North = 90º, etc.).

This field is ignored for Blank Source entries.

A multiplication factor to apply to the Column 2 values. If left blank

Mult Col 2 or one (1), there is no change to the values. Note, Mult Col 2 is
or applied before Add Col 2 below. 6
ValueMult
This field is ignored for Blank Source entries.

An amount to add to Column 2 values. If left blank or zero, there is

Add Col 2 no change to the values. Note, Add Col 2 is applied after Mult Col

or 2. For example, this could be used to add a base flow to a QT 7

ValueAdd boundary or sea level rise allowance for a HT boundary.

This field is ignored for Blank Source entries.

Section 8 Boundaries and Initial Conditions - 42 / 55 Page 407 / 1094

 Default
Keyword Description
Column

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
Column 3 each wave component in a 2D HS (sinusoidal wave) boundary. 8

For all other types of Source entries, leave this field blank.

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
Column 4 component in a 2D HS (sinusoidal wave) boundary. 9

For all other types of Source entries, leave this field blank.

@1292
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.13 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 ).

@1293

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

@1294

Section 8 Boundaries and Initial Conditions - 43 / 55 Page 408 / 1094

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

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

@1296
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.

Section 8 Boundaries and Initial Conditions - 44 / 55 Page 409 / 1094

 @1297

Figure 8.8: Example BC Database Using Event Text

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

@1298

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.

@1299
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.

Section 8 Boundaries and Initial Conditions - 45 / 55 Page 410 / 1094

 Please let [email protected] know if you have suggestions for a boundary conditions
generators

@1300
8.6.4 Delft FEWS Boundaries

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

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 ).

@1301
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

Section 8 Boundaries and Initial Conditions - 46 / 55 Page 411 / 1094

 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.

@1302

Figure 8.10: Example DSS File

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

1. Provide the filename in the “Source” column.

2. Leave “Column 1”, which is used for time, blank (DSS files store the time with the curve
values).
3. 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.
4. 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 (/).

@1303

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.

Section 8 Boundaries and Initial Conditions - 47 / 55 Page 412 / 1094

 @1304
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 == ⟨gis layer⟩

Read GIS Hurricane == ⟨gis layer⟩

This command can be used to read a cyclone, hurricane or typhoon track. The attributes of the
GIS layer are listed in Table 8.14 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 == ⟨gis layer⟩ will only apply the pressure
field and ignore the wind.

@1311 Table 8.14: GIS Attribute Details for Cyclone (2d_cyc) layer

Default GIS
No. Description Type
Attribute Name

1 Time Time in hours. Float

2 p0 Pressure at the eye (hPa). Float

3 pn Pressure of surrounds (hPa). Float

Radius to maximum winds (m) (or ft if using Units ==

4 R Float
US Customary).

5 B See Queensland Government (2001 ). Float

Density of Air (kg/m3) (or lb/ft3 if using Units == US

6 ρair Float
Customary). If zero, Density of Air is used.

Density of Air (kg/m3) (or lb/ft3 if using Units == US

7 km Float
Customary). If zero, Density of Air is used.

8 ThetaMax See Queensland Government (2001 ). Float

9 DeltaFM See Queensland Government (2001 ). Float

Background wind speed in m/s (or ft/s if using Units

10 bw_speed == US Customary). Ignored if less than or equal to Float
zero.

Background wind direction in degrees relative to East

11 bw_dirn Float
(0°), North (90°), etc..

Section 8 Boundaries and Initial Conditions - 48 / 55 Page 413 / 1094

 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 == ⟨latitude value⟩”).

@1315
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:

1. Time (h)
2. Wind (m/s)
3. 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) .

@1316 τ = C10 ρair U10 (8.2)

Where:

τ = shear stress in N/m2.

ρ
air
= density of air in kg/m3.
U10 = wind velocity at 10m above the mean water surface in m/s.
C10 = wind stress coefficient and is calculated using equation (8.3) based on J. Wu (1980 )
and J. Wu (1982 ).

@1322 C10 = (0.8 + 0.065 U10 ) × 10

−3
(8.3)

For US Customary units, wind velocity (U10 ) is specified in ft/s, density (ρair ) is specified in lb/ft3
and shear stress (τ ) is calculated / output in lbf/ft2.

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 (τx ) and shear stress in the Y direction (τy ).
When interpolating grids from point data the wind boundary at each point is converted to τx and τy

and these x and y component stresses are interpolated using the selected method (as described
below).

Section 8 Boundaries and Initial Conditions - 49 / 55 Page 414 / 1094

 Alternatively, a series of τx and τ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, τx and
τ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:

Grid Interpolation Method

Output Grid Format
Output Grid Cell Size
Output Grid Origin
IDWExponent
IDW Maximum Distance
IDW Maximum Point

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.15 .

@1335 Table 8.15: 2D External Wind Stress (2d_ws) Attribute Descriptions

Default GIS Attribute

No Description Type
Name

The name of the BC in the BC Database (see

1 Name Char(100)
Section 8.6 ).

Section 8 Boundaries and Initial Conditions - 50 / 55 Page 415 / 1094

 @1336
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.

@1337
8.9.1 Initial Water Levels (IWL)

@1338 1D Domains
8.9.1.1

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:

1. Create a 1d_iwl layer using an empty layer created by Write Empty GIS Files .
2. 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.
3. Save the GIS layer.
4. 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.

@1339 Table 8.16: 1D Initial Water Level (1d_iwl) Attribute Descriptions

Default GIS Attribute

No Description Type
Name

Initial water level of object relative to model

1 IWL Float
datum (m).

@1340
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:

1. Create a 2d_iwl layer using an empty layer created by Write Empty GIS Files .

Section 8 Boundaries and Initial Conditions - 51 / 55 Page 416 / 1094

 2. Digitise regions or points and assign each object an initial water level value.
3. Save the GIS layer.
4. 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).

@1341 Table 8.17: 2D Initial Water Level (2d_iwl) Attribute Descriptions

Default GIS Attribute

No Description Type
Name

Initial water level of object relative to model

1 IWL Float
datum (m).

@1342 Automatic Initial Water Level

8.9.1.3

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!

@1343
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.2 ). 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:

Set IGW Depth [ {} | <Layer N> ]

Set IGW Level [ {} | <Layer N> ]

They can also be set on a spatial basis using:

Read GIS IGW Depth [ {} | <Layer N> ]

Read Grid IGW Depth [ {} | <Layer N> ]
Read GIS IGW Level [ {} | <Layer N> ]
Read Grid IGW Level [ {} | <Layer N> ]

“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

Section 8 Boundaries and Initial Conditions - 52 / 55 Page 417 / 1094

 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:

Set GWD or Set GWL

Read GIS GWD or Read GIS GWL
Read Grid GWD or Read Grid GWL

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 .

@1344 Table 8.18: 2D Groundwater (2d_gw) GIS Attribute Descriptions

Default GIS
No. Attribute Description Type
Name

The ground water level in metres above datum (if using the
command Read GIS GWL) or depth below ground surface
1 Groundwater in metres (if using the command Read GIS GWD) of the Float
groundwater table at the start of the model simulation. The
units are feet if using Units == US Customary.

@1345
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.

Section 8 Boundaries and Initial Conditions - 53 / 55 Page 418 / 1094

 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

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

@1348
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

@1349
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

Section 8 Boundaries and Initial Conditions - 54 / 55 Page 419 / 1094

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

@1351
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

@1352
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

Section 8 Boundaries and Initial Conditions - 55 / 55 Page 420 / 1094

 @1357

@1358
Section 9 Advection Dispersion

@1359
9.1 Overview

The TUFLOW AD Module is an add-on Module and extension of the TUFLOW hydrodynamic
engines. By including passive transport fields for tracers, the advection, dispersion and fate of
water quality constituents may be simulated. Examples of constituents include salinity, sediment
and/or catchment inflow pollutant concentrations. Both dissolved and particulate constituents can
be simulated. TUFLOW AD takes depth and velocity fields computed by the TUFLOW Classic or
HPC solver and uses this information, together with initial and boundary conditions, to simulate
the transport of the specified constituents. In particular, the effects of both longitudinal dispersion
and transverse turbulent diffusion are included. TUFLOW AD is specifically oriented towards
analyses of systems including coastal waters, estuaries, rivers, floodplains and urban areas. Up to
twenty individual constituents can be simulated within TUFLOW AD. For models with linked 1D-2D
domains, transport through 1D elements linked by SX connections is supported, but transport
through 1D elements linked by HX connections are not.

@1360
9.2 2D Domains

@1361
9.2.1 2D Depth Averaged Equation of Motion

The equation of motion of a passive tracer ϕ (as a concentration), in 2D depth averaged

conservative formulation is:

@1363 ∂(hϕ) ∂(huϕ) ∂(hvϕ) ∂ ∂ϕ ∂ ∂ϕ

+ + − (hD ) − (hD ) = hSϕ (9.1)
∂t ∂x ∂y ∂x ∂x ∂y ∂y

Where:

ϕ = Tracer concentration as mass (or mols) per unit volume

h = Water depth
u and v = Depth averaged velocity components in the x and y directions
x and y = 2D spatial coordinates
t = Time
D = Isotropic dispersion plus turbulent diffusion coefficients values in the x and y directions
Sϕ = Tracer source as mass (or mols) per unit volume per unit time

The first term in the equation can be expanded using the chain rule and then substituting the
continuity equation to get:

Section 9 Advection Dispersion - 1 / 20 Page 421 / 1094

 @1374 ∂(hϕ) ∂ϕ ∂h ∂ϕ ∂(hu) ∂(hv)
= h + ϕ = h − ϕ( + ) (9.2)
∂t ∂t ∂t ∂t ∂x ∂y

Combining Equations (9.1) and (9.2) we get:

@1376 ∂ϕ ∂ϕ ∂ϕ 1 ∂ ∂ϕ ∂ ∂ϕ
+ u + v − [ (hD ) + (hD )] = Sϕ (9.3)
∂t ∂x ∂y h ∂x ∂x ∂y ∂y

@1378
9.2.2 Solution Method (TUFLOW Classic)

The 2D advection dispersion algorithm in TUFLOW Classic is based on the ULTIMATE QUICKEST
method of Leonard (1991 ), Leonard & Niknafs (1991 ) and Leonard et al. (1993 ). The
equation of motion is based on Equation (9.3) , but reformulated to make use of the offset grid
and the TVD interpolation scheme (i.e. it is better to first compute ϕ at the cell faces and then
compute ∂(uϕ)/∂x rather than ∂ϕ/∂x ):

@1382 ∂ϕ ∂(uϕ) ∂(vϕ) 1 ∂ ∂ϕ ∂ ∂ϕ ∂u ∂v

+ + − [ (Dx ) + (Dy )] = Sϕ + ϕ ( + )
∂t ∂x ∂y h ∂x ∂x ∂y ∂y ∂x ∂y

TUFLOW AD applies the dispersion formulation described by Falconer et al. (2005 ). This
formulation computes dispersion in the X and Y directions (Dx and Dy respectively, to suit the
Cartesian computational grid) from user specification of longitudinal and transverse dispersion
coefficients KL and KT , respectively. Specifically, Dx and Dy are computed dynamically at each
grid cell and timestep as follows:

X Direction dispersion plus turbulent diffusion:

@1390 (KL u
2 2
+ KT v )h√g
Dx = max ( , Dw ) (9.5)
|U |C

Y Direction dispersion plus turbulent diffusion:

@1392 (KT u
2 2
+ KL v )h√g
Dy = max ( , Dw ) (9.6)
|U |C

Where:

KL = User specified longitudinal dispersion coefficient

KT = User specified transverse diffusion coefficient
g = Gravitational acceleration
|U | = Velocity magnitude
1

6
h
C = Chezy bed friction coefficient C =
n

Dw = User specified lower bound dispersion coefficient

The value of Dw can be specified as constant or spatially varied as required.

The source terms also includes sink terms such as settling (for particulate species) and decay.
The scheme also includes representation of mixing due to sub-grid-scale turbulence and vertical
shear via the dispersion formulation provided in Falconer et al. (2005 ).

The TUFLOW AD computational procedure used is an explicit scheme based on Leonard (1991 ).
This contrasts to the TUFLOW Classic engine, which employs an implicit scheme. As such,
TUFLOW AD is generally subject to stricter stability constraints than the Classic hydrodynamic

Section 9 Advection Dispersion - 2 / 20 Page 422 / 1094

 engine. As such, the TUFLOW AD calculation takes the form of three steps within each timestep.

The first step involves calculation of the Courant-Friedrichs-Lewy (CFL) condition at all wet cells,
where the CFL in 1 dimension is:

CFL Condition:

@1402 u ∙ Δt
CF L = (9.7)
Δx

Where:

u (or v) = Fluid velocity

Δx = Grid scale
Δt = Timestep

This condition is typically required to be less than 1.0 (additive for both X and Y directions) and
has a broad physical interpretation requiring that the distance fluid is advected in one timestep (
u Δ t ) is less than one grid cell (Δx).

The second step is the computation of a similar condition for the diffusive lengthscale (related to
the Peclet number) that ensures that dispersion also does not cause instability at any grid cell.
The CFL and dispersion dimensionless numbers are then added and the maximum sum at any
given location within a timestep is used to compute the number of sub-stepping iterations required
by TUFLOW AD to remain stable within one TUFLOW timestep.

The third step within each TUFLOW timestep is to execute the advection dispersion calculations
for the required number of iterations, with a modified (smaller) Δt .

The original ULTIMATE QUICKEST solution method has been enhanced and improved as applied
in TUFLOW AD. For example, TUFLOW AD also employs adaptive computational stencil
expansion where it identifies sharp constituent concentration gradients (Leonard & Niknafs, 1991
). Where possible (i.e. away from boundaries and dry cells) and required, the ULTIMATE
QUICKEST stencil is expanded from the standard third order scheme to a ninth order scheme,
only on principle computational axes. Cross terms greater than third order are not included. If
insufficient wet cells exist to switch to ninth order, then seventh and fifth order schemes are
progressively tested (with commensurately decreasing stencils) until all required wet cells are
located.

Application of the ULTIMATE limiter (Leonard, 1991 ) has been found to induce steady flow
anisotropy when extended to multi-dimensional problems and the numerical cross terms
associated with additional dimensions are included in calculations. Wu & Falconer (2000 )
developed a modification to the ULTIMATE limiter that reduces this anisotropy, and this has been
applied within the TUFLOW AD computational engine.

@1411
9.2.3 Solution Method (TUFLOW HPC)

The TUFLOW HPC solver tracks areal density, b = hϕ , of the passive tracer as the primary
prognostic variable. With this change, equations (9.1) and (9.2) combine to become:

@1413 ∂b ∂(ub) ∂(vb) ∂ϕbu ∂ϕbv

+ + − − = Sb (9.8)
∂t ∂x ∂y ∂x ∂y

Where:

Section 9 Advection Dispersion - 3 / 20 Page 423 / 1094

 ϕbu and ϕby are the combined dispersive and diffusive unit fluxes of tracer in the x and y
directions respectively
Sb = source terms (areal density rate)

The diffusive fluxes of tracer across cell faces are comprised of two components. The first is
dispersion (induced by shear in the vertical velocity profile) which acts in the direction of the flow,
and the second is turbulent diffusion which acts in both longitudinal and transverse directions.
Both calculations use the same formulation, but with different coefficients (Falconer et al., 2005 ):

@1418 ϕbL
|U |h√g
KL 0
∂ϕ

∂L
( ) = − [ ]( ∂ϕ
) (9.9)
ϕbT 0 KT
C
∂T

Where:

L and T denote longitudinal and transverse directions

The concentration gradients in the longitudinal and transverse directions can be obtained from
those in cartesian coordinates with a rotational transformation:

∂ϕ

@1422
∂ϕ

∂L cosθ −sinθ ∂x
( ∂ϕ
) = [ ]( ∂ϕ
) (9.10)
sinθ cosθ
∂T ∂y

Where

θ = angle of flow vector such that cosθ =

u
and sinθ =
v

|U | |U |

And similarly the dispersive and diffusive fluxes can be transformed back from flow direction
coordinates to the cartesian coordinates with the reverse transform:

@1427 (
ϕbu
) = [
cosθ sinθ
](
ϕbL
) (9.10)
ϕbv −sinθ cosθ ϕbT

Putting all of this together, and adding an isotropic diffusion term Dw (which can be used to
represent wind/wave induced diffusion) yields:

∂ϕ

@1430 ϕbu −1 ∂x
( ) = −hRDR ( ∂ϕ
) (9.11)
ϕby
∂y

@1432 −1
|U |h√g 2
Kl cos θ+Kt sin θ
2
(Kl −Kt )cosθsinθ Dw 0
RDR = [ 2 2
] + [ ] (9.12)
(Kl −Kt )cosθsinθ Kl sin θ+Kt cos θ 0 Dw
Cz

Note that this form is similar to that of Equations (9.5) and (9.6) but includes the off diagonal
terms that arise in the matrix. Also note that the isotropic diffusion Dw in HPC is a global constant.

@1435
9.2.4 Local Constituent Transformation

In addition to pure advection and dispersion/diffusion, constituents simulated within TUFLOW AD

(in both Classic and HPC) are modified by transient boundary conditions, and optional settling (for
sediment constituents) and decay processes (dissolved and degradable constituents).

TUFLOW AD boundary conditions can be set to vary in time for each constituent, and can be
applied to all TUFLOW boundaries that set water levels and flows (either user-specified or
computed), such as HT or QT. TUFLOW AD also supports SA inflow boundaries, where flows and
concentrations are used to compute mass loads that are delivered to the model domain, mixed

Section 9 Advection Dispersion - 4 / 20 Page 424 / 1094

 with ambient water and then resultant concentrations computed, prior to execution of the
advection routines. Consituents are not supported in rainfall boundaries, which are assumed to be
pure water.

Settling of constituents to simulate removal of particulate matter from the water column has been
included in the engine as a simple linear process. Once settled, constituents do not re-enter the
computational domain. The local source contribution from settling is given by:

ws ws
@1436 Sϕ = − ϕ ; or Sb = − b (9.13)
h h

Where:

ws is the settling velocity for the particles

TUFLOW AD also supports the decay of individual species (if positive decay rates are specified)
and employs first order rate equations to do so. These equations draw on user defined decay
rates:

@1439 Sϕ = −ωϕ ; or Sb = −ωb (9.14)

Where:

ω is the decay rate for the constituent

@1442
9.2.5 Groundwater

The 2023-03-AA release introduces tracking of constituents through the groundwater layers when
run using the TUFLOW HPC solver, including return flow to surface water when horizontal
hydraulic conductivity in included in the soils file. When this feature is used, groundwater return to
the surface typically occurs at the bottom of slopes or adjacent to creeks, representative of
catchment baseflows in reality. Refer to Section 9.5.6 for commands for setting initial
concentrations for sub-surface layers. No dispersion is modelled in the groundwater layers. The
2d_bc “GT” type groundwater boundary does not support defined inflow values for constituents.

Advection-dispersion in groundwater is not supported in TUFLOW Classic or the TUFLOW HPC

Quadtree Module.

@1443
9.2.6 Limitations

TUFLOW AD is designed to model dissolved and particulate constituent advection and dispersion
in coastal waters, estuaries, rivers, and floodplains. This is achieved through solution of the 2D
transport equation combined with sub-models for settling or decay.

Limitations to note include:

1. The dispersion scheme adopted by TUFLOW AD (Falconer et al., 2005 ) is such as to allow
use of literature values for longitudinal and transverse dispersion coefficients (KL and KT ).
Users adopting literature values for these coefficients (as provided in (Falconer et al., 2005
)), should however do so with extreme caution, as they are known to vary widely, and by up to
several orders of magnitude. It is always preferable to use monitoring data to calibrate
advection dispersion models (TUFLOW AD included) and this should be done whenever and
wherever possible. If no such data is available, then literature values can be used for KL and

Section 9 Advection Dispersion - 5 / 20 Page 425 / 1094

 KT , however results need to be appropriately caveated, and TUFLOW AD predictions (as for
any AD model) should be seen as qualitative or indicative at best.
2. Modelling predictions should also be cross checked with desktop calculations where possible.
For example, this might include a hand calculation of expected salt masses in a given tidal
system, with comparison made to TUFLOW AD outputs.
3. TUFLOW AD allows for specification and computation of large dispersion coefficients, and
with the automatic substepping implementation it should generally remain stable. However,
specification of large (i.e. greater than approximately 100-500) dispersion coefficients may
lead to results that are not physically real or defensible. As such, (in conjunction with 2 and 3
above) results should always be sanity checked and correlated with measurements. Relying
on uncalibrated model predictions is not recommended.

@1448
9.3 1D Domains

@1449
9.3.1 1D Cross-Sectional Averaged Equation of Motion

The movement of constituents through 1D (ESTRY) channels is supported via SX connections.

Prior to the 2025 release, movement of constituents through these connections was only on a
mass balance basis. That is, it assumed that the concentration of a constituent exiting an SX
connection is the same as that at the entrance SX connection, at the same timestep. While this
provides a simplified method to pass constituents through relatively ‘short’ 1D channels, it does
not consider the time taken for the constituents to flow over the distance of a 1D channel, nor the
mixing of water with different tracer concentrations at 1D channel junctions.

The 2025 release introduced a new approach to partially support the advection of constituents in
1D channel networks. The mass balance equation is solved by taking into account the velocity in
1D channels and the water volume at 1D nodes. The travel time of the constituents through 1D
channel and the mixing of constituents at 1D junctions are now simulated properly. This new
approach is set as default in the 2025 release by the following ecf command:

AD Approach == Method B

Backward compatibility is offered by setting this command to ‘Method A’.

When Method B (the default) is used, the equation of motion of a passive tracer ϕ (as a
concentration) in 1D ESTRY channels is solved as:

@1451 ∂(Aϕ) ∂(Auϕ) ∂ ∂ϕ

+ − (ADx ) = ASϕ (9.15)
∂t ∂x ∂x ∂x

Where:

ϕ = Tracer concentration as mass (or mols) per unit volume

A = Cross-sectional flow area (up to the water surface)
u = Cross-sectional averaged velocity components in the x direction
x = 1D spatial coordinates in the streamwise direction
t = Time
Dx = Isotropic dispersion plus turbulent diffusion coefficients values in the x direction
Sϕ = Tracer source as mass (or mols) per unit volume per unit time

Section 9 Advection Dispersion - 6 / 20 Page 426 / 1094

 @1460
9.3.2 1D Solution Method (ESTRY)

The TUFLOW 1D (ESTRY) AD solver is based on the implicit finite volume method. Equation
(9.15) is integrated over the 1D nodal volume, from the channel mid-section of the upstream
channel to the mid-section of the downstream channel, i.e. the same 1D node ESTRY uses to
store water volume. The tracer concentration at node i, at the next timestep is calculated as:

@1462 ∑ Qϕ
ϕi,n+1 = ϕi,n + Δt (9.16)
Vi

Where:

ϕi,n+1 = Tracer concentration at node i at next timestep

ϕi,n = Tracer concentration at node i at current timestep
Δt = Timestep
Q = Cross-sectional volumetric flux at the connected channel mid-sections
ϕ = Tracer concentration the connected channel mid-sections
Vi = 1D nodal water volume at node i (up to the water surface)

@1473

Figure 9.1: 1D Channel Advection

ESTRY solves flux/velocity at channel mid-section, so spatial interpolation is not needed for Q .
The mid-section concentration ϕ , on the other hand, is interpolated from the nodal concentration
nd
using 2 order spatial scheme with Superbee gradient limiter (Fringer et al., 2005 ).

@1476
9.3.3 Limitations

The following features are not yet supported:

Diffusive fluxes in 1D channels.

Setting tracer initial concentrations at 1D nodes.
Tracer source term in a 1D node.
HX connections (2d_bc “HX” type).

@1477
9.4 The Modelling Process

@1478
9.4.1 Data Input Requirements

The minimum requirements for setting up a TUFLOW AD model are:

Section 9 Advection Dispersion - 7 / 20 Page 427 / 1094

 1. A properly constructed and stable TUFLOW hydraulic model; and
2. Boundary conditions for constituent concentrations (e.g. ocean salinities, catchment inflow
pollutant concentrations etc.).

Initial conditions, dispersion coefficients, settling and decay rates will all be set to zero if not
specified to be otherwise.

Preferable (and recommended) data requirements include:

1. Water quality calibration information as time-series data at points. This is particularly

important for dispersion coefficient calibration;
2. Spatially variant initial conditions;
3. Particulate matter settling rates (if any); and
4. Dissolved species decay/transformation rates (if any).

@1479
9.4.2 Calibration and Sensitivity

Advection dispersion models are usually calibrated against water quality observations. For
example, salinity recovery data can be used to calibrate and validate models, with longitudinal and
transverse dispersion coefficients being the primary free variables. Dissolved and/or particulate
constituents can then be simulated using the derived dispersion coefficients, and can include use
of settling and/or decay rates as needed.

Ideally, models should be calibrated for conditions similar to those under investigation (e.g. a
catchment inflow to an estuary) although this is not always possible, particularly when data is
limited. In these situations, sensitivity analyses could be carried out by increasing and decreasing
calibration variables, though this not a preferred approach due to the large variability in the
literature with respect to acceptable dispersion coefficients.

@1480
9.4.3 Model Resolution

The 2D domain cell size needs to be sufficiently small to reproduce advection dispersion
behaviour. It is worth noting that, in general, the larger the cell size is with respect to the scale of
mixing processes, the greater potential there is for numerical dispersion to play a role in the model
execution process. Even though TUFLOW AD has in-built measures to reduce these effects, it is
advisable to keep this in mind, and perform at least some limited testing with your model to
determine its sensitivity to cell size.

@1481
9.4.4 Computational Timestep

With TUFLOW Classic, the selection of the timestep is important in that the run time is directly
proportional to the number of timesteps required to calculate model behaviour for the required
time period. Notwithstanding this, with TUFLOW Classic the AD module will automatically substep
with respect to the main hydraulic engine on the basis of maintaining both advective and
dispersive stability (see Section 9.2.2 ) so the selection of timestep should be focused on
ensuring hydraulic stability, as AD stability should follow, providing reasonable dispersion
coefficients are set.

Section 9 Advection Dispersion - 8 / 20 Page 428 / 1094

 TUFLOW HPC, being an explicit method already, uses a self-adaptive timestep which is much
smaller than Classic. Further, it uses the fourth order Runge-Kutta temporal integration scheme,
and the advection dispersion calculations are performed on the same timestep and with the same
scheme. When running AD models in HPC There is generally no need for the user to change the
timestepping from the default method. Using high dispersion coefficients may cause TUFLOW
HPC to use a smaller timestep than otherwise required for the hydraulic calculations due to the
diffusion (Peclet) number control.

@1482
9.4.5 Example AD Models

A step-by-step descrition outlining how to set up an AD model is provided on the TUFLOW Wiki.
An example model dataset is also available in the Advection Dispersion Example Models.

@1483
9.5 Data Input

@1484
9.5.1 Simulation Control File

@1485
9.5.1.1 TUFLOW AD Control File (.adcf File)

The TUFLOW AD Control File or .adcf file points to the two mandatory files required for AD model
execution. It is the top of the tree for the AD model and is called into the .tcf by the AD Control File
command. The .adcf file must reference:

One global database file, using the AD Global Database command. For example,
AD GLOBAL DATABASE == ..\bc_dbase\2d_ad_globaldatabase_Demo1.csv
One boundary database file, using the AD BC Database command. For example,
AD BC DATABASE == ..\bc_dbase\2d_ad_dbase_Demo1.csv

Appendix J lists and describes these commands and their parameters. No other commands are
required in the adcf file.

@1486
9.5.1.2 GIS Input File Types and Naming Conventions

Spatial variation in initial condition and minimum dispersion coefficient is an optional data entry
that can be used. If adding this feature to your model, it is recommended that the prefixes
described in Table 9.1 be adhered to for 2D GIS layers. This greatly enhances the data
management efficiency and importantly makes it much easier for another modeller or reviewer to
quickly interpret the model. This approach is also consistent with that of TUFLOW.

Section 9 Advection Dispersion - 9 / 20 Page 429 / 1094

 @1487 Table 9.1: GIS Input Data Layers and Recommended Prefixes

2D Domain GIS Suggested

Description Section
Layers File Prefix

Layer containing polygons defining the

2D AD Initial Section
2d_ad_ic_ spatial distribution of initial conditions for
Conditions 9.5.5
a given constituent. Optional.

Layer containing polygons defining the

2D AD Minimum
spatial distribution of minimum dispersion Section
Dispersion 2d_ad_md_
coefficients (Dw ) for a given constituent. 9.5.7
Coefficient
Optional.

@1489
9.5.2 1D Geometries

TUFLOW AD does not require any further 1D data in addition to the features already included in
the TUFLOW hydraulic model.

@1490
9.5.3 Specification of Constituent Properties

Constituent properties are specified in the Global Database file, which is identified in the .adcf file
using the AD Global Database command. This database file has a set structure, in much the
same way as TUFLOW boundary database files, and can be created in software such as Microsoft
Excel. The number of constituents simulated by TUFLOW AD is simply the number of line entries
in this file (excepting the header data). Constituents can be removed from the simulation by
prefacing rows in the global database file with the ‘!’ or ‘#’ character. The maximum number of
constituents TUFLOW AD can simulate is 20.

The global database file must be .csv (comma delimited) formatted. The first row must contain the
predefined keywords (in order) as listed in Table 9.2 , separated by commas. Subsequent rows
contain constituent data.

An example global database file is provided in the Advection Dispersion Example Models.

Section 9 Advection Dispersion - 10 / 20 Page 430 / 1094

 @1491 Table 9.2: Global Database Keyword Descriptions

Keyword Description

The name of a constituent. This might be ‘TN’ or ‘Salinity’ (without the

Name inverted commas). The Name field is limited to 40 characters and must be
alphanumeric characters only. Mandatory.

Heat Name Not currently used. Leave blank.

The decay rate (k) of the constituent in units of day-1. This value is used in a
first order decay calculations at each timestep, i.e.

−kt
C(t) = C0 e

Where:

Decay Rate ⋅ C(t) is constituent concentration at time t

⋅ C0 is a reference concentration
⋅ k is the decay rate specified here; and
⋅ t is time

If no decay is required, then either enter 0 or leave the field blank.

The settling rate of the constituent in units of m.day-1. This value is used in a
simple mass balance calculation that removes the constituent from the water
Settling Rate column based on this rate.

If no settling is required, then either enter 0 or leave the field blank.

The value KL for the constituent, as per Equation (9.5) for TUFLOW
Classic and Equation (9.9) for TUFLOW HPC. Allowing such variation
between constituents permits simultaneous simulation of multiple
constituents with varying dispersion properties. This is useful at the model
Longitudinal calibration stage when a range of dispersion coefficients can be tested
Dispersion within one simulation to ascertain the best match to monitoring data. This
Coefficient feature can also be used in sensitivity testing. Notwithstanding this, this
value should not be varied from constituent to constituent once the AD
model is calibrated.

If the field is blank or set to zero, then longitudinal dispersion is switched off.

The value KT for the constituent, as per Equation (9.6) for TUFLOW
Classic and Equation (9.9) for TUFLOW HPC. Allowing such variation can
Transverse be exploited in the same manner as described above for longitudinal
Dispersion dispersion. This value should not be varied from constituent to constituent
Coefficient once the AD model is calibrated.

If the field is blank or set to zero, then transverse dispersion is switched off.

Section 9 Advection Dispersion - 11 / 20 Page 431 / 1094

 Keyword Description

This can be set to either a single number or a path reference to a GIS layer
(2d_ad_ic_). If the former is specified, then that value is applied uniformly to
all wet cells at initialisation.

If a path to a GIS layer is specified, then the layer must comprise of (only)
polygons with a single attribute. The attribute must be of type Float. The field
Initial
name is not used by TUFLOW AD, so can be set to a label that is
Condition
meaningful to the user. The polygon data, with spatially varying attributes of
initial concentration is applied to wet cells at simulation initiation. Wet cells
not covered by any polygon in the specified GIS layer are set to a
concentration of zero.

If the field is left blank, then a concentration of zero is applied to all cells.

Minimum Not currently used. Leave blank.

Maximum Not currently used. Leave blank.

This sets the value of Dw as per Equations (9.5) and (9.6) for TUFLOW
Classic and Equation (9.12) for TUFLOW HPC. It can be set to either a
single number or a path reference to a GIS layer. If the former is specified,
then that value is applied uniformly to all wet cells at each timestep.

If a path to a GIS layer is specified, then the layer must comprise of (only)
polygons with a single attribute. The attribute must be of type Float. The field
Minimum
name is not used by TUFLOW AD, so can be set to a label that is
Dispersion
meaningful to the user. The polygon data, with spatially varying values of
Dw is applied to wet cells at each timestep. Wet cells not covered by any
polygon in the specified GIS layer will have Dw set to zero.

This field cannot be left blank. If a minimum dispersion of zero is required,

then 0.0 must be entered in this field. Errors will result if this field is left
blank.

@1507
9.5.4 Boundary Conditions

TUFLOW AD uses the same approach as TUFLOW to setting up boundary conditions, in that two
types of files are required:

Boundary condition database; and

Boundary condition data files (i.e. timeseries).

Like TUFLOW, TUFLOW AD also uses a comma delimited format for both these file types.

TUFLOW AD does not require specification of any geographical information regarding the location
of boundary conditions. All such required data is passed from TUFLOW to TUFLOW AD for
TUFLOW boundary types HT, QT, HS, HQ, QC, VC, VT, and SA.

Section 9 Advection Dispersion - 12 / 20 Page 432 / 1094

 @1508
9.5.4.1 Boundary Condition (BC) Database

A boundary condition (BC) database is created using spreadsheet software, such as Microsoft
Excel. It must be .csv (comma delimited) formatted and is identified in the .adcf file (see AD BC
Database ). The database contains a list of files and attribute names to search for within those
files. The attribute names are then used to extract the desired boundary condition data.

The TUFLOW AD BC Database is structured in the same way as a standard TUFLOW BC

Database, in that it must contain a header line with subsequent rows of information. The header
line must contain the following keywords, in the below order, with meanings as per Table 9.3 .

“Name, Source, Column 1, Column 2, Add Col 1, Mult Col 2, Add Col 2, Column 3, Column 4”

Section 9 Advection Dispersion - 13 / 20 Page 433 / 1094

 @1509 Table 9.3: AD BC Database Keyword Descriptions

Keyword Description

The name of a BC data set. It consists of two concatenated elements as follows:

First: This must be the same ‘Name’ attribute used in the GIS 2d_bc layer(s)
specified in TUFLOW. This is third attribute in the 2d_bc layer and follows
‘Type’ and ‘Flags’. It may contain spaces, but must not contain commas. It is
not case sensitive.
Second: This must be the name of the appropriate constituent for which the
boundary condition is being specified. This name must be one of those
specified in the AD Global Database ‘Name’ field.
Name
These two names are joined by a double underscore. As such, if there are “M”
2d_bc boundary condition objects specified in TUFLOW, and “N” constituents to
be simulated by TUFLOW AD, then M*N entries are required in the AD BC
Database.

An example is Ocean__Salinity, where the TUFLOW 2d_bc file has a line with
Name attribute “Ocean” and the AD Global Database has a variable called
“Salinity” listed.

Mandatory.

The file from which to extract the BC data. It must be a .csv file. Paths are relative

Source to the AD Global Database.

Mandatory.

Column The name of the first column of data (time values) in the .csv Source File.

1 Mandatory.

The name of the column of data in the .csv Source File. Values in this column are
always concentrations, for all allowable BC sets. These are applied to cells
corresponding to the appropriate locations of all types of BCs specified in
TUFLOW 2d_bc GIS layers. These specified concentrations override any other
computed concentrations at the boundary locations.

Column The exception to the above is for SA boundaries, where the specified
2 concentration is multiplied by the inflow corresponding to that concentration (as
passed to TUFLOW AD from TUFLOW) and the mass load over the SA polygon
computed. This mass load is then added to the mass of constituent within the wet
computational cells within the SA polygon, and mass conservation used to
compute a new resultant ambient concentration.

Mandatory.

Add Col
Not used. Leave Blank.
1

Mult Col
Not used. Leave Blank.
2

Section 9 Advection Dispersion - 14 / 20 Page 434 / 1094

 Keyword Description

Add Col
Not used. Leave Blank.
2

Column
Not used. Leave Blank.
3

Column
Not used. Leave Blank.
4

@1510 BC Database Example

9.5.4.2

The Excel spreadsheet below illustrates a simple example of a TUFLOW AD BC Database,

created in a Microsoft Excel worksheet that is exported as a .csv file for use by TUFLOW AD. Four
line boundaries have been specified via GIS in the TUFLOW model (with Name fields “West”,
“North”, “East” and “South”) and two constituents have been specified in the AD Global Database
(with Name fields “Tracer_01” and “Tracer_02”). Four boundaries and two constituents thus
require eight entries in the TUFLOW AD BC Database file.

The Demo1_Concs.csv file was created by saving the below as a .csv file from Excel. All values
are concentrations in mg/L, with the exception of the Time column, which has units of hours.

@1511
9.5.5 Initial Conditions

Initial conditions are specified for each constituent as either a constant value or spatially varied
value (see Table 9.2 ). The former is simply entered as a decimal (or integer) in the Initial
Condition field of the AD Global Database. This value is applied to all wet cells at model initiation.
The latter is applied by entering a relative (or absolute) file path to a GIS layer in the Initial
Condition field of the AD Global Database. The GIS file has the attributes described in Table 9.4 .

Section 9 Advection Dispersion - 15 / 20 Page 435 / 1094

 @1512 Table 9.4: 2D Initial Conditions (2d_ad_ic) Attribute Descriptions

GIS Attribute Description Type

Conc The initial condition concentration. Float

As many polygons as needed can be included in this layer. Any wet cells not covered by these
polygons will be initialised to a concentration of zero. The naming convention prefix for this layer is
2d_ad_ic_. The objects must be polygons. Rectangles, round rectangles etc. are not supported by
TUFLOW. The attribute name is not read by TUFLOW AD and can be anything meaningful to the
user - “Conc” is used as an example above for clarity.

@1513
9.5.6 Groundwater Initial Conditions

Initial concentrations can be set within groundwater layers using the following .tgc commands:

[Set | Read GIS | Read Grid] IGW Conc Layer N1,N2,..N Tracer M1,M2,..M
== [value | /path/to/file]

Where:

N = The groundwater layer number (reference multiple in a single command)

M = The tracer number (reference multiple in a single command), as ordered in the AD Global
Database

If a layer number is not referenced, it is assumed to apply to layer 1. Likewise, if a tracer number
is not referenced it is assumed to apply to the first tracer. Note, the order that ‘Layer’ and ‘Tracer’
appear in the command does not matter (i.e. tracer numbers could be listed before layer
numbers).

@1514
9.5.7 Minimum Dispersion Coefficient

Minimum dispersion coefficients are specified for each constituent as either a constant value or
spatially varied value (see Table 9.2 ). The former is simply entered as a decimal (or integer) in
the Minimum Dispersion field of the AD Global Database. This value is applied to all wet cells at all
timesteps. The latter is applied by entering a relative (or absolute) file path to a GIS layer in the
Minimum Dispersion field of the AD Global Database. The GIS file has the attributes described in
Table 9.5 .

@1515Table 9.5: 2D Minimum Dispersion Coefficient (2d_ad_md) Attribute Descriptions

GIS Attribute Description Type

Conc The initial condition concentration. Float

As many polygons as needed can be included in this layer. Any wet cells not covered by these
polygons will be assigned a minimum dispersion coefficient of zero. The naming convention prefix
for this layer is 2d_ad_md_. The objects must be polygons. Rectangles, round rectangles etc. are
not supported by TUFLOW. The attribute name is not read by TUFLOW AD and can be anything
meaningful to the user - “MD” is used as an example above for clarity.

Section 9 Advection Dispersion - 16 / 20 Page 436 / 1094

 @1516
9.6 Data Output

@1517
9.6.1 TUFLOW AD Log Files

TUFLOW AD log files are written to the location specified by Log Folder command in the .tcf file,
or if this command is not usedthe same location as the .tcf file. The following logs are available:

An AD simulation log file (.adlf);

A CFL condition log file - output when using Write CFL == ON, for TUFLOW Classic only;
and
A mass balance log file - output when using Write Mass == ON.

@1518 Simulation Log File

9.6.1.1

This file is named ‘TCF name.adlf’. It contains commentary of input reading, constituent
specification etc. as the simulation sets itself up.

Following model initialisation, if Write Iterations == ON is used, for TUFLOW Classic only,
the following is output at each timestep. For example:

Simulation time (h) 0.0125

Finished constituent Tracer_01 at AD substep iteration number 1
Finished constituent Tracer_02 at AD substep iteration number 1
Finished constituent Tracer_02 at AD substep iteration number 2
Finished constituent Tracer_02 at AD substep iteration number 3

These lines show information regarding the simulation time for each constituent. In particular, the
number of AD sub-steps needed to be executed to maintain stability under CFL and Peclet
conditions is reported. In the above example, constituent Tracer_01 required no substepping,
whilst constituent Tracer_02 required 3 substep iterations to maintain stability. This is caused by
Tracer_02 being set up with greater dispersion coefficients than Tracer_01 in the AD Global
Database . Additional rows are added as required by the number of constituents simulated.

This TUFLOW AD timestep information is not available for TUFLOW HPC, or needs review by the
modeller, due to the fact the TUFLOW HPC hydraulic engine and advection dispersion
calculations are performed on the same timestep and with the same scheme. See Section 9.4.4
for discussion regarding timestep differences relating to TUFLOW Classic and TUFLOW HPC.

@1519
9.6.1.2 CFL Log File

This file is named ‘TCF name_ADcfl.csv’. It can be output when using TUFLOW Classic in
conjunction with the Write CFL == ON command. It contains commentary on CFL and Peclet
numbers, maximum dispersion coefficients and number of substep iterations. The column data is
as per Table 9.6 :

Section 9 Advection Dispersion - 17 / 20 Page 437 / 1094

 @1520 Table 9.6: _ADcfl.csv File Columns

Column Description

time (h) The simulation time in hours.

Constituent
The name of the constituent as specified in the AD global database.
Name

The maximum CFL for u velocities anywhere in the computational domain

Max_CFL_u
at that timestep.

The maximum CFL for v velocities anywhere in the computational domain

Max_CFL_v
at that timestep.

The maximum Peclet number for u dispersion anywhere in the

Max_Peclet_u
computational domain at that timestep.

The maximum Peclet number for v dispersion anywhere in the

Max_Peclet_v
computational domain at that timestep.

The maximum of the sum of CFL and Peclet numbers in the x (u) direction
Max_sum_u
anywhere in the computational domain.

The maximum of the sum of CFL and Peclet numbers in the y (v) direction
Max_sum_v
anywhere in the computational domain.

The maximum dispersion coefficient in the x (u) direction anywhere in the

Max_Disp_x
computational domain.

The maximum dispersion coefficient in the y (v) direction anywhere in the

Max_Disp_y
computational domain.

The number of iterations required by TUFLOW AD to remain stable. This

Num_iterations can vary from constituent to constituent if different dispersion coefficients
are applied.

As per the TUFLOW AD timestep information in the ‘.adlf’ file. This log information is not available
for TUFLOW HPC, or needs review by the modeller, due to the fact the TUFLOW HPC hydraulic
engine and advection dispersion calculations are performed on the same timestep and with the
same scheme. See Section 9.4.4 for discussion regarding timestep differences relating to
TUFLOW Classic and TUFLOW HPC.

@1521
9.6.1.3 Mass Log File

This file is named ‘TCF name_ADmass.csv’. It can be output when using TUFLOW Classic or
TUFLOW HPC in conjunction with the Write Mass == ON command. It contains commentary
on mass conservation. Specifically, the column data is as per Table 9.7 :

Section 9 Advection Dispersion - 18 / 20 Page 438 / 1094

 @1522 Table 9.7: _ADmass.csv File Columns

Column Description

time (h) The simulation time in hours.

The total mass of that constituent in the computational domain. TUFLOW AD

Constituent assumes that the constituent concentrations are specified in mg/L, and this
Name 1 number is then in tonnes of constituent. If the concentration is g/L, then this
number should be multiplied by 1000 to be in units of tonnes.

Constituent As per constituent 1. Column repeated until all constituents have been
Name 2 accounted for

@1523
9.6.2 Check Files

When using the AD module, an _AD_check file will be output. For check file information, see the
_AD_check TUFLOW Wiki Page.

@1524
9.6.3 Result Files

Result files contain the computed spatial and temporal evolution of simulated constituents. The
output is a temporal format (maximums are not available) and will be output in the format specified
by the Map Output Format command. For example, if Map Output Format == XMDF is used,
the XMDF output will contain a result type called “Conc Tracer_X”.

The AD output will automatically be produced unless the Map Output Data Types command is set
to “AD OFF”. This off option can also be set on a Map Output format basis (e.g. FLT Map
Output Data Types == AD OFF).

Plot Outputs are currently not supported for TUFLOW AD outputs.

References

@1526 R. A., Lin, B., & Kashefipour, S. M. (2005). Modelling Water Quality Processes in
@1525
Falconer,
Estuaries. In P. B. Bates, S. N. Lane, & R. I. Furguson (Eds.), Computational fluid dynamics:
Applications in environmental hydraulics. John Wiley; Sons.

@1527 O. B., Armfield, S. W., & Street, R. L. (2005). Reducing Numerical Diffusion in Interfacial
Fringer,
Gravity Wave Simulations. International Journal for Numerical Methods in Fluids, 49, 301–329.

@1528 B. P. (1991). The ULTIMATE Conservative Difference Scheme Applied to Unsteady One-
Leonard,
Dimensional Advection. Computer Methods in Applied Mechanics and Engineering, 88(1), 17–
74.

@1529 B. P., MacVean, M. K., & Lock, A. P. (1993). Positivity-Preserving Numerical Schemes for
Leonard,
Multidimensional Advection (No. 93N27091). NASA Centre for Aerospace Information.

@1530 B. P., & Niknafs, H. S. (1991). Cost-Effective Accurate Coarse-Grid Method for Highly
Leonard,
Convective Multidimensional Unsteady Flows (No. 91N21075). NASA Centre for Aerospace

Section 9 Advection Dispersion - 19 / 20 Page 439 / 1094

 Information.

@1531
Wu, & Falconer, R. A. (2000). A Mass Conservative 3-d Numerical Model for Predicting Solute
Fluxes in Estuarine Waters. Advances in Water Resources, 23(5), 531–543.

Section 9 Advection Dispersion - 20 / 20 Page 440 / 1094

 @1535

@1536
Section 10 Combining Domains and Solvers

@1537
10.1 Introduction

This chapter discusses methods available for dynamically linking 1D and 2D domains, linking with
external (third-party) 1D solvers, and linking 2D domains together using Classic’s Multiple 2D
Domains feature. HPC’s Quadtree feature, whilst allowing variable 2D cell sizes, is essentially one
2D domain over which a full 2D solution is applied is discussed in Section 7.4.1 . A comparison
between Classic’s M2D feature and HPC’s quadtree grid is presented in Section 10.7 .

The range of functionalities discussed in the Chapter offer numerous benefits, including greater
model design flexibility, greater computational efficiency and performance, and ability to integrate
TUFLOW domains within supported third-party 1D solvers and models.

1D-2D linked models utilise the individual benefits of 1D and 2D solution schemes. 1D schemes
are typically used to represent culverts or sub-surface pipe networks, and sometimes rivers, where
the flow is essentially one-directional. 2D schemes are suited to the representation of, for
example, rivers and floodplains or estuarine and coastal waters, where the hydrodynamics can
flow in multiple horizontal directions, which requires the ability to simulate flow in a two-
dimensional plane.

TUFLOW’s 2D solutions (Classic and HPC) may be dynamically linked to a variety of different 1D
solutions, including TUFLOW 1D (ESTRY), EPA SWMM (herein referred to as SWMM in this
chapter), Flood Modeller (formerly ISIS), 12D Dynamic Drainage (DDA), and XPSWMM from
Autodesk (formerly XP-Software then Innovyze).

Within the one model, 1D domains that are TUFLOW 1D (ESTRY) and other 1D domains that are
an external 1D scheme can occur. This may be useful where different 1D solvers offer different
capabilities. Further, linking of TUFLOW 1D (ESTRY) directly to either Flood Modeller or SWMM is
also possible.

The software environment for the 1D Solver / TUFLOW 2D combination varies:

TUFLOW 1D (ESTRY) and SWMM are integrated within the TUFLOW executable. Model
build tasks and result viewing associated with these linked 1D solvers is typically completed
using traditional TUFLOW compatible GIS software.
12D Dynamic Drainage is developed by 12D Solutions. They have developed a TUFLOW
interface within their own 12D GUI that offers GUI functionality for 1D and 2D modelling tasks.
The interface provides users with the ability to build models and view results entirely within its
GUI. Alternatively, existing TUFLOW files created in a GIS form can be imported and used in
the 12D GUI.

Section 10 Combining Domains and Solvers - 1 / 25 Page 441 / 1094

 Flood Modeller, developed by Jacobs (formerly the ISIS software developed by Halcrow), is
not built into the TUFLOW executable. Flood Modeller must be purchased from Jacobs,
installed and configured, and to link with TUFLOW, the Flood Modeller TUFLOW Link must
also be purchased and installed. Flood Modeller accesses the TUFLOW solvers via the
TUFLOW_LINK.dll that is part of the standard TUFLOW download. The Flood Modeller GUI is
used for 1D model build tasks, and execution of the linked Flood Modeller 1D / TUFLOW
model. The TUFLOW script (control) file and GIS environment is typically used for the
TUFLOW 1D and 2D components.
XPSWMM functions in a fully independent GUI with TUFLOW fully embedded and operated
“behind-the-scenes”. As such, the model development and results viewing information in this
manual is not applicable and reference should be made to the XPSWMM documentation as
supplied with the software. However, when XPSWMM runs a simulation with TUFLOW linked,
all the standard TUFLOW script files, GIS layers and result outputs are written to disk should
the user with to access these in their native formats.

Varying the 2D cell size within a single model enables use of smaller cell sizes (finer resolution) in
areas where a more detailed assessment is required or a finer grid is required to accurately
represent the hydraulics, with the larger cell sizes covering the remaining areas of the model. The
ability to vary 2D cell sizes within the one model optimises the grid construct thereby reducing
simulation times and the memory footprint compared to a model that adopts a fine resolution over
the entire model domain.

Both TUFLOW Classic and HPC offer the ability to vary 2D cell sizes using two different
approaches: - TUFLOW Classic offers 2D-2D linking of different 2D domains via the Multiple 2D
Domains (M2D) Module. 2D-2D linked Classic models allow for a single model to contain multiple
2D domains of different cell sizes and different orientations. The 2D-2D link is via hidden TUFLOW
1D nodes that essentially pass the water from one 2D domain to another using HX links.
Therefore, the solution across the link is not a full 2D solution, rather a linked 2D-1D-2D solution
results that may not be as accurate as a full 2D solution. - TUFLOW HPC doesn’t support
Classic’s 2D-2D linking, but supports varying 2D cell sizes using a full 2D solution across a
quadtree grid (the Quadtree Module, which purchase/licence wise is shared with Classic’s M2D
Module, is required). The quadtree grid requires all 2D cells are on the same orientation and they
can only vary in size by a factor of two when transitioning from a smaller cell to a larger cell.

@1538
10.2 1D and 2D Domain Linking Theory

TUFLOW 1D and 2D domains can be linked in a variety of ways. Common configurations, as

shown in Figure 10.1 , include:

1D culverts through 2D embankments.

1D pipe networks underneath the 2D domain.
Nesting of a 1D open channel (e.g. creek or river) through a 2D domain.
Connection of a broader 1D network catchment model to a high resolution 2D domain.

@1539

Section 10 Combining Domains and Solvers - 2 / 25 Page 442 / 1094

 Figure 10.1: 1D/2D Linking Configurations
There are two types of 1D/2D linking options available:

1. Head (water level) boundaries to the 2D cells (HX); and

2. Source boundaries to the 2D cells (SX).

These are described in the sections below.

@1540
10.2.1 HX 2D Head Boundary

The HX terminology is derived from a Head boundary being applied to the 2D cell using data from
an eXternal 1D scheme. This type of connection can be used to connect TUFLOW 2D with the 1D
schemes of ESTRY (TUFLOW 1D), SWMM, Flood Modeller and XPSWMM. HX lines are typically
used along riverbanks to define the 1D-2D exchange when 1D is used for in-channel
representation, linked to the floodplain in 2D (commonly referred to as, 1D nested open channel
modelling).

For 1D nested open channel modelling, the HX cells are defined using HX lines, connected to 1D
nodes (i.e. the start and end of 1D channel lines) via connection (CN) lines. HX and CN line type
objects are defined in the 2d_bc format layer. The 2d_bc layer is often renamed with the prefix
2d_hx should the modeller choose to store the HX lines in their own layer(s). The CN lines are
snapped to the 1D nodes and vertices along the HX line.

The open channel area modelled by 1D must be deactivated from the 2D domain (2d_code: code
= 0) otherwise the flow down the open channel will be duplicated in both the 1D and 2D domains.
These model features are presented in Figure 10.2 .

When TUFLOW carries out the hydraulic calculations, water level information at the 1D nodes is
transferred to the HX line vertices that are connected to the 1D nodes via the CN lines. Along the
HX lines, between the connected vertices, the water levels are linearly interpolated.

A HX line must have a CN line connected to each of its ends, along with any connections from
intermediate 1D nodes to HX line vertices. Not every HX vertex has to have a 1D node connected.
However, should a 1D node not be connected, the water level from that 1D node will not contribute
to setting the water level profile along the HX line and undesirable results may occur.

Section 10 Combining Domains and Solvers - 3 / 25 Page 443 / 1094

 If a single 1D node is connected to both ends of a HX line, the water levels in the 2D cells along
the HX line will all be the same thereby producing a horizontal water level profile along the HX
line. This approach is typically used for upstream boundaries into a 2D domain, and the line must
be roughly digitised perpendicular to the flow (alternatively use a 2D QT boundary which
automates this set up).

@1541

Figure 10.2: HX Connection: Nested 1D Open Channel – Plan View

Flow can either enter or leave HX cells. The volume of water entering or leaving the cells is added
or subtracted from the connected 1D nodes to conserve mass. The HX link preserves momentum
in the sense that the velocity field is assumed to be undisturbed across the link, however, the
solution across the HX line is not a complete 2D solution as the velocity field on the inactive side
of the HX line is assumed, not calculated. The 2D velocity direction is not influenced by the
direction of the linked 1D channel.

Because of the momentum preservation, the HX link approach produces a superior 1D-2D linking
performance where complex flow behaviour occurs (e.g. river/floodplain interactions) than using a
flow source approach such as applying a weir flow equation across the link. Figure 10.3 shows
an example of the preservation of momentum across HX lines (shown in light purple) as water
flows across a meander where the main channel is represented in 1D.

@1542

Section 10 Combining Domains and Solvers - 4 / 25 Page 444 / 1094

 Figure 10.3: HX Connection: Example of Momentum Preservation across HX Lines
The elevations of 1D-2D boundary cells determine when water can transfer between the 1D and
2D. Water level is calculated at the cell centres in the 2D engine (see Section 7.2.3 ), once the
water level in the 1D node exceeds the elevation in the HX cell, water can enter or leave the cell.
As such, an accurate definition of the 2D HX cell centre elevations is important. If a levee aligns
with the HX line, a 2d_zsh thick breakline is recommended along the levee to ensure that the 1D-
2D boundary cell elevations are consistent with the levee or spill crest.

In the four panels of Figure 10.4 , the 2D HX connection is shown in section view at four differing
water level stages:

Panel 1: In bank flow: the water level in the 1D section is below the 2D cell elevation and no
flow is occurring across the 1D-2D connection.
Panel 2: Spill into the floodplain: the water level in the 1D section is above the 2D cell
elevation along the left bank (but not the right bank). In this case, water is spilling from the 1D
channel into the 2D floodplain on the left bank.
Panel 3: Flow from floodplain: the water level in the 1D is below the water levels on the 2D
floodplains and water will drain from the 2D domain into the 1D channel, which typical occurs
during a flood recession.
Panel 4: Perched floodplain: the flow is still moving from the 2D into the 1D on the left bank,
however, on the right bank, the water level in the floodplain is below the 2D HX cell elevation
and no flow is occurring (the water is perched).

@1543

Section 10 Combining Domains and Solvers - 5 / 25 Page 445 / 1094

 Figure 10.4: HX Connection: Nested 1D Open Channel – Section View
In addition to 1D-2D connections associated with nested 1D open channel / 2D floodplain
situations, HX connections are also used to connect a 2D domain embedded within a broader 1D
network representing the upstream and/or downstream river sections further afield. In Figure 10.5
, HX lines are shown along the upstream inflow to the 2D Domain as purple lines, the CN lines
are shown in green. The CN lines are snapped to the 1D node at the end of the 1D network and
the two vertices at either end of the HX line.

The water level at the 1D node is uniformly applied to the HX cells wherever the water level
exceeds the cell ZC elevation. As the water level applied along the HX line will be horizontal the
HX line must be digitised roughly perpendicular to the expected flow direction. Should the line not
be perpendicular, circulatory flows maybe generated, so check that the flow patterns along HX
lines appear to be reasonable.

@1544

Figure 10.5: HX Connection: External 1D Network Boundary Connection

Note that for all HX links, the cell centre elevation (ZC) at a HX cell must be above the 1D bed
level (interpolated between connected 1D nodes) otherwise an artificial flow across the link will be
produced. To enforce this, TUFLOW produces an error message during the model initialisation,

Section 10 Combining Domains and Solvers - 6 / 25 Page 446 / 1094

 and terminates the simulation, if the interpolated 1D node elevation exceeds the 2D HX cell centre
elevation (ZC). The ERROR message(s) are geo-referenced to easily identify the HX cells that lie
below the 1D bed profile.

@1545
10.2.2 SX 2D Flow Boundary

The SX terminology is derived from a Source boundary being applied to the 2D cell using data
from an eXternal 1D scheme. This type of connection can be used to connect TUFLOW 2D with
the 1D schemes of TUFLOW 1D (ESTRY), Flood Modeller, SWMM and XPSWMM. SX
connections are typically used to transfer flow between 1D and 2D for 1D structures and at
pits/drains/gully traps that capture water into the pipe network. Unique to SWMM, when using it as
the 1D solver, an SX connection is only required at the downstream end of a 1D culvert (it uses a
HX link at the upstream end due to limitations of the SWMM software).

At SX connections, the water level at the 1D node is reset every timestep as the average water
level along the 2D SX cell(s). Conversely, the flow into or out of the 1D element feeds into the 2D
SX cell(s) as a flow of water with the water level at the 2D cells computed as part of the 2D SWE
solution. As the water level at the 1D node is set based on the water level in the SX cells, the
storage in the 1D node is not used computationally in the 1D. Where there is an SX connection to
2D cell(s) from a 1D node, the average 1D node storage is distributed across the connected 2D
SX cells.

The flow onto the SX cells is treated as a source flow, i.e. it can be positive or negative in
magnitude but has no directional component. If there is more than one SX cell connected, the flow
is, by default, proportioned via the depths in the 2D SX cells. The SX Flow Distribution Cutoff
Depth command can be used to control the depth of water below which an SX cell does not
receive flows from the connected 1D element.

SX objects are digitised in the 2d_bc layer and have the type set to “SX”. They can either be a
point (a single SX cell), line (multiple SX cells) or region object (multiple SX cells). When using the
SX line and region objects, these are joined to the 1D nodes with a single CN type object, also in
the 2d_bc layer, as shown in Figure 10.6 . The (2d_bc) SX point, line and region objects are
shown in purple, the (2d_bc) CN lines are shown in green, and the cells selected for the SX 1D-2D
connection are highlighted in white.

When using an SX point, the point object needs to snap to the 1d network (1d_nwk) at the
nodes (end of the culvert). A single 2D cell is selected for the 1D-2D SX connection.
When using an SX line, a connection line snaps to the SX line and the 1d network (1d_nwk)
node. Multiple 2D cells are selected for the 1D-2D SX connection. If the line does not select
any 2D cells a single 2D cell is selected based on the line’s mid-point.
When using an SX region, a connection line snaps to a vertex of the SX region and 1d
network (1d_nwk) node. Multiple 2D cells are selected for the 1D-2D SX connection based on
whether the 2D cell centre falls within the region. If the region does not select any 2D cells a
single 2D cell is selected based on the region’s centroid.

Note that when connecting an SX connection for a 1D structure it is important to ensure

that the width of connected SX cells at the structure invert (and higher levels for irregular
shaped structures) is equal or more than the width of the 1D structure. This check should
take into account whether any of the 2D SX cells are dry at the level being checked. If the

Section 10 Combining Domains and Solvers - 7 / 25 Page 447 / 1094

 width of water flow across the SX cells is less than the flow width of the 1D structure, the
2D SX cells become the constriction and instabilities or unrealistic flow patterns may
result.

@1546

Figure 10.6: SX Connection Options

The lowest 2D SX cell (based on the ZC, cell centre, elevation) must be below the 1D bed level
(invert) otherwise mass can be artificially generated. TUFLOW produces an ERROR message
during the model initialisation and a simulation will not run if a 1D node elevation falls below the
lowest 2D ZC SX cell elevation.

In addition to culverts through embankments, SX connections are used to connect 1D pipe

network inlets (pits) to the ground surface, which is modelled in 2D. An example is presented in
Figure 10.7 and Figure 10.8 . The SX connections are used to transfer flow between the 1D
pit/pipe network and the 2D domain. To make the workflow more efficient, pit SX connections can
be simply defined using one the pit attributes in a 1d_nwk or 1d_pit layer, thereby removing the
need to have a 2d_bc layer - see Section 5.11.2 .

@1547

Figure 10.7: SX Connection: Pipe Network – Plan View

Section 10 Combining Domains and Solvers - 8 / 25 Page 448 / 1094

 @1548

Figure 10.8: SX Connection: Pipe Network -Section View

@1549
10.3 TUFLOW 1D (ESTRY) to TUFLOW 2D Linking

Linked TUFLOW 1D and 2D domain models use 2D HX and 2D SX boundary types connected to
1D nodes (1d_nwk layer) using CN lines or points in the 2d_bc layer, as described in Section 8.5
. The recommended approach for HX and SX connections are summarised in the following
sections.

@1550
10.3.1 1D Open Channel and 2D Domain Linking

2D_bc HX boundaries are preferred for transitioning between 1D domains and 2D domains
(shown in Figure 10.5 ) or when nesting a 1D open channel network within a 2D domain (shown
in Figure 10.2 ).

An example of these HX connections is provided in Module 11 of the TUFLOW Wiki Tutorials. The
TUFLOW Wiki also includes useful guidance on how to stabilise problematic 1D/2D TUFLOW
HPC HX connections.

@1551
10.3.2 1D Structures Embedded within 2D Domains

2D_bc SX boundaries are preferred for inserting 1D culverts inside a 2D domain. For example, a
1D culvert underneath a road embankment, as shown in Figure 10.6 .

An example of these SX connections is provided in Module 3 of the TUFLOW Wiki Tutorials. The
TUFLOW Wiki also includes useful guidance how to stabilise problematic 1D/2D SX connections.

@1552
10.3.3 1D Pipe Network Pits linked to 2D Domains

Pits/Inlets within an urban drainage environment provide bi-directional connectivity between the
urban surface represented by 2D domains and the 1D sub-surface pipe network. They use the SX
type linking described in Section 10.2.2 . To simplify the model setup process the SX connections

Section 10 Combining Domains and Solvers - 9 / 25 Page 449 / 1094

 are automatically created by setting the Conn_1D_2D attribute for the pit/inlet point object to “SX”
in the 1d_pit or 1d_nwk layer. The type of pit is defined using the ‘Type’ attribute:

“C” pits use zero length circular culverts to calculate the flow transferred between the 1D
network and 2D domain.
“R” pits use zero length box culverts to calculate the flow transferred between the 1D network
and 2D domain.
“W” pits use the weir equation to calculate the flow transferred between the 1D network and
2D domain.
“Q” pits use a user-specified Depth-Discharge curve to transfer flow between the 2D domain
and the 1D domain, based on the 2D water depth.

Section 5.11.2 contains information about the specification of pit parameters. A pipe network
model example is provided in Module 5 of the TUFLOW Wiki Tutorials.

@1553
10.3.4 Virtual Pits linked to 2D Domains

Compared to the above-mentioned approach, virtual pits are an alternative way to model
pits/inlets where the sub-surface pipe network is not being modelled. The flow entering a virtual pit
can either be discharged back into the model further downstream or permanently extracted from
the model. There are three main approaches to using virtual pits:

Virtual Pit Inlets (Type ‘VPI’) only are used to extract flow from the model. One examples
would be where there is no or insufficient data on the pipe network. Another example is where
the pipe network flow discharges to a river (assuming the level in the river does not affect the
flow into the pits) and no pit surcharging back onto the 2D domain occurs.
VPIs are used in with Virtual Pipe Outlets (VPOs), which allow the flow into VPIs to be
discharged back onto the model. VPIs can be allocated to specific VPOs via a common
network ID. VPOs can have a limiting outlet flow. Once the VPO flow reaches the limit, the
excess flow is surcharged back through VPIs, which can be prioritised as to which ones
surcharge first. By default, the routing of flow between VPIs and VPOs on the same network
is instantaneous (i.e. no lag). However from the 2023-03-AB build, it is possible to apply a lag
or shift to the flows from the inlet to the outlet by using the 1d_pit Lag_Approach and
Lag_Value attributes.
Flows from VPIs can be connected to 1D channel nodes to drain flow from the 2D surface and
reintroduce them to the 1D domain further downstream. This is a useful approach to modelling
the major sub-surface drainage system as a pipe network and the minor system as VPIs
feeding into the major system.

Section 5.12 contains more information about virtual pits. Examples of these model
configurations are provided in the 1D Pipe Network / 2D Floodplain Modelling Example Model
Database.

As previously mentioned, pits, virtual pits and nodes can be automatically connected to 2D
domains using the 1d_nwk Conn_1D_2D attribute (see Table 5.25 and Table 5.24 ). If
Conn_1D_2D is set to “SX”, TUFLOW automatically connects the upstream end of the pit channel
or node to the 2D domain.

For this automated 1D-2D SX connection to establish, it is a requirement that the 2D cell must
be active (2d_code, Code = 1). If no active 2D cells are found from any 2D domain, a
WARNING 2122 or 2123 is issued.

Section 10 Combining Domains and Solvers - 10 / 25 Page 450 / 1094

 The command Pit Default 2D Connection can be used to set the global default value for the
1d_nwk Conn_1D_2D attribute.
By default, TUFLOW will connect the 1D pit/virtual pit/node to one or more 2D cells at pit
connections. The number of 2D cells selected is a function of the flow width of the pit inlet
(including the effects of the Number_of and Width_or_Dia 1d_nwk attributes), or the total flow
width of the channels connected to the node. The total width of the 2D cells selected is always
more than the pit inlet width or width of channels. For example, a width of 3.6 m on a 2 m grid
selects two cells. The advantage of selecting more than one 2D cell is to provide enhanced
stability at the 1D/2D connection when the 1D flow width exceeds the 2D cell size. The
number of 2D connection cells is limited to 10 per pit inlet.
The 1d_nwk Conn_No attribute can be used to change the number of 2D cells connected as
follows:
A positive value adds that number of 2D cells to the automatic number. In the example
above, if Conn_No is set to 1, three (2 + 1) 2D cells are connected. The upper limit is 10
connected cells.
If Conn_No is negative, this ignores the automatic approach and fixes the number of 2D
cells connected to the absolute value of Conn_No. For example, a value of -1 would only
connect the pit or node to one (1) 2D cell irrespective of the width.
If more than one 2D cell is being connected, there are two approaches available for how the
2D cells are selected.
For pits, the default is the G (on Grade) option that selects the 2nd, 3rd, etc… cells by
traversing to the next highest 2D cell that neighbours the 2D cell(s) already selected (this
includes diagonal cells, i.e. all 8 cells around a cell are considered). These cells are also
automatically lowered to the same height as the first cell so that their ZC value is at or
below the pit inlet.
For nodes, the default is the S (Sag) option that selects the 2nd, 3rd, etc… cells by
traversing to the next lowest 2D cell. The ZC values of these cells are not changed as
they are already at or below the node invert.
The above approaches can be changed using the G (Grade) and S (Sag) flags for the 1d_nwk
Conn_1D_2D attribute. The G approach is that adopted by default for pits and S for nodes. To
override the default approach, specify G or S as appropriate. For example, if the S approach
is preferred for a pit that is draining a depression, specify an S flag for the Conn_1D_2D
attribute (i.e. “SXS”). Note SX must come first before an optional flag is specified.

Note, the conventional 1D-2D link approach using 2d_bc SX points, lines or regions can still be
used to connect 1D channel ends. This gives the user complete control over the 2D cells selected
and may still be preferred in situations where large 1D structures are being connected to 2D cells.

@1554
10.4 SWMM to TUFLOW Linking

New in the 2023-03-AD release, TUFLOW’s 1D linking and solver options have been expanded to
support the EPA Storm Water Management Model (SWMM), see Chapter 6 . The SWMM engine
(version 5) has been integrated into the TUFLOW executable as a 2D and 1D dynamically linked
1D solver. SWMM version 5 input (.inp) files can be directly input to TUFLOW.

In TUFLOW-SWMM there are three categories of connections between SWMM 1D and TUFLOW:

Direct Connections: These apply to inlets/outlets associate with culverts passing through an
embankment (modelled in 2D), or also open outlets from a pipe network.

Section 10 Combining Domains and Solvers - 11 / 25 Page 451 / 1094

 Storm-Drain Inlets: These apply to surface pits/inlets for capturing overland flow into a pipe
network. Geometry information associated with the storm-drain inlet is used to determine the
discharge that should flow from the 2D domain into the 1D SWMM pipe network.
SWMM 1D connection to TUFLOW 1D (ESTRY) that allows 1D domains to be a combination
of ESTRY and SWMM.

@1555
10.4.1 1D Culvert Connections to 2D Domains

This type of connection is used for cross-drainage such as culverts through an embankment. Due
to limitations within SWMM, HX connections are used at the Nodes–Storage object (upstream
side) and SX connections are applied at the Nodes–Outfalls object (downstream). This
configuration is presented in Figure 10.9 .

Where a Nodes–Storage point is connected to the 2D domain using an inlet or HX connection,

TUFLOW will compute the discharge that should be transferred between the 1D and 2D domain. If
the water level in the 2D domain is higher than the 1D (potentially ponded) water level, then flow
will be transferred from the 2D domain to the 1D. The discharge rate will depend on the difference
in water levels.

A TUFLOW-SWMM culvert model is provided in Module 1 of the TUFLOW-SWMM Wiki Tutorials.

@1556

Figure 10.9: SWMM 1D Connection: Culvert

@1557
10.4.2 1D Pipe Network Connections to 2D Domains

SX type linking described in Section 10.2.2 is recommended for pipe network storm-drain inlets.
For a TUFLOW-SWMM model, storm-drain inlets can be defined in one of two ways, either:

1. Fully defined in a SWMM input (.inp) file format: In this form, all table items listed below
(Streets, Conduits, Inlets, and Inlet Usage) are required. In addition, a “2d_bc” layer is
required to provide the connectivity between the 1D inlets and the 2D domain.
Streets: SWMM uses the street cross-section information in this table to help compute
storm drain inlet discharges, particularly for on-grade inlets.
Conduits (Streets): The conduits table is used to define streets for overland runoff and the
slope is used in the storm drain inlet discharges. This table is not used directly when
running a TUFLOW-SWMM model because the overland flows are calculated within
TUFLOW.
Inlets: This table defines inlet configurations that describe how to determine inlet
discharges. Inlets can be defined based on type and shape such as grates, curbs, and

Section 10 Combining Domains and Solvers - 12 / 25 Page 452 / 1094

 combination, or through curves that describe the relationship between depth and inlet
discharge or approach flow and inlet discharge. The inlets table defines these
parameters. The same inlet configuration can be used in multiple pit locations within the
model.
Inlet Usage: This table identifies the placement of inlets including the street conduit, inlet
(configuration), the node receiving the flow, and local parameters including blockage, size
of local gutter depressions, and specification of on-grade, on-sag placement, or automatic
placement.
2. Defined using a SWMM input (.inp) file with a “swmm_inlet_usage” GIS layer: In this form
TUFLOW creates a GIS layer to assist in the 1D-2D specification. Due to reduced data
requirements and model build workflow efficiency the combined SWMM input (.inp) file
/ “swmm_inlet_usage” GIS layer format is the recommended approach. Using this
format:
Table 10.1 lists the attributes associated with the swmm_inlet_usage GIS layer.
Automatic inlet connections between the 1D network and 2D domain can be implemented
via the “Conn1D_2D” attribute field (instead of manual specification of SX connection
cells within a “2d_bc” GIS layer).
SWMM 5 “Inlet Usage” tables are not used, and Conduits (Streets) are not required.
However, Streets and Inlet tables must be defined in the SWMM input (.inp) file.
2d_bc SX lines may be used to manually define connections associated with on-grade
inlets. This gives the user complete control over the 2D cells selected for the on-grade
flow calculations.
The conventional 1D-2D link approach using 2d_bc CN lines and SX lines can be used
(instead of the automated methods) should greater control be required over the selected
2D cells for the 1D-2D on-grade inlet connections.
The conventional 1D-2D link approach using 2d_bc HX lines and SX points, lines or
regions is required to connect 1D channel ends where “direct” connection to the 2D is
desired.

An example model configuration is shown in Figure 10.10 , and example TUFLOW-SWMM pipe
network models are also provided in Module 2, 3 and 4 of the TUFLOW-SWMM Wiki Tutorials.

Whether inlet usage details are defined in SWMM or in a separate GIS layer, the inlet discharges
are computed within TUFLOW using EPA SWMM 5.2 code before being passed to the SWMM
engine for the 1D solution computations. This approach has been selected to leverage the 2D
domain hydraulic calculations.

If the pressure head in the 1D domain exceeds the 2D water level, the 1D domain will overflow
(surcharge) into the 2D domain. The approach used to compute the surcharge discharge depends
on the inlet setup and whether or not the SWMM node ponds.

1. If the node allows ponding (ponding > 0) (recommended configuration):

The surcharge discharge is based on the depth vs flow curve for custom inlets or from the
orifice equation for other inlet types, plus any additional discharge from the use of the
Maximum Inlet Ponded Depth command.
The coefficient used for inlet surcharging can be specified with the Inlet Surcharge Orifice
Coefficient command.
The discharge for custom curves is applied directly in reverse. For example, a 1D water
level 0.3 feet above the 2D water level will produce the equal, though opposite, discharge
as a 2D water level 0.3 feet above the 1D water level (or ground elevation).

Section 10 Combining Domains and Solvers - 13 / 25 Page 453 / 1094

 2. If the node does not allow ponding (ponding = 0):
Any volume that exceeds the maximum nodal water level (YMax) plus any surcharge
depth (YSur) is reported as flooding by SWMM, which no longer tracks it. Therefore, the
water is passed directly from the SWMM engine to the TUFLOW 2D cells. Although
possible, this approach is not recommended because it prevents the 1D network from
utilising the full pressure head in its flow calculations.

@1558

Figure 10.10: SWMM 1D Connection: Pipe Network

Section 10 Combining Domains and Solvers - 14 / 25 Page 454 / 1094

 @1559 Table 10.1: SWMM Inlet Usage (swmm_iu) Attribute Descriptions

Default GIS
No. Description Type
Attribute Name

The name of the inlet defined in the

1 Inlet Char (100)
SWMM inp file “INLETS” section

The name of the street cross-section that

2 StreetXSEC must be included in the SWMM SWMM Char (100)
inp file “Streets” section.

The elevation of the inlet. If a value of –

3 Elevation 99999 is entered, the elevation will be Float
based on the 2D cell’s elevation.

The longitudinal slope of the street near

4 SlopePct_Long Float
the inlet.

The number of inlets in series at the

5 Number Integer
location (generally 1).

The percentage that the inlet is blocked

6 CloggedPct Float
(defaults to 0.0).

The maximum discharge through the inlet

7 Qmax (default is 0 which does not enforce a Float
maximum).

The depth of a local depression at the

8 aLocal Float
inlet (default 0.0).

The width of a local depression at the

9 wLocal Float
inlet (default 0.0).

Specifies whether the inlet should be

treated as a sag or on-grade. Options are
ON_GRADE, ON_SAG, or AUTOMATIC.
10 Placement AUTOMATIC (the default) will switch Char(10)
between ON_GRADE and ON_SAG
depending upon the flow conditions at the
inlet.

Section 10 Combining Domains and Solvers - 15 / 25 Page 455 / 1094

 Default GIS
No. Description Type
Attribute Name

Used to specify a “SX” connection and

any additional flags such as “SXZ” or
“SXG” that automatically creates a 2D SX
cell and connection at the 2D cell within
which the SWMM node occurs. This
negates the need to create SX objects in
a 2d_bc layer.

Flags:

“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.
“Z” – Adjust the ZC elevation at each
cell at/along/within the 2D SX object
to below the 1D node bed elevation

11 Conn1D_2D where ZC is higher. The ZC elevation Char (10)

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 the
SX ZC Check command that 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
realistic.

By default, if more than one 2D cell is

automatically connected, nodes are
assumed to be connected using the Sag
(S) approach. To override the default
approach, specify “SXG” for an on-grade
connection.

Section 10 Combining Domains and Solvers - 16 / 25 Page 456 / 1094

 Default GIS
No. Description Type
Attribute Name

If “SX” is specified for Conn1D_2D, this

field controls the number of 2D cells
connected as follows. Note this approach
is slightly different than is used by
TUFLOW-ESTRY models.

A positive value indicates the flow

width that should be used to compute
the number of 2D cells to connect to.
12 Conn_Width Float
TUFLOW will choose the nearest
cells that are collectively as wide or
wider than the specified flow width.
If negative, the number of cells
selected is the absolute value of the
number specified. For example, a
value of –1 would connect the inlet to
a single 2D cell.

@1560
10.4.3 SWMM to TUFLOW 1D (ESTRY) Linking

SWMM can be linked to TUFLOW 1D (ESTRY) allowing the modeller to use the different solvers
and their benefits across the 1D domains of a model. Also, note that full support for 1D open
channel modelling using SWMM is not yet available, but can be readily modelled using TUFLOW
1D. A typical combined scenario would be 1D open channel modelling using TUFLOW 1D
dynamically linked to a SWMM pipe network. Combined SWMM 1D-TUFLOW 1D configurations
can be dynamically linked to TUFLOW 2D using the approaches outlined in the previous sections.

SWMM and TUFLOW 1D nodes will be considered linked if:

1. A TUFLOW 1D node in a 1d_nwk layer, and a SWMM node layer are snapped to each other,
and
2. The TUFLOW 1D node has a 1d_nwk Conn_1D_2D attribute of either “X1DH” or “X1DQ”.
A “X1DH” link means a SWMM 1D water level is being applied at the TUFLOW 1D node
(i.e. SWMM sends TUFLOW 1D a water level and TUFLOW 1D sends back a +/- flow to
SWMM). This is applicable at SWMM Nodes–Junctions and Nodes–Storage locations.
A “X1DQ” link means a SWMM inflow/outflow is being applied at the TUFLOW 1D node
(i.e. SWMM sends TUFLOW 1D a +/- flow and TUFLOW 1D sends back a water level).
This is applicable at SWMM Nodes–Outfalls locations.

Note:

The upstream and downstream inverts for the TUFLOW 1D node linked to SWMM should be
set to -99999 unless the node is also being used to set the inverts of channels snapped to it.
SWMM cannot be connected to TUFLOW 1D and TUFLOW 2D from the same SWMM node.
Only a single linkage is supported from a single SWMM node. This limitation is highlighted in
the zoomed inset of Figure 10.11 . In this example the SWMM Link–Conduit is only linked to
TUFLOW 1D, it is not connected to TUFLOW 2D via CN and HX lines. The connection of

Section 10 Combining Domains and Solvers - 17 / 25 Page 457 / 1094

 TUFLOW 2D is associated with the TUFLOW 1D open channels, offset from SWMM by a
single short TUFLOW 1D channel length.

@1561

Figure 10.11: SWMM 1D / TUFLOW 1D Connection

@1562
10.5 Flood Modeller to TUFLOW Linking

TUFLOW 2D domains can be dynamically linked to Flood Modeller (previously known as ISIS).
Flood Modeller can also link to TUFLOW 1D (previously known as ISIS-TUFLOW-PIPE or ISIS-
ESTRY).

Unlike TUFLOW 1D or SWMM, Flood Modeller is not included in the TUFLOW executable
download. It must be installed and configured to support the linking to TUFLOW. The TUFLOW
Link must be purchased from Jacobs and an appropriate software version used. It is
recommended that TUFLOW 2020-10-AD or later is used in conjunction with Flood Modeller
Version 5 or later. Figure 10.12 provides the compatibility between Flood Modeller and TUFLOW
for versions prior to Flood Modeller 6 and TUFLOW 2020-10-AE. Post these releases, all
TUFLOW Classic and TUFLOW HPC (including Quadtree) functionality is supported and
compatible with Flood Modeller. Versions prior to Flood Modeller 4.5 will support TUFLOW Classic
only. Regardless of the TUFLOW 2D solver (i.e. Classic or HPC), the linking mechanism is the
same.

@1563

Figure 10.12: Compatibility of Recent Flood Modeller and TUFLOW versions

@1564
10.5.1 Flood Modeller 1D to TUFLOW 2D Linking

To link Flood Modeller’s 1D scheme to TUFLOW 2D, a TUFLOW 1d_x1d GIS layer defining the
locations of the Flood Modeller 1D nodes is required. The 1d_x1d layer can either be created by
the user or by the Flood Modeller interface.

Section 10 Combining Domains and Solvers - 18 / 25 Page 458 / 1094

 For linking 1D Flood Modeller to TUFLOW 2D, the TUFLOW 1d_x1d layer requires only one
attribute, namely a string 12 characters long that contains the unique IDs of the Flood Modeller 1D
nodes/sections. Any other attributes are presently ignored. Creation of this layer manually is
possible through exporting a text or csv file containing the Node ID and XY coordinates of the
nodes, provided the Flood Modeller co-ordinates are in the same projection as the TUFLOW
model. Note, the IDs are case sensitive (because Flood Modeller IDs are case sensitive).

In the .tcf file, use either the Read GIS X1D Nodes or Read GIS X1D Network command to read
the 1d_x1d layer, as shown in the example below:

Read GIS X1D Network == ..\model\gis\1d_x1d_FM_nodes.shp

The digitising of channels (lines) within a 1d_x1d GIS layer is optional and is only necessary if the
model uses 1D Water Level Lines to display map outputs in the 1D domain (refer to Section 11.2.4
for further details). If GIS layer(s) are provided including channels, they are also read into the .tcf
file using the command Read GIS X1D Network , and should be used with Read GIS X1D WLL .

The example below shows the use of these commands (with the nodes and channels in separate
files):

Read GIS X1D Nodes == ..\Model\gis\1d_x1d_FM_nodes.shp

Read GIS X1D Network == ..\Model\gis\1d_x1d_FM_channels.shp
Read GIS X1D WLL == ..\Model\gis\1d_x1d_FM_wlls.shp

Note, legacy models may include reference to ISIS in the above commands. For example, “X1D”
in Read GIS X1D Network can be substituted with “ISIS” (i.e. Read GIS ISIS Network ).

Connections (CN) in the 2d_bc layer are snapped to the nodes in the 1d_x1d layer in the same
manner as a TUFLOW 1D 1d_nwk layer.

The following restrictions apply when connecting Flood Modeller nodes to TUFLOW 2D:

HX lines should only be connected to Flood Modeller RIVER units. Flood Modeller
INTERPOLATE and REPLICATE units are also permitted. This requires that the Flood
Modeller unit between consecutive connections along a HX line is always a RIVER unit. If this
is not the case, an “ERROR 2043 - 2D HX cell has been assigned to a non-RIVER unit”
occurs. Where a non-RIVER unit occurs (e.g. at a structure), the HX line needs to be broken.
Special Flood Modeller units may be required for some HX and SX connections (refer to the
Flood Modeller documentation).

It is not necessary for all Flood Modeller RIVER units between the upstream and downstream
ends of the HX line to be connected. Nodes/Sections may be intentionally or accidentally omitted
as with TUFLOW 1D nodes. Please note that this is not recommended because by missing or
omitting nodes the 1D water level water surface gradient that is applied along the HX lines will not
be correctly represented.

TUFLOW checks whether the ZC elevation of a HX cell lies above the bed of the 1D nodes and
that the ZC elevation of a SX cell lies below the 1D node bed, and if not, an error occurs (see
Section 10.2.1 and Section 10.2.2 ).

Use the _x1d_nodes_check file to cross-check the external 1D nodes/sections that were read by
TUFLOW, and the associated information passed from the 1D scheme. Also use the
_1d_to_2d_check file to cross-check the correct HX and SX cells are connected to the correct
channels (units). The HX cells in the _1d_to_2d_check layer can be colour coded using the

Section 10 Combining Domains and Solvers - 19 / 25 Page 459 / 1094

 “Primary_no” attribute to identify the external 1D channel (unit) that the flow in/out across the HX
cells is associated with. For Flood Modeller, by default HX cells are assigned to the upstream end
of a river unit as a lateral flow as per Flood Modeller conventions.

Note, the start and end simulation times and the timestep are controlled by Flood Modellers GUI
input fields, therefore, any Start Time , End Time and Timestep commands are ignored in the
.tcf file. Therefore, it is best practice to remove (or comment out) these commands. Within the
Flood Modeller GUI, the Flood Modeller 1D timestep can differ from the TUFLOW timestep. It is
recommended that the Flood Modeller timestep be set as an integer divisor of the TUFLOW
timestep.

No TUFLOW 1D .ecf file is required, and the TUFLOW 1D ESTRY Control File command should
not be specified unless there are also TUFLOW 1D domain(s) in addition to the external scheme
1D domain(s). Flood Modeller nodes can be directly linked to TUFLOW 1D nodes allowing models
to have a combination of Flood Modeller 1D and TUFLOW 1D (ESTRY) - refer to Section 10.5.2 .
An example model demonstrating both ‘SX’ and ‘HX’ type links between Flood Modeller and
TUFLOW is available here.

Note that Flood Modeller HX links may benefit from assigning a Form Loss Coefficient (typically
0.1 to 0.5 in value) to HX lines using the 2d_bc “a” attribute. For HX lines running along the
riverbanks, especially those with high overtopping velocities, improved stability and representation
of the energy losses associated with the water peeling off from the river to the floodplain or vice
versa can be achieved.

For model review purposes, the .tcf command Write X1D Check Files writes out
check_x1D_H_to_2D.csv and check_2D_Q_to_x1D.csv files. These contain the water levels and
flows sent to the 2D to/from Flood Modeller.

Example models demonstrating TUFLOW / Flood Modeller linking are available from the TUFLOW
Gitlab User Group. Detailed documentation for the example models is available from the TUFLOW
Wiki. A TUFLOW / Flood Modeller linked model is provided in Module 1 of the TUFLOW / Flood
Modeller Wiki Tutorials.

@1565
10.5.2 Flood Modeller 1D to TUFLOW 1D (ESTRY) Linking

TUFLOW 1D (ESTRY) domains can be dynamically linked with Flood Modeller. The most common
reason this is carried out is to utilise TUFLOW 1D’s powerful pipe network features (see Section
5.11 ).

Flood Modeller and TUFLOW 1D (ESTRY) nodes will be considered linked if:

1. A TUFLOW 1D node in a 1d_nwk layer, and a Flood Modeller node in a Read GIS X1D Nodes
or Read GIS X1D Network layer are snapped.
Note, legacy models may include reference to ISIS in the command. For example, “X1D”
in Read GIS X1D Nodes can be substituted with “ISIS” (i.e. Read GIS ISIS Nodes ).
2. The TUFLOW 1D node connection method is defined using the TUFLOW 1D 1d_nwk
Conn_1D_2D attribute. If the Conn_1D_2D field is blank, a “X1DH” type is assumed - this is
the default approach. Alternatively, a value of “X1DH” or “X1DQ” can be manually specified.
A “X1DH” link means a Flood Modeller 1D water level is applied at the TUFLOW 1D node
(i.e. Flood Modeller sends TUFLOW 1D a water level and TUFLOW 1D sends back a +/-
flow to Flood Modeller).

Section 10 Combining Domains and Solvers - 20 / 25 Page 460 / 1094

 A “X1DQ” link means a Flood Modeller inflow/outflow is being applied at the TUFLOW 1D
node (i.e. Flood Modeller sends TUFLOW 1D a +/- flow and TUFLOW 1D sends back a
water level).
If the end of the TUFLOW 1D channel and the snapped Flood Modeller / TUFLOW 1D
nodes are not in the same location a TUFLOW 1D 1d_nwk connector “X” channel type
can be used to connect the end of the linked TUFLOW 1D channel to the TUFLOW 1D
node snapped to the Flood Modeller node.
Note that the upstream and downstream inverts for the TUFLOW 1D node linked to Flood
Modeller should be set to -99999 unless the node is also being used to set the inverts of
channels snapped to it.
As a general rule, a TUFLOW 1D X1DH (the default) would be used for most Flood
Modeller TUFLOW 1D links. An X1DQ might be more appropriate where a Flood Modeller
model stops and flows into a TUFLOW 1D model.

Generally, a TUFLOW 1D timestep will be smaller than the Flood Modeller timestep. In these
cases, the total volume is accumulated over all TUFLOW 1D timesteps within a Flood Modeller
timestep, and applied to the Flood Modeller model as a discharge by dividing the volume by the
Flood Modeller timestep.

When running a TUFLOW 1D Flood Modeller linked model, the mass balance output _MB1D.csv
file includes four new columns (which are not present if the 1D-1D linking is not used):

X1DH V In: The volume of water in via a X1DH link.

X1DH V Out: The volume of water out via a X1DH link.
X1DQ V In: The volume of water in via a X1DQ link.
X1DQ V Out: The volume of water out via a X1DQ link.

Also, for model review purposes, the type or existence of a connection can be checked following a
simulation by viewing the Conn_1D_2D attribute in the _nwk_N_check layer. The _messages GIS
layer also contains CHECK 1393 messages at each TUFLOW 1D node linked to a Flood Modeller
node.

Example models demonstrating TUFLOW Flood Modeller linking are available from the TUFLOW
Gitlab User Group. Detailed documentation for the example models is available from the TUFLOW
Wiki. A TUFLOW 1D Flood Modeller linked model is also provided in Module 2 of the TUFLOW /
Flood Modeller Wiki Tutorials.

@1566
10.6 12D-DDA to TUFLOW Linking

12D Dynamic Drainage Analysis (DDA) is developed by 12D Solutions based on the USA EPA-
SWMM solver. 12D have developed a TUFLOW interface within their own 12D GUI that offers GUI
functionality for 1D and 2D modelling tasks. The interface provides users with the ability to build
models and view result entirely within its GUI. Alternatively, existing TUFLOW files created in a
GIS form can be imported and used in the 12D environment.

A TUFLOW engine licence, either purchased directly from 12D Solutions or from TUFLOW is
required to use TUFLOW with 12D-DDA. If purchased from TUFLOW, the 12D modules, such as
the TCF Interface Module and 12D-DDA Drainage Integration (Linking) Module, will need to be
purchased from 12D Solutions.

Section 10 Combining Domains and Solvers - 21 / 25 Page 461 / 1094

 For information detailing how to complete TUFLOW modelling using the 12D GUI, and linking
TUFLOW 2D’s solvers with 12D-DDA, please contact 12D Solutions.

@1567
10.7 Multiple 2D Domains

The Multiple 2D Domain Module license provides access to TUFLOW HPC’s Quadtree and
TUFLOW Classic’s Multiple 2D Domain (M2D) features. Both of these features allow the 2D cell
resolution (cell sizes) to vary across the model. However, they are very different in their hydraulic
solution and construct as described below.

@1568
10.7.1 Classic’s M2D Feature versus HPC Quadtree

TUFLOW HPC only supports one 2D domain, however, the 2D cell size can be varied within
the domain using the quadtree grid feature. In contrast, TUFLOW Classic’s M2D feature
allows different 2D domains of different cell size/orientation to be linked together via hidden
1D nodes and HX lines.
For a HPC quadtree grid, the numerical solution remains a full 2D solution without loss of
accuracy, undesirable numerical artefacts or wave reflections when transitioning from one cell
size to another. For Classic’s M2D feature, there is a loss of accuracy, particularly where the
flow is complex/circulating and the assumptions associated with momentum and the linear
water level profile associated with HX lines are influential.
TUFLOW HPC Quadtree grids are set up by the modeller using a largely automated
approach. Definition of 2D cell resolution regions is all that’s required. By comparison,
TUFLOW Classic M2D requires manual definition of each 2D domain and the linkage between
domains using 2D-2D links.

Please contact [email protected] if you wish to use these features, but do not have the
M2D/Quadtree Module enabled on your licence.

Due to the workflow efficient nature of its implementation, superior stability, numerical accuracy
and preservation of inertia, TUFLOW HPC Quadtree has superseded TUFLOW Classic’s Multiple
2D Domain (M2D) feature as the recommended approach for models that require varied 2D cell
sizes within a single model.

For a complete description of the 2D TUFLOW HPC Quadtree solution and associated commands,
please refer to Section 7.4.1 .

An example TUFLOW HPC Quadtree model is available in Module 7 of the TUFLOW Wiki
Tutorials. A video demonstration the implementation of this multiple 2D Domain feature is also
available in the TUFLOW Library.

@1569
10.7.2 TUFLOW Classic’s Multiple 2D Domains

When using TUFLOW Classic with the M2D feature, any number of 2D domains of different cell
size and orientation can be combined to form one model. The 2D domains can be linked via 1D
domains or directly to each other. For example, a 1D domain of a river system may have several

Section 10 Combining Domains and Solvers - 22 / 25 Page 462 / 1094

 2D domains embedded to represent several towns where a more detailed analysis is required.
Alternatively, direct 2D to 2D linking can be achieved by using the 2d_bc 2D link type (see Section
8.5 ). Examples of these model configurations are shown in Figure 10.13 and Figure 10.14 .

@1570

Figure 10.13: Schematic of a Multiple Domain Model linked via a 1D Domain

@1571

Figure 10.14: Schematic of a Multiple 2D Domain Model using the 2d_bc “2D” Link

To specify more than one 2D domain use Start 2D Domain and End 2D Domain in the .tcf file to
start and end blocks of commands applicable for each 2D domain. The ESTRY Control File and
BC Database commands are independent of the 2D domain block. As such they are typically not
included within the 2D domain block.

The mandatory .tcf commands that occur within a 2D domain block are:

Geometry Control File

Timestep
BC Control File

Optional commands that can be used are:

Section 10 Combining Domains and Solvers - 23 / 25 Page 463 / 1094

 Cell Wet/Dry Depth Read GIS IWL
Instability Water Level Read RowCol IWL
Read GIS FC Read GIS LP
Read GIS GLO Read GIS PO

Note that specifying one of the above commands outside a Start/End 2D Domain block
does not apply that command to all 2D domains. For example, specifying Cell Wet/Dry Depth
outside a block will not set the Cell Wet/Dry Depth value to all 2D domains, and causes ERROR
2107 to occur.

An example of using 2D domain blocks is given below:

Start 2D Domain == East_Domain

Geometry Control File == ..\model\east_domain.tgc
BC Control File == ..\model\east_domain.tbc
Timestep == 10

End 2D Domain

Start 2D Domain == West_Domain

Geometry Control File == ..\model\west_domain.tgc
BC Control File == ..\model\west_domain.tbc
Timestep == 5

End 2D Domain

BC Database == ..\bc_dbase\bcdbase_Q100_2hr_001.csv
ESTRY Control File == ..\model\1D_domain.ecf
Read Materials File == ..\model\n_values.tmf
Start Time == 0
End Time == 12

Multiple 2D domain models use the 2d_bc “2D” link type (see Table 8.5 and Table 8.6 ) as the
boundary cells that transfer flow between the neighbouring domains. The link type creates hidden
1D nodes at each vertex along the 2D link line and also at a regular interval, as defined by the “d”
attribute (see Table 8.6 ). The hidden 1D nodes act as storage that convey the water from one 2D
domain to the other.

The water levels along the 2d_bc 2D link line are linearly interpolated using the water levels in the
hidden 1D nodes. If the water level profile in reality is not close to linear between vertices, strange
flow patterns may occur which can lead to model instability or unrealistic results. As such,
appropriate resolution of the hidden 1D nodes is an important feature of multiple 2D domain
models.

The .tcf command Reveal 1D Nodes can be used to view the hidden 1D nodes. The hidden
nodes will be written to the nwk_N check layer, as shown in Figure 10.15 . For multiple domain
models using the 2d_bc “2D” link, note that this GIS layer must be read into the .tbc files of both
2D domains. The 2D link can then be checked by viewing the _2d_to_2d_check layer which
displays the 2D cells used to link the two domains together. These features, and their check files
are shown in Figure 10.15 .

@1572

Section 10 Combining Domains and Solvers - 24 / 25 Page 464 / 1094

 Figure 10.15: Multiple 2D Domain Model “2D” Link Check Files
The following guidance is recommended when defining the location and orientation of the 2d_bc
“2D” link.

2D link lines will be most stable if digitised perpendicular to the dominant flow direction in high
conveyance locations (e.g. rivers and creeks).
Orientation of the 2D link lines is less critical in low conveyance regions, such as floodplain
storage areas (i.e. perpendicular orientation is not a necessity). High resolution definition of
the hidden 1D nodes may be required. If used, the automated hidden 1D nodes distance
attribute “d” should not be set finer than three times the larger cell size.

If the extents of the 2D domains overlap, it will be necessary to deactivate the overlapping cells in
the other domain. Using the example above, the active area for the ‘West Domain’ will need to be
deactivated in the .tgc file of the ‘East Domain’ and vice versa. The Read GIS Code Invert
command is useful for this process as it allows for the same GIS layer to be used to
active/deactivate cells.

A unique model Timestep is recommended for each 2D domain. The timestep should be defined
so that it conforms to the Courant stability criteria for each domain, as discussed in Section 3.5.3
. The timesteps of all 2D and 1D domains should be an integer multiple of one another.

A TUFLOW Classic Multiple 2D Domain model is available in Module 9 of the TUFLOW Wiki
Tutorials Archive.

Section 10 Combining Domains and Solvers - 25 / 25 Page 465 / 1094

 @1577

@1578
Section 11 Outputs

Prior to carrying out a simulation the desired output needs to be configured and customised. For
viewing outputs, see Chapter 15 . There are also a variety of post-processing utilities available,
see Chapter 17 .

The chapter includes discussion on:

Setting the folder location of where outputs are written (Section 11.1 ).
Configuring map output options including 1D results in a 2D form and the powerful output
zones feature (Section 11.2 ).
Options for setting up time-series output from 1D and 2D domains at specified locations
(Section 11.3 ).
Specialised outputs such as time and depth of inundation along evacuation routes (Section
11.4 ).
Options for customising the check and log file outputs (Section 11.5 ).
List of commands available for customising all the different output options, including output to
the simulation console window, check files and folder locations (Section 11.6 ).

@1579
11.1 Output Location

To set the location of where the outputs are written to, the Output Folder command is used. For
example “Output Folder == <folder>” redirects all TUFLOW output data except the log and
summary files to the specified folder.

Outputs can be written in a different location to where the model sits. It is typically recommended
to write outputs to your local C: or D: drive instead of filling up the network drive, or to keep results
separate to the input data. A URL can be used (e.g. \myserver), which is useful for running
simulations on other computers, but with the output directed to your local drive (your drive will
need to be shared) or other location.

The Output Drive command can be used to change the drive letter of any output files with a full
path specified. For example “Output Drive == K” changes any output filepaths that have a
drive letter to the K drive.

@1580
11.2 Map Outputs

TUFLOW has a range of commands that allows the user to control the formats, data types,
frequency, sub-areas (output zones) or resolution (SGS high-resolution) of a simulation’s output.
The options are highly flexible and can be customised to be different for different output formats
and/or output zones.

Section 11 Outputs - 1 / 68 Page 466 / 1094

 For example, time-based map output may be produced using one format (e.g. XMDF), and the
peak flood level surface for another output (e.g. TIF). Output over a township maybe at a higher
output interval frequency than for the whole model so as to produce a higher quality animation of
flooding through the township, or if using SGS, at a higher resolution (e.g. HRTIF).

The main commands to control map outputs are:

Start Map Output and Map Output Interval : to control when and how frequently to write
map output (Section 11.2.1 ).
Map Output Format : to specify the format of the outputs to be written (Section 11.2.2 ).
Map Output Data Types : to specify the data type, such as water level, stream power, etc.
(Section 11.2.3 ).

For example, application of the above commands may look like:

Output Folder == ..\results\ ! Location of the output files

Map Output Format == XMDF TIF ! Produce map output in XMDF and TIF
formats
Map Output Data Types == h V d ! Output water level, velocities and
depths
Start Map Output == 10 ! Start map output at 10 hours
Map Output Interval (s) == 300 ! Write map output every 5 minutes (300s)
TIF Map Output Interval (s) == 0 ! Output maximums only for TIF format

@1581
11.2.1 Output Time Controls

To control when and how frequent outputs are written, time control commands are used. They can
be set as a global setting or customised for each output format. A variety of formats can be output
for a single simulation, the supported formats are discussed in Section 11.2.2 .

To set default settings the followings commands can be used:

Start Map Output : to control when to start writing outputs.

Map Output Interval (s) : to control the frequency of the output.
End Map Output : to control when to stop writing outputs.

To customise the time control commands to be different to the default or global settings, the map
output format acronym is included at the start of the command. For example, “XMDF Map Output
Interval == 360” will set the output frequency to 360s just for the XMDF format. The format
acronym must be identical to that used in Map Output Format . The following commands can be
applied in this manner.

<format> Start Map Output

<format> Map Output Interval (s)
<format> End Map Output

To apply the same setting to more than one format, the command needs to be repeated for each
format. If a format is not customised the default setting or the setting applied to the whole of the
model is used. The order of commands is important, ensure that commands defining the map
output settings for all format types are read in prior to any commands specific to a certain format
type. For example:

Section 11 Outputs - 2 / 68 Page 467 / 1094

 The following commands set a Map Output Interval of 120 seconds for the XMDF format and
3600 seconds for the TIF format:
Map Output Format == XMDF TIF
Map Output Interval == 120
TIF Map Output Interval == 3600

Swapping the order of the second and third command lines will set a Map Output Interval of
120 seconds for all output formats as the third command overwrites the TIF Map Output
Interval command.
Map Output Format == XMDF TIF
TIF Map Output Interval == 3600
Map Output Interval == 120

Of note is that each output is tracked every timestep for its maximum if Maximums and Minimums
is set to “ON” or “ON MAXIMUMS ONLY” (the default) to ensure that the peak result (water level,
depth, hazard etc.), independent of the time it occurred during a simulation, is recorded.

@1582
11.2.2 Map Output Formats

TUFLOW offers a wide range of map output formats, all non-proprietary, to cater for a range of
GIS and GUI software. There are no constraints over how many output formats a single simulation
can produce. Different formats can have different output settings, and by using Output Zones
different regions of the model can output in different formats.

Map output is offered in the following forms:

Mesh Based : The output is based on a quadrilateral and/or triangular mesh of the 1D and
2D domains. This output is the closest reproduction of the hydraulic calculations, with minimal
interpolation from the 1D and 2D computational points. These formats include: XMDF, DAT,
TMO and WRB.
Grid Based : The output is over a regular north-south grid in a similar manner to a raster
DEM. The hydraulic output at each output grid cell is interpolated from the computational
mesh using the Mesh Based output above. These formats include: TIF, GPKG, FLT, ASC, NC,
TGO, WRR.
High Resolution Grid Based : If using SGS , the retained sampled elevations can be used to
produce high-resolution (HR) grid outputs. All supported Grid Based outputs can be high-
resolution: HRTIF, HRGPKG, HRFLT, HRASC, HRNC, HRTGO, HRWRR.
Combination Mesh and Grid : This format includes: WRC.
GIS Based : GIS layers written as the simulation proceeds (similar to using the post-
processing TUFLOW_to_GIS utility). The format is set by GIS Format .

The selection of formats is controlled by the TCF command Map Output Format . One or more
formats may be specified for the whole model or for an Output Zone (refer to Section 11.2.5 ).

If no output format has been specified, the results are written by default using the XMDF format.
The following sections describe the supported map output formats.

@1583
11.2.2.1 Mesh Based Formats

Mesh based map outputs use a mesh of quadrilaterals and/or triangles of the 2D cells and any 1D
WLLs to manage and store the model results.

Section 11 Outputs - 3 / 68 Page 468 / 1094

 The recommended mesh format is the XMDF.

Section 11 Outputs - 4 / 68 Page 469 / 1094

 @1584
@1588 Table 11.1: Map Output Format Options - Mesh Based Output Formats

Format Description

@1587 The default mesh format.

XMDF (.xmdf) was developed by Aquaveo as a faster and more space

efficient replacement to the DAT format. The XMDF format complies with
the HDF5 standard. The advantages of the XMDF format are:

all specified Map Output Data Types are in the one file;
clear labelling of output types and maximum outputs;
XMDF
an internal folder structure is available for use by GUIs; and
supports compression (see XMDF Output Compression).

For more information on the XMDF structure for standard and specialised
outputs see the TUFLOW Wiki.

The XMDF format is supported by most GUIs, the TUFLOW QGIS Viewer
and the TUFLOW Utilities. For these reasons XMDF is the default.

The DAT (.dat) format is a legacy format now superseded by XMDF and no
DAT longer recommended for use. For more info on the DAT format see the
2018 TUFLOW Manual.

The TMO (.tmo) output format is utilised by 12D Solutions for their
TUFLOW GUI interface. If using 12D to display/view results this format will
need to be specified using Map Output Format . This format contains 2D
TMO domain cell centred outputs from the model.

Note, the Output Zones feature (Section 11.2.5 ) is currently not yet
available for the TMO format.

Section 11 Outputs - 5 / 68 Page 470 / 1094

 Format Description

WaterRIDE by Worley Parsons is commercial software for visualising and

post-processing hydraulic modelling results. TUFLOW supports the WRB
(.wrb), WRC (.wrc) (Section 11.2.2.1.1 ) and WRR (.wrr) (Section 11.2.2.4
) WaterRIDE formats. WaterRIDE triangulation format for visualising and
post-processing hydraulic modelling results. Results are only output in the
cell centred triangular mesh arrangement as WaterRIDE does not support
quadrilateral elements in a mesh.

One .wrb file is produced for each simulation that contains the model’s
ground/bathymetric elevations, water levels, velocities (scalar and vector),
and optionally the Z0 (VxD product) and one hazard category. The .wrb
format is restricted to these data types, other data types specified using
Map Output Data Types are ignored for WaterRIDE output. Also,
WaterRIDE can only display a single hazard category (the first one is used
WRB
if more than one is specified). If Z0 and/or a hazard category are not
specified for WRB output, WaterRIDE can optionally post-process these
hazard values noting that the maximum of these hazard values, and the
actual values, may differ from those directly output from TUFLOW due to
post-processing interpolation effects. Other data types such as depth are
also post-processed by WaterRIDE (and may differ from those directly
output from TUFLOW).

If maximums are tracked (see Maximums and Minimums ) these are also
added to the .wrb file for the data types mentioned above. Note that if
WaterRIDE is used to post-process maximums the values will be different
to those provided by TUFLOW. TUFLOW tracks maximums every
timestep, whilst WaterRIDE post-processes maximums using the values in
the .wrb file, which only occur every Map Output Interval .

A cell centred map output format. The output writes to NetCDF file format
and uses the 2D domain’s cell size and orientation. This feature is only
compatible with single 2D domain models and does not include any 1D
CC output via WLLs. The CC option allows for rotated TUFLOW model grids to
be output at the 2D cell size resolution without interpolation to a north-
south aligned raster. The file format of the output is described on the
TUFLOW Wiki.

Additional time outputs are available using Time Output Cutoff Depths or Time Output Cutoff
Hazards to output maps of the duration of inundation and the time of first inundation above
specified depth(s) or VxD(s).

The options in the table below only apply to the XMDF format. Only one (or none) can be
specified.

Note that the Map Output Format SMS HIGH RES option is a legacy feature no longer supported
and is, therefore, not included in the table below. For details on the SMS HIGH RES feature
search the 2018 TUFLOW Manual.

Section 11 Outputs - 6 / 68 Page 471 / 1094

 @1593
@1597 Table 11.2: Map Output Format Options - Options for XMDF Format

Format Description

@1596 This is the default SMS option and outputs ground elevations and
SMS
results at the cell corners only.

Outputs 2D cells as four triangles rather than as a quadrilateral if

DAT and/or XMDF are specified. The triangles are constructed so
that the 2D cell centre is a common vertex to all four triangles.
This means that the mesh is entirely constructed of triangles (four
triangles per 2D cell and any 1D WLL triangles).

SMS TRIANGLES Note: For the formats that rely on this triangle only mesh
(e.g. ASC, FLT, NC, T3, TGO, WRB, WRR), the SMS
TRIANGLES option does not need to be invoked. Only
specify SMS TRIANGLES if you require your XMDF or DAT
output to be based on a triangle only mesh rather than the
default mesh of quadrilaterals for 2D cells and triangles for
1D WLLs. See Section 11.2.2.1.1 .

11.2.2.1.1 Mesh Configurations

@1602

Quadrilateral and Triangle Mesh Option

The default mesh used by the XMDF format uses quadrilaterals (squares) for the 2D cells and
triangles for representing any 1D WLLs as discussed in Section 11.2.4 . Each 2D domain and the
1D WLL triangles are treated as separate meshes, although they will appear as one when viewing
the .2dm file.

The advantage of this format is that the amount of data output is optimised keeping file sizes small
with little loss of accuracy in translating results from the computational mesh.

Only the XMDF format supports the combination of quadrilaterals and triangles.

Triangular Mesh Option

Except for the XMDF format, all the other mesh-based formats use a triangular mesh to represent
the computational 1D and 2D domains. The triangular mesh is also used by the grid-based
formats (TIF, FLT, ASC, NC, TGO, WRR) to interpolate from the triangular mesh the values at the
grids cells’ centres (this is the cell centres of the output grid, not the 2D domain grid cells).

To utilise this format using the XMDF format, specify SMS TRIANGLES anywhere in the
arguments for the Map Output Format command.

The triangular mesh option incorporates output at the cell centres, so the exact water level
calculated by TUFLOW at the 2D domain cell centres is used when translating results, thereby
providing a slightly more representative surface of the hydraulic calculations. Each 2D cell is
represented as four triangles with a common vertex at the cell centre, giving a higher resolution
spatial representation than just using the 2D cell corners.

However, the number of nodes in the mesh for the 2D domains increases by 20% and the number
of elements by a factor of 4, therefore, the output file sizes will be larger and the viewing and
processing times possibly slower. Any triangular elements from 1D WLLs are not affected and
remain the same in either mesh arrangement.

Section 11 Outputs - 7 / 68 Page 472 / 1094

 2D Cell Corner Interpolation/Extrapolation

Irrespective of the mesh option being used, the Map Output Data Type values at the 2D cell
corners need to be interpolated (or extrapolated if at the wet-dry interface). Two methods were
developed that can be set using the command Map Output Corner Interpolation == METHOD B
or METHOD C. Method C (the default) is recommended as it is simpler and extensive testing has
indicated it resolves issues associated with prior methods. METHOD B does largely resolve earlier
issues, and has the added advantage that the effect of thin breaklines is better handled when they
are dry or flow is upstream controlled.

For model results where the water has risen upwards (e.g. river flooding), the Method B or C
approaches should cause no significant changes in results (i.e. fractions of a mm). Where the flow
is downwards over steep slopes, some changes in results at cell corners will occur, but usually
only slightly. However, maximum hazard values on very steep slopes may experience a more
significant change.

@1603
11.2.2.2 Grid Based Formats

Grid-based formats output the results over a regular grid in similar formats to DEMs and other
raster-based data. The output grid resolution and origin is not necessarily the same as the 2D
hydraulic modelling grid, and will also use any 1D WLL triangulations to include map based output
of 1D domains. Grid based formats are highly suited for use in GIS, and especially for handling
output from very large models (e.g. GPU models).

The available grid formats are listed in Table 11.3 . The output grid format is set with the Map
Output Format command, for example:

Map Output Format == TIF

Alternatively, instead of including a specific format (e.g. TIF or FLT) in the Map Output Format
list, this can also be specified using the Map Output Format == Grid command. In this case
the grids are written by default in TIF format. This can be changed to other grid formats by
specifying the specific format in the .tcf command Grid Format . If Write Check Files is used, the
DEM_Z and DEM_M grid outputs will be of the format specified by the Grid Format command (or
TIF by default). Note that not all formats support compression, so those that don’t can produce
considerably larger file sizes.

The output grids are placed in a sub-folder called “grids”. For TUFLOW Classic the default output
grid resolution is half the smallest 2D cell size (considering that multiple 2D domains may exist).
For TUFLOW HPC the default is half the 2D cell size. For HPC models using Quadtree, the output
resolution is the smallest 2D cell size. The resolution of the output grid can be controlled by the
Grid Output Cell Size command. Only one output grid resolution is possible. If multiple
commands exist, the last occurrence of the command will prevail. The origin of the output grid is
rounded to the nearest cell size. This can be set to the exact model origin using the Grid
Output Origin == Model Origin.

The TUFLOW grid output formats (listed in Table 11.3 ) support all available Map Output Data
Types (listed in Table 11.4 and Table 11.5 ). The minor exceptions are noted in Table 11.3 .

Grids outputs store data on a grid by grid basis and in a north-south direction, therefore
interpolation must occur to convert the data from the TUFLOW calculation points. The raster data
is interpolated from the values at the cell corners and centres.

Section 11 Outputs - 8 / 68 Page 473 / 1094

 For example, the image below shows:

A _grd_check file (black lines)

A _zpt_check showing the TUFLOW calculation (ZC, ZU, ZV and ZH) points;
An output water level TIF grid (underlying grey grid); and
Orange dotted lines showing the triangulation between the cell corners and centres.

The raster data (grid centre indicated by red cross) obtains its value from the triangulation
between A, B, and E.

To more closely align the grid output with the TUFLOW calculation points:

Set the domain to have an Orientation Angle of zero, and

Use the Grid Output Origin == Model Origin command.

The <format> Map Output Interval can be set to zero as follows to trigger only outputting the
maximums for those formats. For example:

TIF Map Output Interval == 0 ! Only output result maximums for TIF grids
FLT Map Output Interval == 0 ! Only output result maximums for FLT grids

All time outputs are supported by the grid map output formats. The grid file extensions are:

_TDur_<cutoff> for duration of inundation;

_TExc_<cutoff> for time <cutoff> is exceeded;
_TMax_h for time of peak water level; and
_TMax_V for time of peak velocity.

Section 11 Outputs - 9 / 68 Page 474 / 1094

 @1604
@1608 Table 11.3: Map Output Format Options - Grid Based Output Formats

Format Description

@1607 The GeoTIFF raster compressible format is supported from the 2023-03
Release and onwards and is the default format. A projection can be set for
the output GeoTIFF rasters by using the TIF Projection command.
Individual files are created for each output type, time, maximums, etc.

TUFLOW supports several compression methods for GeoTIFF, see TIF

TIF Compression , the default is the “deflate” method. A compression

predictor “horizontal differencing” is used to improve the compression ratio,
see TIF Compression Predictor . TUFLOW will default to using all
available CPU cores when writing GeoTIFF files which can speed up
processing when using compression. This can be changed by specifying
the number of threads using the command line argument “-nt[thread
count]”.

ESRI binary (float) version of the ASC format. The data is uncompressed.
The file header containing the dimensions of the grid is output to a .hdr
(text) file and contains the same header as for an .asc file. The remainder
of the output, the 3D surface values, is written to a .flt file as a binary dump

FLT rather than as a text file.

Advantages of this format are that it is very simple and is much faster to
write and open than the ASC format. Main limitations are that file sizes are
large, and a separate file needs to be written for every Map Output Data
Type specified and for every output time (that can be a lot of files!).

The GeoPackage grid format is supported from the 2023-03 Release

onwards. The format uses a tiled structure to make rendering and loading
faster by enabling the ability to only process the required tiles. The tiled
structure also makes pyramids (sometimes referred to as ‘overviews’)
inherently available for the format. Individual files are created for each
output type, time, maximums, etc.
GPKG
The GPKG raster outputs will be grouped if the Spatial Database
command is set to “grouped” (the default).

The GPKG raster format supports LZW compression of the data, see
GPKG Compression . A compression predictor “horizontal differencing” is
used to improve the compression ratio, see GPKG Compression Predictor
.

ESRI ASCII (.asc) uncompressed grid format, a long-established industry

standard format often used for transferring 3D surfaces between GIS
software.

ASC Advantages of this format are that it is very simple and can be viewed in a
text editor. Limitations are that for large grids the file maybe slow to write,
slow to open and work with, file sizes can be very large, and a separate file
needs to be written for every Map Output Data Type specified and for
every output time (that can be a lot of files!).

Section 11 Outputs - 10 / 68 Page 475 / 1094

 Format Description

Outputs grid files in the default grid output (.tif) unless Grid Format is
GRID
specified in the .tcf.

The NETCDF (Network Common Data Format) is a commonly used

compressible format for storing modelling and scientific data. A single file
is created that contains all output types, output times and static outputs
(e.g. maximums).

A number of NetCDF specific commands are supported as listed below.

The TUFLOW Wiki page TUFLOW NetCDF Raster Format provides
additional information.
NC
NetCDF Output Compression
NetCDF Output Start Date
NetCDF Output Time Unit
NetCDF Output Direction
NetCDF Output Format

If using FEWS to view NC output, please ensure that NetCDF Output

Format == FEWS has been set.

The TGO format is utilised by 12D Solutions for their TUFLOW interface.
The output is a north-south aligned raster and includes outputs from
multiple domains and water level lines. Unlike the mesh .tmo format, all
TGO Map Output Data Types are supported, and the resolution of the output
grids can be set using the command Grid Output Cell Size . Individual
files are created for each output type. As of the 2020-10 release the TGO
velocity angle is in radians, previously this was degrees.

A WaterRIDE uncompressed format that contains the time varying grid

output using a north-south aligned raster and includes outputs from
multiple domains and 1D WLLs. All Map Output Data Types are
WRR
supported, and the resolution of the output grids can be set using the
command Grid Output Cell Size . A single file is created for all output
types, times, etc. Due to no compression, file sizes can be very large.

@1613
11.2.2.3 High-Resolution Grids

When using sub-grid sampling (SGS) the sampled elevations are retained, including topography
modifiers such as breaklines. At the end of the geometry processing this allows a high-resolution
grid to be written and used for high resolution map outputs. All grid formats in Table 11.3 are
supported. Currently, high resolution raster outputs are only available for depth (d) and water level
(h) output data types. By default, by turning on high-resolution outputs, a high-resolution DEM
check file (_DEM_Z_HR) is also produced (which replaces the _DEM_Zmin check file).

To produce high-resolution output, add “HR” to the grid format. For example “HRTIF” or “HRFLT”
to produce a high resolution TIF or FLT respectively. Note, the Map Output Interval will also have
to be set, for example, “HRTIF Map Output Interval == 0” will output just the maximums
using the HRTIF format.

Section 11 Outputs - 11 / 68 Page 476 / 1094

 The high resolution grid output uses the following approach:

The water level at each HR raster output cell is interpolated from the computed 2D water
levels.
The depth is the difference between the interpolated water level and the terrain elevation
interpolated from the surrounding SGS sampled elevations.

The regular grid output interpolates depth from cell centres/corners with a default output resolution
of half the cell size. The difference between the regular and the HR grid output is illustrated in
Figure 11.1 .

@1614

Figure 11.1: Regular Grid Depth Output (Left) and HR Grid Depth Output (Right)

When modelling breaklines in TUFLOW, “thin” breaklines modify the cell face elevations but do not
modify the cell storages. When outputting the high-resolution outputs, the user can set whether
the cell face elevations are included using the .tcf command (the default is ON, to use face
elevations):

HR Grid Output Use Face Elevations == {ON} | OFF

The water level and depth interpolation approaches for the high resolution outputs can be altered
depending on the type of model (e.g. hydrology inflows or direct rainfall) and specifically how
TUFLOW outputs the high resolution results around thin breaklines. These output options are
discussed on the HR Output TUFLOW Wiki page.

HR grid outputs are also compatible with the output zone functionality, see Section 11.2.5 .

@1615
11.2.2.4 Combined Format

Combination of a mesh and grid-based approach. The only available combined format is the WRC
format. The WRC format produces a master (.wrc) file and one or more WRR and WRB files. The
approach adopted by TUFLOW is as follows:

Each 2D domain is output as a rotated WRR format grid with the cell size equal to the
TUFLOW cell size. The WRR format is significantly faster than than the WRB format due to its
grid-based formatting. The output values are the cell centre values for each 2D cell.
Any 1D WLL triangulations are output as a separate WRB file.
The WRC “master” file is output to the specified results folder, while the WRR and WRB files
are written to a “waterRIDE” sub folder.

Section 11 Outputs - 12 / 68 Page 477 / 1094

 @1616
11.2.2.5 GIS Based Format

GIS based map outputs use the format specified by GIS Format to write out map output as a
series of GIS layers. Gridded output format as GIS layers can be written directly from TUFLOW
during the simulation by including “GIS” in the Map Output Format command. This offers a similar
functionality to that using the TUFLOW_to_GIS utility via, for example, the –shp option. For scalar
outputs, these are output as a point GIS layer with a separate file for each output time. For vector
outputs, this can be either as a point or region GIS layer. Specific commands to this output format
are:

GIS Grid Vector Type

GIS Grid Vector Direction
GIS Grid Vector SF
GIS Grid Vector TTF

The commands above can be applied to all vector outputs or can be specific to the data type by
prefixing with a “v”, “q” or “W”, for velocity, unit flow or wind respectively. The example below sets
the scale factor to 1 for all outputs except unit flow, which has a smaller factor of 0.1.

GIS Grid Vector SF == 1.0 ! Set scale factor for all GIS vector output
to 1.0
q GIS Grid Vector SF == 0.1 ! Set scale factor for unit flow GIS output
to 0.1

@1617
11.2.3 Map Output Data Types

TUFLOW can output a wide range of output types in map format. Table 11.4 describes all the
non-hazard map output types, while Table 11.5 contains all flood hazard category (Z) map output
types. The map output types produced by a simulation are controlled using the .tcf command Map
Output Data Types .

The map output types’ flags are listed in the first column of the tables and are used to denote the
type(s) to be output. They can occur in any combination or order and are not case-sensitive. For
example, to output water level, velocity and unit flow, enter the following line in the .tcf file:

Map Output Data Types == h V q

Although optional, it is strongly recommended that spaces are used between each data type for
clarity.

The output types are available in a wide range of Map Output Formats and can be varied for
different formats (Section 11.2.2 ) and between output zones (Section 11.2.5 ). Not all Map
Output Data Types are available for all Map Output Formats due to limitations or constraints of
the type/format. The supported formats for each type are documented in Table 11.4 and Table
11.5 .

It is possible to get different output types for different output formats, as discussed in Section
11.2.2 . For example:

TIF Map Output Data Types == h V Z0

XMDF Map Output Data Types == h V q d ci z0

Section 11 Outputs - 13 / 68 Page 478 / 1094

 @1618
@1622 Table 11.4: Map Output Types (Excluding Hazard (Z) Types)

Map Output Supported

Flag Description
Data Type Formats

@1621 Atmospheric pressure in hPa. Atmospheric All formats

Atmospheric Pressure is only available if using the Read GIS excluding
AP
Pressure Cyclone or Read GIS Hurricane commands. TMO, WRB
Maximum and minimum output is not available. and HR.

Bed Shear Stress in N/m2 (or lbf/ft2 in English

Units) is given by the equation below where ρ is
density, g gravity, V velocity, n Manning’s n, and
y depth:

Metric Units:

2 2
ρgV n
2
τbed = (N /m )
1

y 3

English Units:
All formats
Bed Shear ρgV
2
n
2
excluding
BSS
2
τbed = (lbf /f t )
Stress TMO, WRB
1

2.208y 3

and HR.
The Bed Shear Stress map output can be
misleading at very shallow depths as the BSS
formula divides by the depth. The BSS and SP
outputs are linearly reduced to zero once the
depth is below a threshold (by default, 0.1m).
This threshold can be changed using the .tcf
command BSS Cutoff Depth .

Note, prior to the 2017 release BSS output in

English Units were in Poundals per square foot
(pdl/ft2).

Section 11 Outputs - 14 / 68 Page 479 / 1094

 Map Output Supported
Flag Description
Data Type Formats

The cumulative infiltration over the entire

simulation in mm or inches when a soil
infiltration method has been used (see Section
7.3.7 ). Also see the IR (infiltration rate) map
output type below. Maximum and minimum
output is not applicable/available as it is a
cumulative output.

Note, the CI output is restricted to models for All formats

Cumulative which the value is cumulative, specificially this excluding
CI means models that have:
Infiltration TMO, WRB

A single vertical soil layer. and HR.

No horizontal movement of ground water.

No drying of the soil layer through negative
rainfall.

When any of the three options (multiple vertical

layers, horizontal movement or negative rainfall)
are used, the water content in the layer is no
longer a “cumulative value”.

Classic Only. All formats

Courant excluding
Cr Courant number (2D domains only). Maximum
Number TMO, WRB
and minimum output is not available. and HR.

Cell Width No longer supported - previously available via

CWF N/A
Factor the legacy SMS HIGH RES option.

Section 11 Outputs - 15 / 68 Page 480 / 1094

 Map Output Supported
Flag Description
Data Type Formats

Water depths in m or ft. For the cell cornered

results formats (see Section 11.2.2.1.1 ) the
depths are calculated as the interpolated water
level at the nodes (see _h below) less the ZH
value. The interpolated water level may
occasionally lie below the ZH value, in which
case a negative depth may result, which is set to
zero by default (see Zero Negative Depths ).
Both maximum and minimum output are
available. All formats
d Depth For maximum depth output this is calculated at excluding

the end of the simulation based on the maximum WRB.

water level and the ground elevation. For models

that utilise varying ground elevations (using the
Read GIS Variable Z Shape or variable
geometry (VG) boundaries), care should be
taken when interpreting maximum depth outputs.
Hazard outputs (based on velocity and depth)
are tracked at each timestep, and the maximum
for these is the maximum at any timestep during
the model.

Depth to groundwater (from the ground surface)

over time in metres or feet when a groundwater
depth or level has been defined (see Section
7.3.7 ). All formats
Depth to excluding
dGW If using multiple sub-surface layers in TUFLOW
Groundwater TMO, WRB
HPC (see Section 7.4.5.2 it is the distance from
and HR.
the ground surface to the groundwater level of
the layer in question.

Maximum and minimum output is not available.

HPC Only.

The dt map output is a grid map output that

displays the calculated minimum timestep at
each grid cell. It does not necessarily align with All formats
Minimum the timestep adopted in the model (the timestep excluding
dt
Timestep in the model could be less if the previous TMO, WRB

timesteps were smaller). This helps identify and HR.

which cells in the model are controlling the

model timestep. For more information see the
TUFLOW Wiki.

Section 11 Outputs - 16 / 68 Page 481 / 1094

 Map Output Supported
Flag Description
Data Type Formats

Scalar data file containing the energy levels at

the element nodes (cell corners). The energy
levels are based on the interpolation of water
levels and dynamic head (V2/2g) at the output
location. As both the 1D and both 2D solutions
use a staggered computational scheme, the
interpolation of the water levels and/or velocities
to the output location may occasionally cause an
“increase” in energy to be apparent in the output,
therefore, energy output should be treated with
caution.
All formats
For 1D areas, this output should be treated with excluding
E Energy
additional caution as it is derived from TMO, WRB
interpolation of water levels and approximations and HR.
of the channel velocities across the WLLs, which
can be problematic in 1D channels with high
velocities. The energy output for 1D nodes is
available as part of the plotting output (Section
15.3.1 ).

Maximum energy levels is for when the

maximum water level occurs (Note: This may
cause undulations in the maximum energy
due to variations in the time of the maximum
water level).

All formats
Froude Froude number output. No maximum and excluding
F
Number minimum output is available at this stage. TMO, WRB
and HR.

Form Loss No longer supported - previously available via

FLC N/A
Coefficient the legacy SMS HIGH RES option.

Depth of water within each sub-surface layer(s)

when layered interflow has been defined (see All formats
Groundwater Section 7.4.5.2 ). Determined by dividing the excluding
GWd
Depth cumulative infiltration by porosity. TMO, WRB
and HR.
Reported in metres or feet.

Elevation of the groundwater surface (water

table) for each sub-surface layer(s) when All formats
Groundwater layered interflow has been defined (see Section excluding
GWh
Level 7.4.5.2 ). TMO, WRB
and HR.
Reported in metres or feet.

Section 11 Outputs - 17 / 68 Page 482 / 1094

 Map Output Supported
Flag Description
Data Type Formats

Groundwater moisture output. Dimensionless

All formats
number in the range of zero to one representing
Groundwater excluding
GWm a “fraction full” for each sub-surface layer(s)
Moisture TMO, WRB
when layered interflow has been defined (see
and HR.
Section 7.4.5.2 ).

Groundwater unit flow (m2/s, flow per unit width)

at the nodes (cell corners) of the sub-surface All formats
Groundwater layer(s) when layered interflow has been defined excluding
GWq
Unit Flow (see Section 7.4.5.2 ). TMO, WRB
and HR.
Reported in m2/hr or ft2/hr.

Groundwater flow velocity when layered interflow

has been defined (see Section 7.4.5.2 ). The All formats
Groundwater resulting groundwater velocity vector is excluding
GWv
Velocity calculated from the surrounding u and v-points. TMO, WRB
and HR.
Reported in m/hr or ft/hr.

Water level output. For the cell cornered results

formats (see Section 11.2.2.1.1 ) the water
h Water Level levels are interpolated from the water levels All formats.
calculated at the cell centres. Both maximum
and minimum outputs are available.

The infiltration rate in mm/hr or inches/hr over

time when a soil infiltration method has been
used (see Section 7.3.7 ). See also the CI All formats
Infiltration (cumulative infiltration) map output type above. excluding
IR Maximum and minimum output is not available.
Rate TMO, WRB

If using multiple sub-surface layers (see Section and HR.

7.4.5.2 ) the infiltration rate is reported for the

first (top) layer only.

TUFLOW Classic only (for HPC, see the ‘dt’

output).

Measure of the convergence level of the

solution. The measure is a cumulative value
All formats
since the last output time, therefore is an
excluding
MB1 Mass Balance effective way of identifying problem areas in a
TMO, WRB
model that repeatedly have poor convergence
and HR.
and most likely mass error. Very useful for
identifying problem areas within a model.

This output does not include 1D output from

WLLs.

Section 11 Outputs - 18 / 68 Page 483 / 1094

 Map Output Supported
Flag Description
Data Type Formats

TUFLOW Classic only (for HPC, see the ‘dt’

output).
All formats
Same as MB1 above but is accumulated over excluding
MB2 Mass Balance
the entire simulation. TMO, WRB
and HR.
This output does not include 1D output from
WLLs.

Manning’s n values. The n values only vary over

time for materials using the Manning’s n varying All formats
with depth feature. The n values at the cell excluding
n Manning’s n
corners in the _n.xmdf file are interpolated from TMO, WRB
the surrounding four cell mid-sides. Maximum and HR.
and minimum output is not available.

HPC Only.

The Shallow Wave Celerity Number. One of the All formats

Shallow Wave three controls TUFLOW HPC uses to determine excluding
Nc Celerity the maximum timestep to maintain stability. See TMO, WRB
Number the HPC Adaptive Timestepping Wiki Page for and HR.
discussion on adaptive timestepping and the Nc
number.

HPC Only.

The Diffusion Number. One of the three controls All formats

Diffusion TUFLOW HPC uses to determine the maximum excluding
Nd
Number timestep to maintain stability. See the HPC TMO, WRB

Adaptive Timestepping Wiki Page for discussion and HR.

on adaptive timestepping and the Nd number.

HPC Only.

The Courant Number. One of the three controls All formats

Courant TUFLOW HPC uses to determine the maximum excluding
Nu
Number timestep to maintain stability. See the HPC TMO, WRB

Adaptive Timestepping Wiki Page for discussion and HR.

on adaptive timestepping and the Nu number.

Section 11 Outputs - 19 / 68 Page 484 / 1094

 Map Output Supported
Flag Description
Data Type Formats

Unit flow (m2/s, flow per unit width) at the nodes

(cell corners). The resulting flow vector is
calculated from the surrounding u and v-point
velocities and the depth.
All formats
Vector Unit Unit flow may also be used as a measure of excluding
q
Flow flood hazard (i.e. velocity by depth or VxD). TMO, WRB
and HR.
Note: The maximum unit flow is not tracked for
the q output, the Z0 scalar hazard value option
can be used, as this output is tracked at each
timestep.

TUFLOW Classic only.

Flow regime. The output value is 0 (zero) for

normal (sub-critical flow with momentum);
greater than 1 for upstream controlled friction
flow (e.g. supercritical flow); ‑1.5 for broad-
crested weir flow; and ‑1 for flow through a flow All formats

constriction when the deck is submerged. No excluding

R Flow Regime
maximum and minimum output is available at TMO, WRB

this stage. The flow regime at the cell corners and HR.

and centre is a weighted average (using unit

flow) of the flow regimes at the four surrounding
cell mid-sides, therefore, where there’s different
flow regimes at any of the four cell faces the R
value can be misleading due to the averaging.

The route category output over time for

evacuation routes. The definition and number of
categories is based on the values specified
within the Cut_Off_Values attribute of the All formats
Route 2d_zshr GIS layer (see Section 11.4.2 ). The excluding
RC RC values are output as an integer representing
Category TMO, WRB
the closure category specified by the user. and HR.

The maximum RC category value is tracked

every timestep and output (if tracking maximums
is switched on, which is the default).

Section 11 Outputs - 20 / 68 Page 485 / 1094

 Map Output Supported
Flag Description
Data Type Formats

The cumulative rainfall in mm or inches over

time when direct rainfall has been applied to the
model (refer to Section 8.5.3 ). See also the
RFR (rainfall rate) map output type below. Both
the RFC and RFR outputs (see next item) are
inclusive of any boundary adjustments (e.g. in All formats
Cumulative the boundary database) and rainfall losses excluding
RFC applied in the materials file. Soil infiltration is
Rainfall TMO, WRB
applied once the rainfall has been applied to the and HR.
cells, so this is not accounted for in the rainfall
outputs, see also CI (cumulative infiltration) and
IR (infiltration rate) output types.

Maximum and minimum output is not

applicable/available, as it is a cumulative output.

The output contains the total rainfall losses

applied due the initial and continuing rainfall
losses specified in the Read Materials File (.tmf
or .csv) file. The RFML option can be used to All formats
Material track the rainfall based material losses that have excluding
RFML Based Rainfall been applied spatially. The RFC and RFR map TMO, WRB
Loss output data types can be used to output the and HR.
cumulative rainfall and rainfall rate.

Maximum and minimum output is not

applicable/available, as it is a cumulative output.

The rainfall rate in mm/hr or inches/hr over time

when direct rainfall has been applied to the All formats
model (refer to Section 8.5.3 ). See also the excluding
RFR Rainfall Rate
RFC (cumulative rainfall) map output type TMO, WRB
above. Maximum and minimum output is not and HR.
available.

Section 11 Outputs - 21 / 68 Page 486 / 1094

 Map Output Supported
Flag Description
Data Type Formats

Stream Power as given by the equation below

where τbed is bed shear stress (see BSS above)
and V is velocity.

2
StreamP ower = |V |τbed (W /m )

The Stream Power map output can be

misleading at very shallow depths as the BSS
formula divides by the depth. The BSS and SP All formats
outputs are linearly reduced to zero once the excluding
SP Stream Power depth is below a threshold (by default, 0.1m).
TMO, WRB
This threshold can be changed using the .tcf and HR.
command BSS Cutoff Depth.

Prior to the 2017 release SP output in English

Units were in Poundals per square foot (pdl/ft2).
From the 2017 release onwards the units are in
Pounds Force per square foot (lbf/ft2), therefore,
the SP values are 32.174 times smaller than for
releases prior to 2017.

The net source/sink inflows. Note the flow rate All formats
Sink / Source for a cell is shown at the ZH point (top right of excluding
SS the cell).
Flow TMO, WRB

Maximum and minimum output is not available. and HR.

Eddy viscosity coefficient. This is useful for All formats

checking the Smagorinsky coefficient values. No excluding
t Viscosity Coeff
maximum and minimum output is available at TMO, WRB
this stage. and HR.

This output contains the shear stress values

applied via the external stress file (.tesf). All formats

The output values are in Newtons per square excluding

tau Shear stress
metre (N/m2) for SI units and pound-force per TMO, WRB

square foot (lbf/ft2) for US customary (English) and HR.

units.

Section 11 Outputs - 22 / 68 Page 487 / 1094

 Map Output Supported
Flag Description
Data Type Formats

Flow velocity. The resulting velocity vector is

calculated from the surrounding u and v-points.

Note: The maximum and minimum velocities are

tracked over time, however, be careful
interpreting maximum velocities displayed as
vectors as the flow patterns may appear to be All formats
V Vector Velocity opposing each other - this is due to the excluding

maximum velocities not all occuring at the same HR.

instant in time. By default the maximum

velocities are tracked over 0.1m depth, below
this depth the velocity at maximum water level is
used. See the Maximum Velocity Cutoff Depth
command for more information.

All formats
Wind Vector output in m/s at a height of 10m.
excluding
WI10 Wind Vector Available when a cyclone/hurricane boundary is
TMO, WRB
used, see Section 8.7 .
and HR.

Elevations at the cell corners (ZH points). This

information is already contained in the .2dm file,
however, this option is useful if the model’s
bathymetry varies over time because of variable
geometry (2d_vzsh or VG boundaries) or for
morphological modelling. This output is very
useful if you are comparing two or more runs
that have different topography (e.g. before and
after scenarios), and you wish to easily view or
compare the topography for each scenario.
All formats
If the topography in the model does not change excluding
ZH Bathymetry
over time (i.e. no variable Z shapes or TMO, WRB
morphological changes), for the default .xmdf and HR.
output format the ZH Zpt values are output once,
rather than every timestep, thereby not
consuming disk space unnecessarily. The ZH
map output will appear under a XMDF folder
“Fixed”. This feature is only available if using the
XMDF format, for other output formats, the
bathymetry will be output at each output interval.

Currently, no maximum and minimum output is

available.

Section 11 Outputs - 23 / 68 Page 488 / 1094

 @1630
11.2.3.1 Hazard Data Types

Table 11.5 presents the hazard category outputs. Of note is that each hazard is tracked every
timestep for its maximum if Maximums and Minimums is set to “ON” or “ON MAXIMUMS ONLY”
(the default) to ensure that the peak hazard category is recorded during the simulation. Up to ten
(10) different hazard categories per simulation can be specified for map output. Grid map output
hazard categories are output as integer grids (i.e. values are rounded to the nearest integer when
a grid output cell centre is located at a change in category) when using Map Output Data Types
except for output Z0, ZUK0 and ZUK2, which are output as real numbers.

Users have the option to customise hazard outputs based on a .csv file input using the “ZUD1”
hazard type. This feature allows users to define a number of depth, velocity and depth-velocity
product thresholds to create custom hazard categories. Like other hazards these are assessed at
each computational timestep and the maximum is tracked every timestep. To specify a user
defined hazard, add output type “ZUD1” in the “Map Output Data Types ” command, e.g.:

Map Output Data Types == h d V ZUD1

The thresholds are defined through reading a .csv file using the following command:

Read Hazard File == <file_name>.csv

The csv file should contain three (3) columns defining the thresholds for depth, velocity, and
depth-velocity product respectively. The example below produces the same output as for “ZNZ1”
described in Table 11.5 .

@1631

Figure 11.2: Example Hazard File for User Defined Hazard

Category 1: D < 0.1. Note: the velocity, and depth-velocity product thresholds are effectively
not applied by using a large threshold value such as 99999.
Category 2: D < 0.5 and V < 1.0. Note: the depth-velocity product threshold is effectively not
applied by using the large threshold value of 99999.
Category 3: D < 1.0 and V < 2.0 and D*V < 1.0
Category 4: Otherwise
Dry points are assigned Category 0.

A maximum of 10 categories can be specified by the .csv file, but just one User Defined Hazard is
currently allowed per simulation. This functionality is compatible with both TUFLOW Classic and
HPC solvers.

Please email [email protected] if you would like to code a unique hazard output that is currently
not included as an output type option or possible using the user defined hazard type (ZUD1).

Section 11 Outputs - 24 / 68 Page 489 / 1094

 @1632
@1636 Table 11.5: Map Output Hazard (Z) Types

Supported
Flag Description
Formats

@1635
Z0 All formats Velocity x Depth product

Flood hazard category based on the Australian NSW

Floodplain Management Manual (NSW Goverment, 2005b ).
The output is an integer number from 1 to 3 as follows and as
illustrated in the figure below.

1: Low Hazard
2: Intermediate Hazard (dependent on site conditions)
3: High Hazard

Z1 All formats

V > 2.0: Category 5 (Extreme Hazard)

D*V > 1.0: Category 4 (High Hazard Floodway)
D > 1.0: Category 3 (High Hazard Depth)
V + 3.3*D > 2.64: Category 2 (High Hazard)
Otherwise Category 1 (Low Hazard)
Dry points are assigned Category 0

Z2 All formats

Section 11 Outputs - 25 / 68 Page 490 / 1094

 Supported
Flag Description
Formats

V > 2.4: Category 7 (Extreme Hazard)

D*V > 2.0: Category 6 (Extreme Hazard Floodway)
V > 2.0 OR V*D > 1.0: Category 5 (High Hazard Floodway)
D > 2.0: Category 4 (Extreme Hazard Depth)
D > 1.0: Category 3 (High Hazard Depth)
V + 3.3*D > 2.64: Category 2 (High Hazard)
Otherwise Category 1 (Low Hazard)
Dry points are assigned Category 0

Z3 All formats

Flood hazard mapping approach based on the Australian

Guidelines (CSIRO, 2000 ) using the following logic:

D ≤ 0.3 and V ≤ 0.38: Category 1 (Low Hazard)

D ≤ 0.6 and V ≤ 0.8 and D + 0.64*V ≤ 0.82: Category 2
(Medium Hazard)
D ≤ 1.2 and V ≤ 1.5 and D + 0.69*V ≤ 1.38: Category 3
(High Hazard)
Otherwise Category 4 (Extreme Hazard)
Dry points are assigned Category 0

Z4 All formats

Section 11 Outputs - 26 / 68 Page 491 / 1094

 Supported
Flag Description
Formats

Based on Figure L1 of the NSW Floodplain Risk Development

Manual (NSW Goverment, 2005b ), using the following logic:

Category 1 (low hazard): V ≤ 2 and V + 6.667 x D ≤ 3

Category 2 (vehicles unstable) : V ≤ 2 and V + 3.333 x D ≤
2.667
Category 3 (wading unsafe) : V ≤ 2 and D ≤ 2 and V x D ≤
1
Category 4 (extreme) : Otherwise

Z7 All formats

Flood hazard mapping approach based on the draft storm tide

hydraulic hazard categorisation developed for Moreton Bay
Regional Council (GHD, 2011 ). Z9 output values are 0 (zero)
for no hazard and 1 to 5 for H1 to H5 respectively.

Z9 All formats

Section 11 Outputs - 27 / 68 Page 492 / 1094

 Supported
Flag Description
Formats

Flood hazard category as outlined by Australian Emergency

Management Institute in 2014 (Australian Emergency
Management Institute, 2014 ). ZAEM1 output values are 0
(zero) for no hazard and 1 to 6 for H1 to H6 respectively.

ZAEM1 All formats

Flood Intensity output used by Gold Coast City Council

(Australia). The logic applied is as follows:

D < 0.3, V < 0.4 and D*V < 0.25: Category 1 (Low
Intensity)
ZGC1 All formats D < 0.6, V < 0.8 and D*V < 0.4: Category 2 (Medium
Intensity)
D < 1.2, V < 1.5 and D*V < 0.6: Category 3 (High Intensity)
Otherwise Category 4 (Extreme Intensity)
Dry points are assigned Category 0 (No Intensity).

Section 11 Outputs - 28 / 68 Page 493 / 1094

 Supported
Flag Description
Formats

Flood hazard output used by Moreton Bay Regional Council

(Australia). Where:
V > 2.5 or D > 2.5 or V*D > 2.5: Category 5 (H5)
V > 2.0 or D > 2.0 or V*D > 1.0: Category 4 (H4)
V > 3.2 - 4D: Category 3 (H3)
V > 0.5 or D > 0.3: Category 2 (H2)
Otherwise Category 1 (H1)
Dry points are assigned Category 0

ZMBRC All formats

Where:
H1: Hydraulically suitable for parked or moving cars.
H2: Hydraulically suitable for parked or moving heavy vehicles
and wading by able-bodied adults.
H3: Hydraulically suitable for light construction (e.g. Timber
frame and brick veneer).
H4: Hydraulically suitable for heavy construction (e.g. steel
frame and reinforced concrete).
H5: Generally unsuitable

No longer recommended by Melbourne Water. For details on

ZMW1 All formats
this hazard category, see the 2018 TUFLOW Manual.

No longer recommended by Melbourne Water. For details on

ZMW2 All formats
this hazard category, see the 2018 TUFLOW Manual.

Based on Melbourne Water (Australia) FM&M Technical

Specifications (Melbourne Water, 2016 ) to quantify Safety
Risk in Roads. The logic used is as follows:

ZMW3 All formats D*V < 0.4 and D < 0.4: Low Risk
D*V < 0.8 and D < 0.8: Medium Risk
Otherwise: High Risk
Dry points are assigned Category 0

Section 11 Outputs - 29 / 68 Page 494 / 1094

 Supported
Flag Description
Formats

The flood hazard category based on the Hamilton City Council

(New Zealand) Flood Hazard Report [HamiltonFloodMapping].

The categories are defined as:

D < 0.1: Category 1 (Insignificant)

D < 0.5 and V < 1.0: Category 2 (Low)
D < 1.0 and V < 2.0 and D*V < 1.0: Category 3 (Medium)
Otherwise Category 4 (High)
Dry points are assigned Category 0.
ZNZ1 All formats

Hazard category used by Auckland Council, New Zealand.

Category 1 (Low Safety Risk): D*V < 0.4, V < 3.0 m/s and
D < 0.5 m
Category 2 (Moderate Safety Risk): D*V < 0.8, V < 3.0 m/s
ZNZ2 All formats
and D < 1.2 m
Category 3 (High Safety Risk): D*V ≥ 0.8, V ≥ 3.0 m/s and
D ≥ 0.1m, and D ≥ 1.2 m
Dry points are assigned Category 0.

Section 11 Outputs - 30 / 68 Page 495 / 1094

 Supported
Flag Description
Formats

People Hazard category “Hazard to Adults” based on the

Australian Rainfall and Runoff (ARR) Project 10 Stage One
Report (Cox et al., 2010 ).
The values within the ZPA output are:

0 = Safe (no hazard)

1 = Low Hazard
2 = Moderate Hazard
3 = Significant Hazard
4 = Extreme Hazard

It is possible to specify cut-off depth/s representing when the

Safe category applies by using the .tcf command ZP Hazard
Cutoff Depth. Up to three values can be defined, which are the
cut-off depths for ZPA, ZPC and ZPI respectively.

The relevant tables and figures are reproduced below:

ZPA All formats

People Hazard category “Hazard to Children” based on the

ZPC All formats ARR Project 10 Stage One Report (Cox et al., 2010 ). Refer
to the description of output values for ZPA.

People Hazard category “Hazard to Infants and frail/elderly

People” based on the ARR Project 10 Stage One Report (Cox
ZPI All formats
et al., 2010 ). Refer to the description of output values for
ZPA.

Section 11 Outputs - 31 / 68 Page 496 / 1094

 Supported
Flag Description
Formats

The flood hazard category based on the Port Macquarie-

Hastings Council Flood Policy (Port Macquarie-Hastings
Council, 2018 ).

The logic used is as follows:

D < 0.4 and V < 0.5 and D*V < 0.2: Category 1 (Low Risk)
ZPMH All formats D < 0.8 and V < 2.0 and D*V < 0.5: Category 2 (Medium
Risk)
D < 1.8 and V < 2.0 and D*V < 1.5: Category 3 (High Risk)
V < 4.0 and D*V < 2.5: Category 4 (Very High Risk)
Otherwise Category 5 (Extreme Risk)
Dry points are assigned Category 0.

Hazard categories for the Queensland Reconstruction

Authority (Queensland Reconstruction Authority, 2012 ).

ZQRA All formats

Hazard category for the Queensland Department of Transport

and Main Roads. Areas of a model with the Material ID set to a
value of 100 (roads) will be tested for their submergence
/closure status:
ZTMR All formats
Material ID ≠ 100: No hazard reporting (0)
D <= 0: Road is immune (1)
D+V2/2g < 0.3: Road is submerged (2)
Other: Road Closed (3)

Section 11 Outputs - 32 / 68 Page 497 / 1094

 Supported
Flag Description
Formats

Customisable hazard output based on a .csv file input read in

using the Read Hazard File command. This feature allows
users to define a number of depth, velocity and depth-velocity
product thresholds to create custom hazard categories. The
csv file should contain three (3) columns defining the
thresholds for depth, velocity, and depth-velocity product
respectively.
ZUD1 All formats
The example below produces the same output as for “ZNZ1”:

This hazard type is further detailed in Section 11.2.3.1 .

The (real) value of the UK Hazard formula based on

ZUK0 All formats Environment Agency (2006 ) (see UK Hazard Formula , UK
Hazard Land Use and UK Hazard Debris Factor ).

The UK Hazard category (integer) based on Environment

Agency (2006 ) (see UK Hazard Formula , UK Hazard Land
Use and UK Hazard Debris Factor ).

ZUK1 outputs a .xmdf file containing an integer, as per:

ZUK1 All formats 0 = No Hazard (H ≤ 0)

1 = Low Hazard (H ≤ 0.75)
2 = Moderate Hazard (H ≤ 1.25)
3 = Significant Hazard (H ≤ 2.5)
4 = Extreme Hazard (H ≥ 2.5)

The (real) value of the UK Hazard formula based on UK

FD2320 Technical Report (Environment Agency, 2008 ).

F loodH azardRating = ((v + 0.5) ∗ D) + DF

ZUK2 All formats

Where:
v = velocity (m/s)
D = depth (m)
DF = debris factor

Section 11 Outputs - 33 / 68 Page 498 / 1094

 Supported
Flag Description
Formats

The UK Hazard category (integer) based on UK FD2320

Technical Report (Environment Agency, 2008 ).

Where:

1 = Low
2 = Moderate
3 = Significant
ZUK3 All formats 4 = Extreme

@1647
11.2.4 1D Map Outputs

1D domain results can be output in combination with 2D domain(s) by using the 1d_wll GIS layer
and the Read GIS WLL 1D command. 1d_wll GIS layer(s) are used to define and control the 1D
map output. The layer(s) contain lines (called Water Level Lines or WLLs) that cross or snap to 1D
channels and/or nodes. A WLL is essentially a line of horizontal water level, and should be
digitised on this basis (i.e. perpendicular to the flow direction).

The direction of WLLs is important. They must be digitised from left to right looking in the
positive direction of the digitised channel.

When viewing the results, if the 1D WLLs and 2D domains overlap, the 1D results are displayed
on top of the 2D results. However, depending on the viewing platform, when observing the scalar
and vector magnitudes as the cursor is moved around, the 2D values maybe given precedence
over the 1D where the overlap occurs.

Two WLL options are available. The preferred method can be specified by using the command
WLL Approach . Of the two options, Method A and Method B, Method B allows more advanced
and accurate mapping of 1D results in map formats and is the default and recommended method,
and that described below. For documentation on Method A, refer to the TUFLOW 2010 Manual.

It should be noted that water level lines do NOT change the 1D hydraulic computations, they are
purely used in order to display the 1D results in plan (2D) formats.

@1648
11.2.4.1 Water Level Lines

Ground elevations and optionally material (Manning’s n) values can be assigned to points along a
WLL. A more accurate representation of 1D domain velocity and flood hazard can be mapped
using this approach. The velocity at a point on the WLL is estimated by carrying out a parallel
channel analysis along the WLL using the flow in the channel the WLL is associated with as
explained further below.

Section 11 Outputs - 34 / 68 Page 499 / 1094

 The parallel channel analysis assumes the water surface slope is that of the associated channel,
and the water level at the WLL is linearly interpolated between the upstream and downstream
nodes based on the digitised channel length.

WLLs can have any number of vertices. The association of WLLs to channels and nodes is as
follows:

At the channel ends, to lock in the water level at a node, use a 3 vertex line with the middle
vertex snapped to the 1D node. If you use a 3 vertex line across a channel, the channel
“thalweg” is taken at the middle vertex, otherwise, for 2 vertex lines the mid-point of the WLL
line is used.
If a WLL crosses two or more channels, the channel closest to the middle vertex (3 point line)
or half-way point (2 point line) is used.
If a WLL middle vertex snaps to a node with two or more channels on the upstream side, the
channel that is closest in angle to the WLL’s perpendicular (based on the WLL’s two end
points) is used.
For 4 or more vertices, one of the middle vertices (i.e. not an end vertex) must snap to a
vertex on the channel line.

There is one 1d_wll attribute required as described in 11.6 . The attribute, Dist_for_Add_Points,
is the minimum distance in metres along which to generate points for that WLL. If
Dist_for_Add_Points is zero, only the vertices along the WLL are generated.

Estimates of the elevation, depth, velocity and other hydraulic outputs from the parallel channel
analysis are produced at each WLL point including any automatically added ones. The user can
subsequently assign elevations and materials to each point to improve the topographic
representation if so desired (see Section 11.2.4.2 ).

An automatically generated triangulation (TIN) of the WLL points is used to display the outputs in
map based formats.

@1649
@1653 Table 11.6: 1D Water Level Line (1d_wll) Attribute Descriptions

No Default GIS Attribute Name Description Type

@1652 The minimum distance

interval along the WLL to
generate elevation and
material sampling points
(WLL Points). These
points form the corners
1 Dist_for_Add_Points Float
of the triangulation.
If set to zero, no
additional points are
generated (i.e. only the
existing vertices along
the WLL are used).

Use the 1D command Read GIS WLL to specify the 1d_wll layer and automatically create 1D
map output for TUFLOW 1D domains. For Flood Modeller or XPSWMM linked TUFLOW models,
use Read GIS ISIS WLL or Read GIS XP WLL in the .tcf file to read the 1d_wll layer(s). The

Section 11 Outputs - 35 / 68 Page 500 / 1094

 Flood Modeller units or XPSWMM links will also need to be built into a GIS layer and read using
Read GIS ISIS Network or Read GIS XP Network from the .tcf file.

Several 1d_wll layers can be specified covering different sections of the 1D domain(s) if required.
The TIN of triangular elements is created from the WLL points and included in the .2dm mesh file
that can be viewed using the QGIS TUFLOW Viewer or in SMS to check they have been created
correctly. In particular, look for overlapping or strange triangulations that arise from WLLs not
being digitised correctly.

The default approach uses the processed cross-section data (height–width data) from the channel
for setting elevations at each WLL point. For Flood Modeller and XPSWMM, these data are
automatically fed through to TUFLOW and is based on the cross-section information entered into
the Flood Modeller/XPSWMM model.

If a WLL is snapped to a node, the processed data used for setting any bed elevations is from the
higher channel unless it is a bridge in which case it uses the bridge processed data.

WLL Automatic == CULVERTS is particularly useful for automatically generating WLLs for
pipe network systems. WLL No Weirs is useful for not assigning WLLs to weir channels where
they are in parallel to another channel (this is particularly useful for BW, CW and RW channels).

@1658
11.2.4.2 Water Level Line Points

If Write Check Files in the .tcf file is specified, two GIS check layers are created from the WLLs.
These are labelled 1d_WLLo and 1d_WLLp. 1d_WLLo (Water Level Line Objects) reproduces the
WLLs with attributes containing the channel and node the WLL is allocated to for cross-checking
purposes.

1d_WLLp layers (Water Level Line Points) contain all of the elevation points generated based on
the Dist_for_Add_Points attribute. This layer can then be used to allocate elevations (first
attribute) to each point from a DEM (in the same manner that 2D Zpts can be assigned
elevations).

A second attribute, RR, contains the relative resistance of each point (which will have a value of 1
when first generated). The RR attribute can be replaced by the integer material value at each point
by using GIS to assign values from material polygons. The material value must exist in the .tmf file
or a materials.csv file (see Read Materials File ).

The attributes of a 1d_WLLp layer created by Write Check Files and used in
Read GIS WLL Points , Read GIS ISIS WLL Points or Read GIS XP WLL Points are listed in
Table 11.7 .

The parallel channel analysis carried out for each WLL in future simulations will then use the WLL
point data to estimate velocities and other outputs across the WLL instead of using the default
approach of using processed hydraulic data as previously described. Note, the WLLs do NOT
change the 1D hydraulic computations, they are purely used in order to display the 1D results in
plan (2D) formats.

For Flood Modeller and XP-SWMM, the layers are essentially the same, but are named using
xWLLo and xWLLp.

Section 11 Outputs - 36 / 68 Page 501 / 1094

 Note: If using Read GIS WLL Points or Read GIS X1D WLL Points , this layer must be a copy of
the 1d_WLLp layer produced by Write Check Files . Points from this layer can be deleted, but not
added. At deleted points, the default of estimating an elevation from the channel’s processed data
is used. If the 1d_WLL layer is modified or any of the Dist_for_Add_Points attribute values
changed, the 1d_WLLp layer needs to be regenerated and repopulated again.

For culvert channels (R and C channel type), only the end and mid vertices are used along the
WLL, and the elevations are set to the culvert invert irrespective of the number of points along the
WLL or the Dist_for_Add_Points value.

@1659
@1663 Table 11.7: 1D Water Level Line Point (1d_wllp) Attribute Descriptions

Default GIS
No Description Type
Attribute Name

@1662 Ground elevation of the point. Automatically

generated from the channel cross-section
1 Z processed data or updated based on a Float
point inspection of a DEM or other
approach.

In the 1d_WLLp check file, the relative

resistance of the point. A value of 1 is
assigned if the elevation was estimated
from the channel’s processed data. If the
elevation was provided through a point
using Read GIS WLL Points , RR is the
material Manning’s n value divided by the

2 RR or Material channel’s n value. Float

In a 1d_WLLp layer being used in Read

GIS WLL Points or Read GIS X1D WLL
Points , this column should either be set to
an integer material value (normally sourced
from a GIS layer of material polygons) – the
material value must exist in the .tmf file
(see Read Materials File ).

Elevation values along WLLs for bridge channels are always based on the processed data
(i.e. any WLLp Z values are overridden) to ensure that the bridge deck underside is correctly
represented. This has benefits when using the post-processing utility TUFLOW_to_GIS.exe (see
Section 17.3 ) when extracting obverts of structures for longitudinal profiles.

A useful tip at a junction of 1D channels is to use a connector for any side channels (Type = “X” –
see Section 5.9.3 ). Separate WLLs can then be allocated to the side channel and main channel
removing the confusion that sometimes occurs in generating the triangulation between WLLs at
junctions.

Section 11 Outputs - 37 / 68 Page 502 / 1094

 @1668
11.2.4.3 Adding Triangles into the 1d_WLL Layer

When using Method B, triangular regions can also be included in the 1d_WLL layer (as a separate
region or polygon layer if using the .gpkg or .shp formats). The triangles are inserted into the WLL
triangulation. This is particularly useful at junctions or between parallel channels to enhance the
WLL TIN by facilitating a smooth transition of the water level surface at, for example, junctions or
across meanders to infill areas and avoid steps in the output surfaces.

The triangles must snap to the ends of WLL line objects. In the example below, the WLLs are
shown in red and the triangles are shown as yellow. These are connected (snapped) to the ends
of the WLLs. The map output surfaces will interpolate over the triangle based on the hydraulic
output values at the snapped WLLs.

If the region object is not correctly snapped an ERROR 1311 message occurs, pointing to the
vertex on the triangle that is not snapped.

@1669

Figure 11.3: Adding Triangles into 1d_WLL Layer to Infill Areas

@1670
11.2.5 Output Zones

Output Zones are a powerful feature that allows users to generate map and check file outputs for
sub-regions of a model. The region is defined using a polygon feature using the 2d_oz_empty
template file. No attributes are associated with the polygon. One polygon per output zone and GIS
layer is recommended. Note, multiple polygons within a single layer are not supported.

Different Output Zones can have different output formats, start/end times, frequency of output, and
output data types. Any number of Output Zones can be defined for a model, and all, a selection of,
or none of the Output Zones can be activated when the model is run.

Output zones are very useful, particularly for large models, where higher frequency map output is
required for a portion of a model, for example to create an animationfor an urban region using a
shorter map output interval. Another useful purpose is to create an Output Zone for a problematic
section of model that requires closer examination, by generating output on a fine time interval
during the period in question. Another benefit is simply reducing the size of the output files by only
outputting where information is required, and disabling the output for the whole model using Map
Output Entire Model == OFF. Output zones currently only apply to TUFLOW’s map and GIS
check file outputs (i.e. does not apply to time series and other plot outputs).

Note: the Model Output Zones command is used to select which Output Zones are to be
used (activated). If this command is omitted, no output from the Output Zones is written.
Separate multiple Output Zones using a “|” (vertical bar or pipe character). For example, to output
from zones ZoneA and ZoneC specify:

Section 11 Outputs - 38 / 68 Page 503 / 1094

 Model Output Zones == ZoneA | ZoneC

If there are numerous Output Zones, it is recommended that the definitions are placed in one or
more separate files, and use the Read File command to reference these file(s). This will keep the
size of the .tcf file to a minimum. This, however, is not a requirement.

Each Output Zone is defined using a definition block as follows:

Define Output Zone == <ZoneA>

…..

End Define

The following commands can be used within an Output Zone definition. With the exception of
Read GIS Output Zone , all commands are optional. The optional commands can be used to
change the default setting or the setting applied outside the Output Zone definitions.

Read GIS Output Zone

Map Output Format
Start Map Output
End Map Output
Map Output Interval
Map Output Data Types
Output Folder
Maximums and Minimums
Maximums and Minimums Only for Grid
Write Check Files

The Read GIS Output Zone reads a GIS layer containing one or more polygons that define the
regions to be output. The attributes of the layer are not used.

Note: If one of the commands above is not specified within the Output Zone’s definition, the
latest setting of that command prior to the Output Zone’s definition, or the global default if
the command has not been used prior to that location in the .tcf file, will be used. If, for
example, all output is to be in the .xmdf format, only specify Map Output Format == XMDF
once and prior to any Output Zone definitions.

Map Output Entire Model can be used outside an Output Zone definition block to turn on or off
map output for the entire model (the default is ON). If set to OFF only map output for any Output
Zones is written. Map output commands that occur outside Output Zone definitions apply to the
entire model output.

Example: Defining an Output Zone

The example below defines Output Zone “ZoneA”. In the example, a DEM_Z check grid will be the
only check layer written for the Output Zone, and Grid, WRB and XMDF outputs will be produced.
The Grid output will consist of water level (h) and VxD (Z0) results, starting at time 0.5 hours and
ending at 4 hours at an interval of 0.5 hours. The WRB and XMDF output files will contain water
levels (h), velocities (V) and the ZMBRC hazard categories starting at the simulation beginning
and finishing at 6 hours at an interval of 6 minutes.

Section 11 Outputs - 39 / 68 Page 504 / 1094

 ! Entire Model settings
Map Output Format == TIF XMDF
Map Output Interval == 3600 ! Default output interval is hourly
TIF Map Output Interval == 0 ! Maximums only for .tif output
Map Output Data Types == h v q d z0 ! Default output types

Model Output Zones == ZoneA | ZoneB ! Output both of the zones below

Define Output Zone == ZoneA

Read GIS Output Zone == ..\2d_oz_ZoneA.shp

Write Check Files Include == DEM_Z
Map Output Formats == TIF XMDF WRB
End Map Output == 6.0
Map Output Interval == 360
TIF Start Map Output == 0.5
TIF End Map Output == 4.0
TIF Map Output Interval == 1800
XMDF Map Output Data Types == h V ZMBRC
TIF Map Output Data Types == h Z0
End Define

Define Output Zone == ZoneB

Read GIS Output Zone == ..\2d_oz_ZoneB.shp

Map Output Formats == XMDF
Map Output Interval == 360
XMDF Map Output Data Types == h V ZMBRC
End Define

@1671
11.2.6 Gauge Level Output

The 2d_glo GIS layer uses the .tcf command Read GIS GLO and writes map-based output data
when the water level at the gauge reaches user defined levels.

Note: Map output based on reaching gauge levels replaces the conventional approach of
using a Start Map Output time and a Map Output Interval .

The 2d_glo GIS layer is used to define the location of the gauge within the modelled extent. The
gauge is digitised as a point object within a 2d_glo layer with the attributes as described in Table
11.8 and referenced within the .tcf using the command Read GIS GLO .

For TUFLOW Classic only, the water level at the gauge location is tracked by TUFLOW throughout
the simulation and output to the Console DOS Window (see Section 14.2 ) preceded by the
letters “GL”.

When the water level reaches a user specified value, the map output results at that simulation
time will be written. The results are therefore useful for mapping the predicted area of inundation
for specified gauge heights. The range of water levels at the gauge for which the results are
written may be defined using one of two methods:

Section 11 Outputs - 40 / 68 Page 505 / 1094

 By referencing a .csv file within the 2d_glo GIS layer using the first attribute. The .csv file
contains a single column of levels, and comment lines are allowed using the “!” or “#”
character. If a .csv file is specified in the first attribute, the remaining attributes are not used,
but dummy or empty values for these attributes must exist.
By populating the remaining attributes of the 2d_glo GIS layer as described below.

When using the attributes of the 2d_glo GIS layer to define the gauge heights, the map output
results are first written when the water level at the gauge reaches the specified
“Bottom_elevation”. Subsequent results are written as the water level at the gauge rises based on
the value of the “increment” attribute. The map output ceases once the water level at the gauge
reaches the “Top_elevation”.

For example, if the 2d_glo GIS layer has been defined as shown below, map output results will be
written when the water level at the gauge reaches 41m, 41.5m, 42m, 42.5m and 43m.

Only one gauge location may be specified per model simulation. If more than one object exists
within the 2d_glo layer, the gauge that is monitored by TUFLOW will be the last digitised point
object. Similarly, if the Read GIS GLO command is used more than once, only the last
occurrence of the command will be used.

Section 11 Outputs - 41 / 68 Page 506 / 1094

 @1672
@1676 Table 11.8: 2D Gauge Level Output (2d_glo) Attribute Descriptions

No Default GIS Attribute Name Description Type

@1675 Filename (and relative or full

path if needed) of the file
containing the gauge levels to
trigger map output. Must be a
comma or space delimited text
file such as a .csv file. Only the
first column is used, and this
column must contain the gauge
levels. Comment lines using a
leading “!” or “#” can be used at
1 Datafile any point within the file. Char (254)

If this attribute is blank, the

following three attributes are
used to define the gauge levels
to trigger map output. If this
attribute is not blank, the
following three attributes are not
used, but they must exist and
can simply be populated with
empty or default values.

The water level in m above

datum at the gauge at which the
2 Bottom_Elevation Float
writing of map output results will
commence.

The water level in m above

datum at the gauge at which
3 Top_Elevation Float
writing of the map output results
will cease.

The water level increments in

metres between the
4 Increment Bottom_Elevation and Float
Top_Elevation at which the map
output results will be written.

@1681
11.3 Time-Series Outputs

Time-series results (sometimes referred to as Plot Output) produces output for graphing in charts
and profiles. The data output are specified using the Map Output Data Types command, at an
interval specified by the Time Series Output Interval command.

Time-Series data can be output for 1D domains (Section 11.3.1 ) and 2D domains (Section 11.3.2
). If the total flow across the floodplain is required for a 1D/2D model where the river is in 1D and
the floodplain in 2D, flows can be combined using Reporting Locations (Section 11.3.3 ). The

Section 11 Outputs - 42 / 68 Page 507 / 1094

 Structure Reporting feature outputs time-series and summary data for structures (Section 11.3.4
).

There are two formats available for time-series outputs: comma-separated values (.csv) (the
default) and NetCDF (.nc). One of the advantages of NetCDF is all the timeseries output is in a
single compressed .nc file, rather than multiple uncompressed .csv files. To change the format use
Time Series Output Format command.

It is possible to write 1D and 2D time-series outputs as the simulation progresses, using the Write
PO Online command.

@1682
11.3.1 1D Time-Series Output

Time-series data output from 1D domains is available for a range of hydraulic parameters. The
Output Data Types ECF command or the 1D Output Data Types TCF command controls the
types to output. The options are:

A: flow area at channels (m2);

E: energy at nodes (m);
H: water level at nodes (m);
Q: flow at channels (m3/s);
QI: integral flow at channels (m3);
S: structure and grouped structure output (see Section 11.3.4 );
V: velocity at channels (m/s); and
Vol: volume at nodes (m3).

To review the 1D time-series data see 15.3 .

@1683
11.3.2 2D Time-Series Output

Time-series data output from 2D domains is available for a range of hydraulic parameters (as
listed in Table 11.9 ). Output takes the form of time-series hydrographs (referred to as PO – Plot
Output) or longitudinal profiles (LP) over time.

This is carried out by creating one or more GIS layers containing points, lines and regions that
define the locations of PO and LP output. Figure 11.4 illustrates how 2d_po objects are
interpreted.

The start time for PO and LP output and the output interval is set using Start Time Series Output
and Time Series Output Interval . If no start time is specified the simulation start time is used. If
no output interval is specified the simulation will stop with ERROR 0046 to prevent excessive
amounts of memory and disk space from being used.

The output is written to a .csv file and also to the _TS layer (refer to Section 15.3.4 ). 2D domain
time-series (PO) output is synchronised with 1D domain output by default. This allows both 1D
and 2D time-series to be placed in the _TS layer. Set Output Times Same as 2D to OFF in the
.ecf file if 1D and 2D time-series data is not to be synchronised. In this case, no 2D PO is written
to the _TS layer.

Section 11 Outputs - 43 / 68 Page 508 / 1094

 Maximums and minimums are output to four additional rows near the top of the _PO.csv file, and
columns in the _LP.csv files, containing the Maximum, Time of Maximum, Minimum, and Time of
Minimum values. The _TS GIS layer also contains the tracked values. For TUFLOW Classic this
information is tracked every computational timestep. For TUFLOW HPC the maximum/minimum
values are post-processed at the end of the simulation based on the Time Series Output Interval ,
not every computational timestep. Tracking of maximums and minimums can be disabled by
setting the Maximums and Minimums Time Series command to OFF in the .tcf file.

@1684

Figure 11.4: Interpretation of PO Objects and Map Output

@1685
11.3.2.1 Plot Output

The data types available for PO are as listed in Table 11.9 , noting that only supported object
types (i.e. Point, Line and Region) for the data type are documented in the table. PO data is read
into a simulation using the Read GIS PO .tcf command. This is carried out by creating one or
more GIS layers containing points, lines and regions that define the locations of PO and LP
output. Figure 11.4 illustrates how 2d_po objects are interpreted.

Section 11 Outputs - 44 / 68 Page 509 / 1094

 @1686
@1690 Table 11.9: Time-Series (PO) Data Types - Point, Line or Region

Flag Description Comments

@1689 Point: Represents the current water content

of each layer (mm or in of pure water). This
CI Cumulative Infiltration value may increase or decrease depending
on the flows into and out of the cell (it is not
the cumulative value).

Point: Depth of the nearest cell.

Line: The average depth of all wet cells along

the line. Note: In TUFLOW Classic if a line
with more than 2 vertices (i.e. a polyline) is
D_ Depth used, the average water level along each line
segment is output, therefore, use of polylines
is not recommended for this output type at
present. TUFLOW HPC, will take the average
depth along the entire polyline.

Point: Water level at the cell center of the

nearest cell. If the cell is dry, the ground level
G_ Gauge Level (ZC) is output. Used for Read GIS Objects to
record gauge levels when a receptor is first
inundated. Refer to Section 11.3.3 .

Point: Depth of water within sub-surface

GWd Groundwater Depth layer(s) (cumulative infiltration divided by
porosity).

Point: Elevation of groundwater surface

GWh Groundwater Level (water table) within sub-surface layer(s),
reported in m or ft.

Point: A dimensionless number in range 0 - 1

GWm Groundwater Moisture representing “fraction full” of the sub-surface
layer(s).

Point: Unit flow magnitude within the sub-

surface layer(s).

GWq Groundwater Unit Flow Line: Total flow passing through the given
line within each sub-surface layer(s). The
positive flow convention is left to right looking
downstream (same as the Q_ type).

Point: Angle of unit flow vector within each

Groundwater Unit Flow
Gwqa layer. Reported in degrees clockwise from
Angle
north (i.e. a compass bearing).

Groundwater Unit Flow Point: Unit flow u-component within each

Gwqu
U-Component sub-surface layer(s).

Section 11 Outputs - 45 / 68 Page 510 / 1094

 Flag Description Comments

Groundwater Unit Flow Point: Unit flow v-component within each

GWqv
V-Component sub-surface layer(s).

Region: Total volume of water within the

GWVol Groundwater Volume
polygon for each layer (m3 or ft3).

Point: Water level of the nearest cell. If the

H_ Water Level (Head)
cell is dry, the ground level (ZC) is output.

Region: The average water level within the

HAvg Average Water Level
region (wet cells only).

Point:
Used to define the upstream (HU) and
downstream (HD) water levels of a QS
structure (see QS below and Section 11.3.4
). The 2D water level is used to populate the
upstream and downstream water level data in
the new structure output feature. For a point
the water level at the nearest 2D cell centre is
used.
Downstream and
To associate the HU and HD objects with the
HD HU Upstream Structure Water
QS line, all three (QS, HU and HD) must have
Levels
the same ID for the 2d_po Label attribute
(see Table 11.10 ).

Note that the water levels over time are

output to a 2D PO .csv file and the summary
information at the flood peak to the new
_SHmx.csv file. If the point or line is
completely dry, -99999 is output to the .csv
files. The _SHmx.csv file is currently not
produced for 2D only models.

Region: The maximum water level within the

HMax Maximum Water Level
region.

Section 11 Outputs - 46 / 68 Page 511 / 1094

 Flag Description Comments

Line: The flow crossing the line.

The flow is determined by summing the flow

across cell sides whose perpendiculars
intersect the line (see Figure 11.4 ).

The flow is positive if the water is flowing

away from you when looking in a direction
with the start of the PO line on your left and
the end of the line on your right.

If digitising a flow line across a 1D channel

that is carved through the 2D domain, ensure
Q_ Flow or discharge that the line is digitised so that it crosses the
1D channel where there is a change in colour
in linked 2D HX cells as shown in the
1d_to_2d_check or _TSMB1d2d layers
(thematically map using the Primary Node if
not using MapInfo). The 1D flow can then be
added manually in a spreadsheet. However,
note that Read GIS Reporting Location is
now the preferred method for cumulating
flows across a line for 1D/2D models. See
Section 11.3.3 for discussion on
Reporting Locations.

Line: The flow area is calculated using the

QA Flow Area same cell sides as for Q_. An adjustment for
oblique lines is made.

Line: Integrates the flow (as determined for

Q_ above) over time (i.e. the area under a Q_
time-series curve) (i.e. cumulative volume). If
QI Integral Flow
Write PO Online is set to ON, the integral flow
is not calculated until the simulation is
complete.

Qin Flow In Region: The flow into a region.

Qout Flow Out Region: The flow out of a region.

Section 11 Outputs - 47 / 68 Page 512 / 1094

 Flag Description Comments

Line: Same as Q_ above, but also used to

set up a 2D structure output (see Section
11.3.4 ) that will include in addition to the 2D
flow any flows from intersected 1D structures
and the split between below and above deck
QS Structure Flow
flows. Note the flow output to the 2D PO .csv
files is only the 2D flow, while that to the new
_SQ.csv file is the combined 1D/2D structure
flow. The _SQ.csv file is currently not
produced for 2D only models.

Line: The X component of Q_ (i.e. the sum of

QX Flow in X-direction.
the flows at the u-points).

Line: The Y component of Q_ (i.e. the sum of

QY Flow in Y-direction.
the flows at the v-points).

Region: Sink / source flows applied within the

SS Sink Source region (rainfall, infiltration, source area inflow
and SX flows).

Point: The magnitude of the resolved vector

based on the two u-points and two v-points of
the cell in which the point falls. Exactly which
cell is selected may be uncertain if the point

V_ Velocity falls exactly on a cell’s side.

Line: Velocity as Q_/QA (i.e. the depth and

width averaged velocity along the line). Prior
to release 2020-10-AA it used the cell in
which the line starts.

Point: The angle of V_ (degrees relative to

VA Velocity Angle
east where east is zero, north is 90, etc.).

Vol Volume Region: Total volume within the region.

Point: The magnitude of the u-point velocity

Vu or Uu u-point velocity
(i.e. across the right hand side of the cell).

Point: The magnitude of the v-point velocity

Vv v-point velocity
(i.e. across the top side of the cell).

Point: The magnitude of the average of the u-

VX Velocity in X-direction point velocities (i.e. across the left and right
hand sides of the cell).

Point: The magnitude of the average of the v-

VY Velocity in Y-direction point velocities (i.e. across the bottom and
top sides of the cell).

Table 11.10 describes the GIS attributes of the 2d_po layer.

Section 11 Outputs - 48 / 68 Page 513 / 1094

 @1695
@1699 Table 11.10: 2D Plot Output (2d_po) Attribute Descriptions

Default GIS
No Description Type
Attribute Name

@1698 Any combination of the two letter flags

listed in Column 1 of Table 11.9 (limit of
1 Type 10 flags per entry). For example, to output Char (20)
velocity and flow time-series for the same
line, enter “V_Q_”.

Label up to 30 characters long defining

the name of the time-series. The label
appears at the top of the columns of data
in the _PO.csv file. Spaces are permitted,

2 Label but do not use commas. Char (30)

Read GIS Reporting Location is the

preferred method for cumulating flows in
2D1D models. See Section 11.3.3 for
discussion on Reporting Locations.

Optional field for entering comments. Not

3 Comment Char (250)
used.

@1704
11.3.2.2 Long Profile Output

H_ (water level) and V_ (velocity) are the only data types available for long profile (LP) outputs. LP
locations and data types are initiated for a simulation using the Read GIS LP .tcf command.

Table 11.11 describes the GIS attributes of the 2d_lp layer. The 2d_lp layer(s) contain lines
defining where the profile data are to be generated. Each line is given a label to uniquely define
the profile in the output. The starting vertex of the line will set the distance origin for the profile.

The advantage of having TUFLOW generate the profiles directly rather than post-processing them
is the outputs will be slightly more accurate due to no post-processing interpolation rounding, plus
if the profile(s) are repeatedly being plotted, the plotting process can be streamlined via python
scripts that use the LP outputs.

Section 11 Outputs - 49 / 68 Page 514 / 1094

 @1705
@1709 Table 11.11: 2D Longitudinal Profiles (2d_lp) Attribute Descriptions

Default GIS
No Description Type
Attribute Name

@1708 Specify “H_” to output water level. Specify

1 Type Char (20)
“V_” to output velocity.

Label up to 30 characters defining the

name of the longitudinal profile. The label
2 Label appears at the top of the columns of data Char (30)
in the _LP.csv file. Spaces are permitted.
Commas are not permitted.

Optional field for entering comments. Not

3 Comment Char (250)
used.

@1714
11.3.3 Reporting Locations

Read GIS Reporting Location allows for plotting of time-series results that automatically
combines 1D and 2D outputs. For example, it is possible to digitise a reporting location line that
extends across 1D and 2D domains, including multiple 2D domains, and TUFLOW will sum the
flow across any 1D channels intersected by the line and all the 2D cells. This will save the need to
post-process time-series output from 1D and 2D domains to accumulate the flow.

Reporting location lines are digitised into a 0d_RL GIS layer containing only a single attribute, the
name of the reporting location, as outlined in Table 11.12 . Points, lines and regions can be used.
Points will be treated as water level output, lines as flow output and regions as volume output. For
a point snapped to a 1D node, the 1D water level is used, if no 1D node is snapped a 2D water
level is output.

The flow line can cross 1D and 2D sections of the model, for the 1D channels it does not have to
snap to any vertices on the channels, it just needs to intersect them.

@1715
@1719 Table 11.12: 0d_RL Reporting Location Attributes

Default GIS
No Description Type
Attribute Name

@1718 The name of the reporting location.

1 Name Lines and points can share the same Char (32)
name.

The RL outputs are written to the “plot\csv\” folder. The following files are produced:

_RLL_Q.csv - flow time-series;

_RLL_Qmx.csv - maximum flow information;
_RLP_H.csv – water level time series;
_RLP_Hmx.csv – maximum water level information;
_RLR_Vol.csv - volume time-series; and
_RLR_Volmx.csv - maximum volume information.

Section 11 Outputs - 50 / 68 Page 515 / 1094

 As well as the maximum water level and flow information, the time that these occur, the water level
at maximum flow and vice versa, and the maximum change between timesteps are also output to
the mx.csv files.

The RLs are also output to the plot\gis PLOT GIS layers and can be viewed and their time-series
data displayed using the TUFLOW Viewer using the QGIS TUFLOW Plugin as illustrated in Figure
11.5 .

An example model using reporting locations is available in the Example Models on the TUFLOW
Wiki. In addition, see Section 15.4.3 for information on plotting of Reporting Location results.

@1724

Figure 11.5: Example of the QGIS TUFLOW Plugin for a Reporting Location

@1725
11.3.4 Structure Output

The Structure Reporting feature outputs time-series and summary data for single and grouped
structures. 1D and 2D structures are all output together to give a complete set of results. The
summary output at the flood peak also produces the flow split between below and above deck,
along with other information such as the head drop. The structure output is particularly useful in
the reporting of hydraulic structure flows and afflux.

Structures are classified according to the following logic:

1D Structures:

1D structures that are in parallel (i.e. two structures that link to the same upstream and
downstream nodes) are automatically grouped together and treated as a single structure for
this output. The ID assigned to the group is the structure with the lowest bed elevation. Note
that the directions of the digitised channels is important, that is, to form a group all channels
must be digitised in the same direction.
For 1D structures that have no parallel 1D structures, these are also included in the output so
as to provide a complete set of results for all 1D structures.
The flow split between below and above deck is based on the structure geometry, except
weirs contributing to the below deck flow and/or above deck flow, depending on the
configuration.

2D and 1D/2D Structures:

Section 11 Outputs - 51 / 68 Page 516 / 1094

 To create a structure output that includes 2D flow, and optionally any 1D structures, the “QS”
PO line is digitised in a 2d_po layer (see Section 11.3.2.1 ). All 2D flow across this line and
any 1D structures that intersect this line are grouped together. The 1D structure’s 1d_nwk line
does not have to snap with the QS line; they only have to cross over each other. The ID
assigned to the structure output group is the 2d_po QS Label (see Table 11.10 ).
If the 2d_po QS line selects cell sides that are modified by the Layered Flow Constriction or
2D Bridge feature, the summary output will split the flow into a below and above “deck”
component based on Layers 1 to 2 being below “deck” and Layer 3 and 4 above.
2d_po HU and HD lines or points can be used to define the upstream and downstream water
levels of the structure. HU objects should be located upstream of the structure and HD
downstream. The average 2D water level along a line object will be used to populate the
upstream and downstream water level data in the output. Lines can have more than two
vertices (i.e. polylines are accepted). To associate the HU and HD objects with the QS line, all
three (QS, HU and HD) must have the same ID for the 2d_po Label attribute Label (see Table
11.10 ). If a QS line has no HU and/or HD objects associated with it, output that cannot be
produced, such as the water level drop across the structure, is given a -99999 value in the
_SHmx.csv output file described below. HU and HD inputs are necessary for 2d_lfcsh and
2d_bg bridges.

An example model of the structure output for a bridge represented by a 2d_lfcsh is available in the
Example Models on the TUFLOW Wiki.

The structure output is located in the plot/csv folder and includes:

_SQ.csv file that contains time-series data of the flow through the structure. This file is similar
to other time-series .csv output, but it only contains 1D and/or 2D structures as described
above.
_SHmx.csv file that contains a summary of each structure when the upstream water level
reached its maximum. To generate this output the flow and other information is tracked every
timestep for grouped structures. The output columns include: flow, area and average velocity
for below and above deck; total flow, area and average velocity for the whole structure;
upstream and downstream water levels; the head drop across the structure (i.e. upstream
minus downstream water level); and the time these data were recorded (e.g. the time the
upstream water level peaked).
Time-series output for the upstream and downstream water levels are available through the
1d_H.csv, 2d_HD.csv and 2d_HU.csv files. Note that for the 2d_HD.csv and 2d_HU.csv files,
if all 2D cells are dry a -99999 is output.

See Section 15.4.3 for further information on plotting of grouped structure results.

Two structure group check files are output if a model contains any structure groups (either
automatically created, or via a “QS” type line in a 2d_po layer). The check files are both .csv files
as follows:

<simulation name>_Str_Grp_All.csv, contains information for all structure groups, including

single 1D structures.
<simulation name>_Str_Grp_Multi.csv, contains information for structure groups that are
comprised of more than one 1D channel or are generated from a 2d_po “QS” line.

For more information on the structure group check files, please see the Check File Page on the
TUFLOW Wiki.

Section 11 Outputs - 52 / 68 Page 517 / 1094

 @1726
11.4 Specialised Outputs

Specialised outputs include:

Receptors: records the flood level and time at one or more gauge(s) when the receptor is
inundated above the specified trigger level, see Section 11.4.1 .
Evacuation Routes: provides additional information (e.g. first point of closure) along routes,
see Section 11.4.2 .

@1727
11.4.1 Receptors

Read GIS Objects RECORD GAUGE DATA records the flood level and simulation time at one or
more gauge(s) when receptors are first inundated above their trigger inundation levels (e.g. floor
levels). Read GIS Receptors can be used as an alias to Read GIS Objects . Level output
associates a flood level at one or more gauges with the time of first inundation at properties,
buildings, or other areas of interest within the modelled extent.

When the water level at the property reaches a user-defined trigger inundation level, the gauge
height and simulation time are recorded and tagged to the receptor. This is particularly useful for
flood warning and forecasting studies where property specific information on the likelihood of a
property being inundated for a given gauge height can be generated. An example of translating
gauge data information to catchment receptors can be found in the TUFLOW Wiki Example
Models.

Gauges are defined as a point within a 2d_po GIS layer with type “G_” (see Section 11.3.2 and
Table 11.9 ). The levels from all gauges are recorded at each receptor once inundated.

Receptors must be GIS point and/or polygon objects located in one or more GIS layers nominally
prefixed by 2d_obj or 2d_rec. Each object within the layer represents a receptor, property or other
object of interest. For information on the attributes of the GIS layer see the Read GIS Objects
.tgc command. The command also includes options to set the Zpt elevations to the receptor level
or the first attribute in the layer (for example, to set the Zpts to the floor level of the buildings), or
to alternatively use the existing ZC elevations.

Once simulated, a GIS layer is written to the location as specified using the .tcf command Output
Folder , and has a _GDO extension standing for Gauge Data Output. The layer contains point
objects (for regions the centroid is used). The attribute data for the layer are described in Table
11.13 . Figure 11.6 shows an example of how the output GIS layers may be used to illustrate the
flooding of properties in relation to the water level at a gauge.

As well as outputting the water levels at gauge objects (as described above), the water levels at
all point reporting locations and flows for all line reporting locations are also recorded. The
reporting locations can be 1D and/or 2D locations. See Section 11.3.3 for a full description of the
reporting location functionality. For example, flows past a gauge can be recorded, including
combined flows from 1D channels and the 2D domain(s).

Section 11 Outputs - 53 / 68 Page 518 / 1094

 @1728
@1732 Table 11.13: 2d_GDO_ Gauge Data Output Attributes

GIS Attribute Description

@1731 The water level in metres or feet above datum at <gauge_1>

<gauge_1> (as defined in a 2d_po layer) when the water level first reaches
the Trigger_Level at the property/building/object.

If a second, third, fourth… gauge exists, the water level in

<gauge_n>…
metres above datum at each gauge.

The simulation time in hours when the water level at the

Time
receptor first reaches the Trigger_Level.

The trigger inundation level at the receptor. The level will be

either the first attribute in the GIS layer (typically either the
ground level of the property or the floor level of a building), or
Trigger_Level
the lowest ZC value within the property or building polygon if
the “USE ZC” option is specified (i.e. Read GIS Objects USE
ZC ).

“Y” if the ZC 2D cell elevation was used for the Trigger_Level;

Use_ZC
“N” if not.

@1737

Figure 11.6: Example Use of Gauge Data Output Layer

@1738
11.4.2 Evacuation Routes

Evacuation routes can be specified to output information relating to:

Evacuation route suitability;

Warning times;
Risks;
Degree of route inundation; and
Duration of inundation.

The .tgc Read GIS Z Shape Route is used to define the routes and, by default, also adjust the
Zpt elevations along the route using the standard Z Shape options. The 2d_zshr layer is the same
as a 2d_zsh layer, but with three additional attributes, as shown in Table 11.14 . Note, if using the

Section 11 Outputs - 54 / 68 Page 519 / 1094

 TUFLOW HPC SGS functionality (Section 7.4.3 , the cells/faces selected by this command are
assumed flat (e.g. the traditional sampling approach using a single cell centre/face elevation).

The commands Set Route Cut Off Values and Set Route Cut Off Type can be used in the .tcf
and/or .tgc files. If used in the .tcf file, this sets the default values for the 2d_zshr Cut_Off_Type
and Cut_Off_Values attributes if these attributes are left blank. The default values can be changed
between different Read GIS Z Shape Route commands in the .tgc file by repeat usage of the
same commands.

The _RCP output layer is a layer of points showing where a route’s cut off value(s) were first
exceeded (e.g. first point of closure). The layer contains the attributes as shown in Table 11.15 .

The _RC.xmdf output file contains the Route Categories over time and is written when adding RC
to the .tcf command Map Output Data Types . This file can be used to view and animate the route
category values.

A range of evacuation route examples are available in the Example Models on the TUFLOW Wiki.

Section 11 Outputs - 55 / 68 Page 520 / 1094

 @1739
@1743 Table 11.14: 2D Z-Shape Route (2d_zshr) Attribute Descriptions

No Default GIS Attribute Name Description Type

@1742 Unless the BRIDGE Shape_Options

is specified (see below), the Z
1 Z Shape lines adjust the Zpts as Float
described in Table 7.5 for the
same attribute.

Unless the BRIDGE Shape_Options

is specified (see below), the Z
2 dZ Shape lines adjust the Zpts as Float
described in Table 7.5 for the
same attribute.

Refer to the same attribute in Table

3 Shape_Width_or_dMax Float
7.5 .

BRIDGE: Does not use the Z

attribute to adjust the Zpts, instead
uses it to assign evacuation route
categories. This allows for a Z
Shape Route Line to cross a river
without physically blocking it.
Because a route can be comprised
of more than one line (as long as
each line is given the same
4 Shape_Options Char(20)
Route_Name) they will all be
regarded as being part of the same
route. Therefore, to represent a
bridge, split the route line either
side of the bridge and give all three
lines the same Route_Name, with
the line representing the bridge or
river crossing assigned a
Shape_Options of “BRIDGE”.

Used to label the evacuation route.

A route can be split into several
lines if required, provided all the
lines have the same Route_Name
5 Route_Name attribute. This can be useful where Char(40)
the route is more easily sourced or
digitised as several lines, or if using
the BRIDGE option described
above.

Section 11 Outputs - 56 / 68 Page 521 / 1094

 No Default GIS Attribute Name Description Type

Options are as follows:

Blank: The value from the

latest Set Route Cut Off Type
command is applied at that
point in the .tgc file.
Depth: Depth is used to define
the cut-off (default setting).
VxD, Z0 or Hazard: The
velocity x depth hazard product
is used.
6 Cut_Off_Type Char(40)
V or Velocity: The velocity is
used.
Energy: Energy depth is used.
The energy-depth is calculated
as:

2
V
EnergyDepth = d +
2g

More than one 2d_zshr layer may

be used if different cut-off types are
required.

Section 11 Outputs - 57 / 68 Page 522 / 1094

 No Default GIS Attribute Name Description Type

A comma delimited list of one or

more values (e.g. depths) used to
categorise the severity of the
overtopping along the routes. For
example, if “0.1, 0.3, 0.7” is
specified for a depth Cut_Off_Type,
then where the water depth
exceeds 0.1 m, these sections of
the route are assigned a Category
1; above 0.3 m deep Category 2;
and above 0.7 m Category 3. The
values must be in ascending order.
7 Cut_Off_Values Elsewhere the route is assigned Char(80)
Category 0 (i.e. no or less than
Category 1 overtopping). The Route
Categories are output over time in
the _RC.dat file and summarised in
the _RCP layer. Multiple cut-off
values allow for the assessment of
different risk levels (e.g. shallow
depths would be acceptable for
most vehicles and people to safely
negotiate, while deeper depths
would only be acceptable for higher
set vehicles).

@1749
@1753 Table 11.15: RCP Output (2d_zshr) Attribute Description

GIS Attribute Description

@1752
Route_Name The name of the route.

Cut_Off_Value The cut off value applied.

The simulation time in hours the Cut_Off_Value was

First_Cut_Off_Time
first exceeded.

The simulation time in hours when the Cut_Off_Value

Last_Cut_Off_Time
was last exceeded.

The duration in hours that the Cut_Off_Value was

exceeded – not necessarily the difference between
Duration_Cut_Off
the first and last cut off times if the route reopened
during this time.

@1758
11.5 Check and Log Files

The options to control check and log file outputs are discussed in Chapter 14 , with common
commands to control these outputs listed in Table 11.16 .

Section 11 Outputs - 58 / 68 Page 523 / 1094

 @1759
11.6 Output Control Commands

A wide range and variety of commands allow the user to configure TUFLOW output to be different
to the default settings. Table 11.16 lists these commands in different categories followed by a
brief description.

Section 11 Outputs - 59 / 68 Page 524 / 1094

 @1760
@1764 Table 11.16: Commands used to Control TUFLOW Outputs

Requirement Command Description Category

@1763 Define the projection

for the output of GIS
layers. Not all
projection commands
are mandatory,
i.e. only specify
projection settings for
GPKG Projection
the formats required.
Mandatory , SHP Projection , GIS
Commands are:
or MI Projection
GPKG Projection ,
MI Projection , SHP
Projection , GIS
Projection Check ,
SHP Projection
Check Method , TIF
Projection .

Specify one or more

Map Output
Mandatory map output formats to Map
Format
be written.

Mandatory command
that controls the
frequency of map
Map Output
Mandatory output. Alternatively, Map
Interval
set this value to zero
to only output
maximums.

Mandatory command
Time Series that controls the
Mandatory Time-Series
Output Interval frequency of time-
series output.

Customise which
Write Check Files
Recommended check files/layers to Check
output.

Customise the
Recommended Log Folder location for the .tlf File Management
and other files.

Section 11 Outputs - 60 / 68 Page 525 / 1094

 Requirement Command Description Category

Customise the parent

folder for the 2D
based output files. If
the command is place
Recommended Output Folder File Management
in the .ecf or 1D
Domain controls the
folder for the 1D
based output files.

Controls the format

Recommended GIS Format GIS
for output GIS layers.

Controls the map data

types to be output.
Map Output Data
Recommended Default is just water Map
Types
level and velocity, but
there are many more!

Change the default

distance that a pit and
Pit Channel Offset its results are
Optional Check
displayed relative to
the 1D node the pit
flows into.

Set to ON to output
Write X1D Check additional check files
Optional Check
Files for linked external 1D
schemes.

Switch mass balance

Mass Balance
Optional tracking and Console
Output
outputting on or off.

Set the time interval

Mass Balance
Optional for outputting mass Console
Output Interval
balance information.

Controls how often

information is
Screen/Log displayed and written
Optional Console
Display Interval to the .tlf file whilst a
simulation is
underway.

Override the drive

Optional Output Drive letter for all output File Management
files.

Control which output

Optional Output Files File Management
files are to be written.

Section 11 Outputs - 61 / 68 Page 526 / 1094

 Requirement Command Description Category

Customise the
Simulations Log
Optional location for logging File Management
Folder
simulations.

Output empty GIS

layers. Very useful
Write Empty GIS
Optional command when File Management
Files
setting up a new
model.

Controls how and

Write Restart File
Optional when restart files are File Management
at Time
output.

Sets the interval at

Write Restart File
Optional which to write a File Management
Interval
restart file.

Controls the version

Write Restart File
Optional of the restart file File Management
Version
feature to output.

Controls the approach

on whether to keep
Write Restart
Optional overwriting or give a File Management
Filename
unique name for each
restart file.

Global setting on
Optional XF Files whether or not to use File Management
and output XF files.

Set a unique text to

XF Files Include in
Optional be included in XF File Management
Filename
filenames.

Add gauge levels and

Read GIS Objects
Optional other information to GIS
GIS receptor layer(s).

Output a GIS layer of

Write GIS Domain the 2D domains
Optional GIS
processed thus far in
the .tgc file.

Output a GIS layer of

the current 2D Zpts
Optional Write GIS Zpts GIS
elevations at that
point in the .tgc file.

Section 11 Outputs - 62 / 68 Page 527 / 1094

 Requirement Command Description Category

Sets how the outputs

are written when
using GeoPackages.
The grouped (default)
Spatial Database option will group
Optional GIS
Output outputs by folder
location. For example
all check file outputs
will be contained
within one database.

Controls the format

Optional Grid Format for output GIS grid Grid
layers.

Sets the cell size of

output grids, including
Grid Output Cell
Optional check grids. This can Grid
Size
be different to the 2D
cell size(s).

Change how the grid

Grid Output Origin
Optional output origin is Grid
determined.

Output a GIS layer of

the current active 2D
Optional Write GIS Grid cells and their Grid
attributes at that point
in the .tgc file.

UK Hazard Debris
Factor Change the default
UK Hazard settings on how the
Optional Hazard
Formula UK flood hazard
UK Hazard Land output is calculated.
Use

Change the cutoff

depth for outputting
ZP Hazard Cutoff
Optional People Hazard Hazard
Depth
categories (ZPA, ZPC
and ZPI).

Change the default

BSS Cutoff Depth cutoff depth setting
Optional Map
for bed shear stress
output.

Section 11 Outputs - 63 / 68 Page 528 / 1094

 Requirement Command Description Category

Change the end time

for map output to be
different to the
simulation end time.
Optional End Map Output Map
Useful for output
zones where a
shorter output period
is required.

Change the default

cutoff depth for
setting whether a 2D
cell is wet or dry in
the map output.
Map Cutoff Depth Useful for direct
Optional Map
rainfall modelling.
Only used for map
output, ie. it does not
affect the hydraulic
computations like Cell
Wet/Dry Depth does.

Switch on or off the

map output for the
entire model. Useful if
Map Output Entire
Optional using output zones Map
Model
and map output for
the whole model is
not needed.

Change the default

depth that the
Maximum Velocity
Optional approach to tracking Map
Cutoff Depth
maximum velocities is
changed.

Change from regular

time-based map
output to map output
produced at different
Optional Read GIS GLO Map
water levels at a
gauge. GLO stands
for Gauge Level
Output.

Read GIS WLL Change the ground

Points elevations and
Optional Map
Read GIS X1D materials at WLL
WLL Points points along WLLs.

Section 11 Outputs - 64 / 68 Page 529 / 1094

 Requirement Command Description Category

Read GIS WLL Include the results

from 1D elements in
Optional Read GIS X1D Map
the map output using
WLL WLLs.

Change the start of

map output to be
Optional Start Map Output Map
different to the
simulation start time.

Add time of
exceedance and time
Time Output Cutoff of duration for one or
Optional Map
more depth or hazard
values to the map
output data set.

Adds flags to the

.2dm file for use by
some map output
Optional Meshparts viewers such as SMS Other
to control the display
of different parts of a
model.

Add the hidden 1D

Reveal 1D Nodes
Optional nodes used in 2D/2D Other
links to the 1D output.

Controls the
parameter to use
Set Route Cut Off when determining
Optional Other
Type whether a route is
closed. For example,
depth or hazard.

Define one or more

Set Route Cut Off
Optional values for route Other
Values
closure categories.

Change the units of

Optional CSV Time Time-Series
the time column.

Start the time column

Optional Excel Start Date at a specific date for Time-Series
use in Excel.

Section 11 Outputs - 65 / 68 Page 530 / 1094

 Requirement Command Description Category

Controls whether 1D
nodes and channels
are output in
Optional Order Output alphanumeric order or Time-Series
in the order they are
processed during
input.

Set up 2D longitudinal
Optional Read GIS LP Time-Series
profile output.

Set up 2D time-series
Optional Read GIS PO Time-Series
output locations.

Read GIS Set up combined 1D

Optional Reporting Location and 2D time-series Time-Series
output locations.

Change the start of

Start Time Series time-series output to
Optional Time-Series
Output be different to the
simulation start time.

Write time-series
output at each time
map output is written
Optional Write PO Online Time-Series
(rather than just at the
end of the
simulation).

Change the default

Maximums and setting on whether to
Optional Tracking Max/Min
Minimums track maximums
and/or minimums.

Controls whether grid

based map output is
Maximums and
only written out as
Optional Minimums Only for Tracking Max/Min
maximums, ie. switch
Grids
on or off the grid
temporal map output.

Maximums and Controls whether to

Optional Minimums Time track maximums for Tracking Max/Min
Series time-series outputs.

Display a water level

Display Water on the console
Advanced Console
Level window whilst
running.

Section 11 Outputs - 66 / 68 Page 531 / 1094

 Requirement Command Description Category

Show file opening

Force File IO
Advanced information to the Console
Display
console window.

Controls how much

information is
Advanced Verbose Console
displayed and written
to the .tlf file.

Insert a file into a

Advanced Read File File Management
control file.

Define user variables

for use within the
control files. Useful
Advanced Set Variable File Management
for setting output
folder names based
on a scenario.

Change when and

TSF Update
Advanced how often the .tsf file File Management
Interval
is to be updated.

Add the maximum

Calibration Points water levels to a GIS
Advanced GIS
GIS File layer of calibration or
gauge points.

Apply different
approaches to
interpolating results to
Map Output
2D cell corners.
Advanced Corner Map
Primarily provided for
Interpolation
backward
compatibility for
legacy models.

Change how the bed

WLLp Interpolate
Advanced level along a WLL is Map
Bed
assigned.

Define Output
Set up a definition
Zone
Advanced block of commands Output Zones
…
for an output zone.
End Define

Model Output Controls which output

Advanced Output Zones
Zones zones are output.

Read GIS Output Defines the region for

Advanced Output Zones
Zone the output zone.

Section 11 Outputs - 67 / 68 Page 532 / 1094

 References

@1770
@1769
Australian Emergency Management Institute. (2014). Australian Emergency Management
Handbook 7: Managing Floodplain Best Practice in Flood Risk Management in Australia.
https://knowledge.aidr.org.au/media/3521/adr-handbook-7.pdf

@1771
Cox, R., Shard, T., & Blacka, M. (2010). Australian Rainfall and Runoff Revision Project 10:
Appropriate Safety Criteria for People. Austalian Institute of Engineers.
https://arr.ga.gov.au/__data/assets/pdf_file/0006/40578/ARR_Project_10_Stage1_report_Final.
pdf

@1772 (2000). Floodplain Management in Australia Best Practice Principles and Guidelines.
CSIRO.
CSIRO Publishing.

@1773
Environment Agency. (2006). UK FD2321 Technical Report - Flood Risks to People: Phase 2
Project Record. UK Government;
https://assets.publishing.service.gov.uk/media/602bbb768fa8f50386a7f8aa/Flood_risks_to_peo
ple_-_Phase_2_Project_Record.pdf.

@1774
Environment Agency. (2008). Explanatory Note for FD2320 and FD2321 Project Record.
https://assets.publishing.service.gov.uk/media/602bbdcfe90e070561b31432/Explanatory_note
_for_FD2320_and_FD2321_project_record.pdf.

@1775(2011). MBRC Storm Tide Management Study: Stage 1 – Scoping Report.

GHD.

@1776
Melbourne Water. (2016). Flood Mapping Projects Guidelines and Technical Specifications
(Version 1).

@1777Goverment. (2005b). Floodplain Management Manual. NSW Department of Land; Water

NSW
Conservation (NSW Government).

@1778
Port Macquarie-Hastings Council. (2018). PORT MACQUARIE-HASTINGS COUNCIL FLOOD
POLICY. https://www.pmhc.nsw.gov.au/files/assets/public/v/1/document-files/your-
council/publications/policies/port-macquarie-hastings-council-flood-adopted-2018-12-12.pdf.

@1779
Queensland Reconstruction Authority. (2012). Planning for Stronger, More Resilient Fl Oodplains:
Part 2. https://www.qra.qld.gov.au/sites/default/files/2018-10/resilient-floodplains-part2-
full_0.pdf.

Section 11 Outputs - 68 / 68 Page 533 / 1094

 @1784

@1785
Section 12 Hardware and Operating System

@1786
12.1 Introduction

This chapter provides information and guidance that aims to help users choose computer
hardware that will suit their modelling needs. TUFLOW Classic and HPC utilise distinctly different
solution schemes, and likewise have different requirements with regard to the choice of computer
hardware. Descriptions for a number of hardware related commands and options that are specific
to HPC are provided in Section 12.8 .

Additional material on performance/benchmarking and hardware selection advice can be found on

the TUFLOW Wiki:

Hardware Speed Benchmarking

Hardware Selection Advice

@1787
12.2 Operating Systems

TUFLOW Classic and HPC are only available as 64-bit binaries for 64-bit Microsoft Windows
operating systems. Unix/Linux and Mac operating systems are not currently supported. While
TUFLOW Classic and HPC may run on older versions of Windows, support is only available for
Windows 10 and later, and Windows Server 2016 and later.

@1788
12.3 TUFLOW Classic

TUFLOW Classic uses the ADI (alternating direction implicit (Stelling, 1984 )) finite difference
scheme that has been further refined by Syme (1991 ). For further details on the TUFLOW
Classic solution scheme refer to Section 1.1.1 . It is a highly efficient scheme, but is difficult to
parallelise to use multiple threads. As such it runs on a single core of the main CPU (central
processing unit). General hardware advice for TUFLOW Classic is summarised below:

As all modern CPUs have multiple cores, it is possible to run more than one model at a time
on the computer, provided the user has access to sufficient licences.
If running only one model at a time, the primary factor for model speed is the single core
computational capability of the CPU. Generally this is mostly driven by the CPU clock speed -
a CPU with fewer cores but a higher clock speed will likely provide better performance than
one with many cores and a lower clock speed. CPU type and architecture do also play a role
in single core performance. For more information refer to the subsection on performance

Section 12 Hardware and Operating System - 1 / 8 Page 534 / 1094

 proxies. When running models with Classic, having a dual socket mainboard will be of little
benefit if running just one model at a time. Dual socket mainboards are capable of holding two
CPUs, doubling the total number of CPU cores available (e.g. 2 x 16 core CPUs), these are
primarily found in server setups.
If running multiple models simultaneously, the memory bandwidth between CPUs and the
mainboard RAM is quite important, in which case a dual CPU mainboard will usually offer
better performance than a single CPU mainboard. Further, running multiple models
simultaneously will also require increased CPU RAM, which again typically favours a dual
CPU mainboard.
The mainboard memory required for a particular model will vary significantly due to a number
of factors related to model setup. In general the memory required will scale proportionally with
number of model cells.
There is no requirement for a particular GPU (Graphics Processing Unit) to be installed.
However, having a medium quality GPU installed may assist with graphics rendering in any
GIS software being used for visualising model inputs and outputs.
The amount of CPU RAM will determine the size of the model that can be run or a number of
models that can be run at one time. Faster RAM will result in quicker runtimes, however this is
usually a secondary consideration to chip speed, cache size and architecture.

@1789
12.4 TUFLOW HPC (Including Quadtree)

TUFLOW HPC uses an explicit finite volume scheme which is parallelised to utilise multiple CPU
cores, or equally the thousands of cores available on GPUs. The explicit finite volume scheme is
not as computationally efficient as the ADI finite difference scheme used in TUFLOW Classic.
However, because it can be parallelised, benchmarking has found that using the HPC solution
scheme on a modern GPU can run a typical model anywhere from 10 to 100 times faster than
using the Classic scheme on a single core of a modern CPU. For further details on the TUFLOW
HPC solution scheme refer to Section 1.1.2 .

@1790
12.4.1 TUFLOW HPC Solver on CPU

TUFLOW HPC can be run using multiple CPU cores of a single or dual CPU mainboard, in which
case it may offer solution times that are comparable with TUFLOW Classic on a single CPU core.
However, most users prefer to utilise the performance of GPU compute, refer to Section 12.4.2 .
Note that compute using GPU does require a GPU module licence, refer to Section 1.1.5 .

@1791
12.4.2 TUFLOW HPC Solver on GPU

TUFLOW HPC uses the CUDA API that NVIDIA makes available for their GPUs, and therefore
only NVIDIA GPUs are supported. The GPU is a physically separate device that is connected to
the mainboard at a PCI slot. It has its own separate memory which has to be sufficient to hold the
working data for the model solution process, and draws power from the main power supply unit
through its own supply cables. The computer’s power supply unit must be capable of supplying the
mainboard (with the CPUs) and the GPUs attached to the mainboard. The power draw of the
GPUs and the cooling requirements of the whole system can become a constraining issue with
regard to the overall system design.

Section 12 Hardware and Operating System - 2 / 8 Page 535 / 1094

 Note that due to the use of NVIDIA CUDA API, AMD GPU are not supported.

@1792
12.4.3 Types of GPU

In general, the price and performance of a GPU are related to the size of its memory, the number
of compute cores, and importantly the internal architecture of the GPU. In this regard, the NVIDIA
GPUs fall into two broad categories:

1. Gaming GPUs. These usually offer excellent computational performance, but are often
physically large and have high power draw. This means that it is often difficult to have more
than two attached to a mainboard. Despite these drawbacks, installing gaming GPUs often
provides the best overall performance relative to price for TUFLOW modelling.
2. Scientific GPUs. The top-line scientific GPUs can offer superior computational performance
to the top-line gaming GPUs, also offer more GPU memory, and are usually physically smaller
in size with lower power draw. So it is more feasible to have four or more attached to a
mainboard. However, they are significantly more expensive - sometimes an order of
magnitude more expensive than even best gaming GPUs.

@1793
12.4.4 Utilising Multiple GPUs for One Model

TUFLOW HPC (including Quadtree) can utilise multiple GPUs (that are all connected to the same
mainboard) to compute a single simulation. For larger models (typically more than 5,000,000 2D
cells), useful reductions in solve times can be achieved with multiple GPUs. For smaller models
(typically less than 100,000 cells), the solve time may actually increase when run across multiple
GPUs due to the device to device communication latency.

Multiple GPU may be used to run very large models that require more GPU memory than available
on a single GPU device.

@1794
12.4.5 Running Multiple Models on a Single GPU

A single simulation per GPU card will produce the fastest simulation speed from a single model
perspective. Running more than one simulation per GPU card will make the simulation run slower,
though from an overall project perspective may be a more efficient mode of operation. For
example, hypothetically, if a model takes 10 hours to run on a single card, running the same model
in parallel with another simulation may reduce the simulation efficiency to 70%. Those models run
in parallel would finish in 14.3 hours. This is quicker than the 20 hours that would be required if the
models were run in series.

The optimum number of simulations per GPU card varies depending on the card specs (Cuda
cores, RAM etc.) and model compute needs.

@1795
12.4.6 Differences in results between CPU and GPU

TUFLOW Classic uses a very different solution scheme to TUFLOW HPC, and there will be some
differences between these solutions. However what we are discussing here is running the HPC
solver on CPU, and then also on GPU, and comparing the difference. TUFLOW HPC has been
written to utilise one source code, that with the use of macros can be compiled for CPU execution

Section 12 Hardware and Operating System - 3 / 8 Page 536 / 1094

 or for GPU execution without duplication of code. So the lines of code are the same, but the
compilers are different, and the physical hardware that executes the binary instructions is different.
In particular, the number of bits used for floating point representation within the CPU cores and
GPU cores can differ, though both meet the minimum IEEE standards for single (or double)
precision. The math libraries for computing square-roots and logarithms are not absolutely
identical. These differences produce very subtle differences in depth calculations. The differences
are very, very, small - maybe at the 7th decimal place for single precision calculations, but when
an embankment is being over-topped by just a little bit, then a 0.0001% difference in depth can
become a 0.1% difference in over-topping flux, leading to what appear to be larger relative
differences in depth at shallow locations. Such differences can become as large as a few mm or
even cm. These differences are certainly much smaller than the uncertainties involved in flood
modelling, and much smaller than the differences that will arise from running the same model at a
different resolution, or (to the extent possible) in a different software. It is important for all
modellers to understand what constitutes real differences in results vs what is “numerical noise”.

@1796
12.4.7 RAM

RAM is the computer memory required to store all of the model data used during the computation.
A computer has CPU RAM, which is located on the motherboard and accessed from the CPU, and
it has GPU RAM, which is located on the GPU device and accessed from the GPU. The two
memory storage systems are physically separate. Both are required for TUFLOW HPC simulations
(when using GPU for the compute) The amount of GPU RAM is one of two factors that will
determine the size of the model that can be run (the other being CPU RAM). As a general rule,
approximately 5 million 2D cells can be simulated per gigabyte (GB) of GPU RAM depending on
the model features (e.g. a model with infiltration requires more memory due to the extra variables
needed for the infiltration calculation).

TUFLOW HPC on GPU hardware still uses the CPU to compute and store data (in CPU RAM)
during model initialisation and for all 1D calculations. During initialisation and simulation a model
will typically require 4-6 times the amount of CPU RAM relative to GPU RAM. As an example, a
model that utilises 11GB of GPU RAM (typical memory for high-end gaming card, and corresponds
to about a 50 million cell model) the CPU RAM required during initialisation will typically be in
range 44GB to 66GB.

@1797
12.5 Proxies for CPU and GPU performance

When choosing hardware for running engineering software, it is important to consider performance
for price, including an allowance for the cost of the software licencing. With licencing costs
included, this often favours choosing recent high performance hardware. Prices for hardware can
be well known in advance, but knowing what performance will be achieved on particular hardware,
for a specific software, can be difficult.

TUFLOW publishes computational performance results for a benchmark 2D hydraulic model -

refer to the links in Section 12.1 . For other hardware that is not listed on these pages, the
TUFLOW development team has found that some published 3rd party hardware benchmarks offer
a relative performance comparison that appears to be consistent with our own performance
measurements. These may be found at:

Section 12 Hardware and Operating System - 4 / 8 Page 537 / 1094

 https://www.videocardbenchmark.net/

At this site there is a “High End Video Card Chart”. The scores for each GPU are calculated from a
number of different tests, mostly to do with graphics performance. There is also a “GPU Compute
Video Card Chart”, but interestingly we have found the former chart to be a better proxy for how
well a GPU will run a TUFLOW HPC model. This site also has excellent CPU charts for multi-core
and single-core performance.

@1798
12.6 Virtualisation

It is possible to share high-performance compute resources amongst multiple users

simultaneously by running virtual desktops on a machine that users connect to remotely. There are
many reasons why IT professionals favour this solution for sharing expensive resources. However,
the important question that must be asked in advance is: how will the GPU(s) be shared between
users? Unless the Virtual Desktop Infrastructure (VDI) environment is implemented correctly,
users may experience erratic model start up and solve times. There are different sharing
mechanisms possible depending on the type of GPU and the choice of operating system. Some
key points are:

Solving the 2D Shallow Water Equations is a computationally intensive task. TUFLOW HPC is
a well-optimised engine that will efficiently utilise all of a GPU’s compute resources for hours,
sometimes days depending on the size of the model. For optimum performance, it is generally
safest to only allow one HPC compute job per GPU device.
In a VDI environment for modellers, where resources are typically pooled and assigned
dynamically, GPU resources should instead be assigned as isolated and independent
resources, dedicated to a user session.
When opting for large NVIDIA GPUs, choosing a GPU model and a hypervisor that support
Multi Instance GPU is recommended. Otherwise, select multiple smaller GPUs that can be
exclusively assigned to individual user sessions.

@1799
12.7 Cloud Compute

Organisations may host their TUFLOW network licences on the cloud and run simulations on
cloud virtual machines. There are numerous ways both, licencing and simulation can be
configured in a cloud environment, depending on the cloud provider (Microsoft, Google, Amazon,
other etc.) and internal company protocols. Configuration of your cloud environment is your own
responsibility. The Cloud Execution page of the TUFLOW Wiki provides guidance on this subject.

@1800
12.8 Commands

The following commands, all optional, are available for the HPC solution scheme (Solution
Scheme == HPC).

Hardware == GPU | {CPU}

Section 12 Hardware and Operating System - 5 / 8 Page 538 / 1094

 If an NVIDIA GPU is available, then this may be selected using the Hardware command. If GPU
hardware is specified, but the system cannot find an NVIDIA GPU, then ERROR 3005 will result.
The memory required for the TUFLOW model will be compared against the free memory available
on the GPU. If the available memory is insufficient to run the model ERROR 3017 will result. For
models that only just fit within the available device memory by a small margin, it is possible that a
memory allocation will fail due to being unable to find the required memory as a contiguous block,
in which case ERROR 3018 will be reported during model initialisation.

HPC DP Check == {CHECK} | OFF | ERROR

The default setting of “CHECK”, causes TUFLOW to report CHECK 2420 if the HPC solution
scheme is used with the double precision executable. Prior to the 2025 release, the default setting
of this command was “ERROR” and TUFLOW would stop with ERROR 2420 (advising that it is
recommended to use the single precision binary). Due to its explicit finite volume formulation and
being depth based, the HPC 2D scheme does not generally require double precision (DP). There
can also be substantial speed gains using single precision (SP) on some GPU cards, and there is
significantly less memory footprint. However, 1D-2D linked models that also use the ESTRY 1D
engine may still require double precision in situations where the model is at higher elevations.
Additionally, applications such as long-term simulations and/or simulations with groundwater may
require double precision for an accurate result. The “OFF” option will allows users to run the HPC
solution scheme in double precision without producing a CHECK or ERROR message.

GPU Device IDs == <list_of_device_ids>

For computers with more than one GPU, the NVIDIA GPU driver will search all connected GPUs,
and compile an enumerated list of NVIDIA GPUs. This list will range from 0 to n-1, where n is the
number of attached NVIDIA GPUs. This command may be used to:

Run a model on a particular GPU, e.g. “GPU Device IDs == 1” will run the model on the
second NVidia GPU in the list of available NVIDIA GPUs.
Distribute a model over two or more GPUs, e.g. “GPU Device IDs == 0 1” will run the
model spread over the first two NVIDIA GPUs in the list. Note that the GPUs do not have to
be consecutive and the device IDs can appear in any order.
If you only have one GPU device, or you wish to use the primary device, this command is not
needed.

If desired, the selection of GPU Device IDs can be specified on the command line when running
the executable:

To select a specific GPU, specify “-puN” where N is the device ID.

To select mutliple GPUs for a distributed run, supply a “-puN” argument for each device ID
required, for example -pu0 -pu1.
The “-pu” arguments will automatically override any GPU Device IDs specified in the tcf.

Also note:

If the list of device IDs is longer than the number of available devices, then the list will be
truncated to the number of available devices and WARNING 2784 issued.
If a device ID is specified that is outside of the range 0…n-1 then ERROR 3005 will result.

Section 12 Hardware and Operating System - 6 / 8 Page 539 / 1094

 If a device ID is specified that already has a model running on it, then the requested GPU will
be loaded up with the additional model, which will cause both the existing model and the new
model to solve more slowly.
A GPU module licence is required for each GPU.
A CPU thread is created for managing the compute stream for each GPU device.
Available memory checks are performed on all GPUs in the list.
If Hardware target is CPU then this command is ignored.

CPU Threads == {4} | <number_of_threads>

These two commands are identical and control the number of CPU threads used by HPC
(including Quadtree) when solving on CPU instead of GPU. For example, “CPU Threads == 6”
runs the HPC 2D solver across 6 CPU cores. The number of threads may also be specified as a
command line argument -nt[number_of_threads]. Using the command line argument will override
any definition in the tcf file.

Notes:

TUFLOW licences have 4 times the number of TUFLOW engine licences available as HPC
“thread” licences. For example a local or network 4 licence has 16 thread licences available.
The default number of threads that HPC will use for the CPU solver run is 4.
The maximum number of threads possible is the lesser of the maximum number of cores
available on the machine and the number of available TUFLOW thread licences.
Pre-processing of SGS elevations can be computationally intensive, as can the compression
of TIF output files. If the number of threads has not been specified then the number of threads
used for these tasks will default to the maximum number of cores available without requiring
any additional thread licences.

HPC Device Split == <list_of_device_load_factors>

When a model is spread over two or more GPUs (or CPU threads), the model is partitioned into
vertical ribbons and each device solves its own ribbon, with boundary data synchronised between
the devices at each timestep. By default the ribbons are of equal width. However, the
computational burden for each GPU is rarely uniform due to each ribbon having a different active
cell or wet cell count. This command will vary the ribbon sizes in accordance with the load factors
in the list, and therefore can improve overall solution time for unbalanced models. Also, for models
that require nearly all of the available GPU memory on systems with GPUs of different memory,
this command can be used to apportion ribbon sizes accordingly. Additional notes:

Load factors are mapped respectively to the devices in the same order in which they appear
in the list of device IDs.
Load factors are normalised after reading, if required, so their average is one.
Upon completion of the model, TUFLOW will report the approximate computational load split
across the devices, and offer a suggested list of load factors that may improve the workload
balance.
When running on CPU, this command adjusts the ribbon size for each thread.
For a Quadtree model, the decomposition is not performed in ribbons, instead the list of cells
is partitioned.

Section 12 Hardware and Operating System - 7 / 8 Page 540 / 1094

 GPU Peer to Peer Access == DISABLED | {ENABLED IF AVAILABLE}

Some models of NVIDIA GPUs allow for a direct communications link between them, either via a
specific hardware connector or via the PCI bus controller. This is known as ‘peer to peer’ access.
TUFLOW HPC will by default enable peer to peer access if the driver reports that it is available.
This command may be used to specifically disable peer to peer communications if desired.

References

@1802 G. (1984). On the Construction of Computational Methods for Shallow Water Flow
@1801
Stelling,
Problems. Rijkswaterstaat Communications.

@1803 W. (1991). Dynamically Linked Two Dimensional / One-Dimensional Hydrodynamic

Syme,
Modelling Program for Rivers, Estuaries and Coastal Waters (W. Syme, Ed.) [M.Eng.Sc(100%
Research) Thesis]. Dept of Civil Engineering. https://tuflow.com/media/4982/1991-tuflow-
dynamically-linked-2d-and-1d-hydrodynamic-modelling-syme-thesis.pdf

Section 12 Hardware and Operating System - 8 / 8 Page 541 / 1094

 @1808

@1809
Section 13 Managing and Starting
Simulations

@1810
13.1 Introduction

This chapter provides guidance on model naming conventions and how TUFLOW’s powerful
Variables, Events and Scenarios functionalities may be used to simulate any number of scenarios
and events from a single control (.tcf) file.

The latter part of the chapter discusses the installation of TUFLOW, the different TUFLOW dongle
types and how to start a simulation, both as a standalone TUFLOW simulation and in conjunction
with third-party software.

Finally, there is a section on the reproducibility of results when using different hardware.

@1811
13.2 File Naming

Each hydraulic modelling study can easily generate hundreds, if not thousands, of model input
files in addition to a large number of check and result files. Devising a sound naming convention
as part of the modelling process is key to modelling that is easily interpreted, logical, efficient,
quick to error check and quality control, and provide traceability for quality assurance.

The examples below are presented as guidance only. They demonstrate the progression of a
simple model naming convention to a more complex version that incorporates different flood
events and scenarios. The examples focus on the name of the .tcf control file, as this determines
the prefix assigned to both the 1D and 2D check and result files.

Tip: A general recommendation is to avoid long filenames and use acronyms where possible. For
example, for a simulation of the Brisbane River for the existing topography for the 1 in 100, 12
hour duration flood event, “BR_Exg_100yr_12hr_001.tcf” is preferable to
“Brisbane_River_Existing_100year_12hour_001.tcf”.

Example 1: Basic

MODEL_001.tcf

In its simplest form, the names of the majority of TUFLOW models consist of a few characters
denoting the study name and a version number. The characters denoting the study name are
typically included in all input files to specify that the files are unique or created for this study. The
numbering is used to denote different versions of the model, where each time a change is made

Section 13 Managing and Starting Simulations - 1 / 42 Page 542 / 1094

 and the model re-simulated, the version number is incremented. Use of a model version
numbering system ensures it is clear which model input files generated which model output files.
This is particularly important when troubleshooting or quality controlling a model.

Example 2: Event Naming

MODEL_0100F_001.tcf

MODEL_1000F_001.tcf

Most hydraulic modelling studies require the simulation of more than one event. In these cases, it
is preferable to include the name of the event within the simulation name rather than simply
incrementing the model version number. Note that the same number of characters is retained for
the 100-year (0100F) and 1000-year (1000F) events and, in this case, the use of ‘F’ to denote the
simulation is a fluvial flood event. Retaining the same number of characters (for example, by using
preceding zeroes) ensures when the files are viewed in Windows Explorer, they are presented in
ascending order. The model version number is the same in this example and tells the user that the
same version of the model has been simulated for two different flood events.

Refer to Section 13.3.1 which presents a method to model numerous hydraulic events using a
single .tcf control file.

Example 3: Scenario Naming

MODEL_0100F_EXG_001.tcf

MODEL_0100F_PRP_001.tcf

Many hydraulic modelling studies require the simulation of multiple scenarios, such as pre- and
post-development topography scenarios or sensitivity testing where one or more model
parameters are varied. Incorporating the name of the modelled scenario into the .tcf filename
easily differentiates the output files associated with each scenario. The characters used to denote
the scenario are typically also used for model input files specific to the scenario. For example, the
post-development scenario ‘PRP’ may involve the raising of flood defences, hence the GIS layer
used to raise the defences might be named ‘2d_zsh_MODEL_PRP_defence_001.shp’. The
presence of this layer in a model simulation of the pre-development scenario ‘EXG’, will
immediately highlight to the user that a mistake has been made.

Refer to Section 13.3.2 which presents a method to model one or more scenarios using a single
.tcf control file.

@1812
13.3 Simulation Management

TUFLOW incorporates powerful functionality to manage the simulation of multiple events and
multiple scenarios. The flexibility offered allows the user the ability to initiate all simulations using
the one .tcf file should they so desire. Rather than create a new .tcf file for every simulation and a
new .tgc and/or .ecf file for every different model scenario, it is possible to just have one of each of
these files, or at least markedly reduce the number of these files. An example application using a
single set of control files to simulate 328,986 combinations of different model domains, events and
scenarios is published in the TUFLOW Insights Library.

Numerous tutorial examples (with associated data downloads) are available which demonstrate
these powerful features:

Section 13 Managing and Starting Simulations - 2 / 42 Page 543 / 1094

 1. eLearning - Bulk Simulation Management Scenarios, Events and Variables
2. TUFLOW Wiki Tutorial 8 - Scenario Management
3. TUFLOW Wiki Tutorial 9 - Event Management
4. TUFLOW Wiki Example Models - Scenarios, Events and Variables

The following sections of the manual discuss the available options.

@1813
13.3.1 Events

Most hydraulic modelling studies require the simulation of different probabilistic events. For
example, a flood study may have to consider the 2, 5, 10, 20, 50, 100, 200 and 500 year Average
Recurrence Interval events, and one or two extreme floods. Each, or most of these, may have to
be simulated using a range of different duration rainfalls. A downstream boundary such as the
ocean may also need to be varied to model different probability storm tides or climate change
scenarios. The final number of simulations can easily be in the hundreds, if not thousands.

The ability to simulate multiple events using a single .tcf control file not only makes management
of the model easier, it also ensures consistency between the simulations and supports better
project quality control.

Multiple events are set up through the creation of a TUFLOW Event File (recommended extension
.tef) containing .tcf and .ecf commands that are particular to a specific event. The event specific
commands are contained between Define Event and End Define commands. Global .tcf and .ecf
commands can also be used by placing these commands outside the Define Event blocks
(normally at the top). The .tef file is referenced in the .tcf file using the Event File command. The
TUFLOW Event File is typically the last line in a .tcf file. Placing it in this location ensures it will be
the final .tcf command that is read, and any global .tcf and .ecf commands within it will take
precedence over conflicting commands in the parent .tcf and .ecf files.

Up to nine (9) different event groups can be specified for a single simulation. Unlimited events can
be defined within an event group. Example event groups and associated events could be:

Flood event magnitude: 2, 5, 10, 20, 50, 100, 200 and 500 year Average Recurrence Interval
storms.
Storm Duration: 1hr, 2hr, 3hr, 4hr, 6hr, 9hr, 12hr etc.
Design event temporal pattern: TP01, TP02, TP03, TP04, TP05, TP06, TP07, TP08, TP09,
TP10.
Downstream boundary condition: LAT, HAT, 5 year, 10 year.
Climate change time horizon: 2025, 2050, 2100.

Since the .tef file typically lists all available event options, the file can be viewed as a database of
all available event possibilities. This is useful for model peer review purposes.

To automatically insert the event name(s) into the output filenames, making them unique, place
“~e~” or “~e<X>~” (where <X> is from 1 to 9) into the .tcf filename.
Note ~e~ is effectively the same as ~e1~ and is typically used if there is only one event type being
varied.

For example,

MODEL_~e1~_~e2~_EXG_001.tcf can be configured to run any number of events within the e1

and e2 event groups, such as:

Section 13 Managing and Starting Simulations - 3 / 42 Page 544 / 1094

 e1=0100F and e2=12h results in MODEL_0100F_12h_EXG_001
e1=0100F and e2=24h results in MODEL_0100F_24h_EXG_001
e1=1000F and e2=12h results in MODEL_1000F_12h_EXG_001
e1=1000F and e2=24h results in MODEL_1000F_24h_EXG_001

Two options are available to define the event choice for a model simulation:

1. Using a batch file (.bat): Specify the –e or –eX options (see Table 13.2 ) to run the multiple
events using the same .tcf file – refer to the examples below. This option is best suited to
executing bulk simulations.
2. Using the Model Events command: Change the events manually before each simulation
within the .tcf file. Note that if using the –e or -ex option, this will override any events defined
using Model Events in the .tcf file. This option is useful for carrying out quick what-if or
sensitivity simulations. It is not practical for bulk simulation.

The examples below demonstrate two approaches for running simulations of a 20 and 50 year
flood and 1 and 2 hour duration storms.

Example 1 uses a single event group.

Example 2 achieves the same outcome as Example 1, though by using two event groups
(~e1~ and ~e2~) it avoids some of the command repetition required for Example 1.

In the examples, note how the same command (in this case End Time ) is used within the event
blocks to assign a different simulation end time depending on the duration of the event. Also note
the use of BC Event Source , which is a much more powerful alternative to using BC Event Text
and BC Event Name , in that it can be used to define up to 100 different event text / name
combinations instead of being limited to one. The key text field linkages with the BC Database file
are highlighted in yellow.

Events Example 1: One Event Group

Within the BC Database file:

Name,Source,Column 1,Column 2,Add Col 1,Mult Col 2,Add Col 2,

C001,..\Inflows\~ARI~_~DUR~.csv,Time,C001
C002,..\Inflows\~ARI~_~DUR~.csv,Time,C002
…

Include “~e~” in the .tcf filename, for example “Nile_~e~.tcf”, and add the following line at the
bottom of the file:

Event File == Nile_Events.tef

The “Nile_Events.tef” file contains lines such as the below:

!____ Global Default Settings_______________________

Start Time == 0 ! Global value, unless specified below

!____ 20 year event definitions______________________

Define Event == 020y_01h

BC Event Source == ~ARI~ | 020y
BC Event Source == ~DUR~ | 01h

Section 13 Managing and Starting Simulations - 4 / 42 Page 545 / 1094

 End Time == 3
Output Folder == ..\Results\2d\020y
1D Output Folder == ..\Results\1d\020y
End Define
Define Event == 020y_02h
BC Event Source == ~ARI~ | 020y
BC Event Source == ~DUR~ | 02h
End Time == 4
Output Folder == ..\Results\2d\020y
1D Output Folder == ..\Results\1d\020y
End Define
!____ 50 year event definitions______________________

Define Event == 050y_01h

BC Event Source == ~ARI~ | 050y
BC Event Source == ~DUR~ | 01h
End Time == 3
Output Folder == ..\Results\2d\050y
1D Output Folder == ..\Results\1d\050y
End Define
Define Event == 050y_02h
BC Event Source == ~ARI~ | 050y
BC Event Source == ~DUR~ | 02h
End Time == 4
Output Folder == ..\Results\2d\050y
1D Output Folder == ..\Results\1d\050y
End Define

Multiple events can be simulated from a single .tcf file using a batch file. Refer to Section 13.5.2
for details how to create a batch file. Below is an events batch file example in its simplest form,
without looping.

set TUFLOWEXE=C:\Program Files\TUFLOW\TUFLOW_iSP_w64.exe

set RUN=start “TUFLOW” /low /wait /min “%TUFLOWEXE%” -b
%RUN% –e1 020y_01h Nile_~e~.tcf
%RUN% –e1 020y_02h Nile_~e~.tcf
%RUN% –e1 050y_01h Nile_~e~.tcf
%RUN% –e1 050y_02h Nile_~e~.tcf

Events Example 2: Two Event Groups

Within the BC Database file:

Name,Source,Column 1,Column 2,Add Col 1,Mult Col 2,Add Col 2,

C001,..\Inflows\Nile\~ARI~_~DUR~.csv,Time,C001
C002,..\Inflows\Nile\~ARI~_~DUR~.csv,Time,C002
…

Section 13 Managing and Starting Simulations - 5 / 42 Page 546 / 1094

 Include “~e1~” and “~e2” in the .tcf filename, for example “Nile_~e1~_~e2~.tcf”, and add the
following line:

Event File == Nile_Events.tef

The “Nile_Events.tef” file would contain lines such as the below:

!____ Global Default Settings_______________________

Start Time == 0!! Global value, unless specified below

!____ ARI Definitions___________________________

Define Event == 020y

BC Event Source == ~ARI~ | 020y
Output Folder == ..\Results\2d\020y
1D Output Folder == ..\Results\1d\020y
End Define
Define Event == 050y
BC Event Source == ~ARI~ | 050y
Output Folder == ..\Results\2d\050y
1D Output Folder == ..\Results\1d\050y
End Define
!____ DUR Definitions___________________________

Define Event == 01h

BC Event Source == ~DUR~ | 01h
End Time == 3
End Define
Define Event == 02h
BC Event Source == ~DUR~ | 02h
End Time == 4
End Define
To run multiple events from the one .tcf file a .bat file may be used, such as below (see Section
13.5.2 ):

set TUFLOWEXE=C:\Program Files\TUFLOW\TUFLOW_iSP_w64.exe

set RUN=start “TUFLOW” /low /wait /min “%TUFLOWEXE%” -b
%RUN% –e1 020y -e2 01h Nile_~e1~_~e2~.tcf
%RUN% –e1 020y -e2 02h Nile_~e1~_~e2~.tcf
%RUN% –e1 050y -e2 01h Nile_~e1~_~e2~.tcf
%RUN% –e1 050y -e3 02h Nile_~e1~_~e2~.tcf

If Event logic blocks are also permitted in the same manner as the If Scenario command. Refer
to Section 13.3.2 for further information. Also, events are automatically defined as variables and
can be used, for example, to set the output folder name. See Section 13.3.3 for information on
“Variables”.

Reminder: The location of Event File within the .tcf file and the location of the commands
within the .tef file are important. If, for example End Time occurs in the .tcf file after where
Event File occurs, this latter occurrence of End Time will prevail over those specified in the .tef

Section 13 Managing and Starting Simulations - 6 / 42 Page 547 / 1094

 file. Essentially, the commands from the .tef file (for the events specified using the –e or -e run
options or Model Events ) are inserted into the .tcf at the location of the Event File command,
and are processed as if they are embedded into the .tcf file at that location.

Tip: To distinguish between 1D and 2D commands in a .tef file, prefix .ecf commands by “1D”
followed by a space. In the examples below, the .ecf Output Folder command is used to set
different folders for the 1D results depending on the event.

@1814
13.3.2 Scenarios

Using If Scenario is similar to using If…Else If… Else…End If constructs in a programming or

macro language. This feature enables control of the commands to include or exclude depending
on the scenario or combination of scenarios specified by the user at the time of simulation
execution.

Scenarios can be added into most of TUFLOW’s control files. The only control files not supporting
scenarios are the TUFLOW Rainfall Control File (.trcf), TUFLOW External Stress File (.tesf),
Advection Control File (.adcf) or within a Define Control command inside a TUFLOW Operational
Control (.toc) file. Similar to “events”, 9 scenario groups can be specified. Unlimited scenario
variations can be defined within each scenario group.

In Example 1 below, an If Scenario logic block has been inserted into a .tgc file:

Scenarios Example 1:

!____ MAT Definitions___________________________

Set Mat == 1 ! Set unspecified materials to default of 1

Read GIS Mat == shp\2d_mat_existing.shp ! Apply existing materials
If Scenario == opA
Read GIS Mat == shp\2d_mat_opA.shp ! Option A materials
End If

TUFLOW will carry out the following steps:

1. Set all material values over the entire 2D domain to a value of 1.

2. Process the 2d_mat_existing.shp layer to assign material values from a layer of land-use
polygons representing the existing situation.
3. One of the following will then occur:
1. If either “–s1 opA” was specified as a run selection in a batch file, or “Model Scenarios
== opA” was specified in the .tcf file, then the 2d_mat_opA.shp layer would be processed
to modify the material values affected by the Option A scenario. If “~s1~” occurs within
the .tcf filename, it is replaced by “opA” in the output filenames, otherwise “opA” is
appended to the end of the .tcf filename for the output filenames.
2. If opA was not specified as the chosen scenario for a simulation, 2d_mat_opA.shp would
be ignored. For example, that option would be required if modelling the existing scenario.

Example 1 can be extended to include an Option B, where Option B is an extension of Option A,

and also Option C, which is a complete alternative to Option A and the combined Option A and B
design. The If Scenario logic block for this situation is shown in Example 2a below:

Section 13 Managing and Starting Simulations - 7 / 42 Page 548 / 1094

 Scenarios Example 2a:

Set Mat == 1 ! Set unspecified materials to default of 1

Read GIS Mat == shp\2d_mat_existing.shp ! Apply existing materials
If Scenario == opA | opB
Read GIS Mat == shp\2d_mat_opA.shp ! Option A materials
Else If Scenario == opB
Read GIS Mat == shp\2d_mat_opB.shp ! Option B materials
Else If Scenario == opC
Read GIS Mat == shp\2d_mat_opC.shp ! Option C materials
End If

In the above example:

If “–s1 opA” is selected as the scenario for simulation, only 2d_mat_opA.shp will be read.
If “–s1 opB” is selected as the scenario for simulation, 2d_mat_opA.shp and 2d_mat_opB.shp
will be read.
If “–s1 opC” is selected as the scenario for simulation, only 2d_mat_opC.shp will be read.

Example 2b has been expanded further to include an Else and Pause command in 2c. The
command in the Else section will apply if any scenario except opA, opB or opC is called. The
Pause command will halt the simulation initialisation and display the specified message in the
DOS window. The user then has the option to continue or discontinue the simulation. It is good
practice to include Pause commands as a way to avoid accidental use of unspecified scenarios.

Scenarios Example 2c:

Set Mat == 1 ! Set unspecified materials to default of 1

Read GIS Mat == shp\2d_mat_existing.shp ! Apply existing materials
If Scenario == opA | opB
Read GIS Mat == shp\2d_mat_opA.shp ! Option A materials
Else If Scenario == opB
Read GIS Mat == shp\2d_mat_opB.shp ! Option B materials
Else If Scenario == opC
Read GIS Mat == shp\2d_mat_opC.shp ! Option C materials
Else
Pause == Invalid op Scenario
End If

In the example above, the batch file used to run the Option A, Option B and Option C scenarios
may look like this:

set TUFLOWEXE=C:\Program Files\TUFLOW\TUFLOW_iSP_w64.exe

set RUN=start “TUFLOW” /low /wait /min “%TUFLOWEXE%” -b
%RUN% –b -s1 opA Nile_~s1~_001.tcf
%RUN% –b –s1 opB Nile_~s1~_001.tcf
%RUN% –b –s1 opC Nile_~s1~_001.tcf

Section 13 Managing and Starting Simulations - 8 / 42 Page 549 / 1094

 As demonstrated above, it is recommended that scenario group placeholders be used (~s1~, ~s2~
etc.) in the .tcf file name. This provides the modeller with increased output file name control.
Above, ~s1~ in the .tcf file name will be substituted with the chosen scenario in all result, log and
check files. For example, for the first simulation in the queue, Nile_~s1~__001.tcf would become
M01_opA_001 for all output files.

The If Scenario command can be nested up to 10 levels. An example is provided in Scenario

Example 3.

Scenarios Example 3:

If Scenario == CLA
Solution Scheme == CLASSIC
Map Output Data Types == h V q d MB1 MB2
Else If Scenario == HPC
Solution Scheme == HPC
Hardware == GPU
Map Output Data Types == h V q d dt
If Scenario == SGS
SGS == ON
Else If Scenario == noSGS
SGS == OFF
Else
Pause == Error: Invalid SGS Scenario
End If
Else
Pause == Error: Invalid Solver Scenario
End If

Scenarios are automatically defined as “Variables” and can be used, for example, to set the output
folder name. See Section 13.3.3 for information on Variables.

@1815
13.3.3 Variables

The Set Variable command can be used to assign different values for the same variable in
different parts of the various TUFLOW control files. It is an efficient way to centralise information.
It is regularly used to consolidate the definition of multiple variables in a single logic block rather
than having multiple If..Else If.. End If command blocks in different locations or control files.

The Set Variable command can only be specified in the .tcf or within a read file (.trd) referenced
from the .tcf. The variables can then be used in all control files (.tcf, .tgc, .tbc, .ecf, etc). The
variables are referenced within the control files by being enclosing the character string within “<<”
and “>>”.

An example is provided below. Variables associated with modelling at different cell sizes are
defined in the .tcf within a single logic block.

If Scenario == 2m
Set Variable 2D_CELL_SIZE == 2

Section 13 Managing and Starting Simulations - 9 / 42 Page 550 / 1094

 Set Variable 2D_TIMESTEP == 1.0
Else If Scenario == 5m
Set Variable 2D_CELL_SIZE == 5
Set Variable 2D_TIMESTEP == 2.5
Else If Scenario == 10m
Set Variable 2D_CELL_SIZE == 10
Set Variable 2D_TIMESTEP == 5.0
End If

Along with this variable definition, the following is used in the respective control files:

.tcf: Timestep == <<2D_TIMESTEP>>

.tcf: Grid Output Cell Size == <<2D_CELL_SIZE>>
.tgc: Cell Size == <<2D_CELL_SIZE>>

Refer to TUFLOW Wiki Example Models - Variables for various examples of variables in a working
model.

Note: Set Variable scenario blocks are often contained within “read files”, referenced in the .tcf
using the Read File command.

All events and scenarios are automatically set as a variable that can be used within your control
files. For example, if your model results are to be output to different folders depending on
Scenario 1 (~s1~), enter the following into the .tcf file noting the use of << and >> to delineate the
variable name.

Output Folder == ..\results\<<~s1~>>

In the case above, if Scenario ~s1~ is set to “OpA”, TUFLOW automatically sets a variable named
“~s1~” to a value of “OpA”, and the output will be directed to ..\results\OpA.

As an extension to the example above, if the output folder is to also include the first event name,
which, for example, is the return period of the flood, the following could be used:

Output Folder ==..\results\<<~e1~>>_<<~s1~>>

If Event ~e1~ is set to “Q100”, the output will be directed to ..\results\Q100_OpA.

@1816
13.4 TUFLOW Executable Download

@1817
13.4.1 Overview and Where to Install

The TUFLOW release consists of two different versions of the executable as follows:

TUFLOW_iSP_w64.exe
TUFLOW_iDP_w64.exe

The naming convention for each executable is explained in Table 13.1 . Each version has
associated TUFLOW .dll and .ptx files, and several system .dll files.

Section 13 Managing and Starting Simulations - 10 / 42 Page 551 / 1094

 For each version all .exe, .dll and .ptx files must be placed in the same folder and kept together at
all times. Older versions of TUFLOW may not have any .ptx files (these are associated with GPU
based simulations. When replacing with a new build, archive the files by creating a folder of the
same name as the Build ID (e.g. 2023-03-AD), and place all files in this folder.

The Build ID includes the acronym and appears in the top bar of the Console window, in the .tlf file
and elsewhere. For example, if running the single precision, Windows 64-bit version, the Build ID
would be “2023-03-AD-iSP-w64”.

Older builds can always be setup in a similar manner by placing the build in its own folder, if they
are needed for running legacy models.

Model TUFLOW Build or a combination of Model TUFLOW Release , Model Precision and
Model Platform can be used to force a simulation to use a specific TUFLOW build, release, or
precision (SP or DP). This can be very useful for ensuring a consistent TUFLOW
build/release/version is used for a project.

It is recommended that a folder structure such as that shown in Figure 13.1 is used. If an update
(patch) is issued, archive the old build by moving all files to a separate folder or .zip file, and copy
in the new TUFLOW files. This way, batch files, text editors and GIS packages that are used to
start TUFLOW simulations will access the latest build. Previous versions can still be used if
required.

@1818

Figure 13.1: TUFLOW Engine Files

Section 13 Managing and Starting Simulations - 11 / 42 Page 552 / 1094

 @1819 Table 13.1: TUFLOW Versions (iSP, iDP, w64)

Version Description

Single Compiled using single precision (4-byte) real numbers that typically have around
Precision 7 significant figures. This version is recommended for the majority of TUFLOW
(iSP) simulations. See Section 13.4.2 for discussion on precision.

Compiled using double precision (8-byte) real numbers that typically have around
16 significant figures. See Section 13.4.2 for discussion on precision.

For TUFLOW Classic, this version should be used for models with high ground
elevations (greater than 100 to 1,000m) and for direct rainfall models. If a model
falls into these categories and is experiencing mass errors when using the single
precision version, re-run using the double precision version and should the mass
errors reduce to acceptable levels, continue to use double precision, otherwise
contact [email protected].

For TUFLOW HPC, due to its explicit finite volume formulation and being depth
based (rather than using elevation as required for implicit schemes like Classic),
the HPC 2D scheme does not generally require double precision (DP). There can
also be substantial speed gains using single precision (SP) on some GPU cards,
Double
and there is significantly less memory footprint. However, 1D-2D linked models
Precision
that also use the ESTRY 1D engine may still require double precision in
(iDP)
situations where the model is at higher elevations. Additionally, applications such
as long-term simulations and/or simulations with groundwater can be subject to
round-off errors may require double precision for an accurate result. Should mass
volume errors occur, or if you are concerned about the accuracy of ground water
levels, run in double precision and compare with single precision. Should the
mass errors reduce to acceptable levels, continue to use double precision,
otherwise contact [email protected].

Model Precision can be used to ensure that a simulation is started using the
single or double precision version. For example, a single precision version of
TUFLOW will generate an error if used to start the simulation if the command
below is included in the .tcf:

Model Precision == Double

Legacy builds that were compiled as a 32-bit process. w32 TUFLOW builds can
be run on Windows 32-bit and 64-bit platforms. All builds/releases prior to the
2010-10 release (except for the 2009-07-XX-iDP-64 build) are 32-bit. 32-bit
programs are unable to access as much memory (RAM) as 64-bit versions of
Windows
TUFLOW. For large models TUFLOW may generate an error that it is unable to
32-bit
allocate enough memory. Typically, when the memory requirement is ~1.5GB per
(w32)
simulation the 32-bit version of TUFLOW will not be able to allocate enough
RAM.
The 32-bit version of TUFLOW is only available for pre 2017-09 releases. Users
should use the 64-bit versions where possible.

Section 13 Managing and Starting Simulations - 12 / 42 Page 553 / 1094

 Version Description

Compiled as a 64-bit process. w64 TUFLOW builds can only be run on Windows
64-bit platforms.

w64 2010-10 builds have been found to reduce simulation times by 20 to 50%
Windows compared with the 2009-07 (32-bit) release. Slightly different results (mostly
64-bit fractions of a mm) will occur between w32 and w64 for the same model.
(w64)
Model Platform can be used to force a simulation to use a w32 or w64 version.

Note that the 64-bit versions of TUFLOW may only be run using a WIBU
dongle .

Running TUFLOW is carried out by initiating the TUFLOW_X.exe file using one of the approaches
discussed in Section 13.5.2 . The system .dll files are required for the following purposes:

TUFLOW_LINK_X.dll allows other schemes such as 12D DDA, FloodModeller 1D, EPA
SWMM and XPSWMM to dynamically link with TUFLOW.
TUFLOW_USER_DEFINED_X.dll allows users to customise TUFLOW to suit their purposes
(see Section 13.4.3 ).
TUFLOW_AD_X.dll contains the AD (advection-dispersion) module algorithms.
TUFLOW_MORPHOLOGY_X.dll contains the morphology module algorithms. These are
deprecated and retained for backward compatibility.
Other supplied .dlls are system DLLs required by TUFLOW.

A number of .ptx files are required to run TUFLOW HPC/Quadtree simulations on a GPU card,
these are:

hpcKernels_nSP.ptx
hpcKernels_nDP.ptx
qpcKernels_nSP.ptx
qpcKernels_nDP.ptx

As a general rule, once a build is over three years old, it is no longer supported. It can still
be used, but there is no guarantee that older builds will recognise newer dongles or are updated
with bug fixes.

@1820
13.4.2 Single and Double Precision

When storing floating point values on a computer, a certain number of bytes per value is needed.
Single precision numbers use 4 bytes and double precision 8 bytes. This will yield from 6 to 9
digits of precision for single precision and 15 to 17 digits for double. TUFLOW Classic and
TUFLOW HPC are available in both single precision and double precision, however, the reasons
why you would use double precision instead of single are somewhat different for the two solvers.

@1821
13.4.2.1 TUFLOW Classic

Being an implicit matrix based solution, TUFLOW Classic solves for water levels rather than
depths. The affect of this is best illustrated by an example. Consider a model where the highest
ground level is under 10mAD. If a tiny amount of rainfall falls on the cell, this might raise the water

Section 13 Managing and Starting Simulations - 13 / 42 Page 554 / 1094

 level in the cell to 5.000001mAD. Both single and double precision will handle the accuracy
needed as the resulting water level falls within the acceptable number of significant figures for
both precisions.

However, consider another model with much higher elevations, and a cell that has a water level of
1000.000mAD. If this cell receives 0.000001m of rainfall in one timestep, for single precision the
resulting water level will be 1000.000mAD (i.e. the added rainfall has disappeared resulting in an
incorrect calculation and associated mass error). However, for double precision the resulting water
level is 1000.00000100000, which is the correct water level and mass is conserved.

The need to use double precision for Classic also depends on other factors such as cell size and
timestep. As there is no simple rule-of-thumb, the recommended action is to run the model in
single and double precision modes. If the results are unacceptably different, and especially if the
mass error is significantly lower in double precision, then double precision should be used.

Note that the choice of single or double precision also impacts on simulation times and RAM
allocation. iDP versions of TUFLOW Classic will take approximately 25% longer to run and require
up to twice as much memory, limiting the ability to run concurrent simulations. Therefore, if the
results of a model run in both iSP and iDP versions are consistent, the iSP version of TUFLOW is
recommended to take advantage of the faster simulation times and smaller memory footprint.

@1822
13.4.2.2 TUFLOW HPC

Being an explicit solution, the calculation method in TUFLOW HPC uses depth, unlike TUFLOW
Classic which uses water level as discussed above. This means that precision issues associated
with, for example, applying a very small rainfall to a high elevation are not applicable in TUFLOW
HPC, resulting in most models being accurately solved using single precision. However, carrying
out simulations in single and double precision and checking for consistency is still a recommended
task, especially if the simulation is using for example, very small inflows, long-term simulations,
simulations with groundwater or other metrics that are unusually fine-scale. Additionally, 1D-2D
linked models that also use the ESTRY 1D engine may still require double precision in situations
where the model is at higher elevations.

Unless testing shows otherwise, use the single precision version for all TUFLOW HPC
simulations. Note: Double precision solutions on GPU cards can be four times slower than
single precision on some GPU devices! If the TUFLOW HPC simulation is started with the
single precision version of TUFLOW, the HPC solver will utilise a single precision version. If the
simulation is started with the double precision version of TUFLOW, CHECK 2420 will be output by
default stating that the single precision version should be used. This can be turned off, or set to
“ERROR” by using the HPC DP Check command.

@1823
13.4.3 Customising TUFLOW using
TUFLOW_USER_DEFINED.dll

The TUFLOW_USER_DEFINED.dll is a legacy feature for TUFLOW Classic that was primarily
used for customising hazard category outputs and is no longer supported as the same service
cannot be offered for HPC given its GPU code base.

Note: For customising hazard category outputs, see Section 11.2.3.1 .

Section 13 Managing and Starting Simulations - 14 / 42 Page 555 / 1094

 @1824
13.5 Running Simulations

@1825
13.5.1 Dongle Types and Setup

BMT dongles are generally distributed as a WIBU Codemeter (metal) dongle or software licence.
These dongles were introduced in 2010. The older ‘SoftLok’ dongles are no longer supported.

Two types of licences are currently provided:

Local or Standalone Licence – Allows up to a specified limit the number of TUFLOW

simulations to be run from the one computer. For example, a Local 1 licence will allow a single
simulation to be performed on the machine. A local 4 licence allows up to 4 concurrent
simulations. Local 1 to Local 16 licences can be configured.
Network Licence – allows for multiple TUFLOW processes running at any one time across
multiple machines within the limitations of the TUFLOW EULA. For example, a Network 5
licence allows up to 5 concurrent simulations to be performed. This could be 5 simulations on
a single computer, 5 simulations with each one on a different computer, or anything in
between.

Refer to the installation instructions on the TUFLOW Wiki for both types of dongles.

@1826
13.5.1.1 Protocols for Accessing Dongles

If more than one type of dongle is available the protocols for taking and checking licences are:

1. WIBU Codemeter licences are searched for, and if a licence is free it is taken.
2. If no licence is available, you can optionally set for TUFLOW to continue to try and find an
available WIBU dongle licence. This is achieved using the
“C:\BMT\TUFLOW_Dongle_Settings.dcf” file described below. This is useful if there are no
free licences and you wish to start a simulation (the simulation will start once a free licence
becomes available).
3. Once a simulation is under way, and if the licence is lost, TUFLOW will try to regain a licence,
but it cannot switch to a different dongle type / provider. For example, a WIBU dongle can’t be
used to finish a simulation if it is started with another WIBU dongle which is removed.

There are five varieties of licence type / vendor:

BMT physical USB lock (dongle)

BMT software lock (tied to a particular machine)
Aquaveo (SMS) USB lock
Jacobs (Flood Modeller) USB lock
Jacobs (Flood Modeller) software lock

With numerous licencing options available, setting the preferred licence type can (slightly) speed
the simulation start-up. The licence search order can be set via a licence control file
“TUFLOW_licence_settings.lcf”, this replaces the TUFLOW_Dongle_Settings.dcf. Note that this
file can occur in several locations. When looking for a licence setting file TUFLOW searches in the
following locations:

1. A “TUFLOW_licence_settings.lcf” in the same location as the TUFLOW executable.

Section 13 Managing and Starting Simulations - 15 / 42 Page 556 / 1094

 2. A “TUFLOW_licence_settings.lcf” in a TUFLOW folder in the “ProgramData” environment
variable location. By default this will resolve to
C:\ProgramData\TUFLOW\TUFLOW_licence_settings.lcf. Entering %programdata% into the
windows explorer path will take you to the location.
3. C:\BMT\TUFLOW_Licence_Settings.lcf
4. C:\BMT\TUFLOW_Dongle_Settings.dcf

If no licence settings files are found, TUFLOW defaults to the order listed above. WIBU Firm Code
Search Order can be used to control the search order in the TUFLOW_licence_settings.lcf file.

Note: Use of C:\BMT\ above is for legacy reasons and is not recommended as read/write
access to local drives is now often blocked for protection against hackers.

@1827
13.5.1.2 TUFLOW_Licence_Settings.lcf File

The TUFLOW Licence Settings (.lcf) file can be used to set WIBU settings, such as retry time
interval and count. It has the same form and notation as a TUFLOW .tcf file.

This file is optional and if not found the settings below are the default:

! Use this file to set general and WIBU specific dongle parameters
! Use ! or # to comment out commands or make comments
Simulations Log Folder == C:\ProgramData\TUFLOW\<username>\log ! Path or
URL to global .log file
WIBU Retry Time == 60 ! seconds. Values less than 3 are reset to 3.
Default = 60.
WIBU Retry Count == 0 ! Use -1 for indefinitely.
WIBU Dongles Only == OFF ! If ON, searches for WIBU dongles only. Default
is OFF.

In the above, the:

Simulations Log Folder sets the folder path or URL to a folder for logging all
simulations. If the keywords “DO NOT USE” occur within the folder path or URL, this feature
is disabled. Also see Simulations Log Folder .
WIBU Retry Time sets the interval in seconds for retrying to take a licence or regain a lost
licence. The default is 60 and values less than 3 are set to 3.
WIBU Retry Count sets the number of times to retry for a licence at the start of a
simulation. By default, if a licence is lost during the simulation, TUFLOW tries indefinitely to
regain a licence so as not to lose the simulation.
WIBU Dongles Only if set to ON will force TUFLOW to only search for WIBU dongles.

@1828
13.5.1.3 Dongle Failure during a Simulation

If TUFLOW fails to recognise a network lock during a simulation (e.g. the network dongle server
computer is down) it enters a holding pattern and continues trying until a license is found.

For local, standalone locks, TUFLOW prompts with a message that the lock could not be found. If
it’s a USB lock try a different USB port, and press Enter to continue.

Section 13 Managing and Starting Simulations - 16 / 42 Page 557 / 1094

 @1829
13.5.2 Starting a Simulation

There are a number of ways TUFLOW can be started, in each case the TUFLOW executable is
started with the TUFLOW control file (.tcf) as the input argument. There are a number of optional
switches that can be specified when starting a simulation; these are outlined in Table 13.2 .

Starting a TUFLOW simulation can be carried out in a multitude of methods:

1. From within a text editor such as Notepad++

2. Through a batch file
3. From within your GIS software:
1. QGIS via the QGIS TUFLOW Plugin
2. ArcMap via the use of the ArcTUFLOW toolbox
3. MapInfo (through the MiTools add-on)
4. From a Console (DOS) Window
5. Via the right mouse button in Microsoft Explorer
6. Via a runner such as the TUFLOW Runner or TRIM

This section of the manual only provides detailed instructions on initiating simulations through
batch files as it is the most effective method to run several or many simulations. Instructions on all
methods have been described on the TUFLOW Wiki.

@1830
13.5.2.1 Batch File Example and Run Options (Switches)

A batch file is a text file that contains a series of commands or instructions that is read by the
Windows Operating System. The batch file requires the extension .bat to be recognised by
Windows.

The simplest format of a TUFLOW batch file is to specify a single simulation. This is of the format:

<TUFLOW Executable> <TUFLOW Control File>

For example:

C:\TUFLOW\Releases\2023-03\TUFLOW_iSP_w64.exe MR_H99_C25_Q100.tcf

The .bat file is run or opened by double clicking on it in Windows Explorer. This opens a Console
Window and then executes each line of the .bat file. The above batch file will start the TUFLOW
executable with the control file “MR_H99_C25_Q100.tcf” as the input file. As the control file
argument does not have a file path, the batch file must be located in the same folder as the .tcf
file. This could also include a relative or absolute file path, for example in the batch file line below,
the batch file could be stored in any folder as the absolute file path is used. As outlined in Section
4.2.2 , the relative file path is recommended for TUFLOW modelling inputs.

C:\TUFLOW\Releases\2023-03\TUFLOW_iSP_w64.exe
C:\Example\MR_H99_C25_Q100.tcf

To start multiple simulations one after the other, these can be listed in succession.

C:\TUFLOW\Releases\2023-03\TUFLOW_iSP_w64.exe –b MR_H99_C25_Q100.tcf
C:\TUFLOW\Releases\2023-03\TUFLOW_iSP_w64.exe –b MR_H99_C25_Q050.tcf
C:\TUFLOW\Releases\2023-03\TUFLOW_iSP_w64.exe –b MR_H99_C25_Q020.tcf
pause

Section 13 Managing and Starting Simulations - 17 / 42 Page 558 / 1094

 Note the use of the –b (batch) switch, which suppresses the need to press the return key at the
end of a simulation. This ensures that one simulation proceeds on to the next without any need for
user input. The pause at the end stops the Console window from closing automatically after
completion of the last simulations so you can check the status of the simulations.

The –t (test) switch is very useful for testing the data input without running the simulation. It is
good practice to use this switch before carrying out the simulations, as this will tell you whether
there are any data input problems. The –t switch runs TUFLOW to just before it starts the
hydrodynamic computations.

Using the example above, the recommended approach is to first run the following batch file:

C:\TUFLOW\Releases\2023-03\TUFLOW_iSP_w64.exe -b –t MR_H99_C25_Q100.tcf
C:\TUFLOW\Releases\2023-03\TUFLOW_iSP_w64.exe -b –t MR_H99_C25_Q050.tcf
C:\TUFLOW\Releases\2023-03\TUFLOW_iSP_w64.exe -b –t MR_H99_C25_Q020.tcf
pause

This will indicate any input problems (note some WARNINGS do not require a “press return key”,
but they can be located in the .tlf file).

From TUFLOW version 2018-03-AA, it is possible to use the test model option without using a
TUFLOW licence noting no diagnostics are reported so don’t use this option whilst you are
developing/building a model. To utilise this licence free test, the -nlc (No Licence Check) input
argument must be specified, e.g. the command line below would run the model in test model (-t)
without needing a licence (-nlc):

C:\TUFLOW\Releases\2023-03\TUFLOW_iSP_w64.exe -b –t -nlc
MR_H99_C25_Q020.tcf

To carry out the simulations the –t can be removed (and -nlc flag if used) or replaced with the –x
(execute) switch. The -x switch is optional, but is useful when editing the .bat file to quickly change
between –t and –x switches.

C:\TUFLOW\Releases\2023-03\TUFLOW_iSP_w64.exe -b –x MR_H99_C25_Q100.tcf
C:\TUFLOW\Releases\2023-03\TUFLOW_iSP_w64.exe -b –x MR_H99_C25_Q050.tcf
C:\TUFLOW\Releases\2023-03\TUFLOW_iSP_w64.exe -b –x MR_H99_C25_Q020.tcf
pause

Comment lines are specified in a .bat file using “REM” (remark) in the first column. Alternatively,
“::” has a similar effect. The ss64 website has further guidance on using comment lines in batch
files. For example, if you want to re-run only the first simulation in the examples above, edit the file
as follows:

C:\TUFLOW\Releases\2023-03\TUFLOW_iSP_w64.exe -b –x MR_H99_C25_Q100.tcf
:: C:\TUFLOW\Releases\2023-03\TUFLOW_iSP_w64.exe -b –x
MR_H99_C25_Q050.tcf
:: C:\TUFLOW\Releases\2023-03\TUFLOW_iSP_w64.exe -b –x
MR_H99_C25_Q020.tcf
pause

Table 13.2 below describes other switches that are available. The switches are also displayed to
the console if TUFLOW.exe is executed without any arguments (i.e. double click on TUFLOW.exe
in Windows Explorer).

Section 13 Managing and Starting Simulations - 18 / 42 Page 559 / 1094

 Any of the options can be prefixed by a:

“-” (short dash or minus sign);

“-” (long dash); or
“/” (forward slash)

For example, to start a model in batch mode, the following all perform the exact same function:

C:\TUFLOW\Releases\2023-03\TUFLOW_iSP_w64.exe -b MR_H99_C25_Q100.tcf
C:\TUFLOW\Releases\2023-03\TUFLOW_iSP_w64.exe –b MR_H99_C25_Q100.tcf
C:\TUFLOW\Releases\2023-03\TUFLOW_iSP_w64.exe /b MR_H99_C25_Q100.tcf

Section 13 Managing and Starting Simulations - 19 / 42 Page 560 / 1094

 @1831 Table 13.2: TUFLOW.exe Options (Switches)

Switch Description

Automatically create folders (the default). Prevents the dialog prompt

from appearing when encountering non-existent folders (ie. results
-acf
folders), and creates these folders automatically. If for any reason the
folder can’t be created, a dialog will appear.

Batch mode. Used when running two or more simulations in

succession from a .bat file (see Section 13.5.2.1 ). Suppresses
-b display of the TUFLOW “simulation has finished” dialogue window, or a
request to press Enter at the end of a simulation, so that the .bat file
can continue onto the next simulation.

Section 13 Managing and Starting Simulations - 20 / 42 Page 561 / 1094

 Switch Description

-c A copy of a TUFLOW model can be created as described below.

Making a copy of a model is useful for transferring a model to another
Optional additional
site or for making an archive of the input data. Also see the -pm
flags of “a” , “L”, “p”
(package model) option as an alternative.
or “ncf”.
To copy a TUFLOW model, the -c switch must be included on the
(e.g. -c, -cap, -
TUFLOW command line, as a minimum. The -c switch copies only the
cpncf, -cncf)
files read by TUFLOW. Therefore, for MapInfo users, the .mif and .mid
files read by TUFLOW will be copied. To copy the remaining MapInfo
format files (.tab, .id, .dat and .map) use the -ca option described
further below.

Additional optional flags can be added to the base -c switch, in any

combination, including:

“a” (all);
“L” (list);
“p” (path); and
“ncf” (no check files).

The addition of the “a” flag (e.g. -ca) copies all files of the same name
for all input files (i.e. same name, but different extensions). This option
is particularly useful if the .tab and other associated files of a GIS layer
need to be archived or delivered.

The addition of the “L” flag will output the files used by TUFLOW into a
.tcl (TUFLOW Copy List) file but not copy the files to a destination
folder. This can be useful if scripting the copying of models. To run the
copy list the character “L” needs to be specified after the -c input
argument. This works for all copy options, for example the following are
all valid; -cL, -caL -capL. The .tcl file produced is output in the same
directory as the .tcf and takes the simulation name.

The addition of the “p” flag (e.g. -cp) allows the user to specify an
alternate path in which to copy the model. Without this flag, the
location defaults to the .tcf’s location. For example, specifying the
following, will place a copy of the model into a folder
C:\put_model_here:

“TUFLOW.exe” -cp “C:\put_model_here”

“C:\TUFLOW\runs\M01_5m_003.tcf”

The addition of the “ncf” flag (e.g. -cncf) copies the essential input files
and excludes all check files.

Note that these optional flags can be added in any combination to the
base -c switch (e.g. -c, -ca, -cp, -cncf, -cap, -cancf, -cpncf, -capncf).

Specifying -c on the TUFLOW command line creates a folder “<.tcf

filename>_copy” (or “<.tcf filename>_copy_all” if the “a” flag is
added) in the same location as the .tcf file. Under the folder, input files

Section 13 Managing and Starting Simulations - 21 / 42 Page 562 / 1094

 Switch Description

are copied (including the full folder structure), and any check files and
output folders created. For example, specifying:

TUFLOW.exe -c “C:\tuflow_models\my model.tcf” will make a copy of

the TUFLOW model based on the file “my model.tcf” in a folder “my
model.tcf_copy”, or “my model.tcf_copy_all” if using the “a” flag.

Notes:

1. Use the full path to the .tcf file (this is generally the default if
running from an editor such as UltraEdit or using the right
click approach).
2. Make sure there is sufficient disk space (no checks for sufficient
disk space are made).
3. Output folders and some output files are created but these will be
empty.
4. Unless the -ncf option is used, any check folder(s) are created and
check files written (these can be deleted if wishing to minimise the
size of the folder).
5. The full path of the input files is reproduced to provide traceability
and also handle inputs from other drives and URLs. Drive letters
are replaced, for example, “C:” becomes a folder “C Drive”. URLs
(denoted by “\” or “//” at the beginning of the path) are replaced by
a folder called “URL\”.
6. To run the copied .tcf file, it will be necessary to change any non-
relative pathnames according to the point above. Alternatively you
can share and then map, for example, the “D Drive” folder as “D:”.
7. If using MapInfo formats, the Check MI Save Date will need to be
set to WARNING or OFF in the .tcf file if the –ca option has not
been used as the .tab and other files will not have been copied.
8. There is a limit of 1,000 characters (including spaces) on
pathnames. As very long pathnames can result due to the above
approach, if the number of characters exceeds 1,000, problems
may occur.
9. The -c switch automatically invokes the -t (i.e. the simulation does
not commence, only the input data is tested/checked).
10. The -b option still applies if several models wish to be copied using
a batch (.bat) file.

Section 13 Managing and Starting Simulations - 22 / 42 Page 563 / 1094

 Switch Description

Specifies an event name to be used by Define Event in a .tef Event

File to customise inputs for an event. There must be a space between
–e and <name>. <name> may itself contain spaces, but if it does the
event name must be enclosed in quotes. More than one (up to a
maximum of nine) events per simulation may be specified by placing a
number after –e. –e and –e1 are treated the same (don’t specify both
of them otherwise indeterminate results may occur).
-e<name> -e{1-9}
<name> Also see Section 13.3.1 and Model Events .

Examples:
–e Q100 Run the Q100 event.
–e1 Q100 –e2 02h Run the Q100, 2 hour storm event.
–e Q100 –e2 02h Same as above.
–e “100 yr” Run the event name “100 yr” noting quotes required as
there is a space in the name.

The end time for a simulation can be specified using the run option -
et<time_in_hours>. Any end time specified via this run option argument
-et<time_in_hours>
is given the highest priority and overrides the End Time settings in the
.tcf, event files (.tef) and override files.

Section 13 Managing and Starting Simulations - 23 / 42 Page 564 / 1094

 Switch Description

The use of the -nc (no console) switch suppresses the appearance
(hides) the console window (Section 14.2 ). You won’t be able to see
the simulation running, however there will be a TUFLOW process
visible in Windows Task Manager. The -nc switch automatically invokes
the -nmb and -b switches.

The “start” command included in the Advanced Batch File examples in

Section 13.5.2.3 should not be used with the -nc command.

It is strongly recommended to redirect standard console window output

to a text file. It’s recommended that this file be given a unique name for
each run, matching your simulation. “…TUFLOW.exe” –nc my_run.tcf >
my_run.txt

Build 2018-03-AB included some enhancements when running with the

-nc (no console option). These were designed to remove any need for
-nc user input to TUFLOW as follows:

If no .tcf is specified, no licence check is performed and the

simulation is halted. Previously a licence check was performed
and the user was prompted to hit a key to release licences and
close the simulation.
If an invalid .tcf file is specified, the simulation stops and returns
an error level of 1 to the operating system. Previously the user was
prompted to enter a valid .tcf filename.
If the set log path (-slp) is specified in conjunction with the no
console option (-nc) the simulation stops and returns an error level
of 1 to the operating system. Previously the user was prompted to
confirm the set log path.
Removed a number of locations where a simulation could pause
and wait for a user input before closing.

For Build 2018-03-AA or later it is possible to use the copy model (-c
option) or test model (-t option) without using a licence. To utiltise this
licence free copy / test, the -nlc (No Licence Check) input argument
-nlc
must be specified. If running without a TUFLOW licence no diagnostic
output is generated (e.g. messages layer). If these are required, the -
nlc option must be removed.

No Message Boxes. Suppress use of windows message boxes to

-nmb
prompt the user. All prompts will be via the console window.

The use of the -nq (no queries) switch prevents the termination query
dialog from displaying when Ctrl+C is pressed to terminate a simulation
-nq cleanly. If –nq is specified and Ctrl-C is pressed, the simulation
terminates cleanly without a query dialog to check you are certain, so
be careful!

Section 13 Managing and Starting Simulations - 24 / 42 Page 565 / 1094

 Switch Description

Sets the number of CPU threads (cores) to use for a TUFLOW HPC
simulation. Noting that the number of threads requested is limited to
-nt
the maximum number of CPU cores available on the machine, and the
available TUFLOW Thread licences.

Force TUFLOW to search for a network licence (i.e. skip the search for
-nwk
a local licence).

The Output Drive for a simulation can be specified with the –od
-od<drive> command line option. For example –odC will redirect all outputs to the
C:\ drive.

Map output includes Output Zone <name>. For more information on

Output Zones, please refer to Section 11.2.5 . For example “-oz
-oz<name>
ZoneA” would include output for Zone A, similar to the .tcf command:
Model Output Zones == Zone A.

Section 13 Managing and Starting Simulations - 25 / 42 Page 566 / 1094

 Switch Description

-pm The package model (-pm) function copies all input files for all events
and scenarios defined in the model. Unlike the -c option, -pm does not
Optional additional
read and process the data during the file copy. As such it is
flags of “All” , “L” or
substantially faster than -c.
“ini”.
The package model function does not require access to a TUFLOW
licence.

Optional switches are:

“All” (e.g. -pmAll) copies all file extensions

(e.g. 1d_nwk_culv_L.mif, will become 1d_nwk_culv_L.*).
“L” (e.g. -pmL) list the files to be copied into an output file, but
doesn’t copy the files.
“ini” (-pmini <file.ini>) provides a .ini file with user defined options
as described below.

Combinations of the above are also valid, with the order of the optional
switches not being important (-pmAllL would be treated the same as -
pmLAll).

Three options are also available for handling of the binary processed
files created by TUFLOW to speed up the simulation start. These
options are:

-xf0: Do not copy .xf files, only the original inputs are copied.
-xf1: Copy both raw input files and .xf files.
-xf2: Copy only .xf files, if xf files exist for an input only the xf file
will be copied.

For example, the command line below will package the model but not
include any .xf files.

TUFLOW_iSP_w64.exe -pm -xf0 PR_~s1~_~e1~_~e2~_001.tcf

When using package model the default destination folder is created in

the same directory as the .tcf file, with the prefix “pm_”. For example,
C:\Projects\Modelling\TUFLOW\runs\Run_001.tcf will create a package
in the folder “C:\Projects\Modelling\TUFLOW\runs\pm_Run_001”.

A .ini file can be used to overwrite the default base and destination
folders. A .ini file is specified by including the optional ini argument
after -pm followed by the ini file name. For example:

TUFLOW_iSP_w64.exe -pmini package.ini

PR_~s1~_~e1~_~e2~_001.tcf

Valid commands in the .ini file are:

Base Folder == <folder>

Copy Destination == <folder>
Model Scenario ~s<number> == <scenario a> | <scenario b> | …
Model Event ~e<number> == <event a> | <event b> | …

Section 13 Managing and Starting Simulations - 26 / 42 Page 567 / 1094

 Switch Description

Max Event Name == <number> </file.ini>

Used to select which processing units to direct the simulation towards.

At present this only applies to the HPC GPU solver where a simulation
is to be directed to a particular GPU card or cards. –pu must be
specified once for each device. For example, to direct the simulation to

-pu<id> GPU devices 0 and 2, specify –pu0 –pu2. Can be used in place of the
.tcf command GPU Device IDs . Note that the numbering starts at 0
for GPU devices.

Override files (see Section 4.2.16 ) can be used to control the device
ID’s used by a range of computers accessing the same control file.

Query the creation of a folder. If you would prefer to have the create
-qcf folder query dialog to appear (rather than TUFLOW automatically
creating folders - see -acf), you can specify the –qcf run time option.

Specifies a scenario name to be used by If Scenario blocks to

include/exclude commands. There must be a space between –s and
<name>. <name> may itself contain spaces, but if it does the scenario
name must be enclosed in quotes. More than one (maximum of nine)
scenarios per simulation maybe specified by placing a number after –s.
–s and –s1 are treated the same, so don’t specify both of them

-s<name> otherwise indeterminate results may occur.

-s{1-9}<name> Also see Section 13.3.2 and Model Scenarios .

Examples:
–s exg Process all exg scenario commands.
–s1 opA –s2 opB Process all opA and opB scenarios.
–s opA –s2opB Same as above.
–s “Option A” Quotes required as there is a space in the scenario
name.

Simulation Log Path is a legacy option for Softlok (blue) dongles to set
the path to a folder on the intranet to log all simulations initiated from
-slp the lock. Refer to the 2018 manual or earlier for details. (See Section
13.5.1.2 for equivalent option for WIBU Codemeter licences, and also
Simulations Log Folder .)

The start time for a simulation can be specified using the run option -
st<time_in_hours>. Any start time specified via this run option
-st<time_in_hours>
argument is given the highest priority and overrides the Start Time
settings in the .tcf, event files (.tef) and override files.

Test input only. Processes all input data including writing of check files,
but does not start the simulation. Useful for checking that simulations
-t in a .bat file all initialise without error, prior to carrying out the
simulations (especially when the runs will take all night or all weekend
and you made a change you forgot to test!).

Section 13 Managing and Starting Simulations - 27 / 42 Page 568 / 1094

 Switch Description

-wibu Search for a WIBU Codemeter licence only.

-x eXecute the simulation (the default).

@1836
13.5.2.2 Copy/Package Model from Batch Files

TUFLOW can be run in copy mode, which can be useful for transferring a model to another site or
for making an archive of the input data. To copy a TUFLOW model, the -c switch must be included
on the TUFLOW command line. The -nlc (no licence check) flag can be used to copy a model
without the need for a TUFLOW licence. Further details can be found here.

A licence free package model function that copies all input files for all events and scenarios
defined in the model is also available using the -pm switch. If only a single set of events and
scenarios is required, -c is preferable. Unlike the -c option, -pm does not read and process the
data during the file copy, as such it is substantially faster than -c. The package model function
does not require access to a TUFLOW licence. More information on the Package model function
can be found here.

@1837
13.5.2.3 Advanced Batch Files

Batch files can be set up so that they are more generic and easily customised when moving from
one project to another. Within the example below, a variable, TUFLOWEXE, is used to define the
path to the TUFLOW executable, and a variable RUN is used to incorporate options such as
starting the simulation on a low priority and to minimise the console window when the process
starts (/min option).

set TUFLOWEXE=C:\ProgramFiles\TUFLOW\2023-03\TUFLOW_iSP_w64.exe
set RUN=start “TUFLOW” /low /wait /min “%TUFLOWEXE%” -b
%RUN% MR_H99_C25_Q100.tcf
%RUN% MR_H99_C25_Q050.tcf
%RUN% MR_H99_C25_Q020.tcf

The advantage of using variables in batch files is if the path to the TUFLOW executable changes,
or to run a different version of TUFLOW, it is just a simple single line change in the batch file. In
the above, note the use of quotes around %TUFLOWEXE% in the definition for the RUN variable
– quotes are needed around file path names whenever they contain a space. Also note there is no
space between the variable name and the equals sign.

For examples of batch files used for running multiple events and different scenarios from the same
.tcf file, see Sections 13.3.1 and 13.3.2 .

It is also possible to create control logic such as loops in a batch file. For example, this could be
used to loop through a large number of events and scenarios such as the example here.

:: This sets the variables as local, another batch file can use the same
variables
SetLocal
:: Set up variables
set TUFLOWEXE=C:\Program Files\TUFLOW\Releases\2023-

Section 13 Managing and Starting Simulations - 28 / 42 Page 569 / 1094

 03\TUFLOW_iSP_w64.exe
set RUN=start “TUFLOW” /low /wait /min “%TUFLOWEXE%” -b
set A=Q010 Q020 Q050 Q100 Q200
set B=10min 30min 60min 120min 270min
:: Loop through each simulation
FOR %%a in (%A%) do (
FOR %%b in (%B%) DO (
%RUN% -e1 %%a -e2 %%b filename_~e1~_~e2~.tcf
)
)
pause

Further guidance on advanced batch files, including looping examples can be found on this page
of the TUFLOW Wiki.

@1838
13.5.3 Running TUFLOW HPC

The front end of TUFLOW Classic and TUFLOW HPC are identical. No modification of the model
input is needed to utilise the TUFLOW HPC solver (in CPU or GPU compute mode). Similarly, the
output data is written by TUFLOW in the same output formats and data types irrespective of
whether Classic or HPC solvers are used.

The .tcf Solution Scheme command is used to switch the solution scheme from TUFLOW Classic
(the default) to TUFLOW HPC.

Hardware is used to access GPU hardware (CPU is the default). As such, to convert a model
from TUFLOW Classic to TUFLOW HPC and run using GPU hardware only requires two additional
TCF commands in most cases:

Solution Scheme == HPC

Hardware == GPU

With TUFLOW HPC it is possible to use multi-GPU cards to split the simulation across multiple
cards to reduce run times or access more GPU memory. This is carried out either by using the
GPU Device IDs command or with the processing unit command line switch “-pu”). More
@1839
information can be found here. It is also possible to simulate multiple simulations on a single GPU
card, should model memory requirements allow it, however, the simulations will slow down
proportionately.

TUFLOW HPC simulations are started in the same manner as a standard TUFLOW simulation and
explained in Section 13.5.2 .

@1840
13.5.3.1 TUFLOW HPC and GPU Module Commands

The following .tcf commands (apart from Timestep ) are commands specific to the TUFLOW HPC
solver:

Section 13 Managing and Starting Simulations - 29 / 42 Page 570 / 1094

 @1841
Table 13.3: TCF commands (apart from Timestep) specific to the TUFLOW HPC solver

Command Description

The default HPC Courant, shallow wave celerity and diffusion control number
limits can be reduced to effectively underclock the simulation. Using the above
Control command factors all three control numbers. For example, a value of 0.8
Number reduces the default limits by 20%. Reducing the control number limits may be
Factor useful if the simulation is exhibiting erratic behaviour or numerical “noise”,
although testing has found this is rare in real-world models, and if occurring is
more likely to be a sign of poor data or poor model schematisation.

TUFLOW HPC can be run using CPU or GPU hardware. This command
defines the hardware to be used for the compute. CPU is the default and will
run a simulation using the Central Processing Unit (CPU). GPU will run the
simulation using the Graphics Processor Unit (GPU).

When running TUFLOW HPC using the GPU hardware module, the pre
Hardware
(reading of data) and post processing (writing outputs) is managed by the
standard TUFLOW CPU engine. This allows the user to utilise the extensive
range of GIS input functionality available in TUFLOW.

Simulation using GPU hardware requires the GPU Hardware Module in

addition to a standard TUFLOW licence.

TUFLOW HPC is available in both single precision and double precision. If the
simulation is started with the single precision version of TUFLOW, the HPC
solver will utilise a single precision version. If the simulation is started with the
double precision version of TUFLOW, CHECK 2420 will be output by default
stating that the single precision version should be used.

The calculation method in TUFLOW HPC uses depth due to its explicit nature,
unlike TUFLOW Classic that uses water level due to its implicit scheme. This
means that precision issues when using the Classic solver, such as when
HPC DP applying a very small rainfall to a high elevation, are not applicable in HPC.
Check For more information see Section 13.4.2.2 .

Unless testing shows that single and double precision produce significantly
different results, use the single precision version of TUFLOW for all TUFLOW
HPC simulations. Note: Double precision solutions on GPU cards can be four
times slower than single precision! Also, NVIDIA Cards with a compute
capability of 1.2 or less are only able to run single precision versions.

The HPC DP Check command allows the user to disable this check should
double precision be required, or increase it to an ERROR.

Section 13 Managing and Starting Simulations - 30 / 42 Page 571 / 1094

 Command Description

Sets the order of the temporal solution. The default is the recommended 4th
order temporal solution, therefore this command is usually not specified.

HPC We recommend the use of the 4th order temporal scheme as it is

Temporal unconditionally stable with adaptive timestepping turned on and has been

Scheme found to give accurate results and is results are not affected due to changing
the timestepping. Lower order schemes save a little on memory requirements
but are more prone to instability and in some cases unreliable results that are
sensitive to the timestepping intervals.

GPU Device Controls the GPU device or devices to be used for the simulation if multiple
IDs CUDA enabled GPU cards are available in the computer or on the GPU itself.

This command is used to select the desired solution scheme for the compute.
Solution
Use “HPC” to call TUFLOW HPC’s finite volume 2nd order solver
Scheme
(recommended over the 1st order alternative).

If adaptive timestepping is active (the default), the timestep value is only used
for the very first step. To allow the same command to be used for either a
TUFLOW Classic or a HPC simulation the timestep value is divided by 10 for
the initial HPC timestep, therefore, enter a timestep value similar to that that
you would use for TUFLOW Classic.
Timestep
If adaptive timestepping is off, sets the fixed timestep. The timestep will
always be much smaller than TUFLOW Classic’s timesteps as the scheme is
explicit (TUFLOW uses an implicit scheme). As a general rule of thumb specify
a timestep that is around one tenth of the TUFLOW Classic timestep you
would use.

@1842
13.5.3.2 Compatible Graphics Cards

TUFLOW HPC’s GPU hardware module requires an NVIDIA CUDA enabled GPU card. A list of
CUDA enabled GPUs can be found on the following website: https://developer.nvidia.com/cuda-
gpus.

To check if your computer has an NVIDIA GPU and if it is CUDA enabled:

1. Right click on the Windows desktop.

2. If you see “NVIDIA Control Panel” or “NVIDIA Display” in the pop-up dialogue, the computer
has an NVIDIA GPU.
3. Click on “NVIDIA Control Panel” or “NVIDIA Display” in the pop-up dialogue.
4. The GPU model should be displayed in the graphics card information.
5. Check to see if the graphics card is listed on the following website:
https://developer.nvidia.com/cuda-gpus.

The following screen images show the steps outlined above, this may vary slightly between
NVIDIA GPU card models.

@1843

Section 13 Managing and Starting Simulations - 31 / 42 Page 572 / 1094

 Figure 13.2: Accessing NVIDIA Control Panel from the Desktop
@1844

Figure 13.3: NVIDIA GPU Model

@1845

Figure 13.4: Check the Website for your NVIDIA Card

More information on the card can be found in the “System Information” section, which is accessed
from the NVIDIA Control Panel. The system information contains more details on the following:

The number of CUDA cores.

Frequency of the graphics, processors and memory.
Available memory including dedicated graphics and shared memory.

Section 13 Managing and Starting Simulations - 32 / 42 Page 573 / 1094

 @1846

Figure 13.5: NVIDIA System Information

On the NVIDIA website, each CUDA enabled graphics card has a “Compute Capability” listed. For
cards with a compute capability of 1.2 or less, only the single precision version of the GPU Module
can be utilised. However, benchmarking has indicated that the double precision version,
except in rare situations, is NOT required and that for nearly all GPU simulations,
TUFLOW_iSP engine versions should suffice. Refer to Section 13.4.2 .

Extensive GPU hardware benchmarking has been undertaken to assist users who are upgrading
hardware for TUFLOW modelling, with numerous hardware options tested for their speed
performance. The results are provided on the TUFLOW Wiki.

@1847
13.5.3.3 Updating NVIDIA Drivers

It is likely that the NVIDIA drivers will need to be updated periodically to the latest version as the
drivers shipped with Windows Operating Systems are not always up-to-date. To update, open the
NVIDIA Control Panel (by right clicking on the desktop and selecting NVIDIA Control Panel or
NVIDIA Display). Once the control panel has loaded, select Help >> Updates from the menu items.
For further guidance see the Updating NVIDIA Drivers Wiki Page.

If new drivers are available, please download and install these by following the prompts.

NOTE: Even if not prompted by the system, a restart is recommended to ensure the new
drivers are correctly detected prior to running any simulations.

@1848

Figure 13.6: Accessing Driver Updates from the NVIDIA Control Panel

@1849
13.5.3.4 NVLink – Multi-GPU Performance (HPC Only)

NVLink is a connection (cable) for NVIDIA GPU devices providing peer-to-peer (direct) access
between GPUs, rather than having to communicate via the CPU, giving faster communication. For
example, data transfer rate for the RTX 2080 Ti is 32GB/s on the CPU PCIe and 100 GB/s via an
NVLink. The TUFLOW 2020-01 and later releases automatically recognises and utilises any peer-

Section 13 Managing and Starting Simulations - 33 / 42 Page 574 / 1094

 to-peer (p2p) access between GPUs that is possible according to the hardware setup. Peer-to-
peer access typically requires an NVLink connector between GPUs, or in some cases peer-to-peer
access can occur via the PCI bus if all cards are placed into TCC driver mode.

Whilst testing thus far has not produced a huge jump in performance, it is expected greater gains
in the future will arise as it is increasingly possible to connect to large numbers of GPU devices,
especially Cloud-based instances. The user can choose to disable peer-to-peer GPU access by
specifying the .tcf command: GPU Peer to Peer Access == DISABLED | {ENABLED IF
AVAILABLE}. This can also be specified using the command line argument -p2p0 to disable, or -
p2p1 to enable (if available). Peer-to-peer access in rare occasions has failed to work when a peer
connection has been reported as possible by the NVIDIA console or API.

@1850
13.5.3.5 Troubleshooting

If you receive the following error when trying to run the TUFLOW GPU model:

TUFLOW GPU: Interrogating CUDA enabled GPUs …

TUFLOW GPU: Error: Non-CUDA Success Code returned

Please try the following steps:

1. Check the compatibility of your GPU card and whether the latest drivers are installed (see
instructions in Section 13.5.3.2 ).
2. Test with a user account that has administrator privileges as these may be required for
running computations on the GPU.
3. If multiple monitors are running from the video card, try running with only a single monitor.

If the above steps fail to get the simulation to run, please email the NVIDIA system information
(see Section 13.5 ) and TUFLOW log file (.tlf) to [email protected].

@1851
13.5.4 Running TUFLOW 1D Only Simulations

TUFLOW is set up to run as either a 2D model or as a 1D/2D model. It is, however, possible to run
a TUFLOW 1D only model by including a small ‘dummy’ 2D domain within the model files. The 2D
domain can be set up with the .tgc file and can be small, contain few cells of uniform material type
and elevation values. The .tbc file will be set up so that the 2D domain does not receive any flows
and therefore will not impact simulation runtimes. The 1D model can then be constructed within
the .ecf and the simulation set up within the .tcf as per usual. An example model exists on the
TUFLOW User Gitlab Page.

@1852
13.6 Using TUFLOW with Flood Modeller, SWMM,
XP-SWMM, 12D or from SMS

TUFLOW supports the linking with third-party external 1D schemes such as Flood Modeller
(Jacobs), SWMM (USA EPA SWMM Version 5), XP-SWMM (Autodesk), 12D (12D Solutions) as
well as integration within the SMS GUI (Aquaveo). Flood Modeller (formerly known as ISIS), XP-
SWMM and 12D executables access the TUFLOW hydraulic computational engine via the
TUFLOW_LINK.dll. EPA SWMM (Version 5) is built into the standard TUFLOW release (2023-03-

Section 13 Managing and Starting Simulations - 34 / 42 Page 575 / 1094

 AF build or later). Flood Modeller, XP-SWMM, 12D and SMS are generally distributed with the
latest supported version of TUFLOW at the time of release. It is possible to utilise different
versions of TUFLOW with external 1D schemes using the processes described in the following
sections.

@1853
13.6.1 Using TUFLOW with EPA SWMM

When running a TUFLOW - SWMM model, TUFLOW controls the execution of the simulation.
SWMM input commands are specified within a SWMM Control File (.tscf). The SWMM control file
is referenced in the TUFLOW Control File (.tcf) and the available commands listed in Appendix I .

The SWMM Control File can reference multiple SWMM input files (inp) potentially varying by
scenario. These input files are merged giving preferences to later files allowing for the overriding
(upgrading) of existing features. After the input files are merged, the final SWMM model will be
placed in the TUFLOW output folder and will be executed from there. The report and output files
generated by the SWMM engine will also be placed in the TUFLOW output folder.

@1854
13.6.2 Using TUFLOW with Flood Modeller

Flood Modeller is shipped with the latest release of TUFLOW available at the time of development.
It is possible to set Flood Modeller up to use a different version of TUFLOW. Before changing the
version of TUFLOW, firstly check the compatibility between Flood Modeller and TUFLOW versions
in Figure 10.12 . To utilise a newer, or different, version of TUFLOW with Flood Modeller, use the
Flood Modeller interface to set the TUFLOW Engine File location to the path of the TUFLOW
executable required in the Project Settings as shown in Figure 13.7 .

@1855

Figure 13.7: Flood Modeller Settings

If running TUFLOW HPC utilising GPU hardware, it is important that the Flood Modeller folder
contains copies of four TUFLOW files (aka kernels). The Flood Modeller folder is called the “bin”
folder and is located (by default) in “C:\Program Files\Flood Modeller”. It is important that the
kernel files in the Flood Modeller ‘bin’ folder match those of the TUFLOW version specified in the
Flood Modeller project settings. For TUFLOW versions 2023-03-AA release or later, the names of
the kernels have changed and are:

hpcKernels_nSP.ptx
hpcKernels_nDP.ptx
qpcKernels_nSP.ptx
qpcKernels_nDP.ptx

Section 13 Managing and Starting Simulations - 35 / 42 Page 576 / 1094

 If you need to use a later release of TUFLOW or if you find that the link in a Flood Modeller-
TUFLOW coupled model is failing with a ERROR 3999 message (and an error description of ‘ptx
file version mismatch’ in the hpc.tlf), then browse to your TUFLOW engine folder, and copy the
above four files and then paste them into your Flood Modeller bin folder (replacing the files there).
If wanting to use the 2023-03-AA release or later, ensure the relevant kernels are in the Flood
Modeller Bin folder and any other older TUFLOW .ptx files (ie, kernels_nSP.ptx, kernels_nDP.ptx)
are removed.

It is also possible to run Flood Modeller-TUFLOW models using a batch file, which can be useful
where different combinations of Flood Modeller and TUFLOW versions are required. This page
provides instructions on how to set this up.

@1856
13.6.3 Using TUFLOW with 12D

12D is shipped and installed with the latest version of TUFLOW at the time of release. Although it
is recommended to use the latest version of TUFLOW, it is possible to use other versions of
TUFLOW by copying the TUFLOW engine files into the 12D installation folder, which is usually
C:Files\12d\12dmodel\15.00_2d. It is possible to have multiple versions of 12D installed to allow
multiple 12D-TUFLOW pairs to be installed.

There are two ways to run a TUFLOW model within 12D. The first is via the 2D Quick Analysis,
which enables an efficient approach to using TUFLOW with a limited number of parameter options
as shown in Figure 13.8 .

@1857

Figure 13.8: 12D 2D Quick Setting

The second approach is to use the TCF editor allowing full TCF control, and String attribute editing
which exposes all the TUFLOW functionality to a 12D user. The TCF editor is shown in Figure
13.9 .

@1858

Section 13 Managing and Starting Simulations - 36 / 42 Page 577 / 1094

 Figure 13.9: 12D TUFLOW Project Editor

@1859
13.6.4 Using TUFLOW with XP-SWMM

XP-SWMM is generally shipped with the latest release of TUFLOW available at the time of
development. To utilise a new version of TUFLOW with XP-SWMM, all of the .dll and .ptx files
described in the previous section need to be copied to the location where XP SWMM accesses
them (usually in the same folder as the XP-SWMM .exe files). Alternatively, modifying the path and
environment variable found within Advanced Settings allows the user to point to the location of the
TUFLOW .dll and .ptx files. They do not access the TUFLOW.exe file, although there are no
issues in copying this file as well. Note, it is always wise to keep copies of any old .dll/.ptx files in a
separate folder.

@1860
13.6.5 Using TUFLOW with SMS

When running TUFLOW from SMS, SMS by default looks for a TUFLOW.exe in the installation
folder. To change this to the location where you have placed the TUFLOW.exe and .dll/.ptx files,
go to the Edit, Preferences, File Locations tab as shown in Figure 13.10 .

@1861

Figure 13.10: SMS Settings

@1862
13.6.6 Optimising Startup and Run Times

Regardless of the method for initiating a TUFLOW simulation, a simulation start stats file
(_start_stats.txt) is output to the same location as the .tlf file (see Section 14.5.3 ). This file
contains information on the total time and the time elapsed for each stage of model initialisation.

Section 13 Managing and Starting Simulations - 37 / 42 Page 578 / 1094

 This can be used to identify the stages causing slow simulation start-up. If you have a problematic
(slow starting) model, please email this file and corresponding .tlf file through to
[email protected].

From the 2018-03-AA release, a new output file is created named “_run_stats.txt” (see Section
14.5.4 ). This file contains the amount of time that TUFLOW spends in the 1D and 2D
computations. At each mass balance output interval, the percentage of the total computational
effort that TUFLOW has spent in 1D calculations, 2D calculations and other is output to the
run_stats file. The “other” column includes a variety of tasks that are neither 1D or 2D
computations, such as writing of outputs, and transfer of data to GPU (if running on GPU devices).
“Other” also includes time spent within an external 1D solver.

@1863
13.6.6.1 Improved pre-processing of 1D Model Inputs

For the 2020-01 release, reading and processing of 1D inputs has been significantly improved,
particularly for large urban drainage models (>1,000 1D pipe network elements). For a tested
model with 25,000 1D channels, the start-up was approximately 40 times faster with the 2020-01
release compared to the previous 2018-03 release changing the start-up time from nearly two
hours to less than 3 minutes. No changes in model files is required to implement this improved
pre-processing time.

@1864
13.6.6.2 Parallel Processing for SGS initialisation

With the default SGS Method C (the default if “SGS == ON”), the SGS elevations are retained in
memory throughout the pre-processing stage, with the generation of the storage and face
hydraulic data curves occurring only once at the end of the pre-processing. This is a
computationally intense exercise, particularly for large models with small SGS sample distances.
To speed up model initialisation, this has been parallelised to utilise multiple CPU cores.

By default, all CPU threads will be used for final SGS elevation pre-processing unless the number
of threads (-nt[thread count]) command line argument has been specified. For example, to run on
8 threads the command line argument “-nt8” would be used. There is no check for thread licensing
used for pre-processing. If the number of threads specified in the command line argument
exceeds the number of threads available, all threads are used.

At the end of the .tgc file, after all elevation datasets have been processed, an XF file is written if
the XF Files command is set to on (default). The XF file is written to an “xf” folder, which sits in
the same location as the .tgc. The XF file is then used for any subsequent simulations for
optimised pre-processing performance. To avoid re-processing when changes are made to .tgc
data other than elevation (e.g. active cells, materials, soils, etc.), the XF file is not written with the
same filename as the .tgc. Instead, the .xf will be prefixed by “hpc” or “qdt” for HPC single grid and
Quadtree simulations respectively and includes the nesting level and cell size. Any text set with
the .tcf command XF Files Include in Filename is included.

When reading the pre-processed SGS XF file, a check is done on the final SGS elevations, if
these are consistent then the XF file is used.

Section 13 Managing and Starting Simulations - 38 / 42 Page 579 / 1094

 @1865
13.6.6.3 Optimising Multi-GPU Performance (HPC Only)

If a model is simulated across multiple GPU devices, one of the devices (usually the one with the
most wet cells) will be controlling the speed of the simulation and the other devices will be
underutilised. By default, TUFLOW HPC divides a model equally over multiple GPU devices.
However, for real-world models, it is usual for the GPUs to have an inequitable amount of
workload due to the number of active cells and number of wet cells, and this can change
throughout the simulation as the model wets and dries.

From the TUFLOW 2020-01 release it is possible to distribute the workload unequally to the GPU
devices. During a simulation the workload efficiency of each GPU is output to the console and to
the .tlf file with a suggested distribution provided at the end of the simulation. A number of
iterations may be required to fully optimise the distribution.

For example, a model simulated across four GPU devices reported at the end of the simulation in
the .tlf file:

Relative device loads: 60.3% 100.0% 83.7% 53.2%

HPC Suggested workload balance HPC Device Split == 1.23, 0.74, 0.89,
1.40.

The command HPC Device Split == 1.23, 0.74, 0.89, 1.40 was added to the .tcf file
for the next simulation producing the improved device workload efficiencies below and a 20%
faster run time.

Relative device loads: 100.0% 96.1% 96.8% 94.6%

Note: The benefit depends on the model, but if you have a significant variation in workload
efficiencies between GPU devices this feature should provide a noticeable decrease in run
times.

@1866
13.6.7 Auto Terminate (Simulation End) Options

TUFLOW Classic and HPC include an Auto-Terminate feature for stopping simulations after the
flood peak has been experienced within the simulation. This can help project efficiencies by
avoiding unnecessary model simulation time once the peak flood extent has been achieved.

The 2D cells that are monitored to trigger the auto-termination are controlled by specifying a value
of 0 (exclude) or 1 (include) using the .tcf commands: Set Auto Terminate and Read GIS Auto
Terminate .

For example, in the below, all cells are first set to be excluded for monitoring followed by the
reading of a GIS layer to set cells individually.

Set Auto Terminate == 0

Read GIS Auto Terminate == ..\model\gis\2d_AT_001_R.shp

At each Map Output Interval the monitored cells are compared against two criteria:

1. The percentage of the wet cells that have become wet since the last map output interval.
2. The velocity-depth product at the current timestep compared to the tracked maximum.

Section 13 Managing and Starting Simulations - 39 / 42 Page 580 / 1094

 For the percentage of cells that have become wet since the last interval, the maximum allowable
value is controlled with the .tcf command:

Auto Terminate Wet Cell Tolerance </> ==

<maximum_allowable_%_of_newly_wet_cells>

If set to 0, then if any monitored cells have become wet since the last map output the simulation
continues. If set to a value of 5, then up to 5% of monitored cells can become wet since the last
map output while still triggering an auto-termination of the simulation.

For the velocity-depth tolerance, at each output interval the velocity-depth product is compared to
the tracked maximum value. If the current dV product is within the specified tolerance Auto
Terminate dV Value Tolerance the simulation is not terminated.

The total number of cells that are allowable within the specified range is controlled with Auto
Terminate dV Cell Tolerance . If set to a value of 1, then up to 1% of monitored cells can be
within the tolerance value without triggering an auto-termination of the simulation. The larger the
Auto Terminate dV Value Tolerance the further the dV product needs to have dropped from the
peak value.

The time that the auto-terminate feature commences can be controlled using the .tcf command
Auto Terminate Start Time otherwise the Start Time is used.

Note, this option is only assessed at every Map Output Interval .

@1867
13.7 Reproducibility of Results

A key concern with hydraulic modelling is the replication of results across a range of hardware.
The following sections provide some information to be aware of when looking at the replication of
results.

@1868
13.7.1 TUFLOW Classic (CPU only)

The TUFLOW Classic engine is written in Fortran and compiled for Windows™ with Intel™’s
Fortran compiler, leading to well optimised CPU code. The computational algorithm is implicit in
nature and difficult to parallelise for multi-thread execution. As a result race conditions do not exist
and a repeat run of a model with the same inputs, with the same executable on the same type of
CPU, should yield bit-wise identical results (i.e. a subtraction of results should be exactly zero). If
a user finds that repeat model runs (same executable, same CPU) do not yield identical results
then please contact [email protected] as this may indicate a memory access error or an un-
initialised variable in the code.

A repeat model run with the same executable but on a different type of CPU (e.g. Intel Xeon vs i9,
or AMD Epyc vs Ryzen, or Intel vs AMD) may produce very slight differences in results due to the
CPUs having different instruction set extensions that may or may not be utilised. Such differences
are typically less than 1 mm water surface elevation but, in some locations, the differences can
become accentuated due to changes in overtopping or an operational structure threshold.

Even though the source code for TUFLOW Classic is currently seeing little development, as we
update Intel Fortran compilers, different releases of TUFLOW can be expected to show minor
differences even on the same CPU.

Section 13 Managing and Starting Simulations - 40 / 42 Page 581 / 1094

 @1869
13.7.2 TUFLOW HPC (incl. Quadtree) on CPU

The TUFLOW HPC engine (incl Quadtree) is written in C++ with NVIDIA™ CUDA GPU kernels.
The kernels have been carefully written so that they can be compiled for both GPU and CPU
execution. When compiled for CPU execution, the Microsoft Visual Studio compiler is used and
the code is built into the dynamic link libraries (DLLs) in the executable bundle. Similar to
TUFLOW Classic, repeat model runs of the same model (same TUFLOW executable, same CPU
type) should produce bit-wise identical results. Again, if differences are observed please contact
[email protected] as this may indicate an issue that needs to be addressed.

As the TUFLOW HPC and Quadtree solvers are fundamentally different to TUFLOW Classic, there
will always be minor differences between solutions from the different schemes even when using
the same turbulence model and without sub-grid sampling (SGS). As TUFLOW HPC and Quadtree
both default to using the Wu turbulence model while Classic can only use the Smagorinksy model,
the differences will be more significant when run with the default settings.

@1870
13.7.3 TUFLOW HPC (incl. Quadtree) on GPU

When the CUDA kernels are compiled for GPU execution, a GPU agnostic intermediate code file
(ptx) is produced with the final compilation of that being done on a just-in-time basis by the GPU
driver on the machine that the executable is running on. The results may now depend not just on
the version of TUFLOW executable used and type of CPU (since the pre-processing of the model
input is still performed on CPU), but also on the type of GPU and the version of the GPU driver
installed. GPUs have thousands of cores that work in parallel. However, the kernels have been
carefully written to avoid race conditions, and the adaptive timestep control avoids relying on
variables summed with atomic additions of floating point data. Therefore, provided these factors
(version of TUFLOW, CPU type, GPU type, GPU driver version) are kept constant, a repeat model
run will yield bit-wise reproducible results.

Also note that the GPU cores use different hardware for the floating point operations and the GPU
compiler may re-optimise the sequence of instructions for complex lines of code compared to the
CPU compiler. Therefore, even when using the same version of TUFLOW HPC, very small
differences in the solution can be seen when the model is run on GPU compared to running on
CPU. These differences are typically less than 1 mm water surface elevation but again, in some
locations, the differences can become accentuated due to changes in overtopping or an
operational structure threshold.

@1871
13.7.4 TUFLOW HPC (incl. Quadtree) on multiple GPUs / CPU
threads

TUFLOW HPC (incl. Quadtree) support running a model across multiple GPU devices in one
computer. In this case the model is decomposed into subdomains, and model data are exchanged
and sychronised at the domain boundaries as required. Care has been taken to ensure that
results when run on multiple GPUs (of all the same GPU type) are bit-wise identical to when run
on a single GPU. If differences are observed between results from a run on multiple devices vs a
single device please contact [email protected].

Section 13 Managing and Starting Simulations - 41 / 42 Page 582 / 1094

 Likewise when running on multiple CPU threads (default is four unless specified), the model
results should be bit-wise identical to when running on a single thread (CPU Threads == 1).
Please contact us at [email protected] if found otherwise.

Section 13 Managing and Starting Simulations - 42 / 42 Page 583 / 1094

 @1876

@1877
Section 14 Checks and Log Files

@1878
14.1 Introduction

This chapter of the Manual describes the check, log and quality control outputs from TUFLOW.
This encompasses the following outputs:

The Console Window (Section 14.2 );

Message boxes (Section 14.3 );
Local and Global .log (Section 14.4 );
Simulation log files (e.g. .tlf, hpc.tlf, .tsf) (Section 14.5 );
1D Output File (.eof) (Section 14.6 );
Check Files (Section 14.7 ); and
Mass Balance Outputs (Section 14.8 ).

Viewing and processing of results are described in Chapter 15 .

@1879
14.2 Console (DOS) Window Display

TUFLOW displays a lot of information to the Console (DOS) Window during the data input and
simulations stages. However, this typically processes so quick, that it may be difficult to read. The
log file (.tlf) (Section 14.5 ) and check files (Section 14.7 ) contains this information in much
more usable formats, most of which is geo-referenced GIS layers. However, should you wish, you
can look back through the Window buffer to establish where in the input data process the problem
occurs.

After a model has completed initialising its input data and has started its computations, the
simulation status is displayed. The default display frequency for TUFLOW Classic is every
timestep and for TUFLOW HPC on GPU is every 100 timesteps. To change the frequency of
display, the Screen/Log Display Interval command can be used. Where different timesteps are
used for different domains, the display interval is based on the largest timestep. The console
window contains a lot of useful information to keep an eye on your simulations as they progress.
Whilst it isn’t expected to continuously watch the simulations DOS window, it is useful to glance at
occasionally to check that your simulations are “happy”.

If the Console window does not appear (i.e. TUFLOW.exe won’t start) there could be a few
reasons why, this is discussed on the TUFLOW Wiki.

If you are running from a batch file and the window briefly appears, then disappears straight away,
you can force the window to stay open so you can diagnose the issue. This is discussed in
Section 14.2.3 .

Section 14 Checks and Log Files - 1 / 33 Page 584 / 1094

 @1880
14.2.1 TUFLOW Classic

Once the hydraulic calculations commence, the TUFLOW Classic Console Window appears as
something similar to that shown below:

@1881

Figure 14.1: Example TUFLOW Classic Console (DOS) Display Window

The following information is shown along each line in order of occurrence.

Number of timesteps completed, based on the largest timestep of all 1D and 2D domains.
Simulation time in hhhh:mm:ss.
“-d” followed by two numbers:
The maximum number of 1D nodes per timestep that experienced negative depths below
‑0.1m since the previous display line.
The maximum number of 2D cell sides per timestep that experienced negative depths
below ‑0.1m since the previous display line.
The locations of these negative depths are output as warnings in the _messages layer
(see Section 14.5.5 ). Negative depths indicate the model is having difficulty in
convergence at that location, which may lead to an instability. See also Section 16.3.2 .
“Wet” followed by number of wet or active 2D cells.
If automatic weir switching is active (see Free Overfall ) the next information is “CS” (Cell
Sides) followed by two numbers as follows:
The number of cell sides where upstream controlled friction flow occurred (see
Supercritical ).
The number of cell sides where upstream controlled broad-crested weir flow occurred
(see Free Overfall ).
If the free-overfall algorithm is set to ON WITHOUT WEIRS (see Free Overfall ), the next
information is “FO” followed by the number of cell sides where the free-overfall algorithm is
being applied. Note: this option is now rarely used in lieu of the automatic weir and
supercritical flow options.
If Display Water Level was specified, the next piece of information is a “GL” (Gauge Level)
followed by the water level at the location indicated. This is useful to monitor the rise and fall
of the water level at a key location.
If Mass Balance Output is set to ON, “CE” (Cumulative Error) followed by three percentages
is displayed to show the cumulative mass error as follows:
The whole of model % cumulative mass error for all 1D and 2D domains.
The % cumulative mass error for all 1D domains.
The % cumulative mass error for all 2D domains.
If Mass Balance Output is set to ON the following are displayed after the “CE” percentages:

Section 14 Checks and Log Files - 2 / 33 Page 585 / 1094

 “Qi” followed by the total flow into the model (all domains) in m3/s. If the inflow exceeds
999999m3/s or falls below -99999m3/s, the flow is expressed in units of 1,000m3/s and a
single quote symbol is displayed after the number. A double quote symbol indicates the
flow is expressed in units of 1,000,000m3/s.
“Qo” followed by the total flow out of the model (all domains) in m3/s. If the outflow
exceeds 999999m3/s or falls below -99999m3/s, the flow is expressed in units of
1,000m3/s and a single quote symbol is displayed after the number. A double quote
symbol indicates the flow is expressed in units of 1,000,000m3/s.
“dV” followed by the change in volume in m3 of the model (all domains) since the last
display time. If the change in volume exceeds 999999m3 or falls below -99999m3, the
amount is expressed in units of 1,000m3 (mL) and a single quote symbol is displayed
after the number. A double quote symbol indicates the change in volume is expressed in
units of 1,000,000m3.
If maximums are being tracked (i.e. Maximums and Minimums is set to ON or ON
MAXIMUMS ONLY), additional information will be displayed to the Console Window and .tlf
file for each Screen/Log Display Interval . Three numbers are displayed after “Mx” at the end
of each line. The first two numbers are the percentage of 1D nodes and percentage of 2D
cells that reached a new maximum in the last computational timestep. The third number is the
time in decimal hours since no new maximum was recorded anywhere within the model. For
example, “Mx 10 21 0.0” indicates that 10% of 1D nodes and 21% of 2D cells recorded a new
maximum last timestep, and the time since the last recorded maximum is zero. Once all 1D
nodes and 2D cells have reached their maximums the third (time) value will increase above
zero.

The negative depth numbers, cumulative error percentages, inflow, outflow and change in volume
figures are very useful to gauge the health of the model. Frequent negative depths, poor
cumulative error (>1%, noting that some models will show a high mass error at the start, which
can be acceptable provided it diminishes quickly) and “bouncy” inflow, outflow and change in
volume values are all indicators of an unhealthy model. For further discussion see Section 16.1 .

Whenever the map output is written (see Start Map Output and Map Output Interval ), a line
“Writing Output at:” is displayed, followed by the simulation clock time and CPU time. If the CPU
time is significantly lower than the clock time, then either the simulation was paused for a period of
time (see Section 14.2.4 ), the CPU is overloaded or the CPU is not being fully utilised (having
Hyper Threading switched on can cause this to occur).

@1882
14.2.2 TUFLOW HPC

Once the hydraulic calculations commence, the TUFLOW HPC Console Window appears similar
to the two images shown below:

@1883

Section 14 Checks and Log Files - 3 / 33 Page 586 / 1094

 Figure 14.2: Example TUFLOW HPC Console (DOS) Display Windows
For lines starting with “HPC:” the following information is shown along each line in order of
occurrence.

Number of timesteps completed, based on the largest timestep of all 1D and 2D domains.
Simulation time in hhhh:mm:ss.
Timestep Control Numbers:
Nu: Courant Number.
Nc: Shallow Wave Celerity Number.
Nd: Diffusion Number.
Number of wet cells.
Volume.
Computed timestep.
The timestep efficiency.

If the model contains virtual pipe networks, the following additional information is shown:

qInlet: flow extracted from the 2D domain.

qSurcharge: flow surcharging out of inlets, due to the outlet flow being limited.
qOutput: flow entering the 2D domain.

For lines starting with “SIM:”, which occur at regular simulation time increments, additional
statistics are output:

Simulation time in hhhh:mm:ss.

“-d” followed by two numbers:
The maximum number of 1D nodes per timestep that experienced negative depths below
‑0.1m since the previous display line.
The maximum number of 2D cell sides per timestep that experienced negative depths
below ‑0.1m since the previous display line.
Three compute percentage values:
0D % time spent on pre/post processing and CPU/GPU communication overhead.
1D % time spent on 1D compute.
2D % time spent on 2D compute.
“CE” (Cumulative Error) followed by three percentages is displayed to show the cumulative
mass error as follows:
The whole of model % cumulative mass error for all 1D and 2D domains.
The % cumulative mass error for all 1D domains.
The % cumulative mass error for all 2D domains.

Section 14 Checks and Log Files - 4 / 33 Page 587 / 1094

 Model volumes:
“Vi” followed by the total volume of water into the model in m3/s. If the volume in exceeds
999999m3 or falls below -99999m3, the amount is expressed in units of 1,000m3 (mL)
and a single quote symbol is displayed after the number. A double quote symbol indicates
the change in volume is expressed in units of 1,000,000m3.
“Vo” followed by the total volume of water out of the model (all domains) in m3/s. If the
volume out exceeds 999999m3 or falls below -99999m3, the amount is expressed in units
of 1,000m3 (mL) and a single quote symbol is displayed after the number. A double quote
symbol indicates the change in volume is expressed in units of 1,000,000m3.
“dV” followed by the change in volume in m3 of the model (all domains) since the last
display time. If the change in volume exceeds 999999m3 or falls below -99999m3, the
amount is expressed in units of 1,000m3 (mL) and a single quote symbol is displayed
after the number. A double quote symbol indicates the change in volume is expressed in
units of 1,000,000m3.

@1884
14.2.3 The Console (DOS) Window Does Not Appear

If you are running from a batch file and the window briefly appears, then disappears straight away,
you can force the window to stay open so you can diagnose the issue.

To do this, insert “pause” at the end of the batch file and remove any Start “TUFLOW”, -b and/or -t
switch. For example:

C:\TUFLOW\Releases\2023-03-AF\TUFLOW_iSP_w64.exe MR_H99_C25_Q100.tcf
Pause

Using this simple batch file will start the simulation in the main batch window and give you greater
control. Adding “Pause” at the end of the batch will keep the window open.

Common troubleshoot tips can be found here.

@1885
14.2.4 Unexpected Simulation Pause (DOS Quick Edit Mode)

Windows 10 and onwards includes a Quick Edit mode option in the DOS window that can
artificially pause TUFLOW simulations. The Quick edit mode is initiated if the cursor clicks
somewhere on the DOS window while a TUFLOW simulation is running. Quick Edit mode can be
deactivated to avoid this issue.

1. Right click the DOS window header. Select “Properties”.

Section 14 Checks and Log Files - 5 / 33 Page 588 / 1094

 2. Uncheck “Quick Edit Mode”. This will turn it off for the current session.

3. Update the default DOS window properties so this becomes the default mode. Right click the
DOS window header. Select “Defaults”.
4. Uncheck “Quick Edit Mode”, just like in the “Properties” dialog box. This will turn Quick Edit
Mode off for all future sessions.

@1886
14.2.5 Stopping the Console Window

It is possible to stop a simulation by using Ctrl+C. When pressed the first time (with the TUFLOW
console as the active window) the dialogue below is displayed asking whether to stop the
simulation. Clicking on “Yes” will finish the simulation, write all output files and release any
network dongle licence. The simulation is logged as being INTERRUPTED in the .tlf and .log files
(refer to Section 14.4 ). Clicking on “No” will continue the simulation.

Section 14 Checks and Log Files - 6 / 33 Page 589 / 1094

 Ctrl+C is recommended instead of manually cancelling the simulation via clicking the display
window close button. TUFLOW will not finalise writing the output result files if the simulation is
cancelled via clicking the display window close button. For example, result maximums and
minimums will not be written, even if Maximums and Minimums is set to ON.

In versions of Windows prior to Windows 10, it was possible to pause output processing in a
terminal window by pressing Ctrl+S, which would effectively suspend TUFLOW. In modern
versions of Windows, you may be able to achieve the same by either pressing Ctrl+S, the Pause
button, or selecting text in the terminal window with the mouse (if quick edit mode is turned on,
see Section 14.2.4 ). This depends on the versions of software used and their configuration.

@1887
14.2.6 Customisation of Console Window

The windows and buffer sizes of the Console Window are by default set by TUFLOW. During the
model input stages the window is set to 122 characters wide and 30 lines high. During the
hydraulic calculations the width varies depending on the length of the output to the window and
the height is set to 40 lines.

It is possible to manually set the Console Window buffer as well as change the font and colours of
the TUFLOW window. The latter may be useful when differentiating different models on a shared
computer. For further information, refer to guidance found on the TUFLOW Wiki.

@1888
14.2.7 TUFLOW Windows ERROR LEVEL Reporting

If TUFLOW exits unsuccessfully, e.g. an error during initialisation or due to the model going
unstable an ERRORLEVEL is reported to the Windows operating system. This value is 1 if a
premature exit has been encountered and 0 for a normal exit. This can be useful for tracking
simulation issues if using batch files, scripts or a simulation run manager. In a batch file the error
level can be obtained with the %errorlevel% variable. For example:

Start “TUFLOW” /wait TUFLOW_iSP_w64.exe runfile.tcf

echo error level is %errorlevel%

Prior to the 2018-03-AA version of TUFLOW, no error level was reported.

@1889
14.3 Message Boxes

Windows message boxes are used to alert the user to an input problem and when a simulation
has stopped/finished, or is unable to start. This can be suppressed with the -nmb input switch as
described in Table 13.2 .

Some example message boxes are shown below.

Section 14 Checks and Log Files - 7 / 33 Page 590 / 1094

 @1890
14.4 Simulations .log

TUFLOW activity (when simulations are started, finished, interrupted) is written to two log files:

A local file named “\_ TUFLOW Simulations.log”, located in the same folder as the .tcf file.
This file is described in Section 14.4.1 .
A global log file that can optionally be located in a fixed location on your organisation’s
intranet. By default this is written to “C:\ProgramData\TUFLOW\\log\_All TUFLOW
Simulations.log”. To alter the location of this, use the Simulations Log Folder tcf command.
This global log file can also be disabled by setting the Simulations Log Folder command to
“DO NOT USE”. This file is described in Section 14.4.2 .

@1891
14.4.1 Local .log File

The “\_ TUFLOW Simulations.log” file is a text file containing a record of every simulation initiated
from that folder, and is located in the same folder as the .tcf file(s). For the 2023-03 release,
information contained in the file includes the following:

Date and time of the log entry;

Dongle ID (if applicable);
Type of TUFLOW licence. The notation on the type of licence varies depending on the licence
origin as follows:
WIBU Licence:
LOC3/4 for a Local (Standalone) Licence (the numbers in this example indicate it
was the third licence out of four available).
NWK03/10 for a Network Licence (the numbers in this example indicate it was the
third licence out of ten available).
Jacobs (Flood Modeller) Software Licence:
“HalcS” for a local Standalone licence
“HalcN” for a network licence
XP-Software Licence:
“XP” for all types of licences.
A Tutorial Model (no dongle required):
“TUT” for all tutorial or demo models.
Computer Name on which the simulation is being run;
TUFLOW Build ID;

Section 14 Checks and Log Files - 8 / 33 Page 591 / 1094

 Time:
Clock time “CT” after initialisation;
Processor time “PT” after initialisation;
Clock time “CT” at end of simulation;
Processor time “PT” at end of simulation;
Note that the processor time is summed across all threads and includes GPU hardware.
If parallel processing is used in model initialisation or solver this number may be larger
than clock time.
Hardware type and number of processor used:
“CPUx1” for a model run using one CPU thread;
“GPUx1” for a model run using one GPU card;
Simulation status as one of the following:
“Started”;
“Finished”;
“Interrupted” (the simulation was stopped by pressing Ctrl+C);
UNSTABLE (the simulation became unstable based on the water level exceedance
checks).
Simulation name;
Performance for “Finished” or “Interrupted” simulations:
“HPC Solver Used” for models using the HPC Solver.
For models using the Classic Solver:
“fCME” is the Final Cumulative Mass Error at the end of the simulation.
“pCME” is the Peak CME throughout the whole simulation.
“pCME5” is the Peak CME for the period of the simulation that the flow in and out of
the model exceeds 5% of the peak flow in and out (this value generally excludes any
initial high ME values that may occur at the start of some simulations).
“pddV” is the Peak change in dV (change in volume) over one timestep divided by
the peak dV value expressed as a percentage.
“pddV5” is the same as pddV but over the period of the simulation where the flow in
and out of the model exceeds 5% of the peak flow in and out.
.tcf filename;
.tlf filepath.

It is strongly recommended that this file is not deleted or edited as it could provide a
valuable trace back to past simulations.

Excerpts from a local “\_ TUFLOW Simulations.log” file are shown below:

2024-May-30 13:46 Don: 00004465001 NWK 01/20 BMT-1 Build: 2023-03-AE-iSP-w64 Started: M05_

2024-May-30 13:47 Don: 00004465001 NWK 01/20 BMT-1 Build: 2023-03-AE-iSP-w64 Ini: 0:00:01

2024-May-30 13:47 Don: 00004465001 NWK 01/20 BMT-1 Build: 2023-03-AE-iSP-w64 Started: M05_

2024-May-30 13:47 Don: 00004465001 NWK 01/20 BMT-1 Build: 2023-03-AE-iSP-w64 Ini: 0:00:02

2024-May-30 13:47 Don: 00004465001 NWK 01/20 BMT-1 Build: 2023-03-AE-iSP-w64 Started: M05_

2024-May-30 13:48 Don: 00004465001 NWK 01/20 BMT-1 Build: 2023-03-AE-iSP-w64 Ini: 0:00:01

Section 14 Checks and Log Files - 9 / 33 Page 592 / 1094

 @1892
14.4.2 Global .log File

This file is named “\_ All TUFLOW Simulations.log” and by default is located in a folder called
“C:\ProgramData\TUFLOW\\log”.

The path to the global .log file can be changed using the following options:

For all types of licenses use the Simulations Log Folder command in the Dongle Control File
(see Section 13.5.1.2 ).
Alternatively, use Simulations Log Folder in the .tcf file (this option is given priority over the
option above).
For either of the options above, if the keywords “DO NOT USE” occur within the folder path or
URL name, writing to the global .log file is disabled.

The entries to the global .log file are as described for the local .log file above, but will be for all
simulations carried out across the organisation (provided they are all referencing the same folder).

@1893
14.5 Simulation Log Files

TUFLOW writes a number of files to a folder typically called the ‘log’ folder and contained within
the ‘TUFLOW\runs’. The location can be controlled using the Log Folder command. The files
written to this folder contain:

TUFLOW Log File (.tlf)

HPC TUFLOW Log File and HPC timestep history file (.hpc.tlf and .dt.csv)
TUFLOW Summary File (.tsf)
Simulation start statistics (start_stats.txt)
Simulation run statistics (run_stats.txt)
Messages (in both tabular and GIS format) (.csv and .gpkg/.shp/.mif)
GIS workspace (.qgs and .wor)

@1894
14.5.1 TLF

TUFLOW produces a log file (.tlf file) containing a record of the simulation. TUFLOW HPC also
produces a hpc.tlf file due to difficulties in coordinating CPU and GPU file writing processes - see
Section 14.5.1.1 . The file is very useful for establishing data input problems and identifying
instabilities.

Take time to familiarise yourself with the content of the log file. Much of it is a repeat of the
information displayed to the Console Window, so if you can’t access information from the Console
Window, check the log file using a text editor.

At key stages during the model development and application search the file for any “WARNING”,
“CHECK” or “NOTE” messages. “WARNING” messages in particular should be checked regularly.
An “ERROR” keyword indicates an unrecoverable error and causes the simulation to stop. As
many errors as possible are trapped before stopping.

An “XY:” at the beginning of a line indicates the error, warning, check or other message has also
been redirected to a geo-spatial layer (.gpkg, .shp or .mif) (see Section 14.5.5 ). Opening the
layer in the GIS often provides a far more rapid location of the message within the model

Section 14 Checks and Log Files - 10 / 33 Page 593 / 1094

 domain(s) than via other ways.

For more information on the .tlf, see the TUFLOW Wiki.

@1895
14.5.1.1 HPC TLF and DT

Two additional files are produced when using TUFLOW HPC, the hpc.tlf and hpc.dt.csv.

The .hpc.tlf log file records the model timestep, control numbers and volume of water in the model
at each timestep, as described in Section 14.2.2 . It also shows repeated timesteps if the control
number limits were exceeded or there is a significant change in control numbers (more than 20%).
Sometimes repeated timesteps are of no concern, such as when a direct rainfall model has a
sudden change in rainfall when transitioning through a rainfall histogram, or there is a warmup
period with small or no flow rate before a large inflow - the adaptive timestepping is simply
adjusting to the sudden change in flow conditions somewhere within the model. However, if there
is a high occurrence of repeating timesteps when the boundary inflows are smooth, this could be
an indicator of model instability and sensitivity tests reducing the timestepping intervals, using the
Control Number Factor command, carried out. The total number of repeated timesteps is also
recorded in the Simulation Summary of the .tlf file.

For more information on the hpc.tlf, see the TUFLOW Wiki.

The hpc.dt.csv output provides a timeseries of the model timestep and the value of each control
number at each timestep. The following columns are shown:

iStep: Timestep display frequency, as mentioned in Section 14.2 .

tEnd: Simulation time at the end of timestep.
dtStar: Desired timestep from the 2D component of the model.
dt: Actual timestep, can be affected by the 1D timestep and output frequency.
Nu: Courant Number.
Nc: Shallow Wave Celerity Number.
Nd: Diffusion Number.
Eff: Efficiency value that represents the ratio of actual 2D timestep (dt) to possible 2D
timestep (dtStar).

It is possible to view the minimum timestep (dt) in a map output format using Map Output Data
Types == dt to identify which part(s) of the model are controlling the timestepping. For more
information see the TUFLOW Wiki.

For more information of the hpc.dt.csv, see the TUFLOW Wiki.

@1896
14.5.2 TSF

A TUFLOW Summary File (.tsf file) is output to the same location as the .tlf file and provides a
more concise summary of the simulation. This file can also be regularly updated during a
simulation. By default, the summary output interval for a Classic model is set so there are 101
summary output values (for example, an interval of 180 seconds for a 5 hour model). For a HPC
model the summary output interval is set to the Mass Balance Output Interval . If no Mass
Balance Output Interval is specified, the lesser of the Map Output Interval and Time Series
Output Interval is used.

Features are:

Section 14 Checks and Log Files - 11 / 33 Page 594 / 1094

 The TSF Update Interval command can be used to control the interval in seconds to update
the .tsf file while a simulation is running.
The .tsf file has a TUFLOW control file style syntax and contains information on the solution
scheme, hardware, primary simulation inputs, the simulation status, mass balance outputs,
etc. Additional information will be added based on user feedback (please email
[email protected] if you have a suggestion).

The .tsf is updated as the model is running, users can open this file as the model is running to
check on key features and progress. Table 14.1 provides an example of a .tsf. What is written to
the .tsf is listed under ‘Column’ and then described under ‘Description’.

Section 14 Checks and Log Files - 12 / 33 Page 595 / 1094

 @1897 Table 14.1: TUFLOW Summary File Example

Column Description

TUFLOW Control File == File path of the TUFLOW Control File (.tcf), see Section
“D:_001.tcf” 4.2.4 .

TUFLOW Log File == File path of the TUFLOW Log File (.tlf), see Section
“D:_001.tlf” 14.5.1 .

TUFLOW Build == Build:

Name of the TUFLOW Build used, see Section 13.4.1 .
2023-03-AE-iSP-w64

Solution Scheme == HPC The Solution Scheme used. The options are TUFLOW
Classic, or TUFLOW HPC.

Hardware == GPU The Hardware used. The options are CPU or GPU, see
Chapter 12 .

GPU Device IDs == 0 The GPU Device IDs. If multiple GPUs are used, see
Section 12.4.4 , they will be listed here.

Computer Name == BMT-

The computer name that the simulation is running on.
WS2111

Simulation Status == Simulation status as one of the following:

FINISHED
“Started”;
“Finished”;
“Interrupted” (the simulation was stopped by pressing
Ctrl+C); or
UNSTABLE (the simulation became unstable based
on the water level exceedance checks).

Simulation Time (h) == Simulation time at time .tsf is opened (this updates as the
3. simulation progresses).

Simulation Start Time

Simulation Start Time.
(h) == 0.

Simulation End Time (h)

Simulation End Time.
== 3.

Percentage Complete (%)

Progress of the simulation at time .tsf is opened.
== 100

Completed Computational Number of completed computational steps at time .tsf is

Steps == 10769 opened.

CPU Time (h) == 0.002218 CPU Time at time .tsf is opened.

Clock Time (h) ==

Clock Time at time .tsf is opened.
0.006389

Approximate Clock Time

Approximate time remaining of simulation.
Remaining (h) == 0.

Section 14 Checks and Log Files - 13 / 33 Page 596 / 1094

 Column Description

TUFLOW 1D Negative Number of negative 1D depth reported at time .tsf is

Depths == 0 opened.

HPC HCN Repeated If using TUFLOW HPC, the number of repeated timesteps
Timesteps == 0 due to High Control Numbers (HCN) at time .tsf is
opened.

HPC NaN Repeated If using TUFLOW HPC, the number of repeated timesteps
Timesteps == 0 due to Not a Number (NaN) occurring at time .tsf is
opened.

HPC NaN WARNING 2550 == Number of WARNING 2550 reported at time of .tsf being
0 opened.

WARNINGs Prior to Number of WARNINGs prior to the simulation (i.e. during

Simulation == 1 initialisation phase).

WARNINGs During Number of WARNINGs during the simulation (i.e. as the

Simulation == 0 computations are happening).

CHECKs Prior to Number of CHECKs prior to the simulation (i.e. during

Simulation == 0 initialisation phase).

CHECKs During Simulation Number of CHECKs during the simulation (i.e. as the
== 0 computations are happening).

Volume at Start (m3) ==

Volume at the start of the model.
269

Volume at End (m3) ==

Volume at the end of the model.
3478

Total Volume In (m3) == The current amount of volume that has entered the
3472 model.

Total Volume Out (m3) ==

The current amount of volume that has left the model.
265

Volume Error (m3) == 2 The current volume error.

Volume Error (%) == 0.05 The current percent of volume error.

Cumulative Mass Error

The current cumulative mass error reported in the model.
[ME] (%) == 0.05

Summary Output Interval

The interval that the .tsf file is being updated.
(s) == 300.

Number Summary Values ==

The number of summary values written.
37

Volume In Values [Qi] ==

The volume in values for each interval.
0.0, …, 39.3

Section 14 Checks and Log Files - 14 / 33 Page 597 / 1094

 Column Description

Volume Out Values [Qo]

The volume out values for each interval.
== 0.0, …, 0.1

Change in Volume Values

The change in volume values for each interval.
[dV] == 0.0, …, 39.0

Mass Error Values [ME]

The mass error values for each interval.
(%) == 0.0, …, 0.1

Number TUFLOW 1D Nodes The number of 1D nodes within the model, see Section
== 0 5.2 .

Number TUFLOW 1D The number of 1D channels within the model, see Section
Channels == 0 5.2 .

Active 2D Cells == 20611 The number of active 2D cells. Typically set using a
2d_code polygon with attribute of ‘1’, see Section 7.3.1 .

Total 2D Cells == 34000 The number of cells within the 2D domain, see Section
7.3.1 .

Inactive 2D Cells == The number of inactive 2D cells (i.e. the total cells minus
13389 the active cells).

Number 2D Domains == 1 The number of 2D domains. This will be one unless using
the M2D functionality, see Section 10.7.2 .

2D Domain Cell Sizes ==

The 2D domain cell size used, see Section 7.3.1 .
5.

2D Domain Timestep == The 2D timestep. When using HPC this is a variable

0.500 ! Variable timestep and users should refer to the hpc.dt.csv , see
Section 14.5.1.1 .

First Start Map Output

Time of the first map output.
(h) == 0.

Shortest Map Output

The time of the shortest Map Output Interval .
Interval (s) == 300.

@1898
14.5.3 Start Stats

A simulation start stats file (\<simulation_name>\_start_stats.txt) is output to the same location as

the .tlf file. This file contains information on the total time and the time elapsed for each stage of
model initialisation. This can be used to identify the stages causing slow simulation start-up, and
allows the TUFLOW development team to prioritise development tasks to remove bottlenecks in
the start-up through the use of XF files and other enhancements. If you have a problematic (slow
starting) model, please email the _start_stats.txt and corresponding .tlf file through to
[email protected].

Section 14 Checks and Log Files - 15 / 33 Page 598 / 1094

 @1899
14.5.4 Run Stats

A simulation run stats file (\<simulation_name>\_run_stats.txt) is also output to the same location
as the .tlf file. This file contains the amount of time that TUFLOW spends in the 1D and 2D
computations. At each mass balance output interval, the percentage of the total computational
effort that TUFLOW has spent in 1D calculations, 2D calculations and other is output to the
run_stats file. The “other” column includes a variety of tasks that are neither 1D or 2D
computations, such as writing of outputs, and transfer of data to GPU (if running on GPU devices).
The “other” column also includes time spent within an external 1D solver.

@1900
14.5.5 Messages

Error, warning, check and other useful messages that are output to the Console Window and log
file are also output to a .csv file and geo-spatial layer (e.g. .gpkg, .shp or .mif depending of the
GIS format set in the model). Messages output to the geo-spatial layer are those that can be
geographically located within the model domains. These messages layers are output in the Log
Folder .

The three levels of messages generated in increasing order of severity are:

CHECK: A check indicates that something unusual occurred and may, for example, indicate
erroroneous data. For example a breakline failed to modify any cell elevations (CHECK 2079).
WARNING: A warning is more severe than a check message, but the simulation will still
progress. For example, a Manning’s n value of 0.001 would be considered outside typical
industry ranges and will trigger WARNING 2218.
ERROR: An error indicates that the simulation is unable to continue. For example, if no active
cell is found within a source area boundary an ERROR 2014 will occur and the simulation will
terminate.

This feature allows rapid identification of the error location within the GIS environment of
data input errors and simulation instabilities and potential problems. Using this feature can
save considerable time when setting up and checking new models.

Of note is that some messages can be changed from their default setting in situations where the
modeller has determined that the message level does not need to be enforced, or enforced to a
higher level.

A message numbering system has been adopted, prefixing all warnings with a four digit number.
These numbers may be used to cross-reference the warning with a message database that is
stored on the TUFLOW Wiki. The database contains detailed information on the CHECK,
WARNING or ERROR to help check/resolve the issue. Each message falls into one of the
following message categories:

0xxx warning messages refer to errors that occur in neither the 1D or 2D domains.
1xxx warning messages refer to errors that occur in the 1D domains.
2xxx warning messages refer to errors that occur in the 2D domains.
3xxx warning messages refer to errors that are unique to TUFLOW HPC.
4xxx warning messages refer to errors that are unique to Advection Dispersion module.
6xxx warning messages refer to errors that occur in the EPA SWMM 1D domain.

Section 14 Checks and Log Files - 16 / 33 Page 599 / 1094

 As of the QGIS TUFLOW Plugin Version 3.9, it is possible to filter messages by code ID, as shown
in Figure 14.3 . For more information see the QGIS TUFLOW Plugin Changelog.

@1901

Figure 14.3: Filter by Code Number

@1902
14.5.6 GIS Workspaces

A QGIS workspace (.qgs) and MapInfo workspace (.wor) is automatically created for every
simulation. They are named <tcf_filename>.qgs / .wor and are written to the same folder as the .tlf
file. The workspace contains all GIS layers used as input to the simulation, and is an excellent way
of ascertaining the GIS layers used to set up a model, particularly large models with many GIS
inputs, or those with multiple events or scenarios.

Opening the .qgs file in QGIS will open all GIS input and output check layers (.gpkg, .shp and/or
.mif). Note that the visibilities of the output layers are unchecked so that the display time is quick.

The .wor file, when opened in MapInfo, simply opens the .tab layers. No Map or Browser windows
are automatically opened. If the simulated model contains any other vector formats (e.g. .gpkg or
.shp files), these are not opened.

For ArcMap users, the .mxd files cannot be directly written by TUFLOW, as the format is
proprietary. However, the ArcTUFLOW Toolbox can be used to load the simulation input files into
ArcMap.

@1903
14.6 1D Output File

The .eof file is both a summary file for the 1D, as well as a results file. It contains the 1D domain
input datasets, including a complete output of the final input data before the simulation
commences. For example, if a second table overwrites a channel cross-section properties table
during the input process, the table in the .eof file relates to the second table. Similarly,

Section 14 Checks and Log Files - 17 / 33 Page 600 / 1094

 adjustments to data, for example, a datum shift in a gradient channel’s cross-section based on the
upstream and downstream inverts, are also incorporated. Therefore, the .eof file contains the final
dataset that is used by the simulation.

By default the .eof file also contains a result summary of the simulation, including useful
information such as culvert flow regimes at each output time, time of maximum water level, etc.
The channel and node regime flags are located in the two spaces after the velocity, flow and head
values in the time based output. The flags, described in Table 14.2 , are useful for interrogating
the hydraulic regime at nodes and channels. The writing of the outputs in the .eof file can be
suppressed by the Output Files Exclude == EOF command in the .tcf file.

Section 14 Checks and Log Files - 18 / 33 Page 601 / 1094

 @1904 Table 14.2: Channel and Node Flow Regime Flags (.eof File)

Flag
Flag
(Space Description
(Space 2)
1)

The depth at a node fell below -0.1m. A WARNING is also output to

the _messages GIS layer (see Section 14.5.5 . The occurrence of
*
significant negative depths may cause mass conservation errors in
the 1D domain.

One end of a normal channel is close to being dry and a

*
transitioning algorithm was used to dry/wet the channel.

The gradient channel algorithm was applied. This occurs when one
end of the channel is either dry or very shallow. The gradient
# channel algorithm applies a weir equation at the dry or shallow end
in combination with the momentum equation by adjusting the water
surface slope along the channel.

A Adverse flow (i.e. flow gradient is against the slope of the channel).

Upstream controlled friction flow occurred in a Steep (S) channel

D
when the downstream end was dry.

Upstream controlled friction flow occurred in a Steep (S) channel

S
with a Froude Number greater than one (1).

Upstream controlled friction flow occurred in a Steep (S) channel

T with a Froude Number between 0.5 and one (1). T stands for
Transitioning from normal flow to upstream controlled friction flow.

Upstream controlled friction flow occurred in a Steep (S) channel

with a Froude Number less than 0.5. N stands for normal flow,
however, in this case the upstream controlled friction flow approach
N
was adopted. This may occur during the transitioning of flow from
downstream controlled to upstream controlled. If it occurs
repetitively, the configuration of the channel should be reviewed.

Culvert
Flow The culvert flow regime flag as documented in Table 5.6 . Culvert
Regime channels only.
Flags

The channel or node is empty or dry (i.e. the head or water level is
E
at the bottom of the node). E stands for Empty.

The head exceeds the top of the nodes elevation versus surface
F
area table (NA table). F stands for Full.

The head at the mid-point of the channel exceeds the top of the
F
channel’s hydraulics properties table (CS table). F stands for Full.

Section 14 Checks and Log Files - 19 / 33 Page 602 / 1094

 Flag
Flag
(Space Description
(Space 2)
1)

The velocity rate limit was applied to the channel to try and prevent
L oscillations or instabilities – non-inertial channels (structures) only.
See Vel Rate Limit.

The uni-directional flag assigned to the channel was invoked and

U
the velocity/flow was set to zero.

For a Sluice Gate type channel, the flow is not in contact with the
W sluice gate and the channel has reverted to Weir or Rectangular
channel flow as outlined in Section 5.10.5 .

@1905
14.7 Check Files

When the command Write Check Files is specified in the .tcf file and/or .ecf file a number of
various 2D, 1D, 1D/2D and 2D/2D check files can be output. At key stages in a model’s
development, produce these check files, and check their contents to ensure that the input data are
as expected. Note that a number of the check files listed below are only output when the
corresponding feature has been used in the simulated model. The attributes of some check files
(like that of the _grd_check) may vary depending on the feature used within the model.

Table 14.3 lists the various 2D, 1D, 1D/2D and 2D/2D check files that are available to be output.
Links are provided to the TUFLOW Wiki which contains detailed descriptions of the files.

Many of the GIS check layers output by TUFLOW may be mapped within GIS to provide a visual
representation of how the input data has been interpreted by the model. This often makes it easier
and quicker to review a certain aspect of the model rather than individually viewing the attributes
of each GIS check layer.

For example, using the styling functionality (thematic mapping) of GIS software, the user could:

View the spatial distribution of the Soil Infiltration layer (attribute in _grd_check layer).
View the conveyance of 1D channel layers (attribute in _hydroprop_check layer).

Examples of viewing these check files for different GIS packages are provided via the links below
to the TUFLOW Wiki:

QGIS Thematic Mapping

MapInfo Thematic Mapping
ArcMap Thematic Mapping

Tip: the QGIS TUFLOW Plugin and ArcGIS Toolbox contain an ‘Apply TUFLOW Styles to Open
Layers’ tool. This tool automatically styles inputs and outputs, including check layers, greatly
enhancing the visual interpretation of the geo-spatial data.

Section 14 Checks and Log Files - 20 / 33 Page 603 / 1094

 @1906 Table 14.3: Types of Check Files

1D/2D Check 2D/2D Check

2D Check Files 1D Check Files
Files Files

_2d_bc_tables_check _1d_bc_tables_check _x1D_H_to_2D _2d_to_2d_check

_ad_check _1d_pit_inlet_tables_check _x1D_H_from_2D

_bg_uvpt_check _1d_ta_tables_check _2D_Q_to_x1D

_bcc_check _Str_Grp_All _2D_Q_from_x1D

_DEM_M _Str_Grp_Multi _1d_to_2d_check

_DEM_Z _1d_bc_check

_DEM_Zmin _hydroprop_check

_DEM_Z_HR _inverts_check

_dom_check _iwl_check

_fc_check _mhc_check

_fcsh_uvpt_check _nwk_C_check

_glo_check _nwk_N_check

_grd_check _pit_A_check

_input_layers _WLLo_check

_lfcsh_uvpt_check _xWLLo_check

_lp_check _WLLp_check

_po_check _xWLLp_check

_sac_check _xsl_check

_sh_obj_check _x1d_chans_check

_uvpt_check _x1d_nodes_check

_vzsh_check

_zln_zpt_check

_zpt_check

_zsh_zpt_check

@1907
14.8 Mass Balance Output

Mass balance information for TUFLOW Classic or HPC, and TUFLOW 1D (ESTRY), is generated
by setting Mass Balance Output to ON (the default). Due to the different mathematics employed
for the two 2D solvers, the information produced varies between Classic and HPC.

Section 14 Checks and Log Files - 21 / 33 Page 604 / 1094

 @1908
14.8.1 Mass Balance Definitions

TUFLOW reports the “Volume at Start” and “Volume at End” for a simulation in the .tlf (Section
14.5.1 ). These are instantaneous spatial integrals of surface water (not ground water) across
both 1D and 2D domains. “Volume at End” should be the “Volume at Start” plus the time integral of
“Volume In”, less the time integral of “Volume Out”. However, “Volume In” and “Volume Out” are
not as simple as they sound. These are defined as:

Volume In:

2D integral of “Sink-Source” over cells where it is positive.

2D edge inflows (QT, HT, HQ) on cells where the flow is entering the domain.
2D integral of groundwater recharge to surface.
1D node inflows.

Volume Out:

(negative of) 2D integral of “Sink-Source” over cells where it is negative.

2D edge outflows (QT, HT, HQ) on cells where the flow is leaving the domain.
1D node outflows.

Sink-Source is defined on a cell by cell basis as the “vertical” movement of water:

(add) RF rainfall (negative RF is included only if cell is wet).

(add) SA source-area (negative SA is included only if cell is wet).
(subtract) material losses.
(subtract) infiltration losses.

Note that Sink-Source can be negative, in particular when the rain has stopped but water is still
infiltrating into the ground. Importantly, infiltration losses under rainfall cause the “Volume In” to be
less than the simple area integral of rainfall, rather than showing as “Volume Out”.

@1909
14.8.2 TUFLOW 1D Mass Balance

For simulations with a TUFLOW 1D (ESTRY) component, if Mass Balance Output is ON the
following mass balance output is available for 1D:

As discussed in Section 14.2.1 the cumulative mass error percentage appears as three
numbers after the letters “CE” in the Console Window. This data is also output to the .tlf file
(Section 14.5.1 ). The first percentage is the overall model (all 1D and 2D domains) and the
second is for all of the TUFLOW 1D domains (the third discussed in Section 14.8.3 ) (see the
description of the “Cum ME (%)” column in Table 14.4 and Table 14.5 ). Monitoring these
numbers is important so as to establish the “health” of the model, as discussed in Section
16.1 . Ideally all these percentages should be within ±1%. Much higher numbers may occur
at the start of a simulation, especially if there are 2D domain(s) rapidly wetting. This should
not be an issue provided the model quickly settles down and the CE percentages fall within
acceptable amounts.
The _MB1D.csv file contains mass balance reporting for all the 1D (ESTRY) domains (see
Table 14.5 ). It is written to the .ecf Output Folder .
Time based 1D mass error is output as a GIS layer to a _TSMB_P.shp layer (see Table 14.7
for a description of the attributes). Using GIS thematic mapping of the ME_Avg_Abs attribute

Section 14 Checks and Log Files - 22 / 33 Page 605 / 1094

 is a powerful way of identifying any problematic 1D nodes.
Time based mass error reporting across 1D/2D HX links is output as a GIS _TSMB1d2d layer.
Note, when viewing this layer that each 1D node point object is connected to a collection of
2D cell objects that make one overall GIS object (called a Collection). This layer is also useful
for identifying which 2D cells are connected to a 1D node for the 2D HX links. See Table 14.8
for a description of the attributes. Using GIS thematic mapping of the ME_Avg_Abs attribute
is a powerful way of identifying any problematic 2D HX links.

@1910
14.8.3 TUFLOW Classic Mass Balance

For TUFLOW Classic simulations, if Mass Balance Output is ON the following mass balance
output is available:

As discussed in Section 14.2.1 the cumulative mass error percentage appears as three
numbers after the letters “CE” in the Console Window. This data is also output to the .tlf file
(Section 14.5.1 ). The first percentage is the overall model (all 1D and 2D domains), the
second is for all of the TUFLOW 1D domains and the third for all of the 2D domains (see the
description of the “Cum ME (%)” column in Table 14.4 , Table 14.5 and Table 14.6 .
Monitoring these numbers is important so as to establish the “health” of the model, as
discussed in Section 16.1 . Ideally all these percentages should be within ±1%. Much higher
numbers may occur at the start of a simulation, especially if there are 2D domain(s) rapidly
wetting. This should not be an issue provided the model quickly settles down and the CE
percentages fall within acceptable amounts.
Two _MB.csv files are output by TUFLOW reporting on the various inflows and outflows,
volume, predicted volume error and the mass and cumulative mass errors as a percentage as
follows:
The _MB.csv file is for the overall model (all 1D and 2D domains) (see Table 14.4 ). It is
written to the .tcf Output Folder .
The _MB2D.csv file contains mass balance reporting for all 2D domains together and for
each individual 2D domain if using Classic’s Multiple 2D Domain feature (see Table 14.6
). The _MB2D.csv is written to the .tcf Output Folder . These files also report inflows and
outflows across HX and SX connections for 1D/2D links between TUFLOW’s 1D scheme
(ESTRY) and other external 1D schemes (e.g. FloodModeller or SWMM). The overall
mass balance reported does not include flows in any external 1D scheme, but does
include flows across links to an external 1D scheme.
Map output of the 2D mass error can be output by specifying the MB1 and/or MB2 option for
Map Output Data Types . Both MB1 and MB2 outputs are a measure of the convergence
level of the solution. The measure is a cumulative value since the last output time, therefore is
an effective way of identifying problem areas in a model that repeatedly have poor
convergence and most likely mass error. The MB1 output is accumulated since the previous
output time and the MB2 output is accumulated over the entire simulation.

It is possible to specify different time intervals for the display on the screen and the _MB.csv
output files. The .tcf command Mass Balance Output Interval is used for setting the interval in the
_MB.csv files.

A summary of key model performance indicators is also reported at the end of the simulation in the
Console Window and .tlf file (see Section 16.2.3 ).

Section 14 Checks and Log Files - 23 / 33 Page 606 / 1094

 Healthy TUFLOW Classic models fall within ±1% cumulative mass error (see Section 16.1 for
discussion on “unhealthy” models). If a model experiences higher mass errors this may be due to
the following:

Poor numerical convergence due to using too large a timestep and/or areas of the model are
slightly unstable (major instabilities will generate warnings and eventually an error).
Models with significant areas of complex hydraulics, or steep and very shallow flows when
using the direct rainfall approach (Read GIS RF ). These models should be tested using
double precision versions of TUFLOW Classic (see Section 13.4.2 ). This scenario may also
require the default wet/dry depth (Cell Wet/Dry Depth ) to be reduced to minimise mass
errors that can arise from cells frequently wetting and drying with larger wet/dry depths.
Poorly configured 1D/2D or 2D boundaries that are causing oscillations to occur.
High frequency of repeated wetting and drying.
Models located at high elevations above sea level, especially if the inflows are relatively small
or direct rainfall is applied. These models should be run using double precision versions of
TUFLOW Classic (see Section 13.4.2 ). There are no fixed guidelines for when to switch to
double precision, other than to carry out sensitivity tests using single and double precision
versions (as a general rule for Classic, not HPC, all direct rainfall models and models with
elevations greater than 100 to 1,000m usually require or will benefit from using double
precision).
1D nodes that are frequently drying (undershooting), or are being limited if Head Rate Limit
is being used (not recommended) can result in mass errors. The _TSMB and _TSMB1d2d
GIS layers are useful for reviewing 1D mass error. These files report the mass error values as
a flow rate (m3/s) so that they can be compared with the total flow through the model at that
location (i.e. a mass error of 1m3/s at a node where 1,000m3/s is passing through is not an
issue, while it would be if only 2m3/s was passing through the node).
Note that the calculation of mass errors will not detect errors in the model flow boundary
inputs. It is recommended that conventional mass balance checks be carried out (irrespective
of the software used) as a matter of course as a cross-check that the correct amount of water
is entering and leaving the model (see Section 16.4 ).

Section 14 Checks and Log Files - 24 / 33 Page 607 / 1094

 @1911 Table 14.4: MB.csv File Columns

Column Description

Time (h) The simulation time in hours.

The volume of water in m3 flowing into the model across water level (HQ, HS, HT)
H Vol In
boundaries since the previous time.

H Vol The volume of water in m3 flowing out of the model across water level (HQ, HS,
Out HT) boundaries since the previous time.

The volume of water in m3 flowing into the model from flow (QH, QS, QT, RF, SA,
Q Vol In
ST) boundaries since the previous time.

Q Vol The volume of water in m3 flowing out of the model across flow (QH, QS, QT, RF,
Out SA, ST) boundaries since the previous time.

Tot Vol
The total volume of water entering the model since the previous time in m3.
In

Tot Vol
The total volume of water leaving the model since the previous time in m3.
Out

“Tot Vol In” minus “Tot Vol Out” (i.e. the net volume of water in m3 entering the
Vol I-O
model since the previous time).

dVol The change in the model’s volume since the previous time in m3.

“dVol” minus “Vol I-O” (i.e. the volume error or amount of water in m3 unaccounted
Vol Err for since the previous time). A positive value indicates the solution may have
gained mass, while a negative value indicates a possible mass loss.

(“Vol Err”/“Vol I+O”)*100 (i.e. the percentage mass error based on the volume of
water flowing through the model since the previous time). This figure can be large
Q ME at the start of a simulation if there are 2D cells rapidly wetting and the flow through
(%) the model (“Vol I+O”) is relatively small. This is a characteristic of 2D domains,
particularly when using the direct rainfall approach. If “Vol I+O” is less than 1m3,
“Q ME (%)” is set to zero to avoid divide by zero calculations.

“Tot Vol In” + “Tot Vol Out” (i.e. the volume of water in m3 entering and leaving the
Vol I+O
model since the previous time).

Tot Vol The total volume of water in the model in m3.

Cum Vol The cumulative volume of water entering and leaving the model in m3 (i.e. the
I+O cumulative total of “Vol I+O”).

Cum Vol
The cumulative volume error in m3 (i.e. the cumulative total of “Vol Err”).
Err

Section 14 Checks and Log Files - 25 / 33 Page 608 / 1094

 Column Description

(“Cum Vol Err”/max(“Tot Vol” and “Cum Vol I+O”))*100 (i.e. the percentage mass
error based on the maximum of the volume of water that has flowed through the
model and total volume of water in the model). This figure can be large at the start
of a simulation if there are 2D cells rapidly wetting and the flow through the model
Cum ME (“Cum Vol I+O”) is relatively small. This is a particular characteristic of steep
(%) models, particularly when using the direct rainfall approach. This figure can also
be misleadingly low if the model has a very large volume of “stagnant” water such
as a lake or part of the ocean. If max (“Tot Vol” and “Cum Vol I+O”) is less than
1m3, “Cum ME (%)” is set to zero to avoid divide by zero calculations. This figure
is the first number displayed after “CE” on the Console Window.

(“Cum Vol Err”/“Cum Vol I+O”)*100 (i.e. the percentage mass error based on the
cumulative volume of water that has flowed through the model). This figure can be
large at the start of a simulation if there are 2D cells rapidly wetting and the flow
Cum Q
through the model (“Cum Vol I+O”) is relatively small. This is a particular
ME (%)
characteristic of steep models, particularly when using the direct rainfall approach.
If “Cum Vol I+O” is less than 1m3, “Cum Q ME (%)” is set to zero to avoid divide
by zero calculations.

Section 14 Checks and Log Files - 26 / 33 Page 609 / 1094

 @1912 Table 14.5: MB1D.csv File Columns

Column Description

Time (h) The simulation time in hours.

The volume of water in m3 flowing into all 1D domains at 1D water level (HQ, HS,
H V In
HT) boundaries since the previous time.

The volume of water in m3 flowing out of all 1D domains at 1D water level (HQ,
H V Out
HS, HT) boundaries since the previous time.

SX2D V The volume of water in m3 flowing into all 1D domains from 2D SX links since the
In previous time.

SX2D V The volume of water in m3 flowing out of all 1D domains from 2D SX links since
Out the previous time.

The volume of water in m3 flowing into all 1D domains from 1D flow (QH, QS, QT)
Q V In
boundaries, except for 1D QT Regions, since the previous time.

The volume of water in m3 flowing out of all 1D domains from 1D flow (QH, QS,
Q V Out
QT) boundaries, except for 1D QT Regions since the previous time.

The volume of water in m3 flowing into all 1D domains from 1D QT Region flow
QR V In
boundaries, since the previous time.

QR V The volume of water in m3 flowing out of all 1D domains from 1D QT Region flow
Out boundaries, since the previous time.

Q2D V The volume of water in m3 flowing into hidden 1D nodes from 2D QT flow
In boundaries, since the previous time.

Q2D V The volume of water in m3 flowing out of hidden 1D nodes from 2D QT flow
Out boundaries, since the previous time.

HX2D V The volume of water in m3 flowing into all 1D domains across 2D HX links since
In the previous time.

HX2D V The volume of water in m3 flowing out of all 1D domains across 2D HX links since
Out the previous time.

Vol In- Sum of all the volumes in less the sum of all the volumes out (i.e. the net volume
Out of water in m3 entering all the 1D domains since the previous time).

dVol The change in the 1D domains’ volume in m3 since the previous time.

“dVol” minus “Vol In-Out” (i.e. the volume error or amount of water in m3
unaccounted for since the previous time). A positive value indicates the 1D
Vol Err
domains may have gained mass, while a negative value indicates a possible
mass loss.

(“Vol Err”/(ΣV In + ΣV Out))*100 (i.e. the percentage mass error based on the
Q ME volume of water flowing through the 1D domains since the previous time). If (ΣV
(%) In + ΣV Out) is less than 1m3, “Q ME (%)” is set to zero to avoid divide by zero
calculations.

Total Vol The total volume of water in m3 in the 1D domains.

Section 14 Checks and Log Files - 27 / 33 Page 610 / 1094

 Column Description

Cum Vol The cumulative volume of water in m3 entering and leaving the 1D domains
In+Out (i.e. the cumulative total of (ΣV In + ΣV Out)).

Cum Vol
The cumulative volume error in m3 (i.e. the cumulative total of “Vol Err”).
Error

(“Cum Vol Error”/max(“Cum Vol In+Out” and “Total Vol”))*100 (i.e. the percentage
mass error based on the maximum of the volume of water that has flowed through
the 1D domains and the total volume of water in the 1D domains). This figure can
Cum ME be misleadingly low if the 1D domains have a very large volume of “stagnant”
(%) water such as from lakes or part of the ocean. If max (“Cum Vol In+Out” and
“Total Vol”) is less than 1 m3, “Cum ME (%)” is set to zero to avoid divide by zero
calculations. This figure is the second number displayed after “CE” on the
Console Window.

(“Cum Vol Error”/“Cum Vol In+Out”)*100 (i.e. the percentage mass error based on
Cum Q the volume of water that has flowed through the 1D domains). If “Cum Vol In+Out”
ME (%) is less than 1 m3, “Cum Q ME (%)” is set to zero to avoid divide by zero
calculations.

Section 14 Checks and Log Files - 28 / 33 Page 611 / 1094

 @1913 Table 14.6: MB2D.csv File Columns

Column Description

Time (h) The simulation time in hours.

The volume of water in m3 flowing into the 2D domain/s at 2D water level (HQ,
H V In
HS, HT) boundaries since the previous time.

The volume of water in m3 flowing out of the 2D domain/s at 2D water level (HQ,
H V Out
HS, HT) boundaries since the previous time.

The volume of water in m3 flowing into the 2D domain/s across HX links to

Es HX V TUFLOW 1D (ESTRY) domains since the previous time. Note, this figure includes
In any 2D QT boundaries and 2D links as these become HX links connected to
hidden 1D nodes.

The volume of water in m3 flowing out of the 2D domain/s across HX links to

Es HX V TUFLOW 1D (ESTRY) domains since the previous time. Note, this figure includes
Out any 2D QT boundaries and 2D links as these become HX links connected to
hidden 1D nodes.

x1D HX The volume of water in m3 flowing into the 2D domain/s across HX links to an
V In external 1D scheme since the previous time.

x1D HX The volume of water in m3 flowing out of the 2D domain/s across HX links to an
V Out external 1D scheme since the previous time.

The volume of water in m3 flowing into the 2D domain/s from 2D flow sources (RF,
SS V In
SA, SH, ST) boundaries since the previous time.

SS V The volume of water in m3 flowing out of the 2D domain/s from 2D flow sources
Out (RF, SA, SH, ST) boundaries since the previous time.

Es SX V The volume of water in m3 flowing into the 2D domain/s through SX links to

In TUFLOW 1D (ESTRY) domains since the previous time.

Es SX V The volume of water in m3 flowing out of the 2D domain/s through SX links to

Out TUFLOW 1D (ESTRY) domains since the previous time.

x1D SX The volume of water in m3 flowing into the 2D domain/s through SX links to an
V In external 1D scheme since the previous time.

x1D SX The volume of water in m3 flowing out of the 2D domain/s through SX links to an
V Out external 1D scheme since the previous time.

Sum of all the volumes in less the sum of all the volumes out (i.e. the net volume
V In-Out
of water in m3 entering the 2D domain/s since the previous time).

dVol The change in the 2D domain/s’ volume in m3 since the previous time.

“dVol” minus “V In-Out” (i.e. the volume error or amount of water in m3

unaccounted for since the previous time). A positive value indicates the 2D
V Err
domain/s may have gained mass, while a negative value indicates a possible
mass loss.

Section 14 Checks and Log Files - 29 / 33 Page 612 / 1094

 Column Description

(“V Err”/(ΣV In + ΣV Out))*100 (i.e. the percentage mass error based on the
volume of water flowing through the 2D domain/s since the previous time). This
figure can be large at the start of a simulation if the 2D domain/s are rapidly
Q ME
wetting and the flow through the 2D domain/s is relatively small. This is a
(%)
particular characteristic of steep 2D domains, particularly when using the direct
rainfall approach. If (ΣV In + ΣV Out) is less than 1m3, “Q ME (%)” is set to zero to
avoid divide by zero calculations.

Total V The total volume of water in m3 in the 2D domain/s.

Cum V The cumulative volume of water in m3 entering and leaving the 2D domain/s
In+Out (i.e. the cumulative total of (ΣV In + ΣV Out)).

Cum V
The cumulative volume error in m3 (i.e. the cumulative total of “V Err”).
Error

(“Cum V Error”/max(“Cum V In+Out” and “Total V”))*100 (i.e. the percentage mass
error based on the maximum of the volume of water that has flowed through the
2D domain/s and the total volume of water in the 2D domain/s). This figure can be
large at the start of a simulation if the 2D domain/s are rapidly wetting and the flow
through the 2D domain/s is relatively small. This is a particular characteristic of
Cum ME
steep 2D domains, particularly when using the direct rainfall approach with builds
(%)
prior to Build 2008‑08‑AA. This figure can also be misleading low if the 2D
domain/s have a very large volume of “stagnant” water such as from lakes or part
of the ocean. If max (“Cum V In+Out” and “Total V”) is less than 1m3, “Cum ME
(%)” is set to zero to avoid divide by zero calculations. This figure is the third
number displayed after “CE” on the Console Window.

(“Cum V Error”/“Cum V In+Out”)*100, ie. the percentage mass error based on the
cumulative volume of water that has flowed through the 2D domain/s. This figure
can be large at the start of a simulation if the 2D domain/s are rapidly wetting and
Cum Q
the flow through the 2D domain/s is relatively small. This is a particular
ME (%)
characteristic of steep 2D domains, particularly when using the direct rainfall
approach. If “Cum V In+Out” is less than 1m3, “Cum Q ME (%)” is set to zero to
avoid divide by zero calculations.

Section 14 Checks and Log Files - 30 / 33 Page 613 / 1094

 @1914 Table 14.7: TSMB GIS Layer Attributes

Column Description

ID ID of the 1D node.

The average of the absolute mass errors throughout the simulation. This is
an excellent attribute for identifying 1D nodes that are regularly “bouncing”.
By using the average of the absolute values, rather than the ME_Avg
attribute below, any nodes that are bouncing either side of zero mass error
ME_Avg_Abs
will be identified. The best approach to identify these nodes is to using GIS
thematic mapping tools to show, for example, large circles around nodes
with high ME_Avg_Abs values down to small or no circle around nodes with
zero ME_Avg_Abs values. The units are in m3/s.

ME_Peak_m3s The peak (positive or negative) mass error in m3/s.

ME_Avg The average mass error in m3/s.

Not_used This attribute is not yet used.

t____ The mass error in m3/s at time t____ hours.

@1915 Table 14.8: TSMB1d2d GIS Layer Attributes

Column Description

ID of the 1D node. The object appears as a 1D point for the node

ID collectively combined with the 2D cells connected to that 1D node via the
2D HX link.

The average of the absolute mass errors throughout the simulation. This is
an excellent attribute for identifying HX links that have poor mass error or
are “bouncing”. By using the average of the absolute values, rather than the
ME_Avg_Abs ME_Avg attribute below, any HX links that are bouncing either side of zero
mass error will be identified. The best approach to identify these links is to
use GIS thematic mapping tools to differentiate the object display based on
the ME_Avg_Abs values. The units are in m3/s.

ME_Peak_m3s The peak (positive or negative) mass error in m3/s.

ME_Avg The average mass error in m3/s.

Not_used This attribute is not yet used.

t____ The mass error across the 2D HX link in m3/s at time t____ hours.

@1916
14.8.4 TUFLOW HPC Mass Balance

TUFLOW HPC writes the _MB_HPC.csv instead of the _MB2D.csv. The file contains mass
balance tracking of volumes of water in and out, mass error calculations and other information
(see Table 14.9 ). The HPC scheme, being a finite volume scheme, is mathematically volume
conservative. However, small mass errors may arise due to rounding errors in the summation of
fluxes around the cell faces. These mass errors are real but very small - they are a direct function
of the numerical precision used. Further, the summation process for computing the total volume in

Section 14 Checks and Log Files - 31 / 33 Page 614 / 1094

 the domain is also subject to rounding errors. These errors are not real but may show as a very
slight jitter in the summation result from timestep to timestep. Note that single precision
computations use approximately 8 significant figures, and double precision computations use
approximately 16 significant figures.

Unlike Classic, the HPC scheme does not provide a 2D map output of estimated mass error as
this is essentially always zero due to the finite volume scheme formulation. However, a running
estimate of domain integrated mass error is computed considering all inflows and outflows and the
running surface water volume integral. These metrics are written to the _MB_HPC.csv file in the
.tcf Output Folder .

Section 14 Checks and Log Files - 32 / 33 Page 615 / 1094

 @1917 Table 14.9: MB_HPC.csv File Columns

Column Description

Time (h) Simulation time in hours.

iStep Number of computational steps.

Number of repeated timesteps due to Not a Number (NaN) occurring. A NaN

nRS_NaNs occurs when the solution becomes unstable causing a divide by zero or other
undefined calculation forcing a lowering and repeat of the timestep.

Number of repeated timesteps due to High Control Numbers (HCN). A HCN

nRS_HCNs means that one of the three stability criteria was exceeded by more than 20%
forcing a lowering and repeat of the timestep.

The target timestep (ie. the preferred timestep) calculated from the stability
criteria. A lower timestep may have been used if approaching a times series or
dtTarget
map output time, as HPC will reduce the timestep so that the solution
timestepping coincides with the output time.

tLastMax Time of the last recorded maximum water level.

H Vol In Volume in since the previous time via 2D H boundaries (HQ, HT).

H Vol Out Volume out since the previous time via 2D H boundaries (HQ, HT).

Volume in since the previous time from 2D source boundaries (RF, SA, ST,
S/RF Vol In
subsurface water return, infiltration).

S/RF Vol Volume out since the previous time from 2D source boundaries (RF, SA, ST,
Out infiltration).

HX Vol In Volume in since the previous time via 2D HX boundaries.

HX Vol Out Volume out since the previous time via 2D HX boundaries.

SX Vol In Volume in since the previous time via 2D SX boundaries.

SX Vol Out Volume out since the previous time via 2D SX boundaries.

V In-Out Volume In less Volume Out of 2D domain.

dVol Change in total volume of water within 2D domain.

V Err “dVol” less “V In-Out”.

Total V Total volume of water in 2D domain.

Q ME% Mass error expressed as a percentage of “V Err”/(Vin + Vout).

Section 14 Checks and Log Files - 33 / 33 Page 616 / 1094

 @1922

@1923
Section 15 Viewing Outputs

@1924
15.1 Introduction

This chapter provides guidance on viewing and processing TUFLOW output. For guidance on
customising outputs, see Chapter 11 . The fundamental software necessary for viewing results is
discussed in Section 2.2 . The recommended software for viewing TUFLOW results, due to the
TUFLOW Viewer contained within the QGIS TUFLOW Plugin, is QGIS. This chapter is based on
using QGIS as the viewing platform. It describes the following:

Output folder structure (Section 15.2 );

1D outputs (Section 15.3 );
2D outputs (Section 15.4 );
Post processing and scripting (Section 15.5 );
Impact mapping (Section 15.6 ); and
Animation generation (Section 15.7 ).

@1925
15.2 Folder Structure

Simulation outputs are written, by default, as long as the Map

Output Interval tcf command has been specified (a mandatory
command). If an output folder has not been specified (see Section
11.1 ), TUFLOW will write results to the folder in which the .tcf is
located. It is recommended to use the Output Folder command to
write results to a results folder, for example ‘TUFLOW\results’.

The adjacent image shows the typical folder structure of a

TUFLOW model folder, including the breakdown of the results
folder. The typical files found within the results folder are listed in
Table 15.1 . Note, this will depend on the model and the output
commands specified in the .tcf.

If no other output commands (detailed in Chapter 11 ) have been defined, by default TUFLOW
will write outputs in XMDF format, at the interval specified by the mandatory Map Output Interval
command.

Within the results folder, TUFLOW will automatically create a ‘plot’ folder (for example
‘TUFLOW\results\plot’), containing both the .tpc output and a gis folder containing the TUFLOW
plot output in .csv and GIS format (see Section 11.3 ). If the user has requested grid outputs ,
TUFLOW will automatically create a ‘grids’ folder in the location where the results have been
written (for example ‘TUFLOW\results\grids’).

Section 15 Viewing Outputs - 1 / 16 Page 617 / 1094

 What TUFLOW outputs depends on the output settings specified in the model. Table 15.1
describes the typical files contained within the Output folder. If using the Output Folder command
within the .ecf (or Start 1D Domain block) some of these outputs will be located in the folder
referenced by that command.

Section 15 Viewing Outputs - 2 / 16 Page 618 / 1094

 @1926 Table 15.1: Plot Folder File Descriptions

Folder Filename Description

The 2D temporal mesh output (e.g. XMDF or DAT

results\ .xmdf / .dat and associated file types). See Section 15.4.1 for
information on how to view these outputs.

Contains information on inflows and outflows,

_MB.csv
volume, predicted volume error and the mass and
_MB_HPC.csv
results\ cumulative mass errors as a percentage. See
_MB1d.csv
Section 14.8.3 and Section 14.8.4 for information
_1d_MB.csv
on these outputs.

Contains time series data output from 2D domains,

for a range of hydraulic parameters based on the
specified time-series output data type.
_PO.csv The _POMM file contains maximums, minimums,
results\
_POMM.csv time of maximum and time of minimum information.

See Section 15.4.3 for information on how to view

these outputs.

The _TS GIS layers contain time-series output with

each layer presenting different information.

_TS The _TSF GIS layer contain the flow regimes of the

_TSF culverts and pipes.

results\ _TSL The _TSL GIS layer contains the losses of the

_TSMB culverts and pipes.

_TSMB1d2d The _TSMB contains the time based 1D mass error.

These time-series outputs are discussed further in

Section 15.3.4 .

Contains information on culverts and bridges. See

results\ _1d_ccA
Section 15.3.3 for more information.

_1D_mmH GIS layers containing maximum/minimum values for

results\ _1D_mmQ water levels at nodes, and flows and velocities in
_1D_mmV channels. See Section 15.3.2 for more information.

TUFLOW automatically writes raster outputs to a

results\grids folder, in the format specified by the
Map Output Format command. Users typically write
results\grid .tif / .flt / .asc maximum raster output only. User the mesh output
for the temporal outputs due to file size and viewing
abilities. See Section 15.4.2 for information on how
to view these outputs.

TUFLOW Plot Control file is a text file. It is used by

results\plot\ .tpc the QGIS TUFLOW Plugin to load plotting dataset, as
documented in the TUFLOW Wiki.

Section 15 Viewing Outputs - 3 / 16 Page 619 / 1094

 Folder Filename Description

The _1d_Chan layer contains information on the

channel connectivity and properties.
The _1d_Cmx layer contains the channel maximums
_1d_Chan.csv
data: flows and velocities as well as time of the
_1d_Cmx.csv
results\plot\csv\ maximums.
_1d_Nmx.csv
The _1d_Nmx layer contains the node maximums
_1d_Node.csv
data: water levels and energy levels.
The _1d_Node layer contains information on the 1D
nodes.

Time series output for output type <ot> at the 1D

nodes or channels. The output is controlled by the
results\plot\csv\ _1d_<ot>.csv
Output Data Types command, which by default
includes “H”, “Q”, “S” and “V”.

Operational structures time series output, including

results\plot\csv\ _1d_O.csv information on the operational status and time
varying values of variables.

Time series output for each 2d_po output type <ot>,

results\plot\csv\ _2d_<ot>.csv
as triggered by Read GIS PO commands.

Reporting Location water levels (_H) and maximums

plus other information at the peak water level
_RLP_H.csv (_Hmx).
_RLP_Hmx.csv Reporting Location flows (_Q) and maximums plus
_RLL_Q.csv other information at the peak flow (_Qmx).
results\plot\csv\
_RLL_Qmx.csv Reporting Location volumes (_Vol) and maximums
_RLR_Vol.csv plus other information at the peak volume (_Volmx).
_RLR_Volmx.csv
See Section 11.3.3 for information on reporting
locations.

Maximums and other information (_SHmx) and time-

series total structure flow (_SQ) for all 1D structures
_SHmx.csv
results\plot\csv\ and grouped structure output (see Section 11.3.4 ).
_SQ.csv
This output is controlled by the “S” option in Output
Data Types , which by default includes “S”.

Summary .csv file containing information on the GIS

results\plot\gis\ _PLOT.csv
objects and plot types available.

GIS layer in a vector format containing all plot line

_PLOT_L objects (e.g. 1D channels and flow Reporting
results\plot\gis\ _PLOT_P Locations), plot point objects (e.g. 1D nodes and
_PLOT_R water level Reporting Locations) or region objects
(e.g. total volume within the region).

Section 15 Viewing Outputs - 4 / 16 Page 620 / 1094

 @1927
15.3 1D Output

TUFLOW outputs the following 1D outputs:

TUFLOW Plot Control file (.tpc) (Section 15.3.1 )

Maximum and Minimum Output (Section 15.3.2 )
Closed Channels Performance (Section 15.3.3 )
GIS Time Series Outputs (_TS) (Section 15.3.4 )
Open Channel Water Level Line Output (Section 15.3.5 )
ESTRY Output File (.eof) (Section 14.6 )
MB1D.csv (Section 14.8.3 )

For viewing SWMM 1D results, see the TUFLOW-SWMM Result Wiki page

@1928
15.3.1 TUFLOW Plot Control file (TPC)

A range of model time-series results from the 1D and 2D domains are output in .csv file format to
the “results\plot\csv” folder. These files are traditionally used in spreadsheet software for graphing
and time-series analysis. TUFLOW Plot Control file is a text file used by the TUFLOW Viewer
(included in the QGIS TUFLOW Plugin) to load the plotting dataset into QGIS. Viewing the data
spatially and temporally in QGIS is generally considered the preferred approach for day to day
interaction with the csv files due to the increased workflow efficiency working in this manner.
Documentation focused on viewing the .tpc in the TUFLOW Viewer is contained in the Time Series
Output TUFLOW Wiki page. Some key pages related to viewing 1D time-series (plot) outputs are
listed below:

Loading in TPC
Plotting Time Series
Plotting Longitudinal Profiles
Plotting 1D Flow Regimes
Plotting 1D Cross-Section Inputs

An example of loading in a .tpc file into the TUFLOW Viewer is shown below.

Section 15 Viewing Outputs - 5 / 16 Page 621 / 1094

 Note: The tcf Start Time Series Output and Time Series Output Interval commands are used to
control the period and frequency of output available in TUFLOW Viewer in QGIS.

@1930
15.3.2 Maximum and Minimum Output

Maximum and minimum values for water levels at nodes, and flows and velocities in channels, are
output to GIS layers with the extensions 1d_mmH, 1d_mmQ and 1d_mmV, as well as to the end of
the .eof file (see Section 14.6 ). The GIS layers can be opened in a GIS software, an example of
the 1d_mmH and 1d_mmQ, with its automatic styling, is shown in Figure 15.1 .

@1931

Section 15 Viewing Outputs - 6 / 16 Page 622 / 1094

 Figure 15.1: Maximum and Minimum Water Level and Flow Output
The following attributes are contained in the 1d_mmH layer:

Node: ID of the node.

Hmax: maximum water level.
Hmin: minimum water level.
tHmax: time of occurrence of the Hmax value.
tHmin: time of occurrence of the Hmin value.
dH: the largest water level drop across the channels that end at that node. Only channels that
are digitised so that their downstream end is at the node are used to determine dH. Provided
channels are digitised from upstream to downstream this is useful for identifying any
increases in water level caused by any instabilities (thematically map the dH attribute –
negative values indicate the water levels are increasing downstream). Pit channels are
excluded from determining dH.

The following attributes are contained in the 1d_mmQ layer:

Channel: ID of the channel.

Qpeak: equal to the absolute maximum (positive or negative) flow. This is particularly useful
for tidal reaches or where a channel has significant flows in both directions.
Qmax: maximum flow.
Qmin: minimum flow.
tQpeak: time of occurrence of the Qpeak value.
tQmax: time of occurrence of the Qmax value.
tQmin: time of occurrence of the Qmin value.
dHmax: difference in maximum water level drop through the channel. This is useful for quickly
identifying large unexpected changes in flood level.

Section 15 Viewing Outputs - 7 / 16 Page 623 / 1094

 pSmax: the slope as a percentage of the water surface along the channel. This is useful for
quickly identifying any troublesome behaviour along 1D networks by viewing/searching for
any negative (adverse) slopes.
Style_SF: used for the automatic styling of the output. The value is a ratio based on the the
channels Qmax value, and the maximum of all vMax values within the table and therefore will
range between 0 and 1.
Style_dir: angle based on the channels digitised direction.

The following attributes are contained in the 1d_mmV layer:

Channel: ID of the channel.

Vpeak: equal to the absolute maximum (positive or negative). This is particularly useful for
tidal reaches or where a channel has significant flows in both directions.
Vmax: maximum velocity.
Vmin: minimum velocity.
tVpeak: time of occurrence of the Vpeak value.
tVmax: time of occurrence of the Vmax value.
tVmin: time of occurrence of the Vmin value.
Style_SF: used for the automatic styling of the arrow. The value is a ratio based on the the
channels Vmax value, and the maximum of all Vmax values within the table and therefore will
range between 0 and 1.
Style_dir: angle based on the channels digitised direction.

@1932
15.3.3 ccA GIS Layer

The _ccA GIS layer contains a summary of information for culverts and bridges. It includes the
following attributes:

Channel = The ID of the channel.

pFull_Max = The percentage of the peak flow area over the culvert/bridge area. If the
culvert/bridge flowed full at any point during the simulation this will be 100%.
pTime_Full = The percentage of time the culvert/bridge ran full over the time the culvert/bridge
ran at least 10% full.
Area_Max = The peak flow area that occurred during the simulation.
Area_Culv = The culvert/bridge flow area (when full).
Dur_Full = The time in hours the culvert/bridge was running full.
Sur_CD = Surcharge cut-off depth. Depth above pit upstream invert for a pit to be considered
surcharging.
Dur_Sur = Duration of surcharge. Total duration (hrs) that the pipe is considered surcharging.
pTime_Sur = Percent time that the pipe is surcharging relative to the time the pipe is running
at 100% full.
TFirst_Sur = Time of first surcharge (hrs).
Dur_10pFull = The time in hours the culvert/bridge ran 10% full or more.

The layer’s lines can be coloured and thickened according to the pFull_Max attribute (styled using
the QGIS TUFLOW Plugin ‘Apply TUFLOW Styles’ Tool for .shp/.gpkg format or output directly for
the .mid/.mif format). The thinner and paler the line, the smaller the pFull_Max value. The
pFull_Time attribute is also useful for thematically mapping in GIS to identify culverts that are
performing well, and others that are not. The example shown in Figure 15.2 illustrates the _ccA
GIS layer output.

Section 15 Viewing Outputs - 8 / 16 Page 624 / 1094

 @1933

Figure 15.2: Example of the ccA GIS Layer Highlighting Culvert Performance

@1934
15.3.4 _TS GIS Layer

The 1D water levels at nodes (_1d_H.csv), and flows (_1d_Q.csv) and velocities (_1d_V.csv) in
channels are output in separate .csv files. This information is also provided in the _TS GIS layer
and within the .eof file (Section 14.6 ). Maximum and minimum values are not output to the .csv
files however are contained within both the _TS GIS layer and the .eof file as well as the 1d_mmH,
1d_mmQ and 1d_mmV GIS layers (Section 15.3.2 ).

The _TS GIS layers contain time-series output with each layer presenting different information, as
described below and in Table 15.2 . In addition to the time-series data, each layer contains
several attributes at the start, summarising the time-series data. These attributes are:

The maximum and minimum values;

The time in hours of the maximum and minimum values; and
The average and the average of the absolute mass error values (for the TSMB and
TSMB1d2d files only).

Section 15 Viewing Outputs - 9 / 16 Page 625 / 1094

 @1935 Table 15.2: _TS GIS Layer Descriptions

GIS Layer
Description
Name

_TS_L Contains all 1D channel (velocities and flows), 1D nodes (water levels) and
_TS_P 2D PO (plot output locations from 2d_po layers).

Contains the flow regime flags for culverts (see Table 5.6 ), and other
_TSF_P
types of channels (see Table 14.2 ).

Contains the loss / discharge coefficients for the following 1D channels:

For culverts: the three values shown for each time are the inlet (entry)
loss coefficient; additional loss coefficient (this value is the sum of any
1d_nwk Form_Loss (bend loss) value on the channel or an upstream
pit and any manhole energy loss contribution); and outlet (exit) loss
coefficient. If Structure Losses == ADJUST or the “A” flag has
been specified, the entry and exit loss coeficients are adjusted loss
coeficients. If there is a manhole connected to one/both ends of a
culvert, the loss coefficients will be affected by any manhole energy
losses, as discussed in Sections 5.11.4 .

For B bridges: the bridge loss coefficient adopted is shown.

For BB bridges: the two values shown for each time are the bridge loss
_TSL_P
coefficient and the combined entry/exit loss coefficient. If Structure
Losses == ADJUST or the “A” flag has been specified, the combined
entry/exit loss coeficient is the adjusted loss coeficient.

For BArch bridges: the two values shown for each time are the
downstream blockage (J3) and froude number (F3) used in the ‘Afflux
at Arch Bridges’ (HR Wallingford, 1988 ) method. If orifice flow
condition is applied, the two values are the orifice flow discharge
coefficient and the calibration facotor of the discharge coefficient.

For advanced weirs (Section 5.8.4.3 ) and DF channel (Section

5.10.8.2 ): the flow regime is shown followed by two numbers. The
first number is Cf × Cd and the second number is Csf , see Equation
(5.11) .

_TSMB_P Contains the mass errors at 1D nodes (refer to Section 14.8 ).

Contains the mass errors across 1D/2D interface linkages, ie. HX links
_TSMB1d2d_P
(refer to Section 14.8 ).

The _TS GIS layers can be loaded into QGIS. Once loaded, they will automatically appear in the
TUFLOW Viewer Results window, allowing users to view time-series data, as shown in Figure 15.3
.

@1938

Section 15 Viewing Outputs - 10 / 16 Page 626 / 1094

 Figure 15.3: Example of the _TS Layer Flow Output
There are two ways to style the _TS layers. The first way is the default TUFLOW Styling, which
displays arrows for velocity and flow, and points for water level. The second way is by using the
Stability Checking Styling Tool. This tool styles the _TS layer into categories: likely unstable,
possibly stable and stable, as shown in Figure 15.4 . How to use this tool, and the rules applied
to the categories are discussed on the Stability Checking Styling Tool TUFLOW Wiki page.

@1939

Figure 15.4: Example of the _TS Layer Stability Styling

Note that the output frequency of the time output in _TS GIS layers is automatically adjusted so
that the limit of 245 output times is not exceeded (this limit is the maximum number of attributes
allowed in some GIS software). For example, if based on the Time Series Output Interval setting
there are 400 output times, then every second time will be written to the _TS GIS layer giving a
total of 200 output times, but at least the full hydrograph is displayed!

For models that contain 1D operational structures (refer to Section 5.10 ), an additional file
(_1d_O.csv) will be output to the “results\plot\csv” folder containing information on the operation of
each structure over time. This file serves as a valuable check for the commands defined within the
.toc.

Section 15 Viewing Outputs - 11 / 16 Page 627 / 1094

 @1940
15.3.5 1D Water Level Lines (WLL)

As mentioned in Section 11.2.4 , 1D domain results can be output in combination with 2D

domain(s) by using the 1d_wll GIS layer and the Read GIS WLL command. When WLL are used,
the water level from the 1D node is interpolated into a 2D format when viewing the results (for
both mesh and grid outputs). If the 1D WLLs and 2D domains overlap, the 1D results are
displayed on top of the 2D results. Viewing of these 2D mesh and raster results is discussed in
Section 15.4.1 and 15.4.2 .

Additionally, viewing of 1D results in a 2D domain using the WLL functionality is demonstrated in

Tutorial Module 11.

@1941
15.4 2D Output

TUFLOW outputs the following 2D outputs:

Mesh based outputs (Section 15.4.1 )

Grid (raster) based outputs (Section 15.4.2 )

Additionally, time-series data from the 2D domain can be output using plot outputs (Section 15.4.3
).

@1942
15.4.1 Mesh Output

The TUFLOW Viewer (found in the QGIS TUFLOW Plugin) can be used to load mesh temporal
outputs in QGIS. When loading this data into TUFLOW Viewer, all map outputs specified by the
user in the Map Output Data Types will automatically load under the results type panel.
Symbology can be set for the outputs by right-clicking on the output in the results panel, in the
same way described for raster outputs (Section 15.4.2 ).

Documentation focused on map outputs in the TUFLOW Viewer is contained in the TUFLOW Wiki
Map Outputs page. Some key pages related to viewing mesh outputs are linked below:

Loading Map Outputs

Display Maximums
Save Default Styles
Plotting Time Series
Plotting Cross Sections

An example of loading in an .xmdf file into the TUFLOW Viewer is shown below.

Section 15 Viewing Outputs - 12 / 16 Page 628 / 1094

 Note: Using TUFLOW Viewer, it is also possible to extract transect flow time-series from the mesh
output result (see the TUFLOW Wiki for details). Unfortunately, map outputs do not include all
required information for accurate extraction of this output type. A more accurate way, and the
recommended approach, to obtain flow time-series information is to use the 2D plot outputs
(Section 15.4.3 ).

@1944
15.4.2 Raster Output

Grid (raster) based outputs can be loaded into QGIS via drag and drop. Once loaded, there is a
range of styling options. An example of setting the symbology for a raster layer is provided in
Tutorial Model 1.

It is also possible to load NetCDF rasters into TUFLOW Viewer (when the Map Output Format
has been set to NC or HRNC). The Loading NetCDF Grids Wiki page describes this process.

@1945
15.4.3 Plot Output

The location of plot outputs need to be defined prior to the simulation, as described in Section
11.3.2 . 2D time-series data from plot output (PO) or longitudinal profile (LP) data at locations
defined using 2d_po and 2d_lp layers (see Section 11.3.2 ) are output as _PO.csv and _LP<
name>.csv files into the “results” folder. These files can be used in spreadsheet software for
graphing and time-series analysis. 2D plot outputs can also be loaded and viewed in the TUFLOW
Viewer using the same method described in Section 15.3.1 . An example of plotting 2d_po
outputs is shown in Result Viewing - Tutorial 1.

The commands Start Time Series Output and Time Series Output Interval are used to control
the period and frequency of output.

Section 15 Viewing Outputs - 13 / 16 Page 629 / 1094

 When writing plot outputs, TUFLOW produces two .csv files, _PO.csv and _POMM.csv. _PO.csv is
time-series data over the duration of the simulation. _POMM.csv reports the maximum and
minimums. The columns included in the _POMM.csv file are:

Output (for example, columns containing summary information for Flow, Water Level and
Velocity)
Location (name of the 2d_po point, line or region)
Maximum (Extracted from Time Series)
Time of Maximum
Minimum (Extracted From Time Series)
Time of Minimum

Time-series and maximum output in .csv files is also available when using Reporting Locations
(see Section 11.3.3 ) and Structure Groups (see Section 11.3.4 ). These two options provide the
ability to combine 1D and 2D domain outputs. The .csv files that are produced are listed in Table
15.1 .

@1946
15.5 Post Processing

The open non-proprietary file formats used by TUFLOW for its input and output make it well suited
to automation via scripting as a means to improve workflow efficiency. Many modellers develop
their own tools to assist in their use of TUFLOW and to automate many tasks. A GitLab TUFLOW
User Group has been established to support the sharing and collaborative development of these
tools. These tools include scripts to assist with post-processing of TUFLOW outputs.

Where repeated plotting of results is required during a project, or there are a large number of
charts to produce, Python scripts offer an attractive workflow efficient option. For some initial
guidance regarding using Python scripts please see our Python eLearning.

Experienced python coders may also be interested in the PyTUFLOW tools, developed to simplify
result analysis and post-processing automation. PyTUFLOW for instance can allow real-time
calibration plots to be produced during the course of a simulation.

Additionally, the TUFLOW Utilities offer a range of options for post-processing TUFLOW map and
grid output. Some of the more common functions include:

Creating a vector GIS (e.g. .shp) file of velocity vectors;

Creating a grid of the maximum values from two or more input grids; and
Calculating the affluxes between two grids (see Section 15.6 ).

Refer to Chapter 17 and the TUFLOW Utilities Wiki Page for further information on the TUFLOW
Utilities.

@1947
15.6 Impact Mapping

It is often necessary to carry out a comparison of results between two or more model simulations.
For example, to quantify the impact of a proposed development on the predicted flood extent and
flood depths, or assess the sensitivity of the model due to changes in one of the parameters. A

Section 15 Viewing Outputs - 14 / 16 Page 630 / 1094

 number of the TUFLOW utilities (refer to Section 17 ) may be used to carry out this comparison.
For example, the ASC_to_ASC utility may be used to compare the results contained in two grid
output file (TIF, FLT or ASC formats). This utility outputs two result grids, shown in Figure 15.5 :

A difference grid subtracting the second input grid from the first; and
A second grid with a “_wd” suffix, denoting locations where the model was previously wet and
now dry, and vice versa.

@1948

Figure 15.5: Impact Mapping

An example of using the ASC_to_ASC utility to create an impact grid is available in the TUFLOW
Tutorial Module 2.

Alternatively, the RES_to_RES utility may be used. Rather than comparing grid output, the
RES_to_RES compares mesh result files (e.g. .xmdf format) for a single timestep or all timesteps
in the model simulation. Note, unlike ASC_to_ASC, RES_to_RES is limited to comparing model
results with the same underlying .2dm mesh file.

Further information on ASC_to_ASC, RES_to_RES and the other TUFLOW utilities are discussed
in Chapter 17 , with more detail and examples via the TUFLOW Wiki Utilities page.

@1949
15.7 Animations

Result animations can be exported from the TUFLOW Viewer for all accepted result types (map
outputs, time series, particles etc). The process for animation creation is the same regardless of
the result type. The tool will export an image for each timestep in a given range, then use ffmpeg
to convert the images into a video file. TUFLOW Viewer offers the additional functionality of
adding dynamic plots and dynamic time text. It also offers convenience functionality for adding
items such as a legend, images etc, however these can also be added manually in the print
layout.

Instructions on how to export animations is found on the TUFLOW Wiki and an example provided
in the below video.

Section 15 Viewing Outputs - 15 / 16 Page 631 / 1094

 Creating aminations with embedded dynamic plot windows…
windows…

References

@1951
@1950
HR Wallingford. (1988). Afflux at Arch Bridges. https://eprints.hrwallingford.com/219/1/SR182-
Afflux-arch-bridges-HRWallingford.pdf

Section 15 Viewing Outputs - 16 / 16 Page 632 / 1094

 @1955

@1956
Section 16 Quality Control and
Troubleshooting

@1957
16.1 Introduction

Proficient and effective 1D and 2D hydrodynamic modelling is a skill that takes time to develop.
During the development of these skills, most modellers may produce “unhealthy” models at some
point (i.e. models that are problematic in that they regularly go unstable, produce strange flow
patterns, etc.). Whilst, in most cases, the reasons for problems are due to the quality of input data,
other reasons include poor model schematisation, and, of course, human error. With mentoring
from experienced modellers, and/or following an iterative testing process, unhealthy models can
be corrected to become healthy, and hydrodynamic modelling skill levels greatly enhanced. This
section attempts to convey some ways to identify problematic areas within an unhealthy model,
and solutions to resolving the problem.

@1958
16.2 Model Health

Due to the computational differences associated with the two solvers, TUFLOW Classic and
TUFLOW HPC, there are slightly different approaches to assess and deal with model health
issues in each. The following sections will outline the characteristics of unhealthy models in
TUFLOW Classic and HPC separately, though the general approach to troubleshooting is very
similar.

@1959
16.2.1 TUFLOW Classic

Unhealthy TUFLOW Classic models usually exhibit one or more of the following characteristics:

The model only remains stable if using a smaller than recommended timestep.
Poor mass error (> ±1 %) as indicated by the “CE” percentages displayed to the Console
Window (see Section 14.2.1 ), and output to the various mass balance files as described in
Section 14.8 .
“Unnatural” fluctuations of flow in/out and change in volume values (i.e. the Qi, Qo and dV
values displayed to the Console Window) discussed in Section 14.2.1 .
Locations in the model that repetitively have negative depth WARNINGs. These repeatedly
appear as a message such as: “WARNING 2991 - Negative U depth at [030;088], Time =
0:01:30, Depth = -0.4…”. The occurrence of the message several times at a location is usually
not an issue (this means that the model experienced a short and slight numerical
disturbance), however, if it repeatedly occurs for a period of time, it is good practice to resolve

Section 16 Quality Control and Troubleshooting - 1 / 24 Page 633 / 1094

 the source of the problem as this numerical disturbance may cause mass errors, possibly
forcing the use of too small a timestep, and may initiate an instability in a future simulation.

If one or more of the above apply, the model needs to be reviewed and the cause of the unhealthy
behaviour identified. This can be a daunting and difficult task for inexperienced modellers,
however, the guidelines in the sections below are hopefully of some assistance.

@1960
16.2.1.1 Timestep

For the majority of TUFLOW Classic flood models, the 2D Timestep in seconds should be
somewhere between 1
to 1

5
of the 2D Cell Size (in metres). For example, a 10m 2D grid should
2

use a timestep of between 2 and 5 seconds. 2D domains with predominantly sub-critical flow
usually can have timesteps larger than those for steeper models with significant areas of
supercritical flow.

For coastal models, models with large cell sizes (>50m) or models with significant areas of deep
water (>20m), the above rule-of-thumb may not apply with the timestep often being smaller. This is
due to the Courant condition described in Section 3.5 .

There is a tendency for hydraulic modellers to “solve” an instability by reducing the model
timestep. Whilst this may “work”, if the required timestep is less than the above mentioned
recommended minimums, it is usually not solving the fundamental cause of the model’s poor
hydraulic performance or instability. Using too small a timestep can mask fundamental problems in
the input data, and hide mistakes in the construction of the model. For example, if the user
accidentally applies a topography modifier with an elevation -99m below the surrounding cells, a
small timestep may “remove” the instability but does not resolve the issues in the input data.

Using a too large a timestep will cause mass errors. If the model runs stable without any negative
depth warnings, yet the cumulative mass error is poor throughout the simulation, this is often an
indication that the 1D and/or 2D timesteps are too large.

@1963
16.2.2 TUFLOW HPC

TUFLOW HPC uses an explicit finite volume scheme. It uses an automatic adaptive timestep
routine which is unconditionally stable and provides 100% 2D mass conservation. TUFLOW HPC
will not show a mass balance error like TUFLOW Classic but rather, in situations where the
stability is threatened, the model timestep is reduced. In recognition of this behaviour, reviewing
the minimum timestep is useful in determining the health of a TUFLOW HPC model. For TUFLOW
HPC, the *_dt_Min map output file can be used to identify the specific location that is requiring the
minimum timestep to achieve simulation stability. This is useful output to help identify where the
modeller should be reviewing model inputs and model schematisation.

@1964

Section 16 Quality Control and Troubleshooting - 2 / 24 Page 634 / 1094

 Figure 16.1: TUFLOW HPC Minimum Timestep (dt) Map Output
Unhealthy TUFLOW HPC models usually exhibit one or more of the following characteristics:

A large number of repeat timesteps within the Console Window. The total number of repeated
timesteps is recorded in the Simulation Summary section at the end of the .tlf file, and is
reported to the _messages layer. Repeated timesteps are an indication that the TUFLOW
HPC 2D solution is numerically “on-the-edge”. Models that have a high number of repeated
timesteps should be sensitivity tested by reducing the control number limits using the Control
Number Factor command.
The model only remains stable if using an excessively small timestep.
Oscillating timesteps and controls numbers as shown in the *.hpc.dt.csv output to the log
folder.
“Unnatural” fluctuations of flow in/out and change in volume values (i.e. the Qi, Qo and dV
values displayed to the Console Window) discussed in Section 14.2.1 .

Like TUFLOW Classic, if one or more of the above apply, the model needs to be reviewed, the
cause identified and rectified.

Note: Although TUFLOW HPC is 100% mass conservative and will not produce any mass
error in the 2D, it is still important to review the Mass Error from a simulation. Mass Error
can occur in poorly configured models when coupling HPC with 1D elements (either
associated with the 1D/2D linking or in the 1D scheme itself).

@1965
16.2.2.1 Timestep

The TUFLOW HPC solver, by default, uses adaptive timestepping to progress through the
simulation. The timestep is adjusted so that it complies with the mathematical stability criteria of a
2D explicit solution. Due to the underlying solution scheme, TUFLOW HPC typically uses a
smaller timestep than Classic. As a general rule, a healthy TUFLOW HPC timestep is roughly
1

10

of a TUFLOW Classic healthy timestep (i.e. for a cell size of 10m, a healthy TUFLOW Classic
timestep would be 2 to 5s, and therefore a healthy TUFLOW HPC timestep would be between 0.2
to 0.5s).

There are three primary processes that determine the maximum timestep that an explicit solution
of the Shallow Water Equations can use:

Section 16 Quality Control and Troubleshooting - 3 / 24 Page 635 / 1094

 Courant Number, Nu: The Courant number relates to velocity relative to the cell size. Higher
velocities will trigger this as the timestep control.
Wave Celerity Number, Nc: The Celerity Control number relates to water depth relative to
cell size. Energy can pass through deeper water faster than shallow water, as such deep
water will trigger this control.
Diffusion Number, Nd: The diffusion control relates diffusion of momentum relating to the
sub grid viscosity. Small cells subject to deep water will trigger this control.

Further description of these control numbers is provided on the TUFLOW Wiki.

TUFLOW will use the highest timestep possible without exceeding the limits associated with each
of the control numbers. The .hpc.tlf log file records the model timestep, control numbers and the
volume of water in model at each timestep. It also shows repeated timesteps if the control number
limits were exceeded or there is a significant change in control numbers (more than 20%). If a
model has a sudden change in rainfall between timesteps, or has a warmup period with small flow
rate before a large inflow then repeated timesteps are possible. However, if there is a high
occurrence of repeating timesteps when the boundary inflows are smooth, this could be an
indicator of model instability. The total number of repeated timesteps is also recorded in
Simulation Summary of the .tlf file.

@1967

Figure 16.2: TUFLOW HPC.TLF Repeating Timesteps

It is possible to plot the time-varying control number settings from the *.hpc.dt.csv that is output to
the log folder when running a TUFLOW HPC simulation. This can be done using spreadsheet
software such as Excel, or a scripting language such as python. An example using a drag and
drop tool, the TUFLOW Summary Dashboard, is shown in Figure 16.3 . The tool is available on
the TUFLOW Gitlab User Group.

@1968

Figure 16.3: Timestep and Control Numbers plotted from the .hpc.dt.csv

The two key features that modellers should look for in the hpc.dt.csv output, is erratic oscillation of
the timestep values and extremely low timesteps. If an oscillating timestep or an unusually low
timestep is observed in the HPC dt time series, it is important to review the associated value for
each control number (Nu, Nc and Nd). This will allow the modeller to determine which hydraulic
condition is limiting the timestep. Since the 2023-03 release of TUFLOW, it is also possible to
provide map output for the three control number using the Map Output Data Types command
which can also help identify model features leading to reduced timesteps.

Section 16 Quality Control and Troubleshooting - 4 / 24 Page 636 / 1094

 @1969
16.2.3 Healthy Model Indicators

A summary of healthy model indicators is provided at the end of the simulation on the display
console, and at the end of the .tlf file. A selection of these indicators are also written to the “_
TUFLOW Simulations.log” files – see Section 14.4 . The indicators are discussed in Table 16.1
below.

Note, these model health reporting items should be used in conjunction with good model
review practices. They are a set of indicators of various model health parameters. They are
not definitive proof that a simulation was or was not healthy.

Section 16 Quality Control and Troubleshooting - 5 / 24 Page 637 / 1094

 @1970 Table 16.1: Simulation Summary Healthy Model Indicators

Model Health
Reporting Description Solver
Item

The occurrence of negative depths at 1D nodes or 2D cell

sides is an indication that the solution has not converged or
has over-stepped at that location and time. WARNING
1991 for 1D nodes and WARNING 2991 at 2D cell mid-
sides are issued each time a negative depth greater than

Total Negative -0.1m occurs. The location of these warnings can be

viewed using the _messages GIS layer. Classic/HPC
Depths

From a healthy model perspective, the occasional negative

depth is not necessarily a concern, but repeat occurrences
at the same location are an indication of a potential issue.
See Section 16.3.2 for further discussion. Negative depths
may often precede an instability.

Number of CHECKs and WARNINGs issued. At key stages

WARNINGs
of a project, review any CHECKs and WARNINGs, and if
and CHECKs
needed, resolve any issues, particularly for WARNINGs. If
prior to and Classic/HPC
a CHECK or WARNING is not in the _messages layer, this
during
means that it could not be located geographically and only
simulation
occurs in the .tlf file (search the .tlf file to review them).

Review these numbers in the sense that they are in

accordance with your expectations. Usually the “Peak Flow
In” exceeds the “Peak Flow Out” for flood simulations due
to the flood wave being attenuated as it travels through the
Peak Flow In model. Note, at boundaries where a circulation develops,
3
Classic
and Out (m /s) there will be flow in and out and these amounts will
contribute to the Flow In and Out of the model as reported
here and in the _MB.csv files. This behaviour is indicative
of a boundary line that is not well aligned (perpendicular to
flow) and possibly should be changed.

The volume of water in the model at the start and end of

the simulation. Review these numbers, and confirm they
are sensible. A very large residual volume at the end of the
simulation may indicate that the simulation was not run for
Volume at Start
long enough, for example, the flood may not have reached Classic/HPC
and End (m3)
its peak. The time of peak water level is also a good
indicator of this, if the time of peak water level is the same
as the end time of the simulation, the simulation has likely
not run long enough for the flood waters to peak.

Section 16 Quality Control and Troubleshooting - 6 / 24 Page 638 / 1094

 Model Health
Reporting Description Solver
Item

The total volume of water in and out of the model during

the simulation. Review these numbers to confirm they
Volume In and
make sense. Usually the volume out is less than the Classic/HPC
Out (m3)
volume in, as the model has a residual amount of water left
in it at the end of the simulation.

Volume Error is the loss or gain in water over the course of

the simulation. Volume Error is equal to:

(Total Volume In - Total Volume Out) – (Volume at End –

Volume at Start)

Volume Error The Volume Error % value is the Volume Error divided by
3
(m ) Final the Volume In + Out.
Classic/HPC
Cumulative The Final Cumulative Mass Error % is calculated
ME% throughout the simulation using a similar formula, so should
be similar to the Volume Error %. Ideally these values
should be less than 1%, but 2 or 3% can be acceptable
depending on the objectives of the modelling. Values
exceeding 3% usually indicate there are significant
problems with the model.

dV is the change in volume over the whole model in one

timestep, and the values shown here are the peak positive
and negative dV values. Note: these values will be
different to those shown on the display console or in
Peak +ve and
the _MB.csv files if the Screen/Log Display Interval or Classic
–ve dV (m3)
Mass Balance Output Interval are not set to the
computational timestep.
The time in hours that the Peak dV values occurred is also
shown.

Peak ddV is the maximum (positive or negative) change in

dV over one timestep, and the % value is the % of the
maximum Peak dV value. A large ddV value or % indicates
Peak ddV (m3)
the model may have been unsteady at some point. This Classic
(% of Peak dV)
may not be unusual in a model with complex hydraulics,
however, it is another indicator of whether there may be
somewhere in the model that needs reviewing.

The peak CME% value that occurred. As discussed above,

ideally this value should be less than 1%, though larger
Peak values can be acceptable depending on the objectives of
Classic
Cumulative ME the modelling. For example, higher numbers may occur
during the intimal wetting of a Classic model, though still
have a negligible impact on the overall model results.

Section 16 Quality Control and Troubleshooting - 7 / 24 Page 639 / 1094

 Model Health
Reporting Description Solver
Item

The values under “Qi+Qo > 5%” are for the period of the
simulation when the flow in and out exceeded 5% of the
peak flow in and out, and are representative of the bulk of
Values under
the simulation once the flood wave has begun flowing. Classic
“Qi+Qo > 5%”
These indicators are designed to exclude an initial period
of any unsteadiness at the start of the simulation that may
occur in some models.

TUFLOW HPC repeats timesteps if the control number

limits are exceeded or if there is a significant change in
control numbers (>20%). The three control numbers
(Courant Number, Wave Celerity Number and Diffusion
Number) determine the maximum timestep for the
TUFLOW HPC adaptive timestepping. They are reported in
the tlf and in the hpc.dt.csv. In general terms:

Courant number relates to velocity relative to the cell

size. High velocities will trigger this as the control. The
Courant Number should be less than 1;
HPC HCN Celerity Control number relates to water depth relative
Repeated to cell size. Energy can pass through deeper water HPC
Timesteps faster than shallow water, as such deep water will
trigger this control. The Wave Celerity number should
be less than 1;
Diffusion control relates diffusion of momentum relating
to the sub grid viscosity. Small cells in deep water will
trigger this one. The diffusion control number should
be less than 0.3.

A repeat timestep on its own is not necessarily an

indication of an unstable model. Oscillating control
numbers may be indictive of an unstable TUFLOW HPC
model.

Each TUFLOW HPC timestep is tested for the occurrence

HPC NaN of a NaN (Not a Number) which can occurs due to
Repeated undefined mathematical calculations such as a divide by HPC
Timesteps zero or square root of a negative number. The occurrence
of a NaN is indicative of a sudden instability.

Provides the cumulative sum of the number of TUFLOW

HPC timestep corrections (indicated by WARNING 2550)
HPC NaN have been made in order for the TUFLOW HPC solution to
HPC
Warning 2550 remain stable. Whilst not always sign of an unstable model,
it is worth reviewing especially in the case of a large
number of repeated timesteps.

Section 16 Quality Control and Troubleshooting - 8 / 24 Page 640 / 1094

 @1971
16.3 Troubleshooting

Despite the best efforts of a modeller to be proactive in creating healthy models, some aspect of
review and troubleshooting may be required to generate a healthy and robust model.

The most common cause for an unhealthy model is poor underlying topography. In the case of 2D
domains, the quality of the Digital Terrain Model (DTM) is often the problem, therefore, investing
time to create truly representative, well-constructed, DTMs is highly recommended from both the
modelling perspective and the quality of the inundation mapping.

For 1D domains, topographic inaccuracies in cross-section data and at structures is often the
source of problems, although model schematisation can sometime also be the source of issues.
As a general statement, 1D modelling is more of an “art” than 2D modelling, due to the need for
user judgement associated with the selection of cross-section locations, and schematisation of the
1D domain.

For 1D-2D models, often poor stability of the 1D domain can lead to instabilities in the combined
model at higher flows when flow comes out of bank. Therefore, it is suggested that the 1D model
is tested to ensure stability prior to coupling with the 2D domain where possible. Care should also
be taken in the schematisation of any 1D-2D linkages.

Tip: Take an iterative approach to solving problems. As a model stability issue may
cascade to cause others, when searching through the _messages GIS file, resolve the
problems in order of occurrence (i.e. in the order the messages appear in a QGIS attributes
table, top to bottom). Solving issues earlier may automatically resolve the errors reported
later in the simulation

@1972
16.3.1 General Comments

When building a model, be proactive about ensuring the data is as complete as possible and
accurately reflects reality. For 1D stormwater pipe network data, use the 1D Integrity Tool is
recommended to ensure data is consistent and free of common errors, prior to use within a
TUFLOW model simulation. The TUFLOW ‘test’ mode can also be used to test the data inputs
without the simulation phase, see Section 13.5.2.1 for more details. This can be used in the initial
model testing phase without using the high specification modelling hardware that is often required
for the hydrodynamic simulation.

Problems in the input data that get through this initial integrity check are readily identified by using
Write Check Files command in the .tcf file and/or Write Check Files in the .ecf file to generate
GIS check files. These files represent the final combination of the 2D and 1D data inputs, and are
excellent for identifying data input problems. A detailed description of all available check files is
provided in the TUFLOW Wiki.

If the model becomes unstable, TUFLOW writes output data for the last computed timestep. The
location of stability is easily found by viewing the results for the last timestep. Very large velocity
vectors and/or excessively high or low water levels usually occur in the vicinity of the
instability.The instability can also be located using the _messages.shp / .gpkg files (see Section
14.5.5 ).

Section 16 Quality Control and Troubleshooting - 9 / 24 Page 641 / 1094

 Always search the .tlf files for the terms, “UNSTABLE”, “WARNING”, “CHECK” and “ERROR”.
ERRORs stop the simulation, while WARNINGs and CHECKs do not. Note, it is possible that latter
errors are caused by earlier warnings, therefore, search through the .tlf files, or start at the
beginning of the attributes within the _messages.shp/.gpkg file, resolve the earlier errors first,
rather than working backwards from the final error which resulted in the instability.

The Troubleshooting section of the TUFLOW Wiki contains a comprehensive database of

TUFLOW “CHECK”, “WARNING” and “ERROR” messages. Each “CHECK”, “WARNING” and
“ERROR” message has its own Wiki page documenting a description of the message, and
suggestions how to address the message.

@1973
16.3.2 Instability Identification

Instabilities usually start with one or a few computational points “bouncing” as a result of poor
convergence of the mathematical equations being solved. To help identify the start of an instability,
negative depth warnings are issued if the depth in a 2D cell (usually TUFLOW Classic only) or a
1D node falls below ‑0.1m. Negative depth warnings are usually a pre-cursor to an instability of
the true expected solution. It is not uncommon, particularly in areas of rapid wetting and drying for
negative depths to occur before the computational point is made dry (inactive). Hence a buffer of
-0.1m is used before reporting a WARNING.

The WARNING messages are sent to the _messages.shp / .gpkg file (see Section 14.5.5 ).
Import or open this file in GIS software to identify the location of the negative depth calculation. If
the number of these warnings are substantial (e.g. if a model remains stable but with minor
instabilities), select some of the first negative depth warnings in the attribute data and display just
those. The warnings are in order of occurrence. By tracing through the negative depth warnings in
the vicinity of the instability, the original source of the instability can usually be located.

@1974

Figure 16.4: TUFLOW Warning 2551 Messages in QGIS

TUFLOW also uses defined 1D and 2D water level threshold values to trigger an instability
message. The commands associated with these thresholds are Depth Limit Factor (1D domains)
and Instability Water Level (2D domains).

Section 16 Quality Control and Troubleshooting - 10 / 24 Page 642 / 1094

 @1975
16.3.2.1 1D (ESTRY) Domains

As advised in Section 16.3.2 for 2D domains, the location of an instability should be determined
by investigating where the WARNING 1991 messages occur. Common options for helping resolve
unstable or problematic 1D nodes and channels are:

1. If a 1D node or channel has become unstable, causing a simulation to crash yet the water
levels appear stable in the results, check the Depth Limit Factor setting. It may be that the
water level is simply exceeding the maximum depth of the node/channel times the Depth Limit
Factor .
2. If a 1D node has repeated WARNING 1991 messages, and/or has a mass error problem,
check that the cross-section/structure dimensions of adjoining channels are correct and
appropriate. Common causes are:
1. A large change in cross-sectional area for successive channels. If the channel is natural,
then it is likely that one or more of the cross-sections are not representative of the real
situation.
2. One or more incorrect upstream and downstream bed levels. Import the
1d_inverts_check GIS file, label the Invert attribute, and cross-check that the inverts are
correct.
3. A very steep channel entering a gently sloping channel. If this is the real situation, then
additional 1D channels providing a higher computational resolution may be needed,
alternatively inserting a structure at the transition may help.
4. If there is a sudden change in 1D flow area, then a more appropriate and more stable
approach would be to insert a structure representative of the situation to model the
energy losses associated with the contraction and/or expansion of the water.
5. Trial using a smaller 1D Timestep to establish whether the problem is timestep related. If
it is not timestep related, reducing the timestep should have little change in results. In
some problematic models, 1D instabilities may actually magnify with a reducing timestep.
6. A common solution is to add additional storage to the 1D node. This can be done by
using the 1d_nwk Length_or_ANA attribute described in Table 5.30 or using Minimum
NA , Storage Above Structure Obvert or Minimum Channel Storage Length . Usually
adding additional storage at problematic nodes does not adversely affect the results
(unless there are a lot of problematic nodes), however, this should be checked through
sensitivity testing (this can be carried out by adding even more storage again and
ascertaining the effect on the hydraulic results).

Besides investigating where the WARNING 1991 messages occur, the most effective approach to
identify potential problem locations is to thematically map or categorise the _TSMB GIS layer
using the ME_Avg_Abs attribute.

@1976
16.3.2.2 TUFLOW Classic

To identify problematic areas within a TUFLOW Classic 2D domain, the most common approach is
to run the model at a reasonable timestep and investigate where the WARNING 2991 messages
occur. If mass error is an issue in the 2D domain, the MB1 and MB2 outputs (see Map Output
Data Types and Table 11.4 may be of use.

Of particular note, models based on high quality DTMs are as-a-rule rarely problematic. However,
if the DTM is rough or “bumpy” (as can be the case with air-borne laser DTMs), or has poor
triangulation causing sharp ridges as illustrated in the images below, models based on these

Section 16 Quality Control and Troubleshooting - 11 / 24 Page 643 / 1094

 DTMs are much more likely to be problematic in/near these areas.

The following steps are useful to help identify and resolve the problem.

1. Set the 2D Timestep to somewhere between to of the cell size (in metres).
1 1

2 5

2. Run the model until it becomes unstable or has generated the WARNING 2991 messages.
3. Import or open the _messages GIS layer.
4. Within your chosen GIS package, view the _messages GIS layer in a tabular format and try to
trace back from the “UNSTABLE 2999” messages to the initial “WARNING 2991” messages
that were most likely the trigger for the instability.
5. Select a few of these WARNINGs and locate them geographically in the GIS map window.
6. Using the various _check GIS layers, carry out some fundamental checks. For example:
1. 2d_zpt_check or _DEM_Z check file: Check the Zpt values are as you would expect. If
the Zpt values are particularly “bumpy”, try smoothing the ones at/near the WARNING
2991 messages. Where the Zpts change in elevation rapidly (e.g. the outside bend of a
river), deep ZU and ZV elevations can be problematic. If modifying the ZU and ZV values,
tend to assign an elevation closer to the higher of the two ZC values either side of the
ZU/ZV point. To modify the Zpts it is recommended to create a new 2d_zpt or 2d_zsh
layer rather than editing the original data source for quality control purposes.
2. 2d_uvpt_check or 2d_grd_check: check the Manning’s n values are as expected, if not
identify why.

For reference, a detailed description of all available check files is provided in the TUFLOW Wiki.

Other points to note for TUFLOW Classic 2D domains are:

If the model becomes unstable quickly and the instability location is near a 2D water level
boundary, check that the initial water level setting is compatible with the starting water level of
the boundary.
Direct rainfall modelling on high elevations(>100m) may experience unacceptable mass errors
due to a floating point imprecision problem. These models need to use the double precision
version of TUFLOW (see Section 13.4.2 ). In addition, the default Cell Wet/Dry Depth may
need to be lowered from 0.002m to 0.0002m (when using Units == US Customary the
equivalent would be lowering from the default of 0.007 to 0.0007ft) due to the substantial
amount of sheet flow.

Section 16 Quality Control and Troubleshooting - 12 / 24 Page 644 / 1094

 @1979
16.3.2.3 TUFLOW HPC

To identify problematic areas within a TUFLOW HPC 2D domain, the most common approach is to
output the ‘dt’ map output (see Map Output Data Types and Table 11.4 ), and identify the
locations where the lowest timestep (dt) values occur (see Figure 16.1 ). For those locations,
check files are reviewed to search for data input issues. Of the check files, possibly the most
useful for TUFLOW HPC is the _DEM_Z check file in the location of the _dt_min to assess the
topography representation. If the topography doesn’t look realistic, it’s useful to open the
zsh_zpt_check file to assess if there’s any topographic modifications made in this location, or
whether there is an artefact in the input DTM datasets that is causing the irregularity. The
TUFLOW styles can be applied to the zsh_zpt_check file check file to show different adjustments,
red upwards arrows for increased elevation values, blue downwards arrows for decreased
elevation values.

Other points to note for TUFLOW HPC 2D domains are:

Non-perpendicular boundaries can provide instabilities in both TUFLOW Classic and HPC.
Whereas in TUFLOW Classic they will likely lead to an unstable model, they are more
challenging to pick up with TUFLOW HPC because of its unconditionally stability. One
approach to review inflow boundaries in a TUFLOW HPC model is to a add 2d_po line
immediately downstream of any boundary inputs. The PO results can then be used for
detailed review of the model stability in that particular location.
TUFLOW HPC simulates flow depth as its state variable and therefore it does not suffer the
same potential loss of precision as TUFLOW Classic when modelling direct rainfall. Therefore,
it is not a requirement to run a double precision version of TUFLOW HPC for direct rainfall
applications. There are some situations in which TUFLOW HPC may benefit from double
precision, for more information see Section 13.4.2.2 .

@1980
16.3.2.4 1D/2D Links

Some common configuration mistakes associated with 1D/2D links, and recommendations to
resolve them are:

1. Using a mixture of connected HX and SX lines along a river bank can cause mass errors. This
is not a recommended configuration. In these situations the 1D and 2D mass error reporting
can appear satisfactory, however the overall model mass error is poor. HX connections are
the recommended configuration to connect the 1D open channel to the 2D representation of
the floodplain. The _TSMB1d2d GIS layer is useful for identifying mass error issues across
2D HX lines. Note, the units of the mass error values for this layer are presently in m3s-1, not
in percent.
2. Unrealistic flow patterns occurring across the HX lines, sometimes causing strange flow
patterns and circulations in the 2D domain. This behaviour may occur due to one of the
following reasons:
1. Insufficient spatial resolution in the 1D domain. If the interval between 1D nodes is too
large, then the linearly interpolated 1D water level profile that is transferred from the 1D
domain to the 2D domain along the HX line will not accurately reflect the real situation.
This can create recirculation in the 2D and oscillations in the 1D. Check that there is a
sufficiently fine resolution of 1D nodes along the river to be representative of the river’s
longitudinal water surface slope. Typically, areas where there are significant changes in
longitudinal water surface gradient will require finer 1D resolution. Additional 1D nodes

Section 16 Quality Control and Troubleshooting - 13 / 24 Page 645 / 1094

 may be incorporated quickly and easily in the model through the use of automatically
interpolated cross-sections (refer to Section 5.7.7 ).
2. Conversely, having too fine a spatial 1D resolution may cause stability problems due to
insufficient nodal storage. As a general rule-of-thumb, the node surface area should be
similar to the width of the 1D/2D interface multiplied by 3 to 10 cell widths.
3. At a junction of three or more 1D channels, care should be exercised in how the levels
from the side branches are transferred to the HX line(s). If the side branch has much
higher water levels than the main branch, and a HX line segment is connected at one end
to the side branch and the other end to the main branch, a steep water level gradient may
be applied along the HX line segment that is not particularly representative of the real
situation.
4. Similarly, at 1D structures where there is a significant drop in water level (for example,
across a weir), the HX line may need to be stopped upstream and restarted downstream
of the structure to prevent a steep gradient being applied across HX cells over the
structure.
3. Instabilities can occur across HX boundaries that are located in areas of ponding water due to
the frequent transfer of water back and forth between the 1D and 2D domains. Use the
1D_2D_check layer to view the ZC elevations of the boundary, ensuring the elevations are
appropriate and the boundaries have been digitised on the top of banks. In some situations
the HX boundaries may need to be relocated and the schematisation of the model revisited to
resolve the issue.
4. Bumpy topography in the approach to SX boundaries may lead to instabilities. Smooth out the
Zpt elevations where appropriate, ensuring there is a 2D flow path leading to / departing from
the boundary.
5. An inappropriate number of SX boundary cells in relation to the 1D structure width may cause
stability problems. The number of cells selected should generally always correlate to the 1D
structure width. For example, a 5m wide culvert should be connected to 2-3 SX boundary
cells when the cell size is 2m wide. If the 1D structure width is less than or equal to a single
cell width, two rather than one boundary cell may need to be selected to achieve stability.

@1981
16.3.2.5 Other General Troubleshooting Recommendations

Futher general suggestions for common situations that are not uniquely specific to TUFLOW 1D,
Classic, HPC or 1D/2D linking are provided below.

1. If the Console Window does not appear at all when executing a simulation, check for virtual
memory congestion (see Section 14.2.3 ).
2. If the Console Window disappears for no apparent reason, first check the following:
1. You have sufficient disk space on the drive you are writing your results to and where the
.tcf or .ecf files are located (this is where the .tlf file is written by default).
2. Your computer network is/was not down.
3. If you are executing TUFLOW from a Windows batch file, review the batch file syntax is
correct.
3. If TUFLOW indicates that GIS objects are not snapped, not connected, could not be found or
are outside the model domain, check that:
1. The most recent GIS updates have been saved or exported for use by TUFLOW.
2. The relevant GIS layers are in the correct projection and that the objects are snapped to
each other. Some GIS programs can handle layers of different projections, however,
TUFLOW requires that all layers be in the same projection. This projection must be a

Section 16 Quality Control and Troubleshooting - 14 / 24 Page 646 / 1094

 Cartesian projection (not degrees latitude/longitude) and is specified using SHP
Projection , GPKG Projection and/or MI Projection in the .tcf file. The default setting is
that all input layers are of the same projection otherwise an ERROR occurs (see GIS
Projection Check ).
3. Different GIS software may use a different precision in the coordinates, this may result in
objects being snapped within the software but not in TUFLOW. The distance which
objects are considered snapped in TUFLOW can be set with the Snap Tolerance
command in TUFLOW.
4. If you are experiencing instability water levels. Follow the advice given in Section 16.3.2 and
16.3.2.1 . Otherwise, check the water level that is used for detecting instabilities (Instability
Water Level ). If every Z point elevation has not been allocated, the default elevation of
99999 will be assigned. Provided the default settings for the .tcf command Zpt Range Check
have not been altered, TUFLOW will report an ERROR message. If there are very high Z
points in your geometry (relative to your water levels), this allows any instabilities to oscillate
in a very large range. Consequently, the instability can become so extreme that floating point
errors (i.e. the computation is unresolvable) may occur before TUFLOW stops the simulation
and declares it unstable. However, in most cases there should be some water level
exceedance warnings at the end of the .tlf file and/or negative depth warnings in the
_messages GIS layer. To remedy the situation use Instability Water Level to set a realistic
maximum water level. This same effect can occur in 1D domains if the maximum height in a
node storage table or a channel cross-section is very high or the Depth Limit Factor is set
unrealistically high.
If the problem persists, please contact [email protected].
5. If you are having stability problems, check whether the computational timestep is appropriate
(see Section 3.5 , 16.2.1.1 and 16.3.2.1 ).
6. Discontinuous initial water levels, particularly at 1D/2D interfaces are a common source of
instability. If the model is going unstable near a 1D/2D interface shortly after starting, check
that the initial water levels in the 1D and 2D domains are similar and also equal to any water
level timeseries (HT) boundaries included in the model.
7. It is not possible to specify a node as a flow boundary as well as being connected to a 2D SX
boundary (which automatically applies a HX boundary to the node). This combination of flow
boundary and water level (HX) boundary is incompatible. The result is that the HX boundary
overrides the flow boundaries. An ERROR check for this occurrence is output.
8. Deep river bends with “bumpy” topography may cause instabilities in 2D models. Smoothing
the topography, rather than reducing the timestep is recommended.
9. Under-sized 1D node storage (NA tables) connected to 2D HX boundaries may cause
instabilities near the 1D/2D interface. Over-sized storage attenuates the inflow hydrograph. As
a rule-of-thumb, the node surface area should be similar to the width of the 1D/2D interface
multiplied by 3 to 10 cell widths.
10. Irregular topography just inside a 2D boundary may cause instabilities. If problems occur,
smooth the rough topography.

@1982
16.4 QA Check List and Simulation Logging

A quality assurance check of any model used for a project is recommended, even if initial
simulation appears to be trouble free and healthy. Table 16.2 presents a helpful shortlist of
general quality control checks. This list is not exhaustive, a more detailed list is available from

Section 16 Quality Control and Troubleshooting - 15 / 24 Page 647 / 1094

 Modelling Log and Review Template. Model review responsibility should be assigned to an
experienced modeller, not someone who is not familiar with TUFLOW modelling.

Section 16 Quality Control and Troubleshooting - 16 / 24 Page 648 / 1094

 @1983 Table 16.2: Quality Control Check List

Item Description Checked

A modelling log is highly recommended and should be a

requirement on all projects. The log may be in Excel, Word or
other suitable software. A review of the modelling log is to be
made by an experienced modeller. It should contain:
⋅ the TUFLOW executable version used for the modelling;
⋅ Sufficient information to record model versions during
development and calibration;
Modelling Log
⋅ Observations from simulations;
⋅ Key modelling assumptions; and
⋅ A list of data sources used.
A model version naming and numbering system needs to be
designed prior to the modelling. The version numbering system
should be reflected in input data filenames to allow traceability
and the ability to reproduce an old simulation if needed.

A review of the data file management should check:

⋅ Files are named using a logical and appropriate convention
that allows easy interpretation of file purpose and content;
⋅ A logical and appropriate system of folders is used to store
File Naming,
the files;
Structure and
⋅ Relative path names are used for input files
Management
(e.g. “..\model\geometry.tgc”) so that models are easily moved
from one folder to another.
⋅ Documentation of the above in the project Quality Control
Document and/or Modelling Log.

Check whether the 2D cell size is appropriate to reproduce the

2D Cell Size topography needed to satisfactorily meet the objectives of the
and 1D study (see Section 3.3 ), and that the 1D spatial resolution is
resolution appropriate to reproduce the water longitudinal surface
gradient.

Section 16 Quality Control and Troubleshooting - 17 / 24 Page 649 / 1094

 Item Description Checked

The topography review should focus on:

⋅ Correct interrogation of Digital Terrain Model (DTM);
⋅ Correct datum;
⋅ Modifications to the base data (e.g. breaklines) have been
checked.
Regarding the latter, can be carried out by reviewing the
_DEM_Z check file (see Table 14.3 ). Note: Reviewing the
elevations in the .2dm file is not appropriate as only the ZH Zpt
Topography is represented in the .2dm file (the ZH elevation is not used in
the hydrodynamic calculations).
1D cross-section locations and conveyance should be
reviewed. As a general rule, conveyance should steadily
increase downstream. Sudden changes in conveyance need to
be cross-checked (these are often easily identified by sudden
changes in velocities of successive channels). Are hydraulic
controls such as levees, roads and embankments represented
in the model?

Bed resistance values are to be reviewed by an experienced

modeller. The review should focus on checking:
⋅ The DEM_M check file;
⋅ The Manning_n attribute values in the uvpt_check file layer
created by Write Check Files ;
⋅ The Material attribute values in the grd_check file created by
Bed
Write Check Files ; or
Resistance
The reviewer should be looking for:
Values
⋅ Relative consistency between different land-use (material)
types; and
⋅ Values are within accepted calibration values.
GIS thematic mapping is an excellent way to visually and
quickly review the variation in bed resistance and other
parameter values.

Check that the model calibration or validation is satisfactory in

Calibration / regard to the study objectives. Identify any limitations or areas
Validation of potential uncertainty that should be noted when interpreting
the study outcomes.

Section 16 Quality Control and Troubleshooting - 18 / 24 Page 650 / 1094

 Item Description Checked

In addition to the mass balance reporting (see Section 14.8 ),

it is good practice to carry out independent mass checks.
Standard practice is to place 2d_po flow lines (see Section
11.3.2.1 ) in several locations throughout the model. They are
typically aligned roughly perpendicular to the flow direction.
The locations should include lines just inside each of the
boundaries. Other suitable locations are upstream and
downstream of key structures, through structures and areas of
particular interest.
The flows are graphed and conservation of mass checked
(i.e. the amount of water entering the model equals the amount
Mass
leaving allowing for any retention of water in the model).
Conservation
Ensure that the flows from any 1D channels crossed by a
2d_po line are also included in the mass check, and that the
2d_po flow lines are digitised so that they cross the 1D channel
where there is a change in colour of the linked 2D HX cells as
shown in the 1d_to_2d_check files or _TSMB1d2d layers.
In dynamic simulations, an exact match between upstream and
downstream will not occur due to retention of water, however,
examination of the flow lines should reflect this phenomenon.
For steady-state simulations, demonstration of reaching steady
flow conditions is demonstrated when the flow entering the
model equals the flow leaving the model.

Head losses through a structure need to be validated through:

⋅ Calibration to recorded information (if available).
⋅ Desktop calculations based on theory and/or standard
publications (e.g. Hydraulics of Bridge Waterways).
⋅ Cross-checking results using other hydraulic software.
Simple checks can be made by calculating the number of
dynamic head losses that occur and checking that this is in
accordance with what is expected (see Section 7.3.8 ).
It is important to note that contraction and expansion losses
Hydraulic
associated with structures are modelled very differently in 1D
Structures
and 2D schemes. 1D schemes rely on applying form loss
coefficients, as they cannot simulate the horizontal or vertical
changes in velocity direction and speed. 2D schemes model
these horizontal changes and, therefore, do not require the
introduction of form losses to the same extent as that required
for 1D schemes. However, 2D schemes do not model losses in
the vertical or fine-scale horizontal effects (such as around a
bridge pier) and, therefore, may require the introduction of
additional form losses. See Syme (2001b) for further details.

Check that the eddy viscosity formulation and coefficient is

Eddy Viscosity
appropriate (see Section 7.4.3 ).

Section 16 Quality Control and Troubleshooting - 19 / 24 Page 651 / 1094

 @2004
16.5 Models Exceeding Hardware RAM

In some situations TUFLOW modellers may experience an error due to the model simulation
requiring more Random-Access Memory (RAM) than is available in the computer. When this
situation occurs the following message is reported.

@2005

Figure 16.5: TUFLOW RAM Error

The error may be caused by a number of contributing factors. The following sections discuss the
common causes and recommended troubleshooting considerations to help resolve the issue.

@2006
16.5.1 Computer RAM

If a TUFLOW simulation can not allocate sufficient RAM the first check that should be made is the
amount of available RAM on the computer. What are the computers specifications and what is
already being used by other processes? This can be done in Windows Task Manager. Third party
software used to build TUFLOW models and view their results (such as GIS or CAD packages)
can consume large amounts of RAM, leaving little remaining for the TUFLOW simulation.

@2007
16.5.2 TUFLOW Version

The choice of TUFLOW version can influence the amount of RAM needed to simulate the model.
The double precision (DP) versions of TUFLOW utilise more RAM (up to twice as much) than the
single (SP) precision version, as all real numbers are 8-byte reals in the DP version, rather than 4-
byte reals in SP. Refer to Section 13.4.2 for further information on the difference between single
and double precision versions of TUFLOW.

@2008
16.5.3 Model Design

Key model design items that influence memory allocation, and should be reviewed if simulation
RAM requirements need to be reduced, include:

The size of the redundant area around the perimeter of the active model domain;
The number of 2D cells, hence the domain extent and the cell size; and
Choice of model features utilised.

The term, “redundant area” is defined as the difference between the 2D domain size and the
active model area. As discussed in Section 7.3.2 , TUFLOW automatically strips any redundant
rows/columns around the active area of the model to reduce simulation times, this however does
not reduce the amount of RAM consumed by the model. Refer to Sections 7.3.1 and 7.3.2 for
further information on defining the 2D domain and the active/inactive areas of a model.

Section 16 Quality Control and Troubleshooting - 20 / 24 Page 652 / 1094

 Figure 16.6 presents two different versions of an example model. The only difference between
both models is the size of the 2D domain. The 2d_dom check file of the models has been overlaid
on top of the active area of the model, represented by a magenta polygon (2d_code GIS layer with
CD=1).

@2009

Figure 16.6: Influence of 2D Domain Size on RAM Allocation

In this example, the green coloured 2d_dom_check in Figure 16.6 has been defined using the
.tgc command Grid Size (X,Y) == 1800, 2000. Its 2D domain extent is significantly larger
than the active area of the model (the magenta polygon).

In contrast the black coloured 2d_dom_check area in Figure 16.6 shows a much better fit to the
active area. This model domain has been defined using the .tgc command Grid Size (X,Y)
== 800, 1000.

The size of the redundant area can be determined by searching within the .tlf file for the term
“redundant”.

For larger (green) domain in the figure above, the tlf file states the following redundant area
information.

Isolating redundant perimeter sections of 2D domain Domain_001…

…Reduced computational grid by 79%. Now extends from [5,7] to [196,169].
…Reduced output grid by 79%. Now extends from [5,7] to [196,169].

It indicates TUFLOW has reduced the computation grid by 79%, meaning the active area is only
21% of the size of the 2D domain! A search for “memory” in the .tlf file shows the required memory
allocation for the model:

Memory requested for 2D domain Domain_001 = 101 Mb

Total Memory requested thus far = 104 Mb

Section 16 Quality Control and Troubleshooting - 21 / 24 Page 653 / 1094

 For smaller (black) domain in the figure above, the tlf file states the following redundant area
information.

Isolating redundant perimeter sections of 2D domain Domain_001…

…Reduced computational grid by 8%. Now extends from [5,7] to [196,169].
…Reduced output grid by 8%. Now extends from [5,7] to [196,169].

The smaller 2D domain also has a noticeable impact on the memory required to run the model. In
this case, reducing it by a factor of 5, from 104Mb to 27Mb.

Memory requested for 2D domain Domain_001 = 23 Mb

Total Memory requested thus far = 27 Mb

The 2D cell size dictates the total number of cells within a given study area, keeping in mind that
halving the cell size quadruples the number of cells. The number of cells has a direct correlation to
the amount of RAM required to run the model. For each cell, TUFLOW stores a number of
variables including depth/water level and velocity components. The greater the number of cells,
the greater the amount of information stored and therefore the greater the amount of memory
needed to simulate the model. Simulating a variety of models, each with a different cell size during
the initial model development stage, will provide a modeller with an understanding of the impact
the cell size has on simulation time, memory allocation and also model results. Refer to Section
3.3.4 for discussion on cell size convergence testing.

A number of optional TUFLOW features may also increase the simulation memory requirements.
Common features include:

Model Output Zones (Section 11.2.5 ). Adding Extra Output Zones will increase the RAM
requirement.
TIF, ASC or FLT grid raster Map Output Format (Section 11.2.2 ). Consider using these grid
raster output types for maximum reporting only. Use the XMDF or CC format for time varying
dynamic 2D Map Outputs.
Direct rainfall boundary condition inputs defined using the Read GIS RF format can require
significant amounts of RAM. Consider using a Rainfall Control File approach to define the
input instead. It requires a far smaller amount of memory.
Excessively fine TUFLOW HPC sub-grid sampling resolution.

@2010
16.5.4 Memory Usage Reporting

The TUFLOW log file (.tlf) provides a summary of the model’s memory usage. The memory usage
information can be used to identify which items of a model require the most RAM. An example is
provided below:

1D QX and HX BCs automatically detected

1D Geometry data memory …….. 18 Mb
1D Boundary data memory …….. 0 Mb
1D yQ Curves memory ………… 0 Mb
1D Control structures memory … 0 Mb
1D Mesh data memory ………… 3 Mb
1D Results storage memory …… 24 Mb
1D Temporary data memory ……. 8 Mb
1D Computational arrays memory . 0 Mb

Section 16 Quality Control and Troubleshooting - 22 / 24 Page 654 / 1094

 Total 1D domain memory (RAM) requested ………… 54 Mb
Total 1D domain character memory (RAM) requested .. 7 Mb
Domain_001 : Allocating Memory Pointers:
Domain_001 : Grid data memory …………… 47 Mb
Domain_001 : Variable Z and Layered FC memory 0 Mb
Domain_001 : Sub-domain linking memory …… 4 Mb
Domain_001 : Flow constrictions memory …… 16 Mb
Domain_001 : Weirs and viscosity factor memory 14 Mb
Domain_001 : Pressure, wind and waves memory 0 Mb
Domain_001 : General Memory …………….. 14 Mb
Domain_001 : Boundary conditions memory ….. 7 Mb
Domain_001 : Wind & waves boundary memory … 0 Mb
Domain_001 : Work arrays memory …………. 115 Mb
Domain_001 : SMS High Res format memory ….. 0 Mb

@2011
16.5.5 Temporary Memory Usage

A number of input steps may require additional memory for processing during model initialisation.
For example, when a large DEM is input (Read Grid Zpts ), this is read into memory and then
processed. This allows for a very rapid processing of the file, though may consume significant
additional memory. The DEM can be tiled to reduce memory usage at start-up. Other files that
consume additional memory are Read GIS Z Shape , as TUFLOW tracks the modified elevation
and the change in elevation for all Zpts.

The Maximum Vertices and Maximum Points commands can be used to increase or decrease
the size of a single GIS object and will change the memory required.

For models utilising TUFLOW HPC Sub-Grid Sampling (SGS) with the SGS Approach Method A
or B (default prior to 2023-03), the sub-grid sampling was undertaken during the data pre-
processing, though the raw input data not retained. In the 2023-03 TUFLOW release, a new and
improved Method C approach (default in 2023-03 and later) was introduced. Method C retains the
raw sub-grid sampled elevation information from the pre-processing stage for numerous post-
processed result features. Whilst Method C can potentially use more RAM, the approach has
considerable benefits in terms of preserving sub-grid elevation data at cells/faces partially affected
by terrain data layers and allows TUFLOW to produce high-resolution mapping at the SGS
sampling resolution.

Sub-grid sampling is a computationally intensive process, particularly for large models with small
SGS sample distances. To speed up model initialisation, TUFLOW has been configured to utilise
multiple CPU cores. By default, all CPU threads will be used for final SGS elevation pre-
processing unless the number of threads (-nt[thread count]) command line argument has been
specified. For example, to run on 8 threads the command line argument “-nt8” would be used.
There is no check for thread licensing used for pre-processing. All threads are used if the number
of threads specified in the command line argument exceeds the number of threads available.

In addition to the parallelisation of the final SGS elevation pre-processing, XF files are now
supported for SGS Method C. At the end of the .tgc reading, after all elevation datasets have been
processed, an XF file is written if the XF Files command is set to on (default). This XF file can
then be utilised in subsequent simulations, reducing memory requirements and processing time.

Section 16 Quality Control and Troubleshooting - 23 / 24 Page 655 / 1094

 @2012
16.5.6 TUFLOW HPC GPU Module and RAM requirements

When running TUFLOW HPC with the GPU Module, TUFLOW Classic carries out all the pre- and
post-processing of the data (setting up the model and storing and tracking of all output data).
These CPU tasks typically consume significantly more memory than that required to carry out the
hydraulic computations on the GPU card. Therefore, although the hydrodynamic calculations are
carried out on the GPU card/s, significant amounts of CPU RAM are also required. As a rough
guide, the CPU RAM requirement is around 4 to 6 times that of the GPU memory (with grid based
output active and set to the defaults).

@2013
16.6 Past Release Version Backward Compatibility

TUFLOW uses a unique software build identifier to track and manage new versions of the
software. This identifier has changed format in the TUFLOW 2025 release. From the 2025 release
and onwards, version numbering will use the year.minor.patch convention. The year
corresponds to the major version number e.g. this release is 2025.0.0 . Major releases are the
only releases that will admit the possibility of implementing changes to defaults, making other
breaking changes or affecting backwards compatibility. Advice will be provided on this in
corresponding changelogs (e.g. the 2025.0.0 Backward Compatibility Section). Throughout the
year, additional minor releases (releases containing new features and bug fixes, but no breaking
changes) would increment the minor version number (e.g. 2025.1.0 ) and bug fix only releases
would increment the patch version number (e.g. 2025.0.1 ). Previously, the versioning system

used year-month-xx-precision-bitOS where ‘xx’ was the two letters starting at AA then AB, AC, etc.
For precision, iSP = single precision, iDP = double precision.

The build number is written to the first line in the .tlf log files so it is clear what version of the
software was used for a simulation. For example:

Build: 2025.0.0-iSP-w64

Advances in science, subsequently built into new release versions may cause slight result
differences from one release version to another. In recognition of this, if a project is completed
using a specific version of the software, continued future use of that software version for that
particular model is recommended to achieve identical results.

During the life of TUFLOW, every effort has been made to provide full backward compatibility to
past release versions. Chapter 18 lists code changes that may cause a change in model result. If
a legacy or old model is being upgraded to the latest TUFLOW release, it is recommended that
you familiarise yourself with possible changes to the default settings that may change results, and
make the necessary changes as appropriate. In nearly all cases a backward compatibility switch is
provided so that new builds can reproduce past build results (see Defaults ). In rare cases exact
byte identical replication of a past build result may not be possible using a new release version
because different compiler versions were used to create the respective executables.

Section 16 Quality Control and Troubleshooting - 24 / 24 Page 656 / 1094

 @2018

@2019
Section 17 Utilities

@2020
17.1 Introduction

The TUFLOW Utilities are a set of tools that can be used to convert input data for use in a
TUFLOW model, or to process / manipulate the raw 2D result files produced from a model
simulation. Many of the utilities are DOS executables similar to the TUFLOW engine, however
some are macros for use in Excel or Python scripts. GIS based utilities have also been developed
for QGIS, ArcGIS, and MapInfo.

The utilities do not require a TUFLOW licence to utilise.

@2021
17.2 GIS Based Utilities

@2022
17.2.1 QGIS TUFLOW Plugin

If you are using QGIS as your model development or result viewing environment, we strongly
recommend installing the TUFLOW QGIS Plugin. It includes numerous tools to increase workflow
efficiency and powerful result viewing functionality via its TUFLOW Viewer. After installing, the
tools can be found within the TUFLOW QGIS Plugin Menu or the QGIS TUFLOW Processing
Toolbox.

Section 17 Utilities - 1 / 6 Page 657 / 1094

 @2023 Table 17.1: QGIS TUFLOW Plugin - Tools

Category Tool Example

Create or Configure
TUFLOW Project

Import Empty
(template GIS file)

Insert TUFLOW
Attributes to
Existing Layer

Editing Tools Increment Selected

Layer

Reload Data

Arch Bridge Editor -

shown in example
image.

Copy TUFLOW
Command

TUFLOW Runner -
shown in example
image.

Run Tools Run TUFLOW

simulation

Running TUFLOW
Utilities

Section 17 Utilities - 2 / 6 Page 658 / 1094

 Category Tool Example

TUFLOW Viewer -
shown in example
image.

Applying TUFLOW
styles

Import Check Files

From Folder

Load TUFLOW
Visualisation Layers From TCF
Tools
Filter and Sort
TUFLOW Layers

Apply GPKG Layer

Names

Apply Label to
Current Layer

Apply Stability
Styling

ARR to TUFLOW -
shown in example
Hydrology image.
Tools
ReFH2 to TUFLOW

SCS to TUFLOW

1D Integrity Tool -
Integrity Tools shown in example
image.

Section 17 Utilities - 3 / 6 Page 659 / 1094

 Category Tool Example

Convert TUFLOW
Model GIS Format
Processing
Toolbox Package Model -
shown in example
image.

This QGIS Plugin is actively developed, with new versions released frequently. Please send any
feedback, recommendations or new feature ideas to [email protected].

@2024
17.2.2 ArcGIS Pro Toolbar

The ArcGIS Pro Toolbar, shown in Figure 17.1 , helps with streamlining the process of creating
and editing a TUFLOW model in ArcGIS Pro. It is available for download on the TUFLOW Website.
For information on installation and the tools available within the ArcGIS Pro Toolbar, see the
TUFLOW Wiki.

@2025

Figure 17.1: ArcGIS Pro TUFLOW Toolbar

The ArcGIS Pro Toolbar is actively developed. Please send any feedback, recommendations or
new feature ideas to [email protected].

@2026
17.2.3 ArcMap Toolbox

The ArcMap Toolbox is available for ArcMap version 10.1 and newer. The toolbox helps with
streamlining the process of creating and editing a TUFLOW model in ArcMap. For more
information on the ArcMap Toolbox, see the TUFLOW Wiki.

The ArcMap Toolbox is no longer actively developed.

@2027
17.2.4 MiTools

MapInfo and TUFLOW Productivity Utilities (miTools) were developed to improve the efficiency of
setting up and reviewing TUFLOW models, as well as improving the day to day ease of using
MapInfo Professional. For information on miTools, see the TUFLOW Wiki.

Section 17 Utilities - 4 / 6 Page 660 / 1094

 MiTools are no longer actively developed.

@2028
17.3 Console Utilities

The TUFLOW Console Utilities are like the TUFLOW engine in that they are command window
executables with no user interface. They are available for download from the TUFLOW Website.

The TUFLOW Wiki provides a comprehensive list of available options for each utility along with
further examples.

Please send any feedback, recommendations or suggestions on the Utilities to

[email protected].

@2029
17.3.1 Pre and Post Processing

The following utilities are available to assist in pre and post processing:

ASC_to_ASC
TIN_to_TIN
xsGenerator
TUFLOW_to_GIS
RES_to_RES
Convert_to_TS1
12da_to_from_GIS

These Utilities can also be downloaded and run directly through the TUFLOW QGIS Plugin.

@2030
17.3.2 Convert to TUFLOW

The following utilities are available to assist in converting model files from other software to
TUFLOW:

HECRAS_to_TUFLOW
FLO2D_to_TUFLOW
SWMM_to_TUFLOW
Flood_Modeller_to_TUFLOW
MIKE_Flood_to_TUFLOW

Refer to the relevant pages to view the details with regards to the conversion approach.

@2031
17.3.3 Textfile Syntax Highlighting

As described in Section 2.2 , TUFLOW requires the use of control files to bring together the
various GIS and tabular datasets as well as TUFLOW specific commands. To assist in the creation
and review of the control files, syntax highlighting tools have been developed and are available for
the following text file editors:

Notepad++
VSCode

Section 17 Utilities - 5 / 6 Page 661 / 1094

 Ultraedit
Textpad

An example of the syntax highlighting is shown in Figure 2.2 .

@2032
17.3.4 PyTUFLOW

PyTUFLOW is a package of Python tools for extracting TUFLOW time series results. It can be
used to automate output tasks such as checking model health, goodness-of-fit for model
calibration, viewing on-the-fly model output (used in conjunction with Write PO Online ==
ON), and high-volume output plotting from production runs. An example of its use for generating
calibration plots can be seen here.

More information about the PyTUFLOW package can be found on the TUFLOW Wiki.

For worked examples demonstrating the use of PyTUFLOW, please register for the free
Introduction to Python for TUFLOW eLearning Course.

@2033
17.3.5 Excel Macros

A set of Excel TUFLOW Tools is available for download here. These tools can help with the set up
and review of tabular data for input into TUFLOW as well as the review of tabular outputs. Further
description of the tools, including setup instructions, is available on the TUFLOW Wiki.

Section 17 Utilities - 6 / 6 Page 662 / 1094

 @2038

@2039
Section 18 Default Changes

This chapter lists default changes between major releases. For a full list of changes (not only
default changes) between versions since the 2023-03-AF release, see the TUFLOW Classic/HPC
Changelog. For versions 2023-03-AF and prior, see the relevant release notes in the TUFLOW
Downloads Archive.

@2040
18.1 2025.0 Release

Table 18.1 outlines the changes made to the default settings for the 2025.0 release and lists
commands to revert the settings to those used by the prior major release group (2023-03). All
default settings can be reverted to the prior release by using the command, “Defaults == Pre
2025”. For more information on changes, see the TUFLOW Classic/HPC Changelog.

Section 18 Default Changes - 1 / 18 Page 663 / 1094

 @2041
Table 18.1: Default Changes in the 2025.0 Release and Backward Compatibility to 2023-03

Backward Compatibility
Description
Command

Defaults == PRE
Reset all defaults to that used by the 2023-03 release.
2025

The format of a TIN written when the WRITE TIN command is

used with Z Shapes or write TIN commands was changed. The
TIN Output Format
new default (2DM) writes the TIN using the SMS 2DM mesh
== SMS TIN
format, which can be read in by QGIS and SMS. The previous
default (SMS TIN) wrote a TIN that could only be read by SMS.

The default value for the HPC HQ Boundary Filter Constant has
HPC HQ Boundary
been set to 5. This can provide improved stability for HQ
Filter Constant ==
boundaries. For backwards compatibility, set this to 1. See
1
Section 8.3.2.2 .

Internally, HPC multiplies the Nu, Nc, Nd control number limits by

a dynamic control factor. Method A considers that a high control
number step has occurred if any of Nu, Nc, Nd has exceeded the
HPC Timestep
dynamic control number limits (i.e. after the dynamic control
Approach == Method
factor has been applied) by the 20% margin. Method B (the
A
2025.0 default) applies the test using the original static limits
(i.e. before the dynamic control factor has been applied). For
more information see Section 3.5.4 .

A CHECK option has been added to the HPC DP Check

command and set as the new default. This downgrades the HPC DP Check ==
previous default from ERROR. For more information see Section ERROR
13.4.2.2 .

@2042
18.2 2023-03 Release

Table 18.2 outlines the changes made to the default settings for the 2023-03 release and lists
commands to revert the settings to those used by the prior major release group (2020-10). All
default settings can be reverted to the prior release by using the command, “Defaults == Pre
2023”. For more information on changes, see the 2023-03 Release Notes.

Section 18 Default Changes - 2 / 18 Page 664 / 1094

 @2043
Table 18.2: Default Changes in the 2023-03 Release and Backward Compatibility to 2020-10

2023-03 Backward Compatibility

Description of Change
Release Notes Command

Quadtree BC
Change to quadtree handling of inertial Parallel Inertia
Section 6.4
parallel to boundary Approach == Method
A

Viscosity
Upper limiting Manning’s n in Wu turbulence
Section 5.7.1 Coefficient == ⟨
calculation
C3D, C2D, 99⟩

No specific command -
Duplicate Materials IDs Section 2.7.2 Defaults == Pre
2023

No specific command -
Duplicate Soil IDs Section 2.7.3 Defaults == Pre
2023

No specific command -
Duplicate SA Boundaries Section 6.10.2 Defaults == Pre
2023

HPC Weir Approach

HPC Weir Approach Section 5.2
== Method A

HPC SX Momentum
HPC SX Momentum Section 5.2 Approach == Method
A

HPC Boundary
HPC Boundary Approach Section 6.6 Approach == Method
B

No specific command -
Initial Moisture and Green-Ampt infiltration Section 2.3.9 Defaults == Pre
2023

No specific command -
2d_bc QT Point Boundaries (Classic/HPC)
Section 6.7 Defaults == Pre
Unsupported
2023

No specific command -
2d_bc HQ Point Boundaries
Section 6.8 Defaults == Pre
(Classic/HPC/Quadtree) Unsupported
2023

SGS Approach ==
SGS Approach Section 2.2.2
Method B

SGS Depth Output

SGS Depth Output Section 2.2.1
== Exact

Section 18 Default Changes - 3 / 18 Page 665 / 1094

 2023-03 Backward Compatibility
Description of Change
Release Notes Command

SGS Map Extent Full

Mapping of partially wet SGS cells Section 2.2.1
== h

HR Interpolation
High Resolution raster output interpolation
Section 2.2.5 Approach == Method
method
A

HR Thin Z Line
High resolution thin breaklines Section 2.2.6 Output Adjustment
== OFF

@2046
18.3 2020-10 Release

Table 18.3 outlines the changes made to the default settings for the 2020-10 release and lists
commands to revert the settings to those used by the prior major release group (2020-01). All
default settings can be reverted to the prior release by using the command, “Defaults == Pre
2020-10”. For more information on changes, see the 2020-10 Release Notes.

@2047
Table 18.3: Default Changes in the 2020-10 Release and Backward Compatibility to 2020-01

2020-10 Backward Compatibility

Description of Change
Release Notes Command

No backward
Timestepping change Section 6.3.8
compatibility setting.

No backward
Quadtree only Wu turbulence fix Section 6.3.7
compatibility setting.

Quadtree only thick z-shapes and boundaries No backward

Section 3.1.8
fix compatibility setting.

Map Output Vector

Vector output at dry Z points Section 7.11.12
Dry Zpts == ON

Map Cutoff Vector

Map cutoff for vector output values Section 7.11.13
== OFF

HPC HQ Boundary
Support for Classic style HQ curve Section 6.7
Approach == CELL

GIS Project Path

Relative filepaths for GIS workspaces Section 7.10.4
Format == ABSOLUTE

Section 18 Default Changes - 4 / 18 Page 666 / 1094

 @2048
18.4 2020-01 Release

Table 18.4 outlines the changes made to the default settings for the 2020-01 release and lists
commands to revert the settings to those used by the prior major release group (2018-03). All
default settings can be reverted to the prior release by using the command, “Defaults == Pre
2020-01”. For more information on changes, see the 2020-01 Release Notes.

@2049
Table 18.4: Default Changes in the 2020-01 Release and Backward Compatibility to 2018-03

2020-01 Backward Compatibility

Description of Change
Release Notes Command

Viscosity
Turbulence scheme changed Section 5.1 Formulation ==
Smagorinsky

Improvement to dry wall treament for eddy Viscosity Approach

Section 5.2.3
viscosity == Method A

HPC Mannings Depth

Flow depth used for bed friction calculation Section 5.3 Approach == Method
A

HPC Boundary
Improvement to HPC water level boundaries Section 6.1 Approach == Method
A

@2050
18.5 2018-03 Release

Table 18.5 outlines the changes made to the default settings for the 2018-03 release and lists
commands to revert the settings to those used by the prior major release group (2017-09). There
is no “Defaults == Pre 2018” command provided for the 2018-03 release. For more
information on changes, see the 2018-03 Release Notes.

@2051
Table 18.5: Default Changes in the 2018-03 Release and Backward Compatibility to 2017-09

2018-03 Backward Compatibility

Description of Change
Release Notes Command

For TUFLOW HPC an enhancement to the Pit Default

extrapolation of Pit curves to provide Section 2.1.4 Extrapolate Q Curve
consistency with Classic was implemented. == OFF

The treatment of unconnected pits, which

previously would trigger an ERROR, has Pit No 1D
changed to apply these pits as a virtual pipe Section 2.1.5 Connection ==
pit that discharges water directly out of the ERROR
model.

Advanced index feature added to significantly Index 1D2D Links

Section 4.1
improve 1D/2D model simulation speeds. == OFF

Section 18 Default Changes - 5 / 18 Page 667 / 1094

 @2052
18.6 2017-09 Release

Table 18.6 outlines the changes made to the default settings for the 2017-09 release and lists
commands to revert the setting to those used by the prior major release group (2016-03). All
default settings can be reverted to the prior release by using the command, “Defaults == Pre
2017”. For more information on changes, see the 2017-09 Release Notes.

@2053
Table 18.6: Default Changes in the 2017-09 Release and Backward Compatibility to 2016-03

2017-09 Backward Compatibility

Description of Change
Release Notes Command

Set Defaults == PRE

2017 if similar results are
New SX boundaries defaults. Section 4.5
required to the 2016-03-
AE release.

Set Defaults == PRE

2017 or use XF Files
XF files are now being processed for Boundaries ==
Section 4.1
boundaries. OFF if similar results are
required to the 2016-03-
AE release.

Regions in 2d_bc layers now applied as

No backward compatible
regions (previously only cell over region Section 4.5.4
workaround provided.
centroid selected).

Material IL and CL now applied to gridded No backward compatible

Section 4.3
rainfall (previously not applied). workaround provided.

SA regions now always select a 2D cell even

if there are no cell centres falling within the
No backward compatible
region (previously a SA region would not Section 4.4
workaround provided.
select any cell if no cell centres fell within the
region).

If using “Reveal 1D Nodes == ON”,

No backward compatible
“Time Series Output Interval == ” Section 9.2
workaround provided.
must be specified.

@2054
18.7 2016-03 Release

Table 18.7 outlines the changes made to the default settings for the 2016-03 release and lists
commands to revert the setting to those used by the prior major release group (2013-12). All
default settings can be reverted to the prior release by using the command, “Defaults == Pre
2016”. For more information on changes, see the 2016-03 Release Notes.

Section 18 Default Changes - 6 / 18 Page 668 / 1094

 @2055
Table 18.7: Default Changes in the 2016-03 Release and Backward Compatibility to 2013-12

2016-03 Backward Compatibility

Description of Change
Release Notes Command

Set Defaults == PRE

2016 if similar results are
New operational 1D structure defaults. Section 4
required to the 2013-12-
AC release.

Set Defaults == PRE

Primary upstream and downstream 1D
2016 if similar results are
channels now correctly take into account bed Section 6
required to the 2013-12-
slope.
AC release.

Set Layered FLC

Default Approach
== CUMULATE or
A new layered 2D FC calculation method has
Section 8 use Defaults == PRE
been implemented.
2016 if similar results are
required to the 2013-12-
AC release.

Set Defaults == PRE

2016 or use SX Flow
Distribution Cutoff
The SX Flow Distribution Cutoff Depth has
Section 11 Depth == 0.0 if
been raised to 0.005m from 0.0m.
similar results are
required to the 2013-12-
AC release.

Set Defaults == PRE

The “End After Maximum == ” tolerance 2016 if similar results are
Section 21
has been increased to 0.001m from 0.0m. required to the 2013-12-
AC release.

Set Defaults == PRE

A new ERROR message has been added to
2016 if similar results are
cross-check the 1D timestep is a multiple of Section 49
required to the 2013-12-
the timestep for all 2D domains.
AC release.

WARNING 2460 has been escalated to an

Set Defaults == PRE
ERROR and stricter command line syntax
2016 if similar results are
rules have been introduced (“=” will now Section 50
required to the 2013-12-
return an ERROR message if TUFLOW is
AC release.
expecting “==”)

Section 18 Default Changes - 7 / 18 Page 669 / 1094

 2016-03 Backward Compatibility
Description of Change
Release Notes Command

Set GPU Viscosity

The treatment of the eddy viscosity term in
Method == Method A
the GPU Solver has been enhanced in the
or use Defaults ==
2016-03-AD build with slightly improved Section 145
PRE 2016 to achieve the
results in areas of rapidly changing velocity
same results as Build
patterns.
2013-12-AC and prior.

@2056
18.8 2013-12 Release

Table 18.8 outlines the changes made to the default settings for the 2013-12 release and lists
commands to revert the setting to those used by the prior major release group (2012-05). All
default settings can be reverted to the prior release by using the command, “Defaults == Pre
2013”. For more information on changes, see the 2013-12 Release Notes.

Section 18 Default Changes - 8 / 18 Page 670 / 1094

 @2057
Table 18.8: Default Changes in the 2013-12 Release and Backward Compatibility to 2012-05

2013-12 Backward Compatibility

Description of Change
Release Notes Command

For BW or IW channels that automatically

insert a weir over the B or I channel, the weir
width if not manually specified using the EN1 Structure Routines
Section 27
attribute is now based on the maximum width == ORIGINAL
of the B or I channel, rather than the width at
the channel’s invert.

“E” and “H” flags for RG, SG, SP and all new
Structure Flow
weirs set whether to use energy (E) or water Section 41
Levels == WATER
surface (H) levels for the calculations.

For W (weir) channels, “Weir Approach ==

Weir Approach ==
METHOD A” has been reinstated as the Section 68
METHOD B
default setting.

The approach for processing 2d_po flow lines

has been reworked and will now not slow
PO Approach ==
down a simulation if numerous 2d_po flow Section 1
METHOD A
lines exist as was occurring with prior
releases.

Output 1D .csv files to a csv folder in a

Time Series Output
slightly new format that works with our new Section 18
Format == PRE 2013
GIS 1D chart viewer.

Map Output Corner

New interpolation/extrapolation methods to
Section 5 Interpolation ==
the 2D cell corners.
METHOD A

When the Maximum Courant Number is

Maximum Courant
greater than zero, adaptive time-stepping is
Number == 0.3 (only
switched on. For the 4th order time solver a Section 1
applies if GPU Solver
value of 1.0 (the new default) is
== ON)
recommended.

Tracks and outputs the maximums every Maximums and

Section 1
timestep. Minimums == OFF

Changes the default to “INCLUDE TIME” for

Write Restart
restart files so filenames are time-stamped
Section 64 Filename ==
and written for each restart output time, and
OVERWRITE
the files are placed in a folder called “trf”.

The default setting for Link 2D2D Approach Link 2D2D Approach
Section 68
has changed. == METHOD B

Section 18 Default Changes - 9 / 18 Page 671 / 1094

 @2058
18.9 2012-05 Release

Table 18.9 outlines the changes made to the default settings for the 2012-05 release and lists
commands to revert the setting to those used by the prior major release group (2011-09). All
default settings can be reverted to the prior release by using the command, “Defaults == Pre
2012”. For more information on changes, see the 2012-05 Release Notes.

@2059
Table 18.9: Default Changes in the 2012-05 Release and Backward Compatibility to 2011-09

2012-05 Backward Compatibility

Description of Change
Release Notes Command

The approach to the sizing of automatic

Manhole Approach
manholes and the application of losses has Section 48
== METHOD A
been enhanced.

Uses an improved method for interpolating M Channel Approach

Section 91
into the matrix for 1d_nwk M channels. == METHOD A

Proportions SA inflows according to the depth

of water. This feature also enhances SA
SA Proportion to
inflows by applying an inflow in proportion to Section 7
Depth == OFF
the depths of water of the wet cells contained
within the SA polygon.

Enhanced wetting algorithm that provides Wetting and Drying

significant improvement to inflows on steep == ON (2012-05 default
areas (eg. direct rainfall models), whilst Section 47 is Wetting and
maintaining low mass error, greater stability Drying == ON
and often larger timesteps. METHOD B)

The default viscosity coefficients have been Viscosity

changed to 0.5 Smagorinsky coefficient and Section 57 Coefficient ==
2
0.05m /s constant. 0.2, 0.1

Tracking of maximums and minimums every Maximums and

timestep for PO and LP output made Section 27 Minimums Time
available and set as default. Series == OFF

Enhancement to automatic 2D HQ HQ Boundary

boundaries that if the consecutive flow values Section 106 Approach == METHOD
are the same. A

@2060
18.10 2011-09 Release

Table 18.10 outlines the changes made to the default settings for the 2011-09 release and lists
commands to revert the setting to those used by the prior major release group (2010-10). All
default settings can be reverted to the prior release by using the command, “Defaults == Pre
2011”. For more information on changes, see the 2011-09 Release Notes.

Section 18 Default Changes - 10 / 18 Page 672 / 1094

 @2061
Table 18.10: Default Changes in the 2011-09 Release and Backward Compatibility to 2010-10

2011-09 Backward Compatibility

Description of Change
Release Notes Command

The optimised compiler code is treated

differently for Single Precision builds
Release Notes No workaround.
producing slightly different results (fractions
of a mm) for some models.

@2062
18.11 2010-10 Release

Table 18.11 outlines the changes made to the default settings for the 2010-10 release and lists
commands to revert the setting to those used by the prior major release group (2009-07). All
default settings can be reverted to the prior release by using the command, “Defaults == Pre
2010”.

@2063
Table 18.11: Default Changes in the 2010-10 Release and Backward Compatibility to 2009-07

2010-10 User Backward Compatibility

Description of Change
Manual Command

New Intel Fortran Compiler version produces

slightly different results (usually fractions of a Section 9.5 No workaround.
mm).

No workaround. Use the

same platform (w32 or
w32 and w64 versions will give slightly w64) for all simulations.
Section 9.5
different results for the same simulation. Use Model Platform
to force which platform
should be used.

Set Defaults == PRE

2010-10 if similar results
New default settings. Section 9.5
are required to the 2008-
08 or 2009 07 releases.

Generation of TINs for polygons in Read GIS

Shape layers is more robust and uses an
improved approach. In rare cases, the TIN Section 9.5 No workaround.
would fail and TUFLOW would abort the
start-up.

@2064
18.12 2009-07 Release

No default changes were made in the 2009-07 release. For feature changes, see the 2009-07
Release Notes.

Section 18 Default Changes - 11 / 18 Page 673 / 1094

 @2065
18.13 2008-08 Release

Table 18.12 outlines the changes made to the default settings for the 2008-08 release and lists
commands to revert the setting to those used by the prior major release group (2007-07). All
default settings can be reverted to the prior release by using the command, “Defaults == Pre
2008-08”. For more information on these changes, see the 2008-08 Release Notes.

Section 18 Default Changes - 12 / 18 Page 674 / 1094

 @2066
Table 18.12: Default Changes in the 2008-08 Release and Backward Compatibility to 2007-07

Command Change Description of Change

The new defaults produce slightly different

results, and very slight differences also occur
between the three versions offered. For
established models run using the 2007-07-
XX builds, use Defaults == PRE 2008-
08 to use the default settings used by the
Uses a new set of defaults for a number of
2007-07-XX builds. Testing of a range of
commands.
models has shown zero change in results if
Defaults == PRE 2008-08 switch is set,
and the Compaq Fortran compiled version
(cSP) is used. Each of the new default
settings and their effects are discussed in the
rows below.

The method for interpolating n values where

Generally has little effect other than when the
the 2D Manning’s n varies with depth has
flow is predominantly in the depth range that
been enhanced from a linear interpolation of
the n value is varying. The new approach
the M (1/n) value to a spline interpolation of
offers a smoother transition in n values from
the n value. See Bed Resistance Depth
one depth to the other.
Interpolation == .

The default viscosity coefficient is now a

This has slight effect for the majority of
combination of a 0.2 Smagorinsky and 0.1
models. For fine grid models (<2m cell size)
constant coefficient, and there are some
with low bed resistance and significant
enhancements to the application of the
variations in velocity vectors the effect is
viscosity term. See Viscosity
more pronounced but is still slight.
Coefficient .

Inertia and viscosity terms are now not

transferred across dry cell sides when
Generally little effect, but can have some
constructing the coefficients for the solution
minor influence for urban models where
arrays. This was having the effect of
buildings and fences are modelled as solid
generating a circulation on the other side of
thin Z lines.
the wall (albeit a very weak one), which of
course shouldn’t happen!

1D weir flow has been improved as the water

level difference across the weir approaches Very little difference other than improved
zero. The new method is more stable. stability.
See Weir Flow .

Incorporates minor improvements for

transitioning between Regimes A and B, and Very little difference other than improved
between inlet and outlet controlled regimes, stability.
for circular culverts.

Section 18 Default Changes - 13 / 18 Page 675 / 1094

 Command Change Description of Change

The new automatic selection of cells for 2D

SX connections using the 1d_nwk Very little difference other than improved
Conn_1D_2D attribute may choose more stability at the pit 2D connections.
than one 2D cell.

Set Shallow Depth Stability Factor

The default setting for Shallow Depth == 3 for models without direct rainfall to
Stability Factor has changed in the achieve the same results as Builds 2008-08-
2008-08-AC release. AA and 2008-08-AB. See Shallow Depth
Stability Factor for more information.

@2067
18.14 2007-07 Release

Table 18.13 outlines the changes made to the default settings for the 2007-07 release and lists
commands to revert the setting to those used by the prior major release group (2006-06). All
default settings can be reverted to the prior release by using the command, “Defaults == Pre
2007-07-AA”. For more information on these changes, see the 2007-07 Release Notes

Section 18 Default Changes - 14 / 18 Page 676 / 1094

 @2068
Table 18.13: Default Changes in the 2007-07 Release and Backward Compatibility to 2006-06

Command Change Description of Change

The new defaults may produce slightly

different results. For established models run
using the 2006-06-XX builds, use Defaults
Uses a new set of defaults for a number of
== PRE 2007-07-AA to use the default
commands.
settings used by the 2006-06-XX builds.
Each of the new default settings and their
affects are discussed in the rows below.

Will not cause different results if a Set Mat

Change Zero Material Values to == 1 is specified before other material
One == OFF (previously ON) settings in the .tgc file, or if every cell has
been assigned a material value.

Testing thus far has not shown any difference

Inside Region == Method B between the two methods (other than the
(previously Method A) substantial gains in processing time of
polygons).

May change results slightly, but improved

Line Cell Selection == Method
stability and a smoother water levels along
D (previously Method C)
HX lines result.

May change results slightly, but stability

VG Z Adjustment == MAX
should be significantly enhanced in some
ZC (previously ZC)
situations.

Will influence results, usually slightly, but

Bed Resistance Cell Sides == more pronounced where there are sudden
INTERROGATE (previously AVERAGE M) changes in Manning’s n values such as in the
urban environment.

The most significant influences are the

selection of upstream or downstream
Culvert Flow == Method D (previously controlled regimes depending on the H/D
Method C) ratio, and the bug fix relating to Regime E if
Culvert Critical H/D == Structure Losses == ADJUST. Offers
OFF (previously 1.5) improved stability, better convergence for
Regime C and smoother transitioning
between some regimes.

Changed the setting of the default width (if

eN1 < 0.001) of automatic weirs over R and For backward compatibility, original weir
C channels (i.e. RW and CW) to be the width can be set by manually setting the eN1
diameter/width multiplied by the number of attribute to the Diameter_or_Width attribute
culverts (previously, the width was not value of the culvert.
multiplied by the number of culverts).

Section 18 Default Changes - 15 / 18 Page 677 / 1094

 Command Change Description of Change

Bug fix that when using a restart file

No backward compatible workaround
TUFLOW occasionally set the 2D FC bridge
provided.
deck additional loss value incorrectly.

May cause slight changes in results.

Backward compatibility provided if Defaults
Bug fix that incorrectly set the water levels on
== PRE 2007-07-AA is set (noting that
dried VG cells (only applies to simulations
setting this command reinstates the bug).
with source inflows, e.g. SA or RF,
This bug also causes the mass error
somewhere within in the model).
calculations to falsely give a mass error that
is not occurring.

Backward compatibility applied if Defaults

== PRE 2007-07-AA is set, however,
Fixed bug that did not correctly apply the note that this reinstates the bug and the
reduction in conveyance for a FC BD (bridge resistance to flow at FC BD and FD cells may
deck) of FD (floating deck) cell using the need to be reviewed. Indications are that only
2d_fc Mannings_n attribute. minor changes in results occur. The flow area
under 2D FC BD and FD cells is correctly
calculated.

@2069
18.15 2006-06 Release

Table 18.14 outlines the changes made to the default settings for the 2006-06 release and lists
commands to revert the setting to those used by the prior release. All default settings can be
reverted to the prior release by using the command, “Defaults == Pre 2006-06-AA”.

Section 18 Default Changes - 16 / 18 Page 678 / 1094

 @2070
Table 18.14: Default Changes in the 2006-06 Release and Backward Compatibility to 2005-05

Command Change Description of Change

The new defaults will produce different

results. For established models run using the
Uses a new set of defaults for a number of 2005-05-XX builds, use Defaults == PRE
commands. 2006-06-AA to use the previous default
settings. Each of the new default settings and
their affects are discussed in the rows below.

The most pronounced effect of the shallower

wet/dry depths is likely to occur in areas that
Cell Wet/Dry Depth ==
are still filling at the flood peak, such as
0.002 (previously 0.05) and Cell Side
behind a levee that is only just overtopped.
Wet/Dry Depth == 0.001 (previously
The shallower wet/dry depths provides a
0.03)
greater flow depth for a longer period over
the levee.

Usually does not have a major influence on

Adjust Head at ESTRY Interface
results except where very high velocities
== OFF (previously ON)
occur.

May select slightly different cells along

Boundary Cell Selection == Method
boundary/link lines. This may cause a
C (previously Method A) and Line Cell
difference where the line is along the top of
Selection == Method C (previously
levee, possibly creating a “hole” in
Method A)
embankment.

Can have a significant effect where the

Viscosity Formulation ==
viscosity term is influential. This occurs
Smagorinsky (previously Constant)
where the friction term is less dominant
and Viscosity Coefficient ==
(i.e. low Manning’s n and/or deeper water
0.2 (previously 1.0)
such as the lower, tidal, reaches of rivers).

Can have a significant affect in the vicinity of

structures within a 1D network and for culvert
Structure Losses ==
networks. Does not affect 1D structures
ADJUST (previously FIX)
linked to a 2D domain or at the structure
ends not connected to another 1D channel.

Usually negligible effect unless the model

storage is predominantly within 1D closed
sections (i.e. B, C and R channels). The 1D
domain is likely to be more sensitive to
Storage Above Structure Obvert
instabilities due to the much smaller storage
(%) == 5 (previously CHANNEL WIDTH)
above the top of the closed sections,
therefore, a smaller 1D timestep may be
required and/or the Storage Above Structure
Obvert (%) increased.

Section 18 Default Changes - 17 / 18 Page 679 / 1094

 Command Change Description of Change

No effect as previously the model would have

Depth Limit Factor == 10 (previously
become “unstable” as the trigger for an
1)
instability was the top of the channel/node.

Culvert Flow == Method C (previously Usually only minor effects plus improved
Method B) stability.

Culvert Add Dynamic Head ==

Minor influence.
ON (previously OFF)

Negligible influence plus improved stability.

However, note the different treatment of
Bridge Flow == Method B (previously
energy losses once the bridge deck
Method A)
obvert/soffit is submerged if a BG or LC table
is specified.

Only affects the presentation of results. Note,

WLL Approach == Method B (previously
that Method A is no longer recommended or
Method A)
supported.

Does not affect hydraulic calculations,

however, if a Blank, B or W channel is now
Apply All Inverts == ON (previously
lowered/raised because the inverts are now
OFF)
used, this will affect results/stability - see
note at end of Apply All Inverts ).

@2071
18.16 Pre 2006-06 Release

For backward compatibility of builds prior to the 2006-06 release, contact [email protected].

Section 18 Default Changes - 18 / 18 Page 680 / 1094

 @2076

@2077
Appendix A TCF Commands

The TUFLOW Control File (.tcf) is the main control file used to execute a TUFLOW simulation. It includes reference to the second level control
files used to consolidate model commands (for geometry, boundaries, 1D domain, events, etc.). It also lists the simulation parameters that
define the solver settings, time controls and simulation outputs. The available TCF commands are listed below and detailed in Table A.1 .

AD Control File Blockage Matrix CSV Header Line

Adjust Head at ESTRY Interface Blockage Matrix File CSV Maximum Number Columns
Auto Terminate dV Cell Tolerance Blockage Method CSV Time
Auto Terminate dV Value Tolerance Blockage Override Defaults
Auto Terminate Start Time Blockage PMF AEP Define Output Zone
Auto Terminate Wet Cell Tolerance Blockage PMF ARI Demo Model
BC Control File Blockage Return Period Density of Air
BC Database Blue Kenue Start Date Density of Water
BC Event Name Boundary Viscosity Factor Depth/Ripple Height Factor Limit
BC Event Source BSS Cutoff Depth Display Water Level
BC Event Text Calibration Points MI File Distribute HX Flows
BC Wet/Dry Method Cell Side Wet/Dry Depth End 1D Domain
BC Zero Flow Cell Size End 2D Domain
Bed Resistance Cell Sides Cell Wet/Dry Depth End After Maximum
Bed Resistance Depth Interpolation Change Zero Material Values to One End After Maximum Start Time
Bed Resistance Values Check Inside Grid End Define
BG FLC Default Approach Check MI Save Date End Map Output
Blank BG FLC Approach Check MI Save Ext End Time
Blockage AEP Command Line Processing ESTRY Control File
Blockage ARI Control Number Factor Event File
Blockage Default CPU Threads Excel Start Date

Appendix A TCF Commands - 1 / 147 Page 681 / 1094

 External Stress File GPU Peer to Peer Access If Event
FEWS Geodatum GPU Solver If Scenario
FEWS Input File GPU Temporal Scheme Index 1D2D Links
File Retry Max Count Grid Format Input Drive
File Retry Timeout Grid Output Cell Size Inside Region
First Sweep Direction Grid Output Origin Instability Water Level
Force File IO Display Groundwater Blend Threshold Latitude
Free Overfall Hardware Layered FLC Default Approach
Free Overfall Factor HEC-DSS Start Date Line Cell Selection
Froude Check HPC Link 2D2D Adjust Velocity Head
Froude Depth Adjustment HPC 1D Synchronisation Link 2D2D Approach
GA Convergence Value HPC Boundary Approach Link 2D2D Distribute Flow
GA Maximum Iterations HPC Device Split Link 2D2D Global Stability Factor
Geometry Control File HPC DP Check Log Folder
GIS Format HPC Dry Face Inertia Approach Map Cutoff Depth
GIS Grid Vector Direction HPC dt Write Interval Map Cutoff SGS
GIS Grid Vector SF HPC HQ Boundary Approach Map Cutoff Vector
GIS Grid Vector TTF HPC HQ Boundary Filter Constant Map Output Corner Interpolation
GIS Grid Vector Type HPC Infiltration Drying Approach Map Output Data Types
GIS Project Path Format HPC Mannings Depth Approach Map Output Entire Model
GIS Projection Check HPC Non-Newtonian Mixing Exponent Map Output Format
GIS Supported Object Ignored HPC Restart Geometry Map Output Interval
GIS Unsupported Object HPC SX Momentum Approach Map Output Vector Dry Zpts
Global FC Ch Factor HPC Temporal Scheme Mass Balance Corrector
Global Rainfall Use Material Loss HPC Timestep Approach Mass Balance Output
Global Weir Factor HPC Weir Approach Mass Balance Output Interval
GPKG Compression HQ Boundary Approach Maximum 1D Channels
GPKG Compression Predictor HR Grid Output Cell Size Maximum Courant Number
GPKG Conversion Check HR Grid Output Use Face Elevations Maximum Points
GPKG Inputs Read Only HR Interpolation Approach Maximum Velocity Cutoff Depth
GPKG Projection HR Thin Z Line Output Adjustment Maximum Vertices
GPU Device IDs HX Force Weir Equation Maximums and Minimums
GPU DP Check HX ZC Check Maximums and Minimums Only for Grids

Appendix A TCF Commands - 2 / 147 Page 682 / 1094

 Maximums and Minimums Time Series Quadtree BC Parallel Inertia Approach Read GIS XP WLL Points
Maximums Approach Quadtree Control File Read Grid RF
Maximums Start Track Time Rainfall Boundaries Read Hazard File
Maximums Track Time Rainfall Boundary Factor Read Materials File
Meshparts Rainfall Control File Read Restart File
MI Projection Rainfall Gauges Read RowCol IWL
MI Projection Check Ignore Bounds Rainfall Null Value Read Soils File
Model Events RAM Optimisation Recalculate Chezy Interval
Model Output Zones Read File Record Gauge Data
Model Platform Read GIS 12D Network Record Gauge Data EXCLUDE
Model Precision Read GIS 12D Nodes Restart File Ignore Fields
Model Scenarios Read GIS 12D WLL Reveal 1D Nodes
Model TUFLOW Build Read GIS 12D WLL Points SA Minimum Depth
Model TUFLOW Release Read GIS Auto Terminate SA Proportion to Depth
Negative Depth Approach Read GIS Cyclone/Hurricane Screen/Log Display Interval
NetCDF Output Compression Read GIS FC Set Auto Terminate
NetCDF Output Direction Read GIS GLO Set IWL
NetCDF Output Format Read GIS ISIS Network Set Route Cut Off Type
NetCDF Output Start Date Read GIS ISIS Nodes Set Route Cut Off Values
NetCDF Output Time Unit Read GIS ISIS WLL Set Variable
Null Cell Checks Read GIS ISIS WLL Points SGS
Number 2D2D Link Iterations Read GIS IWL SGS Approach
Number Iterations Read GIS LP SGS Breakline Detection Delta
Output Approach Read GIS Output Zone SGS Depth Output
Output Drive Read GIS PO SGS Infiltration Approach
Output Files Read GIS Reporting Location SGS Map Extent ⟨ Full or Trim ⟩

Output Folder Read GIS X1D Network SGS Materials

Pause Read GIS X1D Nodes SGS Max Sample Frequency
Pit Default Extrapolate Q Curve Read GIS X1D WLL SGS Negative Rainfall Approach
Pit No 1D Connection Read GIS X1D WLL Points SGS Sample Frequency
Plot Output Invalid Type Read GIS XP Network SGS Sample Target Distance
PO Approach Read GIS XP Nodes SGS SX Z Flag Approach
Process All Grids Read GIS XP WLL SGS TIN Memory Allocation Factor

Appendix A TCF Commands - 3 / 147 Page 683 / 1094

 SGS Velocity Based Outputs SX Head Distribution Cutoff Depth Use Forward Slash
SGS Z Shape Line Approach SX Storage Approach Verbose
SGS Zpt MAX/MIN Approach SX Storage Factor VG Z Adjustment
Shallow Depth Stability Factor SX ZC Check Viscosity Approach
SHP Projection TIF Compression Viscosity Coefficient
SHP Projection Check Method TIF Compression Predictor Viscosity Formulation
Simulation Pause Interval TIF Projection Water Level Checks
Simulation Pause Start Time Output Corner Interpolation Wetting and Drying
Simulations Log Folder Time Output Cutoff WIBU FIRM Code Search Order
Snap Tolerance Time Series Null Value Wind/Wave Shallow Depths
Soil Initial Loss Time Series Output Format Write Check Files
Soil Negative Rainfall Approach Time Series Output Interval Write Empty GIS Files
Soil Negative Rainfall Factor Timestep Write PO Online
Solution Scheme Timestep Initial Write Restart File at Time
Spatial Database Timestep Maximum Write Restart File Interval
Spatial Database Output Timestep Maximum Increase (%) Write Restart File Version
SQLite On Open SQL Timestep Minimum Write Restart Filename
Start 1D Domain Timestep Repeats Write X1D Check Files
Start 2D Domain TIN Output Format XF Files
Start Map Output TIN Triangulation Approach XF Files Boundaries
Start Time TSF Update Interval XF Files Include in Filename
Start Time Series Output Tutorial Model XF Files Merge TIN Elevations
Supercritical UK Hazard Debris Factor XMDF Output Compression
SWMM Control File UK Hazard Formula Zero Negative Depths
SX Flow Distribution Cutoff Depth UK Hazard Land Use Zero Rainfall Check
SX FMP Unit Type Error Units ZP Hazard Cutoff Depth
SX Head Adjustment Unused HX and SX Connections Zpt Range Check

Appendix A TCF Commands - 4 / 147 Page 684 / 1094

 @2080
@2084 Table A.1: TUFLOW Classic/HPC TCF Commands

Command Solver Description

@2083
@2085
AD Control File == Classic Triggers TUFLOW to execute an AD simulation (see Chapter 9 ) and
[ ⟨ .adcf_file ⟩ ] and HPC specifies the TUFLOW AD control file name. A TUFLOW AD Module
licence is required (see Section 1.1.5.1 ).

@2088 Head at ESTRY Interface ==

Adjust Classic Legacy command:
[ ON | ON Variable | {OFF} ] and HPC
This command’s main use is to provide backward compatibility for older
models using the previous default of “ON” (pre Build 2006-03-AB) . If set
to “ON”, TUFLOW lowers the 1D water level sent to the 2D cells along
HX lines by an average of the dynamic head based on the 2D velocities,
unless the S Flag is specified for a HX line (see Table 8.6 ). This can be
useful where the 1D water level is more representative of a static water
level (1D schemes roughly approximate the variation in water level
across a flow path due to the dynamic head). Based on numerous and
wide ranging application of HX lines, it is recommended that this
command use the default “OFF” setting.

The “ON VARIABLE” option, adjusts the water level on a cell-by-cell

basis and is presently not recommended other than for research
reasons.

Appendix A TCF Commands - 5 / 147 Page 685 / 1094

 Command Solver Description

@2089Terminate dV Cell Tolerance ==

Auto Classic Used to set the % of cells tolerance for automated result monitoring to
[ {0%} | ⟨ value ⟩ ] and HPC stop a simulation after the flood peak. This command is used with the
stop simulation commands Set Auto Terminate and Read GIS Auto
Terminate .

If set to a value of 1, then up to 1% of monitored cells can be within the

tolerance value without triggering an auto terminate. The larger the Auto
Terminate dV Value Tolerance the further the dV product needs to have
dropped from the peak value.

This command is used with the optional commands Auto Terminate dV

Value Tolerance , Auto Terminate Start Time and Auto Terminate Wet
Cell Tolerance .

Note, the Auto Terminate feature is only assessed at every Map Output
Interval .

Refer to Section 13.6.7 for more details.

Appendix A TCF Commands - 6 / 147 Page 686 / 1094

 Command Solver Description

@2092Terminate dV Value Tolerance ==

Auto Classic Used to set the velocity-depth tolerance for automated result monitoring
[ {0} | ⟨ value ⟩ ] and HPC to stop a simulation after the flood peak. This command is used with the
mandatory stop simulation commands Set Auto Terminate and Read
GIS Auto Terminate .

For the velocity-depth tolerance, at each output interval the velocity

depth product is compared to the tracked maximum value. If the current
dV product is within the specified tolerance using Auto Terminate dV
Value Tolerance , the cell is within the range and the simulation is not
auto terminated. The total number of cells that are allowable within the
specified range is controlled with .tcf command Auto Terminate dV Cell
Tolerance .

This command is used with the optional commands Auto Terminate dV

Cell Tolerance , Auto Terminate Start Time and Auto Terminate Wet
Cell Tolerance .

Note, the Auto Terminate feature is only assessed at every Map Output
Interval .

Refer to Section 13.6.7 for more details.

@2095Terminate Start Time ==

Auto Classic Used to set the start time when terminate feature commences, after
[ {Simulation Start Time} | ⟨ value and HPC which result monitoring to stop a simulation after the flood peak is done.
⟩ ] This command is used with the mandatory stop simulation commands
Set Auto Terminate and Read GIS Auto Terminate .

This command is used with the optional commands Auto Terminate dV

Cell Tolerance , Auto Terminate dV Value Tolerance and Auto
Terminate Wet Cell Tolerance .

Note, the Auto Terminate feature is only assessed at every Map Output
Interval .

Refer to Section 13.6.7 for more details.

Appendix A TCF Commands - 7 / 147 Page 687 / 1094

 Command Solver Description

@2098Terminate Wet Cell Tolerance ==

Auto Classic Used to set the percentage of cells that have become wet since the Map
[ {0} | ⟨ value ⟩ ] and HPC Output Interval for automated result monitoring to stop a simulation
after the flood peak. This command is used with the mandatory stop
simulation commands Set Auto Terminate and Read GIS Auto
Terminate .

If set to 0, then if any monitored cells have become wet since the last
map output the simulation continues. If set, for example, to a value of 5,
then up to 5% of monitored cells can become wet since the last map
output without triggering an auto terminate.

This command is used with the optional commands Auto Terminate dV

Cell Tolerance , Auto Terminate dV Value Tolerance , Auto Terminate
Start Time and Auto Terminate Wet Cell Tolerance .

Note, the Auto Terminate feature is only assessed at every Map Output
Interval .

Refer to Section 13.6.7 for more details.

@2101
BC Control File == Classic Specifies the TUFLOW Boundary Control (.tbc) file (see Section 4.2.6 ).
[ ⟨ .tbc ⟩ ] and HPC The available commands that can be read into a .tbc are listed in
Appendix D ).

There can only be one .tbc file per 2D domain.

Appendix A TCF Commands - 8 / 147 Page 688 / 1094

 Command Solver Description

@2104
BC Database == Classic Sets the active BC Database file, as described in Section 8.6 . The file
[ ⟨ .csv ⟩ ] and HPC is usually created using spreadsheet software such as Microsoft Excel.

If the BC Database is specified in the TUFLOW .tcf file, it is set as the

active database for both 2D and 1D models. However, the active
database can be changed at any stage in the .tbc and .ecf files by
repeating the command with the new database set as the ⟨ .csv ⟩.

A BC Database must be specified before any of the other BC

commands are used.

@2109
BC Event Name == Classic Legacy command:
[ ⟨ bc_event_name ⟩ ] and HPC
Sets the active BC name to be substituted wherever BC Event Text
values occurs in the BC Database. See Section 8.6.2 for a description
of how the BC event commands operate and refer to the command BC
Event Source .

If specified in the .tcf file, <bc_event_name> also applies to any 1D

models.

The <bc_event_name> value can be changed at any stage by repeating

this command in the .tbc and .ecf files. For example, it may be set to
“Q100” to read in the 100 year catchment inflows, then set as “H010” to
read in the 10 year ocean levels for the downstream boundary. Note
that, in this case, the locations of the catchment inflows and downstream
boundaries would have to be placed in two separate GIS layers.

Appendix A TCF Commands - 9 / 147 Page 689 / 1094

 Command Solver Description

@2112
BC Event Source == Classic Typically used within Define Event blocks in a .tef file (TUFLOW Event
[ ⟨ bc_event_text⟩ | ⟨ bc_event_name⟩ and HPC File) – see Section 13.3.1 , but can be used one or more times in a .tcf
] file.

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

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

@2117
BC Event Text == Classic Legacy command:
[ ⟨ bc_event_text⟩ ] and HPC
Sets the text in the BC Database that is to be substituted by the BC
Event Name value. See Section 8.6.2 for a description of how the BC
event commands operate.

If specified in the .tcf file, <bc_event_text> also applies to any 1D

models. The <bc_event_text> value can be changed at any stage by
repeating this command in the .tbc and .ecf files, although it is strongly
recommended that the <bc_event_text> value is standardised across all
models and the command is specified only once.

@2120
BC Wet/Dry Method == Classic Legacy command:
[ PRE 2005-11-AF ] Only
Water levels at HX cells are set to be not less than the ZC plus Cell
Wet/Dry Depth value for when the 1D water level falls below the HX
cell. This enhances stability in some situations. For backward
compatibility use the PRE 2005-11-AF option.

Appendix A TCF Commands - 10 / 147 Page 690 / 1094

 Command Solver Description

@2121
BC Zero Flow == Classic If set to START, END or START and END, zeros the start and/or end of
[ {OFF} | START | END | START and and HPC 1D and 2D flow hydrographs (QT, ST, SA) as the option implies. The
END | ] hydrograph is modified by adding another row at the start/end of the
hydrograph with a flow value of zero.

The benefit is that should a simulation start before or finish after the
start/end of a hydrograph, the flow from this hydrograph into the model
will be zero. (TUFLOW, by default, extends the first value of all boundary
conditions backwards in time indefinitely, and the last value forwards in
time indefinitely.)

Only applies to hydrographs sourced via the BC Database file. See

Section 8.6 .

Appendix A TCF Commands - 11 / 147 Page 691 / 1094

 Command Solver Description

@2122
Bed Resistance Cell Sides == Classic Legacy command:
[ AVERAGE M | AVERAGE n | MAXIMUM and HPC
Defines how the bed resistance value at a 2D cell’s mid-side (i.e. that
n | {INTERROGATE} ]
used in the momentum equation) is calculated.

INTERROGATE (the default) applies the exact value from the material
polygons using Read GIS Mat . The INTERROGATE option provides a
higher resolution sampling of material values compared with just
sampling at the cell centres. This higher resolution sampling is
particularly useful in modelling urban areas where frequent and large
changes in Manning’s n occurs.

Note the Read RowCol Mat command is incompatible with the

INTERROGATE option. If using Read RowCol Mat , use AVERAGE M
or AVERAGE n.

The AVERAGE M option (TUFLOW Classic only) takes the average

Manning’s M (1/Manning’s n) value of the two adjoining cell centre
values.

The AVERAGE n option (TUFLOW Classic only) takes the average

Manning’s n values of the cell centres.

The MAXIMUM n option (TUFLOW Classic only) takes the maximum n

values of the cell centres either side of the cell side.

See Section 7.3.6.1 .

Appendix A TCF Commands - 12 / 147 Page 692 / 1094

 Command Solver Description

@2123
Bed Resistance Depth Interpolation = Classic Controls how the Manning’s n value is interpolated between the two
= Only depths if using the varying Manning’s n with depth (see Read Materials
[ LINEAR M | {SPLINE n} | LINEAR File ). The default value is SPLINE n which uses a curved fit so that the
n ] n values transition gradually. LINEAR M and LINEAR n both use a linear
interpolation of the M (1/n) and n value respectively.

The depth taken to interpolate Manning’s n values that vary with depth is
taken as the minimum of the depths at the cell mid-side and the
neighbouring cell centres.

See Section 7.3.6 .

@2124
Bed Resistance Values == Classic
Sets the bed resistance formula to use. The default value is MANNING
[ {MANNING N} | MANNING M | Only
N. See Section 7.5.3 .
CHEZY ]

@2125
BG FLC Default Approach == Classic Specifies the approach used to calculate the FLC at different depths for
[ {LINEAR} | LINEAR-CONSTANT | and HPC the 2d_bg shape (see Section 7.3.8.2 ). The default option is LINEAR
PARABOLIC | INVERTED-PARABOLIC ]
It is possible to individually specify the method to be used for each 2d_
bg structure using the ‘Option’ attribute (refer to Table 7.16 ).

@2126 BG FLC Approach ==

Blank Classic Specifies the approach to automatically generate the superstructure FLC
[ {NONE} | METHOD A | METHOD B ] and HPC value if the SuperS_FLC attribute is not defined. The default option is
NONE (i.e. superstructure FLC must be specified manually). Refer to
Section 7.3.8.2.1 and Table 7.16 .

@2127
Blockage AEP == Classic Sets the AEP (annual exceedance probability) for the current event, this
[ ⟨ aep value in % ⟩ ] and HPC would typically be defined within an event file (.tef), but can also be
specified in the .tcf.

See Section 5.8.1.1 for details of the blockage matrix approach.

Appendix A TCF Commands - 13 / 147 Page 693 / 1094

 Command Solver Description

@2130
Blockage ARI == Classic Sets the ARI (average recurrence interval) for the current event, this
[ ⟨ ari value in years ⟩ ] and HPC would typically be defined within an event file (.tef), but can also be
specified in the .tcf.

See Section 5.8.1.1 for details of the blockage matrix approach.

@2133
Blockage Default == Classic Sets the blockage category to be used if one is not defined in the
[ ⟨ Default Blockage Category ⟩ ] and HPC 1d_nwk pBlockage attribute. The pBlockage field must be left blank for
this to be used, if a numeric value is specified it is used instead. See
Section 5.8.1.1 .

@2136
Blockage Matrix == Classic Turns on or off the Blockage Matrix of culverts, as described in Section
[ {OFF} | ON ] and HPC 5.8.1.1 .

@2137
Blockage Matrix File == Classic Sets the blockage matrix file, as described in Section 5.8.1.1 . There
[ ⟨ link to blockage .csv file ⟩ ] and HPC can only be a single blockage matrix file.

@2140
Blockage Method == Classic Sets the blockage matrix method to either ELM (energy loss method) or
[ ELM | RAM | {} ] and HPC RAM (reduced area method). If blockage matrix is enabled this
command must be specified.ERROR 1622 is returned if Blockage Matrix
is on, though no blockage method is specified.

See Section 5.8.1.1 for blockage matrix details.

@2141
Blockage Override == Classic Sets all culverts to use the specified blockage category. This overwrites
[ ⟨ Blockage Category ⟩ ] and HPC the pBlockage attribute in the 1d_nwk layer. Useful for sensitivity testing.
See Section 5.8.1.1 .

@2144
Blockage PMF AEP == Classic Sets the AEP for the PMF. Only required if PMF is defined in the AEP
[ ⟨ aep value ⟩ ] and HPC column of the blockage matrix file. See Section 5.8.1.1 for blockage
matrix details.

@2147
Blockage PMF ARI == Classic Sets the ARI for the PMF. Only required if PMF is defined in the ARI
[ ⟨ ari value in years ⟩ ] and HPC column of the blockage matrix file. See Section 5.8.1.1 for blockage
matrix details.

Appendix A TCF Commands - 14 / 147 Page 694 / 1094

 Command Solver Description

@2150
Blockage Return Period == Classic Used to set Blockage Matrix return period naming convention to ARI or
[ AEP | ARI ] and HPC AEP. See Section 5.8.1.1 .

If this command above is not set, the first occurrence of either Blockage
ARI or Blockage AEP sets the return period naming convention.

The return period values in the first column of the matrix file specified
with the .tcf command Blockage Matrix File must be in the same
convention. For example, if specifying “Blockage Return Period
== AEP”, values in the matrix file must also be specified in AEP.

See Section 5.8.1.1 for blockage matrix details.

@2151Kenue Start Date ==

Blue Classic Legacy command:
[ ⟨ date in isodate format ⟩ ] and HPC
This date is added to the Blue Kenue output files as per the Blue Kenue
file format. The date should be specified in ISO 8601 (isodate) format
(yyyy-mm-dd). For example, to specify the 5th of November 2023 the .tcf
command would be: Blue Kenue Start Date == 2023-11-05. For
more information on the Blue Kenue format, see the 2018 TUFLOW
Manual.

Appendix A TCF Commands - 15 / 147 Page 695 / 1094

 Command Solver Description

@2154
Boundary Viscosity Factor == Classic Multiplies the eddy viscosity coefficient by <factor> along all open
[ {1.0} | ⟨ factor ⟩ ] and HPC (external) boundaries, and 2D and HX links.

For releases prior to 2016-03 the eddy viscosity coefficient was

previously set to zero for the boundary cells (this was because land
boundaries required this and open boundaries were treated in the same
manner). For the 2013-12 release for Link 2D2D Approach ==
METHOD D the default is set to 1.0 to improve the performance in flow
patterns along the 2D link lines. Changing this value in the range of 0.0
to 5.0 (possibly higher) usually has little effect on results, however,
increasing the factor may help “stabilise” unrealistic circulations along a
boundary or 2D / HX link line without adversely affecting results.
Sensitivity test prior to adopting larger factors.

@2157
BSS Cutoff Depth == Classic Defines the depth threshold (m) below which the Bed Shear Stress
[ {0.1} | ⟨ BSS_cutoff_depth ⟩ ] and HPC (BSS) and Stream Power (SP) Map Output Data Types will linearly
reduce to zero. See Table 11.4 .

@2160
Calibration Points MI File == Classic Assigns the peak water level calculated during the simulation as an extra
[ ⟨ mif_layer ⟩ ] and HPC attribute to the .mif/.mid layer. Useful for obtaining peak flood levels at
calibration points and other locations as direct output from TUFLOW. Up
to a maximum of ten (10) files can be specified.

The GIS layer at present must be in the .mif/.mid format and is opened
and closed during the start-up phase so the existence of the layer is
checked (rather than at the end of the simulation as this causes issues if
the layer does not exist or has a save date later than the .tab file), and
also so that the layers are copied if using the -c or -ca switches (refer to
Table 13.2 ).

Appendix A TCF Commands - 16 / 147 Page 696 / 1094

 Command Solver Description

@2163Side Wet/Dry Depth ==

Cell Classic Legacy command:
[ {0.001} | ⟨ depth_in_m ⟩ ] Only
No longer required or recommended for use subsequent to
implementation of Wetting and Drying == ON METHOD B. See
2010 TUFLOW Manual for details.

@2166Size ==
Cell Classic Legacy command:
[ ⟨ value_in_metres ⟩ ] and HPC
Sets the grid cell size in metres. Rarely used; normally specified in the
.tgc file (see Section 7.2.3 and Cell Size ). If the command exists in
both the .tcf and .tgc, the .tgc command will overwrite the .tcf command.

This command is not supported when using the Quadtree TUFLOW HPC
functionality (Section 7.4.1 ) and the command must be placed in the
.tgc instead.

As of the 2023-03-AF release, using this command in the TCF will give
an error.

@2169Wet/Dry Depth ==
Cell Classic Sets the wet/dry depth for determining when a cell wets and dries. The
[ {0.002} | ⟨ depth_in_m ⟩ ] and HPC default is 0.002m (2mm) or 0.007ft if using Units == US
Customary. The depth should be selected according to the magnitude
of flooding depths. For broad-scale models with large cell sizes values of
up to 0.05m (0.16ft) have typically been used, while for models using the
direct rainfall approach, or that have a high proportion of steep flow, a
wet/dry depth of less than a mm (e.g. 0.0002m or 0.0007ft) may be
required due to the substantial amount of shallow sheet flow. A reduced
wet/dry depth of 0.0002m (0.0007ft) is particularly recommended for
direct rainfall models, noting that the cell wet/dry depth cannot be set to
below 0.0002m (0.2mm) or 0.0007ft.

For TUFLOW Classic Multiple 2D Domain (see Section 10.7.2 ) models,

this command is domain dependent.

Appendix A TCF Commands - 17 / 147 Page 697 / 1094

 Command Solver Description

@2172 Zero Material Values to One =

Change Classic Legacy command:
= and HPC
The default material value is zero which means that every cell must be
[ ON | {OFF} ]
assigned a material value (i.e. use Set Mat as the first materials
command in the .tgc file). For backward compatibility set to ON. See
Section 7.3.6 .

@2173 Inside Grid ==

Check Classic By default, some layers, such as the 2d_bc and 2d_po layers, must have
[ {ERROR} | WARNING | OFF ] and HPC all of their objects fall within the 2D domain they are associated with,
otherwise an ERROR is issued and the simulation stops. Should it be
required that this check be switched off, set to either WARNING (a
WARNING is issued and will be included in the _messages GIS layer) or
OFF (no checks are made). The treatment of objects that fall partly
inside a 2D domain should be cross-checked viewing the check files and
results as to how they were treated.

@2174 MI Save Date ==

Check Classic Checks that the save date of the .mid file is later than the save date of
[ {ERROR} | WARNING | OFF ] and HPC the GIS layer as defined by Check MI Save Ext . The two files must be
located in the same folder. This command is very useful for detecting the
possibility that a GIS layer has been modified, but not exported as
.mif/.mid files prior to the simulation.

For the ERROR option (the default), the simulation terminates and an
error message is given.

For the WARNING option, a warning is written to the screen and log file,
but the simulation proceeds without pausing. It remains the responsibility
of the user to check for any warnings.

The OFF option disables all checks and no warnings are given.

@2175 MI Save Ext ==

Check Classic Sets the extension of the GIS file for which Check MI Save Date uses.
[ {.tab} | ⟨ ext ⟩ ] and HPC The default extension is “.tab”; the MapInfo primary GIS table file.

Appendix A TCF Commands - 18 / 147 Page 698 / 1094

 Command Solver Description

@2178
Command Line Processing == Classic Relaxes a rule added in the 2016-03 release that will force an ERROR if
[ {2016} | Pre 2016 ] and HPC a “==” (double =) is not specified for a command. This is to help prevent
issues associated with specifying a single = and the command not being
processed correctly (as could occur prior to the 2016-03 release).

@2179
Control Number Factor == HPC Only The default HPC courant, shallow wave celerity and diffusion control
[ {1.0} | ⟨ CN_value⟩ ] number limits can be reduced (or increased – be careful!) to effectively
underclock or overclock the simulation. Using the above command
factors all three control numbers. For example, a value of 0.8 reduces
the limits from 1.0, 1.0, 0.3 to 0.8, 0.8, 0.24, and will increase the run
time by 20%. Reducing the control number limits may be useful if the
simulation is exhibiting erratic behaviour or numerical “noise”, although
testing has found this is rare in real-world models, and if occurring is
more likely to be a sign of poor data or poor model schematisation. See
Section 3.5.4 for information relating to TUFLOW HPC’s timestep.

Though not recommended, a HPC simulation can be run using a fixed

instead of adaptive timestep by setting the <cn_value> to 0 and
specifying a Timestep . When running using a fixed timestep, there are
no checks on exceedance of control numbers or application of the
repeated timestep feature. If the control numbers are exceeded, the
simulation has a high risk of going unstable, which is detected by the
occurrence of NaNs (Not a Number) in the calculations. However,
unstable results can occur prior to NaNs being detected, therefore if no
NaNs occur this is not an indication the simulation was stable.

Appendix A TCF Commands - 19 / 147 Page 699 / 1094

 Command Solver Description

@2182
CPU Threads == HPC Only This command can be used to control the number of CPU threads
[ {4.0} | ⟨ number_of_CPU⟩ ] requested by a TUFLOW HPC simulation. For example CPU Threads
== 6 runs the HPC solver across 6 CPU cores, nothing that the number
of threads requested is limited to the maximum number of cores
available on the machine and the available TUFLOW Thread licences.
From the 2020 release, by default, each TUFLOW Engine licence comes
with four times the number of thread licences. Prior to the 2020 release
the default number was two. Therefore, from the 2020 release, a single
TUFLOW engine licence by default utilises four CPU threads.

Where multiple engine licences are available, it is possible for a

simulation to utilise more CPU threads. For example, a local four licence
allows up to a maximum of 16 CPU cores in use at any one time across
all the simulations. This could be four simulations utilising four threads
each or one simulation utilising 16 threads.

For further information see Section 12.8 .

@2185
CSV Header Line == Classic Legacy command:
[ {} | SINGLE ] and HPC
This is a legacy command that applies to formats prior to the default .csv
output for the 2016-03 release.

Specifying SINGLE will only output a single header line in _PO.csv files,
which makes it much easier to use the file for graphing in Excel. The
simulation name is also included in the label so that it’s easy to
distinguish between simulations when graphing comparisons. This is not
the default setting, so this command needs to be specified to activate
the feature.

Appendix A TCF Commands - 20 / 147 Page 700 / 1094

 Command Solver Description

@2186
CSV Maximum Number Columns == Classic Legacy command:
[ ⟨ max_col⟩ ] Only
This is a legacy command that applies to formats prior to the default .csv
output for the 2016-03 release.

Used to specify a maximum number of columns for 1D .csv output files.

The default setting is limitless. Refer also to the .ecf command CSV
Maximum Number Columns .

@2189
CSV Time == Classic Specifies the time values of .csv outputs. The default is HOURS.
[ DAYS | {HOURS} | MINUTES | and HPC
SECONDS ] Will apply to 1D and 2D .csv output. See Section 11.3 .

@2190
Defaults == Classic Sets backward compatibility to the specified release. See Chapter 18 .
[ ⟨ Release⟩ ] and HPC Options are:

PRE 2025
PRE 2023
PRE 2020-10-AB
PRE 2020-10
PRE 2020-01
PRE 2017
PRE 2016
PRE 2013
PRE 2012
PRE 2010
PRE 2008-08
PRE 2007-07-AA
PRE 2006-06-AA

Appendix A TCF Commands - 21 / 147 Page 701 / 1094

 Command Solver Description

@2193 Output Zone ==

Define Classic Starts a block of .tcf commands for an Output Zone named ⟨oz_name⟩.
[ ⟨ oz_name⟩ ] and HPC See Section 11.2.5 . Only one block can be specified for each unique ⟨

oz_name⟩. Use End Define to terminate the block. An ERROR occurs if

End Define is not specified. Refer also to Model Output Zones .

@2200Model ==
Demo Classic When set to ON, allows simulation of the Demo Models (developed for
[ ON | {OFF} ] and HPC the 2012 Flood Managers Association (FMA) Conference) and also
allows Free Mode for small-scale models without the need for a
TUFLOW license. Note that writing to the _All_TUFLOW_Simulations.log
file (see Section 14.4 ) is switched off when this command is set to ON.
For further information on the Demo Models refer to Section 2.1.4 and
the User Guide Free Demo TUFLOW Wiki page.

@2201
Density of Air == Classic Sets the density of air in kg/m3. If a cyclone/hurricane/typhoon track is
[ {1.25} | ⟨ value⟩ ] Only used, the density of air can be varied along the track. See Section 8.7 .

@2204
Density of Water == Classic
Sets the density of water in kg/m3.
[ {1025} | ⟨ value⟩ ] and HPC

@2207
Depth/Ripple Height Factor Limit == Classic Sets an upper limit on the ratio of the water depth over the ripple height
[ {10} | ⟨ value⟩ ] Only in the formula for calculating Chezy values based on water depth. The
value must be greater than 1/12, and if less than 1/12 is set to the
default value of 10. See Section 7.5.3 .

@2210
Display Water Level == Classic Displays the water level on the screen for the cell located at X,Y where X
[ ⟨ X ⟩, ⟨ Y⟩ ] and HPC and Y are the geographic coordinates in metres. See Section 14.2.1 .

Appendix A TCF Commands - 22 / 147 Page 702 / 1094

 Command Solver Description

@2215
Distribute HX Flows == Classic Offers an alternative option for distributing the flow across HX lines
[ ON | {OFF} ] and HPC to/from the 1D nodes, see Section 10.2.1 . The distribution is based on
a linear interpolation based on the distance of the HX cell from the 1D
node. This option, on some models, has improved model performance if
the 1D/2D interface is being problematic. The feature is still under trial
and should be benchmarked before adopting. It is not available for the
Flood Modeller 1D link as incorrect results presently occur. It has not
been tested with the XP-SWMM 1D link.

@2216
End 1D Domain Classic Terminates a Start 1D Domain block of 1D (.ecf) commands in a .tcf
and HPC file. See Chapter 5 .

@2217
End 2D Domain Classic Indicates the end of a block of commands that define a 2D domain. Must
Only only occur after a Start 2D Domain command, otherwise an error
occurs. See Chapter 10.7.2 .

@2218
End After Maximum == Classic Terminates the simulation <eam> hours after the last time a new
[ ⟨ eam⟩ | [ {0.001} | ⟨ h_tol⟩ ] and HPC maximum was recorded anywhere in the model. End Time should also
still be specified as an upper limit to finish the simulation.

<h_tol> is an optional second argument that sets a height tolerance for

detecting whether a 1D node or 2D cell has reached its maximum. For
example, “End After Maximum == 0.25 | 0.01” will terminate the
simulation once either End Time has been reached, or there are no 1D
nodes or 2D cells that have increased by 1cm (0.01m) in the last 15mins
(0.25h). The % of 1D nodes and 2D cells that have reached their
maximum are displayed after the “Mx” on the console window and in the
.tlf file.

The default for <h_tol> is 0.001m (or 0.001ft), unless “Defaults == PRE
2016” in which case the default is 0.0. Note that using a 0.0 tolerance
may not work as expected due to numerical precision issues.

Appendix A TCF Commands - 23 / 147 Page 703 / 1094

 Command Solver Description

@2223
End After Maximum Start Time == Classic The End After Maximum feature will not commence monitoring until
[ {0} | ⟨ time in hours⟩ ] and HPC after a specified time (in hours).

For example, “End After Maximum Start Time == 12” does not
commence monitoring till a simulation time of 12 hours, therefore, the
simulation cannot terminate prior to this time.

@2226
End Define Classic Ends a Define Output Zone block of .tcf commands. This command
and HPC must be specified if Define Output Zone occurs within the .tcf. See
Section 11.2.5 .

@2227
End Map Output == Classic The simulation time in hours when map output terminates. If the
[ ⟨ time_in_hours ⟩ ] and HPC command is omitted, the simulation end time is used.

This command can be defined for different output formats by including

the output format extension on the left of the command. For example, to
set the end time for XMDF output to 10hrs use:

XMDF End Map Output == 10

This functionality is also available for the commands Start Map Output ,
Map Output Interval and Map Output Data Types . Refer to Section
11.2.1 .

This command can be used within a Define Output Zone definition

block to change the setting from that for the entire model map output.

@2230
End Time == Classic Specifies the finish time of the simulation in hours. Value must be
[ ⟨ time_in_hours ⟩ ] and HPC greater than the start time and can be negative. See Section 4.2.4 .

If the command is omitted, an end time of 1 hour is used.

Appendix A TCF Commands - 24 / 147 Page 704 / 1094

 Command Solver Description

@2233 Control File [ {} | AUTO] ==

ESTRY Classic Specifies the TUFLOW 1D / ESTRY control file (.ecf) (see Section 4.2.5
[ {} | AUTO] == ⟨ .ecf_file ⟩ ] and HPC ). There can only be one .ecf file.

The AUTO option automatically sets the .ecf filename to the same as the
.tcf file (except for the extension).

Note all 1D output filenames are now based on the .tcf filename, not the
.ecf filename. This means that if the .ecf file does not change when
setting up a new simulation based on a previous simulation, there is no
need to make a copy of the .ecf file (i.e. the .ecf file can be treated in a
similar manner to the .tgc and .tbc files).

@2236 File ==
Event Classic Sets the active event file, see Section 13.3.1 . All .tcf and .ecf
[ ⟨ .tef_file ⟩ ] and HPC commands can also be read into a .tef. The additional .tef commands
(that cannot be read in to a .tcf or .ecf) are listed in Appendix K .

Whilst this command may be repeated to change the active event file it
is recommended that only one event file be created for all simulations.

@2239 Start Date ==

Excel Classic Adjusts the time column of time series output (Section 11.3 ) by the
[ ⟨ days_since_1900 ⟩ ] and HPC amount specified. The amount is in days from the year 1900 as used by
Microsoft Excel to manage its date fields. To determine this value, enter
the date corresponding to time zero in the TUFLOW simulation as a date
field in Excel. Change the format of the Excel cell to “Number”, and the
number of days since 1900 is shown. Paste this number into the .tcf file
for <days_since_1900>.

Note, only applies:

if CSV Time == DAYS

to 2D timeseries outputs and not 1D timeseries

@2242
External Stress File == Classic Specifies the external stress control file ( .tesf) (see Section 4.2.12 ).
[ ⟨ .tesf_file ⟩ ] and HPC There can only be one .tesf file per 2D domain.

Appendix A TCF Commands - 25 / 147 Page 705 / 1094

 Command Solver Description

@2245Geodatum ==
FEWS Classic Used to write out a FEWS regular grid configuration file (.xml). This .xml
[ ⟨ geodatum string ⟩ ] and HPC file is written if the FEWS Geodatum is specified and the Map Output
Format includes the “NC” format. The .xml file is written to same results
folder as the grid .nc, and has the file name “Grids.xml”. For further
details see the NetCDF Raster Output Format TUFLOW Wiki page.

@2248Input File ==
FEWS Classic Reference to a DELFT-FEWS boundary file in .csv or .xml format. This
[ ⟨ FEWS boundary file ⟩ ] and HPC command can be used to set the duration of the simulation and the
NetCDF Output Start Date for a TUFLOW simulation based on the
information within the DELFT-FEWS file. Refer to Section 8.6.4 .

@2251Retry Max Count ==

File Classic When a file is locked (e.g. due to external use such as during file
[ <max count> | {40} ] and HPC backups) TUFLOW will retry a set number of times (and for a set period
of time - see File Retry Timeout to access the file. The maximum
number of retries is capped to prevent an infinite loops if the file is
permanently locked. The default number of retries is 40.

@2252Retry Timeout ==
File Classic When a file is locked (e.g. due to external use such as during file
[ <max time> | {30} ] and HPC backups) TUFLOW will retry to access the file for a set period of time
(and a set number of retries - see File Retry Max Count ) to access the
file. The default timeout value is 30 seconds.

Appendix A TCF Commands - 26 / 147 Page 706 / 1094

 Command Solver Description

@2253 Sweep Direction ==

First Classic Legacy command:
[ AUTOMATIC | {POSITIVE} | Only
Build 2004-05-AD reworked and tested part of the Stelling scheme that
NEGATIVE ]
can vary the sweep direction depending on the flow regime at the time.
In rare situations, this may cause very slight difference in results
between two models (e.g. before and after cases) in areas where there
should be no difference at all. This was as a result of the unpredictable
sweep direction in one part of the scheme. Testing on a number of
models showed that by fixing the sweep directions, there was virtually no
difference in results. This also solved the rare situation where two
models were showing a slight difference in areas they should not have
been.

This command is provided for backward compatibility, although it is not

considered that this will be necessary in most models. To use the
approach prior to Build 2004-05-AD use the AUTOMATIC option.

@2254 File IO Display ==

Force Classic If set to ON, forces all file opening and closing information to be
[ ON | {OFF} ] and HPC displayed to the screen and .tlf file. Nearly all file opening and closing is
displayed, however some isn’t. For example Write PO Online ==
ON displays a lot of file opening and closing information as the simulation
proceeds, so should you wish to activate this for checking purposes set
this command to ON.

Note: This command would mainly be used for debugging a file

opening and closing issue.

Appendix A TCF Commands - 27 / 147 Page 707 / 1094

 Command Solver Description

@2255Overfall ==
Free Classic Legacy command:
[ {ON} | ON WITHOUT WEIRS | OFF Only
The default ON option activates the free-overfall method described in
]
Syme (1991 ). The method offers better stability; particularly where
major wetting and drying occurs. It also allows large tidal flats to
continue to drain without being cut-off at their edges. This option also
activates the automatic broad-crested weir flow switch between
upstream and downstream controlled flow. Use this option where weir
flow occurs over levees and embankments. This option increases the
computation time, typically by 10 to 30%, depending on the degree of
wetting, drying and weir flow.

Upstream controlled flow is determined by comparison of the upstream

and downstream energy levels. If upstream controlled, the broad-crested
weir formula is used to define the flow across the cell-side. With the
development of the Supercritical flow switch, the automatic weir flow
algorithm was enhanced and only applies to cell-sides that have an
adverse slope (i.e. the bed slope from the ZC to ZU/ZV point is of
opposite sign to the water surface slope) - see Section 7.5.2 .

The ON WITHOUT WEIRS option activates the free-overfall method

without the automatic weir flow switching. Mainly used for models
developed prior to 1999, which is when the weir flow option became
available.

The OFF option deactivates the free-overfall method. Used for models
with little or no wetting and drying, and no upstream controlled weir flow.

@2256Overfall Factor ==
Free Classic Sets the free-overfall factor (see Syme (1991 )).
[ {0.6} | ⟨ value_0.0_to_1.0 ⟩ ] Only
The default is 0.6. The value should be less than 1.0 and greater than
0.0.

Appendix A TCF Commands - 28 / 147 Page 708 / 1094

 Command Solver Description

@2259 Check ==
Froude Classic Sets the minimum Froude Number that upstream controlled friction flow
[ {1} | ⟨ froude_no ⟩ ] Only may occur. Only applies if Supercritical is set to ON, otherwise it is not
used. Improved stability may occur in steeply flowing areas if
<froude_no> is less than 1. <froude_no> cannot be below zero and
would normally not exceed 1. See Section 7.5.2 .

@2262 Depth Adjustment ==

Froude Classic Legacy command:
[ {ON} | OFF ] Only
Switches on or off an additional upstream controlled friction flow check
(see Section 7.5.2 ). Set to OFF for backward compatibility for models
run prior to Build 2003-01-AF that use the upstream controlled friction
feature (i.e. see Supercritical ).

@2263
GA Convergence Value == Classic Sets the Green Ampt iteration infiltration convergence test value. The
[ {0.001} | ⟨ value ⟩ ] Only default value is 0.001m. See Section 7.3.7.1.1 . The default unit for this
command is metres. If Units == US Customary, the unit is feet.

@2266
GA Maximum Iterations == Classic Sets the limit on the number of iterations for the Green Ampt solution.
[ {ON} | OFF ] Only The default value is 10. If the number of iterations exceeds this value a
WARNING 2302 is issued. See Section 7.3.7.1.1 .

@2267
Geometry Control File == Classic Specifies the geometry control file (.tgc) (see Section 4.2.7 ). There can
[ ⟨ .tgc_file ⟩ ] and HPC only be one .tgc file per 2D domain.

Appendix A TCF Commands - 29 / 147 Page 709 / 1094

 Command Solver Description

@2270
GIS Format == Classic Specifies the output format for GIS check layers and GIS outputs such
[ {MIF} | SHP | GPKG ] and HPC as the _TS layers. If the command GIS Format is not specified, the GIS
format used for check layers and other GIS outputs is based on whether
GPKG Projection , SHP Projection or MI Projection has been
specified. If none or all of these commands have been specified, and
GIS Format has not been specified, the default of using .mif files is
adopted. See Section 11.2.2.5 .

Note that the format of an input layer is solely controlled by the file
extension (i.e. .gpkg for the GPKG format, .shp for the SHP format
and .mif for the MIF format).

@2271
GIS Grid Vector Direction == Classic The magnitude and direction are output as attributes on the GIS object
[ {ANGLE} | BEARING | VERBOSE and HPC for output of vector data. This command sets the direction convention.
] For the ANGLE option the direction is output in arithmetic format (0
degrees = East). For BEARING this is set to a compass bearing notation
with (0 degrees = North). If set to VERBOSE, the x-direction component,
y-direction component, angle and bearing are all output as attributes on
the GIS layer.

To apply a different setting for different vector data types, inset the data
type before the command. See Section 11.2.2.5 .

@2272
GIS Grid Vector SF == Classic Scale factor for the scaling of region objects for GIS output of vector
[ {1} | ⟨ scale factor ⟩ ] and HPC data. The default value is 1. A value of 1 means a velocity of 1 m/s is
one 2D cell long, therefore, with a scale factor of 2, a vector of
magnitude 1 m/s would be two 2D cells long. A negative value outputs
vectors of fixed length equal to <scale_factor> in metres or feet.

To apply a different setting for different vector data types, inset the data
type before the command. See Section 11.2.2.5 .

Appendix A TCF Commands - 30 / 147 Page 710 / 1094

 Command Solver Description

@2275
GIS Grid Vector TTF == Classic Tail thickness Factor, scales the thickness of the arrow tails (default = 0).
[ {0} | ⟨ tail_thickness_factor ⟩ and HPC The thickness is the <tail_thickness_factor> times the arrow length. For
] some GIS software such as ArcGIS, a zero tail thickness value may
cause issues as the region shape wraps onto itself. To apply a different
setting for different vector data types, inset the data type before the
command. See Section 11.2.2.5 .

@2278
GIS Grid Vector Type == Classic Specifies whether the vector information (output over a regular grid)
[ {Region} | Point ] and HPC should be as points or region objects. Region objects refer to the arrows
that TUFLOW_to_GIS produces, scaled according to the vector
magnitude. The magnitude and direction are output as attributes to the
layer. The default is regions (as per TUFLOW_to_GIS).

To apply a different setting for different vector data types, inset the data
type before the command. See Section 11.2.2.5 .

@2279
GIS Project Path Format == Classic Sets the referencing type for the workspaces output by TUFLOW, for
[ Absolute | {Relative} ] and HPC QGIS (.qgs) and MapInfo (.wor). “Relative” (the default) uses relative
referencing, this can be changed to absolute by using “Absolute”. See
Section 14.5.6 .

Appendix A TCF Commands - 31 / 147 Page 711 / 1094

 Command Solver Description

@2280
GIS Projection Check == Classic Checks that the GPKG Projection , SHP Projection and/or MI
[ {ERROR} | WARNING ] and HPC Projection setting is the same as the projection for all input layers. See
Section 4.4.1 . The Coordsys line check removes all spaces, tabs and
quotes when making the comparison.

The check includes the “Bounds” values, as having different bounds can
affect the decimal precision used by GIS/CAD software when writing .mif
files, which can affect the TUFLOW test for snapped (connected)
objects.

The default setting is ERROR and will prevent TUFLOW from starting
the model simulation. Changing to WARNING output a message to the
_messages GIS layer (Section 14.5.5 ) and will allow the model to
continue to compile.

@2281
GIS Supported Object Ignored == Classic Controls the response to GIS object ignored messages (for example,
[ ERROR | {WARNING} ] and HPC see Message 2073). If set to ERROR the simulation is terminated, while
is set to WARNING (the default) the message is issued and the
simulation continues. The default is for a WARNING to be issued as per
releases prior to 2016-03.

Note that various TUFLOW inputs expect different GIS object types, so
the behaviour of this reporting varies. For example a 1D boundary
(1d_bc) layer can contain points snapped to the 1D nodes and/or region
objects used to apply flow boundaries to nodes that fall within the region.
So whilst a line is a generally supported object (see GIS Unsupported
Object ) any line objects in a 1d_bc layer are not used and TUFLOW
issues Message 1099.

Appendix A TCF Commands - 32 / 147 Page 712 / 1094

 Command Solver Description

@2282
GIS Unsupported Object == Classic Controls the approach for issuing messages in relation to unsupported
[ {ERROR} | WARNING ] | [ {1} and HPC GIS objects. GIS software typically store vector data in three broad
| ⟨ level ⟩ ] geometries:

Points
Lines
Regions

Within these geometry types, different GIS packages may offer options
for digitising objects. For example, when drawing a line object in MapInfo
the user has the option for a line, a polyline and an arc. From left to right
the editing buttons to digitise a line, polyline and arc in MapInfo are:

These line types are stored differently in the MapInfo .mif file, an extract
of a .mif file which shows a line (with 2 vertices) object (red), a line (with
3 vertices) object (green) and an arc object (blue) is below.

Line 340604.21 5782377 340612.07 5782369.48

Pen (1,2,0)
Pline 3
340609.55 5782359.99
340614.35 5782361.73
340623.19 5782363.59
Pen (1,2,0)
Arc 340630.84 5782358.24 340640.43 5782382.01 180 270
Pen (1,2,0)

Various GIS packages handle the advanced GIS geometries (such as

arcs) differently, for example if converting a MapInfo Arc object using
QGIS, the arc object is converted to a polyline with vertices along the
length. For consistency between packages and to provide better support

Appendix A TCF Commands - 33 / 147 Page 713 / 1094

 Command Solver Description

across GIS platforms not all GIS geometries are supported by TUFLOW.
For lines, arc objects are not supported (but line and polyline objects are
both recognised). For region objects rectangles, rounded rectangles and
ellipses are not supported.

Two special cases of unsupported geometries are “Text” objects, which

can be used to annotate GIS layers, and “None” or “Null” objects, which
GIS software may add to the layer to indicate deleted objects
(particularly if using the shapefile format).

This command controls TUFLOW’s response for geometries that are not
supported by TUFLOW. The ERROR option stops the simulation with a
Message 0323, while WARNING issues Message 0323 and continues
the simulation. There is an optional severity level component that can be
specified as a second argument (separated by a vertical bar) with the
options for <level> being:

The severity levels are:

Level 0 – No checks on unsupported geometries (i.e. previous

behaviour)
Level 1 – Check for ellipses, rectangles, rounded rectangles and
arcs (curved arcs)
Level 2 – All the level 1 checks as above plus checks for null and
text objects.

The default for unsupported objects is ERROR | 1, that is arcs, ellipses,

rectangle and rounded rectangles will cause the simulation to stop, but
any None and Text objects will be ignored.

@2285 FC Ch Factor ==
Global Classic The global Ch factor applied to flow constrictions when the flow
[ {0.8} | ⟨ Ch ⟩ ] Only upstream is submerged and the flow downstream is unsubmerged, using
the pressure flow equation for upstream controlled flow. See Section
7.5.6 .

Appendix A TCF Commands - 34 / 147 Page 714 / 1094

 Command Solver Description

@2288 Rainfall Use Material Loss ==

Global Classic Sets whether material rainfall losses (Section 7.3.6.4 ) are used when
[ OFF | {ON} ] Only using a global rainfall boundary (Section 8.5.3.3 ). Prior to the 2020-10-
AA release, if using material rainfall losses in TUFLOW Classic, the
losses were not applied to any global rainfall boundaries. This command
can be used to turn off material losses. The default for 2020-10-AA and
newer is to apply material losses to global rainfall boundaries (in line
with TUFLOW HPC).

@2289 Weir Factor ==

Global Classic Factor that adjusts the broad-crested weir formula (see Section 7.5.2 ).
[ {1.0} | ⟨ value ⟩ ] and HPC Testing has shown that a value of 1.0 to 1.1 is needed to reproduce
upstream controlled weir flow (Syme, 2001b ). This factor is applied
globally, although spatial variation of the factor can be specified through
a GIS layer read by the geometry control file (see Read GIS WrF .

Note that the global value and the spatially varying value are multiplied
together (i.e. one does not replace the other).

@2292Compression ==
GPKG Classic The GPKG raster format supports LZW compression of the data. The
[ NONE | {LZW} ] and HPC data is compressed by default, however, can be turned off by setting this
command to ‘NONE’. See Section 11.2.2.2 .

@2293Compression Predictor ==
GPKG Classic By default, TUFLOW will also use a compression predictor to improve
[ NONE | {Horizontal and HPC the compression ratio, this can be turned off by setting this command to
Differencing} ] ‘NONE’. See Section 11.2.2.2 .

@2294Conversion Check
GPKG == Classic ERROR 0248 may occur when reading a SHP or MIF file that has been
[ WARNING ] and HPC exported from a GKPG layer (see Section 4.4.1 ). This command can
be used to downgrade ERROR 0248 to a Warning. Alternatively, ensure
the input file follows the correct TUFLOW attributes.

Appendix A TCF Commands - 35 / 147 Page 715 / 1094

 Command Solver Description

@2295Inputs Read Only ==

GPKG Classic Introduced in the 2023-03-AF build, if set to “ON”, this command forces
[ ON | {OFF} ] and HPC TUFLOW to open GPKG input databases in a stricter read only mode.
This should reduce the chance of database locks occuring from
concurrent access from simultaneous TUFLOW simulations.

The ‘read only’ mode has some limitations, for example, “.gpkg-WAL”
and “.gpkg-SHM” files won’t be cleaned up if these are created. It also
won’t be possible to change some of the database settings if this
command is used in conjunction with SQLite On Open SQL .

@2296Projection ==
GPKG Classic Sets the geographic projection for all GIS input and output in
[ ⟨ GPKG layer ⟩ ] and HPC GeoPackage (.gpkg) file format (see Section 4.4.1 ). This is used for
checking whether input layers are in the same projection, and for setting
the projection of all output layers (e.g. check layers).

If a model has a mixture of .gpkg, .shp and .mif files as input, then the
projection must be specified for each (e.g. using GPKG Projection ,
SHP Projection and MI Projection )

Appendix A TCF Commands - 36 / 147 Page 716 / 1094

 Command Solver Description

@2299
GPU Device IDs == HPC Only Controls the GPU device or devices to be used for the simulation if
[ ⟨ list_of_device_ids ⟩ ] multiple CUDA enabled GPU cards are available in the computer or on
the GPU itself. If you only have one GPU device, or you wish to use the
primary device, this command is not needed. If there is more than one
GPU device, and you wish to run the model across cards, enter a list of
device IDs. For example, if you wanted to run a model using GPU
devices 0 and 2, specify:

GPU Device IDs == 0, 2

Note that the GPU device numbering starts at 0 rather than at 1.

A GPU licence will be needed for each device ID.

Also refer to the batch switch –pu<id> described in which has the same
function.

For further information see Section 12.8 .

@2302
GPU DP Check == HPC Only Legacy command:
[ {ERROR} | OFF ]
The GPU Solver is a legacy solver.

The default setting of ERROR, causes TUFLOW to stop with ERROR

2420 advising that it is recommended to use the single precision version
of the GPU Solver. Due its explicit formulation and being depth based,
TUFLOW GPU does not usually require to be run in double precision
(DP) mode. Refer to Section 13.4.2 for further information. There can
also be substantial speed gains using single precision (SP) on some
GPU cards, and there is a significantly less memory footprint. If DP is
desired or required for the GPU Module specify GPU DP Check ==
OFF in the .tcf file, and run using a DP TUFLOW exe.

Appendix A TCF Commands - 37 / 147 Page 717 / 1094

 Command Solver Description

@2303
GPU Peer to Peer Access == HPC Only When running a HPC simulation across multiple GPUs, TUFLOW
[ DISABLED | {ENABLED IF automatically recognises and utilises any peer to peer (p2p) access
AVAILABLE} ] between GPUs that is possible according to the hardware setup. The
user can choose to disable peer to peer GPU by setting this to
‘DISABLE’. This can also be specified using the command line argument
-p2p0 to disable, or -p2p1 to enable (if available). The default is to use
peer to peer access if available. Peer to peer access in rare occasions
has failed to work when a peer connection has been reported as
possible by the nVidia console or API. See Section 12.8 and 13.5.3.4 .

@2304
GPU Solver == GPU Legacy command:
[ [ ON | {OFF} ] (pre-2017
Must be set to ON to use the pre 2017 release version of the TUFLOW
HPC
GPU Engine. Significant improvements were made to the GPU solver for
release) if
the 2017 release. Please use Solution Scheme and Hardware
set to ON
commands to use the improved TUFLOW HPC solver using GPU
hardware. If the command is not specified or set to OFF, the standard
TUFLOW Classic CPU Engine will be used to simulate the model.

Appendix A TCF Commands - 38 / 147 Page 718 / 1094

 Command Solver Description

@2305
GPU Temporal Scheme == GPU Legacy command:
[ [ 1 | 2 | {4} ] (pre-2017
Note: This command relates to the legacy TUFLOW GPU solver. Please
HPC
use Solution Scheme and Hardware commands to use the improved
release)
TUFLOW HPC solver using GPU hardware.

This command sets the order of the temporal solution for TUFLOW GPU
simulations. The default is the recommended 4th order temporal solution
therefore this command is usually not specified.

Available options are:

1 – First order out of place

2 – Second Order
4 – Fourth Order

We recommend the use of the 4th order temporal scheme as it is

unconditionally stable with adaptive timestepping turned on, and
has found to give excellent results. Lower order schemes save a
little on memory requirements, but are more prone to instability and
in some cases unreliable results.

@2306Format ==
Grid Classic Sets the format that TUFLOW uses to write output and check file grids
[ ASC | FLT | {TIF} | GPKG | NC | and HPC (see Section 11.2.2.2 ). The default is the TIF format. Table 11.3 lists
TGO | WRR ] the available formats.

Appendix A TCF Commands - 39 / 147 Page 719 / 1094

 Command Solver Description

@2307Output Cell Size ==

Grid Classic Sets the cell resolution in metres of all grid outputs. For TUFLOW
[ ⟨ grid_cell_size ⟩ ] and HPC Classic the default output grid resolution is half the smallest 2D cell size
(considering that multiple 2D domains may exist). For TUFLOW HPC the
default is half the 2D cell size. For HPC models using Quadtree, the
output resolution is the smallest 2D cell size. For more information see
Section 11.2.2.2 .

A DEM of the final Zpts is automatically written using this resolution if

writing check files unless it is excluded using Write Check Files
Exclude == DEM_Z.

Increasing the grid output cell size will reduce the RAM required and the
size of the output files. Therefore, for very large models, consider
increasing this value if there are memory (RAM) allocation issues. For
more advice on reducing RAM requirements, see the TUFLOW
Simulation Speed wiki page.

@2310Output Origin ==
Grid Classic AUTOMATIC, the default, adjusts the origin for the output grids by
[ {AUTOMATIC} | MODEL ORIGIN ] and HPC rounding to the Grid Output Cell Size so that all grids produced from
different simulations using different model extents, and between different
Output Zones, are all aligned. See Section 11.2.2.2 .

If Grid Output Origin == MODEL ORIGIN is specified, this sets

grid output (e.g. TIF, FLT or ASC) to have its origin exactly at the model’s
lowest left coordinates for map output. Note that output grids of different
origins (due to a change in the model’s schematisation or addition of 1D
WLLs), or from different Output Zones, may not be aligned.

Appendix A TCF Commands - 40 / 147 Page 720 / 1094

 Command Solver Description

@2311
Groundwater Blend Threshold == HPC Only When a soil is nearly saturated, the level is transitioned from the level in
[ ⟨ float ⟩ | {0.9} ] the current layer to the layer above, as this avoids a sudden change in
level as the soil reaches capacity. A “groundwater blend threshold” is
used to control this, this threshold has a default value of 0.9, meaning
that once a soil exceeds 90% of a soil capacity, the level starts to
transition to the level in the layer above. The value must be in the range
0-99. See Section 7.4.5.2 .

@2314
Hardware == Classic This command defines the hardware to be used for the compute. See
[ {CPU} | GPU ] and HPC Section 12 .

CPU will run a simulation using the Central Processing Unit (CPU).

GPU will run the simulation using the Graphics Processor Unit (GPU)
hardware. GPU hardware technology means very large models ($$100
million cells) with fine grids can now be run within a sensible timeframe.

TUFLOW Classic simulations are only possible using CPU. TUFLOW

HPC can be run using CPU or GPU. TUFLOW HPC CPU simulations
can be done using a standard TUFLOW licence. The GPU Hardware
Module is required in addition to a standard TUFLOW licence to run a
simulation on GPU. Refer to Section 1.1.5 for more details.

@2315
HEC-DSS Start Date == Classic Used to identify the date/time that should be used for time-zero. The
[ ⟨ value ⟩ ] and HPC date should be in the isodate format: yyyy-mm-dd hh:mm:ss, where the
time portions are optional. If this command is not used, the first time in
the DSS curve will be treated as time 0.0. See Section 8.6.5 for more
information.

Appendix A TCF Commands - 41 / 147 Page 721 / 1094

 Command Solver Description

@2318
HPC 1D Synchronisation == HPC Only The 1D timestep for a HPC 1D/2D linked model is the maximum or
[ {MAXIMISE 1D TIMESTEP} | EVERY limiting timestep the 1D solver can use. The 1D solver act as an
2D TIMESTEP] | [{10 ] adaptive/varying timestep solution, and can step at different multiples of
steps to the HPC 2D solver. Both 1D and 2D solutions are always
synchronising at the 2D target timestep, or a multiple of the 2D target
timestep if the 1D timestep is sufficiently greater for the 2D to perform
more than one step. If the 1D limiting timestep is less than half the 2D
target timestep, the 1D proceeds in two or more steps eventually
synchronising with the 2D timestep. Where there is not a one-to-one
synchronisation of the 1D and 2D timesteps, a usually negligible mass
error may occur and can be checked by reviewing the CME% values
shown on the Console Window (Section 14.2 , the .tlf file (Section
14.5.1 ) or the _MB.csv file (Section 14.8 ) in the same manner as
Classic. This command forces the 1D and 2D timestepping to be
synchronised one-to-one. For more information on timestepping, see
Section 3.5 .

@2319
HPC [Thin | HPC Only New command for the TUFLOW 2023 release that sets the 2D weir flow
Thick] Weir Parameters == parameters in the HPC solver at thin/thick breaklines, see Section 7.4.4
[ ⟨ Cd ⟩ , ⟨ Ex ⟩ , ⟨ a ⟩ , ⟨ b ⟩ ] . These parameters are the weir coefficient (Cd), the weir flow equation
exponent (Ex) in the advanced weir equation (Section 5.7.5.3), and the
exponents used in the Villemonte equation (a and b). The default values
are 0.577, 1.5, 8.55 and 0.566, respectively.

@2328
HPC Boundary Approach == HPC Only Used to set which HPC Boundary approach to use, for more information
[ Method A | Method B | {Method see Section 8.3.2.1 . Method C is the default which applies energy
C} ] corrections for HT, HQ and QT boundaries. Method B applies energy
correction for HT, HQ, QT and HX boundaries connected to a single 1D
node. Method A, the default for TUFLOW Classic, applies no energy
connections.

Appendix A TCF Commands - 42 / 147 Page 722 / 1094

 Command Solver Description

@2329
HPC Device Split == HPC Only If a model is simulated across multiple GPU devices, one of the devices
[ ⟨ value1, value2, … ⟩ ] (non (usually the one with the most wet cells) will be controlling the speed of
Quadtree) the simulation and the other devices will be under-utilised. By default,
TUFLOW HPC divides a model equally over multiple GPU devices. It is
usual for the GPUs to have an un-equal amount of workload due to the
number of active cells and number of wet cells, and this can change
throughout the simulation as the model wets and dries. This command
allows the user to distribute the workload unequally to the GPU devices.

During a simulation the workload efficiency of each GPU is output to the

console and to the .tlf file with a suggested distribution provided at the
end of the simulation. A number of iterations may be required to fully
optimise the distribution. For example, a model simulated across four
GPU devices reported at the end of the simulation in the .tlf file:

Relative device loads: 60.3% 100.0% 83.7% 53.2%

HPC Suggested workload balance HPC Device Split ==
1.23, 0.74, 0.89, 1.40

For further information see Section 12.8 .

Appendix A TCF Commands - 43 / 147 Page 723 / 1094

 Command Solver Description

@2332
HPC DP Check == HPC Only The default setting of “CHECK”, causes TUFLOW to report CHECK 2420
[ ERROR | OFF | {CHECK} ] (advising that it is recommended to use the single precision version of
the HPC Solver). Due its explicit formulation and being depth based,
TUFLOW HPC does not usually require to be run in double precision
(DP) mode. For information refer to Section 13.4.2 and the TUFLOW
Wiki. There can also be substantial speed gains using single precision
(SP) on some GPU cards, and there is a significantly less memory
footprint. If DP is desired or required for the HPC (and as such, the GPU
Module) specify HPC DP Check == OFF in the .tcf file, and run using
a DP TUFLOW exe. Prior to the 2025 release the default setting of this
command was “ERROR”, causing TUFLOW to stop with ERROR 2420.
This downgrade was made as there are some instances that may
require the use of double precision when using TUFLOW HPC, as stated
in Section 13.4.2 .

@2333
HPC Dry Face Inertia Approach == HPC Only Under rare conditions it is possible for the momentum at a dry face to
[ Method A | {Method B} ] increase even though there is no actual flow across the face, leading to
a runaway velocity condition that drives the timestep down in HPC
solver. A stability improvement was introduced in the 2020-10-AA build
(Method A) that prevents this from happening. Method B, introduced in
the 2020-10-AB build, improves this fix as it was noted that Method A
could cause very faint (generally sub-centimetre scale) noise in afflux
differences. Method A is available for backward compativility to the 2020-
10-AA build. It is strongly recommended to use Method B (the default).

@2334
HPC dt Write Interval == HPC Only Sets the output interval for information written to the .hpc.dt.csv file
[ ⟨ number of timesteps ⟩ | {⟨ (Section 14.5.1.1 ). If not set the default is to use the Screen/Log
Screen/Log Display Interval ⟩ } ] Display Interval . If set to zero of less the file is supressed and not
written.

Appendix A TCF Commands - 44 / 147 Page 724 / 1094

 Command Solver Description

@2339
HPC HQ Boundary Approach == HPC Only HQ boundary computes the flux across the entire boundary line and
[ CELL | {TOTAL} ] 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 HQ boundaries using a cell
by cell approach by setting this command to ‘CELL’. For more
information see Section 8.3.2.2 .

@2340
HPC HQ Boundary Filter Constant == HPC Only Introduced in 2023-03-AD. For cross-sections with very low longitudinal
[ {5} | ⟨ float ⟩ ] slope, the stage vs flow (HQ) relationship can become unstable - a small
change in flow causes a change in water level that subsequently causes
a similar but opposite change in flow. The user may specify the global
HQ boundary filter constant using this command, see Section 8.3.2.3
for further details. From the 2025.0.0 release the default value is 5. Prior
to this, it was set to 1, meaning no filtering (for backward compatibility).

Appendix A TCF Commands - 45 / 147 Page 725 / 1094

 Command Solver Description

@2343
HPC Infiltration Drying Approach == HPC Only Used to control drying when soil infiltration is present, see Section
[ Method A | Method B ] 8.3.2.4 . For models using SGS the default is Method B, otherwise the
default is Method A.

Infiltration is only computed for wet cells, consequently if the applied

rainfall rate is less than the infiltration rate then the cell will repeatedly
dry then wet. This can cause time output results to appear erratic and in
rare cases has resolved stability issues if SGS was implemented.
Currently infiltration rate is limited to the available water within a cell plus
a precision adjustment, allowing the cell to dry. An improved approach
(Method B) is to remove the precision adjustment for cells that have
positive rainfall, so they remain “wet” but with near zero available water,
thus eliminating the cyclical drying and wetting.

For models with SGS on the default approach is to use Method B, while
for Non SGS models the default approach is to use Method A for
backward compatibility. For non-SGS models there maybe be benefits in
switching to Method B noting that this will infinitesimally reduce the
amount of infiltration and therefore infinitesimally increase the amount of
surface water. For SGS activated models, Method B is recommended for
improved stability in rare cases and because the differences between
methods is even less due to the much smaller wetted area in the cell at
the drying point.

@2344
HPC Mannings Depth Approach == HPC Only Sets the approach used for the bed resistance calculation in the u and v
[ Method A | {Method B} ] direction (Section 7.2 ). “Method B” (the default) upwinds the depth of
flow at a face which has found to improve model stability. The previous
method is available by setting this command to “Method A”. Note, if
using the TUFLOW HPC SGS functionality, this command has no effect.

Appendix A TCF Commands - 46 / 147 Page 726 / 1094

 Command Solver Description

@2345
HPC Non-Newtonian Mixing Exponent == HPC Only
Used to specify the mixing exponents, m, o, and p to be used, see
[ ⟨ float ⟩ , ⟨ float ⟩ , ⟨ float ⟩ |
Section 7.4.6.2 . Must be in the range of 0-10.
{0, 0, 0} ]

@2352
HPC Restart Geometry == HPC Only Used to specify restart model geometry. From the 2020-10-AB build and
[ Restart File | {TGC} ] onwards, the default option is “TGC”, which uses the bed elevation
created by .tgc files. The “TGC” approach is consistent with the Classic
solver. The bed elevation from the restart file can be used by selecting
the option “Restart File”, this means changes in .tgc files won’t be
applied in the restarted model. The “Restart File” approach was the
default for HPC models prior to build 2020-10-AB. See Section 8.9.3 .
See also Restart File Ignore Fields .

@2353
HPC SX Momentum Approach == HPC Only Sets whether momentum flux is added to SX cells (Method B), which
[ Method A | Method B ] improves the boundary cell flow behaviour by applying appropriate
momentum source/sink, or if only mass flux is added to SX cells (Method
A). Method A is available for backward compatibility. See Section 8.3.2.4
.

@2354
HPC Temporal Scheme == HPC Only This command sets the order of the temporal solution for TUFLOW HPC
[ 1 | 2 | {4} ] simulations, see Section 13.5.3.1 . The default is the recommended 4th
order temporal solution therefore this command is usually not specified.
Available options are:

1 – First order out of place

2 – Second Order
4 – Fourth Order

We recommend the use of the 4th order temporal scheme as it is

unconditionally stable with adaptive timestepping turned on, and
has found to give excellent results. Lower order schemes save a
little on memory requirements, but are more prone to instability and
in some cases unreliable results.

Appendix A TCF Commands - 47 / 147 Page 727 / 1094

 Command Solver Description

@2355
HPC Timestep Approach == HPC Only Method A determines High Control Number (HCN) events according to
[ Method A | {Method B} ] dynamic control number factors. Method B, introduced in the 2025
release and set as the default, uses static control number factors.
Method B is more tolerant in models that have rapid wetting and drying.
See Section 3.5.4 .

@2356
HPC Weir Approach == HPC Only New command for the TUFLOW 2023 release that sets the 2D weir flow
[ Method A | Method B | {Method B approach in the HPC solver at thin/thick breaklines (see Section 7.4.4 ).
Energy} ]
Available options are:

“Method A”: applies a water level gradient limiter for weir flow
approximation.
“Method B”: applies the weir equation and uses the upstream water
level above the weir invert as Hu.
“Method B Energy” (default): applies the weir equation and uses the
upstream energy level above the weir invert as Hu.

Appendix A TCF Commands - 48 / 147 Page 728 / 1094

 Command Solver Description

@2357
HQ Boundary Approach == Classic Sets the approach to be used for automatically generated 2D HQ
[ METHOD A | METHOD B | {METHOD Only boundaries (refer to Section 8.5 ).
C} ] METHOD A extends the HQ curve by ten metres (or 32.8 ft if using
Units == US Customary) on its last point which can cause a
sudden change in the slope of the curve at this elevation. This method
does not issue WARNING 2365 if the top of the curve is exceeded
during a simulation.

METHOD B sets the top level in HQ curve to be that of the highest cell
elevation, and issues WARNING 2365 if the top of the curve is exceeded
during the simulation. If the elevation range of the curve is less than one
metre, the top elevation is raised to 1 metre above the lowest 2D cell.
Alternatively the 2d_bc d attribute (refer to Table 8.6 ) can be used to
specify the max depth to be used for generating the curve (if less than
1m it is set to 1m).

METHOD C (the default) automatically removes consecutive flow values

in automatic 2D HQ boundary tables. For existing models that run with
an automatic 2D HQ boundary, if the change in consecutive flow values
is less than 0.00001 the results may be very slightly affected by this
change. Use of Method B provides backward compatibility if this is an
issue.

@2358
HR Grid Output Cell Size == HPC Only SGS Only.
[ <distance> ]
Sets the map output resolution for high resolution grid outputs (Section
11.2.2.3 ). If this command is not defined, the default HR Grid Output
Cell Size is set based on the distance between SGS points.

Appendix A TCF Commands - 49 / 147 Page 729 / 1094

 Command Solver Description

@2359
HR Grid Output Use Face Elevations = HPC Only SGS Only.
=
When modelling breaklines in TUFLOW, “thin” breaklines modify the cell
[ {ON} | OFF ]
face elevations but do not modify the cell storages. When outputting
high-resolution outputs (Section 11.2.2.3 ) this command sets whether
the cell face elevations are used.

ON (default): face elevations are used.

OFF: face elevations are not used.

@2360
HR Interpolation Approach == HPC Only SGS Only. Sets the HR interpolation approach method. The HR output
[ Method A | Method B | Method C ] needs to interpolate cell centre water levels to cell corners. However, the
interpolation methods for the standard output (Map Output Corner
Interpolation == Method C) can produce “bumpy” HR water level
output in direct rainfall models with steep terrain, as the water level is
linearly interpolated from the cell centres/corners, while the change of
sub-grid elevations may not be linear.
The following approaches are available for the HR output interpolation:

Method A is the default option that applies the same water level
interpolation method used for the standard output.
Method B performs sheet flow checks at cell faces and ignores the
water level from the upstream cell.
Method C applies the same sheet flow checks as the Method B. In
addition, it also uses the number of wet SGS sampled points as a
weighting that biases non-sheet flow cells that further improves the
mapping to in-stream water levels.

See Section 7.4.3.2.3 and the High-Resolution Output TUFLOW Wiki

page.

Appendix A TCF Commands - 50 / 147 Page 730 / 1094

 Command Solver Description

@2361
HR Thin Z Line Output Adjustment == HPC Only SGS Only.
[ OFF | {ON CELL SIDES} | ON
Sets the Z Line Output Adjustment at thin breaklines for HR Outputs
ALIGNMENT ]
(Section 11.2.2.3 ). The three options provided are:

OFF: Thin breaklines do not affect the HR raster interpolation

ON CELL SIDES (default): This prevents interpolation across cell
sides that have thin breaklines.
ON ALIGNMENT: The location of the breakline within the TUFLOW
cell resolution is stored and stops interpolation occurring over this
topographic barrier.

@2362
HX Force Weir Equation == Classic When set to ON, forces the weir flow equation to be applied across all
[ ON | {OFF} | ⟨ value ⟩ ] Only active HX cell sides when the flow is upstream controlled (the default is
OFF). This command lowers the HX cell centre elevation by 0.002m
below the lowest active HX cell side elevation to force an adverse slope.
If a value is specified the feature is turned ON and the value is the
amount by which to set the HX cell centre elevation below the lowest
active cell side, for example, HX Force Weir Equation == 0.1
would use 0.1 instead of 0.002. See Section 7.5.2 . Note that the
default approach uses either weir flow or super-critical flow when
the flow is upstream controlled, depending on whether the ground
surface gradient from HX cell centre to cell side is adverse (weir
flow) or not adverse (super-critical flow). When the flow is
downstream controlled, regardless of the ground surface slope, the
full 2D equations are applied including allowance for momentum
across the HX 1D/2D link.

Appendix A TCF Commands - 51 / 147 Page 731 / 1094

 Command Solver Description

@2365
HX ZC Check == Classic If ON (the default), checks whether the minimum ZC elevation at or
[ {ON} | OFF ] Only along a HX object (see Table 8.5 and Table 8.6 ) is above the 1D bed
level interpolated between connected 1D nodes. This is necessary to
ensure that there is water in the nodes when the 2D HX cells start to
wet. If the ZC elevation is lower than the 1D bed level, unexpected flows
or a surge of water may occur into the 2D domain. See Section 8.5.1 .

Using the “Z” flag (see HX in ), the ZC elevation is automatically raised

at each 2D HX cell to slightly above the 1D node bed level. Only ZC
elevations that are below the 1D bed are raised.

The checks and any automatic raising of ZC points includes the Cell
Wet/Dry Depth value so that the ZC elevation is above the node bed
plus the cell wet/dry depth.

If this option is set to OFF, lower ZC elevations are allowed and no

automatic raising of ZC elevations occurs. Turning this check off is not
recommended and may results in mass balance issues.

@2366
If Event == Classic Controls which commands to process for different events, as specified
[ ⟨ e1 ⟩ | ⟨ e2 ⟩ | ⟨ e3 ⟩ | and HPC using the –e run (see Section 13.3.1 and Table 13.2 ) or Model Events
… ] .

The “If Event” block must be terminated by “End If”, otherwise an

ERROR occurs.

Optional “Else If Event” and “Else” blocks can be embedded between “If
Event” and “End If”. The first block encountered that refers to a specified
scenario is processed, and all remaining blocks within the “If Event” to
“End If” construct are ignored. If an “Else” block is used it must occur as
the last block (i.e. must occur after any “Else If Event” blocks) and its
commands are only processed if no previous blocks have been
processed.

Appendix A TCF Commands - 52 / 147 Page 732 / 1094

 Command Solver Description

@2373
If Scenario == Classic Controls which commands to process for different scenarios, as
[ ⟨ s1 ⟩ | ⟨ s2 ⟩ | ⟨ s3 ⟩ | … ] and HPC specified using the –s run option (see Section 13.3.2 and Table 13.2 )
or Model Scenarios .

The “If Scenario” block must be terminated by “End If”, otherwise an

ERROR occurs.

Optional “Else If Scenario” and “Else” blocks can be embedded between

“If Scenario” and “End If”. The first block encountered that refers to a
specified scenario is processed, and all remaining blocks within the “If
Scenario” to “End If” construct are ignored. If an “Else” block is used it
must occur as the last block (i.e. must occur after any “Else If Scenario”
blocks) and its commands are only processed if no previous blocks have
been processed.

@2380 1D2D Links ==

Index Classic A sophisticated indexing system was implemented in release version
[ {ON} | OFF ] and HPC 2018-03-AA to improve the run times of models with many HX and SX
links (see Section 10.2 . The improvement in run time is highly
dependent on the size of the 2D domain(s) versus the number of HX and
SX connections. It will also be more noticeable for HPC simulations on
high end GPU devices where the clock time of the 2D computational
effort is substantially lower than if running on a CPU. Improvements in
run time vary from around 10% for the tutorial models to over 4,000%
(i.e. over 40 times faster!) for a HPC model with 30,000 pit SX
connections. This feature benefits both Classic and HPC simulations,
and will also benefit links to external 1D schemes.

@2381 Drive ==
Input Classic Changes the drive letter of any input files with a full path specified. For
[ ⟨ drive_letter ⟩ ] and HPC example “Input Drive == K” changes any input filepaths that have a
drive letter to the K drive. Also see Output Drive . See Section 11.1 .

Appendix A TCF Commands - 53 / 147 Page 733 / 1094

 Command Solver Description

@2384 Region ==
Inside Classic Legacy command:
[ METHOD A | {METHOD B} ] and HPC
Specifies the method used to assign values to 2D cells or cell mid-sides
that fall within a polygon using commands that process polygons from a
GIS layer (e.g. Read GIS Mat ).

Method A uses the previous, much slower method, and is provided in

case of backward compatibility issues. Testing thus far has shown the
two methods yield identical results although it is possible that if a 2D cell
centre or mid-side point lies exactly on a polygon boundary different
results may occur.

Method B offers much faster processing than Method A. To appreciate

the increase in start-up time this feature offers, testing on two large
models reduced the start-up time from 20 minutes to 3 minutes for one
model, and from 40 minutes to 5 minutes for the other. The faster start-
up time occurs for any polygon layers being accessed from the .tgc and
.tbc files, particularly those containing large number of vertices.

@2385
Instability Water Level == Classic The default water level used to detect instabilities higher than the
[ {see_below} | ⟨ value ⟩ ] Only highest cell elevation of all cells (whether wet, dry or permanently dry).
Any unassigned elevations (which are given a value of 99999, are not
included). The default value is 10 metres (or 10ft if using Units ==
US Customary).

Alternatively, this command is used to set the instability water level

manually. See Section 16.3.2.5 .

@2388
Latitude == Classic Sets the latitude used for calculating the Coriolis term in the shallow
[ {0} | ⟨ Only water equations (Equations (7.2) and (7.3) ). A negative value
value_in_degrees_from_equator ⟩ ] indicates south of the equator. A zero value disables the Coriolis term.
See Section 7.5.5 .

Appendix A TCF Commands - 54 / 147 Page 734 / 1094

 Command Solver Description

@2391
Layered FLC Default Approach == Classic Used to specify the settings for layered flow constrictions (see Section
[ METHOD A | {METHOD B} | and HPC 7.3.8.3 ). The default setting is METHOD B (PORTION). For releases
METHOD C | METHOD D ] prior to 2016-03 METHOD A (CUMULATE) was used.

It is possible to individually specify the method to be used for each

structure. Specify either METHOD A (CUMULATE), METHOD B
(PORTION) or METHOD C in the Shape_Options attribute (refer to Table
7.18 ). If none of the options occur, the setting as specified in the
command Layered FLC Default Approach is used.

METHOD A (named CUMULATE in releases prior to 2020-10):

Accumulates losses through each of the layers in the 2d_lfcsh as
the depth of water increases.
METHOD B (named PORTION in releases prior to 2020-10) – the
default: Proportions the losses through each of the layers in the
2d_lfcsh based on the depth of water.
METHOD C: Combines the METHOD A and METHOD B
approaches by utilising METHOD A through to the top of Layer 3
and METHOD B above Layer 3.

Appendix A TCF Commands - 55 / 147 Page 735 / 1094

 Command Solver Description

@2392Cell Selection ==
Line Classic Legacy command:
[ METHOD A | METHOD C | {METHOD and HPC
Sets the method for selecting 2D cells along lines in GIS layers.
D} ]
Method A (used prior to Build 2006-06-AA) is the original method and is
provided for backward compatibility.

Method C (the default up until Build 2007-04-AC), uses the cell “cross-
hair” approach where a cell is only selected if the line intersects
imaginary “cross-hairs” that extend from cell mid-sides to cell mid-sides.

Method D (the default) selects cells using the same approach as for
Method C, however differs in that it uses a more advanced approach for
assigning interpolation weightings of 1D node water levels based on the
perpendicular intersection of the 2D cell centre with the boundary line
(similar to that used for Z Lines). This provides a “smoother” water
surface profile along HX lines, offers better stability along 1D/2D HX
interfaces, and is the recommended approach.

Method C and Method D are particularly useful along HX lines that

follow, for example, the top of a levee or flood defence wall, as it
ensures that the same cells selected along the 1D/2D interface are
those raised by the Z line.

@23932D2D Adjust Velocity Head ==

Link Classic Sets the proportion of the velocity head by which to adjust the water
[ [{0} | ⟨ value ⟩ ] Only levels along the 2D link line. A value of zero applies no adjustment whilst
a value of 1.0 adjusts (downwards) the level by V2/2g. The default is 0.0
(no adjustment). Some tidal models demonstrated improved
performance by setting to 1.0, however, where there is rapid changes in
velocities along a 2D link line, for example in an urban situation where
velocities vary considerably from road to garden to between buildings,
this feature may not improve the 2D link performance, therefore
sensitivity test before adopting. See Section 10.7.2 .

Appendix A TCF Commands - 56 / 147 Page 736 / 1094

 Command Solver Description

@23962D2D Approach ==
Link Classic Command used to determine the approach used to link multiple 2D
[ METHOD A | METHOD B | METHOD Only domains. See Section 10.7.2 .
C | {Method D} ]
Method A is the original 2D2D link approach introduced for the 2009-07
release. This command and Method B was also incorporated into the
2009-07 release.

Method B (also introduced for the 2009-07 release) was an improvement

over Method A which was prone to generating flows where the 2D2D link
was located along dry boundaries with “bumpy” topography. Method B is
preferred over Method A.

Method C (introduced for the 2012-05 release) is the same as Method B,

but allocates the storage of the 2D link cells (these cells do not
contribute to the model’s storage so the storage is assigned to the
hidden nodes) more evenly between the hidden nodes and ensures the
nodes’ bed elevation is at or below the lowest connected 2D link cell.

Method D (the default) includes significant enhancements to the 2D/2D

linking of different 2D domains. It is recommended that models utilising
2D/2D linking upgrade to Build 2013-12-AC or later where possible to
make use of these enhancements. For backwards compatibility, specify
Link 2D2D Approach == Method B.

@23972D2D Distribute Flow ==

Link Classic Improves the distribution of flow between 2D cells along 2d_bc 2D link
[ {ON} | OFF ] Only lines. The default is ON. For 2D/2D linking methods prior to Method D
OFF applies. See Section 10.7.2 .

Appendix A TCF Commands - 57 / 147 Page 737 / 1094

 Command Solver Description

@23982D2D Global Stability Factor ==

Link Classic Will globally factor all 2D link hidden 1D node storages to easily carry
[ {1.0} | ⟨ value ⟩ ] Only out a quick sensitivity test on the effect of increasing the storage of the
hidden 1D nodes or to globally improve stability along 2D link lines if
needed. The default value is 1.0. Usually, increasing the storage of the
hidden 1D nodes by up to around a factor of 5 has only a slight effect on
results. Note that any factor specified using the 2d_bc “a” attribute is
also applied on top of this factor. Also note that the default value for the
2d_bc “a” attribute using Method D is 1.0 (prior methods use 2.0). See
Section 10.7.2 .

@2401
Log Folder == Classic Redirects the .tlf and _messages file output to the specified folder.
[ ⟨ folder ⟩ ] and HPC Typically used to write these files to a folder named log under the runs
folder. For more information, see Section 14.5 .

@2404
Map Cutoff Depth == Classic The minimum depth used as the cutoff that TUFLOW outputs results.
[ {0.0} | ⟨ value_in_m ⟩ ] and HPC Results are only written for cells with depths above the cutoff depth. This
feature is particularly useful for direct rainfall modelling where there is a
need to differentiate between very shallow sheet flow and flooding. See
Section 11.6 . The value is in metres (greater than zero), or feet (if
using Units == US Customary).

Appendix A TCF Commands - 58 / 147 Page 738 / 1094

 Command Solver Description

@2407
Map Cutoff SGS == HPC Only Legacy command:
[ Average | {Exact} | Median |
SGS Only.
Minimum | Percentile ]
Used to control the elevation below which cells are shown as “dry” in the
map output.

For the average, exact, median, and minimum options, a optional

second argument can be specified which is the depth above the datum.
For example, “Map Cutoff SGS == Average | 0.05” will use an
elevation 0.05m above the average SGS elevation sampled for the cell.

A combination of Map Cutoff Depth and Map Cutoff SGS can be used
in conjunction, with the higher elevation used. When SGS is on, the Map
Cutoff Depth refers to a depth above the cell minimum elevation. For
example:

Map Cutoff Depth == 0.05

Map Cutoff SGS == Percentile | 25

Will use the maximum of 0.05m above the lowest SGS sampled
elevation, or the 25th percentile of the SGS elevations sampled within
the cell.

The elevation used for setting whether a cell is wet or dry in the map
output, is reported in the _grd_check file as the “Z_Map_Cutoff”. This is
the SGS Depth Output elevation for each cell plus the map cutoff depth.

Appendix A TCF Commands - 59 / 147 Page 739 / 1094

 Command Solver Description

@2408
Map Cutoff Vector == Classic Default value recommended.
[ {ON} | OFF ] and HPC
When using Map Cutoff Depth with mesh-based output files (XMDF,
DAT), the display of scalar and vector outputs at each mesh is controlled
by a 0/1 flag, which is set as 0 if the local depth is below the cutoff
depth. This flag disables the vector display in SMS however does not in
other GIS programs (e.g. QGIS release version 3.14), and thus the
velocity vectors could display everywhere for a global rainfall model
even if the Map Cutoff Depth command is specified.

The “ON” option (default) enables the map cutoff depth and sets the
vector output value as zero if the cell water depth is below the cutoff
depth. “OFF” option can be used for backward compatibility.

@2409
Map Output Corner Interpolation == Classic Legacy command:
[ METHOD A | METHOD B | {METHOD and HPC
This command determines the approach taken to extrapolate model
C} ]
results to the cell corners at the wet/dry interface.

Method A (the approach adopted prior to the 2013-12 release) was the
original routine where some issues were found with tracking the
maximum depth related outputs, particularly on steep slopes, at the
wet/dry interface where the depth extrapolated to the cell corners was
exaggerated as it was extrapolated horizontally.

Method B and Method C resolve the issues found in Method A. Method

B will provide slightly better output along thin breaklines where they are
dry or free-overfalling occurs, however, Method C provides the most
consistent extrapolation to cell corners in terms of tracking maximum
values at the wet/dry interface on steep slopes and is the recommended
approach and default setting.

Appendix A TCF Commands - 60 / 147 Page 740 / 1094

 Command Solver Description

@2410
Map Output Data Types == Classic Defines the data types to be output. Refer to and for a description of
[ {h V} | ⟨ data_types ⟩ ] and HPC available options. The data types may be specified in any order or
combination and are not case sensitive. Spaces between data types are
optional, however are strongly recommended to ensure there is no
misunderstanding.

For example to output water levels, velocities and unit flow enter the
following line:

Map Output Data Types == h V q

The default is:

Map Output Data Types == h V

The format(s) of the map output is controlled by the .tcf command Map
Output Format (refer to Section 11.2.2 for further information). Note
that not all Map Output Data Types are available for all formats due to
limitations or constraints of the format.

This command may also be defined for different output formats by

including the output format extension on the left of the command (refer
to Section 11.2.3 ). For example, to write the XMDF Map Output Data
Types H and D use:

XMDF Map Output Data Types == h d

This output format specific functionality is also available for commands

Start Map Output , End Map Output and Map Output Interval .

This command can be used within an Output Zone definition block to

change the setting from that for the entire model map output.

Appendix A TCF Commands - 61 / 147 Page 741 / 1094

 Command Solver Description

@2413
Map Output Entire Model == Classic The default is to produce map output for the whole model irrespective of
[ {ON} | OFF ] and HPC the number of Output Zones (refer to Section 11.2.5 ) being written.
Map output commands that occur outside Output Zone definitions apply
to the entire model (i.e. as is the case in previous releases). If map
output for the entire model is not required specify Map Output Entire
Model == OFF.

@2414
Map Output Format == Classic Sets the format(s) for TUFLOW map output.
[ {XMDF} | ⟨ formats ⟩ ] and HPC
The default setting for the 2023-03 release is the XMDF format. The
available output formats are listed in Section 11.2.2 . For example, to
output formats in XMDF and TIF formats specify:

Map Output Format == XMDF TIF

This command can be used within a Define Output Zone block to

change the setting from that for the entire model map output to be
different for the output zone.

There is no limit (other than disk space!) on the number of formats

specified per model simulation. Output format specific commands (Map
Output Interval , Start Map Output , End Map Output and Map Output
Data Types ) can then be used to customise each format type as per
the examples below. Refer to Section 11.2.3 .

For example, to set the Map Output Interval for XMDF output to 6
minutes specify:

XMDF Map Output Interval == 360

Or to only output depths (d) and Bed Shear Stress (BSS) in TIF format
specify:

TIF Map Output Data Types == d BSS

Appendix A TCF Commands - 62 / 147 Page 742 / 1094

 Command Solver Description

@2417
Map Output Interval == Classic The output interval in seconds for map based output. If the command is
[ ⟨ time_in_seconds ⟩ ] and HPC omitted, an ERROR 0045 is output.

If set to zero (0) no time based map output is produced, and only the
maximums are written (note tracking of maximums must be switched on
– see command Maximums and Minimums ).

This command can be defined for different output formats by including

the output format extension on the left of the command. For example, to
set the Map Output Interval for XMDF output to 6 minutes use:

XMDF Map Output Interval == 360

If only the maximums in TIF format are required, use:

TIF Map Output Interval == 0

This output format specific functionality is also available for commands

Start Map Output , End Map Output and Map Output Data Types .
Refer to Section 11.2 .

This command can be used within an Output Zone definition block to

change the setting from that for the entire model map output.

@2420
Map Output Vector Dry Zpts == Classic For mesh-based output files (XMDF, DAT), vector output is normally
[ ON | {OFF} ] and HPC displayed at a mesh vertex if one of the surrounding mesh elements is
wet. If using SGS, this will display vectors at nodes in partially wet cells
that are dry. This can result in velocity vectors displayed at mesh
vertices outside the vertical wall despite those cell corners being dry.
The 2020-10-AA release changes this behaviour by setting this
command to “OFF” by default, which will disable the vector outputs at
dry Zpts. This change applies to both SGS and non-SGS models, and
the “ON” option can be used for backward compatibility.

Appendix A TCF Commands - 63 / 147 Page 743 / 1094

 Command Solver Description

@2421Balance Corrector ==
Mass Classic Legacy command:
[ ON | {OFF} ] Only
No longer required or recommended for use subsequent to
implementation of Wetting and Drying == ON METHOD B. See the
TUFLOW 2010 Manual for details of command.

@2422Balance Output ==
Mass Classic If set to ON (the default), outputs the following:
[ {ON} | OFF ] Only
_MB.csv and _MB2D.csv files in the .tcf Output Folder and
_MB1D.csv in the .ecf Output Folder . These files contain mass
balance calculations for the overall model, 1D domains and 2D
domains at each time a line is displayed to the Console Window.
_MB1 map output for 2D domains only and if specified by Map
Output Data Types .
_TSMB and _TSMB1d2d GIS layers in the .ecf Output Folder .
These files contain summary and time based information on mass
errors occurring at all 1D nodes and at 1D nodes connected to 2D
HX links.

It is possible to use different timesteps for the mass balance outputs and
those shown on the Console Window. The command Mass Balance
Output Interval is used for setting the interval in the mass balance
outputs whilst Screen/Log Display Interval sets the interval for the
Console Window. A summary is included at the end of the simulation on
the display console and .tlf file of key model performance indicators (see
Section 16.2.3 ).

Setting to OFF does not produce any mass balance information to the
Console Window or data files, and will reduce run-times.

For more information, see Section 14.8 .

Appendix A TCF Commands - 64 / 147 Page 744 / 1094

 Command Solver Description

@2423Balance Output Interval ==

Mass Classic The output interval in seconds for the _MB.csv output files. See Section
[ ⟨ time_in_seconds ⟩ ] and HPC 14.8 . If set to 0 (zero), the output interval used is the timestep set by
the Timestep command. If the command is omitted (or set to -1), output
is at the lesser of Map Output Interval and Time Series Output Interval
.

@2426
Maximum 1D Channels == Classic Only used during the first pass through the model input files to allocate
[ ⟨ mchan ⟩ | {100000} ] and HPC temporary space. After this pass, the only memory required is for the
actual number of channels allocated. The default is 100,000, but can
now be increased (or decreased) if required. The upper limit on the
number of nodes is set to twice the number of channels. See Section 5.5
.

@2429
Maximum Courant Number == Classic Legacy command:
[ ⟨ Cr_max ⟩ ] Only
The command is only available for 2D only models.

The Timestep command is only used to set the initial timestep if

<cr_max> is greater than zero. It is possible to control the maximum rate
at which a timestep can increase by using the command Timestep
Maximum Increase . There is no limit to how quickly the timestep can
decrease.

For 2D only models (not supported for 1D/2D linked models or hidden
1D)

Appendix A TCF Commands - 65 / 147 Page 745 / 1094

 Command Solver Description

@2432
Maximum Points == Classic Controls the maximum number of elevation points that can exist in a GIS
[ ⟨ mp ⟩ | {500000} ] and HPC layer referenced by commands such as Create TIN Zpts , Read GIS Z
Line , Read GIS Z HX Line , Read GIS Z Shape , Read GIS Variable
Z Shape , Read GIS FC Shape and Read GIS Layered FC Shape . If
the number of points exceeds the amount specified, an ERROR occurs
and this command needs to be used to increase the maximum number
of points. This value can also be lowered to reduce RAM requirements.
See Section 7.3.5 .

@2435
Maximum Velocity Cutoff Depth == Classic This command sets the depth above which the maximum velocity is
[ ⟨ y ⟩ | {0.1} ] and HPC tracked as the maximum velocity, rather than the velocity at the peak
water level. See Section 11.2.3 .

If set to a large number that exceeds the greatest depth (e.g.

99999.), the maximum velocity will be as in releases prior to 2009-
07, (i.e.. based on the velocity at the peak water level).
If set to 0. (zero), the maximum velocity is tracked as the maximum
velocity irrespective of the velocity at the peak water level.
If <y> is set to a value greater than zero, the maximum velocity is
based on the velocity at the peak water level for depths below <y>,
while for depths above <y>, the maximum velocity is based on the
maximum velocity.

A small value of <y> (e.g. 0.1m which is the default) is recommended, as

high velocities can occur at very shallow depths during the wetting and
drying process.

Note, as a consequence of the velocities now being tracked

independently of the maximum water level (i.e. the maximum water level
and maximum velocity can occur at different times), the maximum unit
flow (q) and energy (E) were disabled.

Appendix A TCF Commands - 66 / 147 Page 746 / 1094

 Command Solver Description

@2438
Maximum Vertices == Classic Controls the maximum number of vertices that can exist in a single
[ ⟨ mp ⟩ | {100000} ] and HPC polyline or polygon in a GIS layer referenced by commands such as
Create TIN Zpts , Read GIS Z Shape , Read GIS Variable Z Shape ,
Read GIS Layered FC Shape , Read GIS Z Line , Read GIS Z HX
Line and Read GIS FC Shape . See Section 7.3.5 and Section
7.3.8.3 . If the number of vertices exceeds the amount specified, an
ERROR occurs and this command needs to be used to increase the
maximum number of vertices. This value can also be lowered to reduce
RAM requirements.

@2441
Maximums and Minimums == Classic Sets whether maximums and/or minimums are to be tracked and written
[ ON | OFF | {ON MAXIMUMS ONLY} and HPC as map output (see Section 11.2 ). The default setting for this command
] is ON MAXIMUMS ONLY. To suppress tracking and outputting of
maximums for map output set to OFF.

If set to ON or ON MAXIMUMS ONLY, additional information will be

displayed to the Console Window and .tlf file for each Screen/Log
Display Interval . Three numbers are displayed after “Mx” at the end of
each line. The first two numbers are the percentage of 1D nodes and
percentage of 2D cells that reached a new maximum in the last
computational timestep. The third number is the time in decimal hours
since no new maximum was recorded anywhere within the model. For
example, “Mx 10 21 0.0” indicates that 10% of 1D nodes and 21% of 2D
cells recorded a new maximum last timestep, and the time since the last
recorded maximum is zero. Once all 1D nodes and 2D cells have
reached their maximums the third (time) value will increase above zero.

This command can be used within an Output Zone definition block to

change the setting from that for the entire model map output.

Appendix A TCF Commands - 67 / 147 Page 747 / 1094

 Command Solver Description

@2442
Maximums and Minimums Only for Grids Classic Legacy command:
== and HPC
Writes only the maximum and minimum grids for specified Map Output
[ ON | {OFF} ]
Data Types at the end of a simulation. This command only applies if the
“Grid”, “TIF”, “FLT”, and/or “ASC” option is specified for the command
Map Output Format .

This command is provided for backward compatibility. The preferable

command is to use the output format specific functionality <format>
Map Output Interval == 0 to output the maximums only for a
specific format type. Refer to Section 11.2.2.2 .

This command can be used within an Output Zone definition block to

change the setting from that for the entire model map output.

@2443
Maximums and Minimums Time Series == Classic If set to ON, allows for tracking of maximums and minimums at every
[ {ON} | OFF ] and HPC timestep for PO and LP outputs. See Section 11.3.2 .

Appendix A TCF Commands - 68 / 147 Page 748 / 1094

 Command Solver Description

@2444
Maximums Approach == HPC Only Legacy command:
[ Method A | {Method B} ]
This command specifies the approach taken in tracking the maximums
for map outputs.

Method A is the original approach and only provided for backward

compatibility for legacy models.

Method B (the default) introduced for Build 2012-05-AC, fixes a bug that
would not correctly track the maximums if both cell cornered map output
(.xmdf and .dat formats) and the GRID (ASCII grid) output were both
specified. As a consequence of this bug, the approach for tracking cell-
centred output maximum water levels is now used by default for both
cell-centred and cell corner output formats. This may cause a very slight
lowering of maximum water levels (usually a mm or less) in isolated
locations.

@2445
Maximums Start Track Time == Classic If tracking of maximums is enabled (the default), this command can be
[ ⟨ time in hours ⟩ ] Only used to set a start time for tracking the maximums. For example, if a
model starts at 0 hours, and the user only wants to track maximums
after 24 hours of model warmup, Maximums Start Track Time ==
24 can be used. See Section 11.2 .

This command needs to be used in conjunction with the <format> Start

Map Output command.

Appendix A TCF Commands - 69 / 147 Page 749 / 1094

 Command Solver Description

@2448
Maximums Track Time == Classic Set to “ON” to enable the tracking of time of maximums for any specified
[ {OFF} | ON | OFF Completely | and HPC hazard outputs, as well as Bed Shear Stress (BSS), Stream Power (SP)
Velocity ] and Energy (E).

Set to “OFF” (the default), to track maximum values, but not the time of
maximum. This command does not apply to water level output; time of
maximum H “Tmax_h” continues to be tracked.

Set to “OFF Completely” to disable the “Tmax_h” output.

TUFLOW Classic Only: Set to “Velocity” to enable the “Tmax_V” output.

See Section 11.2 .

@2449
Meshparts == Classic If set to ON, the SMS mesh .2dm file is split up into different meshparts.
[ ON | {OFF} ] Only Meshparts are determined as follows:

Each 2D domain constitutes one meshpart.

Each 1d_nwk layer constitutes one meshpart.

The benefits of using meshparts are that for recent versions of SMS,
while viewing results different meshparts can be switched on and off.
Can also be useful when using the TUFLOW_to_GIS.exe utility to
remove meshparts from the output. An example is to remove the pipe
network layer WLLs from the output.

The name allocated to the meshpart is either the 2D Domain Name (see
Start 2D Domain ) or the 1d_nwk layer name. The meshpart names can
be clarified by opening the .2dm file in a text editor and searching for the
“MESHPART” keyword.

See Section 11.6 .

Appendix A TCF Commands - 70 / 147 Page 750 / 1094

 Command Solver Description

@2450
MI Projection == Classic Sets the geographic projection for all GIS input and output in MID/MIF
[ ⟨ .mif file ⟩ | and HPC format (see Section 4.4.1 ). If this command is omitted, TUFLOW
Projection_line_from_MIF_file ⟩ ] searches for a file “Header.mif” in each folder it opens GIS files, and
extracts the projection from this file. The “Header.mif” file is any GIS
layer in the correct projection exported in MID/MIF format. If no
“Header.mif” file is found, non-earth coordinates are assumed.

If a model has a mixture of .gpkg, .shp and .mif files as input, then the
projection must be specified for each (e.g. using GPKG Projection ,
SHP Projection and MI Projection ).

Appendix A TCF Commands - 71 / 147 Page 751 / 1094

 Command Solver Description

@2454
MI Projection Check Ignore Bounds = Classic This sets whether to ignore the MapInfo projection Bounds when the MIF
= and HPC projection check is processed (see Section 4.4.1 ).
[ {OFF} | ON ]
If a MapInfo Projection has been specified using the MI Projection
command, TUFLOW checks the projection of the input files against the
specified projection. If there is a discrepancy an ERROR is generated,
see GIS Projection Check to change this from an error to a warning
message.

Internally, when TUFLOW compares the projection of the incoming file

against the specified model project, it removes spaces, tabs and quotes
before checking to see if they match. This can occasionally cause issues
as different software may store the projection bounds differently (causing
an ERROR to be generated). For example, the projection line in a
MapInfo text file may look something like the below:

CoordSys Earth Projection 8, 104, “m”, 177, 0, 0.9996, 500000,

10000000 Bounds (-7500000.0, 2000.0) (8800000.0, 20000000.0).

The portion of this projection line to the left of the “Bounds” command
defines the parameters of the projection, the portion of to the right of the
“Bounds” defines a rectangle in which the coordinate system is valid.
Some GIS software will write these bounds differently for different layers
within the same projection. For example, the two projections below are
identical, though with slightly different projections bounds:

CoordSys Earth Projection 8, 104, “m”, 177, 0, 0.9996, 500000,

10000000 Bounds (-7500000.0, 2000.0) (8800000.0, 20000000.0).

CoordSys Earth Projection 8, 104, “m”, 177, 0, 0.9996, 500000,

10000000 Bounds (-7499999.0, 2000.0) (8800000.0, 20000000.0).

When not using the ignore bounds option, the differences in the
projection lines above would cause the model to stop, if ignoring bounds

Appendix A TCF Commands - 72 / 147 Page 752 / 1094

 Command Solver Description

the model would continue. The command “GIS Projection Check

== {ERROR} | WARNING” can be used to control whether TUFLOW will
halt the simulation with an error or give a warning and continue the
simulation if there is mis-match in the projection of the GIS file and the
projection of the model.

@2455 Events ==
Model Classic Alternative to using the –e option when running TUFLOW (see Table
[ ⟨ e1 ⟩ | ⟨ e2 ⟩ | ⟨ e3 ⟩ … ] and HPC 13.2 ). Up to nine (9) separate events that have been defined using
Define Event can be specified. Separate the event names using vertical
bars. The event names specified will be automatically appended to the
output filenames if ~e~ or ~eX~ are not in the .tcf filename.

For example:

Model Events == Q100 | 02h

Note that using the –e run option will override this command.

@2462 Output Zones ==

Model Classic Controls which outputs zones are to be used. If this command is omitted,
[ ⟨ oz_name_1 ⟩ | ⟨ oz_name_2 ⟩ | and HPC no output from Output Zones will be written. Separate multiple Output
….. ] Zones using a “|”. For example, to output from zones ZoneA and ZoneC
specify:

Model Output Zones == ZoneA | ZoneC

See Section 11.2.5 and the .tcf command Define Output Zone for
further information.

@2467 Platform ==
Model Classic Forces the .tcf file to only be run using either a 32-bit (w32) or 64-bit
[ w32 | w64 ] and HPC (w64) version. If the command is not specified, the model may be run in
either version. If the w32 version of TUFLOW is specified, and the w64
version is used, the simulation stops with an error. Similarly, if w64 is
specified, the simulation stops if the w32 version is used. For further
discussion see Section 13.4.1 .

Appendix A TCF Commands - 73 / 147 Page 753 / 1094

 Command Solver Description

@2468 Precision ==
Model Classic Used to force a model to use either the single or double precision
[ SINGLE | DOUBLE ] and HPC version of TUFLOW. If the command is not specified, the model may be
run in either version. If SINGLE is specified, and the double precision
version of TUFLOW is used, the simulation stops with an error. Similarly,
if DOUBLE is specified, the simulation stops if the single precision
version is used. For further discussion see Section 13.4.2 .

This command is useful for ensuring that the same (single or double)
version of TUFLOW is always used.

@2469 Scenarios ==
Model Classic Alternative to using the –s option when running TUFLOW (see Table
[ ⟨ s1 ⟩ | ⟨ s2 ⟩ | ⟨ s3 ⟩ | and HPC 13.2 ). Up to nine (9) separate scenarios that occur using If Scenario
… ] can be specified. Separate the scenarios names using vertical bars. The
scenario names specified will be automatically appended to the output
filenames if ~s~ or ~sX~ are not in the .tcf filename.

For example:

Model Scenarios == opA | opB

Note that using the –s run option will override this command.

@2476 TUFLOW Build ==

Model Classic Forces the .tcf file to only be run using the specified build of TUFLOW.
[ ⟨ build ⟩ ] and HPC See Section 13.4.1 . <build> must be identical to that displayed in the
.tlf file or when double clicking TUFLOW.exe. The simulation stops with
an error if the specified build is different to that used to run the model.

For example:

Model TUFLOW Build == 2010-10-AA-iSP-w64

Model TUFLOW Build == 2007-07-DB

Appendix A TCF Commands - 74 / 147 Page 754 / 1094

 Command Solver Description

@2479 TUFLOW Release ==

Model Classic Forces the .tcf file to only be run using a build from a specified release of
[ ⟨ release ⟩ ] and HPC TUFLOW. See Section 13.4.1 .

The specified release must be one of the following options:

2006-06
2007-07
2008-08
2009-07
2010-09
2010-10
2011-09
2012-05
2013-12
2016-03
2017-09
2018-03
2020-01
2020-10
2023-03

Appendix A TCF Commands - 75 / 147 Page 755 / 1094

 Command Solver Description

@2482
Negative Depth Approach == Classic Legacy command:
[ Method A | {Method B} ] Only
Method A represents the case of no special treatment of negative
depths.

Method B (the default) provides an improved performance in handling

negative depths (which are a consequence of a non-convergence of the
solution). It is only applied if a cell experiences a depth below zero at its
centre. If the flow across any of the four cell sides is extracting water
from the cell, a high friction is temporarily applied to that side and the
high friction is reduced back to normal within several timesteps. This
tends to stop a cell repeatedly experiencing a negative depth, which can
cause mass errors. The negative depth problem can be particularly
acute where there is very steep (supercritical) flow with high velocities,
combined with some cell sides attempting to switch into weir flow.

@2483 Output Compression ==

NetCDF Classic Sets the compression for the output NetCDF file (see Section 11.2.2.2
[ OFF | {ON} | ⟨ level ⟩ ] and HPC ). If set to ON (the default) a compression level of 1 is used. The
compression level can also be set via a number from 1 – 9. Higher levels
result in smaller files but are slower to write/access, with the greater the
number the greater the compression and slower the write/read time. If
set to OFF a NetCDF “classic” format is used without compression. If set
to ON a NetCDF 4 file is used with compression. The compressed
version works well in ArcMap and Matlab but not in QGIS at the time of
writing.

@2486 Output Direction ==

NetCDF Classic When output in NetCDF raster format (see Section 11.2.2.2 ) any vector
[ {ANGLE} | BEARING ] and HPC outputs (e.g. flow or velocity) are output as two datasets: magnitude and
direction, for example, magnitude_of_velocity and direction_of_velocity.
This command specifies whether the direction_of NetCDF attribute is in
arithmetic (0 degrees east) or geographic (0 degrees north). The default
is arithmetic.

Appendix A TCF Commands - 76 / 147 Page 756 / 1094

 Command Solver Description

@2487 Output Format ==

NetCDF Classic Sets the output format for the NetCDF outputs (see Section 11.2.2.2 ),
[ {Generic} | FEWS ] and HPC the outputs are similar but the FEWS format option outputs the
maximum, time of peak, duration outputs with a time stamp at the
beginning of the simulation to ensure that it loads correctly into FEWS.
For the generic output format no timestep is output with these static
datasets. For more information on the format please see the TUFLOW
Wiki page TUFLOW NetCDF Raster Format for more details.

@2488 Output Start Date ==

NetCDF Classic Sets the output units for the NetCDF (see Section 11.2.2.2 ) time
[ {2000-01-01 00:00} | OFF | ] and HPC variable. If set to OFF or NONE, the “units” attribute of the .nc file is
simply the simulation time unit (e.g. units = ‘hours’). If a date is provided
the NetCDF time units will be in the format “<unit> since <date>”. For
example, unit = ‘hours since 2000-01-01 00:00’ or ‘days since 2000-01-
01 00:00’. The default setting is ‘2000-01-01 00:00’ as not having a date
appears to cause issues in ArcMap. If a date is specified, it is strongly
recommended that this is in isodate format. TUFLOW does not check
the date is valid, it is simply written to the NetCDF time variable as
entered in this command.

See also NetCDF Output Time Unit command below.

@2489 Output Time Unit ==

NetCDF Classic Set the output time unit for .nc outputs (see Section 11.2.2.2 ). The
[ DAY | {HOUR} | MINUTE ] and HPC default is hours (as per other TUFLOW outputs). See also NetCDF
Output Start Date command.

Appendix A TCF Commands - 77 / 147 Page 757 / 1094

 Command Solver Description

@2490Cell Checks ==
Null Classic Legacy command:
[ ON | {OFF} ] Only
Switches on and off the checks that ensure null cells occur on one side
of an external boundary. A TUFLOW simulation prior to Build 2001-08-
AE will not proceed unless a null cell occurs on one side of an external
boundary cell (this was used to indicate the inactive side of the boundary
line). Setting this to OFF (the default) allows ESTRY models to be
inserted through the 2D domain with no need to specify null cells (e.g. a
1D creek flowing through a 2D floodplain). It also allows land cells,
instead of null cells, to be specified against a boundary on the inactive
side.

Note: Prior to Build 2001-08-AE models were checked for the null
cells along boundaries. For models prior to this build, you may
need to set this flag.

@2491 2D2D Link Iterations ==

Number Classic Specifies the number of iterations for setting water levels at control
[ {1} | ⟨ no_iterations ⟩ ] Only points along a 2D line in a 2d_bc layer for stitching 2D domains together.
See Section 10.7.2 .

Appendix A TCF Commands - 78 / 147 Page 758 / 1094

 Command Solver Description

@2494 Iterations ==
Number Classic Specifies the number of iterations per timestep (refer to Stelling (1984 )
[ {2} | ⟨ no_iterations ⟩ ] Only or Syme (1991 )). It is rare this value is changed from 2, the default.
Doubling the number of iterations slows down the simulation by roughly
a factor of two. If a value of less than 2 is specified, 2 is used. See
Section 7.2.2 .

The main exception to the default value of 2 is in the modelling of rapidly

varying flood waves such as dam break hydrographs. For simulations of
this kind, improved convergence and reduced mass error can be
achieved through increasing the number of iterations up to values as
high as 10, although usually 4 should suffice. The recommended
approach is if the simulation is demonstrating unacceptably high mass
error (e.g. &gt;3%), carry out sensitivity tests that increase the number of
iterations to ascertain whether a poor convergence using the default
value of 2 is the cause of the problem. If increasing the number of
iterations has no benefits keep the value at the default value of 2.

@2497 Approach ==
Output Classic Legacy command:
[ {DEFAULT 2016} | PRE 2016 ] and HPC
Sets the output approach. For the TUFLOW 2016-03 release a new
approach for time-series and summary .csv files was implemented that
combines the 1D and 2D plot (time-series) data into a single folder,
allowing utilities such as the QGIS TUFLOW Plugin to provide access to
all plot output under the one folder. Where no output format has been
specified, the new default for the 2016-03 uses the XMDF format.
Specifying Defaults == Pre 2016 or Output Approach == Pre
2016 sets the default to the DAT format.

It is intended that further enhancement of the default settings for map

and other outputs will be added to future releases.

Appendix A TCF Commands - 79 / 147 Page 759 / 1094

 Command Solver Description

@2498 Drive ==
Output Classic Changes the drive letter of any output files with a full path specified. For
[ ⟨ drive_letter ⟩ ] and HPC example “Output Drive == K” changes any output filepaths that have
a drive letter to the K drive. Also see Input Drive . See Section 11.1 .

Appendix A TCF Commands - 80 / 147 Page 760 / 1094

 Command Solver Description

@2501 Files [ {ALL} | NONE |

Output Classic Can be used to suppress or include certain time series and 1D output
INCLUDE | EXCLUDE ] == and HPC (see Section 15.3 ). Whilst this command currently only applies to 1D
[ ⟨ output type list ⟩ ] output it is assigned to the .tcf commands as is intended to extend to
other output files in future releases that may contain 2D output.

The EXCLUDE or INCLUDE options allow for a space delimited list of

file extensions or prefixes to be specified to exclude or include output
files and GIS layers from being written. The notation must be the same
as those used by TUFLOW. For example, “eof” would apply to the .eof
file. To exclude/include more than one layer ensure there are spaces
between the prefixes. If EXCLUDE or INCLUDE occurs more than once,
the latter occurrence prevails.

Note that for the .eof file, this only affects the writing of results output to
this file. The header information and input data written to the .eof file will
still be output.

Valid options to include or exclude are: EOF, 1d_mmH, 1d_mmQ,

1d_mmV, 1d_CCA, TS, TSF, TSL, TSMB, TSMB1D2D.

Examples:

Output Files EXCLUDE == EOF TSMB TSMB1D2D

Output Files INCLUDE == TS, 1d_CCA
Output Files ALL
Output Files NONE

The ALL and NONE options require no file type list. All output files will be
written, specification of the ALL or NONE option will nullify any prior
occurrence of an EXCLUDE or INCLUDE list; this is useful if you wish to
write no or all output files for one particular run – simply add Output Files
ALL to the end of the .tcf file.

Appendix A TCF Commands - 81 / 147 Page 761 / 1094

 Command Solver Description

@2504 Folder ==
Output Classic Redirects all TUFLOW output data except the log and summary files to
[ ⟨ folder ⟩ ] and HPC <folder>. See Section 11.1 . Typically used to write output to your local
C: or D: drive instead of filling up the network drive, or to keep results
separate to the input data. A URL can be used (e.g. \bmtserv ), which is
useful for running simulations on other computers, but with the output
directed to your local drive or other location (your drive will need to be
shared).

This command can be used within an Output Zone definition block to

change the setting from that for the entire model map output.

@2507 ==
Pause Classic Causes TUFLOW to stop whenever it encounters it. It can also be used
[ ⟨ message ⟩ ] and HPC to pause the simulation and display a given message. The user has the
option to continue or discontinue the simulation via a dialog window. See
Section 13.3.2 .

Example:

Pause == Invalid Scenario specified.

@2510
Pit Default Extrapolate Q Curve == HPC Only Q and VPI pit curves are automatically extrapolated using the orifice flow
[ {ON} | OFF ] equation. To cap flow at the last value in a depth discharge curve
(i.e. not extrapolate), this command can be set to “OFF”. See Section
5.11.3 .

Appendix A TCF Commands - 82 / 147 Page 762 / 1094

 Command Solver Description

@2511
Pit No 1D Connection == Classic Unconnected pits (see Section 5.11.2 ) will by default be simulated and
[ {CHECK} | {ERROR} ] and HPC will extract water from a 2D domain (i.e. they are treated as a virtual pipe
pit). A CHECK 1625 message is issued for unconnected pits (excluding
VPI and VPO pits), alerting the modeller to the possibility of a pit
possibly being inadvertently not snapped or within the Pit Search
Distance . Prior to Build 2018-03-AA an ERROR would occur for
unconnected pits such as “ERROR 1353 - No NA data for Node Pit1. If
all the pits should be connected (excluding VPI and VPO pits)”, the user
can specify the .ecf command Pit Search Distance ERROR to force an
ERROR 1626 in the case of a pit not being connected by snapping or
within the Pit Search Distance .

@2512Output Invalid Type ==

Plot Classic When a plot output type (Section 11.3 ) has been assigned to an invalid
[ ERROR | {WARNING} ] and HPC geometry type, TUFLOW will output WARNING 2136. For example, plot
output type “Q” (flow) is valid on a line but not a point.

This can be escalated to an ERROR by setting to “ERROR”.

@2513
PO Approach == Classic Legacy command:
[ METHOD A | {METHOD B} ] and HPC
METHOD A is the original 2d_po flow lines approach and only provided
as a precaution for legacy models. Method A and Method B should give
the same results, but Method B is much faster and can substantially
reduce simulation times if numerous 2d_po flow lines exist.

METHOD B (the default) utilises a substantially faster approach for

2d_po flow lines, which will not slow down a simulation if numerous
2d_po flow lines exist, as was occurring with old releases.

The previous approach can be used by specifyingPO Approach ==

Method A however, this should only be necessary in the event of a
problem arising in which case please email .

Appendix A TCF Commands - 83 / 147 Page 763 / 1094

 Command Solver Description

@2514
Process All Grids == Classic By default the input grid extents for any grids read using the ‘Read Grid
[ {OFF} | ON ] and HPC <grid type>’ command (e.g. Read Grid Mat ) are compared with the
TUFLOW model extent and if the input GIS raster is entirely outside of
the model area these are skipped to reduce the simulation start-up time.
This can be particularly useful if the DEM data is across many tiles, of
which only some tiles fall within the 2D domain. In other words, the .tgc
file can reference all tiles (e.g. for the whole of the UK), but only those
required for the 2D domain are accessed.

To process all grids, regardless of the grid extents, the following .tcf file
command can be included.

Process All Grids == ON

Processing of all input grids is set to “ON” if the previous defaults are
used (e.g. “Defaults == Pre 2017”).

@2515
Quadtree BC Parallel Inertia Approac HPC Only TUFLOW HPC Quadtree Only.
h ==
Controls the handling of inertia parallel at head boundaries for Quadtree
[ Method A | {Method B} ]
simulations. “Method B” provides consistency with TUFLOW Classic and
single level HPC. “Method A” is available for backward compatibility. The
default approach is recommended.

@2516
Quadtree Control File == HPC Only Specifies the quadtree control file (.qcf), see Section 7.4.1 . The
[ ⟨ .qcf_file ⟩ | Single Level ] keyword “Single Level” can be used instead of a control file to run the
Quadtree solver on a single grid model (i.e.. a fixed cell size).

Appendix A TCF Commands - 84 / 147 Page 764 / 1094

 Command Solver Description

@2519
Rainfall Boundaries == Classic The SMOOTHED TIME CENTRED option “smooths” the rainfall
[ {STEPPED} | SMOOTHED | and HPC histogram by converting it into a “hydrograph” shaped curve rather than
SMOOTHED TIME CENTRED ] a histogram shape as is usually adopted for rainfall hyetographs.

If TIME CENTRED is omitted (i.e. SMOOTHED option), the timing is

such that the first rainfall occurs at the time of the first rainfall but
because of the smoothing the volume of rainfall is delayed in time.

The STEPPED option (the default) 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).

See Section 8.5.3 .

@2520
Rainfall Boundary Factor == Classic Sets a global multiplication factor for all rainfall boundaries, including:
[ ⟨ value {1.0} ⟩ ] and HPC
Global Rainfall (Section 8.5.3.3 )
Read GIS RF (Section 8.5.3.4 )
Read GIS SA RF (Section 8.5.2.2 )
Gridded rainfalls (Section 8.5.3.5 )

@2523
Rainfall Control File == Classic Reads the text rainfall control file, if using time vary, gridded rainfall
[ ⟨ .trfc_file ⟩ ] and HPC inputs for the model. See Section 8.5.3.6 for a description of the rainfall
control file. Appendix F contains a full list of all the rainfall control file
commands.

Appendix A TCF Commands - 85 / 147 Page 765 / 1094

 Command Solver Description

@2526
Rainfall Gauges == Classic If each cell is only to be assigned one rainfall time-series (Section
[ One per Cell | {Unlimited per and HPC 8.5.3.4 ) use the “One per Cell” option. If One per Cell is set, an
Cell} ] ERROR 2070 is issued if a 2D cell is assigned rainfall from more than
one RF input (e.g. from overlapping RF polygons) as this would cause a
duplication of rainfall on that cell, and so is a good quality control check.
Note that if the common boundary of adjoining polygons intersects
exactly at a 2D cell’s centre, this ERROR can be produced (slightly re-
shape the polygons around the cell’s centre to fix this). This option can
also reduce the amount of RAM needed for direct rainfall models, as a
separate grid is not needed for each RF input.

@2527
Rainfall Null Value == Classic Rainfall timeseries read in via the Rainfall Control File (.trfc) (Section
[ {-99} | ⟨ null value ⟩ ] and HPC 8.5.3.6 ) can have a null value, which is user defined using this
command. The default null value is -99, and only applies to the IDW
rainfall interpolation approach. If a null value is detected at a point
location, the IDW interpolation is revised to ignore the location. If all
locations have a null value at a boundary time, an ERROR 2642 is
generated. Note, prior to release 2020-10 the default null value was
-99999, not -99.

@2530
RAM Optimisation == HPC Only Legacy command:
[ {ON} | OFF ]
Set to ON to optimise CPU RAM allocation for TUFLOW HPC
simulations. This will cause the CPU RAM requirements to use around
50% less memory. This command should only be set to OFF to identify
whether memory allocation is the cause of any issues when running the
HPC Solver.

Appendix A TCF Commands - 86 / 147 Page 766 / 1094

 Command Solver Description

@2531File ==
Read Classic Directs input to another file. When finished reading <file>, TUFLOW
[ ⟨ file ⟩ ] and HPC returns to reading the .tcf file. See Section 4.2.15 .

This command is particularly useful for projects with a large number of

simulations. Repetitive commands are grouped and placed in another
text file. If one of these commands changes, the command only has to
be edited once, rather than in every .tcf file. The command can be used
to redirect file(s) up to a maximum of ten levels.

Also available in .tgc and .ecf files.

@2534GIS 12D Network ==

Read Classic Reads the location of external 1D scheme nodes and channels.
[ ⟨ gis_layer ⟩ ] and HPC Supported 1D schemes are Flood Modeller (formerly known as ISIS),
XP-SWMM or 12D Solution’s DDA. 1D Nodes and Channels are referred
to as Nodes and Units in Flood Modeller; Nodes and Links in XP-
SWMM; and Pits and Pipes in 12D). The nodes in the GIS layer(s) are
required for linking the external 1D scheme to TUFLOW. The channels
are required only if using Read GIS X1D WLL to integrate 1D and 2D
results in the map output. The only attribute required is the ID of the
Flood Modeller node/unit, XP-SWMM node/link and 12D pit/pipe. See
Section 10.5.1 for details on linking an external 1D scheme to
TUFLOW, and Section 11.2.4 for integrating 1D and 2D results.

For linking with TUFLOW, the linked nodes must occur in this layer or in
a Read GIS X1D Nodes layer. The nodes and channels (links) can be
placed in separate layers, and split over several layers if desired. If
desired, and the WLL feature is not being used, the layer can solely
contain linked nodes and no channels.

Appendix A TCF Commands - 87 / 147 Page 767 / 1094

 Command Solver Description

@2537GIS 12D Nodes ==

Read Classic Legacy command:
[ ⟨ gis_layer ⟩ ] and HPC
This command is superseded by Read GIS X1D Network , but
continues to be supported for legacy models. It is now redundant as the
nodes can be placed in a Read GIS X1D Network layer (the Read GIS
X1D Network layer can only contain the nodes, and no channels, if so
desired).

@2540GIS 12D WLL ==

Read Classic Reads the location of an external 1D scheme’s WLLs. See Section
[ ⟨ gis_layer ⟩ ] and HPC 11.2.4 for integrating 1D and 2D results. The GIS layer is identical to
that used for Read GIS WLL .

@2543GIS 12D WLL Points ==

Read Classic Reads the location of an external 1D scheme’s WLL points for setting
[ ⟨ gis_layer ⟩ ] and HPC elevations and materials at points along WLLs. See Section 11.2.4 for
integrating 1D and 2D results for more details. The GIS layer is identical
to that used for Read GIS WLL Points .

Appendix A TCF Commands - 88 / 147 Page 768 / 1094

 Command Solver Description

@2546GIS Auto Terminate ==

Read Classic TUFLOW simulations can be stopped after the peak flood using the Auto
[ ⟨ file ⟩ ] and HPC Terminate feature. Set Auto Terminate is used to turn on this feature.

The 2D cells that are monitored are controlled by specifying a value of 0

(exclude) or 1 (include). Set Auto Terminate defines the value over the
entire grid. Read GIS Auto Terminate is used to vary the monitoring
location spatially.

At each Map Output Interval the monitored cells are compared against
two criteria:

1. The percentage of the wet cells that have become wet since the last
map output interval.
2. The velocity-depth product at the current timestep compared to the
maximum.

This command is used with the optional commands Auto Terminate dV

Cell Tolerance , Auto Terminate dV Value Tolerance , Auto Terminate
Start Time and Auto Terminate Wet Cell Tolerance .

Note, the Auto Terminate feature is only assessed at every Map Output
Interval .

Refer to Section 13.6.7 for more details.

Appendix A TCF Commands - 89 / 147 Page 769 / 1094

 Command Solver Description

@2549GIS Cyclone/Hurricane [ {} |
Read Classic Reads a cyclone or hurricane track, as discussed in Section 8.7 . The
NO PRESSURE ] [ {} | NO WIND ] == Only attributes of the GIS layer are listed in Table 8.14 . Only the first line in
[ ⟨ gis_layer ⟩ ] 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.

Note that Latitude must be specified so as to distinguish between

southern and northern hemispheres.

@2552GIS FC ==
Read Classic Legacy command:
[ ⟨ gis_layer ⟩ ] Only
It is recommended to use the .tgc command Read GIS Layered FC
Shape in preference to this command.

Opens a GIS layer containing details on flow constrictions to model

bridges, box culverts, etc, see Section 7.5.6.1 . This command may be
used any number of times.

Appendix A TCF Commands - 90 / 147 Page 770 / 1094

 Command Solver Description

@2555GIS GLO ==
Read Classic Opens a GIS layer containing details on gauge level output (2d_glo)
[ ⟨ gis_layer ⟩ ] Only locations (refer to Section 11.2.6 ). GLO controls map output based on
the height of the water at a specified location – this is useful for
producing a series of output based on gauge heights for flood warning
purposes. It can also be used to display the height of the water at the
gauge location to the screen.

A buffer has been incorporated so that GLO only repeats at a level once
the water level has moved at least 0.1m from the gauge level (this stops
repetitive output if the model is “hovering” or “bouncing” around a gauge
level.

Only the last occurrence of this command is used.

@2558GIS ISIS Network ==

Read Classic Reads the location of external 1D scheme nodes and channels.
[ ⟨ gis_layer ⟩ ] and HPC Supported 1D schemes are Flood Modeller (formerly known as ISIS),
XP-SWMM or 12D Solution’s DDA. 1D Nodes and Channels are referred
to as Nodes and Units in Flood Modeller; Nodes and Links in XP-
SWMM; and Pits and Pipes in 12D). The nodes in the GIS layer(s) are
required for linking the external 1D scheme to TUFLOW. The channels
are required only if using Read GIS X1D WLL to integrate 1D and 2D
results in the map output. The only attribute required is the ID of the
Flood Modeller node/unit, XP-SWMM node/link and 12D pit/pipe. See
Section 10.5.1 for details on linking an external 1D scheme to
TUFLOW, and Section 11.2.4 for integrating 1D and 2D results.

For linking with TUFLOW, the linked nodes must occur in this layer or in
a Read GIS X1D Nodes layer. The nodes and channels (links) can be
placed in separate layers, and split over several layers if desired. If
desired, and the WLL feature is not being used, the layer can solely
contain linked nodes and no channels.

Appendix A TCF Commands - 91 / 147 Page 771 / 1094

 Command Solver Description

@2561GIS ISIS Nodes ==

Read Classic Legacy command:
[ ⟨ gis_layer ⟩ ] and HPC
This command is superseded by Read GIS X1D Network , but
continues to be supported for legacy models. It is now redundant as the
nodes can be placed in a Read GIS X1D Network layer (the Read GIS
X1D Network layer can only contain the nodes, and no channels, if so
desired).

@2564GIS ISIS WLL ==

Read Classic Reads the location of an external 1D scheme’s WLLs. See Section
[ ⟨ gis_layer ⟩ ] and HPC 11.2.4 for integrating 1D and 2D results. The GIS layer is identical to
that used for Read GIS WLL .

@2567GIS ISIS WLL Points ==

Read Classic Reads the location of an external 1D scheme’s WLL points for setting
[ ⟨ gis_layer ⟩ ] and HPC elevations and materials at points along WLLs. See Section 11.2.4 for
integrating 1D and 2D results for more details. The GIS layer is identical
to that used for Read GIS WLL Points .

@2570GIS IWL ==
Read Classic Opens a GIS file defining the water level at the start of the simulation.
[ ⟨ gis_layer ⟩ ] and HPC This option allows the water level to vary spatially in height, for example,
to set water levels of lakes. This command may be used any number of
times. Note that if the water level of a cell is specified more than once,
the last occurrence prevails.

Note: This command overwrites any IWL values set in the .tgc file
for the same 2D cells.

For details see Section 8.9.1 . Initial water levels may also be read
directly from a grid file using the command Read Grid IWL .

@2573GIS LP ==
Read Classic Opens a GIS layer containing details on longitudinal profile output (LP)
[ ⟨ gis_layer ⟩ ] Only locations (see Section 11.3.2.2 ). This command may be used any
number of times.

Appendix A TCF Commands - 92 / 147 Page 772 / 1094

 Command Solver Description

@2576GIS Output Zone ==

Read Classic Reads a GIS layer containing a polygon that defines the region to be
[ ⟨ gis_layer ⟩ ] and HPC output. The attributes of the layer are not used. Refer to Section 11.2.5
for further information on Model Output Zones.

@2579GIS PO ==
Read Classic Opens a GIS layer containing details on plot output (PO) locations (see
[ ⟨ gis_layer ⟩ ] and HPC Section 15.4.3 ). This command may be used any number of times.

@2582GIS Reporting Location ==

Read Classic Reads GIS points and lines for time series result from 1D and 2D
[ ⟨ gis_layer ⟩ ] and HPC sections of the model. This feature has the ability to combine flows, and
track maximums, across 1D and 2D domains. See Section 11.3.3 for
further information.

@2585GIS X1D Network ==

Read Classic Reads the location of external 1D scheme nodes and channels.
[ ⟨ gis_layer ⟩ ] and HPC Supported 1D schemes are Flood Modeller (formerly known as ISIS),
XP-SWMM or 12D Solution’s DDA. 1D Nodes and Channels are referred
to as Nodes and Units in Flood Modeller; Nodes and Links in XP-
SWMM; and Pits and Pipes in 12D). The nodes in the GIS layer(s) are
required for linking the external 1D scheme to TUFLOW. The channels
are required only if using Read GIS X1D WLL to integrate 1D and 2D
results in the map output. The only attribute required is the ID of the
Flood Modeller node/unit, XP-SWMM node/link and 12D pit/pipe. See
Section 10.5.1 for details on linking an external 1D scheme to
TUFLOW, and Section 11.2.4 for integrating 1D and 2D results.

For linking with TUFLOW, the linked nodes must occur in this layer or in
a Read GIS X1D Nodes layer. The nodes and channels (links) can be
placed in separate layers, and split over several layers if desired. If
desired, and the WLL feature is not being used, the layer can solely
contain linked nodes and no channels.

Appendix A TCF Commands - 93 / 147 Page 773 / 1094

 Command Solver Description

@2588GIS X1D Nodes ==

Read Classic Legacy command:
[ ⟨ gis_layer ⟩ ] and HPC
This command is superseded by Read GIS X1D Network , but
continues to be supported for legacy models. It is now redundant as the
nodes can be placed in a Read GIS X1D Network layer (the Read GIS
X1D Network layer can only contain the nodes, and no channels, if so
desired).

@2591GIS X1D WLL ==

Read Classic Reads the location of an external 1D scheme’s WLLs. See Section
[ ⟨ gis_layer ⟩ ] and HPC 11.2.4 for integrating 1D and 2D results. The GIS layer is identical to
that used for Read GIS WLL .

@2594GIS X1D WLL Points ==

Read Classic Reads the location of an external 1D scheme’s WLL points for setting
[ ⟨ gis_layer ⟩ ] and HPC elevations and materials at points along WLLs. See Section 11.2.4 for
integrating 1D and 2D results for more details. The GIS layer is identical
to that used for Read GIS WLL Points .

Appendix A TCF Commands - 94 / 147 Page 774 / 1094

 Command Solver Description

@2597GIS XP Network ==
Read Classic Reads the location of external 1D scheme nodes and channels.
[ ⟨ gis_layer ⟩ ] and HPC Supported 1D schemes are Flood Modeller (formerly known as ISIS),
XP-SWMM or 12D Solution’s DDA. 1D Nodes and Channels are referred
to as Nodes and Units in Flood Modeller; Nodes and Links in XP-
SWMM; and Pits and Pipes in 12D). The nodes in the GIS layer(s) are
required for linking the external 1D scheme to TUFLOW. The channels
are required only if using Read GIS X1D WLL to integrate 1D and 2D
results in the map output. The only attribute required is the ID of the
Flood Modeller node/unit, XP-SWMM node/link and 12D pit/pipe. See
Section 10.5.1 for details on linking an external 1D scheme to
TUFLOW, and Section 11.2.4 for integrating 1D and 2D results.

For linking with TUFLOW, the linked nodes must occur in this layer or in
a Read GIS X1D Nodes layer. The nodes and channels (links) can be
placed in separate layers, and split over several layers if desired. If
desired, and the WLL feature is not being used, the layer can solely
contain linked nodes and no channels.

@2600GIS XP Nodes ==
Read Classic Legacy command:
[ ⟨ gis_layer ⟩ ] and HPC
This command is superseded by Read GIS X1D Network , but
continues to be supported for legacy models. It is now redundant as the
nodes can be placed in a Read GIS X1D Network layer (the Read GIS
X1D Network layer can only contain the nodes, and no channels, if so
desired).

@2603GIS XP WLL ==
Read Classic Reads the location of an external 1D scheme’s WLLs. See Section
[ ⟨ gis_layer ⟩ ] and HPC 11.2.4 for integrating 1D and 2D results. The GIS layer is identical to
that used for Read GIS WLL .

Appendix A TCF Commands - 95 / 147 Page 775 / 1094

 Command Solver Description

@2606GIS XP WLL Points ==

Read Classic Reads the location of an external 1D scheme’s WLL points for setting
[ ⟨ gis_layer ⟩ ] and HPC elevations and materials at points along WLLs. See Section 11.2.4 for
integrating 1D and 2D results for more details. The GIS layer is identical
to that used for Read GIS WLL Points .

@2609Grid RF ==
Read Classic Reads a comma-delimited or NetCDF (.nc) file to define the rainfall
[ ⟨ .csv_file ⟩ | ⟨ .nc_file ⟩ ] and HPC applied directly to 2D cells over time. The .csv file is an index file that
references the grids in either GeoTIFF (.tif), ASCII (.asc) or a binary (.flt)
format. The .nc file contains all the rainfall grids over time within the one
file. Refer to Section 8.5.3.5 for further information.

Note that the Read Grid RF command is located within the .tcf file,
unlike the Read GIS RF and Read RowCol RF commands which
are located within the .tbc file. This allows for the rainfall to be applied
across all domains if multiple 2D domains are being used. The Read
Grid RF command is not domain dependent whilst the .tbc file is.

@2614Hazard File ==
Read Classic Reads in a hazard file with a defined hazard threshold. The csv file
[ ⟨ file_name⟩.csv ] and HPC should contain three (3) columns defining the thresholds for depth,
velocity, and depth × velocity product respectively. See Section 11.2.3.1
.

@2618Materials File ==
Read Classic Reads a text file containing Manning’s n values for different materials
[ ⟨ file ⟩ | [ {1.0} | ⟨ and HPC (land-use types).
n_factor ⟩ ]
Two file formats (.csv and .tmf) are available and are discussed in detail
in Section 7.3.6 . Multiple materials files are also able to be specified.

If a second argument, <n_factor> is provided, this value is used to factor

all Manning’s n values. For example, to increase all Manning’s n values
by 10%, enter “ Materials File == My_Materials.tmf | 1.1”.

Only available for Bed Resistance Values == MANNING N based

bed resistance values.

Appendix A TCF Commands - 96 / 147 Page 776 / 1094

 Command Solver Description

@2623Restart File ==
Read Classic Reads a restart file written from a previous simulation (see Write Restart
[ ⟨ .trf_file ⟩ ] and HPC File at Time and Write Restart File Interval ). The file must have the .trf
extension, and if a 1D/2D model there must be a corresponding .erf file.

The water levels, velocities, wetting and drying status and other
information saved in the restart file are used as the initial conditions for
the simulation.

Note that the simulation start time needs to be changed to be the same
as the time of the restart file.

Refer to Section 8.9.3 for further information.

@2626RowCol IWL ==
Read Classic Legacy command:
[ ⟨ .mid_file ⟩ ] and HPC
Opens a .mid file defining the water level in each cell at the start of the
simulation. This option allows the water level to vary spatially in height,
for example, to set water levels of lakes. This command may be used
any number of times. Note that if the water level of a cell is specified
more than once, the last occurrence prevails.

Note: This command overwrites any IWL values set in the .tgc file
for the same 2D cells.

For details see Section 8.9.1 . Initial water levels may also be read
directly from a grid using the command Read Grid IWL .

@2629Soils File ==
Read Classic Reads a text file containing an integer soil ID, infiltration method and soil
[ ⟨ file.tsoilf ⟩ ] and HPC parameters for different soil types. Refer to Section 7.3.7 for more
information.

Appendix A TCF Commands - 97 / 147 Page 777 / 1094

 Command Solver Description

@2632
Recalculate Chezy Interval == Classic Warning: This command overwrites any previous use of Bed Resistance
[ {0} | ⟨ timesteps ⟩ ] Only Values by setting CHEZY.

Sets the number of timesteps between recalculation of Chezy values

based on the ripple height. The default value of zero indicates Chezy
values are not recalculated (i.e. remain constant throughout the
simulation). See Section 7.5.3 .

@2635 Gauge Data ==

Record Classic Sets whether to automatically include reporting location lines, reporting
[ RLP | RLL | Gauge ] and HPC location points, and gauge locations (PO ‘G_’ type) when processing
gauge receptor objects, see Section 11.4.1 . The default is to include all
reporting location lines, points and gauges.

The options are:

“RLP”: reporting location points

“RLL”: reporting location lines
“Gauge”: gauge locations (2d_po ’G_ type)

@2636 Gauge Data EXCLUDE ==

Record Classic Sets whether to automatically exclude reporting location lines, reporting
[ RLP | RLL | Gauge ] and HPC location points, and gauge locations (PO ‘G_’ type) when processing
gauge receptor objects, see Section 11.4.1 . The default is to include all
reporting location lines, points and gauges.
The options are:

“RLP”: reporting location points

“RLL”: reporting location lines
“Gauge”: gauge locations (2d_po ’G_ type)

Appendix A TCF Commands - 98 / 147 Page 778 / 1094

 Command Solver Description

@2637
Restart File Ignore Fields == HPC Only Used to specify which fields to ignore for restart files.
[ ⟨ field ⟩ ] 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.

Appendix A TCF Commands - 99 / 147 Page 779 / 1094

 Command Solver Description

@2640 1D Nodes ==
Reveal Classic When set to ON, displays the hidden 1D nodes within a 2d_bc 2D link
[ ON | {OFF} ] and HPC line for models containing multiple 2D domains and for QT boundaries.
Refer to Section 10.7.2 for more information.

@2641
SA Minimum Depth == Classic Sets the minimum depth a wet cell must have to apply an SA Inflow (see
[ {-99999} | ⟨ depth in m ⟩ ] and HPC Section 8.5.2 ). This can resolve a problem that has occurred where
large SA inflows onto very shallow, high roughness, areas can appear to
gradually flow up hill. This was being caused by the SA inflow being
greater than the rate at which the flow was travelling overland and the
water would slowly creep up the dry slope at the edge of the flooded
area. In such situations using a SA Minimum Depth of around 0.1m will
ensure that this does not occur. Note that the only cases this problem
has been seen to occur was when modelling an extreme flood event
(PMF) on gently sloping high roughness areas.

@2644
SA Proportion to Depth == Classic This command proportions the SA inflows according to the depth of
[ {ON} | OFF ] and HPC water (see Section 8.5.2 ). This feature also enhances SA inflows by
applying an inflow in proportion to the depths of water of the wet cells
contained within the SA polygon. Where the SA hydrographs have been
derived by a hydrologic model that has already included routing effects,
this feature will tend to place more inflows in the deeper areas (i.e. the
creeks, rivers and downstream areas of the SA region), and hence
reduce any routing duplication effects.

Proportioning to depth provides improved performance if using as a side

inflow, especially for dam break type analyses, and reduces the effect of
any duplicated routing when applying local hydrographs from a
hydrology model.

Appendix A TCF Commands - 100 / 147 Page 780 / 1094

 Command Solver Description

@2645
Screen/Log Display Interval == Classic Sets the frequency for display of output to the computer screen and log
[ {1} | {10} | {100} | ⟨ and HPC (.tlf) file (see Section 14.2 ). The default display frequency for TUFLOW
timesteps⟩ ] Classic is 1, TUFLOW HPC on CPU is 10 and TUFLOW HPC on GPU is
100.

A value of zero is treated the same as for a value of 1. A value of ‑2

suppresses the display except for any negative depth warnings. A value
of ‑3 suppresses all timestep displays.

@2648
Set Auto Terminate == Classic TUFLOW simulations can be stopped after the peak flood using the Auto
[ ⟨ 0 ⟩ | 1 ] and HPC Terminate feature. Set Auto Terminate is used to turn on this feature.

The 2D cells that are monitored are controlled by specifying a value of 0

(exclude) or 1 (include). Set Auto Terminate defines the value over the
entire grid. Read GIS Auto Terminate is used to vary the monitoring
location spatially.

At each Map Output Interval the monitored cells are compared against
two criteria:

1. The percentage of the wet cells that have become wet since the last
map output interval.
2. The velocity-depth product at the current timestep compared to the
maximum.

This command is used with the optional commands Auto Terminate dV

Cell Tolerance , Auto Terminate dV Value Tolerance , Auto Terminate
Start Time and Auto Terminate Wet Cell Tolerance .

Note, the Auto Terminate feature is only assessed at every Map Output
Interval .

Refer to Section 13.6.7 for more details.

Appendix A TCF Commands - 101 / 147 Page 781 / 1094

 Command Solver Description

@2651
Set IWL == Classic If a <value> is specified, sets the initial water level for all cells in the 2D
[ ⟨ value ⟩ | AUTO | {0.0} ] and HPC domain to the value, see Section 8.9.1 . Initial water levels for individual
cells can be overwritten using Read GIS IWL or Read Grid IWL .

If AUTO is specified, sets the IWL in 1D and 2D domains to the value of

the water level boundary in the model at the start of the simulation. If the
model has more than one water level boundary, and the starting level is
different, an ERROR 0037 occurs. This feature only works for HT and
HS boundaries. Note that the initial water level is only applied to 1D
nodes and 2D cells that have been allocated a zero IWL (this is the
default value). This means that Read GIS IWL can still be used to set
the IWL in other parts of the model, such as a lake. Note that if Read
GIS IWL sets a zero IWL, then this will be overridden by the AUTO
value.

Note: This command overwrites any IWL values set in the .tgc file
for the same 2D domain.

@2654
Set Route Cut Off Type == Classic Sets the cutoff value type for evacuation routes if the Cut_Off_Type
[ {Depth} | Velocity or V | Only attribute in the Read GIS Z Shape Route layer is blank. Depth, velocity
Hazard or VxD or Z0 | Energy ] and hazard options are available. The cutoff values are set using Set
Route Cut Off Values in the .tcf and/or .tgc file, and evacuation routes
are described in Section 11.4.2 and set using the .tgc file command
Read GIS Z Shape Route .

This command may be used in either the .tcf and/or .tgc file. If used in
the .tcf it is the global default setting when the .tgc file is processed. If
used in the .tgc file its location in the file is important in that it only
applies to subsequent evacuation route commands. It may be used any
number of times in the .tgc file so as to change the evacuation route
settings at different points within the .tgc file.

Appendix A TCF Commands - 102 / 147 Page 782 / 1094

 Command Solver Description

@2655
Set Route Cut Off Values == Classic Sets the cutoff values for the evacuation route feature (see Section
[ ⟨ y1, y2, … ⟩ ] Only 11.4.2 ) if the Cut_Off_Values attribute in the Read GIS Z Shape Route
layer is blank. The type of cutoff values is set using Set Route Cut Off
Type and evacuation routes are set using the .tgc file command Read
GIS Z Shape Route .

This command may be used in either the .tcf and/or .tgc file. If used in
the .tcf it is the global default setting when the .tgc file is processed. If
used in the .tgc file its location in the file is important in that it only
applies to subsequent evacuation route commands. It may be used any
number of times in the .tgc file so as to change the evacuation route
settings at different points within the .tgc file.

Appendix A TCF Commands - 103 / 147 Page 783 / 1094

 Command Solver Description

@2658
Set Variable == Classic In any TUFLOW control file use of this command defines a variable’s
[ ⟨ value ⟩ ] and HPC name and value (Section 13.3.3 ). Wherever you want to refer to the
variable, the variable’s name must be bounded by “<< and “>>”
characters.

Note, that when using Set Variable do not use <<…>> to bound the
variable’s name as is required to reference the variable in the
control files.

Any scenarios and events are automatically set as a variable that can be
used within your control files. For example, if your model results are to
be output to different folders depending on Scenario 1 (~s1~), enter the
following into the .tcf file noting the use of ⟨⟨ and ⟩⟩ to delineate the
variable name.

Output Folder == ..\results\<<~s1~>>

In the case above, if Scenario ~s1~ is set to “OpA”, TUFLOW

automatically sets a variable named “~s1~” to a value of “OpA”, and the
output will be directed to “..\results\OpA”.

As an extension to the example above if the output folder is to also

include the first event name, which, for example, is the return period of
the flood, the following could be used:

Output Folder == ..\results\<<~e1~>>_<<~s1~>>

If Event ~e1~ is set to “Q100”, the output will be directed to

..\results\Q100_OpA.

Variables may be set to any characters and can be referred to as often

as needed in any control file and in other files such as the .tmf and .toc
files. At present you can’t use variables in the bc_dbase.csv files, but
future builds may offer this feature.

Appendix A TCF Commands - 104 / 147 Page 784 / 1094

 Command Solver Description

For example the lines below give some idea of how you could use
variables that explains how scenarios and events are automatically set
as available variables. The commands below set the model’s cell size,
timestep and output interval, and sets the folders for outputting check
files and results according to Scenario 1 which is the model’s grid
resolution (cell size), i.e.. one of “0.5m”, “1.0m” or “2.0m”.

.tcf file entries:

If Scenario == 0.5m
Set Variable 2D_CELL_SIZE == 0.5
Set Variable 2D_Timestep == 0.25
Set Variable Log_Int == 60
Else If Scenario == 1.0m
Set Variable 2D_CELL_SIZE == 1.
Set Variable 2D_Timestep == 0.5
Set Variable Log_Int == 60
Else If Scenario == 2.0m
Set Variable 2D_CELL_SIZE == 2.
Set Variable 2D_Timestep == 1.0
Set Variable Log_Int == 30
End If
! Set times
Start Time == 0
End Time == 0.5
Timestep == <<2D_Timestep>>
Write Check Files == ..\check\<<~s1~>>\
Output Folder == ..\results\<<~s1~>>\
Screen/Log Display Interval == << Log_Int >>

.tgc file entry:

Appendix A TCF Commands - 105 / 147 Page 785 / 1094

 Command Solver Description

Cell Size == <<2D_CELL_SIZE>>

Note that If Scenario and If Event operate at a higher level than Set
Variable , so that they can be used to set different values for the same
variable.

@2663
SGS == HPC Only To implement sub-grid sampling (SGS) the only command required is
[ ON | {OFF} ] SGS == ON.

For information on SGS see Section 7.4.3 .

@2664
SGS Approach == HPC Only SGS Only.
[ Method B | {Method C} ]
Sets the approach for Sub-grid Sampling when SGS is used. See
Section 7.4.3 .

Method C (default): retains the SGS elevations in memory

throughout the pre-processing stage and performs the generation of
the curves only at the end of the pre-processing of all elevation
data. Whilst this method can potentially use more memory (CPU
RAM) there are considerable benefits in terms of preserving sub-
grid elevation data at cells/faces partially affected by terrain data
layers and allows TUFLOW to produce high-resolution mapping at
the SGS sampling resolution.
Method B (legacy): elevations are processed into elevation-volume
curves (for cells) and elevation-flow area/width curves (cell faces)
after reading each elevation dataset. SGS elevations are discarded
after processing the dataset for memory efficiency.

Appendix A TCF Commands - 106 / 147 Page 786 / 1094

 Command Solver Description

@2665
SGS Breakline Detection Delta == HPC Only SGS Only.
[ ⟨ maximum delta value ⟩ ] Used to activate the SGS breakline detection delta check. See Section
7.4.3.1.2 .

The SGS breakline detection check processes each 2D cell to identify

the minimum water surface elevation needed for a continuous wet
connection through the cell traversing between left to right and between
top to bottom. The maximum invert elevation of the left and right faces is
subtracted from the left-right minimum water level and reports it as
“uDelta”. Similarly, the top to bottom value is reported as “vDelta”. uDelta
and vDelta represent the depth of water over the cell face inverts by
which a natural ridge (break) line would block any flow. If either uDelta or
vDelta exceeds the <maximum delta value> a spatial (GIS) CHECK
3542 message is issued at the cell location.

This command can add significant time to the initialisation process, it is

recommended to perform this check during model set up and to turn off
once the creation of breaklines is complete.

Appendix A TCF Commands - 107 / 147 Page 787 / 1094

 Command Solver Description

@2668
SGS Depth Output == HPC Only SGS Only.
[ EXACT | {CELL AVERAGE} | MEAN
Controls how map output values that use water depth are calculated for
| MEDIAN | MINIMUM |
mesh based outputs (e.g. XMDF, DAT) if SGS is used. See Section
PERCENTILE ]
7.4.3.2.2 .

CELL AVERAGE (default): calculates the depth by dividing the cell

volume by cell area.
EXACT: calculates the depth using the ZC and ZH elevations that
would be sampled at their respective locations if SGS was not used,
i.e. the elevations that would be sampled exactly at the cell centre
(ZC) and cell corner (ZH) locations if SGS was not applied.
MEAN: uses the average Z value assigned to the cell centre and the
cell corners from the SGS sampling, i.e. the map output shows the
average depth within a cell / around a cell corner (also see SGS ZH
Sample Ratio below).
MEDIAN: uses the median (50th percentile) elevation for the cell.
MINIMUM: uses the minimum Z value, i.e. the map output shows
the maximum depth within a cell / around a cell corner (also see
SGS ZH Sample Ratio ).
PERCENTILE: uses an elevation based on the specified set
percentile. This requires a second argument, separated by vertical
bar “|”, which is the percentile to use. For example, “SGS Depth
Output == Percentile | 25” will use the 25th percentile of
the SGS elevations sampled within the cell.

Appendix A TCF Commands - 108 / 147 Page 788 / 1094

 Command Solver Description

@2669
SGS Infiltration Approach == HPC Only SGS Only.
[ {AUTO} | TOTAL AREA | WETTED Sets the infiltration approach when SGS is enabled. See Section
AREA ] 7.4.3.1.2 .

Total Area: the infiltration rate used is the raw value computed from
the infiltration model regardless of whether the cell is fully wet or
partially wet. This is the best option for models with long periods of
direct rainfall leading to thin sheet flow.
Wetted Area: the infiltration rate used is factored down according to
the set area fraction of the cell. This the best option to use for the
infiltration of ponded water under no rain conditions.
Auto (default): enables the solver to choose between Total Area and
Wetted Area for each cell depending on whether or not the cell has
rainfall applied at that timestep. If rainfall is non-zero then the raw
infiltration rate is used (Total Area option), and if the rainfall is zero
the infiltration is factored down by the wet area ratio (Wetted Area
option).

Appendix A TCF Commands - 109 / 147 Page 789 / 1094

 Command Solver Description

@2670
SGS Map Extent ⟨ Full or Trim ⟩ == HPC Only SGS Only.
[ ⟨ map data types ⟩ | {ALL} ] Can be used to change the default trimming option (see Section
7.4.3.2.2 . The following options are available:

TRIM (default): sets which map data types are presented as “wet”
for partially inundated cells and which data types are trimmed based
on the Map Cutoff Depth .
FULL: partially wet cells are shown as wet in the map output.

For example:

“SGS Map Extent Trim == All” will trim all mapped data types
the Map Cutoff extents. This is the default and trims all output data
types to the Map Cutoff Depth extents.
“SGS Map Extent Full == h v hazard” will set the water level,
velocity and any hazard outputs to the full extent, while all other
data types will be trimmed.

@2675
SGS Materials == HPC Only Legacy command:
[ {OFF} | ON ]
SGS Only.

Used to enable or disable the sub-grid sampling of materials (land-use).

In the 2023-03 Release this functionality has been disabled and
TUFLOW will report ERROR 2568. It was included in the 2020-10
Release as beta functionality.

@2676
SGS Max Sample Frequency == HPC Only SGS Only.
[ ⟨ maximum frequency ⟩ ]
Sampling frequency in SGS models is capped at 31 sampling points per
cell face by default. This command can be used to increase this limit.
Note, a hard limit of 127 per face still applies. See Section 7.4.3.1.1 .

Appendix A TCF Commands - 110 / 147 Page 790 / 1094

 Command Solver Description

@2679
SGS Negative Rainfall Approach == HPC Only SGS Only.
[ TOTAL AREA | {WETTED AREA} ]
Controls the cell area used when negative rainfall is applied in
conjunction with SGS. See Section 7.4.3.1.2 .

Total Area: uses the whole cell area, regardless of the portion of the
cell that is wet.
Wetted Area (default): option uses only the wetted portion of the
cell.

@2680
SGS Sample Frequency == HPC Only SGS Only.
[ ⟨ frequency ⟩ ] The “frequency” sets the number of sample locations per face. See
Section 7.4.3.1.1 . If a quadtree mesh is used (Section 7.4.1 ),
different frequencies can be defined for each nesting level (e.g. SGS
Sample Frequency == 21, 11, 5).

If neither SGS Sample Frequency nor SGS Sample Target Distance is

set, a scan of the Geometry Control File (.tgc) is performed to find the
minimum raster grid resolution used in Read Grid Zpts commands, and
this is used as the sampling target distance to compute the sampling
frequency.

@2683
SGS Sample Target Distance == HPC Only SGS Only.
[ ⟨ distance⟩ ]
Sets the sampling target distance in meters or feet (if using Units ==
US Customary). This is the recommended approach to set the SGS
sample distance. TUFLOW requires an odd number of sample locations
across a cell face. For example, using a cell size of 10m and a sample
target distance of 1m, TUFLOW will use 11 sample points along the cell
face. If the target distance specified gives an even number, TUFLOW will
round up to the next odd number. See Section 7.4.3.1.1 .

Appendix A TCF Commands - 111 / 147 Page 791 / 1094

 Command Solver Description

@2686
SGS SX Z Flag Approach == HPC Only SGS Only.
[ Method A | {Method B} ]
If set to Method A, cells that are lowered by the “Z” flag on SX
connections are assumed flat (i.e. as per the approach for no SGS). The
default Method B retains the SGS information, but shifts it all to match
the lowered elevation. See Section 7.4.3.1.2 .

@2687
SGS TIN Memory Allocation Factor == HPC Only SGS Only.
[ {1.02} | ⟨ value ⟩ ]
Occasionally points modified by TINs exceed the size of temporary
memory allocated. This command can be used to increase this
temporary memory allocation. For example using a value of ‘1.1’ will
increase the temporary memory allocation by 10%.

@2690
SGS Velocity Based Outputs == HPC Only SGS Only.
[ {CELL AVERAGE DEPTH} | SGS
Sets how the depth is determined for output data types that use a
DEPTH OUTPUT ]
combination of depth and velocity in the calculation. The velocity used
for these outputs should usually be the cell average velocity. For
consistency a cell average depth (default) is applied for these output
types regardless of the “SGS Depth Output ” setting. However, if
desired, this can be changed by using “SGS Depth Output” which will
use the depth set by the “SGS Depth Output ” command.

@2691
SGS Z Shape Line Approach == HPC Only SGS Only.
[ Method A | {Method B} ]
If set to Method A, cell faces are assumed flat (i.e. SGS is not applied
and a rectangular section / flat cell is used). The default, Method B,
applies a gradient along the face based on the cell corners and cell side
Zpt values and for thick lines uses the ZC, ZU, ZV and ZH values to
apply a sloping cell area for the cell volume. See Section 7.4.3.1.2 .

Appendix A TCF Commands - 112 / 147 Page 792 / 1094

 Command Solver Description

@2692
SGS Zpt MAX/MIN Approach == HPC Only Legacy command:
[ IGNORE | {MINIMUM} | MEDIAN
SGS Only.
| CENTRE ]
When MAX/MIN options are used in SGS .tgc commands, the minimum
elevations are used to determine whether the new elevation is
higher/lower than the previous one (default option, MINIMUM). However
occasionally the new elevation has a median elevation lower than the
previous elevation, and in some situations, should be considered as the
“lower” elevation. This command allows users to specify which elevation
is used for the geometry updates using the MIN or MAX settings.

Only available using the legacy “SGS Approach == Method B”.

@2693
Shallow Depth Stability Factor == Classic Legacy command:
[ ⟨ SF ⟩ ] Only
Legacy command. No longer required or recommended for use
subsequent to implementation of Wetting and Drying == ON
METHOD B. See TUFLOW 2010 Manual for details.

@2696
SHP Projection == Classic Sets the geographic projection for all GIS input and output in Shapefile
[ ⟨ SF ⟩ ] and HPC (.shp) file format (see Section 4.4.1 ). This is used for checking whether
input layers are in the same projection, and for setting the projection of
all output layers (e.g. check layers).

If a model has a mixture of .gpkg, .shp and .mif files as input, then the
projection must be specified for each (e.g. using GPKG Projection ,
SHP Projection and MI Projection ).

Appendix A TCF Commands - 113 / 147 Page 793 / 1094

 Command Solver Description

@2699
SHP Projection Check Method == Classic Sets the method for processing of the shapefile format projection (.prj)
[ SIMPLE | {PARSED} ] and HPC file to ensure an input is the same as the model projection (see Section
4.4.1 ). Setting to PARSED (default) parses the parameter data into
number values and compares each of these numbers to check they are
consistent. Setting to ‘SIMPLE’ will read in the file as a character string.
Note, using ‘SIMPLE’ could cause issues if moving between GIS
platforms (e.g. between ArcMap and QGIS), as these could write the .prj
files slightly differently, particularly with a different number of decimal
places. For example, consider the two extracts from .prj files;
“PARAMETER[”latitude_of_origin”,0]” and
“PARAMETER[”latitude_of_origin”,0.0]”. A string compare would highlight
these as not matching.

@2700
Simulation Pause Interval == Classic This command can be used to pause a TUFLOW simulation at set
[ ⟨ Time interval in hours ⟩ ] and HPC intervals during the simulation. This will create a Console pause (Section
14.2 ) requiring a carriage return (enter key) to be pressed before the
simulation will continue.

@2703
Simulation Pause Start == Classic This command can be used to pause a TUFLOW simulation at a set time
[ ⟨ Model time in hours ⟩ ] and HPC during the simulation. This will create a Console pause (Section 14.2 )
requiring a carriage return (enter key) to be pressed before the
simulation will continue.

@2706
Simulations Log Folder == Classic This command is optional and can be used to sets the folder that the “_
[ ⟨ folder ⟩ | Do Not Use ] and HPC All TUFLOW Simulations.log” is written to (see Section 14.4.2 ). The
default folder is “C:\ProgramData\TUFLOW\log”. Setting this command
to ‘Do Not Use’ will supress the writing of the “_ All TUFLOW
Simulations.log”.

Appendix A TCF Commands - 114 / 147 Page 794 / 1094

 Command Solver Description

@2709Tolerance ==
Snap Classic Sets the search distance in metres or feet for detecting whether two GIS
[ {0.001} | ⟨ snap_distance ⟩ ] and HPC objects are connected (snapped), see Section 16.3.2.5 . Note that this
command can be repeated to change the tolerance only for a single
layer. For example the below could be used set the tolerance and then
return it to the default value:

Snap Tolerance == 0.01

Read GIS Network == ..\1d_nwk_example_L.shp
Snap Tolerance == 0.001

@2712Initial Loss ==
Soil Classic Provides flexibility in the handling of material imperviousness when
[ {Ignore Material Impervious} | and HPC applying soil initial losses, either using ILCL or Horton soil infiltration
Use Material Impervious ] methods (Section 7.3.7 ).

The initial losses can be used to model interception losses (i.e. water
that does not reach the soil), in which case the use of a material’s
imperviousness is not warranted and the default “Soil Initial Loss
== Ignore Material Impervious” is preferred.

For the “Soil Initial Loss == Use Material Impervious”

option, the initial loss is reduced by the material’s fraction
imperviousness.

@2713Negative Rainfall Approach

Soil == HPC Only Provides the ability for negative rainfall to draw from the topmost
[ {None} | Factor ] groundwater layer under surface layer cells that are dry, mimicking
evapotranspiration. Refer to Section 7.4.5.2.6 for more information.

“Factor” applies the defined negative rainfall at a (globally) factored rate.

To set the rate, see Soil Negative Rainfall Factor .

@2714Negative Rainfall Factor

Soil == HPC Only Sets the factor value when Soil Negative Rainfall Approach has been
[ ⟨ factor ⟩ | {1} ] set to “factor”. The default factor is 1, meaning that the full value of the
negative rainfall is applied. Refer to Section 7.4.5.2.6 for more
information.

Appendix A TCF Commands - 115 / 147 Page 795 / 1094

 Command Solver Description

@2717
Solution Scheme == Classic This command defines the 2D solution scheme to be used for a
[ {CLASSIC} | HPC | HPC 1st ] and HPC simulation.

Options are:

CLASSIC: the simulation will use TUFLOW’s finite difference implicit

2nd order solver (the default option).
HPC: the simulation will use TUFLOW HPC’s finite volume explicit
2nd order solver.
HPC 1st: uses TUFLOW HPC’s finite volume explicit 1st order
solver. When using HPC, the 2nd order solver is recommended over
the 1st order alternative due to its greater accuracy.

Refer to Section 7.2.1 for a description of TUFLOW HPC and Section

7.2.2 for a description of TUFLOW Classic.

@2718
Spatial Database == Classic Sets the database to use for subsequent inputs when using the
[ ⟨ GPKG database ⟩ ] and HPC GeoPackage format. For more information see Section 4.4.3 .

@2721
Spatial Database Output == Classic Sets how the outputs are written when using GeoPackages, see Section
[ SEPARATE | {GROUPED} ] and HPC 4.4.3.2 .

Options are:

Grouped (default): outputs will be grouped by folder location. For

example all check file outputs will be contained within one database.
Separate: outputs will be grouped by geometry only.

Appendix A TCF Commands - 116 / 147 Page 796 / 1094

 Command Solver Description

@2722 On Open SQL [ {} | Read |

SQLite Classic Executes SQL command(s) when a GPKG database is initially opened.
Write ] == and HPC This command is intended to be used to change general SQLite
[ ⟨ SQL Pragma Command ⟩ | {} ] database settings without the need for TUFLOW to provide custom
commands for each setting. Typically these would be what SQLite calls
‘PRAGMA’ commands. Database settings can be changed outside of
TUFLOW and by default TUFLOW won’t change these when reading
from a GPKG, however some applications could be making changes
without the user being aware (e.g. QGIS will change the journal mode
depending on whether the user is viewing the data or making edits to it)
so this command forces certain settings to be used when TUFLOW
accesses the database.

The addition of key words ‘Read’ or ‘Write’ can provide further context to
the command to apply specifically when TUFLOW is reading or writing
from a database. If neither ‘Read’ or ‘Write’ is provided, the command
will be applied to both read and write contexts.

Multiple SQL commands can be specified by separating the commands

by a semicolon ‘;’. If this command is used multiple times, the last
instance will be used and the command itself does not stack. The
exception to this is separate commands can be used for ‘Read’ and
‘Write’ contexts.

A typical example of using this command would to change the SQLite

journal mode which can be helpful to stop database locks when multiple
simulations are reading from the same database. This can happen when
the journal mode is set to Write Ahead Log (WAL) and one simulation
closes the database at the exact same instance another one is trying to
open it. This occurs because the WAL method forces the creation of a
new file (‘.WAL’) which is deleted when the database is closed (and no
other processes are accessing the database). A temporary lock is placed
on the database when the WAL is deleted and therefore stops any other

Appendix A TCF Commands - 117 / 147 Page 797 / 1094

 Command Solver Description

process from opening it. In this example the user could force TUFLOW
to change the journal mode to ‘delete’ which adopts a rollback journal
and stops any database locks from being placed when simply reading
from the database. The command to do this would be:

SQLite On Open SQL Read == PRAGMA journal_mode =

DELETE;

@2725 1D Domain
Start Classic Indicates the start of a block of 1D Commands (see Appendix B ) in the
and HPC .tcf file. Block must be terminated by using End 1D Domain .

@2726 2D Domain ==
Start Classic Indicates the start of a block of commands that define a 2D domain (see
[ {} | ⟨ 2d_domain_name ⟩ ] Only Section 10.7.2 ). If no 2d_domain_name is specified, the 2D domain is
automatically assigned a name. The name is solely used for reporting in
the .tlf file and elsewhere. Also see End 2D Domain . If there is only
one 2D domain, this command is optional.

@2729 Map Output ==

Start Classic The simulation time in hours when map output commences. If the
[ ⟨ time_in_hours ⟩ ] and HPC command is omitted, the simulation start time is used.

This command can be defined for different output formats by including

the output format extension on the left of the command. For example, to
set the start time for XMDF output to 1hr use:

XMDF Start Map Output == 1

This output format specific functionality is also available for commands

End Map Output , Map Output Interval and Map Output Data Types .
Refer to Section 11.2 .

This command can be used within an Output Zone definition block to

change the setting from that for the entire model map output.

Appendix A TCF Commands - 118 / 147 Page 798 / 1094

 Command Solver Description

@2732 Time ==
Start Classic Specifies the start time of the simulation in hours (see Section 4.2.4 ).
[ ⟨ time_in_hours ⟩ ] Only Value can be negative and it is recommended that it be relative to
midnight for historical events.

@2735 Time Series Output ==

Start Classic The simulation time in hours when time series (PO and LP) output
[ ⟨ time_in_hours ⟩ ] and HPC commences (see Section 11.3.2 ). If the command is omitted, the
simulation start time is used. Also see Time Series Output Interval .

@2738
Supercritical == Classic Sets the supercritical flow mode. If set to ON (the default), flow
[ {ON} | OFF | PRE 2002-11-AD ] Only automatically switches into upstream controlled friction flow, allowing the
supercritical flow conditions on steep slopes to be modelled. See
Section 7.5.2 and Froude Check for more details.

If set to OFF, and Free Overfall is set to ON, the broad-crested weir
formula applies where flow conditions are predicted to be upstream
controlled.

Setting to PRE 2002-11-AD provides backward compatibility for

simulations carried out using supercritical flow prior to Build 2002-11-AD.
In Build 2002-11-AD, additional checks using the Froude Number
specified by Froude Check were incorporated in addition to the
downstream/upstream controlled flow check comparison. This may
produce different results in some flow conditions. The ON option is to be
used in preference to the PRE 2002-11-AD option.

@2739Control File ==
SWMM Classic Specifies the TUFLOW SWMM control file (.tscf), see Section 4.2.14 for
[ ⟨ .tscf_file ⟩ ] and HPC details. See Appendix I for a list of the SWMM control file commands.

Appendix A TCF Commands - 119 / 147 Page 799 / 1094

 Command Solver Description

@2742
SX Flow Distribution Cutoff Depth == Classic Legacy command:
[ {AUTO} | ⟨ depth_m ⟩ ] and HPC
Sets the depth of water below which an SX boundary cell will not receive
flows from the connected 1D element. The default value {AUTO} equals
three times 1.5 times the Cell Wet/Dry Depth .

Prior to the 2016-03 TUFLOW release this was set to 0.0, as soon as the
cell was wet, flow was applied. Set to 0.0 for backward compatibility.

@2745
SX FMP Unit Type Error == Classic For 2D SX connections linked to Flood Modeller Pro (FMP) (Section 10.5
[ {ON} | Off ] and HPC ) a check is performed that the FMP node has been assigned as a
HTBDY node. If this is not the case, a spatial message (ERROR 2043) is
issued and the simulation is stopped.

This error message can be set to a warning with the .tcf command “SX
FMP Unit Type Error == OFF”. If set to off, the above will cause a
WARNING 2043 to be issued, but the simulation will be allowed to
continue.

@2746
SX Head Adjustment == Classic If OFF (the default), makes no adjustment for energy compatibility (i.e.
[ ON | {OFF} ] and HPC the 1D water level and 2D water level are set as equal to each other at
the 2D SX link). See Section 10.2.2 .

Appendix A TCF Commands - 120 / 147 Page 800 / 1094

 Command Solver Description

@2747
SX Head Distribution Cutoff Depth == Classic At an SX link (see Section 10.2.2 ), the water level sent through to the
[ {AUTO} | ⟨ depth_m ⟩ ] and HPC 1D node is based on the water levels of the wet SX cells. Prior to the
2017 release, this level was simply the average of the wet cells. This
approach can cause issues where there are a slightly wet SX cells that
are elevated above the SX cells within the main flow path. This primarily
occurs if using direct rainfall, or if there is some side flow cascading
down the higher SX cells.

For the 2017 release onwards, the default is to calculate the 1D water
level based on proportioning to the SX cell depth. This means that the
water level transferred to the 1D node is biased to that of the deeper
cells.

If depth_m is set to AUTO or is greater than 0.0001, any wet SX cells

with a depth less than depth_m is excluded, and the 1D water level is
calculated as a depth weighted average of the remaining wet SX cells.

@2750
SX Storage Approach == Classic Legacy command:
[ {1D NODE AVERAGE} | Cell Only ] and HPC
As of the 2017-09 release the default is to distribute the average 1D
node storage across connected SX cells (see Section 10.2.2 ). For
backward compatibility in legacy models, and to not assign additional
storage to the 2D SX cells based on the 1D node details, set the SX
Storage Approach to Cell Only.

@2751
SX Storage Factor == Classic <sxs_factor> is a multiplier that globally adjusts all additional storages
[ {1.0, 20.0} | ⟨ sxs_factor ⟩ , ⟨ and HPC applied to SX cells (see Section 10.2.2 ). <sxs_limits> sets the limit by
sxs_limits ⟩ ] which an SX cell can have its storage increased in addition to its own
storage. By default, this is a factor of 20, in which case, if a 1D node’s
storage increases an SX cell’s additional storage by more than 20, the
factor is limited to 20.

Appendix A TCF Commands - 121 / 147 Page 801 / 1094

 Command Solver Description

@2756
SX ZC Check == Classic If ON (the default), checks whether the minimum ZC elevation at or
[ {ON} | OFF | ⟨ dZ_limit_in_m ⟩ and HPC along a SX object (see Section 10.2.2 ) is below the connected or
] snapped 1D node bed level. This is necessary to ensure that the
channels connected to the node only start flowing once the 2D SX cell is
wet and the water level in the cell is above the lowest channel bed. If the
ZC elevation is higher than the lowest channel, unexpected flows or a
surge of water may occur in the 1D channels.

Using the “Z” flag (see SX in Table 8.6 ), the ZC elevation is

automatically lowered at each cell associated with a SX object to below
the connected or snapped 1D node bed level. Only ZC elevations that
are above the node are lowered. The checks and any automatic lowering
of ZC points includes the Cell Wet/Dry Depth value so that the ZC
elevation is below the node bed less the cell wet/dry depth.

If OFF, higher ZC elevations are allowed and no automatic lowering of

ZC elevations occurs.

A value may be entered to set a maximum permitted change in ZC

elevation caused by the use of any “Z” flags for 2D SX links. For
example, if SX ZC Check == 0.5 is specified, then if any 2D cell is
lowered by more than 0.5m an ERROR 2050 occurs. This allows the
modeller to automatically lower 2D cells within the specified limit, but
flag an ERROR 2050 if there is a substantial change, which usually
indicates there is something inconsistent between the 1D channel bed
and the 2D topography. It is strongly recommended that if using the
SX Z flag, that this option is specified.

Appendix A TCF Commands - 122 / 147 Page 802 / 1094

 Command Solver Description

@2759
TIF Compression == Classic Sets the compression for output GeoTIFF grids (see Section 11.2.2.2 ).
[ NONE | LZW | {DEFLATE} ] and HPC The following compression methods are available:

LZW (Read/Write)
DEFLATE (Read/Write) - default

Set to “NONE” to disable compression.

@2760
TIF Compression Predictor == Classic Sets the compression predictor, used to improve the compression ratio
[ NONE | {Horizontal and HPC for TIF outputs (see Section 11.2.2.2 ). Testing has shown that using
Differencing} ] deflate compression with “horizontal differencing” (default) will typically
achieve better compression than the typical method of using a ZIP file
on the same uncompressed data. Can be turned off using “NONE”.

@2761
TIF Projection == Classic Sets the .tif file projection for setting the projection of all output layers
[ /path/to/geotiff ] and HPC (e.g. check and result layers), see Section 4.4.1 . Currently there is no
input projection checking of raster layers.

Appendix A TCF Commands - 123 / 147 Page 803 / 1094

 Command Solver Description

@2762Output Corner Interpolation ==

Time Classic The tracking of the time of exceedance and duration (e.g. Time Output
[ {VALUE | ⟨ user specified value ⟩ } and HPC Cutoff Depths == 0.35, 0.50) is completed at each computational
| WET | START | ⟨ Offset ⟩ ] timestep at both the cell centres and the cell corners (Section 11.2.2 ).
This command allows the user to control how the cell corner values are
treated. This may alter result display on the flood fringe.

VALUE|<user specified value>: The cell corners are given a fixed value
which is user specified. Using this option any cell corners that have not
been exceeded will be given the output value of ‑99. This value can be
used to improve the output contouring. This is the default with a
specified value of -99.

WET: The cell corner values are based on an interpolation of the

surrounding wet cells. Note, this can mask the presence of thin
breaklines in the output.

START | <offset>: The cell corners are given a fixed value based on the
simulation start time plus an offset.

Appendix A TCF Commands - 124 / 147 Page 804 / 1094

 Command Solver Description

@2767Output Cutoff [Depths | VxD |

Time Classic If one or more comma or space delimited values are specified using this
⟨ Hazard⟩ ] == and HPC command, the map output (Section 11.2 ) will contain additional time
[ [ {OFF} | ⟨ v1, v2, … ⟩ ] output in hours for each value v1, v2, … as follows. The type of the
values is controlled by the [ Depths | VxD | ⟨Hazard⟩ ] setting (only one
of these can be specified).

Depths is the depth of water

VxD is the velocity times depth product, and
<hazard> must be one of the hazard categories as documented in
Table 11.5 . VxD and Z0 are one in the same.

1. The time that a cell first experiences a value greater than each of ,
the simulation time of exceedance is retained, and included in the
map output. If using the .xmdf output format, the data is accessed
using a simulation time of 100,000 + v in the .xmdf file, where v is
v1, v2…. This output is useful for mapping flood warning times for
different depths of inundation or when VxD or hazard categories are
exceeded. When output as a grid (.asc or .flt) map output format,
the file extension given to this output is _TExc_.
2. The duration of time that a cell is inundated above each of is also
retained. For .xmdf file map output the durations are stored under
the time of 200,000 + v, where v is v1, v2…. This output is useful for
mapping duration of inundation above v1, v2, …. When output as a
grid (.asc or .flt) map output format, the file extension given to this
output is _TDur_.

Note: If this command is specified more than once, the last one will
prevail.

@2774Series Null Value ==

Time Classic A user specified output null value for water level plot outputs if a cell is
[ {cell elevation} | ⟨ null value and HPC dry (see Section 11.3 ). For other PO outputs, such as; flow, flow area,
⟩ ] velocity, a value of 0.0 is output if a cell is dry.

Appendix A TCF Commands - 125 / 147 Page 805 / 1094

 Command Solver Description

@2777Series Output Format ==

Time Classic This command controls the format of time series outputs written to the
[ {csv} | NC ] and HPC results/plot folder. There are two formats available for time series
outputs (Section 11.3 ): comma-separated values (.csv) and NetCDF
(.nc).

One of the advantages of NetCDF is all the timeseries output is in a

single compressed .nc file, rather than multiple uncompressed .csv files.
This can be useful for large 1D models or large amounts of 2d_po data.

@2778Series Output Interval ==

Time Classic The output interval in seconds for time series based output (PO and LP)
[ ⟨ time_in_seconds ⟩ ] and HPC (see Section 11.3.2 ).

Either Output Interval (s) or Time Series Output Interval must be

specified otherwise an ERROR 0046 message is output. The default
values for these intervals is the computational timestep, and by not
specifying values can cause excessive amounts of memory to be
allocated, sometimes causing undesirable results!

Appendix A TCF Commands - 126 / 147 Page 806 / 1094

 Command Solver Description

@2781
Timestep == Classic Specifies the computation timestep of the simulation in seconds. Value
[ {1.0} | ⟨ timestep_in_seconds ⟩ and HPC must be greater than zero. Timesteps that divide equally into one minute
] or one hour are recommended. For example, 0.5, 1, 2, 3, 5, 6, 7.5, 10,
12, 15, 20, 30, 45, 60, etc. seconds.

Different timesteps can be specified for different 1D and 2D domains. If

the command is specified outside a Start 2D Domain / End 2D Domain
block, the timestep will apply to any 2D domain that is not given a
timestep. If it is specified within a Start 2D Domain / End 2D Domain
block it only applies to that 2D domain.

For TUFLOW Classic simulations, the specified value sets the fixed
timestep for the simulation.

For TUFLOW HPC simulations, the specified value sets the initial
timestep for the simulation. All subsequent timesteps are automatically
calculated using an adaptive timestep approach based on control
number criterion.

Refer to Section 3.5 for further information.

@2784
Timestep Initial == HPC Only The standard Timestep command is only used by the HPC solver for
[ ⟨ initial timestep_in_seconds ⟩ ] the first timestep if using adaptive timestepping mode, see Section 3.5.4
. For consistency with typical Classic timesteps, this timestep is divided
by 10 to provide a timestep commensurate with the explicit solution
scheme used by HPC. Therefore, the general advice if using the
Timestep command is to specify the same timestep as would typically
be used when running the Classic solver. This is usually one fifth to half
of the 2D cell size in metres.

As of the 2017-09-AC Build the Timestep Initial command can be used

to set the HPC initial timestep directly (i.e. the timestep is not divided by
10).

Appendix A TCF Commands - 127 / 147 Page 807 / 1094

 Command Solver Description

@2787
Timestep Maximum == HPC Only Sets a maximum timestep for the simulation, see Section 3.5.4 .
[ {Auto} | ⟨ max timestep in Particularly useful when running a model with significant periods in
seconds ⟩ ] which all cells were dry, as the timestep can increase to the map output
interval leading to stability issues when the model first wets after a dry
period (as the timestep has to reduce rapidly).

If not specified, or set to “Auto”, the maximum timestep is based on the

shallow water wave celerity where the wave speed is calculated based
on c=√gh where the cell wet/dry depth is used as a water depth (h). The
max timestep is calculate as max⁡dt=dx/√gh, so for a 5m cell size with a
2mm wet/dry depth the maximum timestep is 35.7 seconds.

For models with infiltration and direct rainfall with a similar magnitude, it
may be desirable to reduce the maximum timestep to avoid repeat
timesteps.

@2790
Timestep Maximum Increase (%) == Classic Legacy command:
[ {0.5} | ⟨ value_as_a_% ⟩ ] Only
This command controls the maximum rate at which an adaptive
timestep, using the command Maximum Courant Number , can
increase. There is no limit to how quickly the timestep can decrease.

@2793
Timestep Minimum == HPC Only The minimum permissible target timestep allowed by the HPC solver
[ {AUTO } | ⟨ minimun timestep (see Section 3.5.4 ). By default this is set to the minimum of 0.1
(seconds) ⟩ ] seconds or the cell size divided by 200 m/s. In most cases, where there
is no erroneous data or poor model setup, the target timestep will always
be well above the default minimum timestep. The timestep Minimum
value can be manually specified if desired.

Appendix A TCF Commands - 128 / 147 Page 808 / 1094

 Command Solver Description

@2796
Timestep Repeats == HPC Only This command allows the user flexibility to change the allowable number
[ {10 } | ⟨ n_allowed_repeats ⟩ ] of TUFLOW HPC repeated timesteps prior to an instability being
triggered (see Section 3.5.4 ). One situation where this might be useful
is if a 2D only model remains totally dry for some time the timestep can
become very large, and then needs to be rapidly reduced once inflows
commence.

@2799
TIN Output Format == Classic This command will change the format written when the WRITE TIN
[ {2DM} | SMS TIN ] and HPC command is used with z-shape or write TIN commands.

Options:

2DM - Writes the TIN using SMS 2DM mesh format which can be
read by SMS or QGIS.
SMS TIN - Writes the TIN using the SMS TIN format that can be
read by SMS.

@2800
TIN Triangulation Approach == Classic This command sets the triangulation approach when creating TINs from
[ {Method A} | Method B ] and HPC the Create TIN Zpts , Read GIS Z Shape , or any of the related
commands that generate a TIN. Method B was introduced as beta
functionality for the 2025 release and has some benefits over Method A,
as described in Section 7.3.5.4 .

@2801
TSF Update Interval == Classic Sets the interval in seconds to update the .tsf file (Section 14.5.2 )
[ {0} | ⟨ interval_in_sec ⟩ ] Only while a simulation is running. If set to 0 or less (the default) the .tsf file is
only updated at the start and the end of the hydrodynamic calculations.

@2804
Tutorial Model == Classic When set to ON, allows simulation of the Tutorial Models without the
[ ON | {OFF} ] and HPC need for a TUFLOW license. For further information refer to Section
2.1.1 and the Tutorial Introduction TUFLOW Wiki page.

Appendix A TCF Commands - 129 / 147 Page 809 / 1094

 Command Solver Description

@2805
UK Hazard Debris Factor == Classic Sets the debris factor (DF) value for calculating the flood hazard output
[ ⟨ DF ⟩ | {1} ] and HPC for options ZUK0 and ZUK1 (see Table 11.5 ) for UK Hazard Formula
== D*(V+0.5)+DF. If a UK Hazard Land Use is specified, DF is
determined from the debris factor land use table (see UK Hazard Land
Use ).

The default value is 1.0.

@2808
UK Hazard Formula == Classic Sets the formula to be used for calculating the flood hazard output for
[ [ D(V+1.5) | {D(V+0.5)+DF} ] and HPC options ZUK0 and ZUK1 (see Table 11.5 ), where D is depth, V velocity
and DF Debris Factor (see UK Hazard Debris Factor ). If a UK Hazard
Land Use is set, the D(V+0.5)+DF option is used irrespective of this
command.

ZUK0 produces a .xmdf file containing the actual value from applying the
UK Hazard Formula, while ZUK1 outputs a .xmdf file containing an
integer as per:

0 = No Hazard (H ≤ 0)
1 = Low Hazard (H ≤ 0.75)
2 = Moderate Hazard (H ≤ 1.25)
3 = Significant Hazard (H ≤ 2.5)
4 = Extreme Hazard (H ≥ 2.5)

Formulae based on the DEFRA (2006a ).

Appendix A TCF Commands - 130 / 147 Page 810 / 1094

 Command Solver Description

@2814
UK Hazard Land Use == Classic Sets the land use category for varying debris factors with depth and
[ PASTURE | WOODLAND | URBAN | and HPC velocity as specified in DEFRA R&D Outputs: Flood Risks to People
{CONSERVATIVE} | NOT SET ] Phase Two Draft FD2321/ TR2, Table 3.1 as shown below. Use NOT
SET to ignore the land use setting and allow use of UK Hazard Debris
Factor and UK Hazard Formula commands. See Table 11.5 .

If the UK Hazard Land Use is not specified, and the default UK Hazard
Formula is used, the debris factors for the CONSERVATIVE land use
are assumed.

In the table below, the V ⟩ 2m/s criteria in the last row is applied at all
depths greater than 0.1m. Occasionally, as a 2D cell wets, a high
velocity may occur, hence the 0.1m cut-off for applying the V ⟩ 2m/s
criteria.

Guidance on debris factors (DF) for different flood depths,

velocities and dominant land uses

@2817
Depths Pasture/Arable Woodland Urban Conservative

0 to
0 0 0 0.5
0.25 m

0.25 to
0 0.5 1 1
0.75 m

d⟩ 0.75
m
0.5 1 1 1
and/or
v⟩ 2

Ref: DEFRA (2006b ) Table 3.1.

Appendix A TCF Commands - 131 / 147 Page 811 / 1094

 Command Solver Description

@2820 ==
Units Classic By default, TUFLOW uses metric units. Full support for US Customary
[ {METRIC} | ENGLISH | IMPERIAL and HPC Units (English or Imperial – they are identical) is available by setting
| US Customary ] Units == US Customary, Units == English or Units ==
Imperial. The default settings for all inputs are the same as for metric,
but converted to their US Customary units’ equivalent. Where the
manual refers to a default value in metric, TUFLOW will use the
equivalent value in US Customary Units. The input and output units are
as follows:

Length: feet
Area: square feet
Rainfall, Initial Loss and Continuing Loss(/h): inches
Catchment Area: square miles
Constant eddy viscosity value: ft2/s
For determination of hazard categories (Z0 and ZUK0) the values
are based on using feet and seconds.

@2821 HX and SX Connections ==

Unused Classic If set to “ERROR” (the default), any unconnected or redundant CN
[ {ERROR} | WARNING ] and HPC objects in 2d_bc layers are treated as an ERROR. This error is typically
due to a CN object not being snapped to a HX or SX object in the same
2d_bc layer, or the use of two CN objects at either end of a SX line (only
one CN object is required to connect a SX line, thereby making the other
one redundant). See Section 8.5 . Setting to “WARNING” will issue a
WARNING message but allow TUFLOW to continue to run. It is not
recommended that the WARNING option be used other than for
backward compatibility.

@2822
Use Forward Slash == Classic If set to ON, forward slash (/), rather than backslash (\, is used in the text
[ ON | {OFF} ] and HPC output files contain file paths (e.g. .tlf, .qgis, .tpc, .wor). For LINUX
systems forward slash must be used, while for Windows either can be
used. See Section 4.2.2 .

Appendix A TCF Commands - 132 / 147 Page 812 / 1094

 Command Solver Description

@2823
Verbose == Classic Controls the amount of information displayed on the DOS console
[ ON | OFF | {LOW} | HIGH ] and HPC window and written to the .tlf. The options are:

OFF: lowest level volume of content.

LOW: a medium level of reporting (the default).
ON: highest level volume of content.
HIGH: controls the amount of information displayed on the DOS
console window. It is the highest level of reporting, in addition DOS
consult window test associated with the ON option, all input
commands will also be echoed. They will be prefixed with “<<”.
When HIGH is used the .tlf write verbose setting is LOW.

@2824
VG Z Adjustment == Classic When using the VG boundary (Section 8.5 ).
[ {MAX ZC} | ZC | ZH ] Only Options are:

MAX ZC (the default setting): This forces the adjusted ZU/ZV and
ZH points to be set to the maximum ZC value rather than an
interpolated ZC value. This option provides significant
enhancements in some situations to the stability of the flow over the
breach.
The ZC option adjusts ZU/ZV and ZH points to be the average of the
neighbouring ZC elevations.
The ZH option provides backward compatibility for models using the
original VG adjustment of Zpts based on changing the ZH values.

@2825
Viscosity Approach == HPC Only Sets the viscosity approach, from the 2020 release onwards “Method B”
[ Method A | {Method B} ] is the default (which is based on the approach developed for TUFLOW
Classic). For backward compatibility, the previous approach “Method A”
can be used.

Appendix A TCF Commands - 133 / 147 Page 813 / 1094

 Command Solver Description

@2826
Viscosity Coefficient == Classic Sets the viscosity coefficient(s) for the chosen Viscosity Formulation
[ ⟨ value1, value2, … ⟩ ] and HPC (see Sections 7.2.4 , 7.4.2 and 7.5.1 ).
Options are:

“CONSTANT”: reads one value for the constant viscosity. The

default value is 0.05 m2/s for Metric Units and 0.5382 ft2/s for US
Customary Units.
“SMAGORINSKY”: reads two values, the first being the
Smagorinsky coefficient, and the second (optional) the constant
eddy viscosity component. The default values are 0.5 and 0.05 m2/s
respectively for Metric units and 0.5 and 0.5382 ft2/s for US
customary units (note that the Smagorinsky coefficient is
dimensionless).
“WU”: reads up to three values, the first being the Wu3D coefficient,
the second being the Wu2D coefficient, and the third (optional)
being the Manning’s upper limit for the 3D component of the
calculation. The default values are 7.0, 0.0, and 0.1 respectively
regardless of units.
“NON-NEWTONIAN”: reads 5 values (refer Section 7.4.6 ). These
are k, n, μlow , μhigh , and τ0 . There are no default values, the
coefficients must be specified if the non-Newtonian viscosity
formulation is selected. Note these values must be specified in the
system of units selected.

Appendix A TCF Commands - 134 / 147 Page 814 / 1094

 Command Solver Description

@2832
Viscosity Formulation == Classic Sets the viscosity formulation (see Sections 7.2.4 , 7.4.2 and 7.5.1 ).
[ CONSTANT | SMAGORINSKY | WU and HPC Options are:
| NONNEWTONIAN ]
“CONSTANT”: the viscosity coefficient remains constant
“SMAGORINSKY”: applies a hybrid approach that includes
elements of both the Constant and Smagorinsky approaches
“WU”: applies the WU model with 3D and 2D coefficients
“NON-NEWTONIAN”: selects the non-Newtonian calculation

TUFLOW Classic only supports CONSTANT and SMAGORINSKY, with

the default being SMAGORINSKY

TUFLOW HPC supports all, with the default being WU.

@2833 Level Checks ==

Water Classic The default ON option carries out checks on water levels to detect any
[ {ON} | OFF ] Only significant instabilities. Instabilities are triggered when a water level
exceeds the Instability Water Level or falls below the negative of the
Instability Water Level . Switching this option off reduces the
computation time very slightly. See Section 16.3.2 .

Appendix A TCF Commands - 135 / 147 Page 815 / 1094

 Command Solver Description

@2834
Wetting and Drying == Classic Legacy command:
[ {ON METHOD B} | ON | ON NO Only
Controls the wetting and drying method.
SIDE CHECKS | OFF ]
The ON METHOD B approach (default) introduced an enhanced wetting
algorithm in the 2012-05 release that provides significant improvement
to inflows on steep areas (e.g. direct rainfall models), whilst maintaining
low mass error, greater stability and often larger timesteps. Use of this
approach does not require use of the Shallow Depth Stability Factor
that was previously automatically invoked for direct rainfall models. This
method makes an estimate of the likely velocity that will occur when a
cell side first wets and feeds this information into the solution matrices.
Previously, the velocity used was that from the previous timestep which
was zero as the cell side was dry. The zero velocity essentially created a
frictionless slope and would cause a surge of water, albeit very shallow,
when the cell side first wets. This was not usually a major issue,
however, with direct rainfall models all cell sides can become wet in one
timestep and if the terrain is steep a significant surge and unacceptable
mass errors would occur. This method largely overcomes this effect.

The (pre 2012-05 default) ON approach dries cells once the cell water
depth falls below the cell wet/dry depth (see Cell Wet/Dry Depth and
Cell Side Wet/Dry Depth ). A cell becomes wet once an adjoining cell’s
water level is higher than the cell’s wet/dry depth. This method only
considers adjoining wet cells that share a common cell side that is wet.

The ON NO SIDE CHECKS option is as described above, except that

drying at the cell sides is not considered. All four adjoining cells are
always considered.

The OFF option disables wetting and drying. This should only be used
for models that have no cells likely to wet and/or dry.

Appendix A TCF Commands - 136 / 147 Page 816 / 1094

 Command Solver Description

@2835FIRM Code Search Order ==

WIBU Classic Used to control the search order in the TUFLOW_licence_settings.lcf
[ ⟨ list of firm codes ⟩ ] and HPC (not the TCF) the command specified is “WIBU Firm Code Search
Order == ”. See Section 13.5.1.1 .

With numerous licencing options available, setting the preferred licence

type can speed simulation start-up. The licence search order can be set
via a licence control file “TUFLOW_licence_settings.lcf”, this replaces
the TUFLOW_Dongle_Settings.dcf. Note that this file can occur in
several locations. When looking for a licence setting file TUFLOW
searches in the following locations:

A “TUFLOW_licence_settings.lcf” in the same location as the

TUFLOW > executable. This is given the highest priority.
C:_WBM_Licence_Settings.lcf
C:_WBM_Dongle_Settings.dcf

The firm codes used below are unique identifiers used by Wibu.

Vendor / Licence Description Wibu Firm Code

BMT physical dongle 101139

BMT software licence 6000224

Aquaveo physical licence 101394

Jacobs physical licence 101987

Jacobs software licence 5000219

If multiple firmcodes are to be used these are entered with a space

between the values. For example, in the below, this sets the search
order to BMT software lock licences, then BMT hardware lock (dongle)
licences.

WIBU Firm Code Search Order == 6000224 101139

Appendix A TCF Commands - 137 / 147 Page 817 / 1094

 Command Solver Description

Any firm codes not listed are not used. For example to search for only an
Aquaveo hardware lock licence, the .lcf command would be:

WIBU Firm Code Search Order == 101394

@2838
Wind/Wave Shallow Depths == Classic Sets the depth of water when the wind and/or wave stress (Section 8.8
[ {0.2, 1.0} | ⟨ y1, y2 ⟩ ] Only ) are reduced to zero. This command is necessary to avoid a divide by
zero error in the numerical calculation, and model instabilities when high
wind/wave stresses are applied to very shallow depths. Below y1, the
stress is set to zero, above y2 the full stress is applied, and between y1
and y2 the stress is interpolated. y1 and y2 are in metres (or feet if using
Units ==US Customary).

Appendix A TCF Commands - 138 / 147 Page 818 / 1094

 Command Solver Description

@2841 Check Files [ {ALL} | NONE |

Write Classic Creates GIS check files in the format specified by the GIS Format
INCLUDE | EXCLUDE ] == and HPC command and text .csv files for quality control checking of model input
[ ⟨ prefix_list_or_file_prefix ⟩ ] data. Refer to Section 14.7 for further details on the check files
produced. The options available for this command can be used to control
which check layers are written.

The EXCLUDE or INCLUDE options allow for a space delimited list of

file prefixes to be specified to exclude or include GIS layers from being
written. Prefixes must be the same as those used by TUFLOW. For
example, “zpt” would apply to the zpt_check layer. To exclude/include
more than one layer ensure there are spaces between the prefixes. If
EXCLUDE or INCLUDE occurs more than once, the latter occurrence
prevails.

Examples:

Write Check Files EXCLUDE == zpt uvpt ! excludes

writing of the zpt_check and uvpt_check layer

Write Check Files INCLUDE == DEM_Z ! will only write

the Grid of the model’s ground elevations to the same
location as the .tcf file.

The ALL option requires no prefix list. All check files will be written to the
same folder as the .tcf file. Specification of the ALL option will nullify any
prior occurrence of an EXCLUDE or INCLUDE list; this is useful if you
wish to write no or all check files for one particular run – simply add
Write Check Files ALL to the end of the .tcf file.

Alternatively, the Write Check Files command may be used without

options to add a prefix to all check files or specify a location in which to
write the files. If <file_prefix> is omitted or ends in a “\ to indicate a

Appendix A TCF Commands - 139 / 147 Page 819 / 1094

 Command Solver Description

folder, the .tcf filename (without the .tcf extension) is prefixed to each
check file. <prefix_list> can include a folder path that is normally set to
the check folder. See the examples below for this subtle difference.

Examples:

Write Check Files ALL ! writes all check files with no

prefix to the same location as the .tcf file.

Write Check Files == C:\tuflow\check\2d ! writes all

check files to the folder “C:\tuflow\check” and
prefixes them with “2d”

Write Check Files == C:\tuflow\check ! writes all check

files to the folder “C:\tuflow\check” and prefixes
with the .tcf filename

Write Check Files == C:\tuflow\check ! writes all check

files to the folder “C:\tuflow” and prefixes with
“check”

The NONE option is similar to the ALL option and requires no prefix list.
No check files will be written and specification of the NO option will
nullify any prior occurrence of an EXCLUDE or INCLUDE list.

Examples:

Write Check Files NONE ! will suppress the writing of

all check files

Specifying the Write Check Files command in the .tcf file will now
automatically also write the 1D check files. There is no need to specify
Write Check Files in the .ecf file unless a different folder path for the
files is desired.

Appendix A TCF Commands - 140 / 147 Page 820 / 1094

 Command Solver Description

This command can be used within an Output Zone definition block to

change list of check files to exclude or include for the Output Zone.
However, the output path of the check files cannot be specified for
Output Zones.

@2844 Empty GIS Files ==

Write Classic Creates empty (template) 1D and 2D GIS files in the format specified by
[ {} | ⟨ folder ⟩ | ⟨ and HPC the GIS Format command. If no GIS Format has been set, the empty
file_format ⟩ ] files will be in MIF format by default. Each empty layer as described in
Table 2.5 and Table 2.6 is produced with the required attribute
definitions pre-defined, but containing no geographic objects. Provided
the GPKG Projection , SHP Projection or MI Projection command has
been previously specified, each layer has the correct GIS projection.

The layers are prefixed using the prefixes defined in Table 2.5 and
Table 2.6 , and are given a suffix of “_empty”.

If <folder> is specified, the GIS files are located in the folder. If the folder
does not already exist, it will be created.

It is possible to add a second argument after defining the folder, which

can also be used to set the required format of the empty files, as shown
in the second example below.

Examples:

Write Empty GIS Files == ..\model\gis\empty

Write Empty GIS Files == ..\model\gis\empty | SHP

After writing the files, TUFLOW stops executing.

Appendix A TCF Commands - 141 / 147 Page 821 / 1094

 Command Solver Description

@2849 PO Online ==
Write Classic If set to ON writes the 1D and 2D time-series data files as the simulation
[ ON | {OFF} ] and HPC progresses (see Section 11.3 ). The _TS GIS file is only written if there
is a 1D domain in the model. The files are closed off so that they can be
opened in Excel or other software for viewing during a simulation,
however, opening the files in some software (e.g. Excel) may cause
TUFLOW to pause at the next output time until the files are closed. If set
to OFF the files are not written until the simulation finishes.

@2850 Restart File at Time ==

Write Classic Sets when to write the restart file (Section 8.9.3 ) in hours. The restart
[ ⟨ time_in_hours ⟩ ] and HPC files are written to the results folder.

The restart file is given the extension .trf. An .erf file is also written for
the 1D components if there is 1D/2D dynamic linking. The .trf file is a
binary file and not readable by a text editor. The .erf file is a text file and
is readable by a text editor. The first line of the .erf file shows the time
when the restart files were written. The time(s) when the restart files are
written are displayed in the log file(s).

If the time is before the simulation start, the start time is used. Only the
last occurrence of this command is used.

Appendix A TCF Commands - 142 / 147 Page 822 / 1094

 Command Solver Description

@2853 Restart File Interval ==

Write Classic Sets the interval in hours between writing the restart file (Section 8.9.3
[ {0} | ⟨ interval_in_hours ⟩ ] and HPC ). The restart file is overwritten every <interval_in_hours> after the first
restart file write. This is useful if a simulation is going unstable. A restart
file is written prior to the instability, and is used to restart the simulation
after modification of the topography to control the instability – thereby
saving time in reaching the time of instability.

If set to zero, the default, or is negative, the restart file is written only
once at the write restart file time. Only the last occurrence of this
command is used.

The restart files are written in a result folder called “trf”.

Refer also to the command Write Restart Filename .

@2856 Restart File Version ==

Write Classic Uses a more detailed dump of the 2D domains that will result in a more
[ 2 ] and HPC precise restart (see Section 8.9.3 ).

@2857 Restart Filename ==

Write Classic Command to control whether restart files (Section 8.9.3 ) are
[ {INCLUDE TIME} | OVERWRITE ] and HPC overwritten or are time-stamped.

If INCLUDE TIME (the default) is specified, .trf and .erf filenames are
time-stamped and written for each restart output time.

OVERWRITE is the case for all prior versions of TUFLOW where the .trf
and .erf files are overwritten each time restart files are written. If
Defaults == PRE 2013 is set the default setting is OVERWRITE.

To output restart files at regular intervals use the command Write Restart
File Interval .

Appendix A TCF Commands - 143 / 147 Page 823 / 1094

 Command Solver Description

@2858 X1D Check Files ==

Write Classic If set to ON, writes out check_x1D_H_to_2D.csv and
[ ON | {OFF} ] and HPC check_2D_Q_to_x1D.csv files that contain the water levels sent to the
2D and the flows sent by the 2D to/from an external 1D scheme such as
Flood Modeller or XP-SWMM. See Section 10.5.1 .

Note that Write Check Files must be also be specified (and not set to
NONE).

@2859
XF Files == Classic Sets the global default for whether or not to automatically generate XF
[ {ON} | OFF ] and HPC files. See Section 4.6 .

@2860
XF Files Boundaries == Classic XF files (Section 4.6 ) are used to speed up the reading of boundary
[ {ON} | OFF ] and HPC data in both .csv and .ts1 file formats. This works for data referenced
from the “BC Database ” and “Pit Inlet Database ”. As with other .xf
files created by TUFLOW (for example using “Read Grid Zpts ”), the
save date of the .xf file is compared to the save date of the original data
file (.csv or .ts1). If the original dataset has been modified since the .xf
file was created the original dataset is re-read and the .xf file
regenerated. XF files can be turned off globally with the .tcf command:
XF Files , or just for the new boundary/pit database files using XF
Files Boundaries == OFF.

@2861
XF Files Include in Filename == Classic Appends <text> to the end of XF filenames (see Section 4.6 ). This
[ ⟨ text ⟩ ] and HPC command prevents the reprocessing of the DEM each time a different
model utilising the same DEM is run.

@2864
XF Files Merge TIN Elevations == Classic Introduced in the 2023-03-AF build as an enhancement to the XF file
[ {Reprocess} | Use XF ] and HPC feature by reusing the TIN structure in the XF files, but updating the TIN
vertex elevations from the new simulations. ‘Reprocess’ is the default
approach for the 2023-03-AF build and onwards that reprocesses the
TIN vertex elevations for each simulation, while ‘Use XF’ is the original
method, used for builds prior to 2023-03-AF, that applies the TIN vertex
elevations stored in XF files.

Appendix A TCF Commands - 144 / 147 Page 824 / 1094

 Command Solver Description

@2865Output Compression ==
XMDF Classic Sets the file compression level of XMDF map output files (Section
[ {ON} | OFF | ⟨ level ⟩ ] and HPC 11.2.2.1 ). If set to ON, the default, compression level 1 is applied. A
maximum compression level of 9 is allowed. The greater the
compression the smaller the file sizes, but the slower the access speed
when writing and reading the file. Testing has indicated that a
compression level of 1 reduces file sizes by 70 to 80% with little change
in access speeds.

@2868Negative Depths ==
Zero Classic Legacy command:
[ {ON} | OFF ] Only
This is a legacy command provided for backward compatibility. Setting to
ON zeroes depths at cell corners for map output if negative. The
negative depth could arise in old builds of TUFLOW when interpolating
the water level at the cell corners from the surrounding cell centres, due
to the ZH Zpt being higher than the interpolated water level.

Setting to OFF disables this command and should only be effective if the
original cell interpolation method (Map Output Corner
Interpolation == METHOD A) applies. Using the OFF option is not
recommended.

@2869Rainfall Check ==
Zero Classic Introduced for the 2016-03 release to set the level for Message 2460
[ {ERROR} | WARNING ] and HPC that reports whether the f1 and/or f2 attribute is set to zero for a 2d_rf
layer (see Section 8.5.3.4 ). For the 2016-03 release the message is
treated as an ERROR and the simulation will terminate, unless
Defaults == PRE 2016 is set or this command is set to WARNING.

Prior to the 2016-03 release this message was only issued as a

WARNING. For further information see the Message 2460 Wiki Page.

Appendix A TCF Commands - 145 / 147 Page 825 / 1094

 Command Solver Description

@2870
ZP Hazard Cutoff Depth == Classic This command can be used when specifying the ZPA, ZPC, and ZPI
[ {0.01} | ⟨ value ⟩ | ⟨ Only hazard map outputs, based on the People Hazard categories within the
value_ZPA ⟩ ⟨ value ⟩ _ZPC ⟨ value ⟩ Australian Rainfall and Runoff (ARR) Project 10 Stage One report (Cox
_ZPI ] et al., 2010 ). Refer to Table 11.5 for more information.

If one value is specified, the cutoff depth to define when the Safe
category applies is the same for ZPA, ZPC and ZPI. If three values are
specified, these are the cutoff depths for ZPA, ZPC and ZPI respectively.
The default is 0.01m (i.e. if the depth is below 0.01m (1cm), the hazard
category is Safe for ZPA, ZPC and ZPI).

@2879
Zpt Range Check == Classic Legacy command:
[ {-9998, 99998} | ⟨ zmin ⟩ ,⟨ zmax and HPC
Reports an ERROR 2444 (WARNING 2444 if Defaults == Pre
⟩ ]
2012) if any final Zpt is less than zmin or greater than zmax. The
defaults for zmin and zmax are -9998 and 99998 (-9998 is used for the
minimum value as some 3D surface software use -9999 as the null
value). Useful for checking there are no Zpts with inappropriate values.
This check is only carried out once on the final Zpt values just before the
simulation starts, and after writing the _zpt_check layer. In the unlikely
event of an invalid or NaN Zpt occurring an ERROR 2445 (or WARNING
2445) is issued.

References

@2889
@2888
Cox, R., Shard, T., & Blacka, M. (2010). Australian Rainfall and Runoff Revision Project 10: Appropriate Safety Criteria for People. Austalian
Institute of Engineers. https://arr.ga.gov.au/__data/assets/pdf_file/0006/40578/ARR_Project_10_Stage1_report_Final.pdf

@2890
DEFRA. (2006a). DEFRA r&d Outputs: Flood Risks to People Phase Two Draft FD2321/TR1 and TR2. DEFRA.
https://assets.publishing.service.gov.uk/media/602bbc3de90e07055f646148/Flood_risks_to_people_-

Appendix A TCF Commands - 146 / 147 Page 826 / 1094

 _Phase_2_Guidance_Document_Technical_report.pdf

@2891
DEFRA. (2006b). Flood Risks to People Phase 2 FD2321/TR1 the Flood Risks to People Methodology. DEFRA.
https://assets.publishing.service.gov.uk/media/602bbc768fa8f50383c41f80/Flood_risks_to_people_-
_Phase_2_The_flood_risks_to_people_methodology_technical_report.pdf

@2892 G. (1984). On the Construction of Computational Methods for Shallow Water Flow Problems. Rijkswaterstaat Communications.
Stelling,

@2893 W. (1991). Dynamically Linked Two Dimensional / One-Dimensional Hydrodynamic Modelling Program for Rivers, Estuaries and
Syme,
Coastal Waters (W. Syme, Ed.) [M.Eng.Sc(100% Research) Thesis]. Dept of Civil Engineering. https://tuflow.com/media/4982/1991-tuflow-
dynamically-linked-2d-and-1d-hydrodynamic-modelling-syme-thesis.pdf

@2894W. (2001b). TUFLOW – Two & One-Dimensional Unsteady FLOW Software for Rivers, Estuaries and Coastal Waters. The Institution of
Syme,
Engineers, Australia 2D Seminar. https://tuflow.com/media/4985/2001-tuflow-two-and-one-dimensional-unsteady-flow-software-for-rivers-
estuaries-and-coastal-waters-syme.pdf

Appendix A TCF Commands - 147 / 147 Page 827 / 1094

 @2897

@2898
Appendix B ECF Commands

The TUFLOW ESTRY Control File (.ecf) includes commands and data inputs to build the 1D ESTRY domain, it is read into the .tcf using the
ESTRY Control File command. For more information on the .ecf, see Section 4.2.5 . Building the 1D domain is discussed in Chapter 5 .
The available ECF commands are listed below and are detailed in Table B.1 .

AD Approach Froude Depth Adjustment Minimum NA Pit

Apply All Inverts Head Rate Creep Factor Momentum Equation
Arch Bridge Minimum Blockage (%) Head Rate Limit Order Output
BC Database Head Rate Limit Minimum Output Data Types
BC Event Name Interpolate Cross-Sections Output Folder
BC Event Text Interpolate Culvert Inverts Output Interval
Bridge Flow M Channel Approach Output Times Same as 2D
Bridge Zero Coefficients M11 Network Overlapping SX HX Boundary
Conveyance Calculation Manhole Approach Pit Channel Offset
Create Nodes Manhole Default C Exit Coefficient Pit Default 2D Connection
CSV Format Manhole Default Loss Approach Pit Default Extrapolate Q Curve
CSV Maximum Number Columns Manhole Default R Exit Coefficient Pit Default Road Crossfall
CSV Time Manhole Default Side Clearance Pit Inlet Database
Culvert Critical H/D Manhole Default Type Pit Search Distance
Culvert Flow Manhole K Maximum Bend/Drop Read File
Culvert Zero Coefficients Manhole Minimum Dimension Read GIS BC
Depth Discharge Database Manholes at All Culvert Junctions Read GIS IWL
Depth Limit Factor Maximum Operational Controls Read GIS Manhole
Flow Area Minimum Channel Conveyance Length Read GIS Network
Flow Calculation Minimum Channel Storage Length Read GIS Node
Froude Check Minimum NA Read GIS Pits

Appendix B ECF Commands - 1 / 37 Page 828 / 1094

 Read GIS Table Links Structure Flow Levels Vel Rate Limit Minimum
Read GIS WLL Structure Losses Weir Approach
Read GIS WLL Points Structure Losses Approach Weir Flow
Read Operating Controls File Structure Losses SX WLL Approach
S Channel Approach Structure Routines WLL Automatic
Set IWL Taper Closed NA Table WLL No Weirs
Set Variable ⟨name⟩ Timestep WLL Vertical Offset
Spatial Database Trim XZ Profiles WLLp Interpolate Bed
Start Output Vel Rate Creep Factor Write Check Files
Storage Above Structure Obvert Vel Rate Limit XS Database

Appendix B ECF Commands - 2 / 37 Page 829 / 1094

 @2901
@2905 Table B.1: TUFLOW Classic/HPC ECF Commands

Command Solver Description

@2904
@2906
AD Approach == Classic Sets the modelling approach for the Advection Dispersion through 1D
[ METHOD A | {METHOD B} ] and channels.
HPC
Method A is the original approach that assumes the concentration of
a constituent exiting an SX connection is the same as that at the
entrance SX connection at the same timestep.

Method B is the solves equation of motion for tracer constituents

through 1D channel network.

@2907 All Inverts ==

Apply Classic Legacy command:
[ {ON} | OFF ] and
If set to ON, applies the upstream and downstream inverts specified
HPC
in the 1d_nwk layer to all channels (ie. also for B, Blank and W
channels), except where a value of -99999 is specified. Introduced
for Build 2005-05-AN and made the default in Build 2006-03-AB.
Note: If upgrading a model used prior to Build 2006-03-AB, any
inverts for B, Blank and W channels need to be set to –99999 to
ensure the inverts remain unchanged. Otherwise, the inverts for
these channels are likely to be set to zero, as this is the default value
set by MapInfo for the invert attributes.

@2908Bridge Minimum Blockage (%) ==

Arch Classic
Sets the minimum blockage applied in the arch bridge flow
[ {5} | ⟨ min_pblockage ⟩ ] and
calculation (see Section 5.8.3.2 ). The default value is 5 (%).
HPC

Appendix B ECF Commands - 3 / 37 Page 830 / 1094

 Command Solver Description

@2911
BC Database == Classic Sets the active BC Database file, as described in Section 8.6 . The
[ ⟨ .csv_file ⟩ ] and file is usually created using spreadsheet software such as Microsoft
HPC Excel.

If the BC Database is specified in the TUFLOW .tcf file, it is set as

the active database for both 2D and 1D models. However, the active
database can be changed at any stage in the .tbc and .ecf files by
repeating the command with the new database set as the ⟨ .csv_file ⟩

A BC Database must be specified before any of the other BC

commands are used.

@2916
BC Event Name == Classic Sets the active BC name to be substituted where ⟨ bc_event_text ⟩

[ ⟨ bc_event_name ⟩ ] and (see BC Event Text ) occurs in the BC Database. See Section 8.6.2
HPC for a description of how the BC event commands operate.

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

BC Event Name == H010

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

Appendix B ECF Commands - 4 / 37 Page 831 / 1094

 Command Solver Description

@2921
BC Event Text == Classic Sets the text in the BC Database that is to be substituted by the BC
[ ⟨ bc_event_text ⟩ ] and Event Name command value. See Section 8.6.2 for a description
HPC of how the BC event commands operate.

For 1D/2D models this command only needs to be specified in the

.tcf file. It would only be used in the .ecf file for 1D only models or if
for some reason the ⟨ bc_event_text ⟩ value needs to change prior to
reading the 1D BCs. Also see BC Event Text for the .tcf file if the
model is 1D/2D.

The ⟨ bc_event_text ⟩ value can be changed at any stage by

repeating this command in the .ecf file, although it is strongly
recommended that the ⟨ bc_event_text ⟩ value is standardised
across all models and the command is only specified once.

@2930 Flow ==
Bridge Classic Controls the method for calculating bridge flows.
[ Method A | {Method B} ] and
Method A uses the original ESTRY bridge routine. Method B (the
HPC
default), is based on Method A, but provides improved stability
particularly when the bridge is flowing at shallow depths or is wetting
and drying. Method B also does not force the loss coefficient to be a
minimum of 1.5625 once the bridge obvert is surcharged (Method B
uses the value as specified in the BG table).

Refer to Section 5.8.2.1 for further information.

Appendix B ECF Commands - 5 / 37 Page 832 / 1094

 Command Solver Description

@2931 Zero Coefficients ==

Bridge Classic Changes the default BB bridge (Section 5.8.2.4 ) channel
[ {DEFAULT} | OFF | ⟨ Cd ⟩ , ⟨ DLC ⟩ , ⟨ and coefficients applied to zero (0.0) attribute values in the 1d_nwk
ELC ⟩ , ⟨ XLC ⟩ ] HPC layer(s). This command is not used for B bridge channels.

The four values and their associated 1d_nwk attributes are:

Cd: Bridge deck pressure flow surcharge coefficient specified by

the HConF_or_WC attribute (Default = 0.8).
DLC: Bridge deck energy loss coefficient when fully submerged
and not under pressure flow. Specified by the WConF_or_WEx
attribute (Default = 0.5).
ELC: Unadjusted entrance loss coefficient specified by the
EntryC_or_WSa attribute (Default = 0.5). The entrance loss
coefficient applied is adjusted every timestep according to the
approach velocity, as discussed in Section 5.8.2.4 .
XLC: Unadjusted exit loss coefficient specified by the
ExitC_or_WSb attribute (Default = 1.0). The exit loss coefficient
applied is adjusted every timestep according to the departure
velocity, as discussed in Section 5.8.2.4 .

For example, Bridge Zero Coefficients == 0.75, 0.3,

0.5, 0.8 changes the default value for Cd, DLC, ELC and XLC
used for any zero (0) attribute values in 1d_nwk layer(s).

DEFAULT (which is the default setting) will set any zero values to the
default values mentioned above.

OFF will allow a zero value to be applied to the ELC and XLC loss
coefficients. Cd and DLC cannot be non-zero, therefore, if OFF is
specified these will always have their default value above applied if
the 1d_nwk attribute is zero.

Appendix B ECF Commands - 6 / 37 Page 833 / 1094

 Command Solver Description

@2940
Conveyance Calculation == Classic If set to CHANGE IN RESISTANCE, the parallel channel analysis
[ CHANGE IN RESISTANCE | and splits the cross-section into separate parallel channels based on
{ALL PARALLEL} ] HPC wherever there is a change in resistance (due to different relative
resistance, material type or Manning’s n values).

If set to ALL PARALLEL (the default), a parallel channel is created for

every X (distance across section) value. This approach does not
cause conveyance reducing with height warnings.

Refer to Section 5.7.3 .

@2941 Nodes ==
Create Classic If no node is found snapped to the end of a channel a new node is
[ {ON} | OFF ] and automatically created. The ID of the node is the first ten characters of
HPC the channel ID with a “.1” or “.2” extension. “.1” is used if the node is
at the start of the channel and “.2” if at the end. If more than one
channel is connected to the created node, the channel ID that occurs
first alphanumerically is used.

The automatic creation of nodes can be switched off using the OFF
option.

For further information see Section 5.13.1 .

@2942
CSV Format == Classic If set to HORIZONTAL, writes the 1D .csv output file (Section 15.3 )
[ HORIZONTAL | {VERTICAL} ] and with the head/flow/velocity values for a node/channel in rows. The
HPC default is to write the values in columns.

@2943
CSV Maximum Number Columns == Classic Legacy command:
[ ⟨ max_col ⟩ ] and
This is a legacy command that applies to formats prior to the default
HPC
.csv output for the 2016-03 release.

Used to specify a maximum number of columns for 1D .csv output

files. The default setting is limitless. Refer also to the .tcf command
CSV Maximum Number Columns .

Appendix B ECF Commands - 7 / 37 Page 834 / 1094

 Command Solver Description

@2946
CSV Time == Classic Legacy command:
[ {DAYS} | HOURS | MINUTES | SECONDS ] and
Specifies the time values of 1D .csv outputs. The default is DAYS but
HPC
can be changed to HOURS, MINUTES or SECONDS.

The .tcf command CSV Time can be specified to apply to both 1D

and 2D .csv outputs.

@2947
Culvert Critical H/D == Classic Sets the H/D value to be used for determining whether outlet control
[ {OFF} | ⟨ critical_h/d ⟩ | ⟨ v1 ⟩ | ⟨ and Regimes E and F take preference over the inlet control Regimes B or
v2 ⟩ | ⟨ v3 ⟩ ] HPC L. H is the upstream head above the culvert sill and D is the culvert
height. If H/D exceeds ⟨ critical_h/d ⟩ Regime E or F is used,
otherwise the regime with the lower discharge (along with other tests)
is used.

The default is OFF (i.e. infinitely large H/D). Three options are
additionally available:

v1 = Critical H/D value at culvert inlets connected to at least one

open channel.
v2 = Critical H/D value at culvert inlets connected to a pit
channel (and not connected to any open channels).
v3 = Critical H/D value at culvert inlets at culvert only junctions
(no open channels or pits).
Default values are 99999. (i.e. no critical H/D values applied). If
only one value is specified, this is applied to all three. Specifying
OFF applies 99999 to all three values.

Appendix B ECF Commands - 8 / 37 Page 835 / 1094

 Command Solver Description

@2958
Culvert Flow == Classic Controls the method for calculating culvert flows.
[ {Method E} | Method ⟨ letter⟩ ] and Options include:
HPC
Method A is the original ESTRY culvert routines.
Method B is an adaptation of Method A to include regimes K and
L (see Figure 5.4 ). Method B also offers improved stability,
smoother transitions between flow regimes and corrects very
occasional mass conservation errors under certain flow regimes.
Method C is a slight improvement on Method B for flow Regime
C (see Figure 5.4 ).
Method D includes further improvements on Method C and
corrects a bug for Regime E.
Method E is the current default and incorporates minor
improvements for transitioning between Regimes A and B, and
between inlet and outlet controlled regimes, for circular culverts.
Method G (introduced in the 2023-03-AC release) includes an
enhancement to adverse slope culvert flux calculation. Prior to
2023-03-AC, significant exit loss could be applied at the exit of
an adverse slope culvert if the outlet node is dry or close to dry.
This is caused by the misrepresentation exit flow area and exit
velocity. Method G fixes this.

Methods A, B, C and D are provided for backward compatibility only.

Appendix B ECF Commands - 9 / 37 Page 836 / 1094

 Command Solver Description

@2961
Culvert Zero Coefficients == Classic Sets the default culvert coefficients if they are set to zero (0) in the
[ DEFAULT | {OFF} | v1, v2, v3, v4, and 1d_nwk layer(s). The five affected attribute values are as per the
v5 ] HPC following:

v1 Circular culvert inlet controlled contraction coefficient

(Width_Cont attribute).
v2 Rectangular and irregular culvert height contraction
coefficient (Height_Cont attribute).
v3 Rectangular and irregular culvert width contraction coefficient
(Width_Cont attribute).
v4 Culvert inlet loss coefficient (Entry_Loss attribute).
v5 Culvert outlet loss coefficient (Exit_Loss attribute).

For example, Culvert Zero Coefficients == 1.0, 0.6,

0.9, 0.5, 1.0 sets any zero (0) and NULL coefficient values in
1d_nwk layers to the corresponding value from this command. Any
non-zero and non-NULL values remain unchanged.

DEFAULT sets zero coefficients to the default values of 1.0, 0.6, 0.9,
0.5 and 1.0.

OFF (default) doesn’t apply this feature and if the 1d_nwk attributes
are empty (See Table 5.4 ):

For a circular culvert 1,1,0,0 is used.

For a rectangular culvert 0.6,0.9,0,0 is used.

@2962 Discharge Database ==

Depth Classic Specifies the depth discharge database file that references the
[ ⟨ depth_discharge_dbase.csv ⟩ ] and depth-discharge curves for non-operated Q channels. Mandatory if
HPC the model has any Q channels. Performs the same function as Pit
Inlet Database . The same database file can be used for both Q
channels, Q pits and pump channels.

Appendix B ECF Commands - 10 / 37 Page 837 / 1094

 Command Solver Description

@2965 Limit Factor ==

Depth Classic Sets the depth limit for detecting instabilities. The default is set to 10,
[ {10} | ⟨ value ⟩ ] and therefore the water level must exceed ten times the depth of the CS
HPC or NA table before an instability is triggered. See Section Section
5.13.3 .
Specifying a value greater than one extends the cross-section
hydraulic properties and nodal storages above the highest elevation.
For example, if a value of 2 is specified, this will allow water levels to
reach twice the depth where depth is the difference between the
highest and lowest elevations in the table.

Cross-section hydraulic properties above the highest elevation are

calculated based on the flow width remaining constant at the width of
the highest elevation in the table. If the hydraulic properties are
calculated from a cross-section profile, it uses the effective flow width
as shown in the .eof file (it does not use the storage width) – this
preserves the effect of any variation in relative roughness across the
cross-section. All other hydraulic property sources use the storage
width, and any relative roughness effects are ignored once the water
level exceeds the highest elevation. Also note that the wetted
perimeter remains constant above the highest elevation; ie. it is not
increased on the vertical as the flood level rises. Cross-section
properties of bridge channels are not affected by this command.

Nodal storage properties extend upwards by keeping the surface

area constant above the highest elevation in the table.

Appendix B ECF Commands - 11 / 37 Page 838 / 1094

 Command Solver Description

@2968Area ==
Flow Classic Sets the default method for calculating flow area at a channel cross-
[ {EFFECTIVE} | TOTAL ] and section when ESTRY calculates the hydraulic properties from a
HPC cross-section XZ profile table. The default is EFFECTIVE area, which
means that the flow area is the sum of the areas divided by the
relative resistance factor. TOTAL area ignores the relative resistance
factor when calculating area, but uses it to set the wetted perimeter
and hydraulic radius values. Either method gives the same channel
conveyance. If the relative resistance across the profile is not
specified or constant at a value of one, effective and total area are
the same.

The effective area method produces a velocity that applies to the

main channel (where the relative resistance is set to one). The total
area approach produces a velocity depth and width averaged, and
typically underestimates the main channel velocity. The
recommended approach is to use effective area.

See Section 5.7.4 for a more detailed discussion.

@2969Calculation ==
Flow Classic Method A is the original ESTRY channel flow routine.
[ Method A | {Method B} ] and
Method B corrects an anomaly that would sometimes incorrectly
HPC
output 1D flow values where the channel flow regimes are oscillating
every half timestep (for example, between super and sub-critical flow
regimes). Where the channel is switching flow regimes between
timesteps (nearly always the case), the correct flow is calculated.
This fix also affects the flow in/out of 2D SX connections if the
connected 1D channel is oscillating every half timestep. The fix does
not change 1D water level and velocity results, unless they are
influenced by changes due to any effects on SX flows.

Use Method A only for backward compatibility.

Appendix B ECF Commands - 12 / 37 Page 839 / 1094

 Command Solver Description

@2970 Check ==
Froude Classic Sets the minimum Froude Number that upstream controlled friction
[ {1} | ⟨ froude_no ⟩ ] and flow may occur in “S” channels. Improved stability may occur in
HPC steeply flowing areas if ⟨ froude_no ⟩ is less than 1. ⟨ froude_no ⟩

cannot be below zero and would normally not exceed 1.

@2977 Depth Adjustment ==

Froude Classic Switches ON or OFF an additional upstream controlled friction flow
[ {ON} | OFF ] and check for S channels (a similar check is used for 2D domains – see
HPC Section 7.5.2 ).

Only set to OFF for backward compatibility.

@2978Rate Creep Factor ==

Head Classic
[ ⟨ value ⟩ | {1.2} ] and Specifies rate at which the Head Rate Limit value changes.
HPC

@2981Rate Limit ==
Head Classic Specifies the head rate limit applied to nodes. This feature can be
[ ON | {OFF} | ⟨ hrl ⟩ ] and used to stabilise problematic 1D nodes, but should be used with
HPC caution and mass balance checks must be made to ensure there is
no significant mass loss or gain. It is particularly useful where a node
“bounces” temporarily and is prevented from becoming unstable. The
maximum amount the water level can change in half a timestep is the
⟨ hrl ⟩ value after any adjustment by the Head Rate Creep Factor .
The ⟨ hrl ⟩ is adjusted up and down depending on the stability of the
node in a similar approach used for Vel Rate Limit . If the ON option
is used, the ⟨ hrl ⟩ value is set to 0.1.

@2990Rate Limit Minimum ==

Head Classic
Specifies the minimum head rate limit that can occur. See Head Rate
[ ⟨ hrlmin ⟩ | {0.001} ] and
Limit .
HPC

Appendix B ECF Commands - 13 / 37 Page 840 / 1094

 Command Solver Description

@2993
Interpolate Cross-Sections == Classic If set to ON (the default), any channels that don’t have a cross-
[ {ON} | OFF ] and section have their cross-section properties interpolated using the
HPC nearest cross-sections attached to other channels. See Section 5.7.7
for details on the process used. Set to OFF to disable this feature
and force every channel to have a cross-section.

@2994
Interpolate Culvert Inverts == Classic If set to ON (the default), any culverts that don’t have an invert (i.e. a
[ {ON} | OFF ] and -99999 value was assigned to the invert attribute(s) and there were
HPC no inverts assigned via any pits or nodes snapped to the culvert
ends) have their invert(s) interpolated using the nearest assigned
inverts of connected culverts/pipes. Set to OFF to disable this
feature.

@2995
M Channel Approach == Classic Sets the matrix interpolation approach for M channel data (Section
[ Method A | {Method B} ] and 5.9.1 ).
HPC
Method A is the original interpolation approach which uses a 4 value
interpolation routine that, especially along the 0 flow diagonal, might
not interpolate as accurately as using a triangular (3 point) technique.
The main issue with the 4 point routine is that a slightly positive or
negative flow of the wrong sign may result when interpolating close
to the zero flow diagonal.

Method B uses an improved method. It uses a triangular interpolation

with the long side of the triangle parallel to the zero flow diagonal,
and does not experience the problems Method A has when
interpolating close to the zero flow diagonal.

Appendix B ECF Commands - 14 / 37 Page 841 / 1094

 Command Solver Description

@2996
M11 Network == Classic Legacy command:
[ ⟨ .nwk11_file ⟩ ] and
Sets the active MIKE 11 network file as ⟨ .nwk11_file ⟩. The file is
HPC
used to extract link, cross-section and other information using
1d_nwk attributes. Topo_ID must be set to “$Link”. For more details
see the 2018 TUFLOW Manual. This command must be specified
before the relevant Read GIS Network command. The command
may be used at any point to change the active MIKE 11 network file.

@3001
Manhole Approach == Classic Sets the automatic manhole definition approach. See Section
[ METHOD A | METHOD B | {METHOD C} ] and 5.11.4.1 .
HPC
Method A is the original approach which has been found to be too
conservative (i.e. higher losses and therefore higher flood levels) as
indicated by users.

Method B, incorporates a few bug fixes found in Method A.

Method C (the default) incorporates further bug fixes affecting

manholes using the Engelund approach for calculating losses.

If using METHOD B, sensitivity testing the effects of METHOD C

versus METHOD B should be carried out to check for any
unacceptable differences.

@3002
Manhole Default C Exit Coefficient == Classic For C (circular) manholes, sets the default K coefficient for flow out of
[ ⟨ KCE ⟩ | {0.25} ] and the manhole and into the out flowing culvert(s). The default value is
HPC 0.25. See Section 5.11.4 .

@3005
Manhole Default Loss Approach == Classic Sets the default loss approach to be used at automatically generated
[ NONE | {ENGELUND} | FIXED ] and manholes, and manholes where no loss approach is specified. The
HPC default is ENGELUND (see Section 5.11.4 for a description on the
different approaches).

Appendix B ECF Commands - 15 / 37 Page 842 / 1094

 Command Solver Description

@3006
Manhole Default R Exit Coefficient == Classic For R (rectangular) manholes, sets the default K coefficient for flow
[ ⟨ KRE ⟩ | {0.5} ] and out of the manhole and into the out flowing culvert(s). The default
HPC value is 0.5. See Section 5.11.4 .

@3009
Manhole Default Side Clearance == Classic For C (circular) manholes, sets the default side clearance in metres
[ ⟨ value_m ⟩ | {0.3} ] and from the side of the largest culvert to the side of the manhole
HPC chamber (i.e. if the diameter of the chamber is not specified, the
diameter is set to the width/diameter of the largest culvert plus twice
the side clearance).

For R (rectangular) manholes, sets the default side clearance from

the side of the culvert(s) to the side of the manhole chamber. If the
width of the chamber is not specified, the width is set to the greatest
incoming or outgoing width, where the width is calculated as the sum
of the incoming/outgoing culvert widths/diameters, plus twice the side
clearance for the sides, plus twice the side clearance for the space
between each incoming/outgoing culvert if more than one incoming
or outgoing culvert exists.

The default side clearance value can be overridden by specifying a

negative width for a manhole in a 1d_mh layer. The side clearance
applied will be the absolute value of the 1d_mh Width attribute, and
the above approach will be used to determine the manhole
width/diameter. See Section 5.11.4 .

Appendix B ECF Commands - 16 / 37 Page 843 / 1094

 Command Solver Description

@3012
Manhole Default Type == Classic Sets the default type of manhole to be used at automatically
[ C | J | R | CR | {CJR} ] and generated manholes, and manholes where no type approach is
HPC specified.

C is for circular manholes;

R for rectangular manholes;
J for junctions (i.e. no chamber); and
CR and CJR are for a combination of C, R and J depending on
the size/configuration of the connecting culverts (see Section
5.11.4 for further details). The default is CJR.

CR assigns an R type if one or more of the below are true, otherwise

a C type is assigned.

The number of barrels of any culvert is greater than one.

There are any parallel culverts (i.e. two or more culverts with the
same nodes and the culverts are digitised in the same direction).
The diameter of at least one circular culvert (C channel) exceeds
1.2m.
The width of at least one rectangular culvert (R channel)
exceeds 0.45m.

CJR uses the same logic as described above for CR, however, it will
assign a J type instead of a C or R if all of the below are true. The J
type in this case is to cover the situation where access is possible via
the culverts, rather than via a manhole.

The number of barrels of all connected culverts must be one,

and there are no parallel culverts (i.e. two or more culverts with
the same nodes and the culverts are digitised in the same
direction).
There is only one inlet and one outlet culvert.

Appendix B ECF Commands - 17 / 37 Page 844 / 1094

 Command Solver Description

The diameter of at least one circular culvert exceeds 1.8m, or

the width and height of at least one rectangular culvert exceeds
1.2m and 1.8m.

@3013
Manhole K Maximum Bend/Drop == Classic Sets the maximum K energy loss coefficient that can occur for the
[ ⟨ max_K_bd ⟩ | {4.0} ] and sum of the loss coefficients for bends and drops at a manhole when
HPC using the Engelund approach. See Section 5.11.4.4 .

@3016
Manhole Minimum Dimension == Classic Sets the minimum diameter for C manholes and minimum width and
[ ⟨ min_width_m ⟩ | {1.05} ] and length for R manholes. The value is usually controlled by the
HPC minimum dimensions needed for access to manhole chambers, not
by any hydraulic efficiency requirements. See Section 5.11.4 .

@3019
Manholes at All Culvert Junctions == Classic
If set to ON (the default), manholes are automatically created at all
[ {ON} | OFF ] and
culvert junctions. See Section 5.11.4 for more information.
HPC

@3020
Maximum Operational Controls == Classic
Sets the maximum number of operational control channels (Section
[ {1000} | ⟨ number of operational and
5.10 ).
channels/control definitions ⟩ ] HPC

@3023
Minimum Channel Conveyance Length == Classic Automatically increases the conveyance (and storage) length to ⟨

[ {0} | ⟨ length_m ⟩ ] and length_m ⟩ if the channel’s length is less than ⟨ length_m ⟩. The
HPC default setting is zero (i.e. no change to any channel’s length). Does
not apply to pit channels.

Appendix B ECF Commands - 18 / 37 Page 845 / 1094

 Command Solver Description

@3030
Minimum Channel Storage Length == Classic If a channel’s length is less than ⟨ length_m ⟩, then ⟨ length_m ⟩ is
[ {0} | ⟨ length_m ⟩ ] and used for calculating any storage contributions from the channel
HPC widths. It does not affect the channels bed resistance, conveyance or
slope. Can be useful to add additional storage for stability reasons to
nodes at the ends of very short channels. If using this command,
care must be taken not to excessively add additional storage causing
results to be distorted. Generally, adding an appropriate amount of
storage for stability reasons does not distort results, however, it is
strongly recommended that sensitivity tests are carried out to cross-
check the effect of any additional storage, and that any adverse
effects are corrected.

@3037
Minimum NA == Classic Sets the minimum surface area (m2) in all NA tables (except for the
[ {1} | ⟨ value ⟩ ] and upstream (ground) nodes of pit channels). The default value is one
HPC (1m2). This command is useful for stabilising 1D nodes that have
very small storages, particularly at shallow depths. If using this
command, care must be taken not to excessively add additional
storage causing results to be distorted. Generally, adding an
appropriate amount of storage for stability reasons does not distort
results, however, it is strongly recommended that sensitivity tests are
carried out to cross-check the effect of any additional storage, and
that any adverse effects are corrected. The percentage (%) option is
provided which sets the minimum NA value for each node based on a
percentage of the maximum nodal area value for the node.

@3040
Minimum NA Pit == Classic Sets the minimum surface area (m2) of the upstream (ground) nodes
[ {1} | ⟨ value ⟩ ] and of all pit channels. The default value is one (1m2). This command
HPC was introduced to differentiate upstream pit channel nodes from the
Minimum NA setting. If the pit channel is connected to a 2D domain,
this storage has no influence on the hydraulic computations, and
increasing the value has no stability benefits.

Appendix B ECF Commands - 19 / 37 Page 846 / 1094

 Command Solver Description

@3043
Momentum Equation == Classic Legacy command:
[ PRE 2003-08-AD ] and
Sets treatment of the effective flow width above the top of a cross-
HPC
section to the method used prior to Build 2003‑08‑AD to provide
backward compatibility. After this build, the effective flow width at the
top of a cross-section is stored and used to extend the effective flow
area above the highest point in the cross-section. Prior to this build,
the top storage width was used for the effective flow width for flows
above the top of the cross-section. This may only affect results where
relative resistance varies across a cross-section, and flow occurs
above the top of the cross-section, and effective flow area is being
used.

@3044 Output ==
Order Classic Alphanumerically orders 1D output according to the node and
[ {ON} | OFF ] and channel IDs. The exception is the boundary condition data in the .eof
HPC file.

@3045 Data Types ==

Output Classic Similar to the .tcf map output command Map Output Data Types ,
[ {H Q S V} | ⟨ data_types ⟩ ] and this command controls which 1D data types to output, The options
HPC are:

A for flow area at channels (m2)

E for energy (m)
H for water level (m3)
Q for flow at channels (m3/s)
Qi integral flow at channels (m3)
S for structure and grouped structure output (see Section 11.3.4
)
V for velocity (m/s)
Vol volume at nodes (m3)

Appendix B ECF Commands - 20 / 37 Page 847 / 1094

 Command Solver Description

@3048 Folder ==
Output Classic Redirects all ESTRY (1D) output data to another folder. Typically
[ ⟨ folder ⟩ ] and used to write output to your local drive instead of filling up the
HPC network or to keep results separate to the input data. A URL path can
be used (e.g. \bmtserv\Computer001\tuflow\results), which is useful
for running simulations on other computers, but having the output
directed to your local drive or other location (your drive will need to
be shared). The default location for 1D output is that specified using
Output Folder in the .tcf file for 1D/2D models.

@3051 Interval ==
Output Classic Legacy command:
[ ⟨ time ⟩ ] and
The output interval for ESTRY output. The default units are hours;
HPC
however, seconds may be used if the “(s)” option is specified. If the
command is omitted, output is at every computational timestep.

@3054 Times Same as 2D ==

Output Classic For 1D/2D models, the times for 1D output are, by default, the same
[ {ON} | OFF ] and as that of the 2D domain(s) time series output (see Start Time Series
HPC Output and Time Series Output Interval ), unless no 2D time series
output (2d_po layers) has been specified, in which case Start Output
and Output Interval are used. For backward compatibility or to use
different times for 1D time series output, set to OFF.

This change was made so that both 1D and 2D time series data
could be output to the_TS. file, allowing graphing of 1D and 2D time
series data within a GIS (see Section 15.3.4 ).

This command is ignored for 1D only (ESTRY) models.

@3055
Overlapping SX HX Boundary == Classic From the 2025.0 release, by default, TUFLOW pre-processing stops
[ CHECK | {ERROR} ] and simulations with ERROR 1462 if a 1D node is connected to both a
HPC SX and HX boundary. This ERROR message can be downgraded to
CHECK, using the ‘CHECK’ option.

Appendix B ECF Commands - 21 / 37 Page 848 / 1094

 Command Solver Description

@3056
Pit Channel Offset == Classic Sets the display, not computed, length in metres of pit channels in 1D
[ ⟨ length_m ⟩ ] and output and the1d_nwk check files. The channel is displayed on a
HPC north to south alignment. See Section 5.11.2 .

@3059
Pit Default 2D Connection == Classic Sets the default value for the 1d_nwk Conn_1D_2D attribute. For
[ {} | ⟨ Conn_1D_2D ⟩ ] and example, if set to SX, then if the 1d_nwk Conn_1D_2D attribute for a
HPC pit is empty, SX will be used, saving the user to specify SX at pits. To
disconnect a pit NO can be used for the Conn_1D_2D attribute. It is
also possible to have the L and Z options at the one pit (e.g. SXLZ).
See Section 5.11.2 .

@3062
Pit Default Extrapolate Q Curve == Classic TUFLOW automatically extrapolates Q and VPI pits depth discharge
[ {ON} | OFF ] and information beyond the last value in the depth-discharge curve using
HPC an orifice flow equation. To not extrapolate the depth-discharge curve
the 1D command “Pit Default Extrapolate Q Curve
== OFF” can be used. See Section 5.11.2 .

@3063
Pit Default Road Crossfall == Classic Increases the depth at Q pits based on the height of an imaginary
[ ⟨ slope ⟩ ] and triangle of the road cross-section with a crossfall slope of ⟨ slope ⟩. ⟨

HPC slope ⟩ is Vertical/Horizontal as a fraction (not percentage).

The imaginary triangle has the same area as the vertical flow area in
the 2D cell the pit is connected to (i.e. the triangle’s area is the depth
in the 2D cell times the width of the cell). Once the horizontal width of
the triangle is greater than the width of the 2D cell, the formula
changes to give an equivalent area based on a trapezoid consisting
of the triangle plus a rectangle for the remaining area in excess of
the triangle. See Section 5.11.3.1 .

Appendix B ECF Commands - 22 / 37 Page 849 / 1094

 Command Solver Description

@3070
Pit Inlet Database == Classic Specifies the pit inlet database file that references the depth-
[ ⟨ pit_inlet_dbase.csv ⟩ ] and discharge curves for Q pit channels. Mandatory if the model has any
HPC Q pit channels.

Performs the same function as Depth Discharge Database . The

same database file can be used for both Q channels and Q pits.

See Section 5.11.3 for more information.

@3073
Pit Search Distance == Classic Set the distance (radius) in metres to search for the closest node to
[ {0.0} | ⟨ psd_m ⟩ ] and automatically connect pits into the 1D network where pits are not
HPC snapped to channel ends. Pits connected via this feature are
displayed in the 1d_nwk_C_check layer as occurring from the
location of the pit to the node, ie. Pit Channel Offset is not used to
display the pit channels created. The pits are also displayed in the
1d_nwk_N_check layer using a different colour to those pits that are
snapped directly to a channel end.

This command may be used several times in the .ecf file with the
most recent occurrence applying at the time a pit is processed. A
value of 0.0 (the default), disables the pit search feature. See Section
5.11.2 .

@3076File ==
Read Classic Directs input to another file. When finished reading ⟨ file ⟩, ESTRY
[ ⟨ file ⟩ ] and returns to reading the .ecf file.
HPC
This command is particularly useful for projects with a large number
of simulations. Repetitive commands are grouped and placed in
another text file. If one of these commands changes, the command
only has to be edited once, rather than in every .ecf file.

This command can be used to redirect file(s) up to a maximum of ten

levels.

Appendix B ECF Commands - 23 / 37 Page 850 / 1094

 Command Solver Description

@3081GIS BC ==
Read Classic
Reads the location and attributes of 1D model boundary conditions,
[ ⟨ gis_layer ⟩ ] and
as described in Section 8.4 .
HPC

@3084GIS IWL ==
Read Classic Reads initial water level elevations at nodes from a 1d_iwl GIS layer.
[ ⟨ gis_layer ⟩ ] and The 1d_iwl layer contains points snapped to nodes in the 1d_nwk
HPC layer(s). The first attribute of the layer must be the initial water level
as a number (float or decimal). The layer can define any number of
the nodes (it does not need to define all the nodes). The command
can be used any number of times to access more than one 1d_iwl
layer. The command can be used in the .tcf and .tef files as 1D Read
GIS IWL.

See Section 8.9.1.1 for further information.

@3087GIS Manhole ==
Read Classic Reads manhole locations and attributes from a GIS 1d_mh layer as
[ ⟨ gis_layer ⟩ ] and described in Section 5.11.4.2 . Any number of 1d_mh layers may be
HPC read by repeating this command. Manholes that occur in the same
location will override each other with the last manhole processed
prevailing. Manholes processed using this command will overwrite
any automatically generated manholes. Automatically generated
manholes may be individually disabled by digitising points and
specifying “NO” for the Loss_Approach attribute – see Table 5.28 .

@3090GIS Network ==
Read Classic Reads channel and node locations and attributes from a GIS 1d_nwk
[ ⟨ gis_layer ⟩ ] and layer as described in Sections 5.4 and 5.13 . Any number of
HPC 1d_nwk layers may be read by repeating this command. If accessing
external cross-section databases such as MIKE 11 .txt file, the XS
Database command must be specified before this command to set
the active cross-section database.

Appendix B ECF Commands - 24 / 37 Page 851 / 1094

 Command Solver Description

@3093GIS Node ==
Read Classic Reads node locations and attributes from a GIS 1d_nd layer as
[ ⟨ gis_layer ⟩ ] and described in Table 5.31 . Any number of 1d_na layers may be read
HPC by repeating this command. This is an alternative option to the
1d_nwk Read GIS Network command, but applies to 1D nodes only.

@3096GIS Pits ==
Read Classic Reads virtual pipe locations and attributes from a GIS 1d_pit layer,
[ ⟨ gis_layer ⟩ ] and as described in Section 5.12 . If using the virtual pipe functionality a
HPC Pit Inlet Database is required.

@3099GIS Table Links ==

Read Classic Reads links to tabular input of cross-section profiles (1d_xs – see
[ ⟨ gis_layer ⟩ ] and Section 5.7 ), nodal surface areas (1d_na – see Section 5.13.2.1 )
HPC or bridge loss coefficients (1d_bg – see Section 5.8.2 ). The first
attribute is the filename (can include a file path) of the .csv or similar
file containing the table. This attribute can be setup as a hotlink,
allowing the file to be opened in spreadsheet software via a GIS
program.

@3102GIS WLL ==
Read Classic
Reads water level lines (WLL) and polygons for defining 1D map
[ ⟨ gis_layer ⟩ ] and
output, see Section 11.2.4 for further information.
HPC

@3105GIS WLL Points ==

Read Classic For WLL Approach Method B, reads elevation and material points
[ ⟨ gis_layer ⟩ ] and generated from the WLLs. This allows more accurate velocity and
HPC flood hazard mapping. See Section 11.2.4.2 for more information.

@3108Operating Controls File ==

Read Classic Directs input to the Operational Controls file (.toc) containing
[ ⟨ .toc_filename ⟩ ] and operating rules applied to hydraulic structures, pumps and other
HPC controllable devices. More than one .toc file can be created and
accessed should there be a need to break the control definitions into
several files (for example, all pump controls could be placed in one
file and sluice gate controls in another).

Refer to Section 5.10 for more information.

Appendix B ECF Commands - 25 / 37 Page 852 / 1094

 Command Solver Description

@3111
S Channel Approach == Classic PRE 2004-06-AA provides backward compatibility of S channel types
[ PRE 2004-06-AA | METHOD A | {METHOD and for pre 2004-06-AA models.
B} ] HPC
METHOD A improved the S channel algorithm after Build 2004-06-
AA. The new approach utilises the approach used by G channels for
handling situations when the downstream end of a channel is dry or
free-overfalling.

METHOD B (the default) was introduced for the 2010-10 release

after rigorous testing on steep, fast flowing channels showed
improved performance over METHOD A. METHOD B only applies the
G channel approach in adverse flow conditions (i.e. when the water
surface gradient is of opposite slope to the channel bed slope),
whereas METHOD A tests for and may apply the G channel algorithm
on any S channel, and was found in extreme situations to cause
some minor choking of the flow down the channel.

@3112
Set IWL == Classic Sets the initial water level at all nodes to ⟨ IWL ⟩. Initial water levels
[ ⟨ IWL ⟩ ] and different to ⟨ IWL ⟩, for example in a lake, can be set using the “Read
HPC GIS IWL ” command.

@3119
Set Variable ⟨ name⟩ == Classic
Define user variables for use within the control files, see Set Variable
[ ⟨ value⟩ ] and
.
HPC

@3124
Spatial Database == Classic Optional when using the GeoPackage input format. Sets the
[ OFF | TCF ] and database to use for subsequent inputs. For more information see
HPC Section 4.4.3 .

@3125 Output ==
Start Classic Legacy command:
[ ⟨ time_in_hours ⟩ ] and
The simulation time in hours when output commences. If the
HPC
command is omitted, the simulation start time is used.

Appendix B ECF Commands - 26 / 37 Page 853 / 1094

 Command Solver Description

@3128
Storage Above Structure Obvert == Classic Defines how the surface area is to be contributed to the NA table
[ CHANNEL WIDTH | ⟨ value ⟩ | {5} ] and above the obvert of B, C and R channels, it does not apply to
HPC manually defined NA tables. The default is to apply 5% of the
maximum surface area.

The CHANNEL WIDTH option uses the top width of B and R

channels and the diameter for C channels (see Section 5.13.3 ).
Older models that used CHANNEL WIDTH (the default prior to 2006-
03-AB) and require it for stability, will most likely need to adopt a
smaller 1D Timestep . Alternatively, use of CHANNEL WIDTH is
acceptable provided the additional storage that it adds to the model
is relatively minor, or it can be demonstrated to not significantly
influence results.

If a value is specified, the channels width by half the channel length

is applied (provided the UCS attribute is left blank or set to “Y” (yes)
or “T” (true) between the invert and obvert, with ⟨ value ⟩ applied
above the obvert. If the (%) option is specified (the default), the value
applied above the obvert is the percentage of the structure’s
maximum surface area. The default setting is to use 5% of the
structure’s maximum surface area above the obvert. If the (%) option
is not specified, the value is in m2 and is applied as a constant above
the obvert.

For C channels, the correct flow width in the section is applied (rather
than the diameter), and for C and R channels, the Number_of
attribute in the 1d_nwk layer is also used. Use this option where the
storage contributed by B, C and/or R channels is significant
(e.g. pipe model).

Note, the reason a storage value of zero is not automatically used

above the obvert is that a node cannot have zero storage. A value of
zero can be used provided storages at the nodes is contributed by

Appendix B ECF Commands - 27 / 37 Page 854 / 1094

 Command Solver Description

other channels, or a pit storage is applied or commands such as

Minimum NA are used. If the only channels connected to a node are
B, C and R channels, the NA table is extended vertically by 10m
(32.8ft) above the highest obvert. Should water levels exceed this
height, use Depth Limit Factor to extend the table further.

@3133
Structure Flow Levels == Classic For calculating structure flows sets, defines whether to use energy or
[ {ENERGY} | WATER | ENERGY UPSTREAM ] and water surface levels as the global default in the flow calculations. The
HPC default is to use ENERGY (upstream and downstream). As of the
2023-03 Release “ENERGY UPSTREAM” can be used, which uses
energy for the upstream and water level for the downstream. The
global default can be overridden channel by channel using the “E”,
“H”, or “EH” optional flag for the 1d_nwk Type attribute (see Table 5.2
).

@3134
Structure Losses == Classic If set to ADJUST, the entrance and exit losses of culverts and the
[ {ADJUST {EXCEPT BG TABLE}} | FIX ] and bridge loss coefficients are adjusted according to the approach and
HPC departure velocities upstream and downstream of the structure. See
Section for details.

This setting can be overridden using an A (adjust) or F (fix) flag for B,

C and R channels.

If set to ADJUST EXCEPT BG TABLE (the default) only adjusts

losses for culverts and automatically generated BG tables noting that
in the latter it is only the deck loss component that is adjusted as the
component specified via the 1d_nwk Form_Loss attribute is always
treated as fixed. Any manually specified BG tables are not adjusted
unless the “A” flag is used in the 1d_nwk Type attribute or “Structure
Losses == ADJUST” is used without specifying “EXCEPT BG
TABLE”.

See Section 5.8.7 for details.

Appendix B ECF Commands - 28 / 37 Page 855 / 1094

 Command Solver Description

@3135
Structure Losses Approach == Classic METHOD A is the original ESTRY routine.
[ METHOD A | {METHOD B} ] and
METHOD B (the default) is an enhancement over METHOD A. It is
HPC
the same as METHOD A, except that if reverse flow occurs in the
approach or departure primary channels (reverse flow is when flow is
in the opposite direction to the channel’s digitised direction), the
adjustment of entrance and exit losses is based on the flow direction,
not the digitised direction.

Appendix B ECF Commands - 29 / 37 Page 856 / 1094

 Command Solver Description

@3136
Structure Losses SX == Classic Extends the adjustment of contraction and expansion losses for 1D
[ ADJUST | ADJUST SKEW | {FIX} ] and culverts and bridges to automatically adjust at 1D/2D SX
HPC connections.

The “FIX” option is the default and is the approach taken in prior
builds, i.e. no adjustment of the losses.

The “ADJUST” (beta function) option takes the depth averaged

velocities at SX cells and applies them as the
approaching/departure velocities to adjust the entrance/exit loss
coefficients of a 1D structure in the same manner as for a 1D/1D
connection (see Section 5.8.7 ).

The “ADJUST SKEW” (beta function) option also considers the

skew angle of the 2D velocity relative to the 1D structure
entrance/exit. By default, the geographical angle of a 1D
structure entrance/exit is automatically calculated from the
1d_nwk GIS layer to calculate the normal velocity:

Vaproach = u × cos(skew angle) + v × sin(skew angle)

The skew angle can be also specified manually using the “B”
attribute in a 2d_bc SX layer with the following rules:

If B = 0.01° ~ 360°, B defines the geometric angle of 1D

structure entrance/exit.
If B = -0.01° ~ -90°, B defines the absolute skew angle, i.e.:
2 2
Vaproach = √u + v × cos(skew angle)

B attribute is normally left as zero, and in such case, the

automatically calculated geometric angle of the connected
1D GIS network is used.
To manually define a 0° angle, “B = 0.01°” can be specified
where “0.01°” is rounded down to a geometric angle of 0°,
while “B = -0.01°” is rounded up to an absolute angle of 0°.

Appendix B ECF Commands - 30 / 37 Page 857 / 1094

 Command Solver Description

The “Zero Skew Angle” command can be used to make the

cut-off value smaller than 0.01, in order to apply an even
smaller user specified angle.

@3139
Structure Routines == Classic Legacy command:
[ ORIGINAL | {2013} ] and
ORIGINAL only allows structures available prior to Build 2013-12-AA
HPC
to be available to force users to limit their use of structures in a
legacy model.

2013 allows the use of the original structures, plus the many new
structures introduced for Build 2013-12-AA. This includes access to
operational structures and any other new structures added since
Build 2013-12-AA.

@3140 Closed NA Table ==

Taper Classic Reduces the second last surface area value gradually over 3
[ {ON} | OFF ] and additional levels for nodes connected to only closed channels such
HPC as bridges and culverts. Also, for B and R channels, starts to reduce
storage a 20% of the structures total depth below the obvert, to
prevent a sudden change in surface area. This command is still to be
further tested, but may offer additional stability in urban models with
many closed structures.

Appendix B ECF Commands - 31 / 37 Page 858 / 1094

 Command Solver Description

@3141
Timestep == Classic 1D/2D TUFLOW Classic or 1D Only ESTRY Simulations
[ ⟨ timestep_in_seconds ⟩ ] and
Specifies the fixed computational timestep of the simulation in
HPC
seconds. Value must be greater than zero. Timesteps that divide
equally into one minute or one hour are recommended. For example,
0.5, 1, 2, 3, 5, 6, 7.5, 10, 12, 15, 20, 30, 45, 60, etc. seconds.

A 1D timestep different to the timesteps of the 2D domains may be

specified for 1D/2D models, however the 1D timestep must not be
greater than the smallest timestep of the 2D domains.

If the 1D timestep is not equally divisible into the smallest 2D

timestep, the 1D timestep is reduced automatically so that it is
equally divisible. If this command is not specified in the .ecf file, the
smallest 2D timestep is used. See Section 3.5.2 for details.

1D/2D TUFLOW HPC Simulations

The 1D timestep for a HPC 1D/2D linked model represents the

maximum limiting timestep the 1D solver can use. ESTRY uses an
adaptive/varying timestep solution when used with the HPC solver.
Both 1D and 2D solutions are always synchronising at the 2D target
timestep, or a multiple of the 2D target timestep if the 1D timestep is
sufficiently greater for the 2D to perform more than one step. If the
1D limiting timestep is less than half the 2D target timestep, the 1D
proceeds in two or more steps eventually synchronising with the 2D
timestep. Where there is not a one to one synchronisation of the 1D
and 2D timesteps, a usually negligible mass error may occur and can
be checked by reviewing the CME% values shown on the Console
Window, the .tlf file or the _MB.csv file in the same manner as
Classic. . See Section 3.5.2 for details.

Appendix B ECF Commands - 32 / 37 Page 859 / 1094

 Command Solver Description

@3144XZ Profiles ==
Trim Classic Trims the XZ profile extracted from Flood Modeller .dat files so that
[ ON | {OFF} ] and the treatment at the ends of the cross-section profile is similar to that
HPC used by Flood Modeller. If set to OFF the whole XZ profile is stored
with the sections of the profile before and after the left and right
markers disabled. However, the active end of the cross-section
profile will extend to midway between the first/last disabled point and
the last/first active point at either end of the profile. If set to ON, the
points before and after the left and right markers are not stored, and
the cross-section extent is not extended to midway to the first/last
points nearest the left and right markers.

To have similar compatibility with Flood Modeller, this command

should be set to ON.

@3145
Vel Rate Creep Factor == Classic Specifies rate at which the Vel Rate Limit value changes. This value
[ ⟨ value ⟩ | {1.2} ] and is rarely changed from its default value of 1.2. See Vel Rate Limit for
HPC further discussion.

@3148
Vel Rate Limit == Classic Specifies the velocity rate limit applied to non-inertial channels
[ ⟨ vrl ⟩ | {0.2} ] and (structures). This value is rarely changed from its default value of 0.2.
HPC During a computation this value is adjusted downwards if a structure
becomes unstable and upwards if stable using the Vel Rate Creep
Factor value. An “L” is shown in the second space after velocity and
flow time output in the .eof file, and also in the_TSF output, indicating
if the velocity rate limit algorithm was applied. If a structure frequently
has the velocity rate limit applied to it, checks should be made on
structure configuration and on the results at the structure. For
example, check the flow through the structure based on the upstream
and downstream water levels is similar to that using desktop
calculations or other software.

Appendix B ECF Commands - 33 / 37 Page 860 / 1094

 Command Solver Description

@3151
Vel Rate Limit Minimum == Classic
Specifies the minimum velocity rate limit that can occur. See Vel Rate
[ ⟨ vrlmin ⟩ | {0.0001} ] and
Limit .
HPC

@3154Approach ==
Weir Classic This command specifies the approach taken to calculate submerged
[ {Method A} | Method B ] and flow for ‘W’ type weirs (refer to Section 5.8.4.2 ). For all other weir
HPC types, the approaches used are discussed in Section 5.8.4.3 .

Method A (the default) utilises the Bradley submergence approach

which after further analysis is the preferred approach.

Method B was initially introduced to provide better stability for weirs

embedded within 2D domains. In some situations, this approach was
found to not converge very well and caused large head drops.

@3155Flow ==
Weir Classic Method A is the original ESTRY routine and only applies to W weirs.
[ Method A | Method B | {Method C} ] and
Method B is not recommended – only applies to W weirs.
HPC
Method C (the default and introduced for the 2016-03 release),
applies Method A for the original W weirs, provides some minor
improvement to WW weirs, and otherwise has no influence for all
other weir types introduced for the 2013-12 release.

Note that for the 2016-03 release there is a general improvement to

all new weirs introduced for the 2013-12 release when the weirs
became drowned out. Previously it was possible for an instability
(usually associated with a large head drop) and/or presence of NaNs
in the results. The new approach does not experience this issue and
is significantly more stable. There is no backward compatibility switch
for this change.

Appendix B ECF Commands - 34 / 37 Page 861 / 1094

 Command Solver Description

@3156
WLL Approach == Classic If set to Method A uses the simpler approach for incorporating 1D
[ Method A | {Method B} ] and output into SMS and GIS map output. Method B (the default) allows
HPC the use of elevation points and material values to more accurately
map and animate 1D results. See Section 11.2.4 for details on
Method B and the TUFLOW 2010 Manual on Method A (noting that
Method A is no longer supported).

@3157
WLL Automatic == Classic If set to CULVERTS, automatically generates 1D WLLs along
[ CULVERTS | {OFF} ] and culverts (C, R and I channels). The WLL will have the same width as
HPC the culvert width, and can save a lot of digitising for large pipe
models! WLLs are placed a short distance from each end of the
culvert channel, and also at each vertices along the channel line.

See Section 11.2.4 for more details.

@3158
WLL No Weirs == Classic If set to ON, TUFLOW will not assign any WLLs to 1D weir channels.
[ ON | {OFF} ] and This is useful where weir channels modelling flow over a bridge or
HPC culvert (especially those using the BW, CW or RW channel type) is in
parallel to a B, C or R channel. In this instance, it is not known
whether the B, C or R channel, or the W channel will be selected for
assigning results to WLLs. To guarantee that the B, C or R channel is
selected use this command with the ON option.

See Section 11.2.4 for more details.

Appendix B ECF Commands - 35 / 37 Page 862 / 1094

 Command Solver Description

@3159
WLL Vertical Offset == Classic Sets the vertical adjustment of WLL elevations in the mesh .2dm file.
[ ⟨ dZ ⟩ | {10} ] and The value of 10 generally means that the 1D WLL output sits above
HPC the 2D cell output and is more visible (which presents data in order of
increasing height). However, in 3D the 1D appears perched on top of
the 2D. To show the WLL mesh at its correct height for 3D displays
specify a dZ value of 0.0.

This command only affects the .2dm file, so can be applied to a

temporary .tcf file used solely to generate an alternative .2dm file
(i.e. there is no need to carry out the hydraulic calculations).

See Section 11.2.4 for more details.

@3162Interpolate Bed ==
WLLp Classic If set to ON (the default), sets the centre WLL point to the channel
[ {ON} | OFF ] and bed based on the processed data (rather than use any value from a
HPC WLLp layer). This forces the bed profiles in longitudinal profile plots
using the ‑lp switch in the TUFLOW_to_GIS utility (see Section 17 )
to be based on that modelled, rather than that a DTM using WLLp
values (which may sometimes occur above the water surface!). Also
helps to show where the WLLp elevations are inconsistent with the
channel bed when viewing in SMS or using TUFLOW_to_GIS.

Doesn’t apply to culverts and bridges which use this approach

regardless, and only applies to WLL Approach == Method B.

See Section 11.2.4 for more details.

Appendix B ECF Commands - 36 / 37 Page 863 / 1094

 Command Solver Description

@3163 Check Files [Exclude | Include |

Write Classic Creates GIS check files and text .csv files for quality control checking
None | ALL] == and of model input data. A list of check files written are described in
[ ⟨ prefix_list_or_file_prefix ⟩ ] HPC Section 14.7 . Refer to the Write Check Files command in the .tcf
file for an explanation of the various options and for examples.

Specifying the Write Check Files command in the .tcf file will
automatically also write the 1D check files for 1D/2D linked models.
There is no need to specify Write Check Files in the .ecf file unless
a different folder path for the files is desired.

@3166
XS Database == Classic Sets the active cross-section database as ⟨ file ⟩. The extension of
[ ⟨ file ⟩ ] and the file determines its format as follows:
HPC
.dat: indicates a Flood Modeller data file containing XZ cross-
section profiles – also see Trim XZ Profiles .
.txt (legacy feature): indicates a MIKE 11 .txt processed data
import/export file. The file must contain processed cross-section
data; any raw data is ignored.
.pro (legacy feature): indicates a Flood Modeller processed
cross-section data file.

The assignment of cross-sections is carried out using 1d_nwk

attributes as discussed in Section 5.7 .

This command must be specified before a Read GIS Network

command. The command may be used at any point to change the
active cross-section database.

Appendix B ECF Commands - 37 / 37 Page 864 / 1094

 @3179

@3180
Appendix C TGC Commands

The TUFLOW Geometry Control File (.tgc) includes commands and geometric / topographic data inputs to build the 2D domain. It is read into
the .tcf using the Geometry Control File command. For more information on the .tgc, see Section 4.2.7 . Building the 2D domain is
discussed in Chapter 7 . The available TGC commands are listed below and are detailed in Table C.1 .

12DA Read Approach Read GIS Code Read GIS SRF

Allow Dangling Z Lines Read GIS CWF Read GIS Variable Z Shape
Cell Size Read GIS FC Shape Read GIS WrF
Create TIN Zpts Read GIS FLC Read GIS Z HX Line
Default Land Z Read GIS FLC/L Read GIS Z Line
Grid Approach Read GIS FRIC Read GIS Z Shape
Grid Size (N,M) Read GIS GWD Read GIS Z Shape Route
Grid Size (X,Y) Read GIS GWL Read GIS Zpts
If Scenario Read GIS IGW Conc Layer N1,N2,..N Tracer Read GIS Zpts Modify Conveyance
Interpolate ZC M1,M2,..M Read Grid CnM
Interpolate ZHC Read GIS IGW Depth Read Grid Code
Interpolate ZUV Read GIS IGW Level Read Grid CWF
Interpolate ZUVC Read GIS IWL Read Grid FLC
Interpolate ZUVH Read GIS Layered FC Shape Read Grid FLC/L
Orientation Read GIS Location Read Grid FRIC
Orientation Angle Read GIS Mat Read Grid GWD
Origin Read GIS Objects Read Grid GWL
Pause When Polyline Does Not Find Zpt Read GIS Receptors Read Grid IGW Conc Layer N1,N2,..N Tracer
Read File Read GIS Soil M1,M2,..M
Read GIS BG Shape Read GIS Soil Base Elevation Read Grid IGW Depth
Read GIS CnM Read GIS Soil Thickness Read Grid IGW Level

Appendix C TGC Commands - 1 / 88 Page 865 / 1094

 Read Grid IWL Set FLC Set Variable ⟨name⟩
Read Grid Location Set FLC/L Set WrF
Read Grid Mat Set FRIC Set Zpt
Read Grid Soil Set GWD SGS
Read Grid Soil Base Elevation Set GWL SGS Grid Max Null Frac
Read Grid Soil Thickness Set IGW Conc Layer N1,N2,..N Tracer SGS Partial Grid Update Null Frac
Read Grid SRF M1,M2,..M SGS ZH Sample Ratio
Read Grid WrF Set IGW Depth Spatial Database
Read Grid Zpts Set IGW Level Stop
Read RowCol ⟨option⟩ Set IWL Thin Line as Thick
Read RowCol WrF Set Mat TIN Angles
Read RowCol Zpts Set Route Cut Off Type TIN Coincident Point Distance
Read TIN Zpts Set Route Cut Off Values Write GIS Domain
Set CnM Set Soil Write GIS Grid
Set Code Set Soil Base Elevation Write GIS Zpts
Set Code and Clean Zpt Set Soil Thickness ZC
Set CWF Set SRF Zero Z Point

Appendix C TGC Commands - 2 / 88 Page 866 / 1094

 @3185
@3189 Table C.1: TUFLOW Classic/HPC TGC Commands

Command Solver Description

@3188
@3190Read Approach ==
12DA Classic and Defines the approach used to read
[ Method A | {Method B} ] HPC the 12DA file format. Method B
(default) supports super TINs. This
method for reading 12da TIN files
however may require slightly more
memory (RAM) than the previous
method. Set this command to
Method A to revert to the previous
method for reading 12da files. See
Section 4.4.1 .

Appendix C TGC Commands - 3 / 88 Page 867 / 1094

 Command Solver Description

@3191 Dangling Z Lines ==

Allow Classic and Legacy command:
[ ON | {OFF} ] HPC
If a breakline using the Read GIS Z
Line command does not find a
snapped point at the end (i.e. the
end is dangling), but the line has at
least one snapped point elsewhere
along the line, this command when
set to ON, assigns the elevation of
the nearest snapped point to the
dangling end. This command may be
used several times through a .tgc file
to change the setting before different
Read GIS Z Line commands.
Elevations applied to dangling ends
are displayed to the check and log
file.

The default (OFF) option does not

allow dangling breaklines. In which
case, WARNING 2075 is written to
the tlf and the elevation adopted is
that given to the line (i.e. all snapped
points are ignored).

Note, if the Z attribute of the line is

NULL, WARNING 2073 is produce
and the line ignored.

@3192Size ==
Cell Classic and Sets the grid’s cell size in metres (or
[ ⟨ value ⟩ ] HPC feet if using Units == US
Customary). See Section 7.3.1 .

Appendix C TGC Commands - 4 / 88 Page 868 / 1094

 Command Solver Description

@3195 TIN Zpts [ {} | WRITE TIN ] [ XF ON | XF OFF ]

Create == Classic and Creates a TIN for each polygon in
[ ⟨ gis_layer ⟩ ] HPC the GIS layer, and assigns elevations
to any Zpts falling within the TIN. Any
points and lines falling within the
polygon are used for creating the TIN
surface. Lines can have points
snapped to them to create a 3D
breakline effect through the TIN. For
more information and examples, see
Section 7.3.5.4 .

If WRITE TIN is specified, a SMS .tin

or 2dm file is written to the same
location as the GIS layer depending
on the setting of the TIN OUTPUT
FORMAT . The 2DM format can be
read by QGIS. Both formats can be
viewed/checked in SMS, edited and
modified if needed. Read TIN Zpts
can be used to assign Zpt values
resulting from the modified TIN. If
Write Check Files is active and
WRITE TIN is specified, the triangles
are written to the 2d_sh_obj_check
layer.

XF ON and XF OFF switch the

automatic generation of XF files ON
or OFF specifically for ⟨ zpt_file ⟩.
The global default for using XF files
is ON and can be changed using XF
Files .

Appendix C TGC Commands - 5 / 88 Page 869 / 1094

 Command Solver Description

@3200
Default Land Z == Classic and Sets any previously unspecified ZH,
[ ⟨ elevation ⟩ ] HPC ZU, ZV or ZC Zpts to the value for
land cells only (code value of “0”,
see Section 7.3.2 ). Is useful where
all the land cells and their Zpts have
been removed from the GIS layers to
keep file sizes to a minimum.

Appendix C TGC Commands - 6 / 88 Page 870 / 1094

 Command Solver Description

@3203Approach ==
Grid Classic and Legacy command:
[ Method A | {Method B} ] HPC
Method A: for iSP (single precision)
builds, this method was found to
occasionally generate a NaN (not a
number) at a Zpt due to precision
issues. This has been fixed for
Method B.

Method B (default): assigns values to

Zpts that fall within the outer half of
the DEM cells around the DEM
perimeter. Previously, if processing a
group of DEM tiles (i.e. using
multiple Read Grid Zpt commands,
one for each tile), any Zpts lying
within the outer half of the DEM
perimeter cells were not assigned a
value. The new approach assigns
values to Zpts around the DEM
perimeter based on an interpolation
of the two DEM cells the Zpt lies
nearest to. Provided tiled DEMs have
a common edge (or overlapping
edge), all Zpts near the DEM edges
should now be assigned a value.

The Grid Approach command may

be used any number of times within
the .tgc file with the latest setting
prevailing when a’Read Grid <grid
type>’ command is processed. If

Appendix C TGC Commands - 7 / 88 Page 871 / 1094

 Command Solver Description

associated .xf files exist from

previous simulations, and Grid
Approach set to Method B is
applied, TUFLOW will automatically
resample and replace the existing .xf
files. The Zpt values will essentially
be identical or very similar except for
around the perimeter of the DEM as
discussed above. This also applies
for all ‘Read Grid <grid type>’ options
(e.g. also applies to Read Grid Mat
).

@3204Size (N,M) ==
Grid Classic and Sets the dimensions of the grid
[ ⟨ rows ⟩ , ⟨ columns ⟩ ] HPC based on the number of rows and
columns. The values entered must
be integer values. See Section 7.3.1
.

See also the command Read GRID

Location , which defines the size
and location of a 2D domain based
on a DEM.

Appendix C TGC Commands - 8 / 88 Page 872 / 1094

 Command Solver Description

@3209Size (X,Y) ==
Grid Classic and Sets the dimensions of the grid using
[ ⟨ X_length ⟩ , ⟨ Y_length ⟩ ] HPC a distance along the grid’s X‑axis (⟨
X_length ⟩) and Y‑axis (⟨ Y_length ⟩

). The number of columns and rows

is rounded to the nearest integer,
therefore, ⟨ X_length ⟩ and ⟨

Y_length ⟩ do not have to be an

exact multiple of the cell size. See
Section 7.3.1 .

See also the command Read GRID

Location , which defines the size
and location of a 2D domain based
on a DEM.

@3222
If Scenario == Classic and Controls which commands to
[ ⟨ s1 ⟩ | ⟨ s2 ⟩ | ⟨ s3 ⟩ ] HPC process for different scenarios, as
specified using the –s run option
(see Section 13.3.2 and Table 13.2
) or Model Scenarios .

Appendix C TGC Commands - 9 / 88 Page 873 / 1094

 Command Solver Description

@3229
Interpolate ZC [ {} | ALL ] [ {} | LOWER ] Classic and Interpolates ZC elevations where
HPC they have not been specified. If ALL
occurs at the end of the command,
then all ZC elevations are
interpolated. Note: If a value already
exists (for example, from previous
Read GIS Zpts commands) it will
not be affected unless the ALL option
is specified.

The LOWER option sets the ZC

value to the average of the two
lowest of the four ZU and ZV points.
This is useful in models with highly
variable or bumpy topography
(e.g. of urban areas with buildings
incorporated), as it will open up and
smooth some flow paths that were
blocked by a high ZC value. The
default is to set the ZC value to the
average of the four ZU and ZV
values. Note, only applies to
topography commands below this
command in the .tgc file.

Also see Interpolate ZHC ,

Interpolate ZUV , Interpolate ZUVC
, Interpolate ZUVH .

Appendix C TGC Commands - 10 / 88 Page 874 / 1094

 Command Solver Description

@3230
Interpolate ZHC [ {} | ALL ] Classic and Interpolates ZH and ZC elevations
HPC where they have not been specified.
If ALL occurs at the end of the
command, then all ZH and ZC
elevations are interpolated. The
values are a linear interpolation of
the ZU and ZV values.

This command can provide some

“smoothing” of the cell centre and
corner elevations that may be
desirable in a model, particularly if
the DTM data is “bumpy”, such as
occurs from airborne laser surveys.

Note, only applies to topography

commands below this command in
the .tgc file.

Also see Interpolate ZC ,

Interpolate ZUV , Interpolate ZUVC
, Interpolate ZUVH

Appendix C TGC Commands - 11 / 88 Page 875 / 1094

 Command Solver Description

@3231
Interpolate ZUV [ {} | ALL ] [ {} | MAX ] Classic and Interpolates ZU and ZV elevations
HPC where they have not been specified.
If ALL occurs at the end of the
command, then all ZU and ZV
elevations are interpolated. The ZU
and ZV values are a linear
interpolation of the neighbouring ZC
values.

This command can provide some

“smoothing” of the cell side
elevations that may be desirable in a
model, particularly if the DTM data is
“bumpy”, such as occurs from
airborne laser surveys.

The MAX option sets the ZU and ZV

values to the higher of the
neighbouring ZC values (rather than
a linear interpolation). This option is
experimental and is not
recommended for practical use.

Note, only applies to topography

commands below this command in
the .tgc file.

Also see Interpolate ZC ,

Interpolate ZHC , Interpolate ZUVC
, Interpolate ZUVH

Appendix C TGC Commands - 12 / 88 Page 876 / 1094

 Command Solver Description

@3232
Interpolate ZUVC [ {} | ALL ] Classic and Interpolates ZC, ZU and ZV
HPC elevations where they have not been
specified. If ALL occurs at the end of
the command, then all ZC, ZU and
ZV elevations are interpolated. The
ZU and ZV values are a linear
interpolation of the neighbouring ZH
values, while the ZC value is the
average of the four surrounding ZH
values (this was the standard
approach of earlier versions of
TUFLOW where only the Zpts at the
H location were specified).

Note, only applies to topography

commands below this command in
the .tgc file.

Also see Interpolate ZC ,

Interpolate ZHC , Interpolate ZUV ,
Interpolate ZUVH

Appendix C TGC Commands - 13 / 88 Page 877 / 1094

 Command Solver Description

@3233
Interpolate ZUVH [ {} | ALL ] [ {} | MAX ] Classic and Interpolates ZH, ZU and ZV
HPC elevations where they have not been
specified. If ALL occurs at the end of
the command, then all ZH, ZU and
ZV elevations are interpolated. The
ZU and ZV values are a linear
interpolation of the neighbouring ZC
values, while the ZH value is the
average of the four surrounding ZC
values. This option is particularly
useful for converting MIKE 21
models where the elevations are only
specified at the cell centres.

The MAX option sets the ZU and ZV

values to the higher of the
neighbouring ZC values (rather than
a linear interpolation). This option is
experimental and is not
recommended for practical use.

Note, only applies to topography

commands below this command in
the .tgc file.

Also see Interpolate ZC ,

Interpolate ZHC , Interpolate ZUV ,
Interpolate ZUVC

Appendix C TGC Commands - 14 / 88 Page 878 / 1094

 Command Solver Description

@3234
Orientation == Classic and Sets the geographical orientation of
[ ⟨ XX ⟩ , ⟨ YX ⟩ ] HPC the grid in metres (or feet if using
Units == US Customary) using
another point along the bottom (X-
axis) of the grid with coordinates ⟨

XX ⟩, ⟨ YX ⟩. To set the grid’s origin

see Origin . See Section 7.3.1 .

@3243
Orientation Angle == Classic and Sets the geographical orientation of
[ ⟨ angle ⟩ ] HPC the grid using an angle. The angle is
in degrees relative to east (e.g. X-
axis directly north would be 90°).
See Section 7.3.1 .

@3246 ==
Origin Classic and Sets the geographical origin of the
[ ⟨ OX ⟩ , ⟨ OY ⟩ ] HPC grid, the origin being the lower left
corner of the lower left cell. ⟨ OX ⟩ is
the X‑coordinate and ⟨ OY ⟩ the
Y‑coordinate in metres (or feet if
using Units == US Customary).
See Section 7.3.1 .

Appendix C TGC Commands - 15 / 88 Page 879 / 1094

 Command Solver Description

@3255 When Polyline Does Not Find Zpt ==

Pause Classic and Legacy command:
[ ON | {OFF} ] HPC
If a breakline using the Read GIS Z
Line command does not find a Zpt,
the default (OFF) option produces
WARNING 2075 in the tlf and the
elevation adopted is the value
assigned to the line (i.e. all snapped
points are ignored). Note, if the Z
attribute of the line is NULL,
WARNING 2073 is produce and the
line ignored. The ‘OFF’ option is
useful where there are very short
breaklines (for example, survey lines
imported from another software
which has lost the connectivity
between line segments), which do
not affect any Zpts.

By setting this command to ON, if a

breakline using the Read GIS Z Line
command does not find a Zpt,
TUFLOW will pause (with a warning
message) and waits for a return key
to be entered.

This command may be used several

times through a file to change the
setting before different Read GIS Z
Line commands.

Appendix C TGC Commands - 16 / 88 Page 880 / 1094

 Command Solver Description

@3256File ==
Read Classic and Directs input to another file. When
[ ⟨ file ⟩ ] HPC finished reading ⟨ file ⟩, TUFLOW
returns to reading the .tgc file. See
Section 4.2.15 .

This command is particularly useful

for projects with a large number of
.tgc files. Repetitive commands are
grouped and placed in another text
file. If one of these commands
changes, the command only has to
be edited once, rather than in every
.tgc file.

For example, as the grid size,

location and orientation commands
are likely to be the same for all runs,
placing these commands in their own
text file could be advantageous if
ever the grid’s size, location and/or
orientation changes (i.e. only one file
would have to be edited).

This command can be used in

redirected file(s) up to a maximum of
ten levels.

Appendix C TGC Commands - 17 / 88 Page 881 / 1094

 Command Solver Description

@3261GIS BG Shape ==
Read Classic and Used to read in a 2D bridge object
[ ⟨ gis_layer ⟩ ] HPC (2d_bg) GIS layer which constricts
the flow across a 2D cell side. See
Section 7.3.8.2 .

This command was introduced in the

2023-03 release.

@3264GIS CnM ==
Read Classic Only Bed resistance value. CnM is a
[ ⟨ gis_layer ⟩ ] Chezy C, Manning’s n or Manning’s
M value as set by Bed Resistance
Values . Uses 2d_mat GIS layer.
See Section 7.5.3 .

Appendix C TGC Commands - 18 / 88 Page 882 / 1094

 Command Solver Description

@3267GIS Code
Read [ {} | BC | Invert | BC Invert ] == Classic and Used to specify the cell code (see
[ ⟨ gis_layer ⟩ ] HPC Section 7.3.2 ). Uses 2d_code GIS
layer.

The following values can be

specified:

0: Inactive cells (e.g. land or

redundant cells);
1: Active cells (e.g. water);
2: Boundary cells (e.g. active
cells with an external boundary);
-1: Inactive cells within the
active domain.

Any values great than 2 will be

treated as active cells (cell code of
1). Any values less than -1 will be
treated as inactive cells (cell code of
0).

When using “Read GIS Code BC”,

code values are extracted from
objects in a 2d_bc layer that have a
Type attribute of “CD” (instead of the
2d_code), the code value is taken
from the 2d_bc f attribute. See Table
8.6 .

If INVERT is specified (e.g.”Read

GIS Code Invert” or “Read GIS Code
BC Invert”), the active/inactive status
of any Code polygons are reversed

Appendix C TGC Commands - 19 / 88 Page 883 / 1094

 Command Solver Description

(ie. a Code of 1 becomes 0, and a

Code of -1 or 0 becomes 1). This
means that the same layer can be
used by both .tgc and .tbc files when
linking 2D domains using TUFLOW
Classic Multiple 2D Domain Module.

@3270GIS CWF ==
Read Classic and Sets the cell flow width (see Section
[ ⟨ gis_layer ⟩ ] HPC 7.3.9.2 ) based on the input GIS
layer. The value entered for CWF is
a factor to adjust the 2D cell flow
widths (in the same manner as 2D
flow constrictions (2d_fc)), noting
that the changed flow width applies
to all depths. For example 0.1 will
limit the flow width to 10%.

@3273GIS FC Shape [ {} | Write TIN ]

Read == Classic Command to read in a flow
[ ⟨ gis_layer ⟩ ] constriction shape (2d_fcsh) GIS
layer which constricts the flow across
a 2D cell side. See Section 7.5.6.1 .

@3276GIS FLC ==
Read Classic and Applies the form loss attribute values
[ ⟨ gis_layer ⟩ ] HPC to all cells within each region. Uses
2d_flc GIS layer. See Section 7.3.9.3
.

Note, the FLC values will need to be

changed if the 2D cell size changes.

Appendix C TGC Commands - 20 / 88 Page 884 / 1094

 Command Solver Description

@3279GIS FLC/L ==
Read Classic and Applies a form loss per unit length to
[ ⟨ gis_layer ⟩ ] HPC all cells within each region. Uses
2d_flc GIS layer. The effect of
applying the FLC in this manner is
2D cell size independent. See
Section 7.3.9.3 .

@3282GIS FRIC ==
Read Classic Only Ripple height. See Section 7.5.3 .
[ ⟨ gis_layer ⟩ ] Uses 2d_mat GIS layer.

@3285GIS GWD ==
Read Classic and Legacy command:
[ ⟨ gis_layer ⟩ ] HPC
Groundwater depth (see Section
8.9.2 ). Uses 2d_gw GIS layer. This
command may only be specified
following Set Soil , Read GIS Soil
and/or Read Grid Soil commands.

@3288GIS GWL ==
Read Classic and Legacy command:
[ ⟨ gis_layer ⟩ ] HPC
Groundwater level (see Section 8.9.2
). Uses 2d_gw GIS layer. This
command may only be specified
following Set Soil , Read GIS Soil
and/or Read Grid Soil commands.

Appendix C TGC Commands - 21 / 88 Page 885 / 1094

 Command Solver Description

@3291GIS IGW Conc Layer N1,N2,..N Tracer M1,M2,..M ==

Read HPC Only Sets the initial concentration of one
[ ⟨ gis_layer ⟩ ] or more tracers in one or more
groundwater layers of the model
based on the input GIS layer. Where
N1,N2,..N are the groundwater layer
numbers and M1,M2,..M are the
tracer numbers. If a layer number is
not referenced, it is assumed to
apply to layer 1. Likewise, if a tracer
number is not referenced it is
assumed to apply to the first tracer.
For more information see Section
9.5.6 . Uses 2d_gw GIS layer.

Note, the order that ‘Layer’ and

‘Tracer’ appear in the command does
not matter (i.e. tracer numbers could
be listed before layer numbers).

Appendix C TGC Commands - 22 / 88 Page 886 / 1094

 Command Solver Description

@3294GIS IGW Depth [{} |

Read ⟨ Layer N ⟩ ] == Classic and Sets the initial water depth in the Nth
[ ⟨ gis_layer ⟩ ] HPC subsurface layer in meters (or feet if
using Units == US Customary)
based on the input GIS layer.
Assumed to be the depth of water in
the soil (water content divided by
porosity). If Read GIS IGW Depth
Layer N is used with the Read GIS
IGW Level Layer N the highest
initial condition will be adopted. If
using multiple soil layers (see
Section 7.4.5.2 ), the initial
conditions do not automatically
cascade into layers below
(i.e. setting the initial water depth 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

Appendix C TGC Commands - 23 / 88 Page 887 / 1094

 Command Solver Description

Moisture” defined in the .tsoilf. Uses

2d_gw GIS layer. For more
information see Section 8.9.2 .

Note, multiple soil layers in the

vertical are only supported using
TUFLOW HPC.

Appendix C TGC Commands - 24 / 88 Page 888 / 1094

 Command Solver Description

@3299GIS IGW Level [{} |

Read ⟨ Layer N ⟩ ] == Classic and Sets the initial water level in the Nth
[ ⟨ gis_layer ⟩ ] HPC subsurface layer in meters (or feet if
using Units == US Customary)
based on the input GIS layer. If Read
GIS IGW Depth Layer N is used
with the Read GIS IGW Level Layer
N the highest initial condition will be
adopted. 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. Uses
2d_gw GIS layer. For more
information see Section 8.9.2 .

Note, multiple soil layers in the

vertical are only supported using
TUFLOW HPC.

Appendix C TGC Commands - 25 / 88 Page 889 / 1094

 Command Solver Description

@3304GIS IWL ==
Read Classic and Sets the initial water level (see
[ ⟨ gis_layer ⟩ ] HPC Section 8.9.1 ) based on the input
(2d_iwl) GIS layer. The units are
metres (or feet if using Units ==
US Customary).

Note: IWLs can also be set in the .tcf

file (see Set IWL ). This is
preferable if the initial water levels
vary from simulation to simulation as
it removes the necessity to create a
new .tgc file each time the initial
water levels change. Any IWL values
set in the .tcf file override those
specified in the .tgc file for the same
cells.

@3307GIS Layered FC Shape [ {} | Write TIN ]

Read == Classic and Offers the ability to vary flow
[ ⟨ gis_layer ⟩ ] HPC constriction (FC) parameters with
height as a method to model
obstructions, such as bridges and
above ground pipeline infrastructure,
in 2D at all flow heights. Uses
2d_lfcsh GIS layer. See Section
7.3.8.3 for details.

Appendix C TGC Commands - 26 / 88 Page 890 / 1094

 Command Solver Description

@3310GIS Location ==
Read Classic and Sets the geographical origin and
[ ⟨ gis_layer ⟩ ] HPC orientation of the grid based on the
first line or region found in ⟨

gis_layer ⟩. Uses 2d_loc GIS layer.

The orientation is based on the first
point in the line or region being
located at the bottom left corner of
the grid.

If a line is used the second point is

located anywhere along the bottom
of the grid to set the orientation of
the grid – it does not determine the
length of the grid along the X-axis
(use Grid Size (N,M) or Grid Size
(X,Y) to set the size of the grid). A
line must only have two vertices, if
more than two are used (i.e. a
polyline) TUFLOW stops with an
error.

If a region is used it must have four

sides digitised clockwise. The
second vertex is located at or close
to the top left corner of the 2D grid.
The distance from the first to second
vertices determines the length of the
grid’s Y-axis. The third vertex is not
used. The fourth vertex is located at
the bottom right corner of the grid.
The distance from the first to fourth
vertices determines the length of the

Appendix C TGC Commands - 27 / 88 Page 891 / 1094

 Command Solver Description

grid’s X-axis. The grid’s orientation is

determined from the line passing
from the first vertex to the fourth
vertex.

For more information see Section

7.3.1 .

@3315GIS Mat ==
Read Classic and Sets the Material ID (see Section
[ ⟨ gis_layer ⟩ ] HPC 7.3.6 ), using the 2d_mat GIS layer.
The Material ID value must
correspond to a value within the
Materials Definition File Read
Materials File . If Bed
Resistance Cell Sides ==
INTERROGATE (the default), the
material values are directly sampled
at the cell mid-sides. This gives a
higher resolution definition of the
materials data, thereby giving
improved flow patterns where
Manning’s n values vary significantly
such as in an urban environment.

Appendix C TGC Commands - 28 / 88 Page 892 / 1094

 Command Solver Description

@3318GIS Objects [ RECORD GAUGE DATA [ {} | USE ZC |

Read Classic References a 2d_obj (Read GIS
ZPTS ] ] == objects) or 2d_rec (Read GIS
[ ⟨ gis_layer ⟩ ] receptors) GIS layer containing
points or polygons representing
receptors such as properties or
buildings. At present the only option
is to use the RECORD GAUGE
DATA feature, with more options to
record or value add information to
receptors planned for future
releases.

RECORD GAUGE DATA records the

flood level and simulation time at one
or more gauge(s) when the receptor
is first inundated above a trigger
inundation level (e.g. floor level).
Gauges are defined as a point within
a 2d_po GIS layer with type “G_”
(see Section11.3.2 ). The levels
from all gauges are recorded at each
receptor once inundated.

At present up to 20 different layers

may be read in by repeating this
command (let us know if you want to
input more than 20 layers!).

The first attribute in the GIS layer is

used to set the trigger inundation
elevation (e.g. floor level) to record

Appendix C TGC Commands - 29 / 88 Page 893 / 1094

 Command Solver Description

the gauge level(s) unless the USE

ZC option is specified.

The USE ZC option, sets the trigger

inundation level to either the ZC
elevation of the cell (for digitised
point objects) or the lowest ZC
elevation within the polygon (for
digitised polygon objects). In this
case the first attribute is not used as
the trigger inundation level.

The ZPTS option allows TUFLOW to

adjust the Zpts within the polygon or
whole cell at a point object,
essentially merging the functionality
of the Read GIS Zpts command
with Read GIS Objects . In this
case, the first attribute is used to set
the value of the Zpts within each
polygon. If there is a second
attribute, this is used to define the
trigger inundation level, otherwise
the first attribute is used for this
level.

Refer to Section 11.2.4 for further

information.

Alias: Read GIS Receptors .

Appendix C TGC Commands - 30 / 88 Page 894 / 1094

 Command Solver Description

@3321GIS Receptors [ RECORD GAUGE DATA [ {} | USE ZC |

Read Classic Only
See Read GIS Objects for
ZPTS ] ] ==
command description.
[ ⟨ gis_layer ⟩ ]

@3324GIS Soil
Read [{} | ⟨ Layer N ⟩ ] == Classic and Sets the soil ID (see Section 7.3.7 )
[ ⟨ gis_layer ⟩ ] HPC based on the input GIS layer
(2d_soil). The Soil ID value must
correspond to a value within the
.tsoilf file. (refer to Read Soils File ).
Multiple soil layers are supported
when using TUFLOW HPC (see
Section 7.4.5.2 ). The layer(s) that
this command applies to can be
optionally defined using Set Soil
Layer <N[,N2,N3…]> ==
<value> In the absence of a layer
definition the command applies to
layer 1.

Appendix C TGC Commands - 31 / 88 Page 895 / 1094

 Command Solver Description

@3329GIS Soil Base Elevation

Read [{} | ⟨ Layer N ⟩ ] == Classic and Sets the base elevation of the Nth
[ ⟨ gis_layer ⟩ ] HPC subsurface layer in meters (or feet if
using Units == US Customary)
based on the input GIS layer. Uses
2d_gw GIS layer. Note, multiple soil
layers are only supported when
using TUFLOW HPC (see Section
7.4.5.2 ). If the Soil Thickness or
Base Elevation is not set for a given
layer, it is assumed to be infinite. If
both methods are specified for a
given cell the highest of the two will
be adopted. For more information
see Section 7.3.7.1 .

@3334GIS Soil Thickness

Read [{} | ⟨ Layer N ⟩ ] == Classic and Sets the thickness in the vertical of
[ ⟨ gis_layer ⟩ ] HPC the Nth subsurface layer in meters
(or feet if using Units == US
Customary) based on the input GIS
layer. Uses 2d_gw GIS layer. Note,
multiple soil layers are only
supported when using TUFLOW
HPC (see Section 7.4.5.2 ). The
thickness is set from the layer above.
If the Soil Thickness or Base
Elevation is not set for a given
layer, it is assumed to be infinite. If
both methods are specified for a
given cell the highest of the two will
be adopted. For more information
see Section 7.3.7.1 .

Appendix C TGC Commands - 32 / 88 Page 896 / 1094

 Command Solver Description

@3339GIS SRF ==
Read Classic and Sets the storage reduction factor
[ ⟨ gis_layer ⟩ ] HPC from the input GIS layer (2d_srf).
The storage of 2D cells may be
reduced (for example to model
hypothetical filling, or reduced
storage from buildings), or
increased. For example, if a cell has
a Storage Reduction Factor (SRF)
value of 0.1, then its storage (surface
area) is reduced by 10%. If the SRF
value is less than zero, the storage is
increased. The default SRF value is
zero (i.e. no change in storage). For
more information see Section 7.3.9.1
.

Appendix C TGC Commands - 33 / 88 Page 897 / 1094

 Command Solver Description

@3342GIS Variable Z Shape [ XF ON | XF OFF |

Read Classic and Used to define the final 3D shape of
Write TIN ] == HPC the Zpts at the completion of a
[ ⟨ gis_layer ⟩ ] breach, or other change in
topographic shape, during a
simulation. See Section 7.3.5 .
Similar to Read GIS Z Shape , but
with additional attributes to control
the trigger mechanism and time
period of the failure. For examples
and detailed description of the
2d_vzsh GIS layer attributes, see
Section 7.3.5.3 .

The XF ON and XF OFF switch the

automatic generation of XF files ON
or OFF specifically for ⟨ vzsh_file ⟩.
The global default for using XF files
is ON and can be changed using XF
Files .

@3347GIS WrF ==
Read Classic and Applies the WrF value to all cell
[ ⟨ gis_layer ⟩ ] HPC faces based on the input 2d_wrf GIS
layer. The global value Global Weir
Factor and the spatially varying
value are multiplied together (i.e. one
does not replace the other).

Appendix C TGC Commands - 34 / 88 Page 898 / 1094

 Command Solver Description

@3350GIS Z HX Line [ {} | RIDGE or MAX or RAISE ] ==

Read Classic and Uses HX lines and ZP points from a
[ ⟨ gis_layer ⟩ ] HPC 2d_bc (or 2d_hx) layer to set the cell
elevations along HX lines. There
must be at least one “ZP” (Type)
point snapped to each HX line in the
2d_bc layer (alternatively a separate
points layer can be used - see
Section 7.3.5.7.1 ). The 2d_bc “f”
attribute is used to set the elevation
and the “d” attribute is used to adjust
the elevation (i.e. if d = 0, the
elevation remains unchanged –
useful if you wish to raise the line by,
say, 0.2m) - see Table 8.6 .

If no “ZP” points are snapped to the

HX line then no Zpts are adjusted
along that line and a CHECK is
issued stating this.

When adjusting the cell heights, the

THICK approach described for Read
GIS Z Line is used (i.e. the whole
cell is modified).

If RIDGE or MAX or RAISE (they all

perform the same function!) are
specified this becomes the default
setting for the treatment of all HX
lines. Alternatively, the “R” Flag can
be used to force the ridge option for
that line. If RIDGE or MAX or RAISE

Appendix C TGC Commands - 35 / 88 Page 899 / 1094

 Command Solver Description

is specified the “R” flag on a HX line

is redundant - see . An “A” flag
adjusts all elevations irrespective of
whether RIDGE, MAX or RAISE are
used.

Appendix C TGC Commands - 36 / 88 Page 900 / 1094

 Command Solver Description

@3353GIS Z Line ==
Read Classic and Legacy command:
[ ⟨ gis_layer ⟩ ] HPC
Reads a 2d_z_ GIS layer (e.g. .gpkg,
.shp or .mif) containing lines that are
treated as breaklines in the model’s
bathymetry. The breakline can vary
in height along its length (i.e. a 3D
breakline).

This is a powerful feature for quickly

and easily entering a breakline
feature such as a road, railway,
levee, creek, drain, etc. It is
particularly useful where TUFLOW’s
fixed grid discretisation does not
guarantee that the crest along, for
example, a road, is picked up from
the DTM, or the lowest point along a
drain. It saves having to incorporate
roads, levees, etc. into the DTM.

The modified Zpts, except for the

GULLY option, are output to the
2d_zln_zpt_check layer (see Table
12‑2) if Write Check Files has been
set.

The approach uses the polylines in

the layer to set the nearest Zpt
values in the TUFLOW grid to the
polyline’s height.

Appendix C TGC Commands - 37 / 88 Page 901 / 1094

 Command Solver Description

A variable height polyline is created

in the GIS by snapping the polyline
to points in the same layer. The first
attribute column must be a number
(real or integer) representing the
elevation of the points. Other
attributes are ignored. If the polyline
is not snapped with a point at its
beginning and end, the polyline is
assumed to be horizontal (the height
is taken from the polyline’s attribute).
Otherwise, the polyline’s grade is
determined by the height of the
points snapped to the polyline nodes.
It is not necessary to snap a point at
every polyline node – the minimum
requirement is a point snapped to
each polyline end. Height values for
nearby TUFLOW Z-points are
interpolated.

The default is to modify a “thin” line

following the ZH, ZU and ZV Zpts. If
the THICK option occurs,
interpolated Z values are applied to
whole cells (i.e. at the cell centres,
all cell sides and cell corners).

If the RIDGE option is specified, the

Z values are only modified where the
polyline height is higher than the
current Z values. This is useful

Appendix C TGC Commands - 38 / 88 Page 902 / 1094

 Command Solver Description

where, for example, a weir occurs in

a river and it is easier to just digitise
the weir from bank to bank without
having to determine where it should
exactly end. The keyword MAX can
be substituted for RIDGE.

Conversely, the GULLY option

adjusts the ZU, ZV and ZC values
where the polyline is lower than the
current Z value. This option is useful
for ensuring low flow paths such as
small creeks or drains are modelled
without “dams” across their path.
The GULLY option should not be
seen as a method to accurately
define the shape of a waterway.
The keyword MIN can be substituted
for GULLY. Note: The THICK option
is not available with the GULLY
option.

If Line Cell Selection is set to

Method C (the default), a more
advanced approach for the RIDGE
option is used to interpolate Zpt
values. The approach interpolates
from the Zpt to the nearest
intersection of the Z line (i.e. the
perpendicular), or if there is no
perpendicular intersection, the
nearest vertex on the Z line. The

Appendix C TGC Commands - 39 / 88 Page 903 / 1094

 Command Solver Description

previous approaches used a more

simplistic approach of intersecting
the polyline with a line extending
perpendicular to the cell side, and
ZC and ZH values were an average
of the modified ZU and ZV values.
The new approach produces
“smoother” Zpts, and is not prone to
unpredictable final elevations where
multiple Z lines cross through a cell.
For RIDGE, the highest value of the
Z lines that intersect with the “cross-
hairs” is chosen, even if there are
closer Z lines. If RIDGE (or MAX) is
not specified, the value from the
closest eligible Z line is used. ADD
works for both scenarios.

The GULLY option takes the

intersection of the polyline with the
cell side to determine elevations.

If neither the RIDGE nor GULLY

option is specified, the Z values are
adjusted along the entire polyline
length, irrespective of whether the
height of the line is higher or lower
than the current Zpt values. The
RIDGE (not the GULLY)
methodology is used in determining
which Zpts are selected for
modification.

Appendix C TGC Commands - 40 / 88 Page 904 / 1094

 Command Solver Description

The ADD option adds (use negative

values to subtract) the height value
along the polyline to the current Zpt
values.

See also Allow Dangling Z Lines

and Pause When Polyline Does Not
Find Zpt commands). See Section
7.3.5 .

This feature is also incorporated into

Read GIS Z Shape , Read GIS
Variable Z Shape and other shape
commands. These commands offer
more flexible application of Z lines in
that a layer can contain a mixture of
thin and thick lines, a mixture of
RIDGE, GULLY and ADD options,
and a width in metres can be applied
to lines if more than one cell width is
needed to be raised/lowered/added.
See Section 7.3.5.5 for further
information.

Appendix C TGC Commands - 41 / 88 Page 905 / 1094

 Command Solver Description

@3356GIS Z Shape [ {} | RIDGE or MAX or RAISE |

Read Classic and Command that offers powerful
GULLY or MIN or LOWER ] [ XF ON | XF OFF | Write TIN] == HPC options for modifying Zpt elevations
[ ⟨ gis_layer ⟩ ] using points, lines and polygons to
define 3D shapes. For examples and
detailed description of the options
available see Section 7.3.5 . The
full functionality (and more) of Read
GIS Z Line is incorporated into this
command. Uses 2d_zsh GIS layer.

If RIDGE or MAX or RAISE (they all

perform the same function!) are
specified this becomes the default
setting for the treatment of lines
unless the Shape_Options attribute
for a line overrides this setting.
Similarly if GULLY or MIN or LOWER
is specified.

The _sh_obj_check layer may be

used to view the buffer polygons of
wide Z Lines.

XF ON and XF OFF switch the

automatic generation of XF files ON
or OFF specifically for ⟨ zsh_file ⟩.
The global default for using XF files
is ON and can be changed using XF
Files .

Appendix C TGC Commands - 42 / 88 Page 906 / 1094

 Command Solver Description

@3361GIS Z Shape Route [ {} | RIDGE or MAX or RAISE |

Read Classic Command that provides output on
GULLY or MIN or LOWER | Write TIN ] == the degree of inundation along
[ ⟨ gis_layer ⟩ ] routes, and helps define evacuation
routes, warning times, risks and
durations that routes are cut off. It
also performs the same adjustment
to Zpts as per Read GIS Z Shape .

See section 11.4.2 for a description

of this feature. Also see Set Route
Cut Off Values and Set Route Cut
Off Type . Uses 2d_zshr GIS layer.

Appendix C TGC Commands - 43 / 88 Page 907 / 1094

 Command Solver Description

@3364GIS Zpts [ {} | ADD | MAX | MIN ]

Read == Classic and Reads the Zpt values from a GIS
[ ⟨ gis_layer ⟩ ] HPC layer (e.g. .gpkg, .shp or .mif). See
Section 7.3.5 . Uses the 2d_z_ GIS
layer. If other format files are used,
the first attribute (column) must be
the Zpt value attached to the GIS
objects. Any other attribute columns
are ignored.

Any Zpt (ZC, ZU, ZV and ZH) falling

within a region object is assigned the
object’s first attribute value.
Topography modifications defined
using point or line objects will update
the ZC values.

The ADD option adds the first

attribute value of the object to the
Zpts. Use a negative value to
subtract.

The MAX option will only raise a Zpt

from its existing value, while the MIN
option will only lower the Zpt value
from its existing value.

Appendix C TGC Commands - 44 / 88 Page 908 / 1094

 Command Solver Description

@3367GIS Zpts Modify Conveyance ==

Read Classic and Can be used to modify the elevation
[ ⟨ gis_layer ⟩ | ⟨ k_factor ⟩ | ⟨ water_level_grid ⟩ ] HPC for a series of cells based on an
increase or decrease in conveyance.
Three inputs are required for this
operation.

These are:

A GIS layer containing a region /

polygon object within which the
modification will apply;
A conveyance multiplication
factor; and
A water level grid.

Uses 2d_z_ GIS layer. For more

information, see Section 7.3.9.4 .

@3374Grid CnM ==
Read Classic Only Bed resistance value. CnM is a
[ ⟨ grid_file ⟩ ] Chezy C, Manning’s n or Manning’s
M value as set by Bed Resistance
Values . See Section 7.5.3 .

Appendix C TGC Commands - 45 / 88 Page 909 / 1094

 Command Solver Description

@3377Grid Code ==
Read Classic and Used to specify the cell code (see
[ ⟨ grid_file ⟩ ] HPC Section 7.3.2 ).

The following values can be

specified:

0: Inactive cells (e.g. land or

redundant cells);
1: Active cells (e.g. water);
2: Boundary cells (e.g. active
cells with an external boundary);
-1: Inactive cells within the
active domain.

Any values great than 2 will be

treated as active cells (cell code of
1). Any values less than -1 will be
treated as inactive cells (cell code of
0).

Note, this command is not supported

when using the TUFLOW HPC
Quadtree functionality (Section 7.4.1
). Please use Read GIS Code
instead.

Appendix C TGC Commands - 46 / 88 Page 910 / 1094

 Command Solver Description

@3380Grid CWF ==
Read Classic and Sets the cell flow width (see Section
[ ⟨ grid_file ⟩ ] HPC 7.3.9.2 ) based on the input grid.
The value entered for CWF is a
factor to adjust the 2D cell flow
widths (in the same manner as 2D
flow constrictions (2d_fc)), noting
that the changed flow width applies
to all depths. For example 0.1 will
limit the flow width to 10%. Uses
2d_cwf GIS layer.

@3383Grid FLC ==
Read Classic and Applies the form loss attribute values
[ ⟨ grid_file ⟩ ] HPC to all cells within each region. See
Section 7.3.9.3 .

Note that FLC values will need to be

changed if the 2D cell size changes.

@3386Grid FLC/L ==
Read Classic and Applies form losses per unit length to
[ ⟨ grid_file ⟩ ] HPC all cells. The effect of applying the
FLC in this manner is 2D cell size
independent. See Section 7.3.9.3 .

@3389Grid FRIC ==
Read Classic Only Ripple height. See Section 7.5.3 .
[ ⟨ grid_file ⟩ ] Uses 2d_mat GIS layer.

@3392Grid GWD ==
Read Classic and Legacy command:
[ ⟨ grid_file ⟩ ] HPC
Groundwater depth (see Section
8.9.2 ). The Read Grid GWD
command may only be specified
following Set Soil , Read GIS Soil
and/or Read Grid Soil commands.

Appendix C TGC Commands - 47 / 88 Page 911 / 1094

 Command Solver Description

@3395Grid GWL ==
Read Classic and Legacy command:
[ ⟨ grid_file ⟩ ] HPC
Groundwater level (see Section 8.9.2
). The Read Grid GWL command
may only be specified following Set
Soil , Read GIS Soil and/or Read
Grid Soil commands.

@3398Grid IGW Conc Layer N1,N2,..N Tracer M1,M2,..M ==

Read HPC Only Sets the initial concentration of one
[ ⟨ grid_file ⟩ ] or more tracers in one or more
groundwater layers of the model
based on the input grid. Where
N1,N2,..N are the groundwater layer
numbers and M1,M2,..M are the
tracer numbers. If a layer number is
not referenced, it is assumed to
apply to layer 1. Likewise, if a tracer
number is not referenced it is
assumed to apply to the first tracer.
For more information, see Section
9.5.6 .

Note, the order that ‘Layer’ and

‘Tracer’ appear in the command does
not matter (i.e. tracer numbers could
be listed before layer numbers).

Appendix C TGC Commands - 48 / 88 Page 912 / 1094

 Command Solver Description

@3401Grid IGW Depth [{} |

Read ⟨ Layer N ⟩ ] == Classic and Sets the initial water depth in the Nth
[ ⟨ grid_file ⟩ ] HPC subsurface layer in meters or feet
based on the input grid. Assumed to
be the depth of water in the soil
(water content divided by porosity). If
Read Grid IGW Depth Layer N is
used with the Read Grid IGW Level
Layer N the highest initial condition
will be adopted. If using multiple soil
layers (see Section 7.4.5.2 ), the
initial conditions do not automatically
cascade into layers below
(i.e. setting the initial water depth 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. For
more information see Section 8.9.2
.

Appendix C TGC Commands - 49 / 88 Page 913 / 1094

 Command Solver Description

Note, multiple soil layers in the

vertical are only supported using
TUFLOW HPC.

Appendix C TGC Commands - 50 / 88 Page 914 / 1094

 Command Solver Description

@3406Grid IGW Level [{} |

Read ⟨ Layer N ⟩ ] == Classic and Sets the initial water level in the Nth
[ ⟨ grid_file ⟩ ] HPC subsurface layer in meters or feet
based on the input grid. If Read Grid
IGW Depth Layer N is used with the
Read Grid IGW Level Layer N the
highest initial condition will be
adopted. If using multiple soil layers
(see Section 7.4.5.2 ), 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.

Note, multiple soil layers in the

vertical are only supported using
TUFLOW HPC.

Appendix C TGC Commands - 51 / 88 Page 915 / 1094

 Command Solver Description

@3411Grid IWL ==
Read Classic and Sets the initial water level (see
[ ⟨ grid_file ⟩ ] HPC Section 8.9.1 ) based on the input
grid.

Note: IWLs can also be set in the .tcf

file (see Set IWL ). This is
preferable if the initial water levels
vary from simulation to simulation as
it removes the necessity to create a
new .tgc file each time the initial
water levels change. Any IWL values
set in the .tcf file override those
specified in the .tgc file for the same
cells.

@3414Grid Location ==
Read Classic and Sets the size and location of a 2D
[ ⟨ grid_file ⟩ ] HPC domain based on the input grid. The
dimensions of the grid is used to set
the 2D domain’s origin and X,Y
dimensions (i.e. replaces Origin and
Grid Size (X,Y) or Read GIS
Location . The orientation angle is
set to zero (i.e. the 2D domain will be
orientated north-south). Useful where
the model extent is the same as the
DEM. Cell Size still needs to be
specified and can be different to the
DEM’s cell size.

For more information see Section

7.3.1 .

Appendix C TGC Commands - 52 / 88 Page 916 / 1094

 Command Solver Description

@3417Grid Mat ==
Read Classic and Material ID (see Section 7.3.6 ).
[ ⟨ grid_file ⟩ ] HPC The Material ID value must
correspond to a value within the
Materials Definition File Read
Materials File . If Bed
Resistance Cell Sides ==
INTERROGATE (the default), the
material values are directly sampled
at the cell mid-sides. This gives a
higher resolution definition of the
materials data, thereby giving
improved flow patterns where
Manning’s n values vary significantly
such as in an urban environment.

@3420Grid Soil
Read [{} | ⟨ Layer N ⟩ ] == Classic and Sets the soil ID (see Section 7.3.7 )
[ ⟨ grid_file ⟩ ] HPC based on the input grid. The Soil ID
value must correspond to a value
within the .tsoilf file. (refer to Read
Soils File ). Multiple soil layers are
supported when using TUFLOW
HPC (see Section 7.4.5.2 ). The
layer(s) that this command applies to
can be optionally defined using Set
Soil Layer <N[,N2,N3…]> ==
<value>. In the absence of a layer
definition the command applies to
layer 1.

Appendix C TGC Commands - 53 / 88 Page 917 / 1094

 Command Solver Description

@3425Grid Soil Base Elevation

Read [{} | ⟨ Layer N ⟩ ] == Classic and Sets the base elevation of the Nth
[ ⟨ grid_file ⟩ ] HPC subsurface layer in meters or feet
based on the input grid. Note,
multiple soil layers are only
supported when using TUFLOW
HPC (see Section 7.4.5.2 ). If the
Soil Thickness or Base Elevation
is not set for a given layer, it is
assumed to be infinite. If both
methods are specified for a given
cell the highest of the two will be
adopted. For more information see
Section 7.3.7.1 .

@3430Grid Soil Thickness

Read [{} | ⟨ Layer N ⟩ ] == Classic and Sets the thickness in the vertical of
[ ⟨ grid_file ⟩ ] HPC the Nth subsurface layer in meters or
feet based on the input grid layer.
Note, multiple soil layers are only
supported when using TUFLOW
HPC (see Section 7.4.5.2 ). The
thickness is set from the layer above.
If the Soil Thickness or Base
Elevation is not set for a given
layer, it is assumed to be infinite. If
both methods are specified for a
given cell the highest of the two will
be adopted. For more information
see Section 7.3.7.1 .

Appendix C TGC Commands - 54 / 88 Page 918 / 1094

 Command Solver Description

@3435Grid SRF ==
Read Classic and Sets the storage reduction factor
[ ⟨ grid_file ⟩ ] HPC from the input raster grid. The
storage of 2D cells may be reduced
(for example to model hypothetical
filling, or reduced storage from
buildings), or increased. For
example, if a cell has a Storage
Reduction Factor (SRF) value of 0.1,
then its storage (surface area) is
reduced by 10%. If the SRF value is
less than zero, the storage is
increased. The default SRF value is
zero (i.e. no change in storage). For
more information see Section 7.3.9.1
.

@3438Grid WrF ==
Read Classic and Applies the WrF value to all cell
[ ⟨ grid_file ⟩ ] HPC faces based on the input grid. The
global value Global Weir Factor and
the spatially varying value are
multiplied together (i.e. one does not
replace the other).

Appendix C TGC Commands - 55 / 88 Page 919 / 1094

 Command Solver Description

@3441Grid Zpts [ {} | ADD | MAX | MIN ] [ {XF ON} |

Read Classic and Directly interrogates an input grid to
XF OFF ] == HPC set the Zpt elevations. See Section
[ ⟨ grid_file ⟩ | ⟨ gis_layer ⟩ ] 7.3.5 .

The use of this command has

significant advantages over the
previous method of manually
carrying out a point inspection on an
empty 2d_zpt layer. It will allow for
the model to (very likely) become cell
size independent. Changing a 2D
domain’s orientation and dimensions
is also much simpler without the
need to regenerate and point inspect
a 2d_zpt layer. See Section for more
details.

The ADD option adds the value

interrogated from the grid to the
Zpts. Use a negative value to
subtract.

The MAX option will only raise a Zpt

from its existing value, while the MIN
option will only lower the Zpt value
from its existing value.

The XF ON and XF OFF options can

be used to switch the writing of XF
files (see Section ) on or off for
individual inputs.

Appendix C TGC Commands - 56 / 88 Page 920 / 1094

 Command Solver Description

This command permits a second

argument, specifying a GIS layer
containing one or more polygons to
clip the area of Zpts to be inspected.
Elevations will only be assigned to
Zpts lying inside polygons within the
GIS layer. See Section for more
details.

Like other .tgc commands, Read

Grid Zpts may be specified more
than once. You can also specify
ADD, MIN or MAX in the same way
as for other similar commands.

See also the .tgc command Grid

Approach .

Appendix C TGC Commands - 57 / 88 Page 921 / 1094

 Command Solver Description

@3446RowCol
Read ⟨ option⟩ == Classic and Legacy command:
[ ⟨ mid_file ⟩ ] HPC
This is a legacy command. It is
suggested to use the corresponding
“Read GIS ⟨ option ⟩” or “Read Grid
⟨ option ⟩” command instead.

Reads the code, material, IWL, CnM,

fric, WrF or FLC values from a .mid
or similarly formatted (comma
delimited) file. The first three
columns in the file must be “n, m, ⟨

value ⟩”, where n and m are the 2D

grid row, column and ⟨ value ⟩ is the
value of the ⟨ option ⟩ as listed the
2018 TUFLOW Manual.

This command is not supported

when using the TUFLOW HPC
Quadtree functionality.

Appendix C TGC Commands - 58 / 88 Page 922 / 1094

 Command Solver Description

@3461RowCol WrF ==
Read Classic and Legacy command:
[ ⟨ mid_file ⟩ ] HPC
This is a legacy command. It is
suggested to use Read GIS WrF or
Read Grid WrF command instead.

Reads the weir factor from a .mid or

similarly formatted (comma
delimited) file. The first three
columns in the file must be “n, m, ”,
where n and m are the 2D grid row,
column and is the weir factor value.
The global value Global Weir Factor
and the spatially varying value are
multiplied together (i.e. one does not
replace the other).

This command is not supported

when using the TUFLOW HPC
Quadtree functionality.

Appendix C TGC Commands - 59 / 88 Page 923 / 1094

 Command Solver Description

@3464RowCol Zpts [ {} | ADD | MAX | MIN ] [ XF ON |

Read Classic and Legacy command:
XF OFF ] == HPC
This is a legacy command. It is
[ ⟨ zpt_file ⟩ ]
suggested to use the Read GIS Zpts
or Read Grid Zpts command
instead.

Reads in Zpt elevation data. The

.mid file must be the same format as
that produced by the Write GIS Zpts
command.

The ADD option adds the Zpt value

to the current Zpt value.

The MAX and MIN options only

modify the current Zpt value if the
value is higher (MAX option) or lower
(MIN option) than the existing value.

The GIS layer can be trimmed to

contain either only H values or only
U and V values to minimise the size
of the file. In this case use an
“Interpolate” command to interpolate
other Z values (e.g. Interpolate ZUV
).

XF ON and XF OFF switch the

automatic generation of XF files ON
or OFF specifically for ⟨ zpt_file ⟩.
The global default for using XF files
is ON and can be changed using XF
Files .

Appendix C TGC Commands - 60 / 88 Page 924 / 1094

 Command Solver Description

This command is not supported

when using the TUFLOW HPC
Quadtree functionality.

Appendix C TGC Commands - 61 / 88 Page 925 / 1094

 Command Solver Description

@3469TIN Zpts [ {} | ADD | MAX | MIN ] [ {XF ON} |

Read Classic and Use to read a triangulation file (TIN)
XF OFF == HPC to assign elevation values to Zpts.
[ ⟨ tin_file ⟩ | ⟨ gis_layer ⟩ ] See Section 7.3.5 . The following is
a list of accepted TINs. The type of
TIN is determined by the file
extension:

SMS .tin files

SMS .2dm files. This may be
useful for quickly setting up a
TUFLOW model based on a
flexible mesh model that uses a
.2dm file.
12D TINs as a .12da file in ANSI
format.
.xml TINs that are readily
exported from 3D surface TIN
software such as Autodesk’s
Civil3D. The format should be
LandXML saved with line
endings. The format with line
endings may be referred to as
“Pretty Print” format.

ADD adds the TIN value to the Zpt

elevations.

MAX only changes the value of a Zpt

if the TIN value is greater than the
current Zpt value.

Appendix C TGC Commands - 62 / 88 Page 926 / 1094

 Command Solver Description

MIN only changes the value of a Zpt

if the TIN value is less than the
current Zpt value.

Also see Create TIN Zpts to have

TUFLOW create and write out a TIN.

This command permits a second

argument, specifying a GIS layer
containing one or more polygons to
clip the area of Zpts to be inspected.
Elevations will only be assigned to
Zpts lying inside polygons within the
GIS layer. See Section for more
details.

By default, an XF file of the Zpts

assigned an elevation from a Read
TIN Zpts command is created so
that loading up the Zpts is pretty well
instantaneous for subsequent runs
using that TIN. If the TIN is updated,
TUFLOW will automatically resample
the Zpts and create a new XF file.

The XF file can be switched on or off

from the global default settings using
XF Files or specifically for this layer
using “Read TIN Zpts XF OFF ==
…”.

Appendix C TGC Commands - 63 / 88 Page 927 / 1094

 Command Solver Description

@3474
Set CnM == Classic Only Global bed resistance value. CnM is
[ ⟨ value ⟩ ] a Chezy C, Manning’s n or
Manning’s M value as set by Bed
Resistance Values . See Section
7.5.3 .

Appendix C TGC Commands - 64 / 88 Page 928 / 1094

 Command Solver Description

@3477
Set Code [ {} | ZERO ABOVE ZC ] == Classic and Used to globally set the 2D cell code.
[ ⟨ ZC ⟩ ] HPC See Section 7.3.2 for more
information.

The Cell code options are:

0: Inactive cells (e.g. land or

redundant cells);
1: Active cells (e.g. water);
2: Boundary cells (e.g. active
cells with an external boundary);
-1: Inactive cells within the
active domain.

Any values great than 2 will be

treated as active cells (cell code of
1). Any values less than -1 will be
treated as inactive cells (cell code of
0).

The ZERO ABOVE ZC option for Set

Code applies a Code value of zero
(0) to all cells that have a ZC value
greater than the ⟨ZC⟩ value specified
for this command. For example, “Set
Code Zero Above ZC == 50.”
applies a Code 0 (inactive) to all 2D
cells in the domain that have a ZC
value above 50 (this includes any
unassigned ZC values, as the default
value is 99999. Also, if any ZU, ZV or
ZH points on that cell have not yet
been assigned an elevation by any

Appendix C TGC Commands - 65 / 88 Page 929 / 1094

 Command Solver Description

previous Zpt commands, they are set

to the ZC value of a cell they are
attached to, thereby removing any
99999 elevations around the edge of
the model. As this option is
dependent on the Zpt values, the
location of this command relative to
the Zpt commands within the .tgc file
is important. It should occur after the
Zpts have been assigned elevations.
You may also not want to use the Set
Zpt command so that the automatic
trimming of ZU, ZV and ZH points
occurs. This command is very useful
for setting the active area for direct
rainfall models where the DEM has
been trimmed to the catchment
boundary.

Appendix C TGC Commands - 66 / 88 Page 930 / 1094

 Command Solver Description

@3482
Set Code and Clean Zpt == Classic and Assigns cells as active (Code 1) or
[ ⟨ Z_inactive ⟩ ] HPC inactive (Code 0) (see Section 7.3.2
) based on whether the cell has
been assigned an elevation or not.
Also extrapolates Z values to any
unassigned Zpt values in cells
assigned as active. The value of ⟨

Z_inactive ⟩ is used to assign an

elevation to unassigned Zpts. This
command negates the need to
digitise active/inactive code polygons
where:

1. The DEM used to assign

elevations has been trimmed to
the catchment boundary or
model extent (i.e. all null areas
of the DEM will be assigned an
inactive code as these Zpts have
not been assigned an elevation);
or
2. Reading a .2dm file from another
model to assign elevations (refer
to the command Read TIN Zpt
).

Note: This command must occur

after the Zpts have been assigned
their elevations from the DEM or
2dm file. Do not use the Set Zpt
command as this assigns every Zpt a

Appendix C TGC Commands - 67 / 88 Page 931 / 1094

 Command Solver Description

value, and therefore all Zpts have

been assigned a value and this
command will not work.

This command is not supported

when using the TUFLOW HPC
Quadtree (Section 7.4.1 or SGS
(Section 7.4.3 ) functionality.

@3487
Set CWF == Classic and Globally sets the cell flow width (see
[ ⟨ value ⟩ ] HPC Section 7.3.9.2 ). The value entered
for CWF is a factor to adjust the 2D
cell flow widths (in the same manner
as 2D flow constrictions (2d_fc)),
noting that the changed flow width
applies to all depths. For example
0.1 will limit the flow width to 10%.

@3490
Set FLC == Classic and Globally applies a form loss to all
[ ⟨ value ⟩ ] HPC cells. See Section 7.3.9.3 .

Note, FLC values will need to be

changed if the 2D cell size changes.

@3493
Set FLC/L == Classic and Globally applies a form loss per unit
[ ⟨ value ⟩ ] HPC length to all cells. The effect of
applying the FLC in this manner is
2D cell size independent. See
Section 7.3.9.3 .

@3496
Set FRIC == Classic Only Global ripple height command. See
[ ⟨ value ⟩ ] Section 7.5.3 .

Appendix C TGC Commands - 68 / 88 Page 932 / 1094

 Command Solver Description

@3499
Set GWD == Classic and Legacy command:
[ ⟨ value ⟩ ] HPC
Used to set global groundwater
depth (see Section 7.3.7.1 ). The
default is for the GWD/GWL to be
infinitely deep. If a cell has both a
GWD and GWL specified, the higher
of the two (elevation wise) prevails.
This can be checked by viewing the
Map Output Data Type dGW, which
shows the depth to groundwater
(from the ground surface) in metres
or feet. The Set GWD command
may only be specified following Set
Soil , Read GIS Soil and/or Read
Grid Soil commands.

Appendix C TGC Commands - 69 / 88 Page 933 / 1094

 Command Solver Description

@3502
Set GWL == Classic and Legacy command:
[ ⟨ value ⟩ ] HPC
Used to set global groundwater level
(see Section 7.3.7.1 ). The default
is for the GWD/GWL to be infinitely
deep. If a cell has both a GWD and
GWL specified, the higher of the two
(elevation wise) prevails. This can be
checked by viewing the Map Output
Data Type dGW, which shows the
depth to groundwater (from the
ground surface) in metres or feet.
The Set GWL command may only
be specified following Set Soil ,
Read GIS Soil and/or Read GRID
Soil commands.

Appendix C TGC Commands - 70 / 88 Page 934 / 1094

 Command Solver Description

@3505
Set IGW Conc Layer N1,N2,..N Tracer M1,M2,..M == HPC Only Globally sets the initial concentration
[ ⟨ value ⟩ | ⟨ file_path ⟩ ] of one or more tracers in one or
more groundwater layers of the
model. Where N1,N2,..N are the
groundwater layer numbers and
M1,M2,..M are the tracer numbers. If
a layer number is not referenced, it is
assumed to apply to layer 1.
Likewise, if a tracer number is not
referenced it is assumed to apply to
the first tracer. For more information,
see Section 9.5.6 .

Note, the order that ‘Layer’ and

‘Tracer’ appear in the command does
not matter (i.e. tracer numbers could
be listed before layer numbers).

Appendix C TGC Commands - 71 / 88 Page 935 / 1094

 Command Solver Description

@3510
Set IGW Depth [{} | ⟨ Layer N ⟩ ] == HPC Only Globally sets the initial water depth
[ ⟨ value ⟩ | ⟨ file_path ⟩ ] in the Nth subsurface layer in meters
or feet. Assumed to be the depth of
water in the soil (water content
divided by porosity). If Set IGW
Depth Layer N is used with the Set
IGW Level Layer N the highest
initial condition will be adopted. If
using multiple soil layers (see
Section 7.4.5.2 ), the initial
conditions do not automatically
cascade into layers below
(i.e. setting the initial water depth 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. For
more information see Section 8.9.2
.

Appendix C TGC Commands - 72 / 88 Page 936 / 1094

 Command Solver Description

Note, multiple soil layers in the

vertical are only supported using
TUFLOW HPC.

Appendix C TGC Commands - 73 / 88 Page 937 / 1094

 Command Solver Description

@3517
Set IGW Level [{} | ⟨ Layer N ⟩ ] == HPC Only Globally sets the initial water level in
[ ⟨ value ⟩ | ⟨ file_path ⟩ ] the Nth subsurface layer in meters or
feet. If Set IGW Depth Layer N is
used with the Set IGW Level Layer N
the highest initial condition will be
adopted. If using multiple soil layers
(see Section 7.4.5.2 ), 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.

Note, multiple soil layers in the

vertical are only supported using
TUFLOW HPC.

Appendix C TGC Commands - 74 / 88 Page 938 / 1094

 Command Solver Description

@3524
Set IWL == Classic and Globally sets initial water level (see
[ ⟨ value ⟩ ] HPC Section 8.9.1 ).

Note: IWLs can also be set in the .tcf

file (see Set IWL ). This is
preferable if the initial water levels
vary from simulation to simulation as
it removes the necessity to create a
new .tgc file each time the initial
water levels change. Any IWL values
set in the .tcf file override those
specified in the .tgc file for the same
cells.

@3527
Set Mat == Classic and Globally sets Material ID (see
[ ⟨ value ⟩ ] HPC Section 7.3.6 ). The Material ID
value must correspond to a value
within the Materials Definition File
Read Materials File . If Bed
Resistance Cell Sides ==
INTERROGATE (the default), the
material values are directly sampled
at the cell mid-sides. This gives a
higher resolution definition of the
materials data, thereby giving
improved flow patterns where
Manning’s n values vary significantly
such as in an urban environment.

Appendix C TGC Commands - 75 / 88 Page 939 / 1094

 Command Solver Description

@3530
Set Route Cut Off Type == Classic Globally sets the cutoff value type for
[ {Depth} | Velocity or V | Hazard or VxD or Z0 | evacuation routes if the
Energy ] Cut_Off_Type attribute in the Read
GIS Z Shape Route layer is blank.
Depth, velocity and hazard options
are available. The cutoff values are
set using Set Route Cut Off Values
in the .tcf and/or .tgc file, and
evacuation routes are described in
Section 11.4.2 and set using the
.tgc file command Read GIS Z
Shape Route .

This command may be used in either

the .tcf and/or .tgc file. If used in the
.tcf it is the global default setting
when the .tgc file is processed. If
used in the .tgc file its location in the
file is important in that it only applies
to subsequent evacuation route
commands. It may be used any
number of times in the .tgc file so as
to change the evacuation route
settings at different points within the
.tgc file.

Appendix C TGC Commands - 76 / 88 Page 940 / 1094

 Command Solver Description

@3531
Set Route Cut Off Values == Classic Globally sets the cutoff values for the
[ ⟨ y1, y2, … ⟩ ] evacuation route feature (see
Section 11.4.2 ) if the
Cut_Off_Values attribute in the Read
GIS Z Shape Route layer is blank.
The type of cutoff values is set using
Set Route Cut Off Type and
evacuation routes are set using the
.tgc file command Read GIS Z
Shape Route .

This command may be used in either

the .tcf and/or .tgc file. If used in the
.tcf it is the global default setting
when the .tgc file is processed. If
used in the .tgc file its location in the
file is important in that it only applies
to subsequent evacuation route
commands. It may be used any
number of times in the .tgc file so as
to change the evacuation route
settings at different points within the
.tgc file.

Appendix C TGC Commands - 77 / 88 Page 941 / 1094

 Command Solver Description

@3534
Set Soil [{} | ⟨ Layer N ⟩ ] == Classic and Globally sets Soil ID (see Section
[ ⟨ value ⟩ ] HPC 7.3.7 ). The Soil ID value must
correspond to a value within the
.tsoilf file (refer to Read Soils File ).
Multiple soil layers are supported
when using TUFLOW HPC (see
Section 7.4.5.2 ). The layer(s) that
this command applies to can be
optionally defined using Set Soil
Layer <N[,N2,N3…]> ==
<value>. In the absence of a layer
definition the command applies to
layer 1.

@3539
Set Soil Base Elevation [{} | ⟨ Layer N ⟩ ] == Classic and Globally sets the base elevation of
[ ⟨ value ⟩ | ⟨ file_path ⟩ ] HPC the Nth subsurface layer in meters or
feet. Note, multiple soil layers are
only supported when using TUFLOW
HPC (see Section 7.4.5.2 ). If the
Soil Thickness or Base Elevation
is not set for a given layer, it is
assumed to be infinite. If both
methods are specified for a given
cell the highest of the two will be
adopted. For more information see
Section 7.3.7.1 .

Appendix C TGC Commands - 78 / 88 Page 942 / 1094

 Command Solver Description

@3546
Set Soil Thickness [{} | ⟨ Layer N ⟩ ] == Classic and Globally sets the thickness in the
[ ⟨ value ⟩ | ⟨ file_path ⟩ ] HPC vertical of the Nth subsurface layer in
meters or feet. Note, multiple soil
layers are only supported when
using TUFLOW HPC (see Section
7.4.5.2 ). The thickness is set from
the layer above. If the Soil Thickness
or Base Elevation is not set for a
given layer, it is assumed to be
infinite. If both methods are specified
for a given cell the highest of the two
will be adopted. For more information
see Section 7.3.7.1 .

@3553
Set SRF == Classic and Globally sets the storage reduction
[ ⟨ value ⟩ ] HPC factor. The storage of 2D cells may
be reduced (for example to model
hypothetical filling, or reduced
storage from buildings), or
increased. For example, if a cell has
a Storage Reduction Factor (SRF)
value of 0.1, then its storage (surface
area) is reduced by 10%. If the SRF
value is less than zero, the storage is
increased. The default SRF value is
zero (i.e. no change in storage). For
more information see Section 7.3.9.1
.

@3556
Set Variable ⟨ name⟩ == Classic and Define user variables for use within
[ ⟨ value⟩ ] HPC the control files, see Set Variable
and Section 13.3.3 .

Appendix C TGC Commands - 79 / 88 Page 943 / 1094

 Command Solver Description

@3561
Set WrF == Classic and Globally applies the same WrF value
[ ⟨ WrF value ⟩ ] HPC to all cell faces. The global value
Global Weir Factor and the spatially
varying value are multiplied together
(i.e. one does not replace the other).

@3564
Set Zpt == Classic and Globally sets all ZC, ZU, ZV and ZH
[ ⟨ elevation_in_metres ⟩ ] HPC Zpts to the value specified. This is
typically used to set a global
elevation for active cells before
reading in a DEM (using Read Grid
Zpts ). Reviewing the _DEM_Z
check file and searching for the
global value used is an easy way to
identify if there are any gaps in the
DEM dataset that were not expected
(these should be fixed).

Appendix C TGC Commands - 80 / 88 Page 944 / 1094

 Command Solver Description

@3567
SGS [ Grid | TIN ] Sample Distance == HPC Only Legacy command:
[ ⟨ distance in metres / feet ⟩ ]
Available when using SGS (Method
B) only (Section 7.4.3 ).

Sets the sample distance to be used

for both input grid and TIN files.

For grid inputs, if no sample distance

has been set the resolution of the
DEM is used by default. For TIN
datasets, the sample distance must
be set. The sample ‘frequency’ set by
this command is capped at 31 by
default to avoid to avoid long pre-
processing time. In general, a
sample frequency smaller than 31 is
sufficient for most of natural water
ways or artificial structures, and
users may not benefit from applying
a super fine sample distance against
the model cell size. This upper limit
can be increased by using a second
argument in the “SGS Sample
Distance” command, e.g. “SGS
Sample Distance == 1 | 51”
sets the sampling distance to 1 m
and the frequency limit to 51 sample
points per face (2601 per cell).
However, a hard limit of 127 per face
(16,129 per cell) still applies.

Appendix C TGC Commands - 81 / 88 Page 945 / 1094

 Command Solver Description

@3570
SGS Grid Max Null Frac == HPC Only Legacy command:
[ Maximum Null Fraction | ⟨ 0.5 ⟩ ]
Available when using SGS (Method
B) only (see SGS Approach ==
Method B). This command controls
the behaviour if the input grid only
has partial coverage and the existing
elevation in the cell has not been
initialised either with a Set Zpt
command or with an elevation in a
previous dataset. If the fraction of the
cell that has no value (null) in the
input grid is above this value then
the zpt is not updated.

@3573
SGS Partial Grid Update Null Frac == HPC Only Legacy command:
[ Lower Limit, Upper limit | ⟨ 0.1, 0.9 ⟩ ]
Available when using SGS (Method
B) only (see SGS Approach ==
Method B). This command controls
the behaviour if the input grid only
has partial coverage and the cell has
been initialised either with a Set Zpt
command or with an elevation in a
previous dataset. This sets lower and
upper limits for the fraction of the
SGS values that can be null in the
grid. This applies to both cells and
cell faces. The default values for the
lower limit is 0.1 and for the upper
limit 0.9.

Appendix C TGC Commands - 82 / 88 Page 946 / 1094

 Command Solver Description

@3576
SGS ZH Sample Ratio == HPC Only SGS Only.
[ ⟨ ratio ⟩ | {1} ]
Used to control the area used for
SGS at ZH locations. The area is set
to ⟨ratio⟩ × cell_area to sample
and generate Z values around a cell
corner (the sampled elevations are
not used in the hydraulic
computations, only for map output).
The default setting for this command
is 1.0. The corner elevations are also
used to enable the _DEM_Zmin
check file to be written. See Section
7.4.3.2.2 .

@3580
Spatial Database == Classic and Optional when using the
[ OFF | TCF ] HPC GeoPackage input format. Sets the
database to use for subsequent
inputs. For more information see
Section 4.4.3 .

@3581
Stop Classic and Legacy command:
HPC

@3582Line as Thick ==
Thin Classic and Legacy command:
[ ON | {OFF} ] HPC

Appendix C TGC Commands - 83 / 88 Page 947 / 1094

 Command Solver Description

@3583
TIN Angles == Classic and Provides the user with the ability to
[ ⟨ point_angle ⟩ , ⟨ edge_angle ⟩ | {55, 30} ] HPC vary the formation of triangles in
TINs created from Read GIS Z
Shape polygons. See Section
7.3.5.4 .

⟨ point_angle ⟩ controls the minimum

angle from an internal point to two
vertices on the triangulation
perimeter to be used. The smaller
the angle the greater the priority
given to triangulating to an internal
point.

⟨ edge_angle ⟩ controls the

formation of triangles from vertices
along internal boundary of the TIN as
it is created. The greater the angle
the greater the priority given to
triangulating using boundary vertices
only.

The command maybe repeated

within the .tgc file to change the
angles for different commands.

Appendix C TGC Commands - 84 / 88 Page 948 / 1094

 Command Solver Description

@3592
TIN Coincident Point Distance == Classic and Changes the distance used for
[ ⟨ dist_in_m ⟩ | {0.001} ] HPC removing coincident points prior to
creating a TIN. Can be used several
times within the .tgc file to apply
different distances for different
layers/commands. Applies to any
polygon shape or command that
generates a TIN. See Section 7.3.5.4
.

@3595 GIS Domain ==

Write Classic and Creates _dom GIS (e.g. .shp) file
[ ⟨ gis_layer ⟩ ] HPC containing a rectangular region
representing the extent of the 2D
domain. Useful for cross-checking
the 2D domain’s extent in the GIS
rather than generating a large
_grd_check file using Write GIS Grid
.

A _dom_check layer is also created

using Write Check Files , however,
it will contain a rectangular region for
all 2D domains.

Appendix C TGC Commands - 85 / 88 Page 949 / 1094

 Command Solver Description

@3598 GIS Grid ==

Write Classic and Creates a GIS file (e.g. .shp)
[ ⟨ gis_layer ⟩ ] HPC representing the 2D domain’s grid
based on the dimensions, origin and
orientation. The grid is a mesh of
square polygons.

All information relating to grid cells

as defined by any previous
commands up until that point within
the .tgc file is included. The output
layer has the same attributes as a
_grd_check layer.

Tip: Use this command to check that

the grid’s data (code, material, etc.)
is setup correctly by writing to
temporary GIS file (e.g. .shp), and
importing and viewing in the GIS at
different stages in the .tgc file (this
command can be used any number
of times within a .tgc file – remember
to specify a different filename each
time though!).

A _grd_check layer is also created

using Write Check Files , however,
it will contain the active cells of all 2D
domains.

Appendix C TGC Commands - 86 / 88 Page 950 / 1094

 Command Solver Description

@3601 GIS Zpts ==

Write Classic and Writes a GIS file (e.g. .shp)
[ ⟨ gis_layer ⟩ ] HPC containing the points where Zpts
(model elevation) values are defined.

Tip: Use this command to check that

the model’s elevation data is correct.
After building the topography use
this command to write a temporary
GIS file (e.g. .shp). Import into the
GIS and check the elevations are as
expected.

@3604
ZC == Classic and Sets the ZC Zpt equal to the
[ MIN(ZU,ZV) ] HPC minimum of the two ZU and two ZV
Zpts either side and above and
below it.

This essentially allows a grid cell to

wet and dry according to when water
first enters and last leaves the cell. It
may provide enhanced stability in
models with severe wetting and
drying.

Appendix C TGC Commands - 87 / 88 Page 951 / 1094

 Command Solver Description

@3605Z Point ==
Zero Classic and If set to ERROR, causes an ERROR
[ {ERROR} | WARNING ] HPC 2049 message if a snapped point to
a Z Line, or inside or on the
perimeter of a Shape region has a
zero value.
If set to WARNING, a warning
message is issued and the
simulation does not stop.
If the ADD option is used, no
ERRORs or WARNINGs are issued
except in the case of points snapped
to TIN lines.

Appendix C TGC Commands - 88 / 88 Page 952 / 1094

 @3613

@3614
Appendix D TBC Commands

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

BC Database Global Rainfall BC Read GIS SA

BC Event Name Global Rainfall Continuing Loss Read GIS Streams
BC Event Text Global Rainfall Initial Loss Read RowCol RF
Blank BC Type If Scenario Set Variable
Blank HQ Slope Read GIS BC Spatial Database
Global Rainfall Area Factor Read GIS RF Unused HX and SX Connections

Appendix D TBC Commands - 1 / 12 Page 953 / 1094

 @3615
@3619 Table D.1: TUFLOW Classic/HPC TBC Commands

Command Solver Description

@3618
@3620
BC Database == Classic Sets the active BC Database file as described in Section 8.6
[ ⟨ .csv_file ⟩ ] and HPC . The file is usually created using spreadsheet software
such as Microsoft Excel.

If the BC Database is specified in the TUFLOW .tcf file, it is

set as the active database for both 2D and 1D models.
However, the active database can be changed at any stage
in the .tbc and .ecf files by repeating the command with the
new database set as the ⟨ .csv_file ⟩.

A BC Database must be specified before any of the

other BC commands are used.

Appendix D TBC Commands - 2 / 12 Page 954 / 1094

 Command Solver Description

@3625
BC Event Name == Classic Sets the active BC name to be substituted where ⟨

[ ⟨ bc_event_name ⟩ ] and HPC bc_event_text ⟩ (see BC Event Text ) occurs in the BC

Database. See Section 8.6.2 for a description of how the
BC event commands operate.

This command is normally specified in the .tcf file, and only

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

BC Event Name == H010

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

This command has been superseded by the .tcf BC

Event Source command. It combines the functionality
of BC Event Name and BC Event Text into a single
command.

Appendix D TBC Commands - 3 / 12 Page 955 / 1094

 Command Solver Description

@3630
BC Event Text == Classic Sets the text in the BC Database that is to be substituted by
[ ⟨ bc_event_text ⟩ ] and HPC the BC Event Name command value. See Section 8.6.2
for a description of how the BC event commands operate.

This command is normally specified in the .tcf file, and only

used in the .tbc file if for some reason the ⟨ bc_event_text ⟩

value needs to change (this should be very unlikely unless

wanting to split the different boundaries into groups). Also
see BC Event Text for the .tcf file.

This command has been superseded by the .tcf BC

Event Source command. It combines the functionality
of BC Event Name and BC Event Text into a single
command.

@3635 BC Type ==
Blank Classic If a blank BC type occurs the value entered is used. If
[ ⟨ bc_type ⟩ | {NONE} ] and HPC NONE (the default) is specified, a BC type must be
assigned to every object in 2d_bc layers.

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

the example lines below.

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

Appendix D TBC Commands - 4 / 12 Page 956 / 1094

 Command Solver Description

@3638 HQ Slope ==
Blank Classic A default HQ slope can be specified directly in the .tbc, and
[ ⟨ slope ⟩ ] and HPC can be repeated prior to reading different HQ boundaries (in
separate layers). Note, ⟨ slope ⟩ will only be used if no
boundary name is specified for the 2d_bc HQ boundary (as
a specified for the HQ boundary slope is given preference
over the name).

@3643 Rainfall Area Factor ==

Global Classic Sets the factor applied to the global rainfall after the initial
[ {1.0} | ⟨ area_factor ⟩ ] and HPC loss and continuing losses have been applied. This is useful
if you wish to increase the rainfall within the area covered
by the active (Code 1) cells to compensate for areas that
contribute to the runoff that out not included in the active
model area

Appendix D TBC Commands - 5 / 12 Page 957 / 1094

 Command Solver Description

@3646 Rainfall BC ==
Global Classic Sets the BC name in the BC database that defines the
[ ⟨ BC_name ⟩ ] and HPC global rainfall. Using metric units (default), the rainfall is
specified as mm versus time in hours. This is converted to
m3/s and applied as a source versus time (ST). Using
Units == US Customary, the units are inches verses
time. TUFLOW converts it to ft3/s

This command applies rainfall to all active cells. Therefore,

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

If used in conjunction with the commands Global Rainfall

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

Global Rainfall Initial Loss == 10

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

Note rainfall losses in the materials files are not applied to

global rainfall boundaries.

See also the command Global Rainfall Area Factor .

@3649 Rainfall Continuing Loss ==

Global Classic Sets the continuing loss rate for any global rainfall (note
[ {0} | ⟨ CL ⟩ ] and HPC does not apply to rainfall via Read GIS RF or Rainfall
Control File ). Using metric units (default) the rate is mm/h.
Using Units == US Customary, the rate is inch/h.

This command must occur prior to the command Global

Rainfall BC else no losses will be applied.

Appendix D TBC Commands - 6 / 12 Page 958 / 1094

 Command Solver Description

@3652 Rainfall Initial Loss ==

Global Classic Sets the initial loss rate for any global rainfall (note does not
[ {0} | ⟨ IL ⟩ ] and HPC apply to rainfall via Read GIS RF or Rainfall Control File ).
Using metric units (default) the value is in mm. Using Units
== US Customary, the value is in inches.

This command must occur prior to the command Global

Rainfall BC else no losses will be applied.

@3655
If Scenario Classic Controls which commands to process for different scenarios
and HPC as specified using the –s run option (see Section 13.3.2
and Table 13.2 ) or Model Scenarios .

@3656GIS BC ==
Read Classic Reads the location and attributes of 2D model boundary
[ ⟨ gis_layer ⟩ ] and HPC conditions as described in Section 8.5.1 . Uses 2d_bc GIS
layers, as described in Table 8.6 .

@3659GIS RF ==
Read Classic Reads the polygons for applying rainfall directly to 2D cells,
[ ⟨ gis_layer ⟩ ] and HPC as described by RF in Table 8.5 . Uses 2d_rf GIS layers,
as described in Table 8.12 .

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

.tcf command Read Grid RF .

Negative rainfall values when using Read GIS RF are

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

Appendix D TBC Commands - 7 / 12 Page 959 / 1094

 Command Solver Description

@3662GIS SA [ {} |
Read ⟨ option⟩ ] == Classic Available ⟨option⟩ are: “ALL”, “PITS”, “STREAM ONLY”,
[ ⟨ gis_layer ⟩ ] and HPC “STREAM IGNORE”, “RF”, “PO” and “TRIGGER”.

Reads the polygons for distributing source flows over the 2D

domain(s) as described in Section 8.5.2 . Usually used for
specifying rainfall runoff (flow) directly onto the 2D
domain(s).

The “ALL” option is available to apply the flow or rainfall to

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

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

Two options are available for controlling streamlines (refer

to Read GIS Streams ), as described in Section 8.5.2.1.1
:

The “STREAM ONLY” option will only apply the SA

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

Appendix D TBC Commands - 8 / 12 Page 960 / 1094

 Command Solver Description

the inflows using the standard approach for SA inflows

(i.e. lowest cell if all wet, otherwise distributed over the
wet cells).

The “RF” (rainfall) option is available to specify rainfall

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

The “TRIGGER” option allows the initiation of inflow

hydrographs based on a flow or water level trigger so that,
for example, reservoir failures can be initiated based on
when the flood wave reaches the reservoir rather than at a
fixed time. See Section 8.5.2.3 for more details.

The “PO” option models seepage or infiltration based on a

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

Appendix D TBC Commands - 9 / 12 Page 961 / 1094

 Command Solver Description

@3669GIS Streams ==
Read Classic Streamlines, as described in Section 8.5.2.1.1 , allow the
[ ⟨ gis_layer ⟩ ] and HPC user to apply SA inflows along the waterways rather than to
the lowest cell (when all cells are dry within the SA region).

The Read GIS Streams command can be used one or

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

Point and region objects are also recognised, for a point

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

Note only streams with a stream order greater than zero

(0) are used by TUFLOW. 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.

If SA Proportion to Depth == ON (default setting),

the distribution of SA inflows according to depth only applies
to wet non-streamline cells. The approach adopted is as
follows:

The total inflow assigned to streamline cells within a SA

region is proportioned according to the number of

Appendix D TBC Commands - 10 / 12 Page 962 / 1094

 Command Solver Description

streamline cells versus wet non-streamline cells.

The distribution of the inflow allocated to streamline
cells is weighted equally between cells.
The distribution of the inflow allocated to wet non-
streamline cells is weighted according to the depth of
water in the cells.

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

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

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

Appendix D TBC Commands - 11 / 12 Page 963 / 1094

 Command Solver Description

@3675
Set Variable Classic See Section 13.3.3 . If Set Variable is used in the .tcf, if
and HPC you wish to refer to the variable in the .tbc, the variable’s
name must be bounded by “⟨⟨” and “⟩⟩” characters.

@3680
Spatial Database == Classic This is an optional command when using the GeoPackage
[ OFF | TCF ] and HPC input format. It sets the GeoPackage database to use for
subsequent GIS inputs.

@3681 HX and SX Connections ==

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

Appendix D TBC Commands - 12 / 12 Page 964 / 1094

 @3689

@3690
Appendix E TOC Commands

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

Breach Opening Gate Opening Period Startup/Shutdown

Cd Gate Seat Vertical Offset Pump Capacity
Cd Failed Gate Speed Pump Number
Cd Gate Gate Type Pump Operation
Cd Gate Submerged Gate Width Fully Open Sa Failed
Cd Intact Ka Sa Intact
Cd Spillway Ka Intact Sb Failed
Cf Kp Sb Intact
Cf Failed Kp Intact Side Slope (degree)
Cf Intact Method Top Width Breached
Define Number of Piers Top Width Collapse
Depth Breached Operation Top Width Fully Breached
Depth Collapse Orifice Height Fully Open Weir Height
Depth Fully Breached Orifice Opening Weir Height Speed
Discharge Curve Type Orifice Shape Weir Type Failed
End Define Orifice Width Fully Open Weir Type Intact
Ex Failed Period Collapse Weir Width
Ex Intact Period Failure Weir Width Speed
Gate Height Fully Open Period Opening/Closing

Appendix E TOC Commands - 1 / 19 Page 965 / 1094

 @3691
@3695 Table E.1: TUFLOW Classic/HPC TOC Commands

Command Solver Description

@3694
@3696 Opening ==
Breach Classic and The breach status of a Dam Failure Channel.
[ {CLOSE} | OPEN | NO CHANGE ] HPC CLOSE will keep the breach fully closed,
while OPEN will start the breaching process.
NO CHANGE means that the DF channel
operation remains unchanged. The default
status is CLOSE. See Section 5.10.8.2 .

@3697
Cd == Classic and For RO culverts, sets the discharge
[ {0.75 or 0.6} | ⟨ Cd ⟩ ] HPC coefficient used in the (Ansar M. and Nair S.,
2003 ) equation. The default value is 0.75
for RO culverts. See Section 5.10.4 .

For PF channels, sets the discharge

coefficient used in the orifice flow equation
(5.22) . The default value is 0.6 for PF
channels.

@3700
Cd Failed == Classic and Cd Intact sets the weir coefficient (Cd) for
[ ⟨ Cd ⟩ ] HPC the un-breached section of the DF channel,
while Cd Failed sets Cd for the breached
section of the DF channel. This command
overwrites the default Cd values set by the
Weir Type Intact/Failed command. See
Table 5.23 .

@3703
Cd Gate == Classic and Sets the discharge coefficient of the gate. For
[ {0.6 or 0.75} | ⟨ Cd ⟩ ] HPC sluice gates the default value is 0.6 (see
Section 5.10.5 ). For gated spillways the
default is set to the default for Cd Spillway ,
which is 0.75 (see Section 5.10.6 ).

Appendix E TOC Commands - 2 / 19 Page 966 / 1094

 Command Solver Description

@3706
Cd Gate Submerged == Classic and Sets the discharge coefficient of the gate
[ {0.8} | ⟨ Cd ⟩ ] HPC when fully submerged. The default value is
0.8. See Section 5.10.5 .

@3709
Cd Intact == Classic and Cd Intact sets the weir coefficient (Cd) for
[ ⟨ Cd ⟩ ] HPC the un-breached section of the DF channel,
while Cd Failed sets Cd for the breached
section of the DF channel. This command
overwrites the default Cd values set by the
Weir Type Intact/Failed command. See
Table 5.23 .

@3712
Cd Spillway == Classic and Sets the discharge coefficient of the spillway.
[ {0.75} ] HPC Default = 0.75. Prior to the 2016-03 release
the default was 0.5 due to a different version
of the weir equation being used. See Section
5.10.6 .

@3713
Cf == Classic and Weir calibration factor. The default value is
[ {1.0} | ⟨ Cf ⟩ ] HPC 1.0. See Section 5.10.7 .

@3716
Cf Failed == Classic and Sets the weir calibration factor for DF
[ {1.0} | ⟨ Cf ⟩ ] HPC channels. The default values are 1.0. See
Table 5.23 .

@3719
Cf Intact == Classic and Sets the weir calibration factor for DF
[ {1.0} | ⟨ Cf ⟩ ] HPC channels. The default values are 1.0. See
Table 5.23 .

Appendix E TOC Commands - 3 / 19 Page 967 / 1094

 Command Solver Description

@3722 [<structure_type>]
Define Control == Classic and Available structure types (⟨
[ ⟨ control_id ⟩ ] HPC structure_type⟩) include: “Culvert”,
“Pump”, “Q Channel”, “Sluice”, “Spillway”,
“Weir”, “Pipe Failure” or “Dambreak”.

Each Define Control block consists of three

sections:

The default settings for the control’s

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

Within the control definition, commands

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

⟨ control_id ⟩ is a unique control definition

name. For a 1d_nwk channel to use the
control, ⟨ control_id ⟩ must be entered into
the 1d_nwk Inlet_Type attribute. As
mentioned above, more than one channel

Appendix E TOC Commands - 4 / 19 Page 968 / 1094

 Command Solver Description

can reference the same control. For example,

several pumps may utilise the same
operational control logic.

Use End Define to terminate the block. An

ERROR occurs if End Define is not
specified.

@3731 Breached ==
Depth Classic and Sets the initial breach status of the DF
[ ⟨ initial breach depth ⟩ ] HPC channel. Metric units (default) are metres.
Using Units == US Customary, the
units are feet. See Section 5.10.8.2 .

@3734 Collapse ==
Depth Classic and Sets the depth that the dam crest collapse
[ ⟨ depth_collapse ⟩ ] HPC during the Period Collapse at the beginning
of the dam break. The default value is zero
(0). See Section 5.10.8.2 .

@3737 Fully Breached ==

Depth Classic and Sets the height (not elevation) of the dam
[ ⟨ depth_fully_breached ⟩ ] HPC failure opening when fully breached. The
default value is zero (0). See Section
5.10.8.2 .

Appendix E TOC Commands - 5 / 19 Page 969 / 1094

 Command Solver Description

@3740
Discharge Curve Type == Classic and Used to specify how the depth/head
[ {Upstream Depth} | Head Difference | Pump ] HPC discharge curves are calculated in QO
channels. See Section 5.10.3 .

Upstream Depth: (default) Uses the

upstream depth above the channel invert
for the depth discharge curve regardless
of the downstream water level.
Head Difference: Uses the difference in
upstream and downstream water levels
to calculate flow rates from head
discharge curves. This option is more
appropriate for hydraulic structures that
experience downstream controlled flow
regimes.
Pump: Similar to a 1D pump channel,
this option uses the pumping head (i.e.,
downstream water level minus upstream
water level to calculate flow rates from
head discharge curves). The flow is
always in the direction the channel is
digitised. Typically, the curve has
decreasing flows with increasing
pumping head.

@3741
End Define Classic and Ends a Define Control block of .toc
HPC commands for the operating rules applied to
hydraulic structures, pumps and other
controllable devices. See Section 5.10.1.1 .

Appendix E TOC Commands - 6 / 19 Page 970 / 1094

 Command Solver Description

@3742
Ex Failed == Classic and Sets Ex for the breached section of the DF
[ ⟨ Ex ⟩ ] HPC channel. See Section 5.10.8.2 . This
command overwrites the default Ex values
set by the Weir Type Intact/Failed
command. See Table 5.23 .

@3745
Ex Intact == Classic and Ex Intact sets Ex (the weir flow equation
[ ⟨ Ex ⟩ ] HPC exponent) for the un-breached section of the
DF channel. See Section 5.10.8.2 . This
command overwrites the default Ex values
set by the Weir Type Intact/Failed
command. See Table 5.23 .

@3748Height Fully Open ==

Gate Classic and For vertically moving gates the height (not
[ ⟨ height ⟩ ] HPC elevation) of the gate when fully open above
the gate’s seat. If not set, the 1d_nwk
“Height” attribute is used. Metric units
(default) are metres. Using Units == US
Customary, the units are feet.

Appendix E TOC Commands - 7 / 19 Page 971 / 1094

 Command Solver Description

@3751Opening [ {} | (%) ]
Gate == Classic and The position the gate is to be operated
[ [ ++| –| {}] | ⟨ opening ⟩ | {CLOSE} | OPEN | NO HPC towards. A “++” or “–” before ⟨ opening ⟩ will
CHANGE ] incrementally open or close the gate by the
value of ⟨ opening ⟩, otherwise ⟨ opening ⟩ is
taken as the absolute position. The units of ⟨

opening ⟩ are in m or ft, unless “(%)” is

specified, where it is the percentage of the
fully gate open position. CLOSE will start
moving the gate to the fully closed position,
while OPEN will start moving the gate to the
fully open position. NO CHANGE means that
the gate operation remains unchanged. The
default setting is CLOSE.

@3762Seat Vertical Offset ==

Gate Classic and The difference in height in metres (or feet if
[ ⟨ offset ⟩ ] HPC Units == US Customary) between the
spillway crest and the seat of the gate.

@3765Speed [ {} | (min) ]
Gate == Classic and The speed at which the gate moves. Units
[ ⟨ speed ⟩ ] HPC are m/s or ft/s or if “(min)” is specified in
m/min or ft/min. See Sections 5.10.3 ,
5.10.4 , 5.10.5 and 5.10.6 .

@3768Type ==
Gate Classic and Sets the type of gate arrangement.
[ VERTICAL UNDERFLOW | VERTICAL OVERFLOW | HPC VERTICAL/HORIZONTAL indicates the
HORIZONTAL SINGLE | HORIZONTAL DOUBLE ] direction of the gate movement. SINGLE is a
single gate, while DOUBLE are two gates
that move in/out from either side. See
Section 5.10.4 .

Appendix E TOC Commands - 8 / 19 Page 972 / 1094

 Command Solver Description

@3769Width Fully Open ==

Gate Classic and For horizontally moving gates the width of the
[ ⟨ width ⟩ ] HPC gate(s) when fully open. Units are m or ft. If
not set, the 1d_nwk “Width_or_Dia” attribute
is used. See Section 5.10.4 .

@3772
Ka == Classic and Sets the abutment contraction coefficient.
[ {0} | ⟨ value ⟩ ] HPC See Section 5.10.7 .
The default value is set to zero (0) for
backward compatibility. The recommended
values, by USBR (1987 ), for the abutment
contraction coefficient Ka are:

Square abutments with headwall at 90°

to direction of flow: Ka = 0.20.
Rounded abutments with headwall at 90°
to direction of flow, when 0.15H0≤ r≤
0.5H0: Ka = 0.10.
Rounded abutments where r ⟩ 0.5H0,
and headwall is placed not more than
45° to direction of flow: Ka = 0.0.

Appendix E TOC Commands - 9 / 19 Page 973 / 1094

 Command Solver Description

@3776
Ka Intact == Classic and Sets the abutment contraction coefficient.
[ {0} | ⟨ value ⟩ ] HPC See Section 5.10.8.2 for details.
The default value is set to zero (0) for
backward compatibility. The recommended
values, by USBR (1987 ), for the abutment
contraction coefficient Ka are:

Square abutments with headwall at 90°

to direction of flow: Ka = 0.20.

Rounded abutments with headwall at 90°

to direction of flow, when 0.15H0≤ r≤
0.5H0: Ka = 0.10.

Rounded abutments where r ⟩ 0.5H0,

and headwall is placed not more than
45° to direction of flow: Ka = 0.0.

@3780
Kp == Classic and Sets the pier contraction coefficient. See
[ {0} | ⟨ value ⟩ ] HPC Section 5.10.7 .

The default value is set to zero (0) for

backward compatibility. The following values
for the pier contraction coefficient Kp are
recommended by USBR (1987 ):

Square-nosed piers with corners

rounded on a radius equal to
approximately 0.1 of the pier thickness:
Kp = 0.02.
Round-nosed piers: Kp = 0.01.
Pointed-nose piers: Kp = 0.0.

Appendix E TOC Commands - 10 / 19 Page 974 / 1094

 Command Solver Description

@3783
Kp Intact == Classic and Sets the pier contraction coefficient. See
[ {0} | ⟨ value ⟩ ] HPC Section 5.10.8.2 for details.
The default value is set to zero (0) for
backward compatibility. The following values
for the pier contraction coefficient Kp are
recommended by USBR (1987 ).

Square-nosed piers with corners

rounded on a radius equal to
approximately 0.1 of the pier thickness:
Kp = 0.02
Round-nosed piers: Kp = 0.01
Pointed-nose piers: Kp = 0.0

@3786 ==
Method Classic and Sets which method to use for the hydraulic
[ ⟨ method ⟩ ] HPC calculations. As of the 2013-12 release this
command does not need to be applied, as it
is intended for use should alternative
equations become available for a structure in
future releases.

@3789 of Piers ==
Number Classic and Sets the number of piers over a weir. For
[ {0} ] HPC operational weirs, see Section 5.10.7 . For
dam failure modelling, applying the USBR
(1987 ) approach, see Section 5.10.8.2 .
The default value is 0.

@3790
Operation == Classic and Keep the operation of the structure
[ NO CHANGE ] HPC unchanged. UNCHANGED can also be used
instead of NO CHANGE. This function can be
applied to all operational structures types.

Appendix E TOC Commands - 11 / 19 Page 975 / 1094

 Command Solver Description

@3791
Orifice Height Fully Open == Classic and Optional command to set the height of the
[ ⟨ height ⟩ ] HPC piping orifice when fully breached. If omitted,
the value set by 1d_nwk Height_or_WF
attribute is used. See Section 5.10.8.1 .

@3794
Orifice Opening == Classic and The breach status of a Pipe Failure Channel.
[ {CLOSE} | OPEN | NO CHANGE ] HPC CLOSE will keep the breach to the fully
closed, while OPEN will start the breaching
process. NO CHANGE means that the DF
channel operation remains unchanged. The
default status is CLOSE. See Section
5.10.8.1 .

@3795
Orifice Shape == Classic and Sets the shape of the orifice, the default
[ {Rectangular} | Circular ] HPC shape is rectangular. See Section 5.10.8.1 .

@3796
Orifice Width Fully Open == Classic and Optional command to set the width of the
[ ⟨ width ⟩ ] HPC piping orifice when fully breached. If omitted,
the value set by 1d_nwk Width_or_Dia
attribute is used. See Section 5.10.8.1 .

Appendix E TOC Commands - 12 / 19 Page 976 / 1094

 Command Solver Description

@3799 Collapse [ {} | (min) | (s) ]

Period == Classic and For PF channels, sets the time in hour taken
[ {0.0} | ⟨ period ⟩ ] HPC to ‘shut close’ the piping failure channel after
it reaches the full extend. The default value is
0 (i.e. no collapsing at the end of pipe
failure). See Section 5.10.8.1 .

For DF channels, sets the time in hour taken

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

Units are in hours by default, but minutes or

seconds can be used if “(min)” or “(s)” is
specified.

@3802 Failure [ {} | (min) | (s)

Period == Classic and For PF channels, Sets the time in hours
[ {0.0167} | ⟨ period ⟩ ] HPC taken to reach the full size of piping failure.
The default value is 0.0166667 (i.e. 60
seconds). See Section 5.10.8.1 .

For DF channels, Sets the time in hours

taken to reach the full size of dam failure.
The default value is 0.0166667 (i.e. 60
seconds). See Section 5.10.8.2 .

Units are in hours by default, but minutes or

seconds can be used if “(min)” or “(s)” is
specified.

Appendix E TOC Commands - 13 / 19 Page 977 / 1094

 Command Solver Description

@3805 Opening/Closing [ {} | (min) | (s) ] ==

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

Period Opening/Closing == 0.5

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

If this command is omitted the default

opening/closing period is 0.167hrs.

This command is identical to Period

Startup/Shutdown and the two can be used
interchangeably.

Appendix E TOC Commands - 14 / 19 Page 978 / 1094

 Command Solver Description

@3808 Startup/Shutdown [ {} | (min) | (s) ] ==

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

Period Opening/Closing == 0.5

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

If this command is omitted the default

opening/closing period is 0.167hrs.

This command is identical to Period

Opening/Closing and the two can be used
interchangeably.

@3811Capacity ==
Pump Classic and The flow capacity of the pump either as a
[ ⟨ flow ⟩ | ⟨ discharge_curve ⟩ ] HPC constant flow or reference to a dep. If a
constant flow rate, specify ⟨ flow ⟩. If a head-
discharge curve specify the name of the
curve in the Depth Discharge Database .

@3818Number ==
Pump Classic and
Number of pumps in parallel.
[ ⟨ no_pumps ⟩ ] HPC

@3821Operation ==
Pump Classic and Turns the operation of the pump on or off, or
[ ON | OFF | NO CHANGE ] HPC keeps the current operation unchanged.

Appendix E TOC Commands - 15 / 19 Page 979 / 1094

 Command Solver Description

@3822
Sa Failed == Classic and Sets Sa (the Villemonte equation coefficient
[ ⟨ Sa ⟩ ] HPC a) for the breached section of the DF
channel. See Section 5.10.8.2 . This
command overwrites the default Sa values
set by the Weir Type Intact/Failed
command.

@3825
Sa Intact == Classic and Sets Sa (the Villemonte equation coefficient
[ ⟨ Sa ⟩ ] HPC a) for the un-breached section of the DF
channel. See Section 5.10.8.2 . This
command overwrites the default Sa values
set by the Weir Type Intact/Failed
command.

@3828
Sb Failed == Classic and Sets Sb (the Villemonte equation coefficient
[ ⟨ Sb ⟩ ] HPC b) for the breached section of the DF
channel. See Section 5.10.8.2 . This
command overwrites the default Ex values
set by the Weir Type Intact/Failed
command.

@3831
Sb Intact == Classic and Sb Intact sets Sb (the Villemonte equation
[ ⟨ Sb ⟩ ] HPC coefficient b) for the un-breached section of
the DF channel. See Section 5.10.8.2 . This
command overwrites the default Ex values
set by the Weir Type Intact/Failed
command. See Table 5.23 .

@3834Slope (degree) ==
Side Classic and Sets the angle of side slope in degree. This is
[ 90 | ⟨ slope_in_degree ⟩ ] HPC used for bottom width and flow area
calculation. The default value is 90°,
i.e. vertical side walls. See Section 5.10.8.2
.

Appendix E TOC Commands - 16 / 19 Page 980 / 1094

 Command Solver Description

@3837
Top Width Breached == Classic and Sets the initial breach status of the DF
[ ⟨ initial breach depth ⟩ ] HPC channel. Metric units (default) are metres.
Using Units == US Customary, the
units are feet. See Section 5.10.8.2 .

@3840
Top Width Collapse == Classic and Sets the top width that opens up during the
[ ⟨ top_width ⟩ ] HPC Period Collapse . This command is optional.
If not defined, the collapse width is set
proportionally as Top Width Fully Breached *
Depth Collapse / Depth Fully Breached .
See Section 5.10.8.2 .

@3843
Top Width Fully Breached == Classic and Sets the top width of the dam failure channel
[ ⟨ top_width ⟩ ] HPC opening when fully breached. Note that the
total flow with of the DF channel is set by the
1d_nwk Width_or_Dia attribute. This value
can be set smaller than the Width_or_Dia if
the maximum breach width does not reach
the total width of the dam crest. See Section
5.10.8.2 .

@3846Height [ {} | % ]
Weir == Classic and The height (not elevation) of the weir above
[ [++| –|**| //] | ⟨ weir_height ⟩ ] HPC its fully down (open) state to operate
towards. The % option allows the
specification of the percentage of the weir
height that is up (0% would indicate
completely lowered and 100% completely
raised).

Note that the height of the weir above the

crest when fully up is set by the 1d_nwk
Height_or_WF attribute.

Appendix E TOC Commands - 17 / 19 Page 981 / 1094

 Command Solver Description

@3849Height Speed [ {} | (min) ] ==

Weir Classic and The speed at which the weir moves in the
[ ⟨ speed ⟩ ] HPC vertical. Units are m/s or ft/s or if “(min)” is
specified in m/min or ft/min.

@3852Type Failed ==
Weir Classic and Sets the weir parameters for the DF channel
[ ⟨ weir_type ⟩ ] HPC based on Table 5.14 . The default Weir Type
Intact is “WB”, and the default Weir Type
Failed is “WW”. See Table 5.23 .

@3855Type Intact ==
Weir Classic and Sets the weir parameters for the DF channel
[ ⟨ weir_type ⟩ ] HPC based on Table 5.14 . The default Weir Type
Intact is “WB”, and the default Weir Type
Failed is “WW”. See Table 5.23 .

@3858Width [ {} | % ]
Weir == Classic and The width (not elevation) of the weir to
[ ⟨ weir_width ⟩ ] HPC operate towards. The % option allows the
specification of the percentage of the weir
width that is open (0% would indicate
completely closed and 100% completely
open). See Section 5.10.7 .

Note that the full width of the weir is set by

the 1d_nwk Width_or_Dia attribute.

@3861Width Speed [ {} | (min) ]

Weir == Classic and The speed at which the weir moves in the
[ ⟨ speed ⟩ ] HPC horizontal. Units are m/s or ft/s or if “(min)” is
specified in m/min or ft/min. See Section
5.10.7 .

References

@3869M. and Nair S. (2003). Flow Computations at STA-1 West Gated Spillways. South Florida Water Management District.
@3868
Ansar

Appendix E TOC Commands - 18 / 19 Page 982 / 1094

 USBR. (1987). Design of Small Dams [Technology & Engineering]. U.S. Dept. of the Interior, Bureau of Reclamation, 1987-.
@3870
https://www.usbr.gov/tsc/techreferences/mands/mands-pdfs/SmallDams.pdf

Appendix E TOC Commands - 19 / 19 Page 983 / 1094

 @3869

@3870
Appendix F TRFC Commands

The TUFLOW Rainfall Control File (.trfc) contains commands used to generate rainfall grids based on point rainfall gauges, it is read into the
.tcf using the Rainfall Control File command. For more information on the .trfc see Section 4.2.11 . Generating and using rainfall grids is
discussed in Section 8.5.3.6 . The TUFLOW Wiki also includes some useful discussion on this subject. The available TRFC commands are
listed below and are detailed in Table F.1 .

IDW Exponent Read GIS RF Point RF Grid Origin

IDW Maximum Distance Read GIS RF Polygons RF Grid Size (N,M)
IDW Maximum Points Read GIS RF Triangles RF Grid Size (X,Y)
Maximum Hyetograph Points RF Grid Cell Size RF Interpolation Method
Maximum RF Locations RF Grid Format

Appendix F TRFC Commands - 1 / 9 Page 984 / 1094

 @3871
@3875 Table F.1: TUFLOW Classic/HPC TRFC Commands

Command Solver Description

@3874
@3876
IDW Exponent == Classic and If using the RF Interpolation Method == IDW
[ ⟨ p ⟩ | {2} ] HPC the exponent in the IDW equation can be changed from
the default value of 2. Refer to Section 8.5.3.6 for
more details.

@3879
IDW Maximum Distance == Classic and If using the RF Interpolation Method == IDW
[ ⟨ max_dist ⟩ ] HPC the maximum distance for a point to be considered in
the IDW interpolation can be set using this command. If
not specified, no maximum distance is considered.
Using metric units (default), the distance is in metres.
Using Units == US Customary, the units are feet.
Refer to Section 8.5.3.6 for more details.

@3882
IDW Maximum Points == Classic and If using the RF Interpolation Method == IDW
[ ⟨ max_points ⟩ ] HPC the maximum number of points considered in the
interpolation can be specified. This may reduce memory
usage if a very large number of rainfall points are used.
Refer to Section 8.5.3.6 for more details.

@3885
Maximum Hyetograph Points == Classic and Controls the temporary memory allocated for reading /
[ ⟨ max_pts ⟩ | {1,000} ] HPC storing the rainfall data. If more the 1,000 points occur
in the rainfall hyetograph, this can be increased. Can
also be reduced to decrease temporary memory
allocation. Refer to Section 8.5.3.6 for more details.

@3888
Maximum RF Locations == Classic and Controls the temporary memory allocated for reading /
[ ⟨ max_rf_gauges ⟩ | {1,000} ] HPC storing the rainfall data. If more the 1,000 point rainfall
locations are used, this can be increased. Can also be
reduced to decrease temporary memory allocation.
Refer to Section 8.5.3.6 for more details.

Appendix F TRFC Commands - 2 / 9 Page 985 / 1094

 Command Solver Description

@3891GIS RF Point ==
Read Classic and Read the point rainfall locations in the 2d_rf file format.
[ ⟨ gis_layer ⟩ ] HPC For each point the attributes are Name, f1 and f2
factors. If the rainfall factors f1 and/or f2 are zero (or
less than zero), these are changed to 1 and WARNING
2618 is issued. Refer to Section 8.5.3.6 for more
details.

@3894GIS RF Polygons ==
Read Classic and The GIS layer contains a series of polygons or regions
[ ⟨ gis_layer ⟩ ] HPC in the 2d_rf format. These polygons can either have the
rainfall boundary Name (and f1 and f2 factors) specified
on the polygon objects, or if these attributes are blank
TUFLOW looks for rainfall points (specified with the
Read GIS RF Point s) that fall within the polygons. If
the Name attribute in the polygon layer is blank and no
points fall within the polygon an ERROR 2619 occurs.
Refer to Section 8.5.3.6 for more details.

Appendix F TRFC Commands - 3 / 9 Page 986 / 1094

 Command Solver Description

@3897GIS RF Triangles ==
Read Classic and Reads in a GIS layer containing the triangulation of the
[ ⟨ gis_layer ⟩ ] HPC rainfall points. The GIS objects should be polygons or
regions with three vertices, with each vertex snapped to
a rainfall point location as specified by Read GIS RF
Point s. The layer is typically produced by other
software specialising in the interpolation of rainfall, but
can be manually created when only a small number of
rainfall locations exist. The attributes of the GIS layer
are not used. For each grid cell in the rainfall output
grids, the rainfall depth is based on the planar (linear)
interpolation of the three rainfall depths at the vertices
of the bounding triangle. An example of a triangulation
polygon layer (red) connecting the rainfall point
locations (blue) is shown below. Refer to Section
8.5.3.6 for more details.

Appendix F TRFC Commands - 4 / 9 Page 987 / 1094

 Command Solver Description

@3900
RF Grid Cell Size == Classic and Sets the cell size for the generated rainfall grids. If
[ ⟨ value ⟩ ] HPC omitted, a value 10 times the 2D domain cell size is
used. Typically the rainfall can be satisfactorily
represented on a much coarser resolution than that
required for the hydraulic calculations, therefore, using
high resolution rainfall grids is not required and
unnecessarily consumes memory and disk space, and
may slow down the simulation. Refer to Section 8.5.3.6
for more details.

Appendix F TRFC Commands - 5 / 9 Page 988 / 1094

 Command Solver Description

@3903
RF Grid Format == Classic and This mandatory command sets the output grid format.
[ ASC | FLT | NC | TIF ] HPC Options are TIF (GeoTIFF - extension .tif) , FLT (ESRI
binary grid – extension .flt), ASC (ESRI asc grid –
extension .asc), or NC (NetCDF extension .nc).

The rainfall grids are output to a separate folder (RFG\ ⟨

rainfall_grid ⟩) in the location of the .trfc file. If the .trfc

file is in the bc_dbase\ folder, a new folder “bc_dbase\”
is created containing the output grids.

The output formats from the rainfall interpolation are

compatible with the formats used by the .tcf Read Grid
RF , therefore, once the rainfall grids have been
generated this command can be used to apply the
rainfall, rather than regenerate the rainfall grids using
the .trfc file (should the .trfc input files remain
unchanged).

NC: If NetCDF output is specified a single output file

(.nc) containing all timesteps in a single file is created.
This is given the simulation name:
TUFLOW_dbase\simulation_name ⟩.nc ensuring that
the dataset is not accidentally overwritten as the
simulation is running. There is no limit to the number of
rainfall timesteps that are included in the NetCDF
format.

A total rainfall depth is also output, however, this is not

used by TUFLOW during the simulation, and it can be
used for checking purposes. For more information see
TUFLOW NetCDF Rainfall Format Wiki Page.

Appendix F TRFC Commands - 6 / 9 Page 989 / 1094

 Command Solver Description

TIF, FLT and ASC: A series of grids are written (one for
each hyetograph timestep) in the specified formats. Due
to the large number of grids that may be written, these
are separated into a sub-folder under the RFG\ folder,
for example:
_dbase\simulation_name ⟩\simulation_name ⟩_t⟨ time ⟩

.tif

An index file containing a list of the times and rainfall

grid filenames is written in .csv file format in the same
folder, for example:
_dbase\simulation_name ⟩\simulation_name ⟩

_rf_index.csv

A limit of 1,000 grids exists if using the TIF, FLT or ASC

format, if more than 1,000 grids are required the
NetCDF format should be used. Refer to Section 8.5.3.6
for more details.

@3913
RF Grid Origin == Classic and Sets the origin for the output rainfall grid. If this
[ ⟨ OX ⟩ , ⟨ OY ⟩ ] HPC command is omitted the rainfall grid origin is based on
the origin of the TUFLOW 2D domain(s). Refer to
Section 8.5.3.6 for more details.

@3918
RF Grid Size (N,M) == Classic and Sets the size of the output rainfall grids. Similar to the
[ ⟨ rows ⟩ , ⟨ columns ⟩ ] HPC .tgc Grid Size (N,M) command. If omitted the rainfall
grid size is based on the dimensions in the TUFLOW 2D
domain(s). Refer to Section 8.5.3.6 for more details.

@3923
RF Grid Size (X,Y) == Classic and Sets the size of the output rainfall grids. Similar to the
[ ⟨ X_length ⟩ , ⟨ Y_length ⟩ ] HPC .tgc Grid Size (X,Y) command. If omitted the rainfall
grid size is based on the dimensions in the TUFLOW 2D
domain(s). Refer to Section 8.5.3.6 for more details.

Appendix F TRFC Commands - 7 / 9 Page 990 / 1094

 Command Solver Description

@3928
RF Interpolation Method == Classic and Sets the interpolation approach between rainfall
[ IDW | POLYGON | TIN ] HPC locations. This command must be specified with one of
the options as described below.

IDW: An inverse distance weighting approach is used to

calculate the rainfall depth based on the distance to the
surrounding rainfall points (specified by Read GIS RF
Point s).

The exponent (p) can be changed from its default value

of 2 using IDW Exponent . Other commands that affect
the IDW interpolation are IDW Maximum Distance and
IDW Maximum Points .

POLYGON: A series of GIS polygons are specified and

the rainfall for each polygon comes from the point
rainfall. This can be used to apply distributions such as
Thiessen polygons generated from other software. The
regions or polygons are read in the 2d_rf format, and
can either have the rainfall boundary Name (and F1 and
F2 factors) specified via the polygon attributes, or if the
attributes are blank TUFLOW will look for rainfall points
(specified by Read GIS RF Point s) that fall within the
polygons. If the Name attribute in the polygon layer is
blank and no points fall within the polygon an ERROR
2619 occurs.

Appendix F TRFC Commands - 8 / 9 Page 991 / 1094

 Command Solver Description

This method is similar to using a series of rainfall

polygons read in via the .tbc Read GIS RF command.
By pre-processing using a .trfc file, however significant
more memory efficiency occurs, particularly if a large
number of rainfall boundaries is used.

TIN: A TIN (Triangulated Irregular Network) is specified

via Read GIS RF Triangles which connects the rainfall
point locations.

Appendix F TRFC Commands - 9 / 9 Page 992 / 1094

 @3936

@3937
Appendix G TESF Commands

The External Stress File (.tesf) allows the definition of time varying global or spatially varying external forcing such as wind or wave radiation
stresses, it is read into the .tcf using the External Stress File command. For more information on the .tesf see Section 4.2.12 . Applying
external stresses is discussed in Section 8.8 . The available TESF commands are listed below and are detailed in Table G.1 .

Global Wind BC IDW Maximum Point Read GIS Wind Point

Grid Interpolation Method Output Grid Cell Size Read GIS Wind Poly
IDW Exponent Output Grid Format Read Gridded Tau
IDW Maximum Distance Output Grid Origin

Appendix G TESF Commands - 1 / 5 Page 993 / 1094

 @3938
@3942 Table G.1: TUFLOW Classic/HPC TESF Commands

Command Solver Description

@3941
@3943 Wind BC ==
Global Classic and HPC This command defines the
[ ⟨ boundary name ⟩ ] Wind BC name in the BC
Database (Section 8.6 ). It
invokes a global wind boundary
in a model. See Section 4.2.12
.

@3946Interpolation Method ==
Grid Classic and HPC Defines the external stress grid
[ IWD | Poly | {no default} ] interpolation method. See
Section 4.2.12 .

@3947
IDW Exponent == Classic and HPC Sets the exponent term to be
[ {2.0} | ⟨ value ⟩ ] used in the external stress IDW
interpolation. See Section
4.2.12 .

@3950
IDW Maximum Distance == Classic and HPC This can be used to set the
[ ⟨ value ⟩ ] maximum distance for a point to
be considered in the external
stress IDW interpolation, any
points further than this are not
used in the IDW interpolation. If
not specified no maximum
distance is considered. See
Section 4.2.12 .

Appendix G TESF Commands - 2 / 5 Page 994 / 1094

 Command Solver Description

@3953
IDW Maximum Point == Classic and HPC Controls the maximum number
[ {all} | ⟨ maximum points ⟩ ] of points considered in the
external stress IDW
interpolation. By default, all
point locations will be used. If a
very large number of point
locations are provided this
command can be used to
reduce the memory usage. For
example, if 100 wind locations
are provided, and the IDW
Maximum Point is set to 20 at
each output grid interpolation
point only the closest 20 points
are used. See Section 4.2.12 .

@3956 Grid Cell Size ==

Output Classic and HPC Sets the grid size for the
[ ⟨ value ⟩ | {10 x the smallest 2D cell size} ] generated stress grids. If
omitted, a value of 10 times the
smallest 2D cell size is used.
Typically, wind stresses can be
satisfactorily represented on a
much coarser resolution than
that required for the hydraulic
computations, therefore, using
high resolution stress grids is
typically not required and may
unnecessarily increase memory
usage, disk space and may
slow down the simulation. See
Section 4.2.12 .

Appendix G TESF Commands - 3 / 5 Page 995 / 1094

 Command Solver Description

@3959 Grid Format ==

Output Classic and HPC Sets the output grid format to
[ ASC | FLT | {NC} ] be used if interpolating point
data to a stress grid. The
default is to use NetCDF as this
packages all output grid data
for the simulation into a single
.nc file. See Section 4.2.12 .

@3960 Grid Origin ==

Output Classic and HPC Sets the origin for the output
[ x, y ] stress grids. If this command is
omitted, the model origin is
used. See Section 4.2.12 .

@3961GIS Wind Point ==

Read Classic and HPC This command defines spatially
[ ⟨ gis file ⟩ ] varying wind BC name
information, as referenced in
the BC Database (see Section
8.6 ). This command invokes
external stress grid
interpolation. Uses 2d_ws GIS
layers, as described in Table
8.15 .

Appendix G TESF Commands - 4 / 5 Page 996 / 1094

 Command Solver Description

@3964GIS Wind Poly ==

Read Classic and HPC This command defines spatially
[ ⟨ gis file ⟩ ] varying wind BC name
information, as referenced in
the BC Database (see Section
8.6 ). This command invokes
external stress grid
interpolation. See Section
4.2.12 . Uses 2d_ws GIS
layers, as described in Table
8.15 .

@3967Gridded Tau ==
Read Classic and HPC This command is used to
[ ⟨ path to .nc or grid index .csv ⟩ ] reference a user defined
external stress file. See Section
4.2.12 .

Appendix G TESF Commands - 5 / 5 Page 997 / 1094

 @3978

@3979
Appendix H QCF Commands

The Quadtree Control File (.qcf) is used to define the grid refinement areas and optionally the model location and extent, it is read into the .tcf
using the Quadtree Control File command. For more information on the .qcf see Section 4.2.8 . Setting up a quadtree grid is discussed in
Section 7.4.1 . The available QCF commands are listed below and are detailed in Table H.1 .

Base Cell Size Quadtree Mesh Processing Method

Model Origin and Extent Read GIS Nesting
Orientation Angle Spatial Database

Appendix H QCF Commands - 1 / 6 Page 998 / 1094

 @3980
@3984 Table H.1: TUFLOW HPC QCF Commands

Command Solver Description

@3983
@3985Cell Size ==
Base HPC Used to set the Level 1
[ ⟨ cell size⟩ | {TGC} ] (parent) cell size. If set to
“TGC”, then the cell size
defined in the .tgc is used. If
set to a numerical value, can
be used to override the cell
size command in the .tgc file.
Using metric units (default) the
value is in metres. Using
Units == US Customary,
the value is in feet. See
Section 7.4.1 for more details.

Appendix H QCF Commands - 2 / 6 Page 999 / 1094

 Command Solver Description

@3988 Origin and Extent ==

Model HPC If set to “Auto” the extents of
[ {Auto} | TGC ] the Level 1 GIS polygon are
used to define the model origin
and extents. If set to “TGC”,
the model is located as per the
commands in the .tgc file. Note
the angle of the model is
defined with the Orientation
Angle command below. Also
note, if set to “Auto” the GIS
nesting polygons must have a
Level 1 polygon defined,
otherwise an ERROR is
generated. The default setting
is “TGC” if Quadtree
Control File == Single
Level and “Auto” if a .qcf
(e.g. Quadtree Control
File == ⟨ .qcf⟩) is
specified. See Section 7.4.1
for more details.

Appendix H QCF Commands - 3 / 6 Page 1000 / 1094

 Command Solver Description

@3991
Orientation Angle == HPC If set to a numerical value (in
[ ⟨ angle ⟩ | Optimise | {TGC} ] degrees) defines the model
orientation angle and
overwrites any angle / location
.tgc commands. If Set to
“Optimise” the parent Level 1
polygon is used to optimise the
angle of the mesh. As such the
GIS nesting polygon must
have a Level 1 polygon
defined. See Section 7.4.1 for
more details.

Appendix H QCF Commands - 4 / 6 Page 1001 / 1094

 Command Solver Description

@3994
Quadtree Mesh Processing Method == HPC When pre-processing the
[ {FAST} | Memory Efficient ] Quadtree mesh, a hidden 2D
domain is used for areas of
refinement to allow fast
processing of geometry on a
regular grid. The default
approach, “FAST”, treats each
nesting level as a domain,
therefore with 3 levels of
nesting the geometry control
file is processed 3 times. To
reduce initialisation memory
demands it is possible to treat
each GIS polygon in the
2d_qnl as a separate domain
for the processing of geometry
inputs by setting this command
to “Memory Efficient”. Whilst
being more memory efficient
during mesh creation, this may
be slower to initialise. It has no
effect on the speed of the
hydraulic computations or the
memory demand during the
hydraulic calculations. See
Section 7.4.1 for more details.

Appendix H QCF Commands - 5 / 6 Page 1002 / 1094

 Command Solver Description

@3995GIS Nesting ==
Read HPC Used to define polygons of
[ ⟨ gis file in 2d_qnl format ⟩ ] mesh refinement (different
levels). Uses 2d_qnl GIS
layers, as described Section
7.4.1.4 . See Section 7.4.1
for more details.

@3998
Spatial Database == HPC Optional when using the
[ OFF | TCF ] GeoPackage input format.
Sets the database to use for
subsequent inputs. See
Section 4.4.3 .

Appendix H QCF Commands - 6 / 6 Page 1003 / 1094

 @4007

@4008
Appendix I TSCF Commands

The TUFLOW SWMM Control File (.tscf) contains the SWMM input commands, it is read into the .tcf using the SWMM Control File
command. For more information on the .tscf, see Section 4.2.14 . Setting up a SWMM-TUFLOW model is discussed in Chapter 6 . The
available TSCF commands are listed below and are detailed in Table I.1 .

Check INP Save Date Output Folder Read SWMM

Inlet Surcharge Orifice Coefficient READ BC <TYPE> SWMM Iterations
Maximum Inlet Ponded Depth Read GIS SWMM Inlet Usage

Appendix I TSCF Commands - 1 / 9 Page 1004 / 1094

 @4009
@4013 Table I.1: TUFLOW Classic/HPC TSCF Commands

Command Solver Description

@4012

Appendix I TSCF Commands - 2 / 9 Page 1005 / 1094

 Command Solver Description

@4014 INP Save Date ==

Check Classic and Checks that the save date
[ {ERROR} | WARNING | OFF ] HPC of the SWMM .inp file is
later than the save date of
the equivalent SWMM
GeoPackage GIS layer. This
command is very useful for
detecting the possibility that
a GIS layer has been
modified, but not exported
as an .inp prior to the
simulation. For this check to
function, both the .inp and
GIS files must be located in
the same folder.

For the ERROR option (the

default), the simulation
terminates and an error
message is reported.

For the WARNING option, a

warning is written to the
screen and log file, but the
simulation proceeds without
pausing. It remains the
responsibility of the user to
check for any warnings.

The OFF option disables all

checks and no warnings are
given.

Appendix I TSCF Commands - 3 / 9 Page 1006 / 1094

 Command Solver Description

Refer to Section 6.3 for

SWMM GeoPackage GIS
layer information.

@4015 Surcharge Orifice Coefficient ==

Inlet Classic and Specifies the orifice
[ {0.16} ] HPC equation coefficient that is
used when a 1D SWMM
inlet overflows to 2D
TUFLOW (1D SWMM
pressure head is higher
than the 2D TUFLOW water
surface elevation). See
Section 10.4.2 for more
details.

Appendix I TSCF Commands - 4 / 9 Page 1007 / 1094

 Command Solver Description

@4016
Maximum Inlet Ponded Depth == Classic and This command prevents
[ {999} ] HPC unrealistic SWMM ponding
elevations when using
SWMM hydrology to convey
subcatchment flows directly
to pipe network nodes
connected to the 2D
TUFLOW domain. When the
1D SWMM domain water
depth at the node inlet is
above the specified value,
the ponded volume above
this threshold will be
transferred to the 2D
TUFLOW domain in the next
SWMM timestep. Without
this command, flows from
the 1D to the 2D domain are
determined based on the
orifice equation. In that
form, because of the
unrealistic nature of adding
the flows directly to the pipe
network, this can lead to
unrealistically high water
levels in ponded SWMM
nodes. See Section 10.4.2
for more details.

Appendix I TSCF Commands - 5 / 9 Page 1008 / 1094

 Command Solver Description

@4017 Folder ==
Output Classic and The default location for 1D
[ <folder> ] HPC SWMM output is the folder
location specified using the
.tcf Output Folder
command. This command
redirects the SWMM
combined inp file and all
SWMM output data to a
non-default folder location.

Appendix I TSCF Commands - 6 / 9 Page 1009 / 1094

 Command Solver Description

@4018BC <type> ==
READ Classic and Reads curves from the BC
[ <input_curve_1> | <input_curve_2> | … ] HPC database using the Name
lookup (similar to what
would be used in the 2d_bc)
and writes them to the
SWMM .inp file used for the
simulation, into the
[TIMESERIES] section if
“TIMESERIES” is provided,
or otherwise into the generic
curves section. For generic
curves, the type specified
before the “==” becomes the
Type specified in the inp.
Valid types (<type>) are
STORAGE, SHAPE,
DIVERSION, TIDAL,
PUMP1, PUMP2, PUMP3,
PUMP4, PUMP5, RATING,
CONTROL, or WEIR.
Multiple commands can be
used as needed and the
simulation events will be
used as appropriate. See
Section 6.2.5 for more
details.

Appendix I TSCF Commands - 7 / 9 Page 1010 / 1094

 Command Solver Description

@4019GIS SWMM Inlet Usage ==

Read Classic and This command reads a
[ <swmm_inlet_usage_filename> ] HPC SWMM inlet usage filename
to identify locations and
attributes of inlets (pits) that
connect the 2D TUFLOW
and 1D SWMM models. This
feature uses swmm_iu_ GIS
layers, as described in Table
10.1 .

@4020SWMM ==
Read Classic and This command defines the
[ <swmm_inp_filename> ] HPC SWMM input (.inp) file for
the SWMM simulation. This
command can be duplicated
to read in multiple SWMM
input files. TUFLOW
automatically combines the
multiple .inp files into a
single file for the simulation.
If duplicate items, in terms
of SWMM item location and
“Name”, or alternatively
Project–Options, are
included in multiple different
inp files, the entry that is
referenced lowest in the
TUFLOW SWMM Control
File (TSCF) will be used.
See Section 6.1 for more
details.

Appendix I TSCF Commands - 8 / 9 Page 1011 / 1094

 Command Solver Description

@4021Iterations ==
SWMM Classic and Controls the number of
[ {1} ] HPC SWMM iterations that are
run for each 2D timestep.
Increasing the number
decreases the timestep
used by SWMM, potentially
improving model stability,
though increasing 1D
simulation run time. See
Section 10.4 for more
details.

Appendix I TSCF Commands - 9 / 9 Page 1012 / 1094

 @4030

@4031
Appendix J ADCF Commands

The TUFLOW Advection Dispersion Control File (.adcf) contains commands related to the TUFLOW Advection Dispersion (AD) Module for
simulating depth-averaged, constituent fate and transport. It is read into the .tcf using the AD Control File command. For more information on
the .tesf see Section 4.2.13 . The Advection Dispersion module is discussed in Chapter 9 . The available ADCF commands are listed below
and are detailed in Table J.1 .

AD BC Database Write Iterations

AD Global Database Write Mass
Write CFL Write Mass Unit

Appendix J ADCF Commands - 1 / 3 Page 1013 / 1094

 @4032
@4036 Table J.1: TUFLOW Classic/HPC ADCF Commands

Command Solver Description

@4035
@4037
AD BC Database == Classic and HPC A pointer to a file containing
[ <file> ] boundary database information
(e.g. names of boundary files as
mapped to GIS datasets read by
TUFLOW). See Section 9.5.4 .

@4038
AD Global Database == Classic and HPC A pointer to a file containing
[ <file> ] constituent information (e.g. name
and dispersion coefficients). See
Section 9.5.3 .

@4039 CFL ==
Write Classic Only If set to ON, generates a
[ ON | {OFF} ] _ADcfl.csv output file with
commentary on CFL and Peclet
numbers, maximum dispersion
coefficients and number of sub-
step iterations. See Section 9.6.1.2
.

@4040 Iterations ==
Write Classic Only If set to ON, shows information
[ ON | {OFF} ] regarding the simulation time for
each constituent. In particular, the
number of AD sub-steps needed to
be executed to maintain stability
under CFL and Peclet conditions is
reported. Additional rows are
added as required by the number
of constituents simulated. See
Section 9.4.4 .

Appendix J ADCF Commands - 2 / 3 Page 1014 / 1094

 Command Solver Description

@4041 Mass ==
Write Classic and HPC If set to ON, generates a mass
[ ON | {OFF} ] conservation commentary output
file. See Section 9.6.1.3 .

@4042 Mass Unit ==

Write Classic and HPC Sets the unit for the mass output
[ Kg (or Kilogram) | {Tonne} | Gram ] file if Write Mass is set to ON. See
Section 9.6.1.3 .

Appendix J ADCF Commands - 3 / 3 Page 1015 / 1094

 @4051

@4052
Appendix K TEF Commands

The TUFLOW Event File (.tef) contains commands related to Event Management functionality. It is read into the .tcf using the Event File
command. For more information on the .tef, see Section 4.2.9 . Event management is discussed in Section 13.3.1 . All commands listed in
Appendix A and Appendix B can be read into the .tef. The additional .tef specific commands are listed below and are detailed in Table K.1 .

Define Event
End Define

Appendix K TEF Commands - 1 / 2 Page 1016 / 1094

 @4053
@4057 Table K.1: TUFLOW Classic/HPC TEF Commands

Command Solver Description

@4056
@4058 Event ==
Define Classic and HPC Starts a block of .tcf and .ecf commands for
[ <event_name> ] an event named <event_name>. Only one
block can be specified for each unique
event_name. Use End Define to terminate
the block. An ERROR occurs if End Define
is not specified.

For information on Events, see Section

13.3.1 . An example of using Events is
given in the TUFLOW Wiki Tutorial 9.

@4059
End Define Classic and HPC Ends the Define Event block of commands.
This command must be specified if Define
Event occurs within the .tef.

For information on Events, see Section

13.3.1 . An example of using Events is
given in the TUFLOW Wiki Tutorial 9.

Appendix K TEF Commands - 2 / 2 Page 1017 / 1094

 @4068

@4069
Appendix L SWMM GeoPackage Format

This appendix contains the layers and attributes used in the SWMM GeoPackage format which can be converted to and from EPA SWMM inp
files, as discussed in Section 6.3.1 .

Appendix L SWMM GeoPackage Format - 1 / 71 Page 1018 / 1094

 @4070
L.1 SWMM GeoPackage Layer List

@4071
@4075 Table L.1: SWMM Input layers

Category Input Description Geometry Table

@4074 Specifies external hydrographs and

BC @4076
Inflows pollutographs that enter the drainage system at Point Table L.2
specific nodes.

Describes a relationship between two variables

Curves @4077
Curves No Geometry Table L.3
in tabular format.

Curves @4078
Timeseries Describes how a quantity varies over time. No Geometry Table L.4

Supplies parameters for each unconfined

groundwater aquifer in the study area. Aquifers
Groundwater @4079
Aquifers consist of two zones – a lower saturated zone No Geometry Table L.5
and an upper unsaturated zone with a moving
boundary between the two.

Supplies parameters that determine the rate of

groundwater flow between the aquifer
Groundwater @4080
Groundwater Region Table L.6
underneath a subcatchment and a node of the
conveyance system.

Defines custom groundwater flow equations for

Groundwater @4081
GWF Region Table L.7
specific subcatchments.

Specifies optional monthly adjustments to be

made to temperature, evaporation rate, rainfall
Hydrology @4082
Adjustments No Geometry Table L.8
intensity and hydraulic conductivity in each time
period of a simulation.

Specifies how daily potential evaporation rates

Hydrology @4083
Evaporation No Geometry Table L.9
vary with time for the study area.

Appendix L SWMM GeoPackage Format - 2 / 71 Page 1019 / 1094

 Category Input Description Geometry Table

Specifies the shapes of the triangular unit

hydrographs that determine the amount of
Hydrology @4084
Hydrographs No Geometry Table L.10
rainfall-dependent infiltration/inflow (RDII)
entering the drainage system.

Specifies time patterns of dry weather flow or

Hydrology @4085
Patterns quality in the form of adjustment factors applied No Geometry Table L.11
as multipliers to baseline values.

Identifies each rain gage that provides rainfall

Hydrology @4086
Raingages No Geometry Table L.12
data for the study area.

Specifies the parameters that describe rainfall-

Hydrology @4087
RDII dependent infiltration/inflow (RDII) entering the Point Table L.13
drainage system at specific nodes.

Specifies parameters that govern how snowfall

accumulates and melts on the plowable,
Hydrology @4088
Snowpacks No Geometry Table L.14
impervious and pervious surfaces of
subcatchments.

Specifies daily air temperatures, monthly wind

speed, and various snowmelt parameters for
the study area. Required only when snowmelt is
Hydrology @4089
Temperature No Geometry Table L.15
being modeled or when evaporation rates are
computed from daily temperatures or are read
from an external climate file.

Supplies infiltration parameters for each

Contained
subcatchment. Rainfall lost to infiltration only
Hydrology @4090
Infiltration Region within Table
occurs over the pervious subarea of a
L.38
subcatchment.

Appendix L SWMM GeoPackage Format - 3 / 71 Page 1020 / 1094

 Category Input Description Geometry Table

Supplies information about pervious and

impervious areas for each subcatchment. Each
Contained
subcatchment can consist of a pervious
Hydrology @4091
Subareas Region within Table
subarea, an impervious subarea with
L.38
depression storage, and an impervious subarea
without depression storage.

Identifies each subcatchment within the study

Hydrology @4092
Subcatchments area. Subcatchments are land area units that Region Table L.38
generate runoff from rainfall.

Assigns inlet structures to specific street and

Inlets @4093
Inlet Usage Point Table L.16
open channel conduits.

Defines inlet structure designs used to capture

Inlets @4094
Inlets street and channel flow that are sent to below No Geometry Table L.17
ground sewers.

Defines scale-independent LID controls that

LID @4095
Lid_controls No Geometry Table L.18
can be deployed within subcatchments.

Deploys LID controls within specific

LID @4096
Lid_usage Region Table L.19
subcatchment areas.

Identifies each conduit link of the drainage

Links @4097
Conduits system. Conduits are pipes or channels that Line Table L.20
convey water from one node to another.

Determines how pumps and regulators will be

Links @4098
Controls adjusted based on simulation time or conditions No Geometry Table L.21
at specific nodes and links.

Contained
Specifies minor head loss coefficients, flap
Links @4099
Losses Line within Table
gates, and seepage rates for conduits.
L.20

Appendix L SWMM GeoPackage Format - 4 / 71 Page 1021 / 1094

 Category Input Description Geometry Table

Identifies each orifice link of the drainage

system. An orifice link serves to limit the flow
Links @4100
Orifices Line Table L.22
exiting a node and is often used to model flow
diversions and storage node outlets.

Identifies each outlet flow control device of the

drainage system. These are devices used to
Links @4101
Outlets model outflows from storage units or flow Line Table L.23
diversions that have a user-defined relationship
between flow rate and water depth.

Identifies each pump link of the drainage

Links @4102
Pumps Line Table L.24
system.

Describes the cross-section geometry of

Links @4103
Streets No Geometry Table L.25
conduits that represent streets.

Describes the cross-section geometry of natural

Table L.26 and
Links @4104
Transects channels or conduits with irregular shapes No Geometry
Table L.27
following the HEC-2 data format.

Identifies each weir link of the drainage system.

Links @4105
Weirs Weirs are used to model flow diversions and Line Table L.28
storage node outlets.

Contained
Provides cross-section geometric data for within Table
Links @4106
Xsections conduit and regulator links of the drainage Line L.20 , Table
system. L.22 and Table
L.28 .

Appendix L SWMM GeoPackage Format - 5 / 71 Page 1022 / 1094

 Category Input Description Geometry Table

Identifies each flow divider node of the drainage

system. Flow dividers are junctions with exactly
Nodes @4107
Dividers two outflow conduits where the total outflow is Point Table L.29
divided between the two in a prescribed
manner.

Specifies dry weather flow and its quality

Nodes @4108
DWF No Geometry Table L.30
entering the drainage system at specific nodes.

Identifies each junction node of the drainage

system. Junctions are points in space where
Nodes @4109
Junctions channels and pipes connect together. For Point Table L.31
sewer systems they can be either connection
fittings or manholes.

Identifies each outfall node (i.e., final

downstream boundary) of the drainage system
Nodes @4110
Outfalls and the corresponding water stage elevation. Point Table L.32
Only one link can be incident on an outfall
node.

Identifies each storage node of the drainage

system. Storage nodes can have any shape as
Nodes @4111
Storage Point Table L.33
specified by a surface area versus water depth
relation.

Identifies optional interface files used or saved

Project @4112
Files No Geometry Table L.34
by a run.

Project @4113
Options Provides values for various analysis options. No Geometry Table L.35

Describes the contents of the report file that

Project @4114
Report No Geometry Table L.36
SWMM produces.

Appendix L SWMM GeoPackage Format - 6 / 71 Page 1023 / 1094

 Category Input Description Geometry Table

Attaches a descriptive title to the project being

Project @4115
Title No Geometry Table L.37
analyzed.

Specifies the rate that pollutants build up over

WQ @4116
Buildup No Geometry Table L.39
different land uses between rain events.

Specifies the percentage of a subcatchment’s

WQ @4117
Coverages area that is covered by each category of land Region Table L.40
use.

Identifies the various categories of land uses

within the drainage area. Each subcatchment
area can be assigned a different mix of land
WQ @4118
Landuses uses. Each land use can be subjected to a No Geometry Table L.41
different street sweeping schedule. Land uses
are only used in conjunction with pollutant
buildup and wash off.

Specifies the pollutant buildup that exists on

WQ @4119
Loadings Region Table L.42
each subcatchment at the start of a simulation.

WQ @4120
Pollutants Identifies the pollutants being analyzed. No Geometry Table L.43

Specifies the degree of treatment received by

WQ @4121
Treatment pollutants at specific nodes of the drainage Point Table L.44
system.

Specifies the rate at which pollutants are

WQ @4122
Washoff washed off from different land uses during rain No Geometry Table L.45
events.

Appendix L SWMM GeoPackage Format - 7 / 71 Page 1024 / 1094

 @4127
L.2 SWMM GeoPackage Layer Descriptions

@4128
@4132 Table L.2: Inflows

Default GIS Attribute

No. Description Type
Name

@4131 1 Node Name of the node where external inflow enters. Char

2 Type FLOW or <name of a pollutant>. Char

Name of a time series in the TIMESERIES section describing how external

3 Tseries Char
flow or pollutant loading varies with time.

<name of a pollutant>:

CONCEN: if pollutant inflow is described as a concentration (default).

4 PollutType Char
MASS: if it is described as a mass flow rate.

FLOW: Not Used.

The factor that converts the inflow’s mass flow rate units into the project’s
5 Mfactor mass units per second, where the project’s mass units are those specified for Float
the pollutant in the POLLUTANTS section (default is 1.0).

CONCEN if pollutant is described as a concentration, MASS if it is described

6 SeriesType Char
as a mass flow rate (default is CONCEN)

Generally 1 for FLOW; Mfactor for Pollutant - the factor that converts the
inflow’s mass flow rate units into the project’s mass units per second, where
7 Factor1 Float
the project’s mass units are those specified for the pollutant in the
[POLLUTANTS] section (default is 1.0)

A scaling factor that multiplies the recorded time series values (default is
8 Sfactor Float
1.0).

9 Base A constant baseline value added to the time series value (default is 0.0). Float

Appendix L SWMM GeoPackage Format - 8 / 71 Page 1025 / 1094

 Default GIS Attribute
No. Description Type
Name

Name of an optional time pattern in the PATTERNS section used to adjust

10 Pat Char
the baseline value on a periodic basis.

@4137
@4141 Table L.3: Curves

Default GIS Attribute

No. Description Type
Name

@4140 1 Name Name assigned to the curve. Char

The type of curve being defined: STORAGE / SHAPE / DIVERSION / TIDAL /

2 Type Char
PUMP1 / PUMP2 / PUMP3 / PUMP4 / PUMP5 / RATING / CONTROL / WEIR.

3 xval An X (independent variable) value. Float

4 yval The Y (dependent variable) value corresponding to X. Float

@4146
@4150 Table L.4: Timeseries

Default GIS Attribute

No. Description Type
Name

@4149 1 Name Name assigned to the time series. Char

2 Frame The name of a file in which the time series data are stored. Char

3 Date Date in Month/Day/Year format (e.g., June 15, 2001 would be 6/15/2001). Char

Hours since the start of the simulation, expressed as a decimal number or as

4 Time Char
hours:minutes (where hours can be greater than 24).

5 Value A value corresponding to the specified date and time. Float

Appendix L SWMM GeoPackage Format - 9 / 71 Page 1026 / 1094

 @4155
@4159 Table L.5: Aquifers

Default GIS Attribute

No. Description Type
Name

@4158 1 Name Name assigned to aquifer. Char

2 Por Soil porosity (pore space volume / total volume). Float

3 WP Soil wilting point (moisture content of a fully dried soil). Float

4 FC Soil field capacity (moisture content of a fully drained soil). Float

5 Ksat Saturated hydraulic conductivity (in/hr or mm/hr). Float

Slope of the logarithm of hydraulic conductivity versus moisture deficit (porosity

6 Kslope Float
minus moisture content) curve (dimensionless).

7 Tslope Slope of soil tension versus moisture content curve (inches or mm). Float

Fraction of total evaporation available for evapotranspiration in the upper

8 ETu Float
unsaturated zone.

Maximum depth into the lower saturated zone over which evapotranspiration
9 ETs Float
can occur (ft or m).

Seepage rate from saturated zone to deep groundwater when water table is at
10 Seep Float
ground surface (in/hr or mm/hr).

Elevation of the bottom of the aquifer (ft or m). Local values can be assigned to
11 Ebot Float
specific subcatchments in the GROUNDWATER section.

Groundwater table elevation at start of simulation (ft or m). Local values can be
12 Egw Float
assigned to specific subcatchments in the GROUNDWATER section.

Unsaturated zone moisture content at start of simulation (volumetric fraction).

13 Umc Local values can be assigned to specific subcatchments in the Float
GROUNDWATER section.

Appendix L SWMM GeoPackage Format - 10 / 71 Page 1027 / 1094

 Default GIS Attribute
No. Description Type
Name

Name of optional monthly time pattern used to adjust the upper zone
14 ETupat Float
evaporation fraction for different months of the year.

Appendix L SWMM GeoPackage Format - 11 / 71 Page 1028 / 1094

 @4164
@4168 Table L.6: Groundwater

No. Default GIS Attribute Name Description Type

@4167 1 Subcatchment Subcatchment name. Char

2 Aquifer Name of groundwater aquifer underneath the subcatchment. Char

Name of a node in the conveyance system exchanging groundwater with

3 Node Char
the aquifer.

4 Esurf Surface elevation of the subcatchment (ft or m). Float

5 A1 Groundwater flow coefficient (see Equation (L.1) below). Float

6 B1 Groundwater flow exponent (see Equation (L.1) below). Float

7 A2 Surface water flow coefficient (see Equation (L.1) below). Float

8 B2 Surface water flow exponent (see Equation (L.1) below). Float

Surface water – groundwater interaction coefficient (see Equation (L.1)

9 A3 Float
below).

Fixed depth of surface water at the receiving node (ft or m) (set to zero if
10 Dsw Float
surface water depth will vary as computed by flow routing).

Threshold groundwater table elevation which must be reached before any

11 Egwt flow occurs (ft or m). Leave blank (or enter *) to use the elevation of the Float
receiving node’s invert.

Optional. Elevation of the bottom of the aquifer (ft or m). Can be used to
12 Ebot Float
override the values supplied for the subcatchment’s aquifer.

Optional. Groundwater table elevation at the start of the simulation (ft or

13 Wgr m). Can be used to override the values supplied for the subcatchment’s Float
aquifer.

Appendix L SWMM GeoPackage Format - 12 / 71 Page 1029 / 1094

 No. Default GIS Attribute Name Description Type

Optional. Unsaturated zone moisture content at start of simulation

14 Umc (volumetric fraction). Can be used to override the values supplied for the Float
subcatchment’s aquifer.

The flow coefficients are used in the following equation that determines the lateral groundwater flow rate based on groundwater and surface
water elevations:

@4173
B1 B2
QL = A1(Hgw – Hcb ) – A2(Hsw – Hcb ) + A3Hgw Hsw (L.1)

Where:

QL = lateral groundwater flow (cfs per acre or cms per hectare),

Hgw = height of saturated zone above the bottom of the aquifer (ft or m),
Hsw = height of surface water at the receiving node above the aquifer bottom (ft or m),
Hcb = height of the channel bottom above the aquifer bottom (ft or m).

Appendix L SWMM GeoPackage Format - 13 / 71 Page 1030 / 1094

 @4179
@4183 Table L.7: GWF

No. Default GIS Attribute Name Description Type

@4182 1 Subcatchment Subcatchment name. Char

Lateral: to designate an expression for Lateral groundwater flow (to a

2 Type node of the conveyance network). Char

Deep: for vertical loss to Deep groundwater

A math formula expressing the rate of groundwater flow (in cfs per acre
for lateral flow or in/hr for deep flow (cms per hectare and mm/hr if using
metric units) as a function of the following variables:

Hgw: for height of the groundwater table

Hsw: for height of the surface water
Hcb: for height of the channel bottom
Hgs: for height of ground surface

Where all heights are relative to the aquifer bottom and have units of
3 Expr either feet or meters (if using metric units): Char

Ks: for saturated hydraulic conductivity in in/hr or mm/hr

K: for unsaturated hydraulic conductivity in in/hr or mm/hr
Theta: for moisture content of the unsaturated zone
Phi: for aquifer soil porosity
Fi: for infiltration rate from the ground surface in in/hr or mm/hr
Fu: for percolation rate from the upper unsaturated zone in in/hr or
mm/hr
A: for subcatchment area in acres or hectares

Appendix L SWMM GeoPackage Format - 14 / 71 Page 1031 / 1094

 @4188
@4192 Table L.8: Adjustments

Default GIS Attribute

No. Description Type
Name

@4191 Temperature: t1..t12

Evaporation: e1..e12
1 Format Char
Rainfall: r1..r12

Conductivity: c1..c12

t1: adjustments to temperature in January, as plus or minus degrees F

(degrees C if using metric units).

e1: adjustments to evaporation rate in January, as plus or minus in/day

2 Month1 (mm/day if using metric units). Float

r1: multipliers applied to precipitation rate in January.

c1: multipliers applied to soil hydraulic conductivity in January used in either

Horton or Green-Ampt infiltration.

3 Month2 As above, for February. Float

4 Month3 As above, for March. Float

5 Month4 As above, for April. Float

6 Month5 As above, for May. Float

7 Month6 As above, for June. Float

8 Month7 As above, for July. Float

9 Month8 As above, for August. Float

10 Month9 As above, for September. Float

11 Month10 As above, for October. Float

Appendix L SWMM GeoPackage Format - 15 / 71 Page 1032 / 1094

 Default GIS Attribute
No. Description Type
Name

12 Month11 As above, for November. Float

13 Month12 As above, for December. Float

Appendix L SWMM GeoPackage Format - 16 / 71 Page 1033 / 1094

 @4197
@4201 Table L.9: Evaporation

Default GIS Attribute

No. Description Type
Name

@4200 CONSTANT: applies a constant evaporation rate.

MONTHLY: applies a constant evaporation rate per month.

TIMESERIES: applies the specified timeseries.

TEMPERATURE: indicates that evaporation rates will be computed from the

daily air temperatures contained in an external climate file whose name is
provided in the TEMPERATURE section. This method also uses the site’s
latitude, which can also be specified in the TEMPERATURE section.

FILE: indicates that evaporation data will be read directly from the same
external climate file used for air temperatures as specified in the
TEMPERATURE section. Supplying monthly pan coefficients for these data is
1 Format optional. Char

RECOVERY: identifies an optional monthly time pattern of multipliers used to

modify infiltration recovery rates during dry periods. For example, if the normal
infiltration recovery rate was 1% during a specific time period and a pattern
factor of 0.8 applied to this period, then the actual recovery rate would be
0.8%.

DRY_ONLY: determines if evaporation only occurs during periods with no

precipitation. The default is NO.

Note: The evaporation rates provided in this section are potential rates. The
actual amount of water evaporated will depend on the amount available as a
simulation progresses.

2 Evap CONSTANT: constant evaporation rate (in/day or mm/day). Float

3 e1 MONTHLY: evaporation rate in January (in/day or mm/day). Float

4 e2 MONTHLY: evaporation rate in February (in/day or mm/day). Float

Appendix L SWMM GeoPackage Format - 17 / 71 Page 1034 / 1094

 Default GIS Attribute
No. Description Type
Name

5 e3 MONTHLY: evaporation rate in March (in/day or mm/day). Float

6 e4 MONTHLY: evaporation rate in April (in/day or mm/day). Float

7 e5 MONTHLY: evaporation rate in May (in/day or mm/day). Float

8 e6 MONTHLY: evaporation rate in June (in/day or mm/day). Float

9 e7 MONTHLY: evaporation rate in July (in/day or mm/day). Float

10 e8 MONTHLY: evaporation rate in August (in/day or mm/day). Float

11 e9 MONTHLY: evaporation rate in September (in/day or mm/day). Float

MONTHLY: evaporation rate in October (in/day or mm/day if using metric

12 e10 Float
units).

MONTHLY: evaporation rate in November (in/day or mm/day if using metric

13 e11 Float
units).

MONTHLY: evaporation rate in December (in/day or mm/day if using metric

14 e12 Float
units).

TIMESERIES: name of a time series in the TIMESERIES section with

15 Tseries Char
evaporation data.

16 p1 FILE: pan coefficient for January. Float

17 p2 FILE: pan coefficient for February. Float

18 p3 FILE: pan coefficient for March. Float

19 p4 FILE: pan coefficient for April. Float

20 p5 FILE: pan coefficient for May. Float

21 p6 FILE: pan coefficient for June. Float

Appendix L SWMM GeoPackage Format - 18 / 71 Page 1035 / 1094

 Default GIS Attribute
No. Description Type
Name

22 p7 FILE: pan coefficient for July. Float

23 p8 FILE: pan coefficient for August. Float

24 p9 FILE: pan coefficient for September. Float

25 p10 FILE: pan coefficient for October. Float

26 p11 FILE: pan coefficient for November. Float

27 p12 FILE: pan coefficient for December. Float

28 patternID RECOVERY: Name of a monthly time pattern. Char

DRY_ONLY: Yes or No. Determines if evaporation only occurs during periods

29 Value Char
with no precipitation. The Default is No.

Appendix L SWMM GeoPackage Format - 19 / 71 Page 1036 / 1094

 @4206
@4210 Table L.10: Hydrographs

No. Default GIS Attribute Name Description Type

@4209 1 Name Name assigned to a unit hydrograph group. Char

Name of the rain gage used by the unit hydrograph group or month of
2 RaingageOrMonth Char
the year (e.g., JAN, FEB, etc. or ALL for all months).

Three separate unit hydrographs, that represent the short-term,

medium-term, and long-term RDII responses, can be defined for each
3 Term month (or all months taken together). Char

Use either SHORT, MEDIUM, or LONG.

Response ratio for the unit hydrograph. The response ratio (R) is the
4 R fraction of a unit of rainfall depth that becomes RDII. The sum of the Float
ratios for a set of three hydrographs does not have to equal 1.0.

5 T Time to peak (hours) for the unit hydrograph. Float

Recession limb ratio for the unit hydrograph. The recession limb ratio
(K) is the ratio of the duration of the hydrograph’s recession limb to
6 K the time to peak (T) making the hydrograph time base equal to T* Float
(1+K) hours. The area under each unit hydrograph is 1 inch (or mm if
using metric units).

Optional. Maximum initial abstraction depth available (in rain depth

7 Dmax Float
units). If not supplied then the default is no initial abstraction.

Optional. Initial abstraction recovery rate (in rain depth units per day).
8 Drec Float
If not supplied then the default is no initial abstraction.

Optional. Initial abstraction depth already filled at the start of the

9 D0 simulation (in rain depth units). If not supplied then the default is no Float
initial abstraction.

Appendix L SWMM GeoPackage Format - 20 / 71 Page 1037 / 1094

 @4215
@4219 Table L.11: Patterns

Default GIS Attribute

No. Description Type
Name

@4218 1 Name Name used to identify the pattern. Char

MONTHLY: Used to set monthly pattern factors for dry weather flow
constituents.

DAILY: Used to set dry weather pattern factors for each day of the week, where
Sunday is day 1.

HOURLY: Used to set dry weather factors for each hour of the day starting from
midnight.
2 Interval Char
WEEKEND: If these factors are different for weekend days than for weekday
days then the WEEKEND format can be used to specify hourly adjustment
factors just for weekends.

More than one line can be used to enter a pattern’s factors by repeating the
pattern’s name (but not the pattern type) at the beginning of each additional
line. The pattern factors are applied as multipliers to any baseline dry weather
flows or quality concentrations supplied in the DWF section.

MONTHLY: factor for January

3 Factor1 DAILY: factor for Sunday Float

HOURLY: factor for 0:00AM.

MONTHLY: factor for February

4 Factor2 DAILY: factor for Monday Float

HOURLY: factor for 1:00AM.

Appendix L SWMM GeoPackage Format - 21 / 71 Page 1038 / 1094

 Default GIS Attribute
No. Description Type
Name

MONTHLY: factor for March

5 Factor3 DAILY: factor for Tuesday Float

HOURLY: factor for 2:00AM.

MONTHLY: factor for April

6 Factor4 DAILY: factor for Wednesday Float

HOURLY: factor for 3:00AM.

MONTHLY: factor for May

7 Factor5 DAILY: factor for Thursday Float

HOURLY: factor for 4:00AM.

MONTHLY: factor for June

8 Factor6 DAILY: factor for Friday Float

HOURLY: factor for 5:00AM.

MONTHLY: factor for July

9 Factor7 DAILY: factor for Saturday Float

HOURLY: factor for 6:00AM.

MONTHLY: factor for August

10 Factor8 DAILY: not used. Float

HOURLY: factor for 7:00AM.

Appendix L SWMM GeoPackage Format - 22 / 71 Page 1039 / 1094

 Default GIS Attribute
No. Description Type
Name

MONTHLY: factor for September

11 Factor9 DAILY: not used. Float

HOURLY: factor for 8:00AM.

MONTHLY: factor for October

12 Factor10 DAILY: not used. Float

HOURLY: factor for 9:00AM.

MONTHLY: factor for November

13 Factor11 DAILY: not used. Float

HOURLY: factor for 10:00AM.

MONTHLY: factor for December

14 Factor12 DAILY: not used. Float

HOURLY: factor for 11:00AM.

MONTHLY and DAILY: not used.

15 Factor13 Float
HOURLY: factor for 12:00PM.

MONTHLY and DAILY: not used.

16 Factor14 Float
HOURLY: factor for 13:00PM.

MONTHLY and DAILY: not used.

17 Factor15 Float
HOURLY: factor for 14:00PM.

MONTHLY and DAILY: not used.

18 Factor16 Float
HOURLY: factor for 15:00PM.

Appendix L SWMM GeoPackage Format - 23 / 71 Page 1040 / 1094

 Default GIS Attribute
No. Description Type
Name

MONTHLY and DAILY: not used.

19 Factor17 Float
HOURLY: factor for 16:00PM.

MONTHLY and DAILY: not used.

20 Factor18 Float
HOURLY: factor for 17:00PM.

MONTHLY and DAILY: not used.

21 Factor19 Float
HOURLY: factor for 18:00PM.

MONTHLY and DAILY: not used.

22 Factor20 Float
HOURLY: factor for 19:00PM.

MONTHLY and DAILY: not used.

23 Factor21 Float
HOURLY: factor for 20:00PM.

MONTHLY and DAILY: not used.

24 Factor22 Float
HOURLY: factor for 21:00PM.

MONTHLY and DAILY: not used.

25 Factor23 Float
HOURLY: factor for 22:00PM.

MONTHLY and DAILY: not used.

26 Factor24 Float
HOURLY: factor for 23:00PM.

Appendix L SWMM GeoPackage Format - 24 / 71 Page 1041 / 1094

 @4224
@4228 Table L.12: Raingages

No. Default GIS Attribute Name Description Type

@4227 1 Name Name assigned to rain gage. Char

Form of recorded rainfall, either INTENSITY, VOLUME or

2 Form Char
CUMULATIVE.

Time interval between gage readings in decimal hours or

3 Intvl Char
hours:minutes format (e.g., 0:15 for 15-minute readings).

Snow catch deficiency correction factor (use 1.0 for no

4 SnowCatchDeficiency Float
adjustment).

5 Format Either TIMESERIES or FILE. Char

TIMESERIES: Name of a time series in the TIMESERIES section

6 Tseries Char
with rainfall data.

FILE: Name of an external file with rainfall data. Enclose the

external file name in double quotes if it contains spaces and
7 Fname Char
include its full path if it resides in a different directory than the
SWMM input file.

FILE: Name of the recording station in a user-prepared formatted

8 Sta rain file. Only required when using a user-prepared formatted Char
rainfall file.

FILE: Rain depth units for the data in a user-prepared formatted

9 Units rain file, either inches or millimeters if using metric units. Only Char
required when using a user-prepared formatted rainfall file.

Appendix L SWMM GeoPackage Format - 25 / 71 Page 1042 / 1094

 @4233
@4237 Table L.13: RDII

Default GIS Attribute

No. Description Type
Name

@4236 1 Node Name of a node receiving RDII flow. Char

Name of an RDII unit hydrograph group appearing in the HYDROGRAPHS

2 UHgroup Char
section.

Area of the sewershed that contributes RDII to the node (acres or hectares if
3 SewerArea Float
using metric units).

Appendix L SWMM GeoPackage Format - 26 / 71 Page 1043 / 1094

 @4242
@4246 Table L.14: Snowpacks

Default GIS Attribute

No. Description Type
Name

@4245 1 Name Name assigned to snowpack parameter set . Char

PLOWABLE: contains parameters for the impervious area of a subcatchment

that is subject to snow removal by plowing but not to areal depletion. This area
is the fraction SNN0 of the total impervious area.

IMPERVIOUS: contains parameter values for the remaining impervious area.

2 Type PERVIOUS: contains parameter values for the entire pervious area. Char

REMOVAL: describes how snow removed from the plowable area is transferred
onto other areas.

The various transfer fractions should sum to no more than 1.0. If the line is
omitted then no snow removal takes place.

PLOWABLE, IMPERVIOUS and PERVIOUS: Minimum melt coefficient (in/hr-

3 Cmin deg F or mm/hr-deg C if using metric units). Float

REMOVAL: Not Used.

PLOWABLE, IMPERVIOUS and PERVIOUS: Maximum melt coefficient (in/hr-

4 Cmax deg F or mm/hr-deg C if using metric units). Float

REMOVAL: Not Used.

PLOWABLE, IMPERVIOUS and PERVIOUS: Snow melt base temperature (deg

5 Tbase F or deg C if using metric units). Float

REMOVAL: Not Used.

PLOWABLE, IMPERVIOUS and PERVIOUS: Ratio of free water holding

6 FWF capacity to snow depth (fraction). Float

REMOVAL: Not Used.

Appendix L SWMM GeoPackage Format - 27 / 71 Page 1044 / 1094

 Default GIS Attribute
No. Description Type
Name

PLOWABLE, IMPERVIOUS and PERVIOUS: Initial snow depth (water

7 SD0 equivalent in or mm if using metric units). Float

REMOVAL: Not Used.

PLOWABLE, IMPERVIOUS and PERVIOUS: Initial free water in pack (in or mm

8 FW0 if using metric units). Float

REMOVAL: Not Used.

PLOWABLE: Fraction of impervious area that can be plowed.

9 SNN0 Float
IMPERVIOUS, PERVIOUS and REMOVAL: Not Used.

IMPERVIOUS and PERVIOUS: Snow depth above which there is 100% cover

10 SD100 (water equivalent in or mm if using metric units). Float

PLOWABLE and REMOVAL: Not Used.

REMOVAL: Depth of snow on plowable areas at which snow removal begins (in

11 Dplow or mm if using metric units). Char

PLOWABLE, IMPERVIOUS and PERVIOUS: Not Used.

REMOVAL: Fraction of snow on plowable area transferred out of watershed.

12 Fout Float
PLOWABLE, IMPERVIOUS and PERVIOUS: Not Used.

REMOVAL: Fraction of snow on plowable area transferred to impervious area

13 Fimp by plowing. Float

PLOWABLE, IMPERVIOUS and PERVIOUS: Not Used.

REMOVAL: Fraction of snow on plowable area transferred to pervious area by

14 Fperv plowing. Float

PLOWABLE, IMPERVIOUS and PERVIOUS: Not Used.

Appendix L SWMM GeoPackage Format - 28 / 71 Page 1045 / 1094

 Default GIS Attribute
No. Description Type
Name

REMOVAL: Fraction of snow on plowable area converted into immediate melt.

15 Fimelt Float
PLOWABLE, IMPERVIOUS and PERVIOUS: Not Used.

REMOVAL: Fraction of snow on plowable area transferred to pervious area in

16 Fsub another subcatchment. Float

PLOWABLE, IMPERVIOUS and PERVIOUS: Not Used.

REMOVAL: Name of subcatchment receiving the Fsub fraction of transferred

17 Scatch snow. Char

PLOWABLE, IMPERVIOUS and PERVIOUS: Not Used.

@4251
@4255 Table L.15: Temperature

Default GIS Attribute

No. Description Type
Name

@4254 Available options:

FILE
WINDSPEED MONTHLY
1 Option Char
SNOWMELT
ADC IMPERVIOUS
ADC PERVIOUS

2 Value Name of file or relevent value. Add additional value columns when required. Char

Appendix L SWMM GeoPackage Format - 29 / 71 Page 1046 / 1094

 @4260
@4264 Table L.16: Inlet Usage

Default GIS Attribute

No. Description Type
Name

@4263 1 Conduit Name of a street or open channel conduit containing the inlet. Char

2 Inlet Name of an inlet structure (from the INLETS section) to use. Char

3 Node Name of the sewer node receiving flow captured by the inlet. Char

Optional. Number of replicate inlets placed on each side of the street.

4 Number Integer
Default is 1 (for each side of a two-sided street).

Optional. Degree to which inlet capacity is reduced due to clogging (%).

5 PctClogged Float
Default is 0.

Optional. Maximum flow that the inlet can capture (flow units). A Qmax
6 Qmax Float
value of 0 indicates that the inlet has no flow restriction. Default is 0.

Optional. Height of local gutter depression (in or mm). Default is 0. The

local gutter depression applies only over the length of the inlet unlike the
7 aLocal Float
continuous depression for a STREET cross section which exists over the
full curb length.

Optional. Width of local gutter depression (ft or m). Default is 0. The local
gutter depression applies only over the length of the inlet unlike the
8 wLocal Float
continuous depression for a STREET cross section which exists over the
full curb length.

Optional. AUTOMATIC, ON_GRADE, or ON_SAG. The default inlet

placement is AUTOMATIC, meaning that the program uses the network
topography to determine whether an inlet operates on-grade or on-sag.
9 Placement On-grade means the inlet is located on a continuous grade. On-sag means Char
the inlet is located at a sag or sump point where all adjacent conduits
slope towards the inlet leaving no place for water to flow except into the
inlet.

Appendix L SWMM GeoPackage Format - 30 / 71 Page 1047 / 1094

 @4269
@4273 Table L.17: Inlets

No. Default GIS Attribute Name Description Type

@4272 1 Name Name assigned to the inlet structure. Char

Set either GRATE, DROP_GRATE, CURB, DROP_CURB,

2 Type Char
COMBINATION, SLOTTED or CUSTOM.

3 Grate_Length GRATE: length of the inlet parallel to the street curb (ft or m). Float

4 Grate_Width GRATE: width of a GRATE inlet (ft or m). Float

GRATE: type of GRATE used, options availabe:

P_BAR-50: Parallel bar grate with bar spacing 1-7/8-in on center.

P_BAR-50X100: Parallel bar grate with bar spacing 1-7/8-in on
center and 3/8-in diameter lateral rods spaced at 4-in on center.
P_BAR-30: Parallel bar grate with 1-1/8-in on center bar spacing.
CURVED_VANE: Curved vane grate with 3-1/4-in longitudinal bar
and 4-1/4-in transverse bar spacing on center.
5 Grate_Type Char
TILT_BAR-45: 45 degree tilt bar grate with 2-1/4-in longitudinal bar
and 4-in transverse bar spacing on center.
TILT_BAR-30: 30 degree tilt bar grate with 3-1/4-in and 4-in on
center longitudinal and lateral bar spacing respectively.
RETICULINE: “Honeycomb” pattern of lateral bars and longitudinal
bearing bars.
GENERIC: A generic grate design.

6 Grate_Aopen GRATE: if type is GENERIC, fraction of grate’s area that is open. Float

GRATE: if type is GENERIC, splash over velocity (ft/s or m/s if using

7 Grate_vsplash Float
metric units).

CURB: length of the inlet parallel to the street curb (ft or m if using metric
8 Curb_Length Float
units).

9 Curb_Height CURB: height of a opening inlet (ft or m if using metric units). Float

Appendix L SWMM GeoPackage Format - 31 / 71 Page 1048 / 1094

 No. Default GIS Attribute Name Description Type

CURB: the throat angle of a CURB opening inlet (HORIZONTAL,

10 Curb_Throat Char
INCLINED or VERTICAL).

11 Slotted_Length SLOTTED: length of a SLOTTED inlet (ft or m if using metric units). Float

12 Slotted_Width SLOTTED: width of a SLOTTED inlet (ft or m if using metric units). Float

13 Custom_Curve CUSTOM: name of a Rating-type curve (captured flow v. water depth). Char

Appendix L SWMM GeoPackage Format - 32 / 71 Page 1049 / 1094

 @4278
@4282 Table L.18: LID Controls

No. Default GIS Attribute Name Description Type

@4281 1 Name Name assigned to LID process. Char

BC for bio-retention cell

RG for rain garden

GR for green roof

IT for infiltration trench

2 Type Char
PP for permeable pavement

RB for rain barrel

RD for rooftop disconnection

VS for vegetative swale

BC, RG, GR, IT, PP, RD, VS: When confining walls or berms are
present this is the maximum depth to which water can pond above
the surface of the unit before overflow occurs (in inches or mm). For

3 surface_StorHt LIDs that experience overland flow it is the height of any surface Float
depression storage. For swales, it is the height of its trapezoidal
cross-section.

All other types: Not Used.

BC, RG, GR, IT, PP, RD, VS: Fraction of the surface storage volume

4 surface_VegFrac that is filled with vegetation. Float

All other types: Not Used.

Appendix L SWMM GeoPackage Format - 33 / 71 Page 1050 / 1094

 No. Default GIS Attribute Name Description Type

BC, RG, GR, IT, PP, RD, VS: Manning’s coefficient (n) for overland
flow over surface soil cover, pavement, roof surface or a vegetative
swale. Use 0 for other types of LIDs. If value is 0 then any ponded
5 surface_Rough water that exceeds the surface storage depth is assumed to Float

completely overflow the LID control within a single time step.

All other types: Not Used.

BC, RG, GR, IT, PP, RD, VS: slope of a roof surface, pavement
surface or vegetative swale (percent). Use 0 for other types of LIDs.
If value is 0 then any ponded water that exceeds the surface storage
6 surface_Slope depth is assumed to completely overflow the LID control within a Float

single time step.

All other types: Not Used.

BC, RG, GR, IT, PP, RD, VS: slope (run over rise) of the side walls of

7 surface_Xslope a vegetative swale’s cross-section. Use 0 for other types of LIDs. Float

All other types: Not Used.

BC, RG, GR, PP: Thickness of the soil layer (inches or mm if using

8 soil_Thick metric units). Optional for PP. Float

All other types: Not Used.

BC, RG, GR, PP: Soil porosity (pore space volume / total volume).

9 soil_Por Optional for PP. Float

All other types: Not Used.

BC, RG, GR, PP: Soil field capacity (moisture content of a fully

10 soil_FC drained soil). Optional for PP. Float

All other types: Not Used.

Appendix L SWMM GeoPackage Format - 34 / 71 Page 1051 / 1094

 No. Default GIS Attribute Name Description Type

BC, RG, GR, PP: Soil wilting point (moisture content of a fully dried

11 soil_WP soil). Optional for PP. Float

All other types: Not Used.

BC, RG, GR, PP: Soil’s saturated hydraulic conductivity (in/hr or

12 soil_Ksat mm/hr if using metric units). Optional for PP. Float

All other types: Not Used.

BC, RG, GR, PP: Slope of the curve of log (conductivity) versus soil
moisture deficit (porosity minus soil moisture) (dimensionless).
13 soil_Kcoeff Optional for PP. Float

All other types: Not Used.

BC, RG, GR, PP: Soil capillary suction (in or mm if using metric

14 soil_Suct units). Optional for PP. Float

All other types: Not Used.

PP: Thickness of the pavement layer (inches or mm if using metric

15 pavement_Thick units). Float

All other types: Not Used.

PP: Void ratio (volume of void space relative to the volume of solids
in the pavement for continuous systems or for the fill material used in
16 pavement_Vratio modular systems). Note that porosity = void ratio / (1 + void ratio). Float

All other types: Not Used.

PP: Ratio of impervious paver material to total area for modular

17 pavement_FracImp systems; 0 for continuous porous pavement systems. Float

All other types: Not Used.

Appendix L SWMM GeoPackage Format - 35 / 71 Page 1052 / 1094

 No. Default GIS Attribute Name Description Type

PP: Permeability of the concrete or asphalt used in continuous

systems or hydraulic conductivity of the fill material (gravel or sand)
18 pavement_Perm used in modular systems (in/hr or mm/hr). Float

All other types: Not Used.

PP: the number of pavement layer void volumes of runoff treated it

takes to completely clog the pavement. Use a value of 0 to ignore
19 pavement_Vclog clogging. Float

All other types: Not Used.

PP: The number of days that the pavement layer is allowed to clog
before its permeability is restored, typically by vacuuming its surface.

20 pavement_Treg A value of 0 (the default) indicates that no permeability regeneration Float

occurs.

All other types: Not Used.

PP: The fractional degree to which the pavement’s permeability is

restored when a regeneration interval is reached. The default is 0 (no
restoration) while a value of 1 indicates complete restoration to the
21 pavement_Freg original permeability value. Once regeneration occurs the pavement Float

begins to clog once again at a rate determined by Vclog.

All other types: Not Used.

BC, IT, PP, RB: Thickness of the storage layer or height of a rain

22 storage_Height barrel (inches or mm if using metric units). Float

All other types: Not Used.

Appendix L SWMM GeoPackage Format - 36 / 71 Page 1053 / 1094

 No. Default GIS Attribute Name Description Type

BC, IT, PP, RB: void ratio (volume of void space relative to the
volume of solids in the layer). Note that porosity = void ratio / (1 +
23 storage_Vratio void ratio). Float

All other types: Not Used.

BC, IT, PP, RB: The rate at which water seeps from the layer into the
underlying native soil when first constructed (in/hr or mm/hr if using

24 storage_Seepage metric units). If there is an impermeable floor or liner below the layer Float
then use a value of 0.

All other types: Not Used.

BC, IT, PP, RB: Number of storage layer void volumes of runoff
25 storage_Vclog treated it takes to completely clog the layer. Use a value of 0 to Float
ignore clogging.

BC, IT, PP, RB: YES (the default) if a rain barrel is covered, NO if it is

26 storage_Covrd not. Char

All other types: Not Used.

RB, RD, BC, IT, PP: Coefficient C that determines the rate of flow
through the drain as a function of height of stored water above the
drain bottom. For Rooftop Disconnection it is the maximum flow rate

27 drain_Coeff (in inches/hour or mm/hour if using metric units) that the roof’s Float
gutters and downspouts can handle before overflowing. Optional for
BC, IT, PP.

All other types: Not Used.

RB, RD, BC, IT, PP: Exponent n that determines the rate of flow
through the drain as a function of height of stored water above the
28 drain_Expon drain outlet. Optional for BC, IT, PP. Float

All other types: Not Used.

Appendix L SWMM GeoPackage Format - 37 / 71 Page 1054 / 1094

 No. Default GIS Attribute Name Description Type

RB, RD, BC, IT, PP: Height of the drain line above the bottom of the
storage layer or rain barrel (inches or mm if using metric units).
29 drain_Offset Optional for BC, IT, PP. Float

All other types: Not Used.

RB, RD, BC, IT, PP: Number of dry weather hours that must elapse
before the drain line in a rain barrel is opened (the line is assumed to
be closed once rainfall begins). A value of 0 signifies that the barrel’s
30 drain_Delay drain line is always open and drains continuously. This parameter is Float

ignored for other types of LIDs.

All other types: Not Used.

RB, RD, BC, IT, PP: The height of water (in inches or mm) in the
drain’s Storage Layer that causes the drain to automatically open.
31 drain_Hopen Use 0 to disable this feature. Optional for BC, IT, PP. Float

All other types: Not Used.

RB, RD, BC, IT, PP: The height of water (in inches or mm) in the
drain’s Storage Layer that causes the drain to automatically close.
32 drain_Hclose Use 0 to disable this feature. Optional for BC, IT, PP. Float

All other types: Not Used.

RB, RD, BC, IT, PP: The name of an optional Control Curve that
adjusts the computed drain flow as a function of the head of water

33 drain_Qcrv above the drain. Leave blank if not applicable. Optional for BC, IT, Char
PP.

All other types: Not Used.

Appendix L SWMM GeoPackage Format - 38 / 71 Page 1055 / 1094

 No. Default GIS Attribute Name Description Type

GR: Thickness of the drainage mat (inches or mm if using metric

34 drainmat_Thick units). Float

All other types: Not Used.

GR: Ratio of void volume to total volume in the mat.

35 drainmat_Vratio Char
All other types: Not Used.

GR: Manning’s coefficient (n) used to compute the horizontal flow

36 drainmat_Rough rate of drained water through the mat. Char

All other types: Not Used.

Appendix L SWMM GeoPackage Format - 39 / 71 Page 1056 / 1094

 @4287
@4291 Table L.19: LID Usage

No. Default GIS Attribute Name Description Type

@4290 1 Subcatchment Name of the subcatchment using the LID process. Char

2 LID Name of a LID process defined in the LID_CONTROLS section. Char

3 Number Number of replicate LID units deployed. Integer

4 Area Area of each replicate unit (ft2 or m2 if using metric units) Float

Width of the outflow face of each identical LID unit (in ft or m if using
metric units). This parameter applies to roofs, pavement, trenches, and
swales that use overland flow to convey surface runoff off of the unit. It
5 Width Float
can be set to 0 for other LID processes, such as bio-retention cells, rain
gardens, and rain barrels that simply spill any excess captured runoff
over their berms.

The percent to which the LID’s soil, storage, and drain mat zones are
initially filled with water. For soil zones 0 % saturation corresponds to
6 InitSat Float
the wilting point moisture content while 100 % saturation has the
moisture content equal to the porosity.

The percent of the impervious portion of the subcatchment’s non-LID

area whose runoff is treated by the LID practice. (E.g., if rain barrels are
used to capture roof runoff and roofs represent 60% of the impervious
7 FromImp Float
area, then the impervious area treated is 60%). If the LID unit treats
only direct rainfall, such as with a green roof, then this value should be
0. If the LID takes up the entire subcatchment then this field is ignored.

A value of 1 indicates that the surface and drain flow from the LID unit
should be routed back onto the pervious area of the subcatchment that
8 ToPerv Float
contains it. This would be a common choice to make for rain barrels,
rooftop disconnection, and possibly green roofs. The default value is 0.

Appendix L SWMM GeoPackage Format - 40 / 71 Page 1057 / 1094

 No. Default GIS Attribute Name Description Type

Optional name of a file to which detailed time series results for the LID
will be written. Enclose the name in double quotes if it contains spaces
9 RptFile and include its full path if it resides in a different directory than the Char
SWMM input file. Use ’*’ if not applicable and an entry for DrainTo or
FromPerv follows

Optional name of subcatchment or node that receives flow from the

unit’s drain line, if different from the outlet of the subcatchment that the
10 DrainTo Char
LID is placed in. Use ’*’ if not applicable and an entry for FromPerv
follows.

Optional percent of the pervious portion of the subcatchment’s non-LID

11 FromPerv Float
area whose runoff is treated by the LID practice. The default value is 0.

Appendix L SWMM GeoPackage Format - 41 / 71 Page 1058 / 1094

 @4296
@4300 Table L.20: Conduits

No. Default GIS Attribute Name Description Type

@4299 1 Name Name assigned to conduit link. Char

2 From Node Name of the conduit’s upstream node. Char

3 To Node Name of the conduit’s downstream node. Char

4 Length Conduit length (ft or m if using metric units). Float

5 Roughness Manning’s roughness coefficient (n). Float

Offset of the conduit’s upstream end above the invert of its upstream
6 InOffset Float
node (ft or m if using metric units).

Offset of the conduit’s downstream end above the invert of its

7 OutOffset Float
downstream node (ft or m if using metric units).

Flow in the conduit at the start of the simulation (flow units) (default is
8 InitFlow Float
0).

9 MaxFlow Maximum flow allowed in the conduit (flow units) (default is no limit). Float

A cross-section shape, the available shapes include:

Circular, Force_main, Filled_circular2, Rect_closed, Rect_open,

10 xsec_XsecType Trapezoidal, Triangular, Horiz_ellipse, Vert_ellipse, Arch, Parabolic, Char

Power, Rect_triangular, Rect_round, Modbaskethandle, Egg,
Horseshoe, Gothic, Catenary, Semielliptical, Baskethandle,
Semicircular, Custom.

Circular, Force_main, Filled_circular2: Diameter (ft or m if using

metric units)
11 xsec_Geom1 Float
All other shapes: Full height of the cross-section (ft or m if using
metric units)

Appendix L SWMM GeoPackage Format - 42 / 71 Page 1059 / 1094

 No. Default GIS Attribute Name Description Type

Modbaskethandle and Trapezoidal: Base Width

Arch, Horiz_ellipse and Vert_ellipse: Max. Width

Force_main: Roughness

Filled_circular2: Sediment depth

12 xsec_Geom2 Float
Custom: Shape curve

Parabolic, Power, Rect_closed, Rect_open, Rect_round,

Rect_triangular, Triangular: Top width

All other shapes: Not used

Rect_Round: Bottom Radius

Power: Exponent

Trapezoidal: Left Slope

Vert_ellipse and Horiz_ellipse: Size Code

13 xsec_Geom3 Float
Arch: Size Code

ModBasketHandle: Top Radius

Rect_Triangular: Triangle Height

All other shapes: Not used

Trapezoidal: Right slope

14 xsec_Geom4 Float
All other shapes: Not used

Number of barrels (i.e., number of parallel pipes of equal size, slope,

15 xsec_Barrels Integer
and roughness) associated with a conduit (default is 1).

Code number from Table A.10 for the conduit’s inlet geometry if it is a
16 xsec_Culvert Char
culvert subject to possible inlet flow control (leave blank otherwise).

Appendix L SWMM GeoPackage Format - 43 / 71 Page 1060 / 1094

 No. Default GIS Attribute Name Description Type

Name of a Shape Curve in the CURVES section that defines how

17 xsec_Curve Char
cross-section width varies with depth.

Name of an entry in the TRANSECTS section that describes the

18 xsec_Tsect Char
cross-section geometry of an irregular channel.

Name of an entry in the STREETS section that describes the cross-

19 xsec_Street Char
section geometry of a street.

20 losses_Kentry Minor head loss coefficient at the conduit’s entrance. Float

21 losses_Kexit Minor head loss coefficient at the conduit’s exit. Float

22 losses_Kavg Average minor head loss coefficient across the length of the conduit. Float

YES if the conduit has a flap valve that prevents back flow, NO
23 losses_Flap Char
otherwise. (Default is NO).

Rate of seepage loss into the surrounding soil (in/hr or mm/hr if using
24 losses_Seepage Float
metric units). (Default is 0.)

@4305
@4309 Table L.21: Controls

Default GIS Attribute

No. Description Type
Name

@4308 Determines how pumps and regulators will be adjusted based on simulation
1 Text Char
time or conditions at specific nodes and links.

Appendix L SWMM GeoPackage Format - 44 / 71 Page 1061 / 1094

 @4314
@4318 Table L.22: Orifices

No. Default GIS Attribute Name Description Type

@4317 1 Name Name assigned to orifice link. Char

2 From Node Name of the orifice’s inlet node. Char

3 To Node Name of the orifice’s outlet node. Char

The type of orifice - either SIDE if oriented in a vertical plane or

4 Type Char
BOTTOM if oriented in a horizontal plane.

Amount that a Side Orifice’s bottom or the position of a Bottom Orifice

is offset above the invert of inlet node (ft or m, expressed as either a
5 Offset Float
depth or as an elevation, depending on the LINK_OFFSETS option
setting).

6 Qcoeff Discharge coefficient (unitless). Float

7 Gated YES if a flap gate prevents reverse flow, NO if not (default is NO). Char

Time in decimal hours to open a fully closed orifice (or close a fully
8 CloseTime Float
open one). Use 0 if the orifice can open/close instantaneously.

The only allowable shapes are CIRCULAR and RECT_CLOSED

9 xsec_XsecType Char
(closed rectangular).

Circular: Diameter (ft or m)

10 xsec_Geom1 Rect_Closed: Full height of the cross-section (ft or m if using metric Float

units)

Circular: Not used

11 xsec_Geom2 Float
Rect_closed: Top width

12 xsec_Geom3 Not used Float

13 xsec_Geom4 Not used Float

Appendix L SWMM GeoPackage Format - 45 / 71 Page 1062 / 1094

 No. Default GIS Attribute Name Description Type

Number of barrels (i.e., number of parallel pipes of equal size, slope,

14 xsec_Barrels Integer
and roughness) associated with a conduit (default is 1).

Code number from Table A.10 for the conduit’s inlet geometry if it is a
15 xsec_Culvert Char
culvert subject to possible inlet flow control (leave blank otherwise).

Name of a Shape Curve in the CURVES section that defines how

16 xsec_Curve Char
cross-section width varies with depth.

Name of an entry in the TRANSECTS section that describes the

17 xsec_Tsect Char
cross-section geometry of an irregular channel.

Name of an entry in the STREETS section that describes the cross-

18 xsec_Street Char
section geometry of a street.

Appendix L SWMM GeoPackage Format - 46 / 71 Page 1063 / 1094

 @4323
@4327 Table L.23: Outlets

Default GIS Attribute

No. Description Type
Name

@4326 1 Name Name assigned to outlet link. Char

2 From Node Name of the outlet’s inlet node. Char

3 To Node Name of the outlet’s outlet node. Char

Amount that the outlet is offset above the invert of its inlet node (ft or m,
4 Offset expressed as either a depth or as an elevation, depending on the Float
LINK_OFFSETS option setting).

TABULAR/DEPTH, TABULAR/HEAD, FUNCTIONAL/DEPTH,

5 Type Char
FUNCTIONAL/HEAD

Name of the rating curve listed in the CURVES section that describes outflow
rate (flow units) as a function of: - water depth above the offset elevation at the
6 QCurve inlet node (ft or m if using metric units) for a TABULAR/DEPTH outlet. - head Char
difference (ft or m) between the inlet and outflow nodes for a TABULAR/HEAD
outlet.

Coefficient of a power function that relates outflow to: - water depth (ft or m if
using metric units) above the offset elevation at the inlet node for a
7 C1 Float
FUNCTIONAL/DEPTH outlet. - head difference (ft or m if using metric units)
between the inlet and outflow nodes for a FUNCTIONAL/HEAD outlet.

Exponent of a power function that relates outflow to: - water depth (ft or m if
using metric units) above the offset elevation at the inlet node for a
8 C2 Float
FUNCTIONAL/DEPTH outlet. - head difference (ft or m if using metric units)
between the inlet and outflow nodes for a FUNCTIONAL/HEAD outlet.

9 Gated YES if a flap gate prevents reverse flow, NO if not (default is NO). Char

Appendix L SWMM GeoPackage Format - 47 / 71 Page 1064 / 1094

 @4332
@4336 Table L.24: Pumps

Default GIS Attribute

No. Description Type
Name

@4335 1 Name Name assigned to pump link. Char

2 From Node Name of the pump’s inlet node. Char

3 To Node Name of the pump’s outlet node. Char

Name of a pump curve listed in the CURVES section of the input. A pump
curve describes the relation between a pump’s flow rate and conditions at its
inlet and outlet nodes. The following types of pump curves are supported:

Type1: An off-line pump with a wet well where flow increases incrementally
with available wet well volume.
Type2: An in-line pump where flow increases incrementally with inlet node
depth.
Type3: An in-line pump where flow varies continuously with head
4 Pcurve difference between the inlet and outlet nodes. Char
Type4: A variable speed in-line pump where flow varies continuously with
inlet node depth.
Type5: A variable speed version of the Type3 pump where the head v. flow
curve shifts position as the speed setting changes.
Ideal: A transfer pump that does not require a pump curve and is used
mainly for preliminary design. Its flow rate equals the inflow rate to its inlet
node no matter what the head difference is between its inlet and outlet
nodes. Use an asterisk (*) as the value for Pcurve.

5 Status Pump’s status at the start of the simulation (either ON or OFF; default is ON). Char

Depth at the inlet node when the pump turns on (ft or m if using metric units)
6 Startup Float
(default is 0).

Depth at inlet node when the pump shuts off (ft or m if using metric units)
7 Shutoff Float
(default is 0).

Appendix L SWMM GeoPackage Format - 48 / 71 Page 1065 / 1094

 @4341
@4345 Table L.25: Streets

Default GIS
No. Description Type
Attribute Name

@4344 1 Name Name assigned to the street cross-section. Char

2 Tcrown Distance from street’s curb to its crown (ft or m if using metric units). Float

3 Hcurb Curb height (ft or m if using metric units). Float

4 Sx Street cross slope (%). Float

5 nRoad Manning’s roughness coefficient (n) of the road surface Float

6 a Gutter depression height (in or mm if using metric units) (default = 0). Float

7 W Depressed gutter width (ft or m if using metric units) (default = 0). Float

8 Sides 1 for single sided street or 2 for two-sided street (default = 2). Integer

9 Tback Street backing width (ft or m if using metric units) (default = 0). Float

10 Sback Street backing slope (%) (default = 0). Float

11 nBack Street backing Manning’s roughness coefficient (n) (default = 0). Float

Appendix L SWMM GeoPackage Format - 49 / 71 Page 1066 / 1094

 @4350
@4354 Table L.26: Transects

Default GIS Attribute

No. Description Type
Name

@4353 1 Name Name assigned to the transect. Char

Station position which ends the left overbank portion of the channel (ft or m if
2 Xleft Char
using metric units).

Station position which begins the right overbank portion of the channel (ft or m
3 Xright Char
if using metric units).

Meander modifier that represents the ratio of the length of a meandering main
4 Lfactor channel to the length of the overbank area that surrounds it (use 0 if not Char
applicable).

Factor by which distances between stations should be multiplied to increase (or

5 Wfactor Char
decrease) the width of the channel (enter 0 if not applicable).

Amount to be added (or subtracted) from the elevation of each station (ft or m if
6 Eoffset Char
using metric units).

Manning’s roughness coefficient (n) of right overbank portion of channel (use 0

7 Nleft Char
if no change from previous NC line).

Manning’s roughness coefficient (n) of right overbank portion of channel (use 0

8 Nright Char
if no change from previous NC line.

Manning’s roughness coefficient (n) of main channel portion of channel (use 0

9 Nchan1 Char
if no change from previous NC line.

Appendix L SWMM GeoPackage Format - 50 / 71 Page 1067 / 1094

 @4359
@4363 Table L.27: Transects Coordinates

Default GIS Attribute

No. Description Type
Name

@4362 1 Name Name assigned to the transect. Char

Elevation of the channel bottom at a cross-section station relative to some fixed

2 Elev Float
reference (ft or m if using metric units).

Distance of a cross-section station from some fixed reference (ft or m if using

3 Station Float
metric units).

Appendix L SWMM GeoPackage Format - 51 / 71 Page 1068 / 1094

 @4368
@4372 Table L.28: Weirs

No. Default GIS Attribute Name Description Type

@4371 1 Name Name assigned to weir link. Char

2 From Node Name of the weir’s inlet node. Char

3 To Node Name of the weir’s outlet node. Char

TRANSVERSE, SIDEFLOW, V-NOTCH, TRAPEZOIDAL or

4 Type Char
ROADWAY.

Amount that the weir’s opening is offset above the invert of inlet node
5 CrestHt (ft or m if using metric units, expressed as either a depth or as an Float
elevation, depending on the LINK_OFFSETS option setting).

Weir discharge coefficient (for CFS if using US flow units or CMS if

6 Cd Float
using metric flow units).

7 Gated YES if a flap gate prevents reverse flow, NO if not (default is NO). Char

Number of end contractions for a TRANSVERSE or TRAPEZOIDAL

8 EC Char
weir (default is 0).

Discharge coefficient for the triangular ends of a TRAPEZOIDAL weir

9 Cd2 (for CFS if using US flow units or CMS if using metric flow units) Float
(default is the value of Cd).

YES if the weir can surcharge (have an upstream water level higher
10 Sur Char
than the height of the weir’s opening); NO if it cannot (default is YES).

Applies only to ROADWAY weirs. Width of road lanes and shoulders

11 Road_Width Float
for a ROADWAY weir (ft or m if using metric units).

Applies only to ROADWAY weirs. Type of road surface for a

12 Road_Surf Char
ROADWAY weir: PAVED or GRAVEL.

Appendix L SWMM GeoPackage Format - 52 / 71 Page 1069 / 1094

 No. Default GIS Attribute Name Description Type

A cross-section shape. The following shapes must be used with each

type of weir:

Transverse: RECT_OPEN
Sideflow: RECT_OPEN
V-Notch: TRIANGULAR
Trapezoidal: TRAPEZOIDAL
Roadway: RECT_OPEN

13 xsec_XsecType The ROADWAY weir is a broad crested rectangular weir used model Char
roadway crossings usually in conjunction with culvert-type conduits. It
uses the FHWA HDS-5 method to determine a discharge coefficient as
a function of flow depth and roadway width and surface. If no roadway
data are provided then the weir behaves as a TRANSVERSE weir with
Cd as its discharge coefficient. Note that if roadway data are provided,
then values for the other optional weir parameters (NO for Gated, 0 for
EC, 0 for Cd2, and NO for Sur) must be entered even though they do
not apply to ROADWAY weirs.

14 xsec_Geom1 Full height of the cross-section (ft or m if using metric units) Float

Trapezoidal: Base Width

15 xsec_Geom2 Float
Rect_open and Triangular: Top width

Trapezoidal: Left Slope

16 xsec_Geom3 Float
Rect_open and Triangular: Not used

Trapezoidal: Right slope

17 xsec_Geom4 Float
All other shapes: Not used

Number of barrels (i.e., number of parallel pipes of equal size, slope,

18 xsec_Barrels Integer
and roughness) associated with a conduit (default is 1).

Appendix L SWMM GeoPackage Format - 53 / 71 Page 1070 / 1094

 No. Default GIS Attribute Name Description Type

Code number from Table A.10 for the conduit’s inlet geometry if it is a
19 xsec_Culvert Char
culvert subject to possible inlet flow control (leave blank otherwise).

Name of a Shape Curve in the CURVES section that defines how

20 xsec_Curve Char
cross-section width varies with depth.

Name of an entry in the TRANSECTS section that describes the

21 xsec_Tsect Char
cross-section geometry of an irregular channel.

Name of an entry in the STREETS section that describes the cross-

22 xsec_Street Char
section geometry of a street.

Appendix L SWMM GeoPackage Format - 54 / 71 Page 1071 / 1094

 @4377
@4381 Table L.29: Dividers

Default GIS Attribute

No. Description Type
Name

@4380 1 Name Name assigned to divider node. Char

2 Elev Node’s invert elevation (ft or m if using metric units). Float

3 DivLink Name of the link to which flow is diverted. Char

4 Type OVERFLOW: CUTOFF: TABULAR: WEIR: Char

CUTOFF and WEIR: flow at which diversion begins (flow units).

5 Qmin Float
OVERFLOW and TABULAR: Not Used.

TABULAR: name of a curve that relates diverted flow to total flow.

6 Dcurve Float
OVERFLOW, CUTOFF and WEIR: Not Used.

WEIR: height of a WEIR divider (ft or m).

7 Ht Float
OVERFLOW, CUTOFF and TABULAR: Not Used.

WEIR: discharge coefficient for a WEIR divider.

8 Cd Float
OVERFLOW, CUTOFF and TABULAR: Not Used.

OVERFLOW, CUTOFF, TABULAR and WEIR: depth from the ground to the
9 Ymax Float
node’s invert elevation (ft or m if using metric units) (default is 0).

OVERFLOW, CUTOFF, TABULAR and WEIR: water depth at the start of the
10 Y0 Float
simulation (ft or m if using metric units) (default is 0).

OVERFLOW, CUTOFF, TABULAR and WEIR: maximum additional pressure

11 Ysur head above the ground elevation that the node can sustain under surcharge Float
conditions (ft or m if using metric units) (default is 0).

Appendix L SWMM GeoPackage Format - 55 / 71 Page 1072 / 1094

 Default GIS Attribute
No. Description Type
Name

OVERFLOW, CUTOFF, TABULAR and WEIR: area subjected to surface

12 Apond ponding once water depth exceeds Ymax + Ysur (ft2 or m2 if using metric Float
units) (default is 0).

@4386
@4390 Table L.30: DWF

Default GIS Attribute

No. Description Type
Name

@4389 1 Node Name of a node where dry weather flow enters. Char

2 Type Keyword FLOW for flow or a pollutant name for a quality constituent. Char

Average baseline value for corresponding constituent (flow or concentration

units). The actual dry weather input will equal the product of the baseline value
3 Base Float
and any adjustment factors supplied by the specified patterns. If not supplied,
an adjustment factor defaults to 1.0.

Name of first time pattern appearing in the PATTERNS section. The patterns
4 Pat1 can be any combination of monthly, daily, hourly and weekend hourly patterns, Char
listed in any order. See the PATTERNS section for more details.

Name of second time pattern appearing in the PATTERNS section. The

5 Pat2 patterns can be any combination of monthly, daily, hourly and weekend hourly Char
patterns, listed in any order. See the PATTERNS section for more details.

Name of third time pattern appearing in the PATTERNS section. The patterns
6 Pat3 can be any combination of monthly, daily, hourly and weekend hourly patterns, Char
listed in any order. See the PATTERNS section for more details.

Name of fourth time pattern appearing in the PATTERNS section. The

7 Pat4 patterns can be any combination of monthly, daily, hourly and weekend hourly Char
patterns, listed in any order. See the PATTERNS section for more details.

Appendix L SWMM GeoPackage Format - 56 / 71 Page 1073 / 1094

 @4395
@4399 Table L.31: Junctions

Default GIS Attribute

No. Description Type
Name

@4398 1 Name Name assigned to junction node. Char

2 Elev Elevation of the junction’s invert (ft or m if using metric units). Float

Depth from ground to invert elevation (ft or m if using metric units). Default is 0.

3 Ymax If Ymax is 0 then SWMM sets the junction’s maximum depth to the distance Float

from its invert to the top of the highest connecting link.

Water depth at the start of the simulation (ft or m if using metric units). Default
4 Y0 Float
is 0.

Maximum additional pressure head above the ground elevation that the
junction can sustain under surcharge conditions (ft or m if using metric units).

5 Ysur Default is 0. Char

If the junction is part of a force main section of the system then set Ysur to the
maximum pressure that the system can sustain.

Area subjected to surface ponding once water depth exceeds Ymax + Ysur (ft2
or m2 if using metric units). Default is 0.
6 Apond Float
Surface ponding can only occur when Apond is non-zero and the
ALLOW_PONDING analysis option is turned on.

Appendix L SWMM GeoPackage Format - 57 / 71 Page 1074 / 1094

 @4404
@4408 Table L.32: Outfalls

Default GIS Attribute

No. Description Type
Name

@4407 1 Name Name assigned to outfall node. Char

2 Elev Node’s invert elevation (ft or m if using metric units). Float

3 Type Use either FREE, NORMAL, FIXED, TIDAL or TIMESERIES. Char

FIXED: Elevation of a fixed stage outfall (ft or m).

4 Stage Char
FREE, NORMAL, TIDAL and TIMESERIES: Not Used.

TIDAL: Name of a curve in the CURVES section containing tidal height (i.e.,

5 Tcurve outfall stage) v. hour of day over a complete tidal cycle. Char

FREE, NORMAL, FIXED and TIMESERIES: Not Used.

TIMESERIES: Name of a time series in TIMESERIES section that describes

6 Tseries how outfall stage varies with time. Char

FREE, NORMAL, FIXED and TIDAL: Not Used.

YES or NO depending on whether a flap gate is present that prevents reverse

7 Gated Char
flow. The default is NO.

Optional. Name of a subcatchment that receives the outfall’s discharge. The

8 RouteTo Char
default is not to route the outfall’s discharge.

Appendix L SWMM GeoPackage Format - 58 / 71 Page 1075 / 1094

 @4413
@4417 Table L.33: Storage

Default GIS Attribute

No. Description Type
Name

@4416 1 Name Name assigned to storage node. Char

2 Elev Node’s invert elevation (ft or m if using metric units). Float

3 Ymax Water depth when the storage node is full (ft or m if using metric units). Float

4 Y0 Water depth at the start of the simulation (ft or m if using metric units). Float

TABULAR:

FUNCTIONAL:

CYLINDRICAL:
5 TYPE Char
CONICAL:

PARABOLOID:

PYRAMIDAL:

Name of a curve in the CURVES section that relates surface area (ft2 or m2 if
6 Acurve using metric units) to depth (ft or m if using metric units) for TABULAR Char
geometry.

Coefficient of a FUNCTIONAL relation between surface area and depth. Where

7 A1 Float
Area = A0 + A1*DepthA2.

8 A2 Exponent of a FUNCTIONAL relation between surface area and depth. Float

9 A0 Constant of a FUNCTIONAL relation between surface area and depth. Float

Appendix L SWMM GeoPackage Format - 59 / 71 Page 1076 / 1094

 Default GIS Attribute
No. Description Type
Name

CYLINDRICAL: major axis length

CONICAL: major axis length of base

10 L Float
PARABOLOID: major axis length at full height

PYRAMIDAL: base length

CYLINDRICAL: major axis width

CONICAL: major axis width of base

11 W Float
PARABOLOID: minor axis width at full height

PYRAMIDAL: base width

CYLINDRICAL: Not Used.

CONICAL: side slope (run/rise)

12 Z Float
PARABOLOID: full height

PYRAMIDAL: side slope (run/rise)

Maximum additional pressure head above full depth that a closed storage unit
13 Ysur can sustain under surcharge conditions (ft or m if using metric units) (default is Float
0).

Fraction of potential evaporation from the storage unit’s water surface realized
14 Fevap Float
(default is 0).

Optional seepage parameters for soil surrounding the storage unit. Suction
15 Psi Float
head (inches or mm if using metric units).

Optional seepage parameters for soil surrounding the storage unit. Saturated
16 Ksat Float
hydraulic conductivity (in/hr or mm/hr if using metric units).

Appendix L SWMM GeoPackage Format - 60 / 71 Page 1077 / 1094

 Default GIS Attribute
No. Description Type
Name

Optional seepage parameters for soil surrounding the storage unit. Initial
17 IMD Float
moisture deficit (porosity minus moisture content) (fraction).

@4422
@4426 Table L.34: Files

Default GIS Attribute

No. Description Type
Name

@4425 1 Operation Set if the interface file is to be used (USE) or saved (SAVE) by a run. Char

The different types of interface files that are currently available include:

RAINFALL: rainfall interface file (USE / SAVE operation)

RUNOFF: runoff interface file (USE / SAVE operation)
HOTSTART: hot start file (USE / SAVE operation)
2 Filetype RDII: RDII interface file (USE / SAVE operation) Char
INFLOWS: routing interface files (USE operation only)
OUTFLOWS: routing interface files (SAVE operation only)

Rainfall, Runoff, and RDII files can either be used or saved in a run, but not
both. A run can both use and save a Hot Start file (with different names).

The name of an interface file. Enclose the external file name in double quotes
3 Filename if it contains spaces and include its full path if it resides in a different directory Char
than the SWMM input file.

@4431
@4435 Table L.35: Options

Default GIS Attribute

No. Description Type
Name

@4434 Keyword (See Table 6.1 for a full list of keywords, associated values, and
1 Option Char
defaults.)

2 Value Value Char

Appendix L SWMM GeoPackage Format - 61 / 71 Page 1078 / 1094

 @4440
@4444 Table L.36: Report

Default GIS Attribute

No. Description Type
Name

@4443 INPUT specifies whether or not a summary of the input data should be
provided in the output report. The default is NO.

CONTINUITY specifies whether continuity checks should be reported or not.

The default is YES.

FLOWSTATS specifies whether summary flow statistics should be reported or

not. The default is YES.

CONTROLS specifies whether all control actions taken during a simulation

should be listed or not. The default is NO.

SUBCATCHMENTS gives a list of subcatchments whose results are to be

1 Format Char
reported. The default is NONE.

NODES gives a list of nodes whose results are to be reported. The default is
NONE.

LINKS gives a list of links whose results are to be reported. The default is
NONE.

LID specifies that the LID control Name in subcatchment Subcatch should have
a detailed performance report for it written to file Fname.

The SUBCATCHMENTS, NODES, LINKS, and LID lines can be repeated

multiple times.

Appendix L SWMM GeoPackage Format - 62 / 71 Page 1079 / 1094

 Default GIS Attribute
No. Description Type
Name

INPUT: YES / NO

CONTINUITY: YES / NO

FLOWSTATS: YES / NO

CONTROLS: YES / NO
2 Value Char
SUBCATCHMENTS: ALL / NONE /

NODES: ALL / NONE /

LINKS: ALL / NONE /

LID: Name Subcatch Fname

@4449
@4453 Table L.37: Title

Default GIS Attribute

No. Description Type
Name

@4452 Any number of lines may be entered. The first line will be used as a page
1 Title Char
header in the output report.

Appendix L SWMM GeoPackage Format - 63 / 71 Page 1080 / 1094

 @4458
@4462 Table L.38: Subcatchments

No. Default GIS Attribute Name Description Type

@4461 1 Name Name assigned to the subcatchment. Char

Name of a rain gage in the RAINGAGES section assigned to the

2 Rain Gage Char
subcatchment.

Name of the node or subcatchment that receives runoff from the

3 Outlet Char
subcatchment.

4 Area Area of the subcatchment (acres or hectares if using metric units). Float

5 PctImperv Percentage of the subcatchment’s area that is impervious. Float

Characteristic width of the subcatchment (ft or m, if using metric

6 Width Float
units).

7 PctSlope The subcatchment’s slope (percent). Float

Total curb length (any length units) used to describe pollutant

8 CurbLen Float
buildup. Use 0 if not applicable.

Optional name of a snow pack object (from the SNOWPACKS

9 SnowPack section) that characterizes snow accumulation and melting over the Char
subcatchment.

Manning’s coefficient (n) for overland flow over the impervious sub-
10 Subareas_Nimp Float
area.

Manning’s coefficient (n) for overland flow over the pervious sub-
11 Subareas_Nperv Float
area.

Depression storage for the impervious sub-area (inches or mm, if

12 Subareas_Simp Float
using metric units).

Depression storage for the pervious sub-area (inches or mm, if

13 Subareas_Sperv Float
using metric units).

Appendix L SWMM GeoPackage Format - 64 / 71 Page 1081 / 1094

 No. Default GIS Attribute Name Description Type

14 Subareas_PctZero Percent of impervious area with no depression storage. Float

IMPERVIOUS if pervious area runoff runs onto impervious area,

PERVIOUS if impervious runoff runs onto pervious area, or
15 Subareas_RouteTo Char
OUTLET if both areas drain to the subcatchment’s outlet (default =
OUTLET).

Percent of runoff routed from one type of area to another (default =

16 Subareas_PctRouted Float
100).

HORTON and MODIFIED_HORTON: maximum infiltration rate on

the Horton curve (in/hr or mm/hr).

17 Infiltration_p1 GREEN-AMPT and MODIFIED_GREEN_AMPT: soil capillary Float

suction (in or mm if using metric units).

CURVE_NUMBER: SCS Curve Number.

HORTON and MODIFIED_HORTON: minimum infiltration rate on

the Horton curve (in/hr or mm/hr if using metric units).

18 Infiltration_p2 GREEN-AMPT and MODIFIED_GREEN_AMPT: soil saturated Float

hydraulic conductivity (in/hr or mm/hr if using metric units).

CURVE_NUMBER: no longer used.

HORTON and MODIFIED_HORTON: decay rate constant of the

Horton curve (1/hr).

GREEN-AMPT and MODIFIED_GREEN_AMPT: initial soil moisture

19 Infiltration_p3 Float
deficit (porosity minus moisture content) (fraction).

CURVE_NUMBER: time it takes for a fully saturated soil to dry

(days).

Appendix L SWMM GeoPackage Format - 65 / 71 Page 1082 / 1094

 No. Default GIS Attribute Name Description Type

HORTON and MODIFIED_HORTON: time it takes for a fully

saturated soil to dry (days).
20 Infiltration_p4 Float
GREEN-AMPT, MODIFIED_GREEN_AMPT and
CURVE_NUMBER: Not Used.

HORTON and MODIFIED_HORTON: maximum infiltration volume

possible (0 if not applicable) (in or mm if using metric units).
21 Infiltration_p5 Float
GREEN-AMPT, MODIFIED_GREEN_AMPT and
CURVE_NUMBER: Not Used.

Either HORTON, MODIFIED_HORTON, GREEN_AMPT,

MODIFIED_GREEN_AMPT, or CURVE_NUMBER.
22 Infiltration_Method Char
If not specified then the infiltration method supplied in the
OPTIONS section is used.

Appendix L SWMM GeoPackage Format - 66 / 71 Page 1083 / 1094

 @4467
@4471 Table L.39: Buildup

Default GIS Attribute

No. Description Type
Name

@4470 1 Landuse Land use name. Char

2 Pollutant Pollutant name. Char

Buildup function type.

POW (Power): Min(C1, C2*tC3)

EXP (Exponential): C1(1-exp(-C2t))

3 FuncType SAT (Saturation): (C1*t)/(C3+t) Char

EXT (External): C1 is the maximum possible buildup (mass per area or curb
length), C2 is a scaling factor, and C3 is the name of a Time Series that
contains buildup rates (as mass per area or curb length per day) as a function
of time.

4 C1 Buildup function parameters (see FuncType). Float

5 C2 Buildup function parameters (see FuncType). Float

6 C3 Buildup function parameters (see FuncType). Float

7 PerUnit AREA if buildup is per unit area, CURBLENGTH if per length of curb. Char

@4476
@4480 Table L.40: Coverages

No. Default GIS Attribute Name Description Type

@4479 1 Subcatchment Subcatchment name. Char

2 Landuse Land use name. Char

3 Percent Percent of the subcatchment’s area covered by the land use Float

Appendix L SWMM GeoPackage Format - 67 / 71 Page 1084 / 1094

 @4485
@4489 Table L.41: Landuses

No. Default GIS Attribute Name Description Type

@4488 1 Name Land use name. Char

2 SweepIntervalDays Days between street sweeping. Float

Fraction of pollutant buildup available for removal by street

3 AvailabilityFract Float
sweeping.

4 LastSweepDays Days since last sweeping at the start of the simulation. Float

@4494
@4498 Table L.42: Loadings

No. Default GIS Attribute Name Description Type

@4497 1 Subcatchment Name of a subcatchment. Char

2 Landuse Name of a pollutant. Char

Initial buildup of the pollutant (lbs/acre or kg/hectare). If an initial buildup

is not specified for a pollutant, then its initial buildup is computed by
3 Percent Float
applying the DRY_DAYS option (specified in the OPTIONS section) to
the pollutant’s buildup function for each land use in the subcatchment.

Appendix L SWMM GeoPackage Format - 68 / 71 Page 1085 / 1094

 @4503
@4507 Table L.43: Pollutants

Default GIS Attribute

No. Description Type
Name

@4506 Name assigned to a pollutant. Note, FLOW is a reserved word and cannot be
1 Name Char
used to name a pollutant.

Concentration units (MG/L for milligrams per liter, UG/L for micrograms per liter,
2 Units Char
or #/L for direct count per liter).

3 Crain Concentration of the pollutant in rainfall (concentration units). Float

4 Cgw Concentration of the pollutant in groundwater (concentration units). Float

5 cii Concentration of the pollutant in inflow/infiltration (concentration units). Float

6 Kdecay First-order decay coefficient (1/days). Float

YES if pollutant buildup occurs only when there is snow cover, NO otherwise
7 Sflag Char
(default is NO).

8 CoPoll Name of a co-pollutant (default is no co-pollutant designated by a *). Char

Fraction of the co-pollutant’s concentration (default is 0). When pollutant X has

a co-pollutant Y, it means that fraction CoFract of pollutant Y’s runoff
9 CoFract Float
concentration is added to pollutant X’s runoff concentration when wash off from
a subcatchment is computed.

Pollutant concentration in dry weather flow (default is 0). If there is no co-

pollutant but non-default values, then enter an asterisk (*) for the co-pollutant
10 Cdwf name. The dry weather flow concentration can be overridden for any specific Float
node of the conveyance system by editing the node’s Inflows property (see the
INFLOWS section).

Pollutant concentration throughout the conveyance system at the start of the

11 Cinit simulation (default is 0). If there is no co-pollutant but non-default values, then Float
enter an asterisk (*) for the co-pollutant name.

Appendix L SWMM GeoPackage Format - 69 / 71 Page 1086 / 1094

 @4512
@4516 Table L.44: Treatment

Default GIS Attribute

No. Description Type
Name

@4515 1 Node Name of the node where treatment occurs. Char

2 Pollut Name of pollutant receiving treatment. Char

Result computed by treatment function. Choices are:

3 Result C (function computes effluent concentration) Char

R (function computes fractional removal)

Mathematical function expressing treatment result in terms of pollutant

concentrations, pollutant removals, and other standard variables. Treatment
functions can be any well-formed mathematical expression involving:

inlet pollutant concentrations (use the pollutant name to represent a

concentration)

removal of other pollutants (use R_ pre-pended to the pollutant name to

represent removal)

4 Func Char
process variables which include:

FLOW: for flow rate into node (user’s flow units)

DEPTH: for water depth above node invert (ft or m)

AREA: for node surface area (ft2 or m2)

DT: for routing time step (seconds)

HRT: for hydraulic residence time (hours)

Appendix L SWMM GeoPackage Format - 70 / 71 Page 1087 / 1094

 @4521
@4525 Table L.45: Washoff

Default GIS Attribute

No. Description Type
Name

@4524 1 Landuse Land use name. Char

2 Pollutant Pollutant name. Char

Washoff function type. Each washoff function expresses its results in

different units. Available types:

EXP (Exponential): C1(runoff)C2 (buildup) [Mass/hour]. Runoff variable

is expressed in catchment depth per unit of time (in/hr or mm/hr if using
metric units). Char
3 FuncType
RC (Rating Curve): C1(runoff)C2 [Mass/sec]. Runoff variable is in
whatever flow units were specified in the OPTIONS section of the input
file (e.g. CFS, CMS, etc.).

EMC (Event Mean Concentration) C1 [Mass/Liter].

Washoff function coefficients. See FuncType.

EXP: units are (in/hr)-C2 per hour or (mm/hr)-C2 per hour if using metric
4 C1 units. Float

RC: units depend on the flow units employed.

EMC: concentration units.

5 C2 Washoff function coefficients. See FuncType. Float

6 SweepRmv1 Street sweeping removal efficiency (percent). Float

7 BmpRmv1 BMP removal efficiency (percent). Float

Appendix L SWMM GeoPackage Format - 71 / 71 Page 1088 / 1094

 @4534

@4535
References

@4536M. and Nair S. (2003). Flow Computations at STA-1 West Gated Spillways. South Florida
Ansar
Water Management District.

Australian Emergency Management Institute. (2014). Australian Emergency Management

Handbook 7: Managing Floodplain Best Practice in Flood Risk Management in Australia.
https://knowledge.aidr.org.au/media/3521/adr-handbook-7.pdf

Austroads. (1994). Waterway Design - a Guide to the Hydraulic Design of Bridges, Culverts and
Floodways. https://austroads.com.au/

Austroads. (2018). Guide to Bridge Technology Part 8, Hydraulic Design of Waterway Structures.
https://austroads.com.au/

Babister, M., & Barton, C. (2012). Two Dimensional Modelling in Urban and Rural Floodplains
Stage 1 & 2 Report.
https://arr.ga.gov.au/__data/assets/pdf_file/0019/40573/ARR_Project15_TwoDimensional_Mod
elling_DraftReport.pdf

Barton, C. (2001). Flow Through an Abrupt Constriction – 2D Hydrodynamic Model Performance

and Influence of Spatial Resolution (C. Barton, Ed.) [M.Eng.Sc Master Thesis].
https://tuflow.com/media/4983/2001-flow-through-an-abrupt-constriction-2d-hydrodynamic-
performance-and-influence-of-spatial-resolution-barton-thesis.pdf

Benham, S., & Rogencamp, G. (2003). Appliction of 2D Flood Models with 1D Drainage Elements.
NSW FMA Conference. ?

Bos, M. (1976). Discharge Measurement Structures (Publication No. 161). Delft Hydraulic
Laboratory. https://www.samsamwater.com/library/pub20.pdf

Bos, M. (1989). Discharge Measurement Structures (3rd revised edition.). International Institute
for Land Reclamation; Improvement. https://www.samsamwater.com/library/pub20.pdf

Boyte, C. (2014). The Application of Direct Rainfall Models as Hydrologic Models Incorporating
Hydraulic Resistance at Shallow Depths [B.Eng Thesis]. https://tuflow.com/media/5009/2014-
the-application-of-direct-rainfall-models-as-hydrologic-models-incorporating-hydraulic-
resistance-at-shallow-depths-boyte-thesis.pdf

Bradley, J. (1978). Hydraulics of Bridge Waterways (HDS 1, FIWA). Bridge Division.

https://www.fhwa.dot.gov/engineering/hydraulics/pubs/hds1.pdf

CIWEM. (2009). Integrated Urban Drainage Modelling Guide. CIWEM.

Collecutt, G., Baeumer, U., Gao, S., & Syme, W. (2022). Bridge Deck Afflux Modelling –
Benchmarking of CFD and SWE Codes to Real-World Data. Hydrology & Water Resources

References - 1 / 6 Page 1089 / 1094

 Symposium. https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-
of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf

Collecutt, G., Gao, S., & Syme, W. (2020). Mesh-Size Insensitive Turbulence Modelling for the 2D
Shallow Water Equations. River Flow 2020, pp. 1–9. https://tuflow.com/media/5023/2020-
mesh-size-insensitive-turbulence-modelling-for-the-2d-shallow-water-equations-collecutt-et-al-
iahr-river-flow-delft.pdf

Collecutt, G., & Syme, B. (2017). Experimental Benchmarking of Mesh Size and Time-Step
Convergence for a 1st and 2nd Order SWE Finite Volume Scheme. Proceedings of the 37th
IAHR World Congress. https://www.tuflow.com/Download/Publications/07-31-1369.pdf

Cox, R., Shard, T., & Blacka, M. (2010). Australian Rainfall and Runoff Revision Project 10:
Appropriate Safety Criteria for People. Austalian Institute of Engineers.
https://arr.ga.gov.au/__data/assets/pdf_file/0006/40578/ARR_Project_10_Stage1_report_Final.
pdf

CSIRO. (2000). Floodplain Management in Australia Best Practice Principles and Guidelines.
CSIRO Publishing.

DEFRA. (2006a). DEFRA r&d Outputs: Flood Risks to People Phase Two Draft FD2321/TR1 and
TR2. DEFRA.
https://assets.publishing.service.gov.uk/media/602bbc3de90e07055f646148/Flood_risks_to_pe
ople_-_Phase_2_Guidance_Document_Technical_report.pdf

DEFRA. (2006b). Flood Risks to People Phase 2 FD2321/TR1 the Flood Risks to People
Methodology. DEFRA.
https://assets.publishing.service.gov.uk/media/602bbc768fa8f50383c41f80/Flood_risks_to_peo
ple_-_Phase_2_The_flood_risks_to_people_methodology_technical_report.pdf

DHI. (2009). MOUSE PIPE FLOW – Reference Manual. Danish Hydraulic Institute.
https://manuals.mikepoweredbydhi.help/2017/Cities/MOUSEPipeFlowReference.pdf

Environment Agency. (2004). Tidal Thames Embayment Inundation Study. EA, Halcrow, TUFLOW.

Environment Agency. (2006). UK FD2321 Technical Report - Flood Risks to People: Phase 2
Project Record. UK Government;
https://assets.publishing.service.gov.uk/media/602bbb768fa8f50386a7f8aa/Flood_risks_to_peo
ple_-_Phase_2_Project_Record.pdf.

Environment Agency. (2008). Explanatory Note for FD2320 and FD2321 Project Record.
https://assets.publishing.service.gov.uk/media/602bbdcfe90e070561b31432/Explanatory_note
_for_FD2320_and_FD2321_project_record.pdf.

Environment Agency. (2010). The Fluvial Design Guide. Environment Agency.

Falconer, R. A., Lin, B., & Kashefipour, S. M. (2005). Modelling Water Quality Processes in
Estuaries. In P. B. Bates, S. N. Lane, & R. I. Furguson (Eds.), Computational fluid dynamics:
Applications in environmental hydraulics. John Wiley; Sons.

Fringer, O. B., Armfield, S. W., & Street, R. L. (2005). Reducing Numerical Diffusion in Interfacial
Gravity Wave Simulations. International Journal for Numerical Methods in Fluids, 49, 301–329.

References - 2 / 6 Page 1090 / 1094

 Gao, S., Ryan, P., Syme, W., & Collecutt, G. (2022). The End of the 1D Open Channel Cross-
Section? Hydrology & Water Resources Symposium. https://tuflow.com/media/7547/2022-the-
end-of-the-1d-open-channel-cross-section-gao-et-al-hwrs.pdf

GHD. (2011). MBRC Storm Tide Management Study: Stage 1 – Scoping Report.

Hamilton City Council. (2012). Flood Mapping. https://hamilton.govt.nz/property-rates-and-

building/district-plan/flood-mapping/.

Henderson, F. (1966). Open Channel Flow. Macmillan.

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

HR Wallingford. (1988). Afflux at Arch Bridges. https://eprints.hrwallingford.com/219/1/SR182-

Afflux-arch-bridges-HRWallingford.pdf

Huxley, C. (2004). TUFLOW Testing and Validation (B. ENG. Christopher Dylan Huxley, Ed.)
[Thesis].
https://www.tuflow.com/Download/Publications/TUFLOW%20Validation%20and%20Testing,%2
0Huxley,%202004.pdf

Huxley, C., Syme, W., Ryan, P., & Collecutt, G. (2022). Hydraulic Modelling 2D Cell Size Result
Convergence – Comparing the Performance of Different Shallow Water Equation Solution
Schemes. Hydrology and Water Resources Symposium, Engineers Australia.
https://www.tuflow.com/media/7555/2022-hydraulic-modelling-2d-cell-size-result-convergence-
huxley-et-al-hwrs.pdf

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

Leonard, B. P. (1991). The ULTIMATE Conservative Difference Scheme Applied to Unsteady One-
Dimensional Advection. Computer Methods in Applied Mechanics and Engineering, 88(1), 17–
74.

Leonard, B. P., MacVean, M. K., & Lock, A. P. (1993). Positivity-Preserving Numerical Schemes for
Multidimensional Advection (No. 93N27091). NASA Centre for Aerospace Information.

Leonard, B. P., & Niknafs, H. S. (1991). Cost-Effective Accurate Coarse-Grid Method for Highly
Convective Multidimensional Unsteady Flows (No. 91N21075). NASA Centre for Aerospace
Information.

McDonnell, B., Wu, J. X., Ratliff, K., Mullapudi, A., & Tryby, M. (2021). Open Water Analytics
Stormwater Management Model (Version 5.1.13). Zenodo.
https://doi.org/10.5281/zenodo.5484299

Melbourne Water. (2016). Flood Mapping Projects Guidelines and Technical Specifications
(Version 1).

Miller, D. (1994). Discharge Characteristics IAHR Hydraulic Structures Design Manual (No. No.8;
pp. 249 pages). Hydraulic Design Considerations, Balkema Publ.

References - 3 / 6 Page 1091 / 1094

 Morrison, W., & Smith, P. (1978). A Practical Application of a Network Model Numerical Simulation
of Fluid Motion. North Holland Publishing Company.

Neelz, S., & Pender, G. (2013). Benchmarking the Latest Generation of 2D Hydaulic Modeling
Packages. Environment Agency. https://doi.org/SC120002/R

NSW Goverment. (2005a). Floodplain Development Manual: The Management of Flood Liable
Land (pp. 149 pages). Department of Infrastructure, Planning; Natural Resources (NSW
Government). https://www.environment.nsw.gov.au/-/media/OEH/Corporate-
Site/Documents/Water/Floodplains/floodplain-development-manual.pdf

NSW Goverment. (2005b). Floodplain Management Manual. NSW Department of Land; Water
Conservation (NSW Government).

Ollett, P., & Syme, B. (2016). ARR blockage: Numerical implementation and three case studies.
http://www.hydralinc.com/wp-content/uploads/Ollett-Syme-2016-ARR-Blockage.pdf

Port Macquarie-Hastings Council. (2018). PORT MACQUARIE-HASTINGS COUNCIL FLOOD

POLICY. https://www.pmhc.nsw.gov.au/files/assets/public/v/1/document-files/your-
council/publications/policies/port-macquarie-hastings-council-flood-adopted-2018-12-12.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

Queensland Reconstruction Authority. (2012). Planning for Stronger, More Resilient Fl Oodplains:
Part 2. https://www.qra.qld.gov.au/sites/default/files/2018-10/resilient-floodplains-part2-
full_0.pdf.

Rawls, W., Brakesiek, J., & Miller, N. (1983). Green-Ampt Infiltration Parameters from Soils Data.
Journal of Hydraulic Engineering, vol 109, 62–71.

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

Stelling, G. (1984). On the Construction of Computational Methods for Shallow Water Flow
Problems. Rijkswaterstaat Communications.

Syme, W. (1991). Dynamically Linked Two Dimensional / One-Dimensional Hydrodynamic

Modelling Program for Rivers, Estuaries and Coastal Waters (W. Syme, Ed.) [M.Eng.Sc(100%
Research) Thesis]. Dept of Civil Engineering. https://tuflow.com/media/4982/1991-tuflow-
dynamically-linked-2d-and-1d-hydrodynamic-modelling-syme-thesis.pdf

Syme, W. (2001a). Modelling of Bends and Hydraulic Structures in a Two-Dimensional Scheme.

The Institution of Engineers, Australia Conference on Hydraulics in Civil Engineering.
https://tuflow.com/media/4984/2001-modelling-of-bends-and-hydraulic-structures-in-a-2d-
scheme-syme.pdf

Syme, W. (2001b). TUFLOW – Two & One-Dimensional Unsteady FLOW Software for Rivers,
Estuaries and Coastal Waters. The Institution of Engineers, Australia 2D Seminar.

References - 4 / 6 Page 1092 / 1094

 https://tuflow.com/media/4985/2001-tuflow-two-and-one-dimensional-unsteady-flow-software-
for-rivers-estuaries-and-coastal-waters-syme.pdf

Syme, W. (2008). Flooding in Urban Areas - 2D Modelling Approaches for Buildings and Fences.
Engineers Australia, 9th National COnference on Hydraulics in Water Enginnering.
https://tuflow.com/media/4997/2008-flooding-in-urban-areas-2d-modelling-approaches-for-
buildings-and-fences-syme-hwe-aus.pdf

Syme, W., Nielsen, C., & Charteris, A. (1998). Comparison of Two-Dimensional Hydrodynamic
Modelling Systems Part One - Flow Through a Constriction. International Conference on
Hydraulics in Civil Engineering.

TUFLOW. (2018). TUFLOW Classic/HPC User Manual Build 2018-03-AD.

https://downloads.tuflow.com/TUFLOW/Releases/2018-03/TUFLOW%20Manual.2018-03-
AD.pdf

TUFLOW. (2020). TUFLOW Classic and HPC 2020-01 and 2020-10 Release Notes.
https://downloads.tuflow.com/TUFLOW/Releases/2020-
10/TUFLOW%20Release%20Notes.2020-10-AF.pdf

Tullis, B., & Robinson, S. (2008). Quantifying Culvert Exit Loss. Journal of Irrigation and Drainage
Engineering, Vol. 134(No. 2), pp. 263–266.

USACE. (1977). Hydraulic Design Criteria-Sheets 312. US Army Corp of Engineers.

https://apps.dtic.mil/sti/tr/pdf/ADA092238.pdf

USACE. (1987). Hydraulic Design Criteria-Sheets 111-1 to 111-14. US Army Corp of Engineers.
https://apps.dtic.mil/sti/tr/pdf/ADA092237.pdf

USBR. (1987). Design of Small Dams [Technology & Engineering]. U.S. Dept. of the Interior,
Bureau of Reclamation, 1987-. https://www.usbr.gov/tsc/techreferences/mands/mands-
pdfs/SmallDams.pdf

USDA. (1986). Urban Hydrology for Small Watersheds Technical Release 55 (TR-55).
https://nationalstormwater.com/wp/wp-content/uploads/2020/07/Urban-Hydrology-for-Small-
Watersheds-TR-55.pdf

Weeks, W., Barthelmess, A., Rigby, E., Witheridge, G., & Adamson, R. (2009). Australian Rainfall
and Runoff Revision Project 11: Blockage of Hydraulic Structures. Austalian Institute of
Engineers. https://doi.org/P11/S1/007

Weeks, W., Witheridge, G., Rigby, E., Barthelmess, A., & O’Loughlin, G. (2013). Australian Rainfall
and Runoff Revision Project 11: Blockage of Hydraulic Structures. Austalian Institute of
Engineers. https://doi.org/P11/S2/021

Witheridge, G. (2009). Hydraulic Analysis of the Debris Blockage of Culvert Inlets. Catchments &
Creek Pty Ltd.

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.

References - 5 / 6 Page 1093 / 1094

 https://doi.org/https://doi.org/10.1029/JC087iC12p09704

Wu, W., Shields Jr., F. D., Bennett, S. J., & Wang, S. S. Y. (2005). A Depth-Averaged Two-
Dimensional Model for Flow, Sediment Transport, and Bed Topography in Curved Channels
with Riparian Vegetation. Water Resources Research, 41(3).
https://doi.org/https://doi.org/10.1029/2004WR003730

Wu, & Falconer, R. A. (2000). A Mass Conservative 3-d Numerical Model for Predicting Solute
Fluxes in Estuarine Waters. Advances in Water Resources, 23(5), 531–543.

References - 6 / 6 Page 1094 / 1094