Tuflow - User contributions [en]

Run TUFLOW From PowerShell

2025-05-15T12:40:35Z

RobertWright: /* Adding switches */

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|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:
<pre>
C:\bin\TUFLOW\2025.0.3\TUFLOW_iSP_w64.exe model_001.tcf
</pre>

Assuming the script filename is run.ps1, this can be run from the PowerShell command line with this command:
<pre>
.\run.ps1
</pre>

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:
<pre>
cd <Path-to-Tuflow-Runs-Folder>
</pre>

=Multiple simulations=
Running multiple simulations in series can be handled by adding new lines to run.ps1:
<pre>
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
</pre>

=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:
<pre>
C:\bin\TUFLOW\2025.0.3\TUFLOW_iSP_w64.exe -t model_001.tcf
</pre>

=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:
<pre>
$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
}
}
</pre>

=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:
<pre>
$Outlook = New-Object -ComObject Outlook.Application
$Mail = $Outlook.CreateItem(0)
$Mail.Subject = "TUFLOW Simulation Finished"
$Mail.To = "recipient_email_address_here"
$Mail.Send()
</pre>
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:
<pre>
$Mail.Body = Get-Content -Raw .\log\model_001.tlf
$Mail.Send()
</pre>

Run TUFLOW From PowerShell

2025-05-15T11:11:38Z

RobertWright:

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|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:
<pre>
C:\bin\TUFLOW\2025.0.3\TUFLOW_iSP_w64.exe model_001.tcf
</pre>

Assuming the script filename is run.ps1, this can be run from the PowerShell command line with this command:
<pre>
.\run.ps1
</pre>

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:
<pre>
cd <Path-to-Tuflow-Runs-Folder>
</pre>

=Multiple simulations=
Running multiple simulations in series can be handled by adding new lines to run.ps1:
<pre>
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
</pre>

=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:
<pre>
C:\bin\TUFLOW\2025.0.3\TUFLOW_iSP_w64.exe -t model_001.tcf
</pre>

=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:
<pre>
$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
}
}
</pre>

=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:
<pre>
$Outlook = New-Object -ComObject Outlook.Application
$Mail = $Outlook.CreateItem(0)
$Mail.Subject = "TUFLOW Simulation Finished"
$Mail.To = "recipient_email_address_here"
$Mail.Send()
</pre>
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:
<pre>
$Mail.Body = Get-Content -Raw .\log\model_001.tlf
$Mail.Send()
</pre>

Running TUFLOW

2025-05-15T11:07:23Z

RobertWright: /* Single Simulation Execution */

=Introduction=
TUFLOW is a standalone console application. As such, it doesn't require installation to run. The standard TUFLOW setup steps are listed below.

* '''Free DEMO and Tutorial Version''' of TUFLOW:
# Download the latest TUFLOW executable from the TUFLOW website: [https://www.tuflow.com/downloads/#tuflow TUFLOW Release Download]
# Download the TUFLOW Tutorial and Demo models: [https://www.tuflow.com/products/free-models/#tuflow_classic_hpc_models Tutorial Model Download]
# Run TUFLOW using any of the options listed below. User documentation for the tutorial models is available from the [[Tutorial_Introduction | Tutorial Model Introduction]] section of the Wiki.

* '''Licensed Version''' of TUFLOW:
# Download the latest TUFLOW executable from the TUFLOW website: [https://www.tuflow.com/downloads/#tuflow TUFLOW Release Download]
# Download and install the Licensing Dongle Drivers: [[TUFLOW_Licensing|Installing Licensing Software]]
# Run TUFLOW using any of the options listed below.

= Executable Management Advice =
Save a copy of the downloaded TUFLOW executable files to a dedicated location (eg. C:\TUFLOW\Releases\) 
A TUFLOW release consists of two different versions of the executable as follows:
# TUFLOW_iSP_w64.exe - Single Precision Windows 64-bit
# TUFLOW_iDP_w64.exe - Double Precision Windows 64-bit

Refer to the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual] for advice when best to use the different TUFLOW versions. Do not delete or relocate any files in the TUFLOW release folder. All files must be placed in the same folder and kept together at all times. 

