View source for Tutorial M09

= Introduction =
In this module, event management is introduced. This is a powerful functionality running multiple event combinations (e.g. magnitude, duration, temporal patterns, climate change) 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 event management, six TCFs and six bc_dbase files are required to run this module, using event management, only one each is needed:

<br>
[[File:M09 EventManagement 01a.png]]<br>
<br>
 
Events are set up using a define event block in TUFLOW Event File (TEF) - <font color="blue"><tt>Define Event</tt></font> command terminated by <font color="blue"><tt>End Define</tt></font>. <br>

The TUFLOW control files are:
:*TUFLOW Events File (TEF): A database of TCF and ECF commands for different events.<br>

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

= Simulation Control Files =
=== TUFLOW Event File (TEF) ===
<ol>
<li>Navigate to the '''Module_09\Tutorial_Data''' folder. Copy the '''Event_File.tef''' in to the ''' Module_09\TUFLOW\runs''' folder. 
<li>Open the TEF in a text editor. There are three event magnitudes and two event durations listed:
:*Event Magnitudes: 5% AEP, 2% AEP and 1% AEP
:*Event Durations: 1hr and 2hr 
<li>The event specific commands are contained between the <font color="blue"><tt>Define Event</tt></font> and <font color="blue"><tt>End Define</tt></font> commands. 
<li>The <font color="blue"><tt>BC Event Source</tt></font> command is linked to the bc_dbase file. In the below examples, any occurrence of '~AEP~' in the bc_dbase is replaced with '05p' and any occurrence of '~DUR~' in the bc_dbase is replaced with '1hr'.<br>
<font color="green"><tt>! EVENT MAGNITUDES</tt></font><br>
<font color="blue"><tt>Define Event</tt></font> <font color="red"><tt> == </tt></font> <font color="black"><tt>05p</tt></font>
 <ol><font color="blue"><tt>   BC Event Source </tt></font> <font color="red"><tt>==</tt></font> <font color="black"><tt> ~AEP~ | 05p</tt></font>
</ol><font color="blue"><tt>End Define</tt></font><br>
<font color="green"><tt>! EVENT DURATIONS</tt></font><br>
<font color="blue"><tt>Define Event</tt></font> <font color="red"><tt> == </tt></font> <font color="black"><tt>1hr</tt></font>
 <ol><font color="blue"><tt>   BC Event Source </tt></font> <font color="red"><tt>==</tt></font> <font color="black"><tt> ~DUR~ | 1hr</tt></font>
</ol><font color="blue"><tt>End Define</tt></font>
Note: The 'AEP' and 'DUR' are user defined variables. The 'AEP' refers to an event magnitude (Annual Exceedance Probability) and 'DUR' refers to an event duration.<br>
<li>TUFLOW reads all of the defined events in the TEF and selects the ones specified in the batch file. <br>
</ol>

=== TUFLOW Boundary Condition Database (bc_dbase) ===
Update the bc_dbase with event magnitude and event duration placeholders:
<ol>
<li>Navigate to the '''Module_09\Tutorial_Data''' folder. Copy and paste the following files to the ''' Module_09\TUFLOW\bc_dbase''' folder. These files contains the inflows for each event magnitude and duration. 
:*05p1hr.csv
:*05p2hr.csv
:*02p1hr.csv
:*02p2hr.csv
:*01p1hr.csv
:*01p2hr.csv
<li>Save a copy of the '''bc_dbase.csv''' as '''bc_dbase_M09_001.csv'''.
<li>Open the file and make the following updates to the 'Source' column:<br>
<br>
[[File:M09 bc dbase 02.png]]<br>
<br>
<li>Save the bc_dbase.
</ol>

