Tutorial M02

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.

This tutorial builds upon Tutorial Module 1 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 uses QGIS and Notepad++ to setup and run our models.

Example: Modeled riverine channel depth and velocity vector results

Requirements And Downloads

Requirement	Brief Description
Model Data	Download the Tutorial Module 2 Data Package.
Assumed Knowledge	It is recommended to complete Tutorial Module 1 and Meshing Module 2 prior to completing this tutorial.

TUFLOW FV Model Development Workflow

We will develop our model using a combination of the QGIS and Notepad++, noting that the mesh has already been developed in Meshing Module 2.

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 package used together in combination are provided in the figure below:

Prepare Your Working Environment

Copy and unzip the folder to your preferred working location on your computer, for example E:\TUFLOWFV\Tutorial_M02.

• 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 Exe folder contains the TUFLOW FV executable used to run your models.
• The Module_Data folder contains the required mesh files to complete this tutorial.
• The Working folder is for the files you create and work within.

Initialise The Project With GIS Integration

Firstly, launch QGIS and become familiar with the project window. Key attributes of the QGIS project window are described 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:

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 Riverine_Channel_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 TUFLOW FV Project

The TUFLOW 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_M02\Working\.

C. Set the TUFLOW / TUFLOW FV Executable folder to the location where you downloaded TUFLOWFV.exe. The TUFLOW FV executable is provided within the data package as Tutorial_M02\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.

Applying Nodestrings

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

4. Check Lines in the Geometry Type.

5. Select OK.

Your new 2d_ns_Riverine_channel_00 layer will appear in the QGIS layer panel and will be automatically saved into the \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 Riverine_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_Riverine_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.

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.

Applying Materials

TUFLOW FV uses polygons to specify the spatial location of varying material types within the model domain. To reduce the amount of digitising required in this tutorial we have provided the material file in the Module_Data folder. However, we will step through how to specify the different material types within material file.

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

1. Gravel represented by a 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.

Use the following animation and steps to help you assign the material IDs:

1. Copy \Module_Data\2d_mat_Riverine_Channel_000_R.shp and all supporting files into \Working\TUFLOWFV\model\gis. Then drag and drop 2d_mat_Riverine_Channel_000_R.shp into your QGIS workspace.

2. Select the 2d_mat_Riverine_Channel_000_R layer in the layers panel and click the Toggle Editing button on the digitizing tab.

3. Using the Identify Features tool select the polygon identified as gravel in the above figure.

• Select Edit Feature form.
  
• In the Feature Attributes please update the Material to 1.
  

5. Undertake the same steps for Sand applying a Material ID as 2.

6. For the Vegetation Material ID the left and right bank will need to be assigned separately with a Material ID of 3.

7. Once completed please click the Toggle Editing button on the digitizing tab and save changes.

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

TUFLOW FV Model Setup

Boundary Condition Time Series

Copy the provided flows.csv and tide.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.

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 Riverine_Channel_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 riverine 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

!__________________________________________________________________________________________________________________________________
! SIMULATION CONFIGURATION
Bottom Drag Model == Manning                                         ! Use Manning's 'n' Coefficient for bed roughness

!__________________________________________________________________________________________________________________________________
! TIME COMMANDS
Start Time == 0.0                                                    ! Model start time in hours    
End Time == 42.0                                                     ! Model end time in hours
CFL == 1.0                                                           ! Courant stability criterion 
Timestep Limits == 0.01, 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\Riverine_Channel_000.2dm                 ! Computational mesh (this was built during the Meshing Tutorial)
Read GIS Nodestring == ..\model\gis\2d_ns_Riverine_Channel_000_L.shp ! Open boundary nodestring locations and names  
Read GIS Mat == ..\model\gis\2d_mat_Riverine_Channel_000_R.shp       ! Material locations and IDs

!__________________________________________________________________________________________________________________________________
! MATERIAL PROPERTIES
Material == 1                                                        ! Gravel 
  Bottom Roughness == 0.018                                          ! Manning's 'n' roughness coefficient
End Material

Material == 2                                                        ! Sand 
  Bottom Roughness == 0.035                                          ! Manning's 'n' roughness coefficient
End Material  

