7.11 Boundary Conditions

7.11.1 Command Status

Required.

7.11.2 Description

This section describes how boundary conditions are configured within the 2D AD simulation class. It extends Section 5.16.2 and describes the available advection dispersion boundary model implementations as well as the structure and configuration of boundary condition blocks used to assign AD input data. TUFLOW FV syntax examples are provided for each boundary type.

Boundary conditions in TUFLOW FV are assigned using the same workflow described in Section 5.16.2. AD commands related to each step of this workflow are described in the following subsections.

Each boundary condition requires specification of salinity, temperature and tracer concentration where simulated. The corresponding specification method for each boundary condition type described in Section 5.16 is provided following. For clarity, boundary conditions that share common advection dispersion specification methods are grouped.

7.11.2.1 Step 1: Boundary Model Implementations

This is Step 1 of 3 in the boundary condition workflow described in Section 5.16.2. This step identifies the appropriate boundary model implementation based on the physical processes being represented, with specific emphasis on advection dispersion boundary condition configuration.

Table 7.23 summarises the boundary condition implementations available for advection dispersion and provides example applications. This table extends the classifications presented in Table 5.30, which outlines boundary types used in 2D HD simulations and introduces additional boundary conditions relevant only to the advection dispersion simulation class.

Links in the Model Implementation column provide direct access to sections describing configuration options, modelling considerations and TUFLOW FV syntax examples for each boundary type.

Table 7.23: Boundary Condition Model Class - Model Implementations
Model Implementation Description
Water Level Water level boundary conditions. Typically used to represent concentration boundaries in coastal and estuarine or downstream tailwater conditions in river simulations.
Inflow/Outflow Inflow or outflow boundary conditions. Used to include river and catchment inflow concentrations, outfalls or flow extractions.
Stage Discharge User specified or automatic relationship between water level and flow, with associated concentrations. Used to represent tailwater conditions in riverine models.
Ocean Circulation Model Fully specified boundary conditions derived from global ocean circulation models such as HYCOM or BRAN. Used to force ocean currents, salinity and temperature fields at open boundary conditions in coastal models.
Mass Flux Direct mass input/output boundaries. For example to add salt mass associated with brine discharge.
Scalar Concentration Boundary conditions that set the value of scalar variables such as temperature, salinity, suspended sediment, tracers, and water quality constituents. Thes can be applied as external or internal boundaries.
Transport File File with hydrodynamic information from a previous simulation. The file is used to run a subsequent simulation using a sub-set of hydrodynamic calculations, allowing the model to run more efficiently. Typically used for testing scenarios where the hydrodynamics do not change (tracer analysis for example).

7.11.2.2 Step 2: Boundary Location Definition

This is Step 2 of 3 in the boundary condition workflow described in Section 5.16.2. No further updates to boundary location definitions are required for the AD simulation class, with the exception of an additional grid definition block command for the OBC_GRID boundary type. Any other additional boundaries that are advection dispersion only use spatial techniques already described in Section 5.16.2.2.

7.11.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.

If using an OBC_GRID boundary type the Boundary Gridmap command is required in the grid definition block. This additional command is described in Table 7.24.

Table 7.24: Additional AD Simulation Class Grid Definition Block Command
Command Description
Boundary Gridmap Conditional - Required when using OBC_GRID boundary type. Required for the OBC_CURT boundary condition type. Calculates interpolation weightings from the grid onto the boundary nodestrings.
NA NA

7.11.2.3 Step 3: Boundary Condition Block

This is Step 3 of 3 in the boundary condition workflow described in Section 5.16.2. As presented for the 2D HD simulation class, in this step the selected boundary model implementation and boundary location are linked to input data using a boundary condition block (BC block). In general, advection dispersion boundary conditions extend those of hydrodynamics and use the same or similar structure presented in Section 5.16.2.3.

! Conceptual boundary condition block form
BC == boundary_type, location_ID, data_filepath

  …BC_block_commands…

End BC

Where:

  • BC == indicates the start of a boundary condition block
  • boundary_type is a character flag setting the boundary condition type (e.g. Q, WL, QC_GRID)
  • location_ID is a reference to the boundary location. For example the name of a polyline, point, polygon, grid, or via directly specified coordinates within the data set by the data_filepath
  • data_filepath is the file containing the boundary data, which is typically a time series file in CSV or NetCDF format
  • BC_block_commands are any commands that reside within a boundary block. BC block commands provide configuration settings for the boundary including which data to select, whether any scaling or offset values are applied and how to handle missing data
  • End BC closes the boundary condition block

Additional AD boundary condition block commands are summarised in Table 7.25.

Table 7.25: Additional AD Boundary Condition Block Commands
Command Description
BC Nodestrings Conditional - Required when using the OBC_GRID boundary type. Required with the OBC_GRID boundary condition.
Trace Header Conditional - Required if modelling tracers. Maps tracer input headers in the boundary data file to simulated tracer fields. Not required if no tracers are modelled.
Trace Scale Optional - Applies multiplicative scale factors to tracer boundary inputs.
Trace Offset Optional - Applies additive offsets to tracer boundary inputs after scaling.
Trace Default Optional - Sets fallback tracer boundary values when specified tracer headers are not found.

7.11.2.4 Input Data For Boundary Conditions

The input data methods for advection dispersion are the same as those presented in Section 5.16.2.4.

7.11.2.4.1 BC Header, BC Scale, BC Offset and BC Default

