13.3 TUFLOW Executable Download

13.3.1 Overview and Where to Install

The TUFLOW release consists of two different versions of the executable as follows:

TUFLOW_iSP_w64.exe
TUFLOW_iDP_w64.exe

The naming convention for each executable is explained in Table 13.1. Each version has associated TUFLOW .dll and .ptx files, and several system .dll files.

For each version all .exe, .dll and .ptx files must be placed in the same folder and kept together at all times. Older versions of TUFLOW may not have any .ptx files (these are associated with GPU based simulations. When replacing with a new build, archive the files by creating a folder of the same name as the Build ID (e.g. 2023-03-AD), and place all files in this folder.

The Build ID includes the acronym and appears in the top bar of the Console window, in the .tlf file and elsewhere. For example, if running the single precision, Windows 64-bit version, the Build ID would be “2023-03-AD-iSP-w64”.

Older builds can always be setup in a similar manner by placing the build in its own folder, if they are needed for running legacy models.

Model TUFLOW Build or a combination of Model TUFLOW Release, Model Precision and Model Platform can be used to force a simulation to use a specific TUFLOW build, release, or precision (SP or DP). This can be very useful for ensuring a consistent TUFLOW build/release/version is used for a project.

It is recommended that a folder structure such as that shown in Figure 13.1 is used. If an update (patch) is issued, archive the old build by moving all files to a separate folder or .zip file, and copy in the new TUFLOW files. This way, batch files, text editors and GIS packages that are used to start TUFLOW simulations will access the latest build. Previous versions can still be used if required.

Figure 13.1: TUFLOW Engine Files

Table 13.1: **TUFLOW Versions (iSP, iDP, w64)**
Version	Description
Single Precision (iSP)	Compiled using single precision (4-byte) real numbers that typically have around 7 significant figures. This version is recommended for the majority of TUFLOW simulations. See Section 13.3.2 for discussion on precision.
Double Precision (iDP)	Compiled using double precision (8-byte) real numbers that typically have around 16 significant figures. See Section 13.3.2 for discussion on precision. For TUFLOW Classic, this version should be used for models with high ground elevations (greater than 100 to 1,000m) and for direct rainfall models. If a model falls into these categories and is experiencing mass errors when using the single precision version, re-run using the double precision version and should the mass errors reduce to acceptable levels, continue to use double precision, otherwise contact support@tuflow.com. For TUFLOW HPC, due to its explicit finite volume formulation and being depth based (rather than using elevation as required for implicit schemes like Classic), the HPC 2D scheme does not generally require double precision (DP). There can also be substantial speed gains using single precision (SP) on some GPU cards, and there is significantly less memory footprint. However, 1D-2D linked models that also use the ESTRY 1D engine may still require double precision in situations where the model is at higher elevations. Additionally, applications such as long-term simulations and/or simulations with groundwater can be subject to round-off errors may require double precision for an accurate result. Should mass volume errors occur, or if you are concerned about the accuracy of ground water levels, run in double precision and compare with single precision. Should the mass errors reduce to acceptable levels, continue to use double precision, otherwise contact support@tuflow.com. Model Precision can be used to ensure that a simulation is started using the single or double precision version. For example, a single precision version of TUFLOW will generate an error if used to start the simulation if the command below is included in the .tcf: Model Precision == Double
Windows 32-bit (w32)	Legacy builds that were compiled as a 32-bit process. w32 TUFLOW builds can be run on Windows 32-bit and 64-bit platforms. All builds/releases prior to the 2010-10 release (except for the 2009-07-XX-iDP-64 build) are 32-bit. 32-bit programs are unable to access as much memory (RAM) as 64-bit versions of TUFLOW. For large models TUFLOW may generate an error that it is unable to allocate enough memory. Typically, when the memory requirement is ~1.5GB per simulation the 32-bit version of TUFLOW will not be able to allocate enough RAM. The 32-bit version of TUFLOW is only available for pre 2017-09 releases. Users should use the 64-bit versions where possible.
Windows 64-bit (w64)	Compiled as a 64-bit process. w64 TUFLOW builds can only be run on Windows 64-bit platforms. w64 2010-10 builds have been found to reduce simulation times by 20 to 50% compared with the 2009-07 (32-bit) release. Slightly different results (mostly fractions of a mm) will occur between w32 and w64 for the same model. Model Platform can be used to force a simulation to use a w32 or w64 version. Note that the 64-bit versions of TUFLOW may only be run using a WIBU dongle .

Running TUFLOW is carried out by initiating the TUFLOW_X.exe file using one of the approaches discussed in Section 13.4.2. The system .dll files are required for the following purposes:

TUFLOW_LINK_X.dll allows other schemes such as 12D DDA, FloodModeller 1D, EPA SWMM and XPSWMM to dynamically link with TUFLOW.
TUFLOW_USER_DEFINED_X.dll allows users to customise TUFLOW to suit their purposes (see Section 13.3.3).
TUFLOW_AD_X.dll contains the AD (advection-dispersion) module algorithms.
TUFLOW_MORPHOLOGY_X.dll contains the morphology module algorithms. These are deprecated and retained for backward compatibility.
Other supplied .dlls are system DLLs required by TUFLOW.

A number of .ptx files are required to run TUFLOW HPC/Quadtree simulations on a GPU card, these are:

hpcKernels_nSP.ptx
hpcKernels_nDP.ptx
qpcKernels_nSP.ptx
qpcKernels_nDP.ptx

As a general rule, once a build is over three years old, it is no longer supported. It can still be used, but there is no guarantee that older builds will recognise newer dongles or are updated with bug fixes.

13.3.2 Single and Double Precision

When storing floating point values on a computer, a certain number of bytes per value is needed. Single precision numbers use 4 bytes and double precision 8 bytes. This will yield from 6 to 9 digits of precision for single precision and 15 to 17 digits for double. TUFLOW Classic and TUFLOW HPC are available in both single precision and double precision, however, the reasons why you would use double precision instead of single are somewhat different for the two solvers.

13.3.2.1 TUFLOW Classic

Being an implicit matrix based solution, TUFLOW Classic solves for water levels rather than depths. The affect of this is best illustrated by an example. Consider a model where the highest ground level is under 10mAD. If a tiny amount of rainfall falls on the cell, this might raise the water level in the cell to 5.000001mAD. Both single and double precision will handle the accuracy needed as the resulting water level falls within the acceptable number of significant figures for both precisions.

However, consider another model with much higher elevations, and a cell that has a water level of 1000.000mAD. If this cell receives 0.000001m of rainfall in one timestep, for single precision the resulting water level will be 1000.000mAD (i.e. the added rainfall has disappeared resulting in an incorrect calculation and associated mass error). However, for double precision the resulting water level is 1000.00000100000, which is the correct water level and mass is conserved.

The need to use double precision for Classic also depends on other factors such as cell size and timestep. As there is no simple rule-of-thumb, the recommended action is to run the model in single and double precision modes. If the results are unacceptably different, and especially if the mass error is significantly lower in double precision, then double precision should be used.

Note that the choice of single or double precision also impacts on simulation times and RAM allocation. iDP versions of TUFLOW Classic will take approximately 25% longer to run and require up to twice as much memory, limiting the ability to run concurrent simulations. If the results of a model run in both iSP and iDP versions are consistent, the iSP version of TUFLOW is recommended to take advantage of the faster simulation times and smaller memory footprint.

13.3.2.2 TUFLOW HPC

Being an explicit solution, the calculation method in TUFLOW HPC uses depth, unlike TUFLOW Classic which uses water level as discussed above. This means that precision issues associated with, for example, applying a very small rainfall to a high elevation are not applicable in TUFLOW HPC, resulting in most models being accurately solved using single precision. However, carrying out simulations in single and double precision and checking for consistency is still a recommended task, especially if the simulation is using for example, very small inflows, long-term simulations, simulations with groundwater or other metrics that are unusually fine-scale. Additionally, 1D-2D linked models that also use the ESTRY 1D engine may still require double precision in situations where the model is at higher elevations.

Unless testing shows otherwise, use the single precision version for all TUFLOW HPC simulations. Note: Double precision solutions on GPU cards can be four times slower than single precision on some GPU devices! If the TUFLOW HPC simulation is started with the single precision version of TUFLOW, the HPC solver will utilise a single precision version. If the simulation is started with the double precision version of TUFLOW, CHECK 2420 will be output by default stating that the single precision version should be used. This can be turned off, or set to “ERROR” by using the HPC DP Check command.

13.3.3 Customising TUFLOW using TUFLOW_USER_DEFINED.dll

The TUFLOW_USER_DEFINED.dll is a legacy feature for TUFLOW Classic that was primarily used for customising hazard category outputs and is no longer supported as the same service cannot be offered for HPC given its GPU code base.

Note: For customising hazard category outputs, see Section 11.2.3.1.