Tutorial M03 draft

TBC Tutorial Description

Read the Tutorial Model Introduction before starting this tutorial. It outlines programs requiring installation.

This tutorial builds upon the previous tutorial models X and Y introducing and is designed to introduce the skills required for coastal modelling. Specifically, this tutorial demonstrates:

• Defining boundary conditions.
• Defining spatially varying landcover via a material coverage.
• Creating a TUFLOW FV simulation.
• X
• Y
• Z
• Importing and reviewing results.

The workflow uses QGIS and Notepad++ to setup and run our models.

IMAGE OF CUDGEN GoES HERE

TBC Requirements And Downloads

Requirement	Brief Description
Model Data	Download the Tutorial Module 2 Data Package MADDYTODO Change link
Assumed Knowledge	It is recommended to complete Tutorial Module 2 and Meshing Module 3 prior to completing this tutorial.

TBC TUFLOW FV Model Development Workflow

We will develop our model using a combination of the QGIS and Notepad++, noting that the mesh has already been developed in Meshing Module 3.

Key components of the workflow include:

• Initialise the TUFLOW FV project and folder structure with the TUFLOW Viewer Plugin for QGIS.
• Generate our spatial layers such as boundary condition nodestrings and material coverages.
• Create our TUFLOW FV control file and define boundary condition time series input data.
• Run the model via a windows batch file.
• Review the model log files, GIS check files and model results.

These key steps and the software package used together in combination are provided in the figure below:

Prepare Your Working Environment

Copy and unzip the folder to your preferred working location on your computer, 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 animation 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_000.qgz.

Set The Projection

Use the below steps and animation to set your workspace projection:

1. Go to Project > Properties.

2. In the CRS tab, type GDA 94 / MGA zone 56.

3. Select the matching projection in the Predefined Coordinate Reference Systems section.

4. Click Apply and OK.

Configuring A TUFLOW FV Project

The TUFLOW 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 animation 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.

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 an 'empty' 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, we will open and visualise the model mesh using the below steps and animation:

1. Drag and drop the model mesh file Cudgen_Creek_001.2dm from TUFLOWFV\Tutorial_M03\Model_Data folder\Mesh.

2. Right click on the Cudgen_Creek_001 file in the Layers panel and select Properties.

3. From the Symbology tab, under Contours uncheck Show Contours.

4. Under the Rendering tab check Native Mesh Rendering.

5. Click Apply and OK.

Review model bathymetry to understand model elevation using the below steps and animation:

1. Drag and drop the model bathymetry file Cudgen_Creek_bathy_001.asc from TUFLOWFV\Tutorial_M03\Model_Data folder\Mesh into the workspace.

2. Right click on the Cudgen_Creek_bathy_001 file in the Layers panel and select Properties.

3. From the Symbology tab, under Band Rendering select the following options:

• Render type: Singleband pseudocolor.
• Set the Min -10 and Max to 10.
• Color ramp: Turbo.
• Mode: Equal Interval.
• Classes: 25.

• Click Apply and OK.

To view the model extent we will use Google Hybrid Satellite aerial imagery via the AusMap plugin. Follow the below steps and animation 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 Hybrid Satellite.

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.

1. Select the Import Empty File symbol from the TUFLOW Plugin toolbar.

2. In the empty dialog box set the following:

• Set Empty Directory by selecting Browse... to select the folder location of the Working folder.
• Select the Empty Type 2d_ns.
• Update the Run ID name to Cudgen_Creek_ocean_boundary.
• Check the Geometry Type: Lines
• Select OK

Now that the empty Nodestring file has been made we will digitise the model ocean boundary. Use the following steps and animation as a guide:

1. Select the 2d_ns_ocean_boundary_001 in the Layers panel and select Toggle Editing from the Digitizing toolbar.

2. Zoom into the southern end of the mesh extent.

3. Select Add Line Feature from the Digitizing toolbar.

4. Create a line offshore of the mesh at Snapper Rocks. Continue to digitize around the offshore mesh boundary. Note: The boundary condition's do not need to be snapped to the mesh.

5. Use the right mouse button to terminate the line at Norreies 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 animation to to style and label the nodestring with the TUFLOW plugin:

1. Right click 2d_ns_ocean_boundary_001 and select Zoom to Layer(s).

2. From the TUFLOW Plugin toolbar select Apply TUFLOW Styles to Open Layers.

3. From the TUFLOW Plugin toolbar select Apply Label to Current Layer.

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:

1. Estuary main channel represented by a Manning's 'n' roughness value of 0.025 and ID 1.
2. Mangroves represented by a Manning's 'n' roughness value of 0.035 and ID 2.
3. Lake and Canal represented by a Manning's 'n' roughness value of 0.015 and ID 3.
4. Ocean represented by a Manning's 'n' roughness value of 0.030 and ID 4.

Use the below steps and animation to review the model material types:

1. 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.
2. From the TUFLOW Plugin toolbar select Apply TUFLOW Styles to Open Layers.
3. From the TUFLOW Plugin toolbar select Apply Label to Current Layer.
4. Zoom in and review how the materials vary spatially.

TUFLOW FV Model Files

To save time and focus on developing key modeling skills multiple model files have been provided in the Model_Data folder

Copy the following files from the Model_Data folder to the specified folders:

