View source for TUFLOW SWMM Tutorial M04

= Introduction =
This tutorial, Module 4 of the TUFLOW SWMM tutorial dataset will demonstrate TUFLOW's in-bulit event management functionality. This powerful functionality runs 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. For example, without implementing event management a project requiring simulation of the following event combinations would require 144 TCF and bc_dbase files:
* 6 x Event Magnitude (AEP):	01p, 02p, 05p, 10p, 20p, 50p
* 8 x Event Duration (hour):	1h, 2h, 3h, 6h, 9h, 12h, 18h, 24h
* 3 x Climate Change Horizon:	current climate, 2050, 2100
Using predefined naming conventions, with TUFLOW's event management functionality, all the events can be executed from a single TCF and bc_dbase file! 

This feature of TUFLOW makes the management of the model files easier, ensures consistency between the simulations and improves project quality control by reducing the likelihood of human error associated with incorrect file referencing. <br>  

TUFLOW SWMM Tutorial Module 4 builds from the model created in <u>[[TUFLOW_SWMM_Tutorial_M03|TUFLOW SWMM Tutorial Module 3]]</u>. The completed TUFLOW SWMM Module 3 model is provided in the '''''TUFLOW_SWMM_Module_04\TUFLOW''''' folder of the download dataset as the starting point for this tutorial. If you are not already familiar with TUFLOW SWMM linking, we recommend first completing Module 1, 2 and 3 before this tutorial. <br>

= Simulation Control Files =
TUFLOW's automated event management operates by introducing wildcard referencing into the boundary condition database.<br>
A new control file, called the "TUFLOW Event File" is added. It lists all event titles which are applied to the wild charatcter in the boundary condition database. It also lists unique commands to associate with the specific events.<br>
Models are executed using a batch file, with the event specifion listed as a variable in the batch file syntax.


This tutorial example will upgrade our single simulation model to run six (six) event simulations. The simulations will cater for three (3) Annual Exceedance Probability (AEP) event magnitudes:  5%, 2% and 1% AEP (in Average Recurrance Interval (ARI) terminology, this translates to the 1 in 20, 50 and 100 year ARI events). The design storms will be simulated for two (2) event storm durations: 1 and 2 hour.
   
=== TUFLOW Boundary Condition Database (bc_dbase) ===
The first task when updating a model with Event Management functionality is to update the bc_dbase.csv with event magnitude and event duration wildcard placeholders:
<ol>
<li>We will use the following wildcard characters to represent the Events in our model:
<li>Event Magnitude = AEP

<li>Event Duration = DUR 

<li>Navigate to the '''TUFLOW_SWMM_Module_04\Tutorial_Data''' folder. Copy and paste the following files to the ''' TUFLOW_SWMM_Module_04\TUFLOW\bc_dbase''' folder. These files contains the inflows for each event magnitude and duration. 
:*TS04_inflow_05p1hr.csv
:*TS04_inflow_05p2hr.csv
:*TS04_inflow_02p1hr.csv
:*TS04_inflow_02p2hr.csv
:*TS04_inflow_01p1hr.csv
:*TS04_inflow_01p2hr.csv
:*TS04_rainfall_05p1hr.csv
:*TS04_rainfall_05p2hr.csv
:*TS04_rainfall_02p1hr.csv
:*TS04_rainfall_02p2hr.csv
:*TS04_rainfall_01p1hr.csv
:*TS04_rainfall_01p2hr.csv <br>
The files with 'inflow' in their name are flow hydrograph boundary conditions sourced from an external hydrology model, such as HEC-HMS, RORB, URBS, WBNM etc. The files with 'rainfall' in their name are rainfall depth hyetographs used to define the rainfall timeseries in the SWMM urban hydrology section of the model.

<li>Save a copy of the '''bc_dbase.csv''' as '''bc_dbase_TS04_001.csv'''.
<li>Open the file and make the following updates to the 'Source' column:<br>
<br>
[[File:SWMM_M04_Event_bcdbase_001.JPG||500px]]<br>
<br>
<li>Save '''bc_dbase_TS04_001.csv'''.
</ol>

=== TUFLOW Event File (TEF) ===
<ol>
<li>Navigate to the '''TUFLOW_SWMM_Module_04\Tutorial_Data''' folder. Copy the '''TS04_Event_File.tef''' to the '''TUFLOW_SWMM_Module_04\TUFLOW\runs''' folder. 
<li>Open the TEF in a text editor. There are three event magnitudes and two event durations listed:
:*Event Magnitudes: 5% , 2% and 1% AEP
:*Event Durations: 1 and 2 hour 
<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 Control File (TCF) ===
<ol>
<li>Save a copy of '''TS03_5m_001.tcf''' as '''TS04_5m_~e1~_~e2~_001.tcf''' in the '''TUFLOW_SWMM_Module_04\TUFLOW\runs''' folder.
<li>Open the file '''TS04_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_TS04_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> TS04_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_TS03_HPC.bat''' as '''_run_TS04_HPC.bat''' in the '''TUFLOW_SWMM_Module_04\TUFLOW\runs''' folder.

<li>Update the batch file to reference the '''TS04_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-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> -e1 05p -e2 1hr TS04_5m_~e1~_~e2~_001.tcf </tt></font> <br>
<font color="orange"><tt>%run% </tt></font> <font color="black"><tt> -e1 05p -e2 2hr TS04_5m_~e1~_~e2~_001.tcf </tt></font> <br>
<font color="orange"><tt>%run% </tt></font> <font color="black"><tt> -e1 02p -e2 1hr TS04_5m_~e1~_~e2~_001.tcf </tt></font> <br>
<font color="orange"><tt>%run% </tt></font> <font color="black"><tt> -e1 02p -e2 2hr TS04_5m_~e1~_~e2~_001.tcf </tt></font> <br>
<font color="orange"><tt>%run% </tt></font> <font color="black"><tt> -e1 01p -e2 1hr TS04_5m_~e1~_~e2~_001.tcf </tt></font> <br>
<font color="orange"><tt>%run% </tt></font> <font color="black"><tt> -e1 01p -e2 2hr TS04_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 ==
Did your TUFLOW SWMM model fail to run successfully? If so, here is a link to a troubleshooting guide: <u>[[TUFLOW_SWMM_Troubleshooting | TUFLOW SWMM Troubleshooting]]</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=

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

<br>
{{Tips Navigation
|uplink=[[TUFLOW_SWMM_Tutorial_Introduction#Tutorial_Modules| Back to TUFLOW SWMM Tutorial Introduction Main Page]]
}}