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:
- 2d_zsh: A layer used to modify Zpt elevations using points, lines and polygons.
- 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)
- Save a copy of M02_001.tgc as M08_001.tgc in the Module_08\TUFLOW\model folder.
- Open the M08_001.tgc in a text editor.
- 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
- 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)
- Save a copy of M02_5m_001.tcf as M08_~s1~_001.tcf in the Module_08\TUFLOW\runs folder.
- Open the file M08_~s1~_001.tcf in a text editor.
- Update the TGC reference:
Geometry Control File == ..\model\M08_001.tgc ! Reference the TUFLOW Geometry Control File
- 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 seconds
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
- Save the TCF.
Running the Simulation
- Save a copy of _run_M02_HPC.bat as _run_M08_HPC.bat in the Module_08\TUFLOW\runs folder.
- 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-AA\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
- 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:
Check Files
While the model is running, review the added features are specified correctly:
Compare the model cell count:
- 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
- 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:
Compare the model run times:
- Navigate to the Module_08\TUFLOW\runs folder and open the _TUFLOW Simulations.log in a text editor.
- 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:
Simulation Control Files
TUFLOW Geometry Control File (TGC)
- Save a copy of M08_001.tgc as M08_002.tgc in the Module_08\TUFLOW\model folder.
- Open the M08_002.tgc in a text editor.
- Include the following if scenario logic block for existing and developed case after the 'Read GIS Z Shape == gis\2d_zsh_M02_rd_crest_001_L.shp | gis\2d_zsh_M02_rd_crest_001_P.shp' command:
If Scenario == EXG ! Beginning of if statement - existing scenario
- ! Defines a placeholder
Else If Scenario == DEV ! Development scenario
- Create TIN Zpts == 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
- Include the following if scenario logic block for existing and developed case after the 'Read GIS Mat == gis\2d_mat_M01_001_R.shp' command:
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
- Save the TGC.
TUFLOW Control File (TCF)
- Save a copy of M08_~s1~_001.tcf as M08_~s1~_~s2~_002.tcf in the Module_08\TUFLOW\runs folder.
- Open the file M08_~s1~_~s2~_002.tcf in a text editor.
- Update the TGC reference:
Geometry Control File == ..\model\M08_002.tgc ! Reference the TUFLOW Geometry Control File
- Save the TCF.
Running the Simulation
- Open _run_M08_HPC.bat from the Module_08\TUFLOW\runs folder.
- 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-AA\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
- 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:
Check Files
While the model is running, review the added features are specified correctly:
Results
When the model is finished, review the results:
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:
- Save a copy of _run_M08_HPC.bat as _run_M08_HPC_loop.bat in the Module_08\TUFLOW\runs folder.
- 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.
- Save the batch file and double click it in file explorer to run the simulation.
Up |
---|
Back to Tutorial Introduction Main Page |