Main Page GISMESHER Tutorial Module03

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 covers building a mesh using the Solution Guided Meshing (SGM) approach which builds meshes using a semi-automated iterative process. SGM adapts a mesh based upon a previous TUFLOW FV solution and an underlying OEM. Meshes are sized to provide high resolution where needed and low resolution where they would be sufficient. This tutorial assumes that you have done tutorial #1and understand basic use of the GIS mesher software. Like the first tutorial, this tutorial requires access to GIS software and a text editor. There are freely available products such as QGIS and Notepad++ that can be used to complete the tutorial.
This tutorial uses the same files as tutorial 02. The mesh generated will be similar but not the same as tutorial 02 but use SGM.

The goal is to build a mesh that:

1. Has adequate resolution where the elevations are changing rapidly

2. Captures hydraulic controls such as elevated roadways

3. Have cells elongated in the direction of flow in channels

4. Have low resolution in areas where finer cells are not needed to improve run times

5. Is primarily quadrilateral Cells for improved accuracy and run times compared to triangles with similar edge lengths

The SGM process helps users achieve the goals above with user specified parameters to help vary mesh construction as needed for different applications. Some applications need tiny cells to capture the effects of concern while others may need coarser cells to support long duration runs with reasonable run times.

Because the SGM process creates meshes based upon the underlying bathymetry and topography, it is important that these are represented as well as possible. Anomalies in the data such as sharp steps or noisy data may cause mesh refinement where it is not needed or wanted. While these would ideally be fixed in the elevation data, it is possible to overwrite the sizing in local areas which will be explained within the tutorial. At this time, licenses for the GIS Mesher and TUFLOW FV are required to complete this tutorial. Temporary licenses of each are available to trial the software.

SGM Process

SGM is an iterative process to generate a mesh that adapts the cell sizes and orientation based upon TUFLOW FV solutions. The goal of SGM is to generate a mesh that provides appropriate resolution throughout the domain meaning finer cells where needed and coarser cells where allowable. Starting from an initial mesh and TUFLOW FV solution, SGM repeats the 3 steps below for a prescribed number of cycles.

1. Create a GIS layer with updated mesh size and orientation specifications based upon the previous mesh, TUFLOW FV solution, and a DEM.
2. Generate a new mesh utilizing the sizes developed in step 1.
3. Run TUFLOW FV with the mesh generated in step 2.

The following steps will be undertaken during this tutorial to create a mesh using the SGM process:

• Set up global options (preferences)
  
• Create the GIS Mesher project
  
• Create an initial mesh
  
• Setup an initial TUFLOW FV model
  
• Setup the mesh sizing template and associated files
  
• Setup the mesh generation template
  
• Setup the TUFLOW FV template
  
• Run SGM
  
• Modify the SGM parameters and rerun as needed
  
• Modify the final meshing control file to fine tune the mesh
  
• Use the mesh with desired model setup (boundary conditions etc.)
  

This tutorial will walk through these steps for the domain and boundary conditions from tutorial 02. This document can be a useful pattern for applying to your own model domain.

Model Overview

The following example demonstrates the development of a floodplain model with a tidal outlet. There are two inflow boundary conditions (one for the river and one for the tributary). There is a tidal boundary condition near the main river and another near the connection to the lagoon to the south.
The elevation data and aerial imagery for the model is shown below.

Tutorial Data

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 dem_5m.tif

2. Projected aerial imagery orthophoto.

3. The model shapefiles including boundary_001.shp, materials_001.shp and nodestrings_001.shp

4. The boundary condition information provided as csv files tide.csv and inflows.csv

5. Model control files tut03_hydrograph.fvc

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

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

• Elevation data provided as a raster in tif format dem_5m.tif
• Orthorectified aireal imagery
• Land-use areas, provided as SMS Map Coverage
• 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.

Please note that 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 If you run into any problems or need help, please contact support@tuflow.com

SGM Initial Mesh Development

This section will walk through the development of a mesh for this model using the SGM process following the steps outlined in the introduction. The process for each step will be explained along with suggestions on how the steps may change for other applications.

Setup the Global Options (preferences)

