Section 6 Boundaries and Links
6.1 Support for DSS File Format
The 2023-03 release introduces support for time-series data from HEC-DSS files within a boundary condition database. HEC-DSS is a database system for time series, curve, gridded data and more developed by the U.S. Army Corps of Engineers Hydrologic Engineering Center (HEC). See their website at https://www.hec.usace.army.mil/software/hec-dss/ for more information. It is used by the HEC developed models for data input and output. Rather than convert HEC-DSS time-series curves for use in TUFLOW, this data can be accessed directly. HEC-DSS files organise data into paths with six parts (Part A – Part F) that resemble how files are organised on disk. Figure 6.1 shows an example DSS file with a single path, with the curve plotted below.
Figure 6.1: Example DSS File
To use a HEC-DSS time-series curve within a TUFLOW boundary condition database:
- Provide the filename in the “Source” column.
- Leave “Column 1”, which is used for time, blank (DSS files store the time with the curve values).
- Identify the pathname in “Column 2.” Event placeholders such as event can be used as part of the pathname. Wildcards (*) can be used for parts of the path, however, ensure the wildcards will not select more than one path within the file.
- The “Add” and “Mult” columns can be used to offset or scale the time-series values, the same as non-DSS time-series curves.
Figure 6.2 shows how the time-series curve above could be included in a boundary condition database. A wildcard is used for Part D of the pathname (date range). Note that the pathname must start with a forward slash (/).
Figure 6.2: Time-series Curve Example
By default, TUFLOW uses the first point in the time-series curve as TUFLOW time-zero. This can be changed using the new command “
Note: Non-time series data such as gridded data from a HEC-DSS file is not supported at this time. Contact support@tuflow.com to request other features that would be beneficial to your workflows.
6.2 SX Momentum
2023-03 release has improved the handling of momentum flux at SX cells. This change has minor impact on SX cells with sub-critical flow. However, for the SX cells connected to high energy/velocity 1D structures, this enhancement would improve the boundary cell flow behaviour by applying appropriate momentum source/sink. For more details, please refer to the HWRS conference paper (Gao et al., 2022).
Previously, only mass flux has been added to SX cells. For backward capability, please use:
Note: Build 2023-03-AB fixes an minor issue with the reporting of HPC SX Momentum Approach in the .tlf which was missing a new line if Method A was specified.
6.3 Structure Loss Adjustment for SX Connected 1D Structures
Build 2020-10-AA introduced a new beta option to extend the adjustment of contraction and expansion losses for 1D culverts and bridges to automatically adjust at 1D/2D SX connections (refer to Section 6.2 in the 2020 Release Notes). This feature has been tested using Venturi flume experiment and real-world flood model (Gao et al., 2022). However, it is still under development and remains as beta functionality.
6.4 Quadtree Parallel Inertia on HT / HX Boundaries
For the 2023-03 release the handling of inertia parallel at head boundaries for Quadtree simulations (“HT” and “HX” type 2d_bc layers) has been changed to “Method B” to provide better consistency with TUFLOW Classic and single level HPC. A new .tcf command has been introduced:
To revert to the 2020 release method, use “Method A”.
6.5 HPC Support for Boundary Spline Interpolation
The 2023-03 release adds support for boundary cubic spline interpolation (“S” flag in the 2d_bc layer) for HT and QT type boundaries in HPC and Quadtree. Previously, if users specified a spline interpolation HPC would use linear interpolation and no warning message was produced.
6.6 Default HPC Boundary Approach
As outlined in Section 6.1.1 of the 2020 Release Notes,
6.7 QT 2d_bc Point Boundaries No Longer Supported in Classic/HPC
Build 2023-03-AD has removed support for ‘QT’ type boundaries using point geometries in the 2D domain for Classic/HPC models. If a ‘QT’ boundary using point geometry is encountered, TUFLOW will produce “ERROR 2835 - Not expecting point for BC layer with type: QT”. This change aligns Classic/HPC with Quadtree.
It is recommended to use line geometry types when adding ‘QT’ boundaries to the 2D domain, however, for old models the command
6.8 HQ 2d_bc Point Boundaries No Longer Supported in Classic/HPC/Quadtree
Build 2023-03-AD has removed support for ‘HQ’ type boundaries using point geometries in the 2D domain for Classic/HPC/Quadtree models. If a ‘HQ’ boundary using point geometry is encountered, TUFLOW will produce “ERROR 2835 - Not expecting point for BC layer with type: HQ”.
It is recommended to use line geometry types when adding ‘HQ’ boundaries to the 2D domain, however, for old models the command
6.9 Support for Holland Cyclone/Hurricane in HPC/Quadtree
Build 2023-03-AD includes support in HPC/Quadtree for cyclone / hurricane wind and pressure fields with the Holland parametric model. Previously this feature was only supported in Classic. This is specified with either of the .tcf commands below, which are treated identically:
This command can be used to read a cyclone or hurricane track. The attributes of the GIS layer are listed in Table 6.1 and are all float values. Only the first polyline in the layer is read and used for the track. Points are snapped to the line wherever attribute data are to be assigned. It is not necessary to have points snapped to every vertex of the line – values will be interpolated between the digitised points. There must be points with attribute data snapped to the start and end of the polyline track.
The optional
The 2d_cyc layer is also now written when using the
| Attribute Number | GIS Attribute | Description | Data Type |
|---|---|---|---|
| 1 | Time | Time in hours | Float |
| 2 | p0 | Pressure at the eye (hPa) | Float |
| 3 | pn | Pressure of surrounds (hPa) | Float |
| 4 | R | Radius to maximum winds (m) | Float |
| 5 | B | See reference below | Float |
| 6 | rho_air | Density of Air (kg/m3). If zero, Density of Air is used. | Float |
| 7 | km | Density of Air (kg/m3). If zero, Density of Air is used. | Float |
| 8 | ThetaMax | See reference below | Float |
| 9 | DeltaFM | See reference below | Float |
| 10 | bw_speed | Background wind speed in m/s (ignored if less than or equal to zero) | Float |
| 11 | bw_dirn | Background wind direction in degrees relative to East (0°), North (90°), etc. | Float |
The generation of the wind and pressure fields are based on Appendix C of “Queensland Climate Change and Community Vulnerability to Tropical Cyclones – Ocean Hazards Assessment – Stage 1” (Queensland Government, 2001).
The wind and pressure fields can be output using the
Note: that Latitude must be specified (via .tcf command
6.10 Minor Enhancements and Bug Fixes
The 2023-03 release includes a range of minor enhancements and bug fixes relating to boundaries.
6.10.1 Should Not Be Here When Reading TS1 File
The 2023-03 release changes a “Should not be here csv_to_binary[ncolA]” message to ERROR 0628. This error can occur if the TS1 file has become corrupted or if the user accidentally makes manual edits to the file.
6.10.2 Duplicate SA Boundary Names
The 2023-03 release changes the behaviour of HPC and Classic models that use multiple SA polygons with the same boundary name. In the 2023-03 Release, these boundaries are treated separately; as if they were different boundary names with the same hydrograph. Previously, these SA boundaries would be treated as a single boundary and the cells selected by each polygon would be grouped together.
If duplicate SA boundary names are encountered, TUFLOW will issue CHECK 2492 in the 2023-03 Release. The old method can be invoked by reverting to the pre-2023 defaults and WARNING 2492 is produced instead of the check message.
The previous method is not available in Quadtree as this has always used the 2023 default method.
6.10.3 CSV Inputs Containing Multiple Blocks
The 2023-03 release fixes an issue with XF files and .csv boundary data that could occur if there were multiple blocks of data within the .csv file. The file is considered to have multiple blocks when there is boundary data below other boundary data, for example in in Figure 6.3.
Figure 6.3: CSV Input Containing Multiple Blocks
If there are multiple blocks, no XF file will be generated in the 2023-03 release and WARNING 0627 will be issued. Previously TUFLOW would generate an XF file for the first inflow block it read in and ERROR 0141 could be triggered if inflows in other blocks were required (as they would not be present in the XF file).
6.10.4 BC Zero Flow End Fixed in Quadtree
The 2023-03 release fixes the “
6.10.5 BC Zero Flow CHECK Message
The 2023-03 release adds CHECK 0249 if the “
6.10.6 Automatic Initial Water Level When Interpolated
The 2023-03 release fixes a bug that could cause the incorrect water level to be applied when using “
6.10.7 SX Region with Z Flag in Quadtree Model
The 2023-03 release fixes a bug that occurred when using a “Z” flag in a 2d_bc “SX” type region. Previously, the Z flag did not lower the cell face and corner elevations in Quadtree models.
6.10.8 Small SX Region Selects At Least One Cell in Quadtree Model
Previously, if a small SX region doesn’t select any cell centroid in Quadtree models, the SX region was ignored. In the 2023-03 release, the centroid of the SX region will be used to select at least one boundary cell.
6.10.9 Check for Correct Attribute for SA RF Boundaries
6.10.10 Bug Fix for XF files when Time Column has Zero Rows of Data
Build 2023-03-AA fixes an issue with processing and reading of boundary xf files, if the data in column 1, which is time for a level-time (HT) or flow (QT) has zero rows of data, but the column 2 has valid data. This will now generate an ERROR 0651 and halt the simulation.
6.11 2023-03-AB Minor Enhancements and Bug Fixes
6.11.1 Quadtree HQ Total Boundary - Should Not Be Here
Build 2023-03-AB changes the ‘should not be here’ that could occur for quadtree models when using an HQ boundary ‘Total’ approach (this is the default method for HQ boundaries) to ERROR 2858.
The error was being triggered by the cell selection algorithm failing to create a contiguous line of cells which is required to generate a rating curve. This is in turn can be caused by refinement areas being snapped to the boundary line and causing varied cell size along the boundary (where the line can also pass through inactive areas). The best solution to the error is to buffer refinement areas away from the boundary line.
6.11.2 Better Handling of Null Objects in 2d_sa Layer
Build 2023-03-AB improves the handling of Null objects in the 2d_sa input layer. The objects have no geometry and could previously cause an ERROR 2041 to be issued. For build 2023-03-AB these are ignored.
6.12 2023-03-AC Minor Enhancements and Bug Fixes
6.12.1 Fixes Issue with NetCDF Rainfall with Times Greater Than 1,000 Hours
Build 2023-03-AC fixes an issue with NetCDF rainfall inputs with time values greater than 1,000 hours and boundary increments smaller than 1hr, previously this could cause the rainfall boundary to be updated only every hour and not at the boundary frequency.
6.13 2023-03-AD Minor Enhancements and Bug Fixes
6.13.1 Bug Fix for 2D HQ Boundaries Selecting Only One Cell
Build 2023-03-AD fixes a bug that could cause unexpected behaviour (e.g. unrelated errors may be thrown spuriously during initialisation) if a HQ boundary that only selected a single cell was used. This would only occur if the HQ boundary that selected a single cell was the last HQ boundary processed by TUFLOW.
6.13.2 Bug Fix for Quadtree Automatic SX Connections Where “Conn_No” is Set to -1
Build 2023-03-AD fixes a bug affecting Quadtree models only, where the functionality of setting the “Conn_No” to “-1” for 1d_nwk layers was not working. When setting the “Conn_No” to “-1”, TUFLOW should connect the pit or node to one 2D cell only, irrespective of the width. Previously, for Quadtree models, the number of 2D cells selected was still being controlled by the width of the pit or node.
6.13.3 Bug Fix for SA Check Files
Build 2023-03-AD fixes an issue that could occur in Quadtree models if writing check files in mif/mid format in conjunction with using the
6.13.4 Bug Fix for Very Large Models with SX Connections
Build 2023-03-AD fixes an issue that could cause TUFLOW to crash when writing the first output, with no error message. This issue only occurred for very large models with a significant number of SX connections.
6.13.5 Bug Fix for Gridded Rainfall in HPC
Build 2023-03-AD fixes an issue that could occur with gridded rainfall when the time of first rainfall was after the start of the simulation and there was no temporal map output at the time of first rainfall. This could cause the rainfall grids to be updated incorrectly, resulting in some grid times to be skipped. This issue could affect HPC (including quadtree), but did not affect Classic simulations.
6.13.6 Support for Global Wind Boundary in Quadtree
Build 2023-03-AD includes support in Quadtree for global wind stress applied via a
6.14 2023-03-AF Minor Enhancements and Bug Fixes
6.14.1 Support for “Unused HX and SX Connections == WARNING” in Quadtree
Build 2023-03-AF adds support for the command
6.14.2 Quadtree Overlapping Boundary Error Messaging
Build 2023-03-AF adds the following check and error messages to Quadtree when different boundary types select the same cells. This makes Quadtree consistent with TUFLOW HPC and Classic:
- ERROR 2034 - Triggered when there are overlapping HT and HX boundaries
- ERROR 2036 - Triggered when there are overlapping HT and SX boundaries
- ERROR 2036 - Triggered when there are overlapping QT and SX boundaries
- CHECK 2099 - Triggered when there are overlapping HX boundaries in the same layer
6.14.3 Support for Points and Lines in 2D SA Boundaries for Quadtree
Build 2023-03-AF adds support for point or line geometries in 2D source-area (2d_sa) flow boundaries for Quadtree simulations. This behaviour is now consistent with HPC/Classic models. Note that for 2023-03-AF empty point and line template files are now written for 2d_sa layers (see also Section 8.15.10)
6.14.4 Support for Multipart Point and Line Layers in Quadtree Boundaries
Build 2023-03-AF adds support for multipart point or line geometries in boundaries file (.tbc) processing for Quadtree simulations. For multipart layers, each feature can have multiple geometries associated with it. This behaviour is now consistent with HPC/Classic models.
6.14.5 Bug Fix for the Creation of HX Connections in HPC
Build 2023-03-AF fixes an issue in HPC where the log indicates that HX lines were connected to cell midpoints (if the line was too small to select cells using the original cross-hair implementation) but no HX cells were created.
6.14.6 ERROR on SA PO for HPC/Quadtree
Build 2023-03-AF introduces an error if “
6.14.7 Bug Fix for Automatic 1D HQ boundaries of Different Channel Types
Build 2023-03-AF modified the automatic HQ boundaries to allow different channel types upstream of the boundary. However, non-open channels are not recommended for HQ boundaries and a warning will be given. Some effort is also made to prevent invalid HQ curves from being generated.
6.14.8 Bug Fix for SX Pits in Quadtree
Build 2023-03-AF fixes an issue introduced in the 2023-03-AD build, which could cause TUFLOW to crash with “Program Exception - access violation” when processing Quadtree pit connections. This only occurred if there were 1D pits with SX connection that did not select active 2D cells in Quadtree.
6.14.9 ERROR on SA RF with Zero Catchment Area in Quadtree
Build 2023-03-AF provides consistency in messaging between solvers if a Source-Area boundary with the rainfall option (
6.14.10 ERROR on VT Boundary
Build 2023-03-AF will produce an error if a velocity-time (VT) boundary has been specified in Classic, this error is consistent with HPC/Quadtree and the VT boundary should no longer be used.
6.14.11 Downgrade ERROR 2386 to CHECK 2386
When using Quadtree, the 2023-03-AF build will now produce CHECK 2386 instead of ERROR 2386 if a line object in a stream layer (
