Tutorial M01 Archive

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 via the Tutorial Data Package.

Modelling Folder Structure

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

You can either create this yourself or there is an example provided within the data download package Tutorial_Module_01_Simple_Trapazoidal_Channel\TUFLOWFV folder.

TUFLOW FV Model Geometry

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

Map Coverage

Data contained within the SMS Map Coverage is used to define the model mesh layout. Follow the below steps to define your Map Coverage:

1. The first step is to setup the SMS Map coverage. To build a mesh in SMS we use the "Mesh Generator" coverage type. Right click on the "Map Data" label, select "New Coverage" and select "Mesh Generator" from the pop-up window, as shown below:


Note if you would like to convert a existing coverage type to “Mesh Generator” right click on the coverage label in the explorer bar as shown below:


2. The map coverage works in a plan view. Using the “Create Feature Point” button, create the 8 points that define the channel.. As each feature point is created, use the coordinate boxes in the toolbar above the main display window to specify the precise coordinates (x and y), and elevation value (z). .

PT	X	Y	Z
1	0.0	0.0	0.0
2	0.0	25	-5
3	0.0	75	-5
4	0.0	100	0.0
5	1000	0.0	0.0
6	1000	25	-6
7	1000	75	-6
8	1000	100	0.0

The feature points should then look like:

3. Now use the “Create Feature Arc” button to join the dots together. To enable the snapping function navigate to the "Edit" - "Preferences" and "Map" tab.

4. Save the SMS Project into the model\geo folder. The project should be called trap_steady_01.sms.

You have now created the basic map layout that will define the model geometry.

Create Scatter Points

Scatter points contain elevation information which will at a later stage be interpolated onto the model mesh. To Create Scatter Points please follow the following steps:

1. In this example the scatter dataset will be created from the previously created Map Coverage. Do this by selecting “Feature Objects” – “Map -> Scatter” from the menu.

2. Make sure you specify the Z value source from the “Arc end points and vertex elevations” in the dialog box:

3. Use the display button to turn on contours in the scatter data module and view the newly created dataset:

a. Select the "Contours" tab in the "Scatter" Display Options. Also update the "Contour method" within the Contours tab.

b. Select "Color Fill" to visualize the z values. Reverse the colour palette so blue aligns with the minimum value and red with the maximum value.

The above configuration update should now show the below contoured z values:

Note: These steps relating to the scatter point dataset have replaced the often complex steps associated with inputting GIS layers, scatter datasets, etc to create the base topography/bathymetry for the model. The approach demonstrated is fine for a simple test case, but real world applications are often more complex and contain a variety of data sources. This can be done in SMS in a more rigorous manner (discussed in the SMS manuals) but is also done using other software such as GIS and CAD.

Build Polygons

Before we build our mesh we need to Build Polygons. To do this follow the below steps:
1. Click on the "Map Data" entry in the explorer window to do this.

2. The next step is to build polygons, which is done from the menu "Feature Objects" – "Build Polygons".


This takes the feature arcs and creates a series of polygons. It is these polygons that we can now individually investigate and specify mesh properties for.

Build The Mesh

Now we can build a mesh. To build the mesh, use the menu commands "Feature Objects" – "Map -> 2D Mesh".

The resulting mesh, as shown. It doesn’t look very good. But it is a mesh! A mesh has been created using 6 triangular elements (pave), connected by the nodes which, in this case, are the 8 points used to define the extents of the trapezoidal channel.

Note in the image that the scatter data set has been “unticked” in the explorer window – this hides the scatter data in the display, which makes the other information easier to see. Also unclick the map data set to better inspect the mesh data information. This model geometry is not good enough. We require a much higher resolution than this. A higher resolution is achieved by updating the information within the map data coverage, creating more vertices and hence more elements.

Note: more vertices along the polygon arcs = higher mesh resolution.

Please remove the 6 element triangular mesh prior to moving on on the next steps.

Modify Polygons

To make the coverage editable Click on the "Map Data" entry in the explorer window

