View source for TUFLOW Stability Troubleshooting

= Common Questions Answered (FAQ)=
== How can I stabilise 2D boundary? ==
All boundaries:
* Use the latest TUFLOW release:
** The new cell size insensitive Wu turbulence scheme in TUFLOW HPC has become the default from 2020 release. The previous default, Smagorinsky viscosity formulation, could produce unrealistic eddies in the model when cell size got smaller than flow depth.
** Since the 2020 release all H boundaries including QT boundary adjusts the water level by the dynamic head when water is entering the model (a common approach in CFD modelling), which reduces the chance of spurious circulations caused by the boundary assumptions and/or schematisation of the boundary.
* External boundaries (e.g. HT, HQ, QT) should be snapped to the code layer.
* Boundaries should be digitised perpendicular to the flow and well away from the area of interest.
* Every flow path should have its own boundary.
* Rapid changes in elevation immediately adjacent to the boundary should be avoided, the terrain should be reasonably smooth. Z shape polygon can be used to smooth out the topography if required.
* Sufficient number of cells should be connected to the boundary in the main channel. TUFLOW Classic requires at least 3-4 cells and TUFLOW HPC 7-8 cells. Since 2020 release, HPC is using a non-slip boundary similar to Classic and will produce reasonable results with a minimum of 3-4 cells across a primary waterway.
* Using sharp edges and concave angles in boundary polylines should be avoided.
* Apply <font color="blue"><tt>Boundary Viscosity Factor </tt></font> command. For example, applying a factor of 2 will double the eddy viscosity coefficient along all external boundaries. Sensitivity testing should be carried out to confirm model results have not changed.
* Timestep adjustments:
** TUFLOW Classic - timestep should be between 1/2 to 1/5 seconds of the cell size in metres. Some models perform well at the higher range of the timestep, other models need to keep the timestep in the lower ranges
** TUFLOW HPC - most HPC models won't need timestep adjustment. In rare cases <font color="blue"><tt>Control Number Factor </tt></font> command can be used to lower the control number factor which controls the adaptive timestep.
* Increasing bed resistance or adding form losses can also help with stability due to the much higher resistive forces balancing the driving forces (gravity, inertia). This should only be done in rare cases and sensitivity testing should be carried out to confirm model results have not changed.
Specific boundaries:
* Downstream HQ boundaries:
** Should be digitised only at the location where the water is exiting the model, e.g. not around the whole perimeter of the model.
** When the downstream HQ boundary is unstable, the boundary line can be split into sections so that the channel provides a different HQ boundary than the floodplain. The reason this may work is that HQ boundaries work by cutting a cross section along the line and then producing a rating curve using the Manning's equation. If the HQ line is really broad, it may not be representative of what is happening locally at the channel.
* Upstream QT boundaries:
** QT boundaries use hidden 1D node which the flow is applied to, this is spread across the connected 2D cells assuming constant water level along the QT line, i.e. perpendicular to flow. In some locations, for example where divergent flowpaths are separated by a ridge, this may cause circulations.
** Standard 1D output can be written for the hidden 1D node when using <font color="blue"><tt>Reveal 1D Nodes </tt></font> <font color="red"><tt>==</tt></font><tt> ON</tt> command.
** Storage can be increased using the "a" attribute. Setting the attribute to 10 will double the storage, the default is 5.
** Unstable QT boundaries can be replaced by 2d_sa boundaries in some cases. Source area (SA) boundaries apply the flow on to the cell as a volume and let gravity pull the water downstream, they don't preserve momentum and will usually result in lower velocities. QT boundaries, when well behaved, will produce good flow distribution as they apply flow as a volume and momentum. For river boundaries, the preference is to use a 2D QT line, but either can be used. If SA boundary is used instead of QT boundary, it should be placed further upstream and sensitivity testing should be carried out to confirm there are no negative effects at the location of interest.
* HT boundaries:
** Set an initial water level so the model doesn't start completely dry. This can be done globally with <font color="blue"><tt>Set IWL </tt></font> command or locally with 2d_iwl polygon.

