4.5 Water quality control file commands

The water quality control file comprises three parts, with each part containing different types of commands and flags. Whilst it is recommended that these parts be kept separate and in the order described below (especially given how complex water quality simulations can become), doing so is not mandatory and commands or command blocks may be entered in any order.

These parts are as follows, with the first two mirroring the architecture described in Section 2:

1. Simulation controls (i.e. simulation class)
2. Constituent model settings (i.e. constituent model class)
3. Material specifications

Notwithstanding this, a WQ Module control file need not contain any commands, and can be completely blank. This is by design, and intended to allow users to rapidly set up and execute a TUFLOW water quality simulation. If the water quality control file is left blank, then the WQ Module will:

• Construct a simulation using the dissolved oxygen simulation class (which is the simplest class)
• Set the simulation units to mg/L
• Set library defaults for all parameters
• Set the water quality model timestep to the default
• Assign zero dissolved oxygen concentration to all boundary conditions. This is by design, and will assist in ensuring that the subsequent user-defined updating of boundary conditions is thorough and complete (zero dissolved oxygen boundary conditions are rare and therefore easily identifiable).

Initial conditions will also need to be specified in the TUFLOW FV control file as per Section 4.4.2. Specification of boundary conditions can be deferred.

The water quality control file sections are described below. Details specific to each simulation class and constituent model are provided in subsequent sections

4.5.1 Part 1: Simulation controls

Simulation controls set the high level operation of the WQ Module and are not specific to a simulation class. All are optional. Available commands set the:

• Simulation class via Simulation Class ==
• Timestep dt (in seconds) at which TUFLOW calls the WQ Module via WQ dt ==
• Units of simulation via WQ Units ==
• Frequency of equilibrium substepping Fess (in number of timesteps) to execute non-kinetic equilibrium calculations via WQ Equilibrium Substeps ==
• Reporting or suppression of minimum / maximum concentration exceedances (see Section 4.5.2) via Report Min Max Warnings ==

A typical simulation control section might therefore look like the following:

Simulation Class == DO
WQ dt == 600.0
WQ Units == MgL
WQ Equilibrium Substeps == 1
Report Min Max Warnings == ON

4.5.2 Part 2: Constituent model settings

Constituent model settings are those that:

• Specify the constituent model to be used within each preset constituent model class. These are referred to as constituent model blocks
• Set the parameters for each of these constituent models, as commands within these blocks

All are optional, however if a constituent model block is initiated then it requires an End XXXX Model command to terminate the block, where XXXX is the name of the constituent model class, such as inorganic nitrogen. An example of a user selecting to use the adsorbed filterable reactive phosphorous constituent model (that is a model available within the inorganic phosphorus constituent model class), and setting some parameters within that model is as follows:

Inorganic Phosphorus Model == FRPads
  Atmospheric Deposition == 12.6, 0.5
End Inorganic Phosphorus Model

Parameters not specified by the user are set to library defaults.

All constituent models allow for constraining (and then reporting) the predictions of their respective computed variable concentrations via the setting of minimum and maximum limits, if desired. This is often useful in identifying unusual model behaviours or instabilities. Where exceedences of these limits are identified by the WQ Module:

• Time and model cell information is written to the WQ Module log file in real time. This allows for easy identification of potential model issues via periodic examination of the WQ Module log file, rather than waiting for simulation completion
• The WQ Module resets the computed concentration to the relevant specified minimum or maximum concentration

The above resetting will result in mass conservation errors. It should not be relied on to artificially control the behaviour of an otherwise unstable or runaway water quality simulation. Rather, this functionality should be used as a convenient way to check model performance and flag potential issues, with a view to then implementing corrective action. Equally, suppressing warnings written to the WQ log file using the Report Min Max Warnings == command described in Section 4.5.1 is not recommended because doing so may mask underlying model construction issues.

These limits are optionally specified in each constituent model block. An example that sets these limits for ammonium is:

Ammonium Min Max == 0.0, 25.0

Although in the strictest sense, sediment (benthic) flux half saturation concentrations and temperature coefficients are benthic properties, the WQ Module does not yet support these parameters being applied on a spatially varying basis (i.e. per material). As such, these are considered to be constituent model global parameters and so are set in this part of the water quality control file, i.e. within respective constituent model blocks. An example that sets an oxygen half saturation and temperature coefficient for benthic flux is:

Oxygen Benthic == 5.0, 1.08

4.5.3 Part 3: Material specifications

The final part of the water quality control file (*.fvwq) provides for specification of benthic (sediment) fluxes, via material blocks. The commands required to commence and terminate a materials block are as follows:

Material == <up to 10 comma separated material numbers, or “Default”>

and

End Material

This material block nomenclature mirrors that used in the TUFLOW FV and sediment transport control files. An example of specifying oxygen and nitrate benthic fluxes for materials 2, 7 and 12 is:

Material == 2, 7, 12
  Oxygen Flux == -60.0
  Nitrate Flux == 12.5
End Material

The WQ Module allows for specification of a default set of benthic fluxes that are applied across all materials, by using the key word Default instead of specifying material numbers in a material block. These defaults can then be progressively overwritten on a material by material basis by specifying subsequent material blocks.

For example, a model that has ten materials in total, eight of which have the same oxygen benthic flux (all materials except 4 and 7), can have its overall oxygen benthic flux specified as:

Material == Default
  Oxygen Flux == -60.0
End Material

Material == 4, 7
  Oxygen Flux == -20.0
End Material

4.5.4 Summary

In order to set up and execute a water quality simulation using the WQ Module, the following steps are required:

• Modify the TUFLOW FV control file:
  • Add at least the following commands to TUFLOW FV control file (*.fvc):
    • Water Quality Model == TUFLOW
      
    • Water Quality Control File == <water quality control file name>.fvwq
  • Optionally add a folder path command to the TUFLOW FV control file (*.fvc) with a trailing backslash:
    • Water Quality Model Dir == <relative path to *.fvwq file>\
  • Add appropriate initial conditions for all water quality constituents, observing ordering rules where required
  • Initially optionally add boundary conditions for all water quality constituents, observing ordering rules in BC Header == commands
• Create the water quality control file with the corresponding name and path
• Modify the water quality control file
  • Optionally add to the water quality control file:
    • Part 1: A simulation controls section
    • Part 2: A constituent model setting section with one or more constituent model blocks with one or more parameter commands
    • Part 3: A material block specifications section

Once initially constructed, boundary conditions can be added (if not already in place), and progressive refinement and parameterisation of constituent models and benthic fluxes can be affected. Details of these commands and their options within each specific simulation class are provided in subsequent sections. Subsections are separated into the above water quality control file parts for ease and consistency of reference. All commands are optional.

4.5.5 Log files

Every WQ Module water quality simulation generates a log file that contains an echo of the WQ Module construction and execution commentary. It is written to the same location (and with the same name) as the WQ Module control file, with the file extension “fvwqlog”. This file contains a great deal of information that should be carefully reviewed. Suppressing warnings written to this log file, although possible, is not recommended or encouraged.