Tutorial M02 SMS Community Draft

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

Using TUFLOW FV this tutorial illustrates to set up and model of a short section of river. This includes running the model, reviewing results and reviewing how refining the mesh influences the results and run times. The steps you learn in this tutorial will help further your modeling skills to develop more complex, real-world models.

Specifically, this tutorial illustrates how to implement the following:

• Set up the TUFLOW FV model, which includes

- Create model folder structure using GIS integration

- Create nodestring and material files using GIS integration

- Create the TUFLOW FV Control file (FVC)

- Setting up the time commands, model parameters, geometry and mesh, material properties, initial conditions, boundary conditions, and output commands.

• Run model and review the mesh performance using the CFL parameter.
• Review results using the QGIS TUFLOW plugin.
• Duplicate the model and run a refined mesh to review the impacts on the runtime.

Requirements And Downloads

Requirement	Brief Description	Download
TUFLOW FV	TUFLOW FV is a 1-dimensional, 2-dimensional, and 3-dimensional flexible mesh finite volume numerical model that simulates hydrodynamic, sediment transport and water quality processes in oceans, coastal waters, estuaries and rivers. It is recommended to always use the latest release version of TUFLOW FV. This tutorial model does not require a TUFLOW FV licence.	TUFLOW FV Latest Release .
SMS TBC [Querry MS Can we remove this as we don't actually use SMS in this tut]	SMS Aquaevo is a system software designed to build and simulate surface water models. The SMS Community Edition has been designed to offer a simple way to set the model geometry and parameters, a licence is not required to use the Community version of SMS. This tutorial was developed using SMS 13.2.0, it recommended to use this version or later versions of SMS. 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.	SMS licence and download information can be found here SMS Aquaveo.
QGIS QGIS TUFLOW plugin	The geographic information system (GIS) used to build models and view results, for this tutorial we will be using QGIS to view results. This tutorial was developed with QGIS 3.28. It is recommended to have QGIS 3.28 or later to ensure compatibility with TUFLOW plugin latest features. The TUFLOW plugin includes numerous tools to increase workflow efficiency.	QGIS can be download from Latest 64-bit version of QGIS. QGIS TUFLOW Plugin Installation.
NotePad++ Syntax Highlighting	A text editor is required for creation of the TUFLOW FV input files. This tutorial was developed with NotePad++. Ideally a text editor should be able to: Colour code the TUFLOW FV control files; Open other files from the active control file; and Launch a TUFLOW FV simulation. TUFLOW colour coding can be enabled using syntax highlighting.	Latest 64-bit version of Notepad++. TUFLOW syntax highlighting for Notepad++. For instructions on configuring Notepad++ for TUFLOW modelling, see Notepad++ tips.
Model Data	The data provided for the completion of this tutorial includes: Two .2dm mesh files provided in the Module_Data folder, Boundary conditions provided as CSV format in the Module_Data folder, Digitised materials provided as a .shp file in the Module_Data folder, The Complete_Model folder has the files for the completed tutorial in case you get stuck, and The working folder for the files you create and work within	TUFLOW FV Tutorial Models.
Assumed Knowledge	It is assumed that you have completed modelling Tutorial M01. We have designed this tutorial to provide an introduction to modelling with TUFLOW FV, if you run into any problems or need help, please contact support@tuflow.com

Model Overview

Tutorial 2 models a short section of a river with varying roughness values assigned throughout the channel and specified boundary conditions. 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 an upstream inflow boundary and a downstream tidal boundary.

Extract And Save The Data Package

Please ensure you have downloaded the Model Data from TUFLOW FV Tutorial Models. Copy and unzip the folder to your preferred working location on your computer, for example C:\TUFLOWFV\Tutorial_M02_SMS_Community\. [REPLY we might need to update the file path depending on what we call the final m data package folder they download]

• The Complete_Mesh folder has the files for the completed tutorial in case you get stuck.

• The Module_Data folder contains the required mesh files to complete this tutorial.
• The working folder is for the files you create and work within.

Project Initilisation

When using GIS integration with TUFLOW FV it is required that all GIS inputs and the mesh are in the same spatial reference system. The need for a singular spatial reference system for all inputs and outputs is required to ensure GIS objects align correctly with the mesh allowing them to be correctly read by TUFLOW FV. For this tutorial we are going to set the spatial reference system to the projected Mercator system WGS 84 / UTM zone 60S. By now you should have downloaded the QGIS program and installed the QGIS TUFLOW Plugin. The QGIS TUFLOW Plugin installation instructions are located here QGIS TUFLOW Plugin Installation. If you have any issues installing the plugin, please contact support@tuflow.com. This tutorial is assisted by the QGIS TUFLOW Plugin.

Please use the following steps to set the spatial reference system and set up the required TUFLOW FV folder structure:

1. Inside the working folder provided in the data package download create a new folder and name it TUFLOWFV
2. Open a QGIS workspace and save it into the working folder please call it Riverine_Channel_000
3. We now need to set our Projects Coordinate Reference System (CRS)

• Please select the Project from drop down menu > Properties and the project Properties dialog will appear
  
• In the dialog on the right-hand pane select CRS
  
• In the Filter search bar please type WGS 84 / UTM zone 60S
  
• Select Apply and then OK
  

4. Using the TUFLOW Plugin select Plugins from the menu bar > TUFLOW > Editing > Configure / Create TUFLOW Project

5. In the Configure TUFLOW Project dialog please specify the following:

A. Set the Projection Description to WGS 84 / UTM zone 60S

B. Set Project Folder Location to the TUFLOWFV folder that you have created in Step 1,

C. Now navigate to the TUFLOWFV.exe that you downloaded earlier. If you have not yet downloaded the TUFLOW FV executable, please refer to the Requirements and Downloads section,

D. Set the GIS format to SHP,

E. Under TUFLOW Engine select TUFLOW Flexible (TUFLOW FV), and

F. Please check the following Save Default Settings Globally (for all projects), Create Model Folder Structure, Create Template Files, Tutorial Model and select OK.

Please navigate to the Project Folder Location, the previous steps will result in following actions:

• Save Default Setting Globally which will allow the TUFLOW FV Plugin to run TUFLOW FV directly from QGIS. This will be saved for all QGIS projects and you will be setup to access tools on the QGIS plugin like ‘import empty layers’, ‘increment layer’ allowing for rapid model development.
• Create Model Folder Structure, this will create the default folder structure for TUFLOW FV as follows

• Create Template Files which will create the projection file .\TUFLOWFV\model\gis\Projection.prj. For interest you can open this file in a text editor and view the long text string containing spatial reference information for our selected system UTM WGS 84 / Zone 60S. Please close this file without making any changes. The QGIS Plugin also creates the FVC file Create_Empties.fvc in the TUFLOWFV\runs folder, which will be run in TUFLOW FV to create empty files in TUFLOWFV\model\gis\empty.

Please review the folder and associated files that have been written to the ‘Empty’ template files folder: TUFLOWFV\model\gis\empty\. We will use these empty files as the basis for developing the materials, boundary locations, nodestrings and mesh topographic updates. Each empty file has been set with the projection UTM WGS / Zone 60S and has been populated with a series of attribute types that will allow us flexibility over how we assign components to our model.

Applying Materials

Now that we have set up our project, we are ready to build our Materials layers. To reduce the amount of digitising required in this tutorial we have provided the material file in the Module_Data folder. However, we will step through how to specify the different material types within material file. In this tutorial we will apply three material types to our model:

1. Gravel represented by a Mannings roughness value of 0.028, 2. Sand represented by a Mannings roughness value of 0.035, 3. Vegetation represented by a Mannings roughness value of 0.06.

To start please copy 2d_mat_Riverine_Channel_000_R.shp and all supporting files from the Module_Data folder into the \working\TUFLOWFV\model\gis folder.

Please use the following steps to assign your material IDs.

1. Open the 2d_mat_Riverine_Channel_000_R.shp into your QGIS workspace by selecting the Layer from the drop down and Data Source Manager. In the Data Source Manager dialog please select Vector on the righthand panel and in the Source Vector Datasets(s) navigate to the recently copied 2d_mat_Riverine_Channel_000_R.shp file, select Open > Add.
2. Select the 2d_mat_Riverine_Channel_000_R layer in the layers panel and click the Toggle Editing button on the digitizing tab.
3. Now using the Identify Features tool select the polygon identified as gravel in the above figure

3.1 Select Edit Feature form

3.2 In the new dialog box please update the Material to 1

4. Undertake the same steps for Sand applying a Material ID as 2
5. For the Vegetation Material ID the left and right bank will need to be assigned separately with a Material ID of 3
6. Once completed please click the Toggle Editing button on the digitizing tab and save changes.

Nice work, we will later step through how we define the roughness values for each material type in the TUFLOW FV control file in FVC File Contents section.

Applying Nodestrings

TUFLOW FV uses nodestrings to read the boundary conditions specified by the modeler. For this tutorial model we will create our nodestring using the GIS shapefile format. Unlike our materials file the nodestring shapefile has not been provided in Module_data, however, we can use our empty files that we made earlier to create our nodestring shapefile. These files are specifically generated to be read in by TUFLOW FV. Please use the following section to create the nodestrings required for this model.

To import your empty file into the workspace, select Import Empty File tool in the TULFOW tool bar and the dialog will appear. Please use the following steps to create your nodestring file
1. In the Empty Directory navigate to the empty folder your created in section .\working\TUFLOWFV\model\gis\empty
2. Under the Empty Type select 2d_ns
3. In Run Id please adopt the name Riverine_Channel_000
4. Check Lines in the Geometry Type
5. Select OK

Your new 2d_ns_Rivereine_Channel_000 layer will appear in the QGIS layer pane and will now be saved into the \TUFLOWFV\model\gis folder

Now we need to digitise our nodestrings and set specify the ID and type. Please use the following steps:
1. Select the 2d_ns_Riverine_Channel_000_L layer in the layers panel and click the Toggle Editing button on the digitizing tab.
2. Then using the Add Line Feature tool digitise a line at the upstream boundary of the model domain. Use the material layer to help you identify where the nodestring should be place. Note the Node string should be offset from the polygon as shown in the below figure.

Use the below figure to help you digitse your nodestring

3. Now the attribute dialog box will appear. Please specify the ID as 1 and Flags as BD

4. Repeat the process at the downstream boundary, this time setting set the ID as 2 and Flags as BD.
5. Once completed please click the Toggle Editing button on the digitizing tab and save changes.

Note: The ID number is used in TUFLOW FV control file to identify the nodestring and the type BD will use TUFLOW FV’s boundary algorithms to snap the nodestring along the outer edge of the model, as required for open boundary conditions.

TUFLOW FV Model Setup

Once ready, make a copy of Create_Empties.fvc file in the TUFLOWFV\runs folder and name it Riverine_Channel_000.fvc and open this file in Notepad++. This will only contain the commands to define the GIS format and model projection. We will edit this file to create a new run file.

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. The nodestrings you created in the previous section will be used to apply these boundary condtions.

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

In your Riverine_Channel_000.fvc comment out the last command since we don’t need to generate empty files again.

GIS FORMAT  == SHP
SHP Projection  == ..\model\gis\projection.prj
Tutorial Model  == ON
!Write Empty GIS Files == ..\model\gis\empty

FVC File Contents

To simplify this example only those lines that are relevant to this simulation are shown in the fvc file. Use the table to create your fvc file. A description of each entry is provided.

! 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
GIS FORMAT == SHP	Specifies the GIS file formats read into the model
SHP Projection == ..\model\gis\projection.prj	Provides the projection of the GIS files
Tutorial Model == ON	Enables licence free modelling.
! SIMULATION CONFIGURATION	Here we specify the Mannings bed roughness model
Bottom Drag Model == Manning
! 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 == 48
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. Here we read the nodestring GIS file we made early into TUFLOW FV model. We need to set the material ID globally first, and then read the material GIS file into the TUFLOW FV model.
Geometry 2d == ..\model\geo\Riverine_Channel_000.2dm
Read GIS Nodestring == ..\model\gis\2d_ns_Riverine_Channel_000_L.shp
Set Mat == 1
Read GIS Mat == ..\model\gis\2d_mat_Riverine_Channel_000_R.shp
! MATERIAL PROPERTIES	The following roughness values have been suggested for Gravel (1), Sand (2), and Vegetation (3).
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
! 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 netcdf format file is specified. This format is easily viewed in QGIS via the TUFLOW Plugin. The h, v and d mean that result files containing water level, velocity and water depth will be created.
Output dir == ..\results\
Output == netcdf
Output Parameters == h,v,d
Output Interval == 900
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 The TUFLOW FV Log File

TBD ask MS

Reviewing 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 Riverine_Channel_000.nc. The netcdf result files produced by TUFLOW FV are best viewed using the TUFLOW Viewer in QGIS. For instructions on how download the plugin please visit TUFLOW Viewer plugin. Note the following steps and screen shots were undertaken in QGIS version 3.26.

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 two plots: (1) a long section of water level and bed elevation and (2) a time series of the velocity with vectors on.

(1) Zoom into a section of channel. 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:

Now drag the timeseries to observe how the water surface elevation changes throughout the simulation.

(2) Zoom into another section of channel. 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

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

Please use the following steps to open the csv file

1. Select the Layer dropdown and click Data Source Manager
2. On the left panel of the Data Source Dialog box select Delimited Text
3. Under file name navigate to TUFLOWFV\input\log\ and select Riverine_Channel_000_ext_cfl_dt.csv
4. Make sure the File Format is set to CSV (comma separated values)
5. Check First Record has field names and detect field types
6. Set X field to x_ctrd, Y field to y_ctrd, and z field to cfl_dt_min
7. Select Add

Now we have Riverine_Channel_000_ext_cfl_dt.csv displayed as points we will change the symbology so that we can review CFL values throughout the model. To do this right click on Riverine_Channel_000_ext_cfl_dt in the Layers panel and select Properties... and set the following

1. In the layer properties dialog box select Symbology.
2. Set the symbol display to Graduated.
3. Set the display Value to cfl_dt_min
4. Select an appropriate Color ramp from the drop down menu

5. Specify 10 Classes
6. Set classification Mode to Equal Count (Quantile)
7. Select Apply and OK

You should now be able to see how the cfl changes within the model

MB TBC say something smart about looking for low cfl as this will demonstrate which cells are limiting the model time step.

Refining The Mesh

To demonstrate how refining a model mesh influences the model timestep we have provided a second mesh Riverine_Channel_001.2dm in the Module_Data folder. In this mesh we have increased and decreased the cell size in two sections of the channel ,shown in the below figures.

You can visualise this for yourself by dragging and dropping the Riverine_Channel_001.2dm file into your QGIS workspace.

Now we will set up a second FVC file to run the refined mesh. Please follow the below instructions:

1. Make a copy of the Riverine_Channel_000.fvc and name it Riverine_Channel_001.fvc

2. Open Riverine_Channel_001.fvc in your text editor and update the .2dm in the geometry block to Riverine_Channel_001.2dm and Save.

Run TUFLOW FV

Once you have updated the fvc file contents as described above, 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 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 The Mesh Refinement

[Querry MS- can you review and add some smart stuff here]

To review how the mesh cell size and shape influences the model CFL please review Riverine_Channel_001_ext_cfl_dt.csv. To do this please use the same steps outline in section Reviewing Mesh Performance.

• How has the model CFL changed in areas where the mesh was resolution was changed?
• Dosmaller or large cells have a higher CFL?
• 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:

• Common reasons why a model won’t start
• [[A Model Crashes|Common reasons why a model crashes]

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. If you have any further queries, feedback or requests for new functionality please feel free to get in contact with support@tuflow.com.