Overview

How to use this Manual

Instructions are provided below on how to use this manual, including aspects of navigation and searching. These instructions are not provided elsewhere.

Navigation

This manual is designed for digital use within any web browser and has the following features:

• Section headers, to level three, are directly navigable via the left hand pane’s table of contents. This table of contents pane can be toggled on and off from view via the “s” key if more or less page width is required.
• The angled arrows that float at the left and right hand side midpoints of every page can be used to navigate sequentially back and forth to the commencement of preceding or subsequent top level sections.
• Control file commands and cross references for tables and figures are navigable through hyperlinks, where appropriate. Control file commands are listed at the end of the Manual from Appendix A to Appendix K.
• The space bar can be used to scroll down within each page without skipping text. Shift + space bar will similarly scroll up.
• Browser back and forward buttons (or their equivalent keyboard shortcuts alt + \(\langle\)left arrow\(\rangle\) and alt + \(\langle\)right arrow\(\rangle\)) can be used to navigate through browsing history. Some browsers may not return to the scroll location in a page last visited, but to the last clicked section header. Hyperlinks have been built into the body of the manual, and these can be used in lieu of browser buttons if required.

It is recommended that this manual be viewed in a browser window that is maximised or operating in full screen mode, with the latter (although browser dependent) typically toggled via the F11 key.

When following hyperlinks, the target (i.e. location linked to) is displayed at the top of the landing page. The exception to this occurs when a target is located near the bottom of the landing page’s content. In this case, it is not possible for a web browser to display the target at the top of a page because this would generate underlying white space, and as such, the target will appear in the main body of the landing page.

Searching

This entire manual content can be searched by using the search box at the top of the table of contents pane (i.e. screen top left near the TUFLOW logo). This search box can be toggled on and off by clicking the search icon (magnifying glass) at the top left of any page.

The table of contents is dynamically filtered in response to entering text in the search box, and clicking on any remaining table of contents entry will navigate directly to the searched text. Searched text will be highlighted within a page for easy identification, and multiple instances within one page can be navigated through by using the up and down arrow keys. Clearing the search box will restore the table of contents.

About this Manual

This document is the User Manual for the TUFLOW Classic and TUFLOW HPC hydrodynamic computational engines for the 2023-03-AF release. Of particular note for users of earlier manual versions is that there has been a significant reworking of some chapters to integrate the HPC solver, which is now preferred over the Classic solver, into the manual. For example, the content from Chapter 10 in the 2018-03 Manual, which documented the HPC solver, has been relocated and embedded in the main chapters.

For changes to different releases refer to the links in Chapter 18.

If simulating models using prior TUFLOW builds, reference may need to be made to the Release Notes and documentation relevant for that particular build. These can be downloaded from the TUFLOW Classic/HPC Downloads page or requested via support@tuflow.com.

Glossary and Notation

Term	Description
_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.
Build	The TUFLOW Build number is in the format of year-month-xx where xx is two letters starting at AA then AB, AC, etc. for each update for that release. 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: 2001-03-AA.
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”.
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.
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.
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: \(\cdot\) 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. \(\cdot\) Node in a model mesh used for viewing 2D results in SMS. The nodes are located at the cell corners. \(\cdot\) 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.
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.
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.
subcritical flow	A flow condition or behaviour where the fluid velocity is slower then the wave velocity.
Sub-grid-scale turbulence	Horizontal turbulent diffusion of momentum or eddy viscosity.
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.
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.