Add Validation Document to repository (#129)

* Adding validation document
* Process ValDoc review comments by JS

* Update user manual based on feedback by WdL
* page-by-page inclusion of memo Sieben (2024) ... and include a reference to that appendix/memo.

* Add validation case Gendtse Waard (ValDoc Sec 4.1) - added to testbench
Update script to include backward compatibility examples (ValDoc Sec 2.1 & 2.2) in distribution

* Add references to example folders in the user manual and validation document.

* Update version to patch 3.1.1 and update the release notes.

BuildScripts/BuildDfastmi.bat

@@ -55,6 +55,6 @@ START /B /WAIT poetry run nuitka ^
  %cmd_box_args%
 
 rem include example files into the distribution
-xcopy /E examples dfastmi.dist\examples\
+call BuildScripts\Collect_Examples.bat
 
 rem end of build

BuildScripts/Collect_Examples.bat

@@ -0,0 +1,30 @@
+@echo off
+setlocal EnableDelayedExpansion
+
+set target_root=dfastmi.dist
+
+rem ===============================================
+echo Copying the backward compatibility tests ...
+set target_compatibility=%target_root%\examples_compatibility
+echo Creating %target_compatibility%
+mkdir %target_compatibility%
+
+set target=%target_compatibility%\01 - Gendtse Waard\
+echo Copying case to %target%
+mkdir "%target%"
+rem Using "c01.cf?" instead of "c01.cfg" to make sure that copy prints the name of the file copied
+copy "tests\c01 - GendtseWaardNevengeul\c01.cf?" "%target%"
+copy "tests\c01 - GendtseWaardNevengeul\*.xyz" "%target%"
+
+set target=%target_compatibility%\02 - De Lymen\
+echo Copying case to %target%
+mkdir "%target%"
+rem Using "c02.cf?" instead of "c02.cfg" to make sure that copy prints the name of the file copied
+copy "tests\c02 - DeLymen\c02.cf?" "%target%"
+copy "tests\c02 - DeLymen\*.xyz" "%target%"
+
+
+rem ===============================================
+echo.
+echo Copying the examples/validation cases ...
+xcopy /E examples %target_root%\examples\

dfastmi/__init__.py

@@ -34,6 +34,6 @@
 
 from typing import Any, List
 
-__version__ = "3.1.0"
+__version__ = "3.1.1"
 
 __all__: List[Any] = []

dfastmi/messages.UK.ini

@@ -7,28 +7,27 @@ The option 'reduce_output' is active.
 D-FAST Morphological Impact implements an algorithm to estimate the local
 morphological effects of a local intervention (i.e. an adjustment to the
 river). The conceptual framework was originally introduced in
-    "RWS-WD memo WAQUA vuistregel 20-10-08"
+    "RWS-WD memo WAQUA vuistregel (Sieben, 2010)"
 but it has been extended and improved over the years. Check the user manual
 for the details of the currently implemented algorithm.
 
-It is based on an estimation of the equilibrium bed level changes in the main
-channel that would occur eventually when river maintenance would not be
-adjusted.
+It is based on an estimation of the equilibrium bed level changes in the
+main channel that would occur eventually when river maintenance would not
+be adjusted.
 
 The effect is expressed as:
 
     year-averaged bed level change [m] without dredging
     maximum bed level change [m] without dredging
     minimum bed level change [m] without dredging
 
-By means of these estimates bottlenecks can be identified. The results are not
-suitable for direct estimation of the impact on the maintenance of the
+By means of these estimates bottlenecks can be identified. The results are
+not suitable for direct estimation of the impact on the maintenance of the
 navigation channel!
 
-The combination of the total equilibrium sedimentation volume and the yearly
-sediment load of the river determines the period over which the equilibrium
-can be reached.
-
+The combination of the total equilibrium sedimentation volume and the
+yearly sediment load of the river determines the period over which the
+equilibrium can be reached.
 
 This is version {version}.
 

docs/chapters/application.tex

@@ -7,6 +7,17 @@ \chapter{Steps in the analysis}\label{Chp:steps}
 Verify that it is appropriate to use \dfmi instrument; see \autoref{Chp:Guidance}.
 Determine the branch and reach on which it is located; use the \dfmi GUI for this\footnote{The reaches are specified in the GUI both by a descriptive name and by an approximate indication of the river chainage.
 Follow item \ref{reach_bnd} of \autoref{Sec:Limitations} if an intervention is located across or near a branch/reach boundary.}.
+\dfmi is currently configured to support the evaluation of interventions in the following reaches:
+\begin{itemize}
+\item Bovenrijn (Rkm 859-867)
+\item Waal (Rkm 868-951)
+\item Pannerdensch-Kanaal (Rkm 868-879)
+\item Nederrijn (Rkm 880-922)
+\item Lek (Rkm 923-989)
+\item IJssel (Rkm 880-1000)
+\item Merwede (Rkm 951-980)
+\item Meuse (Rkm 16-227)
+\end{itemize}
 Determine the threshold discharge $Q_\text{thr}$ (at Lobith/Borgharen) at which the intervention (indirectly) starts to influence the flow pattern in the main channel.
 The threshold discharge is critical for determining the fraction of the year that the intervention influences the flow, and hence the duration over which the bed level difference (compared to the reference situation) can develop.
 As a result, this value is critical for determining the total volume of sedimentation (or erosion) that can be expected after one year.
@@ -27,24 +38,20 @@ \chapter{Steps in the analysis}\label{Chp:steps}
 \end{tabular}
 \newline
 \newline
-These flow conditions have been pre-configured for the latest \dflowfm schematizations.
+These flow conditions have been pre-configured for the latest \dflowfm schematizations\footnote{The rationale behind the selection of these flow conditions and the associated bed celerity values is given in \autoref{Sec:memo_Sieben24}.}.
 It is not necessary to run simulations for conditions at which the intervention doesn't influence the flow patterns (i.e.~discharges associated with stagnant conditions due to closure of barriers, and discharges below the intervention specific $Q_\text{thr}$).
 At this stage, \dfmi already reports the impacted length (`aanzandingslengte'), which is the distance over which a bed level change can built up during the period that the discharge of the river is above the threshold discharge.
+\dfmi is not suitable for interventions that only (start to) have a noticeable effect at (or above) the highest discharge.
 
 \item Perform for each condition the hydrodynamic simulations for both the reference situation and the situation with intervention.
 Verify that
 \begin{itemize}
 \item the \dflowfm results are stable
-\item the intervention is properly represented on the mesh used (check a.o. proper alignment of groynes and levees, channel shape and bed roughness)
+\item the intervention is properly represented on the mesh used (check a.o.~proper alignment of groynes and levees, channel shape and bed roughness)
 \item all simulations use the same base mesh (changes in dry areas may result in slight differences in the mesh effectively used)
 \item there is a visible difference in the velocities in the main channel between the simulations with and without intervention
 \end{itemize}
-For steady state conditions, it is preferred to use the mean flow conditions over a certain period to suppress any instabilities and fluctuations in the instantaneous flow conditions.
-These results can be obtained by using the Fourier option of \dflowfm.
-For this purpose, a standardized Fourier input file \file{fourier\_last\_s.fou} is included that contains the following configuration:
-\vspace{\baselineskip}
-\verbfilenobox[\scriptsize]{figures/fourier_last_s.fou}
-\vspace{\baselineskip}
+See \autoref{Sec:SteadyState} for recommendations regarding steady-state results.
 
 \item Run \dfastmi to compute for each grid point in the main channel, the following three variables
 
@@ -72,3 +79,14 @@ \chapter{Steps in the analysis}\label{Chp:steps}
 If there are disjunct sedimentation areas, the accumulation should be carried out for each of the areas individually.
 If areas are shorter than the impacted length, then the total equilibrium impact can be reached within one year.
 \end{enumerate}
+
+\section{How to get steady-state results?}\label{Sec:SteadyState}
+
+The dynamic solver of \dflowfm is used to obtain steady-state results by providing a constant forcing over a suitably long simulation period.
+However, even with a constant forcing some fluctuations may remain in the computed flow fields, e.g.~due to natural formation and shedding of eddies, and sensitivity of numerical formulations related to for instance drying-flooding.
+Therefore, it is preferred to use, for steady-state conditions, the mean flow conditions over a certain period to suppress any instabilities and fluctuations in the instantaneous flow conditions.
+These results can be obtained by using the Fourier option of \dflowfm.
+For this purpose, a standardized Fourier input file \file{fourier\_last\_s.fou} is included that contains the following configuration:
+\vspace{\baselineskip}
+\verbfilenobox[\scriptsize]{figures/fourier_last_s.fou}
+\vspace{\baselineskip}

docs/chapters/example.tex

@@ -7,6 +7,8 @@ \chapter{Examples}
 
 \section{Example 1: secondary channel along the Nederrijn}
 
+\emph{The input files of this case are included in the distribution under \file{examples/01 - Palmerswaard}.}
+
 For this first example, we compare the results of \dfastmi with the results of a morphological simulation using Delft3D-FLOW.
 For consistency the \dfastmi analysis was performed using the hydrodynamic results of Delft3D-FLOW\footnote{Since \dfastmi expects \dflowfm results in netCDF UGRID format, the results were converted to the appropriate file format by means of \texttt{sim2ugrid}, see \autoref{Chp:Sim2Ugrid}.}.
 
@@ -66,20 +68,24 @@ \section{Example 1: secondary channel along the Nederrijn}
 
 \verbfilenobox[\scriptsize]{../examples_references/01 - Palmerswaard/output/report.txt}
 
-\autoref{Palmers_mor} shows the results of a reference morphology simulation using Delft3D 4 (for details, see \citet{GiriJagers2022}).
-The figure shows the morphological evolution of the Delft3D simulation.
-The overall \dfastmi results compare well with the long term (12yr) Delft3D simulation although the asymmetry downstream of the main sedimentation patch differs.
+\autoref{Palmers_mor} shows the results side by side of a reference morphology simulation using Delft3D 4 (for details, see \citet{GiriJagers2022}) and the \dfmi version 3 analysis.
+The overall \dfmi results compare well with the long term (\SI{12}{\year}) Delft3D simulation although the asymmetry downstream of the main sedimentation patch differs.
 
 \begin{figure}[H]
-\center
-\includegraphics[width=\textwidth]{figures/Palmers_mor.png}
-\caption{The bed-level difference between the variant and the reference after 1, 5 and 12 years of morphological simulation.}
+\includegraphics[width=\columnwidth/2]{figures/Palmerswaard_delft3d.png}
+\includegraphics[width=\columnwidth/2]{figures/Palmerswaard_dfastmi.png}
+%\fbox{\parbox{\columnwidth}{\todo{Results to be plotted side-by-side.}}}
+\caption{Long-term morphological impact as obtained from a 12 year morphological simulation (left) and as obtained from \dfmi version 3 (right).
+Visualized using QUICKPLOT.}
 \label{Palmers_mor}
 \end{figure}
 
 
+
 \section{Example 2: secondary channel along the Pannerdensch Kanaal}
 
+\emph{The input files of this case are included in the distribution under \file{examples/02 - Panner\-densch Kanaal}.}
+
 For this second example, we follow the same approach as example 1: we compare the results of \dfastmi with the results of a morphological simulation using Delft3D-FLOW.
 The model was based on the DVR model, but the domain was reduced to focus mainly on the Pannerdensch Kanaal \citep{BomLeeuwen2020}.
 Because of the two bifurcations upstream and downstream, it still included parts of all the branches (Bovenrijn, Pannerdensch Kanaal, Waal, Nederrijn and IJssel).
@@ -125,13 +131,14 @@ \section{Example 2: secondary channel along the Pannerdensch Kanaal}
 
 \verbfilenobox[\scriptsize]{../examples_references/02 - Pannerdensch Kanaal/output/report.txt}
 
-\autoref{Pannerden_mor} shows the results of a reference morphology simulation using Delft3D 4 (for details, see \citet{GiriJagers2022}).
-The figure shows the morphological evolution of the Delft3D simulation.
-The overall \dfastmi results compare well with the long term (15yr) Delft3D simulation although \dfmi suggests sedimentation in the centre of the channel downstream of the main sedimentation area whereas the morphological simulation doesn't show that behaviour.
+\autoref{Pannerden_mor} shows the results side by side of a reference morphology simulation using Delft3D 4 (for details, see \citet{GiriJagers2022}) and the \dfmi version 3 analysis.
+The overall \dfmi results compare well with the long term (\SI{15}{\year}) Delft3D simulation although \dfmi suggests sedimentation in the centre of the channel downstream of the main sedimentation area whereas the morphological simulation doesn't show that behaviour.
 
 \begin{figure}[H]
-\center
-\includegraphics[width=\textwidth]{figures/Pannerden_mor.png}
-\caption{The bed-level difference between the variant and the reference after 1 and 15 years of morphological simulation.}
+\includegraphics[width=\columnwidth/2]{figures/Pannerden_delft3d.png}
+\includegraphics[width=\columnwidth/2]{figures/Pannerden_dfastmi.png}
+%\fbox{\parbox{\columnwidth}{\todo{Results to be plotted side-by-side.}}}
+\caption{Long-term morphological impact as obtained from a 12 year morphological simulation (left) and as obtained from \dfmi version 3 (right).
+Visualized using QUICKPLOT.}
 \label{Pannerden_mor}
 \end{figure}

docs/chapters/file_formats.tex

@@ -142,28 +142,27 @@ \subsubsection*{Example}
     D-FAST Morphological Impact implements an algorithm to estimate the local
     morphological effects of a local intervention (i.e. an adjustment to the
     river). The conceptual framework was originally introduced in
-        "RWS-WD memo WAQUA vuistregel 20-10-08"
+        "RWS-WD memo WAQUA vuistregel (Sieben, 2010)"
     but it has been extended and improved over the years. Check the user manual
     for the details of the currently implemented algorithm.
     
-    It is based on an estimation of the equilibrium bed level changes in the main
-    channel that would occur eventually when river maintenance would not be
-    adjusted.
+    It is based on an estimation of the equilibrium bed level changes in the
+    main channel that would occur eventually when river maintenance would not
+    be adjusted.
     
     The effect is expressed as:
     
         year-averaged bed level change [m] without dredging
         maximum bed level change [m] without dredging
         minimum bed level change [m] without dredging
     
-    By means of these estimates bottlenecks can be identified. The results are not
-    suitable for direct estimation of the impact on the maintenance of the
+    By means of these estimates bottlenecks can be identified. The results are
+    not suitable for direct estimation of the impact on the maintenance of the
     navigation channel!
     
-    The combination of the total equilibrium sedimentation volume and the yearly
-    sediment load of the river determines the period over which the equilibrium
-    can be reached.
-    
+    The combination of the total equilibrium sedimentation volume and the
+    yearly sediment load of the river determines the period over which the
+    equilibrium can be reached.
     
     This is version {version}.
     

docs/chapters/guidance.tex

@@ -57,6 +57,7 @@ \section{Assumptions and limitations}\label{Sec:Limitations}
 
 \item Interventions should be properly resolved on the \dflowfm mesh.
 The discharges used by \dfmi should give a balanced representation of the influence of the intervention on the flow patterns.
+\dfmi is not suitable for interventions that only (start to) have a noticeable effect at (or above) the highest discharge.
 
 \item \dfastmi is not yet suited for tidally influenced areas.
 See \autoref{Sec:Tides}.

docs/chapters/intro.tex

@@ -1,7 +1,7 @@
 \chapter{Introduction}
 
 This manual describes \dfastmi version 3 which provides a rapid, first estimate of the bed level changes to be anticipated in the main channel due to the implementation of local river adjustments outside the main channel (so-called interventions).
-The program is a successor to the WAQMORF and \dfastmi version 2 programs that implemented the rule of thumb developed in the context of Rijkswaterstaat programme Stroomlijn by \citep{Sieben2008}.
+The program is a successor to the WAQMORF and \dfastmi version 2 programs that implemented the rule of thumb developed in the context of Rijkswaterstaat programme Stroomlijn by \citet{Sieben2010}.
 This new version follows the same conceptual approach, but uses a fixed set of flow conditions independent of the intervention instead of three intervention-dependent flow conditions.
 It assumes a seasonal discharge variation that can be represented by means of series of flow conditions.
 Bed level changes outside the immediate vicinity of influence of the intervention are ignored in this analysis.
@@ -56,21 +56,21 @@ \chapter{Introduction}
 
 \begin{Verbatim}[frame=single, framesep=5pt]
 D-FAST Morphological Impact implements an algorithm to estimate the local
-morphological effects of a local intervention (i.e. an adjustment to the river).
-The conceptual framework was originally introduced in
-    "RWS-WD memo WAQUA vuistregel 20-10-08"
+morphological effects of a local intervention (i.e. an adjustment to the
+river). The conceptual framework was originally introduced in
+    "RWS-WD memo WAQUA vuistregel (Sieben, 2010)"
 but it has been extended and improved over the years. Check the user manual
 for the details of the currently implemented algorithm.
 
 It is based on an estimation of the equilibrium bed level changes in the
 main channel that would occur eventually when river maintenance would not
 be adjusted.
 
-The effect is expressed in [m] as:
+The effect is expressed as:
 
-    year-averaged bed level change without dredging
-    maximum bed level change without dredging
-    minimum bed level change without dredging
+    year-averaged bed level change [m] without dredging
+    maximum bed level change [m] without dredging
+    minimum bed level change [m] without dredging
 
 By means of these estimates bottlenecks can be identified. The results are
 not suitable for direct estimation of the impact on the maintenance of the