9.4 Data Input

9.4.1 Simulation Control File

9.4.1.1 TUFLOW AD Control File (.adcf File)

The TUFLOW AD Control File or .adcf file points to the two mandatory files required for AD model execution. It is the top of the tree for the AD model and is called into the .tcf by the AD Control File command. The .adcf file must reference:

One global database file, using the AD Global Database command. For example,
AD GLOBAL DATABASE == ..\bc_dbase\2d_ad_globaldatabase_Demo1.csv
One boundary database file, using the AD BC Database command. For example,
AD BC DATABASE == ..\bc_dbase\2d_ad_dbase_Demo1.csv

Appendix J lists and describes these commands and their parameters. No other commands are required in the adcf file.

9.4.1.2 GIS Input File Types and Naming Conventions

Spatial variation in initial condition and minimum dispersion coefficient is an optional data entry that can be used. If adding this feature to your model, it is recommended that the prefixes described in Table 9.1 be adhered to for 2D GIS layers. This greatly enhances the data management efficiency and importantly makes it much easier for another modeller or reviewer to quickly interpret the model. This approach is also consistent with that of TUFLOW.

Table 9.1: GIS Input Data Layers and Recommended Prefixes
2D Domain GIS Layers	Suggested File Prefix	Description	Section
2D AD Initial Conditions	2d_ad_ic_	Layer containing polygons defining the spatial distribution of initial conditions for a given constituent. Optional.	Section 9.4.5
2D AD Minimum Dispersion Coefficient	2d_ad_md_	Layer containing polygons defining the spatial distribution of minimum dispersion coefficients (\(D_w\)) for a given constituent. Optional.	Section 9.4.7

9.4.2 1D Geometries

TUFLOW AD does not require any further 1D data in addition to the features already included in the TUFLOW hydraulic model.

9.4.3 Specification of Constituent Properties

Constituent properties are specified in the Global Database file, which is identified in the .adcf file using the AD Global Database command. This database file has a set structure, in much the same way as TUFLOW boundary database files, and can be created in software such as Microsoft Excel. The number of constituents simulated by TUFLOW AD is simply the number of line entries in this file (excepting the header data). Constituents can be removed from the simulation by prefacing rows in the global database file with the ‘!’ or ‘#’ character. The maximum number of constituents TUFLOW AD can simulate is 20.

The global database file must be .csv (comma delimited) formatted. The first row must contain the predefined keywords (in order) as listed in Table 9.2, separated by commas. Subsequent rows contain constituent data.

Models using an AD global database file are provided in the Advection Dispersion Example Model Dataset on the TUFOW Wiki.