When replacing TUFLOW with a new build, we recommend archiving the past .exe and .dll files by creating a folder of the same name as the Build ID (e.g. 2013-12-AA-iSP-w64), and placing all files in this folder. Build ID information is appears in the top bar of the Console window when TUFLOW is executed, and is reported in the header of the .tlf file.
 [[File:Executable_File_Management_001.png|600px]]

= Run Options=
==Single Simulation Execution==
There are a number of ways TUFLOW can be started, in each case the TUFLOW executable is started with the TUFLOW control file (.tcf) as the input. There are a number of optional switches that can be used to control advanced features as outlined in the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]. 

Common ways of initialising a TUFLOW simulation are:

* [[Run TUFLOW From a Batch-file|Using a Batch-file]]
* [[TUFLOW Runner|Using the TUFLOW Runner]]
* [[Run TUFLOW From PowerShell|Using PowerShell]]
* [[Run TUFLOW From UltraEdit|Running TUFLOW from UltraEdit]]
* [[Run TUFLOW through the command window|Run TUFLOW through the command window]]
* [[NotepadPlusPlus_Run_TUFLOW | Running TUFLOW from Notepad++]]
* [[TextPad_Tips |Textpad Instructions Including Running TUFLOW (Provided by Jacobs)]]
* [[Running_TUFLOW_from_Explorer | Running TUFLOW from Windows Explorer (Pre-Windows 7)]]
* [[QGIS_TUFLOW_Run_TUFLOW | From QGIS with the TUFLOW QGIS Plugin]]
* [[ArcTUFLOW_Run_TUFLOW_Simulation | From ArcMap with the ArcTUFLOW Toolbox]]
* For miTools users, please see the miTools manual for instructions.

==Multiple Simulation Management==
* [[Run TUFLOW From a Batch-file|Using a Batch-file]]
* [[TUFLOW Runner|Using the TUFLOW Runner]]
* [[TRIM_Tips| TUFLOW Run Interface Manager (TRIM)]]
* For miTools users, please see the miTools manual for instructions.

==Scheduling Simulations==
* [[Using_Task_Scheduler_to_Run_Batch_Files|Using Task Scheduler]]
= Cloud Computing =
Organisations with access to Cloud hardware may host Network Licences within their own cloud domain (private or public). 
Click For Details: [[Organisation_Cloud_Software_Execution| Organisation Cloud Software Execution]].

Run TUFLOW From PowerShell

2025-05-15T11:04:31Z

RobertWright: Created page with "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 sc..."

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: [[Create_TUFLOW_Project]]

=A simple example=

A simple PowerShell script is as follows:
<pre>
C:\bin\TUFLOW\2025.0.3\TUFLOW_iSP_w64.exe model_001.tcf
</pre>

Assuming the script filename is run.ps1, this can be run from the PowerShell command line with this command:
<pre>
.\run.ps1
</pre>

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:
<pre>
cd <Path-to-Tuflow-Runs-Folder>
</pre>

=Multiple simulations=
Running multiple simulations in series can be handled by adding new lines to run.ps1:
<pre>
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
</pre>

=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:
<pre>
C:\bin\TUFLOW\2025.0.3\TUFLOW_iSP_w64.exe -t model_001.tcf
</pre>

=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:
<pre>
$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
}
}
</pre>

=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:
<pre>
$Outlook = New-Object -ComObject Outlook.Application
$Mail = $Outlook.CreateItem(0)
$Mail.Subject = "TUFLOW Simulation Finished"
$Mail.To = "recipient_email_address_here"
$Mail.Send()
</pre>
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:
<pre>
$Mail.Body = Get-Content -Raw .\log\model_001.tlf
$Mail.Send()
</pre>

HPC Adaptive Timestepping

2025-04-22T13:27:07Z

RobertWright: Updated limits to reflect the expressions

=Introduction=

The HPC solver, by default, uses adaptive timestepping to progress through the simulation. The timestep is adjusted so that it complies with the mathematical stability criteria of a 2D SWE explicit solution. In contrast, TUFLOW Classic, being an implicit solution, is not numerically bound by these criteria, and can progress through the simulation using a fixed timestep. Due to the underlying solution scheme, HPC typically uses a smaller timestep than Classic. the following sections outline how TUFLOW HPC automatically selects its adaptive timestep.

