Difference between revisions of "Run TUFLOW From a Batch-file"

From Tuflow
Jump to navigation Jump to search
 
Line 200: Line 200:
  
 
The following command could be used to run a model with CPU hardware on 8 threads:  
 
The following command could be used to run a model with CPU hardware on 8 threads:  
<pre>TUFLOW_iSP_w64.exe -b -hwcpu -nt8 FS_Hardware_01.tcf </pre>
+
<pre>"C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -hwcpu -nt8 FS_Hardware_01.tcf </pre>
  
 
The following command could be used to run a model on GPU hardware using 2 devices (GPU 0 and GPU1):
 
The following command could be used to run a model on GPU hardware using 2 devices (GPU 0 and GPU1):
<pre>TUFLOW_iSP_w64.exe -b -hwgpu -pu0 -pu1 FS_Hardware_01.tcf </pre>
+
<pre>"C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -hwgpu -pu0 -pu1 FS_Hardware_01.tcf </pre>
  
 
===Set Start Time for a Simulation===
 
===Set Start Time for a Simulation===

Latest revision as of 10:54, 7 August 2024

TUFLOW simulations can also be started from a batch file. Batch files are text files which contain a series of commands. Batch files allow a large degree of flexibility in starting TUFLOW simulations, advanced batch files can be used to:

  • Run multiple simulations
  • Set CPU priority for TUFLOW simulations
  • Create a wait (e.g. start a simulation in 1 hour)
  • Test simulation input
  • Copy a TUFLOW model
  • Package a TUFLOW model
  • Post process results after simulation has finished.

