Tutorial Module01 Archive

Introduction

Please read the Tutorial Model Introduction before starting this tutorial. It outlines the programs requiring installation and where the source data can be downloaded (e.g. aerial photos, DEM...).


In this first module, a fully two-dimensional (2D) model is built. The steps required to build, run and review a basic 2D TUFLOW model are listed in the table of contents above and shown in the workflow diagram below.





Throughout the tutorial we will create and describe a number of TUFLOW Control Files and GIS layers that are used as input to a TUFLOW model. The TUFLOW Control (text) files introduced in this tutorial include:


1. TUFLOW Simulation Control File (TCF)
2. TUFLOW Geometry Control File (TGC)
3. TUFLOW Boundary Control File (TBC)
4. TUFLOW Boundary Condition Database (.csv)
5. TUFLOW Materials File (.csv)
   

The Geographic Information System (GIS) layers used in this tutorial are:


1. 2d_bc_: A GIS layer defining the locations of external 2D boundaries.
2. 2d_sa_: A GIS layer to define internal 2D flow boundaries.
3. 2d_code_: A GIS layer containing polygons that define the cell codes (active or inactive status).
4. 2d_loc_: A GIS layer defining the origin and orientation of the 2D grid.
5. 2d_mat_: A GIS layer defining the land-use (material) types within the 2D study area.
6. *.asc: A DEM dataset defining the ground elevations within the 2D study area.

Project Initialisation

Setup Model Folders

TUFLOW models are separated into a series of folders which contain the input and output files.

1. Set up the model directory and sub-directories as recommended in the list below (for a more detailed description, please refer to the TUFLOW Manual). Alternatively, you can copy the TUFLOW folder and all sub-folders from the TUFLOW Folders Template folder in the supplied files to a local drive on your computer.
   * If using SMS, the folder structure listed above is automatically created before running the model using the "Export TUFLOW files" command (see Run TUFLOW from within SMS).
   
   

   Sub-Folder	Input / Output	Description
   bc_dbase	Input	Boundary condition database(s) and input time-series data
   check	Output	GIS and other check files to carry out quality control checks (use Write Check Files).
   model	Input	Geometry (.tgc), Boundary (.tbc) and other model control text files (i.e. no GIS files).
   model\gis	Input	GIS layers that are inputs to the 2D and 1D model domains are contained within this folder: model\gis\ is typically used for all ArcGIS and QGIS files
   model\mi	Input	GIS layers that are inputs to the 2D and 1D model domains are contained within this folder: model\mi\ is typically used for MapInfo formatted GIS files
   results	Output	TUFLOW will output the results to this folder in a variety of formats as specified by the user.
   runs	Input	TUFLOW Control Files (.tcf)
   runs\log	Output	TUFLOW log files (.tlf) and messages layers.

   
   

   The following points on TUFLOW folders and filenames are worth noting:
   

   * TUFLOW accepts any folder structure, though the above listed format is most commonly used and is recommended.
   

   * 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 (such as dashes) are not used in the simulation path and filenames (without prior testing).

   * Folder paths, filenames, file extensions and TUFLOW commands are not case sensitive in any TUFLOW control files.

   * The model\mi\ is used for MapInfo inputs, model\gis\ for ArcGIS and QGIS inputs. Any directories that don't apply can be omitted, for example if you are working in MapInfo the model\gis directory may not be be required.

   * For ArcMap 10.1 and newer users, the ArcTUFLOW Toolbox can be used to automatically create the model folders, model projection, TUFLOW control files and run TUFLOW to create the template files.

   * For QGIS users, the TUFLOW QGIS Plugin can be used for the same tasks listed for the ArcTUFLOW toolbox.




Set GIS Projection and Create Empty (Template) GIS Files

The first step when creating a TUFLOW model always requires the user to define the GIS projection (ie. the geographic coordinate system to be used for the TUFLOW model) and also write template GIS files for future model inputs.
Note: All model inputs will need to use a common projection.

1. An aerial photo and DEM of the model area are provided. Open the following layers in your GIS software:
• Module_Data\Aerial_Photos\Aerial_Photo_M01
• Module_Data\DEMs\DEM_M01
* If using SMS, you will need to open the DEM_M01.SMS.tin
2. Create a projection file and write the template GIS files (to be used to build the model) for the project. For a description on how to do this please select your GIS package below.
   
   • ArcGIS - Create Projection (not using the ArcTUFLOW Toolbox)
   • Mapinfo - Create Projection
   • QGIS - Create Projection (not using the QGIS TUFLOW Plugin)
   • SMS - Create Projection and GIS Empty Files
   ArcMap users can automate this step using the ArcTUFLOw Toolbox. Similarly, QGIS users can also automate the process using the QGIS TUFLOW Plugin.
   
3. The next step is to create a TUFLOW Control File (TCF files are used to control the input and output from TUFLOW) and create the 'template' or 'empty' GIS files. TUFLOW will assign the same projection as the GIS layer created above to the template files and also set the file fields or attributes so they are compatible with the desired purpose of the file. See Empty Template GIS Files for more information about each of the TUFLOW template GIS files. In a text editor, create a new file and save to the TUFLOW\runs folder. Since this is Module 1 and the model we’ll produce has a 5m grid, name the file M01_5m_001.tcf.
4. Enter the text as shown below into the newly created text file M01_5m_001.tcf:
   Tutorial Model == ON
   
   MapInfo Users:
   GIS Format == MIF
   MI Projection == ..\model\mi\Projection.mif
   Write Empty MI Files == ..\model\mi\empty
   
   ArcGIS and QGIS Users:
   GIS Format == SHP
   SHP Projection == ..\model\gis\Projection.prj
   Write Empty GIS Files == ..\model\gis\empty | SHP
   
5. Save the TCF file.
   
   Note:
   * You can insert comments into this file if you find it helpful. This is highly recommended. Comments are preceded by an exclamation mark or a hash symbol (i.e. ! or #). Comments can be written after the command or have their own line. Any command following the comment symbol is ignored by TUFLOW.
   * Notice the syntax highlighting in the commands listed above. If you have not already enabled syntax highlighting in your preferred text editing software, we recommend you do. Instructions are provided in the Tips and Tricks section for each software Notepad++, UltraEdit, TextPad.




Run TUFLOW to Create Empty (Template) GIS Files

We now need to run TUFLOW using the TUFLOW Control File (TCF). There are a number of ways TUFLOW can be setup to run. In each case the TUFLOW executable is started with the TCF as the input. For more information on running TUFLOW please refer to the TUFLOW Manual. The most common ways are outlined below. We will be using a batch file for this tutorial, however any of the methods below will work.

• Running TUFLOW from a Batch-file (recommended for this tutorial)
Alternative Methods for Running TUFLOW
• Running TUFLOW from UltraEdit
• Running TUFLOW from Notepad++
• Running TUFLOW from Right Click in Windows XP
• Running TUFLOW from Right Click in Windows 7
• Running TUFLOW using SMS


1. Start TUFLOW from a batch file using the TCF file we have created (M01_5m_001.tcf). Follow the steps outlined in, Running TUFLOW from a Batch-file to create the batch file.
2. Double click the created batch file (.bat) from Windows Explorer to execute the simulation. A console (DOS) window should appear as shown below:
   
   

   
   

3. After a few seconds the information dialog box shown below should appear. Click OK to close the windows.
   
   
   
4. Check the folder specified to view the ‘Empty’ template files have been written.
   • For MapInfo Users these should be in TUFLOW\model\mi\empty\
   • For ArcGIS and QGIS Users this should be TUFLOW\model\gis\empty\




TUFLOW Geometry Control File (TGC) Inputs

Define Location and Dimensions of the 2D Domain

Pre-processing of the Digital Elevation Model (DEM) is not covered in this tutorial. The DEM for the tutorial is provided in a variety of formats, including:

• 12D TIN (Module_Data\DEMs\DEM_M01.12da)
• SMS TIN (Module_Data\DEMs\DEM_M01.SMS.tin)
• Vertical Mapper Grid (Module_Data\DEMs\DEM_M01.tab and .grd files)
• Arc Spatial Analyst format (.img)

Defining the location and orientation of the TUFLOW 2D domain can be undertaken using three different methods as follows:

• Specifying origin coordinates and a second set of coordinates for a point along the X-axis of the domain;
• Digitising a line to represent the bottom edge of the 2D domain (with the line starting at the origin and finishing at a secondary location along the X-axis; or
• Specifying the origin coordinate and domain orientation angle.

The first method is covered in this tutorial. It is required if using an unlicensed version of TUFLOW. The second method is the most commonly used method on day to day projects.


ArcGIS, Mapinfo, and QGIS Users:

1. Create a new text file called M01_5m_002.tgc. Save the file in TUFLOW\model\ folder. This file will become our TUFLOW Geometry Control File (TGC).
   Notice this time we’ve used ‘002’ for numbering the file. This is part of a sound naming convention. This TGC file will be used for simulation ‘002’, hence we’ll number the TGC and any new GIS layers that are added during this model iteration with the same number. This way, in the future, we’ll know that this file and any new tables were created for simulation ‘002’. This also allows us to revert to a previous version of the model without have to undo any changes to the control or GIS files.
   
2. We need to specify the location and dimensions of the TUFLOW domain (computational area) and also the cell size in the TGC file. Add the following text to the TGC file and save.
   Note: you do not need to add the comments, but it is a good habit to get into
   Origin == 292725, 6177615 ! bottom left corner of grid
   Orientation == 293580, 6177415 ! another point along the x-axis of the grid
   Cell Size == 5 ! cell size in metres
   Grid Size (X,Y) == 850, 1000 ! grid dimensions in metres
   

SMS Users:

1. For instructions on how to complete these steps using SMS, see Define the 2D Domain using SMS.




Define Elevations

In the previous section, the extent and dimensions of the 2D domain were defined. We now need to assign elevations at each 2D cell centre, mid-side and corner. These points are known as Zpts.
Knowledge of 2D domain geometry is fundamental to understanding how TUFLOW works. A brief description on the computational function of each of the Zpts in a TUFLOW cell is given in the Zpt Description page.

There are two methods to assign the elevations to the Zpts. The first is to directly input the elevation model into TUFLOW as either a TIN or gridded DEM dataset. TUFLOW will assign the elevations from the elevation dataset to Zpts within the DEM / TIN. This offers the following benefits:


• Speed, direct input of the DEM to TUFLOW is very fast compared to a point inspection in a GIS software; and
• Flexibility, if the cell size, dimension or rotation of the TUFLOW model is changed, TUFLOW will update the elevations automatically.

The second approach is to manually assign the elevation at each of the points using a GIS package. This approach involves TUFLOW writing out the Zpt layer in GIS format and the user defining the elevation at each point in a GIS package. For earlier versions of TUFLOW this method was the only option, it has largely been superseded, but is still supported. For the reasons listed above direct input of the elevation model as either a TIN or DEM is the preferred approach.

ArcGIS, Mapinfo, and QGIS Users
The process of using a direct TIN or DEM read into TUFLOW is outlined below. It is recommended that you have the DEM open in your GIS package, if you do not have it open it can be found in the Module_Data\DEMs\ folder under your GIS package name. Please select one of the following approaches, for users without 12D or SMS the DEM method is recommended.

• Direct input of DEM (recommended)
• Direct input of 12D or SMS TIN

SMS Users The model elevations were previously defined during the Define 2D Domain Using SMS) step. No furtyher actions are required. Please progress to the next step.



Define Preliminary Active and Inactive Areas of the 2D Domain

By default, every grid cell in a TUFLOW model will set as active, thus TUFLOW will allow water to flow anywhere within the extents of the 2D domain. It is rare for a catchment to be a perfect rectangle! To reduce output file sizes and run times, permanently dry and inactive areas can be removed from the model. This can be an iterative process, you might run the model initially and refine. For the purpose of the tutorial you are provided with a polygon, which we will use to define the active area in your GIS package.

1. Firstly, add the Set Code == 0 command to the TGC file. This sets all 2D cells to inactive, we will next define the active areas in GIS.
2. To set the active areas please select you GIS package below:
• Define active area in Mapinfo
• Define active area in ArcGIS (arcTUFLOW)
• Define active area in QGIS
• Define active area in SMS
For ArcMap users not using the ArcTUFLOW toolbox, instructions can be found here: Define active area in ArcGIS (no toolbox).




Discussion on Command Order

When developing a TUFLOW model, it is important to consider how TUFLOW interprets each command in the control files (TCF, TGC, TBC, ECF etc.). In most cases, the location or order within the file is not important, with the last occurrence of that command prevailing. However, for certain commands, particularly those in the TGC file, the order is critical. TUFLOW uses data layering protocol in the TGC.

Commands in the TGC file are read sequentially from the top of the file to the bottom. Where commands alter details for a common cell location (such as code value, elevation or landuse specification), the cell value will be defined by the values specified by the file lower in the TGC. For example, in the case of the Read GIS Code command discussed in the previous section, the 2D cells that fall within the polygon in 2d_Code_M01_002 will define the active/inactive code status irrespective of any code values assigned by previous global code command Set Code == 0 command. Consider the following two blocks of "code" commands below:

Correct Order
Set Code == 0 ! this sets all cells to be inactive
Read GIS Code == ..\model\mi\2d_code_M01_002.MIF ! this updates the cells within the polygon to be active
This command order will achieve the desired outcome. We have initialised the code status for the entire model (as inactive), then updated the status (to active) in the areas contained within the GIS polygon.

Incorrect Order
This is an example of incorrect command order:
Read GIS Code == ..\model\mi\2d_code_M01_002.MIF ! this sets the cells within the polygon to be active
Set Code == 0 ! this sets all cells to be inactive
The second command which sets all cells to be inactive, overwrites the values read in from the GIS layer. The end result will be no active cells in the TUFLOW model!



Define the Materials (Surface Roughness)

Surface roughness or bed resistance values (eg. Manning’s n) are assigned to Materials values. The Module_Data\Module_01\ folder already contains the materials table that we’ll use. We will review these in a GIS package, please select one of:

• Mapinfo
• ArcGIS
• QGIS
• SMS

In order for TUFLOW to associate the Manning’s n to the Material ID, a TUFLOW Materials File is required. This is can be either a text file (.tmf) or an .csv file which can be edited in Excel. In this tutorial model we will utilise the second (.csv) option.

As a minimum this file must contain two columns; the first being the Material ID (as specified in the GIS layer), and the second being the Manning’s n. The .csv file for this tutorial has already been created. Additional data such as loss parameters (applicable for direct rainfall modelling) and depth varying Manning's n values are covered in later modules. The .csv file is presented below (viewed in Excel).



Copy the materials.csv file from the Module_Data\Module_01\Text\ folder into the TUFLOW\model folder.


TUFLOW uses this file to apply the surface roughness values to the 2D cells based on the 2D cell Material values as defined by the Set Mat and Read GIS Mat commands. This materials files will be referred to in the .tcf when we modify this later.



TUFLOW Control File (TCF) Updates

The final step in setting the model geometry is to update our TUFLOW Control File (TCF) to point to the new TUFLOW Geometry Control (TGC) and TUFLOW Materials File (TMF).


1. Open M01_5m_001.tcf in your text editor and save a copy as M01_5m_002.tcf.
2. Comment out (or delete) the "Write Empty GIS Files" line, using a comment character (! or #)

   ! Write Empty GIS Files == ..\model\gis\empty
   

3. Add the following commands (to the M01_5m_002.tcf file) and save the file.

   Geometry Control File == ..\model\M01_5m_002.tgc
   

   Read Materials File == ..\model\materials.csv ! This provides the link between the material ID defined in the .tgc and the Manning's roughess
   




TUFLOW Boundary Condition Control File (TBC) Inputs

In this step we introduce the TUFLOW Boundary Condition Control File (TBC) and Boundary Condition Database (bc_dbase). The TBC file contains information regarding the location of boundary conditions and internal links within the model. These include, but are not limited to:

• Upstream and downstream flow boundaries
• Downstream water level boundaries
• Water sources and abstractions
• Direct rainfall or infiltration
• 1D/2D and 2D/2D links




Define Boundary Condition GIS Locations

For this step, upstream and downstream boundaries are applied.

• A flow vs time (QT) boundary and a source-area (SA) boundary will be used as inflows.
• A stage vs discharge (HQ) boundary is used for the outflow.
  

For details on setting up the GIS layers required, please select your GIS package.


• Mapinfo
• ArcGIS
• QGIS
• SMS




TUFLOW Boundary Control File (TBC) Updates

We next need to read the GIS files created above into the TUFLOW model. We need to create a new text format control file which is the TUFLOW Boundary Condition (TBC) this is similar to the TGC in that it contains the links with the GIS layers.

1. Create a new text file and save as M01_5m_002.tbc in the TUFLOW\model folder. This is our TUFLOW Boundary Condition File.
2. Open this file in a text editor and add the following lines of text and save.
   MapInfo Users
   Read GIS BC == mi\2d_bc_M01_002.mif
   Read GIS SA == mi\2d_sa_M01_002.mif
   
   ArcGIS or QGIS Users
   Read GIS BC == gis\2d_bc_M01_002_L.shp
   Read GIS SA == gis\2d_sa_M01_002_R.shp
   




TUFLOW Boundary Condition Database (bc_dbase)

We now need to associate a hydrograph with each of the upstream boundaries. This is carried out using a boundary condition database. The boundary condition database (bc_dbase) is a powerful function of TUFLOW, potentially saving hours of data input that might otherwise be necessary. The bc database is a comma delimited file with a CSV extension. It can be opened in Excel or any text-editing program. The best approach for managing boundary data is to use an Excel spreadsheet and export the CSV files using the “Save csv” tool provided in the TUFLOW Tools Macro for Excel.


• The process for adding the TUFLOW utilities to Excel is detailed here: Excel Tips.
• alternatively, to use the macro without adding them to Excel, simply open the TUFLOW_Tools_v2.0.xlam in the Module_Data\Module_01\Excel folder.
  


Follow the below listed steps:


1. To create a bc_dbase, start by copying the template bc database (TUFLOW Tutorial Model BC Database.xls) from the Module_Data\Module_01\Excel folder into the TUFLOW\bc_dbase folder (keep the same file name). Open the file in Excel by double clicking on it in Windows Explorer.
   You’ll notice that there are two worksheets. Firstly we’ll complete the bc_dbase worksheet which has column headers in the first 9 columns. As we fill in the entries, it should become clear how they are used, and how TUFLOW interprets the data.
   
2. Enter the name of the first upstream boundary condition into cell A2. The name must appear exactly as it does in the 2d_bc_M01_002 layer, (i.e. FC01).
3. Enter the text “100yr2hr.csv” into cell B2 as per below.
4. Enter the text “inflow_time_hr” into Cell C2 and “inflow_FC01” into Cells D2 as shown below, leaving the remaining 5 columns blank.
   
   

   Name	Source	Column 1	Column 2
   FC01	100yr2hr.csv	inflow_time_hr	inflow_FC01
   FC04	100yr2hr.csv	inflow_time_hr	inflow_FC04

   
   For each of the inflow boundaries, we have specified the GIS name in the name column, specified a source file for TUFLOW to extract the time series data (100yr2hr.csv) and specified the data columns, corresponding to the data headers in the source timeseries file.
   

5. In Excel, switch to the 100yr2hr sheet, and review the hydrographs that have been provided. Note at the stage the "Inflow_FC02" hydrograph is not being used.
   
   
6. If you haven't already, open the TUFLOW_tools_v2.0.xlam, this should create a new drop Menu Item titled TUFLOW. Navigate to this window and select Entire Worksheet to csv.
   
   

   TUFLOW Tools for Excel
   
   

   This utility saves each sheet in the workbook as a .csv file and uses the sheet name to set the filename. If you look in the TUFLOW\bc_dbase\ directory, there should be two new files, "bc_dbase.csv" and "100yr2hr.csv". This has saved all of tabular data from these sheets into a format that TUFLOW can read. The .csv file is a simple text file, with data separated by a comma. This is shown in a text editor below.
   Note: The 100yr2hr worksheet had a chart in excel, this can not be stored in .csv format and is omitted.
   

   




TUFLOW Control File (TCF) Updates

The final step in setting the boundaries is to update our TUFLOW Control File (TCF) to point to the new boundary files (TBC and bc_dbase.csv).


1. Open M01_5m_002.tcf in your text editor and make the following edits.
2. Add the following commands (to the M01_5m_002.tcf file) and save the file.
   BC Control File == ..\model\M01_5m_002.tbc
   BC Database == ..\bc_dbase\bc_dbase.csv
   




TUFLOW Simulation Control File (TCF) Updates

Set Model Controls

This is the last step before running the simulation. Once this step has been completed, most of the ground work has been completed. Subsequent modules build upon this base.

1. Open M01_5m_002.tcf in your text editor and make the following edits.
2. Add the following commands and save the file.

   Start Time == 0 ! Start Simulation a 0 hours
   

   End Time == 3 ! End Simulation a 3 hours
   

   Timestep == 1.5 ! Use a 2D timestep of 1.5 seconds
   

   Log Folder == Log ! Redirects log output (eg. .tlf and _messages GIS layers to the folder "log"

   Output Folder == ..\results\M01\2d\ ! Redirects results files to TUFLOW\Results\M01\2d\

   Write Check Files == ..\check\2d\ ! Specifies check files to be witten to TUFLOW\check\2d\

   Map Output Data Types == h v q d MB1 MB2 ! Output: Levels, Velocities, Unit Flows, Depths, Mass Error
   

   Map Output Interval == 300 ! Output every 300 seconds (5 minutes)
   

   Store Maximums and Minimums == ON MAXIMUMS ONLY ! Save peaks values
   

   Map Output Format == GRID DAT ! Output directly to GIS (grid) as well as SMS (dat) format
   

   You do not need to add the comments, following the exclamation marks. These commands are generally self explanatory. However, for this tutorial model they are included. To clarify the purpose of each line.
   The final command "Map Output Format" controls the output file format, this is discussed further in the results viewing section below.
   The TUFLOW simulation is now ready to be run for the first time.

Run Simulation

Using your preferred method start your TUFLOW simulation. We recommend using the batch file approach, see Running TUFLOW from a Batch-file.

The simulation will take a few minutes to process (depending on the speed of you computer). While the modelling is running, it is worth filling out your Modelling Log. a modelling log includes developer notes keeping a record of TUFLOW simulations and changes from one version to the next. This is not detailed in the Tutorial model but is good practise to get in to. A modelling log is discussed here: TUFLOW Modelling Log (this link was on the tutorial model introduction page). A template modelling log is included in the TUFLOW Folders Template\TUFLOW\ folder of the files supplied with this tutorial.


If your simulation has been successful, the console window should look like the image below.



For instructions on how to complete these steps using SMS, see Set Model Controls and Run the Simulation using SMS.





Viewing Results

Output Formats

In this section we will look at viewing the 2D results. There are a variety of options for viewing TUFLOW results. The following options are most commonly used:


• GIS Grid format: Output directly to raster grid format suitable for use in most GIS packages.

• Can be output in ESRI ascii (.asc) format with the TUFLOW Control File command is: Map Output Format == ASC. This is recommended for MapInfo / Vertical Mapper users.
• Can be output in ESRI binary float (.flt) format with the TUFLOW Control File command is: Map Output Format == FLT. This is recommended for ArcMap and QGIS users.

• SMS .dat format: Used by SMS and also by the QGIS TUFLOW Plugin (both methods outlined below). TUFLOW Control File command is: Map Output Format == Dat
• SMS .xmdf format: Used by SMS and QGIS TUFLOW Plugin. It's a more advanced version of the .dat above. It contains all results in a single output file. The TUFLOW Control File command is: Map Output Format == XMDF
• WaterRide .wrb format: Used by Waterride. The TUFLOW Control File command is: Map Output Format == WRB
• BlueKenue .t3 format: Used by BlueKenue. The TUFLOW Control File command is: Map Output Format == T3

It is also possible to get multiple outputs for a single simulation. For example, GIS grid and WaterRide output can be written using teh syntax Map Output Format == FLT WRB
Note: Prior to the 2013 release of TUFLOW, it was necessary to use a freely available utility (called TUFLOW_to_gis.exe) to convert the .dat or .xmdf formats to GIS grids. However, it is now possible to have TUFLOW output the results directly to GIS format. The .flt format is the default for the 2013-12-AB version and this is best when using ArcMap or QGIS. However, if using MapInfo and Vertical Mapper the .asc format is required.

Depending on the software you are going to use to view the results, you may need to change the Map Output Format and Grid Format commands in the control file and re-run the model. For example if using SMS and ArcMap the recommended settings would be:
Map Output Format == XMDF FLT
However, if using WaterRide and Mapinfo the recommended settings would be:
Map Output Format == WRB ASC


It is also possible to control the frequency and output types for each output format separately, however this is not covered in this tutorial.

Viewing Results

Open and view the TUFLOW results in your viewing package, for instructions on this please select your results package below.


• SMS 10.1
• SMS 11.1
• MapInfo
• ArcGIS
• QGIS using TUFLOW plugin
• QGIS using raster and shapefiles

Reviewing Model Performance

When reviewing our model performance there are a number of useful outputs from TUFLOW. In this section we will introduce some of the available simulation check files and also review the stability and performance of the model. We will look at a number of GIS and text based outputs in this review.

Simulation Check Files

With the Write Check Files command specified in the TCF, TUFLOW will write a series of check files prior to the simulation starting. The check files are useful for reviewing the inputs have been correctly specified. This is particularly the case of long simulations, for example if you have a large model that runs for 12 hours and you are running a model with additional breakline (see Module 3), it is good to check that these features are correctly represented. This can be done using the check files whilst the 12 hour simulation is running, rather than waiting until the simulation finishes! We will introduce the check files as we progress with the tutorial modules. In the first module we will use the _zpt_check file, which contains all the final Zpt elevations, for the active model area. Please select your GIS package.

• Mapinfo
• ArcGIS
• QGIS
• SMS

For information on other TUFLOW check files please refer to the Check Files page of the TUFLOW Wiki.

TUFLOW Log file

The first place to look is at the final output in the DOS window. If you missed this, for example if the model was run in batch mode this information is contained in the TUFLOW Log File (.tlf). Earlier on we add the following command to the TCF:
Log Folder == Log


This command controls where the log file is written. By setting this to Log it will be written to a Log directory under the runs directory.

1. In Windows Explorer, navigate to the TUFLOW\runs\Log\ directory and locate the M01_5m_002.tlf file. Open this file into your text editor. At the end of this file is the Simulation Summary.
As the name suggest this contains a summary of the TUFLOW simulation performance. The first part of the summary contains some information about the files, times and computation time.


SIMULATION SUMMARY

Input File: C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_002.tcf
Log File: C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\log\M01_5m_002.tlf

Start Time (h): 0.
End Time (h):   3.
Computational Steps (based on largest 2D timestep): 7200

CPU Time (hh:mm:ss):        0:01:08 [0.01891 hours]
Clock Time (hh:mm:ss):      0:01:14 [0202056 hours]

Simulation FINISHED

The next part of the Simulation Summary contains information on the messages issued by TUFLOW. Of note is the 2D Negative Depths (1). This indicates that the numerical solution has "overshot" and calculated a negative depth. Repeated negative depths are an indication that the model is not performing well. We will look at where these occur in the next section.

Total 1D Negative Depths: 0
Total 2D Negative Depths: 118

WARNINGs prior to simulation:     2  [1 not in _messages layer]
WARNINGs during simulation:     118  [0 not in _messages layer]
CHECKs prior to simulation:       0  [0 not in _messages layer]
CHECKs during simulation:         0  [0 not in _messages layer]

Following the messages section is a summary of the volumes and mass error in the model. The table towards the end shows the Peak Cumulative ME: was -1.19% and that this occurred at 0.27 hours into the simulation (16 minutes). It is preferable to have a Peak Cumulative ME below 1%. In the sections below we we look at determining where the mass error is occurring.

Peak Flow In (m3/s):   105.9 at Time 0.92
Peak Flow Out (m3/s):  84.1 at Time 1.21
Volume at Start (m3):  237
Volume at End (m3):    149824
Total Volume In (m3):  408904
Total Volume Out (m3): 246025
Volume Error (m3):     -13292 or -2.0% of Volume In + Out
Final Cumulative ME:   -2.03%

                                    Whole Simulation            Qi+Qo > 5%
Peak +ve dV (m3):                  160.0 at    0.89h       160.0 at    0.89h
Peak -ve dV (m3):                  -28.3 at    1.58h       -28.3 at    1.58h
Peak ddV over one timestep:        -12.0 at    0.89h        12.0 at    0.89h
Peak ddV as a % of peak dV:          7.5%                    7.5%
Peak Cumulative ME:               -2.03% at    3.00h      -2.03% at    3.00h

TUFLOW Messages Layers

TUFLOW writes a number of messages, in increasing order of severity these are: Check --> Warning --> Error. Each of the messages generated by TUFLOW has a four digit ID code. A description of each of these messages is given in the message database section of this wiki: (TUFLOW Messages Database). When a numerical model such as TUFLOW struggles to converge to a solution, spurious results such as negative depths can be generated. When this occurs TUFLOW creates a warning and writes this to the _messages.csv file and also to a GIS file. This can be opened in excel, or your GIS package.

1. Open the M01_5m_002_messages.csv file in the TUFLOW\runs\log\ directory. It provides a summary of the messages. For example:

2991

2

293285.826

6177861.233

"WARNING 2991 - Negative U depth at [074;098]."

"Time = 0:38:33"

"Depth = -0.2"

"2D Domain = Domain_001"

This may vary slightly or may not be there at all, depending on the version of TUFLOW you run.
This message indicates that Warning Message 2991 occurred during the simulation.


2. To view the location of this error, import the M01_5m_002_messages.mif or M01_5m_002_messages_P.shp file into your GIS package.

Location of Negative Depth Warning and DEM (Image from MapInfo)

It can be seen that the warning message is occurring in the steep area of the creek bank.

Mass Balance Outputs

Mass balance can be an issue for badly configured numerical models (not just TUFLOW). A modeller should be aware of the health of the model to ensure that the model is well conditioned.
TUFLOW outputs the mass balance in a number of ways:


• In the simulation summary of the .tlf file (see above)
• In the _ TUFLOW Simulations.log, this is written to the TUFLOW\runs\ directory.

This is a text file that can be opened in your text editor. For the M01_5m_002 that was just simulated, here is an extract.


Finished: M01_5m_002   fCME = -2.03%  pCME = -2.03%

The _ TUFLOW Simulations.log also contains a variety of other information, such as date, computer name, TUFLOW build version, the CPU hours and a other useful data.

• Time-series mass balance output. This is written to the same location as the 2D model results (in this case TUFLOW\results\M01\2d\). This file has the same name as the runfile (TCF) with the suffix, _MB.csv. As such the mass balance spreadsheet for this simulation is called M01_5m_002_MB.csv. Open the file in Excel. It contains a summary of the mass entering and leaving the model. Plot the first (time) and last (cumulative mass error %) columns within the spreadsheet to review the time varying mass error values.
• MB1 and MB2 map output. These 2D map outputs can be viewed using the methods described above in Viewing Results.

The MB1 output tracks the convergence of the solution at each cell since the previous output time. The MB2 is the cumulative sum of the MB1 output. In the image below the MB2 output is shown at the final timestep (3 hours). It highlights areas in which the 2D solution has not performed well during the simulation.
It can be seen that these are the areas along the main channel. The creek is approximately 5-10m wide and the flowpath is being represented by 1-2 grid cells. This is likely to be causing the issues.
Possible options for minimising the mass error are discussed in the conclusion below.


MB2 contour lines at time 3hrs, over aerial photo (in SMS)

Conclusion

To conclude, in this module we have created a 2D TUFLOW model. We have setup the required GIS and text based inputs and ran the simulation. We have visualised the results and reviewed the performance of the model.


The model results, depths and velocity outputs look sensible. However, the model has a slight issue with mass balance, which appears in the main channel areas. This is most likely caused by the inadequate representation of the creek with the cell size adopted in the tutorial model. This cell size has been chosen to allow the model to be simulated quickly on most computers.


In Module 3 we will model the creek area as an embedded 1D open channel, this should minimise the mass area noted in this tutorial. Reducing the cell size also allows for a better representation of the channel in the 2D model.


See the Optional Section below, in which we look at halving the cell size and the effect this has on the model results and simulation time.

Whilst reviewing the results, you may have noticed that the water was being held behind these road embankments (which were essentially acting as dams in the model. We will embed 1D culverts through the road embankments in Module 2. This will introduce the 1D control files and linking of the 1D model to the 2D.

Troubleshooting

This section contains links to some common issues that may occur when progressing through the first module of the TUFLOW tutorial model. If you experience an issue that is not detailed on here please either send an email to support@tuflow.com.


• Save date of .tab file is later than .mif or .mid
  
• ERROR 2014 - No active cells within SA inflow polygon
• Why does the TUFLOW DOS Window open, though the TCF isn’t read and the simulation doesn’t execute?

Advanced - Model Resolution (Optional)

This section will include a discussion focused on reducing the cell size from 5m to 2.5m and the impact that this has on the mass balance, model results and run times. In order to reduce the cell size in the model we will need to perform the following steps:

ArcGIS, Mapinfo, and QGIS Users:

1. Save the TUFLOW runfile (M01_5m_002.tcf) as M01_2p5m_003.tcf
2. Save the geometry control file (M01_5m_002.tgc) as M01_2p5m_003.tgc (don't forget to update the .tcf, to include the new geometry control file).
3. Modify the cell size in the geometry control file.
4. Reduce the timestep in the .tcf from 1.5 seconds to 0.5 second:
   

   Timestep == 0.5 ! Use a 2D timestep of 0.5 seconds
   

5. Run the model.
   

SMS Users:

1. For instructions on how to complete these steps using SMS, see Change Cell Size Using SMS.

TIP: If you forget any of the steps, the complete inputs files are provided as part of the download package (zip file).


Results

Using the methods described above, view the results in your preferred package. Do the results appear different? Is the increase in simulation time justified?



Reviewing the model performance, the mass error remains below 1% throughout the entire simulation. A comparison of the model performance is made in the table below.

Cell Size (m)	Timestep (seconds)	Peak Mass Error (%)	Model Runtime (mins)	Runtime Ratio
5	1.5	-2.03	1.15	-
2.5	0.5	-0.26	12	10.5

Discussion

The model performs better with a smaller cell size, as the 5m resolution is a bit too coarse for representing the narrow in-bank flowpath in a 2D manner. In Module 3 we will overcome this issue by modelling the creek using a 1D model, which will be dynamically linked with the 2D model.

It is worth noting the increase in runtime, by halving the cell size by a factor of 2, we have four times as many cells (each 5m x 5m cell is now four 2.5m x 2.5m cells), we also needed to reduce the timestep, as the Courant number is directly related to cell size (refer to the TUFLOW Manual) this would normally be reduced by a factor 2 as well. This translates to an approximate increase in runtime of 8 (four times the number of cells and half the timestep). Choosing an appropriate cell size that allows representation of the hydraulics whilst resulting in realistic run times is an important part of the modelling process. With some planning you should be able to avoid a model that requires excessive run times!

The following Wiki page gives some guidance on estimating model runtimes based on the model area and cell size.

Advanced - HPC Solver (Optional)

This section will introduce how to run the model TUFLOW’s HPC (Heavily Parallelised Compute) solver, and how to fix some common issues that may occur when trying to run a simulation using Graphics Processing Unit (GPU) hardware. Please see HPC Features Archive for more information on TUFLOW HPC features supported in the 2017 release.

TUFLOW HPC can run between 10 and 100 times faster than TUFLOW Classic using NVidia Graphics Processing Units (GPU)(depending on the model configuration and hardware performance).



In order to use the HPC solver, we will need to perform the following steps:
ArcGIS, Mapinfo, and QGIS Users:

1. Save the TUFLOW runfile (M01_2p5m_003.tcf) as M01_2p5m_004.tcf.
2. Add the following command to the TCF file:
   

   Solution Scheme == HPC ! Use HPC solver to run the model
   

3. If you have a CUDA enabled NVIDIA GPU device, you can also add the following command to run the HPC solver using GPU hardware:
   

   Hardware == GPU ! Run HPC solver on GPU
   

4. Save the TCF file and run the model.
   

SMS Users:

1. For instructions on how to complete these steps using SMS, see TUFLOW HPC Using SMS.

TIP: If you forget any of the steps, the complete input files are provided as part of the download package (zip file).


Results

Using the methods described above in the Viewing Results section.

• Check the simulation logs in the DOS window, .tlf and .hpc.tlf log files.
• View the results in your preferred package.

Do the logs and results appear different? Did the simulation run faster using the GPU hardware? For more information about computer hardware and simulation speed, please refer to the Hardware Benchmarking Page.

Troubleshooting for GPU Simulation

If you receive the following error when trying to run the TUFLOW HPC model using GPU hardware:

TUFLOW GPU: Interrogating CUDA enabled GPUs … 
TUFLOW GPU: Error: Non-CUDA Success Code returned 

or

ERROR 2785 - No GPU devices found, enabled or compatible.

Please try the following steps:

1. Check if your GPU card is an NVIDIA GPU card. Currently, TUFLOW does not run on AMD type GPU.
2. Check if your NVIDIA GPU card is CUDA enabled and whether the latest drivers are installed. Please see GPU Setup.


If you experience an issue that is not detailed above please send an email to support@tuflow.com