Tutorial Module04

From TUFLOW FV Wiki
Jump to: navigation, search
LINKS: Main page
Modelling Advice Tutorial Models Tips and Tricks
Mesh Generation Tips Tutorial Module 1 SMS
A Model Won't Start Tutorial Module 2 UltraEdit
A Model Crashes Tutorial Module 3 Notepad++
A Model Runs Slow Tutorial Module 4 Excel
TUFLOW Products Support / Contact TUFLOW FV Utilities
Requesting a Licence Running TUFLOW FV
Mesh Generation Tips

Tutorial Description

This example 2D 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 cyclones, including specification of wind and wave boundary conditions.

Tutorial Data

Download the Tutorial Module 4 dataset from the TUFLOW Website: http://www.tuflow.com/FV%20TutorialModel.aspx

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. For a TUFLOW FV model project called “Gulf_of_Carpentaria_Example”, the folder structure will be:

Tute4 Folder Structure.png

Open SMS. Initialise the project projection.

Projection edit.jpeg


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 = Geographic, Datum = NAD83, Planar Units = ARC Degrees

Module 4 edit2.jpeg

Aerial Imagery

We will register a satellite photo as the background image for our modelling. SMS can use multiple projections within the one project. To demonstrate this functionality we will load the image using a different global projection to the rest of the SMS project.

Save a copy of the file “Gulf of Carpentaria 10.png” from the tutorial module dataset to the geo folder within the project directory.

Open the aerial image within SMS. When prompted, select “Provide world coordinates”.

Tute4 002.png

Select “YES”, when asked, would you like to generate image pyramids?

Tute4 003.png

This will open the image registration window.

Tute4 004.png

Select 3 point registration. Shift the three markers within the image so that “#1” is located in the top left corner of the image, “#2” is in the top right and “#3 is in the bottom left.

The world coordinates for each of these point location now needs to be manually defined within the tables below the figure.


Point #1 Point #2 Point #3
World Coordinates Pixels World Coordinates Pixels World Coordinates Pixels
X 15028131.0 0 15927489.0 1472 15028131.0 0
Y -855257.0 1984 -855257.0 1984 -2060016.0 0


Right Click ‘Gulf of Carpentaria’ within the SMS project explorer window. Select ‘Set Image Projection’.

Tute4 005.png

Select the following, ‘Global Projection’, Projection = Mercator, Datum = WG84, Planar Units = Meters

Tute4 006.png

Save the project in SMS to the “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 geo folder within the project directory.

Open the map data in SMS.

Before we create a mesh from the map data we first need to clean the dataset and build polygons from the data. To clean the data select ‘map’ dataset within the SMS project explorer window. Then select Feature 'Objects >> Clean…' in the toolbar at the top of the SMS window

Tute4 007.png

Update the Clean Options, as per the figure below.

Tute4 008.png

Build polygons from the cleaned map data. 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 Tute4 009.png

Select the main ocean polygon using the polygon select tool (Tute2 018.png). Review the property data, make sure that ‘Paving’ is selected as the Mesh Type.

Tute4 010.png

Select the some of the small islands using the polygon select tool (Tute2 018.png). Review the property data, make sure that ‘None’ is selected as the Mesh Type. This option will exclude elements from these regions of the final mesh. Tute4 011.png

We now want to create a mesh from the map data. Using the polygon select tool (Tute2 018.png), select an area which is not defined as a polygon within the Map dataset. This deselects 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

Tute4 012.png

Select: Merge triangles after meshing

Tute4 013.png

This will produce a mesh from the map data.

Tute4 014.png

External Boundary Conditions

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

Display >> Display Options...

Tute4 015.png

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 (1.1.7.png), 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.

Tute4 016.png

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 nodestring.png) 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’.

Tute4 017.png


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

Tute4 018.png

Save the SMS project. After saving the project also save a copy of model mesh to the 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 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.

Tute4 020.png

Model Scenarios

Copy the remaining files from the tutorial module dataset to the ‘bc’ 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 input 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


! 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 unphysical velocities at very low depths.

Stability limits define the limits which if exceeded, define when the model has crashed