For salinity and temperature, setting boundary conditions is achieved by appending comma separated values to the commands within boundary condition blocks already described in Section 5.16.2.4. The commands are as follows.

BC Header ==

BC Scale ==

BC Offset ==

BC Default ==

As previously described, these commands map CSV columns by header names not fixed column positions.
The BC Header command defines that mapping, so file column order is not important.

  • Simulating salinity only: (previous hydrodynamic boundaries), salinity
  • Simulating temperature only: (previous hydrodynamic boundaries), temperature
  • Simulating both salinity and temperature: (previous hydrodynamic boundaries), salinity, temperature

To demonstrate this concept, the Q boundary type is used as an example where the previous headers are ‘Time_UTC’ and ‘Inflow_m3s’.

! BC Header example for salinity only
BC Header == Time_UTC, Inflow_m3s, SAL_psu ! (previous hydrodynamic boundaries), salinity

! BC Header example for temperature only
BC Header == Time_UTC, Inflow_m3s, T_Cdeg ! (previous hydrodynamic boundaries), temperature

! BC Header example for both salinity and temperature
BC Header == Time_UTC, Inflow_m3s, SAL_psu, T_Cdeg ! (previous hydrodynamic boundaries), salinity, temperature

The header mapping is completed by TUFLOW FV. For example if the CSV has SAL_psu in column 6 and T_Cdeg in column 2 as shown below.

BC Header == (previous hydrodynamic boundaries), SAL_psu, T_Cdeg

Then TUFLOW FV reads: - SAL_psu as salinity, and - T_Cdeg as temperature.

The example CSV below includes extra columns and a non-sequential field order to show that only the header list controls mapping.

Estuary_Inflow_BC_001.csv
Time_UTC, SAL_psu, Inflow_m3s, silt_mgL, clay_mgL, T_Cdeg, finesand_mgL
23/06/2024 00:00:00, 18.7, 14.2, 4.8, 22.5, 14.1, 1.9
23/06/2024 01:00:00, 12.8, 12.8, 5.2, 24.0, 14.6, 2.1
23/06/2024 02:00:00, 14.8, 11.4, 5.6, 25.4, 15.2, 2.4
23/06/2024 03:00:00, 13.1, 10.5, 6.0, 26.8, 15.9, 2.8
23/06/2024 04:00:00, 11.4, 19.7, 6.5, 28.3, 16.4, 3.2

The same ordering applies to BC Scale, BC Offset and BC Default, where these act on the data in the CSV file as follows.

  • BC Scale applies a single scale factor to the CSV data. This is useful for unit conversion.
  • BC Offset applies a single offset (additive or subtractive) amount to the CSV data. This is useful for converting units such as degrees Kelvin to degrees Celsius.
  • If both BC Scale and BC Offset are issued then a y = mx + b relationship is applied as (Applied Boundary) = (BC Scale) * (CSV data) + (BC Offset).
  • BC Default applies the value to the quantity boundary condition if the corresponding column header cannot be found in the CSV data file. This is useful for setting a single constant value on a boundary condition without changing the underlying CSV data file.
7.11.2.4.2 Trace Header, Trace Scale, Trace Offset and Trace Default

The specification of tracer boundary condition data is a direct extension of the above. Specifically, an additional and parallel suite of commands within a BC block are issued as follows.

Trace Header ==

Trace Scale ==

Trace Offset ==

Trace Default ==

The same ordering rules apply as BC Header etc., with the key difference that trace mappings are tracer-only. There is no time or hydrodynamic information in these commands, only tracer entries. For a simulation with NTracer == N list those N tracer headers in the command in order from tracer 1 to tracer N.

  • One tracer: tracer_1
  • Two tracers: tracer_1, tracer_2
  • Three tracers: tracer_1, tracer_2, tracer_3

For example, a simulation of three tracers where TR1_mgL is tracer 1, T_2 is tracer 2 and Tracer_green is tracer 3 requires:

! Trace Header for three tracers
Trace Header == TR1_mgL, T_2, Tracer_green ! {TRACE_1} Tracer 1 header, {TRACE_2} Tracer 2 header, {TRACE_3} Tracer 3 header

These associated commands apply to the same tracer order:

! Trace Scale for three tracers
Trace Scale == 1.0, 2.0, 5.5 ! {1.0} Tracer 1 scale, {1.0} Tracer 2 scale, {1.0} Tracer 3 scale

! Trace Offset for three tracers
Trace Offset == 0.0, 0.2, -0.5 ! {0.0} Tracer 1 offset, {0.0} Tracer 2 offset, {0.0} Tracer 3 offset

! Trace Default for three tracers
Trace Default == 100.0, 200.0, 11.0 ! {NaN} Tracer 1 default, {NaN} Tracer 2 default, {NaN} Tracer 3 default

7.11.3 Water Level

These boundaries (WL, WLS and WL_CURT) are typically, although not exclusively, applied to represent open tidal boundaries (oceanic or estuarine) where dissolved constituent or suspended sediment exchange occurs. They may also be set to zero for tracers when performing flushing (e-folding) style analyses.

The corresponding specification of the advection dispersion tracer components is a direct extension of the water level boundary blocks already established for a 2DHD simulation. The following example illustrates a WL boundary configuration for a simulation that includes salinity, temperature and one tracer. The boundary condition blocks for WLS and WLS_CURT follow the same structure, differing only in the initial BC == specifier.

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

