Tutorial M08

Introduction

In this module, scenario management is introduced. This is a powerful functionality running different simulations using a single set of control files rather than creating a new set of control files for every simulation. This makes the management of the model easier, ensures consistency between the simulations and better quality control. Without implementing scenario management, six TCFs and six TGC files are required to run this module, using scenario management, only one each is needed:



Scenarios are set up using an if scenario logic block - If Scenario command followed by Else If Scenario commands adding on different scenarios and terminated by End If.

The tutorial demonstrates two ways of using scenarios:

• Part 1: Single Scenario - cell size.
• Part 2: Multiple Scenarios - cell size and topography updates.

The GIS layers are:

• TGC layers:

1. 2d_zsh: A layer used to modify Zpt elevations using points, lines and polygons.
2. 2d_mat: A layer used to define the land use (material) types within the developmental area.

Module 8 builds from the model created in Module 2. The completed Module 2 model is provided in the Module_08\TUFLOW folder.

Part 1 - Single Scenario

Use scenario management to run the model with a range of different cell sizes, initial timesteps and SGS sample frequency within a single TCF. These steps are often used to conduct a cell size convergence sensitivity testing.

Simulation Control Files

TUFLOW Geometry Control File (TGC)

1. Save a copy of M02_001.tgc as M08_001.tgc in the Module_08\TUFLOW\model folder.
   
2. Open the M08_001.tgc in a text editor.
3. Comment out or delete the 'cell size' command and add the following if scenario logic block:
   ! Cell Size == 5 ! 2D cell size in metres
   If Scenario == 10m ! Beginning of if statement - 10m scenario
   
   Cell Size == 10 ! 2D cell size in metres - 10 metres
   

   Else If Scenario == 5m ! 5m scenario
   

   Cell Size == 5 ! 2D cell size in metres - 5 metres
   

   Else If Scenario == 2.5m ! 2.5m scenario
   

   Cell Size == 2.5 ! 2D cell size in metres - 2.5 metres
   

   Else ! Else statement
   

   Pause == Error: Scenario Name Not Valid ! Displays specified text if different scenario name is called
   

   End If ! End of if statement
   

4. Save the TGC.

Note: The Pause command causes TUFLOW to stop every time it encounters it. In the example above, if a cell size was specified other than 10m, 5m, or 2.5m, 'Error: Scenario Name Not Valid' would be displayed. The simulation can then be continued or discontinued via a dialog window.

TUFLOW Control File (TCF)

1. Save a copy of M02_5m_001.tcf as M08_~s1~_001.tcf in the Module_08\TUFLOW\runs folder.
2. Open the file M08_~s1~_001.tcf in a text editor.
3. Update the TGC reference:
   Geometry Control File == ..\model\M08_001.tgc ! Reference the TUFLOW Geometry Control File
   
4. The Timestep is dependent on the model cell size. A general guide is to use 1/2 to 1/5 of the model cell size in metres. Comment out or delete the 'Timestep' command and add the following if scenario logic block:
   ! Timestep == 1 ! Specifies the first 2D computational timestep of 1 second
   If Scenario == 10m ! Beginning of if statement - 10m scenario
   
   Timestep == 2 ! Specifies the first 2D computational timestep of 2 seconds
   

   Else If Scenario == 5m ! 5m scenario
   

   Timestep == 1 ! Specifies the first 2D computational timestep of 1 second
   

   Else If Scenario == 2.5m ! 2.5m scenario
   

   Timestep == 0.5 ! Specifies the first 2D computational timestep of 0.5 seconds
   

   Else ! Else statement
   

   Pause == Error: Scenario Name Not Valid ! Displays specified text if different scenario name is called
   

   End If ! End of if statement
   

5. Save the TCF.

Running the Simulation

1. Save a copy of _run_M02_HPC.bat as _run_M08_HPC.bat in the Module_08\TUFLOW\runs folder.
2. Update the batch file to reference the M08_~s1~_001.tcf and include a scenario switch (-s1) defining cell size:
   set exe="..\..\..\exe\2023-03-AF\TUFLOW_iSP_w64.exe"
   set run=start "TUFLOW" /wait %exe% -b
   %run% -s1 10m M08_~s1~_001.tcf
   %run% -s1 5m M08_~s1~_001.tcf
   %run% -s1 2.5m M08_~s1~_001.tcf
   
3. Save the batch file and double click it in file explorer to run the simulation.

Troubleshooting

See tips on common mistakes and troubleshooting steps if the model doesn't run:

• QGIS

Check Files

While the model is running, review the added features are specified correctly:

• QGIS - SHP
• QGIS - GPKG

Compare the model cell count:

1. Navigate to the Module_08\TUFLOW\runs\log folder and open the following files in a text editor:

   • M08_10m_001.tlf
   • M08_5m_001.tlf
   • M08_2.5m_001.tlf

2. Search for 'Number 2D Cells' and view the number of active cells for each model. This is the number of active cells as specified by the 2d_code layer. There are approximately 16 times more cells in the 2.5m model compared to the 10m model:

   • M08_10m_001: 5122
   • M08_5m_001: 20486
   • M08_2.5m_001: 81869

Results

When the model is finished, review the results:

• QGIS

Compare the model run times:

1. Navigate to the Module_08\TUFLOW\runs folder and open the _TUFLOW Simulations.log in a text editor.
2. The file shows the simulation times for all the simulations.
   
   
   

Part 2 - Multiple Scenarios

Use scenario management to run the model with a range of different cell sizes and topography changes within a single TCF. These steps are often used to conduct an impact assessment.

GIS Inputs

Create, import and view input data:

• QGIS - SHP
  
• QGIS - GPKG
  

Simulation Control Files

TUFLOW Geometry Control File (TGC)

