Tutorial M01 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 Trapezoidal Channel Meshing Tutorial. Here we will guide you step-by-step on how to create, run and review a TUFLOW FV model completely within the SMS TUFLOW FV interface. The steps you learn will help further your modeling skills to develop more complex, real-world models.

Specifically this tutorial demonstrates:

• Creating a TUFLOW FV simulation.
• Defining boundary conditions and material specifications.
• Setting up model control components such as: time commands, model parameters, geometry and mesh, material properties, initial conditions, boundary conditions, and output commands.
• Exporting the model including the automated writing of the TUFLOW FV Control File (FVC).

• Running the model.
• Importing and reviewing results.

The below image shows depth and velocity results from the model we will build.

Example: Trapezoidal channel depth and velocity vector results

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 with TUFLOW FV Interface	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 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 Aquaveo.
Model Data	The data provided for the completion of this tutorial includes: The .2dm mesh files provided in the Module_Data folder. Boundary conditions provided as CSV format in the Module_Data folder. The Complete_Model folder has the files for the completed tutorial in case you get stuck. A Working folder where you will create your model files and run your model.	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 Trapezoidal Channel Meshing Tutorial. 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_M01_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 trap_steady_000.sms.

Creating A Simulation

Create a new TUFLOW FV simulation by selecting Project > New Simulation > TUFLOWFV:

A new simulation will appear in the project window:

Rename the Sim Trap_Steady_000 by right clicking on Sim > Rename:

Applying The Model Geometry

The model mesh was previously created in the Trapezoidal Channel Meshing Tutorial. The mesh has been re-provided within the data download package for this tutorial.

Open the mesh by selecting File > Open and navigate to Module_Data\Trap_Channel_000.2dm.

In the Open File As dialogue box select TUFLOWFV Geometry Files (*2dm):

Your mesh and map files will be added to the project:

We won't be needing the Trap_Channel_000-Materials coverage. Right click on the coverage and select Delete:

To visualise the mesh elevations open the Display Options dialogue by clicking the display button . Select the 2D Mesh tab and turn on Contours. Then select the Contours tab.

Visualise the mesh contours by selecting the Contour method Color Fill. Then select the Color Ramp button and Reverse the colour palette so that blue aligns with the minimum values and red with the maximum values.

Apply your mesh to the simulation by right clicking on Trap_Channel_000 > TUFLOWFV Simulations->Trap_Steady_000:

The mesh should look similar to the below figure:

Adding Boundary Conditions

In this section you will learn to digitise Feature Arcs that 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:

Select Models > TUFLOWFV > Boundary Conditions > OK.

Digitise and apply the upstream flow boundary using the following steps and animation:

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, TUFLOW FV will project the nodestring onto the boundary location. This is preferable to snapping a nodestring onto the mesh as it allows you to iterate the mesh design independently of the boundary location.

3. Using the Select Feature Arc tool select and right click on the new arc and select Assign BC...:

4. In the BC Options under the Type: 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. Click Define Cure...:

5. In the BC Curve Editor select Import... navigate to the steadyQ_01.csv in the Module_Data folder and select Open:

6. Your flow boundary should appear as shown in the following figure. The first column (time) is in hours. The second column is the flow (Q) which is applied as a simple steady state flow of 450 m³/s with a 2 hour warm up period. Select OK:

7. Select the Export format tab and under TUFLOWFV simulation export file format select Shapefile and select OK. When SMS saves the simulation the boundary nodestrings will be exported as an ESRI Shapefile GIS layer, rather than be saved as part of the 2dm mesh.

Your Q boundary condition should look similar to the below:

Digitise and apply the downstream water level boundary using the following steps and animation:

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.

3. Using the Select Feature Arc tool select and right click on the new arc and select Assign BC...:

4. In the BC Options under the Type: drop down select WL (Water Level). Keep the subtype as Sub-type 1 and select Define Cure...:

5. In the BC Curve Editor select Import... navigate to the steadyWL_01.csv in the Module_Data folder and select Open:

6. Your water level boundary should appear as shown in the following figure. The first column (time) is in hours. The second column is the water level ('WL') which is applied as a constant water level of -3.5. Select OK:

7. Select the Export format tab and under TUFLOWFV simulation export file format select Shapefile. This will keep the boundary nodestrings independent of the model mesh. Select OK:

Your WL boundary condition should look similar to the below:

Apply the boundary conditions to the simulation by right clicking on Boundary Conditions and selecting Apply to > TUFLOWFV Simulations->trap_steady_000:

TUFLOW FV Control File Definition

Now that the mesh and boundary conditions have been assigned to the simulation we can populate the TUFLOW FV Model Control. Right click on your simulation Trap_Steady_000 and select Model Control:

The TUFLOW FV Model Control dialog box should appear as below. Highlighted in the green box are different key components of a TUFLOW FV model where we can specify parameters and inputs.

Under the General tab check Tutorial model. This will enable license free modelling in TUFLOW FV.

On the Time tab 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). Set the Starting time (h) to 0 and the Ending time (h) to 6.0.
2. The Courant–Friedrichs–Lewy (CFL) limit is 1.0 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. Set the CFL to 1.0 and the Min time step (s) to 0.1 and Max time step (s) 10.0.
   

On the Global parameters tab set the Horizontal mixing model and Define the stability limits.

1. For the Horizontal mixing model 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 viscosity (m²/s) to 0.05 and Maximum eddy viscosity (m²/s) to 99999.0.

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

On the Initial conditions set Define initial water level (m) to -3.5. This initial water level is consistent with our downstream boundary water level.

Use the Output tab to specify the result type and file format. Please follow the below steps:

1. In the Output blocks section select the Add row button.

2. Assign the DATV format.

3. In Output block options - Row 1 check Define interval and specify the Output interval (s) as 600.0.

4. In Datasets check Water depth (m), Water surface elevation (m), Velocity vector and magnitude (m/s), and Velocity magnitude only (m/s).

5. Specify the Output directory: as ..\results\.

Under the Materials tab define the default bed roughness using the below steps:

1. Check Define default material (set mat).
2. Check Override Bottom Roughness
3. Set the Bottom Roughness to a Manning's 'n' value of 0.018.

Under the Boundary conditions tab ensure the Boundary Conditions are present in Linked coverages. You have now set all the required parameters and inputs required for our model. Select OK to finish editing the TUFLOWFV Model Control.

Save The Simulation

Save the simulation by right clicking on Trap_Steady_000 and selecting Save Simulation.

Reviewing The SMS Export (Optional)

This section is provided to improve your understanding of the SMS export process and are not required to run the model.

When the simulation is saved SMS creates the TUFLOW FV folder structure and outputs the model files. The files are save to the location we have specified/created in the Creating a Simulation section. To review the TUFLOW FV folder structure navigate to Working\trap_steady_000_models\TUFLOWFV\.

You should see the following file structure:

Sub-Folder	Input / Output	Description
bc_dbase	Input	Boundary condition database(s) and input time-series data (e.g. tide, flow, meteorology, etc.).
check	Output	GIS and other check files to carry out quality control checks (use Write Check Files).
model\gis	Input	Model mesh files (.2dm).
model\geo	Input	GIS layers that are inputs to the 2D model domain.
results	Output	TUFLOW outputs the results to this folder in a specified formats.
runs	Input	TUFLOWFV Control Files (FVC).
runs\log	Output	Generated simulation log and model performance files.

Review the following model files:

• Open Working\trap_steady_000_models\TUFLOWFV\bc_dbase\Trap_Steady_000_bc_1.csv in Excel or your preferred text editor to review the flow boundary data. The flow rate should be the same as steadyQ_01.csv in the Module_Data.
• Open Working\trap_steady_000_models\TUFLOWFV\bc_dbase\Trap_Steady_000_bc_2.csv in Excel or your preferred text editor to review the water level boundary data. The water level should be the same as steadyWL_01.csv in the Module_Data.
• Open Working\trap_steady_000_models\TUFLOWFV\model\gis\Boundary Conditions.shp by dragging the shape file into your SMS project. These are the nodestrings you digitised in the Adding Boundary Conditions section.
• Open Working\trap_steady_000_models\TUFLOWFV\model\geo\Trap_Channel_000.2dm by dragging the mesh into your SMS project. This is the mesh file you applied to the simulation the Applying The Model Geometry section.
• Open Working\trap_steady_000_models\TUFLOWFV\runs\ FVC Trap_Steady_000.fvc in your preferred text editor to review the model commands and parameters specified TUFLOW FV Control File Definition. For further description on the FVC commands see Chapter 4 Model Set up and Control Files of the TUFLOW FV Manual.

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 Trap_Steady_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 The Results

To view the results select Load Solution.

If you have already closed the Simulation Run Queue right click on the Trap_Steady_000 and select Read Solution.

When you Load Solution or Read Solution SMS will automatically open the following files from from TUFLOWFV\results\ folder:

• Trap_Steady_000_H.dat (_H.dat for water levels).
• Trap_Steady_000_D.dat (_D.dat for water depths).
• Trap_Steady_000_V.dat (_V.dat for velocity vectors).
• Trap_Steady_000_VMAG.dat (_V.dat for velocity magnitude).

