Tutorial M03 draft
THIS PAGE IS CURRENTLY UNDER CONSTRUCTION
Tutorial Description
Read the Tutorial Model Introduction before starting this tutorial. It outlines programs requiring installation.
This tutorial is designed to introduce the skills required for coastal modelling and builds upon the previous tutorials Tutorial Module 1 and Tutorial Module 2. Specifically, this tutorial demonstrates:
- Building a TUFLOW FV coastal model with GIS integration.
- Defining spatially and temporally varying astronomical tide and atmospheric boundary conditions.
- Defining spatially varying landcover via a material coverage.
- Building and running a 2D coastal hydrodynamic model.
- Modelling the effects of wave breaking on hydrodynamics.
The workflow uses QGIS and Notepad++ to setup and run our models.
Model Domain
The tutorial focuses on Cudgen Creek, a small coastal estuary on the eastern Australian coastline.
The model domain extends approximately 20 km north-south and 12km east-west to a depth of 50m.
Requirements And Downloads
Requirement | Brief Description |
---|---|
Model Data | Download the Tutorial Module 3 Data Package. |
Assumed Knowledge | It is recommended to complete Tutorial Module 2 prior to completing this tutorial. |
Prepare Your Working Environment
Copy and unzip the folder to your preferred working location, for example E:\TUFLOWFV\Tutorial_M03.
- The Complete_Model folder contains a completed version of the tutorial and its supporting files. You can use this as a reference if you require.
- The Exe folder contains the TUFLOW FV executable used to run your models.
- The Module_Data folder contains the model files required to complete this tutorial.
- The Working folder is for the files you create and work within.
Initialise The Project With GIS Integration
Save The Workspace
Launch QGIS and use the below steps and video to save the workspace in the Working folder:
- 1. From the menu bar select Project > Save As.
- 2. Navigate to TUFLOWFV\Tutorial_M03\Working folder.
- 3. Save the workspace as Cudgen_Creek_001.qgz.
Set The Projection
Use the below steps and video to set your workspace projection:
- 1. Go to Project > Properties.
- 2. In the CRS tab, type GDA 94.
- 3. Select GDA 94 / MGA zone 56 in the Predefined Coordinate Reference Systems section.
- 4. Click Apply and OK.
Configuring A TUFLOW FV Project
The TUFLOW Viewer plugin is used to configure the TUFLOW FV project. This includes specifying the model and executable file paths, defining the GIS projection (i.e. the geographic coordinate system used for the TUFLOW FV model, all inputs need to use the same projection) and writing GIS empty files for model inputs. Use the below steps and video as guide to configure your TUFLOW FV project:
- 1. Select the Configure / Create TUFLOW Project symbol from the TUFLOW Plugin toolbar.
- 2. Click Select CRS and use the filter to select: GDA 94 / MGA zone 56.
- 3. Click Browse... to select the folder location of the Working folder. This creates the default TUFLOW FV model directory and sub-folders.
- 4. Click Browse... to select the location of the TUFLOW FV single precision executable file. Note: The provided version may differ from the video, however use the build provided in the Exe folder.
- 5. Select SHP as the GIS Format.
- 6. Select TUFLOW Flexible Mesh (TUFLOW FV).
- 7. Tick all box options:
- Save Default Settings Globally (for all projects): The settings configured by this window sets the default for opening a new QGIS workspace.
- Create Model Folder Structure: The TUFLOW sub-folders (e.g. bc_dbase, model, runs) are made within the Working\TUFLOWFV folder.
- Create Template Files: This creates the 'empty' gis file template folder in Working\TUFLOWFV\model\gis folder. It contains all the TUFLOW FV template files in the projection set above. It is important to create new template files for each project to ensure the projection is correct.
- Tutorial Model: Sets a command within the automatically generated FVC instructing TUFLOWFV to run the tutorial model licence free.
- 8. Click OK and a TUFLOW FV DOS console window opens. This runs the first part of a TUFLOW FV model initialisation and creates TUFLOW FV folder structure, projection file, TUFLOW FV empty GIS files and base FVC file called Create_Empties.fvc.
Reviewing The Model Domain
Become familiar with the model location, using the model mesh, bathymetry, and aerial imagery.
Firstly, open and visualise the model mesh using the below steps and video:
Use the below steps and video to open the TUFLOW Viewer and load the mesh:
- Open the TUFLOW Viewer and move it under the layer panel to make it easier to visualise the mesh extent.
- Select File > Load Results - Map Outputs. Navigate to Cudgen_Creek_001.2dm in the Model_Data folder\Mesh.
- From the TUFLOW Viewer select Toggle Mesh Rendering and review the model extent.
Review the model bathymetry using the below steps and video:
- 1. Drag and drop the model bathymetry file Cudgen_Creek_bathy_001.asc from TUFLOWFV\Tutorial_M03\Model_Data folder\Mesh into the workspace. Note the .asc file may take time load into the QGIS window.
- 2. Right click on the Cudgen_Creek_001 file in the Layers panel and select Properties. From the Symbology tab update the Line width to 0.1.
- 3. Right click on the Cudgen_Creek_bathy_001 file in the Layers panel and select Properties.
- 4. From the Symbology tab, under Band Rendering select the following options:
- Render type: Singleband pseudocolor.
- Set the Min -5 and Max to 5.
- Color ramp: Turbo.
- Mode: Equal Interval.
- Classes: 11.
- Click Apply and OK.
- Zoom in and review the model bathymetry.
To view the model extent we will use Google Hybrid Satellite aerial imagery via the AusMap plugin. Follow the below steps and video to install the plugin and display the imagery:
- 1. Open the Plugins installer via Plugins > Manage and Install Plugins....
- 2. In the Plugins dialog under All search AusMap.
- 3. Select AusMap and Install Plugin.
- 4. Once installation is complete select Close.
- 5. From the menu bar select the new drop down AusMap > Google Basemaps > Google Satellite. In the Layers Panel move the Google Hybrid Satellite below the mesh.
- 6. Right click on the Google Satellite > Properties > Transparency and set the Global Opacity and set it to 70%. Now zoom and view the model extent.
Spatial Definition Of Open Boundary Condition
TUFLOW FV uses nodestrings to specify the location of open boundary conditions. We will create our nodestring by importing an empty template GIS layer using the TUFLOW Plugin and digitising the nodestring locations.
- 2. In the empty dialog box set the following:
Now that the empty Nodestring file has been made we will digitise the model ocean boundary. Use the following steps and video as a guide:
- 1. Zoom into the southern end of the mesh extent.
- 2. Select the 2d_ns_Cudgen_Creek_ocean_boundary_001_L in the Layers panel and select Toggle Editing from the Digitizing toolbar.
- 3. Select Add Line Feature from the Digitizing toolbar.
- 4. At the northern end of mesh offshore of the headland digitise a line. Continue to digitise around the offshore mesh boundary. Note: The boundary conditions do not need to be snapped to the mesh when using the BD flag.
- 5. Use the right mouse button to terminate the line at the southern extent of the mesh offshore of the headland. An attributes dialog will appear, use the below attributes:
- ID = Ocean
- Flags = BD
- 6. Select OK
- 7. From the Digitizing toolbar select Save and Toggle Editing.
Use the below steps and video to to style and label the nodestring with the TUFLOW plugin:
- 1. Right click 2d_ns_ocean_boundary_001_L and select Zoom to Layer(s).
- 2. From the TUFLOW Plugin toolbar select Apply TUFLOW Styles to Current Layer.
- 3. From the TUFLOW Plugin toolbar select Apply Label to Current Layer.
- Note: The arrows shown on the nodestring indicate which direction flow is assigned as positive. In our case, flow from offshore to onshore is assigned a positive sign. For boundaries snapped to the edge of the mesh, digiitising the nodestring in either direction will allow the model to function correctly. More care is required when assigning nodestring direction for flux reporting (we cover this later in this tutorial) and for models with hydraulic structures.
Reviewing Materials
TUFLOW FV uses polygons to specify the spatial location of varying material types within the model domain. To reduce the amount of digitising required in this tutorial we have provided the material file in the Module_Data folder. In this model we have assigned four material types:
Landuse | Manning's 'n' Bed Roughness | Material ID |
---|---|---|
Estuary Main Channel | 0.025 | 1 |
Mangroves | 0.035 | 2 |
Lake/Canal | 0.015 | 3 |
Ocean | 0.03 | 4 |
Use the below steps and video to review the model material types:
- Drag and drop the material shapefile 2d_mat_Cudgen_Creek_001_R.shp from TUFLOWFV\Tutorial_M03\Model_Data folder\GIS into the QGIS workspace.
- From the TUFLOW Plugin toolbar select Apply TUFLOW Styles to Open Layers.
- From the TUFLOW Plugin toolbar select Apply Label to Current Layer.
- Right click on the 2d_mat_Cudgen_Creek_001_R.shp and select Properties > Symbology and under Layer Rendering update the Opacity to 100%.
- Zoom in and review how the materials vary spatially.
Provided TUFLOW FV GIS Files
To save you time and allow focus on model simulation and review, multiple model files have been provided. Copy the following files from the Model_Data folder into the specified folders:
Model Data\GIS | Copy to Working\TUFLOWFV | Description |
---|---|---|
2d_mat_Cudgen_Creek_001_R.* | \model\gis | Specifies the spatial location of varying material types within the model domain. |
2d_zln_Cudgen_Creek_breaklines_001_L.* | \model\gis | GIS polyline layer that defines breakline features. These are used to specify spatial variations of elevation within the estuary. The suffix _L defines a polyline feature type. |
2d_zln_Cudgen_Creek_breaklines_001_P.* | \model\gis | GIS point layer that defines the elevation changes along the 2d_zln breakline file. The suffix _P defines a point feature type. |
2d_zln_Cudgen_Creek_bridge_001_R.* | \model\gis | GIS regions (polygon) layer that defines the elevation of the bridge abutments. The suffix _R defines a region feature type. |
2d_ns_Cudgen_Creek_flux_001_L.* | \model\gis | GIS polyline layer that defines 2d_ns used to output fluxes across nodestrings. The suffix _L defines a polyline feature type. |
Model Data\Mesh | Copy to Working\TUFLOWFV | Description |
Cudgen_Creek_001.2dm | \model\geo | Model mesh file. |
Cudgen_Creek_bathy_001.asc | \model\geo | Model bathymetry file. |
*Multiple files with the same name as the shapefile but with a different file extension support a shapefile (e.g. .shx, .prj, .cpg, .dbf). Ensure you copy all files into relevant folder.
Provided TUFLOW FV Boundary Conditions
Boundary conditions are how we assign external hydrodynamic and meteorological forcing to the model. The Cudgen Creek model is going to use astronomical tide and meteorological boundary condition types.
To streamline the model build, we have developed the boundary conditions files for you. Copy the files in the table below from the Model_Data\BC folder into the Working\TUFLOWFV\bc_dbase model boundary condition folder.
The contents of each file are discussed in more detail in the Astronomical Tidal Boundary and Atmospheric Boundaries sections.
Model Data\BC | Description |
---|---|
FES2014_20221231_20230202_UTC.fvc | Astronomical tide water level boundary conditions. |
FES2014_20221231_20230202_UTC.nc | |
CFSR_20230101_20230201_GDA94Z56_UTC.fvc | Atmospheric boundary conditions. Wind speed, mean sea level pressure. |
CFSR_20230101_20230201_GDA94Z56_UTC.nc | |
WAVES_20230101_20230107_GDA94Z56_UTC.fvc | Wave boundary conditions. The grids B, C and D are nested model result outputs from the spectral wave model SWAN. |
B_20230101_20230107_GDA94Z56_UTC.nc | |
C_20230101_20230107_GDA94Z56_UTC.nc | |
D_20230101_20230107_GDA94Z56_UTC.nc |
TUFLOW FV Control File
Create The TUFLOW FV Control File (FVC)
The TUFLOW FV Control File (.fvc extension) is created via a text editor. Notepad++ is recommended for this purpose as it allows for syntax highlighting of TUFLOW FV specific commands. This configuration information is provided in NotepadPlusPlus_Tips.
- 1. To setup our .fvc Launch Notepad++ and select File > Open... and navigate to the TUFLOWFV\runs folder and open Create_Empties.fvc.
- 2. Save a new copy of this file into the TUFLOWFV\runs folder and call it Cudgen_Creek_001.fvc.
- Note: Your FVC will already have some commands. These are default commands produced when you configured the TUFLOW FV project. We will discuss these commands in the next section. Remember to enable the TUFLOW syntax highlighting using TUFLOW syntax highlighting for Notepad++.
- 3. The FVC already contains commands to define the GIS format and model projection. Comment out the last command since we don’t need to generate empty files again.
GIS FORMAT == SHP SHP Projection == ..\model\gis\projection.prj Tutorial Model == ON !Write Empty GIS Files == ..\model\gis\empty
- 4. The required commands are provided in the code blocks below. A brief description is also provided via a series of comments (green text after ! syntax). Copy the commands into your fvc file and save the file in Notepad++:
! TUFLOW FV Tutorial ! 2D hydrodynamic model of Cudgen Creek GIS FORMAT == SHP ! GIS layers will be ESRI Shapefile SHP Projection == ..\model\gis\projection.prj ! Projection string. All GIS layers in the model need to be in the same reference system Tutorial Model == ON ! Run the model in license free demo/tutorial mode ! Write Empty GIS Files == ..\model\gis\empty ! Generate empty template GIS layers. Already completed via QGIS
!__________________________________________________________________________________________________________________________________ ! SIMULATION CONFIGURATION Bottom Drag Model == Manning ! Use Manning's 'n' Coefficient for bed roughness
!__________________________________________________________________________________________________________________________________ ! TIME COMMANDS Time Format == ISODATE ! Specifies the model to use an ISO date and time format dd/mm/yyyy HH:MM:SS Start Time == 01/01/2023 00:00:00 ! Model start time (UTC) End Time == 02/01/2023 00:00:00 ! Model end time (UTC) CFL == 0.95 ! Courant stability criterion Timestep Limits == 0.1, 1.0 ! Minimum model timestep (s), Maximum model timestep (s)
!__________________________________________________________________________________________________________________________________ ! MODEL PARAMETERS Cell Wet/Dry Depths == 0.005, 0.05 ! Cell wet depth (m) below this depth the cell has its momentum set to zero, Cell dry depth (m) below this depth cell is dropped from computation (mass conserving) Momentum Mixing Model == Smagorinsky ! Sub-grid scale eddy viscosity model Global Horizontal Eddy Viscosity == 0.5 ! Smagorinsky coefficient Global Horizontal Eddy Viscosity Limits == 0.05, 99999. ! Minimum eddy viscosity (m^2/s), Maximum eddy viscosity (m^2/s)
!__________________________________________________________________________________________________________________________________ ! GEOMETRY Geometry 2D == ..\model\geo\Cudgen_Creek_001.2dm ! Computational mesh
! Topography/Bathymetry Set Zpts == 10.0 ! Sets the default elevation (m) Read Grid Zpts == ..\model\geo\Cudgen_Creek_bathy_001.asc ! Digital elevation model Read GIS Z Line == ..\model\gis\2d_zln_Cudgen_Creek_breaklines_001_L.shp | ..\model\gis\2d_zln_Cudgen_Creek_breaklines_001_P.shp ! Breaklines 2d_zln polyline and 2d_zln point GIS layers Read GIS Z Line == ..\model\gis\2d_zln_Cudgen_Creek_bridge_001_R.shp ! Bridge abutments represented by a 2d_zln region GIS layer
! Materials Set Mat == 4 ! Sets the default material to Ocean Read GIS Mat == ..\model\gis\2d_mat_Cudgen_Creek_001_R.shp ! Material 2d_mat polygon GIS layer
! Boundary and Flux Reporting Nodestrings Read GIS Nodestring == ..\model\gis\2d_ns_Cudgen_Creek_ocean_boundary_001_L.shp ! Open boundary 2d_ns nodestring GIS layer Read GIS Nodestring == ..\model\gis\2d_ns_Cudgen_Creek_flux_001_L.shp ! Flux 2d_ns nodestring GIS layer
!__________________________________________________________________________________________________________________________________ ! MATERIAL PROPERTIES
Material == 1 ! Estuary channel
Bottom Roughness == 0.025 ! Manning's 'n' roughness coefficient
End Material
Material == 2 ! Mangroves
Bottom Roughness == 0.035 ! Manning's 'n' roughness coefficient
End Material
Material == 3 ! Lake and canal
Bottom Roughness == 0.015 ! Manning's 'n' roughness coefficient
End Material
Material == 4 ! Ocean
Bottom Roughness == 0.030 ! Manning's 'n' roughness coefficient
End Material
!__________________________________________________________________________________________________________________________________ ! INITIAL CONDITIONS Initial Water Level == -0.29 ! Global water level at model start time in meters
!__________________________________________________________________________________________________________________________________ ! BOUNDARY CONDITIONS Include == ..\bc_dbase\FES2014_20221231_20230202_UTC.fvc ! Include file for tidal boundary conditions Include == ..\bc_dbase\CFSR_20230101_20230201_GDA94Z56_UTC.fvc ! Include file for atmospheric boundary conditions
!__________________________________________________________________________________________________________________________________ ! OUTPUT COMMANDS
Logdir == log ! Directory where the TUFLOW FV log file will be saved
Write Check Files == ..\check ! Directory where GIS check files will be saved
Output Dir == ..\results\ ! Directory where time series and map output results will be saved
Output == NetCDF ! Output block, NetCDF output format Output Parameters == h, v, d ! Water level, velocity, water depth
Output Interval == 900. ! Results will be saved every 900 seconds (15mins) of simulation time
End Output
Output == Flux ! Output fluxes across nodestrings Output Interval == 900. ! Results will be saved every 900 seconds (15mins) of simulation time
End Output
Output == Mass ! Report whole of model mass content Output Interval == 900. ! Results will be saved every 900 seconds (15mins) of simulation time
End Output
Astronomical Tidal Boundary
TUFLOW FV offers a range of methods to apply astronomical tide boundaries. While all astronomical tidal boundaries will vary water level as a function of time, you have options for how to spatially vary the water level along the boundary. If using a small domain, it may be sufficient to use a spatially constant (WL type) nodestring boundary. For larger domains, such as the Cudgen tutorial, a spatially varying water level is required to correctly capture the spatial gradient of tidal amplitude and the phase of the tide. In TUFLOW FV the two boundary condition types to provide spatially varying water levels are water level slope (WLS) and water level curtain (WL_CURT). We will be using a water level curtain.
The water level curtain boundary type reads data from a NetCDF data file and assigns it to the location of the nodestring you specify. The NetCDF and include file have been pre-generated using the TUFLOW FV Get Tide tool using data from the FES 2014 global tide model.
Open the TUFLOW FV Include file FES2014_20221231_20230202_UTC.fvc in Notepad++ and review the commands:
! TUFLOW FV FVC File for FES2014 TIDE Dataset ! Written by `get_tide`
! Netcdf start time (UTC): 2022-12-31 00:00 ! Netcdf end time (UTC): 2023-02-02 00:00 ! Notes: !- The time variable is in Coordinated Universal Time (UTC)
BC == WL_CURT, Ocean, FES2014_20221231_20230202_UTC.nc ! WL curtain, nodestring ID provided from your 2d_ns nodestring GIS layer, NetCDF (.nc) .nc file BC Header == time, nsOcean_chainage, dummy, nsOcean_wl ! Time (UTC), chainage (m), elevation (mRL) - Z coordinate variable, not required for 2D water level boundaries. Here 'dummy' will ensure TUFLOW FV ignores this input, water level (mRL, here mMSL) BC Update dt == 60. ! The boundary is updated every 60 (s) BC Time Units == days ! Units for the boundary condition time variable (days since the bc reference time) BC Reference Time == 01/01/1990 00:00 ! Time that the boundary condition time units are relative to dd/mm/yyyy HH:MM BC Default == NaN ! The default value TUFLOW FV assigns if there is any missing water level data. NaN will assign the water level from the adjacent cell (a zero gradient bc) Includes mslp == 0 ! No manual atmospheric pressure correction has been completed to the raw water level data within variable nsOcean_wl. If mslp is included in the model have TUFLOW FV undertake the pressure correction End BC
Note: The line: bc == WL_CURT, Ocean, FES2014_20221231_20230202_UTC.nc contains the nodestring name we entered when digistising our boundary nodestring. This name connects the spatial location of the boundary to the data.
The figure below depicts the water level timeseries at a specified location (20 km) along the ocean boundary. We can see water level fluctuations across the time period that are consistent with astronomical influences on tides.
The astronomical tide boundary can also be viewed as a long section of the water level along the entire ocean boundary at a particular time. For example at: 09/01/2023 00:00:00 (UTC dd/mm/yyyy HH:MM:SS). The figure below shows the spatial variation of the sloping water surface boundary.
Atmospheric Boundaries
Spatially, coastal model domains typically extend tens to hundreds of kilometers along and offshore. When modelling over these distances there can exist significant spatial variation in atmospheric conditions. For example, wind speed at unprotected sites offshore will typically have higher wind speeds when compared with protected overland sites. There also exist temporal variations, such as diurnal sea breeze effects or passing weather fronts. To capture this variation, hydrodynamic models are commonly forced by atmospheric forecast, or reforecast models.
For our boundary conditions, we will be using forecast model output sourced from NCEP CFSv2, pre-generated using the TUFLOW FV Get Atmos tool. Open the TUFLOW FV Include file CFSR_20230101_20230201_GDA94Z56_UTC.fvc in Notepad++ and review the commands:
! TUFLOW FV FVC File for Atmospheric Dataset ! Written by `get_atmos`
! Netcdf start time: 2022-12-31 00:00 ! Netcdf end time: 2023-02-02 00:00 ! Netcdf x-limits: 540010.9087, 580347.5882 ! Netcdf y-limits: 6845154.0753, 6890652.8548 ! Notes: ! - The time variable is in Coordinated Universal Time (UTC)
Grid Definition File == CFSR_20230101_20230201_GDA94Z56_UTC.nc ! NetCDF (.nc) containing coordinate variables that define the regular grid to map data variables to Grid Definition Variables == x, y ! X and y coordinate variables. This model uses cartesian coordinates in GDA94Z56 Grid Definition Label == atmos ! Name of the grid. Can be referred to by multiple boundary conditions later as required End Grid
BC == W10_GRID, atmos, CFSR_20230101_20230201_GDA94Z56_UTC.nc ! Gridded wind boundary type, NetCDF containing data variables BC Header == time, uwnd10m, vwnd10m ! Time (UTC), wind speed x component (m/s), wind speed y component (m/s) BC Update dt == 3600. ! The boundary is updated every 3600 (s) BC Time Units == hours ! Units for the boundary condition time variable (hours since the bc reference time) BC reference time == 01/01/1990 00:00 ! Time that the boundary condition time units are relative to dd/mm/yyyy HH:MM BC Default == NaN ! The default value TUFLOW FV assigns if there is any missing data End BC
BC == MSLP_GRID, atmos, CFSR_20230101_20230201_GDA94Z56_UTC.nc ! Gridded mean sea level pressure boundary type, NetCDF containing data variables BC Header == time, mslp ! Time (UTC), Pressure (TUFLOW FV expects hectopascals, see BC Scale below) BC Update dt == 3600. ! The boundary is updated every 3600 (s) BC Time units == hours ! Units for the boundary condition time variable (hours since the bc reference time) BC Reference Time == 01/01/1990 00:00 ! time that the boundary condition time units are relative to dd/mm/yyyy HH:MM BC Default == NaN ! A NaN value is applied when TUFLOW FV reads a null-value from a boundary condition input BC Scale == 0.01 ! CFSR MSLP data is downloaded in Pascals (Pa). Converting Pa to hPa End BC
Displaying Atmospheric Boundaries In QGIS
Gridded atmospheric data is read into TUFLOW FV via NetCDF format and this data can be readily reviewed in QGIS using the TUFLOW FV. Using the TUFLOW Viewer follow the below steps and video to open the atmospheric data and review the wind vectors:
- Select File > Load Results - Map Outputs. Navigate to CFSR_20230101_20230201_GDA94Z56_UTC.nc in the Working\TUFLOWFV\bc_dbase folder and open it.
- In the Layers Panel move CFSR_20230101_20230201_GDA94Z56_UTC below the Cudgen_Creek_001 mesh file.
- Right click on CFSR_20230101_20230201_GDA94Z56_UTC and select Properties. In the Layer Properties select the Source and from the Assigned Coordinate Reference System (CRS) drop down select EPSG:4326 - WGS 84. Note: The NetCDF contains both longitude latitude and cartesian coordinate variables. To display correctly in QGIS the longitude latitude coordinates are used. When TUFLOW FV reads the boundary conditions via the include file, the cartesian Eastings and Northings variables in GDA94Z56 are specified to ensure the boundary conditions are aligned with the model mesh.
- From the TUFLOW Viewer under Result Type select wind_10 Vector and right to select Properties. Note: for visualisation purposes the video also displays the Easting Map Output.
- In the Layer Properties select Symbology. Select the Vectors tab and update the following:
- Set the Arrow Length to Scaled to Magnitude with a Scale by a factor of 15.0.
- Holding shift select CFSR_20230101_20230201_GDA94Z56_UTC and Cudgen_Creek_001 within the TUFLOW Viewer Open Results window. Both results will be visible in the workspace now.
- Check Show as dates and move the timestep slider to view how the wind vectors change. Notice how the offshore wind speed is higher compared with protected overland areas.
Using the TUFLOW Viewer follow the below steps to plot a time series of MSLP and wind speed:
- Undock and resize the TUFLOW Viewer so that the plot window size is maximised (refer to video) and select the Refresh Current Plot button.
- Select the Plot Time Series drop down and check mean_sea_level_pressure and wind_10m.
- Select the Plot Time Series button the and your cursor will become a crosshair [+]. Digitise the time series on the model mesh (refer to video).
- Under the Result Type set wind_10m to secondary axis by selecting the Secondary Axis button to the right of the result type. Once selected it will turn red.
- Select Settings > Options and select the Plotting tab to update the Display Format* to DD/MM/YYYY.
- Select the Edit axis, curve and image parameters button . From the Customize window Select the Primary Axis and update the following:
- Under X- Axis update the Label to Date (dd/mm/yyyy UTC).
- Under Y- Axis update the Lable to MSLP (Pa).
- Select the Edit axis, curve and image parameters button . From the Customize window Select the Secondary Axis and update the following:
- Under Y- Axis update the Lable to 10m 10min Wind Speed (m/s).
Note that MSLP as downloaded is in units of Pascals. In the Include file CFSR_20230101_20230201_GDA94Z56_UTC.fvc a bc scale of 0.01 is used to convert to hectopascals, the units required by TUFLOW FV.
Use the below steps to close the data and clear the Time series plot:
- Redock the TUFLOW Viewer (refer to Video)
- Under the Open Results right click on CFSR_20230101_20230201_GDA94Z56_UTC and select Close Result.
- Select the Clear Current Plot Button .
Run TUFLOW FV
The model will be run using a Windows Batch file. This approach calls the TUFLOW FV executable file (.exe) and runs the TUFLOW FV Control file (.fvc).
- An example batch file (run_simulations.bat) has been included in the tutorial dataset download within the Complete_Model\TUFLOWFV\runs folder.
- Copy the .bat file into your Working\TUFLOWFV\runs and open it in Notepad++.
- Line 2 (as shown in the figure below) includes a file path to the executable from Exe\2023.1.1. Note: A relative path is used for the executable and the FVC, a full file path can also be used. The path is saved to the local Windows environment variable exe. Line 4 sets the number of parallel CPU threads to run the simulation on. Line 6 calls the TUFLOW FV executable file (it's path is saved in the environmental variation exe) and runs Cudgen_Creek_001.fvc. Line 9 keeps the Windows prompt open, rather than closing it automatically after the simulation completes.
- On Line 7 ensure to add the text REM. REM stands for remark or comment and it disables the line from being executed by Windows. This batch file will run Cudgen_Creek_001.fvc but it will not run the simulation Cudgen_Creek_002.fvc (Cudgen_Creek_002.fvc is an additional model run presented later in the tutorial).
- Save the batch file and double click it in file explorer to run the simulation.
To run the batch file, double click on run_simulations.bat from Windows Explorer:
For more information on setting up a .bat file and running multiple models, head to Running TUFLOW FV.
Troubleshooting And Reviewing Log Files
TUFLOW FV generates a log file which records TUFLOW FV console output. The .log file enables modelers to review the performance, errors and warnings throughout the simulations.
Navigate to Cudgen_Creek_001.log in the Working\TUFLOWFV\runs\log\ folder and open in Notepad++:
- To confirm the model has completed successfully, navigate to the bottom of the log file (Tip: Try the keyboard shortcut CTRL + End). If the model has successfully completed you should see the text Run Sucessful. If not the simulation has exited prematurely and may may be due to syntax errors in the inputs. See the following link for advice: Common reasons why a model won’t start.
- Note the Elapsed System_time. This is the time that the computer took to perform the simulation following model initialisation. On our hardware the model took approximately 11 minutes (662.3602 seconds).
- Note the Runtime ratio of 138.8264 is the dimensionless ratio between model simulation time and the actual time the model took to run. Here the model has been simulated for 24 hrs (86400 s) and took 662.3602 seconds to compute ( 86400 s/ 662.3602 s). For example, this model could run 150 hrs of simulation time in 1 hour and 4 minutes of Elapsed System_time.
- Carefully review the log file warnings issued during the the simulation. Here we have 2 warnings throughout the simulation as shown by the Number of warnings message:
To find review these warnings select Ctrl+F and type "WARNING" into the find dialog box:
The warnings are associated with the tidal boundary bc block:
- The first "WARNING: NS_CHAINAGE variable is stationary (no time dimension)" is stating that the variable NSOCEAN_CHAINAGE has no time dimension. The chainage variable defines the distance along the nodestring where water levels are assigned. Unlike the water level dimension, the chainage does not change with time, and therefore we can safely ignore this message.
- The second "WARNING: DUMMY variable not found in netcdf file. Assigning a NaN value" is stating that the DUMMY variable is not present within the NetCDF. As water level is a 2D variable, the elevation input variable is not required. Here "dummy' has been used as a placeholder for the elevation data that is not required in this simulation. TUFLOW FV will not find the variable "dummy" which is not a variable within the NetCDF and assign a NaN value to this boundary input.
Reviewing Map Output Results
In this section we will review map output results in QGIS using the TUFLOW Viewer Plugin.
As shown below our model setup specifies an output format as a NetCDF file with the map output parameters water level (h), velocity (v), and water depth (d), saved every 900 seconds (15 mins).
Output == NetCDF ! Output block, NetCDF output format Output Parameters == h, v, d ! Water level, velocity, water depth
Output Interval == 900. ! Results will be saved every 900 seconds (15mins) of simulation time
End Output
Results are saved to the file: Working\TUFLOWFV\results\Cudgen_Creek_001.nc.
Note: Model outputs from TUFLOW FV will have the same file name as the TUFLOW FV Control file, however the extension is modified, in this case to '.nc', for NetCDF format.
Use the below steps and video to open the results and set up the TUFLOW Viewer display:
- In the TUFLOW Viewer, right click on the Cudgen_Creek_001 mesh file and select Close Result. We will use the mesh data saved within the NetCDF and no longer need the *.2dm mesh file open.
- Select File > Load Results - Map Outputs. Navigate to Cudgen_Creek_001.nc in the Working\TUFLOWFV\results folder and open it.
- Right click within the Result Type window and select Properties and update the mesh symbology with a Line width of 0.1.
- Select Settings > Options and select the Plotting tab to update the Display Format* to hh:mm. This display format is selected as the model simulation period was only 24 hours. For longer duration models a time display of DD/MM/YYYY hh:mm is preferred.
- Right click on the plot and update the Axis Font Size and Axis Label Font Size to 8.
Using the TUFLOW Viewer follow the below steps and video to visualise how the tide influences flow velocity vectors during the flood and ebb tides:
- Under the Result Type, select velocity vectors and water surface elevation.
- Slide the timestep slider a few timesteps forward and turn off the mesh by selecting Toggle Mesh Rendering.
- Under the Result Type, right click on water surface elevation and select Properties.
- Select the contour tab and update the following:
- Min -0.5 m and Max 0.5 m
- Color ramp Spectral and invert Color Ramp
- Set the classification mode to Equal Interval
- Set the Classes to 11
- Select Apply.
- Select the Vectors tab and update the following:
- Check Display on User Grid
- Specify an X spacing of 30px and Y spacing of 30px
- Set the Arrow Length to Fixed with a length of 8.0
- Select Apply and OK.
- Move the timestep slider to view how the velocity vectors and water surface elevation change throughout the simulation.
Use the below steps and video to create a time series of the water level and velocities at a point:
- From the Result Type unselect velocity vectors and turn on the mesh by selecting Toggle Mesh Rendering.
- Zoom into the estuary entrance (refer to video).
- Select the Plot Time Series drop down and check velocity and water surface elevation.
- Select the Plot Time Series button the and your cursor will become a crosshair [+]. Digitise the time series point near the estuary entrance (refer to video).
Use the below steps and video to plot a velocity long section at the bridge flow constriction:
- From the Result Type window select velocity and velocity vector. Right click on the Map Outputs and select Properties.
- Select the contour tab and update the following:
- Max 0.4 m/s (leave the Min as 0)
- Color ramp Spectral and invert Color Ramp
- Set the classification mode to Equal Interval
- Set the Classes to 11
- Select Apply.
- Select the Vectors tab and update the following:
- Set the Arrow Length to Scaled to Magnitude with a Scale by a factor of 95
- Leave the remaining settings as is
- Select Apply and OK.
- Zoom into the bridge at the lower estuary (refer to video).
- Use the timestep slider to view how the velocity and velocity vectors change throughout the simulation and how the constriction from the bridge influences the velocities.
- 6. Move to time step slider back to timestep 01/01/2023 01:45:00.
- 7. From the Plot Cross Section / Long Plot drop down check velocity.
- 8. Select the Plot Cross Section / Long Plot button and your cursor will become a crosshair [+]. Using the cell centers as a guide digitise a long section from downstream to upstream of the bridge (refer to video)
- 9. Slide the time step to see how the velocity long section changes throughout the simulation.
Reviewing Time Series Results
Overview
As part of the TUFLOW FV control file setup flux outputs were requested at 900 second (15 minute) intervals as shown below:
Output == Flux ! Output fluxes across nodestrings Output Interval == 900. ! Results will be saved every 900 seconds (15mins) of simulation time
End Output
Flux output generates time series output for each nodestring in the model. The time series is calculated based on the net flux that occurs over all the cell faces each nodestring selects. For example, the below picture shows the cell faces selected by nodestring ID CH_1600:
Benefits of outputting flux outputs include:
- Output size: As the locations of the nodestrings are explicitly specified via GIS the result size is many times smaller than the map NetCDF output.
- Flexibility: As file size isn't typically an issue (when compared with NetCDF outputs) there is typically freedom to specify higher temporal resolution output for model checking.
- Accuracy: Flux outputs are the direct mass flows across cell faces selected by the nodestring as modelled by TUFLOW FV. There is no spatial or temporal interpolation. Flux outputs are therefore a reliable estimate of flow rate, or mass fluxes.
- CSV Output: Results can be easily viewed in common viewing software such as Microsoft Excel.
The major disadvantage of flux output is that you need to specify the nodestring locations before you run the model.
Viewing Time Series Results
Use the below steps and video to open the flux outputs and view them using the TUFLOW Viewer:
- From the TUFLOW Viewer select File > Load Results - Time Series. Navigate to Cudgen_Creek_001.tpc in Working\TUFLOWFV\results\plot\ and open.
- Select Yes when asked Do you also want to open result GIS layer?. Select the Cudgen_Creek_001_PLOT_L in the layers panel. This GIS layer contains the nodestring locations and IDs.
- Turn on the Apply Label To Current Layer and select the Select Features curser.
- From the Result Type window select Flow and zoom into the estuary entrance (refer to video).
- Select the NSEntrance nodestring and the flux output for this nodestring will appear in the Time Series plot. Note if you do not have have the Select Features curser activated you will be unable to select the nodestring.
- Use step 4 for the remaining upstream flux nodestrings.
Use the below steps and video to compare the downstream and upstream flux outputs:
- Right click on the plot window and select Clear Plot.
- Right click on Cudgen_Creek_001_PLOT_L and select Zoom to Layer(s).
- Select the nodestring at the estuary entrance and hold the Shift key. Then select the furthest upstream nodestring. As you can see flow rate passing through the upstream nodestring is significantly lower than the downstream nodestring. This is due to attenuation of the astronomical tide by the estuary.
TUFLOW FV Model Waves
In this section the effect of wave breaking on hydrodynamics is explored. Gridded wave boundary conditions are provided from the spectral wave model SWAN. The wave model SWAN is used for wave generation and transformation in relatively shallow waters (see https://swanmodel.sourceforge.io/ for more information). The wave models have been run under a simplified case of constant wind speed from the south east at 25km/hr and a constant 2.5m easterly swell with an 8s period.
TUFLOW FV Control File
Save a copy of Cudgen_Creek_001.fvc and name it Cudgen_Creek_002.fvc. In Notepad++ copy the below commands into your new fvc file and save the file:
Update the Boundary conditions block to include waves:
!__________________________________________________________________________________________________________________________________ ! BOUNDARY CONDITIONS Include == ..\bc_dbase\FES2014_20221231_20230202_UTC.fvc ! Include file for tidal boundary conditions Include == ..\bc_dbase\CFSR_20230101_20230201_GDA94Z56_UTC.fvc ! Include file for atmospheric boundary conditions
Include == ..\bc_dbase\WAVES_20230101_20230107_GDA94Z56_UTC.fvc ! Include file for wave boundary conditions
Update the output block to include the following wave output parameters wave height (WvHt), wave period (WvPer), wave direction (WvDir) and wave stress vectors (WvStr):
Output == NetCDF ! Output block, NetCDF output format Output Parameters == h, v, d, WvHt, WvPer, WvDir, WvStr ! Water level, velocity, water depth, Wave height, Wave period, Wave direction, Wave stress vector
Output Interval == 900. ! Results will be saved every 900 seconds (15mins) of simulation time
End Output
Wave Boundary
For our wave boundary conditions, we are applying gridded wave data generated using the wave model SWAN. The provided NetCDF files were pre-generated using TUFLOW's freely available SWAN GIS Tools. SWAN utilises nested grids to capture wave generation and transformation at the site of interest. Open the TUFLOW FV provided Include file WAVES_20230101_20230107_GDA94Z56_UTC.fvc in Notepad++ and review the commands:
! Wave Boundary Include File ! Contains gridded results from SWAN ! The SWAN models were generated using TUFLOW's freely available SWAN GIS Tools ! Idealised wave conditions with constant 25 m/s SE local winds and 2.5m, 8s easterly offshore swell ! ! --Table 1 - SWAN NetCDF Boundary Variables-- ! X Coordinate (GDA94Z56): Xp ! Y Coordinate (GDA94Z56): Yp ! Time (UTC): time ! Significant Wave Height (m): hsig ! Smoothed Peak Wave Period (s): tpsmoo ! Mean Wave Direction (degrees Cartesian convention**): dir ! Bottom Orbital Velocity Maxima Root Mean Square Value (m/s#): ubot ! Bottom Wave Period (s): tmbot ! Wave Force Vector X Component (N/m^2): wforce_x ! Wave Force Vector Y Component (N/m^2): wforce_y ! Do Not Apply: ignore^ ! ! **Direction wave are heading to in degrees, axis positive anti-clockwise from East ! ! ^ Where 'ignore' used TUFLOW FV will not find this variable and omit it from the simulation ! 'ignore' is used here to not apply wave force outputs for larger model domains ! ! # Ubot bc scaling of 1.414 adjusts ubot to be calculated on significant wave height rather than the SWAN default root mean square wave height ! !__________________________________________________________________________________________________________________________________ ! START OF CONTROL FILE ! Wave breaking and depth limiting parameters Wave Parameters == 0.5, 0.05 ! Wave Gamma (Maximum ratio of wave height (m) / depth(m)), Wave stress depth limit (m)
! SWAN Spectral Wave Model Results ! Grids are 'stamped' on top of each other with increasing priority as you move down the file
! --B 500m South Stradbroke Island to Evans Head-- Grid Definition File == .\B_20230101_20230107_GDA94Z56_UTC.nc ! NetCDF (.nc) file containing spatial grid. 'B Grid' - 500m x 500m regular grid Grid Definition Variables == Xp, Yp ! X and Y coordinates (GDA94Z56 projection) Grid Definition Label == B ! Name of the coordinate grid End BC
BC == WAVE, B, .\B_20230101_20230107_GDA94Z56_UTC.nc ! NetCDF (.nc) file containing wave boundary variables applied to the 'B' grid definition BC Header == time, hsig, tpsmoo, dir, ubot, tmbot, ignore, ignore ! BC variable order. Refer Table 1 above BC Scale == 1., 1., 1., 1.414, 1., 1., 1. ! Scale factor for hsig, tpsmoo, dir, ubot, tmbot, wforce_x, wforce_y (# refer note on ubot scaling) BC Reference Time == 01/01/1970 00:00 ! Time that the BC Time Units are relative to dd/mm/yyyy HH:MM BC Time Units == seconds ! Time units for the BC (seconds since the BC Reference Time) BC Update dt == 900. ! The boundary is updated every 900(s) End BC
! --C 100m Burleigh Heads to Cabarita-- Grid Definition File == .\C_20230101_20230107_GDA94Z56_UTC.nc ! NetCDF (.nc) file containing spatial grid. 'C Grid' - 100m x 100m regular grid Grid Definition Variables == Xp, Yp ! X and Y coordinates (GDA94Z56 projection) Grid Definition Label == C ! Name of the coordinate grid End BC
BC == WAVE, C, .\C_20230101_20230107_GDA94Z56_UTC.nc ! NetCDF (.nc) file containing wave boundary variables applied to the 'C' grid definition BC Header == time, hsig, tpsmoo, dir, ubot, tmbot, ignore, ignore ! BC variable order. Refer Table 1 above BC Scale == 1., 1., 1., 1.414, 1., 1., 1. ! Scale factor for hsig, tpsmoo, dir, ubot, tmbot, wforce_x, wforce_y (# refer note on ubot scaling) BC Reference Time == 01/01/1970 00:00 ! Time that the BC Time Units are relative to dd/mm/yyyy HH:MM BC Time Units == seconds ! Time units for the BC (seconds since the BC Reference Time) BC Update dt == 900. ! The boundary is updated every 900(s) End BC
! --D 20m Local Cudgen Creek Mouth-- Grid Definition File == .\D_20230101_20230107_GDA94Z56_UTC.nc ! NetCDF (.nc) file containing spatial grid. 'D Grid' - 20m x 20m regular grid Grid Definition Variables == Xp, Yp ! X and Y coordinates (GDA94Z56 projection) Grid Definition Label == D ! Name of the coordinate grid End BC
BC == WAVE, D, .\D_20230101_20230107_GDA94Z56_UTC.nc ! NetCDF (.nc) file containing wave boundary variables applied to the 'D' grid definition BC Header == time, hsig, tpsmoo, dir, ubot, tmbot, ignore, ignore ! BC variable order. Refer Table 1 above BC Scale == 1., 1., 1., 1.414, 1., 1., 1. ! Scale factor for hsig, tpsmoo, dir, ubot, tmbot, wforce_x, wforce_y (# refer note on ubot scaling) BC Reference Time == 01/01/1970 00:00 ! Time that the BC Time Units are relative to dd/mm/yyyy HH:MM BC Time Units == seconds ! Time units for the BC (seconds since the BC Reference Time) BC Update dt == 900. ! The boundary is updated every 900(s) End BC
To capture the wave resolution at the estuary entrance the nested grids increase in resolution at the entrance. The spatial extents and grid resolution of the nested model domains are shown in the below figure and table:
Grid ID | Grid Cell Size |
---|---|
B Grid | 500m x 500m |
C Grid | 100m x 100m |
D Grid | 20m x 20m |
Run TUFLOW FV
Open the run_simulations.bat has been included in the tutorial dataset download within the Complete_Model\TUFLOWFV\runs folder. Update the following and run the model:
- Line 6 add the text REM (as shown in the figure below) to disables the line from being executed by Windows.
- On Line 7 remove the text REM so that the batch file will run Cudgen_Creek_002.fvc.
- Save the batch file and double click it in file explorer to run the simulation as shown in section Run TUFLOW FV.
Reviewing Results
In this section we will review map output results in QGIS using the TUFLOW Viewer Plugin. Our model setup specifies an output format as a NetCDF file with the map output parameters water level (h), velocity (v), and water depth (d), wave height (WvHt), wave period (WvPer), wave direction (WvDir) and wave stress vectors (WvStr) saved every 900 seconds (15 mins). Results are saved to the file Working\TUFLOWFV\results\Cudgen_Creek_002.nc.
Use the below steps and video to open the results and review the significant wave height across the model domain:
- Select File > Load Results - Map Outputs. Navigate to Cudgen_Creek_002.nc in the Working\TUFLOWFV\results folder and open it
- From the Result Type window select significant wave height. Right click on the Map Outputs and select Properties.
- Select the contour tab and update the following:
- Max 2.0 m (leave the Min as 0).
- Under the color ramp tab select Create New Color Ramp....
- From the Color ramp type drop down select Catalog: cpt-city.
- Under the Name panel select Top of the (c3g) palettes. From the the colour palettes options select Jet and Ok.
- Select Apply and OK.
- Zoom in towards the estuary entrance (refer to video) and move the timestep slider to view how the wave height varies throughout the simulation.
Use the below steps and video to review the effect that wave breaking is having on hydrodynamics (Breaking wave setup) and compare water level timeseries with no waves (Cudgen_Creek_001) and with waves (Cudgen_Creek_002):
- Hold shift and from the Open Results window select both Cudgen_Creek_001 and Cudgen_Creek_002.
- Zoom into the estuary entrance (refer to video).
- Select the Plot Time Series drop down and check water surface elevation.
- Select the Plot Time Series button the and your cursor will become a crosshair [+]. Digitise the time series point near offshore of the beach (refer to video).
Use the below steps and video to review the the effect that wave breaking is having on hydrodynamics (Breaking wave setup) across the beach profile:
- Make sure both model results are still selected.
- From the Plot Cross Section / Long Plot drop down check water surface elevation.
- Select the Plot Cross Section / Long Plot button and your cursor will become a crosshair [+]. Digitise a long section from onshore to offshore (refer to video)
- Slide the time step to see how the water surface elevation long section changes throughout the simulation.
Use the below steps and video to review the influence waves have on the velocity vectors and compare the velocity vectors with no waves (Cudgen_Creek_001) and with waves (Cudgen_Creek_002):
- From the Open Results window select Cudgen_Creek_002.
- From the Result Type window unselect significant wave height and select Velocity Vector.
- Zoom into the entrance break walls and slide the time step to see how the flow moves around the break walls.
- Now select Cudgen_Creek_001 and slide the time step and compare the model results with and without waves. Notice how the waves move the water velocities around the break walls.
Going Further - Optional - Extended Simulation
Depending on a projects requirements and objectives it is important to simulate models for longer durations to understand the local hydrodynamics. Here we will re-run the model with waves but extend the run time by a week. Save a copy of Cudgen_Creek_002.fvc and name it Cudgen_Creek_2023-01-01_2023-01-07_UTC_003.fvc. In Notepad++ extend the model end time to 07/01/2023. See below command to update your fvc file with and save the file:
End Time == 07/01/2023 00:00:00 ! Model end time
Run TUFLOW FV
Update run_simulation.bat file and re the run model:
- Line 7 add the text REM (as shown in the figure below).
- On Line 8 add %exe% Cudgen_Creek_2023-01-01_2023-01-07_UTC_003.fvc.
- Save the batch file and double click it in file explorer to run the simulation as shown in section Run TUFLOW FV.
Review The Results
Recreate the result plots demonstrated in Reviewing Results section.
The below time series shows the water surface elevation from the 01/01/2023 00:00:00 UTC to 07/01/2023 00:00:00 UTC at the estuary entrance. We can see the mixed semi diurnal tides (two high and two low tides of different size every lunar day) indicative of the hydrodynamics present at this location.
There are many other viewing features available in the TUFLOW Viewer Plugin. If you would like to try out more features check out: Using The TUFLOW Viewer.
Feedback
If you have any queries, feedback or requests for new functionality you would like added to the tutorial modules, please feel free to get in contact with support@tuflow.com.
If you wish to keep up-to-date with all things TUFLOW and TUFLOW FV, then please join our LinkedIn group.
Conclusion And Next Steps
Well done on completing Tutorial Module 3. You have now learnt how to build, run and review a model and model results of a real-world coastal model example.
Return to the Tutorial Introduction Page to complete further meshing and model build tutorials.