Command Line Options for Running Simulations

Overview

It is possible to run 1D, 2D or 1D-2D linked simulations in non-attended mode (when you do not have to interact with the software, for example clicking the buttons "Yes" at the end of the simulation) and in non-graphics mode (i.e. a background mode when you do not see the Flood Modeller windows). When Flood Modeller is run in these modes the result files and the log files will be created as when Flood Modeller is run normally (i.e. from within the user interface), although in the non-graphics modes no summary bitmap (showing simulation time plots) will be produced. Please note that it is possible to not only run 1D simulations in non-attended mode, but also convert the binary results files to non-binary format. These modes are useful for batch runs of Flood Modeller run independently from the Flood Modeller user interface.

The steps needed to implement these modes are described below.

Running Flood Modeller Simulations without generating lf1/lf2 files

In Flood Modeller v4.3 a new graphical display was introduced to show real time progress through running simulations (singular or batch runs). The data underlying the new displays are written to text files that are temporarily created and then deleted when the corresponding simulation has completed (see additional notes as deletion does not always occur). These files have an extension “.lf1” (for 1D simulations) or “.lf2” (for 2D simulations). The default location for these temporary text files is the same folder as the corresponding simulation file, i.e. ief for 1D and xml for 2D, and the files take the same name as the simulation file. Linked models will also generate a single lf1 or lf2 file (not both). The file generated depends on the simulation type:

• 1D only – lf1 is output

• 2D only – lf2 is output

• Flood Modeller linked 1D-2D – lf2 only is output

• Flood Modeller 1D linked to TUFLOW – lf1 only is output

If you are running simulations from a command line then you will bypass the Flood Modeller interface functionality that automatically deletes an lf1 or lf2 file at the end of a simulation. These files can contain a significant amount of data and consequently be quite large. It is therefore recommended that you utilize the argument detailed here to prevent models taking up disk space unnecessarily.

Command Line Syntax

To prevent the solvers writing an lf1 or lf2 use the following commands:

Descriptive syntax is: [Minus sign], [lowercase “L”], [lowercase “F”], [space], [zero]

If multiple command options are included in your command line then it should not matter where in the argument list this is, although the “-lf” term and the “0” must be kept together (separated by a single space).

Example

This example will run the simulation defined by “myModelRun01.ief” using the Flood Modeller 1D solver. It won’t create an lf1 temporary file during the simulation, though live progress data will be shown (in the style of pre-v4.3 Flood Modeller). The “-sd” term means that at the end of the simulation the progress window will automatically shutdown.

Additional notes:

If “0” is omitted or not positioned a single space after the “-lf” term, then no lf1 file is written (for 1D or 1D-TUFLOW simulations); an lf2 file will be written (for 2D or 1D-2D simulations). However, depending on what term comes after the “-lf” term in the command line its inclusion like this will likely cause problems (e.g. trying to save an lf2 file to a filename the same as whatever the next argument in the command line happens to be).

Customising where Flood Modeller Simulations write lf1/lf2 files

As described above, Flood Modeller v4.3 will by default write out a temporary log file to provide data for the revised simulation progress window (within the Flood Modeller interface). The file is a text format (can be viewed in any text editor), it takes the name of the associated simulation file (ief for 1D and xml for 2D) and has an extension “.lf1” or “.lf2” (depending on simulation type – see above for details).

When running models from within the Flood Modeller interface, each lf1 or lf2 file is automatically deleted by the interface at the end of the simulation. However, if you are running simulations from command line arguments then these log files will not be deleted (as they are running independently from the Flood Modeller interface). it should be noted that these files can contain a significant amount of data and consequently be quite large.

Command Line Syntax

If you wish to still generate lf1/lf2 files, but set a custom filename and location for the simulation data to be written to, then use the following command lines:

Descriptive syntax is: [Minus sign], [lowercase “L”], [lowercase “F”], [space], [filename including full folder path and with extension “.lf1” or “.lf2”].

If multiple command options are included in your command line then it should not matter where in the argument list this is, although the “-lf” term and the associated filename must be kept together (separated by a single space).

Example

This example will run the simulation defined by “myModelRun02.xml” using the Flood Modeller 2D solver. It will create an lf2 temporary file during the simulation in a local folder, while the model file is located elsewhere on a network drive. Note that the path for the lf2 file requires “” as it contains spaces. Live progress data will be shown (in the style of pre-v4.3 Flood Modeller). The “-k” term means that at the end of the simulation the progress window will not automatically shutdown.

Additional notes:

<lf1/lf2 filename > can be in quotes (“), but not inverted commas (‘); quotes are needed if the specified name and path contain spaces.

Always include the file extension for your alternative lf1/lf2 filename (i.e. “.lf1” or “.lf2”)

If -lf is not present, only an lf1/lf2 file reference, then the simulation ignores this and reverts to default behavior (i.e. same name as .ief/xml with .lf1/lf2 extension)

If the <lf1/lf2 filename > is invalid, then the simulation ignores this and reverts to default behavior (i.e. same name as .ief/xml with .lf1/lf2 extension)

If filename reference is omitted, then no lf1 file is written (1D); an lf2 file will be written (for 2D or 1D-2D simulations). However, depending on what term comes after the “-lf” term in the command line its inclusion like this will likely cause problems (e.g. trying to save an lf2 file to a filename the same as whatever the next argument in the command line happens to be).

Running 1D Simulations in non-attended mode

To run 1D simulations in non-attended mode, you needs to set up the parameters for running Flood Modeller from the 1D Simulation interface and save them in the .ief file (1D Simulation File). Then to run the model simulation from another application or from the command line the command isisf32.exe should be used.

Command Line Syntax

This takes the ief file name as an argument, e.g.:

Note that the "-sd" switch is optional, and causes the run to auto-shutdown on completion thus removing all interactive operation (essential for unattended batch simulations).

Running 1D Simulations in non-graphics mode

To run 1D simulations in non-graphics mode the command isisf32_nw.exe has to be used.

Command Line Syntax

This command takes the ief file as an argument, e.g:

An unsteady 1D model run will generate binary results files (.zzn and .zzl). If these need to be converted to non-binary format, then this part can also be automated using Tabular CSV.exe.

Running 1D Simulations in test mode

To run 1D simulations in test mode the command isisf32.exe has to be used with the switch "-test".

Command Line Syntax

This command takes the ief file as an argument, e.g:

This function checks for the integrity of a model (by processing the data and running a small number of timesteps). It allows the user to check any required files are located as expected, without outputting any results or requiring a Flood Modeller (Standard or Professional edition) licence to do so.

Converting the binary results files to non-binary format in non-attended mode

To obtain the results in a non-binary format, you will need to create an input file for the Tabular CSV tool. This tool is accessible through the Flood Modeller interface (in the 'Results' tab, select 'Tabular CSV' from the right-hand-side of the '1D results' section). Once in the Tabular CSV tool, set up the Tabular CSV options required and then save the settings as a .tcs file (File menu > Save).

Once the tcs file is created and the binary results have been generated, a line similar to the following will create a CSV file of your selected results (for example maximum water levels).

Command Line Syntax

Note: The “-silent” flag removes interactive operation from Tabular CSV.

Running 2D Simulations in non-attended mode

To run 2D simulations in non-attended mode, you need to set up the parameters for running Flood Modeller from the 2D Simulation interface and save them in the .xml file (2D Simulation File). Then to run the model simulation from another application or from the command line the command isis2D.exe should be used.

Command Line Syntax

This takes the xml file name as an argument, e.g.:

Optional additional arguments are shown below:

• “-k” switch causes the run to NOT auto-shutdown on completion. The default action if this argument is not present is to auto-shutdown, thus removing all interactive operation (essential for unattended batch simulations).

• “-q” switch runs the 2D simulation in “quiet” mode. In this mode, less information is sent to console window displayed during the simulation. This may lead to faster performance (although the improvements will likely be small).

Note that the order of arguments, i.e. the above switches and the specified 2D xml file, should not matter.