Tutorial Module05

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

Tutorial Module 05 investigates temperature and salinity stratification in a small estuary model. The key objective of the tutorial is to demonstrate 3D visualisation techniques of TUFLOW FV results using the TUFLOW Viewer Plugin for QGIS.

Unlike the Tutorial Modules 01 to 04 that provide step-by-step model build instructions, Tutorial Module 05 provides you with a full set of working model files that you can re-run and use to experiment with. Starting with a 2D model, the models we review will progressively increase in complexity, incorporating 3D geometry and density effects to observe stratification. Results will be reviewed using the TUFLOW Viewer Plugin for QGIS.

The tutorial includes the following sub-sections:

• Setup TUFLOW FV for Simulation
• Requirements and Downloads
• Model Overview
• Model Setup
• Run the Models
• Reviewing 2D Model Results
• Review of Density Stratification - 3D Result Visualisation

Setup TUFLOW FV

This tutorial recommends the use of TUFLOW FV 2023.0 or later, available on the TUFLOW Downloads Page. Please download TUFLOW FV and save to C:\TUFLOWFV\ or you preferred location.
This demonstration model dynamically couples TUFLOW FV with GOTM to model vertical turbulence exchanges. To do so, please download the TUFLOW FV External Turbulence API. Once downloaded, unzip the file .\GOTM\tuflowfv_external_turb.dll and replace the default tuflowfv_external_turb.dll that resides in the same directory as TUFLOWFV.exe (for example, C:\TUFLOWFV\2023.0\).

Requirements and Downloads

Requirement	Brief Description	Download
TUFLOW FV	TUFLOW FV is a 1-dimensional, 2-dimensional, and 3-dimensional flexible mesh finite volume numerical model that simulates hydrodynamic, sediment transport and water quality processes in oceans, coastal waters, estuaries and rivers. It is recommended to always use the latest release version of TUFLOW FV. This tutorial model does not require a TUFLOW FV licence.	TUFLOW FV Latest Release
GOTM model	GOTM is a 1D vertical turbulence closure model. It can be coupled to TUFLOW FV using the external vertical mixing model option. Once downloaded, unzip the file .\GOTM\tuflowfv_external_turb.dll and replace the default tuflowfv_external_turb.dll that resides in the same directory as TUFLOWFV.exe (for example, C:\TUFLOWFV\2023.0).	TUFLOW FV External Turbulence API
QGIS QGIS TUFLOW plugin	For this tutorial we will be using QGIS to view results. This tutorial was developed with QGIS 3.28. It is recommended to have QGIS 3.28 or later to ensure compatibility with TUFLOW plugin latest features. The TUFLOW plugin includes numerous tools to increase workflow efficiency.	QGIS can be download from Latest 64-bit version of QGIS QGIS TUFLOW Plugin Installation
NotePad++ Syntax Highlighting	A text editor is required for creation of the TUFLOW FV input files. This tutorial was developed with NotePad++. Ideally a text editor should be able to: Colour code the TUFLOW FV control files; Open other files from the active control file; and Launch a TUFLOW FV simulation. TUFLOW colour coding can be enabled using syntax highlighting.	Latest 64-bit version of Notepad++TUFLOW syntax highlighting for Notepad++ For instructions on configuring Notepad++ for TUFLOW modelling, see Notepad++ tips
Model Data	The data provided for the completion of this tutorial includes the set up for all three models. The data provided in the Complete_Model folder includes: 2dm model mesh file ‘hydraul_006.2dm’ (model\geo folder) 3D layer .csv file (model\csv folder) Supporting GIS files for nodestring and material definition (model\gis folder) GIS empty files for adding features to the model (model\gis\empty folder) Boundary condition data, in .csv and .nc format (bc_dbase and bc_dbase\met\ folders) Meteorology FVC file (bc_dbase\met\ folder) Sediment file FVSED for modelling sediment fluxes (runs folder) Please note results are not provided as part of this tutorial data package. You will need to run the models to produce them.	TUFLOW FV Tutorial Models
Assumed Knowledge	This tutorial assumes you have completed Tutorial Modules 01 to 04, and are familiar with using TUFLOW FV. If you run into any problems or need help, please contact support@tuflow.com	Not Applicable

Model Overview

In estuarine environments, it is common to observe the formation of a 'salt wedge' where less dense freshwater fluxes from the catchment flow over the top of more dense saltwater. For more information on salt wedge estuaries, there's a good summary on the Coastal Wiki.

Modelling the contribution of salinity and temperature to horizontal and vertical density gradients is key to modelling a salt wedge estuary well. Reproducing density gradients requires the 3D simulation of flows, salinity and temperature, atmospheric heat exchange and careful consideration of vertical mixing.

In this demonstration, the results of three models are investigated. Each model simulates temperature and salinity in a different way. Reviewing our model results will show us the impact that these different ways have on our salt wedge formation. The models include:
1. 2D hydrodynamics only with temperature and salinity modelled as passive tracers only.
2. 3D hydrodynamics with temperature and salinity without density coupling.
3. 3D hydrodynamics with temperature and salinity with density coupling.

The TUFLOW FV control files (.fvc) for the models for this tutorial are located in the Complete_Model\TUFLOWFV\runs directory. For information regarding the syntax and command updates made to each model FVC, please follow the links provided in the table below:

HYD_000	2D hydrodynamics only with temperature and salinity modelled as passive tracers only.
HYD_001	3D hydrodynamic without temperature and salinity density coupling.
HYD_002	3D hydrodynamic with density coupling to salinity and temperature.

Model Setup

In this section we will review key components of the model setup.

The folder structure for the Complete_Model folder should contain the following structure:

Model Mesh File

The estuary model mesh comprises a combination of quadrilateral and triangular elements. To review the mesh bed elevation and materials, please step through the below sections.

Firstly, open QGIS and save a project called "Tut_05.qgz" into the Complete_Model folder.

Now we will open the hydraul_006.2dm mesh file. Please use the below steps:
1. Please launch the TUFLOW Viewer by clicking the viewer button from your toolbar.
2. In your File Explorer window, navigate to Complete_Model\TUFLOWFV\model\geo\. Now drag and drop the hydraul_006.2dm file into your QGIS workspace.

Your workspace should look similar to the below:

To review the mesh bed elevation, please use the below steps:

1. In the TUFLOW Viewer, select the Toggle Mesh Rendering .

2. In the Result Type > Map Output window, right click on Bed Elevation and then select Properties.

3. In the Symbology window, please specify the Min and Max display values as -15.00 & 5.00.

4. From the Color ramp dropdown, please select Create New Color Ramp...

5. The Color ramp type dialog will now appear. From the dropdown, please select Catalog: cpt-city and then select OK.

6. You will now see the cpt-city has many colour ramps to choose from. For this tutorial, please click on the Bathymetry palettes. Select the GMT_ocean colour ramp and then OK > Apply > OK.

Your workspace should look similar to the below. Please take your time to zoom in and review the mesh bathymetry.

Now we will review where different materials have been assigned throughout the mesh. Please follow the below steps:

1. This time, in the Result Type > Map Output, right click on the Material ID and select Properties.

2. In the Symbology window, please change the Resampling method to None and then select OK.

Now if you zoom into the mesh, you will be able to see where different materials have been assigned.

Upstream and Downstream Open Boundary Conditions

For the purposes of this demonstrative model, the downstream boundary applies a water level astronomical tide signal with a constant salinity and temperature of 35 ppt and 20^o C respectively. To review the boundary condition data, you can open \bc_dbase\Downstream_WL_001.csv in Excel or in your preferred text editor. The time series span the duration of May 2011, and therefore cover the desired simulation period (first week of May).

At the upstream boundary, a constant inflow of 20m³/s was applied with 0 ppt salinity (fresh water) and a constant temperature of 10^o C. To review the boundary condition data, you can open \bc_dbase\Upstream_Q_001.csv.

Meteorological Boundary Conditions

The meteorological data for the model is stored in the NetCDF file Complete_Model\TUFLOWFV\bc_dbase\met\CFSR_20110401_20110701_AEST.nc. The data has been sourced from CFSv2 model output downloaded using the GetAtmos Python command line interface tool as follows:

GetAtmos A "2011-04-01 00:00" "2011-06-01 00:00" Xmin Xmax Ymin Ymax --source CFSR

Please note we've withheld the coordinates used to shift the location of the model but if you were running GetAtmos, you would replace Xmin, Xmax, Ymin, Ymax with the longitude and latitude values for your study area. For further examples on using GetAtmos, please refer to the GetAtmos Gitlab Page and the TUFLOW FV Python Toolbox Page.

As meteorological data varies spatially, it is preferable to use gridded data for an environment the size of the estuary. For a 3D simulation including atmospheric heat exchange, TUFLOW FV requires the following variables and units:

• 10m 10min wind speed (m/s)
• Mean sea level pressure (hPa)
• Incident downward shortwave radiation (W/m²)
• Incident downward longwave radiation (W/m²)
• Air temperature (^oC)
• Surface relative humidity (%)