! Water Level
BC == WL, Ocean, ..\bc_dbase\Tide_20230101_20240101.csv ! boundary_type, location_ID, data_filepath
  BC Header == Time_UTC, Tide_mMSL, Sali, Temperature ! {TIME}, {WL} (mRL or ftRL), {SAL} (psu), {TEMP} (C)
  BC Scale == 1.0, 1.0, 1.1 ! {1.0} WL scale, {1.0} Salinity scale, {1.0} Temperature scale
  BC Offset == 0.25, 0.0, 0.0 ! {0.0} WL offset, {0.0} Salinity offset, {0.0} Temperature offset
  BC Default == 0.0, 35.0, 20.0 ! {NaN} WL default, {NaN} Salinity default, {NaN} Temperature default
  Trace Header == TC1 ! {TRACE_1} (g/m^3)
  Trace Scale == 2.3 ! {1.0} Tracer 1 scale
  Trace Offset == 0.0 ! {0.0} Tracer 1 offset
  Trace Default == 100.0 ! {NaN} Tracer 1 default (g/m^3)
End BC

7.11.4 Inflow/Outflow

These boundaries (Q, QC QC_POLY, QC_GRID, QCM and QG) are typically, although not exclusively, applied to represent dissolved constituent or suspended sediment exchange. Only Q boundaries apply momentum flux.

The corresponding specification of the advection dispersion tracer components is a direct extension of the flow boundary blocks already established for a 2DHD simulation. The following example illustrates a Q boundary configuration for a simulation that includes salinity, temperature and one tracer. The boundary condition blocks for the other flow boundaries follow the same structure, differing only in the initial BC == specifier.

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

! Inflow
BC == Q, Creek1, ..\bc_dbase\Flow_20230101_20240101.csv ! boundary_type, location_ID, data_filepath
  BC Header == Time_UTC, Flow_Q, Sali, Temperature ! {TIME}, {Q} (m^3/s), {SAL} (psu), {TEMP} (C)
  BC Scale == 1.0, 1.0, 1.1 ! {1.0} Q scale, {1.0} Salinity scale, {1.1} Temperature scale
  BC Offset == 0.25, 0.0, 0.0 ! {0.0} Q offset, {0.0} Salinity offset, {0.0} Temperature offset
  BC Default == 10.0, 35.0, 20.0 ! {NaN} Q default, {NaN} Salinity default, {NaN} Temperature default
  Trace Header == TC23 ! {TRACE_1} Tracer 1 header
  Trace Scale == 2.3 ! {1.0} Tracer 1 scale
  Trace Offset == 0.0 ! {0.0} Tracer 1 offset
  Trace Default == 100.0 ! {NaN} Tracer 1 default
End BC

7.11.4.1 Outflow Scalar Concentration Handling

Outflow scalar concentration handling differs by boundary type. For Q boundaries outflow concentration is taken from the adjacent internal cell using a fixed zero gradient approach. For QC, QC_POLY, QC_GRID, QCM and QG the outflow concentration when water is leaving the model is controlled by the Sub-Type BC block command as follows.

  • Sub-Type == 1 is the default and applies the boundary cell internal concentration for outflow.
  • Sub-Type == 2 applies the concentration from the boundary condition file for outflow. This can represent an external process where the outflow concentration is known.

The following syntax block illustrates the use of Sub-Type for a QC boundary. The same structure applies to QC_POLY, QC_GRID, QCM and QG boundaries differing only in the initial BC == specifier.

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

! Point QC Extraction
BC == QC, Offtake, ..\bc_dbase\Offtake_001.csv ! boundary_type, location_ID, data_filepath
  BC Header == Time_UTC, Flow_Q, SAL_psu, T_Cdeg ! {TIME}, {Q} (m^3/s), {SAL} (psu), {TEMP} (C)
  Sub-Type == 2 ! {1} Internal cell concentration for outflows | {2} Boundary timeseries concentration for outflow
End BC

7.11.5 Stage Discharge

Stage discharge boundary conditions are used to apply downstream tailwater controls where a relationship between water level and flow exists. Both user defined and automatically generated relationships are supported.

The boundary setup process is the same as 2D HD (See Section 5.16.5). No further advection dispersion configuration is required. For flow leaving the model the boundary concentration is taken from adjacent internal model cells. If flow enters the model a zero gradient concentration boundary is applied.

7.11.6 Atmospheric

This section describes the additional atmospheric boundary inputs required to force atmospheric heat exchange (see Section 7.7). Wind speed, mean sea level and tropical cyclone parametric model atmospheric boundaries remain unchanged from the 2D HD simulation class and are described in Section 5.16.6.

These inputs include air temperature, relative humidity, shortwave radiation, longwave radiation, precipitation and cloud cover. Both spatially constant and gridded implementations are available and are listed in Table 7.26. The Boundary Type column links each entry to the corresponding boundary condition subsection for detailed notes and syntax examples. As gridded boundary inputs are usually generated by the same TUFLOW FV Get Atmos workflow and share a single grid definition block, they are grouped in this section.