Scalar mixing model sets the diffusivity model coefficients. An Elder approach has been specified

Momentum mixing model sets the horizontal eddy viscosity calculation method.

A Smagorinsky eddy viscosity approach has been specified, with a Smagorinsky factor of 0.5.

cell wet/dry depths == 5.0e-3, 5.0e-2
stability limits == 50. ,10.
scalar mixing model == Elder
momentum mixing model == Smagorinsky
global horizontal eddy viscosity == 0.5


! 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 == ..\geo\Gulf_of_Carpentaria_001.2dm
cell elevation file == ..\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\TIDE.csv
bc header == TIME,NS1,NS2
end bc
bc == WLS, 2, ..\bc\TIDE.csv
bc header == TIME,NS2,NS3
end bc
bc == WLS, 3, ..\bc\TIDE.csv
bc header == TIME,NS3,NS4
end bc
bc == WLS, 4, ..\bc\TIDE.csv
bc header == TIME,NS5,NS6
end bc
bc == WLS, 5, ..\bc\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 == ..\Output\
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 has crashed. This has likely occured 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.

Tute4 021.png

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

Tute4 022.png

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

Tute4 023.png

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 input folder within the model directory.

! TUFLOW FV TUTORIAL Model description update
!Gulf of Carpentaria – Holland Wind


! 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.
scalar mixing model == Elder
momentum mixing model == Smagorinsky
global horizontal eddy viscosity == 0.5


!GEOMETRY No syntax changes
geometry 2d == ..\geo\Gulf_of_Carpentaria_001.2dm
cell elevation file == ..\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\Example_Holland_Cyclone.csv
end bc
bc == WLS, 1, ..\bc\TIDE.csv
bc header == TIME,NS1,NS2
end bc
bc == WLS, 2, ..\bc\TIDE.csv
bc header == TIME,NS2,NS3
end bc
bc == WLS, 3, ..\bc\TIDE.csv
bc header == TIME,NS3,NS4
end bc
bc == WLS, 4, ..\bc\TIDE.csv
bc header == TIME,NS5,NS6
end bc
bc == WLS, 5, ..\bc\TIDE.csv
bc header == TIME,NS6,NS7
end bc
bc == CYC_HOLLAND, ..\bc\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 == ..\Output\
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]

Tute4 019.png


Run TUFLOW FV

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

Useful links:

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.

Tute4 024.png

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

Tute4 025.png

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

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.

Tute4 026.jpg

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 input folder within the model directory.

! TUFLOW FV TUTORIAL Model description update
! Gulf of Carpentaria – NETCDF Boundary Condition Inputs


! 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.
scalar mixing model == Elder
momentum mixing model == Smagorinsky
global horizontal eddy viscosity == 0.5


!GEOMETRY No syntax changes
geometry 2d == ..\geo\Gulf_of_Carpentaria_001.2dm
cell elevation file == ..\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\BOM_HOLLAND_WIND.nc
grid definition variables == lon,lat
bc == W10_GRID, 1, ..\bc\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\WAVE.nc
grid definition variables == longitude,latitude
bc == Wave, 2, ..\bc\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\TIDE.csv
bc header == TIME,NS1,NS2
end bc
bc == WLS, 2, ..\bc\TIDE.csv
bc header == TIME,NS2,NS3
end bc
bc == WLS, 3, ..\bc\TIDE.csv
bc header == TIME,NS3,NS4
end bc
bc == WLS, 4, ..\bc\TIDE.csv
bc header == TIME,NS5,NS6
end bc
bc == WLS, 5, ..\bc\TIDE.csv
bc header == TIME,NS6,NS7
end bc
grid definition file == ..\bc\BOM_HOLLAND_WIND.nc
grid definition variables == lon,lat
end grid
bc == W10_GRID, 1, ..\bc\BOM_HOLLAND_WIND.nc
bc header == time,u,v
bc update dt == 450.0
end bc
grid definition file == ..\bc\WAVE.nc
grid definition variables == longitude,latitude
end grid
bc == Wave, 2, ..\bc\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 == ..\Output\
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:

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

NETCDF 000.png

Troubleshooting

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

For further support please email support@tuflow.com