Tutorial Module02 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
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 note. This tutorial has been created using SMS version 12.2.
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 in the tutorial dataset, open the provided bathymetry scatter dataset (RiverBend_Bathymetry.tin) in SMS.
Color it by going to "Display" - "Display Options". 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. Tick "Triangles" in the "Display" - "Display Options" and "Scatter" tab to match the Inset.
Also from the same folder, open the provided landuse dataset (RiverBend_LandUse.map) in SMS.
Color it by going to "Display" - "Display Options". In the "Map" untick "Node" and "Vertex" and tick "Fill" and "Legend".
Click on the "Options..." button next to the "Legend". In the "Font" section click on the displayed text and adjust the font style and size.
The landuse will be displayed as below.
This will import three landuse types for this project: Sand, Gravel and Vegetation. For other models, if you which to create a landuse dataset from scratch:
- Create landuse categories in the Material Data table: "Edit" - "Materials Data"
- Create a Map Data Coverage containing polygons defining the spatial distribution of the landuses. The Map Data should be configured as an area property coverage type ("Type"- "Generic" - "Area Property").
These steps are not required for this tutorial since we are importing a pre-prepared dataset.
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 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 Model (in previous versions of SMS the equivalent option was 2D Mesh Models >> Generic 2D Mesh). Name the coverage “Mesh_Features” and then select OK.
Make sure the newly create “Mesh_Features” layers 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.
Zoom in to the northern boundary of the model, and select the two corner vertices (
). After they are selected, right click and convert these to nodes.
Before
After
Select the feature arc (
) and 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 Convert to Vertex. After doing this, follow the steps that were used for the northern end of the model. 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 redistribute with a specified spacing of 20 (metres). The SMS window should now appear as below.
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. 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 an error about overlapping elements
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 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.
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.
Repeat the process along the channel, an example is shown below.
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 (
) you can drag and drop a box around all polygons. With all the polygons selected, right click and select “Attributes”.
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.
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.
In the boundary condition dialogue, set the boundary type to “Water Level” and the select “Define” (step 2 in the image below).
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.
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.
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 select:
- Mesh and assign attributes
- Linear
- Merge triangle after meshing
- Use area coverage and "Land_Use"
When the linear 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.
When prompted, Call the Mesh Name "RiverBend_Mesh001". This will become the name of our TUFLOW FV model.
After the meshing is completed, turn off the scatter dataset and the map data:
In the display options(
), turn on the Elements, Contours, Nodestrings and Nodestring BC
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.
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.
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:
In the general tab, the default options are ok; these should be as per the image below:
In the “Time” tab, set the end time to 48, the model will be 48 hours.
In the output options, set the following parameters.
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.
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 |
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
The following dialogue should be displayed, stating that no model checks have been violated.
Select OK and a console window should be displayed; this will display the location of the inputs and outputs. This step is shown below.
Press any key to begin the conversion press any key. Once the conversion is completed, the console will pause.
In the same directory as the SMS project is saved a TUFLOWFV folder has been created:
Note: For SMS 12.2 this folder is created in \Tutorial\RiverBend_Mesh001\TUFLOW-FV\RiverBend_Mesh001\TUFLOWFV.
Note: The SMS folder structure will be amended to the current setup soon.
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. Add "Tutorial Model == ON" to the .fvc for licence free modelling.
In the console window, press any key to start the model. If the model starts successfully, the console window should appear as below:
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:
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.
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:
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.
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.
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 slect 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 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.
When prompted for a format to open the file, select “use import wizard”.
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.
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, set the contour range to highlight the cells with small timesteps:
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 the impacts on the results and runtime of the model.
Delete 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.
Once the changes have been made to the feature arcs, rebuild the mesh (Feature Objects >> Map to Mesh).
Call the new mesh "RiverBend_Mesh002".
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 increase?
- 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: