Overview

About this Manual

This document is the user manual for the TUFLOW Water Quality (WQ) Module.

Documentation for all previous releases, including archived manuals, is available from TUFLOW Downloads.

How to use This Manual

This section provides an overview of the manual structure and the navigation features available to help locate information. These instructions are only provided in this section.

Structure

Model construction in the WQ Module follows a structured workflow. Users should begin with the Architecture chapter, which provides an overview of the WQ Module’s core architecture. Following that, the Process Descriptions chapter provides a detailed description of the processes and capabilites of the WQ Module, together with a summary of its interactions with TUFLOW FV. Finally, the Model Construction chapter outlines the construction of a TUFLOW simulation with the WQ Module activated.

Several supporting appendices have been included in this manual. These contain interactive content to assist users in understanding and applying the WQ Module, beyond what might typically be included in a static user manual. These Appendices are interlinked and hyperlinked with content from the body of the manual where appropriate.

Navigation

This manual is organised into chapters, which are listed in the left sidebar. Select a chapter to navigate directly to that chapter. The top of the left sidebar also contains a search box which can be used to search the entire manual.

Within each chapter, the right sidebar displays a table of contents containing headings down to level 5 (e.g. Section 1.2.3.4.5). This provides an overview of the current chapter and allows navigation to a specific section. The current section is highlighted in bold as you scroll through the chapter.

At the bottom of each chapter, there are links to the previous and next chapters (when applicable).

The navigation bar at the top of the page provides quick access to the following features:

• Dark mode: Toggle between light and dark themes
• PDF: View the manual as a PDF document
• Reader mode: Collapse or expand the left and right sidebars

Searching

The search function (top of the left sidebar) searches the entire manual, including chapters, tables, appendices and references. Matching results are displayed with a short preview of the surrounding text to help identify the relevant result before navigating to it.

Cross-references are used throughout the manual to link related content, including sections, figures, tables, equations, commands, etc. Hovering over a cross-reference displays a preview of the linked content. Selecting the link navigates directly to the referenced item.

Unit Systems

The WQ Module supports two unit systems: milligrams per litre (mg/L) and millimoles per cubic metre (mmol/m\(^3\)). The unit system is specified via the WQ Units command. i.e. WQ Units == mgl or WQ Units == mmm, respectively. The selected system determines how initial and boundary conditions are interpreted and which default parameter values apply.

In Appendix A — Commands, Appendix O — Computed variables and Appendix P — Diagnostic variables, entries that support both unit systems display information for both of the systems in a small table. Only the row matching the simulation’s unit system is applicable.

Important

For a more detailed explanation of the two unit systems, see Units.

Commands

Commands are displayed in highlighted text and are often provided as a clickable link to their corresponding command description in Appendix A — Commands.

The command appendix provides detailed descriptions of each command and its parameters. Each command includes a summary block containing key information such as relevant construction section links. Command parameters are then described in individual sections (see Parameters for details). The table of contents in the right sidebar provides a convenient way to browse commands and parameters within the appendix.

TUFLOW commands use a structured, colour-coded syntax that is consistent throughout the documentation.

Colour coding:

• Blue: The command
• Red: The operator (==)
• Black: The input(s)/parameter(s)
• Green: Comments (must be preceded by !)

A vertical bar (|) separates the different input options for a command. For example, the following command has three options:

Simulation Class == DO | Inorganics | Organics  ! command definition

Simulation Class == DO              ! option 1 - Dissolved oxygen simulation class
Simulation Class == Inorganics      ! option 2 - Inorganics simulation class
Simulation Class == Organics        ! option 3 - Organics simulation class

For the Water Quality Module, most command inputs are parameters. As such, the usual default ({}) and user defined (<>) syntax for inputs is not used and instead a more detailed description of the commands’ parameter(s) is provided in subsections below the command.

For a detailed guide to reading a command entry in Appendix A — Commands, see the How to read a command entry section in that appendix.

Example command blocks are typically provided within scrollable code blocks. These blocks can be copied directly into a text editor when building a model control file. Select the icon in the upper right corner of the block to copy the entire command block to the clipboard. An example block is provided below:

Simulation Class == DO          ! Set simulation class to Dissolved Oxygen
WQ dt == 600.0                  ! Set the WQ timestep (seconds)
WQ Units == MgL                 ! Set the units used for the WQ simulation

Parameters

Where commands specify computed variable parameters (e.g. half saturation concentrations, sediment fluxes etc.), they are referenced using their parameter notation (outlined below) rather than descriptive text. Parameter references are typically clickable links that navigate directly to the corresponding parameter description in Appendix A — Commands, where the parameter definition and description is provided.

In Appendix A — Commands, parameters are described following their corresponding command. Each parameter section has a description and a summary block with key information, such as default value, units, range and links to relevant science sections. Where a parameter supports two unit system options, information for both of the systems is displayed in a small table. Only the row matching the simulation’s unit system is applicable. See Unit Systems for an explanation of the two unit systems.

Important

Where parameter ranges are provided in Appendix A — Commands, these are not to be taken as fixed, but as indicative only. Some environmental settings may require parameterisation outside the ranges specified in this manual.

Parameter Notation

The primary groups of computed variable parameters are listed below, with the letter or symbol used to denote each. Typical generalisations of units are parenthesised.