Table 7.26: Atmospheric Boundaries
Boundary Type Description
AIR_TEMP Spatially constant air temperature boundary condition.
CLOUD Spatially constant cloud cover boundary condition.
LW_NET Spatially constant net longwave radiation boundary condition.
LW_RAD Spatially constant downward longwave radiation boundary condition.
PRECIP Spatially constant precipitation boundary condition. Can be used to optionally assign rainfall temperature.
REL_HUM Spatially constant relative humidity boundary condition.
SW_RAD Spatially constant shortwave radiation boundary condition.
AIR_TEMP_GRID Gridded air temperature boundary condition.
CLOUD_GRID Gridded cloud cover boundary condition.
LW_NET_GRID Gridded net longwave radiation boundary condition.
LW_RAD_GRID Gridded downward longwave radiation boundary condition.
PRECIP_GRID Gridded precipitation boundary condition. Can be used to optionally assign rainfall temperature.
REL_HUM_GRID Gridded relative humidity boundary condition.
SW_RAD_GRID Gridded shortwave radiation boundary condition.

7.11.6.1 AIR_TEMP

  • Spatial: Spatially constant over the model domain
  • Location: Global
  • Data format: CSV
  • Required input variables: TIME, AIR_TEMP (\(^\circ\)C)
  • Notes:
    • Default air temperature is 0.0\(^\circ\)C if not specified

! Spatially constant air temperature
BC == AIR_TEMP, ..\bc_dbase\MET_20110401_20110701.csv ! boundary_type, data_filepath
  BC Header == time, air_temp ! {TIME}, {AIR_TEMP} (degrees Celsius)
  BC Update dt == 900. ! {0.0} Boundary update interval (s)
End BC

7.11.6.2 CLOUD

  • Spatial: Spatially constant over the model domain
  • Location: Global
  • Data format: CSV
  • Required input variables: TIME, CLOUD (fraction, 0 to 1)
  • Notes:
    • Default cloud cover is 0.0 (clear sky) if not specified

! Spatially constant cloud cover
BC == CLOUD, ..\bc_dbase\MET_20110401_20110701.csv ! boundary_type, data_filepath
  BC Header == time, cloud ! {TIME}, {CLOUD} (0 clear to 1 full cloud)
  BC Update dt == 900. ! {0.0} Boundary update interval (s)
End BC

7.11.6.3 LW_NET

  • Spatial: Spatially constant over the model domain
  • Location: Global
  • Data format: CSV
  • Required input variables: TIME, LW_NET (W/m^2)
  • Notes:
    • Default net longwave radiation is 0.0 W/m^2 if not specified

! Spatially constant net longwave radiation
BC == LW_NET, ..\bc_dbase\MET_20110401_20110701.csv ! boundary_type, data_filepath
  BC Header == time, lw_net ! {TIME}, {LW_NET} (W/m^2)
  BC Update dt == 900. ! {0.0} Boundary update interval (s)
End BC

7.11.6.4 LW_RAD

  • Spatial: Spatially constant over the model domain
  • Location: Global
  • Data format: CSV
  • Required input variables: TIME, LW_RAD (W/m^2)
  • Notes:
    • Default downward longwave radiation is 0.0 W/m^2 if not specified

! Spatially constant downward longwave radiation
BC == LW_RAD, ..\bc_dbase\MET_20110401_20110701.csv ! boundary_type, data_filepath
  BC Header == time, lw_rad ! {TIME}, {LW_RAD} (W/m^2)
  BC Update dt == 900. ! {0.0} Boundary update interval (s)
End BC

7.11.6.5 PRECIP

  • Spatial: Spatially constant over the model domain
  • Location: Global
  • Data format: CSV
  • Required input variables: TIME, PRECIP (m/day)
  • Optional input variables: PRECIP_TEMP (degrees Celsius)
  • Notes:
    • Default precipitation is 0.0 m/day if not specified
    • Default rainfall temperature is the water surface temperature if not specified
    • Sub-Type == 1 (default) applies precipitation to all models regardless of wet/dry state. This is the most common approach and is suitable for models with dynamic wet/dry extent
    • Sub-Type == 2 is applied to only wet model cells. This can be useful if the model wet/dry extent is fixed and known a priori

! Spatially constant precipitation
BC == PRECIP, ..\bc_dbase\MET_20110401_20110701.csv ! boundary_type, data_filepath
  BC Header == time, precip, precip_temp ! {TIME}, {PRECIP} (m/day), {PRECIP_TEMP} (°C)
  BC Update dt == 900. ! {0.0} Boundary update interval (s)
  Sub-Type == 1 ! {1} Precipitation applied to all cells | {2} Precipitation applied to wet cells only
End BC

7.11.6.6 REL_HUM

  • Spatial: Spatially constant over the model domain
  • Location: Global
  • Data format: CSV
  • Required input variables: TIME, REL_HUM (%)
  • Notes:
    • Default relative humidity is 0.0% if not specified

! Spatially constant relative humidity
BC == REL_HUM, ..\bc_dbase\MET_20110401_20110701.csv ! boundary_type, data_filepath
  BC Header == time, rel_hum ! {TIME}, {REL_HUM} (%)
  BC Update dt == 900. ! {0.0} Boundary update interval (s)
End BC

7.11.6.7 SW_RAD

  • Spatial: Spatially constant over the model domain
  • Location: Global
  • Data format: CSV
  • Required input variables: TIME, SW_RAD (W/m^2)
  • Notes:
    • Default shortwave radiation is 0.0 W/m^2 if not specified

! Spatially constant shortwave radiation
BC == SW_RAD, ..\bc_dbase\MET_20110401_20110701.csv ! boundary_type, data_filepath
  BC Header == time, sw_rad ! {TIME}, {SW_RAD} (W/m^2)
  BC Update dt == 900. ! {0.0} Boundary update interval (s)
