Tutorial Module01 SMSInterface

From TUFLOW FV Wiki
Revision as of 14:09, 28 March 2023 by Georgia.stones (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
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 TUFLOW FV interface [TBC name hyperlink]. The SMS TUFLOW FV interface currently supports the development and simulation of 2D Hydrodynamic models only. In this tutorial you will learn how to create and run a TUFLOW FV model and visualise your results in SMS. 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

TFV Interface Set up

Firstly, open a new SMS project and save as trap_steady_01.sms into the working directory. Now we will create a new TUFLOWFV simulation, to do this please right click on Project > New Simulation > TUFLOWFV

Tut01 InTFV CreateSim.png


A new simulation should appear in the project window. To set up our project we will need to undertake the following steps:

  • Please rename the Sim trap_steady_01 by right clicking on Sim > Rename,
  • The Interface will generate the required TUFLOWFV folder structure, to do this please right click on the simulation trap_steady_01 > Save Simulation >

Now navigate to your working directory \working\trap_steady_01_models\TUFLOWFV.

You should have the following TUFLOW FV model folder structure:


Folder Structure Update.png


Please note this tutorial has been created using SMS version 13.2.0. You may use other versions of SMS however some minor differences may exist between the screenshots in this tutorial and the SMS version you are using.

Applying the Model Geometry

In this tutorial we will use the mesh we created in Meshing TUT XX [TBC insert hyperlink], if you have not completed this tutorial, we have provided the mesh file trap_channel_000 in the Module_Data folder. Using the File > Open dialog box please navigate to the mesh file trap_channel_000.2dm

If the following dialog box appears, please select TUFLOWFV Geometry Files (*2dm)

Tut01 InTFV OpenFileAs.png

You should now see your mesh and map files within the project, if you have completed tut X [TBC] these should look familiar. To apply your mesh to the simulation please right click on Trap_Channel_000 > TUFLOWFV Simulations->trap_steady_01

Tut01 InTFV ApplyMesh.png

Now that your mesh is in the simulation, please save your simulation trap_steady_01 > Save Simulation > . Navigate to your model folder \TUFLOWFV\model\geo\ and you will see that your .2dm file has been saved into the geo folder. For your understanding and future models all TUFLOW FV geometry files are stored in the geo 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 (ie. along the left and right edges of the model domain). The Feature Arcs have already been digitised for this example, you will have noticed that Trap_Channel_000 - Nodestrings was added into the map data when you opened the 2dm file, these will be used as your model boundary conditions.

Tut 01 US DS mesh side 01.png

Your Trap_Channel_000 - Nodestrings map file should be assigned a map type of TUFLOWFV Bounadry COntions. To check this please chright click on Trap_Channel_000 - Nodestrings > Type > Models > TUFLOWFV > Boundary Conditions is check

Tut01 InTFV ChkBCType.png


In these steps we will firstly apply the flow boundary and then the water level. Please follow the below steps:

1. Under Map Data in the project window select trap_Channel_000 - Nodestrings so that it is highlighted

2. Using the Select Feature Arc 1.1.5B.png tool double click on the Feature Arc on the left edge (upstream) of the mesh and the Assign Boundary Condition window should appear.

Tut 01 assign BC 00.png

3. From the BC Types drop down, select Q (Nodestring Flow) and a few different options should appear. Firstly, change the subtype to Sub-type 3 and now select Define Cure... . The BC Curve Editor dialog should appear.

4. Increase the number of rows to 4, and populate the flow boundary with the following:

Time (h) Q
0.0 0.0
1.0 100
2.0 450
6.0 450

Your flow boundary should look similar to the below figure. In this case, the boundary conditions are very simple because the run is steady state. Note that the first column (time) is in hours and that there is a warm-up period of 2 hours. 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.

Tut 01 assign BC Q editor00.png

5. Select OK and OK

6. Now on the downstream boundary (right edge of the mesh) we will add a water level boundary. Double click the Feature Arc on the right edge of the mesh that you made in Step 2. From the BC Types drop down select WL (Water Level). This time leave the subtype as Sub-type 1 and select Define Cure.... The BC Curve Editor dialog should appear

7. Increase the number of rows to 2, and populate the flow boundary with the following:

Time (h) WL
0.0 -3.5
48.0 -3.5

Your Water Level boundary should look similar to the below figure.
Tut 01 assign BC WL editor00.png

8. Select OK and OK.

Tut 01 assign WS TFV Sim editor00.png

9. Now we need to apply our Boundary Conditions to the TUFLOWFV simulation. To do this, right click on your mesh Trap_Channel_000-Nodestrings > Apply to > TUFLOWFV Simulations->Sim.

10. Lastly, we need to save your work by right clicking on the simulation and selecting Save Simulation. For your reference, the interface will automatically save the .2dm mesh into .\TUFLOWFV\model\geo folder and the water level and flow boundary conditions .csv files into .\TUFLOWFVbc_dbase\. This can later become the geometry input file for the TUFLOW FV tutorial model in XHYPERLINKX [TBC].

Tut 01 assign WS SaveSim.png


Optional Step Applying BC using a shapefile:
In this tutorial we are applying the boundary conditions directly to the mesh (2dm file), however the SMS Interface TUFLOWFV has the capability to apply the boundary conditions using a GIS shapefile. Open the Assign Boundary Condition dialog that we used to apply the boundary conditions in the previous steps and select the Export format tab and in the drop down TUFLOWFV simulation export file format select Shapefile and apply the nodestrings to your simulation. Save your simulation and navigate to \TUFLOWFV\model\gis and you will see your new shapefile.

Tut01 InTFV BCshpfile.png

TUFLOW FV Model Setup

Now that we have our mesh file and boundary conditions in the simulation we will create the Tuflow FV control file. The TUFLOW FV control file is created via the Model Control dialog box in the SMS Interface. To access the TUFLOWFV Model Control dialog in SMS right click on your simulation trap_steady_001 and select Model Control...

Tut01 InTFV ModelControl.png

The TUFLOWFV Model Control dialog box should now appear as below. As you can see highlighted in the green box there are different tabs where we can specify TUFLOW FV parameters and inputs. Under the General tab please check Tutorial model. This will enable licence free modelling.

Tut01 InTFV ModelControl General.png

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 6.0
2. 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. Please set the CFL to 1.0 and the Min time step (s) to 0.0 and Max time step (s) 10.0


File:Tut01 InTFV ModelControl Time.png

Under the Global parameters tab we will set the Horizontal mixing model and Define the 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, with a Smagorinsky factor of 0.5.


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

2. Please check Define stability limits and set the maximum water level (m) to 10.0 and Maximum velocity (m/s) to 100.0, please note that the velocity limit here is high – that’s because the velocities along the wetting and drying boundary edges are high.

File:Tut01 InTFV ModelControl GlobalPara.png

TBC should I add somehthing about the wind stress and geometry tabs not needing to be used?

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 -3.5

File:Tut01 InTFV ModelControl InCon.png

Under the Output tab we can specify what 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 rows Tut01 InTFV AddRow.png button
2. Now int he new drop down please make sure that the datv format file is specified
3. In the Output block options please check Define Interval and we will specify our Output interval (s) to 600.0
4. Now we will define the results we would like the model to write, in Datasets please check Warer depth (m), Water surface elevation (m), and Velocity vector and magnitude (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\, the results will be written to the results folder

tut01_InTFV_ModelControl_Output.png

Under the Materials tab we will define the default material roughness value. So far, material types haven’t been highlighted. By default, SMS will create elements using a single material type (1). In this model example we will assign a bottom roughness of 0.018 (the default friction approach is a Manning’s number). To do this please check Define default material (set mat), then check Override Bottom Roughness we can now update the Bottom Roughness to 0.018 as show in the example below.

tut01_InTFV_Mat.png

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.

File:Tut01 InTFV BoundaryCon.png

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 trap_steady_01 and Save Simulation Tut01 InTFV SaveSim.png

You will now have a Tulfow FV control file named trap_steady_01.fvc in the .\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

Firstly, download the TUFLOW executable from here and save in a suitable place. So that the SMS inyterface is ruuning the latest version of TUFLOWFV please from the dropdown menu please select Edit > Preferences and under the File Locations find TUFLOWFV in the MOdel Excuitablesx and navigate to thew TUFLOW.exe you have just downlopaded and slect OK


Tut01 InTFV TFVEXE .png

Now to run your model simply right click on the simulation trap_steady_01 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.

Tut01 InTFV SImRunQueue .png


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 the result files will be written to the .\TUFLOWFV\results\ folder; one for the water levels (_H.dat), one for velocities (_V.dat) and another for water depths (_D.dat). They will have the same prefix as the fvc file; in this example they will be called:

trap_steady_01_H.dat

trap_steady_01_V.dat

trap_steady_01_D.dat

To view the results in sms, please select Load Solution, if you have already closed this window simply right click on the trap_steady_01 simulation and select Read Solution

Tut01 InTFV LoadSol .png

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

Tut01 InTFV loadedResults .png

We can also produce longitudinal profiles of the results to do this please undertake the following steps:

1. A feature arc needs to be created in the Map Data (the type of this coverage needs to be “Observation”). Firstly, right click on the Map Data and select New Coverage, now select Observation as the new coverage type.

Tut01 InTFV ObsCoveragetype .png

2. Now we use the Create feature arc Tut 01 interface featureArc 00.png tool and create a feature arc from the upstream to downstream boundary.

Tut01 InTFV ObsFeatureArc .png

3. Then, at the tool bar menur select Display > Plot Wizard. In Plot Wizard window select Observation Profile > Next in the Plot Wizard window

Mod 01 plot wizard step01.00.png

4. Select the following options to plot the Profile

> 1. select Specified in the DataSet(s)" section,
> 2. check your depth result,
> 3. select Specified in the "Time Step(s)" section and
> 4. select All On and Finish

Tut01 InTFV PlotWiz.png

Your result should look similar to this:

Tut01 InTFV DepthResult .png

Inclusion of Salinity

It is relatively straightforward to include a conservative tracer into the model simulation.


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 open the Trap_Channel_001.2dm into your SMS workspace you created in tutorial XX [HYPERLINK TBC] or from the Module_Data folder.


When you load your Trap_Channel_001.2dm file into your workspace the below Open File As window will appear, please ensure that the TUFLOW FV Geometry Files (*.2dm) is selected. You should now see your mesh and map files within the project, if you have completed tut X [TBC] these should look familiar.

Tut01 InTFV OpenFileAs.png


Now, save you SMS project and save as trap_steady_02.sms into the working directory. Now we will create a new TUFLOWFV simulation, to do this please right click on Project > New Simulation > TUFLOWFV

Tut01 InTFV CreateSim.png


A new simulation should appear in the project window. To set up our project we will need to undertake the following steps:

  • Please rename the Sim trap_steady_02 by right clicking on Sim > Rename,

Now that you have your new simulation, please apply your mesh to the simulation please right click on Trap_Channel_001 > TUFLOWFV Simulations->trap_steady_02

Tut01 InTFV ApplymeshSim2.png

Now save your simulation by right clicking on trap_steady_02 > Save Simulation > . Navigate to your model folder \TUFLOWFV\model\geo\ and you will see that your .2dm file has been saved into the geo 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 (ie. along the left and right edges of the model domain). The Feature Arcs have already been digitised for this example, you will have noticed that Trap_Channel_001 - Nodestrings was added into the map data when you opened the 2dm file, these will be used as your model boundary conditions.

Your Trap_Channel_001 - Nodestrings map file should be assigned a map type of TUFLOWFV Boundary Conditions. To check this please right click on Trap_Channel_001 - Nodestrings > Type > Models > TUFLOWFV > Boundary Conditions is checked.

Tut01 InTFV ChkBCType.png


In these steps we will firstly apply the flow boundary and then the water level. Please follow the below steps:

1. Under Map Data in the project window select trap_Channel_001 - Nodestrings so that it is highlighted

2. Using the Select Feature Arc 1.1.5B.png tool double click on the Feature Arc on the left edge (upstream) of the mesh and the Assign Boundary Condition window should appear.

Tut 01 assign BC 00.png

3. From the BC Types drop down, select Q (Nodestring Flow) and a few different options should appear. Firstly, change the subtype to Sub-type 3 and now select Define Cure... . The BC Curve Editor dialog should appear.

4. Increase the number of rows to 4, and populate the flow boundary with the following:

Time (h) Q
0.0 0.0
1.0 100
2.0 450
6.0 450

Your flow boundary should look similar to the below figure. In this case, the boundary conditions are very simple because the run is steady state. Note that the first column (time) is in hours and that there is a warm-up period of 2 hours. 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.

Tut 01 assign BC Q editor00.png

5. Select OK and OK

6. Now on the downstream boundary (right edge of the mesh) we will add a water level boundary. Double click the Feature Arc on the right edge of the mesh that you made in Step 2. From the BC Types drop down select WL (Water Level). This time leave the subtype as Sub-type 1 and select Define Cure.... The BC Curve Editor dialog should appear

7. Increase the number of rows to 2, and populate the flow boundary with the following:

Time (h) WL
0.0 -3.5
48.0 -3.5

Your Water Level boundary should look similar to the below figure.
Tut 01 assign BC WL editor00.png

8. Select OK and OK.

9. Now we need to apply our Boundary Conditions to the TUFLOWFV simulation. To do this, right click on your mesh Trap_Channel_001-Nodestrings > Apply to > TUFLOWFV Simulations->trap_steady_02.

10. Lastly, we need to save your work by right clicking on the simulation and selecting Save Simulation. For your reference, the interface will automatically save the .2dm mesh into _models\TUFLOWFV\model\geo folder. This can later become the geometry input file for the TUFLOW FV tutorial model in XHYPERLINKX [TBC].

Tut 01 assign WS SaveSim.png


TBC- say something about how we are applying the BC straight onto the 2dm but we could do it as a shapefile- this might of been mentioned in a previous tut

TUFLOW FV Model Setup

Now that we have applied our mesh file and boundary conditions in the simulation we will create the TUFLOW FV control file. Please follow the steps outlined in [TBC link].

Run TUFLOW FV

Now to run your model simply right click on the simulation trap_steady_02 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.

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 your Results

Open your results in SMS and following the steps outlined in [TBC link],

Tut01 InTFV Sim2Dresult.png

How has the mesh modification changed the depth in the channel?

Now open your previous result Trap_Steady_01 results and compare to your results. Can you see how changing the mesh has altered your results?

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 TUFLOW FV Interface. 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 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