4.4 TUFLOW FV control file commands

A TUFLOW FV simulation is executed as described in the TUFLOW FV user manual. If the WQ Module is to be activated in a simulation then the following commands are to be included.

4.4.1 WQ Module activation

Activation of the WQ Module is affected by specification of the following mandatory command in the TUFLOW control file:

Water Quality Model == TUFLOW

Following this activation, TUFLOW FV will look for the specification of the name of the separate WQ Module control file via the following mandatory command:

Water Quality Control File == <water quality control file name>.fvwq

This *.fvwq is separate to the *.fvc and contains user specified information that describes the configuration of the water quality simulation. If the *.fvwq is located in the same directory as the *.fvc, then this filename specification needs no associated path. It is recommended however that the *.fvwq be located in a directory separate to the *.fvc so that log and other related water quality specific files can be easily curated. If this approach is adopted, the following additional *.fvc command is required, noting that the folder path is specified as relative to the folder in which the *.fvc resides:

Water Quality Model Directory == <relative path to WQ directory>$\backslash$

This command must terminate in a $\backslash$ character. If this command is issued, then the *.fvwq water quality control file must be located in the directory specified.

In certain circumstances, executing water quality calculations in shallow cells can cause numerical instabilities. To control this behaviour, the WQ Module allows for water quality calculations to be switched off in cells that have depths less than a specified minimum (advection dispersion calculations will however continue to be performed - it is only the water quality-related non-conservative transformations that are turned off). This minimum depth (in meters) is specified in the TUFLOW FV *.fvc via the command:

Cell Water Quality Depth == $d_{min-wq}$

If this command is not issued then the default minimum depth of 0.01m (1cm) is applied.

This command parallels the TUFLOW FV command that controls the execution of hydrodynamic calculations as a function of water depth:

Cell Wet/Dry Depths == Cell Dry Depth (m), Cell Wet Depth (m)

In this TUFLOW FV command:

The cell dry depth value (default = 1.0e-06 m) corresponds to the water depth below which a cell is dropped completely from hydrodynamic (TUFLOW FV) computations (subject to the status of surrounding cells) and is therefore considered to be ‘dry’. Cells that have dried in a given time step are given a stat value of 0 in all TUFLOW FV results files, so this stat field acts as a mask to determine which cells are wet and dry when using post processing tools and or scripts. Dry cells are not contoured in QGIS or SMS when viewed, but appear as transparent. If set to a negative value the cell dry depth is set to zero.
The cell wet depth value (default = 1.0e-02 m) corresponds to the water depth below which a cell’s momentum is set to zero in order to avoid unphysical velocities at very low depths. The cell is not considered to be dry and therefore has a stat value of -1. If this value is less than or equal to the cell dry depth, it is set to the cell dry depth.

Given this, it is therefore recommended that across these commands a user ensures that the following holds:

\[\begin{equation} \text{cell dry depth} < \text{cell wet depth} < \text{cell water quality depth} \tag{4.3} \end{equation}\]

If, for example, cell water quality depth is set to a value less than cell dry depth, then water quality calculations will be attempted on cells that TUFLOW FV considers to be dry, which is to be avoided. If a situation arose where it was absolutely necessary, then cell water quality depth could be set to a value less than cell wet depth (but still greater than cell dry depth), but this is not recommended. To summarise, and if the recommended relative magnitudes of depths presented in Equation (4.3) is adopted, then the following applies:

water depth $\gt$ cell water quality depth: water quality calculations and momentum calculations performed
cell water quality depth $\gt$ water depth $\gt$ cell wet depth : water quality calculations switched off, momentum calculations performed (advection and dispersion calculations also performed on water quality variables)
cell wet depth $\gt$ water depth $\gt$ cell dry depth: water quality calculations switched off, momentum calculations switched off (advection and dispersion calculations also performed)
cell dry depth $\gt$ water depth: no calculations performed - cell is considered dry

To support debugging, water quality calculations can also be turned off completely for all cells and all timesteps by issuing this command in the TUFLOW FV *.fvc:

Disable Water Quality Model == $B_{disable-wq}$

and setting $B_{disable-wq}$ $= 1$. Omitting this command, or setting $B_{disable-wq}$ to zero (“0”) instead of one (“1”), will activate water quality calculations. If this command is set to one (“1”), then the WQ Module will still initialise are report as such, but when TUFLOW executes, the module will not be called.

Consistent with their specification in the *.fvc, the status of these latter two commands and their arguments are reported in the TUFLOW FV log file, rather than the WQ Module log file.

