View source for 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:<br>
<br>
[[File:M08 ScenarioManagement 02.png]]<br>
<br>
Scenarios are set up using an if scenario logic block - <font color="blue"><tt>If Scenario</tt></font> command followed by <font color="blue"><tt>Else If Scenario</tt></font> commands adding on different scenarios and terminated by <font color="blue"><tt>End If</tt></font>.<br>

The tutorial demonstrates two ways of using scenarios:<br>
:*Part 1: Single Scenario - cell size.
:*Part 2: Multiple Scenarios - cell size and topography updates.

The GIS layers are:
:*TGC layers:
<ol><ol><li>2d_zsh: A layer used to modify Zpt elevations using points, lines and polygons.</ol></ol>

'''Module 8 builds from the model created in <u>[[Tutorial_M02 | Module 2]]</u>. The completed Module 2 model is provided in the Module_08\TUFLOW folder.''' <br>
<br>

=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) ===
<ol>
<li>Save a copy of '''M02_001.tgc''' as '''M08_001.tgc''' in the '''Module_08\TUFLOW\model''' folder. <br>
<li>Open the '''M08_001.tgc''' in a text editor.
<li>Comment out or delete the 'cell size' command and add the following if scenario logic block:<br>
<font color="green"><tt>! Cell Size == 5		! 2D cell size in metres</tt></font><br>
<font color="blue"><tt>If Scenario </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>10m </tt></font> <font color="green"><tt>          ! Beginning of if statement - 10m scenario</tt></font> <br>
<ol><font color="blue"><tt>Cell Size </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>10 </tt></font> <font color="green"><tt>         ! 2D cell size in metres - 10 metres</tt></font> <br></ol>
<font color="blue"><tt>Else If Scenario </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>5m </tt></font> <font color="green"><tt>      ! 5m scenario</tt></font> <br>
<ol><font color="blue"><tt>Cell Size </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>5 </tt></font> <font color="green"><tt>          ! 2D cell size in metres - 5 metres</tt></font> <br></ol>
<font color="blue"><tt>Else If Scenario </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>2.5m </tt></font> <font color="green"><tt>    ! 2.5m scenario</tt></font> <br>
<ol><font color="blue"><tt>Cell Size </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>2.5 </tt></font> <font color="green"><tt>        ! 2D cell size in metres - 2.5 metres</tt></font> <br></ol>
<font color="blue"><tt>Else </tt></font> <font color="green"><tt>  ! Else statement</tt></font> <br>
<ol><font color="blue"><tt>Pause </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>Error: Scenario Name Not Valid </tt></font> <font color="green"><tt>  ! Displays specified text if different scenario name is called </tt></font> <br></ol>
<font color="blue"><tt>End If	 </tt></font> <font color="green"><tt>  ! End of if statement</tt></font> <br>
<li>Save the TGC.
</ol>
Note: The <font color="blue"><tt>Pause </tt></font> 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) ===
<ol>
<li>Save a copy of '''M02_5m_001.tcf''' as '''M08_~s1~_001.tcf''' in the '''Module_08\TUFLOW\runs''' folder.
<li>Open the file '''M08_~s1~_001.tcf''' in a text editor.

