TUFLOW Runner
Introduction
The TUFLOW Runner provides a simple GUI for creating a queue of TUFLOW and TUFLOW FV simulations which will be run depending on available licenses and resources. The runner is available from the TUFLOW GitLAB User Group and is also bundled with the TUFLOW QGIS plugin. The TUFLOW Runner can replace the need for batch files.
With TUFLOW Runner you can:
- Manage a queue of simulations to run (combination of TUFLOW/TUFLOW FV).
- Handle TUFLOW scenarios and events
- Add multiple simulations based upon a combination of scenarios and events.
- Run multiple simulations at a time dependent upon computer and plugin resources.
- Change priority of items in the run queue.
- Remove items from the run queue.
- Kill currently running items in the run queue.
- Rerun a previously run simulation from the run queue (right-click).
TUFLOW Runner has also the following features:
- Uses an extensible "plugin" approach so other processes (executables) can be managed in the same queue.
- Manages available computer CPU and GPU resources.
- Tracks progress of running simulation.
- TUFLOW provides graphical output (matplotlib) of simulation volume in and volume out through time.
Other advantages:
- Option to save and load a run queue to easily rerun a group of simulations.
- Plugins can define restrictions for licenses, GPUs and CPUs.
- Scenarios and events are remembered between simulations
- Simulation screen output for running or finished simulations (searchable).
Setting up the TUFLOW Runner
Launch the runner.
- If running from python, launch the "main.py" script.
- If running through the QGIS Plugin, in the QGIS menu select Plugins >> TUFLOW >> RUN >> Launch TUFLOW Runner.
Before using the runner, the computer settings need to be specified. You can do this by Choosing Settings option from the Menu.
The resources tab at the top of the dialog is to specify the machine limits for the number of GPU cards and CPU threads. These will generally only be limiting if you are running both TUFLOW and TUFLOW FV at the same time. Otherwise, model specific limitations will prevent exceeding these limits.
TUFLOW and TUFLOW FV each have their own tab to specify executable locations and configuration parameters. For each configuration, you can choose whether to run with one or more GPUs and how many CPU threads to make available. These settings will override settings specified in the input files (for TUFLOW this requires that the "write hardware flags" is specified and you are using 2023-03-AB release or later). Because TUFLOW may use multiple threads during the initial setup phase but a GPU card during the hydraulic calculations when doing GPU simulations, it is recommended to set the number of CPU threads to the number of cores available on the machine and the reserve value to 0. CPU simulations will generally use the same number of threads for reserved and the primary CPU thread setting. Set the configurations to not exceed available licenses.
If you have 2 GPUs and 24 threads available with licenses to support them, the configurations could be setup multiple ways to maximum the complete resources:
- Option 1 - Three configurations where two have a GPU, 12 threads, and 0 threads reserved and a configuration with 0 GPUs with 24 threads and 24 threads reserved.
- Option 2 - Two configurations where one has 2 GPUs, 12 threads, and 0 threads reserved and a configuration with 0 GPUs with 24 threads and 24 threads reserved.
For either of these options, simulations would try to run on the first specified configuration first so you would want the GPU configurations listed first to take advantage of these resources first.
Even if your licensing and resources allow, it may not be worthwhile to run CPU configurations because of the speed advantages of the GPU hardware.
Running the tool
Start a TUFLOW simulation by following the steps below:
- Select Run type (TUFLOW/TUFLOW FV).
- Identify the folder that contains the simulation files (Base folder) and select the simulation file. This must be .tcf for TUFLOW Classic/HPC or .fvc for TUFLOW FV.
- Click on the Add button to add a simulation to the queue. If a TUFLOW model includes Events (~e~) and/or Scenarios (~s~) by clicking on the Add button a dialog (please see image below) will come up to add model’s Scenarios and/or Events. To add simulations, there must be selected scenarios and events in every category. You can use '_' or another placeholder as needed for default scenarios. The bottom of the window shows the combination of selected events and scenarios. To get the sub-list you are interested in, you may need to use the add command several times.
Please note: For TUFLOW model which includes Scenario and/Events, the (~s~) and/or (~e~) must be included in the simulation filename.
- Then, toggle on Run to run the simulation.
Running Multiple Simulation
The runner will launch as many simulations as available in the queue depending on computer resources and model configurations. As model simulations finish, new simulations will be launched as resources become available.
Troubleshooting
If a TUFLOW model simulation with Events and/or Scenarios is not queued please check that these are specified in the Add Simulation dialog Window (please, see section: Running the tool – Step 3) as the runner requires an entry for each Scenario/Event.
If you have further queries or issues it is recommended contacting support@tuflow.com.