Simulation Builder

  • Updated on Apr 10, 2025
  • Published on Mar 31, 2025
  • 15 minute(s) read

Introduction

A 1D river model simulation can include links to one or multiple event files, providing boundary input data and/or different design scenarios. Simulations can also include links to Hydrology+ hydrograph library files, each with a reference to one hydrograph to utilise as a simulation boundary inflow. Furthermore, if the 1D river model is linked to a TUFLOW 2D model then the 1D simulation file will reference which TUFLOW files to utilise.

In a typical project there may be many different scenarios to investigate by using different model setups. These might look at different return period hydrological events, different climate change epochs and different future design scenarios. Consequently, many 1D river model simulations will need to be setup and run to fully assess all possible combinations of conditions. To do this manually (either in the Flood Modeller user interface or in a text editor) can be a time-consuming process as each simulation will need a separate 1D river simulation file (IEF file) setting up.

The Simulation Builder tool allows you to automatically build up a matrix of 1D simulations, i.e. IEF files. The tool utilises user specified event data to define all permutations and combinations of possible simulations within user specified parameters. Furthermore, the tool allows you to further customise the list of simulations prior to actually “building” them, enabling you to edit durations, timesteps, initial conditions, results destinations and run titles.

This section provides a step-by-step guide on using the Simulation Builder tool as follows:

Using the tool

To utilise the Simulation Builder tool, you must first define one simulation file (IEF file) as a template. This tool then utilises this to define the structure of all the simulations you want to build. For example, if a model utilises 5 different Hydrology+ hydrograph files to specify 5 boundary inputs coupled with an event file to define river sections for a reach where a flood defence development is planned, you need an example simulation file that references these files. Then, the Simulation Builder tool will create new IEF files that always have the same number of input files, but each instance will be unique, using different hydrographs from the associated Hydrology+ files coupled with different combinations of event files.

Furthermore, the template IEF can also include a reference to a TUFLOW model file (TCF file) if all new simulations are 1D-TUFLOW 2D linked models.

The template IEF file also defines the settings used for each new simulation, e.g. run type (steady or unsteady), start and end times, initial conditions files, output folders (for results) and any advanced parameters.

To use the Simulation Builder tool:

It is not necessary to add this IEF file to your project to use it in the Simulation Builder tool. However, if it is present in the Project panel, it can be automatically loaded into Simulation Builder by right-clicking on it and selecting ‘Simulation Builder’ from the context menu. Alternatively, Simulation Builder can be started from the Simulations tab of the main toolbar and you can then browse to add the required IEF file as a template.

Note, to define a new IEF file (e.g. for use in Simulation Builder) use the standard 1D simulation tool, i.e. right-click on Simulations in the Project panel and select New 1D Simulation.

The Simulation Builder interface is displayed, initially with the simulation builder wizard active. The Baseline Settings tab details the selected template IEF file. Settings that can be changed for the new simulations the tool will create are:

  • 1D network – all simulations will use the same 1D river network (but the addition of event files enables modifications to be applied at run time).

  • Initial conditions file – all simulations will adopt the same initial conditions file. The summary table of simulations allows selected simulations to be updated with different initial conditions files prior to building your new simulations.

  • Results folder – this will be set to hold results from all new simulations generated. There is an option to write each simulation’s outputs to separate sub-folders within this location. This is provided as a prompt at the point of building the new simulations.

    The Baseline Settings tab also provides options to load a different template or load a Simulation Builder library file. The Load baseline simulation button accesses a browse window, enables an existing IEF file to be selected. The Simulation Builder interface will then automatically update to reflect the content of this file. The Load Simulation Builder simulations library button displays a browse window to enable selection of a previously saved settings file (XML format file created by Simulation Builder). This populates both the Simulation Builder wizard and the underlying table of defined simulations read from the selected library file.

    When an IEF fie is loaded into Simulation Builder the wizard will update the number of tabs displayed to reflect the number of boundary variables available to change in the IEF. In the example below the referenced IEF file contains two 1D river event files (IED files), a link to a TUFLOW 2D model (represented by a TCF file) and a link to a Hydrology+ hydrograph library file (with one data series selected).

    Varying Event files

    Each event file in a template IEF will be assigned to a tab in the Simulation Builder wizard. These will be named ‘Input 1’, ‘Input 2’, etc. These Input tabs contain a table in which you can specify all alternatives to the IED file in the template. These can be selected by browsing (using the Add Event Files button) or selected from a list of available event files in the current Flood Modeller project (i.e. as listed in the event files section of the Project panel). The list is accessed by clicking the Add Project Event button, as shown below:

    Clicking the Add button adds the selected event files to the Simulation Builder table. Note the event file specified in the template IEF is selected by default (although you can then deselect it). By introducing alternative files to those in the template, you will see the count of number of possible unique simulations that the tool can build change in the lower left corner of the wizard window.

    Each added event file is given an alias. The alias is used within the filenames of new simulations created to include the event file. By default, the event file name without the extension is used, but this can be edited.

    Further refinement of boundary data combinations can be applied if event files represent particular storm probabilities, i.e. return period or AEP. If the Return Period dependent box is ticked then additional columns are displayed. The tool will try to populate these with return period and AEP percentage values estimated from the IED filenames. The return period values can be edited if the tool doesn’t estimate correctly (the corresponding AEP value will automatically update to match any edits). Note that Simulation Builder does not allow different return period datasets to be combined in the same simulation (so not all possible combinations of inputs files will be turned into new simulations).

    Note that every event file will be available under each event tab; the interface does not distinguish between, for example, rainfall events and development scenarios, and it is the responsibility of the user to ensure the relevant events are selected for each tab.

    To proceed, press ‘Next’ to move to the next event tab or press the ‘Back’ button to return to the previous tab. (if more than one event is listed) or to move to the ‘TUFLOW’ tab (if TUFLOW data is associated to the template IEF), or press ‘Add to Preview’ to view a summary of your simulation selections.

    Varying linked TUFLOW models

    If a linked TUFLOW model is referenced in the template IEF, the ‘TUFLOW Links’ tab will be displayed in the Simulation Builder wizard. The data specified in the template IEF is selected by default (although you can deselect it). Simulation Builder provides multiple options for linking all permutations of your simulations to TUFLOW:

  1. By default, i.e. leaving just a single referenced TUFLOW model file, Simulation Builder will link all newly created simulations to instances of this same TUFLOW model. To prevent multiple linked simulations writing same name result files to the same TUFLOW folder, thus overwriting each other, Simulation Builder creates unique copies of the TUFLOW TCF file for each new simulation. Above the table of referenced TCF files, the user has options to write all unique results files to the same folder or to write each result file to a separate unique sub-folder.

  2. If the linked TUFLOW model is also return period dependent, then different TUFLOW simulations can be specified to represent each modelled return period in your suite of simulations. Different return period instances of the TUFLOW model can be defined either by separate TCF files for each or by making copies of the template TCF file and specifying different TUFLOW options for each (the choice will depend on how your TUFLOW models are configured). Use the Add TUFLOW model button to browse to additional TCF files to add to Simulation Builder. Use the Copy Selected button to make a copy of the currently highlighted TCF file in the Simulation Builder table.

