Tutorial M02 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

In this tutorial a simple model of a short section of river is created using the SMS 13.2.0. We will firstly building a mesh for an inbank area of a river and then apply an upstream inflow boundary and a downstream tidal boundary.

Please note: This tutorial has been created using SMS version 13.2.0. If using a different version of SMS some of the dialogue boxes and screen shots may change slightly however the overall workflow should be similar. If you run into any problems or need help please contact support@tuflow.com

Tutorial Data

Download the Tutorial 2 Data Package.
The following datasets will be used during this tutorial:

Bathymetry data, this is provided as a SMS Scatter TIN dataset
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.

Model Setup

SMS Project Initilisation

From the Module_Data folder in the tutorial dataset, open the provided bathymetry scatter dataset RiverBend_Bathymetry.tin in SMS.

Colour the bathymetry by going to "Display" - "Display Options" (or if you prefer try the ctrl+d keyboard shortcut). In the "Scatter" - "Scatter" tab untick "Points" and "Breaklines" and tick "Contours".

In the "Scatter" - "Contours" tab select "Color Fill" for the "Contour Method". Click on the "Color Ramp" button and "Reverse" the Palette Preview

The bathymetry will be displayed as below.

Now in the "Display Options" - "Scatter" tick "Triangles" to match the display below

From the Module_Data folder open the provided landuse dataset RiverBend_LandUse.map.

We now will colour the landuse data by going to "Display" - "Display Options". In the Map untick "Node" and "Vertex" and tick "Fill" and "Legend". Note you may need to adjust the transparency.

Click on the "Options" button next to the Legend. In the "Font" section click on the displayed text "AaBb" and adjust the font style and size.

The landuse will be displayed as below.

The dataset contains three landuse types for this project: Sand, Gravel and Vegetation. When loaded correctly the table of contents in SMS should contain the scatter dataset containing the bathymetry and a map dataset containing the land use polygons as shown below.

Save the project in SMS. To save a project, select "File" - "Save as…" and save the project with TUFLOWFV\model\geo as RiverBend_Mesh001.sms (ensure the file is being saved as a project file type *.sms). Opening this SMS projected file in the future will load all of the model data.

Mesh Creation

Now that the required datasets are loaded we can begin to create the model mesh. We need to create a new coverage in the map module. Right click on the "Map Data" heading and select "New Coverage" as shown below. The coverage type should be set to "Generic" - "Mesh Generator". Name the coverage "Mesh_Features" and then select OK.

Make sure the newly created “Mesh_Features” layer is selected in the table of contents as per the image below.

In this layer we need to create a feature arc (polyline) in SMS to define our model extent. In the majority of cases this can be done using the create feature arc button (). For this tutorial however, the model we are going to create covers the full extent of our bathymetry scatter dataset. We can use the extent of the bathymetry dataset to define our model extent. This is done by converting the data on the scatter dataset into an object in our “Mesh_Features” layer.

To do this right click on the "RiverBend_Bathymetry" scatter dataset and the select "Convert" - "Scatter Boundary -> Map".

When prompted, select the "Mesh_Features" map layer as the target coverage.

After the conversion, the scatter dataset boundary should be in the "Mesh_Features" layer (this is easier to see with the scatter set turned off). This is shown in the image below. Note you may need to change the display options to view the nodes and vertices.

Zoom in to the northern boundary of the model, and select the two corner vertices (). After they are selected, right click and select "Nodes<->Vertices" to convert these to nodes.

Use Select the "Feature Arc" tool to select the feature arc (), then right click and use the "Redistribute Vertices..." to redistribute 10 vertices along the line.

We will repeat the process at the southern edge of the model. There may already be a node already associated with the southern edge or the model. Use the "Node Select" tool () to convert it to a vertex before redistributing the vertex spacing . This is done by selecting the node (left click), right click and select "Nodes<->Vertices". After doing this, follow the steps that were used for the northern end of the model. Using the "Redistribute Vertices..." to redistribute 10 vertices along the line.

