Tutorial Module05 Archive

Introduction

In this tutorial model we will complete a simplistic flood impact assessment. We will start with the model developed in Module 4 and modify this to represent a "developed" scenario. This will involve changing the geometry in the 2D model domain to:


• Remove a portion of the area from the floodplain (fill for development); and
• Lower an area to increase conveyance.

Once the model has been simulated, the pre and post development cases will be compared to determine the changes in peak water level and flood behaviour caused by the development.
In this module, we will also use an alternative 2D output type which stores all the results in a single output file (as opposed to individual data files) and use a folder structure to make the results files easier to navigate.

In a later tutorial module we will look at a more detailed impact assessment in which a detailed design surface is included in the model.

To take advantage of the elevation output in this tutorial, you will need to be running TUFLOW version 2012-05-AE or later. If the ZH (elevation) output type is used (as is the case with earlier versions), this will be written out at each output time as opposed to once for the entire simulation.

GIS Inputs

We have provided the location of the proposed development in the module data under Module_Data\Module_05\. Two GIS layers have been provided, Fill_Area and Cut_Area. For this impact assessment the fill area is to be removed from the floodplain for the 100 year Average Recurrence Interval (ARI) event being modelled. The cut area will have 1 m removed from the existing ground surface to increase the conveyance in the area. To make the GIS changes, please select your GIS package from the list below:

• MapInfo
• ArcGIS or QGIS



Control File

There are two methods for running multiple scenarios in TUFLOW:


• Create separate control files for each simulation; or
• Run multiple simulations from the same control file (.tcf) using simple logic statements

For this tutorial we will use the second approach. We will describe the logic as we progress through this tutorial, however, there are more details in the TUFLOW Manual. For this tutorial we will run two versions of the simulation, called EXG and DEV. The "EXG" case represents the existing or base case scenario. The models have the same boundaries, extents and DEM; the only difference will be that the "DEV" case has an additional layer to represent the proposed changes to the topography.

1. Save a copy of the TUFLOW Control File from module 4 (M04_5m_001.tcf) as M05_5m_~s1~_001.tcf.
   While we are going to run the model using the same control file, we still want individual results outputs and check files for each scenario. When we run the model, ~s1~ included in .tcf filename will be replaced with the scenario name (EXG or DEV).
2. Open the geometry control file M04_5m_001.tgc and save a copy as M05_5m_001.tgc.
3. Add the following in the new geometry control file below the Read GIS Z HX Line command:
   For MapInfo users add the following
   If Scenario == DEV
   

   Read GIS Z Shape == mi\2d_zsh_M05_development_001.mif
   

   Else If Scenario == EXG
   
   Else
   

   Pause == Scenario not recognised
   

   End If
   
   For other GIS users add the following
   If Scenario == DEV
   

   Read GIS Z Shape == gis\2d_zsh_M05_development_001_R.shp
   

   Else If Scenario == EXG
   
   Else
   

   Pause == Scenario not recognised
   

   End If
   
   The elevation section of the geometry control file will now look something like this:
   Set Zpts == 75
   Read GRID Zpts == grid\DEM_M01.asc
   
   Read GIS Z Shape == mi\2d_zsh_M03_Rd_Crest_001.mif
   Read GIS Z HX Line == mi\2d_bc_M04_hx_001.mif | mi\2d_bc_M04_hx_001_P.mif
   
   If Scenario == DEV
   

   Read GIS Z Shape == gis\2d_zsh_M05_development_001.mif
   

   Else If Scenario == EXG
   
   Else
   

   Pause == Scenario not recognised
   

   End If
   If the model is simulated with the DEV scenario, the additional 2d_zsh GIS layer will be read into the model. Otherwise, it will be omitted for the EXG scenario. In the above set of commands, if a scenario other than "DEV" or "EXG" is specified, the Pause command will pause the simulation and output the message Scenario not recognised. Although an optional step, including these commands will ensure that any errors in defining scenarios is captured. This is highly recommended when using nested If Scenario command blocks.
   As with all TUFLOW inputs the scenarios are case insensitive (or should that be cASe InSeNsItIvE)!
   
