New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
chap_ASM.tex in NEMO/trunk/doc/latex/NEMO/subfiles – NEMO

source: NEMO/trunk/doc/latex/NEMO/subfiles/chap_ASM.tex @ 11577

Last change on this file since 11577 was 11577, checked in by nicolasmartin, 5 years ago

New LaTeX commands \nam and \np to mention namelist content
(Partial commit to serve as a backup before other large edits)
In order to benefit of the syntax highlighting and to have a simpler syntax for
citing namelist block (\nam) and parameter (\np) with an optional variable assignment (\forcode{...}),
at this time the only viable solution I found is to require a double marker for
what it looks like the same item:

  1. Marker with the real name: 'tra_adv' block or 'ln_flx' parameter
  2. Marker with underscore character escaping: 'tra\_adv' block or 'ln\_flx' parameter

Despite many searches and attempts, I did not find a workaround to edit on-the-fly one or
the other marker.
In fact, the problem is on one side that the LaTeX index interprets '_' as a switch for lowering like
in math mode while on the other hand the backslash is considered for Pygments as a typo in Fortran
(red box).

For instance, \nam and \np have as of now the aforementioned 2 mandatory arguments in
the previous order (between braces) + an optional argument for \np when the parameter is defined
(between brackets at the first position):

  • \nam: LaTeX code in the \nam{tra_adv}{tra\_adv} -> PDF ' in the &namtra_adv (namelist X.X) ' with syntax highlighting, the hyperlink and the index entry
  • \np: LaTeX code \np[=.true.]{ln_flx}{ln\_flx} -> PDF ln_flux=.true. with syntax highlighting for the whole string and the entry in the 'parameters' index
