6 Model Construction: 3D HD Simulation Class

6.1 Overview

This chapter describes model construction specific to the 3D hydrodynamic (3D HD) simulation class.

The 3D HD simulation class extends the 2D hydrodynamic simulation class described in Chapter 5. This chapter assumes familiarity with the 2D HD model construction process and follows the standard model construction structure defined in that chapter. Content in this chapter documents only model classes and configurations that are new to 3D HD simulations or are extensions of model classes previously introduced in the 2D HD simulation class.

Typical 3D HD simulation class use cases are hydrodynamic applications that do not require salinity, temperature or density effects such as the following.

Hydraulic structure design
Rudimentary scour assessment using bed shear stress outputs (not sediment transport)

This chapter sets up the fundamental 3D model components for 3D advection dispersion, 3D sediment transport, 3D water quality or 3D particle tracking simulations. These components are extended in the following chapters.

6.2 Spatial Order

6.2.1 Command Status

Optional - The commands in this section are only required if second order vertical spatial reconstruction is specified, otherwise defaults will apply and the commands can be omitted from the .fvc file.

6.2.2 Description

This section describes spatial order commands relating to vertical processes. Prior to reading this section users should review horizontal spatial order as described in the 2D HD Simulation Class Chapter (see Section 5.5.2). As for the 2D HD Simulation Class, first and second order vertical spatial order options are available. Supported vertical spatial order model implementations are summarised in Table 6.1, with links to the relevant implementation sections below. Vertical spatial order commands relevant to the 3D HD simulation class are provided in Table 6.2.

Table 6.1: Vertical Spatial Order Model Implementations

Model Implementation	Description
First Order	Uses a first order numerical method when calculating fluxes between cells.
Second Order	Uses a second order numerical method when calculating fluxes between cells.

Table 6.2: Vertical Spatial Order Commands

Command	Description
Spatial Order	Optional - Sets the vertical spatial reconstruction to first or second order.
Vertical Gradient Limiter	Optional - Sets the vertical gradient limiter model used with second order vertical spatial reconstruction. Not used for first order vertical spatial construction.
Vertical AlphaR	Optional - Sets a reduction factor to scale between first and second order vertical spatial reconstructions for vertical velocity model variable fields. Not used for first order vertical spatial construction.

6.2.3 First Order

First order vertical spatial reconstruction calculates fluxes between 3D cells using a uniform value within each cell. This provides a stable and reliable solution. It is the default spatial order implementation.

! First Order Horizontal and Vertical Spatial Accuracy
Spatial Order == 1,1            ! {1 1st Order Horizontal} | 2 2nd Order Horizontal, {1 1st Order Vertical} | 2 2nd Order Vertical

6.2.4 Second Order

Second order vertical spatial reconstruction computes fluxes between 3D cells using estimated gradients within each cell. This approach represents sub cell variation in vertical fluxes rather than assuming uniform conditions and therefore produces a more accurate numerical solution. The scheme is typically applied to problems with strong vertical gradients in velocity or where 3D hydrodynamics will underpin the simulation of density stratification if the model is intended to be extended to AD simulation (see Chapter 7).

! Second Order Vertical Spatial Accuracy
Spatial Order == 1,2            ! {1 1st Order Horizontal} | 2 2nd Order Horizontal, {1 1st Order Vertical} | 2 2nd Order Vertical

! Second Order Vertical Spatial Accuracy With Gradient Limiters
Spatial Order == 1,2            ! {1 1st Order Horizontal} | 2 2nd Order Horizontal, {1 1st Order Vertical} | 2 2nd Order Vertical
Vertical Gradient Limiter == MC ! {MC} | MINMOD | SUPERBEE
Vertical AlphaR == 0.5, 0.5     ! {1.0} AlphaV (velocity), {1.0} AlphaS (scalars, ignored in the 2D HD simulation class)

6.3 Computational Timestep

6.3.1 Command Status

Information Only - Commands are specified during 2D HD model construction.

6.3.2 Description

No additional commands are required for 3D simulation beyond those described in Section 5.7. Additional stability calculations are executed on horizontal and vertical cell faces using the specified timestep limits, as described in Section B.4.5.3.

6.4 Horizontal Mixing

6.4.1 Command Status

Information Only - Commands are specified during 2D HD model construction.

6.4.2 Description

Horizontal mixing is specified as described in Section 5.10 and Section B.7. The same models and parameterisations are available in 3D, however the Wu model (Section 5.10.6) is not recommended for 3D simulation.

6.5 Vertical Mixing

6.5.1 Command Status

Required.

6.5.2 Description

Vertical turbulent mixing of momentum is modelled using the Vertical Mixing Model command. The available models are presented in Table 6.3 and the associated commands are presented in Table 6.4.

Both the \(k-\epsilon\) and \(k-\omega\) models can be optionally extended using the Second Order Vertical Mixing Model, Vertical Mixing Length Scale Limiter and Internal Wave Mixing Model commands. Regardless of the model chosen, vertical turbulent mixing calculations are undertaken at the time interval specified by Turbulence Update dt, in seconds. Further information on the science of each model is provided in Section B.10.

Table 6.3: Vertical Mixing Model Implementations

Model Implementation	Description
Constant	Spatially constant vertical mixing value.
Parametric	Parametric mixing model
K-Epsilon	k-\(\epsilon\) mixing model after Launder & Spalding (1974)
K-Omega	k-\(\omega\) mixing model after Wilcox (1988)

