Section 4 2D Solvers - Classic/HPC

4.1 Overview

There are no changes in Release 2023-03 to the core 2D Classic solver, however, an update to the Fortran Compiler may mean very slight differences compared to the 2020-10 builds.

The new features described in the sections below apply to the 2D HPC solver.

4.2 2D HPC Weir Flow Approach

Where flow in the 2D domain becomes upstream controlled, TUFLOW HPC triggers a weir flow approximation by adjusting the water level gradient. The adjustment was originally calibrated to match the broad-crested weir formula. The 2023-03 Release now supports applying the full weir equation in the 2D domain based on the advanced weir equation (4.1).

\[\begin{equation} Q = {\frac{2}{3}C_{f}C_{d}C_{sf}W\sqrt{2g}H_u^{Ex}} \tag{4.1} \end{equation}\]

\[\begin{equation} C_{sf} = (1-(\frac{H_{d}}{H_{u}})^{a})^{b} \tag{4.2} \end{equation}\]

Where:

  • \(Q\) = Flow over the weir face (m3/s or ft3/s).
  • \(C_{f}\) = Weir calibration factor. Cf can be either changed globally using the “Set WRF” command, or adjusted locally using the “Read GIS WRF” feature. The default value is 1.0.
  • \(C_{d}\) = Weir coefficient. The default is 0.577.
  • \(C_{sf}\) = Weir submergence factor based on the Villemonte equation.
  • \(W\) = Flow width. For 2D weir approach, this is the length of the weir face (m or ft).
  • \(H_{u}\) = Upstream water surface or energy depth relative to the weir invert (m or ft). Can be set by the “HPC Weir Approach” command below.
  • \(Ex\) = Weir flow equation exponent. The default value is 1.5.
  • \(H_{d}\) = Downstream water surface relative to the weir invert (m or ft).
  • \(a, b\) = Exponents used in the Villemonte equation. The default values are 8.55 and 0.556.

In the 2023-03 Release, this feature is turned on by default, but can be changed using the following .tcf command:

HPC Weir Approach == Method A | Method B | {Method B Energy}

  • “Method A” is the previous method that applies the water level gradient limiter only.
  • “Method B” applies the weir equation and uses the upstream water level above the weir invert as Hu.
  • “Method B Energy” is the new default approach. It applies the weir equation and uses the upstream energy level above the weir invert as Hu.

The default coefficients (Cd, Ex, a and b) are based on the parameters used for a Broad-Crested Weir. The following .tcf commands can be used to change them:

HPC Thin Weir Parameters == Cd, Ex, a, b

HPC Thick Weir Parameters == Cd, Ex, a, b

4.3 Support for Record Gauge Data in HPC

The 2023-03 Release adds support for gauge objects in HPC (and Quadtree) which corresponds to the following command in the .tgc and ‘G_’ PO types:

Read GIS Objects RECORD GAUGE DATA == \(\langle\)gis_layer\(\rangle\)

This functionality is documented in Section 9.8.1 of the 2018 TUFLOW Manual.

4.4 Support for Automatic Initial Water Level in Quadtree

The 2023-03 Release adds support for an automatic initial water level (IWL) in Quadtree (previously only available in Classic/HPC). This is implemented using the .tcf command “Set IWL == Auto” and is documented in Section 7.7.1.3 of the 2018 TUFLOW Manual.

4.5 Support for Long Profiles in HPC

The 2023-03 Release adds support for long profiles (2d_lp) in HPC and Quadtree.

Note: the long profile line processing in Quadtree can sometimes select slightly different cells and results can differ from HPC slightly, even if the 2D results are identical.

4.6 Increase in Maximum CPU Threads

The 2023-03 Release increases the maximum number of CPU threads for HPC and Quadtree simulations from 16 to 64. The number of CPU threads can be changed using the “-nt” command line option. If more than the maximum number of CPU threads are requested, ERROR 2485 is reported and the simulation halts. For prior builds this could cause an unrelated error to occur during model initialisation.

Note: a modern GPU is likely to provide much faster simulation times than CPU even with lots of CPU cores, a RTX 4080 GPU has almost 10,000 CUDA cores and a RTX 4090 has over 16,000!

4.7 Minor Enhancements and Bug Fixes

The 2023-03 Release includes a range of minor enhancements and bug fixes to the 2D solver.