Using the "Select Feature Polygon" button , double click on each of the polygons. A dialog box will appear with many options. Check out the SMS manual for a better description, or try a few different options and see what happens.

Some of the key options worth noting are:

• Mesh type:
  • Paving is the classic triangular mesh, where triangles are used to fill the polygon area.
  • Patch fills the polygon area with a patch of quadrilateral (rectangular) elements. There are some limitations to using this mesh type (like having 4 arcs defining the polygon).
• Bathymetry Type:
  • Scatter Set will use the scatter data we have created in the 'Create Scatter Points' step to set the z values in the mesh.
• Preview Mesh:
  • Use this to see how your mesh design looks for this polygon area.
• Along the bottom of the display image is a series of buttons which let you adjust arc lines and the vertices that define them.

For this model example we should adopt a resolution of 12.5 m across the channel and 25 m along the channel. Please follow the below steps to define your mesh:

1. Using the “Select Feature Arc” button , select the top arc adjust the number of vertices (the “Arc Options” buttons) to suit the desired mesh resolution. In this instance, there should be 1,000 / 25 - 1 = 39 vertices. Repeat this for the bottom arc.

2. Repeat for the left and right arcs, which will have 25 / 12.5 - 1 = 1 vertices. You may need to use the “Zoom” button to assist with arc selection.
3. Once this is done, select a "Patch" mesh type. For a straight trapezoidal channel such as this, a "Patch" mesh type is the most efficient.
4. Update the "Bathymetry Type" from "Constant" to "Scatter Set" and select "Scatter Options" to choose the specific dataset to apply.

5. Use the “Preview Mesh” to see what the mesh looks like. Use the "Zoom" function to see the finer details.

6. Once you are happy with the layout of the mesh within this specific polygon, repeat the steps for the remaining polygons. The middle polygon has 50 / 12.5 - 1 = 3 vertices across the channel and 1,000 / 25 -1 = 39 vertices along the channel. The lower polygon has the same vertex count as the top polygon. Note that as each polygon is edited, the arc vertices are updated – this highlights how the mesh generator tracks each polygon to ensure that the overall mesh is consistent.

7. Now repeat the steps listed for Build Polygons and Build The Mesh using the menu commands "Feature Objects" - "Build Polygons" and "Feature Objects" - "Map -> 2D Mesh" to create the mesh.

This time, a reasonable looking mesh should appear.

Note: If a mesh covering only one polygon is produced, please use the “Select Feature Polygon” button, click at any empty location in the screen to deselect all polygons and repeat the "Map -> 2D Mesh" step.
Note: If contours are not visible apply contour display option to 2D Mesh as described above

Nodestrings (Boundary Conditions)

The last step is to insert nodestrings. Nodestrings are a string of nodes that can be used to define the location of boundary condition inflows/outflows. For this example, there will be an upstream and a downstream boundary condition applied (ie along the left and right edges of the model domain). Please follow the below steps:

1. Press the “Create Nodestring” button , then click along the nodes that make up the left edge of the mesh. Nodestrings should all be created from right to left while looking downstream.
2. Repeat this procedure along the right edge of the mesh.
3. To visualise the direction of your nodestrings press the "Select Nodestring" button and select a nodestring.
Hint – hold the “Shift” button down to select all nodes between first clicked and second clicked nodes. Hit "Enter" to finish editing.

You have completed the construction of a mesh, congratulations. Resave your SMS project.

Visualisation

A useful way to review the created mesh is to visualise it in perspective view. To do this use the "Rotate" button , use shift-P to return to plan view.

• Click File >> Save to save the SMS project trap_steady_01.sms. This will preserve all of the input data used to develop our mesh (in case we wish to make updates in the future).
  
• Click File >> Save As. Select the type "2D Mesh files" (*.2dm). Save the file using the name trap_steady_01.2dm. This will become the geometry input file for 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

Nodestring Order

