Merge branch '34-review-update-dia-chapter' into 'main'

Resolve "Review/update DIA chapter"

Closes #34

See merge request !47

latex/NEMO/subfiles/chap_DIA.tex

@@ -21,7 +21,7 @@
     \hline
     {\em   5.0} &
         {\em D. Calvert, A. Coward and S. M{\" u}ller} &
-            {\em General revisions; addition of \autoref{sec:DIA_diamlr}} \\
+            {\em General revisions; addition of \autoref{sec:DIA_diamlr}; expansion of \autoref{sec:DIA_dia25h}} \\
     {\em   4.0} & {\em ...} & {\em ...} \\
     {\em   3.6} & {\em ...} & {\em ...} \\
     {\em   3.4} & {\em ...} & {\em ...} \\
@@ -1710,7 +1710,7 @@ variable named \texttt{vosaline} in a file named \textit{sali\_ref\_clim\_monthl
 This data must be provided as a monthly climatology; \ie\ the file's time coordinate must have a length of 12.
 
 %% =================================================================================================
-\section[Tidal harmonic and generic multiple-linear-regression analysis (\forcode{diamlr.F90})]{Tidal harmonic and generic multiple-linear-regression analysis (\protect\mdl{diamlr})}
+\section[Tidal harmonic and generic multiple-linear-regression analysis (\textit{diamlr.F90})]{Tidal harmonic and generic multiple-linear-regression analysis (\protect\mdl{diamlr})}
 \label{sec:DIA_diamlr}
 
 Functionality for multiple-linear-regression (MLR) analysis of arbitrary output fields, using regressors that are a function of the continuous model time, is available as a diagnostic option of \NEMO.
@@ -1723,33 +1723,33 @@ The MLR analysis is activated by defining an empty file-group entry
 \begin{xmllines}
    <file_group id="diamlr_files" output_freq="<output frequency>" enabled=".TRUE." />
 \end{xmllines}
-in the XIOS configuration, where \xmlcode{<output frequency>} specifies the temporal resolution of the intermediate output: if defined, this file group will be populated during model initialisation.
+in the XIOS configuration, where \texttt{<output frequency>} specifies the temporal resolution of the intermediate output: if defined, this file group will be populated during model initialisation.
 Other prerequisite XIOS-configuration elements (regressors and the time variable) are pre-defined in the default XIOS configuration file \path{./cfgs/SHARED/field_def_nemo-oce.xml}, and can be modified if required.\par
 
-Regressors are defined and enabled within the XIOS field group \xmlcode{<field_group id="diamlr_fields">} in the form of individual fields that are computed from variable \xmlcode{diamlr_time} as
+Regressors are defined and enabled within the XIOS field group \xmlcode{<field_group id="diamlr_fields">} in the form of individual fields that are computed from the spatially uniform field \texttt{diamlr\_time} as
 \begin{xmllines}
    <field id="diamlr_r<mmm>" field_ref="diamlr_time" expr="<expression>" enabled=".TRUE." comment="<comment>" />,
 \end{xmllines}
-where \xmlcode{"<mmm>"} refers to a 3-digit identification number, \xmlcode{"<expression>"} is a functional expression, \xmlcode{"<comment>"} an arbitrary string (which may be utilised to pass information to post-processing utilities), and \xmlcode{"diamlr_time"} refers to the continuous model time in seconds.
-For the functional expression, XIOS requires the specified reference \xmlcode{diamlr_time} to be included; therefore, in order to obtain a constant expression for fitting an intercept, \xmlcode{diamlr_time^0} can be chosen.
-The model time \xmlcode{"diamlr_time"} corresponds to module variable \forcode{adatrj} of module \mdl{dom\_oce} and is defined in module \mdl{daymod}; its continuity across model restarts depends on a selection made in \nam{dom}{dom}.
-Similarly, a XIOS field \xmlcode{<field>} can be selected for MLR analysis through the definition of a field
+where \texttt{<mmm>} is a 3-digit identification number, \texttt{<expression>} a functional expression, and \texttt{<comment>} an arbitrary string (which may be utilised to pass information to post-processing utilities); field \texttt{diamlr\_time} contains the continuous model time in seconds.
+In the functional expression, XIOS requires the specified reference field \texttt{diamlr\_time} to be included; therefore, in order to obtain a constant expression for fitting an intercept, \texttt{diamlr\_time\^{}0} can be chosen.
+The model time \texttt{diamlr\_time} corresponds to module variable \forcode{adatrj} of module \mdl{dom\_oce} and is defined in module \mdl{daymod}; its continuity across model restarts depends on a selection made in \nam{dom}{dom}.
+Similarly, a XIOS field \texttt{<field name>} can be selected for MLR analysis through the definition of a new field
 \begin{xmllines}
-   <field id="diamlr_f<nnn>" field_ref="<field>" enabled=".TRUE." />
+   <field id="diamlr_f<nnn>" field_ref="<field name>" enabled=".TRUE." />
 \end{xmllines}
-in field group \xmlcode{<field_group id="diamlr_fields">}, where \xmlcode{<nnn>} is a 3-digit identification number.\par
+in field group \xmlcode{<field_group id="diamlr_fields">}, where \texttt{<nnn>} is a 3-digit identification number.\par
 
 For the purpose of tidal harmonic analysis, two orthogonal regressors per analysed tidal-constituent signal need to be defined in order to fit both the amplitude and phase of the corresponding harmonic, typically a sine and cosine function with identical argument.
 Further, regressor configurations can be equipped with placeholders to refer to the frequency, phase, and amplitude of each of the constituents available and evaluated for tidal forcing of the model. In particular:
 \begin{description}
-   \item [\xmlcode{__TDE_<constituent>_omega__}] \hfill \\
+   \item [\texttt{\_\_TDE\_<constituent>\_omega\_\_}] \hfill \\
       refers to the angular velocity (in units of rad s$^{-1}$);
-   \item [\xmlcode{__TDE_<constituent>_phase__}] \hfill \\
+   \item [\texttt{\_\_TDE\_<constituent>\_phase\_\_}] \hfill \\
       refers to the phase, including the nodel correction at the beginning of the model run (in units of rad); and
-   \item [\xmlcode{__TDE_<constituent>_amplitude__}] \hfill \\
+   \item [\texttt{\_\_TDE\_<constituent>\_amplitude\_\_}] \hfill \\
       refers to the equilibrium-tide amplitude (in units of m)
 \end{description}
-of tidal constituent \xmlcode{<constituent>}.
+of tidal constituent \texttt{<constituent>}.
 During model initialisation, these placeholders are automatically substituted with the corresponding model-computed values for the respective tidal constituent.\par
 
 A default set of regressors relevant for tidal harmonic analysis has been pre-defined (see \path{./cfgs/SHARED/field_def_nemo-oce.xml}) and can be redefined. An example of such a redefinition can be found in the AMM12 reference configuration, in file \path{./cfgs/AMM12/EXPREF/context_nemo.xml}.\par
@@ -1760,9 +1760,9 @@ Internally, during model initialisation, the initial XIOS configuration for MLR
 The resulting intermediate output consists of fields of scalar products between each regressor and the values of the fields selected for MLR analysis, as well as of scalar products between each regressor-regressor pair, all sampled at the configured interval.
 For the final analysis only the scalar products over the analysis time span are required, thus the intermediate output can be freely subset or combined (added) along its time dimension to select the analysis window (which enables analyses across multiple restart segments) during post-processing.\par
 
-The total number of intermediate output variables depends on the number of analysed fields ($n_{f}$) and the number of regressors ($n_{r}$) (for tidal analysis, $n_{r} = 2n_{c}+1$, \ie\ twice the number of tidal constituents, $n_{c}$, plus one regressor to fit the intercept) and amounts to $n_{f} n_{r} + 2 n_{r}^{2} - n_{r}$ (of which $2 n_{r}^2 - n_{r}$ variables are scalar time series). These output variables are written to output files labelled with \path{diamlr_scalar}, which contain the regressor-regressor scalar products, and with \path{diamlr_grid_<grid_type>}, which contain the regressor-diagnostic scalar-product fields for the fields defined on a grid of type \path{<grid_type>}.\par
+The total number of intermediate output variables depends on the number of analysed fields ($n_{f}$) and the number of regressors ($n_{r}$) (for tidal analysis, $n_{r} = 2n_{c}+1$, \ie\ twice the number of tidal constituents, $n_{c}$, plus one regressor to fit the intercept) and amounts to $n_{f} n_{r} + 2 n_{r}^{2} - n_{r}$ (of which $2 n_{r}^2 - n_{r}$ variables are scalar time series). These output variables are written to output files labelled with \path{diamlr_scalar}, which contain the regressor-regressor scalar products, and with \path{diamlr_grid_<grid_type>}, which contain the regressor-diagnostic scalar-product fields for the fields defined on a grid of type \texttt{<grid\_type>}.\par
 
-For the computation of regression coefficients from previously generated intermediate output files, the rudimentary script \path{./tools/DIAMLR/diamlr.py} can be used. This script is provided as a simple example of the final analysis step: it processes suitable intermediate-output files by adding all available time slices and by computing regression coefficients for all available analysed fields and for all or a subset of the regressors identified from the content of the intermediate-output files. To complete a tidal harmonic analysis, the pairs of regression coefficients associated with each of the tidal constituents selected for analysis (the \xmlcode{comment} attribute could be used for identifying such pairs) could in turn be converted into maps of amplitudes and phases.\par
+For the computation of regression coefficients from previously generated intermediate output files, the rudimentary script \path{./tools/DIAMLR/diamlr.py} can be used. This script is provided as a simple example of the final analysis step: it processes suitable intermediate-output files by adding all available time slices and by computing regression coefficients for all available analysed fields and for all or a subset of the regressors identified from the content of the intermediate-output files. To complete a tidal harmonic analysis, the pairs of regression coefficients associated with each of the tidal constituents selected for analysis (the \texttt{comment} attribute could be used for identifying such pairs) could in turn be converted into maps of amplitudes and phases.\par
 
 %% =================================================================================================
 \section{Other diagnostics}
@@ -1822,19 +1822,26 @@ configuration file: \mdl{diaar5} diagnostics are listed under \xmlcode{<!-- vari
 headers, while \mdl{diaptr} diagnostics are listed within the \xmlcode{<field_group id="diaptr" >} element.
 
 %% =================================================================================================
-\subsection{25 hour mean output for tidal models}
+\subsection[De-tided diagnostic output from tidal models (\textit{dia25h.F90}, \textit{diadetide.F90})]{De-tided diagnostic output from tidal models (\protect\mdl{dia25h}, \protect\mdl{diadetide})}
+\label{sec:DIA_dia25h}
 
-\begin{listing}
-  \nlst{nam_dia25h}
-  \caption{\forcode{&nam_dia25h}}
-  \label{lst:nam_dia25h}
-\end{listing}
+\subsubsection[25-hour averages (\textit{dia25h.F90})]{25-hour averages (\protect\mdl{dia25h})}
+
+Modelled fields of potential temperature, salinity, SSH, velocity, vertical diffusivity and viscosity, TKE, and the mixing length can be approximately de-tided by crudely (fully) removing the signal of the M2 (S2) tidal constituent.
+This operation is carried out by the \mdl{dia25h} module by averaging 25 instantaneous values at one-hour intervals that span consecutive periods of 24 model hours (\ie\ the model state at the boundaries of such sampling windows is accounted for in both adjacent averages).
+As a consequence of this method of averaging 25 hourly values, the least common multiple of the time-step length \np{rn_Dt}{rn\_Dt} and 3600 s is required to be 3600 s.
+This diagnostic is activated when any of the available daily 25-hour-average output fields is selected in the XIOS model-output configuration: \texttt{temper25h}, \texttt{salin25h}, \texttt{ssh25h}, \texttt{vozocrtx25h}, \texttt{vomecrty25h}, \texttt{vovecrtz25h}, \texttt{avt25h}, \texttt{avm25h}, \texttt{tke25h}, or \texttt{mxln25h}.
+
+\subsubsection[Generic de-tiding of model output (\textit{diadetide.F90}, experimental)]{Generic de-tiding of model output (\protect\mdl{diadetide}, experimental)}
+
+A more generic alternative to the de-tiding option provided by module \mdl{dia25h} is available with module \mdl{diadetide};
+this option, however, has not been fully developed and well tested, and therefore should be considered to be an {\em experimental} feature and used with care.
+Like for the \mdl{dia25h} implementation, the current version of this alternative de-tiding option computes daily averages with an averaging window that corresponds to twice the M2 tidal period;
+in contrast to module \mdl{dia25h}, the averaging procedure is more accurate for sufficiently small time steps, the method can be used with an arbitrary time-step length, and it can be applied to analyse arbitrary output fields available for XIOS-based model output.
 
-% TODO: Needs more info- e.g. timestep must be a multiple of 3600s
-The \mdl{dia25h} module computes a crudely detided M2 signal by obtaining a 25 hour mean.
-The 25 hour mean is available for daily runs by summing up the 25 hourly instantananeous hourly values from
-midnight at the start of the day to midnight at the day end.
-This diagnostic is activated by setting \np[=.true.]{ln_dia25h}{ln\_dia25h} in the \nam{_dia25h}{\_dia25h} namelist.
+An example of the application of the de-tiding option provided by module \mdl{diadetide} has been included in the AMM12 reference configuration.
+The corresponding activation can be found in the XIOS file group \texttt{diadetide\_files} defined in file \path{cfgs/AMM12/EXPREF/context_nemo.xml}.
+Implementation details (in particular the computation of the averaging weights) can be found in module \mdl{diadetide}.
 
 %% =================================================================================================
 \subsection{Courant numbers}