Table 6.4: Vertical Mixing Model Commands

Command	Description
Vertical Mixing Model	Conditional - Required for 3D HD simulations. Selects the momentum mixing model for vertical subgrid scale turbulent mixing.
Vertical Mixing Parameters	Conditional. Sets the input parameters for the selected vertical mixing model.
Global Vertical Eddy Viscosity Limits	Optional - Sets a minimum and maximum limit on computed eddy viscosity.
Turbulence Update dt	Optional - Sets the update timestep for the K-Epsilon and K-Omega vertical mixing models.
Global Minimum Vertical TKE	Optional - A user-specified minimum limit on the calculated turbulent kinetic energy.
Global Minimum Vertical EPS	Optional - A user-specified minimum limit on the calculated turbulent dissipation rate.
Second Order Vertical Mixing Model	Optional - Second order vertical turbulence closure method.
Second Order Vertical Mixing Model Parameter Group	Optional - Suite of parameters for use in the second order turbulence closure method.
Vertical Mixing Length Scale Limiter	Optional - Turbulent length scale limter for K-Epsilon and K-Omega vertical mixing models.
Internal Wave Mixing Model	Optional - Account for vertical mixing below the thermocline or halocline associated with internal waves.
Internal Wave Mixing Model Parameters	Optional - Sets the input parameters for the selected internal wave mixing model.

6.5.3 Constant

This model sets a single value for the vertical eddy viscosity.

! Vertical Mixing Model Commands
Vertical Mixing Model == Constant       ! {Constant} | Parametric | K-Epsilon | K-Omega
Vertical Mixing Parameters == 1E-06     ! {0.0} Vertical eddy viscosity (and diffusivity) (m^2/s)

6.5.4 Parametric

This model uses a parametric description to compute eddy viscosity (see Section B.10.1.1). Global upper and lower limits can be applied to constrain the calculation.

! Vertical Mixing Model Commands
Vertical Mixing Model == Parametric                     ! {Constant} | Parametric | K-Epsilon | K-Omega
Vertical Mixing Parameters == 0.41, 0.41                ! {0.41} Parametric model coefficient 1, {0.41} Parametric model coefficient 2
Global Vertical Eddy Viscosity Limits == 1.0e-4, 1.0    ! {0.0} Minimum eddy viscosity (m^2/s), {99999.} Maximum eddy viscosity (m^2/s)

6.5.5 K-Epsilon

This model follows Launder & Spalding (1974) to estimate vertical eddy viscosity (see Section B.10.1.2). Global upper and lower limits can be applied to constrain the calculation. Minimum turbulent kinetic energy (TKE) and turbulent kinetic energy dissipation rates (EPS) can also be set.

Three extension options are available for the \(k-\epsilon\) mixing model. The associated commands are presented in Section 6.5.7.

! Vertical Mixing Model Commands
Vertical Mixing Model == K-Epsilon                                  ! {Constant} | Parametric | K-Epsilon | K-Omega
Vertical Mixing Parameters == 1.44, 1.92, 0.09, 1.0, 1.3, 1.0, 0.0  ! {1.44} C_1e, {1.92} C_2e, {0.09} Cmu, {1.0} sigma_k, {1.3} sigma_omega, {1.0} C_3omega+, {0.0} C_3omega-

! Vertical Mixing Limits
Global Vertical Eddy Viscosity Limits == 1.0e-4, 1.0                ! {0.0} Minimum eddy viscosity (m^2/s), {99999.} Maximum eddy viscosity (m^2/s)
Global Minimum Vertical TKE == 1.e-10                               ! {1E-10 m^2/s^2} Minimum turbulent kinetic energy
Global Minimum Vertical EPS == 1.e-14                               ! {1E-14 m^2/s^3} Minimum dissipation rate

6.5.6 K-Omega

This model follows Wilcox (1988) to estimate vertical eddy viscosity (see Section B.10.1.3). Global upper and lower limits can be applied to constrain the calculation. Minimum turbulent kinetic energy (TKE) and turbulent kinetic energy dissipation rates (EPS) can also be set.

Three extension options are available for the \(k-\omega\) mixing model. The associated commands are presented in Section 6.5.7.

! Vertical Mixing Model Commands
Vertical Mixing Model == K-Omega                                                ! {Constant} | Parametric | K-Epsilon | K-Omega
Vertical Mixing Parameters == 0.55555, 0.075, 0.0768, 2.0, 2.0, 0.0, -0.637117  ! {5/9} alpha, {3/40} beta, {0.09} Cmu, {2.} sigma_k, {2.}sigma_omega, {0.} C_3omega+, {0.} C_3omega-

! Vertical Mixing Limits
Global Vertical Eddy Viscosity Limits == 1.0e-4, 1.0                            ! {0.0} Minimum eddy viscosity (m^2/s), {99999.} Maximum eddy viscosity (m^2/s)
Global Minimum Vertical TKE == 1.e-10                                           ! {1E-10 m^2/s^2} Minimum turbulent kinetic energy
Global Minimum Vertical EPS == 1.e-14                                           ! {1E-14 m^2/s^3} Minimum dissipation rate

6.5.7 K-Epsilon and K-Omega Extension Options

Three extension options are available to both the \(k-\epsilon\) and \(k-\omega\) turbulence models.

