13.2 Simulation Management

TUFLOW incorporates powerful functionality for managing the simulation of multiple events and scenarios. These features allow many simulations to be initiated from a single .tcf file (see Section 4.1.5), rather than duplicating model inputs and control files (e.g. *.tcf, *.tgc, *.ecf, *.tbc, *.trfc, BC Database, etc.) for every model variation. In many cases, one set of control files can be used.

Event and scenario simulation management can support an unlimited number of simulations. For example, the TUFLOW Insights Library includes a case study where a single set of control files was used to run 328,886 combinations of model domains, events and scenarios collectively covering the country of Scotland.

There are numerous examples (with associated data downloads) which demonstrate these powerful features:

The following sections of the manual discuss the available options.

13.2.1 Events

TUFLOW’s Events feature enables the design of a single model setup that can be used to simulate multiple events without duplicating any input control files. This not only makes management of the model easier, but it also ensures consistency between the simulations and supports better project quality control.

Most hydraulic modelling studies require the simulation of multiple different historic and design events. For example, a flood study may assess:

  • Numerous historic calibration/validation events
  • Multiple Annual Exceedance Probability (AEP) events (e.g. 50%, 20%, 10%, 5%, 2%, 1%, 0.5%, 0.2%)
  • Multiple rainfall event durations
  • Various event temporal pattern options
  • Alternative downstream boundary conditions (e.g. storm tides)
  • Future climate change scenarios

The total number of simulations to accommodate for the range of event combinations can sum to hundreds, if not thousands.

Multiple events are set up through a TUFLOW Event File (.tef) using the Define Event command. The structure and configuration of a .tef is described in Section 4.1.10. This section focuses on grouping, selecting and applying events in simulations.

The If Event command block controls which commands are executed based on the selected event(s) at run time. Its structure is equivalent to a standard programming structure: If… Else If… Else… End If. Event logic (If Event) can be used in most of TUFLOW’s control files where model inputs or parameters may vary by extent. Event logic is not supported in the TUFLOW External Stress File (Section 4.1.13), Advection Control File (Section 4.1.14) and within a Define Control block inside a TUFLOW Operational Control File (Section 4.1.11) file. See Section 13.2.1.1 below for more information.

All defined events are automatically available as variables and can be referenced in control files. See Section 13.2.3.

13.2.1.1 Event Groups

Up to nine different event groups (e1 to e9) can be specified for a single simulation. Each group can contain an unlimited number of events. Also, If Event blocks can be nested up to 10 levels, see Example 3 below (Section 13.2.1.4). Event groups typically represent independent parameters such as:

  • Flood event magnitude: 50%, 20%, 10%, 5%, 2%, 1%, 0.5%, 0.2% AEP
  • Storm duration: 1h, 2h, 3h, 4h, 6h, 9h, 12h
  • Design event temporal pattern: TP01, TP02, TP03, TP04, TP05, TP06, TP07, TP08, TP09, TP10
  • Downstream boundary condition: LAT, HAT, 5 year, 10 year
  • Climate change time horizon: 2025, 2050, 2100

The .tef file (see Section 4.1.10) generally lists all available event options and can therefore function as a database of all event options. This is useful for model peer review purposes.

13.2.1.2 Event Naming

When events are defined in a model, the event names are automatically appended to the base .tcf filename to form the output filenames. They are appended in the order they are defined at run time. For example, if the .tcf is MODEL_EXG_001.tcf, then:

  • If event 1 = 01AEP and event 2 = 12h, then output filename = MODEL_EXG_001_01AEP_12h
  • If event 2 = 02AEP and event 2 = 24h, then output filename = MODEL_EXG_001_02AEP_24h

To control where event name(s) are inserted within the output filename, include ~e~ or ~e<x>~ (where <x> is from 1 to 9) into the .tcf filename. The placeholder is replaced with the corresponding event name when the simulation is run. This naming method is recommended to ensure consistent naming conventions across simulations.

Note: ~e~ is effectively the same as ~e1~ and is typically used if there is only one event type being varied.

For example, if the .tcf is MODEL_~e1~_~e2~_EXG_001.tcf, then:

  • If e1 = 01AEP and e2 = 12h, then output filename = MODEL_01AEP_12h_EXG_001
  • If e1 = 02AEP and e2 = 24h, then output filename = MODEL_02AEP_24h_EXG_001

13.2.1.3 Simulating Events

Two options are available to define the event(s) for a model simulation:

  1. Command line options: -e or -e<x> (Table 13.1). This option is best suited for executing bulk simulations. For example: -e1 01AEP -e2 12h
  2. Using the Model Events command in the .tcf: Events are manually specified within the .tcf. This option is suitable for quick “what-if” testing or sensitivity simulations. It is not practical for bulk simulations. Note that if using the -e or -e<x> option, this will override any events defined using Model Events.

13.2.1.4 Event Examples

The following examples demonstrate different ways to structure and apply events.

Events Example 1: Single Event Group

Each AEP/duration combination is defined as a separate event.

BC Database (Section 8.5):

Name,Source,Column 1,Column 2,Add Col 1,Mult Col 2,Add Col 2,
C001,..\Inflows\Nile_~AEP~_~DUR~.csv,Time,C001
C002,..\Inflows\Nile_~AEP~_~DUR~.csv,Time,C002
…

TUFLOW Control File (.tcf):

Include ~e~ in the .tcf filename, for example “Nile_~e~.tcf”, and add the following line at the bottom of the .tcf file to reference the TUFLOW Event file (.tef):

Event File == Nile_Events.tef

TUFLOW Event File (.tef):

Note that ~e~ has been used as an automatic variable in the output location paths. See Section 13.2.3 for details on this feature.

! Global Default Settings

Start Time == 0 ! Global value, unless specified below
Output Folder == ..\Results\2d\<<~e~>>
1D Output Folder == ..\Results\1d\<<~e~>>

 
! 5% AEP flood event definitions

Define Event == 05AEP_01h
      BC Event Source == ~AEP~ | 05AEP
      BC Event Source == ~DUR~ | 01h
      End Time == 3
End Define
Define Event == 05AEP_02h
      BC Event Source == ~AEP~ | 05AEP
      BC Event Source == ~DUR~ | 02h
      End Time == 4
End Define

 
! 2% AEP flood event definitions

Define Event == 02AEP_01h
      BC Event Source == ~AEP~ | 02AEP
      BC Event Source == ~DUR~ | 01h
      End Time == 3
End Define
Define Event == 02AEP_02h
      BC Event Source == ~AEP~ | 02AEP
      BC Event Source == ~DUR~ | 02h
      End Time == 4
End Define

 
Refer to Section 13.4.2 for details on how to execute TUFLOW simulations.

Below is an example Windows batch file that could be used to execute the above example:

set TUFLOWEXE=..\path\to\TUFLOW_executable\TUFLOW_iSP_w64.exe  
set RUN=start "TUFLOW" /wait "%TUFLOWEXE%" -b  
%RUN% –e1 05AEP_01h Nile_~e~.tcf  
%RUN% –e1 05AEP_02h Nile_~e~.tcf  
%RUN% –e1 02AEP_01h Nile_~e~.tcf  
%RUN% –e1 02AEP_02h Nile_~e~.tcf
Events Example 2: Two Event Groups

AEP and duration are separated into independent event groups (e1 and e2). This is a more concise structure, reducing repetition.

BC Database (Section 8.5):

Name,Source,Column 1,Column 2,Add Col 1,Mult Col 2,Add Col 2,
C001,..\Inflows\Nile_~AEP~_~DUR~.csv,Time,C001
C002,..\Inflows\Nile_~AEP~_~DUR~.csv,Time,C002
…

TUFLOW Control File (.tcf):

Include ~e1~ and ~e2~ in the .tcf filename, for example “Nile_~e1~_~e2~.tcf”, and add the following line at the bottom of the .tcf file to reference the TUFLOW Event file (.tef):

Event File == Nile_Events.tef