An example block of these five commands that together activate the WQ Module, point TUFLOW FV to the water quality control file ..\WQ$\Model_000.fvwq and set the minimum depth for executing water quality calculations to 5 centimetres is:

Water Quality Model == TUFLOW
Water Quality Model Directory == ..\WQ\
Water Quality Control File == ..\Model_000.fvwq
Cell Water Quality Depth == 0.05
Disable Water Quality Model == 0

4.4.2 Initial and boundary conditions

In addition to activating the WQ Module and specifying its control file, WQ Module initial and boundary condition information is also set through the TUFLOW FV control file. The processes for doing so are described below. These are followed by discussion of the related matter of constituent ordering within initial and boundary condition specifications.

4.4.2.1 Initial conditions

Water quality initial conditions are specified within or via the TUFLOW FV control file, akin to the manner in which the sediment initial conditions are set on behalf of the sediment transport module. This specification is mandatory.

There are currently a number of ways that water quality initial conditions may be specified. All are affected through TUFLOW FV commands which are described in the TUFLOW FV user manual. If no water quality initial conditions are specified, then a simulation will not execute. The specifications relevant to water quality simulations are described below. The potential limitations of some of these approaches are recognised and will be addressed in future release of the WQ Module.

4.4.2.1.1 Restart files

Restart files are binary files that are generated from previous simulations. These can be used as inputs to initialise water quality simulations, provided that the restart and simulation model geometries, and water quality simulation computed variables and units are identical. A restart file is specified for all simulated quantities (not just water quality) and is controlled through commands described in the TUFLOW FV user manual. The key command is

Restart == <restart file name>.rst

Most often, restart files are located in the log directory, but this is not mandatory.

4.4.2.1.2 Globally uniform

Globally uniform (i.e. across all spatial dimensions) initial conditions are set via a command issued from within the TUFLOW FV control file. This is often useful in setting initial conditions for simple small water bodies or at the commencement of a modelling process where initial conditions are set to be placeholders and updated at a later time. The command to do so is:

Initial WQ Concentration == Ordered Initial Conditions

Each water quality computed variable is set to a single value everywhere. These initial concentrations must be specified in a particular order and this order is described in the following sections for different simulation classes. If the above command is used to set water quality initial conditions, then it must be accompanied by parallel commands that set globally uniform salinity, temperature (and optionally sediment) initial conditions:

Initial Temperature == 15.0
Initial Water Level == 1.00
Initial Sediment Concentration == 10.0
Initial Salinity == 3.5

Setting a mix of globally uniform and other initial conditions (such as profile, 2D or 3D) is not permitted.

4.4.2.1.3 Globally laterally uniform

Globally laterally uniform initial conditions use an initial profile to set hydrodynamic and water quality computed variable concentrations to be everywhere the same laterally, but to vary vertically. This is often useful in setting initial conditions for deep stationary water bodies such as lakes or reservoirs. The command to do so is:

Initial Scalar Profile == .csv

An example of the form of the text file argument <initial condition file name>.csv for simulating five water quality constituents is:

Depth,Sal,temp,sed_1,WQ_1,WQ_2,WQ_3,WQ_4,WQ_5
0.0,2.0,22.0,5.0,8.0,22.0,2.6,1.4,0.5
10.0,2.5,15.0,15.0,5.0,32.0,2.6,1.4,0.2
20.0,3.0,10.0,25.0,0.0,42.0,5.6,5.4,0.1

If the above command is used, then it must include profile information that also sets laterally uniform salinity, temperature (and optionally sediment) initial conditions. Setting a mix of laterally uniform and other initial conditions (such as globally uniform, 2D or 3D) is not permitted.

The order of these columns in the argument csv file is not important, but the columns headers are keywords and must be used as shown. For example, the following structure for <initial condition file name>.csv is permitted:

Depth,temp,WQ_3,Sal,sed_1,WQ_4,WQ_1,WQ_2,WQ_5
0,22,2.6,2,5,1.4,8,22,0.5
10,15,2.6,2.5,15,1.4,5,32,0.2
20,10,3,3,25,5.4,0,42,0.1

Notwithstanding this, it is still considered best practise to develop initial and boundary condition files that have a logically sequential order. Water quality initial conditions headers are labelled “WQ_1”, “WQ_2” onward, and the match between these header labels and water quality computed variables is set by the computed variable ordering of the simulation class deployed.

4.4.2.1.4 Globally vertically uniform

