Tutorial M02 GIS Mesher
GUMB to create a work of art here ;)
| USEFUL LINKS | ||
| Wiki Links | Help | Downloads |
| TUFLOW FV Wiki Main Page | Products Support/Contact | TUFLOW FV Downloads |
| TUFLOW FV Tutorials | Requesting a Licence | Tutorial Module Data |
| TUFLOW Classic/HPC Wiki | TUFLOW FV Glossary | Manuals |
Tutorial Description
This tutorial illustrates the setup and simulation of a short river reach model using the GIS Mesher and then check and visualise the results files using the TUFLOW Plugin in QGIS. Specifically we will:
- Creating boundary condition nodestrings and assigning boundary conditions
- Assigning spatially varying landcover via a material coverage
- Using the TUFLOW FV interface to create the TUFLOW FV Control file (FVC)
- Running the model and reviewing mesh performance
- Duplicating the model and running a refined mesh to review the impacts on runtime
(MADDY TODO: Show picture of model with water depth and velocity results)
Requirements And Downloads
| Requirement | Brief Description | Download |
|---|---|---|
| TUFLOW FV | TUFLOW FV is a one-dimensional, two-dimensional, and three-dimensional flexible mesh finite volume numerical model that simulates hydrodynamic, sediment transport and water quality processes in oceans, coastal waters, estuaries and rivers. Please download the latest TUFLOW FV release. This tutorial model does not require a TUFLOW FV license. |
TUFLOW FV Latest Release . |
| GIS Mesher | The GIS Mesher developed by Rising Water Software builds meshes for hydrodynamic models that use a combination of quadrilateral and triangular meshes. Spatial data is provided to the mesher as GIS layers, so that you can use your favorite GIS application to build quality meshes quickly and easily.
This tutorial was developed using GIS Mesher version 2023.01, it recommended to use this version or later versions of GIS Mesher. If using a different version of the GIS Mesher, some of the dialogue boxes and screen shots may change slightly, however the overall workflow should be similar. If you run into any problems or need help, please contact support@tuflow.com. |
GIS Mesher downloads and release notes can be found here GIS Mesher. |
| QGIS
QGIS TUFLOW plugin |
The Geographic Information System (GIS) QGIS will be used in this tutorial to review model results. This tutorial was developed with QGIS 3.26. It is recommended to have QGIS 3.26 or later to ensure compatibility with TUFLOW plugin latest features.
We will also use the QGIS TUFLOW Plugin which includes numerous tools to increase workflow efficiency. |
QGIS can be download from Latest 64-bit version of QGIS. |
| NotePad++
|
A text editor is required for creation of the TUFLOW FV input files. This tutorial was developed with NotePad++. Ideally a text editor should be able to:
TUFLOW colour coding can be enabled using syntax highlighting. |
Latest 64-bit version of Notepad++.
|
| Model Data | TBC The data provided for the completion of this tutorial includes:
|
TUFLOW FV Tutorial Models. |
| Assumed Knowledge | There are no prerequisites for this tutorial however it is recommended (but not essential) to:
|
Not Applicable. |
Model Overview
In this tutorial we investigate a short river reach subject to astronomical tidal influences at the downstream boundary and river inflows at the upstream boundary. The bed and banks are lined with gravel, sand and vegetation and we'll setup the model to have spatially varied surface roughness.
Extract And Save The Data Package
Please ensure you have downloaded the Model Data from TUFLOW FV Tutorial Models. Copy and unzip the folder to your preferred working location on your computer, for example C:\TUFLOWFV\Tutorial_M02_GIS_Mesher.
- The Complete_Model folder contains a completed version of the tutorial and its supporting files. You can use this as a reference if you require.
- The Module_Data folder contains the required mesh files to complete this tutorial.
- The working folder is where we will build and save our model files.
Creating The Project
The GIS Mesher GUI provides tools for building projects, creating GIS files, running the mesher, and running TUFLOW FV.
Firstly, start-up the GIS Mesher GUI. Now start a new project by selecting File > New Project from the menu.
In the New Project dialog box select the following:
1. Specify the Parent Folder as the working folder in your tutorial folder (likely different than specified below).
2. Set the Project name as tut02.
3. Click on the [...] for the Working projection and select the working_projection.prj file from the Module_Data folder.
4. We will leave the Default GIS filetype as ESRI Shapefile.
5. Uncheck all of the Initial GIS files as we do not require any additional GIS files for this tutorial.
6. Leave the filenames and other settings as default and Click Ok.
Creating a new project creates a set of folders and files that we will use as a starting point to build the model. The folder structure is shown in the figure below:
- The Trap_Channel folder is the parent folder we set when creating the new project.
- The .GISmesher folder stores the project settings for the GIS Mesher GUI (not used in this tutorial).
- The meshing folder will have the meshing control files and has subfolders for GIS and Tables (not used in this tutorial).
- The GIS folder has the template GIS files for the boundary, mesh polylines (used to define size information), and nodestrings which will be used in the meshing process.
- The Tables folder is used for an advanced meshing technique called solution guided meshing which we will not be using.
- The TUFLOWFV folder and sub-folders contain a TUFLOW FV simulation that can be used as a starting point to build models
TUFLOW FV Model Setup
We will now setup our TUFLOW FV Control File and get ready to run TUFLOW FV:
- Copy the tide and flow boundary conditions flows.csv and tide.csv provided in Module_Data into .\TUFLOWFV\bc_dbase. The nodestrings you created in the previous section will be used to apply these boundary conditions. TBC
- Copy TUFLOWFV\runs\Create_Empties.fvc folder and save it as TUFLOWFV\runs\Riverine_Channel_000.fvc. Open the file in Notepad++ and note that the fvc only contains the commands to define the GIS format and model projection. We will edit this file to create a new run file.
- In your Riverine_Channel_000.fvc comment out the last command since we don’t need to generate empty files again. If you don't get the nice syntax highlighted please follow the steps here: TUFLOW syntax highlighting for Notepad++.
Model Mesh
In this tutorial we have provided you with the two mesh files. Please copy Riverine_Channel_000.2dm and Riverine_Channel_001.2dm from the Module_Data folder to ./TUFLOWFV/model/geo. For your understanding and future models all TUFLOW FV geometry files are stored in the geo folder.
Nodestring Order
(MADDY TODO: Do we need this section? Suggest we delete it.)
Open the .\TUFLOWFV\model\geo\Trap_Channel_000.2dm file in a text editor and look for the nodestrings. Do this by searching for NS at the start of the line. For the .2dm file which has been created, the NS lines are as follows:
NS 3 2 84 125 166 207 248 289 -330 1
NS 82 81 123 164 205 246 287 328 -369 2
TUFLOW FV uses the nodestrings as boundaries, with the first nodestring listed being boundary 1, the second nodestring as boundary 2, etc. In this case (by looking at the node list in the .2dm file and comparing to the nodestrings from the GIS Mesher [TBC HYPERLINK tut]), the first nodestring is the upstream boundary (ie – a flow boundary) and the second nodestring is the downstream boundary (ie – a water level boundary).
Don’t panic if the nodes listed in the nodestring either have different numbers or are in reverse order to that shown; this doesn’t influence their behaviour. It is however important that each nodestring lists 9 numbers. This is the number of nodes that the nodestring intercepts.
Boundary Condition Files
For TUFLOW FV, csv (comma delimited) format files contain boundary condition inputs. In this case, the boundary conditions are very simple because the run is steady state. The flow boundary (steadyQ_01.csv) for this model contains the following:
| Time | Flow |
|---|---|
| 0.0 | 0.0 |
| 1.0 | 100 |
| 2.0 | 450 |
| 6.0 | 450 |
Note that the first column (time) is in hours. Note also that there is a warm-up period of 2 hours.
The water level boundary (steadyWL_01.csv) for this model contains the following:
| Time | WL |
|---|---|
| 0.0 | -3.5 |
| 48.0 | -3.5 |
The steadyWL_01.csv and steadyQ_01.csv have been provided in the Model_Data folder. Please copy both files and paste them into the ./TUFLOWFV/bc_dbase folder. For your understanding and future models all TUFLOW FV boundary conditions are kept in the bc_dbase folder.
Create The TUFLOW FV Control File (FVC)
(MADDY TODO: remove references to ultraedit, we've asked people during the requirements to use Notepad++)
The TUFLOW FV control file is created via a text editor in this example we use Notepad++. The software includes configuration features which allow for syntax highlighting of TUFLOW FV specific commands. TUFLOW FV models can also be executed directly from the text editors. This configuration information is provided in the following pages:
Often, an .fvc file is created from an earlier model or from a template. If using a template, then it is good practice to comment out the irrelevant commands. A “!” at the start of the line means that the line is not read by TUFLOW FV. This allows you to insert comments into your fvc file (this is recommended). To simplify this example, only those lines that are relevant to this simulation are shown in the .fvc file. For this tutorial, please call your control file Riverine_Channel_01.fvc. The .fvc file is shown below. A description of each entry is provided.
FVC File Contents
Please use the below table to construct your TUFLOW FV control (FVC) file and save as trap_steady_01.fvc in the ./TUFLOWFV/runs folder
| ! TUFLOW FV TUTORIAL | The first 2 lines are a description of the model simulation. You may also wish to include the initials of the modeller, etc. |
| ! Flow along a trapezoidal channel | |
| Tutorial Model == ON | Enables licence free modelling. |
| ! TIME COMMANDS | The time commands include the start and end times (the default time format is Hours). The CFL limit is 1 by default – TUFLOW FV then assigns a timestep at each computational step according to the CFL limit and between the ranges specified in the timestep limits. |
| Start time == 0.0 | |
| End time == 6.0 | |
| CFL == 1.0 | |
| Timestep limits == 0.0001, 10. | |
| ! MODEL PARAMETERS | The model parameters are those that control various physical and numerical processes.
When the stability limits are exceeded (water level first, then velocity), the model is considered to have crashed. Note that the velocity limit here is high – this is because the velocities along the wetting and drying boundary edges are high. A Smagorinsky eddy viscosity approach has been specified, with a Smagorinsky factor of 0.5. |
| Stability limits == 10. ,100. | |
| Momentum mixing model == Smagorinsky | |
| Global horizontal eddy viscosity == 0.5 | |
| Global horizontal eddy viscosity limits == 0.05, 99999. | |
| ! GEOMETRY | The model geometry is the .2dm created above in this tutorial module. |
| Geometry 2d == ..\model\geo\Trap_Channel_000.2dm | |
| ! MATERIAL PROPERTIES | So far, material types have not been highlighted. By default, the GIS Mesher GUI will create elements using a single material type (1). It is this material type that is assigned a bottom roughness of 0.018 (the default friction approach is a Manning’s number). |
| Material == 1 | |
| Bottom roughness == 0.018 | |
| End material | |
| ! INITIAL CONDITIONS | The initial condition is 2.5 m above the bed at the downstream end (ie -3.5 m). |
| Initial water level == -3.5 | |
| ! BOUNDARY CONDITIONS | The boundary conditions link the .csv files containing the actual flows and water levels to the nodestrings. Nodestring 1 is assigned a flow boundary and Sub-type of 3 which applies the boundary as a flux with a consideration of the depth when distributing flow. Nodestring 2 is assigned a water level boundary. |
| BC == Q, 1, ..\bc_dbase\steadyQ_01.csv | |
| BC header == time,flow | |
| Sub-type == 3 | |
| End BC | |
| BC == WL, 2, ..\bc_dbase\steadyWL_01.csv | |
| BC header == time,WL | |
| end BC | |
| ! OUTPUT COMMANDS | In this instance, a NETCDF format file is specified. This format is easily read into the TUFLOW Viewer for viewing results in QGIS. The h, v and d mean that outputs files containing water level, velocity and water depth will be created. We also use Logdir which specifies the directory for TUFLOW FV simulation log file. |
| Logdir == ..\runs\log | |
| Output dir == ..\results\ | |
| Output == netcdf | |
| Output Parameters == h,v,d | |
| Output Interval == 600 | |
| End output |
Your FVC file should look similar to the figure below. If the syntax colours are not present in your display, we recommend you configure your text editor for TUFLOW FV modelling. Refer to the Notepad++ Tips or UltraEdit Tips Wiki pages.
Run TUFLOW FV With The GIS Mesher GUI
Once you’re happy with the .fvc file contents, run TUFLOW FV using the GIS Mesher GUI.
Firstly make sure the GUI is reading the correct TUFLOW FV executable by selecting Preferences 
and checking that the TUFLOW FV Executables is correct. Please see below.
Please follow the following steps to run TUFLUW FV with the GUI.
- 1. Select the Run TUFLOW FV tab
- 2. Set the Root Folder file path to the runs folder your .fvc is located in
- 3. Set the Simulation to trap_steady_01.fvc
- 4. Click Add to Queue. This will queue your simulation
- 5. Click Run to initiate your model
If your model has completed successfully, the output dialog box will state Run Successful.
You may find that your simulation has crashed. This has likely occurred due to some syntax error in the inputs. Use this link for advice: Common reasons why a model won’t start.
Check Results
During the model simulation one result .nc file will be written. This netcdf file contains water levels velocities and water depths. The file will have the same prefix as the fvc file; in this example it will be called trap_steady_01.nc. The netcdf result files produced by TUFLOW FV are best viewed using the TUFLOW Viewer in QGIS. For instructions on how download the plugin please visit TUFLOW Viewer plugin. Note the following steps and screen shots were undertaken in QGIS version 3.26.
Once you have installed the plugin please click the TUFLOW Viewer button 
. The Tuflow View will appear as below. To open your results please select File>Load Results-Map Output and navigate to your result.
Your QGIS project window should look similar to the below: