Changeset 817 for trunk/DOC/BETA/Chapters/Chap_DOM.tex
- Timestamp:
- 2008-02-09T15:13:48+01:00 (16 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/DOC/BETA/Chapters/Chap_DOM.tex
r781 r817 8 8 9 9 % Missing things: 10 % - istate: description of the initial state 10 % - istate: description of the initial state ==> this has to be put elsewhere.. 11 % perhaps in MISC ? By the way the initialisation of T S and dynamics 12 % should be put outside of DOM routine (better with TRC staff and off-line 13 % tracers) 11 14 % - daymod: definition of the time domain (nit000, nitend andd the calendar) 12 15 % -geo2ocean: how to switch from geographic to mesh coordinate 13 16 % - domclo: closed sea and lakes.... management of closea sea area : specific to global configuration, both forced and coupled 14 17 15 16 17 18 19 Having defined the continuous equations in Chap.~\ref{PE}, we need to choose a discretization on a grid, and numerical algorithms. In the present chapter, we provide a general description of the staggered grid used in OPA, and other information relevant to the main directory routines (time stepping, main program) as well as the DOM (DOMain) directory. 18 \gmcomment{STEVEN :maybe a picture of the directory structure in the introduction which could be referred to here, would help ==> to be added} 19 %%%% 20 21 22 \newpage 23 $\ $\newline % force a new ligne 24 25 26 Having defined the continuous equations in Chap.~\ref{PE}, we need to choose a 27 discretization on a grid, and numerical algorithms. In the present chapter, we 28 provide a general description of the staggered grid used in \NEMO, and other 29 information relevant to the main directory routines (time stepping, main program) 30 as well as the DOM (DOMain) directory. 20 31 21 32 % ================================================================ … … 34 45 \begin{figure}[!tb] \label{Fig_cell} \begin{center} 35 46 \includegraphics[width=0.90\textwidth]{./Figures/Fig_cell.pdf} 36 \caption{Arrangement of variables. $T$ indicates scalar points where temperature, salinity, density, pressure and horizontal divergence are defined. ($u$,$v$,$w$) indicates vector points, and $f$ indicates vorticity points where both relative and planetary vorticities are defined} 47 \caption{Arrangement of variables. $T$ indicates scalar points where temperature, 48 salinity, density, pressure and horizontal divergence are defined. ($u$,$v$,$w$) 49 indicates vector points, and $f$ indicates vorticity points where both relative and 50 planetary vorticities are defined} 37 51 \end{center} \end{figure} 38 52 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 39 53 40 The numerical techniques used to solve the Primitive Equations in this model are based on the traditional, centred second-order finite difference approximation. Special attention has been given to the homogeneity of the solution in the three space directions. The arrangement of variables is the 41 same in all directions. It consists in cells centred on scalar points ($T$, $S$, $p$, $\rho$) with vector points $(u, v, w)$ defined in the centre of each face of the cells (Fig. \ref{Fig_cell}). This is the generalisation to three dimensions of the well-known ``C'' grid in Arakawa's classification. The relative and planetary vorticity, $\zeta$ and $f$, are defined in the centre of each vertical edge and the barotropic stream function $\psi$ is defined at horizontal points overlying the $\zeta$ and $f$-points. 42 43 The ocean mesh ($i.e.$ the position of all the scalar and vector points) is defined by the transformation that gives ($\lambda$ ,$\varphi$ ,$z$) as a function of $(i,j,k)$. The grid-points are located at integer or integer and a half value of $(i,j,k)$ as indicated on Table \ref{Tab_cell}. In all the following, subscripts $u$, $v$, $w$, $f$, $uw$, $vw$ or $fw$ indicate the position of the grid-point where the scale factors are defined. Each scale factor is defined as the local analytical value provided by \eqref{Eq_scale_factors}. As a result, the mesh on which partial derivatives $\frac{\partial}{\partial \lambda}, \frac{\partial}{\partial \varphi}$, and $\frac{\partial}{\partial z} $ are evaluated is a uniform mesh with a grid size unity. Discrete partial derivatives are formulated by the traditional, centred second order finite difference approximation while the scale factors are chosen equal to their local analytical value. An important point here is that the partial derivative of the scale factors must be evaluated by centred finite difference approximation, not from their 44 analytical expression. This preserves the symmetry of the discrete set of equations and therefore allows satisfying many of the continuous properties (see { \colorbox{yellow}{Annexe C}). A similar, related remark can be made about the domain size: when needed, an area, volume, or the total ocean depth must be evaluated as the sum of the relevant scale factors (see \eqref{DOM_bar}) in the next section). 54 The numerical techniques used to solve the Primitive Equations in this model are 55 based on the traditional, centred second-order finite difference approximation. 56 Special attention has been given to the homogeneity of the solution in the three 57 space directions. The arrangement of variables is the same in all directions. 58 It consists of cells centred on scalar points ($T$, $S$, $p$, $\rho$) with vector 59 points $(u, v, w)$ defined in the centre of each face of the cells (Fig. \ref{Fig_cell}). 60 This is the generalisation to three dimensions of the well-known ``C'' grid in 61 Arakawa's classification \citep{Mesinger_Arakawa_Bk76}. The relative and 62 planetary vorticity, $\zeta$ and $f$, are defined in the centre of each vertical edge 63 and the barotropic stream function $\psi$ is defined at horizontal points overlying 64 the $\zeta$ and $f$-points. 65 66 The ocean mesh ($i.e.$ the position of all the scalar and vector points) is defined 67 by the transformation that gives ($\lambda$ ,$\varphi$ ,$z$) as a function of $(i,j,k)$. 68 The grid-points are located at integer or integer and a half value of $(i,j,k)$ as 69 indicated on Table \ref{Tab_cell}. In all the following, subscripts $u$, $v$, $w$, 70 $f$, $uw$, $vw$ or $fw$ indicate the position of the grid-point where the scale 71 factors are defined. Each scale factor is defined as the local analytical value 72 provided by \eqref{Eq_scale_factors}. As a result, the mesh on which partial 73 derivatives $\frac{\partial}{\partial \lambda}, \frac{\partial}{\partial \varphi}$, and 74 $\frac{\partial}{\partial z} $ are evaluated is a uniform mesh with a grid size of unity. Discrete partial derivatives are formulated by the traditional, centred second order 75 finite difference approximation while the scale factors are chosen equal to their 76 local analytical value. An important point here is that the partial derivative of the 77 scale factors must be evaluated by centred finite difference approximation, not 78 from their analytical expression. This preserves the symmetry of the discrete set 79 of equations and therefore satisfies many of the continuous properties (see 80 Appendix~\ref{Apdx_C}). A similar, related remark can be made about the domain 81 size: when needed, an area, volume, or the total ocean depth must be evaluated 82 as the sum of the relevant scale factors (see \eqref{DOM_bar}) in the next section). 45 83 46 84 \begin{table}[!tb] \label{Tab_cell} … … 56 94 fw & $i+1/2$ & $j+1/2$ & $k+1/2$ \\ \hline 57 95 \end{tabular} 58 \caption{Location of grid-points as a function of integer or integer and a half value of the column, line or level. This indexation is only used for the writing of semi-discrete equation. In the code, the indexation use integer value only and has a reverse direction in the vertical (see \S\ref{DOM_Num_Index})} 96 \caption{Location of grid-points as a function of integer or integer and a half value 97 of the column, line or level. This indexing is only used for the writing of the semi- 98 discrete equation. In the code, the indexing uses integer values only and has a 99 reverse direction in the vertical (see \S\ref{DOM_Num_Index})} 59 100 \end{center} 60 101 \end{table} … … 66 107 \label{DOM_operators} 67 108 68 Given the values of a variable $q$ at adjacent points, the derivation and averaging operators at the midpoint between them are: 109 Given the values of a variable $q$ at adjacent points, the differencing and 110 averaging operators at the midpoint between them are: 69 111 \begin{subequations} \label{Eq_di_mi} 70 112 \begin{align} 71 \delta _i [q] &= \ \ q(i+1/2) - q(i-1/2) \\72 \overline q^ i&= \left\{ q(i+1/2) + q(i-1/2) \right\} \; / \; 2113 \delta _i [q] &= \ \ q(i+1/2) - q(i-1/2) \\ 114 \overline q^{\,i} &= \left\{ q(i+1/2) + q(i-1/2) \right\} \; / \; 2 73 115 \end{align} 74 116 \end{subequations} 75 117 76 Similar operators are defined with respect to $i+1/2$, $j$, $j+1/2$, $k$, and $k+1/2$. Following 77 \eqref{Eq_PE_grad} and \eqref{Eq_PE_lap}, the gradient of a variable $q$ defined at $T$-point has its three components defined at $(u,v,w)$ while its Laplacien is defined at $T$-point. These operators have the following discrete forms in the curvilinear $s$-coordinate system: 118 Similar operators are defined with respect to $i+1/2$, $j$, $j+1/2$, $k$, and 119 $k+1/2$. Following \eqref{Eq_PE_grad} and \eqref{Eq_PE_lap}, the gradient of a 120 variable $q$ defined at a $T$-point has its three components defined at $u$-, $v$- 121 and $w$-points while its Laplacien is defined at $T$-point. These operators have 122 the following discrete forms in the curvilinear $s$-coordinate system: 78 123 \begin{equation} \label{Eq_DOM_grad} 79 124 \nabla q\equiv \frac{1}{e_{1u} }\delta _{i+1/2} \left[ q \right]\;\,{\rm {\bf i}} … … 91 136 \end{multline} 92 137 93 Following \eqref{Eq_PE_curl} and \eqref{Eq_PE_div}, a vector ${\rm {\bf A}}=\left( a_1,a_2,a_3\right)$ defined at vector points $(u,v,w)$ has its three curl components defined at $(vw,uw,f)$ and its divergence defined at $T$-points: 138 Following \eqref{Eq_PE_curl} and \eqref{Eq_PE_div}, a vector ${\rm {\bf A}}=\left( a_1,a_2,a_3\right)$ defined at vector points $(u,v,w)$ has its three curl 139 components defined at $vw$-, $uw$, and $f$-points, and its divergence defined 140 at $T$-points: 94 141 \begin{equation} \label{Eq_DOM_curl} 95 142 \begin{split} … … 110 157 \end{equation} 111 158 112 In the special case of pure $z$-coordinates system, \eqref{Eq_DOM_lap} and \eqref{Eq_DOM_div} can be simplified. In this case, the vertical scale factor becomes a function of the single variable $k$ and thus does not depend on the horizontal location of a grid point. It can be simplified from outside and inside the $\delta _i$ and $\delta_j$ operators. 113 114 The vertical average over the whole water column denoted by an overbar becomes for a quantity $q$ which is a masked field (i.e. equal to zero inside solid area): 159 In the special case of a pure $z$-coordinate system, \eqref{Eq_DOM_lap} and 160 \eqref{Eq_DOM_div} can be simplified. In this case, the vertical scale factor 161 becomes a function of the single variable $k$ and thus does not depend on the 162 horizontal location of a grid point. For example \eqref{Eq_DOM_div} reduces to: 163 \begin{equation*} 164 \nabla \cdot {\rm {\bf A}}=\frac{1}{e_{1T} e_{2T} }\left( {\delta 165 _i \left[ {e_{2u} a_1 } \right]+\delta _j \left[ {e_{1v} a_2 } 166 \right]} \right)+\frac{1}{e_{3T} }\delta _k \left[ {a_3 } \right] 167 \end{equation*} 168 169 The vertical average over the whole water column denoted by an overbar becomes 170 for a quantity $q$ which is a masked field (i.e. equal to zero inside solid area): 115 171 \begin{equation} \label{DOM_bar} 116 172 \bar q = \frac{1}{H}\int_{k^b}^{k^o} {q\;e_{3q} \,dk} 117 173 \equiv \frac{1}{H_q }\sum\limits_k {q\;e_{3q} } 118 174 \end{equation} 119 where $H_q$ the ocean depth, is the masked sum of the vertical scale factors at q points, $k^b$ and $k^o$ are the bottom and surface $k$-index, and the symbol $k^o$ referring to a summation over all grid points of the same species in the direction indicated by the subscript (here $k$). 120 121 In continuous, the following properties are satisfied: 175 where $H_q$ is the ocean depth, which is the masked sum of the vertical scale 176 factors at $q$ points, $k^b$ and $k^o$ are the bottom and surface $k$-indices, 177 and the symbol $k^o$ refers to a summation over all grid points of the same type 178 in the direction indicated by the subscript (here $k$). 179 180 In continuous form, the following properties are satisfied: 122 181 \begin{equation} \label{Eq_DOM_curl_grad} 123 182 \nabla \times \nabla q ={\rm {\bf {0}}} … … 127 186 \end{equation} 128 187 129 It is straight forward to demonstrate that these properties are verified locally in discrete form as soon as the scalar $q$ is taken at $T$-points and the vector \textbf{A} has its components defined at vector points $(u,v,w)$. 130 131 Let $a$ and $b$ be two fields defined on the ocean mesh, extended to zero inside continental area. By integration by part it can be shown that the derivation operators ($\delta_i$, $\delta_j$ and $\delta_k$) are anti-symmetric linear operators, and further that the averaging operators $\overline{\cdot}^i$, $\overline{\cdot}^j$ and $\overline{\cdot}^k$) are symmetric linear operators, i.e., 132 \begin{equation} \label{DOM_di_adj} 133 \sum\limits_i {a_i \;\delta _i \left[ b \right]} \equiv -\sum\limits_i 134 {\delta _{i+1/2} \left[ a \right]\;b_{i+1/2} } 135 \end{equation} 136 \begin{equation} \label{DOM_mi_adj} 137 \sum\limits_i {a_i \;\overline b ^i} \equiv \sum\limits_i {\overline a ^{i+1/2}\;b_{i+1/2} } 138 \end{equation} 139 140 In other words, the adjoint of the derivation and averaging operators are $\delta_i^*=\delta_{i+1/2}$ and $\overline{\cdot}^{i\,*}= \overline{\cdot}^{i+1/2}$, respectively. These two properties will be used extensively in the \colorbox{yellow} {Appendix C} to 188 It is straightforward to demonstrate that these properties are verified locally in 189 discrete form as soon as the scalar $q$ is taken at $T$-points and the vector 190 \textbf{A} has its components defined at vector points $(u,v,w)$. 191 192 Let $a$ and $b$ be two fields defined on the mesh, with value zero inside 193 continental area. Using integration by parts it can be shown that the differencing 194 operators ($\delta_i$, $\delta_j$ and $\delta_k$) are anti-symmetric linear 195 operators, and further that the averaging operators $\overline{\,\cdot\,}^{\,i}$, 196 $\overline{\,\cdot\,}^{\,k}$ and $\overline{\,\cdot\,}^{\,k}$) are symmetric linear 197 operators, $i.e.$ 198 \begin{align} 199 \label{DOM_di_adj} 200 \sum\limits_i { a_i \;\delta _i \left[ b \right]} 201 &\equiv -\sum\limits_i {\delta _{i+1/2} \left[ a \right]\;b_{i+1/2} } \\ 202 \label{DOM_mi_adj} 203 \sum\limits_i { a_i \;\overline b^{\,i}} 204 & \equiv \quad \sum\limits_i {\overline a ^{\,i+1/2}\;b_{i+1/2} } 205 \end{align} 206 207 In other words, the adjoint of the differencing and averaging operators are 208 $\delta_i^*=\delta_{i+1/2}$ and 209 ${(\overline{\,\cdot \,}^{\,i})}^*= \overline{\,\cdot\,}^{\,i+1/2}$, respectively. 210 These two properties will be used extensively in the Appendix~\ref{Apdx_C} to 141 211 demonstrate integral conservative properties of the discrete formulation chosen. 142 212 143 213 % ------------------------------------------------------------------------------------------------------------- 144 % Numerical Index ation145 % ------------------------------------------------------------------------------------------------------------- 146 \subsection{Numerical Index ation}214 % Numerical Indexing 215 % ------------------------------------------------------------------------------------------------------------- 216 \subsection{Numerical Indexing} 147 217 \label{DOM_Num_Index} 148 218 … … 150 220 \begin{figure}[!tb] \label{Fig_index_hor} \begin{center} 151 221 \includegraphics[width=0.90\textwidth]{./Figures/Fig_index_hor.pdf} 152 \caption{Horizontal integer indexation used in the \textsc{Fortran} code. The dashed area indicates the cell in which variables contained in arrays have the same $i$- and $j$-indices} 222 \caption{Horizontal integer indexing used in the \textsc{Fortran} code. The dashed 223 area indicates the cell in which variables contained in arrays have the same 224 $i$- and $j$-indices} 153 225 \end{center} \end{figure} 154 226 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 155 227 156 The array representation used in the \textsc{Fortran} code requires an integer indexation while the analytical definition of the mesh (see \S\ref{DOM_cell}) is associated with the use of integer values of $(i,j,k)$ for $T$-points whereas all the other points use both integer and integer and a half values of $(i,j,k)$. Therefore a specific integer indexation must be defined for the latter grid-points 157 (i.e. velocity and vorticity grid-points). Furthermore, it has been chosen to change the direction of the vertical indexation so that the surface level is at $k=1$. 228 The array representation used in the \textsc{Fortran} code requires an integer 229 indexing while the analytical definition of the mesh (see \S\ref{DOM_cell}) is 230 associated with the use of integer values for $T$-points and both integer and 231 integer and a half values for all the other points. Therefore a specific integer 232 indexing must be defined for points other than $T$-points ($i.e.$ velocity and 233 vorticity grid-points). Furthermore, the direction of the vertical indexing has 234 been changed so that the surface level is at $k=1$. 158 235 159 236 % ----------------------------------- 160 % Horizontal Index ation237 % Horizontal Indexing 161 238 % ----------------------------------- 162 \subsubsection{Horizontal Index ation}239 \subsubsection{Horizontal Indexing} 163 240 \label{DOM_Num_Index_hor} 164 241 165 The indexation in the horizontal plane has been chosen as shown in Fig.\ref{Fig_index_hor}. For an increasing $i$ index ($j$ index), the $T$-point and the eastward $u$-point (northward $v$-point) have the same index (see the dashed area in Fig.\ref{Fig_index_hor}). A $T$-point and its nearby northeast $f$-point have the same $i$-and $j$-indices. 242 The indexing in the horizontal plane has been chosen as shown in Fig.\ref{Fig_index_hor}. For an increasing $i$ index ($j$ index), the $T$-point 243 and the eastward $u$-point (northward $v$-point) have the same index 244 (see the dashed area in Fig.\ref{Fig_index_hor}). A $T$-point and its 245 nearest northeast $f$-point have the same $i$-and $j$-indices. 166 246 167 247 % ----------------------------------- 168 % Vertical Indexation248 % Vertical indexing 169 249 % ----------------------------------- 170 \subsubsection{Vertical Index ation}250 \subsubsection{Vertical Indexing} 171 251 \label{DOM_Num_Index_vertical} 172 252 173 In the vertical plane, the chosen indexation requires special attention since the $k$-axis is re-oriented downward in the \textsc{Fortran} code compared to the indexation used for the semi-discrete equations and given in \S\ref{DOM_cell}. The sea surface corresponds to the $w$-level $k=1$ like the $T-$level just below (Fig.\ref{Fig_index_vert}). The last $w$-level ($k=jpk$) is either the ocean bottom or inside the ocean floor while the last $T-$level is always inside the floor (Fig.\ref{Fig_index_vert}). Note that for an increasing $k$ index, a $w$-point and the $T$-point just below have the same $k$ index, in opposition to what is done in the horizontal plane where 174 it is the $T-$point and the nearby velocity points in the direction of the horizontal axis that have the same $i$ or $j$ index (compare the dashed area in Fig.\ref{Fig_index_hor} and \ref{Fig_index_vert}). As the scale factors are chosen to be strictly positive, \emph{a minus sign appears in the \textsc{Fortran} code before all the vertical derivatives of the discrete equations given in this documentation}. 253 In the vertical, the chosen indexing requires special attention since the 254 $k$-axis is re-orientated downward in the \textsc{Fortran} code compared 255 to the indexing used in the semi-discrete equations and given in \S\ref{DOM_cell}. 256 The sea surface corresponds to the $w$-level $k=1$ which is the same index 257 as $T$-level just below (Fig.\ref{Fig_index_vert}). The last $w$-level ($k=jpk$) 258 either corresponds to the ocean floor or is inside the bathymetry while the last 259 $T$-level is always inside the bathymetry (Fig.\ref{Fig_index_vert}). Note that 260 for an increasing $k$ index, a $w$-point and the $T$-point just below have the 261 same $k$ index, in opposition to what is done in the horizontal plane where 262 it is the $T$-point and the nearest velocity points in the direction of the horizontal 263 axis that have the same $i$ or $j$ index (compare the dashed area in Fig.\ref{Fig_index_hor} and \ref{Fig_index_vert}). Since the scale factors are chosen 264 to be strictly positive, a \emph{minus sign} appears in the \textsc{Fortran} code 265 \emph{before all the vertical derivatives} of the discrete equations given in this 266 documentation. 175 267 176 268 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 177 269 \begin{figure}[!pt] \label{Fig_index_vert} \begin{center} 178 270 \includegraphics[width=.90\textwidth]{./Figures/Fig_index_vert.pdf} 179 \caption{Vertical integer indexation used in the \textsc{Fortran } code. Note that the $k$-axis is oriented downward. The dashed area indicates the cell in which variables contained in arrays have the same $k$-index.} 271 \caption{Vertical integer indexing used in the \textsc{Fortran } code. Note that 272 the $k$-axis is orientated downward. The dashed area indicates the cell in 273 which variables contained in arrays have the same $k$-index.} 180 274 \end{center} \end{figure} 181 275 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 182 276 183 277 % ----------------------------------- 184 % Vertical Indexation278 % Domain Size 185 279 % ----------------------------------- 186 \subsubsection{Domain size}280 \subsubsection{Domain Size} 187 281 \label{DOM_size} 188 282 189 The total size of the computational domain is set by the parameters \jp{jpiglo}, \jp{jpjglo} and \jp{jpk} in the $i$, $j$ and $k$ directions respectively. They are given as parameters in the \mdl{par\_oce} module (or additional files included in this module such as \textit{par\_ORCA\_R2.h90}, specific to a given configuration). The use of parameters rather than variables (together with dynamic allocation of arrays) was made because it ensured that the compiler would optimize the executable code efficiently, especially on vector machines (optimization may be less efficient when the problem size is unknown at the time of compilation). Nevertheless, it is possible to set up the code with full dynamical allocation by using the AGRIF packaged \colorbox{yellow}{(ref agrif!+ ref part of the doc)}. Note that are other parameters in \mdl{par\_oce} that refer to the domain size. The two parameters $jpidta$ and $jpjdta$, may be larger than $jpiglo$, $jpjglo$ when the user wants to use only a sub-region of a given configuration. This is the "zoom" capability described in \S\ref{MISC_zoom}. In most applications of the model, $jpidta=jpiglo$, $jpjdta=jpjglo$, and $jpizoom=jpjzoom=1$. Parameters $jpi$ and $jpj$ refer to the size of each processor subdomain when the code is run in parallel using domain decomposition (\key{mpp\_mpi} defined, see \S\ref{LBC_mpp}). 283 The total size of the computational domain is set by the parameters \jp{jpiglo}, 284 \jp{jpjglo} and \jp{jpk} in the $i$, $j$ and $k$ directions respectively. They are 285 given as parameters in the \mdl{par\_oce} module\footnote{When a specific 286 configuration is used (ORCA2 global ocean, etc...) the parameter are actually 287 defined in additional files introduced by \mdl{par\_oce} module via CPP 288 \textit{include} command. For example, ORCA2 parameters are set in 289 \textit{par\_ORCA\_R2.h90} file}. The use of parameters rather than variables 290 (together with dynamic allocation of arrays) was chosen because it ensured that 291 the compiler would optimize the executable code efficiently, especially on vector 292 machines (optimization may be less efficient when the problem size is unknown 293 at the time of compilation). Nevertheless, it is possible to set up the code with full 294 dynamical allocation by using the AGRIF packaged \citep{Debreu_al_CG2008}. 295 % 296 \gmcomment{ add the following ref 297 \colorbox{yellow}{(ref part of the doc)} } 298 % 299 Note that are other parameters in \mdl{par\_oce} that refer to the domain size. 300 The two parameters $jpidta$ and $jpjdta$ may be larger than $jpiglo$, $jpjglo$ 301 when the user wants to use only a sub-region of a given configuration. This is 302 the "zoom" capability described in \S\ref{MISC_zoom}. In most applications of 303 the model, $jpidta=jpiglo$, $jpjdta=jpjglo$, and $jpizoom=jpjzoom=1$. Parameters 304 $jpi$ and $jpj$ refer to the size of each processor subdomain when the code is 305 run in parallel using domain decomposition (\key{mpp\_mpi} defined, see 306 \S\ref{LBC_mpp}). 190 307 191 308 % ================================================================ 192 309 % Domain: Horizontal Grid (mesh) 193 310 % ================================================================ 194 \section{Domain: Horizontal Grid (mesh) (\mdl{domhgr} module)} 311 \section [Domain: Horizontal Grid (mesh) (\textit{domhgr})] 312 {Domain: Horizontal Grid (mesh) \small{(\mdl{domhgr} module)} } 195 313 \label{DOM_hgr} 196 314 … … 201 319 \label{DOM_hgr_coord_e} 202 320 203 The ocean mesh (i.e. the position of all the scalar and vector points) is defined by the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. The grid-points are located at integer or integer and a half values of as indicated in Table~\ref{Tab_cell}. The associated scale factors are defined using the analytical first derivative of the transformation \eqref{Eq_scale_factors}. These definitions are done in two modules, \mdl{domhgr} and \mdl{domzgr}, which provide the horizontal and vertical meshes, respectively. This section deals with the horizontal mesh parameters. 204 205 In a horizontal plane, the location of all the model grid points is defined from the analytical expressions of the latitude $\varphi$ and the longitude $\lambda$ as a function of $(i,j)$. The horizontal scale factors are calculated using \eqref{Eq_scale_factors}. For example, when the latitude and longitude are function of a single value ($j$ and $i$, respectively) (geographical configuration of the mesh), the horizontal mesh definition reduces to define the wanted $\varphi(j)$, $\varphi'(j)$, $\lambda(i)$, and $\lambda'(i)$ in the \mdl{domhgr} module. The model computes the grid-point positions and scale factors in the horizontal plane as follows: 321 The ocean mesh ($i.e.$ the position of all the scalar and vector points) is defined 322 by the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. 323 The grid-points are located at integer or integer and a half values of as indicated 324 in Table~\ref{Tab_cell}. The associated scale factors are defined using the 325 analytical first derivative of the transformation \eqref{Eq_scale_factors}. These 326 definitions are done in two modules, \mdl{domhgr} and \mdl{domzgr}, which 327 provide the horizontal and vertical meshes, respectively. This section deals with 328 the horizontal mesh parameters. 329 330 In a horizontal plane, the location of all the model grid points is defined from the 331 analytical expressions of the longitude $\lambda$ and latitude $\varphi$ as a 332 function of $(i,j)$. The horizontal scale factors are calculated using 333 \eqref{Eq_scale_factors}. For example, when the longitude and latitude are 334 function of a single value ($i$ and $j$, respectively) (geographical configuration 335 of the mesh), the horizontal mesh definition reduces to define the wanted 336 $\lambda(i)$, $\varphi(j)$, and their derivatives $\lambda'(i)$ $\varphi'(j)$ in the 337 \mdl{domhgr} module. The model computes the grid-point positions and scale 338 factors in the horizontal plane as follows: 206 339 \begin{flalign*} 207 \lambda_T &\equiv \text{glamt} = \lambda(i) &\varphi_T &\equiv \text{gphit} = \varphi(j)\\208 \lambda_u &\equiv \text{glamu}= \lambda(i+1/2)& 209 \lambda_v &\equiv \text{glamv}= \lambda(i) &\varphi_v &\equiv \text{gphiv} = \varphi(j+1/2)\\210 \lambda_f &\equiv \text{glamf }= \lambda(i+1/2)& 340 \lambda_T &\equiv \text{glamt}= \lambda(i) & \varphi_T &\equiv \text{gphit} = \varphi(j)\\ 341 \lambda_u &\equiv \text{glamu}= \lambda(i+1/2)& \varphi_u &\equiv \text{gphiu}= \varphi(j)\\ 342 \lambda_v &\equiv \text{glamv}= \lambda(i) & \varphi_v &\equiv \text{gphiv} = \varphi(j+1/2)\\ 343 \lambda_f &\equiv \text{glamf }= \lambda(i+1/2)& \varphi_f &\equiv \text{gphif }= \varphi(j+1/2) 211 344 \end{flalign*} 212 345 \begin{flalign*} 213 346 e_{1T} &\equiv \text{e1t} = r_a |\lambda'(i) \; \cos\varphi(j) |& 214 e_{2T} &\equiv \text{e2t} = r_a |\varphi'(j)| \\347 e_{2T} &\equiv \text{e2t} = r_a |\varphi'(j)| \\ 215 348 e_{1u} &\equiv \text{e1t} = r_a |\lambda'(i+1/2) \; \cos\varphi(j) |& 216 349 e_{2u} &\equiv \text{e2t} = r_a |\varphi'(j)|\\ … … 220 353 e_{2f} &\equiv \text{e2t} = r_a |\varphi'(j+1/2)| 221 354 \end{flalign*} 222 where the last letter of each computational name indicates the grid point considered and $r_a$ is the earth radius (defined in \mdl{phycst} along with all universal constants). Note that the horizontal position and scale factors of $w$-points are exactly equal to those of $T-$points, thus no specific arrays are defined at those grid-points. 223 224 Note that the definition of the scale factors --- as the analytical first derivative of the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$ --- is specific to the OPA model \citep{Marti1992}. As an example, $e_{1T}$ is defined locally at a $T$-point, whereas many other models on a C grid choose to define such a scale factor as the distance between the $U$-points on each side of the $T$-point. Relying on an analytical transformation has two advantages: firstly, there is no ambiguity in the scale factors appearing in the discrete equations, since they are first introduced in the continuous equations; secondly, analytical transformations encourage good practice by the definition of smooth grids \citep{Treguier1996}. An example of the effect of such a choice is shown in Fig.~\ref{Fig_zgr_e3}. 355 where the last letter of each computational name indicates the grid point 356 considered and $r_a$ is the earth radius (defined in \mdl{phycst} along with 357 all universal constants). Note that the horizontal position of and scale factors 358 at $w$-points are exactly equal to those of $T$-points, thus no specific arrays 359 are defined at $w$-points. 360 361 Note that the definition of the scale factors ($i.e.$ as the analytical first derivative 362 of the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$) is 363 specific to the \NEMO model \citep{Marti1992}. As an example, $e_{1T}$ is defined 364 locally at a $T$-point, whereas many other models on a C grid choose to define 365 such a scale factor as the distance between the $U$-points on each side of the 366 $T$-point. Relying on an analytical transformation has two advantages: firstly, there 367 is no ambiguity in the scale factors appearing in the discrete equations, since they 368 are first introduced in the continuous equations; secondly, analytical transformations 369 encourage good practice by the definition of smoothly varying grids (rather than 370 allowing the user to set arbitrary jumps in thickness between adjacent layers) 371 \citep{Treguier1996}. An example of the effect of such a choice is shown in 372 Fig.~\ref{Fig_zgr_e3}. 225 373 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 226 374 \begin{figure}[!t] \label{Fig_zgr_e3} \begin{center} 227 375 \includegraphics[width=0.90\textwidth]{./Figures/Fig_zgr_e3.pdf} 228 \caption{(a) Traditional definition of grid-point position and grid-size in the vertical versus (b) analytically derived grid-point position and scale factors. For both grid here,a same $w$-point depth has been chosen but in (a) the $T$-points are set at the middle of $w$-points while in (b) they are defined from an analytical function: $z(k)=5\,(i-1/2)^3 - 45\,(i-1/2)^2 + 140\,(i-1/2) - 150$. Note the resulting difference between the value of the grid-size $\Delta_k$ and those of the scale factor $e_k$. } 376 \caption{Comparison of (a) traditional definitions of grid-point position and grid-size 377 in the vertical, and (b) analytically derived grid-point position and scale factors. For 378 both grids here, the same $w$-point depth has been chosen but in (a) the 379 $T$-points are set half way between $w$-points while in (b) they are defined from 380 an analytical function: $z(k)=5\,(i-1/2)^3 - 45\,(i-1/2)^2 + 140\,(i-1/2) - 150$. 381 Note the resulting difference between the value of the grid-size $\Delta_k$ and 382 those of the scale factor $e_k$. } 229 383 \end{center} \end{figure} 230 384 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 231 385 232 386 % ------------------------------------------------------------------------------------------------------------- 233 % Choice of horizontal grid s234 % ------------------------------------------------------------------------------------------------------------- 235 \subsection{Choice of horizontal grid s}387 % Choice of horizontal grid 388 % ------------------------------------------------------------------------------------------------------------- 389 \subsection{Choice of horizontal grid} 236 390 \label{DOM_hgr_msh_choice} 237 391 238 The user has three options to define a horizontal grid, involving the parameter $jphgr\_mesh$ of the \mdl{par\_oce} module. 239 \begin{enumerate} 240 \item For the most general curvilinear orthogonal grids, the coordinates and their first derivatives with respect to $i$ and $j$ are provided in a file, read in \rou{hgr\_read} subroutine of the domhgr module: \jp{jphgr\_mesh}=0. 241 \item A few simple analytical grids are provided as examples, that can be selected by setting \jp{jphgr\_mesh}=1 to 5 (see below) 242 \item For other analytical grids, the \mdl{domhgr} module must be modified by the user. 243 \end{enumerate} 244 245 There are two simple cases of geographical grids on the sphere. With \jp{jphgr\_mesh}=1, the grid is regular in space, with grid sizes specified by parameters \pp{ppe1\_deg} and \pp{ppe2\_deg}, respectively. A geographical grid 246 can be very anisotropic at high latitudes, because of the convergence of meridians (the zonal scale factors $e_1$ become much smaller than the meridional scale factors $e_2$). The Mercator grid (\jp{jphgr\_mesh}=4) avoids this anisotropy by refining the meridional scale factors in the same way as the zonal ones. In that case, meridional scale factors and latitudes are calculated analytically using the formulae appropriate for a Mercator projection, based on \pp{ppe1\_deg} which is a reference grid spacing at the equator (this applies even when the geographical equator is situated outside the model domain). In those two cases (\jp{jphgr\_mesh}=1 or 4), the grid position is defined by the longitude and latitude of the south-westhernmost point (\pp{ppglamt0} and \pp{ppgphi0}). Note that for the Mercator grid the user need only provide an approximate starting latitude: the real latitude will be recalculated analytically, so as to ensure that the equator corresponds to a $T$- and$ U$-point. 247 248 Rectangular grids ignoring the spherical geometry are defined with \jp{jphgr\_mesh} = 2, 3, 5. The domain is either a $f$-plane (\jp{jphgr\_mesh} = 2, Coriolis factor is constant) or a beta-plane (\jp{jphgr\_mesh} = 3, the Coriolis factor is linear in the $j$-direction). The grid size is uniform in each direction, and given in meters by the parameters \pp{ppe1\_m} and \pp{ppe2\_m} respectively. The zonal grid coordinate (glam. arrays) is in kilometers, starting at zero with the first T point. The meridional coordinate (gphi. arrays) is in kilometers, and the second $T$-point corresponds to coordinate gphit=0. The input parameter \pp{ppglam0} is ignored. \pp{ppgphi0} is used to set the reference latitude for computation of the Coriolis parameter. In the case of the beta plane, \pp{ppgphi0} corresponds to the center of the domain. Finally, the special case \jp{jphgr\_mesh}=5 corresponds to a beta plane in a rotated domain for the GYRE configuration representing a classical mid-latitude double gyre system. The rotation allows to maximize the jet length relative to the gyre areas (and the number of grid points). 249 250 The choice of the grid must be consistent with the boundary conditions specified by the parameter \jp{jperio} (see {\S\ref{LBC}). 392 The user has three options available in defining a horizontal grid, which involve 393 the parameter $jphgr\_mesh$ of the \mdl{par\_oce} module. 394 \begin{description} 395 \item[\jp{jphgr\_mesh}=0] The most general curvilinear orthogonal grids. 396 The coordinates and their first derivatives with respect to $i$ and $j$ are 397 provided in a file, read in \rou{hgr\_read} subroutine of the domhgr module. 398 \item[\jp{jphgr\_mesh}=1 to 5] A few simple analytical grids are provided (see below). 399 For other analytical grids, the \mdl{domhgr} module must be modified by the user. 400 \end{description} 401 402 There are two simple cases of geographical grids on the sphere. With 403 \jp{jphgr\_mesh}=1, the grid (expressed in degrees) is regular in space, 404 with grid sizes specified by parameters \pp{ppe1\_deg} and \pp{ppe2\_deg}, 405 respectively. Such a geographical grid can be very anisotropic at high latitudes 406 because of the convergence of meridians (the zonal scale factors $e_1$ 407 become much smaller than the meridional scale factors $e_2$). The Mercator 408 grid (\jp{jphgr\_mesh}=4) avoids this anisotropy by refining the meridional scale 409 factors in the same way as the zonal ones. In this case, meridional scale factors 410 and latitudes are calculated analytically using the formulae appropriate for 411 a Mercator projection, based on \pp{ppe1\_deg} which is a reference grid spacing 412 at the equator (this applies even when the geographical equator is situated outside 413 the model domain). 414 %%% 415 \gmcomment{ give here the analytical expression of the Mercator mesh} 416 %%% 417 In these two cases (\jp{jphgr\_mesh}=1 or 4), the grid position is defined by the 418 longitude and latitude of the south-westernmost point (\pp{ppglamt0} 419 and \pp{ppgphi0}). Note that for the Mercator grid the user need only provide 420 an approximate starting latitude: the real latitude will be recalculated analytically, 421 in order to ensure that the equator corresponds to line passing through $T$- 422 and $u$-points. 423 424 Rectangular grids ignoring the spherical geometry are defined with 425 \jp{jphgr\_mesh} = 2, 3, 5. The domain is either an $f$-plane (\jp{jphgr\_mesh} = 2, 426 Coriolis factor is constant) or a beta-plane (\jp{jphgr\_mesh} = 3, the Coriolis factor 427 is linear in the $j$-direction). The grid size is uniform in meter in each direction, 428 and given by the parameters \pp{ppe1\_m} and \pp{ppe2\_m} respectively. 429 The zonal grid coordinate (\textit{glam} arrays) is in kilometers, starting at zero 430 with the first $T$-point. The meridional coordinate (gphi. arrays) is in kilometers, 431 and the second $T$-point corresponds to coordinate $gphit=0$. The input 432 parameter \pp{ppglam0} is ignored. \pp{ppgphi0} is used to set the reference 433 latitude for computation of the Coriolis parameter. In the case of the beta plane, 434 \pp{ppgphi0} corresponds to the center of the domain. Finally, the special case 435 \jp{jphgr\_mesh}=5 corresponds to a beta plane in a rotated domain for the 436 GYRE configuration, representing a classical mid-latitude double gyre system. 437 The rotation allows us to maximize the jet length relative to the gyre areas 438 (and the number of grid points). 439 440 The choice of the grid must be consistent with the boundary conditions specified 441 by the parameter \jp{jperio} (see {\S\ref{LBC}). 251 442 252 443 % ------------------------------------------------------------------------------------------------------------- … … 256 447 \label{DOM_hgr_files} 257 448 258 All the arrays related to a particular ocean model configuration (grid-point position, scale factors, masks) can be saved in files if $\np{nmsh} \not= 0$ (namelist parameter). This can be particularly useful for plots and off-line diagnostics. In some cases, the user may choose to make a local modification of a scale factor in the code. This is the case in global configurations when restricting the width of a specific strait (usually a one-grid-point strait that happens to be too wide due to the insufficient model resolution). On example is Lombok Strait in the ORCA2 configuration. When such modifications are done, the output grid written when $\np{nmsh} \not=0$ is not exactly equal to the input grid. 449 All the arrays relating to a particular ocean model configuration (grid-point 450 position, scale factors, masks) can be saved in files if $\np{nmsh} \not= 0$ 451 (namelist parameter). This can be particularly useful for plots and off-line 452 diagnostics. In some cases, the user may choose to make a local modification 453 of a scale factor in the code. This is the case in global configurations when 454 restricting the width of a specific strait (usually a one-grid-point strait that 455 happens to be too wide due to insufficient model resolution). An example 456 is Gibraltar Strait in the ORCA2 configuration. When such modifications are done, 457 the output grid written when $\np{nmsh} \not=0$ is no more equal to the input grid. 259 458 260 459 % ================================================================ 261 460 % Domain: Vertical Grid (domzgr) 262 461 % ================================================================ 263 \section{Domain: Vertical Grid (\mdl{domzgr} module)} 462 \section [Domain: Vertical Grid (\textit{domzgr})] 463 {Domain: Vertical Grid \small{(\mdl{domzgr} module)} } 264 464 \label{DOM_zgr} 265 465 %-----------------------------------------nam_zgr & namdom------------------------------------------- … … 268 468 %------------------------------------------------------------------------------------------------------------- 269 469 270 In the vertical, the model mesh is determined by four things: (1) the bathymetry given in meters ; (2) the number of levels of the model (\jp{jpk}) ; (3) the analytical transformation $z(i,j,k)$ and the vertical scale factors 271 (derivatives of the transformation) ; and (4) the masking system, i.e. the number of wet model levels at each $(i,j)$. 470 In the vertical, the model mesh is determined by four things: 471 (1) the bathymetry given in meters ; 472 (2) the number of levels of the model (\jp{jpk}) ; 473 (3) the analytical transformation $z(i,j,k)$ and the vertical scale factors 474 (derivatives of the transformation) ; 475 and (4) the masking system, $i.e.$ the number of wet model levels at each 476 $(i,j)$ column of points. 272 477 273 478 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 274 479 \begin{figure}[!tb] \label{Fig_z_zps_s_sps} \begin{center} 275 480 \includegraphics[width=1.0\textwidth]{./Figures/Fig_z_zps_s_sps.pdf} 276 \caption{The ocean bottom as seen by the model: (a) $z$-coordinate with full step, (b) $z$-coordinate with partial step, (c) $s$-coordinate: terrain following representation, (d) hybrid $s-z$ coordinate, (e) hybrid $s-z$ coordinate with partial step, and (f) same as (e) but with variable volume level associated with the non-linear free surface. Note that the variable volume level (\key{vvl}) could be used with any of the 5 coordinates (a) to (e).} 481 \caption{The ocean bottom as seen by the model: 482 (a) $z$-coordinate with full step, 483 (b) $z$-coordinate with partial step, 484 (c) $s$-coordinate: terrain following representation, 485 (d) hybrid $s-z$ coordinate, 486 (e) hybrid $s-z$ coordinate with partial step, and 487 (f) same as (e) but with variable volume associated with the non-linear free surface. 488 Note that the variable volume option (\key{vvl}) can be used with any of the 489 5 coordinates (a) to (e).} 277 490 \end{center} \end{figure} 278 491 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 279 492 280 The choice of a vertical coordinate among all those offered in NEMO, even if it is made through a namelist parameter, must be done once of all at the beginning of an experiment. It is not intended as an option which can be 281 enabled or disabled in the middle of an experiment. Three main choices are offered (Fig.~\ref{Fig_z_zps_s_sps}a to c): $z$-coordinate with full step bathymetry (\np{ln\_zco}=true), $z$-coordinate with partial step bathymetry (\np{ln\_zps}=true), or generalized, $s$-coordinate (\np{ln\_sco}=true). Hybridation of the three main 282 coordinates are available: hybrid $s-z$ or $s-zps$ coordinate (Fig.~\ref{Fig_z_zps_s_sps}d and \ref{Fig_z_zps_s_sps}e). When using the variable volume option \key{vvl}), the coordinate follow the time-variation of the free surface so that the transformation is time dependent: $z(i,j,k,t)$ (Fig.~\ref{Fig_z_zps_s_sps}f). This option can be used with full step bathymetry or $s$-coordinates (hybride and partial step coordinates not yet implemented in NEMO v2.3). 283 284 Contrary to the horizontal grid, the vertical grid is computed in the code and no provision is made for reading it from a file. The only input file is the bathymetry (in meters). After reading the bathymetry, the algorithm for vertical grid definition differs between the different options: 493 The choice of a vertical coordinate, even if it is made through a namelist parameter, 494 must be done once of all at the beginning of an experiment. It is not intended as an 495 option which can be enabled or disabled in the middle of an experiment. Three main 496 choices are offered (Fig.~\ref{Fig_z_zps_s_sps}a to c): $z$-coordinate with full step 497 bathymetry (\np{ln\_zco}=true), $z$-coordinate with partial step bathymetry 498 (\np{ln\_zps}=true), or generalized, $s$-coordinate (\np{ln\_sco}=true). 499 Hybridation of the three main coordinates are available: $s-z$ or $s-zps$ coordinate 500 (Fig.~\ref{Fig_z_zps_s_sps}d and \ref{Fig_z_zps_s_sps}e). When using the variable 501 volume option \key{vvl}) ($i.e.$ non-linear free surface), the coordinate follow the 502 time-variation of the free surface so that the transformation is time dependent: 503 $z(i,j,k,t)$ (Fig.~\ref{Fig_z_zps_s_sps}f). This option can be used with full step 504 bathymetry or $s$-coordinate (hybride and partial step coordinates have not 505 yet been tested in NEMO v2.3). 506 507 Contrary to the horizontal grid, the vertical grid is computed in the code and no 508 provision is made for reading it from a file. The only input file is the bathymetry 509 (in meters)\footnote{N.B. in full step $z$-coordinate, a \textit{bathy\_level} file can 510 replace the \textit{bathy\_meter} file, so that the computation of the number of 511 wet ocean point in each water column is by-passed}. After reading the bathymetry, 512 the algorithm for vertical grid definition differs between the different options: 285 513 \begin{description} 286 514 \item[\textit{zco}] set a reference coordinate transformation $z_0 (k)$, and set $z(i,j,k,t)=z_0 (k)$. 287 515 \item[\textit{zps}] set a reference coordinate transformation $z_0 (k)$, and 288 calculate the height at the deepest levels using the bathymetry, to obtain the final three-dimensional depth and scale factor arrays. 289 \item[\textit{sco}] Smooth the bathymetry to fullfill the hydrostatic consistency criteria and set the three-dimensional transformation. 290 \item[\textit{s-z} and \textit{s-zps}] Smooth the bathymetry to fullfill the hydrostatic consistency criteria and set the three-dimensional transformation $z(i,j,k)$, and possibly introduce masking of extra land points to better fit the original bathymetry file 516 calculate the thickness of the deepest level at each $(i,j)$ point using the 517 bathymetry, to obtain the final three-dimensional depth and scale factor arrays. 518 \item[\textit{sco}] smooth the bathymetry to fulfil the hydrostatic consistency 519 criteria and set the three-dimensional transformation. 520 \item[\textit{s-z} and \textit{s-zps}] smooth the bathymetry to fulfil the hydrostatic 521 consistency criteria and set the three-dimensional transformation $z(i,j,k)$, and 522 possibly introduce masking of extra land points to better fit the original bathymetry file 291 523 \end{description} 292 293 Generally, the arrays describing the grid point depths and vertical scale factors are three dimensional arrays $(i,j,k)$. In the special case of $z$-coordinates with full step bottom topography, it is possible to define 294 those arrays as one-dimensional, in order to save memory. This is performed by defining the \key{zco} C-Pre-Processor (CPP) key. To improve the code readability while providing this flexibility, the vertical coordinates and scale factors are defined as functions of $(i,j,k)$ with "fs" as prefix (examples: \textit{fsdeptht, fse3t,} etc) that can be equal to three-dimensional arrays, or a one dimensional array when \key{zco} is defined. These functions are defined in the file 295 \textit{domzgr\_substitute.h90} of the DOM directory. They are used through the code, and replaced by the corresponding arrays at the time of pre-processing (CPP capability). 524 %%% 525 \gmcomment{ add the description of the smoothing: envelop topography...} 526 %%% 527 528 Generally, the arrays describing the grid point depths and vertical scale factors 529 are three dimensional arrays $(i,j,k)$. In the special case of $z$-coordinates with 530 full step bottom topography, it is possible to define those arrays as one-dimensional, 531 in order to save memory. This is performed by defining the \key{zco} 532 C-Pre-Processor (CPP) key. To improve the code readability while providing this 533 flexibility, the vertical coordinate and scale factors are defined as functions of 534 $(i,j,k)$ with "fs" as prefix (examples: \textit{fsdeptht, fse3t,} etc) that can be either 535 three-dimensional arrays, or a one dimensional array when \key{zco} is defined. 536 These functions are defined in the file \hf{domzgr\_substitute} of the DOM directory. 537 They are used throughout the code, and replaced by the corresponding arrays at 538 the time of pre-processing (CPP capability). 296 539 297 540 % ------------------------------------------------------------------------------------------------------------- … … 304 547 namelist variable \np{ntopo}: 305 548 \begin{description} 306 \item[\np{ntopo} = 0] a flat-bottom domain is defined. The total depth $z_w (jpk)$ is given by the coordinate transformation. The domain can either a closed basin or a periodic channel according to the parameter \jp{jperio}. 307 \item[\np{ntopo} = -1] a domain with a bump of topography at the central latitude and 1/3 of the domain width. This is meant for the "EEL-R5" configuration, a periodic or open boundary channel with a seamount. 308 \item[\np{ntopo} = 1] read a bathymetry. The bathymetry file (Netcdf format) provides the ocean depth (positive, in meters) at each grid point of the model grid. The bathymetry is usually built by interpolating a standard bathymetry product (e.g., ETOPO2) onto the horizontal ocean mesh. The bathymetry file defines the coastline: where the bathymetry is zero, no model levels are defined (all levels are masked). 549 \item[\np{ntopo} = 0] a flat-bottom domain is defined. The total depth $z_w (jpk)$ 550 is given by the coordinate transformation. The domain can either be a closed 551 basin or a periodic channel depending on the parameter \jp{jperio}. 552 \item[\np{ntopo} = -1] a domain with a bump of topography one third of the 553 domain width at the central latitude. This is meant for the "EEL-R5" configuration, 554 a periodic or open boundary channel with a seamount. 555 \item[\np{ntopo} = 1] read a bathymetry. The bathymetry file (Netcdf format) 556 provides the ocean depth (positive, in meters) at each grid point of the model grid. 557 The bathymetry is usually built by interpolating a standard bathymetry product 558 ($e.g.$ ETOPO2) onto the horizontal ocean mesh. Defining the bathymetry also 559 defines the coastline: where the bathymetry is zero, no model levels are defined 560 (all levels are masked). 309 561 \end{description} 310 562 311 When using the rigid lid approximation (\key{dynspg\_rl} defined) isolated land masses (islands) must be identified by negative integers in the input bathymetry file (see \S\ref{MISC_solisl}). 312 313 When the ocean is coupled to an atmospheric model it is better to represent 563 When using the rigid lid approximation (\key{dynspg\_rl} is defined) isolated land 564 masses (islands) must be identified by negative integers in the input bathymetry file 565 (see \S\ref{MISC_solisl}). 566 567 When a global ocean is coupled to an atmospheric model it is better to represent 314 568 all large water bodies (e.g, great lakes, Caspian sea...) even if the model 315 resolution does not allow to represent their communication with the rest of 316 the ocean. This is unnecessary when the ocean is forced by fixed atmospheric 317 conditions. A possibility is offered to the user to set to zero the 318 bathymetry in rectangular regions covering those closed seas (see \S\ref{MISC_closea}), but the code has to be adapted to the user's configuration. 569 resolution does not allow their communication with the rest of the ocean. 570 This is unnecessary when the ocean is forced by fixed atmospheric conditions, 571 so these seas can be removed from the ocean domain. The user has the option 572 to set the bathymetry in closed seas to zero (see \S\ref{MISC_closea}), but the 573 code has to be adapted to the user's configuration. 319 574 320 575 % ------------------------------------------------------------------------------------------------------------- 321 576 % z-coordinate and reference coordinate transformation 322 577 % ------------------------------------------------------------------------------------------------------------- 323 \subsection [$z$-coordinate (\np{ln\_zco}=Tor \key{zco})]324 {$z$-coordinate (\np{ln\_zco}=Tor \key{zco}) and reference coordinate}578 \subsection[$z$-coordinate (\np{ln\_zco} or \key{zco})] 579 {$z$-coordinate (\np{ln\_zco}=.true. or \key{zco}) and reference coordinate} 325 580 \label{DOM_zco} 326 581 … … 328 583 \begin{figure}[!tb] \label{Fig_zgr} \begin{center} 329 584 \includegraphics[width=0.90\textwidth]{./Figures/Fig_zgr.pdf} 330 \caption{Default vertical mesh for ORCA2-L30. Vertical level functions for (a) T-point depth and (b) the associated scale factor as computed from (III.2.1) in z-coordinates.} 585 \caption{Default vertical mesh for ORCA2: 30 ocean levels (L30). Vertical level 586 functions for (a) T-point depth and (b) the associated scale factor as computed 587 from \eqref{DOM_zgr_ana} using \eqref{DOM_zgr_coef} in $z$-coordinate.} 331 588 \end{center} \end{figure} 332 589 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 333 590 334 The reference coordinate transformation $z_0 (k)$ defines the arrays \textit{gdept0} and \textit{gdepw0} for $T$- and $w$-points, respectively. As indicated on Fig.\ref{Fig_index_vert} \jp{jpk} is the number of $w$-levels. $gdepw(1)$ being the ocean surface. There are at most \jp{jpk}-1 $T$-points in the ocean, the additional $T$-point at $jk=jpk$ is below the sea floor and is not used. The vertical location of $w$- and $T$-levels is defined from the analytic expression of the depth $z_0 (k)$ whose analytic derivative with respect to $k$ provides the vertical scale factors. The user must provide the analytical expression of both $z_0 $and its first derivative with respect to $k$. This is done in routine \mdl{domzgr} through statement functions, using parameters provided in the \textit{par\_oce.h90} file. 591 The reference coordinate transformation $z_0 (k)$ defines the arrays $gdept_0$ 592 and $gdepw_0$ for $T$- and $w$-points, respectively. As indicated on 593 Fig.\ref{Fig_index_vert} \jp{jpk} is the number of $w$-levels. $gdepw_0(1)$ is the 594 ocean surface. There are at most \jp{jpk}-1 $T$-points inside the ocean, the 595 additional $T$-point at $jk=jpk$ is below the sea floor and is not used. 596 The vertical location of $w$- and $T$-levels is defined from the analytic expression 597 of the depth $z_0(k)$ whose analytical derivative with respect to $k$ provides the 598 vertical scale factors. The user must provide the analytical expression of both 599 $z_0$ and its first derivative with respect to $k$. This is done in routine \mdl{domzgr} 600 through statement functions, using parameters provided in the \textit{par\_oce.h90} file. 335 601 336 602 It is possible to define a simple regular vertical grid by giving zero stretching (\pp{ppacr=0}). In that case, the parameters \jp{jpk} (number of $w$-levels) and \pp{pphmax} (total ocean depth in meters) fully define the grid. 337 603 338 For climate-related studies it is often desirable to concentrate the vertical resolution near the ocean surface. The following function is proposed as a standard for $z$-coordinates and partial steps: 604 For climate-related studies it is often desirable to concentrate the vertical resolution 605 near the ocean surface. The following function is proposed as a standard for a $z$-coordinate (with either full or partial steps): 339 606 \begin{equation} \label{DOM_zgr_ana} 340 607 \begin{split} … … 343 610 \end{split} 344 611 \end{equation} 345 where $k=1$ to \jp{jpk} for $w$-levels and $k=1$ to $k=1$ for $T-$levels. Such an expression allows us to define a nearly uniform vertical location of levels at the ocean top and bottom with a smooth hyperbolic tangent transition in between (Fig.~\ref{Fig_zgr}). 346 347 The first grid defined for ORCA2 had $10~m$ ($500~m)$ resolution in the surface (bottom) layers and a depth which varies from 0 at the sea surface to a minimum of $-5000~m$. This leads to the following conditions: 612 where $k=1$ to \jp{jpk} for $w$-levels and $k=1$ to $k=1$ for $T-$levels. Such an 613 expression allows us to define a nearly uniform vertical location of levels at the 614 ocean top and bottom with a smooth hyperbolic tangent transition in between 615 (Fig.~\ref{Fig_zgr}). 616 617 The most used vertical grid for ORCA2 has $10~m$ ($500~m)$ resolution in the 618 surface (bottom) layers and a depth which varies from 0 at the sea surface to a 619 minimum of $-5000~m$. This leads to the following conditions: 348 620 \begin{equation} \label{DOM_zgr_coef} 349 621 \begin{split} … … 355 627 \end{equation} 356 628 357 With the choice of the stretching $h_{cr} =3$ and the number of levels \jp{jpk}=$31$, the four coefficients $h_{sur}$, $h_{0}$, $h_{1}$, and $h_{th}$ in \eqref{DOM_zgr_ana} have been determined such that \eqref{DOM_zgr_coef} is satisfied, through an optimisation procedure using a bisection method. For the first standard 358 ORCA2 vertial grid this led to the following values: $h_{sur} =4762.96$, $h_0 =255.58, h_1 =245.5813$, and $h_{th} =21.43336$. The resulting depths and scale factors as a function of the model levels are shown in Fig.~\ref{Fig_zgr} and given in Table \ref{Tab_orca_zgr}. Those values correspond to the parameters \pp{ppsur}, \pp{ppa0}, \pp{ppa1}, \pp{ppkth} in the parameter file \mdl{par\_oce}. 629 With the choice of the stretching $h_{cr} =3$ and the number of levels 630 \jp{jpk}=$31$, the four coefficients $h_{sur}$, $h_{0}$, $h_{1}$, and $h_{th}$ in 631 \eqref{DOM_zgr_ana} have been determined such that \eqref{DOM_zgr_coef} is 632 satisfied, through an optimisation procedure using a bisection method. For the first 633 standard ORCA2 vertical grid this led to the following values: $h_{sur} =4762.96$, 634 $h_0 =255.58, h_1 =245.5813$, and $h_{th} =21.43336$. The resulting depths and 635 scale factors as a function of the model levels are shown in Fig.~\ref{Fig_zgr} and 636 given in Table \ref{Tab_orca_zgr}. Those values correspond to the parameters 637 \pp{ppsur}, \pp{ppa0}, \pp{ppa1}, \pp{ppkth} in the parameter file \mdl{par\_oce}. 359 638 360 639 Rather than entering parameters $h_{sur}$, $h_{0}$, and $h_{1}$ directly, it is 361 640 possible to recalculate them. In that case the user sets 362 \pp{ppsur}=\pp{ppa0}=\pp{ppa1}=\pp{pp\_to\_be\_computed}, in \mdl{par\_oce}, and specifies instead the four following parameters: 641 \pp{ppsur}=\pp{ppa0}=\pp{ppa1}=\pp{pp\_to\_be\_computed}, in \mdl{par\_oce}, 642 and specifies instead the four following parameters: 363 643 \begin{itemize} 364 \item \pp{ppacr}=$h_{cr} $: stretching factor (nondimensional). The larger \pp{ppacr}, the smaller the stretching. Values from $3$ to $10$ are usual. 365 \item \pp{ppkth}=$h_{th} $: is approximately the model level at which maximum stretching occurs (nondimensional, usually of order 1/2 or 2/3 of \jp{jpk}) 644 \item \pp{ppacr}=$h_{cr} $: stretching factor (nondimensional). The larger 645 \pp{ppacr}, the smaller the stretching. Values from $3$ to $10$ are usual. 646 \item \pp{ppkth}=$h_{th} $: is approximately the model level at which maximum 647 stretching occurs (nondimensional, usually of order 1/2 or 2/3 of \jp{jpk}) 366 648 \item \pp{ppdzmin}: minimum thickness for the top layer (in meters) 367 649 \item \pp{pphmax}: total depth of the ocean (meters). 368 650 \end{itemize} 369 As an example, for the $45$ layers used in DRAKKAR configuration those parameters are: \jp{jpk}=46, \pp{ppacr}=9, \pp{ppkth}=23.563, \pp{ppdzmin}=6m, \pp{pphmax}=5750m. 651 As an example, for the $45$ layers used in the DRAKKAR configuration those 652 parameters are: \jp{jpk}=46, \pp{ppacr}=9, \pp{ppkth}=23.563, \pp{ppdzmin}=6m, 653 \pp{pphmax}=5750m. 370 654 371 655 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> … … 396 680 21 & \textbf{732.20} & 611.89 & \textbf{261.03} & 220.35 \\ \hline 397 681 22 & \textbf{1033.22}& 872.87 & \textbf{339.39} & 301.42 \\ \hline 398 23 & \textbf{1405.70}& 1211.59 & 399 24 & \textbf{1830.89}& 1612.98 & 400 25 & \textbf{2289.77}& 2057.13 & 401 26 & \textbf{2768.24}& 2527.22 & 402 27 & \textbf{3257.48}& 3011.90 & 403 28 & \textbf{3752.44}& 3504.46 & 404 29 & \textbf{4250.40}& 4001.16 & 405 30 & \textbf{4749.91}& 4500.02 & 682 23 & \textbf{1405.70}& 1211.59 & \textbf{402.26} & 373.31 \\ \hline 683 24 & \textbf{1830.89}& 1612.98 & \textbf{444.87} & 426.00 \\ \hline 684 25 & \textbf{2289.77}& 2057.13 & \textbf{470.55} & 459.47 \\ \hline 685 26 & \textbf{2768.24}& 2527.22 & \textbf{484.95} & 478.83 \\ \hline 686 27 & \textbf{3257.48}& 3011.90 & \textbf{492.70} & 489.44 \\ \hline 687 28 & \textbf{3752.44}& 3504.46 & \textbf{496.78} & 495.07 \\ \hline 688 29 & \textbf{4250.40}& 4001.16 & \textbf{498.90} & 498.02 \\ \hline 689 30 & \textbf{4749.91}& 4500.02 & \textbf{500.00} & 499.54 \\ \hline 406 690 31 & \textbf{5250.23}& 5000.00 & \textbf{500.56} & 500.33 \\ \hline 407 691 \end{tabular} \end{center} 408 \caption{Default vertical mesh in $z$-coordinate for 30 layers ORCA2 configuration as computed from \eqref{DOM_zgr_ana} using the coefficients given in \eqref{DOM_zgr_coef}} 692 \caption{Default vertical mesh in $z$-coordinate for 30 layers ORCA2 configuration 693 as computed from \eqref{DOM_zgr_ana} using the coefficients given in 694 \eqref{DOM_zgr_coef}} 409 695 \end{table} 410 696 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> … … 413 699 % z-coordinate with partial step 414 700 % ------------------------------------------------------------------------------------------------------------- 415 \subsection{z-coordinate with partial step (\np{ln\_zps}=T)} 701 \subsection [$z$-coordinate with partial step (\np{ln\_zps})] 702 {$z$-coordinate with partial step (\np{ln\_zps}=.true.)} 416 703 \label{DOM_zps} 417 %--------------------------------------------namdom----------------------------------------------------- 704 %--------------------------------------------namdom------------------------------------------------------- 418 705 \namdisplay{namdom} 419 706 %-------------------------------------------------------------------------------------------------------------- 420 707 421 In that case, the depths of the model levels are stilldefined by the708 In $z$-coordinate partial step, the depths of the model levels are defined by the 422 709 reference analytical function $z_0 (k)$ as described in the previous 423 section, exceptedin the bottom layer. The thickness of the bottom layer is710 section, \emph{except} in the bottom layer. The thickness of the bottom layer is 424 711 allowed to vary as a function of geographical location $(\lambda,\varphi)$ to allow a 425 712 better representation of the bathymetry, especially in the case of small … … 431 718 maximum thickness allowed is $2*e_{3t}(jpk-1)$. This has to be kept in mind when 432 719 specifying the maximum depth \pp{pphmax} in partial steps: for example, with 433 \pp{pphmax}$=5750~m$ for the DRAKKAR 45 layer sgrid, the maximum ocean depth allowed is actually $6000~m$ (the default thickness $e_{3t}(jpk-1)$ being $250~m$). Two720 \pp{pphmax}$=5750~m$ for the DRAKKAR 45 layer grid, the maximum ocean depth allowed is actually $6000~m$ (the default thickness $e_{3t}(jpk-1)$ being $250~m$). Two 434 721 variables in the namdom namelist are used to define the partial step 435 722 vertical grid. The mimimum water thickness (in meters) allowed for a cell … … 443 730 % s-coordinate 444 731 % ------------------------------------------------------------------------------------------------------------- 445 \subsection{$s$-coordinate (\np{ln\_sco}=T)} 732 \subsection [$s$-coordinate (\np{ln\_sco})] 733 {$s$-coordinate (\np{ln\_sco}=true)} 446 734 \label{DOM_sco} 447 %------------------------------------------ --nam_zgr_sco---------------------------------------------------735 %------------------------------------------nam_zgr_sco--------------------------------------------------- 448 736 \namdisplay{nam_zgr_sco} 449 737 %-------------------------------------------------------------------------------------------------------------- 450 In s-coordinate (\key{sco} defined), the depths of the model451 levels are defined from the product of a depth field and a stretching452 function andits derivative, respectively:738 In $s$-coordinate (\key{sco} is defined), the depth and thickness of the model 739 levels are defined from the product of a depth field and either a stretching 740 function or its derivative, respectively: 453 741 \begin{equation} \label{DOM_sco_ana} 454 742 \begin{split} 455 z(k) &= h(i,j) \; z_0(k) \\743 z(k) &= h(i,j) \; z_0(k) \\ 456 744 e_3(k) &= h(i,j) \; z_0'(k) 457 745 \end{split} 458 746 \end{equation} 459 where $h$ is the depth of the last $w$-level ($z_0(k)$) defined at $T-$point location460 in the horizontal and $z_0(k)$ is a function which varies from $0$ at the sea747 where $h$ is the depth of the last $w$-level ($z_0(k)$) defined at the $T$-point 748 location in the horizontal and $z_0(k)$ is a function which varies from $0$ at the sea 461 749 surface to $1$ at the ocean bottom. The depth field $h$ is not necessary the ocean 462 depth as a mixed step-like and bottomfollowing representation of the750 depth, since a mixed step-like and bottom-following representation of the 463 751 topography can be used (Fig.~\ref{Fig_z_zps_s_sps}d-e). In the example provided (\hf{zgr\_s} file) $h$ is a smooth envelope bathymetry and steps are used to represent sharp bathymetric gradients. 464 752 … … 472 760 \end{split} 473 761 \end{equation} 474 where $h_c $is the thermocline depth and $\theta$ and $b$ are the surface and762 where $h_c$ is the thermocline depth and $\theta$ and $b$ are the surface and 475 763 bottom control parameters such that $0\leqslant \theta \leqslant 20$, and 476 $0\leqslant b\leqslant 1$. Examples of the stretching function applied to a seamount are given in Fig.~\ref{Fig_sco_function}.764 $0\leqslant b\leqslant 1$. $b$ has been designed to allow surface and/or bottom increase of the vertical resolution (Fig.~\ref{Fig_sco_function}). 477 765 478 766 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 479 767 \begin{figure}[!tb] \label{Fig_sco_function} \begin{center} 480 768 \includegraphics[width=1.0\textwidth]{./Figures/Fig_sco_function.pdf} 481 \caption{ examples of the stretching function applied to a sea mont: from left to right, surface, surface and bottom, and bottom intensified resolution}769 \caption{Examples of the stretching function applied to a sea mont; from left to right: surface, surface and bottom, and bottom intensified resolutions} 482 770 \end{center} \end{figure} 483 771 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> … … 489 777 \label{DOM_zgr_vvl} 490 778 491 This option is described in the report by Levier \textit{et al.} (2007), available on the NEMO web site. 779 This option is described in the Report by Levier \textit{et al.} (2007), available on 780 the \NEMO web site. 492 781 493 782 %gm% key advantage: minimise the diffusion/dispertion associated with advection in response to high frequency surface disturbances … … 511 800 512 801 Modifications of the model bathymetry are performed in the \textit{bat\_ctl} 513 routine (see \mdl{domzgr} module) after mbathy is computed. Isolated grid points that do not 514 communicate with another ocean point at the same level are eliminated. 515 516 In case of rigid-lid approximation and islands in the computational domain (\np{ln\_dynspg\_rl}=true and \key{island} defined), the \textit{mbathy} array must be provided and takes values from $-N$ to \jp{jpk}-1. It provides the 517 following information: $mbathy(i,j) = -n, \ n \in \left] 0,N \right]$, $T-$points are land points of the $n^{th}$ island ; $mbathy(i,j) =0$, $T-$points are land points of the main land (continent) ; $mbathy(i,j) =k$, the first $k$ $T$- and $w$-points are ocean points, the others land points. This is used to compute the island barotropic stream function used in rigid lid computation (see \S\ref{MISC_solisl}). 802 routine (see \mdl{domzgr} module) after mbathy is computed. Isolated grid points 803 that do not communicate with another ocean point at the same level are eliminated. 804 805 In the case of the rigid-lid approximation when islands occur in the computational 806 domain (\np{ln\_dynspg\_rl}=.true. and \key{island} is defined), the \textit{mbathy} 807 array must be provided and takes values from $-N$ to \jp{jpk}-1. It provides the 808 following information: $mbathy(i,j) = -n, \ n \in \left] 0,N \right]$, $T$-points are 809 land points on the $n^{th}$ island ; $mbathy(i,j) =0$, $T$-points are land points 810 on the main land (continent) ; $mbathy(i,j) =k$, the first $k$ $T$- and $w$-points 811 are ocean points, the others are points below the ocean floor. 812 813 This is used to compute the island barotropic stream function used in the rigid lid 814 computation (see \S\ref{MISC_solisl}). 518 815 519 816 From the \textit{mbathy} array, the mask fields are defined as follows: 520 817 \begin{align*} 521 tmask(i,j,k) &= \begin{cases} 1& \text{ if $k\leq mbathy(i,j)$ } \\522 0& \text{ if $k\leq mbathy(i,j)$ } \end{cases} \\523 umask(i,j,k) &= \; tmask(i,j,k) \;.\;tmask(i+1,j,k) \\524 umask(i,j,k) &= \; tmask(i,j,k) \;.\;tmask(i,j+1,k) \\525 umask(i,j,k) &= \; tmask(i,j,k) \;.\;tmask(i+1,j,k) \\526 & \quad . \; tmask(i,j,k) \;.\;tmask(i+1,j,k)818 tmask(i,j,k) &= \begin{cases} \; 1& \text{ if $k\leq mbathy(i,j)$ } \\ 819 \; 0& \text{ if $k\leq mbathy(i,j)$ } \end{cases} \\ 820 umask(i,j,k) &= \; tmask(i,j,k) \ * \ tmask(i+1,j,k) \\ 821 umask(i,j,k) &= \; tmask(i,j,k) \ * \ tmask(i,j+1,k) \\ 822 umask(i,j,k) &= \; tmask(i,j,k) \ * \ tmask(i+1,j,k) \\ 823 & \ \ \, * tmask(i,j,k) \ * \ tmask(i+1,j,k) 527 824 \end{align*} 528 825 529 Note that \textit{wmask} is not defined as it is exactly equal to \textit{tmask} with the numerical 530 indexation used (\S~\ref{DOM_Num_Index}). Moreover, the specification of closed lateral 531 boundaries requires that at least the first and last rows and columns of 532 \textit{mbathy} array are set to zero. In the particular case of an east-west cyclic 533 boundary condition, \textit{mbathy} has its last column equal to the second one and its 534 first column equal to the last but one (and so the mask arrays) (see \S~\ref{LBC_jperio}). 535 536 \colorbox{yellow}{Add one word on tricky trick !} mbathy in further modified in zdfbfr{\ldots}. 826 \gmcomment{ STEVEN: are the dots multiplications?} 827 828 Note that \textit{wmask} is not defined as it is exactly equal to \textit{tmask} with 829 the numerical indexing used (\S~\ref{DOM_Num_Index}). Moreover, the 830 specification of closed lateral boundaries requires that at least the first and last 831 rows and columns of the \textit{mbathy} array are set to zero. In the particular 832 case of an east-west cyclical boundary condition, \textit{mbathy} has its last 833 column equal to the second one and its first column equal to the last but one 834 (and so too the mask arrays) (see \S~\ref{LBC_jperio}). 835 836 %%% 837 \gmcomment{ \colorbox{yellow}{Add one word on tricky trick !} mbathy in further modified in zdfbfr{\ldots}. } 838 %%% 537 839 538 840 % ================================================================ 539 % Time discretisation841 % Time Discretisation 540 842 % ================================================================ 541 843 \section{Time Discretisation} 542 844 \label{DOM_nxt} 543 845 544 The time stepping used in OPA is a three level scheme that can be presented as follows: 846 The time stepping used in \NEMO is a three level scheme that can be 847 represented as follows: 545 848 \begin{equation} \label{Eq_DOM_nxt} 546 849 x^{t+\Delta t} = x^{t-\Delta t} + 2 \, \Delta t \ \text{RHS}_x^{t-\Delta t,t,t+\Delta t} 547 850 \end{equation} 548 where $x$ stand for $u$, $v$, $T$ or $S$, RHS is the Right-Hand-Side of the corresponding time 549 evolution equation, $\Delta t$ is the time step and the overscripts indicate 550 the time at which a quantity is evaluated. Each term of the RHS is evaluated at 551 specific time step(s) depending on the physics to which it is associated. 851 where $x$ stands for $u$, $v$, $T$ or $S$; RHS is the Right-Hand-Side of the 852 corresponding time evolution equation; $\Delta t$ is the time step; and the 853 superscripts indicate the time at which a quantity is evaluated. Each term of the 854 RHS is evaluated at a specific time step(s) depending on the physics with which 855 it is associated. 856 552 857 The choice of the time step used for this evaluation is discussed below as 553 well as the implication in termof starting or restarting a model858 well as the implications in terms of starting or restarting a model 554 859 simulation. Note that the time stepping is generally performed in a one step 555 operation. With such a complex and nonlinear system of equations it would be dangerous to let a prognostic variable evolve in time for each term successively. 556 557 The three level scheme requires three arrays for the prognostic variables. For each variable $x$ there is $x_b$ (before) and $x_n$ (now). The third array, although referred to as $x_a$ (after) in the code, is usually not the variable $x_a$ at the next time step; rather, it is used to store the time derivative (RHS in \eqref{Eq_DOM_nxt}) prior to time-stepping the equation. Generally, the time stepping is performed once at each time step in \mdl{tranxt} and \mdl{dynnxt} modules, excepted for implicit vertical diffusion or sea surface height when time-splitting options are used. 860 operation. With such a complex and nonlinear system of equations it would be dangerous to let a prognostic variable evolve in time for each term separately. 861 %%% 862 \gmcomment{ STEVEN suggest separately instead of successively... wrong?} 863 %%% 864 865 The three level scheme requires three arrays for each prognostic variables. 866 For each variable $x$ there is $x_b$ (before) and $x_n$ (now). The third array, 867 although referred to as $x_a$ (after) in the code, is usually not the variable at 868 the next time step; but rather it is used to store the time derivative (RHS in 869 \eqref{Eq_DOM_nxt}) prior to time-stepping the equation. Generally, the time 870 stepping is performed once at each time step in \mdl{tranxt} and \mdl{dynnxt} 871 modules, except for implicit vertical diffusion or sea surface height when 872 time-splitting options are used. 558 873 559 874 % ------------------------------------------------------------------------------------------------------------- … … 564 879 565 880 The time stepping used for non-diffusive processes is the well-known 566 leapfrog scheme. It is a time centred scheme, i.e. the RHS areevaluated at881 leapfrog scheme. It is a time centred scheme, i.e. the RHS is evaluated at 567 882 time step $t$, the now time step. It is only used for non-diffusive terms, 568 that is momentum and tracer advection, pressure gradient, and coriolis883 that is momentum and tracer advection, pressure gradient, and Coriolis 569 884 terms. This scheme is widely used for advective processes in low-viscosity 570 885 fluids. It is an efficient method that achieves second-order accuracy with … … 578 893 "time-splitting" \citep{Haltiner1980} that develops when the method 579 894 is used to model non linear fluid dynamics: the even and odd time steps tend 580 to diverge betweena physical and a computational mode. Time splitting can895 to diverge into a physical and a computational mode. Time splitting can 581 896 be controlled through the use of an Asselin time filter (first designed by 582 \citep{Robert1966} and more comprehensively studied by \citet{Asselin1972}) or by897 \citep{Robert1966} and more comprehensively studied by \citet{Asselin1972}), or by 583 898 periodically reinitialising the leapfrog solution through a single 584 integration step with a two-level scheme. In OPAwe follow the first899 integration step with a two-level scheme. In \NEMO we follow the first 585 900 strategy: 586 901 \begin{equation} \label{Eq_DOM_nxt_asselin} 587 902 x_F^t = x^t + \gamma \, \left[ x_f^{t-\Delta t} - 2 x^t + x^{t+\Delta t} \right] 588 903 \end{equation} 589 where the subscript $f$ denotes filtered values and $\gamma$ is the asselin coefficient. $\gamma$ is initialized as \np{atfp} (namelist parameter). Its default value is \np{atfp}=0.1. This default value causes a significant dissipation of high frequency motions. Recommanded values in idealized studies of shallow water turbulence are two order of magnitude lower (\citep{Farge1987}). Both strategies do, nevertheless, degrade the accuracy of the calculation from second to first order. The leapfrog scheme associated to a Robert-Asselin 904 where the subscript $f$ denotes filtered values and $\gamma$ is the Asselin 905 coefficient. $\gamma$ is initialized as \np{atfp} (namelist parameter). 906 Its default value is \np{atfp}=0.1. This default value causes a significant dissipation 907 of high frequency motions. Recommended values in idealized studies of shallow 908 water turbulence are two orders of magnitude smaller (\citep{Farge1987}). 909 Both strategies do, nevertheless, degrade the accuracy of the calculation from 910 second to first order. The leapfrog scheme combined with a Robert-Asselin 590 911 time filter has been preferred to other time differencing schemes such as 591 predictor corrector or trapezoidal schemes because the user can better592 control the magnitude and the spatial structure of the time diffusion of the593 scheme. In association with thecentred space discretisation of the912 predictor corrector or trapezoidal schemes, because the user has an explicit 913 and simple control of the magnitude of the time diffusion of the scheme. 914 In association with the 2nd order centred space discretisation of the 594 915 advective terms in the momentum and tracer equations, it avoids implicit 595 numerical diffusion in both the time and space discretisation of the 596 advective term: they are both set explicitly by the user through the Robert-Asselin filter parameter and the viscous and diffusive coefficients. 597 916 numerical diffusion in both the time and space discretisations of the 917 advective term: they are both set explicitly by the user through the Robert-Asselin 918 filter parameter and the viscous and diffusive coefficients. 919 920 \gmcomment{ 598 921 %gm - reflexion about leapfrog: ongoing work with Matthieu Leclair 599 922 % to be updated latter with addition of new time stepping strategy 600 \amtcomment{601 923 \colorbox{yellow}{Note}: 602 1- There is no reason why one should apply a same value of $\gamma$ on both momentum and tracer equations. In climate applications, one could found useful to use a lower value on tracer (quantity that one wants to conserve) than on the dynamics. We never explore this possibility. 603 The Robert-Asselin time filter slightly departs from a simple second order time diffusive operator computed with a forward time stepping due to the presence of $x_f^{t-\Delta t}$ in the right hand side of \ref{Eq_DOM_nxt_asselin}. The original willing of Robert1966 and Asselin1972 was to design a time filter that allow much larger parameter than 0.5. is due to computer saving consideration. In the original asselin filter, $x^{t-\Delta t}$ is used instead: 924 The Robert-Asselin time filter slightly departs from a simple second order time 925 diffusive operator computed with a forward time stepping due to the presence of 926 $x_f^{t-\Delta t}$ in the right hand side of \ref{Eq_DOM_nxt_asselin}. The original 927 willing of Robert1966 and Asselin1972 was to design a time filter that allow much 928 larger parameter than 0.5. is due to computer saving consideration. In the original 929 asselin filter, $x^{t-\Delta t}$ is used instead: 604 930 \begin{equation} \label{Eq_DOM_nxt_asselin_true} 605 931 x_f^t = x^t + \gamma \, \left[ x^{t-\Delta t} - 2 x^t + x^{t+\Delta t} \right] 606 932 \end{equation} 607 Applying a "true" Asselin time filter is nothing more than adding a harmonic diffusive operator in time. Indeed, equations \ref{Eq_DOM_nxt} and \ref{Eq_DOM_nxt_asselin_true} can be rewritten together as: 933 Applying a "true" Asselin time filter is nothing more than adding a harmonic 934 diffusive operator in time. Indeed, equations \ref{Eq_DOM_nxt} and 935 \ref{Eq_DOM_nxt_asselin_true} can be rewritten together as: 608 936 \begin{equation} \label{Eq_DOM_nxt2} 609 937 \begin{split} 610 938 \frac{ x^{t+\Delta t} - x^{t-\Delta t} } { 2 \,\Delta t } 611 939 &= \text{RHS}_x^{t-\Delta t,t,t+\Delta t} + \frac{ x_f^t - x^t }{2 \,\Delta t} \\ 612 &= \text{RHS}_x^{t-\Delta t,t,t+\Delta t} + \gamma\ \frac{ \, \left[ x^{t-\Delta t} - 2 x^t + x^{t+\Delta t} \right] }{2 \,\Delta t} \\ 940 &= \text{RHS}_x^{t-\Delta t,t,t+\Delta t} 941 + \gamma\ \frac{ \, \left[ x^{t-\Delta t} - 2 x^t + x^{t+\Delta t} \right] }{2 \,\Delta t} \\ 613 942 &= \text{RHS}_x^{t-\Delta t,t,t+\Delta t} 614 943 + 2 \Delta t \ \gamma \ \frac{1}{{2 \Delta t}^2} … … 621 950 \end{equation} 622 951 623 Equations \ref{Eq_DOM_nxt2} and \ref{Eq_DOM_nxt3} suggest several remarks. First the Asselin filter is definitively a second order time diffusive operator which is evaluated at centered time step. The magnitude of this diffusion is proportional to the time step (with $\gamma$ usually taken between $10^{-1}$ to $10^{-3}$) . Second, this term has to be taken into account in all budgets of the equations (mass, heat content, salt content, kinetic energy...). Nevertheless,we stress here that it is small and does not create systematic biases. Indeed let us evaluate how it contributes to the time evolution of $x$ between $t_o$ and $t_1$: 952 Equations \ref{Eq_DOM_nxt2} and \ref{Eq_DOM_nxt3} suggest several remarks. 953 First the Asselin filter is definitively a second order time diffusive operator which is 954 evaluated at centered time step. The magnitude of this diffusion is proportional to 955 the time step (with $\gamma$ usually taken between $10^{-1}$ to $10^{-3}$). 956 Second, this term has to be taken into account in all budgets of the equations 957 (mass, heat content, salt content, kinetic energy...). Nevertheless,we stress here 958 that it is small and does not create systematic biases. Indeed let us evaluate how 959 it contributes to the time evolution of $x$ between $t_o$ and $t_1$: 624 960 \begin{equation} \label{Eq_DOM_nxt4} 625 961 \begin{split} … … 640 976 \label{DOM_nxt_forward_imp} 641 977 642 The leapfrog differencing is unsuitable for the representation of diffusive 643 and damping processes. For $D$, a horizontal diffusive terms and/or the 644 restoring terms to a tracer climatology (when they are present, see 645 \S~\ref{TRA_dmp}), a forward time differencing scheme is used : 978 The leapfrog differencing scheme is unsuitable for the representation of 979 diffusive and damping processes. For a tendancy $D_x$, representing a 980 diffusive term or a restoring term to a tracer climatology 981 (when present, see \S~\ref{TRA_dmp}), a forward time differencing scheme 982 is used : 646 983 \begin{equation} \label{Eq_DOM_nxt_euler} 647 x^{t+\Delta t} = x^{t-\Delta t} + 2 \, \Delta t \ \text{RHS}_x^{t-\Delta t}984 x^{t+\Delta t} = x^{t-\Delta t} + 2 \, \Delta t \ {D_x}^{t-\Delta t} 648 985 \end{equation} 649 986 650 987 This is diffusive in time and conditionally stable. For example, the 651 condition of stability for a second and fourth order horizontal diffusions are \citep{Griffies2004}:988 conditions for stability of second and fourth order horizontal diffusion schemes are \citep{Griffies2004}: 652 989 \begin{equation} \label{Eq_DOM_nxt_euler_stability} 653 990 A^h < \left\{ … … 658 995 \right. 659 996 \end{equation} 660 where $e$ is the smallest grid size in the two horizontal direction and $A^h$ the mixing coefficient. The linear constraint \eqref{Eq_DOM_nxt_euler_stability} is a necessary condition, but not sufficient. If it is not satisfied, even mildly, then the model soon becomes wildly unstable. The instability can be removed by either reducingthe time steps or reducing the mixing coefficient.997 where $e$ is the smallest grid size in the two horizontal directions and $A^h$ is the mixing coefficient. The linear constraint \eqref{Eq_DOM_nxt_euler_stability} is a necessary condition, but not sufficient. If it is not satisfied, even mildly, then the model soon becomes wildly unstable. The instability can be removed by either reducing the length of the time steps or reducing the mixing coefficient. 661 998 662 999 For the vertical diffusion terms, a forward time differencing scheme can be 663 1000 used, but usually the numerical stability condition implies a strong 664 constraint on the time step. Two solutions are available in OPAto overcome1001 constraint on the time step. Two solutions are available in \NEMO to overcome 665 1002 the stability constraint: $(a)$ a forward time differencing scheme using a 666 time splitting technique (\np{ln\_zdfexp}= T) or $(b)$ a backward (or implicit)667 time differencing scheme by \np{ln\_zdfexp}= F). In $(a)$, the master1003 time splitting technique (\np{ln\_zdfexp}=.true.) or $(b)$ a backward (or implicit) 1004 time differencing scheme by \np{ln\_zdfexp}=.false.). In $(a)$, the master 668 1005 time step $\Delta $t is cut into $N$ fractional time steps so that the 669 1006 stability criterion is reduced by a factor of $N$. The computation is done as … … 678 1015 \end{split} 679 1016 \end{equation} 680 with DF a vertical diffusion term. The number of fractional time steps, $N$, is given by setting \np{n\_zdfexp}, (namelist parameter). The scheme $(b)$ is unconditionally stable but diffusive. It can be written as follows: 1017 with DF a vertical diffusion term. The number of fractional time steps, $N$, is given 1018 by setting \np{n\_zdfexp}, (namelist parameter). The scheme $(b)$ is unconditionally 1019 stable but diffusive. It can be written as follows: 681 1020 \begin{equation} \label{Eq_DOM_nxt_imp} 682 1021 x^{t+\Delta t} = x^{t-\Delta t} + 2 \, \Delta t \ \text{RHS}_x^{t+\Delta t} … … 692 1031 \right] 693 1032 \end{equation} 694 where RHS is the right hand side of the equation except the vertical diffusion term. We rewrite \eqref{Eq_DOM_nxt_imp} as:1033 where RHS is the right hand side of the equation except for the vertical diffusion term. We rewrite \eqref{Eq_DOM_nxt_imp} as: 695 1034 \begin{equation} \label{Eq_DOM_nxt_imp_mat} 696 1035 -c(k+1)\;u^{t+1}(k+1)+d(k)\;u^{t+1}(k)-\;c(k)\;u^{t+1}(k-1) \equiv b(k) … … 703 1042 \end{align*} 704 1043 705 \eqref{Eq_DOM_nxt_imp_mat} is a linear system of equations. All the elements of the corresponding matrix vanish except those on the diagonals. Moreover, $c(k)$ and $d(k)$ are positive and the diagonal term is greater than the sum of the 706 two extra-diagonal terms, therefore a special adaptation of the Gauss elimination procedure is used to find the solution (see for example \citet{Richtmyer1967}). 1044 \eqref{Eq_DOM_nxt_imp_mat} is a linear system of equations which associated 1045 matrix is tridiagonal. Moreover, $c(k)$ and $d(k)$ are positive and the diagonal 1046 term is greater than the sum of the two extra-diagonal terms, therefore a special 1047 adaptation of the Gauss elimination procedure is used to find the solution 1048 (see for example \citet{Richtmyer1967}). 707 1049 708 1050 % ------------------------------------------------------------------------------------------------------------- … … 714 1056 \namdisplay{namrun} 715 1057 %-------------------------------------------------------------------------------------------------------------- 716 The first time step of this three level scheme when starting from initial conditions is a forward step (Euler time integration): $x^1 = x^0 + \Delta t \ \text{RHS}^0$. 1058 1059 The first time step of this three level scheme when starting from initial conditions 1060 is a forward step (Euler time integration): 1061 \begin{equation} \label{Eq_DOM_euler} 1062 x^1 = x^0 + \Delta t \ \text{RHS}^0 1063 \end{equation} 717 1064 718 1065 It is also possible to restart from a previous computation, by using a … … 720 1067 restartability of the code: the user should obtain the same results to 721 1068 machine precision either by running the model for $2N$ time steps in one go, 722 or by performing two consecutive experiments of $N$ steps with a restart. This 723 requires saving two time levels and many auxiliary data in the restart files 724 in double precision. 725 1069 or by performing two consecutive experiments of $N$ steps with a restart. 1070 This requires saving two time levels and many auxiliary data in the restart 1071 files in machine precision. 1072 1073 Note that when a semi-implicit scheme is used to evaluate the hydrostatic pressure 1074 gradient (see \S\ref{DYN_hpg_imp}), an extra three-dimensional field has to be 1075 added in the restart file to ensure an exact restartability. This is done only optionally 1076 via the namelist parameter \np{nn\_dynhpg\_rst}, so that a reduction of the size of restart file can be obtained when the restartability is not a key issue (operational oceanography or ensemble simulation for seasonal forcast). 1077 %%% 1078 \gmcomment{add here how to force the restart to contain only one time step for operational purposes} 1079 %%% 1080 1081 \gmcomment{ % add a subsection here 726 1082 727 1083 %------------------------------------------------------------------------------------------------------------- … … 735 1091 \colorbox{yellow}{Write documentation on the calendar and the key variable adatrj} 736 1092 737 738 1093 } %% end add 1094
Note: See TracChangeset
for help on using the changeset viewer.