View source for TUFLOW Version Backward Compatibility


=Backward Compatibility Change Register=

For a list of new features and changes for each TUFLOW release, refer to the <u>[https://docs.tuflow.com/classic-hpc/changelog/ TUFLOW Classic/HPC Changelog]</u> (for versions since 2023-03-AF). For versions 2023-03-AF and prior, see the relevant release notes in the <u>[https://www.tuflow.com/downloads/tuflow-classichpc-archive/ TUFLOW Downloads Archive]</u>. 

For backward compatibility and default changes, please see Chapter 18 (Default Changes) of the <u>[https://docs.tuflow.com/classic-hpc/manual/latest TUFLOW Manual]</u>.

=Frequently Asked Questions (FAQ)=
== Why are model results developed in an older release different to a newer release? ==
If comparing a Classic model with HPC, also check the <u>[[HPC_FAQ#Will_TUFLOW_HPC_and_TUFLOW_Classic_results_match.3F | Will TUFLOW HPC and TUFLOW Classic results match?]]</u> page in addition to this answer. <br>
In addition to the above, there are reasons why model results would be different between different TUFLOW releases, whether it is the Classic or HPC solver, as follows:
* General improvements and fine-tuning of the solution scheme, especially for the more complex hydraulic physical terms and situations such as: sub-grid turbulence representation; treatment of shocks (e.g. hydraulic jumps); and transitioning between sub-critical and super-critical flow on steep slopes.
* Some new functionality can cause a significant change in results.  For example:
** Sub-Grid Sampling (SGS) applied to an existing model that used a too coarse cell resolution in high flow areas of highly variable topography (relative to the 2D cell size).  SGS will greatly improve the model's ability to convey water accurately in these situations with vastly improved results.
** New default sub-grid turbulence scheme in the 2020 release of TUFLOW HPC that is cell size independent and allows modellers to use cell sizes much smaller than the flow depth across all scales from flume to large rivers. For more information on differences between Smagorinsky scheme (HPC releases up to 2020) and the Wu turbulence scheme (2020 onwards) see <u>[[HPC_FAQ#With_Wu_turbulence_scheme_being_the_new_default.2C_are_old_models_using_Smagorinsky_wrong.3F | here]]</u>.
* Changes to the default settings and values, e.g.:
**different default eddy viscosity formulation and/or coefficients,
**improved data pre-processing approaches such as sampling materials on cell mid-sides instead of cell centres,
** and many others.
** For backward compatibility the <font color="blue"><tt>Defaults</tt></font> <font color="red"><tt>== </tt></font> command is available to run old models on new releases to replicate past results (note, sometimes full backward compatibility cannot be catered for due to different code compiler and updates that can't be reverted, especially for several releases earlier).
* New features that use GIS attributes previously reserved (i.e. unused). If these attributes were not populated with the recommended “reserved” value (usually 0 or blank), then they can cause unpredictable results in later releases.
* Bug fixes noting that most bug fixes are input/output related and rarely affect the model's hydraulic calculations.
* Change in timestepping can also produce a small change in results. HPC uses the Runge-Kutta 4th order integrator, which is usually fairly insensitive to time step provided the model is running stably. However when a region is filled by flow that only just overtops an embankment, a 10 mm difference in water levels upstream of the embankment can create a much larger difference in levels downstream.  Hence, small differences in time-stepping (along with many other aspects of model setup) can trigger local differences in model results.
* Model orientation (if changed) could also mean slight change in results. This is mostly given by interpolating values from different calculation points. Every cell has nine calculation points. Based on the model origin, all or most of the calculation points would have different topography elevation sampled, which translates to slightly different results.
* If using 1D channel, possibly different cells have been selected as HX boundary and might have different elevations. This can be reviewed in <u>[[Check_Files_1d_to_2d_bc | 1d_to_2d check file]]</u>.

Generally, there should not be substantial differences as the fundamental equations being solved are unchanged and TUFLOW Classic and HPC solvers have always solved all the physical terms using a 2nd order spatial approach. The one exception is the turbulence (eddy viscosity) representation, which is the most complex and challenging to solve of all the physical terms (many 2D schemes simply omit this term). If significant differences (>10% of depth change across the whole model) are observed then it’s most likely due to the first four dot points above. To identify in which release(s) the significant changes occurred, the model can be run with the latest build and for past releases. The changes for each release are documented in their release notes. Past releases and release notes are all available [https://www.tuflow.com/downloads/tuflow-classichpc-archive/. here]. Once the exact release where the changes occurred is tracked down, individual features can be turned off to narrow down the cause.<br>

The recommendation is usually for new or reworked models to use the newest build to take advantage of the latest features and enhancements, some level of calibration might be required for reworked models. The new TUFLOW executable is not different from the previous ones in the meaning that any existing model should be re-calibrated if there are available calibration data. However, particularly if a model is already calibrated, using prior builds of TUFLOW or winding back default settings using <font color="blue"><tt>Defaults</tt></font> <font color="red"><tt>== </tt></font> command is considered reasonable for established models that are to be used for minor tasks where an update of the model would not be cost effective.<br>

== How can differences in model results between TUFLOW builds be investigated? ==
Running TUFLOW on a later build from which it was originally calibrated will not necessarily produce the same results, as discussed in <u>[[TUFLOW_Version_Backward_Compatibility#Why_are_model_results_developed_in_an_older_release_different_to_a_newer_release.3F | Why are model results developed in an older release different to a newer release?]]</u>.

The following is an example of steps that can be taken when upgrading a TUFLOW model’s executable build, checking for consistency to original results each time. 
<ol>
<li> Confirm you are able to run the original model with the original build that would have been used to initially produce results.
* This may be particularly relevant when a model has been externally supplied, for example from a government body. 
* Confirm if reproduced results are consistent with supplied results.
<li> Run the original model with the newer build, along with a relevant <font color="blue"><tt>Defaults</tt></font> <font color="red"><tt>== </tt></font> command (e.g. <font color="blue"><tt>Defaults</tt></font> <font color="red"><tt>== </tt></font> Pre 2011 when the original build was 2010-10).
* Any differences in results compared to the original results may highlight if there are any changes over time where no backward compatibility had been provided for. 
<li> Run the original model with the newer build, and without the <font color="blue"><tt>Defaults</tt></font> <font color="red"><tt>== </tt></font> command.
* This is more likely to see changes in results compared to the original results, which may require justification to the client or resolution by investigating, isolating and remedying the causes, especially if recalibration is not intended as a subsequent step.
<li> Iteratively run the original model with the newer build, stepping through the different release version options for <font color="blue"><tt>Defaults</tt></font> <font color="red"><tt>== </tt></font> command.
* This will allow the modeller to investigate and isolate what changes to TUFLOW builds may be affecting results, and when changes appear.
* Then, individually reverting settings that make up a Default group (see Chapter 18 of the <u>[https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]</u>).
* This can help isolate the primary drivers for any differences in results.
* The <u>[https://docs.tuflow.com/classic-hpc/changelog// TUFLOW Classic/HPC Changelog]</u> accompanying build releases are also a key reference. 
<li> Develop new improved or updated model version, with the newer build (and any grouped or individual defaults that are deemed necessary to retain from the iterative testing in the prior step).
*Continue to verify results against the original results as you then iteratively add in or update to any newer functionality or formats that may be available in the later build, a good quality assurance check that changes are behaving as expected.
</ol>
<br>
{{Tips Navigation
|uplink=[[TUFLOW_Modelling_Guidance | Back to TUFLOW Modelling Guidance]]
}}