Table 9.2: Global Database Keyword Descriptions
Keyword	Description
Name	The name of a constituent. This might be ‘TN’ or ‘Salinity’ (without the inverted commas). The Name field is limited to 40 characters and must be alphanumeric characters only. Mandatory.
Heat Name	Not currently used. Leave blank.
Decay Rate	The decay rate (k) of the constituent in units of day^-1. This value is used in a first order decay calculations at each timestep, i.e. \(C(t) = C_{0}e^{-kt}\) Where: \(\cdot\) \(C(t)\) is constituent concentration at time \(t\) \(\cdot\) \(C_{0}\) is a reference concentration \(\cdot\) \(k\) is the decay rate specified here; and \(\cdot\) \(t\) is time If no decay is required, then either enter 0 or leave the field blank.
Settling Rate	The settling rate of the constituent in units of m.day^-1. This value is used in a simple mass balance calculation that removes the constituent from the water column based on this rate. If no settling is required, then either enter 0 or leave the field blank.
Longitudinal Dispersion Coefficient	The value \(K_{L}\) for the constituent, as per Equation (9.5) for TUFLOW Classic and Equation (9.9) for TUFLOW HPC. Allowing such variation between constituents permits simultaneous simulation of multiple constituents with varying dispersion properties. This is useful at the model calibration stage when a range of dispersion coefficients can be tested within one simulation to ascertain the best match to monitoring data. This feature can also be used in sensitivity testing. Notwithstanding this, this value should not be varied from constituent to constituent once the AD model is calibrated. If the field is blank or set to zero, then longitudinal dispersion is switched off.
Transverse Dispersion Coefficient	The value \(K_{T}\) for the constituent, as per Equation (9.6) for TUFLOW Classic and Equation (9.9) for TUFLOW HPC. Allowing such variation can be exploited in the same manner as described above for longitudinal dispersion. This value should not be varied from constituent to constituent once the AD model is calibrated. If the field is blank or set to zero, then transverse dispersion is switched off.
Initial Condition	This can be set to either a single number or a path reference to a GIS layer (2d_ad_ic_). If the former is specified, then that value is applied uniformly to all wet cells at initialisation. If a path to a GIS layer is specified, then the layer must comprise of (only) polygons with a single attribute. The attribute must be of type Float. The field name is not used by TUFLOW AD, so can be set to a label that is meaningful to the user. The polygon data, with spatially varying attributes of initial concentration is applied to wet cells at simulation initiation. Wet cells not covered by any polygon in the specified GIS layer are set to a concentration of zero. If the field is left blank, then a concentration of zero is applied to all cells.
Minimum	Not currently used. Leave blank.
Maximum	Not currently used. Leave blank.
Minimum Dispersion	This sets the value of \(D_{w}\) as per Equations (9.5) and (9.6) for TUFLOW Classic and Equation (9.12) for TUFLOW HPC. It can be set to either a single number or a path reference to a GIS layer. If the former is specified, then that value is applied uniformly to all wet cells at each timestep. If a path to a GIS layer is specified, then the layer must comprise of (only) polygons with a single attribute. The attribute must be of type Float. The field name is not used by TUFLOW AD, so can be set to a label that is meaningful to the user. The polygon data, with spatially varying values of \(D_{w}\) is applied to wet cells at each timestep. Wet cells not covered by any polygon in the specified GIS layer will have \(D_{w}\) set to zero. This field cannot be left blank. If a minimum dispersion of zero is required, then 0.0 must be entered in this field. Errors will result if this field is left blank.

9.4.4 Boundary Conditions

TUFLOW AD uses the same approach as TUFLOW to setting up boundary conditions, in that two types of files are required:

Boundary condition database; and
Boundary condition data files (i.e. timeseries).

Like TUFLOW, TUFLOW AD also uses a comma delimited format for both these file types.

TUFLOW AD does not require specification of any geographical information regarding the location of boundary conditions. All such required data is passed from TUFLOW to TUFLOW AD for TUFLOW boundary types HT, QT, HS, HQ, QC, VC, VT, and SA.

9.4.4.1 Boundary Condition (BC) Database

A boundary condition (BC) database is created using spreadsheet software, such as Microsoft Excel. It must be .csv (comma delimited) formatted and is identified in the .adcf file (see AD BC Database). The database contains a list of files and attribute names to search for within those files. The attribute names are then used to extract the desired boundary condition data.

The TUFLOW AD BC Database is structured in the same way as a standard TUFLOW BC Database, in that it must contain a header line with subsequent rows of information. The header line must contain the following keywords, in the below order, with meanings as per Table 9.3.

“Name, Source, Column 1, Column 2, Add Col 1, Mult Col 2, Add Col 2, Column 3, Column 4”

Table 9.3: AD BC Database Keyword Descriptions
Keyword	Description
Name	The name of a BC data set. It consists of two concatenated elements as follows: First: This must be the same ‘Name’ attribute used in the GIS 2d_bc layer(s) specified in TUFLOW. This is third attribute in the 2d_bc layer and follows ‘Type’ and ‘Flags’. It may contain spaces, but must not contain commas. It is not case sensitive. Second: This must be the name of the appropriate constituent for which the boundary condition is being specified. This name must be one of those specified in the AD Global Database ‘Name’ field. These two names are joined by a double underscore. As such, if there are “M” 2d_bc boundary condition objects specified in TUFLOW, and “N” constituents to be simulated by TUFLOW AD, then M*N entries are required in the AD BC Database. An example is Ocean__Salinity, where the TUFLOW 2d_bc file has a line with Name attribute “Ocean” and the AD Global Database has a variable called “Salinity” listed. Mandatory.
Source	The file from which to extract the BC data. It must be a .csv file. Paths are relative to the AD Global Database. Mandatory.
Column 1	The name of the first column of data (time values) in the .csv Source File. Mandatory.
Column 2	The name of the column of data in the .csv Source File. Values in this column are always concentrations, for all allowable BC sets. These are applied to cells corresponding to the appropriate locations of all types of BCs specified in TUFLOW 2d_bc GIS layers. These specified concentrations override any other computed concentrations at the boundary locations. The exception to the above is for SA boundaries, where the specified concentration is multiplied by the inflow corresponding to that concentration (as passed to TUFLOW AD from TUFLOW) and the mass load over the SA polygon computed. This mass load is then added to the mass of constituent within the wet computational cells within the SA polygon, and mass conservation used to compute a new resultant ambient concentration. Mandatory.
Add Col 1	Not used. Leave Blank.
Mult Col 2	Not used. Leave Blank.
Add Col 2	Not used. Leave Blank.
Column 3	Not used. Leave Blank.
Column 4	Not used. Leave Blank.