The GetAtmos tools will automatically generate the required TUFLOW FV boundary condition blocks for simulation. Please review the contents of Complete_Model\TUFLOWFV\bc_dbase\met\CFSR_20110401_20110701_AEST.fvc to see how the gridded meteorological boundary conditions are being applied. Note the use of the bc scale command to convert mean sea level pressure from pascals to hectopascals, and the bc offset command to convert from degree Kelvin to degrees Centigrade.

To review our meteorological inputs, we can open the NetCDF in QGIS. Please complete the following steps:

1. To open your results, please select File > Load Results-Map Output and navigate to Complete_Model\TUFLOWFV\bc_dbase\met\CFSR_20110401_20110701_AEST.nc

2. Use the shift key to select both wind_10m and wind_10m Vector within the TUFLOW Viewer > Result Type panel.

3. Tick the Show as dates box to display the time slider in date and time format.

4. Slide the time slider forward to view how the wind speed and direction changes during the months of April and May.

Note that the model domain is well within the spatial extent of our boundary conditions. Try experimenting with the other inputs such as downward shortwave radiation, air temperature and mean sea level pressure.

3D Model Updates

For a detailed description of the commands and syntax in the FVC file, please refer to HYD_001 and HYD_002. Two key updates are the addition of 3D geometry and vertical mixing commands.

Vertical Discretisation

There are 3 methods of vertical discretisation in TUFLOW FV:

1. Sigma
2. Z (Fixed Z)
3. Hybrid Z-Sigma

In this example, hybrid z-sigma coordinates are used as follows:

• The layer faces file specifies 10 fixed z levels that define the faces between vertical cells. Open the file Complete_Model\TUFLOWFV\model\csv\3D_Z_Layers_003.csv in a text editor and review the contents. The values in the file range from -16m to -3m (reduced level model datum). Fixed z layers do not support wetting and drying, so it is important that the face elevation levels you specify remain always wet throughout the simulation. In our model, the tide never falls below -3m and therefore our z layers never dry out.
• Above -3m (reduced level model datum) we have specified that there will be 4 surface sigma layers that are equally distributed between -3m (reduced level model datum) and the water surface. These 4 sigma layers expand and contract during the simulation in response to the local water level and also allow cells to wet and dry.
• The minimum bottom layer at the bed is set to be 0.5m to avoid any thin z-layers between the bottom layer face and the bed (and avoid the associated small timestep).
• The cell 3D depth command causes areas where the depth is less than 1m to revert to a 2D flux calculation and can improve model stability and runtimes, particularly if models exhibit wetting and drying areas (such as within this model).

The relevant 3D geometry commands are shown in the TUFLOW FV command syntax snippet below:

Vertical Mesh Type == z
Layer Faces == ..\model\csv\3D_Z_Layers_003.csv
Surface Sigma Layers< == 4
Min Bottom Layer Thickness< == 0.5
Cell 3D Depth == 1.0

Vertical Mixing

To enable mixing of turbulence, and scalar fields such as temperature and salinity, we need to include vertical mixing model commands in our control file. For this model we are using the k-epsilon option from GOTM.

! Vertical Mixing
Vertical Mixing Model == external
Global Vertical Eddy Viscosity Limits == 1.0e-4, 1.0
Global Vertical Scalar Diffusivity Limits == 0., 1.0
External Turbulence Model Directory == ..\GOTM\
Turbulence Update dt == 1800

Run The Models

Results have not been provided with the data download package and you will need to re-run the models to obtain them. To do this, you can refer to Running TUFLOW FV for a detailed description of the various methods for running a TUFLOW FV simulation. A template batch file is provided in the Complete_Model\TUFLOWFV\runs folder. Within this batch file, you will need to re-path to the version of TUFLOW FV you have downloaded and updated as defined in Setup TUFLOW FV. Please run all three model simulations, noting this may take 10-15 minutes depending on your computer hardware.

Reviewing 2D Model Results

In this section we will review the 2D only model temperature results of simulation HYD_000.fvc via some 2D timeseries and plan view sheet plots.

Creating Timeseries Plots

A 2D variable timeseries plot allows you to view the time series of a single variable at a single location. In this section we will create a timeseries plot of Temperature from the HYD_000 model results.

To open your results, please select File > Load Results-Map Outputs and navigate to results\HYD_000.nc.

Your project window will now look similar to the below:

To extract your temperature timeseries from HYD_000, please use the following steps:
1. In the Result Type window, select the temperature result.
2. Select the Plot Time Series drop-down and in the drop-down check temperature.
3. Now select the Plot Time Series tool and your cursor should now become a crosshair [+].
4. Click on your desired location within your result, as shown by the arrow and red dot in the below figure.