4.7.1 Limiting Manning’s n for Wu Turbulence Calculation

When using the Wu turbulence formulation, the υ_3D term has the Manning’s n as a multiplier, the higher the Manning’s n, the higher the turbulence term. Since the timestep used in HPC and Quadtree is dependent on the turbulence, high Manning’s n values, particularly in deep water, can control the timestep. As detailed in Section 5.2.5 of the 2020 Release Notes, from build 2020-10-AB it is possible to set the upper limit for the Manning’s n value used in the turbulence calculation when using the Wu formulation. This only effects the Wu turbulence calculation; the specified Manning’s n is still used for the bed friction term. To specify an upper Manning’s n limit, a third value can be entered in the Viscosity Coefficients command:

Viscosity Coefficient == \(\langle\)C3D, C2D, Upper Limiting n\(\rangle\)

For the 2023-03 Release the default limiting Manning’s n value is 0.1. For backward compatibility with the 2020 Release this should be set to a 99. For example, to use the default Wu coefficients, with the 2020 defaults of 7 and 0 and no upper limiting Manning’s n value for turbulence the .tcf command would be:

Viscosity Coefficient == 7, 0, 99

If any Manning’s n values are specified (fixed or depth-varying Manning’s n) that exceeds the upper limit, WARNING 2583 is issued.

4.7.2 TIN Clip Layers in Quadtree

The 2023-03 Release fixes polygon clip layers in Quadtree when reading in TINs using “Read TIN Zpts == \(\langle\)tin\(\rangle\) | \(\langle\)clip_layer\(\rangle\)”. Previously, the clip layer was not being applied and the entire TIN was used.

4.7.3 Change to Treatment of non-Polygon Objects in Geometry Trim Layers

The 2023-03 Release changes how invalid clip layer objects are processed when trimming input grid layers (such as using “Read GRID Zpts == \(\langle\)grid\(\rangle\) | \(\langle\)trim.shp\(\rangle\)”). Previously when an invalid object was encountered (e.g., point, polyline, or null object) the entire grid was processed. The behaviour has been changed to be the opposite; invalid objects will now cause TUFLOW to not read in any of the input grid. The previous behaviour could sometimes read in the entire input grid if the clip polygon layer had a null object present that the user was unaware of. Note: For models using SGS, the new behaviour has always been the default, and this has only changed for non-SGS models.

4.7.4 WARNING 3522 Message Text Updated

The 2023-03 Release updates the text in WARNING 3522 (SGS parameters are different from XF file) to reference the specific XF file that produced the warning.

4.7.5 New Thick Breakline Face Selection for Quadtree Model

The 2023-03 Release improves the method to select cell faces when thick breaklines are used. Previously, refined cell faces might not be raised at changes in mesh resolution, shown in Figure 4.1. The 2023-03 Release ensures all the cell faces surrounding a raised cell are selected by thick breaklines, shown in Figure 4.2, as this is required for the new HPC weir flow approach (Section 4.2). For models using “HPC Weir Approach == Method A” (the previous approach), this change has minimal impact on the modelling result.

**Quadtree Thick Breakline Face Selection 2020-10-AF**

Figure 4.1: Quadtree Thick Breakline Face Selection 2020-10-AF

**Quadtree Thick Breakline Face Selection 2023-03-AA**

Figure 4.2: Quadtree Thick Breakline Face Selection 2023-03-AA

4.7.6 Support Read GIS Zpts Polygon Shape in SGS Method C

The 2023-03 Release now supports polygon shapes for the “Read GIS Zpts” command in models using “SGS Approach == Method C”. In the 2020-10 Release, “Read GIS Zpts” polygons were only supported with using “SGS Approach == Method B”.

4.7.7 Support Read GRID Zpts ADD Option for SGS Method C

The 2023-03 Release also supports the ADD option for the “Read GRID Zpts” command in models using “SGS Approach == Method C”. Prior to this release, the “Read GRID Zpts ADD” command was producing incorrect bed elevation for the model.

4.7.8 Read RowCol Zpts and Read GIS Zpts With Point Layer Now Produce ERROR 3517 in SGS or Quadtree Models

The 2023-03 Release will produce ERROR 3517 when Read RowCol Zpts or Read GIS Zpts with a point layer is used in SGS or Quadtree models. Previously TUFLOW would ignore these commands in models using SGS.

4.7.9 Error for .tgc command Read Grid IWL used in .tcf

