Tutorial M01

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

Read the Tutorial Model Introduction before starting this tutorial. It outlines programs requiring installation.

In this tutorial we will build a 2D model of a trapezoidal channel including:

• Creating a TUFLOW FV simulation.
• Defining boundary conditions and material specifications in GIS.
• 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.
• Importing and reviewing results.

Example: Modeled trapezoidal channel depth and velocity vector results

Requirements and Downloads

Requirement	Brief Description
Model Data	Download the Tutorial Module 1 Data Package.
Assumed Knowledge	It is recommended to complete Meshing Module 1 prior to completing this tutorial and is assumed that you have read and downloaded the required software outlined in the Tutorial Introduction.

TUFLOW FV Model Development Workflow

We will develop our model using a combination of the QGIS and Notepad++.

Key components of the workflow include:

• Initialise the TUFLOW FV project and folder structure with the TUFLOW Viewer Plugin for QGIS.
• Generate our spatial layers such as boundary condition nodestrings and material coverages.
• Create our TUFLOW FV control file and define boundary condition time series input data.
• Run the model via a windows batch file.
• Review the model log files, GIS check files and model results.

These key steps and the software packages used together in combination are provided in the figure below (noting the Mesh Design component of the workflow was completed in Meshing Module 1):

Prepare Your Working Environment

Unzip the provided Model Data to your preferred working location, for example E:\TUFLOWFV\Tutorial_M01.

• The Complete_Model folder contains the completed tutorial and its supporting files. You can use this as a reference if you require.
• The Exe folder contains the TUFLOW FV executable used to run your models.
• The Module_Data folder contains the required working files for the tutorial.
• The Working folder is where we will develop our model.

Note: All file paths we refer to in this tutorial will be relative to the location you save the data package. For example, Complete_Model\Trap_Channel_000 refers to E:\TUFLOWFV\Tutorial_M01\Complete_Mesh\Trap_Channel_000

Initialise The Project With GIS Integration

Review The QGIS Interface And Save Your Project

Launch QGIS and become familiar with the project window. Key components of the QGIS project window are described by items 1, 2, 3 and 4 in the figure below:

1. The Menu Bar is used to access QGIS functions.
2. The Layer Panel is used to organise and turn on and off GIS layers.
3. The Toolbar is made up of a series of tools and plugins that are used to edit GIS layers and perform functions.
4. If you have successfully installed the TUFLOW Plugin it will appear in the tool bar as shown below in the green box:

For further documentation see also the TUFLOW Viewer for QGIS Wiki Page.

Save a new project by selecting Project > Save As....

Navigate to the Working folder provided in the data package download and save the project as trap_steady_000.qgz.

Setting The Workspace Projection

When using GIS integration with TUFLOW FV, it is a requirement that the mesh and all GIS inputs are in the same spatial reference system. This ensures GIS objects align correctly with the mesh, allowing them to be correctly read by TUFLOW FV.

Use the following steps to set the project's Coordinate Reference System (CRS):

1. Select Project > Properties:

2. In the Project Properties, select CRS on the left-hand pane.

3. In the Filter search bar, type WGS 84 / UTM zone 60S.

4. Select Apply and OK.

Configuring The TUFLOW FV Project

The TUFLOW Viewer Plugin can be used to configure the TUFLOW FV folder structure and create model template files.

Use the below steps to configure your model:

1. Select Plugins from the menu bar > TUFLOW > Editing > Configure / Create TUFLOW Project.

2. In the Configure TUFLOW Project dialog, specify the following:

A. Set the Projection Description (display only) to WGS 84 / UTM zone 60S.

B. Set the Folder which contains TUFLOW / TUFLOWFV to the location to where you've saved your data package Working folder. For example: E:\TUFLOWFV\Tutorial_M01\Working\.

C. Set the TUFLOW / TUFLOW FV Executable folder to the location where you downloaded TUFLOWFV.exe. The executable is located within the data package as Tutorial_M01\Exe\2023.1.1.