Before we start building the mesh, we need to ensure that we have things set up as needed. To do SGM, we need to run TUFLOW FV on the same machine we are meshing from. You need to have the GIS Mesher and TUFLOW FV downloaded and installed. The GIS Mesher GUI preferences control settings that are not project specific such as the location of the TUFLOW FV executable.

Follow the steps below to make sure that the preferences are set correctly.

1. Bring up the preferences dialog by clicking on the gear symbolin the toolbar or selecting Preferences from the File menu.
2. Set the location of the TUFLOW FV executable as needed.
3. By default, the GIS Mesher uses the working projection when creating new files for the meshing process. Let's leave that as is.
4. Set the Run TUFLOW FV options as needed based upon your individual setup. These will be used the run the initial TUFLOW FV model before running SGM.
5. In the Solution Guided Meshing section, the template files should be correct but change the hardware {GPU/CPU) as is appropriate for your setup. This is used to run TUFLOW FV within the SGM process.

Create the GIS Mesher project

With the preferences set correctly, we are ready to create the GIS Mesher project. The GIS Mesher Project is a folder that contains the meshing and TUFLOW FV files. When the GIS Mesher GUI creates a project, it sets up the folder structure and creates starting files to use when building the mesh.

To create a project, we need to identify a parent folder for the project and projection information for the working and output projections. The projection is provided in the Module_Data folder that accompanies this tutorial. The project will be created in the "working" folder provided with the tutorial files which should be empty when starting the tutorial. For this tutorial, we will use shapefiles that work well in many GIS systems including Qgis, ArcMap and ArcGIS Pro.

Follow the steps below to set up the project folders and create the project:

1. In the GUI, select New Project from the File menu to bring up the New Project Dialog.
2. Specify the working folder as the Parent Folder.
3. Specify tut02 as the project name. This will be the name of the folder created for the meshing project.
4. Click the [...] button for the working projection and select the file _Projection.prj in the Module_Data folder. We will leave the Output projection empty so it will use the working projection.
5. In the Initial GIS files section, unselect all of the files except mesh_points_001, nodestrings_001, boundary_001, and materials_001.
6. In the Solution Guided Meshing Options, leave the iterations at 3 and change SGM Simulation Prefix to tut03.
7. 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 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.

Create initial mesh

The next step is to create an initial mesh to use with the TUFLOW FV model. This mesh will be created using the approaches covered in the first tutorial. However, this mesh will be coarse and simple (constant cell size) relying upon the SGM process to refine the mesh so that it is usable.

To save time, GIS files are provided for the mesh boundary, materials, and nodestrings. We will create a GIS point layer to define mesh sizes around the perimeter of the boundary. This layer provides the initial mesh sizing and will be used with SGM to define sizes outside of the model domain. Dry cells outside of the wet area of the cells will grow based upon these sizes and the max_gradation command (see User's manual for description). This initial size will vary between models depending upon the area being modeled and the purpose for the modeling. A good rule of thumb is to make the initial cell size the maximum size you would use if creating the mesh manually. The initial mesh will be a poor representation of the terrain and generate unusable results. However,it will provide the SGM process a starting point and identify some of the areas to add refinement to better capture the terrain.

Follow the steps below to create the initial mesh from the provided and created flies:
1. Copy the files inside Module_Data\GIS folder into the working\tut03\meshing\GIS folder. You will be overriding files generated by the GIS Mesher GUI. This will copy over the boundary_001.shp, materials_001.shp, and nodestrings_001.shp GIS files.
2. Now open the boundary_001.shp and mesh_points_001.shp from the working\tut03\meshing\GIS folder.
3. Create points around the perimeter of the model and set the size attribute of the points to 100 (m) as shown in figure below.

4. Open the meshing control file tut3_000.mcf in your text editor. Find the commented-out line with the command Read Grid Zpts and uncomment the command by removing ! and use the DEM in the Module_Data folder for mesh elevations by updating ..\..\..\Module_Data\DEM\dem_5m.tif

5. Add the line ..GIS Format == ESRIShapefile at the top of the file. This tells the GIS Mesher to output check files in shapefile format it will also be the default GIS filetype for output f1les that do not have an extension.

Now that everything is set up, we need to generate the mesh by running the mesher from the GUI.

6. In the GIS Mesher GUI, select the Run Mesher tab and select the file tut3_000.mcfcontrol file combo-box and press Run.

This should generate a mesh in the working\tut03\meshing\output folder. There will be a 2dm file, .csv and multiple GIS files. Open the GIS output file, tut03_000_Cells.shp in your GIS application. There should be around 8,000 cells of generally a similar size.

In the symbology set the type to graduated and the value to z(elevation). Your result should look similar to the below figure if styled similarly.

Setup an initial TUFLOW FV model

SGM requires an initial TUFLOW FV model to use to develop the mesh. The TUFLOW FV model will be provided although some changes to the boundary conditions and the simulation controls will be necessary. The first step is to replace the GIS Mesher TUFLOW FV flies with the starting flies provided for the tutorial.
To do this please:

• Delete the sub-folders inside the folder working\tut02\TUFLOWFV
  
• Copy the sub-folders from Module_Data\TUFLOWFV and paste into working\tut03\TUFLOWFV
  

This model currently matches the "production model" or the model we eventually want to use for our analysis. We will set up the SGM model differently from the production model to ensure that the sizes are defined for the entire wet area and to improve SGM run times. It is often preferable to have some differences for the SGM models than the production model.

The SGM model will use a constant discharge at each of the inflow boundaries. The discharges will be larger than the production model peaks to ensure the SGM model covers a larger area than the production model. The inflows for the production model peak at 6,900m3/s and 400m3/s ('??? check the units with Rusty) for the primary and tributary flow boundaries.

We also want to change some of the model parameters. We will decrease the runtime by changing the end time so that the simulation runs for 12 hours instead of 24 hours, reference the new boundary condition file, and change the output options to be compatible with SGM. SGM requires a NetCDF output (can have additional output files as well). In our case, we need maximum statistics turn on because we are going to base our mesh generation on the dataset maximum values.

Please use the following steps to set up the SGM TUFLOWFV model:

1. In the TUFLOW FV\bc folder, make a copy of the file inflows.csv and name it inflows_ss.csv (steady-state). Now open the new csv in your preferred text editor.

• On line 3 change the Main_lnflow to 10000 and Tributary_lnflow to 600
  
• Delete lines from lines 4 to 73
  
• Now on line a change the Main_Inflow to 10000 and Tributary_Inflow to 600
  

Your inflows_ss.csv should look the same as the below:

2. Make a copy the file tut03\TUFLOWFV\runs\tut03_hydrograph to the same folder and it name tut03_000.fvc. This is the control file for the initial TUFLOWFV simulation. Now open the open the new .fvc in a text editor.

• Firstly, find the End Time command and change the end time to 01/01/2010 12:00 this will make the model will run for 12 hours of simulation time
  
• In Geometry Commands block and update the Geometry 2D command to ..\..\meshing\output\tut03_000.2dm and the Cell Elevation File command to ..\..\meshing\output\tut03_000_cell_elevations.csv
  
• In the Boundary Condition block and change the two refences to inflow.csv to inflows_ss.csv
  
• In the Output Command block make sure the output is a NetCDF and add an additional line in the block output statistics == Max see below
  

3. In the GIS Mesher GUI run the TUFLOWFV model tut03_000.fvc using the Run TUFLOWFV tab. Now set the Root Folder to the tutorial root folder. Select the tut03_000.fvc file. Select Add to Queue to add the simulation to the list and click Run to start the simulation.

The time it takes to run the simulation will vary depending upon your system and the number of threads that you are using. When the simulation finishes, we want to check the results to make sure that they appear correct. This tutorial assumes you are using QGIS with the TUFLOW Viewer QGIS plugin to visualise the TUFLOWFV results. For more information and instructions on the TUFLOW Viewer QGIS plugin please visit TUFLOW Viewer
To view your results file in QGIS:

• Firstly, set your projection by opening the Coordinate Reference System Selector and set to WGS 84 / UTM zone 60s
  
• Activate the Tuflow Viewer and open the results by selecting File > Load Results - Map Outputs now navigate to the nectdf output tut03_000.nc
  
• Move the timestep to the end of the simulation. Since we are holding flows constant the final timestep will have the deeper water levels
  
• Select the variable that you want to display and adjust the visuialtion setting as desired
  

See example of output below

Setup the Mesh Sizing Template

In each iteration of SGM, the GIS Mesher generates mesh size information based upon the previous solution and the DEM. This size information is used to generate the revised mesh. A mesh sizing template file contains the required parameters to calculate the new mesh sizes. A default mesh sizing template file is created with the project by the GIS Mesher GUI and in our case is named tut03_mesh_sizing_template.mcf. The mesh sizing template uses the same conventions as the other control files. Lines start with a command followed by a double equals (==) and a value or values afterwards.

Please open tut03_mesh_sizing_template.mcf in text editor as this section will step through the changes needed to set up the mesh sizing template and describe some of the options commonly used. Options that are not discussed in this section are generally left as default when the file was created. The User's Guide has documentation on all of the commands used in the mesh sizing template.

TUFLOW FV Solution and NetCDf Times commands

The TUFLOW FV Solution and NetCDF Times options control the TUFLOW FV solution filename and how the timestep data is used to generate revised mesh sizes. The TUFLOW FV Solution == command specifies the filename used to generate the sizes. The optional NetCDF Times == command is used to have solution guided meshing utilize specific timesteps when developing sizes.

The FV Solution command to specify the solution file uses a variable that is replaced by the GUI, namely "$iteration_previous" which is used to tell which iteration to look at for the solution file. In our case, the name defaulted by the GIS Mesher is correct and does not need to be changed.

By default, the GIS Mesher uses the average of all the timesteps when sizing the next mesh iteration. This can be changed to the maximum by adding "MAX" between "FV Solution" and the double equals symbols (e.g. TUFLOW FV Solution MAX == ). This can also be changed by utilizing the NetCDF Times command that is commented out with an exclamation point (!). When the NetCDF Times command is used, the mesh sizes will be based upon the specifically identified times (in hours). When multiple times are used, the sizing will be based upon the smallest size determined from each output time.

The NetCDF Times command can be used to capture mesh requirements during high and low flows. Generally, a stepped hydrograph is created where the first step matches the low flow (often bankful) discharge, and the second step matches is larger than the largest discharge that will be simulated. This approach ensures that the mesh resolution is appropriate during low flows that may otherwise not be captured when sizing based upon large floods.

The "MAX" option requires that TUFLOW FV is generating maximum outputs (turned on with the output statistics command seen earlier). For this tutorial, we are going to use the "MAX" option. The file change will be described later.

SGM DEM command

SGM requires a seamless elevation raster specified using the "SGM DEM" command. This DEM may be in a different projection than the working projection (the projection information must be stored with the raster). The minimum and maximum elevations for each cell are extracted from the raster and used to compute the revised mesh sizes.

Previous Background Mesh Command

This command references the background mesh for the previous iteration of mesh generation. This size information becomes the starting point for this iteration of mesh refinement (or relaxation). This command should not need to be modified.

Depth Chang Ratio Breaks and Depth Change Size Multiplier command

The Depth Change Ratio Breaks == and Depth Change Size Multipliers == are key commands that largely determine the sizes for the next iteration. Sizes are determined based upon a relative change in the depth within a cell (using minimum and maximum DEM elevations). Relative rather than absolute depth changes are used because a 10m change in deep water may not be critical but a 10m change in the floodplain would definitely be (as would a 1m change). The depth ratio change is defined using the equation:

DepthChangeRatio = (DepthMax - DepthMin) / DepthMin

The Depth Change Ratio Breaks splits the change ratios (between 0.0 and infinity) into zones. The accompanying Depth Change Size Multipliers defines the size multipliers that are used for the primary size for each zone. In the example below, if the depth change ratio is less than 0.7 than the primary size will be the previous size multiplied by 1.2 (increase). If the depth change ratio is between 0.7 and 1.5, the size will be the same. If the ratio is between 1.5 and 3.0, the primary size will be multiplied by 0.5. If the ratio is over 5.0, then the depth change multiplier will be 0.3.

Depth Change Ratio Breaks== 0.7, 1.5, 3.0, 5.0

Depth Change Size Multipliers == 1.2, 1.0, 0.7, 0.5, 0.3

As an example, if a cell has a WSE of 5.0m, a minimum DEM elevation of -10.0, and a maximum DEM elevation of 1.0. The minimum depth would be 4.0m and the maximum depth would be 15m (WSE minus minimum and maximum elevations). The Depth Change ratio would be (15.0-4.0)/4.0 = 2.75 which would make the size multiplier 0.7.

Min Depth for Sizing command

The Depth Change Ratio approach has a drawback that for small minimum depths, a very small maximum depth can cause the mesh to be refined generating very small mesh sizes. To prevent the mesher from adding too much refinement at tiny depths, the Min Depth for Sizing == command is used. This command sets the minimum value that can be used to compute the Depth Change Ratio. For example, suppose that the minimum depth for a cell is 0.01 and the maximum depth is 1.10. Without a Min Depth for Sizing == command, the depth change ratio would be (1.10 - 0.01) / 0.01 = 109! If the user specified 1.0 as the Min Depth for Sizing, the depth change ratio becomes (1.1 - 1.0) / 1.0 = 0.1. The modeler must think about the model domain and the purpose of the model to decide upon an appropriate value for this command.

Max Negative Depth in Dry Cell command

While the Min Depth for Sizing == command prevents unnecessary refinement in shallow water, the Max Negative Depth in Dry Cell command refines mesh cells to prevent cells from extending too far into areas that would be dry. If a cell has a minimum depth (elevation above the WSE), greater than the Max Negative Depth in Dry Cell == command the SGM process will force additional refinement in the area.

Minimum Primary Size command

The Minimum Primary Size == command prevents tiny cells from forming in areas of large elevation gradients. The modeler must decide upon this size since it will vary between models.

Secondary Size Ratio Table command

The previous commands define the target primary cell sizes. Primary cell sizes are enforced in the direction of flow. Cells are aligned in the direction of flow based upon the TULOW FV velocity results. The size perpendicular to flow is referred to as the secondary size. The secondary size is determined using a lookup table based upon the velocity magnitude to get a multiplier which is multiplied by the primary size.

In a hydraulic model, cells are typically elongated in the direction of flow. By using a lookup table, the sizes can be roughly square in areas where the velocity is low and increasingly elongated as velocities increase.

The size table is provided in a csv file identified by the Secondary Size Ratio Table == command. An example table is shown in Figure 7. Anything after an exclamation mark(!) is a comment and ignored by the mesher. ln this example, a cell with zero velocity generates a secondary size multiplier of 1.0 (secondary size same as primary size). Velocities of 2.0 m/s generate a secondary size multiplier of O.5 (secondary size half as long as primary size). Velocities of 4.0 m/s generate a second size multiplier of 0.3. Velocities are linearly interpolated between the values in the table to provide for a smooth transition between areas with different velocities. See example of secondary size ratio file below:

Output Mesh Points command

The result of the generate mesh sizes step is an output file written to the filename specified in the Output Mesh Points file. This filename will be used to adjust the sizing for the mesh in the next meshing iteration. This filename should generally not be changed and must match the meshing template file described later.

Tutorial Setup

With an understanding of how the commands work, we need to set up the sizing template for the tutorial. Please change the commands in tut03_mesh_sizing_template.mcf as outlined below:

1. Add Max to the FV Solution command e.g. FV Solution Max ==

2. Specify the DEM filename in the SGM DEM == command e.g. ..\..\..\Module_Data\DEM\dem_5m.tif

3. Modify the Depth Change Ratio Breaks to Depth Change Ratio Breaks== 0.7, 1.5, 3.0, 5.0

4. Increase the Min Depth for sizing to 2.0 (m)

5. Increase the Max Negative Depth in Dry Cell to 4.0 (m)

6. Increase the SGM Minimum Primary Size to 20.0 (m)

7. Modify the file .Tables\secondary_size_ratio.csv so that it matches the settings below:

Your final mesh sizing template contents should match the below:

Set up the Mesh Generation Template

For the mesh template, we are going to create a modified version of the meshing_template.mcf meshing control file in place of the automatically generated template file. We are going to add the command Read GIS Mesh Points with Direction == command which uses the output from the mesh sizing step to create the next iteration.
To create modified version of the Mesh Generation Template please follow the below steps:

• Delete the file tut03_meshing_template.mcf
  
• Duplicate the file tut03_000.mcf and rename it tut03_meshing_template.mcf now open this file in your text editor
  
• Add the following line below the Read GIS Mesh Points line Read GIS Mesh Points with Direction == .\GIS\tut03_gen_mesh_points_<<$iteration>>_Nodes.shp see example below

This tut03_meshing_template.mcf file will get used in the mesh generation step when running SGM.

Set up the Tuflow FV template

The TUFLOW FV template file will use a modified version of the tut03_000.fvc TUFLOW FV simulation file. The only difference is that the mesh geometry and mesh elevation flies will reference the flies for each iteration of the SGM process.

In the folder tut03\TUFLOW FV\runs folder make a copy of tut03_000.fvc and rename it tut03_sgm_template.fvc

Now replace the Geometry 2D and Cell Elevation commands with the lines below:

Geometry 2D == <<$mesh_filename>>.2dm
Cell Elevation File == <<$mesh_filename>>_cell_elevations.csv

The GIS Mesher will make a modified copy of this file to generate a new TUFLOW FV control file for each SGM iteration.

Run SGM

Now that everything is setup, we need to run SGM.

To run SGM in the GIS Mesher GUI, switch to the Guided Meshing tab and leave the Start Step at 1 and press the Start button

The SGM process should start with the first step (create sizing points) for Iteration #1. The progress bar will show progress. Eventually, the create sizing points step should finish and its progress bar turn green. Then the build mesh step will start, and its progress bar will activate. If you click on one of the steps, the text output from the step is shown in the window below. If the progress bar doesn't activate or one of the project bars turns red, an error has occurred.

What if it didn't work
There were a lot of steps to get to this point and it may not run correctly on the first try. This section has some tips depending upon where the error occurs. If the tips below don't help, try looking in the complete model folder and compare your files to the completed files.

If the error occurs before the create sizing points step
This happens when something is not set up correctly. Check the error message. The problem may need to be fixed in preferences or the project settings. Common errors are that the filenames used for the template files are not the same as those specified in the project settings (File|Project settings).

If the error occurs in the create sizing points step
This generally means there is a problem with the mesh sizing file. Check the output window in the step for errors that may help identify the problem. Check the instructions for the "tut2_mesh_sizing_template.md" file and make sure they match.A common error is not having the DEM filename correct.

If the error occurs in the Build mesh step
This generally means that there is a problem with the meshing template file. Check the output window for the step for errors that may help identify the problem. Check the instructions above regarding the meshing template.

If the error occurs in the Run TUFLOW FV step

This generally means that there is a problem with the TUFLOW control file template. Check the output window of the step for errors and review the steps above relative to the control file template.

Contact technical support if you are unable to resolve the issue

Review Results

This section describes some of what is happening within the SGM process and useful checks to ensure that it is performing as desired. I recommend checking the iteration #1 steps as they finish so you can identify and correct any issues and then kill and restart the SGM process. If the mesher has any problems completing the steps or the files do not match the information presented below, double check the steps above. If you cannot identify the source of the problem, compare the files to those in the provided meshing solution folder. If the problem persists, contact technical support.

Review Iteration 1 - Create Sizing Points

The first step of each iteration is create the sizing points. the GIS Mesher GUI first creates a "mesh sizing" control file from the sizing template file. To check this file:

Open the file tut03.001_gen_sizes.mcf in a text editor.

The variables in the template file which have the pattern <<$varname>> have been replaced with actual values. For example, the Output Mesh Points" command should match the line below.
Output Mesh Points == .\GIS\tut03_gen_mesh_points_001.shp

The GIS Mesher uses the mesh sizing file to generate the mesh points file which provides the sizes for the next mesh iteration based upon the previous solution, DEM and previous sizing information. This file can be checked with your GIS application by opening the file .\meshing\GIS\tut03_gen_mesh_points_001_Nodes.shp file within your GIS application. It can be helpful to color the points based upon attributes or check the values at specific points.
The initial attributes are for mesh sizing. These are computed by the GIS Mesher from the solution values and options specified in the mesh sizing control template file. A more complete description of these attributes is available in the User's Guide but they include:

• flags- is generally left blank,
  
• DirPri is the direction that the primary size is applied to (determined by direction of flow),
  
• SizePri is the primary size (size of the mesh in the direction of flow), and
  
• SizeSec is the secondary size (size perpendicular to the direction of flow).
  

The rest of the attributes contain information extracted from the TUFLOW FV solution used to generate the refined sizes:

• VelMag is the velocity magnitude at the cell (maximum in our case).It is used to determine the secondary size using the secondary size lookup table,
  
• Depth is the depth reported for the cell,
  
• WSE is the WSE reported for the cell,
  
• CellDMin_l is the minimum depth for the cell computed by subtracting the maximum DEM elevation from the WSE,
  
• CellDMax_l is the maximum depth for the cell computed by subtracting the minimum OEM elevation from the WSE,
  
• DRatio_1 is the depth ratio computed using the equation provided above. Larger values indicate a larger relative change in depth within the cell, and
  
• PriSizeMul is the primary size multiplier where values less than 1.0 indicate that the cells are becoming more refined and values greater than 1.0 indicate that the cells are growing. This value is determined from the options in the mesh sizing template file.
  

The below figure shows the mesh sizing points colored by the PriSizeMul. The darkest blue colors are where the mesh will be refined the most in the next iteration. These areas are mainly along the steeper channel sides. The lighter blue color are areas that will be refined but less aggressively. The green color identifies cells where the primary size was not modified (the secondary size may still be modified based upon the velocity). The yellow color indicates areas where the primary sizes are set to increase. The generated mesh won't necessarily meet all of these size targets because of constraints such as the size gradient limit.

Review Iteration 1 - Build Mesh

After the mesh points have been generated, the mesher will generate the updated mesh. The GIS Mesher will first create a new mesh control file from the provided template. As before, the file has variables that get replaced making the file match the SGM version.

Open the file tut2_001.mcf. There should be a command Read GIS Mesh Points with Direction pointing to the mesh nodes shapefile created in Step 1 (as well as other changes).

Next, let's check the generated background mesh. Open the GIS files check\tut2_001_background_mesh_cells.shp and check\tut2_001_background_mesh_nodes.shp in your GIS Application. The background mesh nodes should match the original sizes around the perimeter and the mesh sizing points described in the previous section. The sizes will not always match exactly because of the sizing gradient limits and other parameters. Check some of the interior points and compare them to the mesh sizing points.

Finally, let's load the mesh and compare it to the original mesh (000 iteration). Open output\tut03_000_Cells.shp and output\tut03_001_Cells.shp in your GIS application. Color both cell layers using the z field and toggle them on and off. You should notice some differences in some of the channels where the second iteration is starting to refine the mesh. The below figure shows the mesh cells colored by elevation for iteration #1. Notice that compared to the initial mesh, the cells are smaller and elongated in the direction of flow for the channels.

Review Iteration 1 - Run TUFLOWFV

The final step of each iteration is to run TUFLOWFV with the updated mesh. The GISMesher creates a TUFLOW FV control file for each iteration from the template file. We want to check the TUFLOW FV control file for the first iteration.

Open the file TUFLOWFV\input\tut03_001.fvc in your text editor and now:

• Find the Geometry 2D command and make sure that it points to thetut03_001.2dm file in the meshing folder, and
  
• Find the Cell Elevation File command and make sure that it points to the tut2_001_cellelevations.csv file in the meshing folder.
  
• Now run tut03_001.fvc in the GIS Mesher GUI

We also want to check the TUFLOW FV results. Open the map results in \TUFLOWFV\output\tut03_001.nc and review the model results using the QGIS TUFLOW Viewer plugin. For examples on how to review your results using the QGIS TUFLOW Viewer plugin, visit TUFLOW Viewer.

The figure below shows the solution for the first iteration. Compared to the initial solution, the depths are more refined especially in the channels which are captured much better with this version of the mesh.

Review Later Iterations

After reviewing the results from the first iteration, check the results for the other iterations after they finish. I recommend starting by reviewing the results from each iteration. If the cells are refining as expected and the results look good, there is no reason to check the sub-iteration steps. If there are problems, check the steps outlined above to identify and correct the source of the issue.

Each iteration should provide additional resolution in areas where the elevations are changing most rapidly, and the elongation become better targeted to areas with high velocities. The runtime to generate the mesh will depend upon the hardware that you are using. Running TUFLOWFV on an Nvidia GPU (GPU license required) will improve runtimes.

Modify the SGM parameters and rerun as needed

It is unlikely that you will get the exact mesh you had in mind the first mesh you create using SGM for the project. There will be areas where you want more or less resolution. If small or localized changes are needed the best approach might be to modify the final generated meshing control file which will be covered in the next step. However, if the changes required are on a more global scale, you may want to modify the mesh sizing or meshing templates. We are going to modify the settings so that on a global level we are going to generate larger cells but at the same time add refinement in an area of interest. We will first copy the tut03 folder in the working folder (with its .GISmesher, TUFLOWFV, and meshing folders). We will name this modified version of the meshing project tut03_alt We are going to leave the initial mesh/solution the same (tut03_000) but change the options that will impact the SGM generated meshes. To create the modified project and get started please follow the below steps:

• Open your file explorer to the working folder,
  
• Copy tut03 and rename it tut03_alt, and
  
• In the GIS Mesher GUI select File > Open Project and browse to the working\tut03_alt\.GISmesher\ folder and project_settings.GISMesher file.
  

We will be working in that folder from here forward. Your folder structure should be similar to the below figure

Size Changes

We will first modify some of the global settings to make the generated meshes slightly coarser overall and then add refinement to one specific area.
Open the file tut03_alt\meshing\tut03_mesh_sizing_template.mcf to make the following changes to the global sizing:

• Depth Change Ratio Breaks == 1.0, 1.8, 4.0, 6.0
  
• Min Depth for Sizing == 2.5
  
• Minimum Primary Size == 25.0
  

The GIS Mesher supports spatially varying size limits based upon a GIS layer input. Incorporating size limits can be done as part of SGM or as a modification afterwards. We will set it up and use it within SGM. We have an interest in an area near the downstream end of the river in the floodplain. We are going to force this area to be refined with cells having a maximum primary size of 25 and a maximum secondary size of 15 {forcing some elongation to the cells in the direction of flow).

To create and setup the Size Limits GIS File:

• In the GIS Mesher GUI, select the Create GIS tab.
  
• Set the type to size_limits and the filename to limits_refined_area_001.shp. By including the extension, we tell the GIS Mesher what type of GIS file to create if this is not specified, the GIS Mesher will use the project default.
  
• Leave the Layer name blank since shapefiles don't have layers, and
  
• Click Create File
  

Open the file in your GIS application and undertake the following steps:

• Create a polygon approximately the same as shown in Figure below. Noting that the placement of the polygon does not have to be precise,
  
• For the polygon, assign MaximumPri to 50 and the MaximumSec to 30, and
  
• Leave the other attributes blank (null).
  

Now that the file has been created, we need to add the file to the meshing template:

• Open the file tut03_alt\meshing\tut03_meshing_template.mcf in your text editor, and
• Add the line Read GIS Size Limits == GIS\Iimits_refined_area_001.shp

Rerun SGM

The modified SGM model is ready to run, to do this:

• Switch to the Guided Meshing tab, and
  
• Click Start
  

When the SGM process finishes, check the flies as before. The final mesh should have fewer cells overall with smaller elements around the defined refined area.

Troubleshooting

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

• Common reasons why a model won’t start
• Common reasons why a model crashes

For further support please email support@tuflow.com.

Conclusion

Congratulations on completing Tutorial 03 with GIS Mesher. We've covered a lot in this tutorial, including:

1. The semi-automated process requires little user setup time compared to traditional methods,

2. Cells are sized based upon relative depths to tailor resolution to where it is needed,

3. Cells are elongated in the direction of flow, and

4. Global settings allow users to adjust overall mesh refinement.

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