Tutorial Module05

Jump to: navigation, search

Tutorial description

Unlike the previous tutorial modules Tutorial Module 05 directly provides you with a full set of working model files which you can re-run and experiment with our 3D visualisation tools. Tutorial Module 05 demonstrates the development of a 3D estuary model. Starting with a 2D model the tutorial will progressively increase in complexity incorporating layers and baroclinicity to observe stratification. Additionally, the tutorial includes visualising results using MATLAB and Python scripts.

The tutorial can be broken up into the following sub-sections:

  • Setup TUFLOW FV for Simulation
  • Overview of Provided Data Files
  • Summary of Model Setups
  • Timeseries from 2D Model Results
  • 3D Demo and Visualisation Toolsets
  • Water Quality Demo and Visualisation Toolsets
  • Running each model. No results are provided so you will need to re-run each model to use with the provided example scripts
  • Using the various script files to interrogate and review results

    Setup TUFLOW FV

    This tutorial requires version 2019.01.008 or later. You can download the latest TUFLOW FV build from the TUFLOW Downloads Page

    External Water Quality and Turbulence Model Coupling

    This demonstration model dynamically couples TUFLOW FV with the AED2 water quality model and GOTM turbulence closure schemes. For more information on AED2 and GOTM please refer to the following links:

  • GOTM
  • AED2
  • Update TUFLOW FV DLLs

    In order to link the external 3D water quality and turbulence closure schemes required for this model we need to update two TUFLOW FV files in our TUFLOW FV engine folder. This folder is a user specified saved location, commonly similar to C:\TUFLOWFV\2019.01.008\
    To update please save over the two dll as per the following process:
    Replace the default tuflowfv_external_turb.dll included with the TUFLOW FV download from the TUFLOW Website with the one provided within: https://www.dropbox.com/s/f1cwkx72l1896mb/tuflowfv_external_turb.zip?dl=0
    Replace the default tuflowfv_external_wq.dll included with the TUFLOW FV download from the TUFLOW Website with the one provided within: http://aquatic.science.uwa.edu.au/research/models/AED/Pages/down_tfv_bin.php refer tuflowfv_external_wq-1.3.0.zip

    Dlls for aed2 turb.jpg

    Tutorial Data Download

    The data download for this model is available from the TUFLOW Website Tutorial Module Download.

    The following folders have been provided for this tutorial:

    • Complete_Model: Contains the model setup for the hydrodyamics and water quality 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 six 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),
    • Water quality and GOTM nml files (AED2 and GOTM folders).

    The folder structure for the Complete_Model folder should resemble the folder structure shown below:
    TFV mod5 01 v2.jpeg

    Upstream and Downstream BC files

    To understand the contents of the boundary condition csv files, open the file \bc_dbase\Downstream_H_Temp_Sal_Sed_001.csv.

    TFV mod5 downstream bc.jpg

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

    2dm model mesh file

    If you open the model mesh file 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 info regarding configuring a model this way please refer to Configure model using QGIS.

    TFV mod5 mesh v2.JPG

    Meteorological NetCDF files

    The meteorological data for the model is stored in NetCDF files located in the folder ..\bc\met\. As met 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 met inputs at a series of locations for the duration of the 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):

    TFV mod5 ncdisp.jpg

    As shown above, the NetCDF data includes 745 time values, 3 longitude and 3 latitude values resulting in a 3x3x745 grid. In this example snapshot it shows longwave radiation data. NetCDF data is read onto the mesh at the simulation initialisation via BC grid definition blocks. For more information you can check out the grid defintion 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. A description of these models and the associated results analysis is 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 baroclinicity, atmospheric heat, or meteorological data.
    HYD_001 Basic 3D hydrodynamic model with hybrid z-sigma layering, atmospheric heat and meteorological data added (still no baroclinicity ).
    HYD_002 3D hydrodynamic model with baroclinicity enabled.
    WQ_000 Basic 3D water quality model with water quality parameters, and sediment modelling included.
    WQ_001 3D water quality model with waste water treatment plant (WWTP) added as a boundary condition.
    WQ_002 3D water quality model with altered upstream boundary conditions.

    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 and MATLAB toolbox are available. You will need to download and setup your preferred option. For more information on how to complete this please follow either of the links as follows:

  • TUFLOW FV MATLAB Toolbox Download and Setup
  • TUFLOW FV Python Toolbox Download and Setup

    Initial 2D model (HYD_000)

    As a starting point the model HYD_000.fvc provides a basic 2D hydrodynamic model without baroclinicity, atmospheric heat, or meteorological data enabled.
    For a detailed description of the commands and syntax in the .fvc file, please refer to HYD_000.

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

    HYD_000 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 this are provided in the Customising Output Chapter of the TUFLOW FV User Manual.

    Writing a profile NetCDF file

    To produce a timeseries we need to first postprocess 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 MATLAB please follow the link below:

    2D variable timeseries plot

    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, please follow the 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

    TFV mod5 09.jpg

    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’.
    Tut 5 bc files.jpg

    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

    A sheet plot will visualise a given variable in plan view. To produce a sheet plot for the HYD_000 results, please follow one of the links below:

    An example of a sheet plot with vectors is shown below:

    Sheet plots temperature grad vec v2.JPG

    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.

    Basic 3D model (HYD_001)

    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

    3d Layering.png
    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 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 MET_2011.fvc located in the \bc\met\ folder. The link to this file is given in the ‘include’ line:

    include  == ..\bc\met\MET_2011.fvc

    If you open this file in a text editor you can see the following commands:

    TFV mod5 MET FVC.jpg

    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 HYD_001

    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 dicussion

    Having run the profiles plot script you should see the following plots:

    HYD_000: 2D model

    TFV mod5 12.jpg

    HYD_001: 3D model

    TFV mod5 13.jpg

    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 baroclinicity 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 baroclinicity (HYD_002)

    Until now baroclinicity (the density effects of temperature or salinity) have not been modelled. In this example model the downstream boundary applies a saline tidal boundary 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 (baroclinicity)

    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.

    Baroclinicity simulation 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:

    TFV mod5 16.jpg

    As shown above now that baroclinicity 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 Modelling

    TUFLOW FV can be used to conduct water quality modelling by dynamically coupling to the external water quality model AED2.
    This section provides a sample of AED2 - TUFLOW FV coupling and some basic result visualisation. Please note this is an example only. For the correct setup of AED2 input files please refer to the AED2 Website.
    The model builds on our previously developed hydrodynamic model HYD_002.

    Basic water quality model (WQ_000)

    Syntax additions to HYD_002.fvc are detailed on the page WQ_000. Further discussion of the various model updates is outlined below.

    AED2 model

    The AED2 model is called as an external water quality model. AED2 is driven by a special .nml file type. The nml files required to run the model are located in the WQ directory.

    water quality model == EXTERNAL
    external water quality model dir == ..\WQ\
    WQ Update DT == 900 

    The AED2 model calculations are performed every 900s, specified by the line ‘’WQ Update DT == 900’’. In between calculations, AED2 water quality variables are treated as tracers and their advection/diffusion is calculated by TUFLOW FV.

    The inputs required to run the AED2 model are provided in the nml files located in the WQ folder. These inputs include selecting which water quality packages you wish to include in the model and the initial parameter values required for each module. Please note this is an example only. For the correct setup of AED2 input files please refer to the AED2 Website.
    To view how AED2 is configured, please navigate to the WQ folder and open the main AED2 control file, aed2.nml in text editor (e.g. NotePad++). If you scroll to the aed2_models section, you will see a list of the AED2 modules that are to be simulated.

    TFV mod5 17.jpg

    Observe that a number of these modules have been commented out. For the purposes of our model, we only wish to include sediment flux, oxygen, carbon, silica, nitrogen, phosphorous, organic matter and phytoplankton modules. For each of these modules, you can scroll down to the relevant section of the control file and observe the required input parameters that have been provided. For the phyto and zooplankton models, additional .nml files are required, which can be found in the WQ folder.

    Run WQ_000

    If not also complete, please run WQ_001.fvc from the provided batch file.

    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.

    Water quality simulation results

    DO curtain

    As established in the salinity curtain plot above (refer to Salinity curtain plot), there is an observable salt wedge in the estuary.
    In order to visualise the associated oxygen depletion that occurs in the salt wedge, we will produce a DO curtain. When working with dissolved oxygen (DO), the standard units are mg/L. It would therefore be useful to produce the curtain plot in units of mg/L. To do this in MATLAB, please refer to the link below:

    An example of a DO plot scaled to mg/L units is shown below:

    WQ 000.jpg

    Combined plot

    A combined plot will produce a profile, timeseries, sheet and curtain plot for 4 specified variables. A sheet plot will visualise a given variable in plan view. In order to produce this plot, please follow the link below:

    An example of a colour scaled combined plot produced in MATLAB is provided below:
    TFV mod5 20 V3.jpg

    From this plot it is clear to see DO depletion in the salt wedge, resulting in a low oxygen zone. Is this expected? Yes, the density gradient in the estuary provides a driving force that prevents the layers from mixing, and therefore prevents the saline water from reoxygenation. Additionally, observe the sharp difference in current magnitude between the surface waters and deeper waters, consistent with a lack of mixing between layers.

    Water quality model with WWTP (WQ_001)

    In order to introduce a wwtp discharge a new boundary condition section is added to the fvc. For detailed syntax updates please refer to the page WQ_001.fvc. Further discussion of the various model updates is outlined in the following section.

    Cell inflow bc WWTP

    To add the WWTP discharge to the model, another boundary condition is introduced. This boundary condition is provided as a cell inflow. The cell inflow is specified at the cell with coordinates (159.1269, -31.41123). A vertical distribution file defines the vertical distribution of the discharge. The file uses height coordinates to define the distribution.

    bc == QC, 159.1269, -31.41123, ..\bc\WWTP_Q_Temp_Sal_Sed_WQ_001.csv
       bc header == time_hr,flow_m3s-1,sal_ppt,temp_degC,FineSed_mgL-1,Sand_mgL-1,DO,Si,NH3,NOx,FRP,P_ADS,DOC,POC,DON,PON,DOP,POP,PHY01
       vertical distribution == ..\bc\WWTP_vertical_distribution.csv
       vertical coordinate type == height
    end bc

    Go to to the bc folder and open the file WWTP_Q_Temp_Sal_Sed_WQ_001.csv. You should see the following:

    TFV mod5 21.jpg

    Here you can see the values for TUFLOW FV variables including flow, salinity and temperature are provided at hourly timesteps, as well as AED2 water quality values. You can observe that the DO value is set to 156.25 mmol/m3 or 5mg/L, which is considered a low value. If you open the similar boundary condition files for upstream and downstream conditions, Upstream_Q_Temp_Sal_Sed_WQ_001 and Downstream_H_Temp_Sal_Sed_WQ_001, you can observe that the DO values have been set to 294.88mmol/m3 or 9.4mg/L, which is significantly higher.

    Run WQ_001

    Once you’re happy with the FVC file contents, run TUFLOW FV for WQ_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.

    WWTP simulation results

    As we've done previously, to visualise the associated oxygen depletion that occurs in the salt wedge we will produce a DO curtain. It is known that the estuary is the seasonal habitat of a fish that requires a DO concentration above 8.5 mg/L to survive. The fish needs to be able to travel through the estuary as the breeding season approaches.
    The objective of this task is to investigate how the inclusion of a WWTP discharge into the estuary will impact the fish habitat.
    To produce a scaled DO curtain plot in MATLAB please follow the link below:

    Once you are able to produce DO curtains you should see plots similar to those shown below:

    WQ_000: Before WWTP

    WQ 000 DO Plot.jpg

    WQ_001: After WWTP

    WQ 001 DO Plot.jpg

    What are the consequences of the WWTP for the fish? It becomes difficult for the fish to cross the plume of low oxygen around 8000m chainage.

    Additionally, to investigate the impact of the WWTP you may produce an impact sheet plot. To produce a scaled DO impact sheet plot in MATLAB please follow the link below:

    Once you are able to produce an impact sheet you should be able to run a visualisation similar to the one shown below:

    WWTP DO impact sheet.gif

    As shown above, due to the high organic content and associated COD in the waste water effluent, the effluent has a significantly lower DO value than the prior concentration in the estuary. This has a significant impact on the DO in the region surrounding the inflow, particularly upstream where low DO in the pinch point of the estuary could significantly affect the upstream movement of the fish.

    Altered boundary conditions (WQ_002)

    As an optional exercise go into WQ_001 and change the upstream boundary condition. To do this update the flows using the second upstream file provided in the bc folder: ‘Upstream_Q_Temp_Sal_Sed_WQ_002.csv’. This boundary condition file contains the same values as previously, except for a reduction in flow from 20m3/s to 0.5 m3/s. The relevant line in the fvc should read:

    bc ==  Q, 1, ..\bc\Upstream_Q_Temp_Sal_Sed_WQ_002.csv

    Save the updated fvc as WQ_002.

    Proceed to produce a DO curtain plot for the WQ_002 model. To produce a scaled DO curtain plot in MATLAB, please follow the link below:

    You will see a plot similar to the one shown below:

    WQ 002 DO Plot.jpg

    How did a reduction in upstream flow affect the estuary? What are the implications for the fish? Without higher oxygen flows arriving upstream they are in trouble.


    Congratulations. We've covered a lot in this tutorial including several 2D and 3D visulation techniques of hydrodynamic and water quality outputs.

    To complete more tutorials or get tips and tricks please return to the TUFLOW FV Wiki Mainpage.