Section 5 2D Solvers - Classic/HPC

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

5.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 (5.1).

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

\[\begin{equation} C_{sf} = (1-(\frac{H_{d}}{H_{u}})^{a})^{b} \tag{5.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

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

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

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

5.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!

5.7 Minor Enhancements and Bug Fixes

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

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

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

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

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

5.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 5.1. The 2023-03 Release ensures all the cell faces surrounding a raised cell are selected by thick breaklines, shown in Figure 5.2, as this is required for the new HPC weir flow approach (Section 5.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 5.1: Quadtree Thick Breakline Face Selection 2020-10-AF

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

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

5.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”.

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

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

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

5.8 2023-03-AB Minor Enhancements and Bug Fixes

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

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

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

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

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

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

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

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

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

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

5.9 2023-03-AD Minor Enhancements and Bug Fixes

5.9.1 Bug Fix - HPC Crashing During Initialisation with Exactly 256 Unique Material IDs

Build 2023-03-AD fixes a bug when the user specifies exactly 256 unique material IDs. This would cause HPC to crash without an error during initialisation. This would only occur only in TUFLOW HPC and not TUFLOW Classic or Quadtree.

Build 2023-03-AD increases the limit of unique material IDs for HPC from 256 to 1,000. This brings TUFLOW HPC in line with TUFLOW Classic and Quadtree. If the user specifies more than 1,000 unique material IDs “ERROR 2116 - Exceeded number of allowable Materials” will be produced. Note, the material ID must be a number between 1 - 32,767.

5.9.2 Bug Fix with Process All Grids Command

The TUFLOW control file command: “Process All Grids == {OFF} | ON” controls whether raster input grids that are outside of the model domain are processed or skipped. Build 2023-03-AD fixes a bug where the default approach processed all grids, contrary to the 2018 TUFLOW Manual. From Build 2023-03-AD this correctly defaults to skipping raster grids that are outside the model domain and may provide an improvement in initialisation time compared to prior builds.

5.9.3 Bug Fix with Memory Allocation for Reading Grids with SGS

Build 2023-03-AD fixes an issue which could cause “ERROR 3500 - Could not allocate temporary memory (RAM) for processing SGS GRID …(Method C)” to occur when a DEM was partially or completely outside of the TUFLOW model domain. This issue only occurred for the default SGS approach: “SGS Approach == Method C”.

5.9.4 Bug Fix for Cell Width Factor in HPC

Build 2023-03-AD fixes an issue with cell width factors (CWF) not being correctly applied in HPC. This issue caused TUFLOW to crash after “Transferring Cell Width Factors (CWF)…” with no message.

Note: any models using the HPC solver in conjunction with cell width factors (CWF) should be upgraded to the 2023-03-AD build.

5.9.5 Extra Information in XF Filenames

Build 2023-03-AD adds the data type to the XF file name for raster input files read in with the “Read Grid” command. This occurs for all “Read Grid” options (e.g. soil, material, gwd, code, etc.) except for Zpts. This prevents a potential issue when multiple Read Grid” commands use the same dataset but sample the data at different locations. For example, materials are sampled at cell faces and centres, whilst soils are only sampled at cell centres.

5.9.6 Bug Fix for Wide Lines

Build 2023-03-AD fixes an issue introduced in the 2023-03-AC build when using a “wide” line (width attribute >1.5 times the cell size) in the layered flow constriction (2d_lfcsh) or the evacuation routes (2d_zshr) file format. For build 2023-03-AC this could cause a Fortran error to occur and the TUFLOW simulation to disappear with no log file output.

5.9.7 Enhancement for HPC and Quadtree Restart Files

Build 2023-03-AD adds functionality to restart files to allow data fields to be ignored. To specify which fields to ignore a new command “Restart File Ignore Fields ==” can be set in the .tcf where the fields are any combination of:

  • Geometry (elevations and Manning’s n values)
  • Groundwater (groundwater depths and groundwater tracer concentrations)
  • Maximum (scalar and vector maximums; both values and times, minimum timestep)
  • Rainfall (cumulative rainfall, cumulative rainfall material losses and cumulative cell wet time)
  • TimeOutputCutoff (Time Output Cutoff; time of first inundation and cumulative time inundated)
  • Tracer (surface and groundwater tracer concentrations)
  • Velocity (velocity and turbulence values)
  • WaterLevel (water level)

For example: “Restart File Ignore Fields == Geometry Groundwater” will ignore the geometry and groundwater information in the restart file (for these, the values set in the control files are used).

By default (without the command above) the geometry information in the restart file is ignored and the .tgc information is used instead. See also HPC Restart Geometry == Restart File | {TGC} command. If the “Restart File Ignore Fields ==” command is included, but does not include geometry then message “WARNING 2902 -‘Restart File Ignore Field’ does not include geometry, overwriting geometry in .tgc with restart file” is issued.

Note: Only one of “Restart File Ignore Fields” or “HPC Restart Geometry” should be used, an error is given if both commands are present in a control file.

5.9.8 Quadtree - Removes One Parent Polygon Requirement (Fast Method)

Build 2023-03-AD removes the requirement that a nesting polygon can have no more than one parent polygon (i.e. a “level 3” polygon must only sit inside no more than one “level 2” polygon). This removes the occurence of “ERROR 2831 - More than 1 parent polygon for polygon with nesting level”.

The memory efficient method has not changed and is still contrained to no more than one parent polygon.

5.9.9 Bug Fix for No Time Series Output in run_stats.txt

Build 2023-03-AD fixes an issue that the run_stats.txt file is blank if only maximum map outputs were being written and the “Mass Balance Output Interval” was not specified.

5.9.10 Enhancement Automatic Recreation of Invalid XF Files

In previous versions, some incompatible XF files would result in TUFLOW stopping with the message to delete the XF file and rerun. Build 2023-03-AD modifies the code to automatically recreate the incompatible XF files.

5.9.11 Changes to Reported Timestep Efficiency

A minor change has been made to the calculation of model 2D efficiency when using HPC (including Quadtree). With 1D/2D linked models, HPC can be called to solve the 2D domain for a timestep that is smaller than what it can actually stably use. An instantaneous 2D efficiency value is computed that represents the ratio of actual 2D timestep to possible 2D timestep. The 2D efficiency value reported to console and log file was intended to represent the time weighted average of this number from the beginning of the simulation. If a 1D/2D linked model starts with a period of dry, the 2D efficiency can be expected to be low during the dry period due to the 1D timestep constraining the model, and then improve once the 2D domain became wet and the 2D timesteps became similar to the 1D timestep. However, there was an error in the calculation method and the reported efficiency value was remaining very low for the remainder of the simulation even though the model was actually running efficiently. This has been corrected and the reported 2D efficiency is now more representative for such models. This code change does not affect time stepping or results in any way.

5.9.12 Fix to Initial Groundwater Map Output Results with “GT” Boundaries

Build 2023-03-AD fixes an issue where the groundwater map outputs at the start of the simulation did not reflect the groundwater levels being applied at any groundwater-time (GT) boundaries. Subsequent map output were correct and this change does not affect the hydraulic computations.

5.10 2023-03-AE Minor Enhancements and Bug Fixes

5.10.1 Bug Fix for HPC Running on Multiple GPU/CPU

Build 2023-03-AE fixes a critical issue in the 2023-03-AD build when running HPC solver over multiple GPUs or multiple CPU threads (which is the default when solving on CPU). When processing water level and groundwater level boundaries (HT, HQ and GT type boundaries), the 2023-03-AD version could result in incorrect levels being applied at the boundary. This was dependent on which compute device the boundary was within. Any simulations using HPC with multiple GPUs or CPU threads using the 2023-03-AD release should upgrade to 2023-03-AE.

This issue did not affect Classic or Quadtree simulations.