D. Select the GIS Format as SHP.

E. Select TUFLOW Engine as TUFLOW Flexible (TUFLOW FV).

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

Based on your selection, the TUFLOW Plugin will complete the following actions in the background:

• The Save Default Setting Globally (for all projects) will set the items labelled A, B, C, D and E in the above figure as default for any new QGIS workspaces you open. If you start working on a different modelling project, you'll need to redo the steps above to ensure you are building your model in the correct working directory and importantly the correct spatial coordinate system.
• Create Model Folder Structure will create the default recommended folder structure in E:\TUFLOWFV\Tutorial_M01\Working\TUFLOWFV for you automatically:

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\gis\empty	Input	Empty GIS files required for GIS intergration.
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.

• Create Template Files will:
  1. Create the projection file Working\TUFLOWFV\model\gis\Projection.prj.
  2. Generate a series of empty template shapes we will use to build our model. The plugin will create the file Create_Empties.fvc in the TUFLOWFV\runs folder, and then run it, saving the templates to TUFLOWFV\model\gis\empty.

• By ticking on Tutorial Model, the model initialisation process can be completed without using up one of your TUFLOW FV licenses.

Review the folder and associated files that have been written to 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.

Defining The Location Of Open Boundary Conditions

TUFLOW FV uses nodestrings to specify the location of open boundary conditions. We will create our nodestrings by importing an empty template GIS layer using the TUFLOW Plugin and digitising the nodestring locations.

To import your empty file into the workspace, select Import Empty File from the TUFLOW Plugin toolbar:

Complete the following steps to create a GIS nodestring file:

1. Under Empty Directory, navigate to the Working\TUFLOWFV\model\gis\empty.

2. Under Empty Type, select 2d_ns.

3. Name Run ID Trap_Channel_000.

4. Check Lines in the Geometry Type.

5. Select OK.

Your new 2d_ns_Trap_Channel_000_L layer will appear in the QGIS layer panel and will be automatically saved into the Working\TUFLOWFV\model\gis folder.

Use the below steps to digitise the nodestrings and set the attributes for each feature:

1. Navigate to the Module_Data folder and copy Trap_Channel_000.2dm into \TUFLOWFV\model\geo folder and drag the file into the QGIS project window. We will use the 2dm mesh file to guide the placement of the nodestrings.

2. Select the TUFLOW Viewer on the toolbar. To view the mesh and elevation data in the TUFLOW Viewer, select Toggle Mesh Rendering and the Bed Elevation. Your window should look similar to below. Note that we have identified the upstream and downstream locations for you:

3. Select the 2d_ns_Trap_Channel_000_L layer in the layers panel and click the Toggle Editing button on the digitising tab. Then using the Add Line Feature tool digitise a line at the upstream boundary of the model domain. In the attribute dialog box, specify the ID as 1 and Flags as BD. Use the below animation to help guide you:

4. Repeat the process at the downstream boundary, this time setting the ID as 2 and Flags as BD.

5. Once completed, click the Toggle Editing button on the digitizing tab and save changes.

6. To review the nodestrings select the Apply TUFLOW Styles to Current Layer button. Your window should look similar to the below:

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.
• We offset the nodestring from the mesh and use the BD flag to keep the nodestring as independent as possible from the mesh. With an offset nodestring, alternative mesh resolutions or designs can be simulated without needing to continuously update the nodestrings.
• Do not use the BD flag when defining internal model nodestrings, for example those used for hydraulic structures or flux reporting.

TUFLOW FV Model Setup

Boundary Condition Time Series

Copy the provided steadyQ_01.csv and steadyWL_01.csv boundary conditions time series files from the Module_Data and paste them into the Working\TUFLOWFV\bc_dbase folder. For all models, the TUFLOW convention is that all boundary conditions datasets are kept in the bc_dbase folder. For TUFLOW FV, csv (comma delimited) files, or NetCDF layers that contain time, space and sometime depth varying boundary conditions. For our tutorial example the boundary conditions are very simple. The flow ramps up from zero to 450 m³/s over two hours and then runs at a constant flow, also known as 'steady state'. The flow boundary (steadyQ_01.csv) contains the following:

Time	Flow
0.0	0.0
1.0	100
2.0	450
6.0	450

Note: that the first column (time) is in hours and there is a warm-up period of 2 hours.

A constant water level boundary (steadyWL_01.csv) of -3.5m is specified for this model as follows:

Time	WL
0.0	-3.5
48.0	-3.5

Create The TUFLOW FV Control File (FVC)

The TUFLOW FV Control File (.fvc extension) is created via a text editor. Notepad++ is recommended for this purpose as it allows for syntax highlighting of TUFLOW FV specific commands. This configuration information is provided in NotepadPlusPlus_Tips.

1. To setup our .fvc Launch Notepad++ and select File > Open... and navigate to the TUFLOWFV\runs folder and open Create_Empties.fvc.

2. Save a new copy of this file into the TUFLOWFV\runs folder and call it Trap_Steady_000.fvc.

Note: Your FVC will already have some commands. These are default commands produced when you configured the TFV project. We will discuss these commands in the next section. Remember to enable the TUFLOW syntax highlighting using TUFLOW syntax highlighting for Notepad++.

3. The FVC already contains commands to define the GIS format and model projection. 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

4. The required commands are provided in the code blocks below. A brief description is also provided via a series of comments (green text after ! syntax). Copy the commands into your fvc file and save the file in Notepad++:

! TUFLOW FV TUTORIAL
! Flow along a trapezoidal channel
GIS FORMAT == SHP                                                    ! GIS layers will be ESRI Shapefile
SHP Projection == ..\model\gis\projection.prj                        ! Projection string. All GIS layers in the model need to be in the same reference system
Tutorial Model == ON                                                 ! Run the model in license free demo/tutorial mode
!Write Empty GIS Files == ..\model\gis\empty                         ! Generate empty template GIS layers. Already completed via QGIS

!__________________________________________________________________________________________________________________________________
! TIME COMMANDS
Start Time == 0.0                                                    ! Model start time in hours    
End Time == 6.0                                                      ! Model end time in hours
CFL == 1.0                                                           ! Courant stability criterion 
Timestep Limits == 0.1, 10.                                          ! Minimum model timestep (s), Maximum model timestep (s)

!__________________________________________________________________________________________________________________________________
! MODEL PARAMETERS
Momentum Mixing Model == Smagorinsky                                 ! Sub-grid scale eddy viscosity model
Global Horizontal Eddy Viscosity == 0.5                              ! Smagorinsky coefficient
Global Horizontal Eddy Viscosity Limits == 0.05, 99999.              ! Minimum eddy viscosity (m^2/s), Maximum eddy viscosity (m^2/s)

!__________________________________________________________________________________________________________________________________
! GEOMETRY
Geometry 2D == ..\model\geo\Trap_Channel_000.2dm                     ! Computational mesh (this was built during the Meshing Tutorial)
Read GIS Nodestring == ..\model\gis\2d_ns_Trap_Channel_000_L.shp     ! Open boundary nodestring locations and names

!__________________________________________________________________________________________________________________________________
! MATERIAL PROPERTIES
Material == 1                                                        ! Material block. This model has a single material
  Bottom Roughness == 0.018                                          ! Manning's 'n' roughness coefficient
End Material

!__________________________________________________________________________________________________________________________________
! INITIAL CONDITIONS
Initial Water Level == -3.5                                          ! Global water level at time zero in meters

!__________________________________________________________________________________________________________________________________
! BOUNDARY CONDITIONS
BC == Q, 1, ..\bc_dbase\steadyQ_01.csv                               ! BC Block. Flow boundary and csv input file
  BC Header == time, flow                                            ! Csv headers read to assign time and flow information
  Sub-Type == 3                                                      ! Specified flow rate boundary with momentum terms. Water depth^1.5 flow distribution
End BC

