DRAFT GISMESHER tut

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 walks through the first tutorial model using the GIS Mesher. The GIS Mesher supports building meshes for TUFLOW FV using several approaches. For this tutorial, step by step instructions are given to get you started with the GIS mesher.

The GIS Mesher works in coordination with your favorite GIS application and text editor to build meshes using command files similar to how TUFLOW FV files are utilized. For this workflow, we recommend using the QGIS TUFLOW Viewer for post-processing but Aquaveo SMS may also be used. These instructions will use QGIS but any GIS application that can build ESRI Shapefiles or Geopackage files can be used.

This example problem demonstrates the development of a basic model mesh. Follow the steps performed here and expand upon them to develop more complex, real world models.

The example is a trapezoidal channel, dimensions as shown:

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

Note: Try completing the following steps to create the TUFLOW FV models in this tutorial module. For reference, complete versions of the models can be downloaded from the TUFLOW website: http://www.tuflow.com/FV%20TutorialModel.aspx

Building the Mesh

Using our GIS application and the GIS Mesher, we will create the mesh from GIS layers. At a minimum, the GIS mesher requires a boundary to mesh within and target cell sizes and orientation. Nodestrings, materials, and elevations may also be assigned with the GIS Mesher. Some of these may also be assigned to the TUFLOW FV model using GIS layers. For this tutorial, we will use the GIS Mesher to accomplish the following:

• Create the project using the GIS Mesher GUI
• Define the model domain (boundary polygon)
• Define the mesh sizes
• Specify the nodestring locations
• Add the Elevation data
• Build the mesh using the GIS Mesher

For this simple model a single material is going to be used for the full domain.

Please note this tutorial has been created using QGIS version 3.20.1. You may use other versions of QGIS, however some minor differences may exist between the screenshots in this tutorial and the QGIS version you are using.

Creating the Project

The folders provided in this tutorial include Module_Data, Complete_Model, and Working. Copy these folders to where you would like to work with the project.

• The Module_Data folder includes the bathymetry information for the trapezoidal channel described in Tutorial Description, a projection file for the project, and some other files we won't be using.
• The Complete_Model folder has the files for the completed tutorial in case you get stuck.
• The Working folder is for the files you create and work within.

The GIS Mesher GUI provides tools for building projects, creating GIS files, running the mesher, and running TUFLOW FV. To create the project:

Firstly start-up the GIS Mesher GUI. It should like like the figure below.
Select 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 GIS file type as ESRI Shapefile.
5. For the Initial GIS files please check mesh_polylines, nodestrings, and boundary and uncheck the remaining GIS file types.
6. Leave the filenames and other settings as default.

The dialog should look similar to the figure below 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 .GISmesher folder stores the project settings for the GIS Mesher GUI. The meshing folder will have the meshing control files and has subfolders for GIS and Tables. The GIS folder has the blank 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 subfolders contains a TUFLOW FV simulation that can be used as a starting point to build models. Some of the folders and files will be referred to later.

Defining the model domain

Now that the project has been created, we need to fill-in the layers that were created by the GIS Mesher GUI. We'll start with the model domain (boundary GIS layer).

Note: You may need to add the QGIS plugin NumericalDigitize to access Numeric Digitizing tool

To setup the model boundary (QGIS instructions):
1. Open a new QGIS project and set the project CRS to WGS 84 / UTM zone 60S [EPGS:32760].
2. Load the file Working\tut01\meshing\GIS\boundary_001.shp by selecting Layer | Add Layer | Vector Layer from the menu. Select the file for the Vector Dataset(s) and click Add.
3. Make sure that the editor toolbar is active (right-click on the toolbar area to add it if needed). Select the boundary_001 layer and make editable by selecting the Toggle Editingbutton. Click on the Numerical Digitizingbutton and fill in the x and y values as shown in the figure below, select Coordinates are given in the CRS of the Layer and click OK.

4. Make the ID 1 in the dialog that pops up.

5. In the digitizing toolbar, click the save button and then the Toggle Editing to stop editing.

Your Boundary shapefile should now look the same as the below screen grab:

Define the mesh size information

The mesh size information can be specified on mesh points but we are going to use mesh polylines so we can elongate the cells in the direction of flow. Mesh polylines specify sizes as a size parallel to the polyline and a size perpendicular to the polyline.

To create the polylines and set the mesh sizes (QGIS instructions):
1. Add the file Working\tut01\meshing\GIS\mesh_polylines_001.shp to QGIS using the Layer | Add Layer Command.
2. Select the mesh_polylines_001 layer in the layers panel and click the Toggle Editingbutton on the digitizing tab.
3. Use the Numerical Digitizing tool to create mesh polylines with the following geometry and attributes. Please note that to use this tool, the NumericalDigitize plugin must be installed. To install this plugin, go to Plugins | Manage and Install Plugins, search for "NumericalDigitize" to select the plugin, and then click Install Plugin.