=HPC 2D Timestep=
TUFLOW HPC uses adaptive timestepping to maintain stability. There are three primary processes that determine the maximum timestep that an explicit solution to the Shallow Water Equations can use:
* Courant Number, Nu 
* Wave Celerity Number, Nc 
* Diffusion Number, Nd 

{|class="wikitable" style="text-align: center;"
!colspan="4" style="background-color:#005581; height:50px; font-weight:bold; color:white;"|HPC 2D Adaptive Timestep Controlling Numbers
|-
|style="width: 11%; height:50px;" | Control Number||style="width: 40%;" | Description||style="width: 18%;" | Expression||style="width: 9%;" | Control Number Limit
|-
|style="height:80px;" | Courant Number (Nu)
|This condition ensures that water entering one side of a 2D cell does not pass through the other side within one timestep. For this to be satisfied, the product of the water velocity (𝑢) and model timestep (∆𝑡) must be less than the cell size (∆𝑥).
|[[FILE: Courant Number Equation.PNG |250px]]
|≤1.0
|-
|style="height:110px;" | The Shallow Wave Celerity Number (Nc)
|This numerical condition relates to the shallow water wave celerity (wave speed) and is derived from the fluid flow equations to represent long waves (i.e. wave length is substantially longer than the water depth). The product of the model timestep (∆𝑡) and the long wave speed (square root of the gravity (g) and water depth (h)) must be less than the cell size (∆𝑥), for the condition to be satisfied.
|[[FILE: SWC Number Equation.PNG |250px]]
|≤1.0
|-
|style="height:80px;" | Diffusion Number (Nd)
|This numerical condition relates to the sub-grid scale eddy viscosity term which causes diffusion of momentum. To maintain stability the product of the eddy viscosity coefficient (ν_T) and the timestep (∆𝑡) divided by the square of the grid spacing (∆𝑥2) must remain below 0.3. Models controlled by the diffusion number tend to require a timestep significantly smaller than those controlled by the shallow wave celerity or courant numbers. If you find your model is predominantly diffusion controlled it may be that equivalent solution accuracy can be achieved by selecting a larger cell size. This is worth testing, as it will most likely increase the simulation speed with no loss of result fidelity.
|[[FILE: Diffusion Number Equation.PNG |250px]]
|≤0.3
|}

In general terms:
* Courant number relates to velocity relative to the cell size. High velocities will trigger this as the control.
* Celerity Control number relates to water depth relative to cell size. Energy can pass through deeper water faster than shallow water, as such deep water will trigger this control.
* Diffusion control relates diffusion of momentum relating to the sub grid viscosity. Small cells in deep water will trigger this one.
TUFLOW will use the highest timestep possible without exceeding the limits associated with each of the control numbers. 
The method TUFLOW HPC uses to calculate a timestep and achieve unconditional stability is as follows:
* The <tt>Timestep </tt> command included in the TUFLOW Control File (TCF) is only used for the first calculation timestep. The specified value should be consistent with what would be appropriate for a TUFLOW Classic model (i.e. 1/2 to 1/5 the 2D cell size). Internally, TUFLOW HPC divides this value by 10 to apply a value that is suitable for an explicit solution scheme. All subsequent calculations are completed using the adaptive timestep approach outlined in the following bullet points.
* The HPC timestep is calculated using the hydraulic conditions from the end of the previous timestep.
* If the hydraulic conditions have changed significantly it is possible for one or more of the Nu, Nc, Nd control number criteria to be violated at one or more locations within the model. For example, a sudden change in rainfall from one timestep to the next (which occurs with stepped rainfall boundaries) would potentially cause a violation. The HPC solver, by default, treats a 20% exceedance of a control number as a violation and will implement a repeat timestep feature. HPC uses a repeat timestep feature to maintain unconditional stability. The repeat timestep feature involves retaining the complete hydraulic solution from the previous (good) timestep. Should a control number anywhere within the model be exceeded by more than 20%, the solution reverts to the retained timestep, the timestep is reduced and then repeated.
* Each timestep is also tested for the occurrence of NaNs. A NaN is “Not a Number” and occurs due to undefined mathematical calculations such as a divide by zero or square root of a negative number. The occurrence of a NaN is also indicative of a sudden instability. Should a NaN occur, the repeat timestep feature is implemented. 
* Should a timestep need to be repeated more than ten times consecutively, the solution stops.
* The simulation will also stop if the default minimum permissible timestep of 0.1 seconds has been reached. This value can be manually adjusted using <tt>Timestep Minimum</tt>. 
Repeated timesteps are displayed to the Console Window and the number of them for a time interval are provided in the nRS_NaNs and nRS_HCNs columns in the _HPC.csv file output in the results folder. They are also reported to the _messages layer. 
Repeated timesteps are an indication the 2D HPC solution is numerically “on-the-edge”. Models that have a high number of repeated timesteps should be sensitivity tested by reducing the control number limits using <tt>Control Number Factor</tt>. For example, repeat the simulation using <tt>Control Number Factor</tt><tt>==</tt><tt> 0.8 </tt> and compare the results. If there are acceptably immeasurable changes in the results, then running at the default control number limits can be considered satisfactory.