1. Save a copy of M08_001.tgc as M08_002.tgc in the Module_08\TUFLOW\model folder.
   
2. Open the M08_002.tgc in a text editor.
3. Include the following if scenario logic block for existing and developed case after the 'Read GIS Z Shape' command:
   QGIS - SHP
   If Scenario == EXG ! Beginning of if statement - existing scenario
   
    ! Defines a placeholder
   

   Else If Scenario == DEV ! Development scenario
   

   Read GIS Z Shape == gis\2d_zsh_M02_landscape_002_R.shp | gis\2d_zsh_M02_landscape_002_L.shp | gis\2d_zsh_M02_landscape_002_P.shp ! Defines areas of complex landscaping
   

   Else ! Else statement
   

   Pause == Error: Scenario Name Not Valid ! Displays specified text if different scenario name is called
   

   End If ! End of if statement
   

   QGIS - GPKG
   If Scenario == EXG ! Beginning of if statement - existing scenario
   

    ! Defines a placeholder
   

   Else If Scenario == DEV ! Development scenario
   

   Read GIS Z Shape == 2d_zsh_M02_landscape_002_R | 2d_zsh_M02_landscape_002_L | 2d_zsh_M02_landscape_002_P ! Defines areas of complex landscaping
   

   Else ! Else statement
   

   Pause == Error: Scenario Name Not Valid ! Displays specified text if different scenario name is called
   

   End If ! End of if statement
   

4. Include the following if scenario logic block for existing and developed case after the 'Read GIS Mat' command:
   QGIS - SHP
   If Scenario == EXG ! Beginning of if statement - existing scenario
   
    ! Defines a placeholder
   

   Else If Scenario == DEV ! Development scenario
   

   Read GIS Mat == gis\2d_mat_M02_landscape_002_R.shp ! Sets material values according to attributes in the GIS layer
   

   Else ! Else statement
   

   Pause == Error: Scenario Name Not Valid ! Displays specified text if different scenario name is called
   

   End If ! End of if statement
   

   QGIS - GPKG
   If Scenario == EXG ! Beginning of if statement - existing scenario
   

    ! Defines a placeholder
   

   Else If Scenario == DEV ! Development scenario
   

   Read GIS Mat == 2d_mat_M02_landscape_002_R ! Sets material values according to attributes in the GIS layer
   

   Else ! Else statement
   

   Pause == Error: Scenario Name Not Valid ! Displays specified text if different scenario name is called
   

   End If ! End of if statement
   

5. Save the TGC.

TUFLOW Control File (TCF)

1. Save a copy of M08_~s1~_001.tcf as M08_~s1~_~s2~_002.tcf in the Module_08\TUFLOW\runs folder.
2. Open the file M08_~s1~_~s2~_002.tcf in a text editor.
3. Update the TGC reference:
   Geometry Control File == ..\model\M08_002.tgc ! Reference the TUFLOW Geometry Control File
   
4. For GeoPackage users, update the Spatial Database reference:
   QGIS - GPKG
   Spatial Database == ..\model\gis\M08_002.gpkg ! Specify the location of the GeoPackage Spatial Database
   
5. Save the TCF.

Running the Simulation

1. Open _run_M08_HPC.bat from the Module_08\TUFLOW\runs folder.
2. Update the batch file to reference the M08_~s1~_~s2~_002.tcf and in addition to cell size scenario switch (-s1) include second scenario switch (-s2) defining topography:
   set exe="..\..\..\exe\2023-03-AF\TUFLOW_iSP_w64.exe"
   set run=start "TUFLOW" /wait %exe% -b
   %run% -s1 2.5m -s2 EXG M08_~s1~_~s2~_002.tcf
   %run% -s1 2.5m -s2 DEV M08_~s1~_~s2~_002.tcf
   %run% -s1 5m -s2 EXG M08_~s1~_~s2~_002.tcf
   %run% -s1 5m -s2 DEV M08_~s1~_~s2~_002.tcf
   %run% -s1 10m -s2 EXG M08_~s1~_~s2~_002.tcf
   %run% -s1 10m -s2 DEV M08_~s1~_~s2~_002.tcf
   
3. Save the batch file and double click it in file explorer to run the simulation.
   

Troubleshooting

See tips on common mistakes and troubleshooting steps if the model doesn't run:

• QGIS

Check Files

While the model is running, review the added features are specified correctly:

• QGIS

Results

When the model is finished, review the results:

• QGIS

Conclusion

• Single and multiple scenarios were set up and run with a range of cell sizes and designs.
• Check files were assessed to view the changes based on each scenario.
• Multiple scenario results were viewed using the TUFLOW Viewer.

Looping Batch File (Optional)

Looping batch file is a powerful tool running large number of simulations with the least amount of batch file text:

1. Save a copy of _run_M08_HPC.bat as _run_M08_HPC_loop.bat in the Module_08\TUFLOW\runs folder.
2. Add the following commands. Indentation is important in batch files, insert tabs to match the below spacing:
   echo off
   set exe="..\..\..\exe\2023-03-AA\TUFLOW_iSP_w64.exe"
   set run=start "TUFLOW" /wait %exe% -b
   
   set CSZ=10m 5m 2.5m
   set DES=EXG DEV
   
   for %%a in (%CSZ%) do (
   
   for %%b in (%DES%) do (
   
   echo Running %%a %%b
   %run% -s1 %%a -s2 %%b M08_~s1~_~s2~_002.tcf
   
   )
   
   )
   

   Note: The 'CSZ' and 'DES' are user defined batch file variables. The 'CSZ' refers to a cell size and 'DES' refers to a design scenario.
   

3. Save the batch file and double click it in file explorer to run the simulation.

Up
Back to Tutorial Introduction Main Page