Changeset 11954 for NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_DOM.tex
- Timestamp:
- 2019-11-22T17:15:18+01:00 (4 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_DOM.tex
r11598 r11954 6 6 \label{chap:DOM} 7 7 8 % Missing things: 9 % - istate: description of the initial state ==> this has to be put elsewhere.. 10 % perhaps in MISC ? By the way the initialisation of T S and dynamics 11 % should be put outside of DOM routine (better with TRC staff and off-line 12 % tracers) 13 % -geo2ocean: how to switch from geographic to mesh coordinate 14 % - domclo: closed sea and lakes.... management of closea sea area : specific to global configuration, both forced and coupled 15 16 % {\em 4.0} & {\em Simon M\"{u}ller \& Andrew Coward} & 17 % {\em 18 % Compatibility changes Major simplification has moved many of the options to external domain configuration tools. 19 % (see \autoref{apdx:DOMCFG}) 20 % } \\ 21 % {\em 3.x} & {\em Rachid Benshila, Gurvan Madec \& S\'{e}bastien Masson} & 22 % {\em First version} \\ 8 % Missing things 9 % - istate: description of the initial state ==> this has to be put elsewhere.. 10 % perhaps in MISC ? By the way the initialisation of T S and dynamics 11 % should be put outside of DOM routine (better with TRC staff and off-line 12 % tracers) 13 % - geo2ocean: how to switch from geographic to mesh coordinate 14 % - domclo: closed sea and lakes.... 15 % management of closea sea area: specific to global cfg, both forced and coupled 23 16 24 17 \thispagestyle{plain} … … 29 22 30 23 {\footnotesize 31 \begin{tabularx}{\textwidth}{l||X|X} 32 Release & Author(s) & Modifications \\ 33 \hline 34 {\em 4.0} & {\em ...} & {\em ...} \\ 35 {\em 3.6} & {\em ...} & {\em ...} \\ 36 {\em 3.4} & {\em ...} & {\em ...} \\ 37 {\em <=3.4} & {\em ...} & {\em ...} 24 \begin{tabularx}{0.8\textwidth}{l||X|X} 25 Release & 26 Author(s) & 27 Modifications \\ 28 \hline 29 {\em 4.0 } & 30 {\em Simon M\"{u}ller \& Andrew Coward \newline \newline 31 Simona Flavoni and Tim Graham } & 32 {\em Compatibility changes: many options moved to external domain configuration tools 33 (see \autoref{apdx:DOMCFG}). \newline 34 Updates } \\ 35 {\em 3.6 } & 36 {\em Rachid Benshila, Christian \'{E}th\'{e}, Pierre Mathiot and Gurvan Madec } & 37 {\em Updates } \\ 38 {\em $\leq$ 3.4 } & 39 {\em Gurvan Madec and S\'{e}bastien Masson } & 40 {\em First version } 38 41 \end{tabularx} 39 42 } … … 41 44 \clearpage 42 45 43 Having defined the continuous equations in \autoref{chap:MB} and chosen a time discretisation \autoref{chap:TD}, 46 Having defined the continuous equations in \autoref{chap:MB} and 47 chosen a time discretisation \autoref{chap:TD}, 44 48 we need to choose a grid for spatial discretisation and related numerical algorithms. 45 49 In the present chapter, we provide a general description of the staggered grid used in \NEMO, … … 54 58 \label{subsec:DOM_cell} 55 59 56 \begin{figure} [!tb]60 \begin{figure} 57 61 \centering 58 \includegraphics[width=0. 66\textwidth]{Fig_cell}62 \includegraphics[width=0.33\textwidth]{DOM_cell} 59 63 \caption[Arrangement of variables in the unit cell of space domain]{ 60 64 Arrangement of variables in the unit cell of space domain. 61 65 $t$ indicates scalar points where 62 66 temperature, salinity, density, pressure and horizontal divergence are defined. 63 $(u,v,w)$ indicates vector points, 64 and $f$ indicates vorticity points where 67 $(u,v,w)$ indicates vector points, and $f$ indicates vorticity points where 65 68 both relative and planetary vorticities are defined.} 66 69 \label{fig:DOM_cell} 67 70 \end{figure} 68 71 69 The numerical techniques used to solve the Primitive Equations in this model are based on the traditional,70 centred second-order finite difference approximation.72 The numerical techniques used to solve the Primitive Equations in this model are based on 73 the traditional, centred second-order finite difference approximation. 71 74 Special attention has been given to the homogeneity of the solution in the three spatial directions. 72 75 The arrangement of variables is the same in all directions. 73 It consists of cells centred on scalar points ($t$, $S$, $p$, $\rho$) with vector points $(u, v, w)$ defined in 74 the centre of each face of the cells (\autoref{fig:DOM_cell}). 75 This is the generalisation to three dimensions of the well-known ``C'' grid in Arakawa's classification 76 \citep{mesinger.arakawa_bk76}. 77 The relative and planetary vorticity, $\zeta$ and $f$, are defined in the centre of each vertical edge and 78 the barotropic stream function $\psi$ is defined at horizontal points overlying the $\zeta$ and $f$-points. 79 80 The ocean mesh (\ie\ the position of all the scalar and vector points) is defined by the transformation that 81 gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. 82 The grid-points are located at integer or integer and a half value of $(i,j,k)$ as indicated on \autoref{tab:DOM_cell}. 83 In all the following, subscripts $u$, $v$, $w$, $f$, $uw$, $vw$ or $fw$ indicate the position of 84 the grid-point where the scale factors are defined. 76 It consists of cells centred on scalar points ($t$, $S$, $p$, $\rho$) with 77 vector points $(u, v, w)$ defined in the centre of each face of the cells (\autoref{fig:DOM_cell}). 78 This is the generalisation to three dimensions of the well-known ``C'' grid in 79 Arakawa's classification \citep{mesinger.arakawa_bk76}. 80 The relative and planetary vorticity, $\zeta$ and $f$, are defined in the centre of each 81 vertical edge and the barotropic stream function $\psi$ is defined at horizontal points overlying 82 the $\zeta$ and $f$-points. 83 84 The ocean mesh (\ie\ the position of all the scalar and vector points) is defined by 85 the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. 86 The grid-points are located at integer or integer and a half value of $(i,j,k)$ as indicated on 87 \autoref{tab:DOM_cell}. 88 In all the following, 89 subscripts $u$, $v$, $w$, $f$, $uw$, $vw$ or $fw$ indicate the position of the grid-point where 90 the scale factors are defined. 85 91 Each scale factor is defined as the local analytical value provided by \autoref{eq:MB_scale_factors}. 86 92 As a result, the mesh on which partial derivatives $\pd[]{\lambda}$, $\pd[]{\varphi}$ and 87 93 $\pd[]{z}$ are evaluated is a uniform mesh with a grid size of unity. 88 Discrete partial derivatives are formulated by the traditional, centred second order finite difference approximation 89 while the scale factors are chosen equal to their local analytical value. 94 Discrete partial derivatives are formulated by 95 the traditional, centred second order finite difference approximation while 96 the scale factors are chosen equal to their local analytical value. 90 97 An important point here is that the partial derivative of the scale factors must be evaluated by 91 98 centred finite difference approximation, not from their analytical expression. 92 This preserves the symmetry of the discrete set of equations and therefore satisfies many of93 the continuous properties (see \autoref{apdx:INVARIANTS}).99 This preserves the symmetry of the discrete set of equations and 100 therefore satisfies many of the continuous properties (see \autoref{apdx:INVARIANTS}). 94 101 A similar, related remark can be made about the domain size: 95 when needed, an area, volume, or the total ocean depth must be evaluated as the product or sum of the relevant scale factors96 (see \autoref{eq:DOM_bar} in the next section).97 98 \begin{table} [!tb]102 when needed, an area, volume, or the total ocean depth must be evaluated as 103 the product or sum of the relevant scale factors (see \autoref{eq:DOM_bar} in the next section). 104 105 \begin{table} 99 106 \centering 100 \begin{tabular}{| p{46pt}|p{56pt}|p{56pt}|p{56pt}|}101 \hline 102 t & $i$ & $j $ & $k $ \\103 \hline 104 u 105 \hline 106 v & $i$ & $j + 1/2$ & $k $ \\107 \hline 108 w & $i$ & $j $ & $k + 1/2$ \\109 \hline 110 f 111 \hline 112 uw 113 \hline 114 vw & $i$ & $j + 1/2$ & $k + 1/2$ \\115 \hline 116 fw 107 \begin{tabular}{|l|l|l|l|} 108 \hline 109 t & $i $ & $j $ & $k $ \\ 110 \hline 111 u & $i + 1/2$ & $j $ & $k $ \\ 112 \hline 113 v & $i $ & $j + 1/2$ & $k $ \\ 114 \hline 115 w & $i $ & $j $ & $k + 1/2$ \\ 116 \hline 117 f & $i + 1/2$ & $j + 1/2$ & $k $ \\ 118 \hline 119 uw & $i + 1/2$ & $j $ & $k + 1/2$ \\ 120 \hline 121 vw & $i $ & $j + 1/2$ & $k + 1/2$ \\ 122 \hline 123 fw & $i + 1/2$ & $j + 1/2$ & $k + 1/2$ \\ 117 124 \hline 118 125 \end{tabular} … … 120 127 Location of grid-points as a function of integer or 121 128 integer and a half value of the column, line or level. 122 This indexing is only used for the writing of the semi 129 This indexing is only used for the writing of the semi-discrete equations. 123 130 In the code, the indexing uses integer values only and 124 131 is positive downwards in the vertical with $k=1$ at the surface. … … 137 144 firstly, there is no ambiguity in the scale factors appearing in the discrete equations, 138 145 since they are first introduced in the continuous equations; 139 secondly, analytical transformations encourage good practice by the definition of smoothly varying grids 140 (rather than allowing the user to set arbitrary jumps in thickness between adjacent layers) \citep{treguier.dukowicz.ea_JGR96}. 146 secondly, analytical transformations encourage good practice by 147 the definition of smoothly varying grids 148 (rather than allowing the user to set arbitrary jumps in thickness between adjacent layers) 149 \citep{treguier.dukowicz.ea_JGR96}. 141 150 An example of the effect of such a choice is shown in \autoref{fig:DOM_zgr_e3}. 142 \begin{figure} [!t]151 \begin{figure} 143 152 \centering 144 \includegraphics[width=0. 66\textwidth]{Fig_zgr_e3}153 \includegraphics[width=0.5\textwidth]{DOM_zgr_e3} 145 154 \caption[Comparison of grid-point position, vertical grid-size and scale factors]{ 146 155 Comparison of (a) traditional definitions of grid-point position and grid-size in the vertical, … … 159 168 \label{subsec:DOM_operators} 160 169 161 Given the values of a variable $q$ at adjacent points, the differencing and averaging operators at162 the midpoint between them are:170 Given the values of a variable $q$ at adjacent points, 171 the differencing and averaging operators at the midpoint between them are: 163 172 \begin{alignat*}{2} 164 173 % \label{eq:DOM_di_mi} … … 168 177 169 178 Similar operators are defined with respect to $i + 1/2$, $j$, $j + 1/2$, $k$, and $k + 1/2$. 170 Following \autoref{eq:MB_grad} and \autoref{eq:MB_lap}, the gradient of a variable $q$ defined at a $t$-point has 171 its three components defined at $u$-, $v$- and $w$-points while its Laplacian is defined at the $t$-point. 179 Following \autoref{eq:MB_grad} and \autoref{eq:MB_lap}, 180 the gradient of a variable $q$ defined at a $t$-point has 181 its three components defined at $u$-, $v$- and $w$-points while 182 its Laplacian is defined at the $t$-point. 172 183 These operators have the following discrete forms in the curvilinear $s$-coordinates system: 173 \ [184 \begin{gather*} 174 185 % \label{eq:DOM_grad} 175 186 \nabla q \equiv \frac{1}{e_{1u}} \delta_{i + 1/2} [q] \; \, \vect i 176 187 + \frac{1}{e_{2v}} \delta_{j + 1/2} [q] \; \, \vect j 177 + \frac{1}{e_{3w}} \delta_{k + 1/2} [q] \; \, \vect k 178 \] 179 \begin{multline*} 188 + \frac{1}{e_{3w}} \delta_{k + 1/2} [q] \; \, \vect k \\ 180 189 % \label{eq:DOM_lap} 181 190 \Delta q \equiv \frac{1}{e_{1t} \, e_{2t} \, e_{3t}} 182 191 \; \lt[ \delta_i \lt( \frac{e_{2u} \, e_{3u}}{e_{1u}} \; \delta_{i + 1/2} [q] \rt) 183 + \delta_j \lt( \frac{e_{1v} \, e_{3v}}{e_{2v}} \; \delta_{j + 1/2} [q] \rt) \; \rt] \\192 + \delta_j \lt( \frac{e_{1v} \, e_{3v}}{e_{2v}} \; \delta_{j + 1/2} [q] \rt) \; \rt] 184 193 + \frac{1}{e_{3t}} 185 194 \delta_k \lt[ \frac{1 }{e_{3w}} \; \delta_{k + 1/2} [q] \rt] 186 \end{multline*} 187 188 Following \autoref{eq:MB_curl} and \autoref{eq:MB_div}, a vector $\vect A = (a_1,a_2,a_3)$ defined at 189 vector points $(u,v,w)$ has its three curl components defined at $vw$-, $uw$, and $f$-points, and 195 \end{gather*} 196 197 Following \autoref{eq:MB_curl} and \autoref{eq:MB_div}, 198 a vector $\vect A = (a_1,a_2,a_3)$ defined at vector points $(u,v,w)$ has 199 its three curl components defined at $vw$-, $uw$, and $f$-points, and 190 200 its divergence defined at $t$-points: 191 \begin{multline }201 \begin{multline*} 192 202 % \label{eq:DOM_curl} 193 203 \nabla \times \vect A \equiv \frac{1}{e_{2v} \, e_{3vw}} … … 200 210 \Big[ \delta_{i + 1/2} (e_{2v} \, a_2) 201 211 - \delta_{j + 1/2} (e_{1u} \, a_1) \Big] \vect k 202 \end{multline }203 \ begin{equation}212 \end{multline*} 213 \[ 204 214 % \label{eq:DOM_div} 205 215 \nabla \cdot \vect A \equiv \frac{1}{e_{1t} \, e_{2t} \, e_{3t}} 206 216 \Big[ \delta_i (e_{2u} \, e_{3u} \, a_1) + \delta_j (e_{1v} \, e_{3v} \, a_2) \Big] 207 217 + \frac{1}{e_{3t}} \delta_k (a_3) 208 \ end{equation}209 210 The vertical average over the whole water column is denoted by an overbar and is for211 a masked field $q$ (\ie\ a quantity that is equal to zero inside solid areas):218 \] 219 220 The vertical average over the whole water column is denoted by an overbar and 221 is for a masked field $q$ (\ie\ a quantity that is equal to zero inside solid areas): 212 222 \begin{equation} 213 223 \label{eq:DOM_bar} … … 215 225 \end{equation} 216 226 where $H_q$ is the ocean depth, which is the masked sum of the vertical scale factors at $q$ points, 217 $k^b$ and $k^o$ are the bottom and surface $k$-indices, and the symbol $\sum \limits_k$ refers to a summation over 218 all grid points of the same type in the direction indicated by the subscript (here $k$). 227 $k^b$ and $k^o$ are the bottom and surface $k$-indices, 228 and the symbol $\sum \limits_k$ refers to a summation over all grid points of the same type in 229 the direction indicated by the subscript (here $k$). 219 230 220 231 In continuous form, the following properties are satisfied: … … 226 237 \end{gather} 227 238 228 It is straightforward to demonstrate that these properties are verified locally in discrete form as soon as229 the scalar $q$ is taken at $t$-points and the vector $\vect A$ has its components defined at239 It is straightforward to demonstrate that these properties are verified locally in discrete form as 240 soon as the scalar $q$ is taken at $t$-points and the vector $\vect A$ has its components defined at 230 241 vector points $(u,v,w)$. 231 242 232 243 Let $a$ and $b$ be two fields defined on the mesh, with a value of zero inside continental areas. 233 It can be shown that the differencing operators ($\delta_i$, $\delta_j$ and $\delta_k$) 234 are skew-symmetric linear operators, and further that the averaging operators $\overline{\cdots}^{\, i}$, 235 $\overline{\cdots}^{\, j}$ and $\overline{\cdots}^{\, k}$) are symmetric linear operators, \ie 236 \begin{alignat}{4} 244 It can be shown that the differencing operators ($\delta_i$, $\delta_j$ and 245 $\delta_k$) are skew-symmetric linear operators, 246 and further that the averaging operators ($\overline{\cdots}^{\, i}$, $\overline{\cdots}^{\, j}$ and 247 $\overline{\cdots}^{\, k}$) are symmetric linear operators, \ie 248 \begin{alignat}{5} 237 249 \label{eq:DOM_di_adj} 238 250 &\sum \limits_i a_i \; \delta_i [b] &\equiv &- &&\sum \limits_i \delta _{ i + 1/2} [a] &b_{i + 1/2} \\ … … 241 253 \end{alignat} 242 254 243 In other words, the adjoint of the differencing and averaging operators are $\delta_i^* = \delta_{i + 1/2}$ and 255 In other words, 256 the adjoint of the differencing and averaging operators are $\delta_i^* = \delta_{i + 1/2}$ and 244 257 $(\overline{\cdots}^{\, i})^* = \overline{\cdots}^{\, i + 1/2}$, respectively. 245 258 These two properties will be used extensively in the \autoref{apdx:INVARIANTS} to … … 250 263 \label{subsec:DOM_Num_Index} 251 264 252 \begin{figure} [!tb]265 \begin{figure} 253 266 \centering 254 \includegraphics[width=0. 66\textwidth]{Fig_index_hor}267 \includegraphics[width=0.33\textwidth]{DOM_index_hor} 255 268 \caption[Horizontal integer indexing]{ 256 269 Horizontal integer indexing used in the \fortran\ code. … … 261 274 262 275 The array representation used in the \fortran\ code requires an integer indexing. 263 However, the analytical definition of the mesh (see \autoref{subsec:DOM_cell}) is associated with the use of 264 integer values for $t$-points only while all the other points involve integer and a half values. 276 However, the analytical definition of the mesh (see \autoref{subsec:DOM_cell}) is associated with 277 the use of integer values for $t$-points only while 278 all the other points involve integer and a half values. 265 279 Therefore, a specific integer indexing has been defined for points other than $t$-points 266 280 (\ie\ velocity and vorticity grid-points). 267 Furthermore, the direction of the vertical indexing has been reversed and the surface level set at $k = 1$. 281 Furthermore, the direction of the vertical indexing has been reversed and 282 the surface level set at $k = 1$. 268 283 269 284 %% ================================================================================================= … … 281 296 \label{subsec:DOM_Num_Index_vertical} 282 297 283 In the vertical, the chosen indexing requires special attention since the direction of the $k$-axis in284 the \fortran\ code is the reverse of that used in the semi -discrete equations and285 given in \autoref{subsec:DOM_cell}.286 The sea surface corresponds to the $w$-level $k = 1$, which is the same index as the $t$-level just below287 (\autoref{fig:DOM_index_vert}).298 In the vertical, the chosen indexing requires special attention since 299 the direction of the $k$-axis in the \fortran\ code is the reverse of 300 that used in the semi-discrete equations and given in \autoref{subsec:DOM_cell}. 301 The sea surface corresponds to the $w$-level $k = 1$, 302 which is the same index as the $t$-level just below (\autoref{fig:DOM_index_vert}). 288 303 The last $w$-level ($k = jpk$) either corresponds to or is below the ocean floor while 289 304 the last $t$-level is always outside the ocean domain (\autoref{fig:DOM_index_vert}). 290 305 Note that a $w$-point and the directly underlaying $t$-point have a common $k$ index 291 306 (\ie\ $t$-points and their nearest $w$-point neighbour in negative index direction), 292 in contrast to the indexing on the horizontal plane where the $t$-point has the same index as 293 the nearest velocity points in the positive direction of the respective horizontal axis index 307 in contrast to the indexing on the horizontal plane where 308 the $t$-point has the same index as the nearest velocity points in 309 the positive direction of the respective horizontal axis index 294 310 (compare the dashed area in \autoref{fig:DOM_index_hor} and \autoref{fig:DOM_index_vert}). 295 311 Since the scale factors are chosen to be strictly positive, … … 298 314 accommodate the opposing vertical index directions in implementation and documentation. 299 315 300 \begin{figure} [!pt]316 \begin{figure} 301 317 \centering 302 \includegraphics[width=0. 66\textwidth]{Fig_index_vert}318 \includegraphics[width=0.33\textwidth]{DOM_index_vert} 303 319 \caption[Vertical integer indexing]{ 304 320 Vertical integer indexing used in the \fortran\ code. … … 314 330 315 331 Two typical methods are available to specify the spatial domain configuration; 316 they can be selected using parameter \np{ln_read_cfg}{ln\_read\_cfg} parameter in namelist \nam{cfg}{cfg}. 332 they can be selected using parameter \np{ln_read_cfg}{ln\_read\_cfg} parameter in 333 namelist \nam{cfg}{cfg}. 317 334 318 335 If \np{ln_read_cfg}{ln\_read\_cfg} is set to \forcode{.true.}, 319 the domain-specific parameters and fields are read from a netCDF input file, 320 whose name (without its .nc suffix) can be specified as the value of the \np{cn_domcfg}{cn\_domcfg} parameter in namelist \nam{cfg}{cfg}. 336 the domain-specific parameters and fields are read from a NetCDF input file, 337 whose name (without its .nc suffix) can be specified as 338 the value of the \np{cn_domcfg}{cn\_domcfg} parameter in namelist \nam{cfg}{cfg}. 321 339 322 340 If \np{ln_read_cfg}{ln\_read\_cfg} is set to \forcode{.false.}, … … 324 342 subroutines \mdl{usrdef\_hgr} and \mdl{usrdef\_zgr}. 325 343 These subroutines can be supplied in the \path{MY_SRC} directory of the configuration, 326 and default versions that configure the spatial domain for the GYRE reference configuration are present in327 the \path{./src/OCE/USR} directory.344 and default versions that configure the spatial domain for the GYRE reference configuration are 345 present in the \path{./src/OCE/USR} directory. 328 346 329 347 In version 4.0 there are no longer any options for reading complex bathymetries and … … 332 350 to run similar models with and without partial bottom boxes and/or sigma-coordinates, 333 351 supporting such choices leads to overly complex code. 334 Worse still is the difficulty of ensuring the model configurations intended to be identical are indeed so when 335 the model domain itself can be altered by runtime selections. 336 The code previously used to perform vertical discretisation has been incorporated into an external tool 337 (\path{./tools/DOMAINcfg}) which is briefly described in \autoref{apdx:DOMCFG}. 338 339 The next subsections summarise the parameter and fields related to the configuration of the whole model domain. 340 These represent the minimum information that must be provided either via the \np{cn_domcfg}{cn\_domcfg} file or set by code 341 inserted into user-supplied versions of the \texttt{usrdef\_*} subroutines. 352 Worse still is the difficulty of ensuring the model configurations intended to be identical are 353 indeed so when the model domain itself can be altered by runtime selections. 354 The code previously used to perform vertical discretisation has been incorporated into 355 an external tool (\path{./tools/DOMAINcfg}) which is briefly described in \autoref{apdx:DOMCFG}. 356 357 The next subsections summarise the parameter and fields related to 358 the configuration of the whole model domain. 359 These represent the minimum information that must be provided either via 360 the \np{cn_domcfg}{cn\_domcfg} file or 361 set by code inserted into user-supplied versions of the \texttt{usrdef\_*} subroutines. 342 362 The requirements are presented in three sections: 343 363 the domain size (\autoref{subsec:DOM_size}), the horizontal mesh (\autoref{subsec:DOM_hgr}), … … 348 368 \label{subsec:DOM_size} 349 369 350 The total size of the computational domain is set by the parameters \jp{jpiglo}, \jp{jpjglo} and \jp{jpkglo} for351 the $i$, $j$ and $k$ directions, respectively.352 Note, that the variables \texttt{jpi} and \texttt{jpj} refer to the size of each processor subdomain when353 the code is run in parallel using domain decomposition (\key{mpp\_mpi} defined,354 see \autoref{sec:LBC_mpp}).370 The total size of the computational domain is set by the parameters \jp{jpiglo}, \jp{jpjglo} and 371 \jp{jpkglo} for the $i$, $j$ and $k$ directions, respectively. 372 Note, that the variables \texttt{jpi} and \texttt{jpj} refer to 373 the size of each processor subdomain when the code is run in parallel using domain decomposition 374 (\key{mpp\_mpi} defined, see \autoref{sec:LBC_mpp}). 355 375 356 376 The name of the configuration is set through parameter \np{cn_cfg}{cn\_cfg}, … … 360 380 361 381 The global lateral boundary condition type is selected from 8 options using parameter \jp{jperio}. 362 See \autoref{sec:LBC_jperio} for details on the available options and the corresponding values for \jp{jperio}. 382 See \autoref{sec:LBC_jperio} for details on the available options and 383 the corresponding values for \jp{jperio}. 363 384 364 385 %% ================================================================================================= … … 370 391 \label{sec:DOM_hgr_fields} 371 392 372 The explicit specification of a range of mesh-related fields are required for the definition of a configuration. 393 The explicit specification of a range of mesh-related fields are required for 394 the definition of a configuration. 373 395 These include: 374 396 375 397 \begin{clines} 376 int jpiglo, jpjglo, jpkglo /* global domain sizes*/377 int jperio /* lateral global domain b.c.*/378 double glamt, glamu, glamv, glamf /* geographic longitude (t,u,v and f points respectively)*/379 double gphit, gphiu, gphiv, gphif /* geographic latitude*/380 double e1t, e1u, e1v, e1f /* horizontal scale factors*/381 double e2t, e2u, e2v, e2f /* horizontal scale factors*/398 int jpiglo, jpjglo, jpkglo /* global domain sizes */ 399 int jperio /* lateral global domain b.c. */ 400 double glamt, glamu, glamv, glamf /* geographic longitude (t,u,v and f points respectively) */ 401 double gphit, gphiu, gphiv, gphif /* geographic latitude */ 402 double e1t, e1u, e1v, e1f /* horizontal scale factors */ 403 double e2t, e2u, e2v, e2f /* horizontal scale factors */ 382 404 \end{clines} 383 405 … … 393 415 394 416 \begin{clines} 395 /* Optional:*/396 int ORCA, ORCA_index /* configuration name, configuration resolution*/397 double e1e2u, e1e2v /* U and V surfaces (if grid size reduction in some straits)*/398 double ff_f, ff_t /* Coriolis parameter (if not on the sphere)*/417 /* Optional: */ 418 int ORCA, ORCA_index /* configuration name, configuration resolution */ 419 double e1e2u, e1e2v /* U and V surfaces (if grid size reduction in some straits) */ 420 double ff_f, ff_t /* Coriolis parameter (if not on the sphere) */ 399 421 \end{clines} 400 422 … … 403 425 This is particularly useful for locations such as Gibraltar or Indonesian Throughflow pinch-points 404 426 (see \autoref{sec:MISC_strait} for illustrated examples). 405 The key is to reduce the faces of $T$-cell (\ie\ change the value of the horizontal scale factors at $u$- or $v$-point) but 427 The key is to reduce the faces of $T$-cell 428 (\ie\ change the value of the horizontal scale factors at $u$- or $v$-point) but 406 429 not the volume of the cells. 407 430 Doing otherwise can lead to numerical instability issues. 408 431 In normal operation the surface areas are computed from $e1u * e2u$ and $e1v * e2v$ but 409 432 in cases where a gridsize reduction is required, 410 the unaltered surface areas at $u$ and $v$ grid points (\texttt{e1e2u} and \texttt{e1e2v}, respectively) must be read or 411 pre-computed in \mdl{usrdef\_hgr}. 412 If these arrays are present in the \np{cn_domcfg}{cn\_domcfg} file they are read and the internal computation is suppressed. 413 Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{e1e2u} and \texttt{e1e2v} should set 414 the surface-area computation flag: 433 the unaltered surface areas at $u$ and $v$ grid points 434 (\texttt{e1e2u} and \texttt{e1e2v}, respectively) must be read or pre-computed in \mdl{usrdef\_hgr}. 435 If these arrays are present in the \np{cn_domcfg}{cn\_domcfg} file they are read and 436 the internal computation is suppressed. 437 Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{e1e2u} and \texttt{e1e2v} should 438 set the surface-area computation flag: 415 439 \texttt{ie1e2u\_v} to a non-zero value to suppress their re-computation. 416 440 417 441 \smallskip 418 442 Similar logic applies to the other optional fields: 419 \texttt{ff\_f} and \texttt{ff\_t} which can be used to provide the Coriolis parameter at F- and T-points respectively if 420 the mesh is not on a sphere. 421 If present these fields will be read and used and the normal calculation ($2 * \Omega * \sin(\varphi)$) suppressed. 422 Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{ff\_f} and \texttt{ff\_t} should set 423 the Coriolis computation flag: 443 \texttt{ff\_f} and \texttt{ff\_t} which can be used to 444 provide the Coriolis parameter at F- and T-points respectively if the mesh is not on a sphere. 445 If present these fields will be read and used and 446 the normal calculation ($2 * \Omega * \sin(\varphi)$) suppressed. 447 Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{ff\_f} and \texttt{ff\_t} should 448 set the Coriolis computation flag: 424 449 \texttt{iff} to a non-zero value to suppress their re-computation. 425 450 426 Note that longitudes, latitudes, and scale factors at $w$ points are exactly equal to those of $t$ points,427 th us no specific arrays are defined at $w$ points.451 Note that longitudes, latitudes, and scale factors at $w$ points are exactly equal to 452 those of $t$ points, thus no specific arrays are defined at $w$ points. 428 453 429 454 %% ================================================================================================= 430 455 \subsection[Vertical grid (\textit{domzgr.F90})]{Vertical grid (\protect\mdl{domzgr})} 431 456 \label{subsec:DOM_zgr} 457 432 458 \begin{listing} 433 459 \nlst{namdom} … … 438 464 In the vertical, the model mesh is determined by four things: 439 465 \begin{enumerate} 440 \item the bathymetry given in meters; 441 \item the number of levels of the model (\jp{jpk}); 442 \item the analytical transformation $z(i,j,k)$ and the vertical scale factors (derivatives of the transformation); and 443 \item the masking system, \ie\ the number of wet model levels at each 444 $(i,j)$ location of the horizontal grid. 466 \item the bathymetry given in meters; 467 \item the number of levels of the model (\jp{jpk}); 468 \item the analytical transformation $z(i,j,k)$ and the vertical scale factors 469 (derivatives of the transformation); and 470 \item the masking system, 471 \ie\ the number of wet model levels at each $(i,j)$ location of the horizontal grid. 445 472 \end{enumerate} 446 473 447 \begin{figure} [!tb]474 \begin{figure} 448 475 \centering 449 \includegraphics[width=0. 66\textwidth]{Fig_z_zps_s_sps}476 \includegraphics[width=0.5\textwidth]{DOM_z_zps_s_sps} 450 477 \caption[Ocean bottom regarding coordinate systems ($z$, $s$ and hybrid $s-z$)]{ 451 478 The ocean bottom as seen by the model: 452 (a) $z$-coordinate with full step, 453 (b) $z$-coordinate with partial step, 454 (c) $s$-coordinate: terrain following representation, 455 (d) hybrid $s-z$ coordinate, 456 (e) hybrid $s-z$ coordinate with partial step, and 457 (f) same as (e) but in the non-linear free surface (\protect\np[=.false.]{ln_linssh}{ln\_linssh}). 458 Note that the non-linear free surface can be used with any of the 5 coordinates (a) to (e).} 479 \begin{enumerate*}[label=(\textit{\alph*})] 480 \item $z$-coordinate with full step, 481 \item $z$-coordinate with partial step, 482 \item $s$-coordinate: terrain following representation, 483 \item hybrid $s-z$ coordinate, 484 \item hybrid $s-z$ coordinate with partial step, and 485 \item same as (e) but in the non-linear free surface 486 (\protect\np[=.false.]{ln_linssh}{ln\_linssh}). 487 \end{enumerate*} 488 Note that the non-linear free surface can be used with any of the 5 coordinates (a) to (e).} 459 489 \label{fig:DOM_z_zps_s_sps} 460 490 \end{figure} … … 463 493 it is not intended to be an option which can be changed in the middle of an experiment. 464 494 The one exception to this statement being the choice of linear or non-linear free surface. 465 In v4.0 the linear free surface option is implemented as a special case of the non-linear free surface. 495 In v4.0 the linear free surface option is implemented as 496 a special case of the non-linear free surface. 466 497 This is computationally wasteful since it uses the structures for time-varying 3D metrics 467 498 for fields that (in the linear free surface case) are fixed. 468 However, the linear free-surface is rarely used and implementing it this way means 469 a single configuration file can support both options. 470 471 By default a non-linear free surface is used (\np{ln_linssh}{ln\_linssh} set to \forcode{=.false.} in \nam{dom}{dom}): 472 the coordinate follow the time-variation of the free surface so that the transformation is time dependent: 473 $z(i,j,k,t)$ (\eg\ \autoref{fig:DOM_z_zps_s_sps}f). 474 When a linear free surface is assumed (\np{ln_linssh}{ln\_linssh} set to \forcode{=.true.} in \nam{dom}{dom}), 475 the vertical coordinates are fixed in time, but the seawater can move up and down across the $z_0$ surface 499 However, the linear free-surface is rarely used and 500 implementing it this way means a single configuration file can support both options. 501 502 By default a non-linear free surface is used 503 (\np{ln_linssh}{ln\_linssh} set to \forcode{=.false.} in \nam{dom}{dom}): 504 the coordinate follow the time-variation of the free surface so that 505 the transformation is time dependent: $z(i,j,k,t)$ (\eg\ \autoref{fig:DOM_z_zps_s_sps}f). 506 When a linear free surface is assumed 507 (\np{ln_linssh}{ln\_linssh} set to \forcode{=.true.} in \nam{dom}{dom}), 508 the vertical coordinates are fixed in time, but 509 the seawater can move up and down across the $z_0$ surface 476 510 (in other words, the top of the ocean in not a rigid lid). 477 511 478 512 Note that settings: 479 \np{ln_zco}{ln\_zco}, \np{ln_zps}{ln\_zps}, \np{ln_sco}{ln\_sco} and \np{ln_isfcav}{ln\_isfcav} mentioned in the following sections 480 appear to be namelist options but they are no longer truly namelist options for \NEMO. 513 \np{ln_zco}{ln\_zco}, \np{ln_zps}{ln\_zps}, \np{ln_sco}{ln\_sco} and \np{ln_isfcav}{ln\_isfcav} 514 mentioned in the following sections appear to be namelist options but 515 they are no longer truly namelist options for \NEMO. 481 516 Their value is written to and read from the domain configuration file and 482 517 they should be treated as fixed parameters for a particular configuration. 483 They are namelist options for the \texttt{DOMAINcfg} tool that can be used to build the configuration file and484 serve both to provide a record of the choices made whilst building the configuration and 485 to trigger appropriate code blocks within \NEMO.518 They are namelist options for the \texttt{DOMAINcfg} tool that can be used to 519 build the configuration file and serve both to provide a record of the choices made whilst 520 building the configuration and to trigger appropriate code blocks within \NEMO. 486 521 These values should not be altered in the \np{cn_domcfg}{cn\_domcfg} file. 487 522 … … 501 536 A further choice related to vertical coordinate concerns 502 537 the presence (or not) of ocean cavities beneath ice shelves within the model domain. 503 A setting of \np{ln_isfcav}{ln\_isfcav} as \forcode{.true.} indicates that the domain contains ocean cavities, 538 A setting of \np{ln_isfcav}{ln\_isfcav} as \forcode{.true.} indicates that 539 the domain contains ocean cavities, 504 540 otherwise the top, wet layer of the ocean will always be at the ocean surface. 505 541 This option is currently only available for $z$- or $zps$-coordinates. 506 542 In the latter case, partial steps are also applied at the ocean/ice shelf interface. 507 543 508 Within the model, the arrays describing the grid point depths and vertical scale factors are three set of 509 three dimensional arrays $(i,j,k)$ defined at \textit{before}, \textit{now} and \textit{after} time step. 544 Within the model, 545 the arrays describing the grid point depths and vertical scale factors are 546 three set of three dimensional arrays $(i,j,k)$ defined at 547 \textit{before}, \textit{now} and \textit{after} time step. 510 548 The time at which they are defined is indicated by a suffix: $\_b$, $\_n$, or $\_a$, respectively. 511 549 They are updated at each model time step. … … 534 572 \end{clines} 535 573 536 This set of vertical metrics is sufficient to describe the initial depth and thickness of every gridcell in537 the model regardless of the choice of vertical coordinate.574 This set of vertical metrics is sufficient to describe the initial depth and thickness of 575 every gridcell in the model regardless of the choice of vertical coordinate. 538 576 With constant z-levels, e3 metrics will be uniform across each horizontal level. 539 577 In the partial step case each e3 at the \jp{bottom\_level} … … 541 579 may vary from its horizontal neighbours. 542 580 And, in s-coordinates, variations can occur throughout the water column. 543 With the non-linear free-surface, all the coordinates behave more like the s-coordinate in 544 thatvariations occur throughout the water column with displacements related to the sea surface height.581 With the non-linear free-surface, all the coordinates behave more like the s-coordinate in that 582 variations occur throughout the water column with displacements related to the sea surface height. 545 583 These variations are typically much smaller than those arising from bottom fitted coordinates. 546 584 The values for vertical metrics supplied in the domain configuration file can be considered as 547 585 those arising from a flat sea surface with zero elevation. 548 586 549 The \jp{bottom\_level} and \jp{top\_level} 2D arrays define the \jp{bottom\_level} and top wet levels in each grid column. 587 The \jp{bottom\_level} and \jp{top\_level} 2D arrays define 588 the \jp{bottom\_level} and top wet levels in each grid column. 550 589 Without ice cavities, \jp{top\_level} is essentially a land mask (0 on land; 1 everywhere else). 551 590 With ice cavities, \jp{top\_level} determines the first wet point below the overlying ice shelf. … … 556 595 557 596 From \jp{top\_level} and \jp{bottom\_level} fields, the mask fields are defined as follows: 558 \begin{alignat*}{2} 559 tmask(i,j,k) &= & & 560 \begin{cases} 561 0 &\text{if $ k < top\_level(i,j)$} \\ 562 1 &\text{if $bottom\_level(i,j) \leq k \leq top\_level(i,j)$} \\ 563 0 &\text{if $ k > bottom\_level(i,j)$} 564 \end{cases} 565 \\ 566 umask(i,j,k) &= & &tmask(i,j,k) * tmask(i + 1,j, k) \\ 567 vmask(i,j,k) &= & &tmask(i,j,k) * tmask(i ,j + 1,k) \\ 568 fmask(i,j,k) &= & &tmask(i,j,k) * tmask(i + 1,j, k) \\ 569 & &* &tmask(i,j,k) * tmask(i + 1,j, k) \\ 570 wmask(i,j,k) &= & &tmask(i,j,k) * tmask(i ,j,k - 1) \\ 571 \text{with~} wmask(i,j,1) &= & &tmask(i,j,1) 572 \end{alignat*} 597 \begin{align*} 598 tmask(i,j,k) &= 599 \begin{cases} 600 0 &\text{if $ k < top\_level(i,j)$} \\ 601 1 &\text{if $ bottom\_level(i,j) \leq k \leq top\_level(i,j)$} \\ 602 0 &\text{if $k > bottom\_level(i,j) $} 603 \end{cases} \\ 604 umask(i,j,k) &= tmask(i,j,k) * tmask(i + 1,j, k) \\ 605 vmask(i,j,k) &= tmask(i,j,k) * tmask(i ,j + 1,k) \\ 606 fmask(i,j,k) &= tmask(i,j,k) * tmask(i + 1,j, k) * tmask(i,j,k) * tmask(i + 1,j, k) \\ 607 wmask(i,j,k) &= tmask(i,j,k) * tmask(i ,j,k - 1) \\ 608 \text{with~} wmask(i,j,1) &= tmask(i,j,1) 609 \end{align*} 573 610 574 611 Note that, without ice shelves cavities, 575 masks at $t-$ and $w-$points are identical with the numerical indexing used (\autoref{subsec:DOM_Num_Index}). 576 Nevertheless, $wmask$ are required with ocean cavities to deal with the top boundary (ice shelf/ocean interface) 612 masks at $t-$ and $w-$points are identical with the numerical indexing used 613 (\autoref{subsec:DOM_Num_Index}). 614 Nevertheless, 615 $wmask$ are required with ocean cavities to deal with the top boundary (ice shelf/ocean interface) 577 616 exactly in the same way as for the bottom boundary. 578 617 … … 588 627 \label{subsec:DOM_closea} 589 628 590 When a global ocean is coupled to an atmospheric model it is better to represent all large water bodies591 (\eg\ Great Lakes, Caspian sea \dots) even if the model resolution does not allow their communication with 592 the rest of the ocean.629 When a global ocean is coupled to an atmospheric model it is better to 630 represent all large water bodies (\eg\ Great Lakes, Caspian sea, \dots) even if 631 the model resolution does not allow their communication with the rest of the ocean. 593 632 This is unnecessary when the ocean is forced by fixed atmospheric conditions, 594 633 so these seas can be removed from the ocean domain. 595 The user has the option to set the bathymetry in closed seas to zero (see \autoref{sec:MISC_closea}) and 596 to optionally decide on the fate of any freshwater imbalance over the area. 597 The options are explained in \autoref{sec:MISC_closea} but it should be noted here that 598 a successful use of these options requires appropriate mask fields to be present in the domain configuration file. 634 The user has the option to 635 set the bathymetry in closed seas to zero (see \autoref{sec:MISC_closea}) and to 636 optionally decide on the fate of any freshwater imbalance over the area. 637 The options are explained in \autoref{sec:MISC_closea} but 638 it should be noted here that a successful use of these options requires 639 appropriate mask fields to be present in the domain configuration file. 599 640 Among the possibilities are: 600 641 601 642 \begin{clines} 602 int closea_mask /* non-zero values in closed sea areas for optional masking*/603 int closea_mask_rnf /* non-zero values in closed sea areas with runoff locations (precip only)*/604 int closea_mask_emp /* non-zero values in closed sea areas with runoff locations (total emp)*/643 int closea_mask /* non-zero values in closed sea areas for optional masking */ 644 int closea_mask_rnf /* non-zero values in closed sea areas with runoff locations (precip only) */ 645 int closea_mask_emp /* non-zero values in closed sea areas with runoff locations (total emp) */ 605 646 \end{clines} 606 647 … … 610 651 611 652 Most of the arrays relating to a particular ocean model configuration discussed in this chapter 612 (grid-point position, scale factors) 613 can be saved in a file if 614 namelist parameter \np{ln_write_cfg}{ln\_write\_cfg} (namelist \nam{cfg}{cfg}) is set to\forcode{.true.};653 (grid-point position, scale factors) can be saved in a file if 654 namelist parameter \np{ln_write_cfg}{ln\_write\_cfg} (namelist \nam{cfg}{cfg}) is set to 655 \forcode{.true.}; 615 656 the output filename is set through parameter \np{cn_domcfg_out}{cn\_domcfg\_out}. 616 657 This is only really useful if … … 619 660 620 661 Alternatively, all the arrays relating to a particular ocean model configuration 621 (grid-point position, scale factors, depths and masks) 622 can be saved in a file called \texttt{mesh\_mask} if 623 namelist parameter \np{ln_meshmask}{ln\_meshmask} (namelist \nam{dom}{dom}) is set to \forcode{.true.}. 662 (grid-point position, scale factors, depths and masks) can be saved in 663 a file called \texttt{mesh\_mask} if 664 namelist parameter \np{ln_meshmask}{ln\_meshmask} (namelist \nam{dom}{dom}) is set to 665 \forcode{.true.}. 624 666 This file contains additional fields that can be useful for post-processing applications. 625 667 … … 627 669 \section[Initial state (\textit{istate.F90} and \textit{dtatsd.F90})]{Initial state (\protect\mdl{istate} and \protect\mdl{dtatsd})} 628 670 \label{sec:DOM_DTA_tsd} 671 629 672 \begin{listing} 630 673 \nlst{namtsd} … … 638 681 639 682 \begin{description} 640 \item [{\np[=.true.]{ln_tsd_init}{ln\_tsd\_init}}] Use T and S input files that can be given on the model grid itself or on their native input data grids. 641 In the latter case, the data will be interpolated on-the-fly both in the horizontal and the vertical to the model grid 683 \item [{\np[=.true.]{ln_tsd_init}{ln\_tsd\_init}}] Use T and S input files that can be given on 684 the model grid itself or on their native input data grids. 685 In the latter case, 686 the data will be interpolated on-the-fly both in the horizontal and the vertical to the model grid 642 687 (see \autoref{subsec:SBC_iof}). 643 The information relating to the input files are specified in the \np{sn_tem}{sn\_tem} and \np{sn_sal}{sn\_sal} structures. 688 The information relating to the input files are specified in 689 the \np{sn_tem}{sn\_tem} and \np{sn_sal}{sn\_sal} structures. 644 690 The computation is done in the \mdl{dtatsd} module. 645 \item [{\np[=.false.]{ln_tsd_init}{ln\_tsd\_init}}] Initial values for T and S are set via a user supplied \rou{usr\_def\_istate} routine contained in \mdl{userdef\_istate}. 691 \item [{\np[=.false.]{ln_tsd_init}{ln\_tsd\_init}}] Initial values for T and S are set via 692 a user supplied \rou{usr\_def\_istate} routine contained in \mdl{userdef\_istate}. 646 693 The default version sets horizontally uniform T and profiles as used in the GYRE configuration 647 694 (see \autoref{sec:CFGS_gyre}). 648 695 \end{description} 649 696 650 \ onlyinsubfile{\input{../../global/epilogue}}697 \subinc{\input{../../global/epilogue}} 651 698 652 699 \end{document}
Note: See TracChangeset
for help on using the changeset viewer.