<li>Update the TGC reference: <br>
<font color="blue"><tt>Geometry Control File </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>..\model\M08_001.tgc </tt></font> <font color="green"><tt>  ! Reference the TUFLOW Geometry Control File</tt></font> <br>
<li>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:<br>
<font color="green"><tt>! Timestep == 1		! Specifies the first 2D computational timestep of 1 second</tt></font><br>
<font color="blue"><tt>If Scenario </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>10m </tt></font> <font color="green"><tt>          ! Beginning of if statement - 10m scenario</tt></font> <br>
<ol><font color="blue"><tt>Timestep </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>2 </tt></font> <font color="green"><tt>	! Specifies the first 2D computational timestep of 2 seconds</tt></font> <br></ol>
<font color="blue"><tt>Else If Scenario </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>5m </tt></font> <font color="green"><tt>      ! 5m scenario</tt></font> <br>
<ol><font color="blue"><tt>Timestep </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>1 </tt></font> <font color="green"><tt>  ! Specifies the first 2D computational timestep of 1 seconds</tt></font> <br></ol>
<font color="blue"><tt>Else If Scenario </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>2.5m </tt></font> <font color="green"><tt>    ! 2.5m scenario</tt></font> <br>
<ol><font color="blue"><tt>Timestep </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>0.5 </tt></font> <font color="green"><tt>   ! Specifies the first 2D computational timestep of 0.5 seconds</tt></font> <br></ol>
<font color="blue"><tt>Else </tt></font> <font color="green"><tt>  ! Else statement</tt></font> <br>
<ol><font color="blue"><tt>Pause </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>Error: Scenario Name Not Valid </tt></font> <font color="green"><tt>  ! Displays specified text if different scenario name is called </tt></font> <br></ol>
<font color="blue"><tt>End If	 </tt></font> <font color="green"><tt>  ! End of if statement</tt></font> <br>
<li>Save the TCF.
</ol>

== Running the Simulation ==
<ol>
<li>Save a copy of '''_run_M02_HPC.bat''' as '''_run_M08_HPC.bat''' in the '''Module_08\TUFLOW\runs''' folder.
<li>Update the batch file to reference the '''M08_~s1~_001.tcf''' and include a scenario switch (-s1) defining cell size:<br>
<font color="blue"><tt>'''set'''</tt></font> <font color="black"><tt>exe</tt></font><font color="red"><tt>=</tt></font><font color="black"><tt>"..\..\..\exe\2023-03-AA\TUFLOW_iSP_w64.exe"</tt></font> <br>
<font color="blue"><tt>'''set'''</tt></font> <font color="black"><tt>run</tt></font><font color="red"><tt>=</tt></font><font color="black"><tt>start "TUFLOW" /wait</tt></font> <font color="orange"><tt> %exe%</tt></font> <font color="black"><tt> -b</tt></font> <br>
<font color="orange"><tt>%run% </tt></font> <font color="black"><tt> -s1 10m M08_~s1~_001.tcf </tt></font> <br>
<font color="orange"><tt>%run% </tt></font> <font color="black"><tt> -s1 5m M08_~s1~_001.tcf </tt></font> <br>
<font color="orange"><tt>%run% </tt></font> <font color="black"><tt> -s1 2.5m M08_~s1~_001.tcf </tt></font> <br>
<li>Save the batch file and double click it in file explorer to run the simulation.
</ol>

== Troubleshooting == 
See tips on common mistakes and troubleshooting steps if the model doesn't run:
:*<u>[[Tutorial_Troubleshooting_QGIS | QGIS]]</u>