6.5.7.1 Second Order Model

The Second Order Model (see Section B.10.1.4) is used to optionally extend the \(k-\epsilon\) or \(k-\omega\) Vertical Mixing Model. A parameter group is required in conjunction with this command.

! Enable second-order algebraic formulation for Cmu
Second Order Vertical Mixing Model == Algebraic
! Specify parameter group ID for second-order model (No default)
Second Order Vertical Mixing Model Parameter Group == GL78

6.5.7.2 Lengthscale Limiter

The Lengthscale Limiter (see Section B.10.1.5) is used to optionally extend the \(k-\epsilon\) or \(k-\omega\) Vertical Mixing Model.

! Apply Galperin et al. (1988) length scale limiter using C_Gapl
Vertical Mixing Length Scale Limiter == 0.53    ! <C_Gapl> {0.53}

6.5.7.3 Internal Wave Mixing Model

The Internal Wave Mixing Model (see Section B.10.1.6) is used to optionally extend the \(k-\epsilon\) or \(k-\omega\) Vertical Mixing Model. The default parameters can also be overridden.

! Activate the internal wave mixing model (Kantha and Clayson, 1994)
Internal Wave Mixing Model == ON    ! {OFF}

! Optional override of model parameters == k_lim,iw, R_i,cr, nu_t,shear, nu_t,R, nu_h,R
Internal Wave Mixing Model Parameters == 1.0e-6, 0.7, 5.0e-3, 1.0e-4, 5.0e-5

6.6 Computational Mesh

6.6.1 Command Status

Required.

6.6.2 Description

This section describes computational mesh construction specific to the 3D hydrodynamic simulation class. This mesh construction is a direct extension of that described in Section 5.12 in that the following are required.

Specification of a 2D mesh (as per Section 5.12), and
Specification of a vertical discretisation implementation (extension of 2D HD, this section)

The vertical discretisation implementation determines the manner in which a 2D model is extended to 3D. Supported vertical discretisation implementations are summarised in Table 6.5, with links to the relevant implementation sections below. The required commands for these implementations are summarised in Table 6.6.

Table 6.5: Vertical Computational Mesh Model Implementations

Model Implementation	Description
Sigma	The default vertical mesh for 3D simulations. Uses terrain following sigma layers and supports wetting and drying.
Z	Uses fixed elevation z layers with a configurabled number of surface sigma layers. Suited to density stratification studies where wetting and drying is confined to the surface sigma layer range only.

Table 6.6: Computational Mesh Commands

Command	Description
Layer Face File	Conditional - Required for the 3D simulation class. Specifies the CSV file containing the vertical face distribution used by the selected vertical mesh type.
Vertical Mesh Type	Conditional - Required for the 3D HD simluation class. Selects the vertical discretisation method for the 3D mesh. Defaults to Sigma if not specified
Surface Sigma Layers	Optional - Sets the number of surface sigma layers for the Z vertical mesh type. Defaults to 1 if not specified.
Minimum Bottom Layer Thickness	Optional - Sets a minimum allowable bottom layer thickness to improve numerical robustness in shallow bottom cells. Not applicable to the sigma vertical mesh type.
Cell 3D Depth	Optional - Sets the depth threshold below which 3D momentum calculations are disabled while mass flux calculations are maintained. Useful for model stability in shallow water depths.

6.6.3 Sigma

The sigma implementation assigns the same number of vertical layers at every 2D cell. These layers follow the bed profile across the model domain and together occupy the entire water column (see Figure 6.1). As such, they generally vary spatially in their absolute thickness and in the elevations of their upper and lower faces. Sigma layers are useful for simulating boundary layer problems with a low computational overhead and for capturing areas of wetting and drying. Sigma layers are often not well suited to the simulation of vertical density stratification. Fixed z layers should generally be used in these instances (see Section 6.6.4).

A Layer Face File is also required to set the relative rather than absolute vertical distribution of sigma layers across the water column. This file is a CSV file with one column headed SIGMA. Each row contains a decimal number less than 1.0 (water surface) and greater than 0.0 (bed) that sets the elevation of the layer face as a fraction of the water column. Decimal numbers must be monotonically decreasing from the second row. If this command is not issued, no sigma layers will be assigned and the model will run in 2D.

! Sigma
Vertical Mesh Type == Sigma                         ! {Sigma} | Z
Layer Face File == ..\model\csv\LF_Sigma_001.csv    ! {No default} filepath

In very shallow (but not dry) regions, 3D momentum calculations can be turned off to support stability and speed of computation. The water depth at which this occurs can be set manually. Mass flux calculations are preserved.

! Sigma
Vertical Mesh Type == Sigma                         ! {Sigma} | Z
Layer Face File == ..\model\csv\LF_Sigma_001.csv    ! {No default} filepath
Cell 3D Depth == 0.5                                ! {0.1} Disable 3D momentum flux below this threshold (m)

Example sigma layer face file with five evenly distributed layers.

LF_Sigma_001.csv
SIGMA
0.8
0.6
0.4
0.2

Example sigma layer face file with seven unevenly distributed layers, with higher resolution towards the bed.

LF_Sigma_002.csv
SIGMA
0.9
0.8
0.6
0.2
0.1
0.05

6.6.4 Z

