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:

Events are set up using a define event block in TUFLOW Event File (TEF) - Define Event command terminated by End Define.

The TUFLOW control files are:

• TUFLOW Events File (TEF): A database of TCF and ECF commands for different events.
  

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

Simulation Control Files

TUFLOW Event File (TEF)

1. Navigate to the Module_09\Tutorial_Data folder. Copy the Event_File.tef in to the Module_09\TUFLOW\runs folder.
2. 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

3. The event specific commands are contained between the Define Event and End Define commands.
4. The BC Event Source 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'.
   ! EVENT MAGNITUDES
   Define Event == 05p
   BC Event Source == ~AEP~ | 05p
   End Define
   

   ! EVENT DURATIONS
   Define Event == 1hr

   BC Event Source == ~DUR~ | 1hr
   End Define

   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.
   

5. TUFLOW reads all of the defined events in the TEF and selects the ones specified in the batch file.
   

TUFLOW Boundary Condition Database (bc_dbase)

Update the bc_dbase with event magnitude and event duration placeholders:

1. 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

2. Save a copy of the bc_dbase.csv as bc_dbase_M09_001.csv.
3. Open the file and make the following updates to the 'Source' column:
   
   
   
   
4. Save the bc_dbase.

TUFLOW Control File (TCF)

1. Save a copy of M02_5m_001.tcf as M09_5m_~e1~_~e2~_001.tcf in the Module_09\TUFLOW\runs folder.
2. Open the file M09_5m_~e1~_~e2~_001.tcf in a text editor.
3. Update the reference to the bc_dbase:
   BC Database == ..\bc_dbase\bc_dbase_M09_001.csv ! Reference the Boundary Conditions Database
   
4. Add the following command to reference the TEF at the end of the TCF:
   ! EVENTS
   Event File == Event_File.tef ! Reference the TUFLOW Event File
   
5. Save the TCF.

Running the Simulation

1. Save a copy of _run_M02_HPC.bat as _run_M09_HPC.bat in the Module_09\TUFLOW\runs folder.
2. 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:
   set exe="..\..\..\exe\2023-03-AA\TUFLOW_iSP_w64.exe"
   set run=start "TUFLOW" /wait %exe% -b
   %run% -e1 05p -e2 1hr M09_5m_~e1~_~e2~_001.tcf
   %run% -e1 05p -e2 2hr M09_5m_~e1~_~e2~_001.tcf
   %run% -e1 02p -e2 1hr M09_5m_~e1~_~e2~_001.tcf
   %run% -e1 02p -e2 2hr M09_5m_~e1~_~e2~_001.tcf
   %run% -e1 01p -e2 1hr M09_5m_~e1~_~e2~_001.tcf
   %run% -e1 01p -e2 2hr M09_5m_~e1~_~e2~_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:

1. Open the M09_5m_05p_1hr_001.tlf from the Module_09\TUFLOW\runs\log folder in a text editor.
2. The name of the events replaced the placeholders in the TCF name.
3. Confirm the specified events and event sources:
   
   
   
   

Results

When the model is finished, review the results:

• QGIS

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.

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_M09_HPC.bat as _run_M09_HPC_loop.bat in the Module_09\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 AEP=05p 02p 01p
   set DUR=1hr 2hr
   
   for %%a in (%AEP%) do (
   
   for %%b in (%DUR%) do (
   
   echo Running %%a %%b
   %run% -e1 %%a -e2 %%b M09_5m_~e1~_~e2~_001.tcf
   
   )
   
   )
   

   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.

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

Up
Back to Tutorial Introduction Main Page