Check the box above the table of TUFLOW models to make specified models return period dependent. The table will display extra columns for return period and AEP. The tool will try to populate these with return period and AEP percentage values estimated from the TCF filenames. The return period values can be edited if the tool doesn’t estimate correctly (the corresponding AEP value will automatically update to match any edits). Note that Simulation Builder does not allow different return period datasets to be combined in the same simulation (so each TUFLOW model defined will only be linked to a 1D river simulation representing a matching return period).

The Options field for each TUFLOW model listed allows you to enter all or a subset of the run options set in the TUFLOW model files. The run options set in the template IEF file will be given by default, although these can be edited. The options field for each TUFLOW model listed accepts any text entry, so it is your responsibility to complete this with commands the TUFLOW model will understand.

The Alias names in the TUFOW table will be used in the filenames of the new IEF and TCF files generated by the Simulation Builder tool. By default the tool uses the original TCF filename for the alias text, but this can be edited.

Varying Hydrology+ hydrograph data

If the template IEF file references one or multiple Hydrology+ hydrograph files to provide data for boundary units, then the Simulation Builder wizard will include a ‘Hydrology+ boundary data’ tab. All connected Hydrology+ files will be listed on this one tab. The tables on this tab list the available storm durations, return periods and climate change uplifts that are held in the referenced Hydrology+ hydrograph files. By default, all storm durations and uplift factor options will be selected, i.e. ticked, as shown below. For return periods, if there are multiple Hydrology+ files referenced or other return period dependent files on other tabs of the Simulation Builder wizard, then only return periods coincident in all references will be selected, i.e. ticked. Otherwise, all return periods will be ticked, e.g. if only one Hydrology+ file is present in the template IEF.

In most cases the default selection on this tab will be left unchanged as this will try to produce the maximum number of permutations of different simulations from the specified Hydrology+ boundary data.

Note: It is currently not possible to use Simulation builder to create simulations in which boundaries are using a mix of different return periods. If these scenarios are required for a project, then the simulations would have to be created individually using the standard 1D simulation builder interface (and not Simulation Builder).

Simulations list

When all possible permutations required have been defined in the Simulation Builder wizard click the Add to Simulation List button located below the tabs. The wizard window is closed and all defined simulations are appended to the Simulation Builder simulations table. An example of this is shown below:

Each row in this table represents a separate 1D river simulation (can be linked to TUFLOW). The fields displayed in this table are defined as follows:

  • ID – basic counter allocating unique number to each define simulation. User has option of using these numbers to define unique simulation names (via the Edit tools menu).

  • Name (Event) – name of new IEF that will be created (created by concatenating alias names of different input data components used)

  • Network – name of 1D river network used in new simulation

  • Event(N) – Referenced 1D event (IED) files and/or TUFLOW model files (TCF) in each simulation

  • TUFLOW Link – reference to original TUFLOW TCF in template IEF (note this will be copied for each new simulation to avoid multiple simulations overwriting each other’s 2D results).

  • TUFLOW options – if specified in Simulation Builder wizard

  • Run Type – as read from template IEF

  • Initial Conditions – as specified in Simulation Builder wizard (originally read from template IEF) – can be edited via Edit tools menu for each new simulation (edit individually or for a selected group of simulations).

  • Start Time – as read from template IEF – can be edited via Edit tools menu for each new simulation (edit individually or for a selected group of simulations).

  • Finish Time – as read from template IEF – can be edited via Edit tools menu for each new simulation (edit individually or for a selected group of simulations).

  • Timestep – as read from template IEF – can be edited via Edit tools menu for each new simulation (edit individually or for a selected group of simulations).

  • Save Interval – as read from template IEF – can be edited via Edit tools menu for each new simulation (edit individually or for a selected group of simulations).

  • Results Path – path to 1D river results files for each new simulation (as specified in Simulation Builder wizard)

    Simulation Builder toolbar

    A toolbar is provided above the simulations list table.

    This provides the following functionality:

    Add

    The Add button allows you to add additional rows (IEF files) to the new simulations table. When pressed you are returned to the Simulation Builder wizard, which allows new selections or additional amendments to be made, e.g. different networks, different event data, etc. Once finished press the Add to Simulation List button to exit the wizard and append new simulations to the existing list.

    Save

    The Save button allows the new simulations list to be saved as a Simulation Builder Library file. You will be prompted to choose a filename, and the contents of the simulations table and associated Simulation Builder settings will be saved to an XML file format with extension “.FM1DSim”.

    Build

    The Build button executes the process of creating your specified IEF files (and if required copies of the associated TUFLOW TCF model files). Each row in the table will be built into a separate IEF file. Note that the Build function will always act on all rows in the table, so before clicking Build ensure that you have removed any unwanted simulations (see Remove menu items below).

    A dialog is displayed prompting you to specify a folder name into which all new simulations will be written (this is named as the template IEF by default, although can be edited). Also, if chosen via checkbox on the dialog, the IEF files will be automatically loaded into the Simulations section of the Flood Modeller Project panel inside a sub-folder (with the same name as set in the dialog). There is an option to force existing model files with the same name to be overwritten (this is selected in the dialog by default).

    Options menu

    Export as CSV

    The Export as CSV button allows the table data to be saved in .csv format. You will be prompted to choose a filename. Note that on clicking Build, the tool will automatically also create a CSV file containing the table data.

    Edit Tools menu

    Remove All

    The Remove All button allows you to remove all rows from the Preview table. You will be prompted with a confirmation message prior to deletion.

    Remove Selected

    The Remove Selected button allows you to choose specific rows to remove by highlighting the rows before pressing the button. You will be prompted with a confirmation message prior to deletion.

    Note: An easy way to highlight rows is to click in the far-left blank column of the table. To highlight multiple rows, hold Shift or Ctrl keys whilst clicking with the mouse, i.e. click on row 1 and hold Ctrl whilst clicking on row 7 to highlight rows 1 and 7, click on row 1 and hold Shift whilst clicking on row 7 to highlight rows 1 to 7 inclusive.

    Highlight Duplicates

    The Highlight Duplicates button is a quick way to find any duplicate simulations that will be created during the build process (i.e. with the same combination of networks and event files). When pressed, a background check of the table data will search for duplicate entries by examining each row (and cell) and highlight any duplicate entries (ready for deletion using the Remove Selected function).

    Note that the Highlight Duplicates button will only highlight identical duplicates where the network, event 1, event 2, etc. are all identical. The tool cannot distinguish between data for different events, for example the two simulations below would NOT be considered identical by the tool:

    Use Relative Paths

    The Use Relative Paths button will write relative paths for all file entries referenced in each newly generated IEF file.

    Set Initial Conditions

    If the template IEF contains an Initial Conditions file, the Set Initial Conditions function enables the listed file to be changed.

    Highlight the row or rows (hold Ctrl or Shift keys to highlight multiple rows) and select the Set Initial Conditions menu item from the Edit Tools menu. Browse to choose a different initial conditions file. Then, all selected rows in the table will be updated with this file.

    Note this menu item cannot update initial conditions for a new simulation if the template IEF is using initial conditions from the network (DAT) file.

    Furthermore, take care with simulation filenames if considering multiple initial conditions as any simulations that are identical aside from initial conditions will be given the same name unless manually edited (as the initial conditions do not create part of the filename).

    Use Sequential Name

    The Use Sequential Name menu item toggles new simulation names between the event-based naming convention described above and a naming convention that builds simulation names using only the 1D network name and a sequential number, separated by a hyphen, i.e. my_network.dat-001, my_network.dat-002.

    After selecting to user sequential names, the menu item changes to “Use Alias Names” and selecting it reverts the new simulation filenames to their original format (as created by the Simulation Builder wizard).

    Running simulations upon completion of build process

    Once the build process has completed there will be a series of 1D river model files (ief files) generated. To run all of these models in one action utilise either Flood Platform or access the Flood Modeller batch runner tool (located under the Simulations tab of the Main Toolbar).