TUFLOW FV MATLAB Toolbox

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

Introduction

The purpose of this page is to help get you setup with the TUFLOW FV MATLAB Toolbox and to provide examples that demonstrate its use. (tfv).
The TUFLOW FV MATLAB Toolbox is a suite of tools for post-processing results from the TUFLOW FV hydrodynamic, sediment transport, water quality and particle tracking modelling software.
The MATLAB examples presented herein use Tutorial Module 5 as the example dataset.

Toolbox Overview

MATLAB

These tools require MATLAB installed. The tools have been designed to allow new users to be able to quickly and easily visualise model output. If you're more experienced with MATLAB it also offers an easy platform to build customised visualisations from. Please note these tools have been developed using MATLAB version R2022a. For versions older than R2022a please use some caution as there may be incompatibilities with the toolbox.

The documentation on this page assumes you are familiar with MATLAB and MATLAB graphics objects.

FVG Suite

The accompanying tools rely on object oriented programming to provide a simple front-end interface that is similar to MATLAB built-in components. The tools are based on an fvgraphics object that creates a figure with a scrollbar inside it. The fvgraphics object stores the information necessary to scroll through timesteps and tell other objects to update the images. FVG objects can then be placed in any axis that is created within the fvgraphics object. FVG objects include patch objects that represent mesh cells and are coloured based on the model results. The FVG objects call their own respective FV-Res objects which are responsible for extracting the results from the TUFLOW FV results file and then sending a signal back to the FVG object to update the patches.

Download And Setup

Download Toolbox

To download the TUFLOW FV Matlab Toolbox please visit the TUFLOW Website.

Within the download package are the following folders:

File or Directory Description
.\log\ Pre-run log file outputs used for the example scripts.
.\results\ Pre-run NetCDF outputs used for the example scripts.
.\toolbox\ Pre-run NetCDF outputs used for the example scripts.
.\tutorial\ Series of example scripts.

Unzip and save the download package to a preferred location on your local drive or network. For this example the package has been saved to C:\MATLAB\TUFLOWFV_MATLAB_Toolbox.

Adding Toolbox

  1. To get the required tools setup firstly add the TUFLOW FV MATLAB Toolbox to your MATLAB path. Depending on your version of MATLAB the set path button will be similar to this:
    MATLAB SETPATH 002.jpg
  2. Then add with subfolders:
    MATLAB SETPATH 003.jpg
  3. And select the toolbox folder from your save location. For example: C:\MATLAB\TUFLOWFV_MATLAB_Toolbox\toolbox.
    MATLAB SETPATH 004.jpg

You have now setup your MATLAB environment. Next we will use the provided tutorial scripts to test out the TUFLOW FV MATLAB Toolbox.

Visualising Tutorial Module 5 Results

Tutorial Module 5 demonstrates the development of a 3D estuary model. Starting with a 2D model, the tutorial progressively increases in complexity, incorporating layers and density coupling to observe stratification in an estuary. Before completing the following exercises, if you have not already done so please download the data package for the tutorial from the TUFLOW FV Tutorial / Demo Models page located at www.tuflow.com.

MATLAB Profile

To view the results of the HYD_000 and HYD_001 simulations we will produce profile plots for salinity. A profile plot will allow you to view a variable through the vertical as a timeseries (with time slider bar).

Writing A Profile NetCDF File

In order to produce timeseries and profile plots, a profile NetCDF (nc) file must be written using the output NetCDF file from TUFLOW FV. To write a profile file, please navigate to \tutorial\visual\1.timeseries\ and open the script ‘ts_000_create_profile_file.m’ in MATLAB. Verify that the following lines of code are set to process data from the HYD_000, HYD_001 and HYD_002 models.


Writing profile file v2.JPG


This script will generate NetCDF profile files with the simulation results located at the 9 output sites specified on lines 21 to 29 as shown below:


TFV mod5 06.jpg


Run the script. The associated model profile files (‘HYD_000_PROFILES.nc’, ‘HYD_001_PROFILES.nc’ ... etc.) will now be generated in the results folder.

If you are currently completing Tutorial Module 5 you can return to create a timeseries plot.

Profile Plot

Once profile files have been written, profile plots can be produced. To produce profile plots, navigate to \tutorial\visual\2.profiles\ and open the script ‘pf_000_plot_profiles’. This script will create a vertical profile of elevation vs. a 3D variable from a profile file. Make the appropriate changes shown below to plot salinity at point 1 for the HYD_001 model.

