Tutorial Module01 Gismesher

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

The following example demonstrates the development of a very simple 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

Modelling Folder Structure

The first step is to establish a folder structure. For the TUFLOW FV tutorial model, the folder structure will be:

Mesh Generation Options

This tutorial can be completed with the Surfacewater Modeling System (SMS) from Aquaveo LLC or the GIS Mesher from Rising Water Software LLC.

The GIS Mesher application allows users to create meshes that are mixed quadrilateral and triangular cells using breaklines, variable cell sizes, create nodestrings, and assign elevations using GIS input files (QGIS, ArcGIS, MapInfo, or others). More information about the GIS Mesher application including demonstration videos can be found on the website Rising Water Software Homepage.

Create the mesh

We will create a mesh using the GIS Mesher using the following steps:

1. Setup the mesher project and create the initial GIS files
2. Define the mesh boundary
3. Define the sizes for the mesh elements
4. Identify nodestring locations
5. Assign elevations
6. Run the GIS Mesher application

Setup the Mesher Project

The GIS Mesher is a command-line application that takes text and GIS input files to generate a mesh. The software also comes with a simple GUI that helps to setup projects, create GIS files, and execute the GIS Mesher.

The GIS Mesher version of the tutorial, has three input files in the Module_Data\GIS_mesher folder:

• initial_node_coords.txt - These are coordinates for points that define the geometry of the flume (include elevations).
• bathy_raster.tif - This raster represents the surface defined by "inital_node_coords.txt" and was created using the SAGA tool "Triangulation" within QGIS. Similar tools for converting points with elevations into rasters are available in all GIS packages.
• working_projection.prj - Even though the flume does not really belong to a specific location on earth, we will have a project defined for the project. The projection is UTM zone 60 South in metric units.

A meshing project has a similar structure to the FV folder structure described above. We will create our meshing project within the "geo" folder in our TUFLOW-FV folder hierarchy. A meshing control file is used to control the meshing process supported by GIS files. The GUI will create the folder structure and populate a control file from a template. To setup the project:

1. Startup the GIS Mesher GUI Application.
2. Click on the button "New" in the Project box to add a new meshing project.
3. Click next on the first page of the Create New Project Wizard indicating that we will be creating a new project with the GUI.
4. In the second page of the wizard, set the following parameters
   • Project name: "Tutorial 1"
   • Parent folder: Copy or browse to the geo folder in the FV folder structure
   • Folder name for new meshing project: Meshing
   • Working projection: Browse to the file "working_projection.prj"
   • Output projection: Leave blank
   • Uncheck the following initial files which we don't need: mesh_points, materials, z_poly
5. Click Finish

• 

  GIS Mesher GUI Startup

• 

  GIS Mesher GUI New Project Wizard Page 1

• 

  GIS Mesher GUI New Project Wizard Page 2

The GUI will create a folder named "Meshing" within the geo folder. The folder has a gis folder with projection files for the working and output projections (which are the same in our case) and the GIS files that were selected in the create project dialog. The meshing folder also contains the file "Tutorial 1_001.mcf" which is our starting meshing control file. If you open the meshing control file in a text editor, you will see comments (start with !) and commands some of which reference the files created in the GIS folder. Creating a mesh will involve creating features in the GIS files and modifying the control file.

Define the mesh boundary

To define the mesh boundary, we need to create a GIS polygon representing the mesh extents in the file "boundary_001.shp" created by the GIS Mesher GUI. The steps in this tutorial can be completed in any GIS application that supports edit of GIS files. Detailed steps and screenshots are currently provided for QGIS.

To create the mesh boundary:

1. Startup your favorite GIS application.
2. Load the "bathy_raster.tif" file from the Module_Data\GIS_mesher folder which will provide background for the domain. To do this in QGIS, simply drag the file from Windows Explorer into the QGIS window. Style as desired by right clicking on the raster and choosing properties.
3. Load the file "boundary_001.shp" in the Meshing\GIS folder created by the GIS Mesher GUI. This file is already being referenced from the control file. To do this in QGIS, drag the file into the QGIS window.
4. Create a rectangular polygon from 0.0, 0.0 to 1000.0, 100.0 matching the extents of the raster. Toggle on editing from the toolbar, using the create polygon tool click out a polygon around the perimeter of the raster. Then using the Vertex tool, right click on a vertex to bring up the vertex editor panel (shown in the figure below). Assign the appropriate coordinates to each point.
5. Save your changes. To do this in QGIS, click on the save changes button and toggle editing off for the layer.

Because this shapefile is already referenced from the control file, nothing else needs to be done to include it in the mesh.

Define the sizes for the mesh elements

Element sizes are defined at point or polylines. Sizes are interpolated between defined point sizes. Polylines are required to create elongated elements so in this tutorial we will be using polylines rather than points. The GIS Mesher GUI already created and referenced the GIS file that we want to add the size information to.

To create the sizing polylines:

1. Load the file "mesh_polylines_001.shp" into your GIS application and make the layer editable.
2. Create polylines along the top and bottom edges of the flume boundary. To do this in QGIS, make sure that snapping is on and use the create feature tool to create the polylines making sure that you snap to the vertices on each corner of the domain.
3. Using the attributes dialog for each polyline, set the SizePara (size parallel to the polyline) to 25 meters and SizePerp (size perpendicular) to 12.5 meters. This will define the mesh sizes along each polyline. Because they are oriented in the same direction, the sizes are identical and will be consistent throughout the domain. More advanced mesh sizing options will be explored in future tutorials.
4. Save your changes and toggle editing off.

This layer is already referenced in the meshing control file so the mesh sizes are ready.

Identify nodestring locations

Nodestrings are used to define boundary conditions and plot output lines for TUFLOW-FV. We will only create boundary condition lines at the upstream and downstream ends of the flume. Nodestrings are defined using polylines.

To define the nodestrings:

1. Load the layer "nodestrings_001.shp" into your GIS application and make the layer editable.
2. Make sure that snapping is still on and create polylines along the upstream and downstream edges of the mesh snapping to each of the corners.
3. Using the attribute editing dialog or attribute table, set the "External" field of both polylines to "T" for True. This tells the GIS mesher that the nodestring should follow the external boundary. Set the ID of the west nodestring to 1 and the east nodestring to 2. This will be important when assigning boundary conditions to TUFLOW-FV. The name field is not currently used but will be used in future versions of TUFLOW-FV.
4. Save your changes and toggle editing off.

Assign elevations

For elevations, we want to assign elevations from the "bathy_raster.tif" which is in the "Module_Data\GIS_mesher" parallel to the TUFLOWFV folder. We assign elevations from the raster by modifying the meshing control file "Tutorial 1_001.mcf" that was created by the GIS Mesher GUI. This control file has a lot of comments which start with an exclamation mark (!). There are also a bunch of default parameters and settings based upon the starting template.

To assign the elevations:

1. Open the "Tutorial 1_001.mcf" in the meshing folder in your favorite text editor (I am fond of Notepad++ but any editor will do).
2. Find the comment line with the command Read Grid Zpts.
3. Delete the exclamation markk and change the right side of the double equal (==) to the raster filename which should be "..\..\..\..\Module_Data\GIS_mesher\bathy_raster.tif" if you followed the suggested folder structure. The absolute path to the filename will also work.

Run the GIS Mesher application

The easiest way to run the GIS Mesher is to use the GIS Mesher GUI.

To run the GIS Mesher:

1. Activate the GIS Mesher GUI. The "Tutorial 1" project should still be selected.
2. Make sure that the "Run Mesher" tab is active and that the "Tutorial 1_001.mcf" control file is selected.
3. Click on the "Run button"

The output window provides log information (that is also written to a file in the log folder). The mesher should create a set of files matching the command file name in the "Output" folder inside of the meshing folder.

You can review the setup of the meshing using your GIS application by looking at the following files:

• Tutorial 1_001.shp - This file has the mesh cells (elements) with attributes including the cell id and the elevation of each cell.
• Tutorial 1_001 nodes.shp - This file has the mesh nodes which have a point ID and an elevation. For TUFLOW-FV, elevations can be provided at the ndoes or the cells but cell based elevations are preferred.
• Tutorial 1_001_nodestring.shp - This file contains the final nodestring alignments (after snapping to element edges) and identifies the assigned nodestring IDs for each nodestring.

Now that the mesh has been created, we can setup the TUFLOW-FV model.

TUFLOW FV Model Setup

The following example takes the trapezoidal channel 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

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) should contain 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) should contain the following:

Time	WL
0.0	-3.5
48.0	-3.5

Both files should be placed in the 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.2.
stability limits == 10. ,100.
momentum mixing model == Smagorinsky
global horizontal eddy viscosity == 0.2
! GEOMETRY	The model geometry is the 2dm created above in this tutorial module.
geometry 2d == ..\model\geo\trap_steady_01.2dm
! MATERIAL PROPERTIES	So far, material types haven’t been highlighted. By default, the GIS mesher 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 nodestring 2 is assigned a water level boundary.
bc == Q, 1, ..\bc_dbase\steadyQ_01.csv
bc header == time,flow
Sub-type == 4
end bc
bc == WL, 2, ..\bc_dbase\steadyWL_01.csv
bc header == time,WL
end bc
! OUTPUT COMMANDS	In this instance, a datv format file is specified. This format is easily read into SMS for viewing. The h, v and d mean that outputs files containing water level, velocity and water depth will be created.
output dir == ..\results\
output == datv
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.