The Z implementation assigns vertical layers at fixed absolute heights across the entire model. These layers are horizontal and are useful for simulating vertical density stratification (see Figure 6.2). Z layers cannot wet and dry so specified heights must be always less than the minimum expected surface water level. To allow for surface water level changes and wetting and drying, one sigma layer is activated by default and this layer occupies the vertical range between the uppermost (fixed and user specified) Z layer and the dynamically computed water surface.

Figure 6.2: Z Vertical Mesh With Surface Sigma Layers

A Layer Face File is also required to set the absolute vertical heights of Z layers across the water column. This file is a csv file that has one column, with header Z. Each row has a decimal number that sets the absolute elevation of the layer face in the datum of the bathymetry. Decimal numbers must be monotonically decreasing from the second row. If this command is not issued then no layers will be assigned and the model will run in 2D.

! Z
Vertical Mesh Type == Z ! {Sigma} | Z
Layer Face File == ..\model\csv\LF_Z_001.csv        ! {No default} filepath
Cell 3D Depth == 0.5                                ! {0.1} Disable 3D momentum flux below this threshold (m)

If additional vertical resolution is required above the fixed Z layers then multiple sigma layers can be specified. These layers automatically fill the vertical distance between the uppermost Z layer face and surface water level, with an equal vertical distribution. This surface sigma layer distribution is not user specifiable.

! Z 
Vertical Mesh Type == Z                             ! {Sigma} | Z 
Layer Face File == ..\model\csv\LF_Z_001.csv        ! {No default} filepath
Surface Sigma Layers == 4                           ! {1} Number of sigma layers between uppermost Z layer and water surface level
Cell 3D Depth == 0.5                                ! {0.1} Disable 3D momentum flux below this threshold (m)

In some instances, the fixed Z layer heights may generate very shallow bottom layer cells when applied to bathymetric data. For example, a Z layer face specified at -10.6m against a bathymetric bed elevation of -10.61m will generate a bottom cell depth of 0.01m. This may cause computational difficulties, so can be overridden such that the cell depth is increased locally (by lowering bathymetry) to a user specified minimum.

! Z 
Vertical Mesh Type == Z                             ! {Sigma} | Z 
Layer Face File == ..\model\csv\LF_Z_001.csv        ! {No default} filepath
Surface Sigma Layers == 4                           ! {1} Number of sigma layers between uppermost Z layer and water surface level
Cell 3D Depth == 0.5                                ! {0.1} Disable 3D momentum flux below this threshold (m)

Example Z layer face file. Z elevations are aboslute elevation (mRL).

LF_Z_001.csv
Z
-0.5
-1.0
-2.0
-5.0
-10.0

6.7 Materials

6.7.1 Command Status

Optional - Additional material properties may be added to the 2D HD simulation class material definition.

6.7.2 Description

A subset of the commands described previously are also available for application on a material by material basis. This allows for spatial variation in the specification of some 3D related model parameters. These commands are issued and interpreted as described in Section 5.14.

6.7.2.1 Material Properties

The commands available for material based specification of 3D properties are presented in Table 6.7.

Table 6.7: Material Properties Commands

Command	Description
Vertical Eddy Viscosity Limits	Optional - Assigns material-specific vertical eddy viscosity limits. Overrides the Global Vertical Eddy Viscosity Limits command.

! Locally Increase vertical Eddy Viscosity
Material == 4                                       ! {0} Material ID
    Vertical Eddy Viscosity Limits == 1.0, 99999.   ! {Global value} Minimum eddy viscosity (m^2/s), {Global value} Maximum eddy viscosity (m^2/s)
End Material

6.8 Initial Conditions

6.8.1 Command Status

Optional - If no initial conditions are set then water level and initial velocites are set to zero. Where bathymetry is greater than 0.0 mRL then cells are set to be dry.

6.8.2 Description

This section describes initial condition construction specific to the 3D hydrodynamic simulation class. It is an extension of Section 5.15. Initial condition and restart commands adhere to the command layering approach described elsewhere.

Table 6.8: Initial Condition Model Implementations

Model Implementation	Description
Spatially Varying	Spatially varying initial conditions from input files.

Table 6.9: Initial Condition Commands

Command	Description
Initial Conditon 3D	Optional - Allows for user specified spatially varying water level and spatially and depth varying velocity initial conditions.

6.8.3 Spatially Varying

This initial condition implementation uses a csv file to specify initial water levels and velocities at specific 3D cells. It can be used for all 3D cells, or for specific local features to override prior specifications.

! Initial Conditions - Global initial water level with local initial water level and 3D velocity override
Initial Water Level == 2.5                              ! {0.0} Global initial condition
Initial Condition 3D == ..\model\csv\IC_ML_3D_001.csv   ! {No default} filepath

The CSV file requires the following columns.

Header: ID - 3D cell ID (not 2D cell ID)
Header: WL - Water level (mRL)
Header: U - U velocity (m/s)
Header: V - V velocity (m/s)

Initial conditions are applied only to the listed cell IDs. The file can include all 3D cell IDs or a subset of 3D cell IDs.

The example below shows an initial condition 3D file for a coastal lake using a subset of model cells.