Having used the Plot Time Series tool, you should a similar plot to the below in your time series window:

Do you notice how the temperature oscillates throughout the simulation?

What causes the oscillation?

In the bc_dbase folder, open the files Upstream_Q_Temp_Sal_Sed_001.csv and Downstream_H_Temp_Sal_Sed_001.csv.

Observe that the upstream temperature is set to 10 degrees, while the downstream temperature is set to 20 degrees. The oscillation in temperature is caused by the tide, where the temperature surges during flood tide as 20 degree water enters the model from the downstream boundary, and falls with the ebb tide back towards the upstream temperature of 10 degrees.

How does the initial temperature affect the simulation?

Recall that the initial temperature for the model was set to 20 degrees in the line:

Initial Temperature == 20.

However, as visible in the timeseries plot, the temperature in the timeseries approaches a value closer to 11 degrees by the end of the simulation. With an upstream temperature of 10 degrees and a downstream temperature of 20 degrees, it is natural that there should be an observable temperature gradient through the estuary. However, this temperature gradient will only become visible once the model has run for enough time for the boundary conditions to overwrite the initial global temperature. In this way, a timeseries plot can provide insight to when a model converges towards a steady state. Given that the model temperature quickly diverges from the initial condition, is our selection of initial temperature suitable for this system? Most likely not. Try running the model again with an initial condition of 15 degrees and see how this affects the system.

Creating a 2D Plan View Map (Sheet Plot)

As identified in the timeseries plots, oscillations in temperature are observed. We make the assumption that this is due to the effect of the tide. However, when reviewing results, you should never just look at time series to get a good appreciation of what is happening. To further investigate, we will create a contoured plan view map (a sheet plot in TUFLOW FV nomenclature) with vectors to see how the results are varying both spatially and temporally.

Firstly, clear the timeseries plot you made in the previous section by right clicking on the timeseries plot and selecting Clear Plot Window. Now use the following steps to create a 2D plan view map:

1. In the Result Type, use the shift key select both temperature and velocity Vector.
2. Now drag the timestamp to see how temperature and velocity vectors vary both spatially and temporally throughout the model.
3. Notice you can also use the Next Timestep and Play Through Timesteps buttons to visualise the results for the entire simulation.

As shown below, during ebb tide, the vectors indicate a surge in flow downstream. During this time, the temperature is shown to fall due to cold water flowing downstream. Conversely, in the bottom panel of the figure, showing the model during flood tide, the vectors indicate a surge in flow upstream. During this time, the temperature rises due to the influence of the downstream boundary and initial conditions.

Review of Density Stratification - 3D Result Visualisation

In this section we will:

1. Compare 2D and 3D salinity results via a vertical profile plot.
2. Investigate the impact of enabling density coupling by comparing long section curtain plots of our 3D results.
3. Undertake depth averaging at different 3D depths and display the results as a plan view sheet plot.
4. Extract time series of salinity at different depths.

Reviewing 3D Results With A Vertical Profile Plot

A profile plot allows you to view a variable through the vertical water column at a particular model timestep. In this section, we will compare the salinity profile of the 2D model HYD_000 with the 3D model HYD_001 results. Please make sure that the HYD_000.nc result is still open in your QGIS project window. Open the HYD_001.nc result file via the QGIS TUFLOW Plugin.

Using the below steps, create a salinity profile plot of the 3D model results:
1. In the Open Results window, select HYD_001.
2. In the Result Type window, select salinity.
3. Under the Vertical Profile dropdown , select salinity.
4. Select the Vertical Profile tool. Your cursor should now become a crosshair [+].
5. Click on your result in a similar location to that shown by the arrow in the below figure.
6. Now review your salinity profile result.

Now we will compare the salinity vertical profile of the 3D model to the 2D model. To do this, hold down shift and select both HYD_001 and HYD_000 in Open Results. Your plot should look similar to the below:

The 2D depth averaged model only has one value per model cell. By enabling the model in 3D, we get vertical variation in salinity. However, as HYD_001 does not include density coupling, this result does not include key hydrodynamic forcings required to represent stratification in the estuary.

Next, we will investigate the effect of adding density coupling to our 3D model setup.
1. Open the results file HYD_002.nc via the TUFLOW Viewer Plugin.
2. Follow the steps above to extract a salinity profile, this time near the downstream boundary.
3. Ensure that the three results are selected in the Open Results panel of the TUFLOW Viewer.
4. Move the time slider to 01/05/2011 05:00:00

As you can see, the effect of density coupling on the vertical profile is significant. Near the surface, the initial condition salinity of 10 ppt remains. At depth, the saltwater wedge moves upstream with the incoming tide, resulting in a heavily stratified flow field.

As you can see, the effect of density coupling on the vertical profile is significant. Near the surface, the initial condition salinity of 10 ppt remains. At depth, the saltwater wedge moves upstream with the incoming tide, resulting in a heavily stratified flow field.

Creating Curtain Plot

To further investigate the propagation of the salt wedge, we can extract and review 3D cross sections (or long sections) from our results using a curtain plot. A curtain plot can allow you to view a variable as a function of chainage and depth (with a time slider bar). In this section, we will create a salinity curtain plot from the 3D density coupled model result HYD_002.

To produce a salinity curtain plot for the HYD_002 results, please follow the below steps:
1. In the Open Results window, select HYD_002.
2. In the Result Type window, select salinity.
3. Under the Curtain Plot dropdown, select salinity.
4. Select the Curtain Plot tool. Your cursor should now become a crosshair [+].
5. Now take a long section from the downstream boundary to the upstream boundary.
6. Review your salinity curtain plot.
7. Now use the time stamp controls to review how salinity changes temporally and spatially throughout the model.

As shown above, now that density coupling is included in the model, a salt wedge is clearly visible. As density is now treated as a function of temperature and salinity, the heavier salt water is seen to lie below the freshwater, creating a wedge. This behaviour is common in an estuarine environment where fresh and salt water mixing occurs.

Using Sheet Plots With Different 3D Depth Averaging Methods

Although our results are 3D, when we look at a plan view plot, we can only visualise a depth averaged slice. This section will show you how to apply different depth averaging methods using the TUFLOW Viewer Plugin.

1. In the Open Results panel, select the HYD_002.
2. In the Result Type panel, select salinity.
3. Right click on salinity and then select Properties.

4. Navigate to the Stacked mesh averaging method tab to view the Average 3D Stacked Mesh Results to 2D Dataset Values section.
5. You will note that the default is Sigma, with Start fraction 0.00 and End fraction 1.00. This is a depth averaged 3D visualisation over the full water depth, where 0.00 is the bed level and 1.00 is the water surface.

6. Now change the End fraction value to 0.20. This will show the salinity in the bottom 20% of the water column.

Below is a figure comparing the map results of the full depth average to the map results of the bottom 20%. We see that there are higher salinity concentrations in the bottom 20%, as indicated by the yellow colouring of the figure in the right-hand panel. This implies that water is far saltier near the bed due to the effects of density stratification.

Try experimenting with some of the other depth averaging methods. For more information on the methods available, please refer to our Depth Averaging Results page.

Plotting Timeseries with Different 3D Depth Averaging Methods

In this section we will extract time series results of salinity using different vertical depth averaging methods.

1. In the TUFLOW Viewer Plugin, navigate to the 3D to 2D Averaging Timeseries tool and click the dropdown.
2. From the dropdown options, select Sigma.
3. Use the Add Additional... button to add two new fields. You should now have three fields. Set each of them to the variable salinity. Update the Start Fraction and End Fraction to be given by the following three pairings: (0.0, 1.0) (0, 0.2) and (0.9, 1.0). This will depth average the results over the full water depth, the bottom 20% and top 10% respectively.

Now that we have specified our result type and vertical averaging method, we can create our time series plot:

4. Select the 3D to 2D Averaging Timeseries tool. Your cursor should now become a crosshair [+].
5. Select a location on the results similar to point 2 shown in the figure below.

The resultant timeseries plot shows us that the saltiest water is at depth, with less salty water near the surface.

Going Further - Water Quality Application

The constructed model, HYD_002, may be coupled with a water quality model in order to simulate the behaviour of various water quality constituents.
If you wish to learn how to incorporate water quality into the HYD_002 model, please complete Tutorial Module 09.

Going Further - TUFLOW FV Python and MATLAB Toolboxes

If you'd like to try out the estuary model results within our TUFLOW FV Python or MATLAB Toolboxes please check out the following pages:

• TUFLOW FV Python Toolbox
• TUFLOW FV MATLAB Toolbox

Conclusion

In this tutorial we have explored an idealised stratified estuary case study. We have used several 2D and 3D model result visualisation and review techniques within the TUFLOW Viewer Plugin for QGIS, including:

• 2D time series
• 2D sheets
• 3D profiles
• 3D curtains
• 2D depth averaged 3D result sheets
• 2D depth averaged 3D result time series

We hope that you find these tools useful for your projects. To complete more tutorials or learn more tips and tricks, please return to the TUFLOW FV Wiki Mainpage.