''NOTE: Models that require an excessively small 2D timestep to remain stable are symptomatic of models with input topography or boundary condition errors. Please refer to [Tutorial_Module03 | Tutorial Module 03] for discussion on this topic.''

=HPC 1D Timestep=
HPC links with the 1D solver, ESTRY. When run with HPC (instead of Classic) ESTRY has been reconfigured to automatically act as an adaptive/varying timestep solution, and can step at different multiples of steps to the HPC 2D solver. The ESTRY 1D <tt>Timestep </tt> command for a HPC 1D/2D linked model is the maximum limiting timestep the 1D solver can use, and the 1D and 2D solutions are synchronised based on the size of the "maximum 1D timestep" and the "target 2D timestep":
* If target 2D timestep = maximum 1D timestep: No adjustment is made.
* If target 2D timestep > maximum 1D timestep: the 1D proceeds in two or more steps eventually synchronising with the target 2D timestep.
* If target 2D timestep < Maximum 1D timestep: the 2D timestep is reduced below the target value to synchronise with 1D at a multiple of the 2D timesteps.
Where there is not a one to one synchronisation of the 1D and 2D timesteps, a usually negligible mass error may occur and can be checked by reviewing the CME% values shown on the Console Window, the .tlf file or the _MB.csv file in the same manner as Classic.
 
[[File:1d2ddt.png|800px]]

=HPC Timestep Synchronisation=
HPC uses an adaptive timestep derived from the hydraulic conditions during a simulation. This timestepping approach creates a situation where the computational timestep does not always align exactly with the specified map and time series result output intervals. To account for this TUFLOW HPC makes a timestep adjustments to synchronize the computational timestep with output reporting times. When this occurs the minimum timestep (dt) reported in hpc.dt.csv will report a reduced timestep. This adjustment doesn’t have any effect on the hydraulic calculations, and as such, is not reported in the hpc.tlf or shown in the dt map output. The "dtStar" column in the hpc.dt.csv file also reports the calculated 2D target timestep without any result output synchronisation applied. If the hpc.dt.csv file is being used to quality check the health of a simulation, "dtStar" should be used for the analysis, not "dt". 
 
[[File:dt_sync.png|500px]] 
 

=HPC Quadtree Adaptive Timestepping=
All the above is applicable to the HPC with Quadtree simulations. In addition the Quadtree solver uses a single adaptive timestep for the entire model at any instance in time. Different timesteps are not applied to the respective different resolution nest levels. If a small cell resolution is nested down in water that is deeper than the cell face length, the Diffusion control number would be the critical limiter that is setting the timestep and the model will run slower than expected. This can be confirmed by reviewing the [[HPC_Model_Review#HPC_dt_Time_Series_Output_.28.2A.hpc.dt.csv.29 | hpc.dt.csv file]] information. 
 
{{Tips Navigation
|uplink=[[ HPC_Modelling_Guidance | Back to HPC Modelling Guidance]]
}}