==How can I stabilise 1D features and their 1D/2D boundaries?==
=== 1D open channels including connected bridges and culverts ===
* Split or merge open channel sections - the general advice is to have the length of open channels about 3 to 5 times of their width. Merging very short channels will provide sufficient storage. Splitting long channels into shorter ones with more 1D nodes might smooth the water level slope and the simulated flow rate can become more stable. 
* Increase the storage area where required with 1d_na table or 1d_nwk ANA attribute with type NODE. The extra storage can cause a lag in a the hydrograph and sensitivity testing should be undertaken.
* Use a non-inertial open channel (SN) instead of the standard inertial channel (S) at the location of oscillations. For a non-inertial channel, the inertial terms are ignored which might help stabilise problematic S channels.  Removing the inertial terms is a common approach when for example supercritical flow is present.
* Poor digitisation and interpolation of water level lines (WLL) can cause questionable display of results. Review the spacing of water level lines, distance_to_A attribute for triangulation and if the WLLs are digitised within the HX lines. The calculated 1D results will be stretched across the WLL based on the cross section processed data and location where the 1d_nwk intersects the WLL.

=== 1D culverts ===
* Smooth out 2D topography at inlet and outlet to match culvert inverts. This is best to do with Z shape polygons.
* Lower the 2D topography upstream and downstream of the culvert, the DEM levels should not be elevated above the culvert’s inverts. If using a "Z" flag, this will only lower the cell centres and might not be sufficient in some cases. Z shape polygon is recommended as it will lower all elevation points within the polygon.
* Check that the number of SX cells connected upstream and downstream is the same or greater in flow width to the flow width of the 1D culvert. Review <u>[[Check_Files_1d_to_2d_bc | 1d_to_2d check file]]</u> if the connected cells are as intended. The flow through the culvert is determined from upstream and downstream water levels in the 2D and not from the volume of water entering the 1D/2D cells directly. The volume removed (or added) from the 2D is determined by the culvert hydraulics. Removing large volumes of water from small number of cells can have an exaggerated draw down effect at the SX cells which in turn will affect the flow through the culverts since the upstream water level is lower. Potentially the downstream water level can be higher which will also decrease the flow through the culvert.
* Connect cells that have a constant water level (perpendicular to flow) as the water level boundary will be averaged from the connected cells. Connecting cells that are not perpendicular to the flow could mean the average water level upstream of the culvert to be higher that in reality and downstream average water level will be lower.
* Multiply default SX boundary storage with the 'a' attribute.
* Use polygon SX for more stability, see further guidance <u>[[TUFLOW_1D2D_Boundary_Configuration_Guidance | here]]</u>. If using shapefiles, 2d_bc SX polygon should be read into TUFLOW on the same line as 2d_bc CN line separated by a vertical bar.
* Use Sub-Grid Sampling (SGS) to improve volume calculations upstream and downstream of the structure.

=== 1D pits and pipes ===
* Check that a sufficient number of SX cells are selected for the magnitude of the inflows. If it’s a relatively small 2D cell size and a large pit inflow (negative flow) or surcharge (positive flow) is applied to too few SX cells this will may cause instabilities (which is why TUFLOW selects more than one cell at a pit SX if the width of the pit exceeds the 2D cell size). Increasing the number of SX cells may help.

=== Notes for all features===
* Use the latest available TUFLOW release.
* Use Sub-Grid Sampling (SGS) if using HPC. This allows for more accurate calculations of flow and water level that transitions into the 1D features through the 1D/2D links.
* Double precision might be used, however this would cause models running slower and other measures are recommended to try first.
* Lower 1D timestep can be sensitivity tested, however the timestep should still remain within reasonable bounds. If the 1D timestep is required to be very small for stability reasons, usually other measures can be taken to improve the stability and consequently run time of the model.
* If using TUFLOW Classic, 2D timestep should be between 1/5 and 1/2 of the cell size in metres. Lowering 2D timestep within this range might be beneficial for stabilising 1D/2D links.

== My model reports very high mass balance error at the beginning, then it lowers. Is it unhealthy? ==
With a small number of wet cells in the model even a small erroneous volume can look large when reported as a percentage of mass balance error. Because there is a limited volume in the model, the error is a larger proportion. As more volume enters the model domain, it takes a much bigger error to be of the same proportion overall. Adding a little bit of water that should not be there to a teacup gives a big error in comparison to the total volume. Adding the same little bit of water (erroneous volume) into a lake is negligible.<br>