Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_ASM.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_ASM.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_ASM.tex	(revision 11422)
@@ -8,12 +8,20 @@
 \label{chap:ASM}
 
-Authors: D. Lea,  M. Martin, K. Mogensen, A. Weaver, ...   % do we keep
+\minitoc
 
-\minitoc
+\vfill
+\begin{figure}[b]
+\subsubsection*{Changes record}
+\begin{tabular}{l||l|m{0.65\linewidth}}
+    Release   & Author        & Modifications \\
+    {\em 4.0} & {\em D. J. Lea} & {\em \NEMO 4.0 updates}  \\
+    {\em 3.4} & {\em D. J. Lea, M. Martin, K. Mogensen, A. Weaver} & {\em Initial version}  \\
+\end{tabular}
+\end{figure}
 
 \newpage
 
 The ASM code adds the functionality to apply increments to the model variables: temperature, salinity,
-sea surface height, velocity and sea ice concentration. 
+sea surface height, velocity and sea ice concentration.
 These are read into the model from a NetCDF file which may be produced by separate data assimilation code.
 The code can also output model background fields which are used as an input to data assimilation code.
@@ -37,18 +45,18 @@
 it may be preferable to introduce the increment gradually into the ocean model in order to
 minimize spurious adjustment processes.
-This technique is referred to as Incremental Analysis Updates (IAU) \citep{Bloom_al_MWR96}.
+This technique is referred to as Incremental Analysis Updates (IAU) \citep{bloom.takacs.ea_MWR96}.
 IAU is a common technique used with 3D assimilation methods such as 3D-Var or OI.
 IAU is used when \np{ln\_asmiau} is set to true.
 
-With IAU, the model state trajectory ${\bf x}$ in the assimilation window ($t_{0} \leq t_{i} \leq t_{N}$)
+With IAU, the model state trajectory ${\mathbf x}$ in the assimilation window ($t_{0} \leq t_{i} \leq t_{N}$)
 is corrected by adding the analysis increments for temperature, salinity, horizontal velocity and SSH as
 additional tendency terms to the prognostic equations:
 \begin{align*}
   % \label{eq:wa_traj_iau}
-  {\bf x}^{a}(t_{i}) = M(t_{i}, t_{0})[{\bf x}^{b}(t_{0})] \; + \; F_{i} \delta \tilde{\bf x}^{a}
+  {\mathbf x}^{a}(t_{i}) = M(t_{i}, t_{0})[{\mathbf x}^{b}(t_{0})] \; + \; F_{i} \delta \tilde{\mathbf x}^{a}
 \end{align*}
-where $F_{i}$ is a weighting function for applying the increments $\delta\tilde{\bf x}^{a}$ defined such that
+where $F_{i}$ is a weighting function for applying the increments $\delta\tilde{\mathbf x}^{a}$ defined such that
 $\sum_{i=1}^{N} F_{i}=1$.
-${\bf x}^b$ denotes the model initial state and ${\bf x}^a$ is the model state after the increments are applied.
+${\mathbf x}^b$ denotes the model initial state and ${\mathbf x}^a$ is the model state after the increments are applied.
 To control the adjustment time of the model to the increment,
 the increment can be applied over an arbitrary sub-window, $t_{m} \leq t_{i} \leq t_{n}$,
@@ -56,5 +64,5 @@
 Typically the increments are spread evenly over the full window.
 In addition, two different weighting functions have been implemented.
-The first function employs constant weights, 
+The first function (namelist option \np{niaufn} = 0) employs constant weights,
 \begin{align}
   \label{eq:F1_i}
