TUFLOW CATCH Tutorial M01 Draft

Page Under Construction

Introduction

In this module, a TUFLOW CATCH pollutant export model is developed.

TUFLOW CATCH Tutorial Module 1 is built from the model created in TUFLOW Tutorial Module 6 - Part 3. The completed TUFLOW Module 6 (part 3) is provided in the TUFLOW_CATCH_Module_01\Modelling\TUFLOW folder of the download dataset as the starting point for this tutorial. If you are not already familiar with TUFLOW, we recommend first completing Module 1, 2, 3 and 6 of the TUFLOW Tutorials to establish an understanding of 1D and 2D TUFLOW modelling, as well as direct rainfall models.

Project Initialisation

TUFLOW CATCH models are separated into a series of folders which contain the input and output files. The recommended directory structure for TUFLOW CATCH models consists of a top-level folder, Modelling, which contains three subfolders:

• TUFLOW: Contains TUFLOW HPC input files.
• TUFLOWCatch: Contains the TUFLOW CATCH Control file, as well as all check, results and log files.
• TUFLOWFV: Contains TUFLOW FV input files.

The third level subfolders are outlined below. For a more detailed description, refer to the TUFLOW CATCH Manual. For more information on TUFLOW HPC or TUFLOW FV folder structures, refer to the TUFLOW Manual or the TUFLOW FV Manual.

Folder	Sub-Folder (s)	Description
TUFLOW	bc_dbase model	Follows standard TUFLOW structure.
	catch	Not used, but generated for internal use. It holds files that are produced during computation, but deleted when the simulation finishes successfully.
	check results runs	Not used, but generated for internal use. All TUFLOW check and results files are written to the TUFLOWCatch\check folder and the TUFLOWCatch\results folder respectively. TUFLOW CATCH simulations are run from the .tcc file in the TUFLOWCatch\runs folder.
TUFLOWCatch	bc_dbase	Contains the output boundary condition and time-series data.
	check	Contains the GIS and other check files produced by TUFLOW CATCH, TUFLOW and TUFLOW FV to carry out quality control checks
	model	Not used - generated for internal use.
	results	Contains the result files produced by TUFLOW CATCH, TUFLOW and TUFLOW FV.
	runs	Contains the .tcc simulation control file.
	runs\log	Contains the log files (e.g. .catchlog, .tlf, .log, etc) and _messages.shp files produced by TUFLOW CATCH, TUFLOW and TUFLOW FV.
TUFLOWFV	bc_dbase model stm wqm	Follows standard TUFLOW FV structure.
	check results runs	Not used, but generated for internal use. All TUFLOW FV check and results files are written to the TUFLOWCatch\check folder and the TUFLOWCatch\results folder respectively. TUFLOW CATCH simulations are run from the .tcc file in the TUFLOWCatch\runs folder.

The TUFLOW CATCH folder can be set up manually, or automatically through the TUFLOW CATCH QGIS Plugin.

• TUFLOW CATCH Project Initialisation

GIS Inputs

Create, import and view input data:

• TC01 - GIS Inputs

TUFLOW Boundary Condition Database (bc_dbase)

Update the bc_dbase with a reference to the timeseries temperature data:

1. In Windows File Explorer, navigate to the TUFLOW_CATCH_Module_01\Tutorial_Data folder. Copy the temperature.csv and paste it in the TUFLOW_CATCH_Module_01\Modelling\TUFLOW\bc_dbase folder. This file contains the timeseries temperature data.
2. Open the file. As this file will be read by TUFLOW CATCH, the first column must contain the date in ISODATE format (DD/MM/YYYY hh:mm:ss). It will also be read by TUFLOW HPC, and therefore must have column specifing time in hours from beginning of the model. In this case, the 'TUFLOW_Time' column contains the time in hours. For example, 01/01/2021 10:00:00 corresponds to 0, 01/01/2021 11:00:00 to 1, and so on.
   
   File:Image of temp.csv
   
   
3. In the TUFLOW\bc_dbase folder, save a copy of the bc_dbase_M06_001.csv as bc_dbase_TC01_001.csv.
4. Open the file and add the reference to the timeseries temperature data as shown below:
   
   File:Image of bc dbase
   
   
5. Save the bc_dbase.

Materials