Model Data	Copy to Working	Description
Model_Data\GIS\2d_mat_Cudgen_Creek_001_R.*	Working\TUFLOWFV\model\gis	Specifies the spatial location of varying material types within the model domain.
Model_Data\GIS\2d_zln_Cudgen_Creek_breaklines_001_L.*	Working\TUFLOWFV\model\gis	A GIS polyline layer is being used to define breaklines features to define the spatial variations of elevation changes within the estuary. The suffix _L defines a line feature type.
Model_Data\GIS\2d_zln_Cudgen_Creek_breaklines_001_P.*	Working\TUFLOWFV\model\gis	A GIS point layer is being used to define the elevation changes along the above breaklines file. The suffix _P defines a point feature type.
Model_Data\Mesh\Cudgen_Creek_001.2dm	Working\TUFLOWFV\model\geo	Model mesh file.
Model_Data\Mesh\Cudgen_Creek_bathy_001.asc	Working\TUFLOWFV\model\geo	Model bathymetry file.

*Multiple file extensions support a shapefile. Ensure you copy all files into relevant folder.

TUFLOW FV Boundary Conditions

When developing complex models such as this Cudgen Creek with many boundary conditions Include files are recommended to manage and categorise data inputs. The boundary condition data and Include files have been provided in the Module_Data folder.

• Copy FES2014_20221231_20230202_GDA94Z56_AEST.nc and FES2014_20221231_20230202_GDA94Z56_AEST.fvc from Module_Data\BC\ to Working\TUFLOWFV\bc_dbase.
• Copy CFSR_20230101_20230201_GDA94Z56_AEST.nc and CFSR_20230101_20230201_GDA94Z56_AEST.fvc from Module_Data\BC\ to Working\TUFLOWFV\bc_dbase.

An astronomical tidal boundary is applied using data from the FES 2014 global tide model. The tidal data is provided in a NetCDF format, NetCDF layers contain time, space and sometime depth varying boundary conditions. The FES2014_20221231_20230202_GDA94Z56_AEST.nc file was generated using TUFLOW FV Get Tide command line tool using conda. This step has already been undertaken for you and is not outlined in this tutorial, for more information refer toTUFLOW FV Get Tide. TUFLOW FV Include file FES2014_20221231_20230202_GDA94Z56_AEST.fvc has been provide. Open this in Notepad++ and review the follow:

Model Data	Copy to Working	Description
Model_Data\BC\FES2014_20221231_20230202_GDA94Z56_AEST.fvc	Working\TUFLOWFV\bc_dbase	A TUFLOW FV Include file developed to specific boundary conditions commands for the tidal boundary. Outlined in TUFLOW FV Boundary Conditions.
Model_Data\BC\FES2014_20221231_20230202_GDA94Z56_AEST.nc	Working\TUFLOWFV\bc_dbase	Tide boundary condition data from the FES 2014 global tide model. Outlined in TUFLOW FV Boundary Conditions.
Model_Data\BC\CFSR_20230101_20230201_GDA94Z56_AEST.fvc	Working\TUFLOWFV\bc_dbase	A TUFLOW FV Include file developed to specific boundary conditions commands for the atmospheric boundary. Outlined in TUFLOW FV Boundary Conditions.
Model_Data\BC\CFSR_20230101_20230201_GDA94Z56_AEST.nc	Working\TUFLOWFV\bc_dbase	Atmospheric boundary condition data from the CRFS global atmospheric model.
Model_Data\BC\HYCOM_20230101_20230201_GDA94Z56_AEST.fvc	Working\TUFLOWFV\bc_dbase	A TUFLOW FV Include file developed to specific boundary conditions commands for the ocean boundary. Outlined in TUFLOW FV AD Boundary Conditions. (MB TBD)
Model_Data\BC\HYCOM_20230101_20230201_GDA94Z56_AEST.nc	Working\TUFLOWFV\bc_dbase	Ocean boundary condition data from the HYCOM global ocean model. Outlined in TUFLOW FV AD Boundary Conditions (MB TBD).

MB OUTLINE control file HERE

We will also apply an atmospheric boundary using data from CFSR atmospheric model. The atmospheric conditions applied to the model include:

• Mean sea level pressure
• Wind speed and direction
• Shortwave and longwave radiation
• Air temperature
• Relative humidity

These are provided in CFSR_20230101_20230201_GDA94Z56_AEST.nc and was obtained using TUFLOW FV Get Atmos.

TUFLOW FV Model Setup

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 TFV 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

Run TUFLOW FV

Once we have entered the require commands we can now setup a Windows Batch file and run TUFLOW FV. 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.

1. Copy the .bat file into your Working\TUFLOWFV\runs and open it in Notepad++.
2. 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 Riverine_Channel_000.fvc. Line 8 keeps the Windows prompt open, rather than closing it automatically after the simulation completes.
3. 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 Riverine_Channel_000.fvc but it will not run the simulation Riverine_Channel_001.fvc (Riverine_Channel_001.fvc will be used to investigate timestep sensitivity to mesh design later in the tutorial).
4. 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

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

Reviewing Results

WL and Vel

TUFLOW FV Model Setup With Structures

Reviewing Results

WL and Velocity how do the structures change the hydrodynamics

TUFLOW FV Model Setup AD

Inclusion of Sal and Temp

Including a AD BC

Reviewing Results

Sal and temp

Going Further

Use GetAmos, GetTide.. to download BC data link to pages here.