End BC

7.11.6.8 Gridded Atmospheric Boundary Conditions

The variables required to force the default atmospheric heat exchange Shortwave Radiation Model, Longwave Radiation Model, Latent Heat Model and Sensible Heat Model are AIR_TEMP_GRID, CLOUD_GRID, LW_RAD_GRID, PRECIP_GRID, REL_HUM_GRID and SW_RAD_GRID. These can be developed using the TUFLOW FV Get Atmos tool and are configured with a shared Grid Definition block. LW_NET_GRID is not generated by TUFLOW FV Get Atmos but follows the same structure and is included here for completeness. The key features of these gridded atmospheric boundary conditions are as follows.

  • Spatial: Spatially varying on an x and y grid
  • Location: Grid
  • Data format: NetCDF
  • Required input variables:
    • AIR_TEMP_GRID: TIME, AIR_TEMP (\(^\circ\)C)
    • CLOUD_GRID: TIME, CLOUD (fraction, 0 to 1)
    • LW_RAD_GRID: TIME, LW_RAD (W/m^2)
    • PRECIP_GRID: TIME, PRECIP (m/day)
    • REL_HUM_GRID: TIME, REL_HUM (%)
    • SW_RAD_GRID: TIME, SW_RAD (W/m^2)
    • LW_NET_GRID: TIME, LW_NET (W/m^2)
  • Optional input variables:
    • PRECIP_GRID: PRECIP_TEMP (degrees Celsius)
  • Notes:
    • All gridded values default to 0.0 if not specified
    • The grid can be defined once in Grid Definition and reused by multiple boundary types
    • LW_NET_GRID is not generated by Get Atmos. It is required if using the non-default Net Longwave Radiation Model for atmospheric heat exchange
    • For PRECIP_GRID Sub-Type == 1 (default) applies precipitation to all model cells regardless of wet/dry state. This is the most common approach and is suitable for models with dynamic wet/dry extent
    • For PRECIP_GRID Sub-Type == 2 is applied to only wet model cells. This can be useful if the model wet/dry extent is fixed and known a priori
    • Default rainfall temperature (PRECIP_TEMP) is the water surface temperature if not specified

! TUFLOW FV FVC file for atmospheric dataset
! Written by get_atmos

Grid Definition File == ..\bc_dbase\ERA5_20100301_20100531.nc ! NetCDF file containing the atmospheric forcing grid
  Grid Definition Variables == longitude, latitude ! {No defaults} X,Y coordinate variable names in the NetCDF file
  Grid Definition Label == atmos ! {No default} Reference name for reuse by grid BCs
  Boundary Gridmap == 1 ! {1} Map interpolation method used for boundary application
End Grid

! Gridded air temperature
BC == AIR_TEMP_GRID, atmos, ..\bc_dbase\ERA5_20100301_20100531.nc ! boundary_type, location_ID, data_filepath
  BC Header == time, air_temp ! {TIME}, {AIR_TEMP} (degrees Celsius)
  BC Update dt == 3600. ! (s) Boundary condition update interval
  BC Time Units == hours ! {ISODATE | HOURS} | DAYS | MINUTES | SECONDS - Hours since the BC Reference Time (01/01/1990 00:00:00 or 0.0)
End BC

! Gridded cloud cover
BC == CLOUD_GRID, atmos, ..\bc_dbase\ERA5_20100301_20100531.nc ! boundary_type, location_ID, data_filepath
  BC Header == time, cloud ! {TIME}, {CLOUD} (0 to 1)
  BC Update dt == 3600. ! (s) Boundary condition update interval
  BC Time Units == hours ! {ISODATE | HOURS} | DAYS | MINUTES | SECONDS - Hours since the BC Reference Time (01/01/1990 00:00:00 or 0.0)
End BC

! Gridded downward longwave radiation
BC == LW_RAD_GRID, atmos, ..\bc_dbase\ERA5_20100301_20100531.nc ! boundary_type, location_ID, data_filepath
  BC Header == time, lw_rad ! {TIME}, {LW_RAD} (W/m^2)
  BC Update dt == 3600. ! (s) Boundary condition update interval
  BC Time Units == hours ! {ISODATE | HOURS} | DAYS | MINUTES | SECONDS - Hours since the BC Reference Time (01/01/1990 00:00:00 or 0.0)
End BC

! Gridded precipitation - Precip temp is optional and is not downloaded by the Get Atmos tool
BC == PRECIP_GRID, atmos, ..\bc_dbase\ERA5_20100301_20100531.nc ! boundary_type, location_ID, data_filepath
  BC Header == time, precip ! {TIME}, {PRECIP} (m/day), Optional {PRECIP_TEMP} (degrees Celsius)
  BC Update dt == 3600. ! (s) Boundary condition update interval
  BC Time Units == hours ! {ISODATE | HOURS} | DAYS | MINUTES | SECONDS - Hours since the BC Reference Time (01/01/1990 00:00:00 or 0.0)
  Sub-Type == 1 ! {1} Apply precipitation to all model cells | 2 Apply precipitation to wet model cells only
End BC