@@ -62,12 +70,12 @@
   =\left\{
   \begin{array}{ll}
-    0     &    {\rm if} \; \; \; t_{i} < t_{m}                \\
-    1/M &    {\rm if} \; \; \; t_{m} < t_{i} \leq t_{n} \\
-    0     &    {\rm if} \; \; \; t_{i} > t_{n}
+    0     &    {\mathrm if} \; \; \; t_{i} < t_{m}                \\
+    1/M &    {\mathrm if} \; \; \; t_{m} < t_{i} \leq t_{n} \\
+    0     &    {\mathrm if} \; \; \; t_{i} > t_{n}
   \end{array}
-            \right. 
+            \right.
 \end{align}
 where $M = m-n$.
-The second function employs peaked hat-like weights in order to give maximum weight in the centre of the sub-window,
+The second function (namelist option \np{niaufn} = 1) employs peaked hat-like weights in order to give maximum weight in the centre of the sub-window,
 with the weighting reduced linearly to a small value at the window end-points:
 \begin{align}
@@ -76,12 +84,12 @@
   =\left\{
   \begin{array}{ll}
-    0                           &    {\rm if} \; \; \; t_{i}       <     t_{m}                        \\
-    \alpha \, i               &    {\rm if} \; \; \; t_{m}    \leq t_{i}    \leq   t_{M/2}   \\
-    \alpha \, (M - i +1) &    {\rm if} \; \; \; t_{M/2}  <    t_{i}    \leq   t_{n}       \\
-    0                            &   {\rm if} \; \; \; t_{i}        >    t_{n}
+    0                           &    {\mathrm if} \; \; \; t_{i}       <     t_{m}                        \\
+    \alpha \, i               &    {\mathrm if} \; \; \; t_{m}    \leq t_{i}    \leq   t_{M/2}   \\
+    \alpha \, (M - i +1) &    {\mathrm if} \; \; \; t_{M/2}  <    t_{i}    \leq   t_{n}       \\
+    0                            &   {\mathrm if} \; \; \; t_{i}        >    t_{n}
   \end{array}
                                    \right.
 \end{align}
-where $\alpha^{-1} = \sum_{i=1}^{M/2} 2i$ and $M$ is assumed to be even. 
+where $\alpha^{-1} = \sum_{i=1}^{M/2} 2i$ and $M$ is assumed to be even.
 The weights described by \autoref{eq:F2_i} provide a smoother transition of the analysis trajectory from
 one assimilation cycle to the next than that described by \autoref{eq:F1_i}.
@@ -92,6 +100,9 @@
 \label{sec:ASM_div_dmp}
 
-The velocity increments may be initialized by the iterative application of a divergence damping operator.
-In iteration step $n$ new estimates of velocity increments $u^{n}_I$ and $v^{n}_I$ are updated by:
+It is quite challenging for data assimilation systems to provide non-divergent velocity increments.
+Applying divergent velocity increments will likely cause spurious vertical velocities in the model. This section describes a method to take velocity increments provided to \NEMO ($u^0_I$ and $v^0_I$) and adjust them by the iterative application of a divergence damping operator. The method is also described in \citet{dobricic.pinardi.ea_OS07}.
+
+In iteration step $n$ (starting at $n=1$) new estimates of velocity increments $u^{n}_I$ and $v^{n}_I$ are updated by:
+
 \begin{equation}
   \label{eq:asm_dmp}
@@ -105,5 +116,7 @@
   \right.,
 \end{equation}
-where
+
+where the divergence is defined as
+
 \[
   % \label{eq:asm_div}
@@ -112,5 +125,6 @@
       +\delta_j \left[ {e_{1v}\,e_{3v}\,v^{n-1}_I} \right]} \right).
 \]
-By the application of \autoref{eq:asm_dmp} and \autoref{eq:asm_dmp} the divergence is filtered in each iteration,
+
+By the application of \autoref{eq:asm_dmp} the divergence is filtered in each iteration,
 and the vorticity is left unchanged.
 In the presence of coastal boundaries with zero velocity increments perpendicular to the coast
@@ -118,10 +132,9 @@
 This type of the initialisation reduces the vertical velocity magnitude and
 alleviates the problem of the excessive unphysical vertical mixing in the first steps of the model integration
-\citep{Talagrand_JAS72, Dobricic_al_OS07}.
+\citep{talagrand_JAS72, dobricic.pinardi.ea_OS07}.
 Diffusion coefficients are defined as $A_D = \alpha e_{1t} e_{2t}$, where $\alpha = 0.2$.
 The divergence damping is activated by assigning to \np{nn\_divdmp} in the \textit{nam\_asminc} namelist
 a value greater than zero.
-By choosing this value to be of the order of 100 the increments in
-the vertical velocity will be significantly reduced.
+This specifies the number of iterations of the divergence damping. Setting a value of the order of 100 will result in a significant reduction in the vertical velocity induced by the increments.
 
 
@@ -131,8 +144,8 @@
 \label{sec:ASM_details}
 
-Here we show an example \ngn{namasm} namelist and the header of an example assimilation increments file on
+Here we show an example \ngn{nam\_asminc} namelist and the header of an example assimilation increments file on
 the ORCA2 grid.
 
-%------------------------------------------namasm-----------------------------------------------------
+%------------------------------------------nam_asminc-----------------------------------------------------
 %
 \nlst{nam_asminc}