BC == WL, 2, ..\bc_dbase\steadyWL_01.csv                             ! BC Block. Water level boundary and csv input file
  BC Header == time, WL                                              ! Csv headers read to assign time and water level information
End BC

!__________________________________________________________________________________________________________________________________
! OUTPUT COMMANDS
Logdir == log                                                        ! Location where the TUFLOW FV log file will be saved                                       
Write Check Files == ..\check                                        ! Location where GIS check files will be saved
Output Dir == ..\results\                                            ! Location where time series and map output results will be saved

Output == netcdf                                                     ! Output block, NetCDF output format 
  Output Parameters == h, v, d                                       ! Water level, velocity, water depth
  Output Interval == 600.                                            ! Results will be saved every 600 seconds (10mins) of simulation time
End Output

Your FVC file should look similar to the figure below:

Run TUFLOW FV

Once we have entered the require commands we can now setup a Windows Batch file and run TUFLOW FV. This approach calls the TUFLOW FV executable file (.exe) and runs the TUFLOW FV Control file (.fvc).

An example batch file (run_simulations.bat) has been included in the tutorial dataset download within the Complete_Model\TUFLOWFV\runs folder.

1. Copy the .bat file into your Working\TUFLOWFV\runs and open it in Notepad++.
2. Line 2 (as shown in the figure below) includes a file path to the executable from Exe\2023.1.1. Note: A relative path is used for the executable and the FVC, a full file path can also be used. The path is saved to the local Windows environment variable exe. Line 4 sets the number of parallel CPU threads to run the simulation on. Line 6 calls the TUFLOW FV executable file (it's path is saved in the environmental variation exe) and runs Trap_Steady_000.fvc. Line 8 keeps the Windows prompt open, rather than closing it automatically after the simulation completes.
3. On Line 7 ensure to add the text REM. REM stands for remark or comment and it disables the line from being executed by Windows. This batch file will run Trap_Steady_000.fvc but it will not run the simulation Trap_Steady_001.fvc (Trap_Steady_001.fvc is an optional model run presented later in the tutorial).
4. Save the batch file and double click it in file explorer to run the simulation.

To run the batch file, double click on run_simulations.bat from Windows Explorer.

Running the batch file opens the TUFLOW FV DOS console window and the simulation begins running. The simulation usually takes less than a minute to process (depending on the computer hardware). While the model is running, it is a good practise to fill out a modelling log. It includes developer notes keeping a record of TUFLOW simulations and changes from one version to the next.

If this simulation is successful, the console window will report Run Successful and look similar to the image below.

Troubleshooting

If your simulation has stopped prematurely, it may be due to a common setup issue. See the following link for advice: Common reasons why a model won’t start.

Model Review

TUFLOW FV Log File

TUFLOW FV produces a log file (.log) containing a record of the simulation. Our log file is saved as Working\TUFLOWFV\runs\log\Trap_Steady_000.log. This file is very useful for establishing data input problems and model troubleshooting. Take time to familiarise yourself with the content of the log file. Much of it is a repeat of the information displayed to the Console Window, so if you can’t access information from the Console Window because it's not longer displayed, check the log file using a text editor.

On model completion (or if the model stops prematurely during initialisation) search the file for any “WARNING” or "ERROR" messages. A "WARNING" will allow the model to continue, however they can highlight potential flaws in the model setup. If you see any "WARNING" messages, you should investigate and ensure you are comfortable with the cause. An “ERROR” keyword indicates an unrecoverable error and causes the simulation to stop.

Reviewing Results

In this section we will review map output results in QGIS using the TUFLOW Viewer Plugin.

Our model setup specifies the map output parameters water level (h), velocity (v), and water depth (d), saved every 600 seconds (10 mins). Results are saved to the file Working\TUFLOWFV\results\Trap_Steady_000.nc. Note that model outputs from TUFLOW FV will have the same file name as the TUFLOW FV Control file, however the extension is modified, in this case to '.nc', for NetCDF format.

Open the QGIS workspace trap_steady_000.qgz that you saved into the Working folder earlier. To maintain a tidy workspace close 2d_ns_Trap_Channel_000_L and Trap_Channel_000 by right clicking on the layers and select Remove Layer.... Make sure the TUFLOW Viewer is open.

Use the TUFLOW Viewer to view the results by selecting File>Load Results-Map Output and navigate to Working\TUFLOWFV\results\Trap_Steady_000.nc.

Your QGIS project window should look similar to the below. Notice the different outputs in the Result Type:

We will use the TUFLOW Viewer to visualise the results in two different plot types:

1. A long section of water level and bed elevation; and
2. A time series of the velocity. This will be accompanied by visualisation of velocity and velocity vectors on the map canvas.

(1) To display a long section of the water level and bed elevation follow the below animation and steps:

1. Select the Plot Profile drop down .

2. In the drop down, check bed elevation.

3. In the drop down, check water surface elevation.

4. Draw the long section by selecting the Plot Profile button  so that your cursor now becomes a crosshair [+]. Now you are ready to plot your long section similar to the above animation.

(2) To display a timeseries of the velocity and velocity vectors, follow the below animation and steps:

1. In the Result Type window, select velocity and velocity vector map outputs. Now click through a few time stamps to see how the velocity changes throughout the simulation.

2. Move the time stamp forward to see how the velocity vectors change throughout the model simulation.

3. Select the Plot Time Series drop down and in the drop down check velocity.

4. To plot a time series, select the Plot Time Series button so that your cursor now becomes a crosshair [+]. Click on your results to view a time series similar to the above animation.

For more examples on how to review your results using the QGIS TUFLOW Viewer plugin, visit TUFLOW Viewer.

Going Further (Optional)

Model Topography Modification

In Meshing Module 1, a second mesh was developed with a flow constriction and raised region of bathymetry. In this section we can investigate the hydraulic impact of varying the bed form.

From the Module_Data copy Trap_Channel_001.2dm into Working/TUFLOWFV/model/geo.

Close the previous result file Trap_Steady_000.nc. Drag and drop Trap_Channel_001.2dm into you workspace. You workspace should look similar to the below:

TUFLOW FV Control File Update

Save a copy of Trap_Steady_000.fvc and name it Trap_Steady_001.fvc. Make one change to the file by referencing Trap_Channel_001.2dm as shown below. Save the file.

!__________________________________________________________________________________________________________________________________
! GEOMETRY
Geometry 2D == ..\model\geo\Trap_Channel_001.2dm                     ! Computational mesh (this was built during the Meshing Tutorial)

Run TUFLOW FV

To run the new model Trap_Steady_001.fvc, in your batch file add REM to the start of Line 6 and remove REM from the start of Line 7 (as shown below). As an alternative to typing REM, you can use the Ctrl + Q keyboard shortcut in Notepad++ to toggle REM on or off.

To run the batch file, double click on run_simulations.bat from Windows Explorer.

Reviewing Results

Remove Trap_Channel_001.2dm layer from you workspace and load the results by selecting File>Load Results-Map Output and navigate to Working\TUFLOWFV\results\Trap_Steady_001.nc.

Your workspace should look similar to the below:

In this section we will use the TUFLOW Viewer to visualise a long section of the velocity with vectors on. Follow the below animation and steps:

1. In the Result Type window, select velocity and velocity vector map outputs and click through a few time stamps.

2. Select the Plot Profile drop down .

3. In the drop down, check Velocity.

4. Draw the long section by selecting the Plot Profile button  so that your cursor now becomes a crosshair [+]. Now you are ready to plot your long section similar to the above animation.

5. Click through a few time stamps to see how the velocity changes throughout the simulation.

For a detailed description on how to use the TUFLOW Viewer to view your results, refer to section Reviewing 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 Tutorial Module 01. You have now learnt how to build, run and take introductory steps to review a model and model results.

Return to the Tutorial Introduction Page to complete further meshing and model build tutorials.