! Gridded relative humidity
BC == REL_HUM_GRID, atmos, ..\bc_dbase\ERA5_20100301_20100531.nc ! boundary_type, location_ID, data_filepath
  BC Header == time, rel_hum ! {TIME}, {REL_HUM} (%)
  BC Update dt == 3600. ! (s) Boundary condition update interval
  BC Time Units == hours ! {ISODATE | HOURS} | DAYS | MINUTES | SECONDS - Hours since the BC Reference Time (01/01/1990 00:00:00 or 0.0)
End BC

! Gridded shortwave radiation
BC == SW_RAD_GRID, atmos, ..\bc_dbase\ERA5_20100301_20100531.nc ! boundary_type, location_ID, data_filepath
  BC Header == time, sw_rad ! {TIME}, {SW_RAD} (W/m^2)
  BC Update dt == 3600. ! (s) Boundary condition update interval
  BC Time Units == hours ! {ISODATE | HOURS} | DAYS | MINUTES | SECONDS - Hours since the BC Reference Time (01/01/1990 00:00:00 or 0.0)
End BC

! Gridded net longwave radiation - Not generated by Get Atmos, shown for completeness
BC == LW_NET_GRID, atmos, ..\bc_dbase\ERA5_20100301_20100531.nc ! boundary_type, location_ID, data_filepath
  BC Header == time, lw_net ! {TIME}, {LW_NET} (W/m^2)
  BC Update dt == 3600. ! (s) Boundary condition update interval
  BC Time Units == hours ! {ISODATE | HOURS} | DAYS | MINUTES | SECONDS - Hours since the BC Reference Time (01/01/1990 00:00:00 or 0.0)
End BC

7.11.7 Ocean Circulation Model

Ocean circulation boundaries are used to apply one way forcing from external ocean or estuary model predictions to a TUFLOW FV domain. They are typically used to force a local simulation using fields from a larger scale hydrodynamic or global circulation model, such as HYCOM.

These boundaries are configured with the OBC_GRID boundary type listed in Table 7.27. The Boundary Type links in the table direct readers to the corresponding subsections below, where example TUFLOW FV syntax is provided.

Table 7.27: Ocean Circulation Boundary Conditions
Boundary Type Description
OBC_GRID Ocean circulation model boundary forcing. Allows specification of spatially and temporally varying mean sea level, velocity, salinity and temperature fields.

7.11.7.1 OBC_GRID

  • Spatial: Spatially varying on an x, y and z grid
  • Location: Grid
  • Data format: NetCDF
  • Required input variables: TIME, SSH (m), U (m/s), V (m/s), SAL (psu), TEMP (C)
  • Notes:

! TUFLOW FV FVC File for Ocean Dataset
! Written by get_ocean

! NetCDF start time: 2010-03-01 00:00
! NetCDF end time: 2010-04-30 21:00
! NetCDF x-limits: 135.0400, 142.9600
! NetCDF y-limits: -18.9600, -7.0400

Grid Definition File == ..\bc_dbase\GoC_HYCOM_20100326_20100402_AEST.nc ! Open grid definition block and reference file with grid coordinates
  Grid Definition Variables == longitude, latitude, depth ! The x, y, z coordinate variable names within the specified NetCDF file
  Grid Definition Label == ocean ! Name of the grid
  Boundary Gridmap == 1 ! Use map index to match BC locations to parent grid
End Grid

BC == OBC_GRID, ocean, ..\bc_dbase\GoC_HYCOM_20100326_20100402_AEST.nc ! boundary_type, location_ID, forcing data file
  BC Nodestrings == Eastern_Boundary, Western_Boundary ! Open boundary nodestring IDs that OBC_GRID will interpolated onto
  Sub-Type == 6 ! {1} Specified water level | 2 Reserved | 3 Specified Velocity | 4 Specified Water Level and Velocity (legacy) | 5 Incremental water level | 6 Specified Water Level and Velocity
  BC Header == local_time, surf_el, water_u, water_v, salinity, water_temp ! {TIME}, {SSH} Water surface elevation (m), {U} U velocity component (m/s), {V} V velocity component (m/s), {SAL} Salinity (psu), {TEMP} Temperature (°C)
  BC Update dt == 900. ! {0.0} Boundary update interval (s)
  BC Time Units == hours ! {ISODATE | HOURS} | DAYS | MINUTES | SECONDS - Hours since the BC Reference Time (01/01/1990 00:00:00 or 0.0)
  BC Offset == -0.65, 0.0, 0.0, 0.0, 0.0 ! {0.0} SSH, {0.0} U, {0.0} V, {0.0} SAL, {0.0} TEMP
  Vertical Coordinate Type == depth ! {Elevation} | Depth | Sigma | Height
End BC

7.11.8 Mass Flux

This suite of boundary conditions allows for the addition of mass (or heat) to a simulation as a flux, without the addition of water. For example, this supports simulation of processes such as thermal heat exchange or the removal of nutrients through environmental treatment processes. The most complex boundary condition in the suite (FC_GRID) can be used to force TUFLOW FV with predictions from other numerical models (such as CFD) that simulate high resolution spatial and temporal processes such as diffuser discharges. Regardless, all boundaries apply a flux of mass (salt, heat or tracer) as a rate to the cell or cells specified. This flux is then included in subsequent advection dispersion and related calculations. No momentum flux is applied.

The available flux boundary types are listed in Table 7.28. The links in the Boundary Type column direct the reader to the corresponding subsections below which describe configuration requirements and provide example TUFLOW FV syntax.

