Run TUFLOW From PowerShell

PowerShell is a modern scripting language and command interpreter for Windows that can be used as an alternative to more traditional batch files. When creating a PowerShell script to run TUFLOW, much of the functionality will be similar to batch files, but PowerShell offers some additional benefits such as a more modern syntax and the ability to better interact with other features of the Windows operating system. Perhaps one of the most useful features would be the ability to send an email once a TUFLOW simulation has finished. This would allow, for example, a script running a TUFLOW simulation on a server to inform a user on their own computer that a simulation has finished, and details of that simulation to be sent within the email too.

Unlike batch files, a PowerShell script will not run by default when double clicking it in File Explorer. Instead, a user can run the PowerShell script via the command line, for example by searching and opening “PowerShell” from the Windows start menu.

A PowerShell script can be created in a similar way to a batch file. For example, right click in File Explorer, then click New > Text Document, and then provide a file name and extension (.ps1 for PowerShell). Alternatively, when using the Create TUFLOW Project Tool in QGIS, a PowerShell script is automatically generated in addition to a batch file.

Using PowerShell

Open Windows PowerShell from the Windows start menu. When running a script via the PowerShell command line, the current working directory should typically be set to the same directory as the location of the script and TCF file. To change the current working directory, use the “cd” command. If there are spaces in your folder path, use single quotations around the entry (' '):

cd '<Path-to-Tuflow-Runs-Folder>'

Assuming the PowerShell script filename is run_TUFLOW_simulations.ps1, this can be run from the PowerShell command line with this command:

.\run_TUFLOW_simulations.ps1

Simple Example

A simple PowerShell script to run a single simulation is as follows:

C:\bin\TUFLOW\2025.0.3\TUFLOW_iSP_w64.exe model_001.tcf

If there are spaces in your executable path, use single quotations around the executable entry (' ') and prefix the reference with &. For example:

& 'C:\bin\TUFLOW Example\2025.0.3\TUFLOW_iSP_w64.exe' model_001.tcf

Multiple Simulations

Running multiple simulations in series can be handled by adding new lines to run.ps1. Use a –b (batch) switch to suppress the need to press the return key at the end of each simulation:

C:\bin\TUFLOW\2025.0.3\TUFLOW_iSP_w64.exe -b model_001.tcf
C:\bin\TUFLOW\2025.0.3\TUFLOW_iSP_w64.exe -b model_002.tcf

Adding Switches

To alter the behaviour of TUFLOW, switches can be used in the same way as a batch file (see Batch File Switches):

C:\bin\TUFLOW\2025.0.3\TUFLOW_iSP_w64.exe -b -s1 5m -s2 D01 model_~s1~_~s2~_001.tcf

Looping

Looping is undertaken in a similar way to batch files. The following PowerShell script contains a nested loop, where TUFLOW runs a simulation for all combinations of scenarios and events. Comments can be added using #.

#TUFLOW RUN VARIABLES
$scenarios = @("1m", "2m", "5m")
$events = @("1hr", "2hr", "5hr")

#SIMULATION EXECUTION LOOP
foreach ($scenario in $scenarios){
    foreach ($event in $events){
        C:\bin\TUFLOW\2025.0.3\TUFLOW_iSP_w64.exe -b -s1 $scenario -e1 $event model_~s1~_~e1~.tcf
    }
}

Email Notifications

An email can be sent using PowerShell to inform the user that a TUFLOW run has completed (successfully or otherwise). The following approach requires that Outlook is already set up on the computer running TUFLOW:

$Outlook = New-Object -ComObject Outlook.Application
$Mail = $Outlook.CreateItem(0)
$Mail.Subject = "TUFLOW Simulation Finished"
$Mail.To = "first_recipient_email_address_here"
$Mail.To = "second_recipient_email_address_here"
$Mail.Send()

It is also possible to send the contents of a log file (for example, the simulation TLF or _ TUFLOW Simulations.log) as the body of the email. To do this, you must pre-empt the name and path of the TLF file that will be produced:

$Mail.Body = Get-Content -Raw .\log\model_001.tlf
$Mail.Send()