Tutorial M04 Archive

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

This example TUFLOW FV model is a simplified hydrodynamic model of the Gulf of Carpentaria. The model is provided with time-varying water levels on the open boundaries derived from a global tidal model. The model demonstrates alternative methods for modelling tropical cyclones, including specification of wind and wave boundary conditions.

Please note: This tutorial has been created using SMS version 13.2.0. If using a different version of SMS some of the dialogue boxes and screen shots may change slightly however the overall workflow should be similar. If you run into any problems or need help please contact support@tuflow.com

Tutorial Data

Download the Tutorial Module 4 Data Package.

The following datasets will be used during this tutorial:

• Aerial photography (Gulf of Carpentaria 10.png)
• SMS map data used to create a model mesh (Gulf_of_Carpentaria_001.map)
• Boundary condition data, in comma separated variable (.csv) and netcdf (*.nc) formats

These datasets are contained within the folder titled Module_Data. Complete versions of the model have also been provided within the folder Complete_Model.

Model Setup

Initialise Projection

Establish a folder structure shown below.

Open SMS. Initialise the project projection.

We will be using spherical coordinates (Latitude/Longitude) for this model mesh, rather than rectilinear coordinates due to the significant extent of the model domain.

Select the following, global projection = WGS 1984 and leave the vertical datum as default.

Aerial Imagery

Aerial imagery has been pre-registered to the project projection for this tutorial, open Module_Data\APH\Gulf_of_Carpentaria_000.tif in SMS.

Save the project in SMS to the model\geo folder within the project directory. To save a project, select "File" - "Save as…" Save the project as Gulf_of_Carpentaria.sms (ensure the file is being saved as a project file type *.sms). Opening this SMS project file in the future will load all of the model data.

Build Mesh

Save a copy of the file, Gulf_of_Carpentaria_001.map from the tutorial module dataset to the model\geo folder within the project directory.

Open the map data in SMS.

Before we create a mesh from the map data we need to build polygons from the data. To build polygons select "map" dataset within the SMS project explorer window. Then select "Feature Objects" - "Build Polygons" in the toolbar at the top of the SMS window.

Select the main ocean polygon using the polygon select tool (). Review the property data by double clicking on the polygon and make sure that "Paving" is selected as the Mesh Type.

Select one of the small islands using the polygon select tool (). Review the property data and make sure that "None" is selected as the Mesh Type. This option will exclude elements from these regions of the final mesh.

We now want to create a mesh from the map data. Using the polygon select tool (), select an area which is not defined as a polygon within the Map dataset to deselect all polygons. Creating a mesh when no polygons are selected will create a mesh of the entire dataset, rather than a selected portion of it.

Select "Feature Objects" - "Map -> 2D Mesh".

This will produce a mesh from the map data.

To reduce the number of elements within the mesh we will “Merge Triangles”. For the tutorial module we are required to change the SMS 13.2 default “Merge triangles feature angle” setting.
Please note that this is a requirement of the tutorial 4 model and not necessary when creating meshes outside of tutorial 4. The default “Merge triangles feature angle” of 65 degrees is generally acceptable.

To adjust the default “Merge triangles feature angle”, select the mesh data and then "Select Elements" - "Options".

In the Elements Options dialog box please update “Merge triangles feature angle” to 62.50. See the below example:

Now that the default setting has been updated please follow the below steps to merge triangles.

Select "Elements" - "Merge Triangles"


The below warning will display. Please select "Yes".


The mesh nodes need to be "Renumbered" to do this please untick "Locked" and then select "Nodes" - "Renumber"

External Boundary Conditions

Update the display options to reflect the selected items in the figure below.

Display >> Display Options...

This model uses time-varying water levels on the open boundaries derived from a global tidal model. Five separate nodestrings will be used to define the external boundary locations, along which, sloping water level boundaries will be applied. A sloping water level boundary allows for modelling of spatial variation in water level along a single nodestring. The boundary condition water level which is applied is linearly interpolated from the values which are specified for the start and the end of the nodestring. Due to this, the direction which these nodestrings are digitised is important.