Run TUFLOW FV

Once you’re happy with the fvc file contents, run TUFLOW FV. Refer to the following link for simulation run options: Running TUFLOW FV.
An example batch file (run.bat) has been included in the the tutorial dataset download within the runs folder. You can run the batch file by double clicking it from Windows Explorer. It will sequentially execute the three models that are included in this tutorial module.

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 the result files will be written; one for the water levels (_H.dat), one for velocities (_V.dat) and another for water depths (_D.dat). They will have the same prefix as the fvc file; in this example they will be called:

trap_steady_01_H.dat

trap_steady_01_V.dat

trap_steady_01_D.dat

To view them, start SMS and open the 2dm file. Then, from either the SMS menu or by dragging into the SMS window, open the dat files. There are a range of display options in SMS; the following display shows a longitudinal profile of water depths throughout the simulation. To do this, a feature arc needs to be created in the Map module (the type of this coverage needs to be “Observation”). Then, the “Display” – “Plot Wizard” menu is used. See the SMS manual for advice on viewing results files.

Integrating GIS with Tutorial Model 1

As of the 2019-01 Release of TUFLOW FV you can now use GIS files in combination with a mesh generator (such as SMS) to build you model.
This section is optional but it will show you how to efficiently assign nodestrings, materials and elevations to the mesh, independant of the mesh generation process.
The build process uses the TUFLOW Viewer plugin for QGIS. Over time we will develop parallel workflows for Mapinfo and ArcGIS.
Please refer to Configure model using QGIS to complete the GIS section of this tutorial.

Inclusion of Salinity

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

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 + AD
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.2
Scalar mixing model == constant
Global horizontal scalar diffusivity == 1
! GEOMETRY
geometry 2d == ..\model\geo\trap_steady_01.2dm
! MATERIAL PROPERTIES
material == 1
bottom roughness == 0.018
end material
! INITIAL CONDITIONS
initial water level == -3.5
Initial Salinity == 0	The initial concentration is 0.
! BOUNDARY CONDITIONS	An additional column in the boundary condition files is required, specifying the concentration at the boundary. the new boundary condition has been renamed as version 02.
bc == Q, 1, ..\bc_dbase\steadyQ_002.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	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 header == Time,flow,Sal
end bc
! OUTPUT COMMANDS	An additional output parameter is specified (Sal).
output dir == ..\results\
output == datv
Output Parameters == h,v,d,Sal
Output Interval == 600
end output

Update Boundary Condition Files

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

View Results

The output file with concentrations will have the extension _SAL.dat:

trap_steady_01_SAL.dat

The results view in SMS should look something similar to the following:

Going Further

Model Topography Modification

For modellers with a firm grasp of the basics of modelling, the best way to learn how to setup and run TUFLOW FV is to experiment. In the following example, the mesh has been adjusted to include a “bump” in the centre and a constriction further downstream, which will induce transitions to supercritical flow. Mesh resolution has been increased around these features.

The results are far more interesting using this mesh design. The SMS Map, Scatter and Mesh data associated with this model is provided as trap_steady_03 in the download package, Complete_Model folder.

Note: When viewing model results in SMS it is required that the associated '2dm' file be opened first. Using SMS, skipping this step with either result in:

• a data load error (if the number of vertices/points/elements in the result file do not match that in the 2dm file); or alternatively
• the results dataset will load though not be displayed correctly. This display error occurs due to the number of vertices/points/elements in the result file matching the 2dm file, though the spatial location of the vertices/points/elements not matching.

Model Resolution Update

Try doubling the resolution of the model. What happens to the model simulation time when the model resolution is increased to cells with the following dimensions: 6.25 m across the channel and 12.5 m along the channel?

Halving the cell size results in 4 times the number of cells and a halving of the model timestep (required to meet the Courant criteria limits which calculate the model timestep). As such, halving the full model domain resolution results in an 8 fold increase in simulation time. This result highlights one of the benefits in using the TUFLOW FV flexible mesh model structure, where model resolution refinements can be varied spatially (ie. not applied globally over the entire model). This model structure reduces the overall number of computation cells within a model and increases the simulation runtime efficiency.

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.