Modelling M01 video draft

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: Modelled 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. Refer to this folder as 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 The 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 Toolbar is made up of a series of tools and plugins that are used to edit GIS layers and perform functions.
3. The Layer Panel is used to organise and turn on and off GIS layers.
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.

Use the below steps and video to save a new project:

1. From the menu bar select Project > Save As....
2. Navigate to the Working folder.
3. Name the project trap_steady_000.qgz and select Save.

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 and video 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 is used to configure the TUFLOW FV project. This includes specifying the model and executable file paths, defining the GIS projection (i.e. the geographic coordinate system used for the TUFLOW FV model, all inputs need to use the same projection) and writing GIS empty files for model inputs. Use the below steps and video as guide to configure your TUFLOW FV project:

1.Select the Configure / Create TUFLOW Project symbol from the TUFLOW Plugin toolbar.

2. Check the Project ID (display only) is set to EPSG:32760.

3. Check the Project Description (display only) is set to WGS 84 / UTM zone 60S.

4. Click Browse... to select the folder location of the Working folder. This creates the default TUFLOW FV model directory and sub-folders.

5. Click Browse... to select the location of the TUFLOW FV single precision executable file. Note: The provided version may differ from the video, however use the build provided in the Exe folder.

6. Select SHP as the GIS Format.

7. Select TUFLOW Flexible Mesh (TUFLOW FV).

8. Tick all box options:

• Save Default Settings Globally (for all projects): The settings configured by this window sets the default for opening a new QGIS workspace.
• Create Model Folder Structure: The TUFLOW sub-folders (e.g. bc_dbase, model, runs) are made within the Working\TUFLOWFV folder.
• Create Template Files: This creates the 'empty' gis file template folder in Working\TUFLOWFV\model\gis folder. It contains all the TUFLOW FV template files in the projection set above. It is important to create new template files for each project to ensure the projection is correct.
• Tutorial Model: Sets a command within the automatically generated FVC instructing TUFLOWFV to run the tutorial model licence free.

9. Click OK and a TUFLOW FV DOS console window opens. This runs the first part of a TUFLOW FV model initialisation and creates TUFLOW FV folder structure, projection file, TUFLOW FV empty GIS files and base FVC file called Create_Empties.fvc. In the Windows Explorer navigate to Working\TUFLOWFV to review the newly created folder structure and files.

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

Use the below steps and video to import an empty nodestring file:

1. Select Import Empty File from the TUFLOW Plugin toolbar:
2. Under Empty Directory, navigate to the Working\TUFLOWFV\model\gis\empty.
3. Under Empty Type, select 2d_ns.
4. Name Run ID Trap_Channel_000.
5. Check Lines in the Geometry Type.
6. Select OK. The 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.

Navigate to the Module_Data folder and copy the Trap_Channel_000.2dm and Trap_Channel_001.2dm mesh files into the Working\TUFLOWFV\model\geo folder. These files will be used later in the models demonstrated in this tutorial. However, in this section, we will use the Trap_Channel_000.2dm mesh file to guide the placement of the nodestrings.

Use below steps and video to load and style the mesh:

1. Select the TUFLOW Viewer on the toolbar.
2. From the viewer select File > Load Results - Map Outputs and navigate to Working\TUFLOWFV\model\geo\Trap_Channel_000.2dm.
3. If the layer is not visible right click on Trap_Channel_000 in the layers panel and select Zoom to Layer(s).
4. From select Toggle Mesh Rendering to view the mesh cells.

It is important to digitise boundary nodestrings from the right bank to the left bank when looking downstream. This is because the direction the nodestring faces determines the sign convention (positive or negative value) used in model output results, such as polyline fluxes and mass balance. Use the following steps and video as a guide:

1. From the Layer Panel, select the 2d_ns_Trap_Channel_000_L layer. Then, from the TUFLOW Plugin toolbar, select Apply TUFLOW Styles to Current Layer. The layer symbology will now update.
2. From the Toolbar select Toggle Editing button and then
3. From the Toolbar select Add Line Feature .
4. Digitise a line at the upstream boundary of the model domain (refer to video). In the attribute dialog box, specify the following:
   • Set ID as 1.
   • Set Flags as BD and select OK.
5. Repeat the process at the downstream boundary (refer to video). In the attribute dialog box, specify the following:
   • Set ID as 2.
   • Set Flags as BD and select OK.
6. From the Toolbar click Save Layer Edits and Toggle Editing button.

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 Notepad++ 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\2025.1.0. Note: A relative path is used for the executable and the FVC, a full file path can also be used. As new versions of TUFLOW FV are released, the executable file in the model data download will be updated. Therefore, the version available in the download may not match the one shown in the videos or figures presented here. The path is saved to the local Windows environment variable exe.
3. Line 4 sets the number of parallel CPU threads to run the simulation on.
4. Line 6 calls the TUFLOW FV executable file (it's path is saved in the environmental variation exe) and runs Trap_Steady_000.fvc.
5. 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).
6. Line 9 keeps the Windows prompt open, rather than closing it automatically after the simulation completes.
7. 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 video above.

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 identifying data input issues and troubleshooting the model. Take some time to familiarise yourself with its contents. Much of the information is a repeat of what appears in the Console Window, so if that is no longer accessible, you can refer to 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 model results using the below steps and video:

1. Holding shift select 2d_ns_Trap_Channel_000_L and Trap_Channel_000 from the Layers Panel and click Remove Layer / Group in the Layer tools.
2. From the TUFLOW Viewer select File > Load Results-Map Output and navigate to Working\TUFLOWFV\results\Trap_Steady_000.nc.
3. Review the the different outputs in the Result Types.

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. Select the Plot Profile button  so that your cursor now becomes a crosshair [+].
5. Digitise a long section (refer to video) and review the results.
6. Once complete select Clear Current Plot .

(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. Select the Plot Time Series button so that your cursor now becomes a crosshair [+].
5. Digitise a time series point (refer to video) and review the results.
6. Once complete select Clear Current Plot and close the result by right clicking Trap_Steady_000 in the TUFLOW Viewer and select Close Results.

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

Note: It is good practice to close any result files when finished reviewing, as the model cannot be re-run if result files are open.

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.

Previously, Trap_Channel_001.2dm was copied into the Working/TUFLOWFV/model/geo directory. Use the below steps and video to review the mesh:

1. From the Windows Explorer drag and drop Working/TUFLOWFV/model/geo/Trap_Channel_001.2dm into the workspace,
2. Toggle on the mesh rendering from the TUFLOW Viewer.
3. Review the elevation changes and channel constriction within the mesh.
4. Select Trap_Channel_001.2dm and from the Layers Panel and click Remove Layer / Group in the Layer tools.

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

This section reviews the effects of elevation changes and channel constriction on modelled velocities.

Use the below steps and video to open and review a long section of the modelled velocities:

1. From the TUFLOW Viewer select File > Load Results-Map Output and navigate to Working\TUFLOWFV\results\Trap_Steady_001.nc.
2. In the Result Type window, select velocity and velocity vector map outputs.
3. Select the Plot Profile drop down .
4. In the drop down, check Velocity.
5. Select the Plot Profile button  so that your cursor now becomes a crosshair [+].
6. Digitise a long section (refer to video).
7. Click through a few time stamps to see how the velocity changes throughout the simulation.

After reviewing results from the Trap_Steady_000 and Trap_Steady_001 simulations, you should observe the following:

• The constriction on the water flow has resulted in higher velocities. This is an outcome of the continuity equation: Velocity (m/s) = Flow (m³/s) / Cross sectional flow area (m²). With constant flow, a reduced cross-sectional area leads to increased velocity.
• Water depth varies in response to changes in bed elevation. Raised bed sections reduce the available depth, prompting an adjustment in the water surface elevation. Elevation changes—such as a bump or constriction in the mesh—limit the flow area and therefore increase local velocities, again due to the continuity principle.

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.