Appendix C Files and data fields

Depending on the core supported configuration selected, TUFLOW CATCH outputs one or more files, each with their own data fields. If the recommended output protocols described in Section 6 are followed, then these are:

  • TUFLOW HPC
    • One *.xmdf with all catchment based results
  • TUFLOW FV
    • One *.nc for hydrodynamics and sediments
    • One *.nc for water quality
    • Possibly others (e.g. particle tracking)

Each of these files has any number of data fields, depending on the TUFLOW CATCH configuration, selected pollutants and water quality module settings. Notwithstanding this, the following will hold under the above output protocols:

  • All TUFLOW CATCH map data fields will be contained within the TUFLOW HPC results file (*.xmdf)
  • Receiving waterway hydrodynamic map data fields are those of standard TUFLOW FV outputs (*.nc)
  • Receiving waterway water quality map data fields are those of standard TUFLOW FV WQ outputs (*.nc)

The outputs and data fields of the second two points above are not dealt with here because they are described in the TUFLOW FV Manuals and TUFLOW FV WQ Manual Appendices.

The first point above (TUFLOW CATCH data fields) is dealt with in this Appendix. Rather than attempt to list every potential data field that might be included in this output file, the attributes of the available data field types are presented. The names of these data fields will vary depending on pollutant names and other parameters, but each type follows a set naming convention. These data field types are:

  • Surface water concentration
  • Groundwater Layer concentration
  • Dry mass
  • Net mass

These are described in the following sections.

C.1 Surface water concentrations

Surface water concentration data fields have the following properties:

  • Content:
    • Reports the temporally and spatially varying concentration of a dissolved or particulate pollutant in surface water
  • Name:
    • “Conc <pollutant_name>”, e.g. “Conc WQ_NITRATE_MG_L”
  • Units:
    • mg/L when Washoff1 model accumulation rates are specified in kg/ha/yr
    • mg/L when Shear1 erosion rates are specified in g/m\(^2\)/s

These fields are reported at all wet TUFLOW HPC cells for all simulated constituents that are listed within pollutant export material blocks. Constant and timeseries pollutants are not reported because they are assigned only during boundary condition writing, rather than being numerically simulated in the catchment domain.

C.2 Groundwater concentrations

Groundwater concentration data fields have the following properties:

  • Content:
    • Reports the temporally and spatially varying concentration of a dissolved or particulate pollutant in groundwater associated with soil layer N (N = 1, 2, …)
  • Name:
    • “GW Layer <Layer number> Conc <pollutant_name>”, e.g. “GW Layer 1 Conc PFAS”
  • Units:
    • mg/L when Washoff1 model accumulation rates are specified in kg/ha/yr
    • mg/L when Shear1 erosion rates are specified in g/m\(^2\)/s

These fields are reported at all TUFLOW HPC cells for all simulated constituents that are listed within pollutant export material blocks. Constant and timeseries pollutants are not reported because they are assigned only during boundary condition writing, rather than being simulated in the catchment domain. These GW Layer data fields will be zero at all times and locations for a given pollutant <name> if its infiltration has been set to off via

Infiltration <name> == off

C.3 Dry mass

Dry mass data fields are created and reported only for pollutants that are set to use the Washoff1 pollutant export model. They have the following properties:

  • Content:
    • Reports the temporally and spatially varying dry mass of accumulated pollutant. It is initialised to zero at simulation commencement
  • Name:
    • “Dry Mass <pollutant_name>”, e.g. “Dry Mass WQ_POC_MG_L”
  • Units:
    • kg/ha when Washoff1 model accumulation rates are specified in kg/ha/yr

These fields are reported at all TUFLOW HPC cells for all simulated constituents that are listed within pollutant export material blocks and use the Washoff1 pollutant export model. Constant and timeseries pollutants are not reported because they are assigned only during boundary condition writing, rather than being simulated in the catchment domain. Multiplying each pollutant’s Dry Mass outputs by the TUFLOW HPC cell area (in hectares) and summing across the domain will compute the total dry store mass of each pollutant (in kilograms) as a function of time.

C.4 Net mass

Net mass data fields are created and reported only for pollutants that are set to use the Shear1 pollutant export model. They have the following properties:

  • Content:
    • Reports the temporally and spatially varying net mass of a pollutant. It is initialised to zero at simulation commencement. A negative/positive number at a given location reflects net erosion/deposition, respectively
  • Name:
    • “Net Mass <pollutant_name>”, e.g. “Net Mass WQ_SED_FINES”
  • Units:
    • kg/ha when Shear1 model accumulation rates are specified in g/m\(^2\)/s