IC_ML_3D_001.csv - This lake resides over 18 3D cells (6 2D cells x 3 layers deep)
ID, WL, U, V
69, 1.1, 0.00, 0.00
70, 1.1, 0.02, 0.01
71, 1.1, 0.03, 0.02
84, 1.1, 0.05, 0.03
85, 1.1, 0.06, 0.04
86, 1.1, 0.08, 0.05
87, 1.1, 0.09, 0.06
88, 1.1, 0.10, 0.08
89, 1.1, 0.12, 0.09
126, 1.1, 0.13, 0.10
127, 1.1, 0.15, 0.11
128, 1.1, 0.16, 0.12
135, 1.1, 0.18, 0.14
136, 1.1, 0.19, 0.15
137, 1.1, 0.21, 0.17
198, 1.1, 0.22, 0.18
199, 1.1, 0.24, 0.20
200, 1.1, 0.25, 0.21

6.9 Boundary Conditions

6.9.1 Command Status

Optional - 3D features can be optionally applied to the boundary implementations specifed during 2D HD model construction.

6.9.2 Description

This section describes boundary condition construction specific to the 3D hydrodynamic simulation class. The steps of implementation are not re-described here but the layout broadly parallels that of Section 5.16.

6.9.2.1 Boundary Model Implementations

Table 6.10 summarises the available implementations and provides example applications. The links in the Model Implementation column direct the reader to dedicated sections describing configuration options and TUFLOW FV syntax examples. This table is not the full list of boundary condition implementations available in TUFLOW FV. It is a sub-set relevant to the 3D HD simulation class. This is the parallel of Step 1 from Section 5.16.2.1.

Table 6.10: 3D HD Boundary Condition Model Implementations

Model Implementation	Description
Inflow/Outflow	Inflow or outflow boundary conditions. Used to include river and catchment inflows, outfalls or flow extractions.
Force	Force vector boundary conditions. For example to include the influence of a jet, propeller wash or used in combination with an inflow/outflow boundary to assign flow momentum.

6.9.2.2 Boundary Location Definition

Boundary locations are defined as per Step 2 in Section 5.16.2.2 and remain unchanged for the 3D HD Simulation Class other than for type GRID, which is described in Section 6.9.2.2.1.

6.9.2.2.1 Grid

Grid definition blocks define the location of gridded boundary condition types. These definitions establish an interpolation mapping from the grid to the computational mesh. Only coordinate definition using the Grid Definition File option is supported for 3D simulations.

The available grid definition commands for the 3D HD simulation class are the same as those presented in Table 5.34. Additional z coordinate attributes are required for use in the 3D Simulation Class.

! Grid Boundary Location Definition
Grid Definition File == ./LP_2001_005_10m_001.nc    ! {No default} Open grid definition block and reference NetCDF with grid coordinates
    Grid Definition Variables == x, y, z            ! {No default} x, y and z coordinate variable names within the specified NetCDF file
    Vertical Coordinate Type == depth               ! {Depth} |  Height | Elevation | Sigma
    Grid Definition Label == WWTP_discharge         ! {No default} User defined grid name
End Grid

6.9.2.3 Boundary Condition Block

Boundary locations are linked with associated data via boundary condition blocks, as described in Section 5.16.2.3. The commands available within each block are described in Table 5.35, with additional 3D specific commands provided in Table 6.11.

Table 6.11: Boundary Condition Commands

Command	Description
Vertical Distribution File	Optional - BC block command that sets the vertical distribution of the application of a 3D boundary condition.
Vertical Coordinate Type	Optional - Sets the vertical coordinate system for entries in the Vertical Distribution File. Defaults to Depth.
Sub-Type	Optional - BC block command that modifies the manner in which boundary conditons are applied in 3D. Defaults to 1.

6.9.3 Inflow/Outflow

These boundaries are typically applied to represent water exchange. The behaviours of these boundaries in 3D can be specified as follows.

Setting a vertical distribution across a column of cells (Section 6.9.3.1)
Setting the manner of interaction with boundary faces (Section 6.9.3.2)
Assigning fully three dimensional fields (Section 6.9.3.3)

6.9.3.1 Vertical Distribution

The specification of QC, QC_POLY, QCM and QG boundaries can include two additional paired commands to set the vertical distribution of the specified inflow. These commands are Vertical Coordinate Type and Vertical Distribution File. If no vertical distribution is specified the boundary is applied across the full water column.

The syntax block below demonstrates these commands using a QC boundary example. Example vertical distribution files are also provided for each vertical coordinate type. The same syntax applies to QC_POLY, QCM and QG.

! Point Boundary Location Definition
Read GIS SA == ..\model\gis\2d_sa_MyInflows_001_P.shp

! Catchment C2 Inflow
BC == QC, C2, ..\bc_dbase\M01_002.csv                           ! boundary_type, location_ID, data_filepath
    BC Header == time_hr, C2                                    ! {TIME}, {Q} (m^3/s or ft^3/s)
    Vertical Coordinate Type == Height                          ! {Depth} |  Height | Elevation | Sigma
    Vertical Distribution File == ..\bc_dbase\M01_002_VDist.csv ! {No default} data_filepath
End BC

The vertical distribution file contains two columns of data as follows.

Vertical coordinate, as per the specified type. Header: Height/Depth/Elevation/Sigma
Flow weighting at each vertical coordinate, as a number between 0 and 1. Weights are normalised and do not need to sum to a particular total value, Header: Weight

An example of a Height specification that delivers flow to the bottom two metres (to the nearest centimetre) of the water column follows.