File size: 8.4 KB
Line 
1\documentclass[../main/NEMO_manual]{subfiles}
2
3\begin{document}
4% ================================================================
5% Chapter Assimilation increments (ASM)
6% ================================================================
7\chapter{Apply Assimilation Increments (ASM)}
8\label{chap:ASM}
9
10\chaptertoc
11
12\vfill
13\begin{figure}[b]
14\subsubsection*{Changes record}
15\begin{tabular}{l||l|m{0.65\linewidth}}
16    Release   & Author        & Modifications \\
17    {\em 4.0} & {\em D. J. Lea} & {\em \NEMO\ 4.0 updates}  \\
18    {\em 3.4} & {\em D. J. Lea, M. Martin, K. Mogensen, A. Weaver} & {\em Initial version}  \\
19\end{tabular}
20\end{figure}
21
22\newpage
23
24The ASM code adds the functionality to apply increments to the model variables: temperature, salinity,
25sea surface height, velocity and sea ice concentration.
26These are read into the model from a NetCDF file which may be produced by separate data assimilation code.
27The code can also output model background fields which are used as an input to data assimilation code.
28This is all controlled by the namelist \nam{_asminc}{\_asminc}.
29There is a brief description of all the namelist options provided.
30To build the ASM code \key{asminc} must be set.
31
32%===============================================================
33
34\section{Direct initialization}
35\label{sec:ASM_DI}
36
37Direct initialization (DI) refers to the instantaneous correction of the model background state using
38the analysis increment.
39DI is used when \np{ln_asmdin}{ln\_asmdin} is set to true.
40
41\section{Incremental analysis updates}
42\label{sec:ASM_IAU}
43
44Rather than updating the model state directly with the analysis increment,
45it may be preferable to introduce the increment gradually into the ocean model in order to
46minimize spurious adjustment processes.
47This technique is referred to as Incremental Analysis Updates (IAU) \citep{bloom.takacs.ea_MWR96}.
48IAU is a common technique used with 3D assimilation methods such as 3D-Var or OI.
49IAU is used when \np{ln_asmiau}{ln\_asmiau} is set to true.
50
51With IAU, the model state trajectory ${\mathbf x}$ in the assimilation window ($t_{0} \leq t_{i} \leq t_{N}$)
52is corrected by adding the analysis increments for temperature, salinity, horizontal velocity and SSH as
53additional tendency terms to the prognostic equations:
54\begin{align*}
55  % \label{eq:ASM_wa_traj_iau}
56  {\mathbf x}^{a}(t_{i}) = M(t_{i}, t_{0})[{\mathbf x}^{b}(t_{0})] \; + \; F_{i} \delta \tilde{\mathbf x}^{a}
57\end{align*}
58where $F_{i}$ is a weighting function for applying the increments $\delta\tilde{\mathbf x}^{a}$ defined such that
59$\sum_{i=1}^{N} F_{i}=1$.
60${\mathbf x}^b$ denotes the model initial state and ${\mathbf x}^a$ is the model state after the increments are applied.
61To control the adjustment time of the model to the increment,
62the increment can be applied over an arbitrary sub-window, $t_{m} \leq t_{i} \leq t_{n}$,
63of the main assimilation window, where $t_{0} \leq t_{m} \leq t_{i}$ and $t_{i} \leq t_{n} \leq t_{N}$.
64Typically the increments are spread evenly over the full window.
65In addition, two different weighting functions have been implemented.
66The first function (namelist option \np{niaufn}=0) employs constant weights,
67\begin{align}
68  \label{eq:ASM_F1_i}
69  F^{(1)}_{i}
70  =\left\{
71  \begin{array}{ll}
72    0     &    {\mathrm if} \; \; \; t_{i} < t_{m}                \\
73    1/M &    {\mathrm if} \; \; \; t_{m} < t_{i} \leq t_{n} \\
74    0     &    {\mathrm if} \; \; \; t_{i} > t_{n}
75  \end{array}
76            \right.
77\end{align}
78where $M = m-n$.
79The 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,
80with the weighting reduced linearly to a small value at the window end-points:
81\begin{align}
82  \label{eq:ASM_F2_i}
83  F^{(2)}_{i}
84  =\left\{
85  \begin{array}{ll}
86    0                           &    {\mathrm if} \; \; \; t_{i}       <     t_{m}                        \\
87    \alpha \, i               &    {\mathrm if} \; \; \; t_{m}    \leq t_{i}    \leq   t_{M/2}   \\
88    \alpha \, (M - i +1) &    {\mathrm if} \; \; \; t_{M/2}  <    t_{i}    \leq   t_{n}       \\
89    0                            &   {\mathrm if} \; \; \; t_{i}        >    t_{n}
90  \end{array}
91                                   \right.
92\end{align}
93where $\alpha^{-1} = \sum_{i=1}^{M/2} 2i$ and $M$ is assumed to be even.
94The weights described by \autoref{eq:ASM_F2_i} provide a smoother transition of the analysis trajectory from
95one assimilation cycle to the next than that described by \autoref{eq:ASM_F1_i}.
96
97%==========================================================================
98% Divergence damping description %%%
99\section{Divergence damping initialisation}
100\label{sec:ASM_div_dmp}
101
102It is quite challenging for data assimilation systems to provide non-divergent velocity increments.
103Applying 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}.
104
105In iteration step $n$ (starting at $n=1$) new estimates of velocity increments $u^{n}_I$ and $v^{n}_I$ are updated by:
106
107\begin{equation}
108  \label{eq:ASM_dmp}
109  \left\{
110    \begin{aligned}
111      u^{n}_I = u^{n-1}_I + \frac{1}{e_{1u} } \delta_{i+1/2} \left( {A_D
112          \;\chi^{n-1}_I } \right) \\ \\
113      v^{n}_I = v^{n-1}_I + \frac{1}{e_{2v} } \delta_{j+1/2} \left( {A_D
114          \;\chi^{n-1}_I } \right) \\
115    \end{aligned}
116  \right.,
117\end{equation}
118
119where the divergence is defined as
120
121\[
122  % \label{eq:ASM_div}
123  \chi^{n-1}_I = \frac{1}{e_{1t}\,e_{2t}\,e_{3t} }
124  \left( {\delta_i \left[ {e_{2u}\,e_{3u}\,u^{n-1}_I} \right]
125      +\delta_j \left[ {e_{1v}\,e_{3v}\,v^{n-1}_I} \right]} \right).
126\]
127
128By the application of \autoref{eq:ASM_dmp} the divergence is filtered in each iteration,
129and the vorticity is left unchanged.
130In the presence of coastal boundaries with zero velocity increments perpendicular to the coast
131the divergence is strongly damped.
132This type of the initialisation reduces the vertical velocity magnitude and
133alleviates the problem of the excessive unphysical vertical mixing in the first steps of the model integration
134\citep{talagrand_JAS72, dobricic.pinardi.ea_OS07}.
135Diffusion coefficients are defined as $A_D = \alpha e_{1t} e_{2t}$, where $\alpha = 0.2$.
136The divergence damping is activated by assigning to \np{nn_divdmp}{nn\_divdmp} in the \nam{_asminc}{\_asminc} namelist
137a value greater than zero.
138This 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.
139
140
141%==========================================================================
142
143\section{Implementation details}
144\label{sec:ASM_details}
145
146Here we show an example \nam{_asminc}{\_asminc} namelist and the header of an example assimilation increments file on
147the ORCA2 grid.
148
149%------------------------------------------nam_asminc-----------------------------------------------------
150%
151\begin{listing}
152  \nlst{nam_asminc}
153  \caption{\forcode{&nam_asminc}}
154  \label{lst:nam_asminc}
155\end{listing}
156%-------------------------------------------------------------------------------------------------------------
157
158The header of an assimilation increments file produced using the NetCDF tool
159\mbox{\textit{ncdump~-h}} is shown below
160
161\begin{clines}
162netcdf assim_background_increments {
163dimensions:
164        x = 182 ;
165        y = 149 ;
166        z = 31 ;
167        t = UNLIMITED ; // (1 currently)
168variables:
169        float nav_lon(y, x) ;
170        float nav_lat(y, x) ;
171        float nav_lev(z) ;
172        double time_counter(t) ;
173        double time ;
174        double z_inc_dateb ;
175        double z_inc_datef ;
176        double bckint(t, z, y, x) ;
177        double bckins(t, z, y, x) ;
178        double bckinu(t, z, y, x) ;
179        double bckinv(t, z, y, x) ;
180        double bckineta(t, y, x) ;
181
182// global attributes:
183                :DOMAIN_number_total = 1 ;
184                :DOMAIN_number = 0 ;
185                :DOMAIN_dimensions_ids = 1, 2 ;
186                :DOMAIN_size_global = 182, 149 ;
187                :DOMAIN_size_local = 182, 149 ;
188                :DOMAIN_position_first = 1, 1 ;
189                :DOMAIN_position_last = 182, 149 ;
190                :DOMAIN_halo_size_start = 0, 0 ;
191                :DOMAIN_halo_size_end = 0, 0 ;
192                :DOMAIN_type = "BOX" ;
193}
194\end{clines}
195
196\biblio
197
198\pindex
199
200\end{document}
Note: See TracBrowser for help on using the repository browser.