• Fluxes, \(F\) (mass or moles per unit area or volume per unit time)
• Rates, \(R\) (per unit time)
• Concentrations, \(K\) (mass or moles per unit volume)
• Temperature coefficients, \(\theta\) (dimensionless)
• Fractions, \(f\) (dimensionless decimal between 0.0 and 1.0)
• Ratios, \(X\) (dimensionless decimal that may be greater than 1.0, but always non-negative)
• Limitation functions, \(L\) (a dimensionless decimal between 0.0 and 1.0)
• Power exponents, \(P\) (typically dimensionless), and
• Velocities, \(V\) (metres per day)
• Boolean flags, \(B\) (either zero or one)

Typically (but not always) an instance of each of these groups will describe a computed variable and a process. Where appropriate, the computed variable and process are denoted as superscripts and subscripts, respectively. For example:

• The flux of oxygen across the sediment-water interface is notated as \(F_{sed}^{O_2}\)
• The rate of denitrification of nitrate is notated as \(R_{denit}^{NO_3}\),
• The half saturation concentration of oxygen controlling the flux of filterable reactive phosphorus across the sediment-water interface is notated as \(K_{sed-O_2}^{FRP}\)
• The temperature coefficient controlling the flux of ammonium across the sediment-water interface is notated as \(\theta_{sed}^{NH_4}\)

In describing calculation processes (primarily in the Appendices) where a quantity is recomputed by the WQ Module as a direct modification of a user input or previously calculated quantity, then \(\left< computed \right>\) is used in the quantity’s subscript. For example, a user can specify a sediment flux of ammonium, which is a parameter notated as \(F_{sed}^{NH_4}\). The WQ Module can modify this parameter based on dynamic environmental conditions, and if so, the modified quantity is notated as \(F_{sed \left< computed \right>}^{NH_4}\).

Computed Variables

Computed variables are the state variables tracked and advected by the WQ Module at every computational cell and timestep. Their concentrations are preserved between timesteps and are written to output files at the requested output times. Output computed variables are listed and described in Appendix O — Computed variables.

The unit systems described in Unit Systems applies to computed variables. For a guide to reading computed variable entries in Appendix O — Computed variables, see Overview.

Concentration values of computed variables refer to the elemental mass of the constituent rather than the molecular mass. See Concentration Nomenclature below for details.

Diagnostic Variables

Diagnostic variables are derived quantities computed during each WQ timestep, such as process rates and fluxes. Unlike computed variables, they are not tracked or advected between timesteps — each value is a snapshot of a rate or flux at a given instant. Diagnostic variables are listed and described in Appendix P — Diagnostic variables.

The unit systems described in Unit Systems applies to diagnostic variables. For a guide to reading diagnostic variable entries in Appendix P — Diagnostic variables, see Overview.

Concentration Nomenclature

Examples of processes and model simulations are provided in this manual, and these in turn refer to computed variable concentrations. These concentrations are denoted in square brackets, such as \(\left[NO_3\right]\) for nitrate. The commonly accepted nomenclature for these variable concentrations is used in this manual, such as “nitrate concentration”. The numerical value of this concentration refers, however, to the concentration of elemental nitrogen within nitrate molecules: “6 mg/L of nitrate” means 6 mg/L of elemental nitrogen that is contained within nitrate molecules, not 6 mg/L of nitrate molecules. This is implicit in all references to all computed variables. More detail in this regard is provided in Units, which should be reviewed carefully.

Interactive Figures

Some figures are interactive, allowing data to be explored directly within the manual. These figures support understanding of processes and the influence of specifiable parameters on water quality outcomes.

Note

In the PDF version of the manual, interactive figures are displayed as static images.

The figure below provides an example. Move the slider or press play to see the effect a sediment property has on water column concentrations. Zoom in by clicking and dragging out a box within the plot axes to be enlarged, and double click to return to the original axis limits. Mouse hover over a line on the figure to see plotted values.

Figure 1

Figure 2

Interactive Networks

Interactive networks are used to illustrate simulation architecture and process descriptions. Networks comprise of nodes connected by lines, with interactive features.

Note

In the PDF version of the manual, interactive networks are displayed as static images.

• Architecture networks:
  • Nodes represent items within water quality architectural levels.
  • Nodes are circular and coloured based on their architectural level:
    • simulation classes
    • model classes
    • constituent models
    • computed variables
  • Architectural relationships are displayed as connecting directional lines, with each line’s colour matching that of its originating node
• Process description networks:
  • Nodes represent processes
  • Nodes are either:
    • Circular processes nodes and are coloured as sources or sinks of computed variables. If a process is both source and sink, its fill and outline are coloured accordingly.
    • Square computed variable nodes coloured as computed variables.
  • Process and computed variable relationships are displayed as connecting directional lines, with each line’s colour indicating whether its direction is a source or sink with respect to its originating node.

Connecting lines may have midpoint labels, and where present, these indicate indirect relationships to additional processes or computed variables.

Below are some tips for interacting with networks:

• Single click or hover over a node to highlight its nearest neighbours. Single clicking anywhere off the network will deselect these.
• Use the Select by id drop down menu to select a particular node of interest. Its nearest neighbours will also be automatically selected.
• Single click or hover over a legend entry to highlight all nodes of that type. Single clicking anywhere off the network will deselect these.
• Single click, hold and drag a node to move it.
• Single click, hold and drag white space anywhere within the activated network area to pan the entire network.
• Use the mouse wheel to zoom in and out of the network.
• Double click on any node that has the label starting text “Cluster on group :”. This will explode the nodes to see its containing subsidiary nodes. To return to the original state, click the ‘Re-initialise cluster’ button on the bottom right of the frame.

Below are example architecture and process description networks to explore.

Feedback

Constructive suggestions to improve this manual are welcome, and can be emailed to support@tuflow.com.