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.

A simple example

A simple PowerShell script is as follows:

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

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

.\run.ps1

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:

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

Multiple simulations

Running multiple simulations in series can be handled by adding new lines to run.ps1:

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

Adding switches

To alter the behaviour of TUFLOW, switches can be used in the same way as a batch file. For example, running with the test switch -t:

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

Looping

Looping is undertaken in a similar way to batch files. The following PowerShell script contains a nested loop, so that TUFLOW runs a simulation for all combinations of scenario and event:

$scenarios = @("1m", "2m", "5m")
$events = @("1hr", "2hr", "5hr")
foreach ($scenario in $scenarios){
    foreach ($event in $events){
        C:\Users\robert.wright\bin\TUFLOW\2025.0.2\TUFLOW_iSP_w64.exe -b -s1 $scenario -e1 $event model_~s1~_~e1~.tcf
    }
}

Sending an email when a simulation ends

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 = "recipient_email_address_here"
$Mail.Send()

It is also possible to send the contents of a log file (for example, the TLF) 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()