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
  • 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 Turbulence Model Coupling

    This demonstration model dynamically couples TUFLOW FV with the GOTM to model vertical turbulence exchanges.

    Update TUFLOW FV DLLs

    In order to link the external 3D 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 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

    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 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 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),

    The folder structure for the Complete_Model folder should resemble the folder structure shown below (noting the AED2 folder has been removed):
    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.

    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.


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

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