HEIGHT,WEIGHT
0.00,1.0
2.00,1.0
2.01,0.0
2.10,0.0
99.0,0.0

An example of a Depth specification that delivers flow to the water column between 1 and 3 metres below the water surface (to the nearest centimetre) follows.

DEPTH,WEIGHT
0.00,0.0
0.99,0.0
1.00,1.0
3.00,1.0
3.01,0.0
99.0,0.0

An example of an Elevation specification that delivers flow to the water column between 10.5 and 11.5 metres absolute elevation (to the nearest centimetre) follows.

ELEVATION,WEIGHT
-99.0,0.0
10.49,0.0
10.50,1.0
11.50,1.0
11.51,0.0
99.00,0.0

An example of a Sigma specification that delivers flow to the middle 50 percent of the water column (to the nearest percent) follows.

SIGMA,WEIGHT
0.00,0.0
0.24,0.0
0.25,1.0
0.75,1.0
0.76,0.0
1.00,0.0

6.9.3.2 Boundary Face Interaction

The specification of a Q boundary can include an additional command to set the manner in which the flow interacts with the boundary faces. This is a sub-type command as follows.

Sub-Type == 2. Assigns a uniform flow distribution to the inflow and prevents 3D recirculation on the boundary. Momentum is not added directly to the computational domain
Sub-Type == 4. Assigns a depth^1.5 flow distribution to the inflow and prevents 3D recirculation on the boundary. Momentum is not added directly to the computational domain

Sub-Type == 1 and Sub-Type == 3 are not recommended for application of 3D Q boundaries.

! Polyline (Nodestring) Boundary Location Definition
Read GIS Nodestring == ..\model\gis\2d_ns_MyInflows_001_L.shp

! Inflow Boundary - River
BC == Q, Mary, ..\bc_dbase\M01_002.csv      ! boundary_type, location_ID, data_filepath
    BC Header == time_hr, MaryRiver         ! {TIME}, {Q} (m^3/s or ft^3/s)
    Sub-Type == 4                           ! {1} | 2 | 3 | 4 - Distribute nodestring flow as a function of cell water depth (h^1.5)
End BC

6.9.3.3 3D Flow Field

This is applied as per Section 5.16.4.4, but with the additional spatial coordinate (z).

! Grid Location Definition
Grid Definition File == example_diffuser.nc                     ! The NetCDF file containing coordinates used to define the grid to which gridded boundary conditions are applied
    Grid Definition Variables == longitude, latitude, Z         ! {No default} X coordinate variable, Y coordinate variable to be read from the NetCDF to create the grid map
    Grid Definition Label == diffuser_grid                      ! {No default} Grid name
    Gridmap Compression == 1                                    ! {0} Use the grid extent to mask the mesh update extent
End Grid

! Model Inflow From Outfall/Diffuser
BC == QC_GRID, diffuser_grid, example_diffuser.nc               ! boundary_type, location_ID, data_filepath
    BC Header == time, weight, flow                             ! {TIME}, {WEIGHT}, {Q} (m^3/s or ft^3/s)- NetCDF variable names
    BC Time Units == hours                                      ! The unit of time for the boundary condition ! {ISODATE | HOURS} | DAYS | MINUTES | SECONDS  -  Hours since the BC Reference Time (01/01/1990 00:00:00 or 0.0)
    BC Update dt == 300.0                                       ! {0} Update the boundary data every 300 seconds
End BC

6.9.4 Force

These boundaries apply an x and y component force vector to the model as introduced in Section 5.16.8. In 3D the boundary behaviour can also be configured with a vertical distribution (Section 6.9.4.1).

6.9.4.1 Vertical Distribution

The specification of FORCE and FORCE_POLY boundaries can include two additional paired commands to set the vertical distribution of the specified force. These commands are Vertical Coordinate Type and Vertical Distribution File. If no vertical distribution is specified then the boundary is applied across the entire water column.

! Point Boundary Location Definition
Read GIS SA == ..\model\gis\2d_sa_Pipe_Outlet_001_P.shp

! Force boundary - Add momentum flux to pipe outlet
BC == FORCE, Pipe_Outlet_001, ..\bc_dbase\Outlets_001.csv       ! boundary_type, location_ID, data_filepath
    BC Header == Time, Force_X, Force_Y                         ! {TIME}, {FORCEX} (N), {FORCEY} (N)
    Vertical Coordinate Type == Height                          ! {Depth} |  Height | Elevation | Sigma
    Vertical Distribution File == ..\bc_dbase\F01_002_VDist.csv ! data_filepath
End BC

6.10 Hydraulic Structures

6.10.1 Command Status

Optional - 3D features can be optionally applied to the structure implementations specifed during 2D HD model construction.

6.10.2 Description

TUFLOW FV supports a range of hydraulic structure connection types. These are described in Section 5.17.2.2. The behaviour of these connection types can be modified as part of a 3D HD simulation.

6.10.3 Structure Connection Types

Structure connections are defined using one of the methods described in Table 5.45. The behaviours of these connection types in 3D can be modified by setting a vertical distribution across a column of cells (Section 6.9.3.1)

6.10.3.1 Vertical Distribution

The flow of water through 3D connection types can be controlled by specifying Vertical Coordinate Type and Vertical Distribution File. The commands and syntax for doing so are the same as that described in Section 6.9.3.1. An example syntax block for a linked nodestring structure connection with a vertical flow specification follows.

