Modelling M02 video draft

From TUFLOW FV Wiki
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

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.

Provided TUFLOW FV Files

To save you time and allow focus on model simulation and review, multiple model files have been provided.

From data package copy the files in the Module_Data folder outlined in the Module_Data\ column and paste these files into the relevant folders outlined in the Copy to Working\TUFLOWFV column (refer to below table):

Module Data Copy to Working\TUFLOWFV Description
2d_mat_Riverine_Channel_000_R.* \model\gis Specifies the spatial location of varying material types within the model domain.
Riverine_Channel_000.2dm \model\geo Model mesh file.
Riverine_Channel_001.2dm \model\geo Refined model mesh file.
flows.csv \bc_dbase Model boundary condition.
tide.csv \bc_dbase Model boundary condition.

*Multiple files with the same name as the shapefile but with a different file extension support a shapefile (e.g. .shx, .prj, .cpg, .dbf). Ensure you copy all files into relevant folder.

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 Toolbar 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 Riverine_Channel_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 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 will open. 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.


10. 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 selected above 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.

Provided TUFLOW FV Files

To save you time and allow focus on model simulation and review, multiple model files have been provided.

From data package copy the files in the Module_Data folder outlined in the Module_Data\ column and paste these files into the relevant folders outlined in the Copy to Working\TUFLOWFV column (refer to below table):

Module Data Copy to Working\TUFLOWFV Description
2d_mat_Riverine_Channel_000_R.* \model\gis Specifies the spatial location of varying material types within the model domain.
Riverine_Channel_000.2dm \model\geo Model mesh file.
Riverine_Channel_001.2dm \model\geo Refined model mesh file.
flows.csv \bc_dbase Model boundary condition.
tide.csv \bc_dbase Model boundary condition.

*Multiple files with the same name as the shapefile but with a different file extension support a shapefile (e.g. .shx, .prj, .cpg, .dbf). Ensure you copy all files into relevant folder.

Spatial Definition Of Open boundaries

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 create a GIS nodestring file:

  1. To import your empty file into the workspace, 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 Riverine_Channel_000.
  5. Check Lines in the Geometry Type.
  6. 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 model mesh for a guide to digistise the nodestrings. The steps and video below outline how to open and view the mesh using the TUFLOW plugin:

  1. Select the TUFLOW Viewer on the Toolbar.
  2. From the TUFLOW Viewer select File > Load Results-Map Output and navigate to Working\TUFLOWFV\model\geo\Riverine_Channel_000.2dm.
  3. Right click on the new layer Riverine_Channel_000 > Properties. In the Layer Properties dialog select Source and from the assign CRS drop down make sure the project CRS EPSG:32760- WGS 84 / UTM zone 60S is assigned. Select Apply and Ok (refer to video).
  4. Right Riverine_Channel_000 > Zoom to Layer(s).
  5. To view the mesh and elevation data in the TUFLOW Viewer, select Toggle Mesh Rendering and the Bed Elevation.


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 to digitise the upstream and downstream nodestrings:

  1. From the Layer Panel, select the 2d_ns_Riverine_Channel_000_L layer. Then, from the TUFLOW Plugin Toolbar, select Apply TUFLOW Styles to Current Layer . The layer symbology will now update.
  2. Zoom into the upstream boundary (refer to video).
  3. From the Toolbar select Toggle Editing and then select Add Line Feature .
  4. Digitise a line at the upstream boundary of the model domain (refer to video). Note remember always digitise from right bank to the left bank when looking downstream. 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.

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.

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 below steps and video to assign the material IDs:

  1. In window explorer navigate to Working\TUFLOWFV\model\gis then drag and drop 2d_mat_Riverine_Channel_000_R.shp into the QGIS workspace. Close the TUFLOW viewer as it is not needed in this section.
  2. Select the 2d_mat_Riverine_Channel_000_R layer in the layers panel and click Toggle Editing.
  3. From the Toolbar select the Identify Features tool and select the polygon identified as gravel in the above figure.
    • In the Identify Results dialog select Edit Feature form (refer to video).
    • In the Feature Attributes dialog set the Material to 1 and click OK.
  4. Using the Identify Features tool select the Sand polygon and set the Material to 2.
  5. Using the Identify Features tool select the Vegetation polygon on the right bank and set the Material to 3. Repeat for Vegetation polygon on the left bank.
  6. Select Save Layer Edits and Toggle Editing.
  7. Select Apply TUFLOW Styles to Current Layer and Apply Label to Current Layer from the Toolbar and review the material IDs.

In the TUFLOW FV Model Setup [MADDYTODO add hyperlink] section the Manning’s roughness values for each material type is defined in the TUFLOW FV control file.

TUFLOW FV Model Setup

Boundary Condition Time Series

This model uses an upstream inflow and a downstream tidal boundary, with the hydrodynamic boundary condition data provided in a .csv file. For TUFLOW FV, boundary condition datasets are typically in CSV (comma-delimited) format or NetCDF files, which can contain time-, space-, and sometimes depth-varying data. Review the boundary condition data files flow.csv and tide.csv located in the Working\TUFLOWFV\bc_dbase folder.

The figures below show the model boundary conditions: a water level timeseries (left) displaying a tidal signal with regular rising and falling water levels over about 48 hours, and an inflow hydrograph (rigth) representing a large flood event, where flow rises steadily to a peak of around 500 m³/s before falling back to zero. The impact of this flood event will be investigated further in the Reviewing Results section.

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 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 == 24.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\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 Riverine_Channel_000.fvc.
  5. Line 9 keeps the Windows prompt open, rather than closing it automatically after the simulation completes.
  6. 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).

Note: 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.

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.

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.  

The figure below is an example of the model log. Open the log file Working\TUFLOWFV\runs\log\Riverine_Channel_000.log and scroll to the bottom to view the simulation summary information. The information should appear as follows:

  • Input file: Specifies the location of the FVC file.
  • Log file: Specifies the location of the log file.
  • Computer name: Displays the name of the computer on which the model was run.
  • User name: Displays the username of the computer.
  • Execution Timestamps: The time the simulation started.
  • Execution Completed: The time the simulation finished.
  • Number of warnings = 0: Indicates the model run completed without warnings.
  • Run successful: Confirms that the simulation completed successfully without errors.
  • Exiting TUFLOWFV: Indicates that the TUFLOW FV engine has terminated — either after a successful simulation or due to an error.

Reviewing Results

The simulation has been configured to output NetCDF format results, with water levels, velocities, and water depths saved every 900 seconds (15mins). In this section, a longitudinal profile of the water surface elevation and time series of the modelled velocities and water surface elevation will be used to assess the model results.

Use the below steps and video to open the results, using the TUFLOW Viewer:

  1. Select the TUFLOW Viewer on the Toolbar.
  2. From the viewer select File>Load Results-Map Output and navigate to Working\TUFLOWFV\results\Riverine_Channel_000.nc.
  3. Review the output types under Result Types.


Long Section Plot

This section demonstrates how to extract a long section of water level and bed elevation from the simulation results, and reviews how the water level elevation changes throughout the simulation. Use the below steps and video to create the long section:

  1. Zoom into the mid section of the channel (refer to video).
  2. Select the Plot Cross Section drop down . From the drop down check bed elevation and water surface elevation.
  3. Select the Plot Cross Section button and your cursor should now become a crosshair [+]. Digitise a long section of the channel (refer to video) and right click to finish. Review the long section result in the plot window.
  4. Move through the time series to observe how the water surface elevation changes throughout the simulation in the plot window.
  5. Once finished clear the plot window .


Time Series Plot

This section demonstrates how to extract two timeseries from the results. The first tracks velocity at a specific point throughout the simulation and reviews velocity vectors across the model domain. The second examines how the interaction between the tide and flood wave affects water levels at the downstream boundary. Follow the steps and videos below to create the time series:

  1. Zoom into the mid section of the channel (refer to video).
  2. In the Result Type window select Velocity and velocity Vector map outputs.
  3. Move through the time series to observe how the velocity vectors change throughout the simulation.
  4. Select the Plot Time Series drop down and in the drop down check velocity.
  5. Select the Plot Time Series button and your cursor should now become a crosshair [+]. Digitise a time series point in the channel. Observe the velocity in the plot window, noting how it gradually increases as the simulation progresses.

Using a time series point, investigate how the interaction between the tide and the flood wave influences water levels at the downstream boundary:

  1. Zoom into downstream boundary (refer to video).
  2. Clear the plot window and for visualisation purposes select Bed Elevation and unselect Velocity vector from the Result Type window.
  3. Select the Plot Time Series drop down and in the drop down uncheck velocity and check water surface elevation.
  4. Select the Plot Time Series button and your cursor should now become a crosshair [+]. Digitise a time series point in the channel.
  5. Review the how the water surface elevation changes throughout the simulation. The typical tidal signal is clearly visible during the first ~18 hours, with regular peaks and troughs representing the incoming and outgoing tide. However, after approximately 18 hours, the tidal signature changes noticeably. This shift is caused by the significant inflow applied at the upstream boundary. As the flood wave approaches its peak, it alters the water surface elevation, resulting in a reduced tidal response.

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/s2) or (ft/s2)

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.

Use the following steps and videos to open and review the CSV file containing CFL diagnostic information generated by TUFLOW FV at successful model completion:

  1. From the Toolbar select Open Data Source Manager .
  2. In the Data Source Dialog box select Delimited Text.
  3. Using the File Name browser navigate to TUFLOWFV\input\log\Riverine_Channel_000_ext_cfl_dt.csv and select Open.
  4. Make sure the File Format is set to CSV (comma separated values).
  5. Check First record has field names and Detect field types fields.
  6. Set X field to x_ctrd, Y field to y_ctrd, and Z field to cfl_dt_min.
  7. Set the Geometry CRS to Project CRS: EPSG:32760 - WGS 84 / UTM zone 60S.
  8. Select Add and Close.


Before reviewing the models minimum timestep, update the symbology using the steps and video below.

  1. From the Layers Panel right click on Riverine_Channel_000_ext_cfl_dt and select Properties....
  2. In the Layer Properties dialog select Symbology.
  3. Under the symbology tab select Graduated and set the following:
    • Set the display Value to cfl_dt_min. Note cfl_dt_min is the the minimum allowable timestep for a given mesh cell.
    • Select Color ramp to Virdis then right click on the colour ramp and select Inver Color Ramp.
    • Set the classification Mode to Equal Count (Quantile).
    • Specify 10 Classes.
  4. Select Apply and OK.


You should now be able to see how the model minimum timestep varies across the model domain. Use the below steps and video to review to identify the cells that have the lowest timestep:

  1. In the Layer Panel, expand both layers to view the layer data..
  2. Right click on the Riverine_Channel_000_ext_cfl_dt data and select Toggle Items.
  3. To isolate the timestep-limiting cells, check the lowest class range (e.g.,0.178 - 0.33).
  4. Zoom into the channel and identify where the limiting time steps are. For this model, the limiting cells are in the deep water within the river bends. 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.

Going Further (Optional)

Mesh Design And Impact On Runtime

To demonstrate how mesh design influences model timestep, a second mesh file, Riverine_Channel_001.2dm, has been provided. In some cases, a modeller may need higher resolution along the channel banks to accurately represent steep gradients. Increasing mesh resolution in these areas can improve how well the model captures bank slopes. However, as mentioned earlier, finer mesh resolution can also reduce the model timestep and increase runtime. Therefore, it’s important to understand where high resolution is truly necessary and where it can be avoided. This section highlights how intentional changes to mesh resolution can affect model speed.

Follow the steps and video view the second mesh:

  1. From the TUFLOW Viewer select File > Load Results-Map Output and navigate to Working\TUFLOWFV\model\geo\Riverine_Channel_001.2dm.
  2. Right click on the new layer Riverine_Channel_000 > Properties. In the Layer Properties dialog select Source and from the assign CRS drop down make sure the project CRS EPSG:32760- WGS 84 / UTM zone 60S is assigned. Select Apply and Ok (refer to video).
  3. Zoom into the mesh review increased resolution at the channel banks. The Riverine_Channel_000 should still be open in the workspace, toggle the meshes and compare.


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.

Note: 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 figures presented here.

To run the batch file, double click on run_simulations.bat from Windows Explorer. Refer to demonstration in the previous Run TUFLOW FV section.

Reviewing The Mesh Refinement

To review how changing the mesh resolution influences the model timestep please review Riverine_Channel_001_ext_cfl_dt.csv. Open the file and set the symbology using the same steps in Reviewing Mesh Performance.

Compare Riverine_Channel_001_ext_cfl_dt.csv with Riverine_Channel_000_ext_cfl_dt.csv. The video below highlights the differences in the cfl_dt_min between the two meshes. Note that the lowest min_dt value is smaller in Riverine_Channel_001_ext_cfl_dt.



  • How has the model timestep changed in areas where the mesh resolution was changed?
  • Where are the timestep-limiting cells located? Is this different to the previous model?

You should see that the time step 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.

Retrieved from "https://fvwiki.tuflow.com/w/index.php?title=Modelling_M02_video_draft&oldid=17504"