=== TUFLOW Control File (TCF) ===
<ol>
<li>Save a copy of '''M02_5m_001.tcf''' as '''M09_5m_~e1~_~e2~_001.tcf''' in the '''Module_09\TUFLOW\runs''' folder.
<li>Open the file '''M09_5m_~e1~_~e2~_001.tcf''' in a text editor.
<li>Update the reference to the bc_dbase:<br>
<font color="blue"><tt>BC Database </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> ..\bc_dbase\bc_dbase_M09_001.csv	 </tt></font> <font color="green"><tt>  ! Reference the Boundary Conditions Database</tt></font> <br>
<li>Add the following command to reference the TEF at the end of the TCF:  <br>
<font color="green"><tt>! EVENTS</tt></font> <br>
<font color="blue"><tt>Event File </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> Event_File.tef	 </tt></font> <font color="green"><tt>  ! Reference the TUFLOW Event File</tt></font> <br>
<li>Save the TCF.
</ol>
<br>

= Running the Simulation =
<ol>
<li>Save a copy of '''_run_M02_HPC.bat''' as '''_run_M09_HPC.bat''' in the '''Module_09\TUFLOW\runs''' folder.
<li>Update the batch file to reference the '''M09_5m_~e1~_~e2~_001.tcf''' and include event switches (-e1, -e2) defining event magnitude and event duration:<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-AF\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> -e1 05p -e2 1hr M09_5m_~e1~_~e2~_001.tcf </tt></font> <br>
<font color="orange"><tt>%run% </tt></font> <font color="black"><tt> -e1 05p -e2 2hr M09_5m_~e1~_~e2~_001.tcf </tt></font> <br>
<font color="orange"><tt>%run% </tt></font> <font color="black"><tt> -e1 02p -e2 1hr M09_5m_~e1~_~e2~_001.tcf </tt></font> <br>
<font color="orange"><tt>%run% </tt></font> <font color="black"><tt> -e1 02p -e2 2hr M09_5m_~e1~_~e2~_001.tcf </tt></font> <br>
<font color="orange"><tt>%run% </tt></font> <font color="black"><tt> -e1 01p -e2 1hr M09_5m_~e1~_~e2~_001.tcf </tt></font> <br>
<font color="orange"><tt>%run% </tt></font> <font color="black"><tt> -e1 01p -e2 2hr M09_5m_~e1~_~e2~_001.tcf </tt></font> <br>
<li>Save the batch file and double click it in file explorer to run the simulation.<br>
</ol>
<br>

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

= Check Files =
While the model is running, review the added features are specified correctly:
<ol>
<li>Open the '''M09_5m_05p_1hr_001.tlf''' from the '''Module_09\TUFLOW\runs\log''' folder in a text editor. 
<li>The name of the events replaced the placeholders in the TCF name.
<li>Confirm the specified events and event sources:<br>
{{Video|name=Animation_M09_Check_01c.mp4|width=928}}
<br>
</ol>

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

= Conclusion =
:*Multiple events were set up in the TUFLOW Event File (TEF) with define event blocks.
:*TUFLOW Log Files (TLF) were reviewed.
:*Multiple event results were inspected 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_M09_HPC.bat''' as '''_run_M09_HPC_loop.bat''' in the '''Module_09\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-AF\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> AEP</tt></font><font color="red"><tt>=</tt></font><font color="black"><tt>05p 02p 01p</tt></font><br>
<font color="blue"><tt>set</tt></font> <font color="black"><tt> DUR</tt></font><font color="red"><tt>=</tt></font><font color="black"><tt>1hr 2hr</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>%AEP%</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>%DUR%</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>-e1 </tt></font><font color="orange"><tt>%%a</tt></font><font color="black"><tt> -e2 </tt></font><font color="orange"><tt>%%b </tt></font><font color="black"><tt>M09_5m_~e1~_~e2~_001.tcf</tt></font> <br>
</ol></ol>	)<br>
</ol>)<br>
Note: The 'AEP' and 'DUR' are user defined batch file variables. The 'AEP' refers to an event magnitude (Annual Exceedance Probability) and 'DUR' refers to an event duration.
<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]]
}}