! Structure block – user defined timeseries
! or Linked Nodestrings
Structure == Linked Nodestrings, [location_ID_US], [location_ID_DS]
    Flux Function == Timeseries                                 ! User specified flow time series
    Flux File == ..\model\csv\flow_timeseries.csv               ! Time, Q time series
    Vertical Coordinate Type == Height                          ! {Elevation} |Depth | Height | Sigma
    Vertical Distribution File == ..\bc_dbase\S01_023_VDist.csv ! data_filepath
End Structure

6.11 Model Outputs

6.11.1 Command Status

Optional - 3D features can be optionally added to the model output implementations specifed during 2D HD model construction.

6.11.2 Description

This section describes model output features specific to the 3D hydrodynamic simulation class. It is an extension of 2D HD model outputs (see Section 5.18).

6.11.2.1 Output Model Implementations

The output model implementations for the 3D HD simulation class are the same as those in Table 5.73, with additional implementations for 3D presented in Table 6.12. Each 3D output type is described with configuration examples in the following sub-sections.

Table 6.12: Output Model Implementations

Ouptut Type	Description
Profile	3D vertical profile output defined at discrete point locations.

6.11.2.2 Output Block

The available 3D HD simulation class output block commands extend those in Table 5.75 and are presented in Table 6.13.

Table 6.13: Output Block Commands

Command	Description
Vertical Averaging	Optional - Defines the vertical coordinate type and range over which 3D results are averaged to produce point or 2D mesh outputs.

6.11.2.2.1 Output Parameters

Output parameters for the 3D HD Simulation Class extend those presented in Table 5.76 and are listed in Table 6.14. User specified output parameters are only required for points, profiles and mesh output types. All other output types report automatically configured output parameters.

Table 6.14: Output Parameters - 3D HD Simulation Class

Ouptut Parameter	Description	Units
W	Vertical velocity.	m/s
TURBZ_TKE	Turbulent kinetic energy.	m²/s²
TURBZ_EPS	Dissipation rate of turbulent kinetic energy.	m²/s³
TURBZ_L	Turbulence length scale.	m
TURBZ_SPFSQ	Shear frequency squared (S^2).	1/s²
TURBZ_BVFSQ	Brunt-Vaisala frequency squared (N^2).	1/s²
TURBZ_NUM	Eddy viscosity.	m²/s
TURBZ_NUH	Thermal diffusivity.	m²/s
TURBZ_NUS	Scalar diffusivity.	m²/s
TURBZ	Outputs all turbulence parameters mentioned above.	Mixed (uses each variable’s native units)

6.11.3 Mesh

Mesh outputs are described in Section 5.18.3 and apply equally to the 3D HD Simulation Class. An additional command can be used to specify how 3D results are depth averaged to provide 2D output, where required, for NetCDF, XMDF and datv output types.

As summarised in Table 6.15, NetCDF is the only output type that natively supports fully 3D output and is therefore the recommended 3D mesh output format. XMDF and datv support 2D output only and therefore require depth averaging.

If no depth averaging method is specified the following defaults apply.

NetCDF writes fully 3D results
XMDF and datv write results averaged over the full water depth

Table 6.15: Mesh Output Format - 2D and 3D Compatiblity Matrix

Output Format	2D	3D
NetCDF	Yes	Yes
XMDF	Yes	No
Datv	Yes	No

The available depth averaging method options are listed in Table 6.16. Examples of each depth averaging method are provided below and apply to all mesh output types (NetCDF, XMDF and datv).

Table 6.16: Depth Averaging Methods - 3D HD Simulation Class

Vertical Averaging Method	Description
depth-all	Averaged over the entire depth.
depth-range	Averaged over the vertical distance between two specified depths measured positive down from the water surface (zero).
height-range	Averaged over the vertical distance between two specified heights measured positive up from the bed (zero).
elevation-range	Averaged over the vertical distance between two specified absolute elevations measured positive up from the model datum.
sigma-range	Averaged over the vertical distance between two specified proportions (0.0 to 1.0) of the water depth measured positive up from the bed (0.0) to the water surface (1.0).
layer-range-top	Averaged over the vertical distance spanned by two specified layers inclusive. Layer 1 is the top layer and layer number increases positive down. If the same layer is specified only that layer is output.
layer-range-bot	Averaged over the vertical distance spanned by two specified layers inclusive. Layer 1 is the bottom layer and layer number increases positive up. If the same layer is specified only that layer is output.

Example averaging over the full water column.

! Depth-All
Output == [mesh_output_format]                        ! NetCDF, XMDF or datv
    Output Parameters == h, v, w                      ! Water level (mRL), velocity (m/s), vertical velocity (m/s)
    Output Interval == 900.                           ! {0.0} (s)
    Vertical Averaging == Depth-All                   ! {Depth-All} | Depth-Range | Height-Range | Elevation-Range | Sigma-Range | Layer-Range-Top | Layer-Range-Bot, {0.0} Depth 1 (m), {99999.} Depth 2 (m)
End Output

Example averaging over the top 2.5 metres of the water column.