Note that the results have the same prefix as the TUFLOW Control File (.fvc) with the result type appended as a suffix.

Your workspace should now look similar to the below.

Use the below animation to guide you in visualising the velocity vectors and depth timesteps:

Create A Longitudinal Profile Plot

Use the following steps to produce a longitudinal profile of the depth result:

1. Create a new feature arc by right clicking on Map Data > New Coverage and Set the Coverage Type to Observation:

2. Use the Create feature arc tool to create an arc from the upstream to downstream boundary:

3. From the menu select Display > Plot Wizard:

4. In the Plot Wizard window select Observation Profile > Next:

5. Specify the following options to plot the Profile:

• Select Specified in the DataSet(s) section.
• Check your depth result.
• Select Specified in the Time Step(s) section.
• Check the following time steps: 0 00:00:00, 0 01:00:00, 0 01:30:00, 0 02:00:00, and 0 06:00:00.
• Select Finish.

The resulting longitudinal plot should look similar to the below image where chainage 0 is the upstream boundary and chainage 1000 is the downstream boundary. The results show water depths varying from 1.5 to 2.5m over the simulation:

Note: If you cannot see the legend right click on the plot area select Legend > Bottom.

Create A Time Series Plot

Use the following steps to produce a time series plot of the depth result:

1. Delete the Arc you created in the previous section. In the Observation type place a new point towards the downstream boundary using the Create Feature Point tool as shown in this animation:

2. From the menu select Display > Plot Wizard:

3. In the Plot Wizard - Step 1 of 2 window select Time Series > Next:

4. Specify the following options to plot the times series:

• Select Point 1 in Points section.
• Select Use Selected datasets.
• Check your depth result.
• Click Finish.

5. On the plot increase the Y axis max to 2.55. Use the below animation as a guide:

Your time series plot should look similar to the below:

Running A Refined Mesh Case (Optional)

Model Topography Modification

In the Going Further Section of the Trapezoidal Channel Meshing Tutorial we modified the trapezoidal channel to include a modification to the channel bed and a channel constriction.

Here, we will create a new simulation, and re-run our model with the alternative mesh to see how it affects the flow behaviour.

From the Module_Data folder open Trap_Channel_001.2dm into your SMS workspace.

On the Open File As select TUFLOW FV Geometry Files (*.2dm).

You should now see the below mesh:

Right click on simulation trap_steady_000 and select Duplicate:

Right click on new simulation and select Rename and call it Trap_Steady_001:

Apply the mesh to the Trap_Steady_001 simulation by right clicking on Trap_Channel_001 > Apply to > TUFLOWFV Simulations->Trap_Steady_001:

Save Simulation

Save your simulation by right clicking on Trap_Steady_001 > Save Simulation.

Run TUFLOW FV

Run the model by right clicking on the simulation Trap_Steady_001 and select Run Simulation:

The Simulation Run Queue should now appear. You will notice the command window will show TUFLOW FV processing, when complete you the command line should show Run Successful.

Select Load Solution to view the results.

Reviewing Results

Create a longitudinal depth profile using the step outlined in the previous section here. Your results should look similar to the below:

In this section we visualise a timeseries of the velocity and compare how the channel constriction has changed the velocity magnitude. Use the below steps to help you:

1. Delete the previous feature arc and point in the observation coverage type. Then add a new feature point at the downstream side of the constriction. Use the below animation and steps to guide you:

2. From the Display dropdown select Plot Wizard.

3. In Plot Wizard - Step 1 of 2 dialog select Time Series.

4. In Plot Wizard - Step 2 of 2 specify the following options:

• Select Point 2 in Points section.
• Select Use Selected datasets.
• Check trap_steady_000_VMAG and trap_steady_001_VMAG.
• Click Finish.

Your results should look similar to the below:
Note: Remember to change the Y axis limits to view your results.

Following review of the Trap_Steady_000 and Trap_Steady_001 results, do you see how the channel modifications alter the depth and velocity of flow? We observe:

• The constriction on the water flow has resulted in higher velocities towards the downstream end of the channel. This is an outcome of the continuity equation: Velocity (m/s) = Flow (m³/s) / Cross sectional flow area (m²). As the flow is held constant during the simulation, as we reduce the available cross sectional flow area, the flow velocity must increase.
• The flow depth varies in response to modifications in bed form.

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 the Trapezoidal Channel TUFLOW FV Model using the SMS Interface. You have now learnt how to build and run a simple model in SMS.

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

1. Build upon your modelling skills by modelling a Riverine Reach in Tutorial Module 2.
2. Head back to the Tutorial Module Introduction Landing Page to try other tutorials.
3. Return to the TUFLOW FV Wiki Mainpage.