Batch files are executed by double clicking the created .bat file from Windows Explorer.

    Simple batch file

    To use a batch file, create a new text file in the TUFLOW\runs directory. The name is arbitrary but the file must have the extension ".bat". For example the file name could be _run_TUFLOW.bat.

    Open this file in a text editor and add the following line.

    "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" "M01_5m_001.tcf"

    This is the simplest command line for starting TUFLOW, the line above contains only two arguments, the first is the path to the TUFLOW executable and the second argument "M01_5m_001.tcf" is the simulation file name. Depending on the location of the executable the above command line will need to be modified. The quotations around the TUFLOW executable and the .tcf file name are only required if there are spaces in the file names. However, it is recommended to include these to avoid problems.

    Batch File Switches

    These switches are available in all batch files, they are not specific to TUFLOW.

    Pause

    A second line with the text "pause" can be added, this will prompt the user to press a key at the end of the batch file. This is useful if the DOS window disappears from the screen, before you can read the output. The pause command will keep the window open.

    "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" "M01_5m_001.tcf"
    pause

    Starting process in new window

    In order to run multiple simulations at the same time, each simulation needs be started in a new console window. To do this begin the batch file line with the "Start" command, a for the window is then added. For example, to start the simulation above in a new window titled "TUFLOW" the following would be used.

    Start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe"  "M01_5m_001.tcf"

    Wait

    If multiple simulations are to be run, it is often desirable to run these in series, i.e. the second simulation starts after the first has finished. a /wait switch can be added which makes the batch file wait until the process is finished before moving onto the next command.
    An example of this is:

    Start "TUFLOW" /wait "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" M01_5m_001.tcf
    Start "TUFLOW" /wait "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" M01_2.5m_001.tcf

    Without the wait command, both simulations would start at the same time.
    Note: Unless there is a third simulation in the batch file the /wait command in the second line is not required, this prevents the batchfile from moving onto the third line.

    Setting a priority

    The priority of a process (such a TUFLOW simulation) can be specified within a batch file. This can be useful for a number of reasons:

    • Lowering the priority of a simulation to allow you to continue working;
    • Setting a high priority for critical runs; or
    • Making sure you runs are high priority on a shared computing resource!

    The following are valid priority switches (in increasing order of priority):

    • /LOW
    • /BELOWNORMAL
    • /NORMAL
    • /ABOVENORMAL
    • /HIGH
    • /REALTIME

    An example of a low priority simulation is:

    start "TUFLOW" /low "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" "M01_5m_001.tcf"

    TIP: The priority of a TUFLOW simulation can be changed at a later stage by using the Windows Task Manager, navigate to the Processes tab and right click on the TUFLOW process (e.g. TUFLOW_iSP_w64.exe) and select the set priority option.

    Minimising the console window

    Using the /min switch will keep the console window for TUFLOW models minimised, so it doesn't pop up to the front every time when the next model starts.

    Start "TUFLOW" /wait /min "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" M01_5m_001.tcf
    Start "TUFLOW" /wait /min "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" M01_2.5m_001.tcf

    No Console Option

    Using the -nc switch will run a simulation without opening a DOS console window. This option is desirable for people running simulation on the cloud. Note, if an invalid .tcf file is specified, the simulation stops and returns an error level of 1 to the operating system.

    Start "TUFLOW" /wait /min "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -nc M01_5m_001.tcf
    Start "TUFLOW" /wait /min "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -nc M01_2.5m_001.tcf

    TUFLOW switches in a batch file

    These switches are specific to TUFLOW simulations.

    Testing a simulation

    The -t (test) switch is very useful for testing the data input without running the simulation. It is good practice to use this switch before carrying out the simulations, as this will tell you whether there are any data input problems. The -t switch runs TUFLOW to just before it starts the hydrodynamic computations. An example is:

    start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -t "M01_5m_001.tcf"

    Batch mode in TUFLOW

    The use of the –b (batch) switch which suppresses the need to press the return key at the end of a simulation. This ensures that one simulation proceeds on to the next without any need for user input. This is required for running multiple simulations in series (one after the other). An example is:

    start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b "M01_5m_001.tcf"

    Automatically Create Folders in a TUFLOW model

    The use of the -acf (automatically create folders) switch prevents the dialog prompt from appearing when encountering non-existent folders (ie. results folders), and creates these folders automatically. If for any reason the folder can't be created, a dialog will appear. This feature was first introduced for Build 2012-05-AE and is not available for TUFLOW builds prior to this. For models simulated with Build 2013-12-AA or later, non-existent folders are now automatically created. If you would prefer to have the create folder query dialog to appear, you can specify the –qcf run time option (stands for query create folders).
    An example is:

    start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -acf "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"

    Suppress Queries in a TUFLOW model

    The use of the -nq (no queries) switch prevents the termination query dialog from displaying when Ctrl+C is pressed to terminate a simulation cleanly. If –nq is specified and Ctrl-C is pressed, the simulation terminates cleanly without a query dialog to check you are certain, so be careful! This feature was first introduced for Build 2012-05-AE and is not available for TUFLOW builds prior to this.
    An example is:

    start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -nq "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"

    Copy a TUFLOW model

    TUFLOW can be run in copy mode, which can be useful for transferring a model to another site or for making an archive of the input data.

    To copy a TUFLOW model, the -c switch must be included on the TUFLOW command line, as a minimum. The -c switch copies only the files read by TUFLOW. As such, for MapInfo users, the .mif and .mid files read by TUFLOW will be copied. The remaining MapInfo format files (.tab, .id, .dat and .map) are not read by TUFLOW and will not be copied. By default, the -c switch copies all TUFLOW inputs for the simulation into a subdirectory where the .tcf is located (generally TUFLOW\runs\).

    Additional optional flags can be added to the base -c switch, in any combination, including:

    • “a” (all);
    The addition of the “a” flag (e.g. -ca) copies all files of the same name for all input files (ie. same name, but different extensions). This option is particularly useful if the .tab and other associated files of a GIS layer need to be archived or delivered.
    • “L” (list);
    The addition of the “L” flag will output the files used by TUFLOW into a .tcl (TUFLOW Copy List) file but not copy the files to a destination folder. This can be useful if scripting the copying of models. To run the copy list the character “L” needs to be specified after the -c input argument. This works for all copy options, for example, the following are all valid; -cL, -caL, -capL. The .tcl file produced is output in the same directory as the .tcf and takes the simulation name.
    • “p” (path); and
    The addition of the “p” flag (e.g. -cp) allows the user to specify an alternate path in which to copy the model. Without this flag, the location defaults to the .tcf’s location. For example, specifying the following, will place a copy of the model into a folder C:\put_model_here:

    REM start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -cp "C:\put_model_here" "C:\TUFLOW\runs\M01_5m_001.tcf"

    • “ncf” (no check files)
    The addition of the “ncf” flag (e.g. -cncf) copies the essential input files and excludes all check files.

    Note that these optional flags can be added in any combination to the base -c switch (e.g. -c, -ca, -cp, -cncf, -cap, -cancf, -cpncf, -capncf).

    Specifying -c on the TUFLOW command line creates a folder “<.tcf filename>_copy” (or “<.tcf filename>_copy_all” if the “a” flag is added) in the same location as the .tcf file. Under the folder, input files are copied (including the full folder structure), and any check files and output folders created. For example, specifying:

    start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -c “C:\tuflow_models\my model.tcf” will make a copy of the TUFLOW model based on the file “my model.tcf” in a folder "my model.tcf_copy", or "my model.tcf_copy_all" if using the “a” flag.

    Note:

    1. Use the full path to the .tcf file (this is the default if running from UltraEdit or using the right click approach).
    2. Make sure there is sufficient disk space (no checks for sufficient disk space are made).
    3. Output folders and some output files are created but these will be empty.
    4. Any check folder(s) are created and check files written (these can be deleted if wishing to minimise the size of the folder).
    5. The full path of the input files is reproduced to provide traceability and also handle inputs from other drives and URLs. Drive letters are replaced, for example, “C:” becomes a folder “C Drive”. URLs (denoted by “\\” or “//” at the beginning of the path) are replaced by a folder called “URL\”.
    6. To run the copied .tcf file, it will be necessary to change any non-relative pathnames according to the point above. Alternatively you can share and then map, for example, the “D Drive” folder as “D:”.
    7. The Check MI Save Date will need to be set to WARNING or OFF in the .tcf file if the –ca option has not been used as the .tab and other files will not have been copied.
    8. There is a limit of 1,000 characters (including spaces) on pathnames. As very long pathnames can result due to the above approach, if the number of characters exceeds 1,000, problems may occur.
    9. The -c switch automatically invokes the -t (ie. the simulation does not commence, only the input data is tested/checked).
    10. The -b option still applies if several models wish to be copied using a batch (.bat) file.

    An example that copies all files (-ca switch) is:

    start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -ca "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"

    An example that copies all files to an alternate path (-cap) is:

    start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -cap "C:\Copy_of_model" "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"

    An example that copies all files to an alternate path, excluding any check files, (-capncf) is:

    start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -capncf "C:\Copy_of_model" "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"

    Package a TUFLOW model

    Package model function attempts to copy all input files for all events and scenarios defined in the model, if only single set of events and scenarios is required, -c is preferable. Unlike the -c option, -pm does not read and process the data during the file copy, as such it is substantially faster than -c. The package model function does not require access to a TUFLOW licence.

    A tool in QGIS (as part of the TUFLOW Plugin) exists which provides a dialog to the package model options, which allows users to bypass the creation of a batch file:
    Package Model in QGIS

    Additional optional flags can be added to the base -pm switch, in any combination, including:

    • “All”;
    The addition of the “All” flag (e.g. -pmAll) copies all file extensions (e.g. 1d_nwk_culv_L.mif, will become 1d_nwk_culv_L.*).
    • “L” (list); and
    The addition of the “L” flag (e.g. -pmL) list the files to be copied into an output file, but don’t copy.
    • “ini” (file.ini)
    The addition of the “ini” flag (e.g. -pmini) provides a .ini file with user defined options. A .ini file can be used to overwrite the default base and destination folders, and specify events/scenarios for models with events/scenarios in filenames. Valid options should be separated by a vertical bar.

    Combinations of the above are also valid, with the order of the optional switches not being important (-pmAllL would be treated the same as -pmLAll).
    When using package model the default destination folder is created in the same directory as the .tcf file, with the prefix “pm_”. For example, C:\Projects\Modelling\TUFLOW\runs\Run_001.tcf will create a package in the folder “C:\Projects\Modelling\TUFLOW\runs\pm_Run_001\.

    Three options are also available for handling of the binary processed files created by TUFLOW to speed up the simulation start. These options are:

    • “-xf0”;
    Do not copy .xf files, only the original inputs are copied.
    • “-xf1”; and
    Copy both raw input files and .xf files.
    • “-xf2”
    Copy only .xf files, if xf files exist for an input only the xf will be copied.


    An example of package model that copies all files is:

    start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -pmAll "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"

    An example of package model that copies all files except .xf files, (-pmAll -xf0) is:

    start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -pmAll -xf0 "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"

    An example of package model that copies all files with specified .ini file (-pmAllini) is:

    start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -pmAllini package.ini "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"

    An example of .ini file to overwrite the default base and destination folders, and specify events/scenarios for models with events/scenarios in filenames:

    Base Folder == <folder>
    Copy Destination == <folder>
    Model Scenario ~s<number>~ == <scenario A> | <scenario B> | …
    Model Event ~e<number>~ == <event A> | <event B> | …
    

    GPU Module Control

    The -pu switch can be used to select which GPU card or cards to direct the simulation towards. –pu must be specified once for each device. For example, to direct the simulation to GPU devices 0 and 2, specify -pu0 -pu2. (Note: the GPU device numbering starts a 0, not 1). For example:

    start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -pu0 -pu2 "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"

    Event and Scenario Management

    The -e and -s switches can be used to manage multiple events and scenarios from a single tuflow control file. The -e and -s wildcard is replaced by the following entry specified in the batch file. For example, the following batch file commands will run two simulations in series:

    • M01_Q050_24hr_2m_Dev_001.tcf; and
    • M01_Q100_24hr_2m_Dev_001.tcf;
    Start "TUFLOW" /wait  "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b  -e1 Q050  -e2 24hr  -s1 2m  -s2 Dev  "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_~e1~_~e2~_~s1~_s2~_001.tcf"
    Start "TUFLOW" /wait  "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe"  -b  -e1 Q100  -e2 24hr  -s1 2m  -s2 Dev  "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_~e1~_~e2~_~s1~_s2~_001.tcf"

    Please be aware that the % symbol is a special character in a batch file. If the % symbol is used within a wildcard, it will not be read when searching for that wildcard in TUFLOW.
    For example if the following event wildcard is used;

    • -e 10%

    TUFLOW will search for '10' instead of '10%' as the event wildcard.

    It is recommended that modellers avoid the use of a % symbol in any wildcard values. The string 'pct' is a great alternative for the % symbol.
    For example, using:

    • -e 10pct

    Alternatively, using the % symbol twice in a row as shown below should result in a desired wildcard value.

    • -e 10%% (TUFLOW will search for 10%)

    Set Hardware

    The -hwgpu or -hwcpu switches can be used overwrite any "Hardware ==' command specified in the .tcf to GPU or CPU, respectively. This feature was first introduced for Build 2023-03-AB and is not available for TUFLOW builds prior to this.

    These switches can be used in conjunction with the -nt (number of threads) or -pu (processing unit id) to provide full control over the hardware usage via the command line.

    The following command could be used to run a model with CPU hardware on 8 threads:

    "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -hwcpu -nt8 FS_Hardware_01.tcf 

    The following command could be used to run a model on GPU hardware using 2 devices (GPU 0 and GPU1):

    "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -hwgpu -pu0 -pu1 FS_Hardware_01.tcf 

    Set Start Time for a Simulation

    The use of the -st<time_in_hours> (start time) switch allows the user to specify the start time for a simulation. Any start time specified via this run option argument is given the highest priority and overrides the "Start Time ==" settings in the .tcf, event files (.tef) and override files.
    An example is:

    start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -st0 "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"

    Set End Time for a Simulation

    The use of the -et<time_in_hours> (end time) switch allows the user to specify the end time for a simulation. Any end time specified via this run option argument is given the highest priority and overrides the "End Time ==" settings in the .tcf, event files (.tef) and override files.
    An example is:

    start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -et3 "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"

    Suppress Message Box Prompts

    The use of the -nmb (no message boxes) switch suppresses the use of Windows message boxes to prompt the user. All prompts will be via the console window.
    An example is:

    start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -nmb "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"

    Search for a Network License

    The use of the -nwk (network) switch forces TUFLOW to search for a network licence. I.e. Skip the search for a local license.
    An example is:

    start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -nwk "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"

    Search for a WIBU License

    The use of the -wibu (WIBU license) switch forces TUFLOW to search only for a WIBU Codemeter license.
    An example is:

    start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -wibu "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"

    Specify the Output Drive

    The -od<drive> (output drive) switch allows the user to specify the Output Drive for a simulation.
    For example, the following will redirect all outputs to the C:\ drive:

    start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -odC "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"

    Specify Map Output

    The -oz<name> (output zone) switch specifies that the map output includes the input zone.
    For example, the following would include output for 'Zone A':

    start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -ozZoneA "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"

    Query the Creation of a Folder

    The -qcf (query the creation of a folder) switch is useful if you would prefer to have the create folder query dialog appear (rather than TUFLOW automatically creating folders - see -acf).
    An example is:

    start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -qcf "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"

    Execute a Simulation (the Default)

    The -x (execute) switch executes the simulation. This switch is used by default and does not need to be included on the TUFLOW command line.

    Copy or Test Model License Free

    For Build 2018-03-AA or later, it is possible to use the copy model (-c option) or test model (-t option) without using a license. To utilise this licence free copy/test, the -nlc (no license check) input argument must be specified. If running without a TUFLOW licence, no diagnostic output is generated (e.g. messages layer). If these are required, the -nlc option must be removed.

    Simulation Log Path (Legacy)

    The -slp (simulation log path) switch is a legacy option for Solftlock (blue) dongles to set the path to a folder on the intranet to log all simulation initiated from the lock. Refer to the TUFLOW Manual (2018 or earlier) for details.

    Advanced Batch Files

    The below section shows example batch files for maximizing run efficiency,

    Creating a delay

    Windows 7 and newer

    For a Windows 7 and newer operating system a delay of a set duration can be created with the Timeout <seconds> command. For example:

    Timeout 10

    Will create a 10 second delay, a countdown timer is given. Press any key to continue.

    Other Systems

    It is possible to create a delay of specified length in a batch file. The best way do this is actually to create a second batch file! To do this create a text file and call it wait.bat. Within that file enter the following text:

    @ping 127.0.0.1 -n 2 -w 1000 > nul
    @ping 127.0.0.1 -n %1% -w 1000> nul

    To create the pause we ping an address for a set time and disregard the output. Once the wait.bat has been created, it can be called from another batchfile using the following syntax:

    call wait <time in seconds.

    In the example below, the first simulation is started and then 60 seconds later (using the wait.bat file) the second simulation is started. Note there is no /wait flag specified, if there was the batchfile would wait for 60 seconds after the first simulation had finished before starting the second simulation.

    Start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" M01_5m_001.tcf
    call wait 60
    Start "TUFLOW" /wait "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" M01_2.5m_001.tcf

    For this to work the wait.bat file needs to be in the same folder as the batchfile calling it. You can put the file in a specific location and add this path as an environment variable. If this is done "call wait

    Variables

    Batch files can be easily setup so that they are more generic and easily customised when moving from one project to another. For example, in the below a variable, TUFLOWEXE, is used to define the path to the TUFLOW exe to be used, and a variable RUN is used to incorporate options such as the /wait so that the simulations run in series (one after the other).

    set TUFLOWEXE="C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe"
    set RUN=start "TUFLOW" /wait "%TUFLOWEXE%" -b
    %RUN% MR_H99_C25_Q100.tcf
    %RUN% MR_H99_C25_Q050.tcf
    %RUN% MR_H99_C25_Q020.tcf

    The advantage of using variables is if the path to the TUFLOW exe changes, or to run a different version of TUFLOW, it is just a simple change in the .bat file. In the above, note the use of quotes around %TUFLOWEXE% in the definition for the RUN variable – quotes are needed around file pathnames whenever they contain a space.

    Looping in a batch file

    If you have a large number of events to run using the event files a for loop can be used in a batch file. In this example we have 5 event magnitudes (-e1 input) and 5 event durations (-e2 input). The following batch file can be used to run all 25 simulations one after the other:

    @echo off
    
    REM This sets the variables as local, so you can use another batch file with A and B variables
    SetLocal
    
    REM set up variables
    set A=Q010 Q020 Q050 Q100 Q200
    set B=10min 30min 60min 120min 270min
    
    REM Loop Through
    FOR %%a in (%A%) do (
        FOR %%b in (%B%) DO (
            start "TUFLOW" /wait "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -e1 %%a -e2 %%b filename.tcf
        )
    )
    pause
    

    In order to test the syntax, you can test the batch file by replacing the following line:
    start "TUFLOW" /wait "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -e1 %%a -e2 %%b filename.tcf
    With the following line:
    echo start "TUFLOW" /wait "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -e1 %%a -e2 %%b filename.tcf
    By using the echo in the command line, rather than starting the simulations the command line will be displayed in the DOS output. In the example above the DOS output is shown in the image below.

    DOS nested batch output.png

    Alternatively this can be achieved using the following syntax, which is essentially the same but has the for loops compressed to a single line:

    @echo off
    setlocal
    set A=Q010 Q020 Q050 Q100 Q200
    set B=10min 30min 60min 120min 270min
    
    FOR %%a in (%A%) do FOR %%b in (%B%) do start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -e1 %%a -e2 %%b filename_~e1~_~e2~.tcf
    pause
    

    This can be extended to more variables for example:

    @echo off
    setlocal
    set A=Q010 Q020 Q050 Q100 Q200
    set B=10min 30min 60min 120min 270min
    set C=Exg Dev Mit
    
    FOR %%a in (%A%) do (
        FOR %%b in (%B%) do (
            FOR %%c in (%C%) do (
                start "TUFLOW" /wait "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -e1 %%a -e2 %%b -s1 %%c filename_~e1~_~e2~_~s1~.tcf
            )
        )
    )
    pause
    

    Looping in a batch file up to a certain number of runs

    The below example shows a method for controlling the number of concurrent simulations.

    As a brief description of the below, the "do_while_loop_start" counts the number of processes in the task manager which have "TUFLOW" in the name. If this is greater than or equal to the variable "CPU_Cores" then the batch file waits for 60 seconds.

    @ echo off
     
    Set A=Q001 Q002 Q005 Q010 Q020 Q050 Q100
    Set B=Exg Dev
    set /a CPU_Cores=3
     
     
    FOR %%a in (%A%) DO (               
        FOR %%b in (%B%) DO (
           call :do_while_loop_start
           Start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -e1 %%a -s1 %%b M01_5m_~e1~_~s1~_001.tcf
           )
    )
    
    Pause
     
    :do_while_loop_start
        set /a count=0
        for /f %%x in ('tasklist ^| find /c "TUFLOW"') do set count=%%x
        if %count% geq %CPU_Cores% (
            PING 1.1.1.1 -n 1 -w 60000 >NUL
            goto do_while_loop_start
    )
    


    Another way to achieve the same result using IF logic is shown below. This batch file will loop through the series of 14 simulations in groups of three. The batch file will pause until the last of the three active model simulations are complete. When complete, the next series of three simulations will be started in parallel.

    @ echo off
    setlocal enabledelayedexpansion
     
    SET A=Q001 Q002 Q005 Q010 Q020 Q050 Q100
    SET B=Exg Dev
    SET P=3
    
    SET /A Counter=0
    FOR %%a in (%A%) DO (               
        FOR %%b in (%B%) DO (
           SET /A Counter+=1
           IF /i !Counter!==!P! (
               Start "TUFLOW" /wait "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -e1 %%a -s1 %%b M01_5m_~e1~_~s1~_001.tcf
               SET /A Counter=0
    	) ELSE (
    	   Start "TUFLOW"       "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -e1 %%a -s1 %%b M01_5m_~e1~_~s1~_001.tcf
    	)
        )
    )
    

    Looping in a batch file using scenario logic

    Sometimes when using different scenarios, it is useful to run a specific set of events for one scenario but other events for a different scenario.
    This can be automated within looped batch files using a bit of logic.
    In the the example below there is model with defended and undefended scenarios. The defended scenario needs to be run for the 20, 100 and 200 year events but the undefended scenario is only run for the 100 year event. All models are run for the hr and 3hr critical durations.
    The below batch file also uses the looping up to a certain number of runs, as seen in the point above.
    To customize this script, alter the location of the TUFLOW executable, the name of tcf and the scenarios that you would like to run (Refer to 'Set A==', 'Set C==' and 'Set B==').

    @ echo off
    setlocal enabledelayedexpansion
    
    REM ______________SET RUN VARIABLES_____________
    set TUFLOWEXE="C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe"
    set RUN=start "TUFLOW" /low "%TUFLOWEXE%" -b 
    set /a CPU_Cores=5
    
    set tcf=M01_5m_~s1~_~e1~_~e2~_001.tcf
    
    Set A=UDEF DEF
    REM set B in loop beow 
    Set C==01hr 03hr
    
    
    REM ______________SET LOOPS____________________
    FOR %%a in (%A%) do (
    
    REM _____DEFINE RUN LOGIC______
    	IF "%%a"=="UDEF" (
    		set B=100yr
    	)
     	IF "%%a"=="DEF" (
     		set B=020yr 100yr 200yr
     	)
    	
    REM ______________RUN LOOPS____________________
    	FOR %%b in (!B!) do (
    		FOR %%c in (%C%) do (
    			call :do_while_loop_start
    			%RUN% -s1 %%a -e1 %%b -e2 %%c %tcf%
    			timeout 60
    			
    		)
    	)
    )
    
    
    REM ___________COUNT RUN INSTANCES______________
    :do_while_loop_start
        set /a count=0
        for /f %%x in ('tasklist ^| find /c "TUFLOW"') do set count=%%x
        if %count% geq %CPU_Cores% (
            PING 1.1.1.1 -n 1 -w 60000 >NUL
            goto do_while_loop_start
    )
    
    endlocal
    

    Coordinating Asynchronous Simulations

    This batch file will set off asynchronous runs on separate threads, and then wait for all runs to finish before moving to the next process. This example kicks off 8 tuflow.exe processes and then waits before collating (in fortran) and processing the results (in python). Both “combine_therad_outputs.exe” and “Post_process.py” are dummy programs only (with dummy arguments), and are included just to demonstrate how any sort of post processing might be called after the synchronisation of all TUFLOW simulations.

    @echo off
    
    :: Set local
    setlocal
    :: User defined variables – will need to be changed
    set "for_infile=inputs_fortran.inp"
    set "run_exe="C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe""
    set "file_prefix=C:\temp\test"
    set "sum_exe=combine_thread_outputs.exe"
    set "n_threads=8"
    set "pyt_code=Post_process.py"
    set "pyt_infile=inputs_python.inp"
    
    :: Random lock file
    set "lock=%temp%\wait%random%.lock"
    
    :: Launch processes asynchronously, with stream 9 redirected to a lock file.
    :: The lock file will remain locked until the individual exe instance ends.
    :: %%a is sent to %run_exe% as an argument to set the thread to use
    for /L %%a in (0,1,7) do (
    start "" 9>"%lock%%%a" %run_exe% %for_infile% %%a
    )
    
    :: Wait for the processes to finish
    :Waitrun
    1>nul 2>nul ping /n %n_threads% ::1
    for /L %%N in (0,1,7) do (
      (call ) 9>"%lock%%%N" || goto :Waitrun
    ) 2>nul
    
    :: Delete the lock files
    del "%lock%*"
    
    :: Collate thread outputs
    %sum_exe% %file_prefix% %n_threads%
    
    :: Make image
    python %pyt_code% %pyt_infile%
    
    :: Finish up
    echo Done.
    

    Shutdown on Completion

    Often we may have a number of TUFLOW simulations going when we leave work on a Friday afternoon, if these are not going to take all weekend to run, using some of the batch file logic above you can create a batch file that will shutdown the computer when no TUFLOW simulations are running. An example batch file for this purpose is below:

    echo off
    
    :do_while_loop_start
        set /a count=0
        for /f %%x in ('tasklist ^| find /c "TUFLOW"') do set count=%%x
        IF %count%==0 (
    		shutdown.exe /s /t 30
    	) ELSE (
            timeout 60
            goto do_while_loop_start
    	)
    pause
    

    This batch file counts the number of processes with "TUFLOW" in the process name and if this is greater than 0, a delay of 60 seconds is created and the loop started again. If no "TUFLOW" simulations are running a shutdown command is issued.
    To test the batch file it is recommended that you add an "echo" in front of the shutdown.exe /s /t 30 command to ensure it is working correctly (I use this on a Windows 7 machine, but have not tested it on either XP or Windows 8).
    In order to restart the machine rather than power it off the /s can be replaced with /r. This can be useful when a heavily utilised modelling computer needs a restart!