Tutorial Module02

Jump to: navigation, search
LINKS: Main page
Modelling Advice Tutorial Models Tips and Tricks
Mesh Generation Tips Tutorial Module 1 SMS
A Model Won't Start Tutorial Module 2 UltraEdit
A Model Crashes Tutorial Module 3 Notepad++
A Model Runs Slow Tutorial Module 4 Excel
TUFLOW Products Support / Contact TUFLOW FV Utilities
Requesting a Licence Running TUFLOW FV
Mesh Generation Tips

Tutorial Description

In this tutorial a simple model of a short section of river is created using the SMS TUFLOW FV interface. We will be building a mesh for an inbank area of a river, we will be applying an upstream inflow boundary and a downstream tidal boundary.
Please follow the configuration steps provided in the following link before starting this tutorial: http://fvwiki.tuflow.com/index.php?title=TUFLOW_FV_SMS_Interface

Tutorial Data

Download the Tutorial Module 2 dataset from the TUFLOW Website: http://www.tuflow.com/FV%20TutorialModel.aspx

The following datasets will be used during this tutorial:

  • Bathymetry data, 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'.

Model Setup

SMS Project Initilisation

Open SMS. Load the TUFLOW FV model definition file in SMS to initilise the SMS TUFLOW FV Interface. To do this, open the TUFLOW_FV.2dm file provided as part of the TUFLOW FV SMS interface dataset (http://fvwiki.tuflow.com/index.php?title=TUFLOW_FV_SMS_Interface)
From the 'Module_Data' folder, open the provided bathymetry scatter dataset (RiverBend_Bathymetry.tin) in SMS.

Tute2 000.png

Also from the same folder, open the provided landuse dataset (RiverBend_LandUse.map) in SMS.

Tute2 001.png

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.

Tute2 002.png

Save the project in SMS. To save a project, select File >> Save as… Save the project 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 Models >> Generic 2D Mesh. Name the coverage “Mesh_Features” and then select OK.

Tute2 003.pngTute2 004.png

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

Tute2 005.png

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 (Tute2 006.png). 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.

Tute2 007.png

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.

Tute2 008.png

Zoom in to the northern boundary of the model, and select the two corner vertices (Tute2 009.png) and convert these to nodes.

Tute2 010.png Before

Tute2 011.png After

Select the feature arc (Tute2 012.png) and then right click and use the redistribute vertices to redistribute 10 vertices along the line.

Tute2 013.png

Tute2 014.png

Repeat the process at the southern edge of the model.

Tute2 015.png

Select the two feature arcs along the banks of the river and redistribute with a specified spacing of 20 (metres). The SMS window should now appear as below.

Tute2 017.png

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

Tute2 016.png

Using the polygon select tool (Tute2 018.png), select the polygon which has been created from the feature arcs. The default mesh type is paving, using this mesh type, the default elements are triangles as per the image below.

Tute2 019.png

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 an error about overlapping elements

Tute2 020.png

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 (Tute2 021.png) 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.

Tute2 022.png

Once the additional arcs have been created, the polygons need to be rebuilt. To do this select Features 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.

Tute2 023.png

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.

Tute2 024.png

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

Tute2 025.png

When you have finished creating you 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 (Tute2 026.png) you can drag and drop a box around all polygons. With all the polygons selected, right click and select “Attributes”.

Tute2 027.png

In the prompt, tick the check box next to Bathymetry type and the select “Scatter Set”. Once selected, hit the “Scatter Options” button. In the Scatter options set the Interpolation method to Linear and the extrapolation to “Single Value” and enter a value of 2.

When SMS has reshaped the vertices along the edge of the model it is possible that some are just outside the bathymetry dataset. The extrapolation method defines how these are set, we have used a high elevation, and alternative option is to use the Inverse Distance Weighting option.

Tute2 028.png

Tute2 029.png

Boundary Condition Definition

We next need to define the locations for our boundary conditions. Select the feature arc at the northern edge of the model and in the “attributes” dialogue, set this type to Boundary Condition, as per the image below. Then select Options...

Tute2 030.png

In the boundary condition dialogue, set the boundary type to “Water Level” and the select “Define” (step 2 in the image below).

Tute2 031.png

Open the Tide.xlsx or Tide.csv in Excel (these are in the provided data), copy and paste the data into the series editor. All data can be copied at the same time; this does not need to be done one column at a time. The dialogue should look like the below.

Tute2 032.png

At the southern end of the model select the feature arc and apply a flow boundary. The flow is in the “flows.xlsx”. See also the image below. The boundary data and locations can be changed after the mesh has been created. This is described further below.

Tute2 033.png

Mesh Finalisation

We are now ready to build the mesh from the map data. To do this select Feature Objects >> Map >> 2D Mesh.

In the 2D Mesh Options check the “Use area coverage” option. In the drop box ensure that the Land_Use layer is selected. When the mesh is created, this uses the land use layer for setting the material definition in the elements created. This can also be set individually on the polygons in the “Mesh_Features” layer.

Tute2 034.png

After the meshing is completed, turn off the scatter dataset and the map data:

Tute2 035.png

In the display options, turn on the elements, contours and nodestrings

Tute2 036.png

The mesh elements and boundaries should now be visible. The image below shows the entire mesh on the left and a zoomed in inset on the right. In the inset it can be seen that the mesh elements align with the flow direction. Whilst not mandatory, this is the preferred mesh alignment.

Tute2 037.png

Boundary Condition Update

To modify the boundary data (we do not need to do this just yet, but it is useful to know), ensure you are in the mesh module (by clicking in the mesh in the table of contents), use the select nodestring button to select the nodestring, and then choose “Assign BC…” This is shown in the image below. To create a new boundary after the mesh has been created, the create nodestring tool ( ) can be used. After a nodestring is created a boundary can be applied to it.

Tute2 038.png

The next step in the modelling process is to assign the model parameters.

Model Parameters

To assign the model parameters access the “Global Parameters” from the TUFLOW FV menu item:

Tute2 039.png

In the general tab, the default options are ok; these should be as per the image below:

Tute2 040.png

In the “Time” tab, set the end time to 48, the model will be 48 hours.

Tute2 041.png

In the output options, set the following parameters.

Tute2 042.png

The HD and Advanced commands can be left unchanged. Hit OK to apply the changes. Once the global parameters are set, we need to set the Manning’s value to be used for the three land use types (sand, gravel and vegetated). To do this select TUFLOW FV >> Material Properties.

Tute2 043.png

For each of the three items listed on the left of the screen set a Manning’s value. Suggested values are in the table below.

Land Use Manning’s n
Gravel 0.035
Sand 0.028
Vegetation 0.06

Tute2 044.png

The model is now ready to run!

Running the Model

Save the SMS project. The TUFLOW FV files will be created in a sub directory in the same location as the SMS project (.sms). To run the model select TUFLOW FV >> Run TUFLOW FV

Tute2 045.png

The following dialogue should be displayed, stating that no model checks have been violated.

Tute2 046.png

Select OK and a console window should be displayed; this will display the location of the inputs and outputs. This step is shown below.

Tute2 047.png

Press any key to begin the conversion press any key. Once the conversion is completed, the console will pause.

Tute2 048.png

In the same directory as the SMS project is saved a TUFLOWFV folder has been created:

Tute2 049.png

In the TUFLOWFV\input\ directory which contains the control file (.fvc). This can be opened in a text editor. The first part of the control file is displayed below.

Tute2 050.png

In the console window, press any key to start the model. If the model starts successfully, the console window should appear as below:

Tute2 051.png

If the model fails to start successfully please see the troubleshooting section below. Depending on computer speed and number of processors available, the model may take a few minutes to finish. Once finished the console should appear as below:

Tute2 052.png

Reviewing Results

The results files for the model simulation should have written to the TUFLOWFV\output\ directory. In the input we asked for two dat output 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.

Tute2 053.png

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:

Tute2 054.png

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

Tute2 055.png

Step through the results in the “Time Steps” window. The contour increment can be changed in the display options. In the Mesh Data there are three scalar dataset 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.

Tute2 056.png

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.

Tute2 057.png

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

Tute2 059.png

After creating the points, select Display >> Plot Wizard.

Select the Time Series plot type.

Tute2 060.png

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

Tute2 061.png

Tute2 062.png

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

Tute2 063.png

When prompted for a format to open the file, select “use import wizard”.

Tute2 064.png

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

Tute2 065.png

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:

Tute2 066.png

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

Tute2 067.png

In the contour options, set the contour range to highlight the cells with small timesteps:

Tute2 068.png

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

Tute2 069.png

Refining the Mesh

In this section we will increase the resolution in the mesh to see how the impacts on the results and runtime of the model. Save the project as RiverBend_Mesh002.sms to avoid overwriting the previous version of the model. Once a new project has been saved, in a shallow area of the model double the resolution in the model, see the image below for a suggested location.

Tute2 070.png

Once the changes have been made to the feature arcs, rebuild the mesh (Feature Objects >> Map to Mesh). Make sure to tick the delete the existing mesh.

Tute2 071.png

An example refined mesh is presented below:

Tute2 072.png

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

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


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