Select the two feature arcs (if you hold down the shift key while clicking you can select multiple arcs) along the banks of the river and this time redistribute with a "Specified Spacing" of 20 (meters).

In order to build a mesh, we need to create a polygon from the feature arcs. To do this, select "Feature Objects" - "Build Polygons".

Using the "Polygon Select" tool (), select the polygon which has been created from the feature arcs and in "2D Mesh Polygon Properties" dialog box select "Preview Mesh". The default mesh type is paving, using this mesh type, the default elements are triangles as per the image below.

The mesh type patch uses quadrilateral elements preferentially. Change the mesh type to "Patch" and select "Preview Mesh". With the entire section of river as a single patch mesh, the quadrilateral elements get wrapped around the bend as shown in the image below:

Note: You may receive the following error

To avoid this, it is best to include sections across the channel (perpendicular to flow) at regular spacing along the channel, and in particularly around the bends.

To do this use the "Create Feature Arc" button () to create the lines across the river. These do not need to snap to existing vertices, new ones will be created if required. An example is shown below, once the lines are drawn, 10 vertices should be distributed along each arc. Using the "Select" tool, multiple arcs can be selected holding down shift.

Once the additional arcs have been created, the polygons need to be rebuilt. To do this select "Feature Objects" - "Build Polygons" from the menu. Once rebuilt, the individual polygons can be selected and have different mesh types applied. Select the southernmost polygon and select attributes (or double click on the polygon). Ensure the "Mesh Type" is set to patch and then hit "Preview Mesh".

In the "Mesh Preview" window, the mesh is now much better aligned with the predominant flow direction than previously. However, along one bank there are more vertices than the other; TUFLOW FV can handle both triangles and quadrilateral elements, so this is not a major issue. However, to align the elements with the flow direction, quadrilaterals are preferred over triangles (small elements, such as triangles in deep water can also reduce the timestep).

In this scenario, the river width remains relatively constant and we will use quadrilateral elements throughout the mesh. To achieve this, in the "Mesh Properties" dialogue, select the two bank lines and then in the "Arc Options" the number of vertices can be redistributed. If both are selected, each bank will have the same number of vertices and quadrilateral elements will be created. Steps to achieve this are outlined below

Repeat the process along the channel, an example is shown below.

When you have finished creating your mesh areas, we need to specify an elevation data source. This can be done individually for each polygon, however, as the bathymetry source is consistent, we can select all polygons using the "Polygon Select" tool (). To select all polygons you can drag a box around the polygons. With all the polygons selected, right click and select "Polygon Attributes...".

In the prompt, tick the "Elevation (bathytopo) type" and the select "Scatter Set". Once selected, hit the "Scatter Options" button. In the "Scatter Options" set the interpolation to "Linear" and the extrapolation to "Inverse Distance Weighted". When SMS has reshaped the vertices along the edge of the model it is possible that some are just outside the bathymetry dataset.

Configuring Mesh

The following section outlines how to generate the mesh and apply the materials and boundary conditions to the mesh.

Mesh Generation

Firstly convert the "Map Data Coverage" to "Generic Model". See steps below

Note this step was not undertaken in Module 1 but is required in Module 2 to import the materials onto the mesh.

Now convert your map_features coverage to a 2D mesh. To do this follow the steps shown in the below figure.

Applying Materials

To apply the materials coverage to the 2D mesh right click on Land_use coverage and select Map Materials to Mesh. 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.

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 (southern edge of the model domain) and a downstream (northern edge of the model domain) boundary condition applied.

To insert the nodestrings please follow the below steps:

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

Your mesh should now look similar to this:

Your River Bend mesh is now complete save it as .2dm into the \model\geo folder

TUFLOW FV Model Setup

