Example Models Home page

From Tuflow
Revision as of 22:51, 8 March 2016 by Alex.curran (Talk | contribs) (Created page with "<ol> == Introduction == If you haven't already read the introduction to the tutorial model, please see this <u> tutorial model</u> page. This page discusse...")

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

    Introduction

    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.
    Tute M01 Directory Structure v3.png
    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.
  1. Set up the model directory and sub-directories as recommended in the list below (for a description please see Table 2.1 of 2010 TUFLOW Manual). Alternatively, you can copy the TUFLOW folder and all sub-folders to a local drive from the TUFLOW Folders Template folder in the supplied files.

    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
    • bc_dbase
    • check
    • model
    • model\mi (for MapInfo Users)
    • model\gis (for ArcGIS, SAGA and QGIS Users)
    • results
    • runs
    • runs\log
    The model\mi\ is used for MapInfo inputs, model\gis\ for ArcGIS, SAGA and QGIS inputs. The MapInfo files have traditionally been located in the model\mi directory, and they continue to be for this tutorial, however, if desired they could also use be located in the model\gis\ directory. 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.
  2. 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).

    Running TUFLOW

    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.

    Alternative Methods for Running TUFLOW

    Set GIS Projection and Create Empty (Template) Files

  3. An aerial photo and DEM of the model area are provided. In your GIS software open the following layers:
    • Module_Data\Aerial_Photos\Aerial_Photo_M01
    • Module_Data\DEMs\DEM_M01

    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.

    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.

  4. 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 as M01_5m_001.tcf.
  5. Enter the text as shown below into the newly created text file M01_5m_001.tcf:
    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

  6. Save the file.
  7. 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.

  8. We now need to run TUFLOW using this TUFLOW Control File. Please use the method that you setup in the Running TUFLOW section above.
    Start TUFLOW using the run file created (M01_5m_001.tcf). A console (DOS) window should appear as shown below:

  9. Tute M01 DOS Empties.png

    After a few seconds the information dialog box shown below should appear. Click OK to close the windows.

    Tute M01 TUFLOW Empties Created.png

    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.

  10. Create a new text file and save as M01_5m_002.tgc in the TUFLOW\model\ folder. This file will become our TUFLOW Geometry Control File (TGC).
  11. 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.

  12. Add the following text to the TGC file and save. Note that you do not need to add the comments, but it is a good habit to get into!
  13. 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

    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’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.

  14. 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.
  15. To set the active areas please select you GIS package below:
  16. For ArcMap users not using the ArcTUFLOW toolbox, instructions can be found here Define active area in ArcGIS (no toolbox).

  17. Enter the following line of text into the .tgc after the Set Code == 0 command and save the TGC file.
    MapInfo Users:
    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:
    Order 1
    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.
    Order 2
    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:
    MapInfo Users:
    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.

    Tute M01 material csv.png

  18. 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.
  19. 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.

  20. Create a new text file and save as M01_5m_002.tbc in the TUFLOW\model folder. This is our TUFLOW Boundary Condition File.
  21. 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, 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.

  22. 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\model\bc_dbase folder (keep the same file name). Open the file in Excel by double clicking on it in Windows Explorer.
  23. 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.

  24. 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, ie. “FC01”.
  25. Enter the text “100yr2hr.csv” into cell B2 as per below.
  26. Enter the text “inflow_time_hr” into Cell C2 and “inflow_FC01” into Cells D2 as shown below, leaving the remaining 5 columns blank.
  27. Tute M01 bc dbase1.png
    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 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.

  28. 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.
  29. Tute M01 bc dbase2.png
  30. If you haven't already, open the TUFLOW_tools_v2.0.xlam, this should create a new Menu Item titled TUFLOW. Navigate to this window and select Entire Worksheet to csv.
  31. 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 ommitted.

    Tute M01 bc dbase3.png


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

  32. Enter the following text in the .tcf file and save:
    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.

  33. Save a copy of M01_5m_001.tcf as M01_5m_002.tcf and make the following edits.
  34. Comment out (or delete) the "Write Empty GIS Files" line, using a comment character (! or #)
    ! Write Empty GIS Files == ..\model\gis\empty
  35. 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
    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.
  36. Using your preferred method detailed above (in Running TUFLOW), start TUFLOW. I am using batch file to start TUFLOW and I simply double click on this file in Windows Explorer.
  37. 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.

    Tute M01 Simulation Finished.png

    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

    Output Formats

    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!

    Viewing Results

  38. Open and view the TUFLOW results in your viewing package, for instructions on this please select your results package below.
  39. 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.

  40. In Windows Explorer, navigate to the TUFLOW\runs\Log\ directory and locate the M01_5m_002.tlf file. Drag and drop this file into your text editor. At the end of this file is the Simulation Summary.
  41. 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.

  42. Open the M01_5m_002_messages.csv file in the TUFLOW\runs\log\ directory. There may be a line in this file:
  43. 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.

  44. 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.
  45. 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 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.
    Tute M01 MB chart.jpg
    • 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.

    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 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.

    Troubleshooting

    This section contains a link to some common issues that may occur when progressing through the first module of the TUFLOW tutorial model.

    Advanced (Optional)

    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.

    Model Setup

    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).

    Results

    Using the methods described above here, view the results in your preferred package. Do the results appear much different?

    Optional 2.5m cell size simulation, depth and velocity results at 1:05 hours

    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
    5 1.5 -1.91 -0.57 2.3 -
    2.5 1.0 -0.81 -0.14 13.5 6.0

    Discussion

    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.