! Depth-Range
Output == [mesh_output_format]                        ! NetCDF, XMDF or datv
    Output Parameters == h, v, w                      ! Water level (mRL), velocity (m/s), vertical velocity (m/s)
    Output Interval == 900.                           ! {0.0} (s)
    Vertical Averaging == Depth-Range, 0, 2.5         ! {Depth-All} | Depth-Range | Height-Range | Elevation-Range | Sigma-Range | Layer-Range-Top | Layer-Range-Bot, {0.0} Depth 1 (m), {99999.} Depth 2 (m)
End Output

Example averaging from 1 m to 4.5 m above the bed.

! Height-Range
Output == [mesh_output_format]                        ! NetCDF, XMDF or datv
    Output Parameters == h, v, w                      ! Water level (mRL), velocity (m/s), vertical velocity (m/s)
    Output Interval == 900.                           ! {0.0} (s)
    Vertical Averaging == Height-Range, 1.0, 4.5      ! {Depth-All} | Depth-Range | Height-Range | Elevation-Range | Sigma-Range | Layer-Range-Top | Layer-Range-Bot, {0.0} Height 1 (m), {99999.} Height 2 (m)
End Output

Example averaging between absolute elevations 25.5 m and 30.0 m in the model datum.

! Elevation-Range
Output == [mesh_output_format]                        ! NetCDF, XMDF or datv
    Output Parameters == h, v, w                      ! Water level (mRL), velocity (m/s), vertical velocity (m/s)
    Output Interval == 900.                           ! {0.0} (s)
    Vertical Averaging == Elevation-Range, 25.5, 30.0 ! {Depth-All} | Depth-Range | Height-Range | Elevation-Range | Sigma-Range | Layer-Range-Top | Layer-Range-Bot, {0.0} Elevation 1 (mRL), {99999.} Elevation 2 (mRL)
End Output

Example averaging over the middle 50% of the water column.

! Sigma-Range
Output == [mesh_output_format]                        ! NetCDF, XMDF or datv
    Output Parameters == h, v, w                      ! Water level (mRL), velocity (m/s), vertical velocity (m/s)
    Output Interval == 900.                           ! {0.0} (s)
    Vertical Averaging == Sigma-Range, 0.25, 0.75     ! {Depth-All} | Depth-Range | Height-Range | Elevation-Range | Sigma-Range | Layer-Range-Top | Layer-Range-Bot, {0.0} Sigma 1 (0-1), {99999.} Sigma 2 (0-1)
End Output

Example averaging over layers 2 to 5 from the surface downward inclusive.

! Layer-Range-Top
Output == [mesh_output_format]                        ! NetCDF, XMDF or datv
    Output Parameters == h, v, w                      ! Water level (mRL), velocity (m/s), vertical velocity (m/s)
    Output Interval == 900.                           ! {0.0} (s)
    Vertical Averaging == Layer-Range-Top, 2, 5       ! {Depth-All} | Depth-Range | Height-Range | Elevation-Range | Sigma-Range | Layer-Range-Top | Layer-Range-Bot, {0.0} Layer 1, {99999.} Layer 2
End Output

Example averaging over layers 2 to 4 from the bottom upward inclusive.

! Layer-Range-Bot
Output == [mesh_output_format]                        ! NetCDF, XMDF or datv
    Output Parameters == h, v, w                      ! Water level (mRL), velocity (m/s), vertical velocity (m/s)
    Output Interval == 900.                           ! {0.0} (s)
    Vertical Averaging == Layer-Range-Bot, 2, 4       ! {Depth-All} | Depth-Range | Height-Range | Elevation-Range | Sigma-Range | Layer-Range-Top | Layer-Range-Bot, {0.0} Layer 1, {99999.} Layer 2
End Output

6.11.4 Point

Point outputs are described in Section 5.18.4 and apply equally to the 3D HD Simulation Class. An additional command may be issued to specify how 3D results are depth averaged to provide 2D output, if required. These commands are the same as described in Section 6.11.3. An example output is shown below, where averaging is over the second to fifth layers from the bed. If no vertical averaging is specified then depth-all is applied.

For a given point location the vert_min and vert_max attributes will override the default vertical averaging limits (0,99999.) or those specified via the Vertical Averaging command.

! ADCP Calibration Points
Output == Points                                        ! CSV timeseries at each output point
    Read GIS PO == ..\model\gis\3d_po_ACDPs_001_P.shp   ! Point locations
    Output Parameters == h, d, v                        ! Water level (mRL or ft), depth (m or ft), velocity (m/s of ft/s)
    Output Interval == 900.                             ! {0.0} (s)
    Vertical Averaging == Layer-Range-Bot, 2, 5         ! {Depth-All} | Depth-Range | Height-Range | Elevation-Range | Sigma-Range | Layer-Range-Top | Layer-Range-Bot, {0.0} Layer 1, {99999.} Layer 2
End Output

6.11.5 Profile

Profile outputs are specified in the same manner to point outputs, except profile outputs include depth information (so do not require depth averaging specification) and are written in NetCDF format. A points layer that locates the profiles is required within the output block. An example output block is shown below. Vertical averaging is not required for profile outputs as the output is inherently 3D.

! ADCP Calibration Points
Output == Profile,                                      ! CSV timeseries at each output point
    Read GIS PO == ..\model\gis\3d_po_ACDPs_001_P.shp   ! Point locations
    Output Parameters == v, w                           ! Velocity (m/s), Vertical velocity (m/s)
    Output Interval == 900.                             ! {0.0} (s)
    Suffix == MendsSt                                   ! {No default}
End Output