FV MATLAB Tools

From TUFLOW FV Wiki
Jump to: navigation, search

This online guide is designed to be a brief overview of the suite of MATLAB tools for visualising model results.

Introduction

This page provides you with an overview of the TUFLOW FV MATLAB Toolbox and uses several example scripts to showcase it's functionality.
The MATLAB examples presented herein use Tutorial Module 5 as the example dataset. The provided scripts can be easily modified for use with your own datasets, however we encourage you to start out with the pre-defined examples provided with Tutorial Module 5. The data download and model setup for Tutorial 5 is provided here: Tutorial Module 5.

Toolbox Overview

MATLAB

These tools require the user to have MATLAB installed on their computer. The tools have all been designed in such a was as to allow new users to be able to quickly and easily visualise their model output. For users more experienced with MATLAB, it also offers an easy platform for highly customized visualisations. It is recommended that users unfamiliar with MATLAB learn the basics of plotting with MATLAB Graphics, using 3rd party tutorials and textbooks, or using official documentation on the MathWorks Website. Please note these tools have been developed using MATLAB version R2016b. For versions older than R2016b please use some caution as there may be incompatibilites with the toolbox.

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. It also 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, they include patch objects that represent mesh cells and are colored based on the model results. The FVG objects call their own respective FV-Res Objects, that 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 www.tuflow.com and download the TUFLOW FV MATLAB toolbox from the TUFLOW FV Utilities page. Save the toolbox in \Analysis\matlab.

Adding toolbox to path

To get the required tools setup firstly add the MATLAB tools to your MATLAB path. Depending on your version of MATLAB this will look something like this:


TFV mod5 02.jpg


Then add with subfolders:


TFV mod5 03.jpg


And select the matlab_toolbox folder as per below:


TFV mod5 04.jpg


Visualising Tutorial Module 5 results

Tutorial Module 05 demonstrates the development of a 3D estuary model. Starting with a 2D model, the tutorial progressively increases in complexity, incorporating layers, baroclinity and water quality modelling to observe stratification and dissolved oxygen distributions 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.

To start visualising the results for the estuary models for this section, copy the TUFLOW FV Matlab Toolbox folder into Analysis\matlab.

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, HYD_002, WQ_000, WQ_001 and WQ_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 output folder.
Note: to produce profile files for water quality variables, additional WQ profile files must be written. To do this, please use the script ‘ts_000_create_profile_file_WQ.m’ which is located in the same directory (\tutorial\visual\1.timeseries).

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

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 Basic 3D model (HYD_001).

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

2D variable timeseries plot

A 2D variable 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 Initial 2D model HYD_000.

MATLAB Sheet

As identified in the timeseries plots, it takes a while for a temperature gradient to be established in the estuary as boundary conditions are stitched across model, overwriting the initial global temperature. To further investigate how the temperature gradient is established in the estuary, a sheet plot can be produced. A sheet plot will visualise a given variable in plan view.

Sheet plot

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, '../../../../Complete_Model/TUFLOWFV/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, '../../../../Complete_Model/TUFLOWFV/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.

Impact Sheet plot

An impact sheet plot will allow you to observe the changes to a variable in plan view. For example, during Tutorial Module 5, a waste water treatment plant (WWTP) is added to the water quality simulation. In order to observe the change to DO in the estuary, an impact sheet plot can be used. To produce an impact sheet plot, please navigate to \tutorial\visual\3.sheets and open the script 'sh_006_impact_sheet_multiple_models.m'. The following steps provide a demonstration of how to configure the impact sheet plot for dissolved oxygen.

  • Verify that the script is pointed at the relevant TUFLOW FV results files (where WQ_000_WQ.nc is the base_tfvfile and WQ_001_WQ.nc is the dev_tfvfile),
  • Verify that the variables (vec_var and diff_var) are set to 'WQ_OXY_OXY',
  • Verify that the colour scaling lines set up an appropriate DO (mg/L) scale (refer to Scaling the colour bar).

Before running the script, the User input section should appear like the lines shown below:

Impact sheet.jpg

After you run the script, you should see results as shown below:

WWTP DO impact sheet v2.gif

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. As shown above, 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.

If you are currently completing Tutorial Module 5 you can return to the WWTP simulation results.

MATLAB Curtain

To view the results of the baroclinicity enabled simulation, HYD_002, 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). Now that baroclinicity has been enabled, a 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 baroclinicity HYD_002.

DO visualisations: scaling the colour bar

When working with dissolved oxygen (DO), the standard units are mg/L. It would therefore be useful to produce the curtain plots in units of mg/L. As AED2 works in units of mmol/m3, the TUFLOW FV results file “WQ_000_WQ.nc” contains DO values in mmol/m3. Therefore, to visualise these results in different units, a scaling factor must be applied to the plot. This is easiest achieved by simply scaling the colour bar. Open the script ‘cu_000_plot_curtain_WQ.m’ (located in \tutorial\visual\4.curtains). As done previously make the appropriate changes in the user input section to plot a curtain for the variable WQ_OXY_OXY. For the model results file, use WQ_000_WQ.nc, and for the geofile use WQ_000_geo.nc . These changes are shown below:

TFV mod5 22 v2.jpg


Under Advanced Plot Settings, in the lines below the pline definition, add the following lines of code (ln 51-53 shown below):

TFV mod5 23.jpg

scales.WQ_OXY_OXY = [[8.5 10]*1000/32 160]; This line produces a struct containing the upper and lower bounds of the DO scale, as well as how many points to include (160). The values 8.5 and 10 mg/L are converted to mmol/m3 (using *1000/32) and then stored within the struct.
scaletick.WQ_OXY_OXY = [8.5:0.5:10]*1000/32; This line of code produces a struct containing the values for tick marks on the DO scale every 0.5 mg/L, again directly converted to mmol/m3.
scalefactor.WQ_OXY_OXY = 32/1000; This line of code details the conversion from mmol/m3 to mg/L for use later in scaling the colour bar.


Additionally, under Formatting alter the following lines of code:


TFV mod5 24 v5.JPG


%hcbar = colorbar(ax,'location','Southoutside'); Comment out the original hcbar definition line which used the colorbar function.
hcbar = mycolor(ax,scales.(var),'location','Southoutside'); Define the colour bar using the mycolor function. This function reads the scales struct to implement the limits and number of points for the colour bar.
set(hcbar,'ytick',scaletick.(var)); This line sets the tick marks specified earlier onto the colour bar at the defined points.
set(hcbar,'yticklabel',num2str(scaletick.(var)'*scalefactor.(var),'%.1f')); This line scales the tick mark values specified in mmol/m3 back into mg/L units to be displayed (8.5, 9.0, 9.5,10).


Having made all these changes, run the script for the WQ_000 model. You should see a plot similar to the one shown below. Please note, if you are unable to successfully modify and run the script, the modified script ‘cu_000_plot_curtain_WQ_mgL.m’ (located in the same directory) has been provided to assist you.

WQ_000

WQ 000.jpg

If you are currently completing Tutorial Module 5 you can return to the Water quality simulation results.

MATLAB Combined

In order to produce a combined plot, a profile file must first be written. To do this please refer to Writing a profile NetCDF file. This must be done using both the ‘ts_000_create_profile_file.m’ and ‘ts_000_create_profile_file_WQ’ scripts to generate both standard and water quality model profile files. Once this has been done, please navigate to \tutorial\visual\5.combined_plots\ and open the script ‘co_000_plot_multiple_ways_WQ’. This script will plot a profile, timeseries, sheet and curtain plot for 4 specified variables.
In the User Input section of the code ensure the provided files are for the WQ_000 model. Then proceed to change the code accordingly for current magnitude (‘V’) profile and timeseries plots at point 5- and dissolved oxygen (‘WQ_OXY_OXY’) sheet and curtain plots as shown below.

TFV mod5 18 v2.jpg


For the sheet and curtain plot settings ensure that clim_sheet and clim_curt are approximately 100 to 350 mmol/m3 in order for the dissolved oxygen range to show up within the colour range. Additionally ensure the date corresponds to the week of the simulation (1st to 7th May 2011).

TFV mod5 19.jpg

Run the script. You should see a collection of plots similar to the figure shown below:

TFV mod5 20.jpg

If you are currently completing Tutorial Module 5 you can return to the Water quality simulation results. Alternatively if you would like to see how to colour scale the combined plot please see below.

Colour scaled combined plot

As an additional exercise, try to apply colour bar scaling to display the sheet and curtain plots in mg/L units for DO.

For assistance with scaling the DO curtain plot, please refer to Scaling the colour bar. For assistance with scaling the DO sheet plot please see the below section.

Colour scaling sheet plot

For the color scaled sheet plot, start by ensuring the following lines of code are included at the end of the User input section:

scales.WQ_OXY_OXY = [[8.5 10]*1000/32 160];	
scaletick.WQ_OXY_OXY = [8.5:0.5:10]*1000/32;	
scalefactor.WQ_OXY_OXY = 32/1000;

Additionally, the formatting block of code should be altered too. For the colour scaled sheet plot, an example of the altered formatting block is shown below:

Colour scaling sheet plot.jpg

Some of the key points to be careful of while scaling the combined plot include:

  • Using 'var_sheet' instead of 'var',
  • Working with the specific axis, 'ax(3)' instead of 'ax',
  • Altering the 'Position' vector values to correctly position the bar,
  • Changing the units to be displayed as "mg/L" in the User input section of code.

Once the scale is adjusted for mg/L units you should see figures like the ones below. Please note, if you are unable to successfully modify and run the script, the modified script "co_000_plot_multiple_ways_WQ_mgL.m" (located in the same directory) has been provided to assist you.

TFV mod5 20 V3.jpg

If you are currently completing Tutorial Module 5 you can return to the Water quality simulation results.

FVG visualisation tutorials

The following tutorials show further basic uses of the FVG visualisation suite. For more advanced uses, and questions on usage, please use the TUFLOWFV Forum.