Material == 3                                                        ! Vegetation 
  Bottom Roughness == 0.06                                           ! Manning's 'n' roughness coefficient
End Material  

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

!__________________________________________________________________________________________________________________________________
! BOUNDARY CONDITIONS
BC == Q, 1, ..\bc_dbase\flows.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\tide.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 == 900.                                            ! Results will be saved every 900 seconds (15mins) 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 Riverine_Channel_000.fvc. Line 9 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 Riverine_Channel_000.fvc but it will not run the simulation Riverine_Channel_001.fvc (Riverine_Channel_001.fvc will be used to investigate timestep sensitivity to mesh design 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.

For more information on setting up a .bat file and running multiple models, head to Running TUFLOW FV.

Troubleshooting

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 Results

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\Riverine_Channel_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, 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.  

Our simulation has been configured to output NetCDF format results, with water levels, velocities, and water depths saved every 900 seconds (15mins). To review the results, in QGIS click the TUFLOW Viewer button which should open the TUFLOW Viewer panel as shown below. To open your results please select File>Load Results-Map Output and navigate to Working\TUFLOWFV\results\Riverine_Channel_000.nc and Open.

Your QGIS project window should look similar to the below:

We will now visualise the results in two plots:

1. A long section of water level and bed elevation.
2. A time series of the velocity.

Long Section Plot

To display a long section of the water level and bed elevation zoom into a section of channel and:

1. Display the mesh by selecting the Toggle Mesh Rendering.

2. Select the Plot Cross Section drop down .

3. In the drop down check bed elevation.

4. In the drop down check water surface elevation.

To draw the long section please select the and your cursor should now become a crosshair [+]. Now you are ready to plot your long section. See the long section example below:

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

Time Series Plot

To display a timeseries of the velocity and velocity vectors follow the below steps:

1. Display the mesh by selecting the Toggle Mesh Rendering.

2. In the Result Type window select velocity and velocity vector map outputs.

3. Now increase the time stamp see how the velocity vectors change throughout the model simulation.

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

5. To extract the timeseries section select the and your cursor should now become a crosshair [+]. Click on your results to view a time series similar to the below:

For more examples on how to review your results using the TUFLOW Viewer Plugin there are a range of examples presented on the TUFLOW Viewer wiki page.

Reviewing Mesh Performance

In this section we will review the run time performance of our mesh and provide an introduction to TUFLOW FV's adaptive time stepping.

CFL And Adaptive Time Stepping

To ensure a model runs stable, a TUFLOW FV simulation must conform to the Courant-Friedrichs-Lewy condition (CFL). The CFL is calculated as a function of cell area, the cell shape, the water depth, and the velocity of flow according to:

Where:

u ^. n = Flow velocity (m/s) or (ft/s)

g = Gravitational acceleration (m/s²) or (ft/s²)

h = The water depth (m) or (ft)

Delta t = Model time step (s)

L* = Cell size length scale (Calculated from cell face length and cell area. See the TUFLOW FV Manual for more information on the calculation of L*).

The numerical calculations of TUFLOW FV require that the CFL must always be kept below 1.0 to ensure that the solution is physically sound.

When considering the calculation of the CFL, in general terms:

• The deeper the water, the larger the CFL.
• The faster the flow, the larger the CFL.
• The bigger the timestep, the larger the CFL.
• The smaller the cell size, the larger the CFL.

So a small cell in deep water will tend to control overall model stability, more so than a large cell in shallow water.

To ensure the CFL is always kept below 1.0, TUFLOW FV calculates the CFL at all cells in the model and will modify the model timestep throughout the simulation to ensure that no cells exceed the CFL criterion. This 'adaptive timestep' approach is a common feature of hydrodynamic modelling solvers. While this is a good thing for stability, if a mesh is poorly configured there can be individual outlier cells that can unnecessary slow down the model.

As a modeller, we don't have a lot of control over the flow velocity or water depth, as they are physical components of the system we want to model. However, we do have control over the mesh design (L*), and to a lesser extent the model timestep (Delta t).

The most effective way to keep your model stable and efficient is to design a good mesh. It is also the component you have the most control over.

Reviewing CFL Diagnostic Files

The speed of a TUFLOW FV simulation, at a given point during the simulation, is limited by the cell with the highest calculated CFL number. i.e. the entire model is forced to run at a timestep low enough to ensure that the 'worst CFL' performing cell remains stable. It should be noted that the location of the poorest performing cell/s may change as the simulation progresses due to changes in the flow field.

As a modeller, we need to review these 'poor timestep' model cells. In these areas it may be possible to improve our mesh. At the very least, we need to be comfortable that the mesh configuration in these areas is required. i.e. In these areas do we need this mesh resolution, or design to model the process we are trying to simulate? Or, can we improve the mesh be adjusted in these areas to improve efficiency. The time spent reviewing your mesh during this process can save you valuable time, effort and money later on during delivery of your project.

To help locate which cells are slowing your model down, is beneficial to review the timestep diagnostics produced by TUFLOW FV.

Close any layers or results files in the QGIS workspace and drag and drop the \TUFLOWFV\model\geoRiverine_Channel_000.2dm into the QGIS map canvas. Select Toggle Mesh Rendering in the TUFLOW Viewer and then close the TUFLOW Viewer:

Use the following steps to open a csv file of CFL diagnostic information generated by TUFLOW FV at successful model completion:

1. Select the Layer dropdown and click Data Source Manager.

2. On the left panel of the Data Source Dialog box select Delimited Text.

3. Under file name navigate to TUFLOWFV\input\log\ and select Riverine_Channel_000_ext_cfl_dt.csv.

4. Make sure the File Format is set to CSV (comma separated values).

5. Check First Record has field names and detect field types.

6. Set X field to x_ctrd, Y field to y_ctrd, and z field to cfl_dt_min.

7. Select Add.

Now we have Riverine_Channel_000_ext_cfl_dt.csv displayed as points, we will change the symbology so that we can review the minimum model timestep. Right click on Riverine_Channel_000_ext_cfl_dt in the Layers panel and select Properties... and set the following:

1. In the layer properties dialog box select Symbology.

2. Set the symbol display to Graduated.

3. Set the display Value to cfl_dt_min.

4. Select an appropriate Color ramp from the drop down menu.

5. Specify 10 Classes.

6. Set classification Mode to Equal Count (Quantile).

7. Select Apply and OK.

You should now be able to see how the model minimum timestep varies across the model domain. This can be used to identify the cells that are limiting the timestep of the model.

To isolate the cells that are limiting the timestep, in the layer panel uncheck classes 0.378 - 4999.5:

Zoom in around the upstream boundary of the model. For this model, the limiting cells are in the deep water within the river bends and also the narrow cells on the channel banks. To increase the speed of the model we would need to relax (coarsen) the mesh definition in these areas.

For more discussion and techniques on reviewing the model timestep diagnostics and improving your runtime see A Model Runs Slow.

Mesh Design And Impact On Runtime

To demonstrate how modifying the mesh, either by refining or enlarging cells, influences the model timestep we have provided a second mesh Riverine_Channel_001.2dm in the Module_Data folder. We will review this mesh, update our TUFLOW FV control file, re-run the model and review the impact on run time.

Navigate to the Module_Data folder and copy Riverine_Channel_001.2dm into \TUFLOWFV\model\geo. Visualise the mesh by dragging and dropping Riverine_Channel_001.2dm file into your QGIS workspace. In this mesh we have increased and decreased the cell size in two sections of the channel, shown in the below figures:

TUFLOW FV Control File Update

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

!__________________________________________________________________________________________________________________________________
! GEOMETRY
Geometry 2D == ..\model\geo\Riverine_Channel_001.2dm                     ! Modified computational mesh to demonstrate time step impacts.

Run TUFLOW FV

To run the new model Riverine_Channel_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 The Mesh Refinement

To review how mesh cell size and shape influences the model timestep please review Riverine_Channel_001_ext_cfl_dt.csv. Open the file using the same steps we previously completed in Reviewing Mesh Performance.

• How has the model timestep changed in areas where the mesh resolution was changed?

You should see that the time step in the larger cells has increased and the timestep in the smaller cells has decreased. This is a because we have modified the length scale L* for these cells, which in turn affects the CLF, and ultimately the model timestep.

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