Tutorial Module01 SMSComEd
| 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
This tutorial builds upon the Meshing tutorial with Aquaveo SMS Community Edition [TBC name hyperlink]. Specifically, you will learn how to create and run a TUFLOW FV model and visualise your results. For this workflow, we will be using the QGIS TUFLOW Viewer to visuliase the results. Follow the steps performed here and expand upon them to develop more complex, real-world models.
This tutorial requires the mesh file Trap_Channel_000.2dm created in [TBC Hyperlink tut]. Please complete the meshing tutorial [TBC HYPERLINK] before proceeding or alternatively you may adopt the mesh file provided in module data download from [TBC HYPERLINK].
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.
Tutorial Data
Download the Tutorial Module 01 GIS [TBC link] Mesher dataset from the TUFLOW Website.
The folders provided in this tutorial include Module_Data, Complete_Model, and working. Copy these folders to where you would like to work with the project.
- The Module_Data folder contains the .2dm mesh file for those that have not completed tutorial [TBC hyperlink]
- The Complete_Model folder has the files for the completed tutorial in case you get stuck
- The working folder is for the files you create and work within
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 [TBC folder path] folder.
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
Model Mesh
If you have completed tutorial [TBC HYPERKINK] please copy your .2dm file Trap_Channel_000.2dm to ./TUFLOWFV/model/geo. Alternatively, please copy the Trap_Channel_000.2dm from the Module_Data folder into ./TUFLOWFV/model/geo.
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:
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.5.
|
| Stability limits == 10. ,100. | |
| 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_Channel_000.2dm | |
| ! MATERIAL PROPERTIES | So far, material types haven’t been highlighted. By default, the GIS Mesher GUI 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 NETCDF format file is specified. This format is easily read into the TUFLOW Viewer for viewing results in QGIS. The h, v and d mean that outputs files containing water level, velocity and water depth will be created. We also use Logdir which specifies the directory for TUFLOW FV simulation log file. |
| Logdir == ..\runs\log | |
| Output dir == ..\results\ | |
| Output == netcdf | |
| Output Parameters == h,v,d | |
| Output Interval == 600 | |
| End output |
Note for more information and instructions on the TUFLOW Viewer QGIS plugin please visit TUFLOW Viewer
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
During the model simulation one result .nc file will be written. This netcdf file contains water levels velocities and water depths. The file will have the same prefix as the fvc file; in this example it will be called trap_steady_01.nc. The netcdf result files produced by TUFLOW FV are best viewed using the TUFLOW Viewer in QGIS. For instructions on how download the TUFLOW Viewer plugin please visit | https://wiki.tuflow.com/index.php?title=TUFLOW_Viewer. Note the following steps and screen shots were undertaken in QGIS version 3.26.2
Once you have installed the plugin please click the TUFLOW Viewer button 
. The Tuflow View will appear as below. To open your results please select File>Load Results-Map Output and navigate to your result.
Your QGIS project window should look similar to the below:
In this section we will use the the TUFLOW Viewer to visualise the results in three plots: (1) a long section of water level and bed elevation and (2) a time series of the velocity with vectors on.
(1) To display a long section of the water level and bed elevation follow the below steps:
- 1. Display the mesh by selecting the Toggle Mesh Rendering
- 2. Select the Plot cross drop down
- 3. In the drop down check bed elevation
- 4. In the drop down check water surface elevation
To draw the long section please select the 
and your cursor should now become a crosshair [+]. Now you are ready to plot your long section. See the long section example below:
(2) To display a timeseries of the velocity and velocity vectors follow the below steps:
- 1. Display the mesh by selecting the Toggle Mesh Rendering
- 2. In the Result Type window select velocity and velocity vector map outputs
- 3. Now increase the time stamp see how the velocity vectors change throughout the model simulation
- 4. Select the Plot Time Series drop down
and in the drop down check velocity - 5. To draw the long section please select the and your cursor should now become a crosshair [+]. Click on your results to view a time series similar to the below:
For more examples on how to review your results using the Qgis TUFLOW Viewer plugin visit TUFLOW Viewer
Inclusion of Salinity
It is relatively straightforward to include a conservative tracer into the model simulation.
Save a copy of Trap_Steady_01.fvc and name it Trap_Steady_02.fvc 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 modelled with salinity | |
| 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.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_Channel_000.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.
|
| BC == Q, 1, ..\bc_dbase\steadyQ_02.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 == netcdf | |
| 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 |
Run TUFLOW FV
Once you’re happy with the fvc file contents, run TUFLOW FV with your batch file. Refer to the following link for simulation run options: Running TUFLOW FV.
Remember to run your new FVC trap_steady_02.fvc
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.
View Results
Open the trap_steady_02.nc using the TUFLOW Viewer in QGIS [TBC reference previous section on reviewing results]. For instructions on how download the TUFLOW Viewer plugin please visit | https://wiki.tuflow.com/index.php?title=TUFLOW_Viewer and for a detailed description on how to use the Tuflow Viewer to view your results please refer to section XX [TBC link to]
Take a timeseries of the Salinity output. Your result should look something similar to the following:
Congratulations you have successfully built and run a TUFLOW FV model.
Going Further
Model Topography Modification
In the previous Meshing Tutorial XX [HYPERLINK TBC] Section XX [HYPERLINK TBC] we modified the trapezoidal channel to include a bump in the channel bed and a downstream channel constriction, see below example. If you have not completed Meshing Tutorial XX [HYPERLINK TBC] we have provided the mesh file Trap_Channel_001.2dm in Module_Data folder.
File:Tut 01Modified Mesh 00.png
Please copy the Trap_Channel_001.2dm you created in tutorial XX [HYPERLINK TBC] or from the Moule_Data folder and paste it into working\TUFLOWFV\model\geo\
FVC File Updates
Save a copy of Trap_Steady_02.fvc and name it Trap_Steady_03.fvc The following additional components listed in the right-hand column of the table below are required within the FVC file:
| ! 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 modelled with salinity and a modified mesh. | |
| Tutorial Model == ON | |
| ! SIMULATION CONFIGURATION | |
| Include salinity == 1,0 | |
| ! TIME COMMANDS | |
| Start time == 0.0 | |
| End time == 6.0 | |
| CFL == 1.0 | |
| Timestep limits == 0.0001, 10. | |
| ! MODEL PARAMETERS | |
| Stability limits == 10. ,100. | |
| 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 | The model geometry is the 2dm created above in this tutorial module. Please use the new mesh Trap_Channel_001.2dm |
| Geometry 2d == ..\model\geo\Trap_Channel_001.2dm | |
| ! MATERIAL PROPERTIES | |
| Material == 1 | |
| Bottom roughness == 0.018 | |
| End material | |
| ! INITIAL CONDITIONS | |
| Initial water level == -3.5 | |
| Initial Salinity == 0 | |
| ! BOUNDARY CONDITIONS | |
| BC == Q, 1, ..\bc_dbase\steadyQ_02.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 | |
| Output dir == ..\results\ | |
| Output == netcdf | |
| 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.
Run TUFLOW FV
Once you’re happy with the fvc file contents, run TUFLOW FV with your batch file. Refer to the following link for simulation run options: Running TUFLOW FV.
Remember to run your new FVC trap_steady_03.fvc
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
Open the trap_steady_03.nc using the TUFLOW Viewer in QGIS [TBC reference previous section on reviewing results] for a detailed description on how to use the Tuflow Viewer to view your results please refer to section XX [TBC link to]
Your QGIS project window should look similar to the below:
In this section we will use the TUFLOW Viewer to visualise the long section of the velocity with vectors on. For a detailed description on how to use the Tuflow Viewer to view your results please refer to section XX [TBC link to]
How has the inclusion of a bump and constriction in your mesh changed the velocity in the channel?
Now open your previous result Trap_Steady_02.nc and compare to your results. Can you see how changing the mesh has altered your results?
Model Resolution Update TBC Check with Mitch
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.
Conclusion
Congratulations on completing Tutorial 1 with the Aquaveo SMS Community Edition. We've covered a lot in this tutorial including introduction to modelling with TUWFLOW FV, development of a TUFLOW FV model, how to run your model, check the results using the TUFLOW Viewer in QGIS and reviewed how mesh changes influence your model 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