TFV mod5 11.jpg

An example of a profile plot for HYD_001 is shown below:

HYD_001: 3D model

TFV mod5 13.jpg

If you are currently completing Tutorial Module 5 you can return to the 3D profile results discussion.

MATLAB Timeseries

A timeseries plot allows you to view the changes to a variable over time. This can be useful for determining when a model converges to a solution from initial values. To view the results of the HYD_000 temperature simulation we will produce a timeseries plot for temperature. In order to produce timeseries and profile plots, a profile NetCDF (nc) file must be written (please refer to Writing a profile NetCDF file).

Timeseries Plot

A timeseries plot allows you to view the time series of a single variable at a single location. To produce a timeseries plot, please go to \tutorial\visual\1.timeseries\ and open the script ‘ts_001_plot_2D_variable_timeseries.m’ in MATLAB. Change lines 16, 17, 18 and 28 to produce a plot for temperature at point 4. The final code after these changes have been made is shown below.


TFV mod5 07 v2.jpg


If you run the script at point 4, you should see a plot similar to the one shown below:

TFV mod5 09.jpg

If you are currently completing Tutorial Module 5 you can return to the timeseries results discussion.

MATLAB Sheet

To produce a sheet plot, please navigate to \tutorial\visual\3.sheets and open the script 'sh_000_plot_sheet.m'. As an example for how to configure the script please complete the following steps to produce a temperature sheet for the HYD_000 model.

  • Point the script to the TUFLOW FV results file (TFV_resfile) for HYD_000, '../../../results/HYD_000.nc',
  • Change the variable (var) to 'TEMP',
  • Change the colour limits (clim) to [10 20],
  • Change the title name (long_name) to 'Temperature (deg C)'.


Sheet plots temperature.JPG

Run the script and use the time slider bar to observe how the temperature gradient is developed in the estuary:

Sheet plots temperature grad.GIF

Sheet Plot with Vectors

As identified in the timeseries plots, oscillation in temperature is observed, presumably due to the tide. To further investigate how the temperature is affected by the tide and boundary conditions, a sheet plot of temperature with velocity vectors can be produced. To produce a sheet plot with vectors, please navigate to \tutorial\visual\3.sheets and open the script 'sh_000_plot_sheet_with_vectors.m'. Please follow the steps below to produce a temperature sheet plot with velocity vectors.

  • Point the script to the TUFLOW FV results file (TFV_resfile) for HYD_000, '../../../results/HYD_000.nc',
  • Change the sheet variable (sheet_var) to 'TEMP',
  • Ensure the vector variable (vec_var) is set to 'V',
  • Change the colour limits (clim) to [10 20],
  • Change the title name (long_name) to 'Temperature (deg C)'.


Sheet plots temperature vec.JPG

Run the script and use the time slider bar to observe how temperature is affected by the tide in the estuary.

Some sheet plots with vectors produced in MATLAB are shown below:

Sheet plots temperature grad vec v2.JPG

If you are currently completing Tutorial Module 5 you can return to the Initial 2D model HYD_000.

MATLAB Curtain

To view the results with density coupling we will produce a curtain plot. A curtain plot allows you to view a variable along a cross section as a function of chainage and depth (with time slider bar). The curtain plot will allow us to see the formation of a salt wedge in the estuary.

Curtain Plot

To produce a curtain plot, please navigate to \tutorial\visual\4.curtains\ and open the script ‘cu_000_plot_curtain.m’. This script will create a cross sectional profile for a 3D variable using both the model results file and model geofile as inputs. The cross section to be plotted is along the polyline specified on lines 22 to 49 as shown below:

TFV mod5 14.jpg


Make the appropriate changes shown below to plot a curtain for salinity for the HYD_002 model.


TFV mod5 15 v3.jpg


Run the script for HYD_002. Slide the time control bar across to the final point, at 00:00 on the 7th of May. You should see the following plot:

TFV mod5 16.jpg


If you are currently completing Tutorial Module 5 you can return to the 3D model with density coupling HYD_002.

FVG Visualisation Tutorials

The following tutorials show further basic uses of the FVG visualisation suite. For more advanced uses, and questions on usage, please email support@tuflow.com.

Conclusion

Thanks for working through the TUFLOW FV MATLAB Toolbox tutorial page. We hope it has been useful. If you have any questions or would like to contribute please get in contact with us via support@tuflow.com. Please return the TUFLOW FV Wiki Main Page and happy modelling.