a. Polyline 1 south side of flume

i. geometry: from 0,0 to 1000, 0

ii. attributes: sizePara = 25, SizePerp = 12.5

b. Polyline 2 north side of flume

i. geometry: from 0,100 to 1000,100

ii. attributes: sizePara = 25, SizePerp = 12.5

4. Click the Save button and then Toggle Editing button on the digitizing toolbar.

Your mesh_polylines shapefile should now look the same as the below screen grab:

Specify the nodestring locations

Now that we have told the mesher how to size the mesh cells, we need to identify the nodestring locations. We need a nodestring on the upstream side of the model for the inflow boundary condition and a nodestring on the downstream side of the model for the WSE boundary.

To specify the nodestring locations (QGIS instructions):
1. Add the file Working\tut01\meshing\GIS\nodestrings_001.shp to QGIS using the Layer | Add Layer Command.
2. Select the nodestrings_001 layer in the layers panel and click the Toggle Editingbutton on the digitizing tab.
3. With snapping enabled (snapping toolbar), Add a Line Feature for the inflow on the left side of the mesh (from 0, 0 to 0, 100). Set the ID to 1 and specify T for External which forces the nodestring to follow the mesh boundary.
4. Repeat step 3 for the downstream side of the mesh (1000, 0 to 1000,100). Set the ID to 2 and External to T.
5. Click the Save button and then Toggle Editing button on the digitizing toolbar.

The figure below shows the direction and ID of your newly created nodestrings:

Add the Elevation data

We need to tell the GIS Mesher the elevation data to apply to the model. This is done by changing the meshing control file.

To specify the flume bathymetry for elevations:
1. Open the file Working\tut01\meshing\tut01_000.mcf in a text editor (Notepad++ is a free editor that has a lot of useful features).
2. Find the line that has Read Grid Zpts The line starts with an exclamation mark (!) which comments it out. Remove the exclamation mark and change it to Read Grid Zpts == ..\..\..\Module_Data\bathy_raster.tif as shown in the figure below.

Build the mesh using the GIS Mesher

Now we need to build the mesh from the GIS Mesher GUI. To do this:
1. In the Run Mesher tab, verify that the control file is tut01_000.mcf
2. Click Run. The text in the output should provide feedback on the meshing process and after a few seconds include the line GIS Mesher Finished Successfully.

3. Load the file meshing\output\tut01_000_cells.shp into your GIS Application. This is the mesh in shapefile format. The z attribute has the elevations assigned to the cells. The figure below shows the z elevations colored using the Viridis color ramp in QGIS. Note that the .2dm file will be used for TUFLOW FV.

TUFLOW FV Model Setup

The following example takes the trapezoidal channel mesh created above and sets up, runs and visualises a hydrodynamic simulation. Specifications for the model setup of the trapezoidal channel are as follows:

• The bed is lined with a coarse concrete; a Manning friction of 0.018
• There is a constant upstream inflow of 450 m3/s
• The downstream water level is 2.5 m above the bed

Nodestring Order

Open the meshing/output/tut01_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), 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

Copy the tut01_000.2dm to TUFLOWFV/model/geo

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. Create the flow boundary (steadyQ_01.csv) and include 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.

Now create water level boundary (steadyWL_01.csv) and include the following:

Time	WL
0.0	-3.5
48.0	-3.5

Both files should be placed in the TUFLOWFV/bc_dbase folder.

Create the TUFLOW FV Control File (FVC)

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:

• NotepadPlusPlus_Tips .
  
• UltraEdit_Tips .

Often, an fvc file is created from an earlier model or from a template. If using a template then it’s 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 example, the file is called trap_steady_01.fvc. The fvc file is shown below. A description of each entry is provided.

FVC File Contents

! 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 – that’s 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\tut01_001.2dm
! MATERIAL PROPERTIES	So far, material types haven’t 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

Note for more information and instructions on the TUFLOW Viewer QGIS plugin please visit TUFLOW Viewer

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 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 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 que your simulation

5. to initiate your model click Run

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 . See the following 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 TUFLOW Viewer plugin please visit | https://wiki.tuflow.com/index.php?title=TUFLOW_Viewer.

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 three 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 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 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

Troubleshooting

This section contains a link to 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 1 with GIS Mesher. We've covered a lot in this tutorial including introduction to modelling with TUWFLOW FV, development of a simple mesh model using GIS Mesher, TUFLOW FV model set up and how to run your model in the GIS Mesher GUI and check the results using the TUFLOW Viewer in QGIS.

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 here: https://www.linkedin.com/groups/1908583 If you have any further queries, feedback or requests for new functionality please feel free to get in contact with support@tuflow.com