Example Models Home page
- 1 Introduction
- 2 Setup Model Folders
- 3 Running TUFLOW
- 4 Set GIS Projection and Create Empty (Template) Files
- 5 Define Location and Dimensions of the 2D Domain
- 6 Define Elevations
- 7 Define Preliminary Active and Inactive Areas of the 2D Domain
- 8 Discussion on order of commands
- 9 Define the Materials (Surface Roughness)
- 10 Define Boundary Conditions
- 11 Set Model Controls and Run the Simulation
- 12 Using Check Files to Review Topography
- 13 Viewing the Results
- 14 Reviewing Model Performance
- 15 Conclusion
- 16 Troubleshooting
- 17 Advanced (Optional)
If you haven't already read the introduction to the tutorial model, please see this tutorial model page. This page discusses the requirements (hardware and software) and references some recommended reading before starting this tutorial. This page also give instruction on downloading the data required to complete this tutorial (e.g. aerial photos, DEM...).
In this first module, a fully two-dimensional model (no 1D) is built. The table of contents above outlines the steps required to build, run and review the model. In this module we will create and describe a number of TUFLOW control files and GIS layers which are inputted to the TUFLOW model.
The TUFLOW Control (text) files to be introduced are:
- TUFLOW Simulation Control File (.tcf);
- TUFLOW Geometry Control File (.tgc);
- TUFLOW Boundary Conditions Control File (.tbc); and
- TUFLOW Materials File (.csv).
The GIS Layers to be introduced are listed below:
- 2d_bc_ Mandatory layer(s) defining the locations of 2D boundaries (this type is also used in later modules to create 2D/1D dynamic links);
- 2d_code_ Optional GIS layer(s) containing objects, typically polygons, that define the cell codes;
- 2d_loc_ Layer defining the origin and orientation of the 2D grid. This layer is optional, however, is the preferred method for geographically locating 2D domains;
- 2d_mat_ Layer(s) to define or change the land-use (material) types of 2D cells;
- 2d_sa_ Optional layer(s) to define internal flow boundaries; and
Setup Model Folders
TUFLOW models are separated into a series of folders which contain the input and output files. Any folder structure may be used; however, it is strongly recommended that the structure below is used for the tutorial model!
The following points on TUFLOW folders and filenames are worth noting:
- 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.
|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 data files, except for the GIS layers which are located in the model\mi or model\gis folder (see below).|
|model\mi||Input||GIS layers that are inputs to the 2D and 1D model domains: model\mi\ - is typically used for MapInfo formatted GIS files|
|model\gis||Input||GIS layers that are inputs to the 2D and 1D model domains: model\gis\ - is typically used for all GIS software except MapInfo (see above)|
|results||Output||TUFLOW will output the results 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.|
Note: For ArcMap 10.1 and newer users, the ArcTUFLOW toolbox can be used to create the model folders, model projection, TUFLOW control files and run TUFLOW to create the template files. This process is outlined in the ArcGIS - Create TUFLOW project (ArcTUFLOW toolbox) page. This is the recommended approach for ArcMap users, however, the following methodology can be followed. Under a TUFLOW directory in which your modelling will be done, the following directories are recommended. TUFLOW Folders
- model\mi (for MapInfo Users)
- model\gis (for ArcGIS, SAGA and QGIS Users)
If using SMS, the file structure above is created before running the model using the "Export TUFLOW files" command (see Run TUFLOW from within SMS).
There are a number of ways TUFLOW can be setup to run. In each case the TUFLOW executable is started with the TUFLOW control file (.tcf) as the input. For more information on running TUFLOW please see Chapter 5 of the 2010 TUFLOW manual. The most common ways are outlined below. For the TUFLOW tutorial model a batch file will be used, however, any of the methods below will work.
- Running TUFLOW from a Batch-file (recommended for 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
Set GIS Projection and Create Empty (Template) Files
A GIS layer with the models GIS projection (ie. the geographic coordinate system to be used for the TUFLOW model) needs to be created and exported so that the model is correctly located on the earth’s surface. TUFLOW can then be used to create a series of template, or ‘empty’, MapInfo tables, which are used to build the model.
For a description on how to do this please select your GIS package below.
- Mapinfo - Create Projection
- SAGA GIS - Create Projection
- QGIS - Create Projection
- SMS - Create Projection
Arc Map: For ArcMap users, this step was covered in the ArcGIS - Create TUFLOW project (ArcTUFLOW toolbox) if using the ArcMap toolbox and is the preferred approach. For users not using the ArcTUFLOW toolbox, please see this step ArcGIS - Create Projection (no toolbox).
The next step is to create a TUFLOW Control File (.tcf file used to control the input and output from TUFLOW), and create the ‘empty’ or template GIS files. These will have the same projection as the GIS layer created above.
Tutorial Model == ON
For MapInfo add the following commands.
GIS Format == MIF
MI Projection == ..\model\mi\Projection.mif
Write Empty MI Files == ..\model\mi\empty
Or for ArcGIS, SAGA or QGIS add the following commands.
GIS Format == SHP
SHP Projection == ..\model\gis\Projection.prj
Write Empty GIS Files == ..\model\gis\empty | SHP
You can insert comments into this file if you find this helpful to take notes. 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.
Start TUFLOW using the run file created (M01_5m_001.tcf). A console (DOS) window should appear as shown below:
After a few seconds the information dialog box shown below should appear. Click OK to close the windows.
Check the folder specified to view the ‘Empty’ template files have been written. For MapInfo these should be in TUFLOW\model\mi\empty\ for ArcGIS and SAGA this should be TUFLOW\model\gis\empty\.
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 as a:
- 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 the origin coordinates and coordinates of a second point along the X-axis of the domain;
- Digitising a line to represent the bottom edge of the 2D domain; or
- Specifying the origin coordinates and orientation angle.
Only the first method is covered in this tutorial, as this is required if using an unlicensed version of TUFLOW. The second method is the most common.
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 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.
In the TGC file we need to specify the location and dimensions of the TUFLOW domain (computational area) and also the cell size.
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
- For instructions on how to complete these steps using SMS, see Define the 2D Domain using SMS.
In the previous section, the extent and dimensions of the 2D domain were defined. We now need to assign elevations at each 2D cell’s centre, mid-side and corner. These points are known as Zpts.
Knowledge of 2D domain geometry is fundamental to understanding how TUFLOW works. It is highly recommended to read Section 4.4 of the 2010 TUFLOW User Manual in this regard. 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. 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 accordingly.
The second approach is to 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 inspecting 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. However, the alternative GIS based approach is described in the GIS based Zpt inspection.
Direct Input of DEM or TIN (preferred approach)
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. When the model is started, the check files can be used to ensure the DEM or TIN read has been successful. This process will be outlined later in this tutorial module. Please select one of the following approaches, for users without 12D or SMS the DEM method is recommended.
Inspection of elevations in GIS package (alternate approach)
The alternative GIS based approach method of inspecting elevations is described in GIS based Zpt inspection. This is the method some TUFLOW users may be familiar with.
- Note that when using SMS, you create z points as part of the "Define Location and Dimensions of the 2D Domain" step (see Define 2D Domain Using SMS).
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.
- Define active area in Mapinfo
- Define active area in ArcGIS (arcTUFLOW)
- Define active area in SAGA GIS
- 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).
Read GIS Code == ..\model\mi\2d_code_M01_002.MIF
ArcGIS Users, SAGA and QGIS users:
Read GIS Code == ..\model\gis\2d_code_M01_002_R.SHP
Discussion on order of commands
This is an appropriate place to discuss the order of commands in TUFLOW files. When developing a TUFLOW model, it is important to consider how TUFLOW interprets each command in the control files. For most commands, 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. For example, in the case of the Read GIS Code command discussed above, the 2D cells that fall within the polygon(s) in the 2d_Code_M01_002 will have their code values updated irrespective of any code values assigned by previous code commands such as the Set Code == 0 command. Consider the following two blocks of "code" commands below:
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 is order of commands will achieve the desired outcome.
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:
In order to read in the GIS layer created above. Enter the following text into the .tgc file:
Set Mat == 1 ! Set every cell to a material ID of 1 (Pasture)
And depending on the GIS package used above one of:
Read GIS Mat == mi\2d_mat_M01_002.MIF
ArcGIS Users, SAGA and QGIS users:
Read GIS Mat == gis\2d_mat_M01_002_R.shp
The Set Mat command sets all 2D cells to a Material ID of 1, which is used for pasture. The Read GIS Mat command updates any 2D cells that fall within the polygons in the 2d_mat layer with the Material attribute value of each polygon. As discussed above for the cell code values, the order of these Mat commands is important.
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 (rainfall modelling) and depth varying Manning's n values are covered in later modules. The .csv as viewed in Excel is presented below.
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.
Define Boundary Conditions
In this step we introduce the TUFLOW Boundary Conditions Control File (TBC) and Boundary Condition Database (bc_dbase). The TBC file contains information regarding the location of boundary conditions and links within the model. These include, but are not limited to:
- Upstream and downstream flow boundaries
- Downstream water level boundaries
- Water sources and abstractions
- 1D/2D and 2D/2D links
- Direct rainfall or infiltration
GIS Boundary Locations
For this step, upstream and downstream boundaries are applied. For the inflows, a flow vs time (QT) boundaries and a source-area boundary are specified, and for outflows, a stage vs discharge (HQ) boundary is used.
For details on setting up the GIS layers required, please select your GIS package.
Control Files and Boundary Condition Database
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.
Read GIS BC == mi\2d_bc_M01_002.mif
Read GIS SA == mi\2d_sa_M01_002.mif
ArcGIS, SAGA or QGIS Users
Read GIS BC == gis\2d_bc_M01_002_L.shp
Read GIS SA == gis\2d_sa_M01_002_R.shp
We now need to associate a hydrograph with each of the upstream boundaries. This is carried out using a boundary condition database. The bc database 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 add in for Excel. The process for adding these utilities to Excel, so that they open with Excel is detailed here: Excel Tips. To use these without adding them to Excel simply open the TUFLOW_Tools_v2.0.xlam in the Module_Data\Module_01\Excel folder.
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.
|Name||Source||Column 1||Column 2|
For each of the inflow boundaries, we have specified the name in the name column, specified a source for TUFLOW to extract the data (100yr2hr.csv) and specified the data columns to extract the data.
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 ommitted.
The final step in setting the boundaries is to update our TCF to point to the new boundary files (.tbc and bc_dbase.csv).
BC Control File == ..\model\M01_5m_002.tbc
BC Database == ..\bc_dbase\bc_dbase.csv
Set Model Controls and Run the Simulation
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.
- ! Write Empty GIS Files == ..\model\gis\empty
- 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
- 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
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.
The simulation will take a few minutes to process (depending on the speed of you computer). Take this opportunity to have a stretch and look away from the screen for a moment. While the modelling is running, it is worth filling out your Modelling Log which keeps a record of TUFLOW simulations and changes. 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 you 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.
Using Check Files to Review Topography
With the Write Check Files command TUFLOW will write a series of check files prior to the simulation starting. These are a great way of reviewing the input files to ensure that the inputs have been correctly specified. For long simulations this is particularly desirable, for example if you have a large model that runs for 4 hours, and you are running with an additional breakline (see Module 3), it is good to check that these are included, rather than waiting for 4 hours! We will introduce the check files are 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. To do this please select your GIS package.
Viewing the Results
In this section we will look at viewing the 2D results. There are a variety of options for viewing TUFLOW results. For the 2013-12 version of TUFLOW, the following options are available:
- GIS Grid format, output directly to grid format suitable for use in most GIS packages. Can be output in ESRI ascii (.asc) format with the TUFLOW Control File command: 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: Map Output Format == FLT. This is recommended for ArcMap and QGIS users.
- SMS .dat format, used by SMS and also by the Crayfish QGIS Plugin (both methods outlined below). TUFLOW Control File command: Map Output Format == Dat
- SMS .xmdf format, used by SMS, a more advanced version of the .dat above, contains all results in a single output file. Not compatible with Crayfish. TUFLOW Control File command: Map Output Format == XMDF
- WaterRide .wrb format. TUFLOW Control File command: Map Output Format == WRB
- BlueKenue .t3 format. TUFLOW Control File command: Map Output Format == T3
It is also possible to get multiple outputs for a single simulation. For example, to get GIS grid in .flt format and WaterRide output, the user would specify Map Output Format == FLT WRB.
Prior to the 2013 release of TUFLOW, it was necessary to use a freely available utility (called TUFLOW_to_gis) 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!
Reviewing Model Performance
When reviewing our model performance there are a number of useful outputs from TUFLOW. In this section we will review the stability and performance of the model. We will look at a number of text and GIS based outputs in this review.
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 text to our .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.
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:28 or 0.02446 hours Clock Time (hh:mm:ss): 0:01:29 or 0.02472 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: 1 WARNINGs prior to simulation: 1 [1 not in _messages layer] WARNINGs during simulation: 1 [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 of the shows the 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): 87.9 at Time 1.20 Volume at Start (m3): 236 Volume at End (m3): 150019 Total Volume In (m3): 409515 Total Volume Out (m3): 255964 Volume Error (m3): -3769 or -0.6% of Volume In + Out Final Cumulative ME: -0.57% Whole Simulation Qi+Qo > 5% Peak +ve dV (m3): 213.4 at 0.89h 213.4 at 0.89h Peak -ve dV (m3): -26.6 at 1.58h -26.6 at 1.58h Peak ddV over one timestep: -56.3 at 0.89h 4.8 at 0.96h Peak ddV as a % of peak dV: 26.4% 2.2% Peak Cumulative ME: -1.19% at 0.27h -0.57% at 2.99h
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.
|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.
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 juts 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 or 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 = -0.57% pCME = -1.19%
- The _ TUFLOW Simulations.log also contains a variety of other information, such as date, computer name, TUFLOW build version, the CPU hours and a number of other data. This is not discussed in detail in this section.
- Time-series of 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 _MB.csv for this simulation this mass balance spreadsheet is called M01_5m_002_MB.csv. This file can be opened in Excel. This contains a breakdown of the mass entering and leaving the model. A plot of the first (time) and last (cumulative mass error %) is shown below.
- MB1 and MB2 map output. These 2D map outputs can be viewed using the methods described above in viewing the results.
The MB1 output tracks the convergence of the solution at each cell since the previous output time. The MB2 output is the cumulative of the MB1 output up to the output time. In the image below the MB2 output is shown at the final timestep (3 hours), this highlights area s in which the 2D solution has not performed well over 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.
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 the 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.
In the next module (Module 2), we will embed 1D culverts through the road embankments. 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. This will introduce the 1D control files and the linking of the 1D model to the 2D.
This section contains a link to some common issues that may occur when progressing through the first module of the TUFLOW tutorial model.
- Save date of .tab file is later than .mif or .mid
- ERROR 2014 - No active cells within SA inflow polygon
This section will include a discussion varying the cell size from 5m, to 2.5 and the impact that this has on the mass balance, model results and runtimes.
In order to reduce the cell size in the model we will need to perform the following steps:
- Save the TUFLOW runfile (M01_5m_002.tcf) as M01_2p5m_003.tcf
- 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).
- Modify the cell size in the geometry control file.
- Reduce the timestep in the .tcf from 1.5 seconds to 1 second:
- Timestep == 1.0 ! Use a 2D timestep of 1. seconds
- Run the model
TIP If you forget any of the steps, the complete inputs files are provided as part of the download package (zip file).
Using the methods described above here, view the results in your preferred package. Do the results appear much different?
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 (%)||Final Mass Error (%)||Model Runtime (mins)||Runtime Ratio|
The model preforms significantly better with a smaller cell size, as the 5m resolution is a bit too coarse for representing the narrow flowpath in a 2D manner. In module 3 we will overcome this issue by modelling the creek in the 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 (see Section 3.6 of the 2010 TUFLOW manual) this would normally be reduced by a factor 2 as well. This relates to approximate increase in runtime of 8 (four times the cell and half the timestep). Choosing an appropriate cell size that allows representation of the hydraulics, whilst resulting in realistic runtimes, is an important part of the modelling process. With some planning you may be able to avoid a model that run for days, weeks or months!
The following post on the TUFLOW forum gives some guidance on estimating model runtimes based on the model area and cell size.