4. Save the geometry control file.
5. Update the geometry control file reference in the .tcf to the new M05_5m_001.tgc.
Next we will update a number of other options in the TUFLOW Control File .tcf.
6. For this and later modules we will use the .xmdf results output format. This is an alternative to the .dat files and has a number of advantages such as:
   • All results are stored in the same file
   • Results are much faster to access because indexing information is included; and
   • Use of a folder structure makes viewing results easier
   The .dat version can however still be used if preferred. In addition, we will also output ASC grid outputs. Add the following commands to the .tcf:
   Map Output Format == xmdf ASC
   ASC Map Output Interval == 0
   
The second command applies to ASC map output file formats only as denoted by the 'ASC' prefix. Specifying an interval of 0 will output only the maximums.

7. Add "ZH" to the Map Output Data Types. This will output the model elevations to the results file:
   Map Output Data Types == h V q d MB1 MB2 ZH
   

Run the models

We are now ready to run the model. Now that we have two scenarios, we can run them from a batch file, specifying the scenario switch, or from a text editor / windows explorer with the scenario included in the .tcf file. Both methods are described below.


From a batch file

Batch files are a powerful way of running multiple simulations. There is a page on the wiki dedicated to batch files. To run the simulations in series (one after the other), the batch file should look like the below:

Start "TUFLOW" /wait "C:\TUFLOW\Releases\2017-09-AC\w64\TUFLOW_iSP_w64.exe" -b -s1 EXG M05_5m_~s1~_001.tcf Start "TUFLOW" /wait "C:\TUFLOW\Releases\2017-09-AC\w64\TUFLOW_iSP_w64.exe" -b -s1 DEV M05_5m_~s1~_001.tcf

From left to right the inputs in the batch file do the following:

• Start "TUFLOW" opens a new window and gives it the title "TUFLOW".
  
• The /wait argument prevents the second line from running until the first simulation has finished. (To run the second line at the same time simply remove the /wait argument.)
  
• The next argument is the TUFLOW executable to be used. In our case this is C:\TUFLOW\Releases\2017-09-AC\w64\TUFLOW_iSP_w64.exe. This filepath will need to be updated.
  
• The -b switch tells TUFLOW to run in "batch" mode. This suppresses the message boxes at the end of the simulation and allows subsequent runs to start without user intervention.
  
• We need to input the scenario that we wish to simulate. The -s1 switch indicates a scenario argument. -s1 DEV indicates that the "DEV" scenario should be simulated. -s1 EXG indicates that the "EXG" scenario should be simulated. Up to 9 scenarios can be used in a single simulation.
  
• The final argument M05_5m_~s1~_001.tcf is the TUFLOW control file to be used for the simulation.

From Text Editor / Windows

In the batch file method above we specified the scenario to run. When we are creating a model or have only a small number of scenarios to run it is useful to be be able to start a simulation without using a batch file. To do this we need to include the scenario in the .tcf. To do so add the following line to the M05_5m_~s1~_001.tcf:
Model Scenarios == EXG
Save the control file and start the simulation from your text editor. Update the scenario to:
Model Scenarios == DEV
Resave the file and start the simulation. There should now be two simulations running. This method provides a quick way to start the simulations from your text editor, but when you have multiple scenarios and events batch files can streamline the process!

Compare Results

Once the simulations have finished processing we can compare the differences between the results for the "developed" and "existing" cases.


There are a number of different methods for comparing results datasets. In this tutorial we will outline this process in three ways:


• Using SMS
• Using GIS to subtract the grids
• Using the TUFLOW utilities

Care needs to be taken as not all methods will compare results when values exist in only one of the datasets. For example, in GIS a typical grid (raster) calculation will only output a difference if both grids have values. This can exclude areas from the difference grid where there has been an increase or decrease in flood extent.

SMS

SMS allows the user to easily compare datasets for the temporal and maximums data. To step through the process please see the following page.

• Flood afflux calculation in SMS

GIS

The TUFLOW to GIS utility can be used to export the results into GIS format as a raster dataset. Within your GIS package a grid calculation is performed to calculate the difference in peak water level. The first step in this process is to use the TUFLOW to GIS utility to create the gridded results files. Use of the utility was described in Module 1. There is also a separate page discussing the TUFLOW to GIS utility.
For this tutorial we will convert the peak water level results to raster grids using a batch file:


1. Create a new text file in the TUFLOW\results\M05\2d\ folder. Save this as convert_to_GIS.bat
2. Open this file in a text editor and add the following text. Note that in the first line, you will need to update the filepath to TUFLOW_to_GIS.exe to match the location of the utility on your computer.
   

   set t2g="C:\TUFLOW\utilities\TUFLOW_to_GIS.exe" %t2g% -asc -b -typeH -max -out M05_5m_exg_001_hMax M05_5m_exg_001.xmdf %t2g% -asc -b -typeH -max -out M05_5m_dev_001_hMax M05_5m_dev_001.xmdf

To perform the GIS calculation please select your GIS package below:

• MapInfo (Vertical Mapper)
• ArcMap
• QGIS

TUFLOW Utilities

There are two methods for calculating the flood afflux using the TUFLOW utilities:

• Using res_to_res (this requires the same number of elements in both scenarios)
• Using asc_to_asc

Both of these methods are outlined below.

Res_to_Res

This method compares the results at each of the model output points and requires an identical number of nodes in each results file. If the model extent or number of cells has changed between models, you will be unable to compare using this method.


1. Create a new text file in the TUFLOW\Results\M05\2d\ folder and save as afflux_res_to_res.bat
2. Open the file in a text editor and add the following lines:
   

   "C:\TUFLOW\utilities\res_to_res.exe" -dif -typeH -t99999 -out dH_M05_5m_001.xmdf M05_5m_dev_001.xmdf M05_5m_exg_001.xmdf

The above line will calculate the flood afflux and output this into a new file named dH_M05_5m_001.xmdf. The -t99999 flag specifies that the afflux is to be calculated at the maximums. If this were omitted the afflux would be calculated at each output timestep.
3. Double click on the batch file in Windows explorer to begin the utility.
This file can now be loaded into SMS or alternatively can be converted to GIS using the TUFLOW_to_GIS utility. The command for doing this is:


"C:\TUFLOW\utilities\TUFLOW_to_GIS_w64.exe" -asc -s1 -2dm M05_5m_Exg_001.2dm dH_M05_5m_001.xmdf

The results are stored in a folder "difference" in the .xmdf file with the name "diff_M05_5m_dev_001 - M05_5m_exg_001". When converting to .asc instead of using the -typeH argument -s1 is used instead to convert the 1st (and in this case only) scalar dataset. The -2dm M05_5m_Exg_001.2dm is used to specify the 2D mesh file to be associated with the .xmdf file. For the xmdf file output from TUFLOW the .2dm file has the same filename as the .xmdf file just a different extension. In this case a new .xmdf file has been created and so we need to specify the correct .2dm file.

Asc_to_Asc

The asc_to_asc utility performs a comparison of each of the raster cells in a pair of raster grids. For this reason, the output grid files must have the same extent and cell size. By default the utility will produce two output files, the first is the difference in locations where both models are wet. The second contains the areas where there has been a change in inundation extent (eg. was dry now wet). The first step in using the asc_to_asc utility is to convert the TUFLOW outputs into .asc format using TUFLOW_to_GIS.exe:

1. Create a new text file in the TUFLOW\results\M05\2d\ folder. Save this as afflux_asc_to_asc.bat
2. Open this file in a text editor and add the following text. Note that in the first two lines you will need to update the filepaths to the TUFLOW_to_GIS and Asc_to_Asc utilities to match their locations on your computer.
   

   set t2g="C:\TUFLOW\utilities\TUFLOW_to_GIS.exe" set a2a="C:\TUFLOW\utilities\asc_to_asc.exe" %t2g% -asc -b -typeH -max -out M05_5m_exg_001_hMax.asc M05_5m_exg_001.xmdf %t2g% -asc -b -typeH -max -out M05_5m_dev_001_hMax.asc M05_5m_dev_001.xmdf %a2a% -dif -out dhMax_M05_5m_001.asc M05_5m_dev_001_hMax.asc M05_5m_exg_001_hMax.asc

