GISMESHER Tutorial Module02

From TUFLOW FV Wiki
Revision as of 12:53, 28 March 2023 by Georgia.stones (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
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 second tutorial model using the Rising Water Software GIS Mesher (version 2022.01). 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 will be used to create a simple model of a short section of river. We will build a mesh for an inbank area of a river before applying an upstream inflow boundary and a downstream tidal boundary.

The GIS Mesher works in coordination with your favourite GIS application and text editor to build meshes using command files similar to how TUFLOW FV files are utilised. For this workflow, we recommend using the QGIS TUFLOW Viewer for post-processing, however 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.

The model for this tutorial is a simple river with a couple of bends in the domain. The figure below shows the elevation data and identifies the flow direction.

Tut 02 bathy overview.png

Please note that this tutorial has been created using the GIS Mesher version 2022.01 and QGIS version 3.26.2. You may use other versions of the GIS Mesher or QGIS, however some minor differences may exist between the screenshots in this tutorial and the software version you are using If you run into any problems or need help, please contact support@tuflow.com

Tutorial Data

Download the Tutorial Module 2 dataset from the TUFLOW Website: http://www.tuflow.com/FV%20TutorialModel.aspx
The following datasets will be used during this tutorial:

  • Bathymetry data, provided as raster TIN dataset
  • The model domain provided as a polygonal shapefile
  • Land-use areas, provided as a shapefile
  • Boundary condition data, in comma separated variable (.csv) format

These datasets are contained within the folder titled Module_Data. Complete versions of the model have also been provided within the folder Complete_Model. The TUFLOW FV folder structure we will work within for this tutorial is provided as TUFLOWFV.

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

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 contains:
1. Elevation data provided as a raster in tif format rb_dem.tif
2. The model domain provided as a polygonal shapefile boundary_001.shp
3. The materials to use for TUFLOW FV provided as a polygonal shapefile materials_001.shp
4. The boundary condition information provided as csv files tide.csv and flows.csv
5. The project projection file _Projection.prj
  • The Complete_Model folder contains 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.
Tut 01 GIS MESHER GUI 00.png

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 _projection.prj file from the Module_Data folder.
4. We will leave the GIS filetype as "ESRI Shapefile".
5. For the Initial GIS files please check mesh_polylines, nodestrings, boundary and materials, then uncheck the remaining GIS filetypes.
6. Leave the filenames and other settings as default.

The dialog should look similar to the figure below. Click OK.

Tut 02 create proj.png

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 TUFLOW FV folder and subfolders contain 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.

Tut 02 GISMESHfolder struc.png

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

To save time, the model boundary has been provided. Copy all the files that start with boundary_001 from the Module_Data folder, replacing the files of the same names in the Working\tut02\meshing\GIS folder. These files are a GIS shapefile and its supporting files.

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 meshing\GIS\boundary_001.shp and 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 EditingTut 01 qgis editable 00.png button on the digitizing tab.
3. Select the Add a Line Feature Tut 01 digiLine 00.png button on the digitizing toolbar.
4. With Snapping Enabled Tut 01 EnableSnapping 00.png set the Enable Tracing offset to 10m. Now trace the western bank of the boundary to generate mesh polylines along the side of the model boundary.
Tut 02 trace offset.png.

5. Set the feature attributes as the following: sizePara to 24 (m) and sizePerp to 8 (m). This will make cells 24m in the direction of the polylines and 8m perpendicular.

6. To trace the eastern bank of the boundary firstly change the Enable Tracing offset to -10m and now trace the east bank of the boundary

7. Set the feature attributes as the following: sizePara to 24 (m) and sizePerp to 8 (m). This will make cells 24m in the direction of the polylines and 8m perpendicular.

8. Turn off Enable Tracing in snapping toolbar.

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

Your project window should look similar to the below.
Tut 02 mesh polylines.png

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\tut02\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 EditingTut 01 qgis editable 00.png button on the digitizing tab.
3. With snapping enabled Tut 01 EnableSnapping 00.png (snapping toolbar), Add a Line Feature Tut 01 digiLine 00.png across the mesh at the model inflow (See figure below). Set the ID to 1 and specify T for External which forces the nodestring to follow the mesh boundary.
4. Repeat step 3 at the model outflow (see figure below). Set the ID to 2 and External to T.
5. Click the Save button and then the Toggle Editing button on the digitizing toolbar.

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

Tut 02 NodeString 00.png

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 bathymetry for elevations:
1. Open the file Working\tut02\meshing\tut02_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\rb_dem.tif, as shown in the figure below.

Tut 02 MCF GRID COMMANDS 00.png

Incorporate the materials information

Manning Roughness Coefficients are assigned to the mesh based upon a "material" type that is specified for each cell. The materials can be provided using a GIS polygon layer with IDs for each of the materials. A default material (generally the most prevalent) can be assigned in the GIS Mesher Control File to reduce the amount of digitizing required.

To reduce digitizing, the material polygons have been provided. From the Module_Data folder, copy materials_001 with the varied file extensions to Working\tut02\meshing\GIS, and replace the existing materials file in GIS folder.

Open the Meshing Control File, tut02_000.mcf in your text editor. Look for the line with the command Set Materials == 1, and ensure that this is set to 1. This command sets the default material ID.

Tut 02 set mat.png

If you load the materials data into your GIS application and colour by material ID, you should see something similar to the figure below. The Manning N values will be defined when setting up the TUFLOW FV model.

Tut 02 mat ID .png

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 tut02_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.
Tut 02 runGUI .png
3. Load the file meshing\output\tut02_000_cells.shp into your GIS Application to verify that the mesh appears correct.

The mesh should look something like the figure below if styled similarly based upon z value. You can also symbolize the mesh based upon the "MaterialID" field to verify that these are set correctly.

Tut 02 cell mesher.png

TUFLOW FV Model Setup

In this section we take the meandering river channel created above and set up, run and visualise a hydrodynamic simulation. Specifications for the roughness values and boundary conditions are as follows:

  • The bed and banks are lined with gravel, sand and vegetation; a Manning friction of 0.035 for gravel, 0.028 for sand and 0.06 for vegetation will be adopted
  • There is a upstream inflow boundary and a downstream tidal boundary

Nodestring Order

Open the meshing/output/tut02_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 81 84 250 251 253 255 257 271 272 264
NS -263 1
NS 129 130 137 448 512 420 146 143 411 439
NS 133 -134 2

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 nodestring 1 lists 10 numbers and nodestring 2 lists 11 numbers. This is the number of nodes that the nodestring intercepts.

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

Copy the tut02_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 tide and flow boundary conditions are provided in the Module_Data folder. Please copy the flows.csv and tide.csv into the .\TUFLOWFV\bc_dbase folder and copy over any duplicate files in bc_dbase.

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:

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

FVC File Contents

! TUFLOW FV TUTORIAL MODULE 2 The first 2 lines are a description of the model simulation. You may also wish to include the initials of the modeller, etc.
! River Bend
Tutorial Model == ON Enables licence free modelling.
! SIMULATION CONFIGURATION Here we specify the Mannings bed roughness model.
Bottom Drag Model == Manning
! 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 == 48
CFL == 0.9
Timestep Limits == 0.0001,100
! MODEL PARAMETERS The model parameters are those that control various physical and numerical processes.

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\tut02_000.2dm


! MATERIAL PROPERTIES The following roughness values have been suggested for Gravel (1), Sand (2), and Vegetation (3).
material == 1 ! Gravel
bottom roughness == 0.028
end material
material == 2 ! Sand
bottom roughness == 0.035
end material
material == 3 ! Vegetation
bottom roughness == 0.06
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 == 0.0


! 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 consideration of the depth when distributing flow. Nodestring 2 is assigned a water level boundary.
bc == Q, 1, ..\bc_dbase\flows.csv
bc header == time,flow
Sub-type == 3
end bc


bc == WL, 2, ..\bc_dbase\tide.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


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.

Tut 02 FVC .png

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 Tut 01 preferences .png and checking the TUFLOW FV Executable is correct. Please see below:

Tut 01 checking EXE .png

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 River_Bend_01.fvc
4. Click Add to Queue. This will queue your simulation
5. To initiate your model, click Run

Tut 02 run tfv.png

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.

Review 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 River_Bend_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 Tut 01 PluginButton .png. The TUFLOW View will appear as below. To open your results, please select File>Load Results-Map Output and navigate to your result.

Tut 01 LoadResults .png

Your QGIS project window should look similar to the below:
Tut 02 Result window.png

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 Tut 01 XSplot button .png
3. In the drop down, check bed elevation
4. In the drop down, check water surface elevation

Tut 01 ViewResults setup XS 00 .png

To draw the long section, please select the Tut 01 XSplot button .png and your cursor should now become a crosshair [+]. Now you are ready to plot your long section. See the long section example below:
Tut 02 LS 00.png


(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 Tut 01 TSplot button .png and in the drop down check velocity
5. To draw the long section, please select the Tut 01 TSplot button .png and your cursor should now become a crosshair [+]. Click on your results to view a time series similar to the below:

Tut 02 TS 00.png


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

Reviewing Mesh Performance

In this section we will look at the performance of the mesh in terms of timesteps required. The TUFLOW FV model uses an adaptive timestep which is based on the specified Courant-Friedrichs-Lewy condition (CFL parameter). The model timestep is calculated based on the cell size and depth. A poorly configured mesh with a single small cell in deep water can limit the timestep of the entire model. Therefore, after running the model it is beneficial to review the timestep required to run the model. We will review the timestep information in QGIS, using an output file created in TUFLOWFV\runs\log. Please follow the below steps.

1. Add the file Working\tut02\TUFLOWFV\runs\River_Bend_01_ext_cfl_dt.csv to QGIS using the Layer | Add Layer | Add Delimited Text Layer Command.
2. In the Add Delimited Text Layer window, navigate to the River_Bend_01_ext_cfl_dt.csv in the log folder
3. In the File Format, select CSV (comma separated values)
4. In the Records and Field options, check First record has field names and leave everything else unchecked
5. In the Geometry Definition, select Point coordinates
6. In the Geometry Definition, set X field to ctrd_x, Y field to ctrd_y and Z field to cfl_dt_min
7. In the Geometry Definition, set the Geometry CRS to 32760 - WGS 84 / UTM zone 60S
8. In the Sample Data window, using the dropdowns, set the following attributes: id to Integer (32 bit), ctrd_x to decimal, ctrd_x to decimal, cfl_dt_min to decimal and cfl_dt_mean to decimal. For earlier versions of QGIS that do not have this option please check Detect field types under the Record and Field Options section

Now select Add to open the dataset.

Tut 02 import CFL CSV 01.png

The River_Bend_01_ext_cfl_dt point dataset will be imported into the project window. In the Layer Properties of River_Bend_01_ext_cfl_dt, please set the Symbology as specified below:

1. Set the symbology type to Graduated
2. Set the Value to cfl_dt_min
3. Set the mode to Equal Interval
4. Set the class number to 8
5. Select Classify
6. Manually change the class minimum to 0.2 and increase at 0.10 increments to 1.0 in the Values and Legend columns
7. Select Apply

Tut 02 Aset CFL symbology 01.png

The timesteps should now appear as a series of points, as per the image below. This can be used to identify the cells that are limiting the timestep of the model. In this case, the limiting cells are in the deep water around the bends in the model. To increase the speed of the model we would need to relax (coarsen) the mesh definition in these areas.

Tut 02 CFL checks 00.png

Refining the Mesh

Mesh generation is rarely done all at once. Meshes are refined as model results are reviewed to better capture hydraulic controls, to add refinement as needed, or coarsen the mesh to improve run times.

There are lots of ways to modify sizes in the GIS Mesher, including:

  • Change the size parameters on existing points or polylines.
  • Add additional size points or polylines - This can be useful if you want to refine an area and there is sufficient space for a size transition.
  • Use the Size Multiplier command to scale the sizes for an entire mesh points or mesh polylines layer.
  • Add a Size Multiplier GIS layer to scale the sizes attached to mesh points or mesh polylines.

We will use the Size Multiplier GIS layer to create a mesh with an area of refinement.

To set up the refined mesh, we firstly need to create the Size Multiplier GIS layer. Please follow the below steps:
1. In the GIS Mesher GUI, switch to the Create GIS tab.
2. Choose size_multipliers for the Type.
3. Now set the filename to sm_refinement_001.shpand leave the layername field blank.
4. Click Create file. The file will be created in the Working\tut02\meshing\GIS folder.

Tut 02 create sizemulti shp.png

Now load the created Size Multiplier GIS layer, boundary layer and DEM into QGIS:

  • .\Working\tut02\meshing\GIS\sm_refinement_001.shp
  • .\Working\tut02\meshing\GIS\boundary_001.shp
  • .\Module_Data\rb_dem.tif

We will now edit sm_refinement_001.shp and set the Size Multiplier values:

1. Select the sm_refinement_001 layer in the layers panel and click the Toggle EditingTut 01 qgis editable 00.pngbutton on the digitizing tab.
2. Create a polygon in approximately the same location shown in the figure below.
3. Set the MultiPri and MultiSec attributes both to 0.5. This will override the mesh sizing in the area to make the cells half as large in the primary (parallel to polyline) and secondary directions (perpendicular to the polylines).
4. Click the Save button and then Toggle Editing button on the digitizing toolbar.

Tut 02 mesh refinement parameters.png


We will now create the refined mesh:
1. Make a copy of the file tut2_000.mcf in the Working\tut02\meshing folder and name it tut2_001.mcf
2. Open the new file tut2_001.mcf in your text editor and add the line Read GIS Size Multipliers == GIS\sm_refinement_001.shp. The location in the file is not critical however after the global options and projection commands is recommended to keep those items at the top.
3. In the GIS Mesher, change to the Run Mesher tab and select the file tut2_001.mcf and click Run. This will regenerate the mesh with refined area.
You should now have a new mesh file \.meshing\output\tut02_001.2dm
Tut 02 runGUI fvc02.png

We will now test our new mesh in TUFLOW FV:
1. Copy your new mesh file tut02_001.2dm to .\TUFLOWFV\model\geo
2. Make a copy of the River_Bend_01.fvc and rename it River_Bend_02.fvc
3. Update the Geometry command to Geometry 2D == ..\model\geo\tut02_001.2dm
Tut 02 2dm updateFVC .png

4. You are now ready to run your model. Please follow the previous section TUFLOW FV with the GIS Mesher GUI

Once you have successfully run your please review the performance of your new mesh using the previous steps in section Mesh Performance

  • How much did the model runtime change?
  • Did the timestep in the model change?

Troubleshooting

This section contains a link to some common issues that may occur when progressing through the TUFLOW FV tutorial models:

For further support please email support@tuflow.com.

Conclusion

Congratulations on completing Tutorial 2 with GIS Mesher. We've covered a lot in this tutorial, including mesh generation, application of multiple materials, reviewing mesh performance, mesh refinement, running models in the GIS Mesher GUI, and checking 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