These fields are reported at all TUFLOW HPC cells for all simulated constituents that are listed within pollutant export material blocks and use the Shear1 pollutant export model. Constant and timeseries pollutants are not reported because they are assigned only during boundary condition writing, rather than being simulated in the catchment domain. Dividing each pollutant’s Net Mass outputs by a user defined bulk density, and then again dividing by 10000 (i.e. m\(^2\)/ha) will compute the erosion or deposition depth of each pollutant as a function of space and time.

C.5 Other outputs

TUFLOW CATCH produces a small suite of supporting outputs that are simple text files. These are listed below. If the TUFLOW CATCH BC output folder is set to ..\bc_dase as recommended:

Catch BC Output Folder == ..\bc_dbase

then all files below are written to the TUFLOWCatch\bc_dbase\ folder.

C.5.1 Mass balance

A series of three mass balance files are written as follows (assuming a *.tcc file name of Model_001.tcc).

C.5.1.1 Surface water mass balance

One file per simulation is produced as follows:

  • Content:
    • Timeseries of spatially summed cumulative surface water flow and associated pollutant masses leaving the TUFLOW HPC model (either to a polygon (Pollutant export TUFLOW CATCH configuration) or TUFLOW FV model domain (Hydrology and Integrated TUFLOW CATCH configurations))
  • Name:
    • Model_001_catchment_hydraulic_mass_balance_surface.csv
  • Units:
    • Time: ISODATE format
    • Volume: m\(^3\) (cumulative)
    • All pollutants: g (cumulative) (not reported for Hydrology configuration as pollutants are not simulated)
  • Uses
    • Can be directly imported into common plotting packages to show total surface cumulative flow and pollutant mass export at the outlet of the TUFLOW HPC model domain (or, equally, entry to the TUFLOW FV domain if used)
    • Provides an accessible means of high level scenario comparisons, for example where cumulative surface catchment flows and pollutants loads are to be compared between different catchment land use options, management interventions or rainfall sequences

C.5.1.2 Groundwater mass balance

One file per simulation is produced as follows:

  • Content:
    • Timeseries of spatially summed cumulative groundwater flow and associated pollutant masses leaving the TUFLOW HPC model (either to a polygon (Pollutant export TUFLOW CATCH configuration) or TUFLOW FV model domain (Hydrology and Integrated TUFLOW CATCH configurations))
  • Name:
    • Model_001_catchment_hydraulic_mass_balance_groundwater.csv
  • Units:
    • Time: ISODATE format
    • Volume: m\(^3\) (cumulative)
    • All pollutants: g (cumulative) (not reported for Hydrology configuration as pollutants are not simulated)
  • Uses
    • Can be directly imported into common plotting packages to show total groundwater cumulative flow and pollutant mass export at the outlet of the TUFLOW HPC model domain (or, equally, entry to the TUFLOW FV domain if used)
    • Provides an accessible means of high level scenario comparisons, for example where cumulative groundwater catchment flows and pollutants loads are to be compared between different catchment land use options, management interventions or rainfall sequences

C.5.1.3 Total mass balance

One file per simulation is produced as follows. Its content is the summation of the data reported in the respective surface and groundwater mass balance outputs described in Sections C.5.1.1 and C.5.1.2:

  • Content:
    • Timeseries of spatially summed cumulative surface and groundwater flow and associated pollutant masses combined leaving the TUFLOW HPC model (either to a polygon (Pollutant export TUFLOW CATCH configuration) or TUFLOW FV model domain (Hydrology and Integrated TUFLOW CATCH configurations))
  • Name:
    • Model_001_catchment_hydraulic_mass_balance.csv
  • Units:
    • Time: ISODATE format
    • Volume: m\(^3\) (cumulative)
    • All pollutants: g (cumulative) (not reported for Hydrology configuration as pollutants are not simulated)
  • Uses
    • Can be directly imported into common plotting packages to show cumulative total flow and pollutant mass export at the outlet of the TUFLOW HPC model domain (or, equally, entry to the TUFLOW FV domain if used)
    • Provides an accessible means of high level scenario comparisons, for example where cumulative total catchment flows and pollutants loads are to be compared between different catchment land use options, management interventions or rainfall sequences

C.5.2 Receiving polygon

If TUFLOW CATCH has been executed in the Pollutant export configuration, then a timeseries output file is produced that reports incoming flow and concentrations to that user defined polygon. This is broadly a concentration based equivalent to the output described in Section C.5.1.3, with some extra fields reported.