In this section we take the meandering river channel created above and sets up, runs and visualises 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 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 671 670 669 668 667 666 665 664 663 662
NS -661 1
NS 1128 1173 1168 1163 1158 1153 1148 1143 1138 1133
NS -1123 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 10 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 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.

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 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	Here we specify the Mannings bed roughness model
! 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 == 42
CFL == 0.9
Timestep Limits == 0.01,10.
! 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 == 100., 10.
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\RiverBend_Mesh001.2dm
! MATERIAL PROPERTIES	The following roughness values have been suggested for Gravel (1), Sand (2), and Vegetation (3). If using SMS community edition only material ID=1 will be assigned. However, multiple materials can be assigned via GIS integration in TUFLOW FV. If you would like to know more please contact support at support@tuflow.com.
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 0 m.
Initial Water Level == 0.0	The initial condition is 0 m.
! 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\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 datv format file is specified. This format is easily read into SMS for viewing. The h, v and d mean that result 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 that you can copy to your working folder TUFLOWFV\runs. 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.

Reviewing Results

The results files for the model simulation should have written to the TUFLOWFV\results\ directory. In the input we asked for two dat result types, h (level) and v (velocity). These files can be loaded in SMS either using the "File" - "Open" interface or by dragging and dropping the files from Windows explorer.

Note: If you have closed the SMS project, you will need to open either the SMS project file, or the resulting model geometry (2dm) file prior to opening the result (dat) files.

These results will display in the table of contents in the Mesh Data. Turn off the Scatter and Map Data layers:

In "Display Options" enable viewing of contour and vector data:

The contour increment can be changed in the "Display Options"

Step through the results in the "Time Steps" window. In the Mesh Data there are three scalar datasets available for viewing (elevation, RiverBend_Mesh001_H and RiverBend_Mesh001_V_mag). The elevation dataset does not change over time. There is one vector set (velocity) available.

To extract time series at a point, create a new Map Data coverage (by right clicking on Map Data). This should be set to an "Observation" type. This is shown in the image below.

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 Reviewing Mesh Performance

Once created, highlight the dataset and select the "Create Feature Point" button (). Create a feature point in the location you would like to extract results. Multiple points can be extracted at the same time.

After creating the points, select "Display" - "Plot Wizard".

Select the "Time Series" plot type.

Choose the dataset and time period to extract the results, as per the image below and then select "Finish", the plot will be displayed.

In later modules we cover using the point output in TUFLOW FV to output results directly in .csv format; this allows higher frequency results to be extracted than the map output.

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 SMS, using an output file created in the TUFLOWFV\input\log\ directory: In SMS open the RiverBend_Mesh001_ext_cfl_dt.csv file.

The File Import Wizard can be used to import a large variety of data into SMS. In this case the file is in a comma separated value (.csv) format. In the file import options select "Delimited" and select "Comma" as the delimiter.

At the next prompt, turn off the triangulate data, and using the dropboxes, set the ctrd_x data to be mapped as "X", the ctrd_Y to be mapped as "Y" and the dt_min (minimum timestep) to be mapped as "Z". This is shown in the dialogue below:

Select “Finish” to open the data. There will be a new scatter dataset created, in the "Display Options" set the points to be visible, and select "Use contour colour scheme".

In the contour options, specify a contour range to highlight the cells with small timesteps. See the below example:

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.

Refining the Mesh

In this section we will increase the resolution in the mesh to see how this impacts the results and runtime of the model.

Remove the existing mesh from the SMS project.

Save the project as RiverBend_Mesh002.sms to avoid overwriting the previous version of the model. Once a new project has been saved, double the model resolution in a shallow area of the model, see the image below for a suggested location and resolution.

Once the changes have been made to the feature arcs, rebuild the mesh "Feature Objects" - "Map to Mesh".

Call the new mesh "RiverBend_Mesh002".

Note: don't forget to add your nodestrings and map your materials to the mesh

An example refined mesh is presented below:

If you are happy with the refined mesh, save the project (RiverBend_Mesh002.sms) and run the model again.

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. We've covered a lot in this tutorial including mesh generation, application of multiple materials, reviewing mesh performance and refining your mesh.

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