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 demonstrates the development of a 3D estuary model. Starting with a 2D model, the tutorial will progressively increase in complexity, incorporating 3D geometry and density effects to observe stratification. Additionally, the tutorial includes visualising results using the TUFLOW FV MATLAB and Python Toolboxes.
Unlike the previous tutorial modules, Tutorial Module 05 directly provides you with a full set of working model files that you can re-run and experiment with 3D visualisation tools.
The tutorial can be broken up into the following sub-sections:
Setup TUFLOW FV
This tutorial recommends the use of TUFLOW FV 2020.03.105, available on the TUFLOW Downloads Page. Please download TUFLOW FV 2020.03.105 and save to C:\TUFLOWFV\2020.03.105\ or your preferred location.
This demonstration model dynamically couples TUFLOW FV with GOTM to model vertical turbulence exchanges.
To dynamically couple GOTM and TUFLOW FV, 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 your TUFLOWFV.exe (for example, C:\TUFLOWFV\2020.03.105\).
Tutorial Data Download
The data download for this model is available from the TUFLOW Website.
The following folders have been provided for this tutorial:
- Complete_Model: Contains the model setup for the hydrodyamic models covered in this tutorial. Further information regarding the contents of the Complete_Model folder is included below.
- Analysis: This folder will include the Python or MATLAB scripts to post-process the results of the models.
Complete Model Folder Contents
In the Complete Model folder the model set up for all three models is included in the folder TUFLOWFV and 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.
The folder structure for the Complete_Model folder should resemble the folder structure shown below (Note: The AED2 folder has been removed. This tutorial will be upgraded over time to use the TUFLOW FV Water Quality Module):
Upstream And Downstream Boundary Condition Files
To understand the contents of the boundary condition .csv files, open \bc_dbase\Downstream_H_Temp_Sal_Sed_001.csv.
Specified in this .csv file are values for key variables of the TUFLOW FV model. These values span the duration of May 2011, and therefore cover the desired simulation period (first week of May). As these values are located at the downstream boundary of the estuary, they can be linked to the .2dm mesh via association with a nodestring.
Model Mesh File
If you open the model mesh file Complete_Model\TUFLOWFV\model\geo\hydraul_006.2dm in SMS, you will see the mesh for the estuary. You will notice there are no nodestrings on the mesh. This is because this model has been configured using QGIS, whereby nodestrings are defined using GIS SHP files in the FVC. For additional information regarding configuring a model this way, please refer to Configure model using QGIS.
Meteorological NetCDF Files
The meteorological data for the model is stored in NetCDF files located in the folder Complete_Model\TUFLOWFV\bc_dbase\met\. As meteorological data varies spatially, it is preferable to use gridded data for an environment the size of the estuary. This data will include values for key meteorological inputs at a series of locations for the duration of the simulation time period. The NetCDF file format is ideal for this application as it possible to store data in different dimensions. Below is a depiction of how a NetCDF file for long wave radiation can be interpreted by MATLAB (using the ncdisp command):
As shown above, the NetCDF data includes 745 time values, 3 longitude values and 3 latitude values, resulting in a 3x3x745 grid. This example snapshot shows longwave radiation data. NetCDF data is read onto the mesh at the simulation initialisation via BC grid definition blocks. For more information, consult the grid definition block syntax in the met include file.
Summary Of Model Setups
The FVC files for the models covered in this tutorial are located in the Complete_Model\TUFLOWFV\runs directory. Descriptions of these models and the associated results analysis are provided in the following sections.
For information regarding the syntax and command updates made to each model FVC, please follow the links provided in the table below.
| HYD_000 | Initial 2D hydrodynamic model without density coupling, atmospheric heat, or meteorological data. |
| HYD_001 | Basic 3D hydrodynamic model with hybrid z-sigma layering, atmospheric heat and meteorological data added (no density coupling). |
| HYD_002 | 3D hydrodynamic model with density coupling to heat and temperature. |
3D Visualisation Setup
This tutorial uses visualisation toolboxes that assist with the viewing and processing of 2D and 3D TUFLOW FV results. Both a Python toolbox and a MATLAB toolbox are available.
You will need to download and set up your preferred option. For more information on how to complete the set up process for each of the toolboxes, please follow the relevant link below:
Initial 2D Model
As a starting point, the model HYD_000.fvc provides a basic 2D hydrodynamic model without density effects, atmospheric heat, or meteorological data enabled.
For a detailed description of the commands and syntax in the FVC file, please refer to HYD_000.
Results have not been provided with the data download package and you will need to run HYD_000 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 repath to the version of TUFLOW FV you have downloaded and updated as defined in Setup TUFLOW FV. Feel free to run one model at a time or all at once in sequence.
2D Model Results
In this section we are going to visualise a simple timeseries by post-processing the model NetCDF with your preferred visualisation toolbox.
Please note that it is also possible to extract timeseries and profile information during simulation. Steps on how to do this are provided in the Customising Output Chapter of the TUFLOW FV User Manual.
Writing Profile Outputs And Creating Timeseries Plots
To produce a timeseries we need to first post-process a profile NetCDF file from the raw TUFLOW FV results.
The profiles file will include simulation results located at a series of pre-specified output sites.
In order to produce a profiles file using either of MATLAB and Python, please follow the relevant link below:
A 2D variable timeseries plot allows you to view the time series of a single variable at a single location. In order to produce this plot, a profile file must first be written (refer Writing a profile NetCDF file). To produce a timeseries plot for the HYD_000 results using either of MATLAB and Python, please follow the relevant link below. This link also includes a discussion of the observed results:
Timeseries Discussion
Having run the timeseries plot script at point 4, you should see the following plot:
Point 4
What causes the oscillation?
In the bc 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 is brought in, and falls with the ebb tide back towards the upstream temperature of 10 degrees. This illustrates the effect that boundary conditions will have on a model.
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 at point 4 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.
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 sheet plot with vectors to see how the results are varying both spatially and temporally.
An example of a sheet plot with vectors is shown below:
As shown above, during ebb tide, the vectors indicate a surge in flow downstream. During this time, the temperature is shown to fall toward the upstream temperature. Conversely, during flood tide, the vectors indicate a surge in flow upstream. During this time, the temperature is shown to rise back toward the downstream temperature.
3D Model Simulation And Visualisation
Although useful for many applications a 2D model neglects vertical transfers or variation in velocity with depth.
In order to model features such as density driven flows, vertical mixing, turbulence, stratification and conduct complex water quality modelling a 3D model is often required.
3D Model With No Density Coupling
HYD_001 is a 3D hydrodynamic model with vertical hybrid z-sigma layering, atmospheric heat and meteorological data added. HYD_001 does not however allow the flow to be affected by density gradients, in this case due to the influences of temperature and salinity (sediment can also affect density if chosen to). The required syntax updates to HYD_000.fvc to update to 3D are detailed on the page HYD_001. Further discussion of the various model updates is outlined in the following sections.
3D Geometry Command Updates
There are 3 methods of vertical discretisation in TUFLOW FV:
- Sigma
- Z
- Hybrid Z-Sigma
In this example hybrid Z-Sigma coordinates are used. The layer faces file specifies 10 z layer interface levels. The z levels are specified at elevations that are always wet at each cell and this is required to avoid instabilities. Above these there are 4 sigma layers that are equally distributed between the upper z layer and the water surface.
The minimum bottom layer at the bed is set to be 0.5m to avoid any thin vertical layering close to the bed (and 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, particually if models exhibit wetting and drying areas such as this model.
Vertical Mesh Type == z Layer Faces == ..\geo\3D_Z_Layers_003.csv Sigma Layers == 4 Min Bottom Layer Thickness == 0.5 Cell 3D Depth == 1.0
Meteorological Boundary Conditions
Heat fluxes between the water surface and the atmosphere are handled by TUFLOW FV's heat module (a component of the Advection Dispersion Module). Typical meteorological inputs include winds, radiation fluxes, air temperature and relative humidity. The required inputs are a function of the selected heat model. It is common for regional meteorological model or climate reanalysis data to be provided as input to TUFLOW FV as is shown in the example. The process of assigning meteorological data onto the mesh is conducted in the file: Complete_Model\bc_dbase\met\MET_2011.fvc. The link to this file is given in the ‘include’ line:
!MET include == ..\bc_dbase\met\MET_2011.fvc
If you open this file in a text editor you can see the following commands:
As shown above, the grid definition commands read the longitude and latitude variables from the NetCDF file, and save the mapping to the ‘ncep’ grid label.
grid definition file == ./NPD_NCEP_CFSR_dlwr_May2011.nc grid definition variables == lon, lat grid definition label == ncep end grid
This ncep grid is then used to link the bc data (time, dswr) to the mesh.
bc == SW_RAD_GRID, ncep, ./NPD_NCEP_CFSR_dswr_May2011.nc bc header == time,dswr bc update dt == 900. bc time units == hours bc reference time == 01/01/1990 00:00 end bc
Note: There are 3 grids defined and used in the MET_2011.fvc file. This is because 3 different grids were used among the various NetCDF met files.
Run 3D Model With No Density Coupling
If you've reviewed the model setup and wish to visualise 3D results please run TUFLOW FV for HYD_001.fvc.
For assistance with running the model, please refer to Running TUFLOW FV for a detailed description of the various methods for running a TUFLOW simulation.
3D Simulation Results
Profile Plot
A profile plot can allow you to view a variable through the vertical at a given time. This can then be animated with the time slider bar provided in the MATLAB figure. In order to produce a profile plot in MATLAB, you must first post process a profile file (refer Writing a profile NetCDF file, noting the the creation of a profile file is optional using the Python Toolbox as they can be processed on the fly).
To produce profile plots for the HYD_001 results, please follow the link below. This link also includes a discussion of the observed results.
Profiles Discussion
Having run the profiles plot script you should see the following plots:
HYD_000: 2D model
HYD_001: 3D model
As shown above, once layers are included in HYD_001, there is vertical variation in salinity. However, as shown in the plot for HYD_001, the deeper water appears to be less saline. Is this what should happen in an estuarine environment? No. This is because density coupling has not been included in HYD_001. In reality you would expect to see an increase in salinity at lower depths, due to the increased density of salt water.
3D Model With Density Coupling
Until now the effects of temperature or salinity of water density have not been modelled. In this example model we will switch on density coupling. At the downstream boundary a saline tidal boundary is applied and upstream a cool, freshwater inflow that results in the formation of a salt wedge as the freshwater flows over the dense salty water. This section explores the visualisation of the example salt wedge.
FVC Updates With Density Coupling
Syntax additions to HYD_001.fvc are detailed on the page HYD_002 . As with previous models please run the HYD_002.fvc so we can experiment with result visualisation.
3D Density Coupling Results
Curtain Plot
A curtain plot can allow you to view a variable along a cross section as a function of chainage and depth (with time slider bar).
To produce a curtain plot for the HYD_002 results, please follow the link below:
An example of a salinity curtain plot for the HYD_002 model, produced in MATLAB, is shown below:
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.
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.
Conclusion
Congratulations. We've covered a lot in this tutorial, including several 2D and 3D visualisation techniques of hydrodynamic outputs.
To complete more tutorials or learn more tips and tricks, please return to the TUFLOW FV Wiki Mainpage.