The first two lines set the locations of the utilities on your computer. Lines three and four convert the existing and developed case results to .asc format. The final line creates the difference grids using the asc_to_asc utility. The resulting grids can be opened / imported into your GIS package and contoured and a colouring style applied.

Conclusion

We have used the powerful topographic modification features in TUFLOW to run a 100 year ARI design flood for an existing and a proposed topography. We have compared the predicted peak water levels for the two simulations to create a flood afflux result grid. A variety of methods for calculating the flood afflux were provided.

Troubleshooting

If the TUFLOW simulation fails to start TUFLOW will output the error in a number of locations. Firstly, check the Console Window or the TUFLOW Log File (.tlf) (located in the TUFLOW\runs\log\ folder with the name M05_5m_001.tlf). This file can be opened in a text editor and the error is generally located at the end of the file. You can however search for "Error" if you can not see the error. In most cases there is also a spatial location for the error message (if the error reported in the log file is prefixed by XY:). To check the location of the geographic errors, open the M05_5m_001_messages.mif or M05_5m_001_messages_P.shp file in your GIS package.

This section contains links to some possible problems that may occur when progressing through the fifth tutorial module. If you experience an issue that is not detailed below, please email support@tuflow.com.


• Save date of .tab file is later than .mif or .mid
• When reviewing check files or results, I can't see the changes




Advanced - HPC Solver (Optional)

This section introduces how to run the model using TUFLOW’s HPC (Heavily Parallelised Compute) solver with scenario control. It is much more convenient to select the model solver using scenario control than how it was done in the previous tutorials, because you only need to create one .tcf file for both the HPC and/or Classic simulations.

Please see HPC Features Archive for more information on TUFLOW HPC features supported in the 2017 release.

Model Setup

In order to use the HPC solver, we will need to perform the following steps:

1. Save the TUFLOW runfile (M05_5m_~s1~_001.tcf) as M05_5m_~s1~_~s2~_002.tcf.
2. Add the following command to the TCF file:
   If Scenario == HPC
   

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

   Else If Scenario == CLA
   

   Solution Scheme == Classic
   

   Else
   

   Pause == Invalid solution scheme
   

   End If
   
   If you have a CUDA enabled NVIDIA GPU device, you can also add the "Hardware == GPU" command under the "Solution Scheme == HPC" command to run the HPC solver using GPU hardware. As such, the scenario logic should now look like this:
   If Scenario == HPC
   

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

   Hardware == GPU ! Run HPC solver on GPU
   

   Else If Scenario == CLA
   

   Solution Scheme == Classic
   

   Else
   

   Pause == Invalid solution scheme
   

   End If
   
3. Save the TCF file.
   
4. Update the batch file as follows and Run the model.
   

   Start "TUFLOW" /wait "C:\TUFLOW\Releases\2017-09-AC\w64\TUFLOW_iSP_w64.exe" -b -s1 EXG -s2 HPC M05_5m_~s1~_~s2~_002.tcf Start "TUFLOW" /wait "C:\TUFLOW\Releases\2017-09-AC\w64\TUFLOW_iSP_w64.exe" -b -s1 EXG -s2 CLA M05_5m_~s1~_~s2~_002.tcf Start "TUFLOW" /wait "C:\TUFLOW\Releases\2017-09-AC\w64\TUFLOW_iSP_w64.exe" -b -s1 DEV -s2 HPC M05_5m_~s1~_~s2~_002.tcf Start "TUFLOW" /wait "C:\TUFLOW\Releases\2017-09-AC\w64\TUFLOW_iSP_w64.exe" -b -s1 DEV -s2 CLA M05_5m_~s1~_~s2~_002.tcf

Results

Using the methods described above in the Viewing Results section of Module 1.

• 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 to the TUFLOW Classic simulation?

Troubleshooting for GPU Simulations

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