Tutorial M01 GIS Mesher

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 builds upon the Trapezoidal Channel Meshing Tutorial. In this tutorial you will learn how to create and run a TUFLOW FV model using the GIS Mesher and then check and visualise the results files using the TUFLOW Plugin in QGIS. Specifically we will:

• Create the TUFLOW FV Control file (FVC)
• Setup key model commands and outputs

• Run the model and check the results

If you want to further your modelling experience you can then also try our 'Going Further' section where we'll:

• Add advection-dispersion (AD) to simulate saline water
• Run model with a modified mesh and compare the results to the previous mesh.

Trapezoidal Channel Project Area

The trapezoidal channel has dimensions as shown below:

• Top width = 100 m
• Bottom width = 50 m
• Depth = 5 m
• Length of channel = 1,000 m
• Grade of channel = 1 in 1,000
• The model domain should have a resolution of 12.5 m across the channel and 25 m along the channel

(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 1-dimensional, 2-dimensional, and 3-dimensional flexible mesh finite volume numerical model that simulates hydrodynamic, sediment transport and water quality processes in oceans, coastal waters, estuaries and rivers. It is recommended to always use the latest release version of TUFLOW FV. This tutorial model does not require a TUFLOW FV licence.	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. QGIS TUFLOW Plugin Installation.
NotePad++ Syntax Highlighting	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: Colour code the TUFLOW FV control files. Open other files from the active control file. Launch a TUFLOW FV simulation. TUFLOW colour coding can be enabled using syntax highlighting.	Latest 64-bit version of Notepad++. TUFLOW syntax highlighting for Notepad++. For instructions on configuring Notepad++ for TUFLOW modelling, see Notepad++ tips.
Model Data	The data provided for the completion of this tutorial includes: The .2dm mesh files provided in the Module_Data folder. Boundary conditions provided in CSV format in the Module_Data folder. The Complete_Model folder has the files for the completed tutorial in case you get stuck. The working folder is where you will create your model files.	TUFLOW FV Tutorial Models.
Assumed Knowledge	There are no prerequisites for this tutorial however it is recommended (but not essential) to complete or review the Trapezoidal Channel Meshing Tutorial.	Not Applicable.

Prepare Your Working Environment

(MADDY TODO: Create a simple chart that shows the workflow of how GIS Mesher and QGIS will be used together in the Tutorial).

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, for example C:\TUFLOWFV\Tutorial_M01_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 you'll create, build and run the model.

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 tut01.
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

Model Mesh

In this tutorial we have provided you with the model mesh. Please copy Trap_Channel_000.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. Notepad++ or UltraEdit is recommended for this purpose. These software include 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:

• Notepad++ Tips .
  
• UltraEdit Tips .

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 trap_steady_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 == 100. ,10.
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.

MB REPLACE BELOW - the stability limits are wrong

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:

In this section, we will use the the TUFLOW Viewer to visualise the results in two plots: (1) a long section of water level and bed elevation, and (2) a time series of the velocity with vectors on.

(1) To display a long section of the water level and bed elevation, follow the below steps:

1. Display the mesh by selecting the Toggle Mesh Rendering

2. Select the Plot cross drop down

3. In the drop down, check bed elevation

4. In the drop down, check water surface elevation

To draw the long section, please select the Plot cross drop down and your cursor should now become a crosshair [+]. Now you are ready to plot your long section. See the long section example below:

(2) To display a timeseries of the velocity and velocity vectors, follow the below steps:

1. Display the mesh by selecting the Toggle Mesh Rendering

2. In the Result Type window, select velocity and velocity vector map outputs

3. Now increase the time stamp to see how the velocity vectors change throughout the model simulation

4. Select the Plot Time Series drop down and in the drop down check velocity

5. To draw the long section, please select the and your cursor should now become a crosshair [+]. Click on your results to view a time series similar to the below:

For more examples on how to review your results using the QGIS TUFLOW Viewer plugin, visit TUFLOW Viewer.

Going Further

Model Topography Modification

In this section we will review how changes to the mesh alter your model results. In this instance we have provided a mesh file of that trapezoidal channel was to include a bump in the channel bed and a downstream channel constriction. From the Module_Data copy Trap_Channel_001.2dm into working/TUFLOWFV/model/geo.

To preview the mesh please drag and drop the Trap_Channel_001.2dm into your QGIS workspace to review to the changes to mesh file.

In the plugin, please select the Bed Elevation Map Output and Toggle Mesh Rendering:

FVC File Updates

Save a copy of Trap_Steady_02.fvc and name it Trap_Steady_03.fvc The following additional components listed in the right-hand column of the table below are required within the FVC file:

! 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 modelled with salinity and a modified mesh.
Tutorial Model == ON
! SIMULATION CONFIGURATION
Include salinity == 1,0
! TIME COMMANDS
Start time == 0.0
End time == 6.0
CFL == 1.0
Timestep limits == 0.0001, 10.
! MODEL PARAMETERS
Stability limits == 10. ,100.
Momentum mixing model == Smagorinsky
Global horizontal eddy viscosity == 0.5
Global horizontal eddy viscosity limits == 0.05, 99999.
Scalar mixing model == Smagorinsky
Global horizontal scalar diffusivity == 0.5
Global horizontal scalar diffusivity limits == 0.05, 99999.
! GEOMETRY	The model geometry is the 2dm created above in this tutorial module. Please use the new mesh Trap_Channel_001.2dm
Geometry 2d == ..\model\geo\Trap_Channel_001.2dm
! MATERIAL PROPERTIES
Material == 1
Bottom roughness == 0.018
End material
! INITIAL CONDITIONS
Initial water level == -3.5
Initial Salinity == 0
! BOUNDARY CONDITIONS
BC == Q, 1, ..\bc_dbase\steadyQ_02.csv
BC header == time,flow,Sal
Sub-type == 4
End BC
BC == WL, 2, ..\bc_dbase\steadyWL_02.csv
BC header == time,WL,Sal
End BC
BC == QC, 240,55, ..\bc_dbase\cellQ_02.csv
BC header == Time,flow,Sal
End BC
! OUTPUT COMMANDS
Output dir == ..\results\
Output == netcdf
Output Parameters == h,v,d,Sal
Output Interval == 600
End output

The TUFLOW FV control 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 the Model

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_02.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.

Reviewing Results

Using the instruction outlined in the previous section Reviewing Results open trap_steady_03.nc using the TUFLOW Viewer in QGIS. Your QGIS project window should look similar to the below:

In this section we will use the TUFLOW Viewer to visualise the long section of the velocity with vectors on. For a detailed description on how to use the Tuflow Viewer to view your results please refer to section Reviewing Results

Discussion:

How has the inclusion of a bump and constriction in your mesh changed the velocity in the channel?

Now open your previous result Trap_Steady_02.nc and compare to your results. Can you see how changing the mesh has altered your results?

Inclusion Of Salinity

It is relatively straightforward to include a conservative tracer into the model simulation.

Save a copy of Trap_Steady_01.fvc and name it Trap_Steady_02.fvc. The following additional components listed in the right-hand column of the table below are required within the FVC file:

FVC File Updates

! 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 modelled with salinity
Tutorial Model == ON	Enables licence free modelling.
! SIMULATION CONFIGURATION	Include salinity as a model parameter (the first number = 1), but decoupled from the density simulations (the second number = 0).
Include salinity == 1,0
! TIME COMMANDS
Start time == 0.0
End time == 6.0
CFL == 1.0
Timestep limits == 0.0001, 10.
! MODEL PARAMETERS	The scalar mixing model and diffusivity are specified as model parameters.
Stability limits == 10. ,100.
Momentum mixing model == Smagorinsky
Global horizontal eddy viscosity == 0.5
Global horizontal eddy viscosity limits == 0.05, 99999.
Scalar mixing model == Smagorinsky
Global horizontal scalar diffusivity == 0.5
Global horizontal scalar diffusivity limits == 0.05, 99999.
! GEOMETRY
Geometry 2d == ..\model\geo\Trap_Channel_000.2dm
! MATERIAL PROPERTIES
Material == 1
Bottom roughness == 0.018
End material
! INITIAL CONDITIONS	The initial water level is -3.5 and initial salinity concentration is 0.
Initial water level == -3.5
Initial Salinity == 0
! BOUNDARY CONDITIONS	An additional column in the boundary condition files is required, specifying the concentration at the boundary. The new boundary condition files have been renamed as version 02. A new boundary condition (QC) defines a constant inflow into an element (or cell). The numbers 240,55 are the x,y coordinates where the inflow will occur.
BC == Q, 1, ..\bc_dbase\steadyQ_02.csv
BC header == time,flow,Sal
Sub-type == 4
End BC
BC == WL, 2, ..\bc_dbase\steadyWL_02.csv
BC header == time,WL,Sal
End BC
BC == QC, 240,55, ..\bc_dbase\cellQ_02.csv
BC header == Time,flow,Sal
End BC
! OUTPUT COMMANDS	An additional output parameter is specified (Sal).
Output dir == ..\results\
Output == netcdf
Output Parameters == h,v,d,Sal
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.

Update Boundary Condition Files

Please copy the below files from Module_Data folder and placed in the ./TUFLOWFV/bc_dbase folder.

The updated flow boundary (steadyQ_02.csv) should contain the following:

Time	Flow	Sal
0.0	0.0	0.0
1.0	100	0.0
2.0	450	0.0
6.0	450	0.0

The water level boundary (steadyWL_02.csv) should contain the following:

Time	WL	Sal
0.0	0.0	0.0
48.0	-3.5	0.0

The cell inflow boundary (cellQ_02.csv) should contain the following:

Time	Flow	Sal
0.0	0.0	30.0
1.0	10.0	30.0
2.0	10.0	30.0
6.0	10.0	30.0

Run the Model

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_02.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.

View Results

Open the trap_steady_02.nc using the TUFLOW Viewer in QGIS. For instructions on how download the TUFLOW Viewer plugin, please visit | https://wiki.tuflow.com/index.php?title=TUFLOW_Viewer.

Take a timeseries of the Salinity output. Your result should look similar to the following:

Congratulations! You have successfully built and run a TUFLOW FV model.

Troubleshooting

This section contains a link help you troubleshoot some common issues that may occur when progressing through the first module of the TUFLOW FV tutorial model: Common reasons why a model won’t start.

Click on the following link to return to the main tutorial page.

Conclusion

Congratulations on completing Tutorial Module 01 with GIS Mesher. We've covered a lot in this tutorial, including introduction to modelling with TUFLOW FV, development of a TUFLOW FV model, running a model in the GIS Mesher GUI, checking the results using the TUFLOW Viewer in QGIS, and reviewed how mesh changes influence your model results.

To complete more tutorials or learn more tips and tricks, please return to the TUFLOW FV Wiki Mainpage. We will continue to add more functionality over time, so please periodically review. If you wish to keep up to date with all things TUFLOW and TUFLOW FV, then please join our LinkedIn group. If you have any queries, feedback or requests for new functionality, please feel free to get in contact with support@tuflow.com