Assuming a *.tcc file name of Model_001.tcc has been executed, the file is as follows:

  • Content:
    • Timeseries of spatially summed instantaneous surface and groundwater flow and associated pollutant concentrations combined leaving the TUFLOW HPC model to a polygon (Pollutant export TUFLOW CATCH configuration)
  • Name:
    • Model_001_catchment_hydraulic_receiving.csv
  • Units:
    • Time: ISODATE format
    • Flow: m\(^3\)/s
    • Salinity: g/L if used
    • Temperature: \(^{\circ}\)C if used
    • All pollutants: mg/L or \(\mu\)g/L as appropriate for each sediment fraction or water quality pollutant
  • Uses
    • Can be directly imported into common plotting packages to show instantaneous total flow and pollutant concentrations at the outlet of the TUFLOW HPC model domain
    • Provides an accessible means of high level scenario comparisons, for example where total catchment flows and pollutants concentrations are to be compared between different catchment land use options, management interventions or rainfall sequences

C.5.3 TUFLOW FV boundaries

A series of TUFLOW FV boundary related files are written as follows.

C.5.3.1 BC blocks

A single file that contains all required TUFLOW FV nodestring (Q) and cell (QC) inflow boundary BC blocks is written by TUFLOW CATCH. This file is called automatically by TUFLOW FV under TUFLOW CATCH when required. It is at the heart of the automated linking offered by TUFLOW CATCH. Users should not edit this file in any way.

  • Content:
    • TUFLOW FV BC blocks that direct TUFLOW FV to boundary condition data files prepared by TUFLOW HPC under TUFLOW CATCH. Only produced in the Hydrology and Integrated TUFLOW CATCH configurations. Two example blocks are shown below
    !-----------------------------------------------------------------------------------------
! Nodestring boundaries
BC == Q, NW_Inflow, NW_Inflow.csv
 Sub-Type == 2
 BC Header == Time,Flow,Salinity,Temperature,SED_FINES
End BC
!-----------------------------------------------------------------------------------------
! Lateral boundaries
BC == QC, 1178572.028, 4996161.397, cell1.csv
 BC Header == Time,Flow,Salinity,Temperature,SED_FINES
End BC
  • Name:
    • Model_001_catchment_hydraulic.fvcatchbc
  • Units:
    • NA
  • Uses
    • Used internally by TUFLOW CATCH to link TUFLOW HPC and TUFLOW FV simulations. Users should not edit this file in any way

This file calls underlying nodestring and/or lateral boundary condition data files produced by TUFLOW HPC, and these are described below.

C.5.3.2 Nodestring boundary data

If TUFLOW CATCH has been executed in the Hydrology or Integrated configuration and TUFLOW FV nodestrings have been specified as catchment inflows via

Catchment BC Nodestring == <path to GIS nodestring file>

then individual data files are produced for each nodestring boundary:

  • Content:
    • Timeseries of flow and associated pollutant concentrations crossing the nodestring
  • Name:
    • “<GIS name>.csv”, e.g. “SW_Inflow.csv”, where “SW_Inflow” is the user defined name given to the nodestring in GIS
  • Units:
    • Time: ISODATE format
    • Flow: m\(^3\)/s
    • Salinity: g/L if used
    • Temperature: \(^{\circ}\)C if used
    • All pollutants: mg/L or \(\mu\)g/L as appropriate for each sediment fraction or water quality pollutant
  • Uses
    • Called by Model_001_catchment_hydraulic.fvcatchbc to link TUFLOW HPC and TUFLOW FV under TUFLOW CATCH. Users should not edit this file in any way, including opening and saving it in Excel, which can cause the time format to change and become unreadable.

C.5.3.3 Lateral boundary data

If TUFLOW CATCH has been executed in the Hydrology or Integrated configuration then individual lateral data files are produced for each transfer cell boundary:

  • Content:
    • Timeseries of flow and associated pollutant concentrations entering a cell
  • Name:
    • “cell_<TUFLOW mesh cell ID>.csv”, e.g. “cell37.csv”, where 37 is the 2D cell ID in the TUFLOW FV mesh
  • Units:
    • Time: ISODATE format
    • Flow: m\(^3\)/s
    • Salinity: g/L if used
    • Temperature: \(^{\circ}\)C if used
    • All pollutants: mg/L or \(\mu\)g/L as appropriate for each sediment fraction or water quality pollutant
  • Uses
    • Called by Model_001_catchment_hydraulic.fvcatchbc to link TUFLOW HPC and TUFLOW FV under TUFLOW CATCH. Users should not edit this file in any way, including opening and saving it in Excel, which can cause the time format to change and become unreadable.