9.4.4.2 BC Database Example

The Excel spreadsheet below illustrates a simple example of a TUFLOW AD BC Database, created in a Microsoft Excel worksheet that is exported as a .csv file for use by TUFLOW AD. Four line boundaries have been specified via GIS in the TUFLOW model (with Name fields “West”, “North”, “East” and “South”) and two constituents have been specified in the AD Global Database (with Name fields “Tracer_01” and “Tracer_02”). Four boundaries and two constituents thus require eight entries in the TUFLOW AD BC Database file.

The Demo1_Concs.csv file was created by saving the below as a .csv file from Excel. All values are concentrations in mg/L, with the exception of the Time column, which has units of hours.

9.4.5 Initial Conditions

Initial conditions are specified for each constituent as either a constant value or spatially varied value (see Table 9.2). The former is simply entered as a decimal (or integer) in the Initial Condition field of the AD Global Database. This value is applied to all wet cells at model initiation. The latter is applied by entering a relative (or absolute) file path to a GIS layer in the Initial Condition field of the AD Global Database. The GIS file has the attributes described in Table 9.4.

Table 9.4: 2D Initial Conditions (2d_ad_ic) Attribute Descriptions
GIS Attribute	Description	Type
Conc	The initial condition concentration.	Float

As many polygons as needed can be included in this layer. Any wet cells not covered by these polygons will be initialised to a concentration of zero. The naming convention prefix for this layer is 2d_ad_ic_. The objects must be polygons. Rectangles, round rectangles etc. are not supported by TUFLOW. The attribute name is not read by TUFLOW AD and can be anything meaningful to the user - “Conc” is used as an example above for clarity.

9.4.6 Groundwater Initial Conditions

Initial concentrations can be set within groundwater layers using the following .tgc commands:

[Set | Read GIS | Read Grid] IGW Conc Layer N1,N2,..N Tracer M1,M2,..M == [value | /path/to/file]

Where:

N = The groundwater layer number (reference multiple in a single command)
M = The tracer number (reference multiple in a single command), as ordered in the AD Global Database

If a layer number is not referenced, it is assumed to apply to layer 1. Likewise, if a tracer number is not referenced it is assumed to apply to the first tracer. Note, the order that ‘Layer’ and ‘Tracer’ appear in the command does not matter (i.e. tracer numbers could be listed before layer numbers).

9.4.7 Minimum Dispersion Coefficient

Minimum dispersion coefficients are specified for each constituent as either a constant value or spatially varied value (see Table 9.2). The former is simply entered as a decimal (or integer) in the Minimum Dispersion field of the AD Global Database. This value is applied to all wet cells at all timesteps. The latter is applied by entering a relative (or absolute) file path to a GIS layer in the Minimum Dispersion field of the AD Global Database. The GIS file has the attributes described in Table 9.5.

Table 9.5: 2D Minimum Dispersion Coefficient (2d_ad_md) Attribute Descriptions
GIS Attribute	Description	Type
Conc	The initial condition concentration.	Float

As many polygons as needed can be included in this layer. Any wet cells not covered by these polygons will be assigned a minimum dispersion coefficient of zero. The naming convention prefix for this layer is 2d_ad_md_. The objects must be polygons. Rectangles, round rectangles etc. are not supported by TUFLOW. The attribute name is not read by TUFLOW AD and can be anything meaningful to the user - “MD” is used as an example above for clarity.