13.2 Simulation Management
TUFLOW incorporates powerful functionality to manage the simulation of multiple events and multiple scenarios. The flexibility offered allows the user the ability to initiate all simulations using the one .tcf file should they so desire. Rather than create a new .tcf file for every simulation and a new .tgc and/or .ecf file for every different model scenario, it is possible to just have one of each of these files, or at least markedly reduce the number of these files. An example application using a single set of control files to simulate 328,986 combinations of different model domains, events and scenarios is published in the TUFLOW Insights Library.
Numerous tutorial examples (with associated data downloads) are available which demonstrate these powerful features:- eLearning - Bulk Simulation Management Scenarios, Events and Variables
- TUFLOW Tutorial Module 8 - Scenario Management
- TUFLOW Tutorial Module 9 - Event Management
- TUFLOW Tutorial Example Models - Scenarios, Events and Variables
The following sections of the manual discuss the available options.
13.2.1 Events
Most hydraulic modelling studies require the simulation of different probabilistic events. For example, a flood study may have to consider the 2, 5, 10, 20, 50, 100, 200 and 500 year Average Recurrence Interval events, and one or two extreme floods. Each, or most of these, may have to be simulated using a range of different duration rainfalls. A downstream boundary such as the ocean may also need to be varied to model different probability storm tides or climate change scenarios. The final number of simulations can easily be in the hundreds, if not thousands.
The ability to simulate multiple events using a single .tcf control file not only makes management of the model easier, it also ensures consistency between the simulations and supports better project quality control.
Multiple events are set up through the creation of a TUFLOW Event File (recommended extension .tef) containing .tcf and .ecf commands that are particular to a specific event. The event specific commands are contained between Define Event and End Define commands. Global .tcf and .ecf commands can also be used by placing these commands outside the Define Event blocks (normally at the top). The .tef file is referenced in the .tcf file using the Event File command. The TUFLOW Event File is typically the last line in a .tcf file. Placing it in this location ensures it will be the final .tcf command that is read, and any global .tcf and .ecf commands within it will take precedence over conflicting commands in the parent .tcf and .ecf files.
Up to nine (9) different event groups can be specified for a single simulation. Unlimited events can be defined within an event group. Example event groups and associated events could be:
- Flood event magnitude: 2, 5, 10, 20, 50, 100, 200 and 500 year Average Recurrence Interval storms.
- Storm Duration: 1hr, 2hr, 3hr, 4hr, 6hr, 9hr, 12hr etc.
- 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.
Since the .tef file typically lists all available event options, the file can be viewed as a database of all available event possibilities. This is useful for model peer review purposes.
To automatically insert the event name(s) into the output filenames, making them unique, place “~e~” or “~e<X>~” (where <X> is from 1 to 9) into the .tcf filename.
Note ~e~ is effectively the same as ~e1~ and is typically used if there is only one event type being varied.
For example,
MODEL_~e1~_~e2~_EXG_001.tcf can be configured to run any number of events within the e1 and e2 event groups, such as:
- e1=0100F and e2=12h results in MODEL_0100F_12h_EXG_001
- e1=0100F and e2=24h results in MODEL_0100F_24h_EXG_001
- e1=1000F and e2=12h results in MODEL_1000F_12h_EXG_001
- e1=1000F and e2=24h results in MODEL_1000F_24h_EXG_001
Two options are available to define the event choice for a model simulation:
- Using a batch file (.bat): Specify the –e or –eX options (see Table 13.2) to run the multiple events using the same .tcf file – refer to the examples below. This option is best suited to executing bulk simulations.
- Using the Model Events command: Change the events manually before each simulation within the .tcf file. Note that if using the –e or -ex option, this will override any events defined using Model Events in the .tcf file. This option is useful for carrying out quick what-if or sensitivity simulations. It is not practical for bulk simulation.
The examples below demonstrate two approaches for running simulations of a 20 and 50 year flood and 1 and 2 hour duration storms.
- Example 1 uses a single event group.
- Example 2 achieves the same outcome as Example 1, though by using two event groups (~e1~ and ~e2~) it avoids some of the command repetition required for Example 1.
In the examples, note how the same command (in this case End Time) is used within the event blocks to assign a different simulation end time depending on the duration of the event. Also note the use of BC Event Source, which is a much more powerful alternative to using BC Event Text and BC Event Name, in that it can be used to define up to 100 different event text / name combinations instead of being
limited to one. The key text field linkages with the BC Database file are highlighted in yellow.
Events Example 1: One Event Group
Within the BC Database file:
Name,Source,Column 1,Column 2,Add Col 1,Mult Col 2,Add Col 2,
C001,..\Inflows\~ARI~_~DUR~.csv,Time,C001
C002,..\Inflows\~ARI~_~DUR~.csv,Time,C002
…
Include “~e~” in the .tcf filename, for example “Nile_~e~.tcf”, and add the following line at the bottom of the file:
The “Nile_Events.tef” file contains lines such as the below:
Multiple events can be simulated from a single .tcf file using a batch file. Refer to Section 13.4.2 for details how to create a batch file. Below is an events batch file example in its simplest form, without looping.
set RUN=start “TUFLOW” /low /wait /min “%TUFLOWEXE%” -b
%RUN% –e1 020y_01h Nile_~e~.tcf
%RUN% –e1 020y_02h Nile_~e~.tcf
%RUN% –e1 050y_01h Nile_~e~.tcf
%RUN% –e1 050y_02h Nile_~e~.tcf
Events Example 2: Two Event Groups
Within the BC Database file:
Name,Source,Column 1,Column 2,Add Col 1,Mult Col 2,Add Col 2,
C001,..\Inflows\Nile\~ARI~_~DUR~.csv,Time,C001
C002,..\Inflows\Nile\~ARI~_~DUR~.csv,Time,C002
…
Include “~e1~” and “~e2” in the .tcf filename, for example “Nile_~e1~_~e2~.tcf”, and add the following line:
The “Nile_Events.tef” file would contain lines such as the below:
To run multiple events from the one .tcf file a .bat file may be used, such as below (see Section 13.4.2):
set RUN=start “TUFLOW” /low /wait /min “%TUFLOWEXE%” -b
%RUN% –e1 020y -e2 01h Nile_~e1~_~e2~.tcf
%RUN% –e1 020y -e2 02h Nile_~e1~_~e2~.tcf
%RUN% –e1 050y -e2 01h Nile_~e1~_~e2~.tcf
%RUN% –e1 050y -e3 02h Nile_~e1~_~e2~.tcf
If Event logic blocks are also permitted (in the .tcf) in the same manner as the If Scenario command and can be useful for more advanced applications. Refer to Section 13.2.2 for further information. Also, events are automatically defined as variables and can be used, for example, to set the output folder name. See Section 13.2.3 for information on “Variables”.
Models using events are provided in the Bulk Simulation Management Example Model Dataset on the TUFLOW Wiki.
Reminder: The location of Event File within the .tcf file and the location of the commands within the .tef file are important. If, for example End Time occurs in the .tcf file after where Event File occurs, this latter occurrence of End Time will prevail over those specified in the .tef file. Essentially, the commands from the .tef file (for the events specified using the –e or -e
Tip: To distinguish between 1D and 2D commands in a .tef file, prefix .ecf commands by “1D” followed by a space. In the examples below, the .ecf Output Folder command is used to set different folders for the 1D results depending on the event.
13.2.2 Scenarios
Using If Scenario is similar to using If…Else If… Else…End If constructs in a programming or macro language. This feature enables control of the commands to include or exclude depending on the scenario or combination of scenarios specified by the user at the time of simulation execution.
Scenarios can be added into most of TUFLOW’s control files. The only control files not supporting scenarios are the TUFLOW Rainfall Control File (.trcf), TUFLOW External Stress File (.tesf), Advection Control File (.adcf) or within a Define Control command inside a TUFLOW Operational Control (.toc) file. Similar to “events”, 9 scenario groups can be specified. Unlimited scenario variations can be defined within each scenario group.
In Example 1 below, an If Scenario logic block has been inserted into a .tgc file:
Scenarios Example 1:
TUFLOW will carry out the following steps:
- Set all material values over the entire 2D domain to a value of 1.
- Process the 2d_mat_existing.shp layer to assign material values from a layer of land-use polygons representing the existing situation.
- One of the following will then occur:
- If either “–s1 opA” was specified as a run selection in a batch file, or “Model Scenarios
== opA” was specified in the .tcf file, then the 2d_mat_opA.shp layer would be processed to modify the material values affected by the Option A scenario. If “~s1~” occurs within the .tcf filename, it is replaced by “opA” in the output filenames, otherwise “opA” is appended to the end of the .tcf filename for the output filenames.
- If opA was not specified as the chosen scenario for a simulation, 2d_mat_opA.shp would be ignored. For example, that option would be required if modelling the existing scenario.
- If either “–s1 opA” was specified as a run selection in a batch file, or “Model Scenarios
Example 1 can be extended to include an Option B, where Option B is an extension of Option A, and also Option C, which is a complete alternative to Option A and the combined Option A and B design. The If Scenario logic block for this situation is shown in Example 2a below:
Scenarios Example 2a:
In the above example:
- If “–s1 opA” is selected as the scenario for simulation, only 2d_mat_opA.shp will be read.
- If “–s1 opB” is selected as the scenario for simulation, 2d_mat_opA.shp and 2d_mat_opB.shp will be read.
- If “–s1 opC” is selected as the scenario for simulation, only 2d_mat_opC.shp will be read.
Example 2b has been expanded further to include an Else and Pause command in 2c. The command in the Else section will apply if any scenario except opA, opB or opC is called. The Pause command will halt the simulation initialisation and display the specified message in the console window. The user then has the option to continue or discontinue the simulation. It is good practice to include Pause commands as a way to avoid accidental use of unspecified scenarios.
Scenarios Example 2c:
In the example above, the batch file used to run the Option A, Option B and Option C scenarios may look like this:
set RUN=start “TUFLOW” /low /wait /min “%TUFLOWEXE%” -b
%RUN% –b -s1 opA Nile_~s1~_001.tcf
%RUN% –b –s1 opB Nile_~s1~_001.tcf
%RUN% –b –s1 opC Nile_~s1~_001.tcf
As demonstrated above, it is recommended that scenario group placeholders be used (~s1~, ~s2~ etc.) in the .tcf file name. This provides the modeller with increased output file name control. Above, ~s1~ in the .tcf file name will be substituted with the chosen scenario in all result, log and check files. For example, for the first simulation in the queue, Nile_~s1~__001.tcf would become M01_opA_001 for all output files.
The If Scenario command can be nested up to 10 levels. An example is provided in Scenario Example 3.
Scenarios Example 3:
Scenarios are automatically defined as “Variables” and can be used, for example, to set the output folder name. See Section 13.2.3 for information on Variables.
Models using scenarios are provided in the Bulk Simulation Management Example Model Dataset on the TUFLOW Wiki.
13.2.3 Variables
The Set Variable command can be used to assign different values for the same variable in different parts of the various TUFLOW control files. It is an efficient way to centralise information. It is regularly used to consolidate the definition of multiple variables in a single logic block rather than having multiple If..Else If.. End If command blocks in different locations or control files.
The Set Variable command can only be specified in the .tcf or within a read file (.trd) referenced from the .tcf. The variables can then be used in all control files (.tcf, .tgc, .tbc, .ecf, etc). The variables are referenced within the control files by being enclosing the character string within “<<” and “>>”.
An example is provided below. Variables associated with modelling at different cell sizes are defined in the .tcf within a single logic block.
Along with this variable definition, the following is used in the respective control files:
- .tcf: Timestep
== <<2D_TIMESTEP>> - .tcf: Grid Output Cell Size
== <<2D_CELL_SIZE>> - .tgc: Cell Size
== <<2D_CELL_SIZE>>
Models using variables are provided in the Bulk Simulation Management Example Model Dataset on the TUFLOW Wiki.
Note: Set Variable scenario blocks are often contained within “read files”, referenced in the .tcf using the Read File command.
All events and scenarios are automatically set as a variable that can be used within your control files. For example, if your model results are to be output to different folders depending on Scenario 1 (~s1~), enter the following into the .tcf file noting the use of << and >> to delineate the variable name.
Output Folder
In the case above, if Scenario ~s1~ is set to “OpA”, TUFLOW automatically sets a variable named “~s1~” to a value of “OpA”, and the output will be directed to ..\results\OpA.
As an extension to the example above, if the output folder is to also include the first event name, which, for example, is the return period of the flood, the following could be used:
Output Folder
If Event ~e1~ is set to “Q100”, the output will be directed to ..\results\Q100_OpA.