TUFLOW Event File (.tef):

Note that ~e1~ has been used as an automatic variable in the output location paths. See Section 13.2.3 for details on this feature.

! Global Default Settings

Start Time == 0 ! Global value, unless specified below
Output Folder == ..\Results\2d\<<~e1~>>
1D Output Folder == ..\Results\1d\<<~e1~>>

 
! AEP Definitions

Define Event == 05AEP
      BC Event Source == ~AEP~ | 05AEP
End Define
Define Event == 02AEP
      BC Event Source == ~AEP~ | 02AEP
End Define

 
! DUR Definitions

Define Event == 01h
      BC Event Source == ~DUR~ | 01h
      End Time == 3
End Define
Define Event == 02h
      BC Event Source == ~DUR~ | 02h
      End Time == 4
End Define

 
Refer to Section 13.4.2 for details on how to execute TUFLOW simulations.

Below is an example Windows batch file that could be used to execute the above example:

set TUFLOWEXE=..\path\to\TUFLOW_executable\TUFLOW_iSP_w64.exe  
set RUN=start "TUFLOW" /wait "%TUFLOWEXE%" -b  
%RUN% –e1 05AEP -e2 01h Nile_~e1~_~e2~.tcf  
%RUN% –e1 05AEP -e2 02h Nile_~e1~_~e2~.tcf  
%RUN% –e1 02AEP -e2 01h Nile_~e1~_~e2~.tcf  
%RUN% –e1 05AEP -e2 02h Nile_~e1~_~e2~.tcf
Events Example 3: Nested Events

This example varies check file outputs by event. This is useful as it can reduce simulation time. If Event logic is used because the change depends on the event being simulated. When the model runs, the appropriate check files will automatically be output based on the event magnitude (AEP). This example assumes a .tef defining these events exists and has been read into the .tcf using the Event File command.

TUFLOW Control File (.tcf):

! Limit check files output by event

If Event == 05AEP | 02AEP ! Block read if event is 05AEP or 02AEP
      Write Check Files EXCLUDE == uvpt zpt grd
Else If Event == 01AEP ! Block read if event is 01AEP
      If Event == 48h ! Block read if event is 05AEP and 48h
             Write Check Files EXCLUDE == uvpt zpt grd
      Else ! Block read if event is 05AEP and not 48h
             Write Check Files INCLUDE == 1d_bc_tables 2d_bc_tables bcc iwl
      End If
Else
      Write Check Files INCLUDE == 1d_bc_tables 2d_bc_tables bcc iwl
End If


Models using events are provided in the TUFLOW Tutorial Module 9 and the Bulk Simulation Management Example Model Dataset on the TUFLOW Wiki.

13.2.2 Scenarios

TUFLOW’s Scenarios feature enables the design of a single model setup that can be used to simulate multiple scenarios without duplicating any input control files. This not only makes management of the model easier, but it also ensures consistency between the simulations and supports better project quality control.

The If Scenario command block controls which commands are executed based on the selected scenario(s) at run time. Its structure is equivalent to a standard programming structure: If… Else If… Else… End If. Up to nine scenario groups can be defined within a model (s1 to s9), each containing unlimited scenario variations. Also If Scenario command blocks can be nested up to 10 levels, see Example 3 below (Section 13.2.2.3).

Scenarios can be implemented in most of TUFLOW’s control files where model inputs or parameters may vary by scenario. Scenario logic is not supported in the TUFLOW External Stress File (Section 4.1.13), Advection Control File (Section 4.1.14) and within a Define Control block inside a TUFLOW Operational Control File (Section 4.1.11).

All defined scenarios are automatically available as variables and can be referenced in control files. See Section 13.2.3.

13.2.2.1 Scenario Naming

When scenarios are defined in a model, the scenario names are automatically appended to the base .tcf filename to form the output filenames. They are appended in the order they are defined at run time. For example, if the .tcf is MODEL_EXG_001.tcf, then:

  • If scenario 1 = 5m and scenario 2 = opA, then output filename = MODEL_EXG_001_5m_opA
  • If scenario 2 = 10m and scenario 2 = opB, then output filename = MODEL_EXG_001_10m_opB

