Index: NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_ASM.tex
===================================================================
--- NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_ASM.tex	(revision 11207)
+++ NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_ASM.tex	(revision 12149)
@@ -2,26 +2,39 @@
 
 \begin{document}
-% ================================================================
-% Chapter Assimilation increments (ASM)
-% ================================================================
+
 \chapter{Apply Assimilation Increments (ASM)}
 \label{chap:ASM}
 
-Authors: D. Lea,  M. Martin, K. Mogensen, A. Weaver, ...   % do we keep
+%    {\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}  \\
 
-\minitoc
+\thispagestyle{plain}
 
-\newpage
+\chaptertoc
+
+\paragraph{Changes record} ~\\
+
+{\footnotesize
+  \begin{tabularx}{\textwidth}{l||X|X}
+    Release & Author(s) & Modifications \\
+    \hline
+    {\em   4.0} & {\em ...} & {\em ...} \\
+    {\em   3.6} & {\em ...} & {\em ...} \\
+    {\em   3.4} & {\em ...} & {\em ...} \\
+    {\em <=3.4} & {\em ...} & {\em ...}
+  \end{tabularx}
+}
+
+\clearpage
 
 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.
-This is all controlled by the namelist \textit{\ngn{nam\_asminc} }.
+This is all controlled by the namelist \nam{_asminc}{\_asminc}.
 There is a brief description of all the namelist options provided.
 To build the ASM code \key{asminc} must be set.
 
-%===============================================================
-
+%% =================================================================================================
 \section{Direct initialization}
 \label{sec:ASM_DI}
@@ -29,6 +42,7 @@
 Direct initialization (DI) refers to the instantaneous correction of the model background state using
 the analysis increment.
-DI is used when \np{ln\_asmdin} is set to true.
+DI is used when \np{ln_asmdin}{ln\_asmdin} is set to true.
 
+%% =================================================================================================
 \section{Incremental analysis updates}
 \label{sec:ASM_IAU}
@@ -39,5 +53,5 @@
 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.
+IAU is used when \np{ln_asmiau}{ln\_asmiau} is set to true.
 
 With IAU, the model state trajectory ${\mathbf x}$ in the assimilation window ($t_{0} \leq t_{i} \leq t_{N}$)
@@ -45,5 +59,5 @@
 additional tendency terms to the prognostic equations:
 \begin{align*}
-  % \label{eq:wa_traj_iau}
+  % \label{eq:ASM_wa_traj_iau}
   {\mathbf x}^{a}(t_{i}) = M(t_{i}, t_{0})[{\mathbf x}^{b}(t_{0})] \; + \; F_{i} \delta \tilde{\mathbf x}^{a}
 \end{align*}
@@ -56,7 +70,7 @@
 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}{niaufn}=0) employs constant weights,
 \begin{align}
-  \label{eq:F1_i}
+  \label{eq:ASM_F1_i}
   F^{(1)}_{i}
   =\left\{
@@ -66,11 +80,11 @@
     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}{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}
-  \label{eq:F2_i}
+  \label{eq:ASM_F2_i}
   F^{(2)}_{i}
   =\left\{
@@ -83,17 +97,19 @@
                                    \right.
 \end{align}
-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}.
+where $\alpha^{-1} = \sum_{i=1}^{M/2} 2i$ and $M$ is assumed to be even.
+The weights described by \autoref{eq:ASM_F2_i} provide a smoother transition of the analysis trajectory from
+one assimilation cycle to the next than that described by \autoref{eq:ASM_F1_i}.
 
-%==========================================================================
-% Divergence damping description %%%
+%% =================================================================================================
 \section{Divergence damping initialisation}
 \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}
+  \label{eq:ASM_dmp}
   \left\{
     \begin{aligned}
@@ -105,12 +121,15 @@
   \right.,
 \end{equation}
-where
+
+where the divergence is defined as
+
 \[
-  % \label{eq:asm_div}
+  % \label{eq:ASM_div}
   \chi^{n-1}_I = \frac{1}{e_{1t}\,e_{2t}\,e_{3t} }
   \left( {\delta_i \left[ {e_{2u}\,e_{3u}\,u^{n-1}_I} \right]
       +\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
@@ -120,22 +139,20 @@
 \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
+The divergence damping is activated by assigning to \np{nn_divdmp}{nn\_divdmp} in the \nam{_asminc}{\_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.
 
-
-%==========================================================================
-
+%% =================================================================================================
 \section{Implementation details}
 \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 \nam{_asminc}{\_asminc} namelist and the header of an example assimilation increments file on
 the ORCA2 grid.
 
-%------------------------------------------namasm-----------------------------------------------------
-%
-\nlst{nam_asminc}
-%-------------------------------------------------------------------------------------------------------------
+\begin{listing}
+  \nlst{nam_asminc}
+  \caption{\forcode{&nam_asminc}}
+  \label{lst:nam_asminc}
+\end{listing}
 
 The header of an assimilation increments file produced using the NetCDF tool
@@ -177,7 +194,5 @@
 \end{clines}
 
-\biblio
-
-\pindex
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
