Introduction

About this manual

This document is the user manual for the TUFLOW Water Quality Module (WQM), release 2022.00.

How to use this manual

Instructions are provided below on how to use this manual, including aspects of navigation, table filtering, plot animation and network diagram interaction. These instructions are not provided elsewhere.

Searching

This entire manual content can be searched by using the search box at the top of the table of contents pane (i.e. screen top left near the TUFLOW logo). This search box can be toggled on and off by clicking the search icon (magnifying glass) at the top left of any page.

The table of contents is dynamically filtered in response to entering text in the search box, and clicking on any remaining table of contents entry will navigate directly to the searched text. Searched text will be highlighted within a page for easy identification, and multiple instances within one page can be navigated through by using the up and down arrow keys. Clearing the search box will restore the table of contents.

Tables

Where appropriate, tables are searchable via use of the search box, which is located at the top right of any search enabled table. Not all tables are searchable. When text is entered into the search box, table rows are dynamically filtered to only show those that contain the search text. This allows on-the-fly condensing of large tables so that only relevant content is presented.

Tables can be sorted alphabetically (or reverse alphabetically) with respect to any column by clicking column headers. Where appropriate, the number of rows displayed is selectable via the Show entries drop down. Undisplayed rows can be accessed by clicking Previous or Next or by using the numbered navigation boxes, all of which are located at the bottom of each table.

Below is an example of a searchable table. Type “nitrate” (without the inverted commas) into the search box to see the table behaviour, or change the number of rows displayed (given this demonstration table has nine rows, only selecting “5” will change the number of rows displayed) and use the navigation buttons at the bottom of the table to look through all the data. The right hand column has hyperlinked words that allow navigation between related commands, or different versions of the same command, for ease of access. All hyperlinks have been deliberately disabled in this demonstration table, but are active (and explained) in live tables elsewhere in this manual.

Command Description Links
oxygen flux ==
 \(\langle\)\(F_{sed}^{O_2}\)\(\rangle\)
Used in a materials block to control the sediment flux rate of oxygen. Simulation construction section 4.6.4. \(\text{ }\)
inorganic nitrogen model ==
 \(\langle\)AmmoniumNitrate\(\rangle\)
Used to commence an inorganic nitrogen constituent model block via specification of a constituent model from the inorganic nitrogen constituent model class. Simulation construction section 4.7.3.3 \(\text{ }\)
atmospheric deposition ==
 \(\langle\)\(\left[{TN}\right]_{rain}\),\(R_{atm-dry}^{TN}\),\(f_{TN}^{NO_3}\)\(\rangle\)
Used in an inorganic nitrogen constituent model block to control the wet and dry atmospheric deposition of inorganic nitrogen. Simulation construction section 4.7.3.3.1. \(\text{ }\)
denitrification ==
 \(\langle\)Michaelis Menten,\(R_{denit}^{NO_3}\),\(K_{denit-O2-MM}^{NO_3}\),\(\theta_{denit}^{NO_3}\)\(\rangle\)
Used in an inorganic nitrogen constituent model block to activate the Michaelis Menten model and control denitrification and its response to ambient oxygen concentrations and temperature. Simulation construction section 4.7.3.3.1 exponential
denitrification ==
 \(\langle\)exponential,\(R_{denit}^{NO_3}\),\(K_{denit-O2-exp}^{NO_3}\),\(\theta_{denit}^{NO_3}\)\(\rangle\)
Used in an inorganic nitrogen constituent model block to activate the exponential model and control denitrification and its response to ambient oxygen concentrations and temperature. Simulation construction section4.7.3.3.1 Michaelis Menten
FRP min max ==
 \(\langle\)\(\left[FRP\right]_{min}^{FRP}\),\(\left[FRP\right]_{max}^{FRP}\)\(\rangle\)
Used in an inorganic phosphorus constituent model block to set minimum and maximum FRP concentrations. Simulation construction section 4.7.3.4.1 \(\text{ }\)
temperature limitation ==
 \(\langle\)none\(\rangle\)
