View source for Running linked Flood Modeller - TUFLOW Models

==Introduction==
There are several different ways to run a linked Flood Modeller-TUFLOW or ISIS-TUFLOW model. <br>
This wiki page is intended to guide the user through the main methods of installing the link correctly and provide information on troubleshooting. <br>
Other resources for installation help include:
*<u>[https://wiki.tuflow.com/index.php?title=TUFLOW_Licensing Installing a TUFLOW dongle]</u>
*<u>[https://wiki.tuflow.com/index.php?title=Running_TUFLOW Running a TUFLOW Model]</u>
*<u>[https://help.floodmodeller.com/floodmodeller/ Installing Flood Modeller]</u>
*<u>[https://help.floodmodeller.com/isis/ISIS.htm Installing ISIS (for backwards compatibility)]</u>

Licensing considerations for running linked models have not been considered in this section. It was been assumed that the User has purchased the Flood Modeller-TUFLOW link module or is making use of the free versions.

==Methods to Run Linked Flood Modeller-TUFLOW models==
The four main methods for installing Flood Modeller and TUFLOW to run linked models are detailed below.
It is assumed for all methods that Flood Modeller has already been installed and TUFLOW has been downloaded.

===Set the TUFLOW Engine File Location in the Flood Modeller Interface===
Using the Flood Modeller interface to set the location of the TUFLOW engine files for the TUFLOW build you want to use, is the simplest approach to linking Flood Modeller and TUFLOW and does not duplicate files.  This method is recommended if it is expected that the same versions of Flood Modeller and TUFLOW will be used consistently when running linked models. 
<br><br>

1) Open the Flood Modeller software and in the 'Home' tab select the 'General' option. <br>
[[file:FM Home Tab.png|500px]] <br>

2) Select the 'Project Settings' sub-menu and within the TUFLOW Engine File Location choose to browse to the version of TUFLOW that you would like to link Flood Modeller to. Choose 'Open' and then 'OK'. <br>
[[file:FM TUFLOW Linking.png|500px]] <br>

3) Save the changes that you have made to the setup.  This will update the settings file (formed.ini).  

4) Restart Flood Modeller to effect the revised setting.

4) The linked model can then be run by opening the .ief file within the Flood Modeller Interface and clicking Run. <br>

===Set an Environment Variable===
Setting TUFLOW as an environment variable allows for simple installation and minimises duplication of files. This method is recommended if it is expected that the same versions of Flood Modeller and TUFLOW will be used consistently when running linked models. 
<br><br>
1) Click on the start button in windows and open the Control Panel. In the Control Panel, navigate to System.<br>
[[file:control_panel.png|800px]]<br>
2) Click on Advanced Systems Settings. In the Advanced tab, click Environment Variables.<br>
[[file:Adv_Sys_Set.png|800px]]<br>
3) Under System Variables, click on the Path Variable and select Edit.<br>
In the dialog box, under Variable value, add a semi-colon after the current text and then the full file path to the location of the TUFLOW executable. <br>
4) The linked model may be run by opening the .ief file within the Flood Modeller Interface and clicking Run. <br>
[[file:env_var.png|800px]]


===Batch File===
This method allows the user the flexibility to simulate models using different version of Flood Modeller and TUFLOW on the same computer.<br>
After setting up this method the model is run through a batch file. The benefit of this method is that it allows for the running of multiple simulations.  Later versions of Flood Modeller have a Batch run facility which can be used for this purpose. <br> <br>
1)  Using a file explorer, navigate to the location of the TUFLOW executable files. Copy all of the files either within the 'w32' folder or 'w64' folder depending on whether the 32 bit or 64 bit version of Flood Modeller has been installed on the computer.<br>
[[file:tuflow_download_files.png|500px]]<br>
2) Navigate to the location on the local drive where Flood Modeller has been installed. In this case, it is ''C:\Program Files\Flood Modeller'' although your path may differ depending on your system and installation. <br>
Paste the copied TUFLOW files into the ''bin'' folder. If asked, copy and replace the files. <br><br>
3) To set up this method for multiple versions of Flood Modeller and TUFLOW:<br>
* Create an empty folder and appropriately rename it to denote the versions of Flood Modeller and TUFLOW.
* Copy the entirety of the 'bin' folder from the version of Flood Modeller that you wish to use.
* Paste this 'bin' folder inside the newly created folder.<br>
* Copy and paste in all TUFLOW executable files from the version that you wish to use inside the 'bin' folder. Remember to ensure either the 32-bit or 64-bit executables are copied. These need to be compatible with the version of Flood Modeller used.

[[File:Diff TF versions.JPG]]
<br><br>

To run linked Flood Modeller-TUFLOW models with this method, create a <u>[[Run_TUFLOW_From_a_Batch-file | batch file]]</u>.<br>
* In a text editor, paste the path to the Flood Modeller executable file (ISISf32.exe for single precision and ISISf32_DoubleP.exe for double precision) and the name of the .ief file. It may be necessary to include the filepath if the .ief file is not saved in the same folder as the batch file.
* Add the optional batch switch '-sd'. This is useful when running multiple simulations as it allows for the simulation to automatically shutdown on completion removing the need for any user intervention. 
* Double click on the batch file in a file explorer to start the simulation.
[[File:FMT run batch.PNG|700px]]<br>

===Flood Modeller Batch Runs===
The Flood Modeller batch run functionality can be used to set up multiple batch runs of Flood Modeller-TUFLOW linked models.<br>
Refer to the following guidance document on the Flood Modeller <u>[https://help.floodmodeller.com/docs/the-batch-runner-2 website]</u> for further information  <br>

==Using TUFLOW Events and Scenarios when Running Linked Models ==
The Events and Scenarios feature within TUFLOW can be used when running linked models. Further information on this feature may be found within <u>[https://www.tuflow.com/Download/Presentations/2012/2012%20Aust%20Workshops%20-%20TUFLOW%20Multiple%20Events%20and%20Scenarios.pdf this presentation]</u> and in the <u>[[TUFLOW_Example_Models | TUFLOW example models]]</u>.<br>
<br>
Each unique Flood Modeller - TUFLOW simulation will still require its own .ief file. However, each of these .ief files may refer to the same TUFLOW .tcf control file. The TUFLOW Event or Scenario is specified within the 'Run Options' Section of the 'Links' tab within the .ief file.<br>

In the below example, the .ief file is named 'my_model_0100F_EXG_002.ief'. It references a TUFLOW .tcf file named 'my_model_~e1~_~s1~_002.tcf'.<br>
By adding '-e1 0100F -s1 EXG' to the 'Run Options' box, the '0100F' event and the 'EXG' scenario is selected by TUFLOW.<br>
<br>
[[File:FMT EventsScenarios.PNG]]

==Single vs Double Precision and 32-Bit vs 64-Bit==
A common error encountered when compiling linked Flood Modeller-TUFLOW models is inconsistency between versions. These errors will typically cause the model run to fail before the simulation has commenced.<br>
<br>
There are two factors to getting this correct:<br>
1) <u>[https://www.computerhope.com/issues/ch001498.htm 32-Bit or 64-Bit]</u> versions<br>
Both TUFLOW and Flood Modeller have both 32-Bit and 64-Bit versions.<br>
When installing Flood Modeller, the user has the option to selection which version to install. As TUFLOW does not require installation, the option of selecting 32-Bit or 64-Bit occurs when choosing which executable to simulate the model. It is important that the 32 or 64 bit versions match. This can be verified by viewing the Flood Modeller diagnositics file (.zzd) and the TUFLOW log file (.tlf).<br>

2) <u>[https://www.tuflow.com/forum/index.php?/topic/821-single-precision-vs-double-precision/ Single vs Double Precision]</u><br>
Both TUFLOW and Flood Modeller have Single and Double precision versions. In short, these refer to the number of decimal points used when carrying out the calculations. Depending on the model, one version may be preferred over the other. CH2M have provided some further guidance on <u>[https://www.floodmodeller.com/en-gb/news/articles/2013/6/double-precision-single-precision-and-batching-konrad-adams-isis-and-tuflow-specialist/ this page] </u>. <br>
<br>
 
Whichever precision version is selected when simulation a linked Flood Modeller -TUFLOW model, it is important to ensure consistency between the packages. This can be verified by viewing the Flood Modeller diagnositics file (.zzd) and the TUFLOW log file (.tlf).<br>
[[File:Version_check.png]]

==Flood Modeller-TUFLOW HPC/Quadtree==

Flood Modeller is compatible with TUFLOW Classic, TUFLOW HPC and TUFLOW Quadtree.  In order to use TUFLOW HPC, Flood Modeller 4.6 or later should be used.  It is recommended that TUFLOW 2018-03-AE or later is used.  This allows connectivity between Flood Modeller, TUFLOW HPC and TUFLOW 1D (aka ESTRY).  The benefit of using TUFLOW HPC is to allow the 2D calculations to utilise GPU card technology for significant reductions in simulation time compared to TUFLOW Classic.  The following section [[Running linked Flood Modeller - TUFLOW Models#Flood Modeller-TUFLOW Benchmarking including TUFLOW HPC|here]] provides some benchmarking tests demonstrating this.

In order to use TUFLOW Quadtree, then Flood Modeller 5 or later is required, which should be used in conjunction with TUFLOW 2020-01-AB or later.  

When using Flood Modeller and TUFLOW HPC/Quadtree, it is important that the Flood Modeller folder must contain copies of four TUFLOW files. This folder is called the “bin” folder and is located (by default) in “C:\Program Files\Flood Modeller”. For TUFLOW versions 2020-10-AF and earlier, the four required TUFLOW files are called:

* kernels_nSP.ptx
* kernels_nDP.ptx
* QPC_kernels_nDP.ptx
* QPC_kernels_nDP.ptx

If using the 2023-03-AA release or later up to, but not including, the 2026.0.0 release, the names of the kernels have changed and are now: 

* hpcKernels_nSP.ptx 
* hpcKernels_nDP.ptx
* qpcKernels_nSP.ptx 
* qpcKernels_nDP.ptx
If using the 2026.0.0 release or later,  the .ptx kernels have been replaced by .fatbin container files, which are named: 

* hpcKernels_nDP.fatbin
* hpcKernels_nSP.fatbin
* qpcKernels_nDP.fatbin
* qpcKernels_nSP.fatbin

The Flood Modeller installation includes versions of these files that should be compatible with the latest version of TUFLOW available at the time of the Flood Modeller release. If you need to use a later release of TUFLOW or if you find that the link in a Flood Modeller-TUFLOW coupled model is failing with a [[TUFLOW Message 3999|3999 error]] message (and an error description of 'ptx file file version mismatch' in the hpc.tlf), then browse to your TUFLOW engine folder, and copy the above four files and then paste them into your Flood Modeller bin folder (replacing the files there).  If wanting to use the 2023-03-AA release or later, please ensure the relevant kernels are in the Flood Modeller Bin folder and any other TUFLOW .ptx files (ie, kernels_nSP.ptx, kernels_nDP.ptx) are removed. If wanting to use the 2026.0.0 release or later, please ensure the relevant .fatbin files have been transferred to the Flood Modeller Bin folder. 

== Troubleshooting ==

When switching between different build versions of TUFLOW it is possible to receive errors relating to the linking of the software. This is can be due to incorrect linking files being called when the link is established.  If using TUFLOW HPC/Quadtree refer to the section above.  Other linking issues can result in the TUFLOW initialisation phase failing with no specific error or warning.  These are most commonly a symptom of mismatched files within TUFLOW and in the Flood Modeller Bin Folder.

If a linked model is failing, with the last message in the .tlf being: <br>

<font color="blue"><tt>Attempting to create XMDF file </tt></font> <font color="black"><tt>"\\Example_path\Model.xmdf"</tt></font> <br>

Navigate to the specific TUFLOW Build that is being used, locate the following files below and copy and paste these into the Flood Modeller Bin folder: <br>

*'''hdf5.dll'''
*'''hdf5_hl.dll'''

Should this error continue to happen it is recommended re-installing Flood Modeller or contacting [mailto:support@tuflow.com support@tuflow.com] attaching the .tlf and also informing which build versions of both software packages is being used.

In some instances, when running from Flood Modeller, a linked Flood Modeller-TUFLOW model will fail during the model initialisation phase without saving a TLF file.  In such an instance it is worth testing the TUFLOW model by running a TUFLOW only model (or using the Test Model functionality. Please see here: [https://wiki.tuflow.com/index.php?title=Run_TUFLOW_From_a_Batch-file#Testing_a_simulation Testing a simulation]).  The pre-processing will ultimately fail as it is not being run in conjunction with the Flood Modeller model, but it will flag up any input errors which occur within the TUFLOW model and result in the TLF not being written.

If you have further queries or issues it is recommended contacting [mailto:support@tuflow.com support@tuflow.com].

==Flood Modeller-TUFLOW Benchmarking including TUFLOW HPC==

The following page provides information on some linked Flood Modeller-TUFLOW Benchmarking on different PC's utilising TUFLOW Classic, TUFLOW HPC on multiple CPU and TUFLOW HPC on a GPU Card.

<u>[[Flood Modeller-TUFLOW Benchmarking|Flood Modeller-TUFLOW Benchmarking]]</u>. <br>