As per the 2018 TUFLOW Manual, the “Read Gridded IWL” command should be specified in the .tgc and not the .tcf. For Build 2023-03-AA, ERROR 2586 will be generated if this command is specified in the .tcf and the simulation is halted. Previously this command was ignored.

4.8 Minor Enhancements and Bug Fixes 2023-03-AB

4.8.1 Running Simulations at the Exact Same Time Causes XF File “End Of File” Error

When running simulations at the same time through a batch file or runner utility, sometimes the xf files would crash due to both simulations trying to access the xf files at the same time. This generally occurred only when the connection to the hard drive was slow, such as across a network or when using an external drive. Build 2023-03-AB adds changes to better handle collisions that were encountered. However, running from a local hard drive provides the best performance and stability.

4.8.2 Bug Fix for “Should Not Be Here [tE” with HPC and Restart Files

Build 2023-03-AB fixes an issue that caused “Should not be here [tE=….” to be output to the console and log outputs at the first model timestep. The model continued to run, and this did not affect behaviour of the model.

4.8.3 Bug Fix for “Should not Be Here [tE” at End of Simulation

Build 2023-03-AB fixes an issue that caused “Should not be here [tE=….” to be repeatedly output at the end of the simulation. This caused an infinite loop to occur and the simulation not to write the maximums and final output. This occurred very rarely and only if a very small initial timestep was set for the model. This only occurred for HPC simulations.

4.8.4 Bug Fix for Forward Slash in Check File Path

Build 2023-03-AB fixes an issue with “Write Check Files” and forward slashes. If the final character is a “” then this is treated as a path to the check folder, and all check files get written with the simulation name, e.g.:

Write Check Files == ..\check\

However, if the final character is not a backslash then this is treated a prefix, e.g.:

Write Check Files == ..\check\run_002

In the above example all files will be written to the ..\check\ folder and will use the prefix “run_002” instead of the simulation name. When using a forward slash notation (Write Check Files == ../check/) then this was being treated as a prefix and not a folder path. For build 2023-03-AB both \ and / are treated as a path.

4.8.5 Bug Fix for Stability Issue with Thick Breaklines

Applying the advanced weir equation over thin and thick breaklines was introduced in 2023-03-AA. However, it has become apparent that on rare occasions the depth adjustment applied to faces parallel to the flow (thick breaklines only) can cause a stability issue. The depth adjustment on these faces has been removed in version 2023-03-AB. This may produce very minor changes in results to models with thick breaklines.

4.8.6 Bug Fix for Small HPC models on CPU with a Large Number of Threads

Previous versions of HPC (not Quadtree models) could fail to run due to an incorrect decomposition when splitting the model over a large number of CPU threads. This issue is fixed in 2023-03-AB.

4.8.7 Bug Fix with SGS Calculation

For SGS Approach Method C, on very (very) rare occasions the SGS calculations for a cell could cause a cell to have a fixed storage instead of a height varying storage. This issue was introduced in 2023-03-AA and has been fixed in 2023-03-AB. For models that did generate an erroneous SGS calculation on a particular cell, a very small change in results may be expected.

Due to this issue the XF files (described in Section 2.2.8 need to be updated if moving to the 2023-03-AB build from the 2023-03-AA build.

4.8.8 Bug Fix with Fixed Form Loss Coefficients in Quadtree

When applying additional fixed form loss coefficients (“Set FLC”“, Read GIS FLC” and “Read Grid FLC”) within a Quadtree model, the coefficients were being incorrectly applied. This issue is fixed in 2023-03-AB.

4.8.9 Update to CHECK 3505 SGS TIN for Quadtree Model

Build 2023-03-AB now only outputs CHECK 3505 – SGS TIN Outside Model Domain for nesting level 1 when running Quadtree simulations. Previously this check message could be spuriously generated for TIN inputs that were within the base nesting level, but outside the extents of the finer nesting levels.

4.8.10 Bug Fix 2d_lfcsh Layers in Quadtree Snapped to Code

Build 2023-03-AB fixes an unreported bug that could incorrectly treat polylines snapped to the code boundary in Quadtree. Previously this had the potential to cause a memory overrun and affect the model in unexpected ways.

Not all polyline inputs are affected. Common inputs affected include 2d_zsh (and other breakline inputs), 2d_lfcsh, and 2d_po inputs.