Digitise three separate nodestrings along the north-western ocean boundary. To do this:

• Select the ‘Mesh Map\ Mesh Data’ within the SMS project explorer window
• Using the create nodestring tool (), select the a external vertex at the southern end of nodestring 1 (shown in the figure below)
• Hold in shift (this will select all nodes between the two selected as the start and end of the nodestring.
• Click the end of nodestring 1. This should be located approximately 1/3 of the way across the north-western ocean boundary.
• Repeat these steps for nodestring 2 and 3.

Before we progress further it is best to check that the direction which these nodestrings have been digitised is correct. Using the select nodestring tool () select each of the nodestrings. When selected, the arrows at either end of the nodestring should point to the right (east).

If they do not, reverse the nodestring direction by right clicking the nodestring and selecting "Reverse Direction".

Digitise two separate nodestrings along the north-eastern ocean boundary. These nodestrings should be digitised from north the south (opposite to the first three nodestrings).

Save the SMS project. After saving the project also save a copy of model mesh to the model\geo folder. This file will be used by TUFLOW FV to define the models geometry and external boundary locations. To do this, select File >> Save Mesh… Save the mesh as Gulf_of_Carpentaria_001.2dm (ensure the file is being saved as a project file type *.2dm).

This file currently doesn’t include elevation/bathymetric data within the mesh. In this tutorial example we will show you how to define this within the model control file, supplementing the element definition included in the 2dm file.

Save a copy of the file Gulf_of_Carpentaria_001_2dm.csv from the tutorial module dataset to the model\geo folder within the project directory. This file defines the cell centre elevation for each element within our mesh. This bathymetry data has been derived from a Geoscience Australia DEM.

Model Scenarios

Copy the remaining files from the tutorial module dataset to the bc_dbase folder within the project directory. These files will be used as the boundary conditions for the following model examples:

• A basic tidal model (applying a sloping water level boundary)
• A cyclone/hurricane model (using internal parametric holland wind and pressure model inputs)
• A cyclone/hurricane model (using external wind and wave model results as inputs to TUFLOW FV)
• A basic sediment transport model example

Tidal Model

Using a text editor, create an fvc file called GCarp_Tide_001.fvc within the runs folder. The control file should include the syntax commands listed on the lefthand side of the following table.

! TUFLOW FV TUTORIAL	The first 2 lines are a description of the model simulation. You may also wish to include the initials of the modeller, etc.
! Gulf of Carpentaria - Tide
Tutorial Model == ON	Enables licence free modelling.
! GENERAL PARAMETERS	The default friction approach is a Manning’s number. Bottom drag model == ks uses an alternate approach, using a log-law velocity profile. This approach requires specification of a surface roughness length scale, “ks”.
bottom drag model == ks
! TIME COMMANDS	The time commands include the time format (ISO = date and time). Start and end times. The CFL limit is 0.95 (slightly less than the default – TUFLOW FV then assigns a timestep at each computational step according to the CFL limit and also between the ranges specified in the timestep limits.
time format == ISODATE
start time == 26/03/2010 16:30:00
end time == 01/04/2010 23:00:00
cfl == 0.95
timestep limits == 0.1, 30.
! MODEL PARAMETERS	The model parameters are those that control various physical and numerical processes. Cell wet/dry depths sets the cell wetting and drying depths in metres. The drying value corresponds to a minimum depth below which the cell is dropped from computations (subject to the status of surrounding cells). The wet value corresponds to a minimum depth below which cell momentum is set to zero, in order to avoid nonphysical velocities at very low depths. Stability limits define the limits which if exceeded, define when the model has crashed Momentum mixing model sets the horizontal eddy viscosity calculation method. A Smagorinsky eddy viscosity approach has been specified, with a Smagorinsky factor of 0.2.
cell wet/dry depths == 5.0e-3, 5.0e-2
stability limits == 50.,10.
momentum mixing model == Smagorinsky
global horizontal eddy viscosity == 0.2
global horizontal eddy viscosity limits == 0.05, 99999.
! GEOMETRY	The model geometry is the 2dm created above in this tutorial module. This 2dm file example only defines the mesh/element configuration. Elevations are being specified for each cell centre using the coordinate values listed in Gulf_of_Carpentaria_001_2dm.csv Spherical specifies that the x,y coordinates within the model mesh use a spherical convention (Lat/Long) instead of a rectilinear convention.
geometry 2d == ..\model\geo\Gulf_of_Carpentaria_001.2dm
cell elevation file == ..\model\geo\Gulf_of_Carpentaria_001_2dm.csv, coordinate
spherical == 1
! MATERIAL PROPERTIES	So far, material types haven’t been highlighted. By default, SMS will create elements using a single material type (1). It is this material type that is assigned a bottom roughness of 0.05 (ks value).
material == 1
bottom roughness == 0.05
end material
! INITIAL CONDITIONS	The initial internal model boundary conditions.
initial waterlevel ==0
! BOUNDARY CONDITIONS	The boundary conditions link the csv files containing the water level information along the external boundaries to the model. Sloping water level boundaries are being used. These allow for modelling of spatial variation in water level along each of the nodestring locations. The boundary condition water level which is applied is linearly interpolated from the values which are specified for the start and the end of the nodestring.
bc == WLS, 1, ..\bc_dbase\TIDE.csv
bc header == TIME,NS1,NS2
end bc
bc == WLS, 2, ..\bc_dbase\TIDE.csv
bc header == TIME,NS2,NS3
end bc
bc == WLS, 3, ..\bc_dbase\TIDE.csv
bc header == TIME,NS3,NS4
end bc
bc == WLS, 4, ..\bc_dbase\TIDE.csv
bc header == TIME,NS5,NS6
end bc
bc == WLS, 5, ..\bc_dbase\TIDE.csv
bc header == TIME,NS6,NS7
end bc
! OUTPUT COMMANDS	In this instance, a datv format file is specified. This format is easily read into SMS for viewing. The h, v and zb mean that outputs files containing water level, velocity and bed elevation will be created.
output dir == ..\results\
output == datv
output parameters == h,v,zb
output interval == 900
end output

Run TUFLOW FV

Once you’re happy with the fvc file contents, run TUFLOW FV. Refer to the following link for simulation run options: Running TUFLOW FV.

You may find that your simulation exited. This may have occurred due to some syntax error in the inputs. See the following link for advice: Common reasons why a model won’t start.

Tidal Model Results

TUFLOW FV dat results can be viewed in either SMS or a range of GIS packages, such as MapInfo, ArcGIS, QGIS and SAGA. We will use SMS in this example. For information how to process results into a suitable format for other GIS packages, refer to TUFLOW FV Utilities.

Open the model geometry file, Gulf_of_Carpentaria_001.2dm and background imagery in SMS. Within this tutorial, the 2dm file only defined the mesh configuration, not the bathymetry elevations. As such, viewing the geometry file does not display the bathymetry that was used during the simulation.

Open the model result file GCarp_Tide_001_ZB.dat. This result file will display the bathymetry data used by the model.

Open the water level and velocity result files, GCarp_Tide_001_H.dat and GCarp_Tide_001_V.dat. You will notice that the timestamps displayed by SMS do not reflect the time format of the model. You will need to update the time settings in SMS to display the results using isodate format. Follow the steps outlined in, Changing SMS Time Settings (Hours to Isodate), to update the time settings.

Step through the tide simulation results.

An animation of the results can also be created using SMS following the steps outlined in: How to Create an Animation.

Cyclone/Hurricane Hydrodynamic Model (Tide + Parametric Holland Wind/Pressure)

Adding boundary conditions to turn on the TUFLOW FV holland parametric wind/pressure model is relatively straight forward. A hypothetical cyclone has been used to illustrate the process of adding these input boundary conditions. The syntax additions to the Tidal model are highlighted below. After making the syntax updates, save the TUFLOW FV control file with the name, GCarp_Holland_001.fvc. The control file should be saved to the runs folder within the model directory.

! TUFLOW FV TUTORIAL	Model description update
! Gulf of Carpentaria – Holland Wind
Tutorial Model == ON	Enables licence free modelling.
! GENERAL PARAMETERS	No syntax changes
bottom drag model == ks
! TIME COMMANDS	No syntax changes
time format == ISODATE
start time == 26/03/2010 16:30:00
end time == 01/04/2010 23:00:00
cfl == 0.95
timestep limits == 0. 1, 30.
! MODEL PARAMETERS	No syntax changes
cell wet/dry depths == 5.0e-3, 5.0e-2
stability limits == 50.,10.
momentum mixing model == Smagorinsky
global horizontal eddy viscosity == 0.2
global horizontal eddy viscosity limits == 0.05, 99999.
! GEOMETRY	No syntax changes
geometry 2d == ..\model\geo\Gulf_of_Carpentaria_001.2dm
cell elevation file == ..\model\geo\Gulf_of_Carpentaria_001_2dm.csv, coordinate
spherical == 1
! MATERIAL PROPERTIES	No syntax changes
material == 1
bottom roughness == 0.05
end material
! INITIAL CONDITIONS	No syntax changes
initial waterlevel ==0
! BOUNDARY CONDITIONS	An additional boundary condition command is required to specify the cyclone/hurricane wind and pressure field to the model. bc == CYC_HOLLAND, ..\bc_dbase\Example_Holland_Cyclone.csv end bc
bc == WLS, 1, ..\bc_dbase\TIDE.csv
bc header == TIME,NS1,NS2
end bc
bc == WLS, 2, ..\bc_dbase\TIDE.csv
bc header == TIME,NS2,NS3
end bc
bc == WLS, 3, ..\bc_dbase\TIDE.csv
bc header == TIME,NS3,NS4
end bc
bc == WLS, 4, ..\bc_dbase\TIDE.csv
bc header == TIME,NS5,NS6
end bc
bc == WLS, 5, ..\bc_dbase\TIDE.csv
bc header == TIME,NS6,NS7
end bc
bc == CYC_HOLLAND, ..\bc_dbase\Example_Holland_Cyclone.csv
end bc
! OUTPUT COMMANDS	An additional output has been added. W10 represents the wind at a height of 10m above the water surface output parameters == h,v,W10
output dir == ..\results\
output == datv
output parameters == h,v,W10
output interval == 900
end output

Holland Wind Model Boundary Condition Inputs

In the above example the cyclone/hurricane is defined by parameters for a Holland cyclone vortex model (Harper and Holland, 1999). The parameters included within the boundary condition input (Example_Holland_Cyclone.csv) include:

• Cyclone position [X, Y]

• Central pressure [P0]

• Ambient pressure [PA]

• Radius to maximum winds [RMAX]

• Peakedness [B]

• Air density [RHOA]

• Km (mean near surface wind speed / gradient level wind speed) [KM]

• Line of maximum wind [THETMAX]

• Asymmetry factor [DELTAFM]

• Latitude [Latitude]

• Background wind [WBGX. WBGY]

Run TUFLOW FV

Once you’re happy with the fvc file contents, run TUFLOW FV.

Useful links:

• Running TUFLOW FV
• Common reasons why a model won’t start

Tide + Parametric Holland Wind/Pressure Model Results

Open the model windfield results, GCarp_Holland_001_W10.dat. Check that the results reflect the parametric inputs specified as the boundary conditions. be sure to turn on Vectors in the "Display Options" and update the Vector options as desired.

Open the water level results, GCarp_Holland_001_H.dat. Compare them against the results from the tide only simulation (GCarp_Tide_001_H.dat). SMS can be used to compute this comparison spatially and temporally. Refer to the following link for steps outlining how this can be done: SMS Data Calculations.
Note: The SMS Community Edition does not allow for completion of the following step. If you are using SMS Community Edition, please proceed to the next section Cyclone/Hurricane Hydrodynamic Model (Tide + External Wind/Pressure and Wave Model)

Cyclone/Hurricane Hydrodynamic Model (Tide + External Wind/Pressure and Wave Model)

As an update to the previous Holland parametric wind model example (increment the fvc file to 002), this example will use NETCDF format files as wave and wind boundary condition inputs. These boundary condition inputs have been derived from data which was collected from Cyclone Paul, which crossed the Gulf in 2010.

The syntax additions/modifications to the holland parametric wind/pressure model are highlighted below. After making the syntax updates, save the TUFLOW FV control file with the name, GCarp_Holland_002.fvc. The control file should be saved to the runs folder within the model directory.

! TUFLOW FV TUTORIAL	Model description update.
! Gulf of Carpentaria – NETCDF Boundary Condition Inputs
Tutorial Model == ON	Enables licence free modelling.
! GENERAL PARAMETERS	No syntax changes.
bottom drag model == ks
! TIME COMMANDS	Updated simulation end time: end time == 03/04/2010 23:00:00
time format == ISODATE
start time == 26/03/2010 16:30:00
end time == 03/04/2010 23:00:00
cfl == 0.95
timestep limits == 0. 1, 30.
! MODEL PARAMETERS	No syntax changes.
cell wet/dry depths == 5.0e-3, 5.0e-2
stability limits == 50.,10.
momentum mixing model == Smagorinsky
global horizontal eddy viscosity == 0.2
global horizontal eddy viscosity limits == 0.05, 99999.
! GEOMETRY	No syntax changes.
geometry 2d == ..\model\geo\Gulf_of_Carpentaria_001.2dm
cell elevation file == ..\model\geo\Gulf_of_Carpentaria_001_2dm.csv, coordinate
spherical == 1
! MATERIAL PROPERTIES	No syntax changes.
material == 1
bottom roughness == 0.05
end material
! INITIAL CONDITIONS	No syntax changes.
initial waterlevel ==0
! BOUNDARY CONDITIONS	The parametric Holland wind/pressure model input from the previous example (bc == CYC_HOLLAND) have been replaced with NETCDF inputs. grid definition file == ..\bc_dbase\BOM_HOLLAND_WIND.nc grid definition variables == lon,lat end grid bc == W10_GRID, 1, ..\bc_dbase\BOM_HOLLAND_WIND.nc bc header == time,u,v bc update dt == 450.0 end bc Wave boundary condition inputs have also been added, from which TUFOW FV calculates the hydrodynamics. grid definition file == ..\bc_dbase\WAVE.nc grid definition variables == longitude,latitude end grid bc == Wave, 2, ..\bc_dbase\WAVE.nc bc header == time,hs,tps,thetap bc reference time == 01/01/1970 00:00 bc time units == seconds bc update dt == 3600. end bc
bc == WLS, 1, ..\bc_dbase\TIDE.csv
bc header == TIME,NS1,NS2
end bc
bc == WLS, 2, ..\bc_dbase\TIDE.csv
bc header == TIME,NS2,NS3
end bc
bc == WLS, 3, ..\bc_dbase\TIDE.csv
bc header == TIME,NS3,NS4
end bc
bc == WLS, 4, ..\bc_dbase\TIDE.csv
bc header == TIME,NS5,NS6
end bc
bc == WLS, 5, ..\bc_dbase\TIDE.csv
bc header == TIME,NS6,NS7
end bc
grid definition file == ..\bc_dbase\BOM_HOLLAND_WIND.nc
grid definition variables == lon,lat
end grid
bc == W10_GRID, 1, ..\bc_dbase\BOM_HOLLAND_WIND.nc
bc header == time,u,v
bc update dt == 450.0
end bc
grid definition file == ..\bc_dbase\WAVE.nc
grid definition variables == longitude,latitude
end grid
bc == Wave, 2, ..\bc_dbase\WAVE.nc
bc header == time,hs,tps,thetap
bc reference time == 01/01/1970 00:00
bc time units == seconds
bc update dt == 3600.
end bc
! OUTPUT COMMANDS	Additional wave height, period and direction outputs have been added. output parameters == h,v,W10,wvht,wvper,wvdir In addition to datv output, NECDF output has also been specified. output == netcdf output parameters == H,V,W10,wvht,wvper,wvdir output interval == 900. end output
output dir == ..\results\
output == datv
output parameters == h,v,W10,wvht,wvper,wvdir
output interval == 900
end output
output == netcdf
output parameters == H,V,W10,wvht,wvper,wvdir
output interval == 900.
end output

NetCDF Boundary Condition Inputs

As an update to the previous Holland parametric wind model example, this example will use NETCDF format files as wave and wind boundary condition inputs. These boundary condition inputs have been derived from data which was collected from Cyclone Paul, which crossed the Gulf in 2010.

SWAN is a third-generation wave model developed at the Delft University of Technology (Delft University of Technology, 2006). SWAN version 40.91AB can be configured to output NETCDF format results which can be used as wave inputs to TUFLOW-FV models. The outputs can be produced for the SWAN computational grid or for a defined output grid using FRAME or GROUP commands (SWAN User Manual). The format of the SWAN output command is:

BLOCK ‘grid_name’ NOHEADER ‘out_file_name’ &
LAY-OUT 3 HSIGN TPS PDIR OUTPUT yyyymmdd.HHMMSS dt dtunit

For the purposes of this tutorial, SWAN model wave forcing output from a simulation of Cyclone Paul (which crossed the Gulf in 2010) has been provided.

As an update to the previous Holland wind model example, in addition to the wave boundary condition input, wind has be applied as a boundary condition using NETCDF format. The NETCDF file specifies 10m wind speed time series on an array of grid points. This file has also been provided.

Run TUFLOW FV

Once you’re happy with the fvc file contents, run TUFLOW FV.

Useful links:

• Running TUFLOW FV
• Common reasons why a model won’t start

Tide + External Wind/Pressure and Wave Model Results

'DAT' and 'NETCDF' output types have been specified for this simulation. Review the DAT results either in SMS or one of the following GIS packages; MapInfo, ArcGIS, QGIS and SAGA (see DOS Utilities).

NETCDF results can be read using a range of freeware software. We however recommend using Matlab. A range of Matlab functions have been created which automated many common TUFLOW FV result processing tasks (see Matlab Utilities).

Troubleshooting

This section contains a link to some common issues that may occur when progressing through the TUFLOW FV tutorial models:

• Common reasons why a model won’t start
• Common reasons why a model crashes

For further support please email support@tuflow.com.

Conclusion

Congratulations on completing Tutorial 4. We've covered a lot in this tutorial, including:

• Simulating a simplified hydrodynamic model of the Gulf of Carpentaria.
• Simulating a Cyclone/Hurricane Hydrodynamic Model using cyclone/hurricane parameters defined by the Holland cyclone vortex model (Harper and Holland, 1999)
• Re simulating the Cyclone/Hurricane Hydrodynamic Model with external Wind/Pressure and Wave boundary conditions using NETCDF format files.

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

We will continue to add more functionality over time, so please periodically review. If you wish to keep up to date with all things TUFLOW and TUFLOW FV, please join our LinkedIn group here: https://www.linkedin.com/groups/1908583 If you have any further queries, feedback or requests for new functionality, please feel free to get in contact with support@tuflow.com