Table 7.28: Mass Flux Boundaries
Boundary Type Description
FC Mass flux applied to an individual 2D cell using a timeseries input.
FC_POLY Mass flux applied to 2D cells whose centroids fall within a specified polygon using a timeseries input.
FCM Mass flux applied to a moving point with time varying X and Y coordinates from a timeseries input.
FC_GRID Mass flux applied to a gridded set of cells using NetCDF time varying flux and weighting data.

In general the required units of the specified fluxes follow these rules:

  • Quantities with mg/m\(^3\) (\(\mu\)g/L) concentration units require fluxes in units of mg/s
  • Quantities with g/m\(^3\) (mg/L) concentration units require fluxes in units of g/s
  • Quantities with kg/m\(^3\) (g/L) concentration units or psu require fluxes in units of kg/s

As such the required units of fluxes for salt heat and tracers are:

  • Salt: kg/s
  • Temperature: Joules/\(C_p\)/\(\rho\)/s if heat flux is known or C m\(^3\)/s if a pure temperature flux is known
  • Tracer: g/s

7.11.8.1 FC

  • Spatial: Constant
  • Location: Point
  • Data format: CSV
  • Required input variables: TIME and flux values. For the ordering of flux values see Section 7.11.2.4
  • Notes:
    • FC is the conceptual parallel to the QC boundary described in the 2D HD simulation class

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

! Mass Flux
BC == FC, SF23, ..\bc_dbase\F01_002.csv ! boundary_type, location_ID, data_filepath
  BC Header == time_hr, SalFlux, TempFlux, TracerFlux ! {TIME}, {FLUX_SAL} (kg/s), {FLUX_HEAT} (J/C_p/density/s), {FLUX_TRACE_1} (g/s)
  BC Update dt == 900. ! {0.0} Boundary update interval (s)
End BC

7.11.8.2 FC_POLY

  • Spatial: Constant
  • Location: Polygon
  • Data format: CSV
  • Required input variables: TIME and flux values. For the ordering of flux values see Section 7.11.2.4
  • Notes:
    • FC_POLY is the conceptual parallel to the QC_POLY boundary described in the 2D HD simulation class

! Region Boundary Location Definition
Read GIS SA == ..\model\gis\2d_sa_Fluxes_001_R.shp

! Mass Flux In Polygon
BC == FC_POLY, SF23P, ..\bc_dbase\F01_002.csv ! boundary_type, location_ID, data_filepath
  BC Header == time_hr, SalFlux, TempFlux, TracerFlux ! {TIME}, {FLUX_SAL} (kg/s), {FLUX_HEAT} (J/C_p/density/s), {FLUX_TRACE_1} (g/s)
  BC Update dt == 900. ! {0.0} Boundary update interval (s)
End BC

7.11.8.3 FCM

  • Spatial: Mass flux applied to moving point
  • Location: Moving Point
  • Data format: CSV
  • Required input variables: TIME, X (m or decimal degrees), Y (m or decimal degrees) and flux values. For the ordering of flux values see Section 7.11.2.4
  • Notes:
    • FCM is the conceptual parallel to the QCM boundary described in the 2D HD simulation class

! Moving Point Flux
BC == FCM, ..\bc_dbase\Ship_Ballast_001.csv ! boundary_type, data_filepath
  BC Header == Time, X, Y, SalFlux, TempFlux, TracerFlux ! {TIME}, {X} (m or decimal degrees), {Y} (m or decimal degrees), {FLUX_SAL} (kg/s), {FLUX_HEAT} (J/C_p/density/s), {FLUX_TRACE_1} (g/s)
  BC Update dt == 900. ! {0.0} Boundary update interval (s)
End BC

7.11.8.4 FC_GRID

  • Spatial: Gridded
  • Location: Grid
  • Data format: NetCDF
  • Required input variables: Grid location definition, TIME, WEIGHT and flux values. For the ordering of flux values see Section 7.11.2.4
  • Notes:
    • FC_GRID is the conceptual parallel to the QC_GRID boundary described in the 2D HD simulation class

! Grid Location Definition
Grid Definition File == example_diffuser.nc ! NetCDF file containing coordinates used to define the grid map
  Grid Definition Variables == longitude, latitude, z ! X, Y and Z coordinate variable names in the NetCDF
  Grid Definition Label == diffuser_grid ! Grid name
  Vertical Coordinate Type == elevation ! {Elevation} | Depth | Sigma | Height
End Grid

! Model Mass Flux From Outfall/Diffuser
BC == FC_GRID, diffuser_grid, example_diffuser.nc ! boundary_type, location_ID, data_filepath
  BC Header == time, weight, SFLX ! {TIME}, {WEIGHT}, {FLUX_SAL} (kg/s) - NetCDF variable names
  BC Time Units == hours ! {ISODATE | HOURS} | DAYS | MINUTES | SECONDS - Hours since the BC Reference Time (01/01/1990 00:00:00 or 0.0)
  BC Update dt == 900. ! {0.0} Boundary update interval (s)
  Vertical Coordinate Type == elevation ! {Elevation} | Depth | Sigma | Height
End BC

7.11.9 Scalar Concentration

This suite of boundary conditions allows specification of salt, temperature and tracers independent of corresponding hydrodynamic boundary specifications. This can be useful, for example, where hydrodynamic and concentration boundary data are provided by independent third parties and are on different timesteps. This SCALAR boundary avoids the need for a user to interpolate the data sets onto a common timestep. TUFLOW FV undertakes this task automatically when the SCALAR BC block is issued.