Open the 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 1 2 4 7 11 16 22 29 -37 1
NS 198 206 213 219 224 228 231 233 -234 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 nodes in SMS), the first nodestring is the upstream boundary (ie – a flow boundary) and the second nodestring is the downstream boundary (ie – a water level boundary).

Don’t panic if the nodes listed in the nodestring either have different numbers or are in reverse order to that shown; this doesn’t influence their behaviour. It is however important that each nodestring lists 9 numbers. This is the number of nodes that the nodestring intercepts

Boundary Condition Files

For TUFLOW FV, csv (comma delimited) format files contain boundary condition inputs. In this case, the boundary conditions are very simple because the run is steady state. The flow boundary (steadyQ_01.csv) 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.1, 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.
momentum mixing model == Smagorinsky
global horizontal eddy viscosity == 0.5
global horizontal eddy viscosity limits == 0.05, 99999.
! GEOMETRY	The model geometry is the 2dm created above in this tutorial module.
geometry 2d == ..\model\geo\trap_steady_01.2dm
! MATERIAL PROPERTIES	So far, material types haven’t been highlighted. By default, SMS 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 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_simulations.bat) has been included in the the tutorial dataset download within the Complete_model\TUFLOWFV\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

Note: The SMS Community Edition does not allow for completion of this step. If you are using SMS Community Edition, please proceed to the following step Inclusion of Salinity

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 the results, 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 please follow the below steps:

1. A feature arc needs to be created in the Map Data (the type of this coverage needs to be “Observation”). Then, the "Display" - "Plot Wizard" menu is used.

2. Select "Observation Profile"- "Next" in the Plot Wizard window

3. Select the following options to plot the Profile
> select "Specified" in the "DataSet(s)" section,
> check your depth result,
> select "Specified" in the "Time Step(s)" section and
> select "All On".

Your result should look similar to this:

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.1, 10.
! MODEL PARAMETERS	The scalar mixing model and diffusivity are specified as model parameters.
momentum mixing model == Smagorinsky
global horizontal eddy viscosity == 0.5
global horizontal eddy viscosity limits == 0.05, 99999.
scalar mixing model == Smagorinsky
global horizontal scalar diffusivity == 0.5
global horizontal scalar diffusivity limits == 0.05, 99999.
! GEOMETRY
geometry 2d == ..\model\geo\trap_steady_01.2dm
! MATERIAL PROPERTIES
material == 1
bottom roughness == 0.018
end material
! INITIAL CONDITIONS	The initial water level is -3.5 and initial salinity concentration is 0.
initial water level == -3.5
Initial Salinity == 0
! BOUNDARY CONDITIONS	An additional column in the boundary condition files is required, specifying the concentration at the boundary. The new boundary condition files have been renamed as version 02. A new boundary condition (QC) defines a constant inflow into an element (or cell). The numbers 240,55 are the x,y coordinates where the inflow will occur.
bc == Q, 1, ..\bc_dbase\steadyQ_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
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

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.

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:

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_02 in the download package, \Complete_model\TUFLOWFV\model\geo 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.

GIS Integration

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 your model. This section is optional but is highly recommended and will show you how to efficiently assign nodestrings, materials and elevations to the mesh, independent of the mesh generation process.

The build process uses the TUFLOW Viewer plugin for QGIS. To use the Plugin you will need to Download and Install QGIS (Version 3.6 or more later) and also install the TUFLOW Viewer Plugin. Configure Model with GIS

Follow: Configure model using QGIS to complete the GIS section of this tutorial.

Please note that FVC files 004 to 007 within the Complete_model\TUFLOWFV\runs folder relate to this section.

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.

Conclusion

Congratulations on completing Tutorial 1. We've covered a lot in this tutorial including introduction to modelling with TUFLOW FV, development of a simple mesh model, TUFLOW FV model set up and how to run your model and check the results.

To complete more tutorials or learn more tips and tricks please return to the TUFLOW FV Wiki Mainpage

We will continue to add more functionality over time so please periodically review. If you wish to keep up to date with all things TUFLOW and TUFLOW FV then please join our LinkedIn group 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