Used in a phytoplankton constituent model block to turn off phytoplankton group temperature limitation. Simulation construction section 4.7.3.5.1.1 standard
temperature limitation ==
 \(\langle\)standard,\(T_{std}^{phy}\),\(T_{opt}^{phy}\),\(T_{max}^{phy}\)\(\rangle\)
Used in a phytoplankton constituent model block to set the standard phytoplankton group temperature limitation function. Simulation construction section 4.7.3.5.1.1 none
oxygen ==
 \(\langle\)on;off\(\rangle\)
Used in an inorganic phosphorus constituent model block to switch the dependence of FRP processes on dissolved oxygen on or off. Simulation construction section 4.7.3.4.1 \(\text{ }\)

Colour coding is often used for distinguishing different tabulated data types. In the above example, WQ Module commands are pink and the associated argument options for each command are blue and contained in angled parentheses. Colour coding applied to other table types is explained throughout this manual when required.

Figures

Where appropriate, this manual contains interactive figures that support understanding of processes and the influence of specifiable parameters on water quality outcomes. 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.

Networks

Interactive networks are used to assist in describing simulation architectures and process descriptions. In all cases, networks comprise nodes and connecting lines.

  • In the case of architecture networks, nodes are coloured and labelled circles. These nodes represent items within water quality architectural levels and are coloured as simulation classes, model classes, constituent models, or computed variables. Architectural relationships are displayed as connecting directional lines, with each line’s colour matching that of its originating node
  • In the case of process descriptions, nodes are coloured and labelled and are either circles (processes) or squares (computed variables). Circular process nodes are coloured as sources or sinks of computed variables. Where a process is both source and sink, its fill and outline are coloured accordingly. Square computed variables are all presented as the same colour. 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.

Single click anywhere on a network to activate interaction. A clicked network will show as being boxed in blue when activated. Once activated:

  • Single click or hover over a node to highlight its nearest neighbours. Single clicking anywhere off the network will deselect these. The intention is that this allows users to quickly identify related processes and computed variables
  • 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, hold and drag a node to move it if it covers other text or links. All nodes are able to be moved by hand in this way
  • Single click, hold and drag white space anywhere within the activated network area to drag 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
  • Double click on any node within an exploded group to implode the group back to its original state
  • Click the Reinitialize clustering button at the bottom of a network that uses clustering to return an exploded network to its original position, zoom and unexploded state. Not all networks use clustering so this button may not always be present

Networks are deactivated when anywhere outside its blue box is clicked.

In some instances, the network may explode to a position outside the original view frame, and some nodes or connecting lines might disappear. This is intentional, and prevents networks rescaling and becoming unreadably small. If this does happen and content of interest is off screen, simply use the mouse wheel to zoom out, or click, hold and drag the network in a direction that will bring obscured nodes back on screen, or do both.

Below are example architecture and process description networks to explore.






Commands

Where specific commands are described, they appear in highlighted text, and often as a clickable link to the corresponding command description in Appendix B. That Appendix is a searchable table of all commands, as per the demonstration table presented in this introduction. The below is an example of a WQ Module command (the hyperlink has been disabled for this example). \(\newcommand{\blockindent}{\hspace{0.5cm}}\)

simulation class ==

Where commands specify computed variable parameters (e.g. half saturation concentrations, sediment fluxes etc.) then for consistency and brevity, these parameters are included directly in the command example using their notation (see following section that describes notation) rather than descriptive words. These notated parameters are also often a clickable link to descriptive explanations in Appendix Q. The link below is an example of a WQ Module command with variables presented in their respective notations. Hyperlinks have been removed in this example.

\(\blockindent\) oxygen benthic == \(K_{sed-O_2}^{O_2}\), \(\theta_{sed}^{O_2}\)

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}\)
  • The fraction of total nitrogen rainfall concentration (or dry atmospheric fallout) that is nitrate is notated as \(f_{atm-TN}^{NO_3}\)

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}\).

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 Section 4.2, which should be reviewed carefully.

Feedback

Constructive suggestions to improve this manual are welcome, and can be emailed to .