Other implementations of these boundaries (CP and CP_POLY) allow specification of concentration profiles at points or within polygons. These boundaries are useful when initial conditions are based on measurements at fixed locations. Using these boundaries with the warmup horizontal mixing model (see Section 7.5.7) allows cotemporal field profile measurements to generate globally smooth initial conditions. These CP and CP_POLY boundaries are typically used only for this initialisation application.

The available scalar boundaries are listed in Table 7.29. The links in the Boundary Type column direct the reader to the corresponding subsections below which describe configuration requirements and provide example TUFLOW FV syntax.

Table 7.29: Scalar Concentration Boundaries
Boundary Type Description
SCALAR Applies salinity temperature and tracer timeseries to an existing hydrodynamic boundary location.
CP Applies concentration profiles at points and is typically used with warmup mixing to generate initial conditions.
CP_POLY Applies concentration profiles within polygons and is typically used with warmup mixing to generate initial conditions.

7.11.9.1 SCALAR

  • Spatial: Constant
  • Location: Point, Line or Polygon
  • Data: CSV
  • Required Input Variables: TIME, concentrations. For the ordering of concentration values see Section 7.11.2.4
  • Notes:
    • SCALAR is applied to a corresponding hydrodynamic boundary, including point (QC), line (Q, WL, WLS) or polygon (QC_POLY)
    • Each SCALAR BC block must specify a location_ID that has already been declared and associated with a hydrodynamic boundary

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

! Catchment C2 Concentrations
BC == SCALAR, C2, ..\bc_dbase\C01_002.csv ! boundary_type, location_ID, data_filepath
  BC Header == time_hr, Sal, Tmp ! {TIME}, {SAL} (psu), {TEMP} (C)
  Trace Header == TRC23 ! {TRACE_1} Tracer 1 concentration (g/m^3)
  BC Update dt == 900. ! {0.0} Boundary update interval (s)
End BC

7.11.9.2 CP

  • Spatial: Variable
  • Location: Point(s)
  • Data: CSV Profile
  • Required Input Variables: DEPTH, concentrations. For the ordering of concentration values see Section 7.11.2.4
  • Notes:
    • Points are specified by a SA points file
    • DEPTH is the first column in the csv file and positive is downwards
    • Typically used with the warmup horizontal scalar diffusivity model (see Section 7.5.7) to generate smooth initial conditions saved to a restart file used to then initialise subsequent simulations

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

! Instream Concentrations
BC == CP, Site2, ..\bc_dbase\Site2_002.csv ! boundary_type, location_ID, data_filepath
  BC Header == Depth, Sal_psu, Tmptre, Tc1 ! {DEPTH}, {SAL} (psu), {TEMP} (C), {TRACE_1} (g/m^3)
End BC

7.11.9.3 CP_POLY

  • Spatial: Variable
  • Location: Polygon(s)
  • Data: CSV Profile
  • Required Input Variables: DEPTH, concentrations. For the ordering of concentration values see Section 7.11.2.4
  • Notes:
    • Polygons are specified by a SA polygon file
    • DEPTH is the first column in the csv file and positive is downwards
    • Typically used with the warmup horizontal scalar diffusivity model (see Section 7.5.7) to generate smooth initial conditions saved to a restart file used to then initialise subsequent simulations

! Polygon Location Definition
Read GIS SA == ..\model\gis\2d_sa_Monitoring_001_R.shp

! Instream Concentrations
BC == CP_POLY, Site23, ..\bc_dbase\Site23_021.csv ! boundary_type, location_ID, data_filepath
  BC Header == Depth, Sal_psu, Tmptre, Tc1 ! {DEPTH}, {SAL} (psu), {TEMP} (C), {TRACE_1} (g/m^3)
End BC

7.11.10 Transport File

Environmental modelling investigations often include simulation of multiple scenarios related to changes in dissolved constituent fluxes or concentrations, but not to underlying hydrodynamics. One example might be examination of the wider ecological impact of improving the quality (but not volumetric discharge) of a proposed wastewater treatment plant outfall. This might be achieved within TUFLOW FV by varying only concentrations on a QC boundary between multiple scenarios. In such cases, TUFLOW FV offers the option to reduce the recalculation of unchanging inter-scenario hydrodynamics by specifying a transport file boundary condition to an advection dispersion (or higher order sediment / water quality) simulation. The transport file is an output of a previous simulation (see Section 5.18.9) and contains precomputed cell volume, x-momentum and y-momentum information to support more efficient simulation of advection dispersion scenarios with unchanging hydrodynamics.

  • Spatial: Variable
  • Location: Entire computational domain
  • Data: NetCDF file generated from previous simulation
  • Required Input Variables: Set by previous simulation
  • Notes:
    • Transport files can only be used where hydrodynamics are unchanged. This includes water levels, inflows/outflows, fluxes, forces, atmospheric forcing and similar boundaries that change densities or flow fields
    • Only advected and dispersed quantities that do not contribute to density can be changed between scenarios that use the same transport file. If salinity and/or temperature (including atmospheric forcing) are simulated and include baroclinic effects, then these must remain unchanged between scenarios
    • Timestep limits must remain unchanged between the hydrodynamic simulation that generated the transport file and subsequent simulations that deploy it as a boundary condition

! Transport file
BC == TRANSPORT, ..\results\MB_001_trans.nc ! boundary_type, data_filepath
End BC