Tutorial M02 SMS Interface

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 Module 2 and the Tutorial Module 1 - SMS Interface by introducing the concepts of spatially varying materials and mesh efficiency testing.:

Specifically, this tutorial demonstrates:

• Defining boundary conditions.
• Defining spatially varying landcover via a material coverage.
• Creating a TUFLOW FV simulation.
• Setting up model control components such as: time commands, model parameters, geometry and mesh, material properties, initial conditions, boundary conditions, and output commands.
• Running the model and reviewing mesh performance.
• Importing and reviewing results.

The workflow is undertaken in Aquaveo SMS and utilises the TUFLOW FV interface developed by Aquaveo. (MITCH TO DO pls check you're happy with how I refer to SMS)

Example: Modeled riverine channel depth result

Requirements And Downloads

Requirement	Brief Description	Download
TUFLOW FV	TUFLOW FV is a one-dimensional, two-dimensional, and three-dimensional flexible mesh finite volume numerical model that simulates hydrodynamic, sediment transport and water quality processes in oceans, coastal waters, estuaries and rivers. Please download the latest TUFLOW FV release. This tutorial model does not require a TUFLOW FV license.	TUFLOW FV Latest Release .
SMS	Aquaveo SMS is designed to build, simulate and review surface water models. The TUFLOW FV Interface within SMS has been designed to offer a simple way to set the model geometry and parameters. An SMS licence is required to use the interface. To complete this tutorial please download an evaluation license of SMS via https://evaluate.aquaveo.com/. 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.	SMS download information can be found here SMS Aquaveo. To use the TUFLOW FV Interface for SMS please apply for an evaluation license via Aqauveo.
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 .map file in the Module_Data folder. The Complete_Model folder has the files for the completed tutorial in case you get stuck. The Working folder to build and run the model within.	TUFLOW FV Tutorial Models.
Assumed Knowledge	There are no prerequisites for this tutorial however it is recommended (but not essential) to: Complete or review the Riverine Channel Meshing Tutorial. (MITCH TODO, update meshing links) Complete or review Tutorial Module 01 using the TUFLOW FV SMS Interface. Review the TUFLOW FV Interface Parameters page by Aquaveo.	Not Applicable.

Prepare Your Working Environment

Install SMS

If you haven't yet installed SMS as part of a previous tutorial, download the latest release of SMS from the SMS downloads page. Once downloaded run the setup executable and follow the prompts. If you need further guidance on installation, use the Introduction to Setting up SMS help page or you can contact the SMS help team via the Help Menu.  

Extract And Save The Data Package

Ensure you have downloaded the Model Data from TUFLOW FV Tutorial Models. Copy and unzip the folder to your preferred working location, for example E:\TUFLOWFV\Tutorial_M02_SMS_Interface.

• The Complete_Model folder contains a completed version of the tutorial and its supporting files. You can use this as a reference if you require.

• The Module_Data folder contains the required mesh files to complete this tutorial.
• The Working directory is where you will create your SMS project and model.

Setup SMS Project

Before we start modelling, we'll setup our working projection and save a new SMS project. Launch SMS and your workspace will be as shown below:

Setting The Workspace Projection

Set the projection by navigating to Display > Display Projection....

In the Display Projection dialogue box set Global projection and click Set Projection.

Using Filter Strings: search WGS 84 UTM zone 60s and select WGS 84 UTM zone 60 > OK > OK.

Saving The Workspace

Save the empty project from the menu bar by selecting File > Save As....

Navigate to your Working folder and save the project as Riverine_Channel_000.sms.

Creating A Simulation

To create a new TUFLOW FV simulation right click on Project > New Simulation > TUFLOWFV.

A new simulation should appear in the project window. Use the below steps to set up the simulation:

• Rename the simulation Riverine_Channel_000 by right clicking on Sim > Rename.

• Right click on the simulation and select save simulation: Riverine_Channel_000 > Save Simulation.

This will generate the TUFLOW FV model folder structure located at: Working\Riverine_Channel_000_models\TUFLOWFV.

You should have the following TUFLOW FV model folder structure:

Applying The Model Geometry

From the SMS menu bar select File > Open... and navigate to the mesh file Module_Data\Riverine_Channel_000.2dm. Select TUFLOWFV Geometry Files (*2dm) as shown below:

To visualise the mesh bathymetry select Display > Display Options. In the 2D Mesh options tick Contours.

Select the Contours tab and under the Contour method select Color Fill and click Color Ramp.... In the Color Options under the Palette Preview option click Reverse. Now select OK > OK.

Your mesh will look similar to the below:

Apply the mesh to the simulation by right clicking on Riverine_Channel_000 > Apply to > TUFLOWFV Simulations->Riverine_Channel_000 as follows:

Save the simulation again Riverine_Channel_000 > Save Simulation. Navigate to the TUFLOWFV\model\geo folder and you will see that your .2dm file has been saved into the geo folder.

Assigning Materials And Bed Roughness

Next we will specify our spatially varying materials layer. To reduce the amount of digitising required in this tutorial we have provided the material file in the Module_Data folder.

In this tutorial we will apply three material types to our model:

1. Gravel represented by a Manning's 'n' roughness value of 0.028.
2. Sand represented by a Manning's 'n' roughness value of 0.035.
3. Vegetation represented by a Manning's 'n' roughness value of 0.06.

Firstly open the materials file provided in Module_Data\RiverBend_LandUse.map. Note the colour display of the varying materials will be different to the above figure.

We won't need the Riverine_Channel_000-Materials coverage. Right click on the coverage and select Delete:

Change the map file type to be compatible with TUFLOW FV by right clicking on Land_Use and select Type > Models > TUFLOWFV > Materials.

Use the following steps to specify the Manning's 'n' roughness value for each material:

1. Select the Land_Use coverage to make it active. Use the Select Feature Polygon tool to select the gravel polygon then right click and select Assign Material:

The Assign Material dialog will appear.

Use the following steps and figure to assign a Manning's 'n' roughness for gravel:

A. Select Add Material the green cross.

B. Change the Color and Texture of the material to represent gravel.

C. Rename the material Gravel.

D. Check Override Bottom Roughness.

E. Apply a Bottom Roughness value of 0.028.

F. Under the TUFLOW Simulation export file Format dropdown select Shapefile.

G. Select the row so that the new material is highlighted.

H. Select OK.

2. Use the Feature Polygon tool to select the sand polygon then right click and select Assign Material:

Use the following steps and figure to assign a Manning's 'n' roughness for sand:

A. Select Add Material the green cross.

B. Change the Color and Texture of the material to represent gravel.

C. Rename the material Sand.

D. Check Override Bottom Roughness.

E. Apply a Bottom Roughness value of 0.035.

F. Under the TUFLOW Simulation export file Format dropdown select Shapefile.

G. Select the row so that the new material is highlighted.

H. Select OK.

3. Using the Select Feature Polygon hold Shift and select both vegetation polygons. Right click and select Assign Material:

This time the dialog box should display Material assignment will be applied to all selected polygons, this indicates that you have selected both polygons.

Use the following steps and figure to assign a Manning's 'n' roughness for vegetation:

A. Select Add Material the green cross.

B. Change the Color and Texture of the material to represent gravel.

C. Rename the material Vegetation.

D. Check Override Bottom Roughness.

E. Apply a Bottom Roughness value of 0.06.

F. Under the TUFLOW Simulation export file Format dropdown select Shapefile.

G. Select the row so that the new material is highlighted.

H. Select OK.

4. Apply the materials to the simulation by right clicking on Land_Use and select Apply to > TUFLOWFV Simulations->Riverine_Channel_000 as follows:

Your simulation should now contain the Land_Use material file:

Save your work by right clicking on the simulation and selecting Save Simulation.

Navigate to the TUFLOWFV\model\gis folder and you will see that the .shp file has been saved into the gis folder.

Adding Boundary Conditions

When using the SMS TUFLOW FV interface, a Feature Arc can be used to define the location of boundary condition inflows/outflows. For this example, there is an upstream and a downstream boundary condition applied (see figure below). In this section you will learn to digitise Feature Arcs which are used to apply the boundary conditions to the model.

To make a TUFLOW FV boundary conditions coverage type right click on Map Data > New Coverage.

The New Coverage dialog box will appear, select: Models > TUFLOWFV > Boundary Conditions.

Use the below steps and animation to digitise the inflow boundary and apply the the flow data:

1. Select the Boundary Conditions to make the map data active.
2. Using the Create Feature Arc tool digitise a line at the upstream end of the mesh. Note that we do not snap our boundary condition to the model mesh.
3. Using the Select Feature Arc tool please select and right click on the arc > Assign BC.
4. The Assign Boundary Conditions dialog will appear. From the BC Types drop down, select Q (Nodestring Flow). Change the subtype to Sub-type 3, this applies the boundary as a flux with a consideration of the depth when distributing flow. Now select Define Cure....
5. In the BC Curve Editor dialog select Import... and navigate to the Flows.csv in the Module_Data folder. You should now see the inflow curve. Select OK.

6. Now Select the Export format tab and from the TUFLOWFV simulation export file format drop down select Shapefile. Select OK to apply the flow boundary .

Use the below steps and animation to digitise the WL boundary and apply the the tide data:

1. Select the Boundary Conditions to make the map data active.
2. Using the Create Feature Arc tool digitise a line at the downstream end of the mesh. Note that we do not need to snap our boundary condition to the model mesh.
3. Using the Select Feature Arc tool please select and right click on the arc > Assign BC.
4. The Assign Boundary Conditions dialog will appear. From the BC Types drop down select WL (Water Level). This time leave the subtype as Sub-type 1 and select Define Cure....
5. In the BC Curve Editor dialog select Import... and navigate to the tide.csv in the Module_Data folder. You should now see in the tidal signal being read into the model. Select OK.

6. Now Select the Export format tab and from the TUFLOWFV simulation export file format drop down select Shapefile. Select OK to apply the WL boundary.

Now apply our Boundary Conditions to the TUFLOW FV simulation by right clicking on Boundary Conditions > Apply to > TUFLOWFV Simulations->Riverine_Channel_000

Save your work by right clicking on the simulation and selecting Save Simulation. For your reference, the interface will automatically save the .shp files into TUFLOWFV\model\gis folder and the water level and flow boundary conditions .csv files into TUFLOWFV\bc_dbase.

TUFLOW FV Model Setup

Now that we have our mesh, materials, and boundary conditions in the simulation we are ready to configure the TUFLOW FV Control file (.fvc file extension type). To configure the FVC with the TUFLOWFV interface right click on your simulation Riverine_Channel_000 and select Model Control:

The TUFLOW FV Model Control dialog box should now appear as below. Highlighted in the green are the different tabs where we can specify TUFLOW FV parameters and inputs. Under the General tab please check Tutorial model. This will enable TUFLOW FV to be run license free.

Now under the Time tab we will update the start and end time of our simulation and specify the model time step limit:

1. The time commands include the start and end times (the default time format is Hours). Please set the Starting time (h) to 0 and the Ending time (h) to 42.0.

2. The Courant–Friedrichs–Lewy (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. Please set the CFL to 0.9 and the Min time step (s) to 0.01 and Max time step (s) 10.0.

Under the Global parameters tab we will set the Horizontal mixing model and Define stability limits. 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. A Smagorinsky eddy viscosity approach has been specified for this model.

1. For the Horizontal mixing model please select Smagorinsky from the drop down and set the following:

• Set Global horizontal eddy viscosity coefficient to 0.5.
• Check Define global horizontal eddy viscosity limits, setting the Minimum eddy viscocity (m2/s) to 0.05 and Maximum eddy viscosity (m2/s) to 99999.

2. Please check Define stability limits and set the Maximum water level (m) to 100.0 and Maximum velocity (m/s) to 10.0.

Under the Initial conditions tab we will define the initial water level. To do this please check Define initial water level (m) and set it to 0.0 m consistent with our downstream boundary condition water level at the model start time.

Under the Output tab we can specify which results we want the model to output and what file format we would like our results in. In this instance, a DATV format file is specified, this format is easily read into SMS for viewing and we will specify the water level, velocity and water depth results to be created. To do this please undertake the following:

1. In the Output block we will select the Add row button.

2. Now in the new drop down please make sure that the DATV format file is specified.

3. In the Output block options - Row 1 please check Define Interval and we will specify our Output interval (s) to 900.0.

4. Now we will define the results we would like the model to write, in Datasets please check Water depth (m), Water surface elevation (m), Velocity vector and magnitude (m/s), and Velocity magnitude only (m/s).

5. Lastly, we will need to specify where we want the results to be written to, in Directories please specify the Output directory as ..\results.

Under the Materials tab please check that the correct materials is being applied to the simulation by selecting Land_Use in the Linked coverage window and leave everything as default.

Under the Boundary conditions tab please check that the boundary conditions you applied to the simulation are being refenced in the Linked coverage window and leave everything as default.

We have now set all the required parameters and input required for our model please select OK and in the project window right click on your simulation Riverine_Channel_000 and Save Simulation.

You will now have a TUFLOW FV control file named Riverine_Channel_000.fvc in the Working\TUFLOWFV\runs folder. You can open this a in a text editor to see the different commands and parameters you have set.

Run TUFLOW FV

Ensure you have downloaded the TUFLOW FV executable from here and unzip the folder to your preferred location, for example: E:\TUFLOWFV\TUFLOW_FV_Windows\2023.1.1. Now use the following steps to run your model:

1. Check that SMS is using the correct TUFLOW FV executable by selecting Edit > Preferences:

2. Select the File Locations tab and under Model Executables select TUFLOW FV. Navigate to your downloaded TUFLOWFV.exe and select OK.

3. To run the model right click on the simulation Riverine_Channel_000 and select Run Simulation:

The Simulation Run Queue should appear. You will notice the command window will show TUFLOW FV processing. Once the simulation is complete the Command line will show Run Successful.

Reviewing Results

Map Output Results

During the model simulation the result files will be written to the TUFLOWFV\results\ folder. They will have the same prefix as the fvc file; in this example they will be called:

• Riverine_Channel_000_H.dat
• Riverine_Channel_000_V.dat
• Riverine_Channel_000_VMAG.dat
• Riverine_Channel_000_D.dat

To view the results please select Load Solution. If you have already closed this window, simply right click on the Riverine_Channel_000 simulation and select Read Solution.

Your workspace should now look similar to the below. Step through the timesteps for each result in the bottom left corner to see how the results change over the simulation.

To add the velocity vectors select Display > Display Options from the menu bar. In the Display Options under the 2D Mesh tab check Contours and Vectors and uncheck everything else:

Note you can modify the vector display options under the Vectors tab.

Zoom into a section of the channel and step through the timesteps to view how the velocity vectors change throughout the model simulation:

Extracting Long Sections And Time Series

In this section we will use the visualise the results in two plots: a long section profile of water level and bed elevation and a time series of the velocity. Return the Time Step to 0 00:00:00.

To extract a timeseries or longitudinal profile from the results we first need to create an Observation Coverage in the Map Data. To do this please right click on the Map Data and select New Coverage, now select Observation as the new coverage type and OK:

The first plot we will produce is a long section profile of the water level result and bed elevation after 24 hours of simulation.

Select the Observation coverage you have made. Using the Create feature arc tool digitise a feature arc from the upstream to downstream boundary roughly in the center of the channel. Use the below figure for guidance:

From the tool bar menu select Display > Plot Wizard.

The Plot Wizard - Step 1 of 2 dialog box will appear. Use the following steps to plot your profile:

1. Select Observation Profile > Next in the Plot Wizard Step 1 of 2 window.

2. Select Next and the Plot Wizard Step 2 of 2 window will appear.

3. Under Coverage check Arc 1. This the feature arc you just created.

4. Under DatatSet(s) options select Specified.

5. Check Riverine_Channel_000 Z for the elevation data and Riverine_Channel_000_H for the water level result.

6. Under the Time step(s) options select Specified.

7. Under timeseries scroll down and Check the timestep 1 00:00:00.

8. Select Finish.

Add a legend to your plot right click on the plot area select Legend > Bottom. Your water level and elevation profiles should look similar to the below plot:

Now we will create a timeseries plot of the velocity output.

Select the Observation coverage you have made earlier and delete the feature arc. Use the Create feature point tool to digitise a point near the downstream boundary, as shown below:

From the tool bar menu select Display > Plot Wizard. The Plot Wizard - Step 1 of 2 dialog box will appear. Use the following steps to plot your timeseries:

1. Select Time Series in the Plot Wizard Step 1 of 2 window.

2. Select Next and the Plot Wizard Step 2 of 2 window will appear.

3. Under Points check Point 1. This the feature point you just created.

4. Select Use selected datasets.

5. Check the Riverine_Channel_000_VMAG result.

6. Now select Finish.

Your velocity timeseries The plot should look similar to the below:

A neat way to visualise how your velocity changes in space is to move your feature point. To do this by leave your timeseries plot open and using the Select Objects (or select feature tool) move the point upstream. Please use the below animation as a guide:

Reviewing Mesh Performance

In this section we will review the run time performance of our mesh. TUFLOW FV uses an adaptive timestep which is based on the specified Courant-Friedrichs-Lewy condition (CFL parameter). For hydraulic models the model timestep is calculated based on the cell size, it's shape, the water depth and the velocity of flow. If a mesh is poorly configured there can be individual outlier cells that can unnecessary slow down the model. Therefore, after running the model it is beneficial to review the timestep diagnostics produced by TUFLOW FV.

Select select File > Open and navigate to TUFLOWFV\runs\log\Riverine_Channel_000_ext_cfl_dt.csv file. Note that this file will only be created after the successful completion of a model run.

Using the File Import Wizard - Step 1 of 2 specify the File import options as Delimited, and Set the column delimeters to Comma. Click Next.

The File Import Wizard - Step 2 of 2 dialog will now appear. Turn off the triangulate data, and using the dropboxes: set the id to be mapped as Pt Name, 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. Click Finish.

Your window should look similar to the below:

Use the display settings to visualise how the CFL varies spatially. Select Display Options from the toolbar. Ensure Scatter is selected and from the dialog box check Points and Use contour color scheme. Leave everything else unchecked and select the Contours tab.

In the Contours options set the following:

1. Under Contour method select Color Fill and Use color ramp.

2. Under Data range check Specify a range: set the Min as 0.1 and Max as 0.8 then make sure the Fill Below options are both unchecked.

3. Under Contour interval set as Specified Interval and set the interval to 0.1.

4. Select OK.

Turn on your mesh with the elements visible. 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 on the banks 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.

To improve your skills as a modeler it is highly recommended that you understand the computational effort required to run a TUFLOW FV model detailed here.

Feedback

If you have any queries, feedback or requests for new functionality you would like added to the tutorial modules, please feel free to get in contact with support@tuflow.com.

If you wish to keep up-to-date with all things TUFLOW and TUFLOW FV, then please join our LinkedIn group.

Conclusion and Next Steps

Well done on completing Tutorial Module 02 integrating the SMS Interface. You have now learnt how to build, run and take introductory steps to review a model and model results.

To go further, please choose from one of the following three options:

1. Build upon your modelling skills by modelling a (MITCH TO DO THIS would be Cudgen. We need to add a link -TBD)
2. Head back to the Tutorial Module Introduction Landing Page to try other tutorials.
3. Return to the TUFLOW FV Wiki Mainpage.