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:
- “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:
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:
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 “
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
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:
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:
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 “
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 “
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 “
![**Quadtree Thick Breakline Face Selection 2020-10-AF**](images/QDTThickBrk202010AF.png)
Figure 5.1: Quadtree Thick Breakline Face Selection 2020-10-AF
![**Quadtree Thick Breakline Face Selection 2023-03-AA**](images/QDTThickBrk202303AA.png)
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 “
5.7.7 Support Read GRID Zpts ADD Option for SGS Method C
The 2023-03 Release also supports the ADD option for the “
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
5.7.9 Error for TGC Command Read Grid IWL used in .tcf
As per the 2018 TUFLOW Manual, the “
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.:
However, if the final character is not a backslash then this is treated a prefix, e.g.:
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 (“
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
5.9.2 Bug Fix with Process All Grids Command
The TUFLOW control file command: “
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: “
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 “
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 “
- 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: “
By default (without the command above) the geometry information in the restart file is ignored and the .tgc information is used instead. See also
Note: Only one of “
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.
5.11 2023-03-AF Minor Enhancements and Bug Fixes
5.11.1 Bug Fix for Quadtree SGS xf files being unnecessarily locked for the entire simulation
Build 2023-03-AF fixes an issue where the SGS processed elevations (xf files) for quadtree models were not closed correctly causing the file to be locked for the whole simulation. Thi issue only affected Quadtree not HPC and SGS does not apply to classic. This could lead to issue with the locked file preventing other simulations from starting concurrently (has no effect if running models one at a time).
5.11.2 Removed limit of 1,000 soil types
Build 2023-03-AF removes the 1,000 soil type limit that existed previously. Soil types are now effectively unlimited, limited only by the amount of machine resources (or up to 1.7 billion or something).