Globally vertically uniform initial conditions use an initial two dimensional map to set hydrodynamic and water quality computed variable concentrations to be everywhere the same vertically, but to vary laterally. This is often useful in setting initial conditions for shallow water bodies that have horizontal concentration gradients such as small estuaries or urban lakes. The command to do so is:

Initial Condition 2D == .csv

An example of the form of the text file argument <initial condition file name>.csv for simulating five water quality constituents is:

ID,WL,sal,temp,sed_1,WQ_1
1,1.0,3.5,15,10.0,8.0
2,1.0,3.5,15,10.0,7.5
3,1.0,3.5,15,10.0,7.0
4,1.0,3.5,15,10.0,6.5

If the above command is used, then it must include information that also sets vertically uniform salinity and temperature (and optionally sediment) initial conditions, as well as water level. Setting a mix of vertically uniform and other initial conditions (such as globally uniform, laterally uniform or 3D) is not permitted.

ID,WQ_1,WL,sed_1,sal,temp
1,8.0,1.0,10.0,3.5,15
2,7.5,1.0,10.0,3.5,15
3,7.0,1.0,10.0,3.5,15
4,6.5,1.0,10.0,3.5,15

4.4.2.1.5 Globally varying

Globally variable initial conditions use an initial three dimensional map to set hydrodynamic and water quality computed variable concentrations at each 3D cell. This is analogous to using a restart file. The command to do so is:

Initial Condition 3D == .csv

An example of the form of the text file argument <initial condition file name>.csv for simulating five water quality constituents is as follows, noting that the “ID” column refers to a three dimensional cell ID, rather than the two dimensional column ID used in the Initial Condition 2D == command.

ID,WL,sal,temp,sed_1,WQ_1
1,1.0,3.5,15,10.0,8.0
2,1.0,3.5,14,10.0,7.5
3,1.0,3.5,13,10.0,7.0
4,1.0,3.5,12,8.0,6.5
5,1.0,3.5,15,10.0,8.0
6,1.0,3.5,14,10.0,7.4
7,1.0,3.5,13,10.0,7.1
8,1.0,3.5,11,9.0,6.6

If the above command is used, then it must include information that also sets globally varying salinity and temperature (and optionally sediment) initial conditions, as well as water level. Setting a mix of vertically uniform and other initial conditions (such as globally uniform, laterally uniform or 2D) is not permitted.

ID,WQ_1,WL,sed_1,sal,temp
1,8.0,1.0,10.0,3.5,15
2,7.5,1.0,10.0,3.5,14
3,7.0,1.0,10.0,3.5,13
4,6.5,1.0,8.0,3.5,12
5,8.0,1.0,10.0,3.5,15
6,7.4,1.0,10.0,3.5,14
7,7.1,1.0,10.0,3.5,13
8,6.6,1.0,9.0,3.5,12

4.4.2.2 Boundary conditions

Water quality boundary conditions are also specified via the *.fvc file, either directly or via an include statement that points TUFLOW FV to a subsidiary boundary condition control file(s). This specification of water quality variable concentrations is optional, so in early water quality model construction stages this specification can be omitted. Omitted water quality boundary conditions will be set to zero. It is not recommended that this approach be taken beyond initial simulation setup stages, but that it be used only to develop a water quality simulation to the point where it executes without issuing error or unwanted warning messages. At this point, all water quality boundary conditions should be assigned.

All TUFLOW boundary conditions that specify water temperature or salinity will also require specification of the behaviour of simulated water quality variables. Common boundary conditions to which this applies include inflows (e.g. types Q, QC, QN, QG and others) and tidal boundaries (e.g. types WLS). Wave and meteorological boundary conditions do not need specification of water quality conditions.

As for initial conditions, boundary conditions that use columnar data structures (e.g. *.csv files) are interpreted using column headers specified in an expected order within calling TUFLOW FV BC blocks. Further detail and the associated ordering is provided in the following sections (sections 4.6, 4.7 and 4.8 for simulation classes DO, inorganics and organics, respectively).

4.4.2.3 Ordering

Specification of initial conditions and most boundary conditions presently relies on listing water quality variables in a particular order. This applies in all instances when water quality initial or boundary conditions are provided in columnar or list form, which is most frequently in text file format. This is conceptually similar to the manner in which TUFLOW FV also relies on ordering of its initial and boundary conditions.

Future releases of TUFLOW FV will allow alternative methods for specification of initial and boundary conditions that do not rely on assumed ordering. In the interim however, the following applies.