== Check Files ==
While the model is running, review the added features are specified correctly:
:*<u>[[Tutorial_M08_001_Check_Files_QGIS | QGIS]]</u>
Compare the model cell count:
<ol>
<li>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'''
<li>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
</ol>

== Results==
When the model is finished, review the results:
:*<u>[[Tutorial_M08_001_Results_QGIS | QGIS]]</u>
Compare the model run times:
<ol>
<li>Navigate to the '''Module_08\TUFLOW\runs''' folder and open the '''_TUFLOW Simulations.log'''  in a text editor.
<li>The file shows the simulation times for all the simulations.
<br>
[[File:M08 TUFLOW Simulations.png]]<br>
</ol>
<br>

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

== GIS Inputs ==
Create, import and view input data:<br>
:*<u>[[Tutorial_M08_002_GIS_Inputs_QGIS | QGIS]]</u><br>

== Simulation Control Files == 
=== TUFLOW Geometry Control File (TGC) ===
<ol>
<li>Save a copy of '''M08_001.tgc''' as '''M08_002.tgc''' in the '''Module_08\TUFLOW\model''' folder. <br>
<li>Open the '''M08_002.tgc''' in a text editor.
<li>Include the following if scenario logic block for existing and developed case after the '<font color="blue"><tt>Read GIS Z Shape </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>gis\2d_zsh_M02_rd_crest_001_L.shp | gis\2d_zsh_M02_rd_crest_001_P.shp</tt></font>' command:<br>
<font color="blue"><tt>If Scenario </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>EXG </tt></font> <font color="green"><tt>          ! Beginning of if statement - existing scenario</tt></font> <br>
<ol><font color="green"><tt> ! Defines a placeholder</tt></font> <br></ol>
<font color="blue"><tt>Else If Scenario </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>DEV </tt></font> <font color="green"><tt>     ! Development scenario</tt></font> <br>
<ol><font color="blue"><tt>Create TIN Zpts </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>gis\2d_zsh_M02_landscape_002_R.shp | gis\2d_zsh_M02_landscape_002_L.shp | gis\2d_zsh_M02_landscape_002_P.shp </tt></font> <font color="green"><tt>         ! Defines areas of complex landscaping</tt></font> <br></ol>
<font color="blue"><tt>Else </tt></font> <font color="green"><tt>  ! Else statement</tt></font> <br>
<ol><font color="blue"><tt>Pause </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>Error: Scenario Name Not Valid </tt></font> <font color="green"><tt>  ! Displays specified text if different scenario name is called </tt></font> <br></ol>
<font color="blue"><tt>End If	 </tt></font> <font color="green"><tt>  ! End of if statement</tt></font> <br>
<li>Save the TGC.
</ol>

=== TUFLOW Control File (TCF) ===
<ol>
<li>Save a copy of '''M08_~s1~_001.tcf''' as '''M08_~s1~_~s2~_002.tcf''' in the '''Module_08\TUFLOW\runs''' folder.
<li>Open the file '''M08_~s1~_~s2~_002.tcf''' in a text editor.
<li>Update the TGC reference: <br>
<font color="blue"><tt>Geometry Control File </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>..\model\M08_002.tgc </tt></font> <font color="green"><tt>  ! Reference the TUFLOW Geometry Control File</tt></font> <br>
<li>Save the TCF.
</ol>

== Running the Simulation ==
<ol>
<li>Open '''_run_M08_HPC.bat''' from the '''Module_08\TUFLOW\runs''' folder.
<li>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:<br>
<font color="blue"><tt>'''set'''</tt></font> <font color="black"><tt>exe</tt></font><font color="red"><tt>=</tt></font><font color="black"><tt>"..\..\..\exe\2023-03-AA\TUFLOW_iSP_w64.exe"</tt></font> <br>
<font color="blue"><tt>'''set'''</tt></font> <font color="black"><tt>run</tt></font><font color="red"><tt>=</tt></font><font color="black"><tt>start "TUFLOW" /wait</tt></font> <font color="orange"><tt> %exe%</tt></font> <font color="black"><tt> -b</tt></font> <br>
<font color="orange"><tt>%run% </tt></font> <font color="black"><tt> -s1 2.5m -s2 EXG M08_~s1~_~s2~_002.tcf </tt></font> <br>
<font color="orange"><tt>%run% </tt></font> <font color="black"><tt> -s1 2.5m -s2 DEV M08_~s1~_~s2~_002.tcf </tt></font> <br>
<font color="orange"><tt>%run% </tt></font> <font color="black"><tt> -s1 5m -s2 EXG M08_~s1~_~s2~_002.tcf </tt></font> <br>
<font color="orange"><tt>%run% </tt></font> <font color="black"><tt> -s1 5m -s2 DEV M08_~s1~_~s2~_002.tcf </tt></font> <br>
<font color="orange"><tt>%run% </tt></font> <font color="black"><tt> -s1 10m -s2 EXG M08_~s1~_~s2~_002.tcf </tt></font> <br>
<font color="orange"><tt>%run% </tt></font> <font color="black"><tt> -s1 10m -s2 DEV M08_~s1~_~s2~_002.tcf </tt></font> <br>
<li>Save the batch file and double click it in file explorer to run the simulation.<br>
</ol>

== Troubleshooting == 
See tips on common mistakes and troubleshooting steps if the model doesn't run:
:*<u>[[Tutorial_Troubleshooting_QGIS | QGIS]]</u>

== Check Files ==
While the model is running, review the added features are specified correctly:
:*<u>[[Tutorial_M08_002_Check_Files_QGIS | QGIS]]</u>

== Results==
When the model is finished, review the results:
:*<u>[[Tutorial_M08_002_Results_QGIS | QGIS]]</u>
<br>

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

=Looping Batch File (Optional)=
Looping batch file is a powerful tool running large number of simulations with the least amount of batch file text:
<ol>
<li>Save a copy of '''_run_M08_HPC.bat''' as '''_run_M08_HPC_loop.bat''' in the '''Module_08\TUFLOW\runs''' folder.
<li>Add the following commands. Indentation is important in batch files, insert tabs to match the below spacing:<br>
<font color="blue"><tt>echo </tt></font> <font color="black"><tt>off</tt></font><br>
<font color="blue"><tt>set </tt></font> <font color="black"><tt>exe</tt></font><font color="red"><tt>=</tt></font><font color="black"><tt>"..\..\..\exe\2023-03-AA\TUFLOW_iSP_w64.exe"</tt></font><br>
<font color="blue"><tt>set </tt></font> <font color="black"><tt>run</tt></font><font color="red"><tt>=</tt></font><font color="black"><tt>start "TUFLOW" /wait </tt></font><font color="orange"><tt>%exe%</tt></font><font color="black"><tt> -b</tt></font><br>
<br>
<font color="blue"><tt>set</tt></font> <font color="black"><tt> CSZ</tt></font><font color="red"><tt>=</tt></font><font color="black"><tt>10m 5m 2.5m</tt></font><br>
<font color="blue"><tt>set</tt></font> <font color="black"><tt> DES</tt></font><font color="red"><tt>=</tt></font><font color="black"><tt>EXG DEV</tt></font><br>
<br>
<font color="blue"><tt>for </tt></font><font color="orange"><tt>%%a</tt></font><font color="blue"><tt> in </tt></font><font color="black"><tt>(</tt></font><font color="orange"><tt>%CSZ%</tt></font><font color="black"><tt>)</tt></font><font color="blue"><tt> do </tt></font><font color="black"><tt>(</tt></font><br>
<ol><font color="blue"><tt>	for </tt></font><font color="orange"><tt>%%b</tt></font><font color="blue"><tt> in </tt></font><font color="black"><tt>(</tt></font><font color="orange"><tt>%DES%</tt></font><font color="black"><tt>)</tt></font><font color="blue"><tt> do </tt></font><font color="black"><tt>( </tt></font><br>
<ol><ol><font color="blue"><tt>		echo </tt></font><font color="black"><tt>Running </tt></font><font color="orange"><tt>%%a %%b </tt></font><br>
	<font color="orange"><tt>	%run% </tt></font><font color="black"><tt>-s1 </tt></font><font color="orange"><tt>%%a</tt></font><font color="black"><tt> -s2 </tt></font><font color="orange"><tt>%%b </tt></font><font color="black"><tt>M08_~s1~_~s2~_002.tcf</tt></font> <br>
</ol></ol>	)<br>
</ol>)<br>
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. <br>
<li>Save the batch file and double click it in file explorer to run the simulation.
</ol><br>

{{Tips Navigation
|uplink=[[Tutorial_Introduction| Back to Tutorial Introduction Main Page]]
}}