Surface roughness or bed resistance values (e.g. Manning’s n) are assigned to material IDs. To simulate a more complex catchment area, more material IDs have been specified.

1. In Windows File Explorer, navigate to the TUFLOW_CATCH_Module_01\Tutorial_Data folder. Copy the materials_TC01_001.csv and paste it in the TUFLOW_CATCH_Module_01\Modelling\TUFLOW\model folder. This file is a modified version of materials_M06_002.csv from TUFLOW Tutorial Module 6.
2. Open the file. Roughness values (Manning's n) have been applied to the five new material IDs:
   
   File:Image of mat file
   
   
3. These new material IDs have been assigned to allow different pollutant export properties to be specified to each material ID. This is discussed in the TUFLOW CATCH Control File section.

TUFLOW Soil File (.tsoilf)

The soils (.tsoilf) file is similar to the materials file. A positive integer ID is assigned to each soil, then an infiltration method followed by the soil parameters. For this tutorial, there is only one soil type (ID 1) which is applied across the whole model.

1. In Windows File Explorer, navigate to the TUFLOW_CATCH_Module_01\Tutorial_Data folder. Copy the TC01_soils_001.tsoilf and paste it in the TUFLOW_CATCH_Module_01\Modelling\TUFLOW\model folder.
2. Open the file. The Green-Ampt (GA) infiltration method has been used. For more information on infiltration methods, refer to the TUFLOW Manual.
   
   File:Pic of file
   
   

Simulation Control Files

The following steps will require use of a text editor. The tutorial demonstration uses Notepad++. For its configuration information refer to Notepad++ Tips.

TUFLOW Geometry Control File (TGC)

1. Save a copy of M02_001.tgc as TC01_001.tgc in the TUFLOW_CATCH_Module_01\Modelling\TUFLOW\model folder.
2. Open the TC01_001.tgc in a text editor and add the following line after the 'Read GIS Mat' command to reference the new materials GIS layer.
   Read GIS Mat == gis\2d_mat_TC01_001_R.shp ! Sets material values according to attributes in the GIS layer
   
3. Save the TGC.

TUFLOW Boundary Control File (TBC)

1. Save a copy of M06_003.tbc as TC01_001.tbc in the TUFLOW_CATCH_Module_01\Modelling\TUFLOW\model folder.
2. Open the TC01_001.tbc in a text editor and update the reference to the 2D boundaries:
   Read GIS BC == gis\2d_bc_TC01_001_L.shp ! Reads in downstream 2D boundary
   
3. Add the additional lines to reference the 1D/2D culvert connections:
   Read GIS BC == gis\2d_bc_M03_culverts_001_P.shp ! Links the 1D culverts to the 2D domain
   Read GIS BC == gis\2d_bc_M03_culverts_001_R.shp | gis\2d_bc_M03_culverts_001_L.shp ! Links the 1D culverts to the 2D domain
   
4. Save the TBC.

TUFLOW ESTRY Control File (ECF)

1. Navigate to the TUFLOW_CATCH_Module_01\Modelling\TUFLOW\model folder, and open TC01_001.ecf in a text editor. This file was created using the TUFLOW CATCH plugin.
2. Add the following command lines to set the 1D computational timestep and define the culverts:
   Timestep == 0.5 ! Specifies a 1D computational timestep as 0.5 seconds
   Read GIS Network == gis\1d_nwk_M03_culverts_001_L.shp ! Defines culverts
3. Add the following command line to define the Advection Dispersion (AD) approach. For more information on Advection Dispersion, please refer to the TUFLOW Manual.
   AD Approach == METHOD A ! Sets the modelling approach for the Advection Dispersion through 1D channels
4. Save the ECF.

TUFLOW CATCH Control File (TCC)

A TUFLOW CATCH simulation is set up and executed by constructing a TUFLOW CATCH Control file (.tcc). TUFLOW Control file (.tcf) and TUFLOW FV Control file (.fvc) are not used. The TCC has four command blocks:

1. Global commands
2. Catchment Hydraulic Model (TUFLOW HPC) commands
3. Catchment Pollutant Export Model
4. Receiving Model (TUFLOW FV) commands

All blocks must be included in the above order, but the later three can be switched on and off with a single command.

The TUFLOW CATCH plugin has created a TCC template file in the TUFLOWCatch\runs folder, TC01_001.tcc. This file has been populated with all the commands needed to execute a TUFLOW CATCH simulation. In this section, the template commands will be populated/updated for this tutorial model.

Global

This section contains information that is applied equally to both TUFLOW HPC and TUFLOW FV.

1. Navigate to the TUFLOW_CATCH_Module_01\Modelling\TUFLOWCatch\runs folder and open TC01_001.tcc into a text editor.
2. In the 'Simulation Settings' section, update the time commands:
   Start Time == 01/01/2021 10:00:00 ! Specifies the simulation start time
   End Time == 01/01/2021 13:00:00 ! Specifies the simulation end time
   
3. In the 'Boundary Condition Configuration' section, update the BC and CSV output intervals:
   Catch BC Output Interval Nodestring == 300 ! Outputs BC nodestring data every 300 seconds
   Catch BC Output Interval Lateral == 300 ! Outputs BC lateral data every 300 seconds
   CSV Write Frequency Day == 0.01 ! Writes CSV output every 0.01 days
   

Catchment Hydraulic Model (TUFLOW HPC)

This block contains commands that construct the TUFLOW HPC simulation. These commands are almost entirely those that would be used in setting up a standalone TUFLOW HPC control file (.tcf), with a small number of additional commands that relate to TUFLOW CATCH.

1. Set the catchment hydraulic model:
   Catchment Hydraulic Model == HPC
2. Set the zero date. TUFLOW HPC does not support ISODATE format, while TUFLOW FV requires it. This command ensures compatibility by setting the date in TUFLOW FV ISODATE format that corresponds to zero hours in TUFLOW HPC boundary condition files.
   Zero Date == 01/01/2021 10:00 ! Specifies the simulation start time in TUFLOW FV ISODATE format
   
3. In the 'GIS' section, set the projection for the output grid files:
   TIF Projection == ..\..\TUFLOW\model\grid\DEM.tif ! Sets the GIS projection for the output grid files
   
4. In the 'Solver' section, set the timestep maximum and time format:
   Timestep Maximum == 2.5 ! Specifies a maximum timestep (seconds)
   Time Format == TUFLOWFV ! Specifies the time format of output results
   
5. In the 'SGS' section, set the sample target distance:
   SGS Sample Target Distance == 0.5 ! Sets SGS Sample Target Distance (meters)
   
6. In the 'Control Files' section, ensure all control files are referenced.
   Geometry Control File == ..\..\TUFLOW\model\TC01_001.tgc ! Reference the TUFLOW Geometry Control File
   BC Control File == ..\..\TUFLOW\model\TC01_001.tbc ! Reference the TUFLOW Boundary Conditions Control File
   BC Database == .\..\TUFLOW\bc_dbase\bc_dbase_TC01_001.csv ! Reference the Boundary Conditions Database
   Read Materials File == ..\..\TUFLOW\model\materials_TC01_001.csv ! Reference the Materials Definition File
   Rainfall Control File == ..\..\TUFLOW\model\M06_point2grid_003.trfc ! Reference the TUFLOW Rainfall Control File
   Estry Control File == ..\..\TUFLOW\model\TC01_001.ecf ! Reference the ESTRY (1D) Control File
   
7. In the 'Soils' section, reference the soils file (.tsoilf), and define the soil parameters:
   Read Soils File == ..\..\TUFLOW\model\TC01_soils_001.tsoilf ! Reference the Soils File
   Soil Negative Rainfall Approach == FACTOR ! ???
   Soil Negative Rainfall Factor == 0.2 ! ???
   
8. In the 'Pollutant Configuration' section, reference the receiving polygon and set the pollutants. In this tutorial, salinity, temperature, dissolved oxygen (WQ_DISS_OXYGEN_MG_L), alive and dead ecoli (WQ_PATH_ECOLI_ALIVE/DEAD_CFU_100ML) and clay sediment (SED_CLAY) are simulated.
   Receiving Polygon == ..\..\TUFLOW\model\gis\2d_rp_TC01_001_R.shp ! GIS layer defining the receiving polygon
   Pollutant == Salinity, Temperature, WQ_DISS_OXYGEN_MG_L, WQ_PATH_ECOLI_ALIVE_CFU_100ML, WQ_PATH_ECOLI_DEAD_CFU_100ML, SED_CLAY ! Specify the pollutant names
   

Pollutant Export Model

This block contains commands that control the pollutant export (and other constituent) simulation.

1. Set the pollutant export model:
   Catchment Pollutant Export Model == Mass Accumulation Release
2. In the 'Constant Concentrations' section, add the following commands. They set the pollutants 'Salinity' and 'WQ_DISS_OXYGEN_MG_L' (dissolved oxygen) to have a contstant concentration across the whole simulation. is this right??
   Constant Salinity == 0.0  ! ???
   Constant WQ_DISS_OXYGEN_MG_L == 8.0  ! ???
   
3. In the 'Time Series' section, add the following command. It sets the pollutant 'Temperature' to be a time-series input, and points to the name 'temp' in the bc_dbase.
   Time-Series Temperature == Temperature ! ???
   
4. In the 'Pollutant Export Properties' section, add the material block 'ALL' from the page linked below. This block defines the default (or spatially uniform) pollutant export properties for each pollutant. Once uniform conditions have been set, progressive specifications of material by material pollutant behavior can be set. These specifications overwrite previous settings on a spatial basis. Including the default (ALL) material block is considered best practice, as it ensures that all pollutants have their pollutant export properties specified for the entire TUFLOW HPC domain - otherwise, an error will occur. any more info on this?. For more information on the pollutant export parameters, refer to the specific section in the catch manual.
   

   • Pollutant Export Properties: ALL

5. To set the pollutant export properties for the different material IDs, blocks similar to the above can be used. The material IDs correspond to those defined in the 2d_mat_TC01_001.shp and 2d_mat_M01_001.shp GIS layers.
   To estimate E. coli export rates for each paddock, the area of each paddock was calculated. Based on this, appropriate animal populations were assigned. Using these values, the E. coli rates were calculated. For more information on pollutant export calculations, refer to the specific section of the catch manual
   
   File:Image of materials file over aerial image with labels on (paddockA, ...)

   Material ID	Paddock Name	Area (ha)	Animals
   6	paddockA	1.5	23 Sheep, 7 Lambs
   7	paddockB	0.3	2 Cows
   8	paddockC	1.2	20 Sheep
   9	paddockD	1	4 Cows, 2 Calves

   
   explain how we came up with the clay rates?

6. Set the pollutant export properties for material ID 1. This is the material ID for all areas within the model domain not covered by a material region. These pollutant export properties define the release and deposition of clay sediment. Sediment pollutants generally use the 'Shear1' method. For more information on 'Shear1', refer to the specific section of the catch manual.
   

   • Pollutant Export Properties: 1

7. Set the pollutant export properties for material ID 4 (waterholes, eddies, etc). These properties define settling (deposition velocity) of alive and dead E. coli to 2 meters per day (approx 25cm during the simulation).
   

   • Pollutant Export Properties: 4

8. Set the pollutant export properties for material ID's 6 (paddockA), 7 (paddockB), 8 (paddockC) and 9 (paddockD). These properties define the accumulation (rate) and washoff of alive and dead E. coli for the animals on the paddock.
   

   • Pollutant Export Properties: 6, 7, 8, 9

9. For this tutorial, leave all interventions commands as is. They will be discussed in TUFLOW CATCH Tutorial 4.
10. Save the TCC.

Receiving Model (TUFLOW FV)

For this tutorial, leave all commands as is. This section of the TCC will be discussed in TUFLOW CATCH Tutorial 2.

Running the Simulation

1. In Windows File Explorer, navigate to the TUFLOWCatch\runs folder. The TUFLOW CATCH plugin created a batch file (.bat) that references the .tcc called Demonstration.bat.
2. Save a copy of Demonstration.bat as _run_TC01_CATCH.bat maybe change name?? and open the file in a text editor.
3. Update the batch file to reference the TUFLOW CATCH executable:
   set exe="..\..\..\..\exe\TUFLOWCATCH\2025.0.1\TUFLOWCATCH.exe"
   %exe% TC01_001.tcc
4. Double click the batch file in file explorer to run the simulation.
   

Troubleshooting

See tips on common mistakes and troubleshooting steps if the model doesn't run:

• QGIS

Check Files and Results Output

Complete the steps outlined in the following links to review check files and simulation results from the TUFLOW CATCH pollutant export model simulation:

• TC01 - Check Files
  
• TC01 - Results