4.4.2.3.1 Initial Conditions

Initial conditions, if set using means other than a restart file, must be specified with water quality constituents in a preset order (globally uniform), or be referenced using incrementally numbered headers as “WQ_1”, “WQ_2” etc (profile, 2D or 3D, see Section 4.4.2.1).

For globally uniform initial conditions (Section 4.4.2.1.2), the following *.fvc command can be used for a typical inorganics simulation class:

Initial WQ Concentration == 7.5, 0.0, 4.2, 10.5, 0.6, 5.5

There are no references to headers or variable names, but TUFLOW FV assumes that these numbers correspond to the ordered variables of the particular configuration of the inorganics simulation class returned to it from the WQ Module. In this example, this ordering is:

Dissolved oxygen (7.5 mg/L)
Silicate (0.0 mg/L)
Ammonium (4.2 mg/L)
Nitrate (10.5 mg/L)
Filterable reactive phosphorus (0.6 mg/L), and
One phytoplankton group (5.5 $\mu$g/L)

The expected ordering is the same as that for boundary condition specifications, as described below.

For other initial condition specifications that involve providing csv files, the headers “WQ_1”, “WQ_2” etc must be used to denote water quality initial conditions. The ordering of the associated columns does not matter, however the assignment of a computed variable initial condition to a “WQ_XX” header (where XX is a number) does rely on the ordering described below - the first water quality computed variable expected should be headed “WQ_1” and so on.

4.4.2.3.2 Boundary Conditions

Ordering of water quality boundary conditions is only important when specifying header information via the BC Header == (or equivalent) command within a TUFLOW FV *.fvc file BC block. It is in these commands (where comma separated header strings are specified) that TUFLOW FV expects a particular order of TUFLOW FV and WQ Module constituents. No column ordering is expected in boundary condition data files themselves. Ordering is only expected in the order of headers specified within a BC block within an TUFLOW FV control file. This is best illustrated by example.

If a user has elected to deploy the inorganics simulation class without sediment, then the following will be simulated (beyond the basic velocity and water level hydrodynamic variable suite):

Salinity
Temperature
Dissolved oxygen
Silicate
Ammonium
Nitrate
Filterable reactive phosphorus
One (assumed for this example, but can be multiple) phytoplankton group

These will eventually need proper boundary condition specification in boundary condition blocks and have supporting data provided in (usually) text files. In a simple model with only one WL boundary condition, a BC block of the following form would be required as a minimum to properly specify the hydrodynamic and water quality boundaries:

BC == WL, 1, datafile.csv
BC Header == Time, WSEl, Sali, Temp, DOxy, SiO4, NH41, Nitr, FRPh, Bluegreen
End BC

To be clear:

The names listed on the “BC Header ==” line (time, wse etc.) are not keywords or special names, and can be any names that a user chooses
TUFLOW FV will however, assume that these names (whatever they have been set to) have been listed in such an order that they have a one to one correspondence to the ten computed variables as follows:
1. Time $\rightarrow$ Time stamp
2. WSEl $\rightarrow$ Water surface elevation
3. Sali $\rightarrow$ Salinity
4. Temp $\rightarrow$ Temperature
5. DOxy $\rightarrow$ Dissolved oxygen
6. SiO4 $\rightarrow$ Silicate
7. NH41 $\rightarrow$ Ammonium
8. Nitr $\rightarrow$ Nitrate
9. FRPh $\rightarrow$ Filterable reactive phosphorus
10. Bluegreen $\rightarrow$ Phytoplankton group one
TUFLOW then matches the user specified names to the expected simulation variables, based on this ordering, to then interrogate boundary condition files.

Following the above matching, TUFLOW FV interrogates the relevant boundary condition file (“datafile.csv” in the example above), where this file can have its columns arranged in any order: the order of these columns does not matter because TUFLOW FV will use the mapping previously developed via the BC Header == command to look through all data file columns one by one, searching for the headers specified, regardless of the actual ordering of boundary condition file columns. For example, the silicate boundary condition data could be positioned in column 14 of the boundary condition file, but as long as it is labelled with the correct header (“SiO4” as specified in BC Header ==), TUFLOW FV will know to assign column 14 of the boundary condition data file to the silicate computed variable.

Ordering is set by the user’s selection of simulation class and constituent models, and is explicitly listed in each simulation class section (Sections 4.6.5, 4.7.5 and 4.8.5 for DO, inorganics and organics, respectively). The expected ordering for a particular simulation is also reported in the simulation water quality log file for checking.