To control where scenario name(s) are inserted within the output filename, include ~s~ or ~s<x>~ (where <x> is from 1 to 9) into the .tcf filename. The placeholder is replaced with the corresponding scenario name when the simulation is run. This naming method is recommended to ensure consistent naming conventions across simulations.

Note: ~s~ is effectively the same as ~s1~ and is typically used if there is only one scenario type being varied.

For example, if the .tcf is MODEL_~s1~_~s2~_EXG_001.tcf, then:

  • If s1 = 5m and s2 = opA, then output filename = MODEL_5m_opA_EXG_001
  • If s1 = 10m and s2 = opB, then output filename = MODEL_10m_opB_EXG_001

13.2.2.2 Simulating Scenarios

Two options are available to define the scenario(s) for a model simulation:

  1. Command line options: -s or -s<x> (Table 13.1). This option is best suited for executing bulk simulations. For example: -s1 5m -s2 opA
  2. Using the Model Scenarios command in the .tcf: Scenarios are manually specified within the .tcf. This option is suitable for quick “what-if” testing or sensitivity simulations. It is not practical for bulk simulations. Note that if using the -s or -s<x> option, this will override any scenarios defined using Model Scenarios.

13.2.2.3 Scenario Examples

The following examples demonstrate how If Scenario logic can be used to represent multiple design options within a single model setup.

Scenarios Example 1: Simple Design Option

A scenario block is added into a TUFLOW Geometry Control File (.tgc) to vary materials. For further details on land use and materials, see Section 7.2.7.

! Material Definitions

Set Mat == 1 ! Set unspecified materials to default of 1
Read GIS Mat == shp\2d_mat_existing.shp ! Apply existing materials
If Scenario == opA ! Block read if scenario is opA
      Read GIS Mat == shp\2d_mat_opA.shp ! Option A materials
End If

 
TUFLOW execution logic:

  1. Default Material ID of 1 is set over the entire 2D domain
  2. Existing land use materials are applied via the 2d_mat_existing.shp layer
  3. If opA is selected (via -s1 opA or Model Scenarios == opA):
    • 2d_mat_opA.shp is processed and overrides the existing Material ID’s already assigned with the 2d_mat_existing.shp where they overlap
  4. If opA is not selected, the 2d_mat_opA.shp is ignored
Scenarios Example 2: Hierarchical Options

Scenario blocks are added into a TUFLOW Geometry Control File (.tgc) to vary materials. For further details on land use and materials, see Section 7.2.7.

! Material Definitions

Set Mat == 1 ! Set unspecified materials to default of 1
Read GIS Mat == shp\2d_mat_existing.shp ! Apply existing materials
If Scenario == opA | opB ! Block read if scenario is opA or opB
      Read GIS Mat == shp\2d_mat_opA.shp
Else If Scenario == opC ! Block read if scenario is opC
      Read GIS Mat == shp\2d_mat_opC.shp
Else
      Pause == Invalid op Scenario
End If
If Scenario == opB ! Block read if scenario is opB
      Read GIS Mat == shp\2d_mat_opB.shp
Else If Scenario == opA | opB ! Block read if scenario is opA or opC
      ! Empty block
Else
      Pause == Invalid op Scenario
End If

 
TUFLOW execution logic:

  • opA: Base scenario
    • Only 2d_mat_opA.shp will be read
  • opB: Extension of opA
    • 2d_mat_opA.shp and 2d_mat_opB.shp will be read
  • opC: Alternative scenario to opA and opB
    • Only 2d_mat_opC.shp will be read

Note: Including a Pause command is recommended to prevent unintended scenario selections. The Pause command will halt the simulation initialisation and display the specified message. In the example above, this message would be “Invalid op Scenario”.

Refer to Section 13.4.2 for details on how to execute TUFLOW simulations.

Below is an example Windows batch file that could be used to execute the above example:

set TUFLOWEXE=..\path\to\TUFLOW_executable\TUFLOW_iSP_w64.exe  
set RUN=start "TUFLOW" /wait "%TUFLOWEXE%" -b  
%RUN% –s1 opA Nile_~s1~.tcf  
%RUN% –s1 opB Nile_~s1~.tcf  
%RUN% –s1 opC Nile_~s1~.tcf
Scenarios Example 3: Nested Scenarios

Nested scenario blocks are added to the TUFLOW Control File (.tcf) to vary model parameters.

If Scenario == CLA ! Block read if scenario is CLA
      Solution Scheme == CLASSIC
      Map Output Data Types == h V q d MB1 MB2
Else If Scenario == HPC ! Block read if scenario is HPC
      Solution Scheme == HPC
      Map Output Data Types == h V q d dt
      Hardware == GPU
      If Scenario == SGS ! Block read if scenario is HPC and SGS
             SGS == ON
      Else If Scenario == noSGS ! Block read if scenario is HPC and noSGS
             SGS == OFF
      Else ! Block read if scenario is HPC and not SGS or noSGS
             Pause == Invalid SGS Scenario
      End If
Else
      Pause == Invalid Solver Scenario
End If


Models using scenarios are provided in the TUFLOW Tutorial Module 8 and the Bulk Simulation Management Example Model Dataset on the TUFLOW Wiki.

13.2.3 Variables

The Set Variable <name> command is used to define a variable that can be referenced throughout a TUFLOW model. Variables provide a structured way to centralise model parameters and reuse them consistently across multiple control files.

Variables can be defined in:

  • TUFLOW Control Files (.tcf): See Section 4.1.5
  • TUFLOW Event Files (.tef): See Section 4.1.6
  • Read Files (.trd): See Section 4.1.16
  • Override Files: See Section 4.1.17

Read and override files are extensions of the control file into which they are read. Therefore, variables defined within a read or override file are only valid if that file is read into a .tcf or .tef.

Note that all defined events (Section 13.2.1) and scenarios (Section 13.2.2) are automatically available as variables.

Once a variable has been defined, it can be referenced in any control file (*.tcf, *.tgc, *.ecf, *.tbc, etc.). The variables are referenced within control files by <<variable>>. For example:

Set Variable ALT_START_TIME == 1
Start Time == <<ALT_START_TIME>>

13.2.3.1 Variable Examples

The following examples show some helpful uses of variables.

Variables Example 1: Defining Variables in Logic Blocks

In the example below, variables associated with different cell sizes are defined in the .tcf within a single logic block.

If Scenario == 2m
      Set Variable 2D_CELL_SIZE == 2
      Set Variable 2D_TIMESTEP == 1.0
Else If Scenario == 5m
      Set Variable 2D_CELL_SIZE == 5
      Set Variable 2D_TIMESTEP == 2.5
Else If Scenario == 10m
      Set Variable 2D_CELL_SIZE == 10
      Set Variable 2D_TIMESTEP == 5.0
End If

 
These variables can then be used across multiple control files:

  • TUFLOW Control File (.tcf): Timestep == <<2D_TIMESTEP>>
  • TUFLOW Control File (.tcf): Grid Output Cell Size == <<2D_CELL_SIZE>>
  • TUFLOW Geometry Control File (.tgc): Cell Size == <<2D_CELL_SIZE>>

This structure ensures all cell size and timestep commands remain consistent across the model for each scenario.

Variables Example 2: Events and Scenarios as Variables

As mentioned above, all defined events and scenarios are automatically available as variables. This allows them to be referenced directly within control files. For example, to direct results to scenario specific folders:

Output Folder == ..\results\<<~s1~>>

If ~s1~ is set to opA, then outputs are written to ..\results\opA

Also, event and scenario variables can be combined:

Output Folder == ..\results\<<~e1~>>_<<~s1~>>

If ~e1~ is 05AEP and ~s1~ is opA, then outputs are written to ..\results\05AEP_opA


Models using variables are provided in the Bulk Simulation Management Example Model Dataset on the TUFLOW Wiki.