- Timestamp:
- 2019-10-29T18:14:49+01:00 (4 years ago)
- Location:
- NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc
- Files:
-
- 15 deleted
- 22 edited
- 26 copied
Legend:
- Unmodified
- Added
- Removed
-
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc
- Property svn:ignore deleted
-
Property
svn:externals
set to
^/utils/badges badges
^/utils/logos logos
-
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex
- Property svn:ignore deleted
-
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO
- Property svn:ignore deleted
-
Property
svn:externals
set to
^/utils/figures/NEMO figures
-
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/main
- Property svn:ignore
-
old new 1 *.aux2 *.bbl3 *.blg4 *.dvi5 *.fdb*6 *.fls7 *.idx8 1 *.ilg 9 2 *.ind 10 *.log11 *.maf12 *.mtc*13 *.out14 *.pdf15 *.toc16 _minted-*
-
- Property svn:ignore
-
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles
- Property svn:ignore
-
old new 1 *.aux 2 *.bbl 3 *.blg 4 *.dvi 5 *.fdb* 6 *.fls 7 *.idx 1 *.ind 8 2 *.ilg 9 *.ind10 *.log11 *.maf12 *.mtc*13 *.out14 *.pdf15 *.toc16 _minted-*
-
- Property svn:ignore
-
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_ASM.tex
r10442 r11831 2 2 3 3 \begin{document} 4 % ================================================================ 5 % Chapter Assimilation increments (ASM) 6 % ================================================================ 4 7 5 \chapter{Apply Assimilation Increments (ASM)} 8 6 \label{chap:ASM} 9 7 10 Authors: D. Lea, M. Martin, K. Mogensen, A. Weaver, ... % do we keep 8 % {\em 4.0} & {\em D. J. Lea} & {\em \NEMO\ 4.0 updates} \\ 9 % {\em 3.4} & {\em D. J. Lea, M. Martin, K. Mogensen, A. Weaver} & {\em Initial version} \\ 11 10 12 \ minitoc11 \thispagestyle{plain} 13 12 14 \newpage 13 \chaptertoc 14 15 \paragraph{Changes record} ~\\ 16 17 {\footnotesize 18 \begin{tabularx}{\textwidth}{l||X|X} 19 Release & Author(s) & Modifications \\ 20 \hline 21 {\em 4.0} & {\em ...} & {\em ...} \\ 22 {\em 3.6} & {\em ...} & {\em ...} \\ 23 {\em 3.4} & {\em ...} & {\em ...} \\ 24 {\em <=3.4} & {\em ...} & {\em ...} 25 \end{tabularx} 26 } 27 28 \clearpage 15 29 16 30 The ASM code adds the functionality to apply increments to the model variables: temperature, salinity, 17 sea surface height, velocity and sea ice concentration. 31 sea surface height, velocity and sea ice concentration. 18 32 These are read into the model from a NetCDF file which may be produced by separate data assimilation code. 19 33 The code can also output model background fields which are used as an input to data assimilation code. 20 This is all controlled by the namelist \ textit{\ngn{nam\_asminc}}.34 This is all controlled by the namelist \nam{_asminc}{\_asminc}. 21 35 There is a brief description of all the namelist options provided. 22 36 To build the ASM code \key{asminc} must be set. 23 37 24 %=============================================================== 25 38 %% ================================================================================================= 26 39 \section{Direct initialization} 27 40 \label{sec:ASM_DI} … … 29 42 Direct initialization (DI) refers to the instantaneous correction of the model background state using 30 43 the analysis increment. 31 DI is used when \np{ln \_asmdin} is set to true.44 DI is used when \np{ln_asmdin}{ln\_asmdin} is set to true. 32 45 46 %% ================================================================================================= 33 47 \section{Incremental analysis updates} 34 48 \label{sec:ASM_IAU} … … 37 51 it may be preferable to introduce the increment gradually into the ocean model in order to 38 52 minimize spurious adjustment processes. 39 This technique is referred to as Incremental Analysis Updates (IAU) \citep{ Bloom_al_MWR96}.53 This technique is referred to as Incremental Analysis Updates (IAU) \citep{bloom.takacs.ea_MWR96}. 40 54 IAU is a common technique used with 3D assimilation methods such as 3D-Var or OI. 41 IAU is used when \np{ln \_asmiau} is set to true.55 IAU is used when \np{ln_asmiau}{ln\_asmiau} is set to true. 42 56 43 With IAU, the model state trajectory ${\ bf x}$ in the assimilation window ($t_{0} \leq t_{i} \leq t_{N}$)57 With IAU, the model state trajectory ${\mathbf x}$ in the assimilation window ($t_{0} \leq t_{i} \leq t_{N}$) 44 58 is corrected by adding the analysis increments for temperature, salinity, horizontal velocity and SSH as 45 59 additional tendency terms to the prognostic equations: 46 60 \begin{align*} 47 % \label{eq: wa_traj_iau}48 {\ bf x}^{a}(t_{i}) = M(t_{i}, t_{0})[{\bf x}^{b}(t_{0})] \; + \; F_{i} \delta \tilde{\bf x}^{a}61 % \label{eq:ASM_wa_traj_iau} 62 {\mathbf x}^{a}(t_{i}) = M(t_{i}, t_{0})[{\mathbf x}^{b}(t_{0})] \; + \; F_{i} \delta \tilde{\mathbf x}^{a} 49 63 \end{align*} 50 where $F_{i}$ is a weighting function for applying the increments $\delta\tilde{\ bf x}^{a}$ defined such that64 where $F_{i}$ is a weighting function for applying the increments $\delta\tilde{\mathbf x}^{a}$ defined such that 51 65 $\sum_{i=1}^{N} F_{i}=1$. 52 ${\ bf x}^b$ denotes the model initial state and ${\bf x}^a$ is the model state after the increments are applied.66 ${\mathbf x}^b$ denotes the model initial state and ${\mathbf x}^a$ is the model state after the increments are applied. 53 67 To control the adjustment time of the model to the increment, 54 68 the increment can be applied over an arbitrary sub-window, $t_{m} \leq t_{i} \leq t_{n}$, … … 56 70 Typically the increments are spread evenly over the full window. 57 71 In addition, two different weighting functions have been implemented. 58 The first function employs constant weights,72 The first function (namelist option \np{niaufn}{niaufn}=0) employs constant weights, 59 73 \begin{align} 60 \label{eq: F1_i}74 \label{eq:ASM_F1_i} 61 75 F^{(1)}_{i} 62 76 =\left\{ 63 77 \begin{array}{ll} 64 0 & {\ rm if} \; \; \; t_{i} < t_{m} \\65 1/M & {\ rm if} \; \; \; t_{m} < t_{i} \leq t_{n} \\66 0 & {\ rm if} \; \; \; t_{i} > t_{n}78 0 & {\mathrm if} \; \; \; t_{i} < t_{m} \\ 79 1/M & {\mathrm if} \; \; \; t_{m} < t_{i} \leq t_{n} \\ 80 0 & {\mathrm if} \; \; \; t_{i} > t_{n} 67 81 \end{array} 68 \right. 82 \right. 69 83 \end{align} 70 84 where $M = m-n$. 71 The second function employs peaked hat-like weights in order to give maximum weight in the centre of the sub-window,85 The second function (namelist option \np{niaufn}{niaufn}=1) employs peaked hat-like weights in order to give maximum weight in the centre of the sub-window, 72 86 with the weighting reduced linearly to a small value at the window end-points: 73 87 \begin{align} 74 \label{eq: F2_i}88 \label{eq:ASM_F2_i} 75 89 F^{(2)}_{i} 76 90 =\left\{ 77 91 \begin{array}{ll} 78 0 & {\ rm if} \; \; \; t_{i} < t_{m} \\79 \alpha \, i & {\ rm if} \; \; \; t_{m} \leq t_{i} \leq t_{M/2} \\80 \alpha \, (M - i +1) & {\ rm if} \; \; \; t_{M/2} < t_{i} \leq t_{n} \\81 0 & {\ rm if} \; \; \; t_{i} > t_{n}92 0 & {\mathrm if} \; \; \; t_{i} < t_{m} \\ 93 \alpha \, i & {\mathrm if} \; \; \; t_{m} \leq t_{i} \leq t_{M/2} \\ 94 \alpha \, (M - i +1) & {\mathrm if} \; \; \; t_{M/2} < t_{i} \leq t_{n} \\ 95 0 & {\mathrm if} \; \; \; t_{i} > t_{n} 82 96 \end{array} 83 97 \right. 84 98 \end{align} 85 where $\alpha^{-1} = \sum_{i=1}^{M/2} 2i$ and $M$ is assumed to be even. 86 The weights described by \autoref{eq: F2_i} provide a smoother transition of the analysis trajectory from87 one assimilation cycle to the next than that described by \autoref{eq: F1_i}.99 where $\alpha^{-1} = \sum_{i=1}^{M/2} 2i$ and $M$ is assumed to be even. 100 The weights described by \autoref{eq:ASM_F2_i} provide a smoother transition of the analysis trajectory from 101 one assimilation cycle to the next than that described by \autoref{eq:ASM_F1_i}. 88 102 89 %========================================================================== 90 % Divergence damping description %%% 103 %% ================================================================================================= 91 104 \section{Divergence damping initialisation} 92 105 \label{sec:ASM_div_dmp} 93 106 94 The velocity increments may be initialized by the iterative application of a divergence damping operator. 95 In iteration step $n$ new estimates of velocity increments $u^{n}_I$ and $v^{n}_I$ are updated by: 107 It is quite challenging for data assimilation systems to provide non-divergent velocity increments. 108 Applying divergent velocity increments will likely cause spurious vertical velocities in the model. This section describes a method to take velocity increments provided to \NEMO\ ($u^0_I$ and $v^0_I$) and adjust them by the iterative application of a divergence damping operator. The method is also described in \citet{dobricic.pinardi.ea_OS07}. 109 110 In iteration step $n$ (starting at $n=1$) new estimates of velocity increments $u^{n}_I$ and $v^{n}_I$ are updated by: 111 96 112 \begin{equation} 97 \label{eq: asm_dmp}113 \label{eq:ASM_dmp} 98 114 \left\{ 99 115 \begin{aligned} … … 105 121 \right., 106 122 \end{equation} 107 where 123 124 where the divergence is defined as 125 108 126 \[ 109 % \label{eq: asm_div}127 % \label{eq:ASM_div} 110 128 \chi^{n-1}_I = \frac{1}{e_{1t}\,e_{2t}\,e_{3t} } 111 129 \left( {\delta_i \left[ {e_{2u}\,e_{3u}\,u^{n-1}_I} \right] 112 130 +\delta_j \left[ {e_{1v}\,e_{3v}\,v^{n-1}_I} \right]} \right). 113 131 \] 114 By the application of \autoref{eq:asm_dmp} and \autoref{eq:asm_dmp} the divergence is filtered in each iteration, 132 133 By the application of \autoref{eq:ASM_dmp} the divergence is filtered in each iteration, 115 134 and the vorticity is left unchanged. 116 135 In the presence of coastal boundaries with zero velocity increments perpendicular to the coast … … 118 137 This type of the initialisation reduces the vertical velocity magnitude and 119 138 alleviates the problem of the excessive unphysical vertical mixing in the first steps of the model integration 120 \citep{ Talagrand_JAS72, Dobricic_al_OS07}.139 \citep{talagrand_JAS72, dobricic.pinardi.ea_OS07}. 121 140 Diffusion coefficients are defined as $A_D = \alpha e_{1t} e_{2t}$, where $\alpha = 0.2$. 122 The divergence damping is activated by assigning to \np{nn \_divdmp} in the \textit{nam\_asminc} namelist141 The divergence damping is activated by assigning to \np{nn_divdmp}{nn\_divdmp} in the \nam{_asminc}{\_asminc} namelist 123 142 a value greater than zero. 124 By choosing this value to be of the order of 100 the increments in 125 the vertical velocity will be significantly reduced. 143 This specifies the number of iterations of the divergence damping. Setting a value of the order of 100 will result in a significant reduction in the vertical velocity induced by the increments. 126 144 127 128 %========================================================================== 129 145 %% ================================================================================================= 130 146 \section{Implementation details} 131 147 \label{sec:ASM_details} 132 148 133 Here we show an example \n gn{namasm} namelist and the header of an example assimilation increments file on149 Here we show an example \nam{_asminc}{\_asminc} namelist and the header of an example assimilation increments file on 134 150 the ORCA2 grid. 135 151 136 %------------------------------------------namasm----------------------------------------------------- 137 % 138 \nlst{nam_asminc} 139 %------------------------------------------------------------------------------------------------------------- 152 \begin{listing} 153 \nlst{nam_asminc} 154 \caption{\forcode{&nam_asminc}} 155 \label{lst:nam_asminc} 156 \end{listing} 140 157 141 158 The header of an assimilation increments file produced using the NetCDF tool … … 177 194 \end{clines} 178 195 179 \biblio 180 181 \pindex 196 \subinc{\input{../../global/epilogue}} 182 197 183 198 \end{document} -
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_DIA.tex
r10509 r11831 2 2 3 3 \begin{document} 4 % ================================================================ 5 % Chapter I/O & Diagnostics 6 % ================================================================ 4 7 5 \chapter{Output and Diagnostics (IOM, DIA, TRD, FLO)} 8 6 \label{chap:DIA} 9 7 10 \minitoc 11 12 \newpage 13 14 % ================================================================ 15 % Old Model Output 16 % ================================================================ 17 \section{Old model output (default)} 8 % {\em 4.0} & {\em Mirek Andrejczuk, Massimiliano Drudi} & {\em } \\ 9 % {\em } & {\em Dorotea Iovino, Nicolas Martin} & {\em } \\ 10 % {\em 3.6} & {\em Gurvan Madec, Sebastien Masson } & {\em } \\ 11 % {\em 3.4} & {\em Gurvan Madec, Rachid Benshila, Andrew Coward } & {\em } \\ 12 % {\em } & {\em Christian Ethe, Sebastien Masson } & {\em } \\ 13 14 \thispagestyle{plain} 15 16 \chaptertoc 17 18 \paragraph{Changes record} ~\\ 19 20 {\footnotesize 21 \begin{tabularx}{\textwidth}{l||X|X} 22 Release & Author(s) & Modifications \\ 23 \hline 24 {\em 4.0} & {\em ...} & {\em ...} \\ 25 {\em 3.6} & {\em ...} & {\em ...} \\ 26 {\em 3.4} & {\em ...} & {\em ...} \\ 27 {\em <=3.4} & {\em ...} & {\em ...} 28 \end{tabularx} 29 } 30 31 \clearpage 32 33 %% ================================================================================================= 34 \section{Model output} 18 35 \label{sec:DIA_io_old} 19 36 … … 25 42 the same run performed in one step. 26 43 It should be noted that this requires that the restart file contains two consecutive time steps for 27 all the prognostic variables, and that it is saved in the same binary format as the one used by the computer that 28 is to read it (in particular, 32 bits binary IEEE format must not be used for this file). 44 all the prognostic variables. 29 45 30 46 The output listing and file(s) are predefined but should be checked and eventually adapted to the user's needs. 31 The output listing is stored in the $ocean.output$file.32 The information is printed from within the code on the logical unit $numout$.47 The output listing is stored in the \textit{ocean.output} file. 48 The information is printed from within the code on the logical unit \texttt{numout}. 33 49 To locate these prints, use the UNIX command "\textit{grep -i numout}" in the source code directory. 34 50 … … 39 55 A complete description of the use of this I/O server is presented in the next section. 40 56 41 By default, \key{iomput} is not defined, 42 NEMO produces NetCDF with the old IOIPSL library which has been kept for compatibility and its easy installation. 43 However, the IOIPSL library is quite inefficient on parallel machines and, since version 3.2, 44 many diagnostic options have been added presuming the use of \key{iomput}. 45 The usefulness of the default IOIPSL-based option is expected to reduce with each new release. 46 If \key{iomput} is not defined, output files and content are defined in the \mdl{diawri} module and 47 contain mean (or instantaneous if \key{diainstant} is defined) values over a regular period of 48 nn\_write time-steps (namelist parameter). 49 50 %\gmcomment{ % start of gmcomment 51 52 % ================================================================ 53 % Diagnostics 54 % ================================================================ 57 %\cmtgm{ % start of gmcomment 58 59 %% ================================================================================================= 55 60 \section{Standard model output (IOM)} 56 61 \label{sec:DIA_iom} 57 62 58 Since version 3.2, iomput is the NEMOoutput interface of choice.63 Since version 3.2, iomput is the \NEMO\ output interface of choice. 59 64 It has been designed to be simple to use, flexible and efficient. 60 The two main purposes of iomput are: 65 The two main purposes of iomput are: 61 66 62 67 \begin{enumerate} 63 \item 64 The complete and flexible control of the output files through external XML files adapted by 68 \item The complete and flexible control of the output files through external XML files adapted by 65 69 the user from standard templates. 66 \item 67 To achieve high performance and scalable output through the optional distribution of 70 \item To achieve high performance and scalable output through the optional distribution of 68 71 all diagnostic output related tasks to dedicated processes. 69 72 \end{enumerate} 70 73 71 The first functionality allows the user to specify, without code changes or recompilation, 74 The first functionality allows the user to specify, without code changes or recompilation, 72 75 aspects of the diagnostic output stream, such as: 73 76 74 77 \begin{itemize} 75 \item 76 The choice of output frequencies that can be different for each file (including real months and years). 77 \item 78 The choice of file contents; includes complete flexibility over which data are written in which files 78 \item The choice of output frequencies that can be different for each file (including real months and years). 79 \item The choice of file contents; includes complete flexibility over which data are written in which files 79 80 (the same data can be written in different files). 80 \item 81 The possibility to split output files at a chosen frequency. 82 \item 83 The possibility to extract a vertical or an horizontal subdomain. 84 \item 85 The choice of the temporal operation to perform, \eg: average, accumulate, instantaneous, min, max and once. 86 \item 87 Control over metadata via a large XML "database" of possible output fields. 81 \item The possibility to split output files at a chosen frequency. 82 \item The possibility to extract a vertical or an horizontal subdomain. 83 \item The choice of the temporal operation to perform, \eg: average, accumulate, instantaneous, min, max and once. 84 \item Control over metadata via a large XML "database" of possible output fields. 88 85 \end{itemize} 89 86 … … 91 88 in a very easy way. 92 89 All details of iomput functionalities are listed in the following subsections. 93 Examples of the XML files that control the outputs can be found in: \path{NEMOGCM/CONFIG/ORCA2_LIM/EXP00/iodef.xml}, 94 \path{NEMOGCM/CONFIG/SHARED/field_def.xml} and \path{NEMOGCM/CONFIG/SHARED/domain_def.xml}. \\ 90 Examples of the XML files that control the outputs can be found in: 91 \path{cfgs/ORCA2_ICE_PISCES/EXPREF/iodef.xml}, 92 \path{cfgs/SHARED/field_def_nemo-oce.xml}, 93 \path{cfgs/SHARED/field_def_nemo-pisces.xml}, 94 \path{cfgs/SHARED/field_def_nemo-ice.xml} and \path{cfgs/SHARED/domain_def_nemo.xml}. \\ 95 95 96 96 The second functionality targets output performance when running in parallel (\key{mpp\_mpi}). 97 Iomput provides the possibility to specify N dedicated I/O processes (in addition to the NEMOprocesses)97 Iomput provides the possibility to specify N dedicated I/O processes (in addition to the \NEMO\ processes) 98 98 to collect and write the outputs. 99 99 With an appropriate choice of N by the user, the bottleneck associated with the writing of 100 100 the output files can be greatly reduced. 101 101 102 In version 3.6, the iom\_putinterface depends on103 an external code called \href{https://forge.ipsl.jussieu.fr/ioserver/browser/XIOS/branchs/xios- 1.0}{XIOS-1.0}104 (use of revision 618 or higher is required).102 In version 3.6, the \rou{iom\_put} interface depends on 103 an external code called \href{https://forge.ipsl.jussieu.fr/ioserver/browser/XIOS/branchs/xios-2.5}{XIOS-2.5} 104 %(use of revision 618 or higher is required). 105 105 This new IO server can take advantage of the parallel I/O functionality of NetCDF4 to 106 106 create a single output file and therefore to bypass the rebuilding phase. 107 107 Note that writing in parallel into the same NetCDF files requires that your NetCDF4 library is linked to 108 an HDF5 library that has been correctly compiled (\ie with the configure option $--$enable-parallel).108 an HDF5 library that has been correctly compiled (\ie\ with the configure option $--$enable-parallel). 109 109 Note that the files created by iomput through XIOS are incompatible with NetCDF3. 110 110 All post-processsing and visualization tools must therefore be compatible with NetCDF4 and not only NetCDF3. 111 111 112 112 Even if not using the parallel I/O functionality of NetCDF4, using N dedicated I/O servers, 113 where N is typically much less than the number of NEMOprocessors, will reduce the number of output files created.114 This can greatly reduce the post-processing burden usually associated with using large numbers of NEMOprocessors.113 where N is typically much less than the number of \NEMO\ processors, will reduce the number of output files created. 114 This can greatly reduce the post-processing burden usually associated with using large numbers of \NEMO\ processors. 115 115 Note that for smaller configurations, the rebuilding phase can be avoided, 116 116 even without a parallel-enabled NetCDF4 library, simply by employing only one dedicated I/O server. 117 117 118 %% ================================================================================================= 118 119 \subsection{XIOS: Reading and writing restart file} 119 120 120 XIOS may be used to read single file restart produced by NEMO. Currently only the variables written to121 file \forcode{numror} can be handled by XIOS. To activate restart reading using XIOS, set \np {ln\_xios\_read}\forcode{ = .true.}122 in \textit{namelist\_cfg}. This setting will be ignored when multiple restart files are present, and default NEMO123 functionality will be used for reading. There is no need to change iodef.xml file to use XIOS to read 124 restart, all definitions are done within the NEMO code. For high resolution configuration, however,121 XIOS may be used to read single file restart produced by \NEMO. Currently only the variables written to 122 file \forcode{numror} can be handled by XIOS. To activate restart reading using XIOS, set \np[=.true. ]{ln_xios_read}{ln\_xios\_read} 123 in \textit{namelist\_cfg}. This setting will be ignored when multiple restart files are present, and default \NEMO 124 functionality will be used for reading. There is no need to change iodef.xml file to use XIOS to read 125 restart, all definitions are done within the \NEMO\ code. For high resolution configuration, however, 125 126 there may be a need to add the following line in iodef.xml (xios context): 126 127 … … 129 130 \end{xmllines} 130 131 131 This variable sets timeout for reading. 132 133 If XIOS is to be used to read restart from file generated with an earlier NEMOversion (3.6 for instance),132 This variable sets timeout for reading. 133 134 If XIOS is to be used to read restart from file generated with an earlier \NEMO\ version (3.6 for instance), 134 135 dimension \forcode{z} defined in restart file must be renamed to \forcode{nav_lev}.\\ 135 136 136 XIOS can also be used to write NEMO restart. A namelist parameter \np{nn\_wxios} is used to determine the137 type of restart NEMO will write. If it is set to 0, default NEMO functionality will be used - each138 processor writes its own restart file; if it is set to 1 XIOS will write restart into a single file; 139 for \np {nn\_wxios = 2} the restart will be written by XIOS into multiple files, one for each XIOS server.140 Note, however, that \textbf{ NEMO will not read restart generated by XIOS when \np{nn\_wxios = 2}}. The restart will141 have to be rebuild before continuing the run. This option aims to reduce number of restart files generated by NEMO only,142 and may be useful when there is a need to change number of processors used to run simulation. 137 XIOS can also be used to write \NEMO\ restart. A namelist parameter \np{nn_wxios}{nn\_wxios} is used to determine the 138 type of restart \NEMO\ will write. If it is set to 0, default \NEMO\ functionality will be used - each 139 processor writes its own restart file; if it is set to 1 XIOS will write restart into a single file; 140 for \np[=2]{nn_wxios}{nn\_wxios} the restart will be written by XIOS into multiple files, one for each XIOS server. 141 Note, however, that \textbf{\NEMO\ will not read restart generated by XIOS when \np[=2]{nn_wxios}{nn\_wxios}}. The restart will 142 have to be rebuild before continuing the run. This option aims to reduce number of restart files generated by \NEMO\ only, 143 and may be useful when there is a need to change number of processors used to run simulation. 143 144 144 145 If an additional variable must be written to a restart file, the following steps are needed: 145 \begin{ description}146 \item[step 1:] add variable name to a list of restart variables (in subroutine \rou{iom\_set\_rst\_vars,} \mdl{iom}) and 147 define correct grid for the variable (\forcode{grid_N_3D} - 3D variable, \forcode{grid_N} - 2D variable, \forcode{grid_vector} - 146 \begin{enumerate} 147 \item Add variable name to a list of restart variables (in subroutine \rou{iom\_set\_rst\_vars,} \mdl{iom}) and 148 define correct grid for the variable (\forcode{grid_N_3D} - 3D variable, \forcode{grid_N} - 2D variable, \forcode{grid_vector} - 148 149 1D variable, \forcode{grid_scalar} - scalar), 149 \item[step 2:] add variable to the list of fields written by restart. This can be done either in subroutine 150 \rou{iom\_set\_rstw\_core} (\mdl{iom}) or by calling \rou{iom\_set\_rstw\_active} (\mdl{iom}) with the name of a variable 151 as an argument. This convention follows approach for writing restart using iom, where variables are 150 \item Add variable to the list of fields written by restart. This can be done either in subroutine 151 \rou{iom\_set\_rstw\_core} (\mdl{iom}) or by calling \rou{iom\_set\_rstw\_active} (\mdl{iom}) with the name of a variable 152 as an argument. This convention follows approach for writing restart using iom, where variables are 152 153 written either by \rou{rst\_write} or by calling \rou{iom\_rstput} from individual routines. 153 \end{description} 154 154 \end{enumerate} 155 155 156 156 An older versions of XIOS do not support reading functionality. It's recommended to use at least XIOS2@1451. 157 157 158 158 %% ================================================================================================= 159 159 \subsection{XIOS: XML Inputs-Outputs Server} 160 160 161 %% ================================================================================================= 161 162 \subsubsection{Attached or detached mode?} 162 163 … … 168 169 \xmlline|<variable id="using_server" type="bool"></variable>| 169 170 170 The {\tt using\_server} setting determines whether or not the server will be used in \textit{attached mode} 171 (as a library) [{\tt> false <}] or in \textit{detached mode} 172 (as an external executable on N additional, dedicated cpus) [{\tt > true <}]. 173 The \textit{attached mode} is simpler to use but much less efficient for massively parallel applications. 171 The \texttt{using\_server} setting determines whether or not the server will be used in 172 \textit{attached mode} 173 (as a library) [\texttt{> false <}] or in \textit{detached mode} 174 (as an external executable on N additional, dedicated cpus) [\texttt{ > true <}]. 175 The \textit{attached mode} is simpler to use but much less efficient for 176 massively parallel applications. 174 177 The type of each file can be either ''multiple\_file'' or ''one\_file''. 175 178 176 179 In \textit{attached mode} and if the type of file is ''multiple\_file'', 177 then each NEMOprocess will also act as an IO server and produce its own set of output files.180 then each \NEMO\ process will also act as an IO server and produce its own set of output files. 178 181 Superficially, this emulates the standard behaviour in previous versions. 179 182 However, the subdomain written out by each process does not correspond to … … 187 190 write to its own set of output files. 188 191 If the ''one\_file'' option is chosen then all XIOS processes will collect their longitudinal strips and 189 write (in parallel) to a single output file. 192 write (in parallel) to a single output file. 190 193 Note running in detached mode requires launching a Multiple Process Multiple Data (MPMD) parallel job. 191 194 The following subsection provides a typical example but the syntax will vary in different MPP environments. 192 195 196 %% ================================================================================================= 193 197 \subsubsection{Number of cpu used by XIOS in detached mode} 194 198 195 199 The number of cores used by the XIOS is specified when launching the model. 196 The number of cores dedicated to XIOS should be from \texttildelow1/10 to \texttildelow1/50 of the number of 197 cores dedicated to NEMO.200 The number of cores dedicated to XIOS should be from \texttildelow1/10 to \texttildelow1/50 of the number of 201 cores dedicated to \NEMO. 198 202 Some manufacturers suggest using O($\sqrt{N}$) dedicated IO processors for N processors but 199 this is a general recommendation and not specific to NEMO.203 this is a general recommendation and not specific to \NEMO. 200 204 It is difficult to provide precise recommendations because the optimal choice will depend on 201 the particular hardware properties of the target system 205 the particular hardware properties of the target system 202 206 (parallel filesystem performance, available memory, memory bandwidth etc.) 203 207 and the volume and frequency of data to be created. … … 205 209 \cmd|mpirun -np 62 ./nemo.exe : -np 2 ./xios_server.exe| 206 210 211 %% ================================================================================================= 207 212 \subsubsection{Control of XIOS: the context in iodef.xml} 208 213 209 As well as the {\tt using\_server} flag, other controls on the use of XIOS are set in the XIOS context in iodef.xml. 214 As well as the \texttt{using\_server} flag, other controls on the use of XIOS are set in 215 the XIOS context in \textit{iodef.xml}. 210 216 See the XML basics section below for more details on XML syntax and rules. 211 217 212 218 \begin{table} 213 \scriptsize214 219 \begin{tabularx}{\textwidth}{|lXl|} 215 220 \hline … … 220 225 \hline 221 226 buffer\_size & 222 buffer size used by XIOS to send data from NEMOto XIOS.227 buffer size used by XIOS to send data from \NEMO\ to XIOS. 223 228 Larger is more efficient. 224 229 Note that needed/used buffer sizes are summarized at the end of the job & … … 226 231 \hline 227 232 buffer\_server\_factor\_size & 228 ratio between NEMOand XIOS buffer size.233 ratio between \NEMO\ and XIOS buffer size. 229 234 Should be 2. & 230 235 2 \\ … … 243 248 \hline 244 249 oasis\_codes\_id & 245 when using oasis, define the identifier of NEMOin the namcouple.250 when using oasis, define the identifier of \NEMO\ in the namcouple. 246 251 Note that the identifier of XIOS is xios.x & 247 252 oceanx \\ … … 250 255 \end{table} 251 256 257 %% ================================================================================================= 252 258 \subsection{Practical issues} 253 259 260 %% ================================================================================================= 254 261 \subsubsection{Installation} 255 262 256 As mentioned, XIOS is supported separately and must be downloaded and compiled before it can be used with NEMO.263 As mentioned, XIOS is supported separately and must be downloaded and compiled before it can be used with \NEMO. 257 264 See the installation guide on the \href{http://forge.ipsl.jussieu.fr/ioserver/wiki}{XIOS} wiki for help and guidance. 258 NEMO will need to link to the compiled XIOS library. 259 The \href{https://forge.ipsl.jussieu.fr/nemo/wiki/Users/ModelInterfacing/InputsOutputs#Inputs-OutputsusingXIOS} 260 {XIOS with NEMO} guide provides an example illustration of how this can be achieved. 261 265 \NEMO\ will need to link to the compiled XIOS library. 266 The \href{https://forge.ipsl.jussieu.fr/nemo/chrome/site/doc/NEMO/guide/html/install.html#extract-and-install-xios} 267 {Extract and install XIOS} guide provides an example illustration of how this can be achieved. 268 269 %% ================================================================================================= 262 270 \subsubsection{Add your own outputs} 263 271 … … 268 276 269 277 \begin{enumerate} 270 \item[1.] 271 in NEMO code, add a \forcode{CALL iom\_put( 'identifier', array )} where you want to output a 2D or 3D array. 272 \item[2.] 273 If necessary, add \forcode{USE iom ! I/O manager library} to the list of used modules in 278 \item in \NEMO\ code, add a \forcode{CALL iom_put( 'identifier', array )} where you want to output a 2D or 3D array. 279 \item If necessary, add \forcode{USE iom ! I/O manager library} to the list of used modules in 274 280 the upper part of your module. 275 \item[3.] 276 in the field\_def.xml file, add the definition of your variable using the same identifier you used in the f90 code 281 \item in the field\_def.xml file, add the definition of your variable using the same identifier you used in the f90 code 277 282 (see subsequent sections for a details of the XML syntax and rules). 278 283 For example: 279 280 284 \begin{xmllines} 281 285 <field_definition> 282 286 <field_group id="grid_T" grid_ref="grid_T_3D"> <!-- T grid --> 283 287 ... 284 <field id="identifier" long_name="blabla" ... /> 288 <field id="identifier" long_name="blabla" ... /> 285 289 ... 286 </field_definition> 287 \end{xmllines} 288 290 </field_definition> 291 \end{xmllines} 289 292 Note your definition must be added to the field\_group whose reference grid is consistent with the size of 290 293 the array passed to iomput. … … 293 296 (iom\_set\_domain\_attr and iom\_set\_axis\_attr in \mdl{iom}) or defined in the domain\_def.xml file. 294 297 \eg: 295 296 298 \begin{xmllines} 297 299 <grid id="grid_T_3D" domain_ref="grid_T" axis_ref="deptht"/> 298 300 \end{xmllines} 299 300 Note, if your array is computed within the surface module each \np{nn\_fsbc} time\_step, 301 Note, if your array is computed within the surface module each \np{nn_fsbc}{nn\_fsbc} time\_step, 301 302 add the field definition within the field\_group defined with the id "SBC": 302 303 \xmlcode{<field_group id="SBC" ...>} which has been defined with the correct frequency of operations 303 304 (iom\_set\_field\_attr in \mdl{iom}) 304 \item[4.] 305 add your field in one of the output files defined in iodef.xml 305 \item add your field in one of the output files defined in iodef.xml 306 306 (again see subsequent sections for syntax and rules) 307 308 \begin{xmllines} 309 <file id="file1" .../> 307 \begin{xmllines} 308 <file id="file1" .../> 310 309 ... 311 <field field_ref="identifier" /> 310 <field field_ref="identifier" /> 312 311 ... 313 </file> 314 \end{xmllines} 315 312 </file> 313 \end{xmllines} 316 314 \end{enumerate} 317 315 316 %% ================================================================================================= 318 317 \subsection{XML fundamentals} 319 318 319 %% ================================================================================================= 320 320 \subsubsection{ XML basic rules} 321 321 … … 327 327 See \href{http://www.xmlnews.org/docs/xml-basics.html}{here} for more details. 328 328 329 \subsubsection{Structure of the XML file used in NEMO} 329 %% ================================================================================================= 330 \subsubsection{Structure of the XML file used in \NEMO} 330 331 331 332 The XML file used in XIOS is structured by 7 families of tags: … … 334 335 335 336 \begin{table} 336 \scriptsize337 337 \begin{tabular*}{\textwidth}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} 338 338 \hline … … 366 366 367 367 \begin{table} 368 \scriptsize369 368 \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} 370 369 \hline … … 376 375 \xmlcode{<context id="xios" ... >} \\ 377 376 \hline 378 context nemo & context containing IO information for NEMO (mother grid when using AGRIF) &377 context nemo & context containing IO information for \NEMO\ (mother grid when using AGRIF) & 379 378 \xmlcode{<context id="nemo" ... >} \\ 380 379 \hline 381 context 1\_nemo & context containing IO information for NEMO child grid 1 (when using AGRIF) &380 context 1\_nemo & context containing IO information for \NEMO\ child grid 1 (when using AGRIF) & 382 381 \xmlcode{<context id="1_nemo" ... >} \\ 383 382 \hline 384 context n\_nemo & context containing IO information for NEMO child grid n (when using AGRIF) &383 context n\_nemo & context containing IO information for \NEMO\ child grid n (when using AGRIF) & 385 384 \xmlcode{<context id="n_nemo" ... >} \\ 386 385 \hline … … 391 390 392 391 \begin{table} 393 \scriptsize394 392 \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} 395 393 \hline … … 407 405 \end{table} 408 406 409 \noindent Each context tag related to NEMO (mother or child grids) is divided into 5 parts407 \noindent Each context tag related to \NEMO\ (mother or child grids) is divided into 5 parts 410 408 (that can be defined in any order): 411 409 412 410 \begin{table} 413 \scriptsize414 411 \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} 415 412 \hline … … 436 433 \end{table} 437 434 435 %% ================================================================================================= 438 436 \subsubsection{Nesting XML files} 439 437 … … 441 439 The inclusion of XML files into the main XML file can be done through the attribute src: 442 440 \xmlline|<context src="./nemo_def.xml" />| 443 444 \noindent In NEMO, by default, the field and domain definition is done in 2 separate files: 445 \path{NEMOGCM/CONFIG/SHARED/field_def.xml} and \path{NEMOGCM/CONFIG/SHARED/domain_def.xml} that 441 442 \noindent In \NEMO, by default, the field definition is done in 3 separate files ( 443 \path{cfgs/SHARED/field_def_nemo-oce.xml}, 444 \path{cfgs/SHARED/field_def_nemo-pisces.xml} and 445 \path{cfgs/SHARED/field_def_nemo-ice.xml} ) and the domain definition is done in another file ( \path{cfgs/SHARED/domain_def_nemo.xml} ) 446 that 446 447 are included in the main iodef.xml file through the following commands: 447 448 \begin{xmllines} 448 < field_definition src="./field_def.xml"/>449 <domain_definition src="./domain_def.xml" /> 450 \end{xmllines} 451 449 <context id="nemo" src="./context_nemo.xml"/> 450 \end{xmllines} 451 452 %% ================================================================================================= 452 453 \subsubsection{Use of inheritance} 453 454 … … 462 463 \begin{xmllines} 463 464 <field_definition operation="average" > 464 <field id="sst" /> <!-- averaged sst --> 465 <field id="sss" operation="instant"/> <!-- instantaneous sss --> 466 </field_definition> 465 <field id="sst" /> <!-- averaged sst --> 466 <field id="sss" operation="instant"/> <!-- instantaneous sss --> 467 </field_definition> 467 468 \end{xmllines} 468 469 … … 481 482 </field_definition> 482 483 <file_definition> 483 <file id="myfile" output_freq="1d" /> 484 <file id="myfile" output_freq="1d" /> 484 485 <field field_ref="sst" /> <!-- default def --> 485 486 <field field_ref="sss" long_name="my description" /> <!-- overwrite --> 486 487 </file> 487 </file_definition> 488 </file_definition> 488 489 \end{xmllines} 489 490 490 491 Inherit (and overwrite, if needed) the attributes of a tag you are refering to. 491 492 493 %% ================================================================================================= 492 494 \subsubsection{Use of groups} 493 495 … … 508 510 509 511 Secondly, the group can be used to replace a list of elements. 510 Several examples of groups of fields are proposed at the end of the file \path{CONFIG/SHARED/field_def.xml}. 512 Several examples of groups of fields are proposed at the end of the XML field files ( 513 \path{cfgs/SHARED/field_def_nemo-oce.xml}, 514 \path{cfgs/SHARED/field_def_nemo-pisces.xml} and 515 \path{cfgs/SHARED/field_def_nemo-ice.xml} ) . 511 516 For example, a short list of the usual variables related to the U grid: 512 517 … … 514 519 <field_group id="groupU" > 515 520 <field field_ref="uoce" /> 516 <field field_ref="s uoce" />521 <field field_ref="ssu" /> 517 522 <field field_ref="utau" /> 518 523 </field_group> … … 525 530 <field_group group_ref="groupU" /> 526 531 <field field_ref="uocetr_eff" /> <!-- add another field --> 527 </file> 528 \end{xmllines} 529 532 </file> 533 \end{xmllines} 534 535 %% ================================================================================================= 530 536 \subsection{Detailed functionalities} 531 537 … … 533 539 the new functionalities offered by the XML interface of XIOS. 534 540 541 %% ================================================================================================= 535 542 \subsubsection{Define horizontal subdomains} 536 543 537 544 Horizontal subdomains are defined through the attributs zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj of 538 545 the tag family domain. 539 It must therefore be done in the domain part of the XML file. 540 For example, in \path{ CONFIG/SHARED/domain_def.xml}, we provide the following example of a definition of546 It must therefore be done in the domain part of the XML file. 547 For example, in \path{cfgs/SHARED/domain_def.xml}, we provide the following example of a definition of 541 548 a 5 by 5 box with the bottom left corner at point (10,10). 542 549 543 550 \begin{xmllines} 544 <domain _group id="grid_T">545 < domain id="myzoom" zoom_ibegin="10" zoom_jbegin="10" zoom_ni="5" zoom_nj="5" />551 <domain id="myzoomT" domain_ref="grid_T"> 552 <zoom_domain ibegin="10" jbegin="10" ni="5" nj="5" /> 546 553 \end{xmllines} 547 554 … … 551 558 \begin{xmllines} 552 559 <file id="myfile_vzoom" output_freq="1d" > 553 <field field_ref="toce" domain_ref="myzoom "/>560 <field field_ref="toce" domain_ref="myzoomT"/> 554 561 </file> 555 562 \end{xmllines} 556 563 557 Moorings are seen as an extrem case corresponding to a 1 by 1 subdomain. 564 Moorings are seen as an extrem case corresponding to a 1 by 1 subdomain. 558 565 The Equatorial section, the TAO, RAMA and PIRATA moorings are already registered in the code and 559 566 can therefore be outputted without taking care of their (i,j) position in the grid. … … 568 575 \end{xmllines} 569 576 570 Note that if the domain decomposition used in XIOS cuts the subdomain in several parts and if 571 you use the ''multiple\_file'' type for your output files, 572 you will endup with several files you will need to rebuild using unprovided tools (like ncpdq and ncrcat, 577 Note that if the domain decomposition used in XIOS cuts the subdomain in several parts and if 578 you use the ''multiple\_file'' type for your output files, 579 you will endup with several files you will need to rebuild using unprovided tools (like ncpdq and ncrcat, 573 580 \href{http://nco.sourceforge.net/nco.html#Concatenation}{see nco manual}). 574 581 We are therefore advising to use the ''one\_file'' type in this case. 575 582 583 %% ================================================================================================= 576 584 \subsubsection{Define vertical zooms} 577 585 578 Vertical zooms are defined through the attributs zoom\_begin and zoom\_ endof the tag family axis.586 Vertical zooms are defined through the attributs zoom\_begin and zoom\_n of the tag family axis. 579 587 It must therefore be done in the axis part of the XML file. 580 For example, in \path{NEMOGCM/CONFIG/ORCA2_LIM/iodef_demo.xml}, we provide the following example: 581 582 \begin{xmllines} 583 <axis_group id="deptht" long_name="Vertical T levels" unit="m" positive="down" > 584 <axis id="deptht" /> 585 <axis id="deptht_myzoom" zoom_begin="1" zoom_end="10" /> 588 For example, in \path{cfgs/ORCA2_ICE_PISCES/EXPREF/iodef_demo.xml}, we provide the following example: 589 590 \begin{xmllines} 591 <axis_definition> 592 <axis id="deptht" long_name="Vertical T levels" unit="m" positive="down" /> 593 <axis id="deptht_zoom" azix_ref="deptht" > 594 <zoom_axis zoom_begin="1" zoom_n="10" /> 595 </axis> 586 596 \end{xmllines} 587 597 … … 595 605 \end{xmllines} 596 606 607 %% ================================================================================================= 597 608 \subsubsection{Control of the output file names} 598 609 … … 601 612 602 613 \begin{xmllines} 603 <file_group id="1d" output_freq="1d" name="myfile_1d" > 614 <file_group id="1d" output_freq="1d" name="myfile_1d" > 604 615 <file id="myfileA" name_suffix="_AAA" > <!-- will create file "myfile_1d_AAA" --> 605 616 ... … … 620 631 621 632 \begin{table} 622 \scriptsize623 633 \begin{tabularx}{\textwidth}{|lX|} 624 634 \hline … … 656 666 \end{table} 657 667 658 \noindent For example, 668 \noindent For example, 659 669 \xmlline|<file id="myfile_hzoom" name="myfile_@expname@_@startdate@_freq@freq@" output_freq="1d" >| 660 670 … … 668 678 \noindent will give the following file name radical: \ifile{myfile\_ORCA2\_19891231\_freq1d} 669 679 670 \subsubsection{Other controls of the XML attributes from NEMO} 671 672 The values of some attributes are defined by subroutine calls within NEMO 680 %% ================================================================================================= 681 \subsubsection{Other controls of the XML attributes from \NEMO} 682 683 The values of some attributes are defined by subroutine calls within \NEMO 673 684 (calls to iom\_set\_domain\_attr, iom\_set\_axis\_attr and iom\_set\_field\_attr in \mdl{iom}). 674 685 Any definition given in the XML file will be overwritten. … … 681 692 682 693 \begin{table} 683 \scriptsize 684 \begin{tabularx}{\textwidth}{|X|c|c|c|} 694 \begin{tabular}{|l|c|c|} 685 695 \hline 686 696 tag ids affected by automatic definition of some of their attributes & 687 697 name attribute & 688 attribute value \\698 attribute value \\ 689 699 \hline 690 700 \hline 691 701 field\_definition & 692 702 freq\_op & 693 \np{rn \_rdt}\\703 \np{rn_rdt}{rn\_rdt} \\ 694 704 \hline 695 705 SBC & 696 706 freq\_op & 697 \np{rn \_rdt} $\times$ \np{nn\_fsbc}\\707 \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_fsbc}{nn\_fsbc} \\ 698 708 \hline 699 709 ptrc\_T & 700 710 freq\_op & 701 \np{rn \_rdt} $\times$ \np{nn\_dttrc}\\711 \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_dttrc}{nn\_dttrc} \\ 702 712 \hline 703 713 diad\_T & 704 714 freq\_op & 705 \np{rn \_rdt} $\times$ \np{nn\_dttrc}\\715 \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_dttrc}{nn\_dttrc} \\ 706 716 \hline 707 717 EqT, EqU, EqW & 708 718 jbegin, ni, & 709 according to the grid \\710 &719 according to the grid \\ 720 & 711 721 name\_suffix & 712 \\722 \\ 713 723 \hline 714 724 TAO, RAMA and PIRATA moorings & 715 725 zoom\_ibegin, zoom\_jbegin, & 716 according to the grid \\717 &726 according to the grid \\ 727 & 718 728 name\_suffix & 719 \\720 \hline 721 \end{tabular x}729 \\ 730 \hline 731 \end{tabular} 722 732 \end{table} 723 733 734 %% ================================================================================================= 724 735 \subsubsection{Advanced use of XIOS functionalities} 725 736 737 %% ================================================================================================= 726 738 \subsection{XML reference tables} 727 \label{subsec: IOM_xmlref}739 \label{subsec:DIA_IOM_xmlref} 728 740 729 741 \begin{enumerate} 730 \item 731 Simple computation: directly define the computation when refering to the variable in the file definition. 742 \item Simple computation: directly define the computation when refering to the variable in the file definition. 732 743 733 744 \begin{xmllines} … … 737 748 \end{xmllines} 738 749 739 \item 740 Simple computation: define a new variable and use it in the file definition. 750 \item Simple computation: define a new variable and use it in the file definition. 741 751 742 752 in field\_definition: … … 755 765 sst2 won't be evaluated. 756 766 757 \item 758 Change of variable precision: 767 \item Change of variable precision: 759 768 760 769 \begin{xmllines} … … 765 774 \end{xmllines} 766 775 767 Note that, then the code is crashing, writting real4 variables forces a numerical conve ction from776 Note that, then the code is crashing, writting real4 variables forces a numerical conversion from 768 777 real8 to real4 which will create an internal error in NetCDF and will avoid the creation of the output files. 769 778 Forcing double precision outputs with prec="8" (for example in the field\_definition) will avoid this problem. 770 779 771 \item 772 add user defined attributes: 773 774 \begin{xmllines} 775 <file_group id="1d" output_freq="1d" output_level="10" enabled=".true."> <!-- 1d files --> 780 \item add user defined attributes: 781 782 \begin{xmllines} 783 <file_group id="1d" output_freq="1d" output_level="10" enabled=".true."> <!-- 1d files --> 776 784 <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" > 777 785 <field field_ref="sst" name="tos" > … … 782 790 <variable id="my_global_attribute" type="string" > blabla_global </variable> 783 791 </file> 784 </file_group> 785 \end{xmllines} 786 787 \item 788 use of the ``@'' function: example 1, weighted temporal average 792 </file_group> 793 \end{xmllines} 794 795 \item use of the ``@'' function: example 1, weighted temporal average 789 796 790 797 - define a new variable in field\_definition … … 797 804 798 805 \begin{xmllines} 799 <file_group id="5d" output_freq="5d" output_level="10" enabled=".true." > <!-- 5d files --> 806 <file_group id="5d" output_freq="5d" output_level="10" enabled=".true." > <!-- 5d files --> 800 807 <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" > 801 808 <field field_ref="toce" operation="instant" freq_op="5d" > @toce_e3t / @e3t </field> 802 809 </file> 803 </file_group> 810 </file_group> 804 811 \end{xmllines} 805 812 … … 814 821 Note that in this case, freq\_op must be equal to the file output\_freq. 815 822 816 \item 817 use of the ``@'' function: example 2, monthly SSH standard deviation 823 \item use of the ``@'' function: example 2, monthly SSH standard deviation 818 824 819 825 - define a new variable in field\_definition … … 826 832 827 833 \begin{xmllines} 828 <file_group id="1m" output_freq="1m" output_level="10" enabled=".true." > <!-- 1m files --> 834 <file_group id="1m" output_freq="1m" output_level="10" enabled=".true." > <!-- 1m files --> 829 835 <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" > 830 <field field_ref="ssh" name="sshstd" long_name="sea_surface_temperature_standard_deviation" 836 <field field_ref="ssh" name="sshstd" long_name="sea_surface_temperature_standard_deviation" 831 837 operation="instant" freq_op="1m" > 832 838 sqrt( @ssh2 - @ssh * @ssh ) 833 839 </field> 834 840 </file> 835 </file_group> 841 </file_group> 836 842 \end{xmllines} 837 843 … … 840 846 here we use the default, average. 841 847 So, in the above case, @ssh2 will do the monthly mean of ssh*ssh. 842 Operation="instant" refers to the temporal operation to be performed on the field ''sqrt( @ssh2 - @ssh * @ssh )'': 848 Operation="instant" refers to the temporal operation to be performed on the field ''sqrt( @ssh2 - @ssh * @ssh )'': 843 849 here the temporal average is alreday done by the ``@'' function so we just use instant. 844 850 field\_ref="ssh" means that attributes not explicitely defined, are inherited from ssh field. 845 851 Note that in this case, freq\_op must be equal to the file output\_freq. 846 852 847 \item 848 use of the ``@'' function: example 3, monthly average of SST diurnal cycle 853 \item use of the ``@'' function: example 3, monthly average of SST diurnal cycle 849 854 850 855 - define 2 new variables in field\_definition … … 858 863 859 864 \begin{xmllines} 860 <file_group id="1m" output_freq="1m" output_level="10" enabled=".true." > <!-- 1m files --> 865 <file_group id="1m" output_freq="1m" output_level="10" enabled=".true." > <!-- 1m files --> 861 866 <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" > 862 867 <field field_ref="sst" name="sstdcy" long_name="amplitude of sst diurnal cycle" operation="average" freq_op="1d" > … … 864 869 </field> 865 870 </file> 866 </file_group> 871 </file_group> 867 872 \end{xmllines} 868 873 … … 877 882 field\_ref="sst" means that attributes not explicitely defined, are inherited from sst field. 878 883 884 %% ================================================================================================= 879 885 \subsubsection{Tag list per family} 880 886 881 887 \begin{table} 882 \scriptsize883 888 \begin{tabularx}{\textwidth}{|l|X|X|l|X|} 884 889 \hline … … 903 908 \hline 904 909 \end{tabularx} 905 \caption{ Context tags}910 \caption{XIOS: context tags} 906 911 \end{table} 907 912 908 913 \begin{table} 909 \scriptsize910 914 \begin{tabularx}{\textwidth}{|l|X|X|X|l|} 911 915 \hline … … 938 942 \hline 939 943 \end{tabularx} 940 \caption{ Field tags ("\tt{field\_*}")}944 \caption{XIOS: field tags ("\texttt{field\_*}")} 941 945 \end{table} 942 946 943 947 \begin{table} 944 \scriptsize945 948 \begin{tabularx}{\textwidth}{|l|X|X|X|l|} 946 949 \hline … … 974 977 \hline 975 978 \end{tabularx} 976 \caption{ File tags ("\tt{file\_*}")}979 \caption{XIOS: file tags ("\texttt{file\_*}")} 977 980 \end{table} 978 981 979 982 \begin{table} 980 \scriptsize981 983 \begin{tabularx}{\textwidth}{|l|X|X|X|X|} 982 984 \hline … … 1007 1009 \hline 1008 1010 \end{tabularx} 1009 \caption{ Axis tags ("\tt{axis\_*}")}1011 \caption{XIOS: axis tags ("\texttt{axis\_*}")} 1010 1012 \end{table} 1011 1013 1012 1014 \begin{table} 1013 \scriptsize1014 1015 \begin{tabularx}{\textwidth}{|l|X|X|X|X|} 1015 1016 \hline … … 1040 1041 \hline 1041 1042 \end{tabularx} 1042 \caption{ Domain tags ("\tt{domain\_*)}"}1043 \caption{XIOS: domain tags ("\texttt{domain\_*)}"} 1043 1044 \end{table} 1044 1045 1045 1046 \begin{table} 1046 \scriptsize1047 1047 \begin{tabularx}{\textwidth}{|l|X|X|X|X|} 1048 1048 \hline … … 1073 1073 \hline 1074 1074 \end{tabularx} 1075 \caption{ Grid tags ("\tt{grid\_*}")}1075 \caption{XIOS: grid tags ("\texttt{grid\_*}")} 1076 1076 \end{table} 1077 1077 1078 %% ================================================================================================= 1078 1079 \subsubsection{Attributes list per family} 1079 1080 1080 1081 \begin{table} 1081 \scriptsize1082 1082 \begin{tabularx}{\textwidth}{|l|X|l|l|} 1083 1083 \hline … … 1114 1114 \hline 1115 1115 \end{tabularx} 1116 \caption{ Reference attributes ("\tt{*\_ref}")}1116 \caption{XIOS: reference attributes ("\texttt{*\_ref}")} 1117 1117 \end{table} 1118 1118 1119 1119 \begin{table} 1120 \scriptsize1121 1120 \begin{tabularx}{\textwidth}{|l|X|l|l|} 1122 1121 \hline … … 1150 1149 \hline 1151 1150 \end{tabularx} 1152 \caption{ Domain attributes ("\tt{zoom\_*}")}1151 \caption{XIOS: domain attributes ("\texttt{zoom\_*}")} 1153 1152 \end{table} 1154 1153 1155 1154 \begin{table} 1156 \scriptsize1157 1155 \begin{tabularx}{\textwidth}{|l|X|l|l|} 1158 1156 \hline … … 1205 1203 \hline 1206 1204 \end{tabularx} 1207 \caption{ File attributes}1205 \caption{XIOS: file attributes} 1208 1206 \end{table} 1209 1207 1210 1208 \begin{table} 1211 \scriptsize1212 1209 \begin{tabularx}{\textwidth}{|l|X|l|l|} 1213 1210 \hline … … 1254 1251 \hline 1255 1252 \end{tabularx} 1256 \caption{ Field attributes}1253 \caption{XIOS: field attributes} 1257 1254 \end{table} 1258 1255 1259 1256 \begin{table} 1260 \scriptsize1261 1257 \begin{tabularx}{\textwidth}{|l|X|X|X|} 1262 1258 \hline … … 1313 1309 \hline 1314 1310 \end{tabularx} 1315 \caption{ Miscellaneous attributes}1311 \caption{XIOS: miscellaneous attributes} 1316 1312 \end{table} 1317 1313 1314 %% ================================================================================================= 1318 1315 \subsection{CF metadata standard compliance} 1319 1316 1320 Output from the XIOS -1.0 IO server is compliant with1317 Output from the XIOS IO server is compliant with 1321 1318 \href{http://cfconventions.org/Data/cf-conventions/cf-conventions-1.5/build/cf-conventions.html}{version 1.5} of 1322 the CF metadata standard. 1319 the CF metadata standard. 1323 1320 Therefore while a user may wish to add their own metadata to the output files (as demonstrated in example 4 of 1324 section \autoref{subsec: IOM_xmlref}) the metadata should, for the most part, comply with the CF-1.5 standard.1321 section \autoref{subsec:DIA_IOM_xmlref}) the metadata should, for the most part, comply with the CF-1.5 standard. 1325 1322 1326 1323 Some metadata that may significantly increase the file size (horizontal cell areas and vertices) are controlled by 1327 the namelist parameter \np{ln \_cfmeta} in the \ngn{namrun} namelist.1324 the namelist parameter \np{ln_cfmeta}{ln\_cfmeta} in the \nam{run}{run} namelist. 1328 1325 This must be set to true if these metadata are to be included in the output files. 1329 1326 1330 1331 % ================================================================ 1332 % NetCDF4 support 1333 % ================================================================ 1334 \section{NetCDF4 support (\protect\key{netcdf4})} 1327 %% ================================================================================================= 1328 \section[NetCDF4 support (\texttt{\textbf{key\_netcdf4}})]{NetCDF4 support (\protect\key{netcdf4})} 1335 1329 \label{sec:DIA_nc4} 1336 1330 … … 1340 1334 Chunking and compression can lead to significant reductions in file sizes for a small runtime overhead. 1341 1335 For a fuller discussion on chunking and other performance issues the reader is referred to 1342 the NetCDF4 documentation found \href{http ://www.unidata.ucar.edu/software/netcdf/docs/netcdf.html#Chunking}{here}.1336 the NetCDF4 documentation found \href{https://www.unidata.ucar.edu/software/netcdf/docs/netcdf_perf_chunking.html}{here}. 1343 1337 1344 1338 The new features are only available when the code has been linked with a NetCDF4 library … … 1346 1340 Datasets created with chunking and compression are not backwards compatible with NetCDF3 "classic" format but 1347 1341 most analysis codes can be relinked simply with the new libraries and will then read both NetCDF3 and NetCDF4 files. 1348 NEMO executables linked with NetCDF4 libraries can be made to produce NetCDF3 files by 1349 setting the \np{ln\_nc4zip} logical to false in the \textit{namnc4} namelist: 1350 1351 %------------------------------------------namnc4---------------------------------------------------- 1352 1353 \nlst{namnc4} 1354 %------------------------------------------------------------------------------------------------------------- 1342 \NEMO\ executables linked with NetCDF4 libraries can be made to produce NetCDF3 files by 1343 setting the \np{ln_nc4zip}{ln\_nc4zip} logical to false in the \nam{nc4}{nc4} namelist: 1344 1345 \begin{listing} 1346 \nlst{namnc4} 1347 \caption{\forcode{&namnc4}} 1348 \label{lst:namnc4} 1349 \end{listing} 1355 1350 1356 1351 If \key{netcdf4} has not been defined, these namelist parameters are not read. 1357 In this case, \np{ln \_nc4zip} is set false and dummy routines for a few NetCDF4-specific functions are defined.1352 In this case, \np{ln_nc4zip}{ln\_nc4zip} is set false and dummy routines for a few NetCDF4-specific functions are defined. 1358 1353 These functions will not be used but need to be included so that compilation is possible with NetCDF3 libraries. 1359 1354 … … 1389 1384 \end{forlines} 1390 1385 1391 \noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\t t 46x38x1} respectively in1392 the mono-processor case (\ie global domain of {\small\tt 182x149x31}).1393 An illustration of the potential space savings that NetCDF4 chunking and compression provides is given in 1394 table \autoref{tab: NC4} which compares the results of two short runs of the ORCA2\_LIM reference configuration with1386 \noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\texttt 46x38x1} respectively in 1387 the mono-processor case (\ie\ global domain of {\small\texttt 182x149x31}). 1388 An illustration of the potential space savings that NetCDF4 chunking and compression provides is given in 1389 table \autoref{tab:DIA_NC4} which compares the results of two short runs of the ORCA2\_LIM reference configuration with 1395 1390 a 4x2 mpi partitioning. 1396 1391 Note the variation in the compression ratio achieved which reflects chiefly the dry to wet volume ratio of 1397 1392 each processing region. 1398 1393 1399 %------------------------------------------TABLE----------------------------------------------------1400 1394 \begin{table} 1401 \scriptsize1402 1395 \centering 1403 1396 \begin{tabular}{lrrr} … … 1431 1424 ORCA2\_2d\_grid\_W\_0007.nc & 4416 & 1368 & 70\% \\ 1432 1425 \end{tabular} 1433 \caption{ 1434 \protect\label{tab:NC4} 1435 Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression 1436 } 1426 \caption{Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression} 1427 \label{tab:DIA_NC4} 1437 1428 \end{table} 1438 %----------------------------------------------------------------------------------------------------1439 1429 1440 1430 When \key{iomput} is activated with \key{netcdf4} chunking and compression parameters for fields produced via 1441 \ np{iom\_put} calls are set via an equivalent and identically named namelist to \textit{namnc4} in1442 \ np{xmlio\_server.def}.1443 Typically this namelist serves the mean files whilst the \n gn{ namnc4} in the main namelist file continues to1431 \rou{iom\_put} calls are set via an equivalent and identically named namelist to \nam{nc4}{nc4} in 1432 \textit{xmlio\_server.def}. 1433 Typically this namelist serves the mean files whilst the \nam{nc4}{nc4} in the main namelist file continues to 1444 1434 serve the restart files. 1445 1435 This duplication is unfortunate but appropriate since, if using io\_servers, the domain sizes of 1446 1436 the individual files produced by the io\_server processes may be different to those produced by 1447 1437 the invidual processing regions and different chunking choices may be desired. 1448 1449 % ------------------------------------------------------------------------------------------------------------- 1450 % Tracer/Dynamics Trends 1451 % ------------------------------------------------------------------------------------------------------------- 1452 \section{Tracer/Dynamics trends (\protect\ngn{namtrd})} 1438 1439 %% ================================================================================================= 1440 \section[Tracer/Dynamics trends (\forcode{&namtrd})]{Tracer/Dynamics trends (\protect\nam{trd}{trd})} 1453 1441 \label{sec:DIA_trd} 1454 1442 1455 %------------------------------------------namtrd---------------------------------------------------- 1456 1457 \nlst{namtrd} 1458 %------------------------------------------------------------------------------------------------------------- 1443 \begin{listing} 1444 \nlst{namtrd} 1445 \caption{\forcode{&namtrd}} 1446 \label{lst:namtrd} 1447 \end{listing} 1459 1448 1460 1449 Each trend of the dynamics and/or temperature and salinity time evolution equations can be send to 1461 1450 \mdl{trddyn} and/or \mdl{trdtra} modules (see TRD directory) just after their computation 1462 (\ie at the end of each $dyn\cdots.F90$ and/or $tra\cdots.F90$routines).1463 This capability is controlled by options offered in \n gn{namtrd} namelist.1464 Note that the output are done with xIOS, and therefore the \key{IOM} is required.1465 1466 What is done depends on the \n gn{namtrd} logical set to \forcode{.true.}:1451 (\ie\ at the end of each \textit{dyn....F90} and/or \textit{tra....F90} routines). 1452 This capability is controlled by options offered in \nam{trd}{trd} namelist. 1453 Note that the output are done with XIOS, and therefore the \key{iomput} is required. 1454 1455 What is done depends on the \nam{trd}{trd} logical set to \forcode{.true.}: 1467 1456 1468 1457 \begin{description} 1469 \item[\np{ln\_glo\_trd}]: 1470 at each \np{nn\_trd} time-step a check of the basin averaged properties of 1458 \item [{\np{ln_glo_trd}{ln\_glo\_trd}}]: at each \np{nn_trd}{nn\_trd} time-step a check of the basin averaged properties of 1471 1459 the momentum and tracer equations is performed. 1472 1460 This also includes a check of $T^2$, $S^2$, $\tfrac{1}{2} (u^2+v2)$, 1473 1461 and potential energy time evolution equations properties; 1474 \item[\np{ln\_dyn\_trd}]: 1475 each 3D trend of the evolution of the two momentum components is output; 1476 \item[\np{ln\_dyn\_mxl}]: 1477 each 3D trend of the evolution of the two momentum components averaged over the mixed layer is output; 1478 \item[\np{ln\_vor\_trd}]: 1479 a vertical summation of the moment tendencies is performed, 1462 \item [{\np{ln_dyn_trd}{ln\_dyn\_trd}}]: each 3D trend of the evolution of the two momentum components is output; 1463 \item [{\np{ln_dyn_mxl}{ln\_dyn\_mxl}}]: each 3D trend of the evolution of the two momentum components averaged over the mixed layer is output; 1464 \item [{\np{ln_vor_trd}{ln\_vor\_trd}}]: a vertical summation of the moment tendencies is performed, 1480 1465 then the curl is computed to obtain the barotropic vorticity tendencies which are output; 1481 \item[\np{ln\_KE\_trd}] : 1482 each 3D trend of the Kinetic Energy equation is output; 1483 \item[\np{ln\_tra\_trd}]: 1484 each 3D trend of the evolution of temperature and salinity is output; 1485 \item[\np{ln\_tra\_mxl}]: 1486 each 2D trend of the evolution of temperature and salinity averaged over the mixed layer is output; 1466 \item [{\np{ln_KE_trd}{ln\_KE\_trd}}] : each 3D trend of the Kinetic Energy equation is output; 1467 \item [{\np{ln_tra_trd}{ln\_tra\_trd}}]: each 3D trend of the evolution of temperature and salinity is output; 1468 \item [{\np{ln_tra_mxl}{ln\_tra\_mxl}}]: each 2D trend of the evolution of temperature and salinity averaged over the mixed layer is output; 1487 1469 \end{description} 1488 1470 1489 Note that the mixed layer tendency diagnostic can also be used on biogeochemical models via 1490 the \key{trdtrc} and \key{trdm ld\_trc} CPP keys.1471 Note that the mixed layer tendency diagnostic can also be used on biogeochemical models via 1472 the \key{trdtrc} and \key{trdmxl\_trc} CPP keys. 1491 1473 1492 1474 \textbf{Note that} in the current version (v3.6), many changes has been introduced but not fully tested. 1493 In particular, options associated with \np{ln \_dyn\_mxl}, \np{ln\_vor\_trd}, and \np{ln\_tra\_mxl} are not working,1494 and none of the options have been tested with variable volume (\ie \key{vvl} defined).1495 1496 % -------------------------------------------------------------------------------------------------------------1497 % On-line Floats trajectories 1498 % ------------------------------------------------------------------------------------------------------------- 1499 \section{FLO: On-Line Floats trajectories (\protect\key{floats})} 1500 \ label{sec:FLO}1501 %--------------------------------------------namflo------------------------------------------------------- 1502 1503 \nlst{namflo} 1504 %-------------------------------------------------------------------------------------------------------------- 1475 In particular, options associated with \np{ln_dyn_mxl}{ln\_dyn\_mxl}, \np{ln_vor_trd}{ln\_vor\_trd}, and \np{ln_tra_mxl}{ln\_tra\_mxl} are not working, 1476 and none of the options have been tested with variable volume (\ie\ \np[=.true.]{ln_linssh}{ln\_linssh}). 1477 1478 %% ================================================================================================= 1479 \section[FLO: On-Line Floats trajectories (\texttt{\textbf{key\_floats}})]{FLO: On-Line Floats trajectories (\protect\key{floats})} 1480 \label{sec:DIA_FLO} 1481 1482 \begin{listing} 1483 \nlst{namflo} 1484 \caption{\forcode{&namflo}} 1485 \label{lst:namflo} 1486 \end{listing} 1505 1487 1506 1488 The on-line computation of floats advected either by the three dimensional velocity field or constraint to 1507 1489 remain at a given depth ($w = 0$ in the computation) have been introduced in the system during the CLIPPER project. 1508 Options are defined by \n gn{namflo} namelisvariables.1509 The algorithm used is based either on the work of \cite{ Blanke_Raynaud_JPO97} (default option),1510 or on a $4^th$ Runge-Hutta algorithm (\np {ln\_flork4}\forcode{ = .true.}).1511 Note that the \cite{ Blanke_Raynaud_JPO97} algorithm have the advantage of providing trajectories which1490 Options are defined by \nam{flo}{flo} namelist variables. 1491 The algorithm used is based either on the work of \cite{blanke.raynaud_JPO97} (default option), 1492 or on a $4^th$ Runge-Hutta algorithm (\np[=.true.]{ln_flork4}{ln\_flork4}). 1493 Note that the \cite{blanke.raynaud_JPO97} algorithm have the advantage of providing trajectories which 1512 1494 are consistent with the numeric of the code, so that the trajectories never intercept the bathymetry. 1513 1495 1496 %% ================================================================================================= 1514 1497 \subsubsection{Input data: initial coordinates} 1515 1498 1516 1499 Initial coordinates can be given with Ariane Tools convention 1517 (IJK coordinates, (\np {ln\_ariane}\forcode{ = .true.}) ) or with longitude and latitude.1518 1519 In case of Ariane convention, input filename is \ np{init\_float\_ariane}.1500 (IJK coordinates, (\np[=.true.]{ln_ariane}{ln\_ariane}) ) or with longitude and latitude. 1501 1502 In case of Ariane convention, input filename is \textit{init\_float\_ariane}. 1520 1503 Its format is: \\ 1521 { \scriptsize \texttt{I J K nisobfl itrashitrash}}1504 { \texttt{I J K nisobfl itrash}} 1522 1505 1523 1506 \noindent with: … … 1525 1508 - I,J,K : indexes of initial position 1526 1509 1527 - nisobfl: 0 for an isobar float, 1 for a float following the w velocity 1510 - nisobfl: 0 for an isobar float, 1 for a float following the w velocity 1528 1511 1529 1512 - itrash : set to zero; it is a dummy variable to respect Ariane Tools convention … … 1531 1514 \noindent Example: \\ 1532 1515 \noindent 1533 { \scriptsize1516 { 1534 1517 \texttt{ 1535 1518 100.00000 90.00000 -1.50000 1.00000 0.00000 \\ … … 1542 1525 In the other case (longitude and latitude), input filename is init\_float. 1543 1526 Its format is: \\ 1544 { \scriptsize\texttt{Long Lat depth nisobfl ngrpfl itrash}}1527 { \texttt{Long Lat depth nisobfl ngrpfl itrash}} 1545 1528 1546 1529 \noindent with: … … 1556 1539 \noindent Example: \\ 1557 1540 \noindent 1558 { \scriptsize1541 { 1559 1542 \texttt{ 1560 1543 20.0 0.0 0.0 0 1 1 \\ … … 1565 1548 } \\ 1566 1549 1567 \np{jpnfl} is the total number of floats during the run. 1568 When initial positions are read in a restart file (\np{ln\_rstflo}\forcode{ = .true.} ), 1569 \np{jpnflnewflo} can be added in the initialization file. 1570 1550 \np{jpnfl}{jpnfl} is the total number of floats during the run. 1551 When initial positions are read in a restart file (\np[=.true.]{ln_rstflo}{ln\_rstflo} ), 1552 \np{jpnflnewflo}{jpnflnewflo} can be added in the initialization file. 1553 1554 %% ================================================================================================= 1571 1555 \subsubsection{Output data} 1572 1556 1573 \np{nn \_writefl} is the frequency of writing in float output file and \np{nn\_stockfl} is the frequency of1557 \np{nn_writefl}{nn\_writefl} is the frequency of writing in float output file and \np{nn_stockfl}{nn\_stockfl} is the frequency of 1574 1558 creation of the float restart file. 1575 1559 1576 Output data can be written in ascii files (\np {ln\_flo\_ascii}\forcode{ = .true.}).1560 Output data can be written in ascii files (\np[=.true.]{ln_flo_ascii}{ln\_flo\_ascii}). 1577 1561 In that case, output filename is trajec\_float. 1578 1562 1579 Another possiblity of writing format is Netcdf (\np{ln\_flo\_ascii}\forcode{ = .false.}). 1580 There are 2 possibilities: 1581 1582 - if (\key{iomput}) is used, outputs are selected in iodef.xml. 1563 Another possiblity of writing format is Netcdf (\np[=.false.]{ln_flo_ascii}{ln\_flo\_ascii}) with 1564 \key{iomput} and outputs selected in iodef.xml. 1583 1565 Here it is an example of specification to put in files description section: 1584 1566 … … 1597 1579 \end{xmllines} 1598 1580 1599 - if (\key{iomput}) is not used, a file called \ifile{trajec\_float} will be created by IOIPSL library. 1600 1601 See also \href{http://stockage.univ-brest.fr/~grima/Ariane/}{here} the web site describing the off-line use of 1602 this marvellous diagnostic tool. 1603 1604 % ------------------------------------------------------------------------------------------------------------- 1605 % Harmonic analysis of tidal constituents 1606 % ------------------------------------------------------------------------------------------------------------- 1607 \section{Harmonic analysis of tidal constituents (\protect\key{diaharm}) } 1581 %% ================================================================================================= 1582 \section[Harmonic analysis of tidal constituents (\texttt{\textbf{key\_diaharm}})]{Harmonic analysis of tidal constituents (\protect\key{diaharm})} 1608 1583 \label{sec:DIA_diag_harm} 1609 1584 1610 %------------------------------------------namdia_harm---------------------------------------------------- 1611 % 1612 \nlst{nam_diaharm} 1613 %---------------------------------------------------------------------------------------------------------- 1585 \begin{listing} 1586 \nlst{nam_diaharm} 1587 \caption{\forcode{&nam_diaharm}} 1588 \label{lst:nam_diaharm} 1589 \end{listing} 1614 1590 1615 1591 A module is available to compute the amplitude and phase of tidal waves. 1616 1592 This on-line Harmonic analysis is actived with \key{diaharm}. 1617 1593 1618 Some parameters are available in namelist \n gn{namdia\_harm}:1619 1620 - \np{nit000 \_han} is the first time step used for harmonic analysis1621 1622 - \np{nitend \_han} is the last time step used for harmonic analysis1623 1624 - \np{nstep \_han} is the time step frequency for harmonic analysis1625 1626 - \np{nb\_ana} is the number of harmonics to analyse1627 1628 - \np{tname} is an array with names of tidal constituents to analyse1629 1630 \np{nit000 \_han} and \np{nitend\_han} must be between \np{nit000} and \np{nitend} of the simulation.1594 Some parameters are available in namelist \nam{_diaharm}{\_diaharm}: 1595 1596 - \np{nit000_han}{nit000\_han} is the first time step used for harmonic analysis 1597 1598 - \np{nitend_han}{nitend\_han} is the last time step used for harmonic analysis 1599 1600 - \np{nstep_han}{nstep\_han} is the time step frequency for harmonic analysis 1601 1602 % - \np{nb_ana}{nb\_ana} is the number of harmonics to analyse 1603 1604 - \np{tname}{tname} is an array with names of tidal constituents to analyse 1605 1606 \np{nit000_han}{nit000\_han} and \np{nitend_han}{nitend\_han} must be between \np{nit000}{nit000} and \np{nitend}{nitend} of the simulation. 1631 1607 The restart capability is not implemented. 1632 1608 … … 1649 1625 We obtain in output $C_{j}$ and $S_{j}$ for each tidal wave. 1650 1626 1651 % ------------------------------------------------------------------------------------------------------------- 1652 % Sections transports 1653 % ------------------------------------------------------------------------------------------------------------- 1654 \section{Transports across sections (\protect\key{diadct}) } 1627 %% ================================================================================================= 1628 \section[Transports across sections (\texttt{\textbf{key\_diadct}})]{Transports across sections (\protect\key{diadct})} 1655 1629 \label{sec:DIA_diag_dct} 1656 1630 1657 %------------------------------------------namdct---------------------------------------------------- 1658 1659 \nlst{namdct} 1660 %------------------------------------------------------------------------------------------------------------- 1631 \begin{listing} 1632 \nlst{nam_diadct} 1633 \caption{\forcode{&nam_diadct}} 1634 \label{lst:nam_diadct} 1635 \end{listing} 1661 1636 1662 1637 A module is available to compute the transport of volume, heat and salt through sections. … … 1664 1639 1665 1640 Each section is defined by the coordinates of its 2 extremities. 1666 The pathways between them are contructed using tools which can be found in \texttt{ NEMOGCM/TOOLS/SECTIONS\_DIADCT}1667 and are written in a binary file \texttt{section\_ijglobal.diadct \_ORCA2\_LIM} which is later read in by1668 NEMOto compute on-line transports.1641 The pathways between them are contructed using tools which can be found in \texttt{tools/SECTIONS\_DIADCT} 1642 and are written in a binary file \texttt{section\_ijglobal.diadct} which is later read in by 1643 \NEMO\ to compute on-line transports. 1669 1644 1670 1645 The on-line transports module creates three output ascii files: … … 1676 1651 - \texttt{salt\_transport} for salt transports (unit: $10^{9}Kg s^{-1}$) \\ 1677 1652 1678 Namelist variables in \n gn{namdct} control how frequently the flows are summed and the time scales over which1653 Namelist variables in \nam{_diadct}{\_diadct} control how frequently the flows are summed and the time scales over which 1679 1654 they are averaged, as well as the level of output for debugging: 1680 \np{nn\_dct} : frequency of instantaneous transports computing 1681 \np{nn\_dctwri}: frequency of writing ( mean of instantaneous transports ) 1682 \np{nn\_debug} : debugging of the section 1683 1655 \np{nn_dct}{nn\_dct} : frequency of instantaneous transports computing 1656 \np{nn_dctwri}{nn\_dctwri}: frequency of writing ( mean of instantaneous transports ) 1657 \np{nn_debug}{nn\_debug} : debugging of the section 1658 1659 %% ================================================================================================= 1684 1660 \subsubsection{Creating a binary file containing the pathway of each section} 1685 1661 1686 In \texttt{ NEMOGCM/TOOLS/SECTIONS\_DIADCT/run},1662 In \texttt{tools/SECTIONS\_DIADCT/run}, 1687 1663 the file \textit{ {list\_sections.ascii\_global}} contains a list of all the sections that are to be computed 1688 1664 (this list of sections is based on MERSEA project metrics). … … 1691 1667 1692 1668 Each section is defined by: \\ 1693 \noindent { \scriptsize\texttt{long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name}} \\1669 \noindent { \texttt{long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name}} \\ 1694 1670 with: 1695 1671 … … 1698 1674 - \texttt{long2 lat2}, coordinates of the second extremity of the section; 1699 1675 1700 - \texttt{nclass} the number of bounds of your classes (\eg bounds for 2 classes);1676 - \texttt{nclass} the number of bounds of your classes (\eg\ bounds for 2 classes); 1701 1677 1702 1678 - \texttt{okstrpond} to compute heat and salt transports, \texttt{nostrpond} if no; … … 1708 1684 1709 1685 \noindent If nclass $\neq$ 0, the next lines contain the class type and the nclass bounds: \\ 1710 { \scriptsize1686 { 1711 1687 \texttt{ 1712 1688 long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name \\ … … 1731 1707 1732 1708 - \texttt{zsigp} for potential density classes \\ 1733 1709 1734 1710 The script \texttt{job.ksh} computes the pathway for each section and creates a binary file 1735 \texttt{section\_ijglobal.diadct \_ORCA2\_LIM} which is read byNEMO. \\1711 \texttt{section\_ijglobal.diadct} which is read by \NEMO. \\ 1736 1712 1737 1713 It is possible to use this tools for new configuations: \texttt{job.ksh} has to be updated with … … 1741 1717 and the ATL\_Cuba\_Florida with 4 temperature clases (5 class bounds), are shown: \\ 1742 1718 \noindent 1743 { \scriptsize1719 { 1744 1720 \texttt{ 1745 1721 -68. -54.5 -60. -64.7 00 okstrpond noice ACC\_Drake\_Passage \\ … … 1753 1729 } 1754 1730 1731 %% ================================================================================================= 1755 1732 \subsubsection{To read the output files} 1756 1733 1757 1734 The output format is: \\ 1758 { \scriptsize1735 { 1759 1736 \texttt{ 1760 1737 date, time-step number, section number, \\ … … 1778 1755 1779 1756 \begin{table} 1780 \scriptsize1781 1757 \begin{tabular}{|l|l|l|l|l|} 1782 1758 \hline … … 1792 1768 \end{table} 1793 1769 1794 % ================================================================ 1795 % Steric effect in sea surface height 1796 % ================================================================ 1770 %% ================================================================================================= 1797 1771 \section{Diagnosing the steric effect in sea surface height} 1798 1772 \label{sec:DIA_steric} 1799 1800 1773 1801 1774 Changes in steric sea level are caused when changes in the density of the water column imply an expansion or … … 1809 1782 The steric effect is therefore not explicitely represented. 1810 1783 This approximation does not represent a serious error with respect to the flow field calculated by the model 1811 \citep{ Greatbatch_JGR94}, but extra attention is required when investigating sea level,1784 \citep{greatbatch_JGR94}, but extra attention is required when investigating sea level, 1812 1785 as steric changes are an important contribution to local changes in sea level on seasonal and climatic time scales. 1813 1786 This is especially true for investigation into sea level rise due to global warming. 1814 1787 1815 1788 Fortunately, the steric contribution to the sea level consists of a spatially uniform component that 1816 can be diagnosed by considering the mass budget of the world ocean \citep{ Greatbatch_JGR94}.1789 can be diagnosed by considering the mass budget of the world ocean \citep{greatbatch_JGR94}. 1817 1790 In order to better understand how global mean sea level evolves and thus how the steric sea level can be diagnosed, 1818 1791 we compare, in the following, the non-Boussinesq and Boussinesq cases. 1819 1792 1820 1793 Let denote 1821 $\mathcal{M}$ the total mass of liquid seawater ($\mathcal{M} = \int_D \rho dv$), 1822 $\mathcal{V}$ the total volume of seawater ($\mathcal{V} = \int_D dv$), 1823 $\mathcal{A}$ the total surface of the ocean ($\mathcal{A} = \int_S ds$), 1824 $\bar{\rho}$ the global mean seawater (\textit{in situ}) density 1794 $\mathcal{M}$ the total mass of liquid seawater ($\mathcal{M} = \int_D \rho dv$), 1795 $\mathcal{V}$ the total volume of seawater ($\mathcal{V} = \int_D dv$), 1796 $\mathcal{A}$ the total surface of the ocean ($\mathcal{A} = \int_S ds$), 1797 $\bar{\rho}$ the global mean seawater (\textit{in situ}) density 1825 1798 ($\bar{\rho} = 1/\mathcal{V} \int_D \rho \,dv$), and 1826 $\bar{\eta}$ the global mean sea level 1799 $\bar{\eta}$ the global mean sea level 1827 1800 ($\bar{\eta} = 1/\mathcal{A} \int_S \eta \,ds$). 1828 1801 … … 1834 1807 \mathcal{V} &= \mathcal{A} \;\bar{\eta} 1835 1808 \end{split} 1836 \label{eq: MV_nBq}1809 \label{eq:DIA_MV_nBq} 1837 1810 \end{equation} 1838 1811 … … 1842 1815 \frac{1}{e_3} \partial_t ( e_3\,\rho) + \nabla( \rho \, \textbf{U} ) 1843 1816 = \left. \frac{\textit{emp}}{e_3}\right|_\textit{surface} 1844 \label{eq: Co_nBq}1817 \label{eq:DIA_Co_nBq} 1845 1818 \end{equation} 1846 1819 1847 1820 where $\rho$ is the \textit{in situ} density, and \textit{emp} the surface mass exchanges with the other media of 1848 1821 the Earth system (atmosphere, sea-ice, land). 1849 Its global averaged leads to the total mass change 1822 Its global averaged leads to the total mass change 1850 1823 1851 1824 \begin{equation} 1852 1825 \partial_t \mathcal{M} = \mathcal{A} \;\overline{\textit{emp}} 1853 \label{eq: Mass_nBq}1826 \label{eq:DIA_Mass_nBq} 1854 1827 \end{equation} 1855 1828 1856 1829 where $\overline{\textit{emp}} = \int_S \textit{emp}\,ds$ is the net mass flux through the ocean surface. 1857 Bringing \autoref{eq: Mass_nBq} and the time derivative of \autoref{eq:MV_nBq} together leads to1830 Bringing \autoref{eq:DIA_Mass_nBq} and the time derivative of \autoref{eq:DIA_MV_nBq} together leads to 1858 1831 the evolution equation of the mean sea level 1859 1832 … … 1861 1834 \partial_t \bar{\eta} = \frac{\overline{\textit{emp}}}{ \bar{\rho}} 1862 1835 - \frac{\mathcal{V}}{\mathcal{A}} \;\frac{\partial_t \bar{\rho} }{\bar{\rho}} 1863 \label{eq: ssh_nBq}1836 \label{eq:DIA_ssh_nBq} 1864 1837 \end{equation} 1865 1838 1866 The first term in equation \autoref{eq: ssh_nBq} alters sea level by adding or subtracting mass from the ocean.1867 The second term arises from temporal changes in the global mean density; \ie from steric effects.1839 The first term in equation \autoref{eq:DIA_ssh_nBq} alters sea level by adding or subtracting mass from the ocean. 1840 The second term arises from temporal changes in the global mean density; \ie\ from steric effects. 1868 1841 1869 1842 In a Boussinesq fluid, $\rho$ is replaced by $\rho_o$ in all the equation except when $\rho$ appears multiplied by 1870 the gravity (\ie in the hydrostatic balance of the primitive Equations).1871 In particular, the mass conservation equation, \autoref{eq: Co_nBq}, degenerates into the incompressibility equation:1843 the gravity (\ie\ in the hydrostatic balance of the primitive Equations). 1844 In particular, the mass conservation equation, \autoref{eq:DIA_Co_nBq}, degenerates into the incompressibility equation: 1872 1845 1873 1846 \[ 1874 1847 \frac{1}{e_3} \partial_t ( e_3 ) + \nabla( \textbf{U} ) = \left. \frac{\textit{emp}}{\rho_o \,e_3}\right|_ \textit{surface} 1875 % \label{eq: Co_Bq}1848 % \label{eq:DIA_Co_Bq} 1876 1849 \] 1877 1850 … … 1880 1853 \[ 1881 1854 \partial_t \mathcal{V} = \mathcal{A} \;\frac{\overline{\textit{emp}}}{\rho_o} 1882 % \label{eq: V_Bq}1855 % \label{eq:DIA_V_Bq} 1883 1856 \] 1884 1857 … … 1888 1861 the ocean surface, not by changes in mean mass of the ocean: the steric effect is missing in a Boussinesq fluid. 1889 1862 1890 Nevertheless, following \citep{ Greatbatch_JGR94}, the steric effect on the volume can be diagnosed by1891 considering the mass budget of the ocean. 1863 Nevertheless, following \citep{greatbatch_JGR94}, the steric effect on the volume can be diagnosed by 1864 considering the mass budget of the ocean. 1892 1865 The apparent changes in $\mathcal{M}$, mass of the ocean, which are not induced by surface mass flux 1893 1866 must be compensated by a spatially uniform change in the mean sea level due to expansion/contraction of the ocean 1894 \citep{ Greatbatch_JGR94}.1867 \citep{greatbatch_JGR94}. 1895 1868 In others words, the Boussinesq mass, $\mathcal{M}_o$, can be related to $\mathcal{M}$, 1896 1869 the total mass of the ocean seen by the Boussinesq model, via the steric contribution to the sea level, … … 1899 1872 \begin{equation} 1900 1873 \mathcal{M}_o = \mathcal{M} + \rho_o \,\eta_s \,\mathcal{A} 1901 \label{eq: M_Bq}1874 \label{eq:DIA_M_Bq} 1902 1875 \end{equation} 1903 1876 … … 1905 1878 is converted into a mean change in sea level. 1906 1879 Introducing the total density anomaly, $\mathcal{D}= \int_D d_a \,dv$, 1907 where $d_a = (\rho -\rho_o ) / \rho_o$ is the density anomaly used in \NEMO (cf. \autoref{subsec:TRA_eos})1908 in \autoref{eq: M_Bq} leads to a very simple form for the steric height:1880 where $d_a = (\rho -\rho_o ) / \rho_o$ is the density anomaly used in \NEMO\ (cf. \autoref{subsec:TRA_eos}) 1881 in \autoref{eq:DIA_M_Bq} leads to a very simple form for the steric height: 1909 1882 1910 1883 \begin{equation} 1911 1884 \eta_s = - \frac{1}{\mathcal{A}} \mathcal{D} 1912 \label{eq: steric_Bq}1885 \label{eq:DIA_steric_Bq} 1913 1886 \end{equation} 1914 1887 1915 1888 The above formulation of the steric height of a Boussinesq ocean requires four remarks. 1916 1889 First, one can be tempted to define $\rho_o$ as the initial value of $\mathcal{M}/\mathcal{V}$, 1917 \ie set $\mathcal{D}_{t=0}=0$, so that the initial steric height is zero.1890 \ie\ set $\mathcal{D}_{t=0}=0$, so that the initial steric height is zero. 1918 1891 We do not recommend that. 1919 1892 Indeed, in this case $\rho_o$ depends on the initial state of the ocean. … … 1924 1897 This value is a sensible choice for the reference density used in a Boussinesq ocean climate model since, 1925 1898 with the exception of only a small percentage of the ocean, density in the World Ocean varies by no more than 1926 2$\%$ from this value (\cite{ Gill1982}, page 47).1899 2$\%$ from this value (\cite{gill_bk82}, page 47). 1927 1900 1928 1901 Second, we have assumed here that the total ocean surface, $\mathcal{A}$, 1929 1902 does not change when the sea level is changing as it is the case in all global ocean GCMs 1930 1903 (wetting and drying of grid point is not allowed). 1931 1932 Third, the discretisation of \autoref{eq: steric_Bq} depends on the type of free surface which is considered.1933 In the non linear free surface case, \ie \key{vvl} defined, it is given by1904 1905 Third, the discretisation of \autoref{eq:DIA_steric_Bq} depends on the type of free surface which is considered. 1906 In the non linear free surface case, \ie\ \np[=.true.]{ln_linssh}{ln\_linssh}, it is given by 1934 1907 1935 1908 \[ 1936 1909 \eta_s = - \frac{ \sum_{i,\,j,\,k} d_a\; e_{1t} e_{2t} e_{3t} }{ \sum_{i,\,j,\,k} e_{1t} e_{2t} e_{3t} } 1937 % \label{eq: discrete_steric_Bq_nfs}1910 % \label{eq:DIA_discrete_steric_Bq_nfs} 1938 1911 \] 1939 1912 … … 1945 1918 \eta_s = - \frac{ \sum_{i,\,j,\,k} d_a\; e_{1t}e_{2t}e_{3t} + \sum_{i,\,j} d_a\; e_{1t}e_{2t} \eta } 1946 1919 { \sum_{i,\,j,\,k} e_{1t}e_{2t}e_{3t} + \sum_{i,\,j} e_{1t}e_{2t} \eta } 1947 % \label{eq: discrete_steric_Bq_fs}1920 % \label{eq:DIA_discrete_steric_Bq_fs} 1948 1921 \] 1949 1922 … … 1954 1927 so that there are no associated ocean currents. 1955 1928 Hence, the dynamically relevant sea level is the effective sea level, 1956 \ie the sea level as if sea ice (and snow) were converted to liquid seawater \citep{Campin_al_OM08}.1957 However, in the current version of \NEMO the sea-ice is levitating above the ocean without mass exchanges between1929 \ie\ the sea level as if sea ice (and snow) were converted to liquid seawater \citep{campin.marshall.ea_OM08}. 1930 However, in the current version of \NEMO\ the sea-ice is levitating above the ocean without mass exchanges between 1958 1931 ice and ocean. 1959 1932 Therefore the model effective sea level is always given by $\eta + \eta_s$, whether or not there is sea ice present. … … 1965 1938 \[ 1966 1939 \eta_s = - \frac{1}{\mathcal{A}} \int_D d_a(T,S_o,p_o) \,dv 1967 % \label{eq: thermosteric_Bq}1940 % \label{eq:DIA_thermosteric_Bq} 1968 1941 \] 1969 1942 1970 1943 where $S_o$ and $p_o$ are the initial salinity and pressure, respectively. 1971 1944 1972 Both steric and thermosteric sea level are computed in \mdl{diaar5} which needs the \key{diaar5} defined to 1973 be called. 1974 1975 % ------------------------------------------------------------------------------------------------------------- 1976 % Other Diagnostics 1977 % ------------------------------------------------------------------------------------------------------------- 1978 \section{Other diagnostics (\protect\key{diahth}, \protect\key{diaar5})} 1945 Both steric and thermosteric sea level are computed in \mdl{diaar5}. 1946 1947 %% ================================================================================================= 1948 \section{Other diagnostics} 1979 1949 \label{sec:DIA_diag_others} 1980 1950 … … 1982 1952 The available ready-to-add diagnostics modules can be found in directory DIA. 1983 1953 1984 \subsection{Depth of various quantities (\protect\mdl{diahth})} 1954 %% ================================================================================================= 1955 \subsection[Depth of various quantities (\textit{diahth.F90})]{Depth of various quantities (\protect\mdl{diahth})} 1985 1956 1986 1957 Among the available diagnostics the following ones are obtained when defining the \key{diahth} CPP key: 1987 1958 1988 - the mixed layer depth (based on a density criterion \citep{de _Boyer_Montegut_al_JGR04}) (\mdl{diahth})1959 - the mixed layer depth (based on a density criterion \citep{de-boyer-montegut.madec.ea_JGR04}) (\mdl{diahth}) 1989 1960 1990 1961 - the turbocline depth (based on a turbulent mixing coefficient criterion) (\mdl{diahth}) … … 1994 1965 - the depth of the thermocline (maximum of the vertical temperature gradient) (\mdl{diahth}) 1995 1966 1996 % ----------------------------------------------------------- 1997 % Poleward heat and salt transports 1998 % ----------------------------------------------------------- 1999 2000 \subsection{Poleward heat and salt transports (\protect\mdl{diaptr})} 2001 2002 %------------------------------------------namptr----------------------------------------- 2003 2004 \nlst{namptr} 2005 %----------------------------------------------------------------------------------------- 2006 2007 The poleward heat and salt transports, their advective and diffusive component, 2008 and the meriodional stream function can be computed on-line in \mdl{diaptr} \np{ln\_diaptr} to true 2009 (see the \textit{\ngn{namptr} } namelist below). 2010 When \np{ln\_subbas}\forcode{ = .true.}, transports and stream function are computed for the Atlantic, Indian, 1967 \begin{figure}[!t] 1968 \centering 1969 \includegraphics[width=0.66\textwidth]{DIA_mask_subasins} 1970 \caption[Decomposition of the World Ocean to compute transports as well as 1971 the meridional stream-function]{ 1972 Decomposition of the World Ocean (here ORCA2) into sub-basin used in to 1973 compute the heat and salt transports as well as the meridional stream-function: 1974 Atlantic basin (red), Pacific basin (green), 1975 Indian basin (blue), Indo-Pacific basin (blue+green). 1976 Note that semi-enclosed seas (Red, Med and Baltic seas) as well as 1977 Hudson Bay are removed from the sub-basins. 1978 Note also that the Arctic Ocean has been split into Atlantic and 1979 Pacific basins along the North fold line. 1980 } 1981 \label{fig:DIA_mask_subasins} 1982 \end{figure} 1983 1984 %% ================================================================================================= 1985 \subsection[CMIP specific diagnostics (\textit{diaar5.F90}, \textit{diaptr.F90})]{CMIP specific diagnostics (\protect\mdl{diaar5})} 1986 1987 A series of diagnostics has been added in the \mdl{diaar5} and \mdl{diaptr}. 1988 In \mdl{diaar5} they correspond to outputs that are required for AR5 simulations (CMIP5) 1989 (see also \autoref{sec:DIA_steric} for one of them). 1990 The module \mdl{diaar5} is active when one of the following outputs is required : 1991 global total volume (voltot), global mean ssh (sshtot), global total mass (masstot), global mean temperature (temptot), 1992 global mean ssh steric (sshsteric), global mean ssh thermosteric (sshthster), global mean salinity (saltot), 1993 sea water pressure at sea floor (botpres), dynamic sea surface height (sshdyn). 1994 1995 In \mdl{diaptr} when \np[=.true.]{ln_diaptr}{ln\_diaptr} 1996 (see the \nam{ptr}{ptr} namelist below) can be computed on-line the poleward heat and salt transports, 1997 their advective and diffusive component, and the meriodional stream function . 1998 When \np[=.true.]{ln_subbas}{ln\_subbas}, transports and stream function are computed for the Atlantic, Indian, 2011 1999 Pacific and Indo-Pacific Oceans (defined north of 30\deg{S}) as well as for the World Ocean. 2012 2000 The sub-basin decomposition requires an input file (\ifile{subbasins}) which contains three 2D mask arrays, 2013 the Indo-Pacific mask been deduced from the sum of the Indian and Pacific mask (\autoref{fig:mask_subasins}). 2014 2015 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 2016 \begin{figure}[!t] 2017 \begin{center} 2018 \includegraphics[width=1.0\textwidth]{Fig_mask_subasins} 2019 \caption{ 2020 \protect\label{fig:mask_subasins} 2021 Decomposition of the World Ocean (here ORCA2) into sub-basin used in to 2022 compute the heat and salt transports as well as the meridional stream-function: 2023 Atlantic basin (red), Pacific basin (green), Indian basin (bleue), Indo-Pacific basin (bleue+green). 2024 Note that semi-enclosed seas (Red, Med and Baltic seas) as well as Hudson Bay are removed from the sub-basins. 2025 Note also that the Arctic Ocean has been split into Atlantic and Pacific basins along the North fold line. 2026 } 2027 \end{center} 2028 \end{figure} 2029 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 2030 2031 % ----------------------------------------------------------- 2032 % CMIP specific diagnostics 2033 % ----------------------------------------------------------- 2034 \subsection{CMIP specific diagnostics (\protect\mdl{diaar5})} 2035 2036 A series of diagnostics has been added in the \mdl{diaar5}. 2037 They corresponds to outputs that are required for AR5 simulations (CMIP5) 2038 (see also \autoref{sec:DIA_steric} for one of them). 2039 Activating those outputs requires to define the \key{diaar5} CPP key. 2040 2041 % ----------------------------------------------------------- 2042 % 25 hour mean and hourly Surface, Mid and Bed 2043 % ----------------------------------------------------------- 2001 the Indo-Pacific mask been deduced from the sum of the Indian and Pacific mask (\autoref{fig:DIA_mask_subasins}). 2002 2003 \begin{listing} 2004 \nlst{namptr} 2005 \caption{\forcode{&namptr}} 2006 \label{lst:namptr} 2007 \end{listing} 2008 2009 %% ================================================================================================= 2044 2010 \subsection{25 hour mean output for tidal models} 2045 2011 2046 %------------------------------------------nam_dia25h------------------------------------- 2047 2048 \nlst{nam_dia25h} 2049 %----------------------------------------------------------------------------------------- 2012 \begin{listing} 2013 \nlst{nam_dia25h} 2014 \caption{\forcode{&nam_dia25h}} 2015 \label{lst:nam_dia25h} 2016 \end{listing} 2050 2017 2051 2018 A module is available to compute a crudely detided M2 signal by obtaining a 25 hour mean. … … 2054 2021 This diagnostic is actived with the logical $ln\_dia25h$. 2055 2022 2056 % ----------------------------------------------------------- 2057 % Top Middle and Bed hourly output 2058 % ----------------------------------------------------------- 2023 %% ================================================================================================= 2059 2024 \subsection{Top middle and bed hourly output} 2060 2025 2061 %------------------------------------------nam_diatmb----------------------------------------------------- 2062 2063 \nlst{nam_diatmb} 2064 %---------------------------------------------------------------------------------------------------------- 2026 \begin{listing} 2027 \nlst{nam_diatmb} 2028 \caption{\forcode{&nam_diatmb}} 2029 \label{lst:nam_diatmb} 2030 \end{listing} 2065 2031 2066 2032 A module is available to output the surface (top), mid water and bed diagnostics of a set of standard variables. … … 2070 2036 This diagnostic is actived with the logical $ln\_diatmb$. 2071 2037 2072 % ----------------------------------------------------------- 2073 % Courant numbers 2074 % ----------------------------------------------------------- 2038 %% ================================================================================================= 2075 2039 \subsection{Courant numbers} 2076 2040 … … 2080 2044 \[ 2081 2045 C_u = |u|\frac{\rdt}{e_{1u}}, \quad C_v = |v|\frac{\rdt}{e_{2v}}, \quad C_w = |w|\frac{\rdt}{e_{3w}} 2082 % \label{eq: CFL}2046 % \label{eq:DIA_CFL} 2083 2047 \] 2084 2048 … … 2089 2053 Values greater than 1 indicate that information is propagated across more than one grid cell in a single time step. 2090 2054 2091 The variables can be activated by setting the \np{nn \_diacfl} namelist parameter to 1 in the \ngn{namctl} namelist.2055 The variables can be activated by setting the \np{nn_diacfl}{nn\_diacfl} namelist parameter to 1 in the \nam{ctl}{ctl} namelist. 2092 2056 The diagnostics will be written out to an ascii file named cfl\_diagnostics.ascii. 2093 2057 In this file the maximum value of $C_u$, $C_v$, and $C_w$ are printed at each timestep along with the coordinates of … … 2095 2059 At the end of the model run the maximum value of $C_u$, $C_v$, and $C_w$ for the whole model run is printed along 2096 2060 with the coordinates of each. 2097 The maximum values from the run are also copied to the ocean.output file. 2098 2099 % ================================================================ 2100 2101 \biblio 2102 2103 \pindex 2061 The maximum values from the run are also copied to the ocean.output file. 2062 2063 \subinc{\input{../../global/epilogue}} 2104 2064 2105 2065 \end{document} -
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_DIU.tex
r10442 r11831 2 2 3 3 \begin{document} 4 % ================================================================ 5 % Diurnal SST models (DIU) 6 % Edited by James While 7 % ================================================================ 4 8 5 \chapter{Diurnal SST Models (DIU)} 9 6 \label{chap:DIU} 10 7 11 \ minitoc8 \thispagestyle{plain} 12 9 10 \chaptertoc 13 11 14 \newpage 15 $\ $\newline % force a new line 12 \paragraph{Changes record} ~\\ 13 14 {\footnotesize 15 \begin{tabularx}{\textwidth}{l||X|X} 16 Release & Author(s) & Modifications \\ 17 \hline 18 {\em 4.0} & {\em ...} & {\em ...} \\ 19 {\em 3.6} & {\em ...} & {\em ...} \\ 20 {\em 3.4} & {\em ...} & {\em ...} \\ 21 {\em <=3.4} & {\em ...} & {\em ...} 22 \end{tabularx} 23 } 24 25 \clearpage 16 26 17 27 Code to produce an estimate of the diurnal warming and cooling of the sea surface skin 18 temperature (skin SST) is found in the DIU directory. 28 temperature (skin SST) is found in the DIU directory. 19 29 The skin temperature can be split into three parts: 20 30 \begin{itemize} 21 \item 22 A foundation SST which is free from diurnal warming. 23 \item 24 A warm layer, typically ~3\,m thick, 31 \item A foundation SST which is free from diurnal warming. 32 \item A warm layer, typically ~3\,m thick, 25 33 where heating from solar radiation can cause a warm stably stratified layer during the daytime 26 \item 27 A cool skin, a thin layer, approximately ~1\, mm thick, 34 \item A cool skin, a thin layer, approximately ~1\, mm thick, 28 35 where long wave cooling is dominant and cools the immediate ocean surface. 29 36 \end{itemize} 30 37 31 38 Models are provided for both the warm layer, \mdl{diurnal\_bulk}, and the cool skin, \mdl{cool\_skin}. 32 Foundation SST is not considered as it can be obtained either from the main NEMOmodel33 (\ie from the temperature of the top few model levels) or from some other source.39 Foundation SST is not considered as it can be obtained either from the main \NEMO\ model 40 (\ie\ from the temperature of the top few model levels) or from some other source. 34 41 It must be noted that both the cool skin and warm layer models produce estimates of the change in temperature 35 ($\Delta T_{\ rm{cs}}$ and $\Delta T_{\rm{wl}}$) and42 ($\Delta T_{\mathrm{cs}}$ and $\Delta T_{\mathrm{wl}}$) and 36 43 both must be added to a foundation SST to obtain the true skin temperature. 37 44 38 Both the cool skin and warm layer models are controlled through the namelist \n gn{namdiu}:45 Both the cool skin and warm layer models are controlled through the namelist \nam{diu}{diu}: 39 46 40 \nlst{namdiu} 47 \begin{listing} 48 \nlst{namdiu} 49 \caption{\forcode{&namdiu}} 50 \label{lst:namdiu} 51 \end{listing} 52 41 53 This namelist contains only two variables: 42 54 \begin{description} 43 \item[\np{ln\_diurnal}] 44 A logical switch for turning on/off both the cool skin and warm layer. 45 \item[\np{ln\_diurnal\_only}] 46 A logical switch which if \forcode{.true.} will run the diurnal model without the other dynamical parts of NEMO. 47 \np{ln\_diurnal\_only} must be \forcode{.false.} if \np{ln\_diurnal} is \forcode{.false.}. 55 \item [{\np{ln_diurnal}{ln\_diurnal}}] A logical switch for turning on/off both the cool skin and warm layer. 56 \item [{\np{ln_diurnal_only}{ln\_diurnal\_only}}] A logical switch which if \forcode{.true.} will run the diurnal model without the other dynamical parts of \NEMO. 57 \np{ln_diurnal_only}{ln\_diurnal\_only} must be \forcode{.false.} if \np{ln_diurnal}{ln\_diurnal} is \forcode{.false.}. 48 58 \end{description} 49 59 … … 53 63 Initialisation is through the restart file. 54 64 Specifically the code will expect the presence of the 2-D variable ``Dsst'' to initialise the warm layer. 55 The cool skin model, which is determined purely by the instantaneous fluxes, has no initialisation variable. 65 The cool skin model, which is determined purely by the instantaneous fluxes, has no initialisation variable. 56 66 57 % ===============================================================67 %% ================================================================================================= 58 68 \section{Warm layer model} 59 \label{sec:warm_layer_sec} 60 %=============================================================== 69 \label{sec:DIU_warm_layer_sec} 61 70 62 The warm layer is calculated using the model of \citet{ Takaya_al_JGR10} (TAKAYA10 model hereafter).71 The warm layer is calculated using the model of \citet{takaya.bidlot.ea_JGR10} (TAKAYA10 model hereafter). 63 72 This is a simple flux based model that is defined by the equations 64 73 \begin{align} 65 \frac{\partial{\Delta T_{\ rm{wl}}}}{\partial{t}}&=&\frac{Q(\nu+1)}{D_T\rho_w c_p74 \frac{\partial{\Delta T_{\mathrm{wl}}}}{\partial{t}}&=&\frac{Q(\nu+1)}{D_T\rho_w c_p 66 75 \nu}-\frac{(\nu+1)ku^*_{w}f(L_a)\Delta T}{D_T\Phi\!\left(\frac{D_T}{L}\right)} \mbox{,} 67 \label{eq: ecmwf1} \\68 L&=&\frac{\rho_w c_p u^{*^3}_{w}}{\kappa g \alpha_w Q }\mbox{,}\label{eq: ecmwf2}76 \label{eq:DIU_ecmwf1} \\ 77 L&=&\frac{\rho_w c_p u^{*^3}_{w}}{\kappa g \alpha_w Q }\mbox{,}\label{eq:DIU_ecmwf2} 69 78 \end{align} 70 where $\Delta T_{\ rm{wl}}$ is the temperature difference between the top of the warm layer and the depth $D_T=3$\,m at which there is assumed to be no diurnal signal.71 In equation (\autoref{eq: ecmwf1}) $\alpha_w=2\times10^{-4}$ is the thermal expansion coefficient of water,79 where $\Delta T_{\mathrm{wl}}$ is the temperature difference between the top of the warm layer and the depth $D_T=3$\,m at which there is assumed to be no diurnal signal. 80 In equation (\autoref{eq:DIU_ecmwf1}) $\alpha_w=2\times10^{-4}$ is the thermal expansion coefficient of water, 72 81 $\kappa=0.4$ is von K\'{a}rm\'{a}n's constant, $c_p$ is the heat capacity at constant pressure of sea water, 73 82 $\rho_w$ is the water density, and $L$ is the Monin-Obukhov length. 74 83 The tunable variable $\nu$ is a shape parameter that defines the expected subskin temperature profile via 75 $T(z) = T(0) - \left( \frac{z}{D_T} \right)^\nu \Delta T_{\ rm{wl}}$,84 $T(z) = T(0) - \left( \frac{z}{D_T} \right)^\nu \Delta T_{\mathrm{wl}}$, 76 85 where $T$ is the absolute temperature and $z\le D_T$ is the depth below the top of the warm layer. 77 86 The influence of wind on TAKAYA10 comes through the magnitude of the friction velocity of the water $u^*_{w}$, … … 79 88 the relationship $u^*_{w} = u_{10}\sqrt{\frac{C_d\rho_a}{\rho_w}}$, where $C_d$ is the drag coefficient, 80 89 and $\rho_a$ is the density of air. 81 The symbol $Q$ in equation (\autoref{eq: ecmwf1}) is the instantaneous total thermal energy flux into90 The symbol $Q$ in equation (\autoref{eq:DIU_ecmwf1}) is the instantaneous total thermal energy flux into 82 91 the diurnal layer, \ie 83 92 \[ 84 Q = Q_{\ rm{sol}} + Q_{\rm{lw}} + Q_{\rm{h}}\mbox{,}85 % \label{eq: e_flux_eqn}93 Q = Q_{\mathrm{sol}} + Q_{\mathrm{lw}} + Q_{\mathrm{h}}\mbox{,} 94 % \label{eq:DIU_e_flux_eqn} 86 95 \] 87 where $Q_{\ rm{h}}$ is the sensible and latent heat flux, $Q_{\rm{lw}}$ is the long wave flux,88 and $Q_{\ rm{sol}}$ is the solar flux absorbed within the diurnal warm layer.89 For $Q_{\ rm{sol}}$ the 9 term representation of \citet{Gentemann_al_JGR09} is used.90 In equation \autoref{eq: ecmwf1} the function $f(L_a)=\max(1,L_a^{\frac{2}{3}})$,96 where $Q_{\mathrm{h}}$ is the sensible and latent heat flux, $Q_{\mathrm{lw}}$ is the long wave flux, 97 and $Q_{\mathrm{sol}}$ is the solar flux absorbed within the diurnal warm layer. 98 For $Q_{\mathrm{sol}}$ the 9 term representation of \citet{gentemann.minnett.ea_JGR09} is used. 99 In equation \autoref{eq:DIU_ecmwf1} the function $f(L_a)=\max(1,L_a^{\frac{2}{3}})$, 91 100 where $L_a=0.3$\footnote{ 92 101 This is a global average value, more accurately $L_a$ could be computed as $L_a=(u^*_{w}/u_s)^{\frac{1}{2}}$, … … 99 108 4\zeta^2}{1+3\zeta+0.25\zeta^2} &(\zeta \ge 0) \\ 100 109 (1 - 16\zeta)^{-\frac{1}{2}} & (\zeta < 0) \mbox{,} 101 \end{array} \right. \label{eq: stab_func_eqn}110 \end{array} \right. \label{eq:DIU_stab_func_eqn} 102 111 \end{equation} 103 where $\zeta=\frac{D_T}{L}$. It is clear that the first derivative of (\autoref{eq: stab_func_eqn}),104 and thus of (\autoref{eq: ecmwf1}), is discontinuous at $\zeta=0$ (\ie$Q\rightarrow0$ in105 equation (\autoref{eq: ecmwf2})).112 where $\zeta=\frac{D_T}{L}$. It is clear that the first derivative of (\autoref{eq:DIU_stab_func_eqn}), 113 and thus of (\autoref{eq:DIU_ecmwf1}), is discontinuous at $\zeta=0$ (\ie\ $Q\rightarrow0$ in 114 equation (\autoref{eq:DIU_ecmwf2})). 106 115 107 The two terms on the right hand side of (\autoref{eq: ecmwf1}) represent different processes.116 The two terms on the right hand side of (\autoref{eq:DIU_ecmwf1}) represent different processes. 108 117 The first term is simply the diabatic heating or cooling of the diurnal warm layer due to 109 118 thermal energy fluxes into and out of the layer. … … 111 120 In practice the second term acts as a relaxation on the temperature. 112 121 113 %=============================================================== 122 %% ================================================================================================= 123 \section{Cool skin model} 124 \label{sec:DIU_cool_skin_sec} 114 125 115 \section{Cool skin model} 116 \label{sec:cool_skin_sec} 117 118 %=============================================================== 119 120 The cool skin is modelled using the framework of \citet{Saunders_JAS82} who used a formulation of the near surface temperature difference based upon the heat flux and the friction velocity $u^*_{w}$. 121 As the cool skin is so thin (~1\,mm) we ignore the solar flux component to the heat flux and the Saunders equation for the cool skin temperature difference $\Delta T_{\rm{cs}}$ becomes 126 The cool skin is modelled using the framework of \citet{saunders_JAS67} who used a formulation of the near surface temperature difference based upon the heat flux and the friction velocity $u^*_{w}$. 127 As the cool skin is so thin (~1\,mm) we ignore the solar flux component to the heat flux and the Saunders equation for the cool skin temperature difference $\Delta T_{\mathrm{cs}}$ becomes 122 128 \[ 123 % \label{eq: sunders_eqn}124 \Delta T_{\ rm{cs}}=\frac{Q_{\rm{ns}}\delta}{k_t} \mbox{,}129 % \label{eq:DIU_sunders_eqn} 130 \Delta T_{\mathrm{cs}}=\frac{Q_{\mathrm{ns}}\delta}{k_t} \mbox{,} 125 131 \] 126 where $Q_{\ rm{ns}}$ is the, usually negative, non-solar heat flux into the ocean and132 where $Q_{\mathrm{ns}}$ is the, usually negative, non-solar heat flux into the ocean and 127 133 $k_t$ is the thermal conductivity of sea water. 128 134 $\delta$ is the thickness of the skin layer and is given by 129 135 \begin{equation} 130 \label{eq: sunders_thick_eqn}136 \label{eq:DIU_sunders_thick_eqn} 131 137 \delta=\frac{\lambda \mu}{u^*_{w}} \mbox{,} 132 138 \end{equation} 133 139 where $\mu$ is the kinematic viscosity of sea water and $\lambda$ is a constant of proportionality which 134 \citet{ Saunders_JAS82} suggested varied between 5 and 10.140 \citet{saunders_JAS67} suggested varied between 5 and 10. 135 141 136 The value of $\lambda$ used in equation (\autoref{eq: sunders_thick_eqn}) is that of \citet{Artale_al_JGR02},137 which is shown in \citet{ Tu_Tsuang_GRL05} to outperform a number of other parametrisations at142 The value of $\lambda$ used in equation (\autoref{eq:DIU_sunders_thick_eqn}) is that of \citet{artale.iudicone.ea_JGR02}, 143 which is shown in \citet{tu.tsuang_GRL05} to outperform a number of other parametrisations at 138 144 both low and high wind speeds. 139 145 Specifically, 140 146 \[ 141 % \label{eq: artale_lambda_eqn}147 % \label{eq:DIU_artale_lambda_eqn} 142 148 \lambda = \frac{ 8.64\times10^4 u^*_{w} k_t }{ \rho c_p h \mu \gamma }\mbox{,} 143 149 \] … … 145 151 $\gamma$ is a dimensionless function of wind speed $u$: 146 152 \[ 147 % \label{eq: artale_gamma_eqn}153 % \label{eq:DIU_artale_gamma_eqn} 148 154 \gamma = 149 155 \begin{cases} … … 154 160 \] 155 161 156 \biblio 157 158 \pindex 162 \subinc{\input{../../global/epilogue}} 159 163 160 164 \end{document} -
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_DOM.tex
r10502 r11831 2 2 3 3 \begin{document} 4 % ================================================================ 5 % Chapter 2 ——— Space and Time Domain (DOM) 6 % ================================================================ 4 7 5 \chapter{Space Domain (DOM)} 8 6 \label{chap:DOM} 9 7 10 \minitoc 11 12 % Missing things: 13 % - istate: description of the initial state ==> this has to be put elsewhere.. 14 % perhaps in MISC ? By the way the initialisation of T S and dynamics 15 % should be put outside of DOM routine (better with TRC staff and off-line 16 % tracers) 17 % -geo2ocean: how to switch from geographic to mesh coordinate 18 % - domclo: closed sea and lakes.... management of closea sea area : specific to global configuration, both forced and coupled 19 20 \newpage 21 22 Having defined the continuous equations in \autoref{chap:PE} and chosen a time discretization \autoref{chap:STP}, 23 we need to choose a discretization on a grid, and numerical algorithms. 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 16 17 \thispagestyle{plain} 18 19 \chaptertoc 20 21 \paragraph{Changes record} ~\\ 22 23 {\footnotesize 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 } 41 \end{tabularx} 42 } 43 44 \clearpage 45 46 Having defined the continuous equations in \autoref{chap:MB} and 47 chosen a time discretisation \autoref{chap:TD}, 48 we need to choose a grid for spatial discretisation and related numerical algorithms. 24 49 In the present chapter, we provide a general description of the staggered grid used in \NEMO, 25 and other information relevant to the main directory routines as well as the DOM (DOMain) directory. 26 27 % ================================================================ 28 % Fundamentals of the Discretisation 29 % ================================================================ 50 and other relevant information about the DOM (DOMain) source code modules. 51 52 %% ================================================================================================= 30 53 \section{Fundamentals of the discretisation} 31 54 \label{sec:DOM_basics} 32 55 33 % ------------------------------------------------------------------------------------------------------------- 34 % Arrangement of Variables 35 % ------------------------------------------------------------------------------------------------------------- 56 %% ================================================================================================= 36 57 \subsection{Arrangement of variables} 37 58 \label{subsec:DOM_cell} 38 59 39 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 40 \begin{figure}[!tb] 41 \begin{center} 42 \includegraphics[]{Fig_cell} 43 \caption{ 44 \protect\label{fig:cell} 45 Arrangement of variables. 46 $t$ indicates scalar points where temperature, salinity, density, pressure and 47 horizontal divergence are defined. 48 $(u,v,w)$ indicates vector points, and $f$ indicates vorticity points where both relative and 49 planetary vorticities are defined. 50 } 51 \end{center} 60 \begin{figure} 61 \centering 62 \includegraphics[width=0.33\textwidth]{DOM_cell} 63 \caption[Arrangement of variables in the unit cell of space domain]{ 64 Arrangement of variables in the unit cell of space domain. 65 $t$ indicates scalar points where 66 temperature, salinity, density, pressure and horizontal divergence are defined. 67 $(u,v,w)$ indicates vector points, and $f$ indicates vorticity points where 68 both relative and planetary vorticities are defined.} 69 \label{fig:DOM_cell} 52 70 \end{figure} 53 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 54 55 The numerical techniques used to solve the Primitive Equations in this model are based on the traditional, 56 centred second-order finite difference approximation. 57 Special attention has been given to the homogeneity of the solution in the three space directions. 71 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. 74 Special attention has been given to the homogeneity of the solution in the three spatial directions. 58 75 The arrangement of variables is the same in all directions. 59 It consists of cells centred on scalar points ($t$, $S$, $p$, $\rho$) with vector points $(u, v, w)$ defined in 60 the centre of each face of the cells (\autoref{fig:cell}). 61 This is the generalisation to three dimensions of the well-known ``C'' grid in Arakawa's classification 62 \citep{Mesinger_Arakawa_Bk76}. 63 The relative and planetary vorticity, $\zeta$ and $f$, are defined in the centre of each vertical edge and 64 the barotropic stream function $\psi$ is defined at horizontal points overlying the $\zeta$ and $f$-points. 65 66 The ocean mesh (\ie the position of all the scalar and vector points) is defined by the transformation that 67 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 indicated on \autoref{tab:cell}. 69 In all the following, subscripts $u$, $v$, $w$, $f$, $uw$, $vw$ or $fw$ indicate the position of 70 the grid-point where the scale factors are defined. 71 Each scale factor is defined as the local analytical value provided by \autoref{eq:scale_factors}. 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. 91 Each scale factor is defined as the local analytical value provided by \autoref{eq:MB_scale_factors}. 72 92 As a result, the mesh on which partial derivatives $\pd[]{\lambda}$, $\pd[]{\varphi}$ and 73 $\pd[]{z}$ are evaluated in a uniform mesh with a grid size of unity. 74 Discrete partial derivatives are formulated by the traditional, centred second order finite difference approximation 75 while the scale factors are chosen equal to their local analytical value. 93 $\pd[]{z}$ are evaluated is a uniform mesh with a grid size of unity. 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. 76 97 An important point here is that the partial derivative of the scale factors must be evaluated by 77 98 centred finite difference approximation, not from their analytical expression. 78 This preserves the symmetry of the discrete set of equations and therefore satisfies many of79 the continuous properties (see \autoref{apdx:C}).99 This preserves the symmetry of the discrete set of equations and 100 therefore satisfies many of the continuous properties (see \autoref{apdx:INVARIANTS}). 80 101 A similar, related remark can be made about the domain size: 81 when needed, an area, volume, or the total ocean depth must be evaluated as the sum of the relevant scale factors 82 (see \autoref{eq:DOM_bar} in the next section). 83 84 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 85 \begin{table}[!tb] 86 \begin{center} 87 \begin{tabular}{|p{46pt}|p{56pt}|p{56pt}|p{56pt}|} 88 \hline 89 T & $i $ & $j $ & $k $ \\ 90 \hline 91 u & $i + 1/2$ & $j $ & $k $ \\ 92 \hline 93 v & $i $ & $j + 1/2$ & $k $ \\ 94 \hline 95 w & $i $ & $j $ & $k + 1/2$ \\ 96 \hline 97 f & $i + 1/2$ & $j + 1/2$ & $k $ \\ 98 \hline 99 uw & $i + 1/2$ & $j $ & $k + 1/2$ \\ 100 \hline 101 vw & $i $ & $j + 1/2$ & $k + 1/2$ \\ 102 \hline 103 fw & $i + 1/2$ & $j + 1/2$ & $k + 1/2$ \\ 104 \hline 105 \end{tabular} 106 \caption{ 107 \protect\label{tab:cell} 108 Location of grid-points as a function of integer or integer and a half value of the column, line or level. 109 This indexing is only used for the writing of the semi -discrete equation. 110 In the code, the indexing uses integer values only and has a reverse direction in the vertical 111 (see \autoref{subsec:DOM_Num_Index}) 112 } 113 \end{center} 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} 106 \centering 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$ \\ 124 \hline 125 \end{tabular} 126 \caption[Location of grid-points]{ 127 Location of grid-points as a function of integer or 128 integer and a half value of the column, line or level. 129 This indexing is only used for the writing of the semi-discrete equations. 130 In the code, the indexing uses integer values only and 131 is positive downwards in the vertical with $k=1$ at the surface. 132 (see \autoref{subsec:DOM_Num_Index})} 133 \label{tab:DOM_cell} 114 134 \end{table} 115 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 116 117 % ------------------------------------------------------------------------------------------------------------- 118 % Vector Invariant Formulation 119 % ------------------------------------------------------------------------------------------------------------- 135 136 Note that the definition of the scale factors 137 (\ie\ as the analytical first derivative of the transformation that 138 results in $(\lambda,\varphi,z)$ as a function of $(i,j,k)$) 139 is specific to the \NEMO\ model \citep{marti.madec.ea_JGR92}. 140 As an example, a scale factor in the $i$ direction is defined locally at a $t$-point, 141 whereas many other models on a C grid choose to define such a scale factor as 142 the distance between the $u$-points on each side of the $t$-point. 143 Relying on an analytical transformation has two advantages: 144 firstly, there is no ambiguity in the scale factors appearing in the discrete equations, 145 since they are first introduced in the continuous equations; 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}. 150 An example of the effect of such a choice is shown in \autoref{fig:DOM_zgr_e3}. 151 \begin{figure} 152 \centering 153 \includegraphics[width=0.5\textwidth]{DOM_zgr_e3} 154 \caption[Comparison of grid-point position, vertical grid-size and scale factors]{ 155 Comparison of (a) traditional definitions of grid-point position and grid-size in the vertical, 156 and (b) analytically derived grid-point position and scale factors. 157 For both grids here, the same $w$-point depth has been chosen but 158 in (a) the $t$-points are set half way between $w$-points while 159 in (b) they are defined from an analytical function: 160 $z(k) = 5 \, (k - 1/2)^3 - 45 \, (k - 1/2)^2 + 140 \, (k - 1/2) - 150$. 161 Note the resulting difference between the value of the grid-size $\Delta_k$ and 162 those of the scale factor $e_k$.} 163 \label{fig:DOM_zgr_e3} 164 \end{figure} 165 166 %% ================================================================================================= 120 167 \subsection{Discrete operators} 121 168 \label{subsec:DOM_operators} 122 169 123 Given the values of a variable $q$ at adjacent points, the differencing and averaging operators at124 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: 125 172 \begin{alignat*}{2} 126 % \label{eq: di_mi}173 % \label{eq:DOM_di_mi} 127 174 \delta_i [q] &= & &q (i + 1/2) - q (i - 1/2) \\ 128 175 \overline q^{\, i} &= &\big\{ &q (i + 1/2) + q (i - 1/2) \big\} / 2 … … 130 177 131 178 Similar operators are defined with respect to $i + 1/2$, $j$, $j + 1/2$, $k$, and $k + 1/2$. 132 Following \autoref{eq:PE_grad} and \autoref{eq:PE_lap}, the gradient of a variable $q$ defined at 133 a $t$-point has its three components defined at $u$-, $v$- and $w$-points while 134 its Laplacian is defined at $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. 135 183 These operators have the following discrete forms in the curvilinear $s$-coordinates system: 136 \ [184 \begin{gather*} 137 185 % \label{eq:DOM_grad} 138 186 \nabla q \equiv \frac{1}{e_{1u}} \delta_{i + 1/2} [q] \; \, \vect i 139 187 + \frac{1}{e_{2v}} \delta_{j + 1/2} [q] \; \, \vect j 140 + \frac{1}{e_{3w}} \delta_{k + 1/2} [q] \; \, \vect k 141 \] 142 \begin{multline*} 188 + \frac{1}{e_{3w}} \delta_{k + 1/2} [q] \; \, \vect k \\ 143 189 % \label{eq:DOM_lap} 144 190 \Delta q \equiv \frac{1}{e_{1t} \, e_{2t} \, e_{3t}} 145 191 \; \lt[ \delta_i \lt( \frac{e_{2u} \, e_{3u}}{e_{1u}} \; \delta_{i + 1/2} [q] \rt) 146 + \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] 147 193 + \frac{1}{e_{3t}} 148 194 \delta_k \lt[ \frac{1 }{e_{3w}} \; \delta_{k + 1/2} [q] \rt] 149 \end{multline*} 150 151 Following \autoref{eq:PE_curl} and \autoref{eq:PE_div}, a vector $\vect A = (a_1,a_2,a_3)$ defined at 152 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 153 200 its divergence defined at $t$-points: 154 \begin{multline }201 \begin{multline*} 155 202 % \label{eq:DOM_curl} 156 203 \nabla \times \vect A \equiv \frac{1}{e_{2v} \, e_{3vw}} … … 163 210 \Big[ \delta_{i + 1/2} (e_{2v} \, a_2) 164 211 - \delta_{j + 1/2} (e_{1u} \, a_1) \Big] \vect k 165 \end{multline }166 \ begin{equation}212 \end{multline*} 213 \[ 167 214 % \label{eq:DOM_div} 168 215 \nabla \cdot \vect A \equiv \frac{1}{e_{1t} \, e_{2t} \, e_{3t}} 169 216 \Big[ \delta_i (e_{2u} \, e_{3u} \, a_1) + \delta_j (e_{1v} \, e_{3v} \, a_2) \Big] 170 217 + \frac{1}{e_{3t}} \delta_k (a_3) 171 \ end{equation}172 173 The vertical average over the whole water column denoted by an overbar becomes for a quantity $q$ which174 is a masked field (i.e. equal to zero inside solid area):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): 175 222 \begin{equation} 176 223 \label{eq:DOM_bar} … … 178 225 \end{equation} 179 226 where $H_q$ is the ocean depth, which is the masked sum of the vertical scale factors at $q$ points, 180 $k^b$ and $k^o$ are the bottom and surface $k$-indices, and the symbol $k^o$ refers to a summation over 181 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$). 182 230 183 231 In continuous form, the following properties are satisfied: … … 189 237 \end{gather} 190 238 191 It is straightforward to demonstrate that these properties are verified locally in discrete form as soon as192 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 193 241 vector points $(u,v,w)$. 194 242 195 Let $a$ and $b$ be two fields defined on the mesh, with value zero inside continental area. 196 Using integration by parts it can be shown that the differencing operators ($\delta_i$, $\delta_j$ and $\delta_k$) 197 are skew-symmetric linear operators, and further that the averaging operators $\overline{\cdots}^{\, i}$, 198 $\overline{\cdots}^{\, j}$ and $\overline{\cdots}^{\, k}$) are symmetric linear operators, \ie 199 \begin{alignat}{4} 243 Let $a$ and $b$ be two fields defined on the mesh, with a value of zero inside continental areas. 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} 200 249 \label{eq:DOM_di_adj} 201 250 &\sum \limits_i a_i \; \delta_i [b] &\equiv &- &&\sum \limits_i \delta _{ i + 1/2} [a] &b_{i + 1/2} \\ … … 204 253 \end{alignat} 205 254 206 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 207 257 $(\overline{\cdots}^{\, i})^* = \overline{\cdots}^{\, i + 1/2}$, respectively. 208 These two properties will be used extensively in the \autoref{apdx: C} to258 These two properties will be used extensively in the \autoref{apdx:INVARIANTS} to 209 259 demonstrate integral conservative properties of the discrete formulation chosen. 210 260 211 % ------------------------------------------------------------------------------------------------------------- 212 % Numerical Indexing 213 % ------------------------------------------------------------------------------------------------------------- 261 %% ================================================================================================= 214 262 \subsection{Numerical indexing} 215 263 \label{subsec:DOM_Num_Index} 216 264 217 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 218 \begin{figure}[!tb] 219 \begin{center} 220 \includegraphics[]{Fig_index_hor} 221 \caption{ 222 \protect\label{fig:index_hor} 223 Horizontal integer indexing used in the \fortran code. 224 The dashed area indicates the cell in which variables contained in arrays have the same $i$- and $j$-indices 225 } 226 \end{center} 265 \begin{figure} 266 \centering 267 \includegraphics[width=0.33\textwidth]{DOM_index_hor} 268 \caption[Horizontal integer indexing]{ 269 Horizontal integer indexing used in the \fortran\ code. 270 The dashed area indicates the cell in which 271 variables contained in arrays have the same $i$- and $j$-indices} 272 \label{fig:DOM_index_hor} 227 273 \end{figure} 228 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 229 230 The array representation used in the \fortran code requires an integer indexing while 231 the analytical definition of the mesh (see \autoref{subsec:DOM_cell}) is associated with the use of 232 integer values for $t$-points and both integer and integer and a half values for all the other points. 233 Therefore a specific integer indexing must be defined for points other than $t$-points 234 (\ie velocity and vorticity grid-points). 235 Furthermore, the direction of the vertical indexing has been changed so that the surface level is at $k = 1$. 236 237 % ----------------------------------- 238 % Horizontal Indexing 239 % ----------------------------------- 274 275 The array representation used in the \fortran\ code requires an integer indexing. 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. 279 Therefore, a specific integer indexing has been defined for points other than $t$-points 280 (\ie\ velocity and vorticity grid-points). 281 Furthermore, the direction of the vertical indexing has been reversed and 282 the surface level set at $k = 1$. 283 284 %% ================================================================================================= 240 285 \subsubsection{Horizontal indexing} 241 286 \label{subsec:DOM_Num_Index_hor} 242 287 243 The indexing in the horizontal plane has been chosen as shown in \autoref{fig: index_hor}.288 The indexing in the horizontal plane has been chosen as shown in \autoref{fig:DOM_index_hor}. 244 289 For an increasing $i$ index ($j$ index), 245 290 the $t$-point and the eastward $u$-point (northward $v$-point) have the same index 246 (see the dashed area in \autoref{fig:index_hor}). 247 A $t$-point and its nearest northeast $f$-point have the same $i$-and $j$-indices. 248 249 % ----------------------------------- 250 % Vertical indexing 251 % ----------------------------------- 291 (see the dashed area in \autoref{fig:DOM_index_hor}). 292 A $t$-point and its nearest north-east $f$-point have the same $i$-and $j$-indices. 293 294 %% ================================================================================================= 252 295 \subsubsection{Vertical indexing} 253 296 \label{subsec:DOM_Num_Index_vertical} 254 297 255 In the vertical, the chosen indexing requires special attention since the $k$-axis is re-orientated downward in 256 the \fortran code compared to the indexing used in the semi -discrete equations and 257 given in \autoref{subsec:DOM_cell}. 258 The sea surface corresponds to the $w$-level $k = 1$ which is the same index as $t$-level just below 259 (\autoref{fig:index_vert}). 260 The last $w$-level ($k = jpk$) either corresponds to the ocean floor or is inside the bathymetry while 261 the last $t$-level is always inside the bathymetry (\autoref{fig:index_vert}). 262 Note that for an increasing $k$ index, a $w$-point and the $t$-point just below have the same $k$ index, 263 in opposition to what is done in the horizontal plane where 264 it is the $t$-point and the nearest velocity points in the direction of the horizontal axis that 265 have the same $i$ or $j$ index 266 (compare the dashed area in \autoref{fig:index_hor} and \autoref{fig: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}). 303 The last $w$-level ($k = jpk$) either corresponds to or is below the ocean floor while 304 the last $t$-level is always outside the ocean domain (\autoref{fig:DOM_index_vert}). 305 Note that a $w$-point and the directly underlaying $t$-point have a common $k$ index 306 (\ie\ $t$-points and their nearest $w$-point neighbour in negative index direction), 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 310 (compare the dashed area in \autoref{fig:DOM_index_hor} and \autoref{fig:DOM_index_vert}). 267 311 Since the scale factors are chosen to be strictly positive, 268 a \textit{minus sign} appears in the \fortran code \textit{before all the vertical derivatives} of 269 the discrete equations given in this documentation. 270 271 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 272 \begin{figure}[!pt] 273 \begin{center} 274 \includegraphics[]{Fig_index_vert} 275 \caption{ 276 \protect\label{fig:index_vert} 277 Vertical integer indexing used in the \fortran code. 278 Note that the $k$-axis is orientated downward. 279 The dashed area indicates the cell in which variables contained in arrays have the same $k$-index. 280 } 281 \end{center} 312 a \textit{minus sign} is included in the \fortran\ implementations of 313 \textit{all the vertical derivatives} of the discrete equations given in this manual in order to 314 accommodate the opposing vertical index directions in implementation and documentation. 315 316 \begin{figure} 317 \centering 318 \includegraphics[width=0.33\textwidth]{DOM_index_vert} 319 \caption[Vertical integer indexing]{ 320 Vertical integer indexing used in the \fortran\ code. 321 Note that the $k$-axis is oriented downward. 322 The dashed area indicates the cell in which 323 variables contained in arrays have a common $k$-index.} 324 \label{fig:DOM_index_vert} 282 325 \end{figure} 283 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 284 285 % ----------------------------------- 286 % Domain Size 287 % ----------------------------------- 288 \subsubsection{Domain size} 326 327 %% ================================================================================================= 328 \section{Spatial domain configuration} 329 \label{subsec:DOM_config} 330 331 Two typical methods are available to specify the spatial domain configuration; 332 they can be selected using parameter \np{ln_read_cfg}{ln\_read\_cfg} parameter in 333 namelist \nam{cfg}{cfg}. 334 335 If \np{ln_read_cfg}{ln\_read\_cfg} is set to \forcode{.true.}, 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}. 339 340 If \np{ln_read_cfg}{ln\_read\_cfg} is set to \forcode{.false.}, 341 the domain-specific parameters and fields can be provided (\eg\ analytically computed) by 342 subroutines \mdl{usrdef\_hgr} and \mdl{usrdef\_zgr}. 343 These subroutines can be supplied in the \path{MY_SRC} directory of the configuration, 344 and default versions that configure the spatial domain for the GYRE reference configuration are 345 present in the \path{./src/OCE/USR} directory. 346 347 In version 4.0 there are no longer any options for reading complex bathymetries and 348 performing a vertical discretisation at run-time. 349 Whilst it is occasionally convenient to have a common bathymetry file and, for example, 350 to run similar models with and without partial bottom boxes and/or sigma-coordinates, 351 supporting such choices leads to overly complex code. 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. 362 The requirements are presented in three sections: 363 the domain size (\autoref{subsec:DOM_size}), the horizontal mesh (\autoref{subsec:DOM_hgr}), 364 and the vertical grid (\autoref{subsec:DOM_zgr}). 365 366 %% ================================================================================================= 367 \subsection{Domain size} 289 368 \label{subsec:DOM_size} 290 369 291 The total size of the computational domain is set by the parameters \np{jpiglo}, 292 \np{jpjglo} and \np{jpkglo} in the $i$, $j$ and $k$ directions respectively. 293 Parameters $jpi$ and $jpj$ refer to the size of each processor subdomain when 294 the code is run in parallel using domain decomposition (\key{mpp\_mpi} defined, 295 see \autoref{sec:LBC_mpp}). 296 297 % ================================================================ 298 % Domain: List of fields needed 299 % ================================================================ 300 \section{Needed fields} 301 \label{sec:DOM_fields} 302 The ocean mesh (\ie the position of all the scalar and vector points) is defined by the transformation that 303 gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. 304 The grid-points are located at integer or integer and a half values of as indicated in \autoref{tab:cell}. 305 The associated scale factors are defined using the analytical first derivative of the transformation 306 \autoref{eq:scale_factors}. 307 Necessary fields for configuration definition are: 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}). 375 376 The name of the configuration is set through parameter \np{cn_cfg}{cn\_cfg}, 377 and the nominal resolution through parameter \np{nn_cfg}{nn\_cfg} 378 (unless in the input file both of variables \texttt{ORCA} and \texttt{ORCA\_index} are present, 379 in which case \np{cn_cfg}{cn\_cfg} and \np{nn_cfg}{nn\_cfg} are set from these values accordingly). 380 381 The global lateral boundary condition type is selected from 8 options using parameter \jp{jperio}. 382 See \autoref{sec:LBC_jperio} for details on the available options and 383 the corresponding values for \jp{jperio}. 384 385 %% ================================================================================================= 386 \subsection[Horizontal grid mesh (\textit{domhgr.F90}]{Horizontal grid mesh (\protect\mdl{domhgr})} 387 \label{subsec:DOM_hgr} 388 389 %% ================================================================================================= 390 \subsubsection{Required fields} 391 \label{sec:DOM_hgr_fields} 392 393 The explicit specification of a range of mesh-related fields are required for 394 the definition of a configuration. 395 These include: 396 397 \begin{clines} 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 */ 404 \end{clines} 405 406 The values of the geographic longitude and latitude arrays at indices $i,j$ correspond to 407 the analytical expressions of the longitude $\lambda$ and latitude $\varphi$ as a function of $(i,j)$, 408 evaluated at the values as specified in \autoref{tab:DOM_cell} for the respective grid-point position. 409 The calculation of the values of the horizontal scale factor arrays in general additionally involves 410 partial derivatives of $\lambda$ and $\varphi$ with respect to $i$ and $j$, 411 evaluated for the same arguments as $\lambda$ and $\varphi$. 412 413 %% ================================================================================================= 414 \subsubsection{Optional fields} 415 416 \begin{clines} 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) */ 421 \end{clines} 422 423 \NEMO\ can support the local reduction of key strait widths by 424 altering individual values of e2u or e1v at the appropriate locations. 425 This is particularly useful for locations such as Gibraltar or Indonesian Throughflow pinch-points 426 (see \autoref{sec:MISC_strait} for illustrated examples). 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 429 not the volume of the cells. 430 Doing otherwise can lead to numerical instability issues. 431 In normal operation the surface areas are computed from $e1u * e2u$ and $e1v * e2v$ but 432 in cases where a gridsize reduction is required, 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: 439 \texttt{ie1e2u\_v} to a non-zero value to suppress their re-computation. 440 441 \smallskip 442 Similar logic applies to the other optional fields: 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: 449 \texttt{iff} to a non-zero value to suppress their re-computation. 450 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. 453 454 %% ================================================================================================= 455 \subsection[Vertical grid (\textit{domzgr.F90})]{Vertical grid (\protect\mdl{domzgr})} 456 \label{subsec:DOM_zgr} 457 458 \begin{listing} 459 \nlst{namdom} 460 \caption{\forcode{&namdom}} 461 \label{lst:namdom} 462 \end{listing} 463 464 In the vertical, the model mesh is determined by four things: 465 \begin{enumerate} 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. 472 \end{enumerate} 473 474 \begin{figure} 475 \centering 476 \includegraphics[width=0.5\textwidth]{DOM_z_zps_s_sps} 477 \caption[Ocean bottom regarding coordinate systems ($z$, $s$ and hybrid $s-z$)]{ 478 The ocean bottom as seen by the model: 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).} 489 \label{fig:DOM_z_zps_s_sps} 490 \end{figure} 491 492 The choice of a vertical coordinate is made when setting up the configuration; 493 it is not intended to be an option which can be changed in the middle of an experiment. 494 The one exception to this statement being the choice of linear or 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. 497 This is computationally wasteful since it uses the structures for time-varying 3D metrics 498 for fields that (in the linear free surface case) are fixed. 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 510 (in other words, the top of the ocean in not a rigid lid). 511 512 Note that settings: 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. 516 Their value is written to and read from the domain configuration file and 517 they should be treated as fixed parameters for a particular configuration. 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. 521 These values should not be altered in the \np{cn_domcfg}{cn\_domcfg} file. 522 523 \medskip 524 The decision on these choices must be made when the \np{cn_domcfg}{cn\_domcfg} file is constructed. 525 Three main choices are offered (\autoref{fig:DOM_z_zps_s_sps}a-c): 308 526 309 527 \begin{itemize} 310 \item 311 Geographic position: 312 longitude with \texttt{glamt}, \texttt{glamu}, \texttt{glamv}, \texttt{glamf} and 313 latitude with \texttt{gphit}, \texttt{gphiu}, \texttt{gphiv}, \texttt{gphif} 314 (all respectively at T, U, V and F point) 315 \item 316 Coriolis parameter (if domain not on the sphere): \texttt{ff\_f} and \texttt{ff\_t} 317 (at T and F point) 318 \item 319 Scale factors: 320 \texttt{e1t}, \texttt{e1u}, \texttt{e1v} and \texttt{e1f} (on i direction), 321 \texttt{e2t}, \texttt{e2u}, \texttt{e2v} and \texttt{e2f} (on j direction) and 322 \texttt{ie1e2u\_v}, \texttt{e1e2u}, \texttt{e1e2v}. \\ 323 \texttt{e1e2u}, \texttt{e1e2v} are u and v surfaces (if gridsize reduction in some straits), 324 \texttt{ie1e2u\_v} is to flag set u and v surfaces are neither read nor computed. 528 \item $z$-coordinate with full step bathymetry (\np[=.true.]{ln_zco}{ln\_zco}), 529 \item $z$-coordinate with partial step ($zps$) bathymetry (\np[=.true.]{ln_zps}{ln\_zps}), 530 \item Generalized, $s$-coordinate (\np[=.true.]{ln_sco}{ln\_sco}). 325 531 \end{itemize} 326 327 These fields can be read in an domain input file which name is setted in \np{cn\_domcfg} parameter specified in 328 \ngn{namcfg}. 329 330 \nlst{namcfg} 331 332 Or they can be defined in an analytical way in \path{MY_SRC} directory of the configuration. 333 For Reference Configurations of NEMO input domain files are supplied by NEMO System Team. 334 For analytical definition of input fields two routines are supplied: \mdl{usrdef\_hgr} and \mdl{usrdef\_zgr}. 335 They are an example of GYRE configuration parameters, and they are available in \path{src/OCE/USR} directory, 336 they provide the horizontal and vertical mesh. 337 % ------------------------------------------------------------------------------------------------------------- 338 % Needed fields 339 % ------------------------------------------------------------------------------------------------------------- 340 %\subsection{List of needed fields to build DOMAIN} 341 %\label{subsec:DOM_fields_list} 342 343 344 % ================================================================ 345 % Domain: Horizontal Grid (mesh) 346 % ================================================================ 347 \section{Horizontal grid mesh (\protect\mdl{domhgr})} 348 \label{sec:DOM_hgr} 349 350 % ------------------------------------------------------------------------------------------------------------- 351 % Coordinates and scale factors 352 % ------------------------------------------------------------------------------------------------------------- 353 \subsection{Coordinates and scale factors} 354 \label{subsec:DOM_hgr_coord_e} 355 356 The ocean mesh (\ie the position of all the scalar and vector points) is defined by 357 the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. 358 The grid-points are located at integer or integer and a half values of as indicated in \autoref{tab:cell}. 359 The associated scale factors are defined using the analytical first derivative of the transformation 360 \autoref{eq:scale_factors}. 361 These definitions are done in two modules, \mdl{domhgr} and \mdl{domzgr}, 362 which provide the horizontal and vertical meshes, respectively. 363 This section deals with the horizontal mesh parameters. 364 365 In a horizontal plane, the location of all the model grid points is defined from 366 the analytical expressions of the longitude $\lambda$ and latitude $\varphi$ as a function of $(i,j)$. 367 The horizontal scale factors are calculated using \autoref{eq:scale_factors}. 368 For example, when the longitude and latitude are function of a single value 369 ($i$ and $j$, respectively) (geographical configuration of the mesh), 370 the horizontal mesh definition reduces to define the wanted $\lambda(i)$, $\varphi(j)$, 371 and their derivatives $\lambda'(i) \ \varphi'(j)$ in the \mdl{domhgr} module. 372 The model computes the grid-point positions and scale factors in the horizontal plane as follows: 532 533 Additionally, hybrid combinations of the three main coordinates are available: 534 $s-z$ or $s-zps$ coordinate (\autoref{fig:DOM_z_zps_s_sps}d and \autoref{fig:DOM_z_zps_s_sps}e). 535 536 A further choice related to vertical coordinate concerns 537 the presence (or not) of ocean cavities beneath ice shelves within the model domain. 538 A setting of \np{ln_isfcav}{ln\_isfcav} as \forcode{.true.} indicates that 539 the domain contains ocean cavities, 540 otherwise the top, wet layer of the ocean will always be at the ocean surface. 541 This option is currently only available for $z$- or $zps$-coordinates. 542 In the latter case, partial steps are also applied at the ocean/ice shelf interface. 543 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. 548 The time at which they are defined is indicated by a suffix: $\_b$, $\_n$, or $\_a$, respectively. 549 They are updated at each model time step. 550 The initial fixed reference coordinate system is held in variable names with a $\_0$ suffix. 551 When the linear free surface option is used (\np[=.true.]{ln_linssh}{ln\_linssh}), 552 \textit{before}, \textit{now} and \textit{after} arrays are initially set to 553 their reference counterpart and remain fixed. 554 555 %% ================================================================================================= 556 \subsubsection{Required fields} 557 \label{sec:DOM_zgr_fields} 558 559 The explicit specification of a range of fields related to the vertical grid are required for 560 the definition of a configuration. 561 These include: 562 563 \begin{clines} 564 int ln_zco, ln_zps, ln_sco /* flags for z-coord, z-coord with partial steps and s-coord */ 565 int ln_isfcav /* flag for ice shelf cavities */ 566 double e3t_1d, e3w_1d /* reference vertical scale factors at T and W points */ 567 double e3t_0, e3u_0, e3v_0, e3f_0, e3w_0 /* vertical scale factors 3D coordinate at T,U,V,F and W points */ 568 double e3uw_0, e3vw_0 /* vertical scale factors 3D coordinate at UW and VW points */ 569 int bottom_level, top_level /* last wet T-points, 1st wet T-points (for ice shelf cavities) */ 570 /* For reference: */ 571 float bathy_metry /* bathymetry used in setting top and bottom levels */ 572 \end{clines} 573 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. 576 With constant z-levels, e3 metrics will be uniform across each horizontal level. 577 In the partial step case each e3 at the \jp{bottom\_level} 578 (and, possibly, \jp{top\_level} if ice cavities are present) 579 may vary from its horizontal neighbours. 580 And, in s-coordinates, variations can occur throughout the water column. 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. 583 These variations are typically much smaller than those arising from bottom fitted coordinates. 584 The values for vertical metrics supplied in the domain configuration file can be considered as 585 those arising from a flat sea surface with zero elevation. 586 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. 589 Without ice cavities, \jp{top\_level} is essentially a land mask (0 on land; 1 everywhere else). 590 With ice cavities, \jp{top\_level} determines the first wet point below the overlying ice shelf. 591 592 %% ================================================================================================= 593 \subsubsection{Level bathymetry and mask} 594 \label{subsec:DOM_msk} 595 596 From \jp{top\_level} and \jp{bottom\_level} fields, the mask fields are defined as follows: 373 597 \begin{align*} 374 \lambda_t &\equiv \text{glamt} = \lambda (i ) 375 &\varphi_t &\equiv \text{gphit} = \varphi (j ) \\ 376 \lambda_u &\equiv \text{glamu} = \lambda (i + 1/2) 377 &\varphi_u &\equiv \text{gphiu} = \varphi (j ) \\ 378 \lambda_v &\equiv \text{glamv} = \lambda (i ) 379 &\varphi_v &\equiv \text{gphiv} = \varphi (j + 1/2) \\ 380 \lambda_f &\equiv \text{glamf} = \lambda (i + 1/2) 381 &\varphi_f &\equiv \text{gphif} = \varphi (j + 1/2) \\ 382 e_{1t} &\equiv \text{e1t} = r_a |\lambda'(i ) \; \cos\varphi(j ) | 383 &e_{2t} &\equiv \text{e2t} = r_a |\varphi'(j ) | \\ 384 e_{1u} &\equiv \text{e1t} = r_a |\lambda'(i + 1/2) \; \cos\varphi(j ) | 385 &e_{2u} &\equiv \text{e2t} = r_a |\varphi'(j ) | \\ 386 e_{1v} &\equiv \text{e1t} = r_a |\lambda'(i ) \; \cos\varphi(j + 1/2) | 387 &e_{2v} &\equiv \text{e2t} = r_a |\varphi'(j + 1/2) | \\ 388 e_{1f} &\equiv \text{e1t} = r_a |\lambda'(i + 1/2) \; \cos\varphi(j + 1/2) | 389 &e_{2f} &\equiv \text{e2t} = r_a |\varphi'(j + 1/2) | 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) 390 609 \end{align*} 391 where the last letter of each computational name indicates the grid point considered and 392 $r_a$ is the earth radius (defined in \mdl{phycst} along with all universal constants). 393 Note that the horizontal position of and scale factors at $w$-points are exactly equal to those of $t$-points, 394 thus no specific arrays are defined at $w$-points. 395 396 Note that the definition of the scale factors 397 (\ie as the analytical first derivative of the transformation that 398 gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$) 399 is specific to the \NEMO model \citep{Marti_al_JGR92}. 400 As an example, $e_{1t}$ is defined locally at a $t$-point, 401 whereas many other models on a C grid choose to define such a scale factor as 402 the distance between the $U$-points on each side of the $t$-point. 403 Relying on an analytical transformation has two advantages: 404 firstly, there is no ambiguity in the scale factors appearing in the discrete equations, 405 since they are first introduced in the continuous equations; 406 secondly, analytical transformations encourage good practice by the definition of smoothly varying grids 407 (rather than allowing the user to set arbitrary jumps in thickness between adjacent layers) \citep{Treguier1996}. 408 An example of the effect of such a choice is shown in \autoref{fig:zgr_e3}. 409 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 410 \begin{figure}[!t] 411 \begin{center} 412 \includegraphics[]{Fig_zgr_e3} 413 \caption{ 414 \protect\label{fig:zgr_e3} 415 Comparison of (a) traditional definitions of grid-point position and grid-size in the vertical, 416 and (b) analytically derived grid-point position and scale factors. 417 For both grids here, the same $w$-point depth has been chosen but 418 in (a) the $t$-points are set half way between $w$-points while 419 in (b) they are defined from an analytical function: 420 $z(k) = 5 \, (k - 1/2)^3 - 45 \, (k - 1/2)^2 + 140 \, (k - 1/2) - 150$. 421 Note the resulting difference between the value of the grid-size $\Delta_k$ and 422 those of the scale factor $e_k$. 423 } 424 \end{center} 425 \end{figure} 426 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 427 428 % ------------------------------------------------------------------------------------------------------------- 429 % Choice of horizontal grid 430 % ------------------------------------------------------------------------------------------------------------- 431 \subsection{Choice of horizontal grid} 432 \label{subsec:DOM_hgr_msh_choice} 433 434 % ------------------------------------------------------------------------------------------------------------- 435 % Grid files 436 % ------------------------------------------------------------------------------------------------------------- 437 \subsection{Output grid files} 438 \label{subsec:DOM_hgr_files} 439 440 All the arrays relating to a particular ocean model configuration (grid-point position, scale factors, masks) 441 can be saved in files if \np{nn\_msh} $\not = 0$ (namelist variable in \ngn{namdom}). 442 This can be particularly useful for plots and off-line diagnostics. 443 In some cases, the user may choose to make a local modification of a scale factor in the code. 444 This is the case in global configurations when restricting the width of a specific strait 445 (usually a one-grid-point strait that happens to be too wide due to insufficient model resolution). 446 An example is Gibraltar Strait in the ORCA2 configuration. 447 When such modifications are done, 448 the output grid written when \np{nn\_msh} $\not = 0$ is no more equal to the input grid. 449 450 % ================================================================ 451 % Domain: Vertical Grid (domzgr) 452 % ================================================================ 453 \section{Vertical grid (\protect\mdl{domzgr})} 454 \label{sec:DOM_zgr} 455 %-----------------------------------------nam_zgr & namdom------------------------------------------- 456 % 457 %\nlst{namzgr} 458 459 \nlst{namdom} 460 %------------------------------------------------------------------------------------------------------------- 461 462 Variables are defined through the \ngn{namzgr} and \ngn{namdom} namelists. 463 In the vertical, the model mesh is determined by four things: 464 (1) the bathymetry given in meters; 465 (2) the number of levels of the model (\jp{jpk}); 466 (3) the analytical transformation $z(i,j,k)$ and the vertical scale factors (derivatives of the transformation); and 467 (4) the masking system, \ie the number of wet model levels at each 468 $(i,j)$ column of points. 469 470 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 471 \begin{figure}[!tb] 472 \begin{center} 473 \includegraphics[]{Fig_z_zps_s_sps} 474 \caption{ 475 \protect\label{fig:z_zps_s_sps} 476 The ocean bottom as seen by the model: 477 (a) $z$-coordinate with full step, 478 (b) $z$-coordinate with partial step, 479 (c) $s$-coordinate: terrain following representation, 480 (d) hybrid $s-z$ coordinate, 481 (e) hybrid $s-z$ coordinate with partial step, and 482 (f) same as (e) but in the non-linear free surface (\protect\np{ln\_linssh}~\forcode{= .false.}). 483 Note that the non-linear free surface can be used with any of the 5 coordinates (a) to (e). 484 } 485 \end{center} 486 \end{figure} 487 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 488 489 The choice of a vertical coordinate, even if it is made through \ngn{namzgr} namelist parameters, 490 must be done once of all at the beginning of an experiment. 491 It is not intended as an option which can be enabled or disabled in the middle of an experiment. 492 Three main choices are offered (\autoref{fig:z_zps_s_sps}): 493 $z$-coordinate with full step bathymetry (\np{ln\_zco}~\forcode{= .true.}), 494 $z$-coordinate with partial step bathymetry (\np{ln\_zps}~\forcode{= .true.}), 495 or generalized, $s$-coordinate (\np{ln\_sco}~\forcode{= .true.}). 496 Hybridation of the three main coordinates are available: 497 $s-z$ or $s-zps$ coordinate (\autoref{fig:z_zps_s_sps} and \autoref{fig:z_zps_s_sps}). 498 By default a non-linear free surface is used: the coordinate follow the time-variation of the free surface so that 499 the transformation is time dependent: $z(i,j,k,t)$ (\autoref{fig:z_zps_s_sps}). 500 When a linear free surface is assumed (\np{ln\_linssh}~\forcode{= .true.}), 501 the vertical coordinate are fixed in time, but the seawater can move up and down across the $z_0$ surface 502 (in other words, the top of the ocean in not a rigid-lid). 503 The last choice in terms of vertical coordinate concerns the presence (or not) in 504 the model domain of ocean cavities beneath ice shelves. 505 Setting \np{ln\_isfcav} to true allows to manage ocean cavities, otherwise they are filled in. 506 This option is currently only available in $z$- or $zps$-coordinate, 507 and partial step are also applied at the ocean/ice shelf interface. 508 509 Contrary to the horizontal grid, the vertical grid is computed in the code and no provision is made for 510 reading it from a file. 511 The only input file is the bathymetry (in meters) (\ifile{bathy\_meter}) 512 \footnote{ 513 N.B. in full step $z$-coordinate, a \ifile{bathy\_level} file can replace the \ifile{bathy\_meter} file, 514 so that the computation of the number of wet ocean point in each water column is by-passed}. 515 If \np{ln\_isfcav}~\forcode{= .true.}, an extra file input file (\ifile{isf\_draft\_meter}) describing 516 the ice shelf draft (in meters) is needed. 517 518 After reading the bathymetry, the algorithm for vertical grid definition differs between the different options: 519 \begin{description} 520 \item[\textit{zco}] 521 set a reference coordinate transformation $z_0(k)$, and set $z(i,j,k,t) = z_0(k)$. 522 \item[\textit{zps}] 523 set a reference coordinate transformation $z_0(k)$, and calculate the thickness of the deepest level at 524 each $(i,j)$ point using the bathymetry, to obtain the final three-dimensional depth and scale factor arrays. 525 \item[\textit{sco}] 526 smooth the bathymetry to fulfill the hydrostatic consistency criteria and 527 set the three-dimensional transformation. 528 \item[\textit{s-z} and \textit{s-zps}] 529 smooth the bathymetry to fulfill the hydrostatic consistency criteria and 530 set the three-dimensional transformation $z(i,j,k)$, 531 and possibly introduce masking of extra land points to better fit the original bathymetry file. 532 \end{description} 533 %%% 534 \gmcomment{ add the description of the smoothing: envelop topography...} 535 %%% 536 537 Unless a linear free surface is used (\np{ln\_linssh}~\forcode{= .false.}), 538 the arrays describing the grid point depths and vertical scale factors are three set of 539 three dimensional arrays $(i,j,k)$ defined at \textit{before}, \textit{now} and \textit{after} time step. 540 The time at which they are defined is indicated by a suffix: $\_b$, $\_n$, or $\_a$, respectively. 541 They are updated at each model time step using a fixed reference coordinate system which 542 computer names have a $\_0$ suffix. 543 When the linear free surface option is used (\np{ln\_linssh}~\forcode{= .true.}), \textit{before}, 544 \textit{now} and \textit{after} arrays are simply set one for all to their reference counterpart. 545 546 % ------------------------------------------------------------------------------------------------------------- 547 % Meter Bathymetry 548 % ------------------------------------------------------------------------------------------------------------- 549 \subsection{Meter bathymetry} 550 \label{subsec:DOM_bathy} 551 552 Three options are possible for defining the bathymetry, according to the namelist variable \np{nn\_bathy} 553 (found in \ngn{namdom} namelist): 554 \begin{description} 555 \item[\np{nn\_bathy}~\forcode{= 0}]: 556 a flat-bottom domain is defined. 557 The total depth $z_w (jpk)$ is given by the coordinate transformation. 558 The domain can either be a closed basin or a periodic channel depending on the parameter \np{jperio}. 559 \item[\np{nn\_bathy}~\forcode{= -1}]: 560 a domain with a bump of topography one third of the domain width at the central latitude. 561 This is meant for the "EEL-R5" configuration, a periodic or open boundary channel with a seamount. 562 \item[\np{nn\_bathy}~\forcode{= 1}]: 563 read a bathymetry and ice shelf draft (if needed). 564 The \ifile{bathy\_meter} file (Netcdf format) provides the ocean depth (positive, in meters) at 565 each grid point of the model grid. 566 The bathymetry is usually built by interpolating a standard bathymetry product (\eg ETOPO2) onto 567 the horizontal ocean mesh. 568 Defining the bathymetry also defines the coastline: where the bathymetry is zero, 569 no model levels are defined (all levels are masked). 570 571 The \ifile{isfdraft\_meter} file (Netcdf format) provides the ice shelf draft (positive, in meters) at 572 each grid point of the model grid. 573 This file is only needed if \np{ln\_isfcav}~\forcode{= .true.}. 574 Defining the ice shelf draft will also define the ice shelf edge and the grounding line position. 575 \end{description} 576 577 When a global ocean is coupled to an atmospheric model it is better to represent all large water bodies 578 (\eg great lakes, Caspian sea...) even if the model resolution does not allow their communication with 579 the rest of the ocean. 610 611 Note that, without ice shelves cavities, 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) 616 exactly in the same way as for the bottom boundary. 617 618 %% The specification of closed lateral boundaries requires that at least 619 %% the first and last rows and columns of the \textit{mbathy} array are set to zero. 620 %% In the particular case of an east-west cyclical boundary condition, \textit{mbathy} has its last column equal to 621 %% the second one and its first column equal to the last but one (and so too the mask arrays) 622 %% (see \autoref{fig:LBC_jperio}). 623 624 % Closed seas 625 %% ================================================================================================= 626 \subsection{Closed seas} 627 \label{subsec:DOM_closea} 628 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. 580 632 This is unnecessary when the ocean is forced by fixed atmospheric conditions, 581 633 so these seas can be removed from the ocean domain. 582 The user has the option to set the bathymetry in closed seas to zero (see \autoref{sec:MISC_closea}), 583 but the code has to be adapted to the user's configuration. 584 585 % ------------------------------------------------------------------------------------------------------------- 586 % z-coordinate and reference coordinate transformation 587 % ------------------------------------------------------------------------------------------------------------- 588 \subsection[$Z$-coordinate (\protect\np{ln\_zco}~\forcode{= .true.}) and ref. coordinate] 589 {$Z$-coordinate (\protect\np{ln\_zco}~\forcode{= .true.}) and reference coordinate} 590 \label{subsec:DOM_zco} 591 592 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 593 \begin{figure}[!tb] 594 \begin{center} 595 \includegraphics[]{Fig_zgr} 596 \caption{ 597 \protect\label{fig:zgr} 598 Default vertical mesh for ORCA2: 30 ocean levels (L30). 599 Vertical level functions for (a) T-point depth and (b) the associated scale factor as computed from 600 \autoref{eq:DOM_zgr_ana_1} using \autoref{eq:DOM_zgr_coef} in $z$-coordinate. 601 } 602 \end{center} 603 \end{figure} 604 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 605 606 The reference coordinate transformation $z_0(k)$ defines the arrays $gdept_0$ and $gdepw_0$ for $t$- and $w$-points, 607 respectively. 608 As indicated on \autoref{fig:index_vert} \jp{jpk} is the number of $w$-levels. 609 $gdepw_0(1)$ is the ocean surface. 610 There are at most \jp{jpk}-1 $t$-points inside the ocean, 611 the additional $t$-point at $jk = jpk$ is below the sea floor and is not used. 612 The vertical location of $w$- and $t$-levels is defined from the analytic expression of the depth $z_0(k)$ whose 613 analytical derivative with respect to $k$ provides the vertical scale factors. 614 The user must provide the analytical expression of both $z_0$ and its first derivative with respect to $k$. 615 This is done in routine \mdl{domzgr} through statement functions, 616 using parameters provided in the \ngn{namcfg} namelist. 617 618 It is possible to define a simple regular vertical grid by giving zero stretching (\np{ppacr}~\forcode{= 0}). 619 In that case, the parameters \jp{jpk} (number of $w$-levels) and 620 \np{pphmax} (total ocean depth in meters) fully define the grid. 621 622 For climate-related studies it is often desirable to concentrate the vertical resolution near the ocean surface. 623 The following function is proposed as a standard for a $z$-coordinate (with either full or partial steps): 624 \begin{gather} 625 \label{eq:DOM_zgr_ana_1} 626 z_0 (k) = h_{sur} - h_0 \; k - \; h_1 \; \log \big[ \cosh ((k - h_{th}) / h_{cr}) \big] \\ 627 e_3^0(k) = \lt| - h_0 - h_1 \; \tanh \big[ (k - h_{th}) / h_{cr} \big] \rt| 628 \end{gather} 629 where $k = 1$ to \jp{jpk} for $w$-levels and $k = 1$ to $k = 1$ for $T-$levels. 630 Such an expression allows us to define a nearly uniform vertical location of levels at the ocean top and bottom with 631 a smooth hyperbolic tangent transition in between (\autoref{fig:zgr}). 632 633 If the ice shelf cavities are opened (\np{ln\_isfcav}~\forcode{= .true.}), the definition of $z_0$ is the same. 634 However, definition of $e_3^0$ at $t$- and $w$-points is respectively changed to: 635 \begin{equation} 636 \label{eq:DOM_zgr_ana_2} 637 \begin{split} 638 e_3^T(k) &= z_W (k + 1) - z_W (k ) \\ 639 e_3^W(k) &= z_T (k ) - z_T (k - 1) 640 \end{split} 641 \end{equation} 642 This formulation decrease the self-generated circulation into the ice shelf cavity 643 (which can, in extreme case, leads to blow up).\\ 644 645 The most used vertical grid for ORCA2 has $10~m$ ($500~m$) resolution in the surface (bottom) layers and 646 a depth which varies from 0 at the sea surface to a minimum of $-5000~m$. 647 This leads to the following conditions: 648 \begin{equation} 649 \label{eq:DOM_zgr_coef} 650 \begin{array}{ll} 651 e_3 (1 + 1/2) = 10. & z(1 ) = 0. \\ 652 e_3 (jpk - 1/2) = 500. & z(jpk) = -5000. 653 \end{array} 654 \end{equation} 655 656 With the choice of the stretching $h_{cr} = 3$ and the number of levels \jp{jpk}~$= 31$, 657 the four coefficients $h_{sur}$, $h_0$, $h_1$, and $h_{th}$ in 658 \autoref{eq:DOM_zgr_ana_2} have been determined such that 659 \autoref{eq:DOM_zgr_coef} is satisfied, through an optimisation procedure using a bisection method. 660 For the first standard ORCA2 vertical grid this led to the following values: 661 $h_{sur} = 4762.96$, $h_0 = 255.58, h_1 = 245.5813$, and $h_{th} = 21.43336$. 662 The resulting depths and scale factors as a function of the model levels are shown in 663 \autoref{fig:zgr} and given in \autoref{tab:orca_zgr}. 664 Those values correspond to the parameters \np{ppsur}, \np{ppa0}, \np{ppa1}, \np{ppkth} in \ngn{namcfg} namelist. 665 666 Rather than entering parameters $h_{sur}$, $h_0$, and $h_1$ directly, it is possible to recalculate them. 667 In that case the user sets \np{ppsur}~$=$~\np{ppa0}~$=$~\np{ppa1}~$= 999999$., 668 in \ngn{namcfg} namelist, and specifies instead the four following parameters: 669 \begin{itemize} 670 \item 671 \np{ppacr}~$= h_{cr}$: stretching factor (nondimensional). 672 The larger \np{ppacr}, the smaller the stretching. 673 Values from $3$ to $10$ are usual. 674 \item 675 \np{ppkth}~$= h_{th}$: is approximately the model level at which maximum stretching occurs 676 (nondimensional, usually of order 1/2 or 2/3 of \jp{jpk}) 677 \item 678 \np{ppdzmin}: minimum thickness for the top layer (in meters). 679 \item 680 \np{pphmax}: total depth of the ocean (meters). 681 \end{itemize} 682 As an example, for the $45$ layers used in the DRAKKAR configuration those parameters are: 683 \jp{jpk}~$= 46$, \np{ppacr}~$= 9$, \np{ppkth}~$= 23.563$, \np{ppdzmin}~$= 6~m$, \np{pphmax}~$= 5750~m$. 684 685 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 686 \begin{table} 687 \begin{center} 688 \begin{tabular}{c||r|r|r|r} 689 \hline 690 \textbf{LEVEL} & \textbf{gdept\_1d} & \textbf{gdepw\_1d} & \textbf{e3t\_1d } & \textbf{e3w\_1d} \\ 691 \hline 692 1 & \textbf{ 5.00} & 0.00 & \textbf{ 10.00} & 10.00 \\ 693 \hline 694 2 & \textbf{ 15.00} & 10.00 & \textbf{ 10.00} & 10.00 \\ 695 \hline 696 3 & \textbf{ 25.00} & 20.00 & \textbf{ 10.00} & 10.00 \\ 697 \hline 698 4 & \textbf{ 35.01} & 30.00 & \textbf{ 10.01} & 10.00 \\ 699 \hline 700 5 & \textbf{ 45.01} & 40.01 & \textbf{ 10.01} & 10.01 \\ 701 \hline 702 6 & \textbf{ 55.03} & 50.02 & \textbf{ 10.02} & 10.02 \\ 703 \hline 704 7 & \textbf{ 65.06} & 60.04 & \textbf{ 10.04} & 10.03 \\ 705 \hline 706 8 & \textbf{ 75.13} & 70.09 & \textbf{ 10.09} & 10.06 \\ 707 \hline 708 9 & \textbf{ 85.25} & 80.18 & \textbf{ 10.17} & 10.12 \\ 709 \hline 710 10 & \textbf{ 95.49} & 90.35 & \textbf{ 10.33} & 10.24 \\ 711 \hline 712 11 & \textbf{ 105.97} & 100.69 & \textbf{ 10.65} & 10.47 \\ 713 \hline 714 12 & \textbf{ 116.90} & 111.36 & \textbf{ 11.27} & 10.91 \\ 715 \hline 716 13 & \textbf{ 128.70} & 122.65 & \textbf{ 12.47} & 11.77 \\ 717 \hline 718 14 & \textbf{ 142.20} & 135.16 & \textbf{ 14.78} & 13.43 \\ 719 \hline 720 15 & \textbf{ 158.96} & 150.03 & \textbf{ 19.23} & 16.65 \\ 721 \hline 722 16 & \textbf{ 181.96} & 169.42 & \textbf{ 27.66} & 22.78 \\ 723 \hline 724 17 & \textbf{ 216.65} & 197.37 & \textbf{ 43.26} & 34.30 \\ 725 \hline 726 18 & \textbf{ 272.48} & 241.13 & \textbf{ 70.88} & 55.21 \\ 727 \hline 728 19 & \textbf{ 364.30} & 312.74 & \textbf{ 116.11} & 90.99 \\ 729 \hline 730 20 & \textbf{ 511.53} & 429.72 & \textbf{ 181.55} & 146.43 \\ 731 \hline 732 21 & \textbf{ 732.20} & 611.89 & \textbf{ 261.03} & 220.35 \\ 733 \hline 734 22 & \textbf{ 1033.22} & 872.87 & \textbf{ 339.39} & 301.42 \\ 735 \hline 736 23 & \textbf{ 1405.70} & 1211.59 & \textbf{ 402.26} & 373.31 \\ 737 \hline 738 24 & \textbf{ 1830.89} & 1612.98 & \textbf{ 444.87} & 426.00 \\ 739 \hline 740 25 & \textbf{ 2289.77} & 2057.13 & \textbf{ 470.55} & 459.47 \\ 741 \hline 742 26 & \textbf{ 2768.24} & 2527.22 & \textbf{ 484.95} & 478.83 \\ 743 \hline 744 27 & \textbf{ 3257.48} & 3011.90 & \textbf{ 492.70} & 489.44 \\ 745 \hline 746 28 & \textbf{ 3752.44} & 3504.46 & \textbf{ 496.78} & 495.07 \\ 747 \hline 748 29 & \textbf{ 4250.40} & 4001.16 & \textbf{ 498.90} & 498.02 \\ 749 \hline 750 30 & \textbf{ 4749.91} & 4500.02 & \textbf{ 500.00} & 499.54 \\ 751 \hline 752 31 & \textbf{ 5250.23} & 5000.00 & \textbf{ 500.56} & 500.33 \\ 753 \hline 754 \end{tabular} 755 \end{center} 756 \caption{ 757 \protect\label{tab:orca_zgr} 758 Default vertical mesh in $z$-coordinate for 30 layers ORCA2 configuration as computed from 759 \autoref{eq:DOM_zgr_ana_2} using the coefficients given in \autoref{eq:DOM_zgr_coef} 760 } 761 \end{table} 762 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 763 764 % ------------------------------------------------------------------------------------------------------------- 765 % z-coordinate with partial step 766 % ------------------------------------------------------------------------------------------------------------- 767 \subsection{$Z$-coordinate with partial step (\protect\np{ln\_zps}~\forcode{= .true.})} 768 \label{subsec:DOM_zps} 769 %--------------------------------------------namdom------------------------------------------------------- 770 771 \nlst{namdom} 772 %-------------------------------------------------------------------------------------------------------------- 773 774 In $z$-coordinate partial step, 775 the depths of the model levels are defined by the reference analytical function $z_0(k)$ as described in 776 the previous section, \textit{except} in the bottom layer. 777 The thickness of the bottom layer is allowed to vary as a function of geographical location $(\lambda,\varphi)$ to 778 allow a better representation of the bathymetry, especially in the case of small slopes 779 (where the bathymetry varies by less than one level thickness from one grid point to the next). 780 The reference layer thicknesses $e_{3t}^0$ have been defined in the absence of bathymetry. 781 With partial steps, layers from 1 to \jp{jpk}-2 can have a thickness smaller than $e_{3t}(jk)$. 782 The model deepest layer (\jp{jpk}-1) is allowed to have either a smaller or larger thickness than $e_{3t}(jpk)$: 783 the maximum thickness allowed is $2*e_{3t}(jpk - 1)$. 784 This has to be kept in mind when specifying values in \ngn{namdom} namelist, 785 as the maximum depth \np{pphmax} in partial steps: 786 for example, with \np{pphmax}~$= 5750~m$ for the DRAKKAR 45 layer grid, 787 the maximum ocean depth allowed is actually $6000~m$ (the default thickness $e_{3t}(jpk - 1)$ being $250~m$). 788 Two variables in the namdom namelist are used to define the partial step vertical grid. 789 The mimimum water thickness (in meters) allowed for a cell partially filled with bathymetry at level jk is 790 the minimum of \np{rn\_e3zps\_min} (thickness in meters, usually $20~m$) or $e_{3t}(jk)*$\np{rn\_e3zps\_rat} 791 (a fraction, usually 10\%, of the default thickness $e_{3t}(jk)$). 792 793 \gmcomment{ \colorbox{yellow}{Add a figure here of pstep especially at last ocean level } } 794 795 % ------------------------------------------------------------------------------------------------------------- 796 % s-coordinate 797 % ------------------------------------------------------------------------------------------------------------- 798 \subsection{$S$-coordinate (\protect\np{ln\_sco}~\forcode{= .true.})} 799 \label{subsec:DOM_sco} 800 %------------------------------------------nam_zgr_sco--------------------------------------------------- 801 % 802 %\nlst{namzgr_sco} 803 %-------------------------------------------------------------------------------------------------------------- 804 Options are defined in \ngn{namzgr\_sco}. 805 In $s$-coordinate (\np{ln\_sco}~\forcode{= .true.}), the depth and thickness of the model levels are defined from 806 the product of a depth field and either a stretching function or its derivative, respectively: 807 808 \begin{align*} 809 % \label{eq:DOM_sco_ana} 810 z(k) &= h(i,j) \; z_0 (k) \\ 811 e_3(k) &= h(i,j) \; z_0'(k) 812 \end{align*} 813 814 where $h$ is the depth of the last $w$-level ($z_0(k)$) defined at the $t$-point location in the horizontal and 815 $z_0(k)$ is a function which varies from $0$ at the sea surface to $1$ at the ocean bottom. 816 The depth field $h$ is not necessary the ocean depth, 817 since a mixed step-like and bottom-following representation of the topography can be used 818 (\autoref{fig:z_zps_s_sps}) or an envelop bathymetry can be defined (\autoref{fig:z_zps_s_sps}). 819 The namelist parameter \np{rn\_rmax} determines the slope at which 820 the terrain-following coordinate intersects the sea bed and becomes a pseudo z-coordinate. 821 The coordinate can also be hybridised by specifying \np{rn\_sbot\_min} and \np{rn\_sbot\_max} as 822 the minimum and maximum depths at which the terrain-following vertical coordinate is calculated. 823 824 Options for stretching the coordinate are provided as examples, 825 but care must be taken to ensure that the vertical stretch used is appropriate for the application. 826 827 The original default NEMO s-coordinate stretching is available if neither of the other options are specified as true 828 (\np{ln\_s\_SH94}~\forcode{= .false.} and \np{ln\_s\_SF12}~\forcode{= .false.}). 829 This uses a depth independent $\tanh$ function for the stretching \citep{Madec_al_JPO96}: 830 831 \[ 832 z = s_{min} + C (s) (H - s_{min}) 833 % \label{eq:SH94_1} 834 \] 835 836 where $s_{min}$ is the depth at which the $s$-coordinate stretching starts and 837 allows a $z$-coordinate to placed on top of the stretched coordinate, 838 and $z$ is the depth (negative down from the asea surface). 839 \begin{gather*} 840 s = - \frac{k}{n - 1} \quad \text{and} \quad 0 \leq k \leq n - 1 841 % \label{eq:DOM_s} 842 \\ 843 % \label{eq:DOM_sco_function} 844 C(s) = \frac{[\tanh(\theta \, (s + b)) - \tanh(\theta \, b)]}{2 \; \sinh(\theta)} 845 \end{gather*} 846 847 A stretching function, 848 modified from the commonly used \citet{Song_Haidvogel_JCP94} stretching (\np{ln\_s\_SH94}~\forcode{= .true.}), 849 is also available and is more commonly used for shelf seas modelling: 850 851 \[ 852 C(s) = (1 - b) \frac{\sinh(\theta s)}{\sinh(\theta)} 853 + b \frac{\tanh \lt[ \theta \lt(s + \frac{1}{2} \rt) \rt] - \tanh \lt( \frac{\theta}{2} \rt)} 854 { 2 \tanh \lt( \frac{\theta}{2} \rt)} 855 % \label{eq:SH94_2} 856 \] 857 858 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 859 \begin{figure}[!ht] 860 \begin{center} 861 \includegraphics[]{Fig_sco_function} 862 \caption{ 863 \protect\label{fig:sco_function} 864 Examples of the stretching function applied to a seamount; 865 from left to right: surface, surface and bottom, and bottom intensified resolutions 866 } 867 \end{center} 868 \end{figure} 869 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 870 871 where $H_c$ is the critical depth (\np{rn\_hc}) at which the coordinate transitions from pure $\sigma$ to 872 the stretched coordinate, and $\theta$ (\np{rn\_theta}) and $b$ (\np{rn\_bb}) are the surface and 873 bottom control parameters such that $0 \leqslant \theta \leqslant 20$, and $0 \leqslant b \leqslant 1$. 874 $b$ has been designed to allow surface and/or bottom increase of the vertical resolution 875 (\autoref{fig:sco_function}). 876 877 Another example has been provided at version 3.5 (\np{ln\_s\_SF12}) that allows a fixed surface resolution in 878 an analytical terrain-following stretching \citet{Siddorn_Furner_OM12}. 879 In this case the a stretching function $\gamma$ is defined such that: 880 881 \begin{equation} 882 z = - \gamma h \quad \text{with} \quad 0 \leq \gamma \leq 1 883 % \label{eq:z} 884 \end{equation} 885 886 The function is defined with respect to $\sigma$, the unstretched terrain-following coordinate: 887 888 \begin{gather*} 889 % \label{eq:DOM_gamma_deriv} 890 \gamma = A \lt( \sigma - \frac{1}{2} (\sigma^2 + f (\sigma)) \rt) 891 + B \lt( \sigma^3 - f (\sigma) \rt) + f (\sigma) \\ 892 \intertext{Where:} 893 % \label{eq:DOM_gamma} 894 f(\sigma) = (\alpha + 2) \sigma^{\alpha + 1} - (\alpha + 1) \sigma^{\alpha + 2} 895 \quad \text{and} \quad \sigma = \frac{k}{n - 1} 896 \end{gather*} 897 898 This gives an analytical stretching of $\sigma$ that is solvable in $A$ and $B$ as a function of 899 the user prescribed stretching parameter $\alpha$ (\np{rn\_alpha}) that stretches towards 900 the surface ($\alpha > 1.0$) or the bottom ($\alpha < 1.0$) and 901 user prescribed surface (\np{rn\_zs}) and bottom depths. 902 The bottom cell depth in this example is given as a function of water depth: 903 904 \[ 905 % \label{eq:DOM_zb} 906 Z_b = h a + b 907 \] 908 909 where the namelist parameters \np{rn\_zb\_a} and \np{rn\_zb\_b} are $a$ and $b$ respectively. 910 911 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 912 \begin{figure}[!ht] 913 \includegraphics[]{Fig_DOM_compare_coordinates_surface} 914 \caption{ 915 A comparison of the \citet{Song_Haidvogel_JCP94} $S$-coordinate (solid lines), 916 a 50 level $Z$-coordinate (contoured surfaces) and 917 the \citet{Siddorn_Furner_OM12} $S$-coordinate (dashed lines) in the surface $100~m$ for 918 a idealised bathymetry that goes from $50~m$ to $5500~m$ depth. 919 For clarity every third coordinate surface is shown. 920 } 921 \label{fig:fig_compare_coordinates_surface} 922 \end{figure} 923 % >>>>>>>>>>>>>>>>>>>>>>>>>>>> 924 925 This gives a smooth analytical stretching in computational space that is constrained to 926 given specified surface and bottom grid cell thicknesses in real space. 927 This is not to be confused with the hybrid schemes that 928 superimpose geopotential coordinates on terrain following coordinates thus 929 creating a non-analytical vertical coordinate that 930 therefore may suffer from large gradients in the vertical resolutions. 931 This stretching is less straightforward to implement than the \citet{Song_Haidvogel_JCP94} stretching, 932 but has the advantage of resolving diurnal processes in deep water and has generally flatter slopes. 933 934 As with the \citet{Song_Haidvogel_JCP94} stretching the stretch is only applied at depths greater than 935 the critical depth $h_c$. 936 In this example two options are available in depths shallower than $h_c$, 937 with pure sigma being applied if the \np{ln\_sigcrit} is true and pure z-coordinates if it is false 938 (the z-coordinate being equal to the depths of the stretched coordinate at $h_c$). 939 940 Minimising the horizontal slope of the vertical coordinate is important in terrain-following systems as 941 large slopes lead to hydrostatic consistency. 942 A hydrostatic consistency parameter diagnostic following \citet{Haney1991} has been implemented, 943 and is output as part of the model mesh file at the start of the run. 944 945 % ------------------------------------------------------------------------------------------------------------- 946 % z*- or s*-coordinate 947 % ------------------------------------------------------------------------------------------------------------- 948 \subsection{\zstar- or \sstar-coordinate (\protect\np{ln\_linssh}~\forcode{= .false.})} 949 \label{subsec:DOM_zgr_star} 950 951 This option is described in the Report by Levier \textit{et al.} (2007), available on the \NEMO web site. 952 953 %gm% key advantage: minimise the diffusion/dispertion associated with advection in response to high frequency surface disturbances 954 955 % ------------------------------------------------------------------------------------------------------------- 956 % level bathymetry and mask 957 % ------------------------------------------------------------------------------------------------------------- 958 \subsection{Level bathymetry and mask} 959 \label{subsec:DOM_msk} 960 961 Whatever the vertical coordinate used, the model offers the possibility of representing the bottom topography with 962 steps that follow the face of the model cells (step like topography) \citep{Madec_al_JPO96}. 963 The distribution of the steps in the horizontal is defined in a 2D integer array, mbathy, which 964 gives the number of ocean levels (\ie those that are not masked) at each $t$-point. 965 mbathy is computed from the meter bathymetry using the definiton of gdept as the number of $t$-points which 966 gdept $\leq$ bathy. 967 968 Modifications of the model bathymetry are performed in the \textit{bat\_ctl} routine (see \mdl{domzgr} module) after 969 mbathy is computed. 970 Isolated grid points that do not communicate with another ocean point at the same level are eliminated. 971 972 As for the representation of bathymetry, a 2D integer array, misfdep, is created. 973 misfdep defines the level of the first wet $t$-point. 974 All the cells between $k = 1$ and $misfdep(i,j) - 1$ are masked. 975 By default, $misfdep(:,:) = 1$ and no cells are masked. 976 977 In case of ice shelf cavities, modifications of the model bathymetry and ice shelf draft into 978 the cavities are performed in the \textit{zgr\_isf} routine. 979 The compatibility between ice shelf draft and bathymetry is checked. 980 All the locations where the isf cavity is thinnest than \np{rn\_isfhmin} meters are grounded (\ie masked). 981 If only one cell on the water column is opened at $t$-, $u$- or $v$-points, 982 the bathymetry or the ice shelf draft is dug to fit this constrain. 983 If the incompatibility is too strong (need to dig more than 1 cell), the cell is masked. 984 985 From the \textit{mbathy} and \textit{misfdep} array, the mask fields are defined as follows: 986 \begin{alignat*}{2} 987 tmask(i,j,k) &= & & 988 \begin{cases} 989 0 &\text{if $ k < misfdep(i,j)$} \\ 990 1 &\text{if $misfdep(i,j) \leq k \leq mbathy(i,j)$} \\ 991 0 &\text{if $ k > mbathy(i,j)$} 992 \end{cases} 993 \\ 994 umask(i,j,k) &= & &tmask(i,j,k) * tmask(i + 1,j, k) \\ 995 vmask(i,j,k) &= & &tmask(i,j,k) * tmask(i ,j + 1,k) \\ 996 fmask(i,j,k) &= & &tmask(i,j,k) * tmask(i + 1,j, k) \\ 997 & &* &tmask(i,j,k) * tmask(i + 1,j, k) \\ 998 wmask(i,j,k) &= & &tmask(i,j,k) * tmask(i ,j,k - 1) \\ 999 \text{with~} wmask(i,j,1) &= & &tmask(i,j,1) 1000 \end{alignat*} 1001 1002 Note that, without ice shelves cavities, 1003 masks at $t-$ and $w-$points are identical with the numerical indexing used (\autoref{subsec:DOM_Num_Index}). 1004 Nevertheless, $wmask$ are required with ocean cavities to deal with the top boundary (ice shelf/ocean interface) 1005 exactly in the same way as for the bottom boundary. 1006 1007 The specification of closed lateral boundaries requires that at least 1008 the first and last rows and columns of the \textit{mbathy} array are set to zero. 1009 In the particular case of an east-west cyclical boundary condition, \textit{mbathy} has its last column equal to 1010 the second one and its first column equal to the last but one (and so too the mask arrays) 1011 (see \autoref{fig:LBC_jperio}). 1012 1013 % ================================================================ 1014 % Domain: Initial State (dtatsd & istate) 1015 % ================================================================ 1016 \section{Initial state (\protect\mdl{istate} and \protect\mdl{dtatsd})} 1017 \label{sec:DTA_tsd} 1018 %-----------------------------------------namtsd------------------------------------------- 1019 1020 \nlst{namtsd} 1021 %------------------------------------------------------------------------------------------ 1022 1023 Options are defined in \ngn{namtsd}. 1024 By default, the ocean start from rest (the velocity field is set to zero) and the initialization of temperature and 1025 salinity fields is controlled through the \np{ln\_tsd\_ini} namelist parameter. 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. 640 Among the possibilities are: 641 642 \begin{clines} 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) */ 646 \end{clines} 647 648 %% ================================================================================================= 649 \subsection{Output grid files} 650 \label{subsec:DOM_meshmask} 651 652 Most of the arrays relating to a particular ocean model configuration discussed in this chapter 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.}; 656 the output filename is set through parameter \np{cn_domcfg_out}{cn\_domcfg\_out}. 657 This is only really useful if 658 the fields are computed in subroutines \mdl{usrdef\_hgr} or \mdl{usrdef\_zgr} and 659 checking or confirmation is required. 660 661 Alternatively, all the arrays relating to a particular ocean model configuration 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.}. 666 This file contains additional fields that can be useful for post-processing applications. 667 668 %% ================================================================================================= 669 \section[Initial state (\textit{istate.F90} and \textit{dtatsd.F90})]{Initial state (\protect\mdl{istate} and \protect\mdl{dtatsd})} 670 \label{sec:DOM_DTA_tsd} 671 672 \begin{listing} 673 \nlst{namtsd} 674 \caption{\forcode{&namtsd}} 675 \label{lst:namtsd} 676 \end{listing} 677 678 Basic initial state options are defined in \nam{tsd}{tsd}. 679 By default, the ocean starts from rest (the velocity field is set to zero) and 680 the initialization of temperature and salinity fields is controlled through the \np{ln_tsd_init}{ln\_tsd\_init} namelist parameter. 681 1026 682 \begin{description} 1027 \item [\np{ln\_tsd\_init}~\forcode{= .true.}]1028 use a T and S input files that can be given on the model grid itself or on their native input data 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. 1029 685 In the latter case, 1030 686 the data will be interpolated on-the-fly both in the horizontal and the vertical to the model grid 1031 687 (see \autoref{subsec:SBC_iof}). 1032 The information relative to the input files are given in the \np{sn\_tem} and \np{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. 1033 690 The computation is done in the \mdl{dtatsd} module. 1034 \item[\np{ln\_tsd\_init}~\forcode{= .false.}] 1035 use constant salinity value of $35.5~psu$ and an analytical profile of temperature 1036 (typical of the tropical ocean), see \rou{istate\_t\_s} subroutine called from \mdl{istate} module. 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}. 693 The default version sets horizontally uniform T and profiles as used in the GYRE configuration 694 (see \autoref{sec:CFGS_gyre}). 1037 695 \end{description} 1038 696 1039 \biblio 1040 1041 \pindex 697 \subinc{\input{../../global/epilogue}} 1042 698 1043 699 \end{document} -
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_DYN.tex
r10499 r11831 2 2 3 3 \begin{document} 4 % ================================================================ 5 % Chapter ——— Ocean Dynamics (DYN) 6 % ================================================================ 4 7 5 \chapter{Ocean Dynamics (DYN)} 8 6 \label{chap:DYN} 9 7 10 \minitoc 8 \thispagestyle{plain} 9 10 \chaptertoc 11 12 \paragraph{Changes record} ~\\ 13 14 {\footnotesize 15 \begin{tabularx}{\textwidth}{l||X|X} 16 Release & Author(s) & Modifications \\ 17 \hline 18 {\em 4.0} & {\em ...} & {\em ...} \\ 19 {\em 3.6} & {\em ...} & {\em ...} \\ 20 {\em 3.4} & {\em ...} & {\em ...} \\ 21 {\em <=3.4} & {\em ...} & {\em ...} 22 \end{tabularx} 23 } 24 25 \clearpage 11 26 12 27 Using the representation described in \autoref{chap:DOM}, … … 36 51 (surface wind stress calculation using bulk formulae, estimation of mixing coefficients) 37 52 that are carried out in modules SBC, LDF and ZDF and are described in 38 \autoref{chap:SBC}, \autoref{chap:LDF} and \autoref{chap:ZDF}, respectively. 53 \autoref{chap:SBC}, \autoref{chap:LDF} and \autoref{chap:ZDF}, respectively. 39 54 40 55 In the present chapter we also describe the diagnostic equations used to compute the horizontal divergence, 41 56 curl of the velocities (\emph{divcur} module) and the vertical velocity (\emph{wzvmod} module). 42 57 43 The different options available to the user are managed by namelist variables. 44 For term \textit{ttt} in the momentum equations, the logical namelist variables are \textit{ln\_dynttt\_xxx}, 58 The different options available to the user are managed by namelist variables. 59 For term \textit{ttt} in the momentum equations, the logical namelist variables are \textit{ln\_dynttt\_xxx}, 45 60 where \textit{xxx} is a 3 or 4 letter acronym corresponding to each optional scheme. 46 If a CPP key is used for this term its name is \key{ttt}.61 %If a CPP key is used for this term its name is \key{ttt}. 47 62 The corresponding code can be found in the \textit{dynttt\_xxx} module in the DYN directory, 48 63 and it is usually computed in the \textit{dyn\_ttt\_xxx} subroutine. 49 64 50 65 The user has the option of extracting and outputting each tendency term from the 3D momentum equations 51 (\ key{trddyn} defined), as described in \autoref{chap:MISC}.52 Furthermore, the tendency terms associated with the 2D barotropic vorticity balance (when \ key{trdvor} is defined)66 (\texttt{trddyn?} defined), as described in \autoref{chap:MISC}. 67 Furthermore, the tendency terms associated with the 2D barotropic vorticity balance (when \texttt{trdvor?} is defined) 53 68 can be derived from the 3D terms. 54 %%% 55 \gmcomment{STEVEN: not quite sure I've got the sense of the last sentence. does 56 MISC correspond to "extracting tendency terms" or "vorticity balance"?} 57 58 % ================================================================ 59 % Sea Surface Height evolution & Diagnostics variables 60 % ================================================================ 69 \cmtgm{STEVEN: not quite sure I've got the sense of the last sentence. 70 Does MISC correspond to "extracting tendency terms" or "vorticity balance"?} 71 72 %% ================================================================================================= 61 73 \section{Sea surface height and diagnostic variables ($\eta$, $\zeta$, $\chi$, $w$)} 62 74 \label{sec:DYN_divcur_wzv} 63 75 64 %-------------------------------------------------------------------------------------------------------------- 65 % Horizontal divergence and relative vorticity 66 %-------------------------------------------------------------------------------------------------------------- 67 \subsection{Horizontal divergence and relative vorticity (\protect\mdl{divcur})} 76 %% ================================================================================================= 77 \subsection[Horizontal divergence and relative vorticity (\textit{divcur.F90})]{Horizontal divergence and relative vorticity (\protect\mdl{divcur})} 68 78 \label{subsec:DYN_divcur} 69 79 70 The vorticity is defined at an $f$-point (\ie corner point) as follows:71 \begin{equation} 72 \label{eq: divcur_cur}80 The vorticity is defined at an $f$-point (\ie\ corner point) as follows: 81 \begin{equation} 82 \label{eq:DYN_divcur_cur} 73 83 \zeta =\frac{1}{e_{1f}\,e_{2f} }\left( {\;\delta_{i+1/2} \left[ {e_{2v}\;v} \right] 74 84 -\delta_{j+1/2} \left[ {e_{1u}\;u} \right]\;} \right) 75 \end{equation} 85 \end{equation} 76 86 77 87 The horizontal divergence is defined at a $T$-point. 78 88 It is given by: 79 89 \[ 80 % \label{eq: divcur_div}90 % \label{eq:DYN_divcur_div} 81 91 \chi =\frac{1}{e_{1t}\,e_{2t}\,e_{3t} } 82 92 \left( {\delta_i \left[ {e_{2u}\,e_{3u}\,u} \right] … … 96 106 ensure perfect restartability. 97 107 The vorticity and divergence at the \textit{now} time step are used for the computation of 98 the nonlinear advection and of the vertical velocity respectively. 99 100 %-------------------------------------------------------------------------------------------------------------- 101 % Sea Surface Height evolution 102 %-------------------------------------------------------------------------------------------------------------- 103 \subsection{Horizontal divergence and relative vorticity (\protect\mdl{sshwzv})} 108 the nonlinear advection and of the vertical velocity respectively. 109 110 %% ================================================================================================= 111 \subsection[Horizontal divergence and relative vorticity (\textit{sshwzv.F90})]{Horizontal divergence and relative vorticity (\protect\mdl{sshwzv})} 104 112 \label{subsec:DYN_sshwzv} 105 113 106 114 The sea surface height is given by: 107 115 \begin{equation} 108 \label{eq: dynspg_ssh}116 \label{eq:DYN_spg_ssh} 109 117 \begin{aligned} 110 118 \frac{\partial \eta }{\partial t} … … 115 123 \end{aligned} 116 124 \end{equation} 117 where \textit{emp} is the surface freshwater budget (evaporation minus precipitation), 125 where \textit{emp} is the surface freshwater budget (evaporation minus precipitation), 118 126 expressed in Kg/m$^2$/s (which is equal to mm/s), 119 127 and $\rho_w$=1,035~Kg/m$^3$ is the reference density of sea water (Boussinesq approximation). 120 128 If river runoff is expressed as a surface freshwater flux (see \autoref{chap:SBC}) then 121 \textit{emp} can be written as the evaporation minus precipitation, minus the river runoff. 129 \textit{emp} can be written as the evaporation minus precipitation, minus the river runoff. 122 130 The sea-surface height is evaluated using exactly the same time stepping scheme as 123 the tracer equation \autoref{eq: tra_nxt}:131 the tracer equation \autoref{eq:TRA_nxt}: 124 132 a leapfrog scheme in combination with an Asselin time filter, 125 \ie the velocity appearing in \autoref{eq:dynspg_ssh} is centred in time (\textit{now} velocity).133 \ie\ the velocity appearing in \autoref{eq:DYN_spg_ssh} is centred in time (\textit{now} velocity). 126 134 This is of paramount importance. 127 135 Replacing $T$ by the number $1$ in the tracer equation and summing over the water column must lead to 128 136 the sea surface height equation otherwise tracer content will not be conserved 129 \citep{ Griffies_al_MWR01, Leclair_Madec_OM09}.137 \citep{griffies.pacanowski.ea_MWR01, leclair.madec_OM09}. 130 138 131 139 The vertical velocity is computed by an upward integration of the horizontal divergence starting at the bottom, 132 140 taking into account the change of the thickness of the levels: 133 141 \begin{equation} 134 \label{eq: wzv}142 \label{eq:DYN_wzv} 135 143 \left\{ 136 144 \begin{aligned} … … 142 150 \end{equation} 143 151 144 In the case of a non-linear free surface (\ key{vvl}), the top vertical velocity is $-\textit{emp}/\rho_w$,152 In the case of a non-linear free surface (\texttt{vvl?}), the top vertical velocity is $-\textit{emp}/\rho_w$, 145 153 as changes in the divergence of the barotropic transport are absorbed into the change of the level thicknesses, 146 154 re-orientated downward. 147 \ gmcomment{not sure of this... to be modified with the change in emp setting}148 In the case of a linear free surface, the time derivative in \autoref{eq: wzv} disappears.155 \cmtgm{not sure of this... to be modified with the change in emp setting} 156 In the case of a linear free surface, the time derivative in \autoref{eq:DYN_wzv} disappears. 149 157 The upper boundary condition applies at a fixed level $z=0$. 150 158 The top vertical velocity is thus equal to the divergence of the barotropic transport 151 (\ie the first term in the right-hand-side of \autoref{eq:dynspg_ssh}).159 (\ie\ the first term in the right-hand-side of \autoref{eq:DYN_spg_ssh}). 152 160 153 161 Note also that whereas the vertical velocity has the same discrete expression in $z$- and $s$-coordinates, 154 162 its physical meaning is not the same: 155 163 in the second case, $w$ is the velocity normal to the $s$-surfaces. 156 Note also that the $k$-axis is re-orientated downwards in the \fortran code compared to 157 the indexing used in the semi-discrete equations such as \autoref{eq:wzv} 158 (see \autoref{subsec:DOM_Num_Index_vertical}). 159 160 161 % ================================================================ 162 % Coriolis and Advection terms: vector invariant form 163 % ================================================================ 164 Note also that the $k$-axis is re-orientated downwards in the \fortran\ code compared to 165 the indexing used in the semi-discrete equations such as \autoref{eq:DYN_wzv} 166 (see \autoref{subsec:DOM_Num_Index_vertical}). 167 168 %% ================================================================================================= 164 169 \section{Coriolis and advection: vector invariant form} 165 170 \label{sec:DYN_adv_cor_vect} 166 %-----------------------------------------nam_dynadv---------------------------------------------------- 167 168 \nlst{namdyn_adv} 169 %------------------------------------------------------------------------------------------------------------- 171 172 \begin{listing} 173 \nlst{namdyn_adv} 174 \caption{\forcode{&namdyn_adv}} 175 \label{lst:namdyn_adv} 176 \end{listing} 170 177 171 178 The vector invariant form of the momentum equations is the one most often used in 172 applications of the \NEMO ocean model.179 applications of the \NEMO\ ocean model. 173 180 The flux form option (see next section) has been present since version $2$. 174 Options are defined through the \n gn{namdyn\_adv} namelist variables Coriolis and181 Options are defined through the \nam{dyn_adv}{dyn\_adv} namelist variables Coriolis and 175 182 momentum advection terms are evaluated using a leapfrog scheme, 176 \ie the velocity appearing in these expressions is centred in time (\textit{now} velocity).183 \ie\ the velocity appearing in these expressions is centred in time (\textit{now} velocity). 177 184 At the lateral boundaries either free slip, no slip or partial slip boundary conditions are applied following 178 185 \autoref{chap:LBC}. 179 186 180 % ------------------------------------------------------------------------------------------------------------- 181 % Vorticity term 182 % ------------------------------------------------------------------------------------------------------------- 183 \subsection{Vorticity term (\protect\mdl{dynvor})} 187 %% ================================================================================================= 188 \subsection[Vorticity term (\textit{dynvor.F90})]{Vorticity term (\protect\mdl{dynvor})} 184 189 \label{subsec:DYN_vor} 185 %------------------------------------------nam_dynvor---------------------------------------------------- 186 187 \nlst{namdyn_vor} 188 %------------------------------------------------------------------------------------------------------------- 189 190 Options are defined through the \ngn{namdyn\_vor} namelist variables. 191 Four discretisations of the vorticity term (\np{ln\_dynvor\_xxx}\forcode{ = .true.}) are available: 190 191 \begin{listing} 192 \nlst{namdyn_vor} 193 \caption{\forcode{&namdyn_vor}} 194 \label{lst:namdyn_vor} 195 \end{listing} 196 197 Options are defined through the \nam{dyn_vor}{dyn\_vor} namelist variables. 198 Four discretisations of the vorticity term (\texttt{ln\_dynvor\_xxx}\forcode{=.true.}) are available: 192 199 conserving potential enstrophy of horizontally non-divergent flow (ENS scheme); 193 200 conserving horizontal kinetic energy (ENE scheme); … … 195 202 horizontal kinetic energy for the planetary vorticity term (MIX scheme); 196 203 or conserving both the potential enstrophy of horizontally non-divergent flow and horizontal kinetic energy 197 (EEN scheme) (see \autoref{subsec: C_vorEEN}).204 (EEN scheme) (see \autoref{subsec:INVARIANTS_vorEEN}). 198 205 In the case of ENS, ENE or MIX schemes the land sea mask may be slightly modified to ensure the consistency of 199 vorticity term with analytical equations (\np {ln\_dynvor\_con}\forcode{ = .true.}).206 vorticity term with analytical equations (\np[=.true.]{ln_dynvor_con}{ln\_dynvor\_con}). 200 207 The vorticity terms are all computed in dedicated routines that can be found in the \mdl{dynvor} module. 201 208 202 %-------------------------------------------------------------203 209 % enstrophy conserving scheme 204 % -------------------------------------------------------------205 \subsubsection {Enstrophy conserving scheme (\protect\np{ln\_dynvor\_ens}\forcode{ = .true.})}210 %% ================================================================================================= 211 \subsubsection[Enstrophy conserving scheme (\forcode{ln_dynvor_ens})]{Enstrophy conserving scheme (\protect\np{ln_dynvor_ens}{ln\_dynvor\_ens})} 206 212 \label{subsec:DYN_vor_ens} 207 213 208 214 In the enstrophy conserving case (ENS scheme), 209 215 the discrete formulation of the vorticity term provides a global conservation of the enstrophy 210 ($ [ (\zeta +f ) / e_{3f} ]^2 $ in $s$-coordinates) for a horizontally non-divergent flow (\ie $\chi$=$0$),216 ($ [ (\zeta +f ) / e_{3f} ]^2 $ in $s$-coordinates) for a horizontally non-divergent flow (\ie\ $\chi$=$0$), 211 217 but does not conserve the total kinetic energy. 212 218 It is given by: 213 219 \begin{equation} 214 \label{eq: dynvor_ens}220 \label{eq:DYN_vor_ens} 215 221 \left\{ 216 222 \begin{aligned} … … 221 227 \end{aligned} 222 228 \right. 223 \end{equation} 224 225 %------------------------------------------------------------- 229 \end{equation} 230 226 231 % energy conserving scheme 227 % -------------------------------------------------------------228 \subsubsection {Energy conserving scheme (\protect\np{ln\_dynvor\_ene}\forcode{ = .true.})}232 %% ================================================================================================= 233 \subsubsection[Energy conserving scheme (\forcode{ln_dynvor_ene})]{Energy conserving scheme (\protect\np{ln_dynvor_ene}{ln\_dynvor\_ene})} 229 234 \label{subsec:DYN_vor_ene} 230 235 … … 232 237 It is given by: 233 238 \begin{equation} 234 \label{eq: dynvor_ene}239 \label{eq:DYN_vor_ene} 235 240 \left\{ 236 241 \begin{aligned} … … 241 246 \end{aligned} 242 247 \right. 243 \end{equation} 244 245 %------------------------------------------------------------- 248 \end{equation} 249 246 250 % mix energy/enstrophy conserving scheme 247 % -------------------------------------------------------------248 \subsubsection {Mixed energy/enstrophy conserving scheme (\protect\np{ln\_dynvor\_mix}\forcode{ = .true.})}251 %% ================================================================================================= 252 \subsubsection[Mixed energy/enstrophy conserving scheme (\forcode{ln_dynvor_mix})]{Mixed energy/enstrophy conserving scheme (\protect\np{ln_dynvor_mix}{ln\_dynvor\_mix})} 249 253 \label{subsec:DYN_vor_mix} 250 254 251 255 For the mixed energy/enstrophy conserving scheme (MIX scheme), a mixture of the two previous schemes is used. 252 It consists of the ENS scheme (\autoref{eq: dynvor_ens}) for the relative vorticity term,253 and of the ENE scheme (\autoref{eq: dynvor_ene}) applied to the planetary vorticity term.254 \[ 255 % \label{eq: dynvor_mix}256 It consists of the ENS scheme (\autoref{eq:DYN_vor_ens}) for the relative vorticity term, 257 and of the ENE scheme (\autoref{eq:DYN_vor_ene}) applied to the planetary vorticity term. 258 \[ 259 % \label{eq:DYN_vor_mix} 256 260 \left\{ { 257 261 \begin{aligned} … … 268 272 \] 269 273 270 %-------------------------------------------------------------271 274 % energy and enstrophy conserving scheme 272 % -------------------------------------------------------------273 \subsubsection {Energy and enstrophy conserving scheme (\protect\np{ln\_dynvor\_een}\forcode{ = .true.})}275 %% ================================================================================================= 276 \subsubsection[Energy and enstrophy conserving scheme (\forcode{ln_dynvor_een})]{Energy and enstrophy conserving scheme (\protect\np{ln_dynvor_een}{ln\_dynvor\_een})} 274 277 \label{subsec:DYN_vor_een} 275 278 … … 278 281 the presence of grid point oscillation structures that will be invisible to the operator. 279 282 These structures are \textit{computational modes} that will be at least partly damped by 280 the momentum diffusion operator (\ie the subgrid-scale advection), but not by the resolved advection term.283 the momentum diffusion operator (\ie\ the subgrid-scale advection), but not by the resolved advection term. 281 284 The ENS and ENE schemes therefore do not contribute to dump any grid point noise in the horizontal velocity field. 282 285 Such noise would result in more noise in the vertical velocity field, an undesirable feature. … … 284 287 $u$ and $v$ are located at different grid points, 285 288 a price worth paying to avoid a double averaging in the pressure gradient term as in the $B$-grid. 286 \ gmcomment{ To circumvent this, Adcroft (ADD REF HERE)289 \cmtgm{ To circumvent this, Adcroft (ADD REF HERE) 287 290 Nevertheless, this technique strongly distort the phase and group velocity of Rossby waves....} 288 291 289 A very nice solution to the problem of double averaging was proposed by \citet{ Arakawa_Hsu_MWR90}.292 A very nice solution to the problem of double averaging was proposed by \citet{arakawa.hsu_MWR90}. 290 293 The idea is to get rid of the double averaging by considering triad combinations of vorticity. 291 294 It is noteworthy that this solution is conceptually quite similar to the one proposed by 292 \citep{ Griffies_al_JPO98} for the discretization of the iso-neutral diffusion operator (see \autoref{apdx:C}).293 294 The \citet{ Arakawa_Hsu_MWR90} vorticity advection scheme for a single layer is modified295 for spherical coordinates as described by \citet{ Arakawa_Lamb_MWR81} to obtain the EEN scheme.296 First consider the discrete expression of the potential vorticity, $q$, defined at an $f$-point: 297 \[ 298 % \label{eq: pot_vor}295 \citep{griffies.gnanadesikan.ea_JPO98} for the discretization of the iso-neutral diffusion operator (see \autoref{apdx:INVARIANTS}). 296 297 The \citet{arakawa.hsu_MWR90} vorticity advection scheme for a single layer is modified 298 for spherical coordinates as described by \citet{arakawa.lamb_MWR81} to obtain the EEN scheme. 299 First consider the discrete expression of the potential vorticity, $q$, defined at an $f$-point: 300 \[ 301 % \label{eq:DYN_pot_vor} 299 302 q = \frac{\zeta +f} {e_{3f} } 300 303 \] 301 where the relative vorticity is defined by (\autoref{eq: divcur_cur}),302 the Coriolis parameter is given by $f=2 \,\Omega \;\sin \varphi _f $ and the layer thickness at $f$-points is: 303 \begin{equation} 304 \label{eq: een_e3f}304 where the relative vorticity is defined by (\autoref{eq:DYN_divcur_cur}), 305 the Coriolis parameter is given by $f=2 \,\Omega \;\sin \varphi _f $ and the layer thickness at $f$-points is: 306 \begin{equation} 307 \label{eq:DYN_een_e3f} 305 308 e_{3f} = \overline{\overline {e_{3t} }} ^{\,i+1/2,j+1/2} 306 309 \end{equation} 307 310 308 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>309 311 \begin{figure}[!ht] 310 \begin{center} 311 \includegraphics[width=0.70\textwidth]{Fig_DYN_een_triad} 312 \caption{ 313 \protect\label{fig:DYN_een_triad} 314 Triads used in the energy and enstrophy conserving scheme (een) for 315 $u$-component (upper panel) and $v$-component (lower panel). 316 } 317 \end{center} 312 \centering 313 \includegraphics[width=0.66\textwidth]{DYN_een_triad} 314 \caption[Triads used in the energy and enstrophy conserving scheme (EEN)]{ 315 Triads used in the energy and enstrophy conserving scheme (EEN) for 316 $u$-component (upper panel) and $v$-component (lower panel).} 317 \label{fig:DYN_een_triad} 318 318 \end{figure} 319 % >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 320 321 A key point in \autoref{eq:een_e3f} is how the averaging in the \textbf{i}- and \textbf{j}- directions is made. 319 320 A key point in \autoref{eq:DYN_een_e3f} is how the averaging in the \textbf{i}- and \textbf{j}- directions is made. 322 321 It uses the sum of masked t-point vertical scale factor divided either by the sum of the four t-point masks 323 (\np {nn\_een\_e3f}\forcode{ = 1}), or just by $4$ (\np{nn\_een\_e3f}\forcode{ = .true.}).322 (\np[=1]{nn_een_e3f}{nn\_een\_e3f}), or just by $4$ (\np[=.true.]{nn_een_e3f}{nn\_een\_e3f}). 324 323 The latter case preserves the continuity of $e_{3f}$ when one or more of the neighbouring $e_{3t}$ tends to zero and 325 324 extends by continuity the value of $e_{3f}$ into the land areas. … … 327 326 (with a systematic reduction of $e_{3f}$ when a model level intercept the bathymetry) 328 327 that tends to reinforce the topostrophy of the flow 329 (\ie the tendency of the flow to follow the isobaths) \citep{Penduff_al_OS07}.328 (\ie\ the tendency of the flow to follow the isobaths) \citep{penduff.le-sommer.ea_OS07}. 330 329 331 330 Next, the vorticity triads, $ {^i_j}\mathbb{Q}^{i_p}_{j_p}$ can be defined at a $T$-point as 332 331 the following triad combinations of the neighbouring potential vorticities defined at f-points 333 (\autoref{fig:DYN_een_triad}): 334 \begin{equation} 335 \label{eq: Q_triads}332 (\autoref{fig:DYN_een_triad}): 333 \begin{equation} 334 \label{eq:DYN_Q_triads} 336 335 _i^j \mathbb{Q}^{i_p}_{j_p} 337 336 = \frac{1}{12} \ \left( q^{i-i_p}_{j+j_p} + q^{i+j_p}_{j+i_p} + q^{i+i_p}_{j-j_p} \right) 338 337 \end{equation} 339 where the indices $i_p$ and $k_p$ take the values: $i_p = -1/2$ or $1/2$ and $j_p = -1/2$ or $1/2$. 340 341 Finally, the vorticity terms are represented as: 342 \begin{equation} 343 \label{eq: dynvor_een}338 where the indices $i_p$ and $k_p$ take the values: $i_p = -1/2$ or $1/2$ and $j_p = -1/2$ or $1/2$. 339 340 Finally, the vorticity terms are represented as: 341 \begin{equation} 342 \label{eq:DYN_vor_een} 344 343 \left\{ { 345 344 \begin{aligned} … … 350 349 \end{aligned} 351 350 } \right. 352 \end{equation} 351 \end{equation} 353 352 354 353 This EEN scheme in fact combines the conservation properties of the ENS and ENE schemes. 355 354 It conserves both total energy and potential enstrophy in the limit of horizontally nondivergent flow 356 (\ie $\chi$=$0$) (see \autoref{subsec:C_vorEEN}).355 (\ie\ $\chi$=$0$) (see \autoref{subsec:INVARIANTS_vorEEN}). 357 356 Applied to a realistic ocean configuration, it has been shown that it leads to a significant reduction of 358 the noise in the vertical velocity field \citep{ Le_Sommer_al_OM09}.357 the noise in the vertical velocity field \citep{le-sommer.penduff.ea_OM09}. 359 358 Furthermore, used in combination with a partial steps representation of bottom topography, 360 359 it improves the interaction between current and topography, 361 leading to a larger topostrophy of the flow \citep{Barnier_al_OD06, Penduff_al_OS07}. 362 363 %-------------------------------------------------------------------------------------------------------------- 364 % Kinetic Energy Gradient term 365 %-------------------------------------------------------------------------------------------------------------- 366 \subsection{Kinetic energy gradient term (\protect\mdl{dynkeg})} 360 leading to a larger topostrophy of the flow \citep{barnier.madec.ea_OD06, penduff.le-sommer.ea_OS07}. 361 362 %% ================================================================================================= 363 \subsection[Kinetic energy gradient term (\textit{dynkeg.F90})]{Kinetic energy gradient term (\protect\mdl{dynkeg})} 367 364 \label{subsec:DYN_keg} 368 365 369 As demonstrated in \autoref{apdx: C},366 As demonstrated in \autoref{apdx:INVARIANTS}, 370 367 there is a single discrete formulation of the kinetic energy gradient term that, 371 368 together with the formulation chosen for the vertical advection (see below), 372 369 conserves the total kinetic energy: 373 370 \[ 374 % \label{eq: dynkeg}371 % \label{eq:DYN_keg} 375 372 \left\{ 376 373 \begin{aligned} … … 381 378 \] 382 379 383 %-------------------------------------------------------------------------------------------------------------- 384 % Vertical advection term 385 %-------------------------------------------------------------------------------------------------------------- 386 \subsection{Vertical advection term (\protect\mdl{dynzad}) } 380 %% ================================================================================================= 381 \subsection[Vertical advection term (\textit{dynzad.F90})]{Vertical advection term (\protect\mdl{dynzad})} 387 382 \label{subsec:DYN_zad} 388 383 … … 391 386 conserves the total kinetic energy. 392 387 Indeed, the change of KE due to the vertical advection is exactly balanced by 393 the change of KE due to the gradient of KE (see \autoref{apdx: C}).394 \[ 395 % \label{eq: dynzad}388 the change of KE due to the gradient of KE (see \autoref{apdx:INVARIANTS}). 389 \[ 390 % \label{eq:DYN_zad} 396 391 \left\{ 397 392 \begin{aligned} … … 401 396 \right. 402 397 \] 403 When \np {ln\_dynzad\_zts}\forcode{ = .true.},398 When \np[=.true.]{ln_dynzad_zts}{ln\_dynzad\_zts}, 404 399 a split-explicit time stepping with 5 sub-timesteps is used on the vertical advection term. 405 This option can be useful when the value of the timestep is limited by vertical advection \citep{ Lemarie_OM2015}.400 This option can be useful when the value of the timestep is limited by vertical advection \citep{lemarie.debreu.ea_OM15}. 406 401 Note that in this case, 407 402 a similar split-explicit time stepping should be used on vertical advection of tracer to ensure a better stability, 408 an option which is only available with a TVD scheme (see \np{ln\_traadv\_tvd\_zts} in \autoref{subsec:TRA_adv_tvd}). 409 410 411 % ================================================================ 412 % Coriolis and Advection : flux form 413 % ================================================================ 403 an option which is only available with a TVD scheme (see \np{ln_traadv_tvd_zts}{ln\_traadv\_tvd\_zts} in \autoref{subsec:TRA_adv_tvd}). 404 405 %% ================================================================================================= 414 406 \section{Coriolis and advection: flux form} 415 407 \label{sec:DYN_adv_cor_flux} 416 %------------------------------------------nam_dynadv---------------------------------------------------- 417 418 \nlst{namdyn_adv} 419 %------------------------------------------------------------------------------------------------------------- 420 421 Options are defined through the \ngn{namdyn\_adv} namelist variables. 408 409 Options are defined through the \nam{dyn_adv}{dyn\_adv} namelist variables. 422 410 In the flux form (as in the vector invariant form), 423 411 the Coriolis and momentum advection terms are evaluated using a leapfrog scheme, 424 \ie the velocity appearing in their expressions is centred in time (\textit{now} velocity).412 \ie\ the velocity appearing in their expressions is centred in time (\textit{now} velocity). 425 413 At the lateral boundaries either free slip, 426 414 no slip or partial slip boundary conditions are applied following \autoref{chap:LBC}. 427 415 428 429 %-------------------------------------------------------------------------------------------------------------- 430 % Coriolis plus curvature metric terms 431 %-------------------------------------------------------------------------------------------------------------- 432 \subsection{Coriolis plus curvature metric terms (\protect\mdl{dynvor}) } 416 %% ================================================================================================= 417 \subsection[Coriolis plus curvature metric terms (\textit{dynvor.F90})]{Coriolis plus curvature metric terms (\protect\mdl{dynvor})} 433 418 \label{subsec:DYN_cor_flux} 434 419 435 420 In flux form, the vorticity term reduces to a Coriolis term in which the Coriolis parameter has been modified to account for the "metric" term. 436 421 This altered Coriolis parameter is thus discretised at $f$-points. 437 It is given by: 422 It is given by: 438 423 \begin{multline*} 439 % \label{eq: dyncor_metric}424 % \label{eq:DYN_cor_metric} 440 425 f+\frac{1}{e_1 e_2 }\left( {v\frac{\partial e_2 }{\partial i} - u\frac{\partial e_1 }{\partial j}} \right) \\ 441 426 \equiv f + \frac{1}{e_{1f} e_{2f} } \left( { \ \overline v ^{i+1/2}\delta_{i+1/2} \left[ {e_{2u} } \right] 442 427 - \overline u ^{j+1/2}\delta_{j+1/2} \left[ {e_{1u} } \right] } \ \right) 443 \end{multline*} 444 445 Any of the (\autoref{eq: dynvor_ens}), (\autoref{eq:dynvor_ene}) and (\autoref{eq:dynvor_een}) schemes can be used to428 \end{multline*} 429 430 Any of the (\autoref{eq:DYN_vor_ens}), (\autoref{eq:DYN_vor_ene}) and (\autoref{eq:DYN_vor_een}) schemes can be used to 446 431 compute the product of the Coriolis parameter and the vorticity. 447 However, the energy-conserving scheme (\autoref{eq:dynvor_een}) has exclusively been used to date. 448 This term is evaluated using a leapfrog scheme, \ie the velocity is centred in time (\textit{now} velocity). 449 450 %-------------------------------------------------------------------------------------------------------------- 451 % Flux form Advection term 452 %-------------------------------------------------------------------------------------------------------------- 453 \subsection{Flux form advection term (\protect\mdl{dynadv}) } 432 However, the energy-conserving scheme (\autoref{eq:DYN_vor_een}) has exclusively been used to date. 433 This term is evaluated using a leapfrog scheme, \ie\ the velocity is centred in time (\textit{now} velocity). 434 435 %% ================================================================================================= 436 \subsection[Flux form advection term (\textit{dynadv.F90})]{Flux form advection term (\protect\mdl{dynadv})} 454 437 \label{subsec:DYN_adv_flux} 455 438 456 439 The discrete expression of the advection term is given by: 457 440 \[ 458 % \label{eq: dynadv}441 % \label{eq:DYN_adv} 459 442 \left\{ 460 443 \begin{aligned} … … 475 458 a $2^{nd}$ order centered finite difference scheme, CEN2, 476 459 or a $3^{rd}$ order upstream biased scheme, UBS. 477 The latter is described in \citet{ Shchepetkin_McWilliams_OM05}.478 The schemes are selected using the namelist logicals \np{ln \_dynadv\_cen2} and \np{ln\_dynadv\_ubs}.460 The latter is described in \citet{shchepetkin.mcwilliams_OM05}. 461 The schemes are selected using the namelist logicals \np{ln_dynadv_cen2}{ln\_dynadv\_cen2} and \np{ln_dynadv_ubs}{ln\_dynadv\_ubs}. 479 462 In flux form, the schemes differ by the choice of a space and time interpolation to define the value of 480 $u$ and $v$ at the centre of each face of $u$- and $v$-cells, \ie at the $T$-, $f$-, 481 and $uw$-points for $u$ and at the $f$-, $T$- and $vw$-points for $v$. 482 483 %------------------------------------------------------------- 463 $u$ and $v$ at the centre of each face of $u$- and $v$-cells, \ie\ at the $T$-, $f$-, 464 and $uw$-points for $u$ and at the $f$-, $T$- and $vw$-points for $v$. 465 484 466 % 2nd order centred scheme 485 % -------------------------------------------------------------486 \subsubsection {CEN2: $2^{nd}$ order centred scheme (\protect\np{ln\_dynadv\_cen2}\forcode{ = .true.})}467 %% ================================================================================================= 468 \subsubsection[CEN2: $2^{nd}$ order centred scheme (\forcode{ln_dynadv_cen2})]{CEN2: $2^{nd}$ order centred scheme (\protect\np{ln_dynadv_cen2}{ln\_dynadv\_cen2})} 487 469 \label{subsec:DYN_adv_cen2} 488 470 489 471 In the centered $2^{nd}$ order formulation, the velocity is evaluated as the mean of the two neighbouring points: 490 472 \begin{equation} 491 \label{eq: dynadv_cen2}473 \label{eq:DYN_adv_cen2} 492 474 \left\{ 493 475 \begin{aligned} … … 496 478 \end{aligned} 497 479 \right. 498 \end{equation} 499 500 The scheme is non diffusive (\ie conserves the kinetic energy) but dispersive (\ieit may create false extrema).480 \end{equation} 481 482 The scheme is non diffusive (\ie\ conserves the kinetic energy) but dispersive (\ie\ it may create false extrema). 501 483 It is therefore notoriously noisy and must be used in conjunction with an explicit diffusion operator to 502 484 produce a sensible solution. … … 504 486 so $u$ and $v$ are the \emph{now} velocities. 505 487 506 %-------------------------------------------------------------507 488 % UBS scheme 508 % -------------------------------------------------------------509 \subsubsection {UBS: Upstream Biased Scheme (\protect\np{ln\_dynadv\_ubs}\forcode{ = .true.})}489 %% ================================================================================================= 490 \subsubsection[UBS: Upstream Biased Scheme (\forcode{ln_dynadv_ubs})]{UBS: Upstream Biased Scheme (\protect\np{ln_dynadv_ubs}{ln\_dynadv\_ubs})} 510 491 \label{subsec:DYN_adv_ubs} 511 492 … … 514 495 For example, the evaluation of $u_T^{ubs} $ is done as follows: 515 496 \begin{equation} 516 \label{eq: dynadv_ubs}497 \label{eq:DYN_adv_ubs} 517 498 u_T^{ubs} =\overline u ^i-\;\frac{1}{6} 518 499 \begin{cases} … … 522 503 \end{equation} 523 504 where $u"_{i+1/2} =\delta_{i+1/2} \left[ {\delta_i \left[ u \right]} \right]$. 524 This results in a dissipatively dominant (\ie hyper-diffusive) truncation error525 \citep{ Shchepetkin_McWilliams_OM05}.526 The overall performance of the advection scheme is similar to that reported in \citet{ Farrow1995}.505 This results in a dissipatively dominant (\ie\ hyper-diffusive) truncation error 506 \citep{shchepetkin.mcwilliams_OM05}. 507 The overall performance of the advection scheme is similar to that reported in \citet{farrow.stevens_JPO95}. 527 508 It is a relatively good compromise between accuracy and smoothness. 528 509 It is not a \emph{positive} scheme, meaning that false extrema are permitted. 529 510 But the amplitudes of the false extrema are significantly reduced over those in the centred second order method. 530 As the scheme already includes a diffusion component, it can be used without explicit lateral diffusion on momentum 531 (\ie \np{ln\_dynldf\_lap}\forcode{ = }\np{ln\_dynldf\_bilap}\forcode{ = .false.}),511 As the scheme already includes a diffusion component, it can be used without explicit lateral diffusion on momentum 512 (\ie\ \np[=]{ln_dynldf_lap}{ln\_dynldf\_lap}\np[=.false.]{ln_dynldf_bilap}{ln\_dynldf\_bilap}), 532 513 and it is recommended to do so. 533 514 534 515 The UBS scheme is not used in all directions. 535 In the vertical, the centred $2^{nd}$ order evaluation of the advection is preferred, \ie $u_{uw}^{ubs}$ and536 $u_{vw}^{ubs}$ in \autoref{eq: dynadv_cen2} are used.537 UBS is diffusive and is associated with vertical mixing of momentum. \ gmcomment{ gm pursue the516 In the vertical, the centred $2^{nd}$ order evaluation of the advection is preferred, \ie\ $u_{uw}^{ubs}$ and 517 $u_{vw}^{ubs}$ in \autoref{eq:DYN_adv_cen2} are used. 518 UBS is diffusive and is associated with vertical mixing of momentum. \cmtgm{ gm pursue the 538 519 sentence:Since vertical mixing of momentum is a source term of the TKE equation... } 539 520 540 For stability reasons, the first term in (\autoref{eq: dynadv_ubs}),521 For stability reasons, the first term in (\autoref{eq:DYN_adv_ubs}), 541 522 which corresponds to a second order centred scheme, is evaluated using the \textit{now} velocity (centred in time), 542 523 while the second term, which is the diffusion part of the scheme, 543 524 is evaluated using the \textit{before} velocity (forward in time). 544 This is discussed by \citet{ Webb_al_JAOT98} in the context of the Quick advection scheme.525 This is discussed by \citet{webb.de-cuevas.ea_JAOT98} in the context of the Quick advection scheme. 545 526 546 527 Note that the UBS and QUICK (Quadratic Upstream Interpolation for Convective Kinematics) schemes only differ by 547 528 one coefficient. 548 Replacing $1/6$ by $1/8$ in (\autoref{eq: dynadv_ubs}) leads to the QUICK advection scheme \citep{Webb_al_JAOT98}.529 Replacing $1/6$ by $1/8$ in (\autoref{eq:DYN_adv_ubs}) leads to the QUICK advection scheme \citep{webb.de-cuevas.ea_JAOT98}. 549 530 This option is not available through a namelist parameter, since the $1/6$ coefficient is hard coded. 550 531 Nevertheless it is quite easy to make the substitution in the \mdl{dynadv\_ubs} module and obtain a QUICK scheme. … … 553 534 there is also the possibility of using a $4^{th}$ order evaluation of the advective velocity as in ROMS. 554 535 This is an error and should be suppressed soon. 555 %%% 556 \gmcomment{action : this have to be done} 557 %%% 558 559 % ================================================================ 560 % Hydrostatic pressure gradient term 561 % ================================================================ 562 \section{Hydrostatic pressure gradient (\protect\mdl{dynhpg})} 536 \cmtgm{action : this have to be done} 537 538 %% ================================================================================================= 539 \section[Hydrostatic pressure gradient (\textit{dynhpg.F90})]{Hydrostatic pressure gradient (\protect\mdl{dynhpg})} 563 540 \label{sec:DYN_hpg} 564 %------------------------------------------nam_dynhpg--------------------------------------------------- 565 566 \nlst{namdyn_hpg} 567 %------------------------------------------------------------------------------------------------------------- 568 569 Options are defined through the \ngn{namdyn\_hpg} namelist variables. 541 542 \begin{listing} 543 \nlst{namdyn_hpg} 544 \caption{\forcode{&namdyn_hpg}} 545 \label{lst:namdyn_hpg} 546 \end{listing} 547 548 Options are defined through the \nam{dyn_hpg}{dyn\_hpg} namelist variables. 570 549 The key distinction between the different algorithms used for 571 550 the hydrostatic pressure gradient is the vertical coordinate used, 572 since HPG is a \emph{horizontal} pressure gradient, \ie computed along geopotential surfaces.551 since HPG is a \emph{horizontal} pressure gradient, \ie\ computed along geopotential surfaces. 573 552 As a result, any tilt of the surface of the computational levels will require a specific treatment to 574 553 compute the hydrostatic pressure gradient. 575 554 576 555 The hydrostatic pressure gradient term is evaluated either using a leapfrog scheme, 577 \ie the density appearing in its expression is centred in time (\emph{now} $\rho$),556 \ie\ the density appearing in its expression is centred in time (\emph{now} $\rho$), 578 557 or a semi-implcit scheme. 579 558 At the lateral boundaries either free slip, no slip or partial slip boundary conditions are applied. 580 559 581 %-------------------------------------------------------------------------------------------------------------- 582 % z-coordinate with full step 583 %-------------------------------------------------------------------------------------------------------------- 584 \subsection{Full step $Z$-coordinate (\protect\np{ln\_dynhpg\_zco}\forcode{ = .true.})} 560 %% ================================================================================================= 561 \subsection[Full step $Z$-coordinate (\forcode{ln_dynhpg_zco})]{Full step $Z$-coordinate (\protect\np{ln_dynhpg_zco}{ln\_dynhpg\_zco})} 585 562 \label{subsec:DYN_hpg_zco} 586 563 … … 592 569 for $k=km$ (surface layer, $jk=1$ in the code) 593 570 \begin{equation} 594 \label{eq: dynhpg_zco_surf}571 \label{eq:DYN_hpg_zco_surf} 595 572 \left\{ 596 573 \begin{aligned} … … 601 578 \end{aligned} 602 579 \right. 603 \end{equation} 580 \end{equation} 604 581 605 582 for $1<k<km$ (interior layer) 606 583 \begin{equation} 607 \label{eq: dynhpg_zco}584 \label{eq:DYN_hpg_zco} 608 585 \left\{ 609 586 \begin{aligned} … … 616 593 \end{aligned} 617 594 \right. 618 \end{equation} 619 620 Note that the $1/2$ factor in (\autoref{eq: dynhpg_zco_surf}) is adequate because of the definition of $e_{3w}$ as595 \end{equation} 596 597 Note that the $1/2$ factor in (\autoref{eq:DYN_hpg_zco_surf}) is adequate because of the definition of $e_{3w}$ as 621 598 the vertical derivative of the scale factor at the surface level ($z=0$). 622 Note also that in case of variable volume level (\key{vvl} defined), 623 the surface pressure gradient is included in \autoref{eq:dynhpg_zco_surf} and 624 \autoref{eq:dynhpg_zco} through the space and time variations of the vertical scale factor $e_{3w}$. 625 626 %-------------------------------------------------------------------------------------------------------------- 627 % z-coordinate with partial step 628 %-------------------------------------------------------------------------------------------------------------- 629 \subsection{Partial step $Z$-coordinate (\protect\np{ln\_dynhpg\_zps}\forcode{ = .true.})} 599 Note also that in case of variable volume level (\texttt{vvl?} defined), 600 the surface pressure gradient is included in \autoref{eq:DYN_hpg_zco_surf} and 601 \autoref{eq:DYN_hpg_zco} through the space and time variations of the vertical scale factor $e_{3w}$. 602 603 %% ================================================================================================= 604 \subsection[Partial step $Z$-coordinate (\forcode{ln_dynhpg_zps})]{Partial step $Z$-coordinate (\protect\np{ln_dynhpg_zps}{ln\_dynhpg\_zps})} 630 605 \label{subsec:DYN_hpg_zps} 631 606 … … 633 608 Before taking horizontal gradients between these tracer points, 634 609 a linear interpolation is used to approximate the deeper tracer as if 635 it actually lived at the depth of the shallower tracer point. 610 it actually lived at the depth of the shallower tracer point. 636 611 637 612 Apart from this modification, … … 645 620 module \mdl{zpsdhe} located in the TRA directory and described in \autoref{sec:TRA_zpshde}. 646 621 647 %-------------------------------------------------------------------------------------------------------------- 648 % s- and s-z-coordinates 649 %-------------------------------------------------------------------------------------------------------------- 622 %% ================================================================================================= 650 623 \subsection{$S$- and $Z$-$S$-coordinates} 651 624 \label{subsec:DYN_hpg_sco} 652 625 653 626 Pressure gradient formulations in an $s$-coordinate have been the subject of a vast number of papers 654 (\eg, \citet{ Song1998, Shchepetkin_McWilliams_OM05}).627 (\eg, \citet{song_MWR98, shchepetkin.mcwilliams_OM05}). 655 628 A number of different pressure gradient options are coded but the ROMS-like, 656 629 density Jacobian with cubic polynomial method is currently disabled whilst known bugs are under investigation. 657 630 658 $\bullet$ Traditional coding (see for example \citet{ Madec_al_JPO96}: (\np{ln\_dynhpg\_sco}\forcode{ = .true.})659 \begin{equation} 660 \label{eq: dynhpg_sco}631 $\bullet$ Traditional coding (see for example \citet{madec.delecluse.ea_JPO96}: (\np[=.true.]{ln_dynhpg_sco}{ln\_dynhpg\_sco}) 632 \begin{equation} 633 \label{eq:DYN_hpg_sco} 661 634 \left\{ 662 635 \begin{aligned} … … 667 640 \end{aligned} 668 641 \right. 669 \end{equation} 642 \end{equation} 670 643 671 644 Where the first term is the pressure gradient along coordinates, 672 computed as in \autoref{eq: dynhpg_zco_surf} - \autoref{eq:dynhpg_zco},673 and $z_T$ is the depth of the $T$-point evaluated from the sum of the vertical scale factors at the $w$-point 645 computed as in \autoref{eq:DYN_hpg_zco_surf} - \autoref{eq:DYN_hpg_zco}, 646 and $z_T$ is the depth of the $T$-point evaluated from the sum of the vertical scale factors at the $w$-point 674 647 ($e_{3w}$). 675 676 $\bullet$ Traditional coding with adaptation for ice shelf cavities (\np {ln\_dynhpg\_isf}\forcode{ = .true.}).677 This scheme need the activation of ice shelf cavities (\np {ln\_isfcav}\forcode{ = .true.}).678 679 $\bullet$ Pressure Jacobian scheme (prj) (a research paper in preparation) (\np {ln\_dynhpg\_prj}\forcode{ = .true.})680 681 $\bullet$ Density Jacobian with cubic polynomial scheme (DJC) \citep{ Shchepetkin_McWilliams_OM05}682 (\np {ln\_dynhpg\_djc}\forcode{ = .true.}) (currently disabled; under development)683 684 Note that expression \autoref{eq: dynhpg_sco} is commonly used when the variable volume formulation is activated685 (\ key{vvl}) because in that case, even with a flat bottom,686 the coordinate surfaces are not horizontal but follow the free surface \citep{ Levier2007}.687 The pressure jacobian scheme (\np {ln\_dynhpg\_prj}\forcode{ = .true.}) is available as688 an improved option to \np {ln\_dynhpg\_sco}\forcode{ = .true.} when \key{vvl} is active.648 649 $\bullet$ Traditional coding with adaptation for ice shelf cavities (\np[=.true.]{ln_dynhpg_isf}{ln\_dynhpg\_isf}). 650 This scheme need the activation of ice shelf cavities (\np[=.true.]{ln_isfcav}{ln\_isfcav}). 651 652 $\bullet$ Pressure Jacobian scheme (prj) (a research paper in preparation) (\np[=.true.]{ln_dynhpg_prj}{ln\_dynhpg\_prj}) 653 654 $\bullet$ Density Jacobian with cubic polynomial scheme (DJC) \citep{shchepetkin.mcwilliams_OM05} 655 (\np[=.true.]{ln_dynhpg_djc}{ln\_dynhpg\_djc}) (currently disabled; under development) 656 657 Note that expression \autoref{eq:DYN_hpg_sco} is commonly used when the variable volume formulation is activated 658 (\texttt{vvl?}) because in that case, even with a flat bottom, 659 the coordinate surfaces are not horizontal but follow the free surface \citep{levier.treguier.ea_rpt07}. 660 The pressure jacobian scheme (\np[=.true.]{ln_dynhpg_prj}{ln\_dynhpg\_prj}) is available as 661 an improved option to \np[=.true.]{ln_dynhpg_sco}{ln\_dynhpg\_sco} when \texttt{vvl?} is active. 689 662 The pressure Jacobian scheme uses a constrained cubic spline to 690 663 reconstruct the density profile across the water column. … … 694 667 This method can provide a more accurate calculation of the horizontal pressure gradient than the standard scheme. 695 668 669 %% ================================================================================================= 696 670 \subsection{Ice shelf cavity} 697 671 \label{subsec:DYN_hpg_isf} 672 698 673 Beneath an ice shelf, the total pressure gradient is the sum of the pressure gradient due to the ice shelf load and 699 the pressure gradient due to the ocean load (\np {ln\_dynhpg\_isf}\forcode{ = .true.}).\\674 the pressure gradient due to the ocean load (\np[=.true.]{ln_dynhpg_isf}{ln\_dynhpg\_isf}).\\ 700 675 701 676 The main hypothesis to compute the ice shelf load is that the ice shelf is in an isostatic equilibrium. … … 704 679 corresponds to the water replaced by the ice shelf. 705 680 This top pressure is constant over time. 706 A detailed description of this method is described in \citet{Losch2008}.\\ 707 708 The pressure gradient due to ocean load is computed using the expression \autoref{eq:dynhpg_sco} described in 709 \autoref{subsec:DYN_hpg_sco}. 710 711 %-------------------------------------------------------------------------------------------------------------- 712 % Time-scheme 713 %-------------------------------------------------------------------------------------------------------------- 714 \subsection{Time-scheme (\protect\np{ln\_dynhpg\_imp}\forcode{ = .true./.false.})} 681 A detailed description of this method is described in \citet{losch_JGR08}.\\ 682 683 The pressure gradient due to ocean load is computed using the expression \autoref{eq:DYN_hpg_sco} described in 684 \autoref{subsec:DYN_hpg_sco}. 685 686 %% ================================================================================================= 687 \subsection[Time-scheme (\forcode{ln_dynhpg_imp})]{Time-scheme (\protect\np{ln_dynhpg_imp}{ln\_dynhpg\_imp})} 715 688 \label{subsec:DYN_hpg_imp} 716 689 … … 722 695 the physical phenomenon that controls the time-step is internal gravity waves (IGWs). 723 696 A semi-implicit scheme for doubling the stability limit associated with IGWs can be used 724 \citep{ Brown_Campana_MWR78, Maltrud1998}.697 \citep{brown.campana_MWR78, maltrud.smith.ea_JGR98}. 725 698 It involves the evaluation of the hydrostatic pressure gradient as 726 699 an average over the three time levels $t-\rdt$, $t$, and $t+\rdt$ 727 (\ie \textit{before}, \textit{now} and \textit{after} time-steps),728 rather than at the central time level $t$ only, as in the standard leapfrog scheme. 729 730 $\bullet$ leapfrog scheme (\np {ln\_dynhpg\_imp}\forcode{ = .true.}):731 732 \begin{equation} 733 \label{eq: dynhpg_lf}700 (\ie\ \textit{before}, \textit{now} and \textit{after} time-steps), 701 rather than at the central time level $t$ only, as in the standard leapfrog scheme. 702 703 $\bullet$ leapfrog scheme (\np[=.true.]{ln_dynhpg_imp}{ln\_dynhpg\_imp}): 704 705 \begin{equation} 706 \label{eq:DYN_hpg_lf} 734 707 \frac{u^{t+\rdt}-u^{t-\rdt}}{2\rdt} = \;\cdots \; 735 708 -\frac{1}{\rho_o \,e_{1u} }\delta_{i+1/2} \left[ {p_h^t } \right] 736 709 \end{equation} 737 710 738 $\bullet$ semi-implicit scheme (\np {ln\_dynhpg\_imp}\forcode{ = .true.}):739 \begin{equation} 740 \label{eq: dynhpg_imp}711 $\bullet$ semi-implicit scheme (\np[=.true.]{ln_dynhpg_imp}{ln\_dynhpg\_imp}): 712 \begin{equation} 713 \label{eq:DYN_hpg_imp} 741 714 \frac{u^{t+\rdt}-u^{t-\rdt}}{2\rdt} = \;\cdots \; 742 715 -\frac{1}{4\,\rho_o \,e_{1u} } \delta_{i+1/2} \left[ p_h^{t+\rdt} +2\,p_h^t +p_h^{t-\rdt} \right] 743 716 \end{equation} 744 717 745 The semi-implicit time scheme \autoref{eq: dynhpg_imp} is made possible without718 The semi-implicit time scheme \autoref{eq:DYN_hpg_imp} is made possible without 746 719 significant additional computation since the density can be updated to time level $t+\rdt$ before 747 720 computing the horizontal hydrostatic pressure gradient. 748 721 It can be easily shown that the stability limit associated with the hydrostatic pressure gradient doubles using 749 \autoref{eq: dynhpg_imp} compared to that using the standard leapfrog scheme \autoref{eq:dynhpg_lf}.750 Note that \autoref{eq: dynhpg_imp} is equivalent to applying a time filter to the pressure gradient to722 \autoref{eq:DYN_hpg_imp} compared to that using the standard leapfrog scheme \autoref{eq:DYN_hpg_lf}. 723 Note that \autoref{eq:DYN_hpg_imp} is equivalent to applying a time filter to the pressure gradient to 751 724 eliminate high frequency IGWs. 752 Obviously, when using \autoref{eq: dynhpg_imp},725 Obviously, when using \autoref{eq:DYN_hpg_imp}, 753 726 the doubling of the time-step is achievable only if no other factors control the time-step, 754 727 such as the stability limits associated with advection or diffusion. 755 728 756 In practice, the semi-implicit scheme is used when \np {ln\_dynhpg\_imp}\forcode{ = .true.}.729 In practice, the semi-implicit scheme is used when \np[=.true.]{ln_dynhpg_imp}{ln\_dynhpg\_imp}. 757 730 In this case, we choose to apply the time filter to temperature and salinity used in the equation of state, 758 731 instead of applying it to the hydrostatic pressure or to the density, … … 760 733 The density used to compute the hydrostatic pressure gradient (whatever the formulation) is evaluated as follows: 761 734 \[ 762 % \label{eq: rho_flt}735 % \label{eq:DYN_rho_flt} 763 736 \rho^t = \rho( \widetilde{T},\widetilde {S},z_t) 764 737 \quad \text{with} \quad … … 768 741 Note that in the semi-implicit case, it is necessary to save the filtered density, 769 742 an extra three-dimensional field, in the restart file to restart the model with exact reproducibility. 770 This option is controlled by \np{nn\_dynhpg\_rst}, a namelist parameter. 771 772 % ================================================================ 773 % Surface Pressure Gradient 774 % ================================================================ 775 \section{Surface pressure gradient (\protect\mdl{dynspg})} 743 This option is controlled by \np{nn_dynhpg_rst}{nn\_dynhpg\_rst}, a namelist parameter. 744 745 %% ================================================================================================= 746 \section[Surface pressure gradient (\textit{dynspg.F90})]{Surface pressure gradient (\protect\mdl{dynspg})} 776 747 \label{sec:DYN_spg} 777 %-----------------------------------------nam_dynspg---------------------------------------------------- 778 779 \nlst{namdyn_spg} 780 %------------------------------------------------------------------------------------------------------------ 781 782 Options are defined through the \ngn{namdyn\_spg} namelist variables. 783 The surface pressure gradient term is related to the representation of the free surface (\autoref{sec:PE_hor_pg}). 748 749 \begin{listing} 750 \nlst{namdyn_spg} 751 \caption{\forcode{&namdyn_spg}} 752 \label{lst:namdyn_spg} 753 \end{listing} 754 755 Options are defined through the \nam{dyn_spg}{dyn\_spg} namelist variables. 756 The surface pressure gradient term is related to the representation of the free surface (\autoref{sec:MB_hor_pg}). 784 757 The main distinction is between the fixed volume case (linear free surface) and 785 the variable volume case (nonlinear free surface, \ key{vvl} is defined).786 In the linear free surface case (\autoref{subsec: PE_free_surface})758 the variable volume case (nonlinear free surface, \texttt{vvl?} is defined). 759 In the linear free surface case (\autoref{subsec:MB_free_surface}) 787 760 the vertical scale factors $e_{3}$ are fixed in time, 788 while they are time-dependent in the nonlinear case (\autoref{subsec: PE_free_surface}).789 With both linear and nonlinear free surface, external gravity waves are allowed in the equations, 761 while they are time-dependent in the nonlinear case (\autoref{subsec:MB_free_surface}). 762 With both linear and nonlinear free surface, external gravity waves are allowed in the equations, 790 763 which imposes a very small time step when an explicit time stepping is used. 791 Two methods are proposed to allow a longer time step for the three-dimensional equations: 792 the filtered free surface, which is a modification of the continuous equations (see \autoref{eq: PE_flt}),764 Two methods are proposed to allow a longer time step for the three-dimensional equations: 765 the filtered free surface, which is a modification of the continuous equations (see \autoref{eq:MB_flt?}), 793 766 and the split-explicit free surface described below. 794 The extra term introduced in the filtered method is calculated implicitly, 767 The extra term introduced in the filtered method is calculated implicitly, 795 768 so that the update of the next velocities is done in module \mdl{dynspg\_flt} and not in \mdl{dynnxt}. 796 769 797 798 770 The form of the surface pressure gradient term depends on how the user wants to 799 handle the fast external gravity waves that are a solution of the analytical equation (\autoref{sec: PE_hor_pg}).771 handle the fast external gravity waves that are a solution of the analytical equation (\autoref{sec:MB_hor_pg}). 800 772 Three formulations are available, all controlled by a CPP key (ln\_dynspg\_xxx): 801 773 an explicit formulation which requires a small time step; 802 774 a filtered free surface formulation which allows a larger time step by 803 adding a filtering term into the momentum equation; 775 adding a filtering term into the momentum equation; 804 776 and a split-explicit free surface formulation, described below, which also allows a larger time step. 805 777 … … 807 779 As a consequence the update of the $next$ velocities is done in module \mdl{dynspg\_flt} and not in \mdl{dynnxt}. 808 780 809 810 %-------------------------------------------------------------------------------------------------------------- 811 % Explicit free surface formulation 812 %-------------------------------------------------------------------------------------------------------------- 813 \subsection{Explicit free surface (\protect\key{dynspg\_exp})} 781 %% ================================================================================================= 782 \subsection[Explicit free surface (\forcode{ln_dynspg_exp})]{Explicit free surface (\protect\np{ln_dynspg_exp}{ln\_dynspg\_exp})} 814 783 \label{subsec:DYN_spg_exp} 815 784 816 In the explicit free surface formulation (\ key{dynspg\_exp} defined),785 In the explicit free surface formulation (\np{ln_dynspg_exp}{ln\_dynspg\_exp} set to true), 817 786 the model time step is chosen to be small enough to resolve the external gravity waves 818 787 (typically a few tens of seconds). 819 The surface pressure gradient, evaluated using a leap-frog scheme (\ie centered in time),788 The surface pressure gradient, evaluated using a leap-frog scheme (\ie\ centered in time), 820 789 is thus simply given by : 821 790 \begin{equation} 822 \label{eq: dynspg_exp}791 \label{eq:DYN_spg_exp} 823 792 \left\{ 824 793 \begin{aligned} … … 827 796 \end{aligned} 828 797 \right. 829 \end{equation} 830 831 Note that in the non-linear free surface case (\ie \key{vvl} defined),798 \end{equation} 799 800 Note that in the non-linear free surface case (\ie\ \texttt{vvl?} defined), 832 801 the surface pressure gradient is already included in the momentum tendency through 833 802 the level thickness variation allowed in the computation of the hydrostatic pressure gradient. 834 803 Thus, nothing is done in the \mdl{dynspg\_exp} module. 835 804 836 %-------------------------------------------------------------------------------------------------------------- 837 % Split-explict free surface formulation 838 %-------------------------------------------------------------------------------------------------------------- 839 \subsection{Split-explicit free surface (\protect\key{dynspg\_ts})} 805 %% ================================================================================================= 806 \subsection[Split-explicit free surface (\forcode{ln_dynspg_ts})]{Split-explicit free surface (\protect\np{ln_dynspg_ts}{ln\_dynspg\_ts})} 840 807 \label{subsec:DYN_spg_ts} 841 %------------------------------------------namsplit-----------------------------------------------------------842 %843 808 %\nlst{namsplit} 844 %------------------------------------------------------------------------------------------------------------- 845 846 The split-explicit free surface formulation used in \NEMO (\key{dynspg\_ts} defined), 847 also called the time-splitting formulation, follows the one proposed by \citet{Shchepetkin_McWilliams_OM05}. 809 810 The split-explicit free surface formulation used in \NEMO\ (\np{ln_dynspg_ts}{ln\_dynspg\_ts} set to true), 811 also called the time-splitting formulation, follows the one proposed by \citet{shchepetkin.mcwilliams_OM05}. 848 812 The general idea is to solve the free surface equation and the associated barotropic velocity equations with 849 813 a smaller time step than $\rdt$, the time step used for the three dimensional prognostic variables 850 (\autoref{fig:DYN_ dynspg_ts}).814 (\autoref{fig:DYN_spg_ts}). 851 815 The size of the small time step, $\rdt_e$ (the external mode or barotropic time step) is provided through 852 the \np{nn \_baro} namelist parameter as: $\rdt_e = \rdt / nn\_baro$.853 This parameter can be optionally defined automatically (\np {ln\_bt\_nn\_auto}\forcode{ = .true.}) considering that816 the \np{nn_baro}{nn\_baro} namelist parameter as: $\rdt_e = \rdt / nn\_baro$. 817 This parameter can be optionally defined automatically (\np[=.true.]{ln_bt_nn_auto}{ln\_bt\_nn\_auto}) considering that 854 818 the stability of the barotropic system is essentially controled by external waves propagation. 855 819 Maximum Courant number is in that case time independent, and easily computed online from the input bathymetry. 856 Therefore, $\rdt_e$ is adjusted so that the Maximum allowed Courant number is smaller than \np{rn\_bt\_cmax}. 857 858 %%% 820 Therefore, $\rdt_e$ is adjusted so that the Maximum allowed Courant number is smaller than \np{rn_bt_cmax}{rn\_bt\_cmax}. 821 859 822 The barotropic mode solves the following equations: 860 823 % \begin{subequations} 861 % \label{eq: BT}862 \begin{equation} 863 \label{eq: BT_dyn}864 \frac{\partial {\ rm \overline{{\bf U}}_h} }{\partial t}=865 -f\;{\ rm {\bf k}}\times {\rm \overline{{\bf U}}_h}866 -g\nabla _h \eta -\frac{c_b^{\textbf U}}{H+\eta} \ rm {\overline{{\bf U}}_h} + \rm {\overline{\bf G}}867 \end{equation} 868 \[ 869 % \label{eq: BT_ssh}870 \frac{\partial \eta }{\partial t}=-\nabla \cdot \left[ {\left( {H+\eta } \right) \; {\ rm{\bf \overline{U}}}_h \,} \right]+P-E824 % \label{eq:DYN_BT} 825 \begin{equation} 826 \label{eq:DYN_BT_dyn} 827 \frac{\partial {\mathrm \overline{{\mathbf U}}_h} }{\partial t}= 828 -f\;{\mathrm {\mathbf k}}\times {\mathrm \overline{{\mathbf U}}_h} 829 -g\nabla _h \eta -\frac{c_b^{\textbf U}}{H+\eta} \mathrm {\overline{{\mathbf U}}_h} + \mathrm {\overline{\mathbf G}} 830 \end{equation} 831 \[ 832 % \label{eq:DYN_BT_ssh} 833 \frac{\partial \eta }{\partial t}=-\nabla \cdot \left[ {\left( {H+\eta } \right) \; {\mathrm{\mathbf \overline{U}}}_h \,} \right]+P-E 871 834 \] 872 835 % \end{subequations} 873 where $\ rm {\overline{\bf G}}$ is a forcing term held constant, containing coupling term between modes,836 where $\mathrm {\overline{\mathbf G}}$ is a forcing term held constant, containing coupling term between modes, 874 837 surface atmospheric forcing as well as slowly varying barotropic terms not explicitly computed to gain efficiency. 875 The third term on the right hand side of \autoref{eq: BT_dyn} represents the bottom stress876 (see section \autoref{sec:ZDF_ bfr}), explicitly accounted for at each barotropic iteration.838 The third term on the right hand side of \autoref{eq:DYN_BT_dyn} represents the bottom stress 839 (see section \autoref{sec:ZDF_drg}), explicitly accounted for at each barotropic iteration. 877 840 Temporal discretization of the system above follows a three-time step Generalized Forward Backward algorithm 878 detailed in \citet{Shchepetkin_McWilliams_OM05}. 879 AB3-AM4 coefficients used in \NEMO follow the second-order accurate, 880 "multi-purpose" stability compromise as defined in \citet{Shchepetkin_McWilliams_Bk08} 881 (see their figure 12, lower left). 882 883 %> > > > > > > > > > > > > > > > > > > > > > > > > > > > 841 detailed in \citet{shchepetkin.mcwilliams_OM05}. 842 AB3-AM4 coefficients used in \NEMO\ follow the second-order accurate, 843 "multi-purpose" stability compromise as defined in \citet{shchepetkin.mcwilliams_ibk09} 844 (see their figure 12, lower left). 845 884 846 \begin{figure}[!t] 885 \begin{center} 886 \includegraphics[width=0.7\textwidth]{Fig_DYN_dynspg_ts} 887 \caption{ 888 \protect\label{fig:DYN_dynspg_ts} 889 Schematic of the split-explicit time stepping scheme for the external and internal modes. 890 Time increases to the right. In this particular exemple, 891 a boxcar averaging window over $nn\_baro$ barotropic time steps is used ($nn\_bt\_flt=1$) and $nn\_baro=5$. 892 Internal mode time steps (which are also the model time steps) are denoted by $t-\rdt$, $t$ and $t+\rdt$. 893 Variables with $k$ superscript refer to instantaneous barotropic variables, 894 $< >$ and $<< >>$ operator refer to time filtered variables using respectively primary (red vertical bars) and 895 secondary weights (blue vertical bars). 896 The former are used to obtain time filtered quantities at $t+\rdt$ while 897 the latter are used to obtain time averaged transports to advect tracers. 898 a) Forward time integration: \protect\np{ln\_bt\_fw}\forcode{ = .true.}, 899 \protect\np{ln\_bt\_av}\forcode{ = .true.}. 900 b) Centred time integration: \protect\np{ln\_bt\_fw}\forcode{ = .false.}, 901 \protect\np{ln\_bt\_av}\forcode{ = .true.}. 902 c) Forward time integration with no time filtering (POM-like scheme): 903 \protect\np{ln\_bt\_fw}\forcode{ = .true.}, \protect\np{ln\_bt\_av}\forcode{ = .false.}. 904 } 905 \end{center} 847 \centering 848 \includegraphics[width=0.66\textwidth]{DYN_dynspg_ts} 849 \caption[Split-explicit time stepping scheme for the external and internal modes]{ 850 Schematic of the split-explicit time stepping scheme for the external and internal modes. 851 Time increases to the right. 852 In this particular exemple, 853 a boxcar averaging window over \np{nn_baro}{nn\_baro} barotropic time steps is used 854 (\np[=1]{nn_bt_flt}{nn\_bt\_flt}) and \np[=5]{nn_baro}{nn\_baro}. 855 Internal mode time steps (which are also the model time steps) are denoted by 856 $t-\rdt$, $t$ and $t+\rdt$. 857 Variables with $k$ superscript refer to instantaneous barotropic variables, 858 $< >$ and $<< >>$ operator refer to time filtered variables using respectively primary 859 (red vertical bars) and secondary weights (blue vertical bars). 860 The former are used to obtain time filtered quantities at $t+\rdt$ while 861 the latter are used to obtain time averaged transports to advect tracers. 862 a) Forward time integration: 863 \protect\np[=.true.]{ln_bt_fw}{ln\_bt\_fw}, \protect\np[=.true.]{ln_bt_av}{ln\_bt\_av}. 864 b) Centred time integration: 865 \protect\np[=.false.]{ln_bt_fw}{ln\_bt\_fw}, \protect\np[=.true.]{ln_bt_av}{ln\_bt\_av}. 866 c) Forward time integration with no time filtering (POM-like scheme): 867 \protect\np[=.true.]{ln_bt_fw}{ln\_bt\_fw}, \protect\np[=.false.]{ln_bt_av}{ln\_bt\_av}.} 868 \label{fig:DYN_spg_ts} 906 869 \end{figure} 907 %> > > > > > > > > > > > > > > > > > > > > > > > > > > > 908 909 In the default case (\np{ln\_bt\_fw}\forcode{ = .true.}), 870 871 In the default case (\np[=.true.]{ln_bt_fw}{ln\_bt\_fw}), 910 872 the external mode is integrated between \textit{now} and \textit{after} baroclinic time-steps 911 (\autoref{fig:DYN_ dynspg_ts}a).873 (\autoref{fig:DYN_spg_ts}a). 912 874 To avoid aliasing of fast barotropic motions into three dimensional equations, 913 time filtering is eventually applied on barotropic quantities (\np {ln\_bt\_av}\forcode{ = .true.}).875 time filtering is eventually applied on barotropic quantities (\np[=.true.]{ln_bt_av}{ln\_bt\_av}). 914 876 In that case, the integration is extended slightly beyond \textit{after} time step to 915 877 provide time filtered quantities. 916 878 These are used for the subsequent initialization of the barotropic mode in the following baroclinic step. 917 Since external mode equations written at baroclinic time steps finally follow a forward time stepping scheme, 879 Since external mode equations written at baroclinic time steps finally follow a forward time stepping scheme, 918 880 asselin filtering is not applied to barotropic quantities.\\ 919 881 Alternatively, one can choose to integrate barotropic equations starting from \textit{before} time step 920 (\np {ln\_bt\_fw}\forcode{ = .false.}).921 Although more computationaly expensive ( \np{nn \_baro} additional iterations are indeed necessary),882 (\np[=.false.]{ln_bt_fw}{ln\_bt\_fw}). 883 Although more computationaly expensive ( \np{nn_baro}{nn\_baro} additional iterations are indeed necessary), 922 884 the baroclinic to barotropic forcing term given at \textit{now} time step become centred in 923 885 the middle of the integration window. … … 926 888 %references to Patrick Marsaleix' work here. Also work done by SHOM group. 927 889 928 %%%929 890 930 891 As far as tracer conservation is concerned, … … 936 897 and time splitting not compatible. 937 898 Advective barotropic velocities are obtained by using a secondary set of filtering weights, 938 uniquely defined from the filter coefficients used for the time averaging (\citet{ Shchepetkin_McWilliams_OM05}).899 uniquely defined from the filter coefficients used for the time averaging (\citet{shchepetkin.mcwilliams_OM05}). 939 900 Consistency between the time averaged continuity equation and the time stepping of tracers is here the key to 940 901 obtain exact conservation. 941 902 942 %%%943 903 944 904 One can eventually choose to feedback instantaneous values by not using any time filter 945 (\np {ln\_bt\_av}\forcode{ = .false.}).905 (\np[=.false.]{ln_bt_av}{ln\_bt\_av}). 946 906 In that case, external mode equations are continuous in time, 947 \ie they are not re-initialized when starting a new sub-stepping sequence.907 \ie\ they are not re-initialized when starting a new sub-stepping sequence. 948 908 This is the method used so far in the POM model, the stability being maintained by 949 909 refreshing at (almost) each barotropic time step advection and horizontal diffusion terms. 950 Since the latter terms have not been added in \NEMO for computational efficiency,910 Since the latter terms have not been added in \NEMO\ for computational efficiency, 951 911 removing time filtering is not recommended except for debugging purposes. 952 912 This may be used for instance to appreciate the damping effect of the standard formulation on 953 913 external gravity waves in idealized or weakly non-linear cases. 954 914 Although the damping is lower than for the filtered free surface, 955 it is still significant as shown by \citet{Levier2007} in the case of an analytical barotropic Kelvin wave. 956 957 %>>>>>=============== 958 \gmcomment{ %%% copy from griffies Book 915 it is still significant as shown by \citet{levier.treguier.ea_rpt07} in the case of an analytical barotropic Kelvin wave. 916 917 \cmtgm{ %%% copy from griffies Book 959 918 960 919 \textbf{title: Time stepping the barotropic system } … … 963 922 Hence, we can update the surface height and vertically integrated velocity with a leap-frog scheme using 964 923 the small barotropic time step $\rdt$. 965 We have 924 We have 966 925 967 926 \[ … … 986 945 and total depth of the ocean $H(\tau)$ are held for the duration of the barotropic time stepping over 987 946 a single cycle. 988 This is also the time that sets the barotropic time steps via 947 This is also the time that sets the barotropic time steps via 989 948 \[ 990 949 % \label{eq:DYN_spg_ts_t} … … 992 951 \] 993 952 with $n$ an integer. 994 The density scaled surface pressure is evaluated via 953 The density scaled surface pressure is evaluated via 995 954 \[ 996 955 % \label{eq:DYN_spg_ts_ps} … … 1001 960 \end{cases} 1002 961 \] 1003 To get started, we assume the following initial conditions 962 To get started, we assume the following initial conditions 1004 963 \[ 1005 964 % \label{eq:DYN_spg_ts_eta} … … 1009 968 \end{split} 1010 969 \] 1011 with 970 with 1012 971 \[ 1013 972 % \label{eq:DYN_spg_ts_etaF} … … 1015 974 \] 1016 975 the time averaged surface height taken from the previous barotropic cycle. 1017 Likewise, 976 Likewise, 1018 977 \[ 1019 978 % \label{eq:DYN_spg_ts_u} … … 1021 980 \textbf{U}(\tau,t_{n=1}) = \textbf{U}^{(b)}(\tau,t_{n=0}) + \rdt \ \text{RHS}_{n=0} 1022 981 \] 1023 with 982 with 1024 983 \[ 1025 984 % \label{eq:DYN_spg_ts_u} … … 1027 986 \] 1028 987 the time averaged vertically integrated transport. 1029 Notably, there is no Robert-Asselin time filter used in the barotropic portion of the integration. 988 Notably, there is no Robert-Asselin time filter used in the barotropic portion of the integration. 1030 989 1031 990 Upon reaching $t_{n=N} = \tau + 2\rdt \tau$ , 1032 991 the vertically integrated velocity is time averaged to produce the updated vertically integrated velocity at 1033 baroclinic time $\tau + \rdt \tau$ 992 baroclinic time $\tau + \rdt \tau$ 1034 993 \[ 1035 994 % \label{eq:DYN_spg_ts_u} … … 1037 996 \] 1038 997 The surface height on the new baroclinic time step is then determined via a baroclinic leap-frog using 1039 the following form 998 the following form 1040 999 1041 1000 \begin{equation} 1042 1001 \label{eq:DYN_spg_ts_ssh} 1043 \eta(\tau+\Delta) - \eta^{F}(\tau-\Delta) = 2\rdt \ \left[ - \nabla \cdot \textbf{U}(\tau) + \text{EMP}_w \right] 1002 \eta(\tau+\Delta) - \eta^{F}(\tau-\Delta) = 2\rdt \ \left[ - \nabla \cdot \textbf{U}(\tau) + \text{EMP}_w \right] 1044 1003 \end{equation} 1045 1004 1046 1005 The use of this "big-leap-frog" scheme for the surface height ensures compatibility between 1047 1006 the mass/volume budgets and the tracer budgets. 1048 More discussion of this point is provided in Chapter 10 (see in particular Section 10.2). 1049 1007 More discussion of this point is provided in Chapter 10 (see in particular Section 10.2). 1008 1050 1009 In general, some form of time filter is needed to maintain integrity of the surface height field due to 1051 1010 the leap-frog splitting mode in equation \autoref{eq:DYN_spg_ts_ssh}. 1052 1011 We have tried various forms of such filtering, 1053 with the following method discussed in \cite{ Griffies_al_MWR01} chosen due to1012 with the following method discussed in \cite{griffies.pacanowski.ea_MWR01} chosen due to 1054 1013 its stability and reasonably good maintenance of tracer conservation properties (see ??). 1055 1014 … … 1058 1017 \eta^{F}(\tau-\Delta) = \overline{\eta^{(b)}(\tau)} 1059 1018 \end{equation} 1060 Another approach tried was 1019 Another approach tried was 1061 1020 1062 1021 \[ … … 1071 1030 eliminating tracer and surface height time filtering (see ?? for more complete discussion). 1072 1031 However, in the general case with a non-zero $\alpha$, 1073 the filter \autoref{eq:DYN_spg_ts_sshf} was found to be more conservative, and so is recommended. 1032 the filter \autoref{eq:DYN_spg_ts_sshf} was found to be more conservative, and so is recommended. 1074 1033 1075 1034 } %%end gm comment (copy of griffies book) 1076 1035 1077 %>>>>>=============== 1078 1079 1080 %-------------------------------------------------------------------------------------------------------------- 1081 % Filtered free surface formulation 1082 %-------------------------------------------------------------------------------------------------------------- 1083 \subsection{Filtered free surface (\protect\key{dynspg\_flt})} 1036 %% ================================================================================================= 1037 \subsection{Filtered free surface (\forcode{dynspg_flt?})} 1084 1038 \label{subsec:DYN_spg_fltp} 1085 1039 1086 The filtered formulation follows the \citet{ Roullet_Madec_JGR00} implementation.1087 The extra term introduced in the equations (see \autoref{subsec: PE_free_surface}) is solved implicitly.1040 The filtered formulation follows the \citet{roullet.madec_JGR00} implementation. 1041 The extra term introduced in the equations (see \autoref{subsec:MB_free_surface}) is solved implicitly. 1088 1042 The elliptic solvers available in the code are documented in \autoref{chap:MISC}. 1089 1043 1090 1044 %% gm %%======>>>> given here the discrete eqs provided to the solver 1091 \ gmcomment{ %%% copy from chap-model basics1045 \cmtgm{ %%% copy from chap-model basics 1092 1046 \[ 1093 % \label{eq: spg_flt}1094 \frac{\partial {\ rm {\bf U}}_h }{\partial t}= {\rm {\bf M}}1047 % \label{eq:DYN_spg_flt} 1048 \frac{\partial {\mathrm {\mathbf U}}_h }{\partial t}= {\mathrm {\mathbf M}} 1095 1049 - g \nabla \left( \tilde{\rho} \ \eta \right) 1096 1050 - g \ T_c \nabla \left( \widetilde{\rho} \ \partial_t \eta \right) … … 1098 1052 where $T_c$, is a parameter with dimensions of time which characterizes the force, 1099 1053 $\widetilde{\rho} = \rho / \rho_o$ is the dimensionless density, 1100 and $\ rm {\bf M}$ represents the collected contributions of the Coriolis, hydrostatic pressure gradient,1101 non-linear and viscous terms in \autoref{eq: PE_dyn}.1102 } %end gmcomment1103 1104 Note that in the linear free surface formulation (\ key{vvl} not defined),1054 and $\mathrm {\mathbf M}$ represents the collected contributions of the Coriolis, hydrostatic pressure gradient, 1055 non-linear and viscous terms in \autoref{eq:MB_dyn}. 1056 } %end cmtgm 1057 1058 Note that in the linear free surface formulation (\texttt{vvl?} not defined), 1105 1059 the ocean depth is time-independent and so is the matrix to be inverted. 1106 It is computed once and for all and applies to all ocean time steps. 1107 1108 % ================================================================ 1109 % Lateral diffusion term 1110 % ================================================================ 1111 \section{Lateral diffusion term and operators (\protect\mdl{dynldf})} 1060 It is computed once and for all and applies to all ocean time steps. 1061 1062 %% ================================================================================================= 1063 \section[Lateral diffusion term and operators (\textit{dynldf.F90})]{Lateral diffusion term and operators (\protect\mdl{dynldf})} 1112 1064 \label{sec:DYN_ldf} 1113 %------------------------------------------nam_dynldf---------------------------------------------------- 1114 1115 \nlst{namdyn_ldf} 1116 %------------------------------------------------------------------------------------------------------------- 1117 1118 Options are defined through the \ngn{namdyn\_ldf} namelist variables. 1065 1066 \begin{listing} 1067 \nlst{namdyn_ldf} 1068 \caption{\forcode{&namdyn_ldf}} 1069 \label{lst:namdyn_ldf} 1070 \end{listing} 1071 1072 Options are defined through the \nam{dyn_ldf}{dyn\_ldf} namelist variables. 1119 1073 The options available for lateral diffusion are to use either laplacian (rotated or not) or biharmonic operators. 1120 1074 The coefficients may be constant or spatially variable; 1121 1075 the description of the coefficients is found in the chapter on lateral physics (\autoref{chap:LDF}). 1122 1076 The lateral diffusion of momentum is evaluated using a forward scheme, 1123 \ie the velocity appearing in its expression is the \textit{before} velocity in time,1077 \ie\ the velocity appearing in its expression is the \textit{before} velocity in time, 1124 1078 except for the pure vertical component that appears when a tensor of rotation is used. 1125 This latter term is solved implicitly together with the vertical diffusion term (see \autoref{chap: STP}).1079 This latter term is solved implicitly together with the vertical diffusion term (see \autoref{chap:TD}). 1126 1080 1127 1081 At the lateral boundaries either free slip, 1128 1082 no slip or partial slip boundary conditions are applied according to the user's choice (see \autoref{chap:LBC}). 1129 1083 1130 \ gmcomment{1084 \cmtgm{ 1131 1085 Hyperviscous operators are frequently used in the simulation of turbulent flows to 1132 1086 control the dissipation of unresolved small scale features. … … 1137 1091 In finite difference methods, 1138 1092 the biharmonic operator is frequently the method of choice to achieve this scale selective dissipation since 1139 its damping time (\ie its spin down time) scale like $\lambda^{-4}$ for disturbances of wavelength $\lambda$1093 its damping time (\ie\ its spin down time) scale like $\lambda^{-4}$ for disturbances of wavelength $\lambda$ 1140 1094 (so that short waves damped more rapidelly than long ones), 1141 1095 whereas the Laplace operator damping time scales only like $\lambda^{-2}$. 1142 1096 } 1143 1097 1144 % ================================================================ 1145 \subsection[Iso-level laplacian (\protect\np{ln\_dynldf\_lap}\forcode{ = .true.})] 1146 {Iso-level laplacian operator (\protect\np{ln\_dynldf\_lap}\forcode{ = .true.})} 1098 %% ================================================================================================= 1099 \subsection[Iso-level laplacian (\forcode{ln_dynldf_lap})]{Iso-level laplacian operator (\protect\np{ln_dynldf_lap}{ln\_dynldf\_lap})} 1147 1100 \label{subsec:DYN_ldf_lap} 1148 1101 1149 For lateral iso-level diffusion, the discrete operator is: 1150 \begin{equation} 1151 \label{eq: dynldf_lap}1102 For lateral iso-level diffusion, the discrete operator is: 1103 \begin{equation} 1104 \label{eq:DYN_ldf_lap} 1152 1105 \left\{ 1153 1106 \begin{aligned} 1154 D_u^{l{\ rm {\bf U}}} =\frac{1}{e_{1u} }\delta_{i+1/2} \left[ {A_T^{lm}1155 \;\chi } \right]-\frac{1}{e_{2u} {\kern 1pt}e_{3u} }\delta_j \left[ 1107 D_u^{l{\mathrm {\mathbf U}}} =\frac{1}{e_{1u} }\delta_{i+1/2} \left[ {A_T^{lm} 1108 \;\chi } \right]-\frac{1}{e_{2u} {\kern 1pt}e_{3u} }\delta_j \left[ 1156 1109 {A_f^{lm} \;e_{3f} \zeta } \right] \\ \\ 1157 D_v^{l{\ rm {\bf U}}} =\frac{1}{e_{2v} }\delta_{j+1/2} \left[ {A_T^{lm}1158 \;\chi } \right]+\frac{1}{e_{1v} {\kern 1pt}e_{3v} }\delta_i \left[ 1110 D_v^{l{\mathrm {\mathbf U}}} =\frac{1}{e_{2v} }\delta_{j+1/2} \left[ {A_T^{lm} 1111 \;\chi } \right]+\frac{1}{e_{1v} {\kern 1pt}e_{3v} }\delta_i \left[ 1159 1112 {A_f^{lm} \;e_{3f} \zeta } \right] 1160 1113 \end{aligned} 1161 1114 \right. 1162 \end{equation} 1163 1164 As explained in \autoref{subsec: PE_ldf},1115 \end{equation} 1116 1117 As explained in \autoref{subsec:MB_ldf}, 1165 1118 this formulation (as the gradient of a divergence and curl of the vorticity) preserves symmetry and 1166 ensures a complete separation between the vorticity and divergence parts of the momentum diffusion. 1167 1168 %-------------------------------------------------------------------------------------------------------------- 1169 % Rotated laplacian operator 1170 %-------------------------------------------------------------------------------------------------------------- 1171 \subsection[Rotated laplacian (\protect\np{ln\_dynldf\_iso}\forcode{ = .true.})] 1172 {Rotated laplacian operator (\protect\np{ln\_dynldf\_iso}\forcode{ = .true.})} 1119 ensures a complete separation between the vorticity and divergence parts of the momentum diffusion. 1120 1121 %% ================================================================================================= 1122 \subsection[Rotated laplacian (\forcode{ln_dynldf_iso})]{Rotated laplacian operator (\protect\np{ln_dynldf_iso}{ln\_dynldf\_iso})} 1173 1123 \label{subsec:DYN_ldf_iso} 1174 1124 1175 1125 A rotation of the lateral momentum diffusion operator is needed in several cases: 1176 for iso-neutral diffusion in the $z$-coordinate (\np {ln\_dynldf\_iso}\forcode{ = .true.}) and1177 for either iso-neutral (\np {ln\_dynldf\_iso}\forcode{ = .true.}) or1178 geopotential (\np {ln\_dynldf\_hor}\forcode{ = .true.}) diffusion in the $s$-coordinate.1126 for iso-neutral diffusion in the $z$-coordinate (\np[=.true.]{ln_dynldf_iso}{ln\_dynldf\_iso}) and 1127 for either iso-neutral (\np[=.true.]{ln_dynldf_iso}{ln\_dynldf\_iso}) or 1128 geopotential (\np[=.true.]{ln_dynldf_hor}{ln\_dynldf\_hor}) diffusion in the $s$-coordinate. 1179 1129 In the partial step case, coordinates are horizontal except at the deepest level and 1180 no rotation is performed when \np {ln\_dynldf\_hor}\forcode{ = .true.}.1130 no rotation is performed when \np[=.true.]{ln_dynldf_hor}{ln\_dynldf\_hor}. 1181 1131 The diffusion operator is defined simply as the divergence of down gradient momentum fluxes on 1182 1132 each momentum component. … … 1184 1134 The resulting discrete representation is: 1185 1135 \begin{equation} 1186 \label{eq: dyn_ldf_iso}1136 \label{eq:DYN_ldf_iso} 1187 1137 \begin{split} 1188 1138 D_u^{l\textbf{U}} &= \frac{1}{e_{1u} \, e_{2u} \, e_{3u} } \\ … … 1208 1158 -e_{2f} \; r_{1f} \,\overline{\overline {\delta_{k+1/2}[v]}}^{\,i+1/2,\,k}} 1209 1159 \right)} \right]} \right. \\ 1210 & \qquad +\ \delta_j \left[ {A_T^{lm} \left( {\frac{e_{1t}\,e_{3t} }{e_{2t} 1160 & \qquad +\ \delta_j \left[ {A_T^{lm} \left( {\frac{e_{1t}\,e_{3t} }{e_{2t} 1211 1161 }\,\delta_{j} [v] - e_{1t}\, r_{2t} 1212 1162 \,\overline{\overline {\delta_{k+1/2} [v]}} ^{\,j,\,k}} 1213 1163 \right)} \right] \\ 1214 & \qquad +\ \delta_k \left[ {A_{vw}^{lm} \left( {-e_{2v} \, r_{1vw} \,\overline{\overline 1164 & \qquad +\ \delta_k \left[ {A_{vw}^{lm} \left( {-e_{2v} \, r_{1vw} \,\overline{\overline 1215 1165 {\delta_{i+1/2} [v]}}^{\,i+1/2,\,k+1/2} }\right.} \right. \\ 1216 1166 & \ \qquad \qquad \qquad \quad\ 1217 1167 - e_{1v} \, r_{2vw} \,\overline{\overline {\delta_{j+1/2} [v]}} ^{\,j+1/2,\,k+1/2} \\ 1218 & \left. {\left. { \ \qquad \qquad \qquad \ \ \ \left. {\ 1168 & \left. {\left. { \ \qquad \qquad \qquad \ \ \ \left. {\ 1219 1169 +\frac{e_{1v}\, e_{2v} }{e_{3vw} }\,\left( {r_{1vw}^2+r_{2vw}^2} 1220 \right)\,\delta_{k+1/2} [v]} \right)} \right]\;\;\;} \right\} 1170 \right)\,\delta_{k+1/2} [v]} \right)} \right]\;\;\;} \right\} 1221 1171 \end{split} 1222 1172 \end{equation} 1223 1173 where $r_1$ and $r_2$ are the slopes between the surface along which the diffusion operator acts and 1224 the surface of computation ($z$- or $s$-surfaces). 1174 the surface of computation ($z$- or $s$-surfaces). 1225 1175 The way these slopes are evaluated is given in the lateral physics chapter (\autoref{chap:LDF}). 1226 1176 1227 %-------------------------------------------------------------------------------------------------------------- 1228 % Iso-level bilaplacian operator 1229 %-------------------------------------------------------------------------------------------------------------- 1230 \subsection[Iso-level bilaplacian (\protect\np{ln\_dynldf\_bilap}\forcode{ = .true.})] 1231 {Iso-level bilaplacian operator (\protect\np{ln\_dynldf\_bilap}\forcode{ = .true.})} 1177 %% ================================================================================================= 1178 \subsection[Iso-level bilaplacian (\forcode{ln_dynldf_bilap})]{Iso-level bilaplacian operator (\protect\np{ln_dynldf_bilap}{ln\_dynldf\_bilap})} 1232 1179 \label{subsec:DYN_ldf_bilap} 1233 1180 1234 The lateral fourth order operator formulation on momentum is obtained by applying \autoref{eq: dynldf_lap} twice.1181 The lateral fourth order operator formulation on momentum is obtained by applying \autoref{eq:DYN_ldf_lap} twice. 1235 1182 It requires an additional assumption on boundary conditions: 1236 1183 the first derivative term normal to the coast depends on the free or no-slip lateral boundary conditions chosen, 1237 1184 while the third derivative terms normal to the coast are set to zero (see \autoref{chap:LBC}). 1238 %%% 1239 \gmcomment{add a remark on the the change in the position of the coefficient} 1240 %%% 1241 1242 % ================================================================ 1243 % Vertical diffusion term 1244 % ================================================================ 1245 \section{Vertical diffusion term (\protect\mdl{dynzdf})} 1185 \cmtgm{add a remark on the the change in the position of the coefficient} 1186 1187 %% ================================================================================================= 1188 \section[Vertical diffusion term (\textit{dynzdf.F90})]{Vertical diffusion term (\protect\mdl{dynzdf})} 1246 1189 \label{sec:DYN_zdf} 1247 %----------------------------------------------namzdf------------------------------------------------------ 1248 1249 \nlst{namzdf} 1250 %------------------------------------------------------------------------------------------------------------- 1251 1252 Options are defined through the \ngn{namzdf} namelist variables. 1190 1191 Options are defined through the \nam{zdf}{zdf} namelist variables. 1253 1192 The large vertical diffusion coefficient found in the surface mixed layer together with high vertical resolution implies that in the case of explicit time stepping there would be too restrictive a constraint on the time step. 1254 1193 Two time stepping schemes can be used for the vertical diffusion term: 1255 1194 $(a)$ a forward time differencing scheme 1256 (\np {ln\_zdfexp}\forcode{ = .true.}) using a time splitting technique (\np{nn\_zdfexp} $>$ 1) or1257 $(b)$ a backward (or implicit) time differencing scheme (\np {ln\_zdfexp}\forcode{ = .false.})1258 (see \autoref{chap: STP}).1259 Note that namelist variables \np{ln \_zdfexp} and \np{nn\_zdfexp} apply to both tracers and dynamics.1195 (\np[=.true.]{ln_zdfexp}{ln\_zdfexp}) using a time splitting technique (\np{nn_zdfexp}{nn\_zdfexp} $>$ 1) or 1196 $(b)$ a backward (or implicit) time differencing scheme (\np[=.false.]{ln_zdfexp}{ln\_zdfexp}) 1197 (see \autoref{chap:TD}). 1198 Note that namelist variables \np{ln_zdfexp}{ln\_zdfexp} and \np{nn_zdfexp}{nn\_zdfexp} apply to both tracers and dynamics. 1260 1199 1261 1200 The formulation of the vertical subgrid scale physics is the same whatever the vertical coordinate is. 1262 The vertical diffusion operators given by \autoref{eq: PE_zdf} take the following semi-discrete space form:1263 \[ 1264 % \label{eq: dynzdf}1201 The vertical diffusion operators given by \autoref{eq:MB_zdf} take the following semi-discrete space form: 1202 \[ 1203 % \label{eq:DYN_zdf} 1265 1204 \left\{ 1266 1205 \begin{aligned} … … 1280 1219 the vertical turbulent momentum fluxes, 1281 1220 \begin{equation} 1282 \label{eq: dynzdf_sbc}1221 \label{eq:DYN_zdf_sbc} 1283 1222 \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{z=1} 1284 1223 = \frac{1}{\rho_o} \binom{\tau_u}{\tau_v } … … 1286 1225 where $\left( \tau_u ,\tau_v \right)$ are the two components of the wind stress vector in 1287 1226 the (\textbf{i},\textbf{j}) coordinate system. 1288 The high mixing coefficients in the surface mixed layer ensure that the surface wind stress is distributed in 1227 The high mixing coefficients in the surface mixed layer ensure that the surface wind stress is distributed in 1289 1228 the vertical over the mixed layer depth. 1290 1229 If the vertical mixing coefficient is small (when no mixed layer scheme is used) … … 1293 1232 1294 1233 The turbulent flux of momentum at the bottom of the ocean is specified through a bottom friction parameterisation 1295 (see \autoref{sec:ZDF_bfr}) 1296 1297 % ================================================================ 1298 % External Forcing 1299 % ================================================================ 1234 (see \autoref{sec:ZDF_drg}) 1235 1236 %% ================================================================================================= 1300 1237 \section{External forcings} 1301 1238 \label{sec:DYN_forcing} … … 1303 1240 Besides the surface and bottom stresses (see the above section) 1304 1241 which are introduced as boundary conditions on the vertical mixing, 1305 three other forcings may enter the dynamical equations by affecting the surface pressure gradient. 1306 1307 (1) When \np {ln\_apr\_dyn}\forcode{ = .true.} (see \autoref{sec:SBC_apr}),1242 three other forcings may enter the dynamical equations by affecting the surface pressure gradient. 1243 1244 (1) When \np[=.true.]{ln_apr_dyn}{ln\_apr\_dyn} (see \autoref{sec:SBC_apr}), 1308 1245 the atmospheric pressure is taken into account when computing the surface pressure gradient. 1309 1246 1310 (2) When \np {ln\_tide\_pot}\forcode{ = .true.} and \np{ln\_tide}\forcode{ = .true.} (see \autoref{sec:SBC_tide}),1247 (2) When \np[=.true.]{ln_tide_pot}{ln\_tide\_pot} and \np[=.true.]{ln_tide}{ln\_tide} (see \autoref{sec:SBC_tide}), 1311 1248 the tidal potential is taken into account when computing the surface pressure gradient. 1312 1249 1313 (3) When \np {nn\_ice\_embd}\forcode{ = 2} and LIM or CICE is used1314 (\ie when the sea-ice is embedded in the ocean),1250 (3) When \np[=2]{nn_ice_embd}{nn\_ice\_embd} and LIM or CICE is used 1251 (\ie\ when the sea-ice is embedded in the ocean), 1315 1252 the snow-ice mass is taken into account when computing the surface pressure gradient. 1316 1253 1317 1318 \gmcomment{ missing : the lateral boundary condition !!! another external forcing 1254 \cmtgm{ missing : the lateral boundary condition !!! another external forcing 1319 1255 } 1320 1256 1321 % ================================================================ 1322 % Wetting and drying 1323 % ================================================================ 1257 %% ================================================================================================= 1324 1258 \section{Wetting and drying } 1325 1259 \label{sec:DYN_wetdry} 1260 1326 1261 There are two main options for wetting and drying code (wd): 1327 1262 (a) an iterative limiter (il) and (b) a directional limiter (dl). 1328 The directional limiter is based on the scheme developed by \cite{ WarnerEtal13} for RO1263 The directional limiter is based on the scheme developed by \cite{warner.defne.ea_CG13} for RO 1329 1264 MS 1330 which was in turn based on ideas developed for POM by \cite{ Oey06}. The iterative1265 which was in turn based on ideas developed for POM by \cite{oey_OM06}. The iterative 1331 1266 limiter is a new scheme. The iterative limiter is activated by setting $\mathrm{ln\_wd\_il} = \mathrm{.true.}$ 1332 1267 and $\mathrm{ln\_wd\_dl} = \mathrm{.false.}$. The directional limiter is activated 1333 1268 by setting $\mathrm{ln\_wd\_dl} = \mathrm{.true.}$ and $\mathrm{ln\_wd\_il} = \mathrm{.false.}$. 1334 1269 1335 \nlst{namwad} 1270 \begin{listing} 1271 \nlst{namwad} 1272 \caption{\forcode{&namwad}} 1273 \label{lst:namwad} 1274 \end{listing} 1336 1275 1337 1276 The following terminology is used. The depth of the topography (positive downwards) 1338 at each $(i,j)$ point is the quantity stored in array $\mathrm{ht\_wd}$ in the NEMOcode.1277 at each $(i,j)$ point is the quantity stored in array $\mathrm{ht\_wd}$ in the \NEMO\ code. 1339 1278 The height of the free surface (positive upwards) is denoted by $ \mathrm{ssh}$. Given the sign 1340 1279 conventions used, the water depth, $h$, is the height of the free surface plus the depth of the … … 1344 1283 covered by water. They require the topography specified with a model 1345 1284 configuration to have negative depths at points where the land is higher than the 1346 topography's reference sea-level. The vertical grid in NEMOis normally computed relative to an1285 topography's reference sea-level. The vertical grid in \NEMO\ is normally computed relative to an 1347 1286 initial state with zero sea surface height elevation. 1348 1287 The user can choose to compute the vertical grid and heights in the model relative to … … 1363 1302 All these configurations have used pure sigma coordinates. It is expected that 1364 1303 the wetting and drying code will work in domains with more general s-coordinates provided 1365 the coordinates are pure sigma in the region where wetting and drying actually occurs. 1304 the coordinates are pure sigma in the region where wetting and drying actually occurs. 1366 1305 1367 1306 The next sub-section descrbies the directional limiter and the following sub-section the iterative limiter. 1368 1307 The final sub-section covers some additional considerations that are relevant to both schemes. 1369 1308 1370 1371 %-----------------------------------------------------------------------------------------1372 1309 % Iterative limiters 1373 %----------------------------------------------------------------------------------------- 1374 \subsection [Directional limiter (\textit{wet\_dry})] 1375 {Directional limiter (\mdl{wet\_dry})} 1310 %% ================================================================================================= 1311 \subsection[Directional limiter (\textit{wet\_dry.F90})]{Directional limiter (\mdl{wet\_dry})} 1376 1312 \label{subsec:DYN_wd_directional_limiter} 1313 1377 1314 The principal idea of the directional limiter is that 1378 water should not be allowed to flow out of a dry tracer cell (i.e. one whose water depth is less than rn\_wdmin1).1315 water should not be allowed to flow out of a dry tracer cell (i.e. one whose water depth is less than \np{rn_wdmin1}{rn\_wdmin1}). 1379 1316 1380 1317 All the changes associated with this option are made to the barotropic solver for the non-linear … … 1386 1323 1387 1324 The flux across each $u$-face of a tracer cell is multiplied by a factor zuwdmask (an array which depends on ji and jj). 1388 If the user sets ln\_wd\_dl\_ramp = .False.then zuwdmask is 1 when the1389 flux is from a cell with water depth greater than rn\_wdmin1and 0 otherwise. If the user sets1390 ln\_wd\_dl\_ramp = .True.the flux across the face is ramped down as the water depth decreases1391 from 2 * rn\_wdmin1 to rn\_wdmin1. The use of this ramp reduced grid-scale noise in idealised test cases.1325 If the user sets \np[=.false.]{ln_wd_dl_ramp}{ln\_wd\_dl\_ramp} then zuwdmask is 1 when the 1326 flux is from a cell with water depth greater than \np{rn_wdmin1}{rn\_wdmin1} and 0 otherwise. If the user sets 1327 \np[=.true.]{ln_wd_dl_ramp}{ln\_wd\_dl\_ramp} the flux across the face is ramped down as the water depth decreases 1328 from 2 * \np{rn_wdmin1}{rn\_wdmin1} to \np{rn_wdmin1}{rn\_wdmin1}. The use of this ramp reduced grid-scale noise in idealised test cases. 1392 1329 1393 1330 At the point where the flux across a $u$-face is multiplied by zuwdmask , we have chosen … … 1399 1336 treatment in the calculation of the flux of mass across the cell face. 1400 1337 1401 1402 \cite{WarnerEtal13} state that in their scheme the velocity masks at the cell faces for the baroclinic 1338 \cite{warner.defne.ea_CG13} state that in their scheme the velocity masks at the cell faces for the baroclinic 1403 1339 timesteps are set to 0 or 1 depending on whether the average of the masks over the barotropic sub-steps is respectively less than 1404 1340 or greater than 0.5. That scheme does not conserve tracers in integrations started from constant tracer 1405 1341 fields (tracers independent of $x$, $y$ and $z$). Our scheme conserves constant tracers because 1406 1342 the velocities used at the tracer cell faces on the baroclinic timesteps are carefully calculated by dynspg\_ts 1407 to equal their mean value during the barotropic steps. If the user sets ln\_wd\_dl\_bc = .True., the 1408 baroclinic velocities are also multiplied by a suitably weighted average of zuwdmask. 1409 1410 %----------------------------------------------------------------------------------------- 1343 to equal their mean value during the barotropic steps. If the user sets \np[=.true.]{ln_wd_dl_bc}{ln\_wd\_dl\_bc}, the 1344 baroclinic velocities are also multiplied by a suitably weighted average of zuwdmask. 1345 1411 1346 % Iterative limiters 1412 %----------------------------------------------------------------------------------------- 1413 1414 \subsection [Iterative limiter (\textit{wet\_dry})] 1415 {Iterative limiter (\mdl{wet\_dry})} 1347 1348 %% ================================================================================================= 1349 \subsection[Iterative limiter (\textit{wet\_dry.F90})]{Iterative limiter (\mdl{wet\_dry})} 1416 1350 \label{subsec:DYN_wd_iterative_limiter} 1417 1351 1418 \subsubsection [Iterative flux limiter (\textit{wet\_dry})] 1419 1420 \label{subs ubsec:DYN_wd_il_spg_limiter}1352 %% ================================================================================================= 1353 \subsubsection[Iterative flux limiter (\textit{wet\_dry.F90})]{Iterative flux limiter (\mdl{wet\_dry})} 1354 \label{subsec:DYN_wd_il_spg_limiter} 1421 1355 1422 1356 The iterative limiter modifies the fluxes across the faces of cells that are either already ``dry'' … … 1426 1360 1427 1361 The continuity equation for the total water depth in a column 1428 \begin{equation} \label{dyn_wd_continuity} 1429 \frac{\partial h}{\partial t} + \mathbf{\nabla.}(h\mathbf{u}) = 0 . 1362 \begin{equation} 1363 \label{eq:DYN_wd_continuity} 1364 \frac{\partial h}{\partial t} + \mathbf{\nabla.}(h\mathbf{u}) = 0 . 1430 1365 \end{equation} 1431 1366 can be written in discrete form as 1432 1367 1433 \begin{align} \label{dyn_wd_continuity_2} 1434 \frac{e_1 e_2}{\Delta t} ( h_{i,j}(t_{n+1}) - h_{i,j}(t_e) ) 1435 &= - ( \mathrm{flxu}_{i+1,j} - \mathrm{flxu}_{i,j} + \mathrm{flxv}_{i,j+1} - \mathrm{flxv}_{i,j} ) \\ 1436 &= \mathrm{zzflx}_{i,j} . 1368 \begin{align} 1369 \label{eq:DYN_wd_continuity_2} 1370 \frac{e_1 e_2}{\Delta t} ( h_{i,j}(t_{n+1}) - h_{i,j}(t_e) ) 1371 &= - ( \mathrm{flxu}_{i+1,j} - \mathrm{flxu}_{i,j} + \mathrm{flxv}_{i,j+1} - \mathrm{flxv}_{i,j} ) \\ 1372 &= \mathrm{zzflx}_{i,j} . 1437 1373 \end{align} 1438 1374 … … 1447 1383 (zzflxp) and fluxes that are into the cell (zzflxn). Clearly 1448 1384 1449 \begin{equation} \label{dyn_wd_zzflx_p_n_1} 1450 \mathrm{zzflx}_{i,j} = \mathrm{zzflxp}_{i,j} + \mathrm{zzflxn}_{i,j} . 1385 \begin{equation} 1386 \label{eq:DYN_wd_zzflx_p_n_1} 1387 \mathrm{zzflx}_{i,j} = \mathrm{zzflxp}_{i,j} + \mathrm{zzflxn}_{i,j} . 1451 1388 \end{equation} 1452 1389 … … 1459 1396 $\mathrm{zcoef}_{i,j}^{(m)}$ such that: 1460 1397 1461 \begin{equation} \label{dyn_wd_continuity_coef} 1462 \begin{split} 1463 \mathrm{zzflxp}^{(m)}_{i,j} =& \mathrm{zcoef}_{i,j}^{(m)} \mathrm{zzflxp}^{(0)}_{i,j} \\ 1464 \mathrm{zzflxn}^{(m)}_{i,j} =& \mathrm{zcoef}_{i,j}^{(m)} \mathrm{zzflxn}^{(0)}_{i,j} 1465 \end{split} 1398 \begin{equation} 1399 \label{eq:DYN_wd_continuity_coef} 1400 \begin{split} 1401 \mathrm{zzflxp}^{(m)}_{i,j} =& \mathrm{zcoef}_{i,j}^{(m)} \mathrm{zzflxp}^{(0)}_{i,j} \\ 1402 \mathrm{zzflxn}^{(m)}_{i,j} =& \mathrm{zcoef}_{i,j}^{(m)} \mathrm{zzflxn}^{(0)}_{i,j} 1403 \end{split} 1466 1404 \end{equation} 1467 1405 … … 1471 1409 The iteration is initialised by setting 1472 1410 1473 \begin{equation} \label{dyn_wd_zzflx_initial} 1474 \mathrm{zzflxp^{(0)}}_{i,j} = \mathrm{zzflxp}_{i,j} , \quad \mathrm{zzflxn^{(0)}}_{i,j} = \mathrm{zzflxn}_{i,j} . 1411 \begin{equation} 1412 \label{eq:DYN_wd_zzflx_initial} 1413 \mathrm{zzflxp^{(0)}}_{i,j} = \mathrm{zzflxp}_{i,j} , \quad \mathrm{zzflxn^{(0)}}_{i,j} = \mathrm{zzflxn}_{i,j} . 1475 1414 \end{equation} 1476 1415 1477 1416 The fluxes out of cell $(i,j)$ are updated at the $m+1$th iteration if the depth of the 1478 1417 cell on timestep $t_e$, namely $h_{i,j}(t_e)$, is less than the total flux out of the cell 1479 times the timestep divided by the cell area. Using (\ ref{dyn_wd_continuity_2}) this1418 times the timestep divided by the cell area. Using (\autoref{eq:DYN_wd_continuity_2}) this 1480 1419 condition is 1481 1420 1482 \begin{equation} \label{dyn_wd_continuity_if} 1483 h_{i,j}(t_e) - \mathrm{rn\_wdmin1} < \frac{\Delta t}{e_1 e_2} ( \mathrm{zzflxp}^{(m)}_{i,j} + \mathrm{zzflxn}^{(m)}_{i,j} ) . 1484 \end{equation} 1485 1486 Rearranging (\ref{dyn_wd_continuity_if}) we can obtain an expression for the maximum 1421 \begin{equation} 1422 \label{eq:DYN_wd_continuity_if} 1423 h_{i,j}(t_e) - \mathrm{rn\_wdmin1} < \frac{\Delta t}{e_1 e_2} ( \mathrm{zzflxp}^{(m)}_{i,j} + \mathrm{zzflxn}^{(m)}_{i,j} ) . 1424 \end{equation} 1425 1426 Rearranging (\autoref{eq:DYN_wd_continuity_if}) we can obtain an expression for the maximum 1487 1427 outward flux that can be allowed and still maintain the minimum wet depth: 1488 1428 1489 \begin{equation} \label{dyn_wd_max_flux} 1490 \begin{split} 1491 \mathrm{zzflxp}^{(m+1)}_{i,j} = \Big[ (h_{i,j}(t_e) & - \mathrm{rn\_wdmin1} - \mathrm{rn\_wdmin2}) \frac{e_1 e_2}{\Delta t} \phantom{]} \\ 1492 \phantom{[} & - \mathrm{zzflxn}^{(m)}_{i,j} \Big] 1493 \end{split} 1494 \end{equation} 1495 1496 Note a small tolerance ($\mathrm{rn\_wdmin2}$) has been introduced here {\it [Q: Why is 1497 this necessary/desirable?]}. Substituting from (\ref{dyn_wd_continuity_coef}) gives an 1429 \begin{equation} 1430 \label{eq:DYN_wd_max_flux} 1431 \begin{split} 1432 \mathrm{zzflxp}^{(m+1)}_{i,j} = \Big[ (h_{i,j}(t_e) & - \mathrm{rn\_wdmin1} - \mathrm{rn\_wdmin2}) \frac{e_1 e_2}{\Delta t} \phantom{]} \\ 1433 \phantom{[} & - \mathrm{zzflxn}^{(m)}_{i,j} \Big] 1434 \end{split} 1435 \end{equation} 1436 1437 Note a small tolerance ($\mathrm{rn\_wdmin2}$) has been introduced here {\itshape [Q: Why is 1438 this necessary/desirable?]}. Substituting from (\autoref{eq:DYN_wd_continuity_coef}) gives an 1498 1439 expression for the coefficient needed to multiply the outward flux at this cell in order 1499 1440 to avoid drying. 1500 1441 1501 \begin{equation} \label{dyn_wd_continuity_nxtcoef} 1502 \begin{split} 1503 \mathrm{zcoef}^{(m+1)}_{i,j} = \Big[ (h_{i,j}(t_e) & - \mathrm{rn\_wdmin1} - \mathrm{rn\_wdmin2}) \frac{e_1 e_2}{\Delta t} \phantom{]} \\ 1504 \phantom{[} & - \mathrm{zzflxn}^{(m)}_{i,j} \Big] \frac{1}{ \mathrm{zzflxp}^{(0)}_{i,j} } 1505 \end{split} 1442 \begin{equation} 1443 \label{eq:DYN_wd_continuity_nxtcoef} 1444 \begin{split} 1445 \mathrm{zcoef}^{(m+1)}_{i,j} = \Big[ (h_{i,j}(t_e) & - \mathrm{rn\_wdmin1} - \mathrm{rn\_wdmin2}) \frac{e_1 e_2}{\Delta t} \phantom{]} \\ 1446 \phantom{[} & - \mathrm{zzflxn}^{(m)}_{i,j} \Big] \frac{1}{ \mathrm{zzflxp}^{(0)}_{i,j} } 1447 \end{split} 1506 1448 \end{equation} 1507 1449 … … 1518 1460 directional limiter does. 1519 1461 1520 1521 %----------------------------------------------------------------------------------------1522 1462 % Surface pressure gradients 1523 %---------------------------------------------------------------------------------------- 1524 \subsubsection [Modification of surface pressure gradients (\textit{dynhpg})] 1525 {Modification of surface pressure gradients (\mdl{dynhpg})} 1526 \label{subsubsec:DYN_wd_il_spg} 1463 %% ================================================================================================= 1464 \subsubsection[Modification of surface pressure gradients (\textit{dynhpg.F90})]{Modification of surface pressure gradients (\mdl{dynhpg})} 1465 \label{subsec:DYN_wd_il_spg} 1527 1466 1528 1467 At ``dry'' points the water depth is usually close to $\mathrm{rn\_wdmin1}$. If the … … 1537 1476 neighbouring $(i+1,j)$ and $(i,j)$ tracer points. zcpx is calculated using two logicals 1538 1477 variables, $\mathrm{ll\_tmp1}$ and $\mathrm{ll\_tmp2}$ which are evaluated for each grid 1539 column. The three possible combinations are illustrated in figure \ref{Fig_WAD_dynhpg}. 1540 1541 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1542 \begin{figure}[!ht] \begin{center} 1543 \includegraphics[width=0.8\textwidth]{Fig_WAD_dynhpg} 1544 \caption{ \label{Fig_WAD_dynhpg} 1545 Illustrations of the three possible combinations of the logical variables controlling the 1546 limiting of the horizontal pressure gradient in wetting and drying regimes} 1547 \end{center}\end{figure} 1548 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1478 column. The three possible combinations are illustrated in \autoref{fig:DYN_WAD_dynhpg}. 1479 1480 \begin{figure}[!ht] 1481 \centering 1482 \includegraphics[width=0.66\textwidth]{DYN_WAD_dynhpg} 1483 \caption[Combinations controlling the limiting of the horizontal pressure gradient in 1484 wetting and drying regimes]{ 1485 Three possible combinations of the logical variables controlling the 1486 limiting of the horizontal pressure gradient in wetting and drying regimes} 1487 \label{fig:DYN_WAD_dynhpg} 1488 \end{figure} 1549 1489 1550 1490 The first logical, $\mathrm{ll\_tmp1}$, is set to true if and only if the water depth at … … 1553 1493 of the topography at the two points: 1554 1494 1555 \begin{equation} \label{dyn_ll_tmp1} 1556 \begin{split} 1557 \mathrm{ll\_tmp1} = & \mathrm{MIN(sshn(ji,jj), sshn(ji+1,jj))} > \\ 1495 \begin{equation} 1496 \label{eq:DYN_ll_tmp1} 1497 \begin{split} 1498 \mathrm{ll\_tmp1} = & \mathrm{MIN(sshn(ji,jj), sshn(ji+1,jj))} > \\ 1558 1499 & \quad \mathrm{MAX(-ht\_wd(ji,jj), -ht\_wd(ji+1,jj))\ .and.} \\ 1559 & \mathrm{MAX(sshn(ji,jj) + ht\_wd(ji,jj),} \\1560 & \mathrm{\phantom{MAX(}sshn(ji+1,jj) + ht\_wd(ji+1,jj))} >\\1561 & \quad\quad\mathrm{rn\_wdmin1 + rn\_wdmin2 }1562 \end{split}1500 & \mathrm{MAX(sshn(ji,jj) + ht\_wd(ji,jj),} \\ 1501 & \mathrm{\phantom{MAX(}sshn(ji+1,jj) + ht\_wd(ji+1,jj))} >\\ 1502 & \quad\quad\mathrm{rn\_wdmin1 + rn\_wdmin2 } 1503 \end{split} 1563 1504 \end{equation} 1564 1505 … … 1567 1508 at the two points plus $\mathrm{rn\_wdmin1} + \mathrm{rn\_wdmin2}$ 1568 1509 1569 \begin{equation} \label{dyn_ll_tmp2} 1570 \begin{split} 1571 \mathrm{ ll\_tmp2 } = & \mathrm{( ABS( sshn(ji,jj) - sshn(ji+1,jj) ) > 1.E-12 )\ .AND.}\\ 1572 & \mathrm{( MAX(sshn(ji,jj), sshn(ji+1,jj)) > } \\ 1573 & \mathrm{\phantom{(} MAX(-ht\_wd(ji,jj), -ht\_wd(ji+1,jj)) + rn\_wdmin1 + rn\_wdmin2}) . 1574 \end{split} 1510 \begin{equation} 1511 \label{eq:DYN_ll_tmp2} 1512 \begin{split} 1513 \mathrm{ ll\_tmp2 } = & \mathrm{( ABS( sshn(ji,jj) - sshn(ji+1,jj) ) > 1.E-12 )\ .AND.}\\ 1514 & \mathrm{( MAX(sshn(ji,jj), sshn(ji+1,jj)) > } \\ 1515 & \mathrm{\phantom{(} MAX(-ht\_wd(ji,jj), -ht\_wd(ji+1,jj)) + rn\_wdmin1 + rn\_wdmin2}) . 1516 \end{split} 1575 1517 \end{equation} 1576 1518 … … 1588 1530 conditions. 1589 1531 1590 \subsubsection [Additional considerations (\textit{usrdef\_zgr})] 1591 1592 \label{subs ubsec:WAD_additional}1532 %% ================================================================================================= 1533 \subsubsection[Additional considerations (\textit{usrdef\_zgr.F90})]{Additional considerations (\mdl{usrdef\_zgr})} 1534 \label{subsec:DYN_WAD_additional} 1593 1535 1594 1536 In the very shallow water where wetting and drying occurs the parametrisation of … … 1600 1542 in uncoupled integrations the net surface heat fluxes need to be appropriately limited. 1601 1543 1602 %----------------------------------------------------------------------------------------1603 1544 % The WAD test cases 1604 %---------------------------------------------------------------------------------------- 1605 \subsection [The WAD test cases (\textit{usrdef\_zgr})] 1606 {The WAD test cases (\mdl{usrdef\_zgr})} 1607 \label{WAD_test_cases} 1545 %% ================================================================================================= 1546 \subsection[The WAD test cases (\textit{usrdef\_zgr.F90})]{The WAD test cases (\mdl{usrdef\_zgr})} 1547 \label{subsec:DYN_WAD_test_cases} 1608 1548 1609 1549 See the WAD tests MY\_DOC documention for details of the WAD test cases. 1610 1550 1611 1612 1613 % ================================================================ 1614 % Time evolution term 1615 % ================================================================ 1616 \section{Time evolution term (\protect\mdl{dynnxt})} 1551 %% ================================================================================================= 1552 \section[Time evolution term (\textit{dynnxt.F90})]{Time evolution term (\protect\mdl{dynnxt})} 1617 1553 \label{sec:DYN_nxt} 1618 1554 1619 %----------------------------------------------namdom---------------------------------------------------- 1620 1621 \nlst{namdom} 1622 %------------------------------------------------------------------------------------------------------------- 1623 1624 Options are defined through the \ngn{namdom} namelist variables. 1555 Options are defined through the \nam{dom}{dom} namelist variables. 1625 1556 The general framework for dynamics time stepping is a leap-frog scheme, 1626 \ie a three level centred time scheme associated with an Asselin time filter (cf. \autoref{chap:STP}).1557 \ie\ a three level centred time scheme associated with an Asselin time filter (cf. \autoref{chap:TD}). 1627 1558 The scheme is applied to the velocity, except when 1628 1559 using the flux form of momentum advection (cf. \autoref{sec:DYN_adv_cor_flux}) 1629 in the variable volume case (\ key{vvl} defined),1630 where it has to be applied to the thickness weighted velocity (see \autoref{sec: A_momentum})1560 in the variable volume case (\texttt{vvl?} defined), 1561 where it has to be applied to the thickness weighted velocity (see \autoref{sec:SCOORD_momentum}) 1631 1562 1632 1563 $\bullet$ vector invariant form or linear free surface 1633 (\np {ln\_dynhpg\_vec}\forcode{ = .true.} ; \key{vvl} not defined):1634 \[ 1635 % \label{eq: dynnxt_vec}1564 (\np[=.true.]{ln_dynhpg_vec}{ln\_dynhpg\_vec} ; \texttt{vvl?} not defined): 1565 \[ 1566 % \label{eq:DYN_nxt_vec} 1636 1567 \left\{ 1637 1568 \begin{aligned} … … 1643 1574 1644 1575 $\bullet$ flux form and nonlinear free surface 1645 (\np {ln\_dynhpg\_vec}\forcode{ = .false.} ; \key{vvl} defined):1646 \[ 1647 % \label{eq: dynnxt_flux}1576 (\np[=.false.]{ln_dynhpg_vec}{ln\_dynhpg\_vec} ; \texttt{vvl?} defined): 1577 \[ 1578 % \label{eq:DYN_nxt_flux} 1648 1579 \left\{ 1649 1580 \begin{aligned} … … 1656 1587 where RHS is the right hand side of the momentum equation, 1657 1588 the subscript $f$ denotes filtered values and $\gamma$ is the Asselin coefficient. 1658 $\gamma$ is initialized as \np{nn \_atfp} (namelist parameter).1659 Its default value is \np {nn\_atfp}\forcode{ = 10.e-3}.1589 $\gamma$ is initialized as \np{nn_atfp}{nn\_atfp} (namelist parameter). 1590 Its default value is \np[=10.e-3]{nn_atfp}{nn\_atfp}. 1660 1591 In both cases, the modified Asselin filter is not applied since perfect conservation is not an issue for 1661 1592 the momentum equations. … … 1665 1596 and only array swapping and Asselin filtering is done in \mdl{dynnxt}. 1666 1597 1667 % ================================================================ 1668 \biblio 1669 1670 \pindex 1598 \subinc{\input{../../global/epilogue}} 1671 1599 1672 1600 \end{document} -
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_LBC.tex
r10614 r11831 2 2 3 3 \begin{document} 4 % ================================================================ 5 % Chapter — Lateral Boundary Condition (LBC) 6 % ================================================================ 4 7 5 \chapter{Lateral Boundary Condition (LBC)} 8 6 \label{chap:LBC} 9 7 10 \minitoc 11 12 \newpage 13 14 %gm% add here introduction to this chapter 15 16 % ================================================================ 17 % Boundary Condition at the Coast 18 % ================================================================ 19 \section{Boundary condition at the coast (\protect\np{rn\_shlat})} 8 \thispagestyle{plain} 9 10 \chaptertoc 11 12 \paragraph{Changes record} ~\\ 13 14 {\footnotesize 15 \begin{tabularx}{\textwidth}{l||X|X} 16 Release & Author(s) & Modifications \\ 17 \hline 18 {\em 4.0} & {\em ...} & {\em ...} \\ 19 {\em 3.6} & {\em ...} & {\em ...} \\ 20 {\em 3.4} & {\em ...} & {\em ...} \\ 21 {\em <=3.4} & {\em ...} & {\em ...} 22 \end{tabularx} 23 } 24 25 \clearpage 26 27 \cmtgm{Add here introduction to this chapter} 28 29 %% ================================================================================================= 30 \section[Boundary condition at the coast (\forcode{rn_shlat})]{Boundary condition at the coast (\protect\np{rn_shlat}{rn\_shlat})} 20 31 \label{sec:LBC_coast} 21 %--------------------------------------------nam_lbc------------------------------------------------------- 22 23 \nlst{namlbc} 24 %-------------------------------------------------------------------------------------------------------------- 25 26 %The lateral ocean boundary conditions contiguous to coastlines are Neumann conditions for heat and salt (no flux across boundaries) and Dirichlet conditions for momentum (ranging from free-slip to "strong" no-slip). They are handled automatically by the mask system (see \autoref{subsec:DOM_msk}). 27 28 %OPA allows land and topography grid points in the computational domain due to the presence of continents or islands, and includes the use of a full or partial step representation of bottom topography. The computation is performed over the whole domain, \ie we do not try to restrict the computation to ocean-only points. This choice has two motivations. Firstly, working on ocean only grid points overloads the code and harms the code readability. Secondly, and more importantly, it drastically reduces the vector portion of the computation, leading to a dramatic increase of CPU time requirement on vector computers. The current section describes how the masking affects the computation of the various terms of the equations with respect to the boundary condition at solid walls. The process of defining which areas are to be masked is described in \autoref{subsec:DOM_msk}. 29 30 Options are defined through the \ngn{namlbc} namelist variables. 32 33 \begin{listing} 34 \nlst{namlbc} 35 \caption{\forcode{&namlbc}} 36 \label{lst:namlbc} 37 \end{listing} 38 39 %The lateral ocean boundary conditions contiguous to coastlines are Neumann conditions for heat and salt 40 %(no flux across boundaries) and Dirichlet conditions for momentum (ranging from free-slip to "strong" no-slip). 41 %They are handled automatically by the mask system (see \autoref{subsec:DOM_msk}). 42 43 %OPA allows land and topography grid points in the computational domain due to the presence of continents or islands, 44 %and includes the use of a full or partial step representation of bottom topography. 45 %The computation is performed over the whole domain, \ie\ we do not try to restrict the computation to ocean-only points. 46 %This choice has two motivations. 47 %Firstly, working on ocean only grid points overloads the code and harms the code readability. 48 %Secondly, and more importantly, it drastically reduces the vector portion of the computation, 49 %leading to a dramatic increase of CPU time requirement on vector computers. 50 %The current section describes how the masking affects the computation of the various terms of the equations 51 %with respect to the boundary condition at solid walls. 52 %The process of defining which areas are to be masked is described in \autoref{subsec:DOM_msk}. 53 54 Options are defined through the \nam{lbc}{lbc} namelist variables. 31 55 The discrete representation of a domain with complex boundaries (coastlines and bottom topography) leads to 32 56 arrays that include large portions where a computation is not required as the model variables remain at zero. … … 40 64 Since most of the boundary conditions consist of a zero flux across the solid boundaries, 41 65 they can be simply applied by multiplying variables by the correct mask arrays, 42 \ie the mask array of the grid point where the flux is evaluated.66 \ie\ the mask array of the grid point where the flux is evaluated. 43 67 For example, the heat flux in the \textbf{i}-direction is evaluated at $u$-points. 44 68 Evaluating this quantity as, 45 69 46 70 \[ 47 % \label{eq: lbc_aaaa}71 % \label{eq:LBC_aaaa} 48 72 \frac{A^{lT} }{e_1 }\frac{\partial T}{\partial i}\equiv \frac{A_u^{lT} 49 73 }{e_{1u} } \; \delta_{i+1 / 2} \left[ T \right]\;\;mask_u … … 51 75 (where mask$_{u}$ is the mask array at a $u$-point) ensures that the heat flux is zero inside land and 52 76 at the boundaries, since mask$_{u}$ is zero at solid boundaries which in this case are defined at $u$-points 53 (normal velocity $u$ remains zero at the coast) (\autoref{fig:LBC_uv}). 54 55 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 77 (normal velocity $u$ remains zero at the coast) (\autoref{fig:LBC_uv}). 78 56 79 \begin{figure}[!t] 57 \begin{center} 58 \includegraphics[width=0.90\textwidth]{Fig_LBC_uv} 59 \caption{ 60 \protect\label{fig:LBC_uv} 61 Lateral boundary (thick line) at T-level. 62 The velocity normal to the boundary is set to zero. 63 } 64 \end{center} 80 \centering 81 \includegraphics[width=0.66\textwidth]{LBC_uv} 82 \caption[Lateral boundary at $T$-level]{ 83 Lateral boundary (thick line) at T-level. 84 The velocity normal to the boundary is set to zero.} 85 \label{fig:LBC_uv} 65 86 \end{figure} 66 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>67 87 68 88 For momentum the situation is a bit more complex as two boundary conditions must be provided along the coast … … 78 98 and is required in order to compute the vorticity at the coast. 79 99 Four different types of lateral boundary condition are available, 80 controlled by the value of the \np{rn \_shlat} namelist parameter100 controlled by the value of the \np{rn_shlat}{rn\_shlat} namelist parameter 81 101 (The value of the mask$_{f}$ array along the coastline is set equal to this parameter). 82 102 These are: 83 103 84 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>85 104 \begin{figure}[!p] 86 \begin{center} 87 \includegraphics[width=0.90\textwidth]{Fig_LBC_shlat} 88 \caption{ 89 \protect\label{fig:LBC_shlat} 90 lateral boundary condition 91 (a) free-slip ($rn\_shlat=0$); 92 (b) no-slip ($rn\_shlat=2$); 93 (c) "partial" free-slip ($0<rn\_shlat<2$) and 94 (d) "strong" no-slip ($2<rn\_shlat$). 95 Implied "ghost" velocity inside land area is display in grey. 96 } 97 \end{center} 105 \centering 106 \includegraphics[width=0.66\textwidth]{LBC_shlat} 107 \caption[Lateral boundary conditions]{ 108 Lateral boundary conditions 109 (a) free-slip (\protect\np[=0]{rn_shlat}{rn\_shlat}); 110 (b) no-slip (\protect\np[=2]{rn_shlat}{rn\_shlat}); 111 (c) "partial" free-slip (\forcode{0<}\protect\np[<2]{rn_shlat}{rn\_shlat}) and 112 (d) "strong" no-slip (\forcode{2<}\protect\np{rn_shlat}{rn\_shlat}). 113 Implied "ghost" velocity inside land area is display in grey.} 114 \label{fig:LBC_shlat} 98 115 \end{figure} 99 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>100 116 101 117 \begin{description} 102 118 103 \item [free-slip boundary condition (\np{rn\_shlat}\forcode{ = 0}):] the tangential velocity at119 \item [free-slip boundary condition ({\np[=0]{rn_shlat}{rn\_shlat}})] the tangential velocity at 104 120 the coastline is equal to the offshore velocity, 105 \ie the normal derivative of the tangential velocity is zero at the coast,121 \ie\ the normal derivative of the tangential velocity is zero at the coast, 106 122 so the vorticity: mask$_{f}$ array is set to zero inside the land and just at the coast 107 123 (\autoref{fig:LBC_shlat}-a). 108 124 109 \item [no-slip boundary condition (\np{rn\_shlat}\forcode{ = 2}):] the tangential velocity vanishes at the coastline.125 \item [no-slip boundary condition ({\np[=2]{rn_shlat}{rn\_shlat}})] the tangential velocity vanishes at the coastline. 110 126 Assuming that the tangential velocity decreases linearly from 111 127 the closest ocean velocity grid point to the coastline, … … 113 129 the closest ocean velocity gridpoint were of the same magnitude but in the opposite direction 114 130 (\autoref{fig:LBC_shlat}-b). 115 Therefore, the vorticity along the coastlines is given by: 131 Therefore, the vorticity along the coastlines is given by: 116 132 117 133 \[ … … 122 138 the no-slip boundary condition, simply by multiplying it by the mask$_{f}$ : 123 139 \[ 124 % \label{eq: lbc_bbbb}140 % \label{eq:LBC_bbbb} 125 141 \zeta \equiv \frac{1}{e_{1f} {\kern 1pt}e_{2f} }\left( {\delta_{i+1/2} 126 142 \left[ {e_{2v} \,v} \right]-\delta_{j+1/2} \left[ {e_{1u} \,u} \right]} … … 128 144 \] 129 145 130 \item ["partial" free-slip boundary condition (0$<$\np{rn\_shlat}$<$2):] the tangential velocity at131 the coastline is smaller than the offshore velocity, \ie there is a lateral friction but146 \item ["partial" free-slip boundary condition (0$<$\np{rn_shlat}{rn\_shlat}$<$2)] the tangential velocity at 147 the coastline is smaller than the offshore velocity, \ie\ there is a lateral friction but 132 148 not strong enough to make the tangential velocity at the coast vanish (\autoref{fig:LBC_shlat}-c). 133 149 This can be selected by providing a value of mask$_{f}$ strictly inbetween $0$ and $2$. 134 150 135 \item ["strong" no-slip boundary condition (2$<$\np{rn\_shlat}):] the viscous boundary layer is assumed to151 \item ["strong" no-slip boundary condition (2$<$\np{rn_shlat}{rn\_shlat})] the viscous boundary layer is assumed to 136 152 be smaller than half the grid size (\autoref{fig:LBC_shlat}-d). 137 153 The friction is thus larger than in the no-slip case. … … 139 155 \end{description} 140 156 141 Note that when the bottom topography is entirely represented by the $s$-coor -dinates (pure $s$-coordinate),157 Note that when the bottom topography is entirely represented by the $s$-coordinates (pure $s$-coordinate), 142 158 the lateral boundary condition on tangential velocity is of much less importance as 143 159 it is only applied next to the coast where the minimum water depth can be quite shallow. 144 160 145 146 % ================================================================ 147 % Boundary Condition around the Model Domain 148 % ================================================================ 149 \section{Model domain boundary condition (\protect\np{jperio})} 161 %% ================================================================================================= 162 \section[Model domain boundary condition (\forcode{jperio})]{Model domain boundary condition (\protect\jp{jperio})} 150 163 \label{sec:LBC_jperio} 151 164 … … 153 166 closed, cyclic east-west, cyclic north-south, a north-fold, and combination closed-north fold or 154 167 bi-cyclic east-west and north-fold. 155 The north-fold boundary condition is associated with the 3-pole ORCA mesh. 156 157 % ------------------------------------------------------------------------------------------------------------- 158 % Closed, cyclic (\np{jperio}\forcode{ = 0..2}) 159 % ------------------------------------------------------------------------------------------------------------- 160 \subsection{Closed, cyclic (\protect\np{jperio}\forcode{= [0127]})} 168 The north-fold boundary condition is associated with the 3-pole ORCA mesh. 169 170 %% ================================================================================================= 171 \subsection[Closed, cyclic (\forcode{=0,1,2,7})]{Closed, cyclic (\protect\jp{jperio}\forcode{=0,1,2,7})} 161 172 \label{subsec:LBC_jperio012} 162 173 163 174 The choice of closed or cyclic model domain boundary condition is made by 164 setting \ np{jperio} to 0, 1, 2 or 7 in namelist \ngn{namcfg}.175 setting \jp{jperio} to 0, 1, 2 or 7 in namelist \nam{cfg}{cfg}. 165 176 Each time such a boundary condition is needed, it is set by a call to routine \mdl{lbclnk}. 166 177 The computation of momentum and tracer trends proceeds from $i=2$ to $i=jpi-1$ and from $j=2$ to $j=jpj-1$, 167 \ie in the model interior.178 \ie\ in the model interior. 168 179 To choose a lateral model boundary condition is to specify the first and last rows and columns of 169 the model variables. 180 the model variables. 170 181 171 182 \begin{description} 172 183 173 \item[For closed boundary (\np{jperio}\forcode{ = 0})], 174 solid walls are imposed at all model boundaries: 184 \item [For closed boundary (\jp{jperio}\forcode{=0})], solid walls are imposed at all model boundaries: 175 185 first and last rows and columns are set to zero. 176 186 177 \item[For cyclic east-west boundary (\np{jperio}\forcode{ = 1})], 178 first and last rows are set to zero (closed) whilst the first column is set to 187 \item [For cyclic east-west boundary (\jp{jperio}\forcode{=1})], first and last rows are set to zero (closed) whilst the first column is set to 179 188 the value of the last-but-one column and the last column to the value of the second one 180 189 (\autoref{fig:LBC_jperio}-a). 181 190 Whatever flows out of the eastern (western) end of the basin enters the western (eastern) end. 182 191 183 \item[For cyclic north-south boundary (\np{jperio}\forcode{ = 2})], 184 first and last columns are set to zero (closed) whilst the first row is set to 192 \item [For cyclic north-south boundary (\jp{jperio}\forcode{=2})], first and last columns are set to zero (closed) whilst the first row is set to 185 193 the value of the last-but-one row and the last row to the value of the second one 186 194 (\autoref{fig:LBC_jperio}-a). 187 195 Whatever flows out of the northern (southern) end of the basin enters the southern (northern) end. 188 196 189 \item [Bi-cyclic east-west and north-south boundary (\np{jperio}\forcode{ =7})] combines cases 1 and 2.197 \item [Bi-cyclic east-west and north-south boundary (\jp{jperio}\forcode{=7})] combines cases 1 and 2. 190 198 191 199 \end{description} 192 200 193 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>194 201 \begin{figure}[!t] 195 \begin{center} 196 \includegraphics[width=1.0\textwidth]{Fig_LBC_jperio} 197 \caption{ 198 \protect\label{fig:LBC_jperio} 199 setting of (a) east-west cyclic (b) symmetric across the equator boundary conditions. 200 } 201 \end{center} 202 \centering 203 \includegraphics[width=0.66\textwidth]{LBC_jperio} 204 \caption[Setting of east-west cyclic and symmetric across the Equator boundary conditions]{ 205 Setting of (a) east-west cyclic (b) symmetric across the Equator boundary conditions} 206 \label{fig:LBC_jperio} 202 207 \end{figure} 203 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 204 205 % ------------------------------------------------------------------------------------------------------------- 206 % North fold (\textit{jperio = 3 }to $6)$ 207 % ------------------------------------------------------------------------------------------------------------- 208 \subsection{North-fold (\protect\np{jperio}\forcode{ = 3..6})} 208 209 %% ================================================================================================= 210 \subsection[North-fold (\forcode{=3,6})]{North-fold (\protect\jp{jperio}\forcode{=3,6})} 209 211 \label{subsec:LBC_north_fold} 210 212 211 213 The north fold boundary condition has been introduced in order to handle the north boundary of 212 214 a three-polar ORCA grid. 213 Such a grid has two poles in the northern hemisphere (\autoref{fig: MISC_ORCA_msh},214 and thus requires a specific treatment illustrated in \autoref{fig: North_Fold_T}.215 Such a grid has two poles in the northern hemisphere (\autoref{fig:CFGS_ORCA_msh}, 216 and thus requires a specific treatment illustrated in \autoref{fig:LBC_North_Fold_T}. 215 217 Further information can be found in \mdl{lbcnfd} module which applies the north fold boundary condition. 216 218 217 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>218 219 \begin{figure}[!t] 219 \begin{center} 220 \includegraphics[width=0.90\textwidth]{Fig_North_Fold_T} 221 \caption{ 222 \protect\label{fig:North_Fold_T} 223 North fold boundary with a $T$-point pivot and cyclic east-west boundary condition ($jperio=4$), 224 as used in ORCA 2, 1/4, and 1/12. 225 Pink shaded area corresponds to the inner domain mask (see text). 226 } 227 \end{center} 220 \centering 221 \includegraphics[width=0.66\textwidth]{LBC_North_Fold_T} 222 \caption[North fold boundary in ORCA 2\deg, 1/4\deg and 1/12\deg]{ 223 North fold boundary with a $T$-point pivot and cyclic east-west boundary condition ($jperio=4$), 224 as used in ORCA 2\deg, 1/4\deg and 1/12\deg. 225 Pink shaded area corresponds to the inner domain mask (see text).} 226 \label{fig:LBC_North_Fold_T} 228 227 \end{figure} 229 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 230 231 % ==================================================================== 232 % Exchange with neighbouring processors 233 % ==================================================================== 234 \section{Exchange with neighbouring processors (\protect\mdl{lbclnk}, \protect\mdl{lib\_mpp})} 228 229 %% ================================================================================================= 230 \section[Exchange with neighbouring processors (\textit{lbclnk.F90}, \textit{lib\_mpp.F90})]{Exchange with neighbouring processors (\protect\mdl{lbclnk}, \protect\mdl{lib\_mpp})} 235 231 \label{sec:LBC_mpp} 236 232 233 \begin{listing} 234 \nlst{nammpp} 235 \caption{\forcode{&nammpp}} 236 \label{lst:nammpp} 237 \end{listing} 238 237 239 For massively parallel processing (mpp), a domain decomposition method is used. 238 The basic idea of the method is to split the large computation domain of a numerical experiment into 239 s everal smaller domains and solve the set of equations by addressing independent local problems.240 The basic idea of the method is to split the large computation domain of a numerical experiment into several smaller domains and 241 solve the set of equations by addressing independent local problems. 240 242 Each processor has its own local memory and computes the model equation over a subdomain of the whole model domain. 241 The subdomain boundary conditions are specified through communications between processors which 242 are organized by explicit statements (message passing method). 243 244 A big advantage is that the method does not need many modifications of the initial \fortran code. 245 From the modeller's point of view, each sub domain running on a processor is identical to the "mono-domain" code. 246 In addition, the programmer manages the communications between subdomains, 247 and the code is faster when the number of processors is increased. 248 The porting of OPA code on an iPSC860 was achieved during Guyon's PhD [Guyon et al. 1994, 1995] 249 in collaboration with CETIIS and ONERA. 250 The implementation in the operational context and the studies of performance on 251 a T3D and T3E Cray computers have been made in collaboration with IDRIS and CNRS. 243 The subdomain boundary conditions are specified through communications between processors which are organized by 244 explicit statements (message passing method). 252 245 The present implementation is largely inspired by Guyon's work [Guyon 1995]. 253 246 … … 256 249 depend at the very most on one neighbouring point. 257 250 The only non-local computations concern the vertical physics 258 (implicit diffusion, turbulent closure scheme, ...) (delocalization over the whole water column), 259 and the solving of the elliptic equation associated with the surface pressure gradient computation 260 (delocalization over the whole horizontal domain). 251 (implicit diffusion, turbulent closure scheme, ...). 261 252 Therefore, a pencil strategy is used for the data sub-structuration: 262 253 the 3D initial domain is laid out on local processor memories following a 2D horizontal topological splitting. … … 267 258 After a computation, a communication phase starts: 268 259 each processor sends to its neighbouring processors the update values of the points corresponding to 269 the interior overlapping area to its neighbouring sub-domain (\ie the innermost of the two overlapping rows). 270 The communication is done through the Message Passing Interface (MPI). 260 the interior overlapping area to its neighbouring sub-domain (\ie\ the innermost of the two overlapping rows). 261 Communications are first done according to the east-west direction and next according to the north-south direction. 262 There is no specific communications for the corners. 263 The communication is done through the Message Passing Interface (MPI) and requires \key{mpp\_mpi}. 264 Use also \key{mpi2} if MPI3 is not available on your computer. 271 265 The data exchanges between processors are required at the very place where 272 266 lateral domain boundary conditions are set in the mono-domain computation: 273 267 the \rou{lbc\_lnk} routine (found in \mdl{lbclnk} module) which manages such conditions is interfaced with 274 routines found in \mdl{lib\_mpp} module when running on an MPP computer (\ie when \key{mpp\_mpi} defined). 275 It has to be pointed out that when using the MPP version of the model, 276 the east-west cyclic boundary condition is done implicitly, 277 whilst the south-symmetric boundary condition option is not available. 278 279 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 268 routines found in \mdl{lib\_mpp} module. 269 The output file \textit{communication\_report.txt} provides the list of which routines do how 270 many communications during 1 time step of the model.\\ 271 280 272 \begin{figure}[!t] 281 \begin{center} 282 \includegraphics[width=0.90\textwidth]{Fig_mpp} 283 \caption{ 284 \protect\label{fig:mpp} 285 Positioning of a sub-domain when massively parallel processing is used. 286 } 287 \end{center} 273 \centering 274 \includegraphics[width=0.66\textwidth]{LBC_mpp} 275 \caption{Positioning of a sub-domain when massively parallel processing is used} 276 \label{fig:LBC_mpp} 288 277 \end{figure} 289 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 290 291 In the standard version of \NEMO, the splitting is regular and arithmetic. 292 The i-axis is divided by \jp{jpni} and 293 the j-axis by \jp{jpnj} for a number of processors \jp{jpnij} most often equal to $jpni \times jpnj$ 294 (parameters set in \ngn{nammpp} namelist). 295 Each processor is independent and without message passing or synchronous process, 296 programs run alone and access just its own local memory. 297 For this reason, the main model dimensions are now the local dimensions of the subdomain (pencil) that 298 are named \jp{jpi}, \jp{jpj}, \jp{jpk}. 278 279 In \NEMO, the splitting is regular and arithmetic. 280 The total number of subdomains corresponds to the number of MPI processes allocated to \NEMO\ when the model is launched 281 (\ie\ mpirun -np x ./nemo will automatically give x subdomains). 282 The i-axis is divided by \np{jpni}{jpni} and the j-axis by \np{jpnj}{jpnj}. 283 These parameters are defined in \nam{mpp}{mpp} namelist. 284 If \np{jpni}{jpni} and \np{jpnj}{jpnj} are < 1, they will be automatically redefined in the code to give the best domain decomposition 285 (see bellow). 286 287 Each processor is independent and without message passing or synchronous process, programs run alone and access just its own local memory. 288 For this reason, 289 the main model dimensions are now the local dimensions of the subdomain (pencil) that are named \jp{jpi}, \jp{jpj}, \jp{jpk}. 299 290 These dimensions include the internal domain and the overlapping rows. 300 The number of rows to exchange (known as the halo) is usually set to one (\jp{jpreci}=1, in \mdl{par\_oce}). 301 The whole domain dimensions are named \np{jpiglo}, \np{jpjglo} and \jp{jpk}. 291 The number of rows to exchange (known as the halo) is usually set to one (nn\_hls=1, in \mdl{par\_oce}, 292 and must be kept to one until further notice). 293 The whole domain dimensions are named \jp{jpiglo}, \jp{jpjglo} and \jp{jpk}. 302 294 The relationship between the whole domain and a sub-domain is: 295 \begin{gather*} 296 jpi = ( jpiglo-2\times nn\_hls + (jpni-1) ) / jpni + 2\times nn\_hls \\ 297 jpj = ( jpjglo-2\times nn\_hls + (jpnj-1) ) / jpnj + 2\times nn\_hls 298 \end{gather*} 299 300 One also defines variables nldi and nlei which correspond to the internal domain bounds, and the variables nimpp and njmpp which are the position of the (1,1) grid-point in the global domain (\autoref{fig:LBC_mpp}). Note that since the version 4, there is no more extra-halo area as defined in \autoref{fig:LBC_mpp} so \jp{jpi} is now always equal to nlci and \jp{jpj} equal to nlcj. 301 302 An element of $T_{l}$, a local array (subdomain) corresponds to an element of $T_{g}$, 303 a global array (whole domain) by the relationship: 303 304 \[ 304 jpi = ( jpiglo-2*jpreci + (jpni-1) ) / jpni + 2*jpreci 305 jpj = ( jpjglo-2*jprecj + (jpnj-1) ) / jpnj + 2*jprecj 306 \] 307 where \jp{jpni}, \jp{jpnj} are the number of processors following the i- and j-axis. 308 309 One also defines variables nldi and nlei which correspond to the internal domain bounds, 310 and the variables nimpp and njmpp which are the position of the (1,1) grid-point in the global domain. 311 An element of $T_{l}$, a local array (subdomain) corresponds to an element of $T_{g}$, 312 a global array (whole domain) by the relationship: 313 \[ 314 % \label{eq:lbc_nimpp} 305 % \label{eq:LBC_nimpp} 315 306 T_{g} (i+nimpp-1,j+njmpp-1,k) = T_{l} (i,j,k), 316 307 \] 317 with $1 \leq i \leq jpi$, $1 \leq j \leq jpj $ , and $1 \leq k \leq jpk$. 318 319 Processors are numbered from 0 to $jpnij-1$, the number is saved in the variable nproc. 320 In the standard version, a processor has no more than 321 four neighbouring processors named nono (for north), noea (east), noso (south) and nowe (west) and 322 two variables, nbondi and nbondj, indicate the relative position of the processor: 323 \begin{itemize} 324 \item nbondi = -1 an east neighbour, no west processor, 325 \item nbondi = 0 an east neighbour, a west neighbour, 326 \item nbondi = 1 no east processor, a west neighbour, 327 \item nbondi = 2 no splitting following the i-axis. 328 \end{itemize} 329 During the simulation, processors exchange data with their neighbours. 330 If there is effectively a neighbour, the processor receives variables from this processor on its overlapping row, 331 and sends the data issued from internal domain corresponding to the overlapping row of the other processor. 332 333 334 The \NEMO model computes equation terms with the help of mask arrays (0 on land points and 1 on sea points). 335 It is easily readable and very efficient in the context of a computer with vectorial architecture. 336 However, in the case of a scalar processor, computations over the land regions become more expensive in 337 terms of CPU time. 338 It is worse when we use a complex configuration with a realistic bathymetry like the global ocean where 339 more than 50 \% of points are land points. 340 For this reason, a pre-processing tool can be used to choose the mpp domain decomposition with a maximum number of 341 only land points processors, which can then be eliminated (\autoref{fig:mppini2}) 342 (For example, the mpp\_optimiz tools, available from the DRAKKAR web site). 343 This optimisation is dependent on the specific bathymetry employed. 344 The user then chooses optimal parameters \jp{jpni}, \jp{jpnj} and \jp{jpnij} with $jpnij < jpni \times jpnj$, 345 leading to the elimination of $jpni \times jpnj - jpnij$ land processors. 346 When those parameters are specified in \ngn{nammpp} namelist, 347 the algorithm in the \rou{inimpp2} routine sets each processor's parameters (nbound, nono, noea,...) so that 348 the land-only processors are not taken into account. 349 350 \gmcomment{Note that the inimpp2 routine is general so that the original inimpp 351 routine should be suppressed from the code.} 352 353 When land processors are eliminated, 354 the value corresponding to these locations in the model output files is undefined. 355 Note that this is a problem for the meshmask file which requires to be defined over the whole domain. 356 Therefore, user should not eliminate land processors when creating a meshmask file 357 (\ie when setting a non-zero value to \np{nn\_msh}). 358 359 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 308 with $1 \leq i \leq jpi$, $1 \leq j \leq jpj $ , and $1 \leq k \leq jpk$. 309 310 The 1-d arrays $mig(1:\jp{jpi})$ and $mjg(1:\jp{jpj})$, defined in \rou{dom\_glo} routine (\mdl{domain} module), should be used to get global domain indices from local domain indices. The 1-d arrays, $mi0(1:\jp{jpiglo})$, $mi1(1:\jp{jpiglo})$ and $mj0(1:\jp{jpjglo})$, $mj1(1:\jp{jpjglo})$ have the reverse purpose and should be used to define loop indices expressed in global domain indices (see examples in \mdl{dtastd} module).\\ 311 312 The \NEMO\ model computes equation terms with the help of mask arrays (0 on land points and 1 on sea points). It is therefore possible that an MPI subdomain contains only land points. To save ressources, we try to supress from the computational domain as much land subdomains as possible. For example if $N_{mpi}$ processes are allocated to NEMO, the domain decomposition will be given by the following equation: 313 \[ 314 N_{mpi} = jpni \times jpnj - N_{land} + N_{useless} 315 \] 316 $N_{land}$ is the total number of land subdomains in the domain decomposition defined by \np{jpni}{jpni} and \np{jpnj}{jpnj}. $N_{useless}$ is the number of land subdomains that are kept in the compuational domain in order to make sure that $N_{mpi}$ MPI processes are indeed allocated to a given subdomain. The values of $N_{mpi}$, \np{jpni}{jpni}, \np{jpnj}{jpnj}, $N_{land}$ and $N_{useless}$ are printed in the output file \texttt{ocean.output}. $N_{useless}$ must, of course, be as small as possible to limit the waste of ressources. A warning is issued in \texttt{ocean.output} if $N_{useless}$ is not zero. Note that non-zero value of $N_{useless}$ is uselly required when using AGRIF as, up to now, the parent grid and each of the child grids must use all the $N_{mpi}$ processes. 317 318 If the domain decomposition is automatically defined (when \np{jpni}{jpni} and \np{jpnj}{jpnj} are < 1), the decomposition chosen by the model will minimise the sub-domain size (defined as $max_{all domains}(jpi \times jpj)$) and maximize the number of eliminated land subdomains. This means that no other domain decomposition (a set of \np{jpni}{jpni} and \np{jpnj}{jpnj} values) will use less processes than $(jpni \times jpnj - N_{land})$ and get a smaller subdomain size. 319 In order to specify $N_{mpi}$ properly (minimize $N_{useless}$), you must run the model once with \np{ln_list}{ln\_list} activated. In this case, the model will start the initialisation phase, print the list of optimum decompositions ($N_{mpi}$, \np{jpni}{jpni} and \np{jpnj}{jpnj}) in \texttt{ocean.output} and directly abort. The maximum value of $N_{mpi}$ tested in this list is given by $max(N_{MPI\_tasks}, jpni \times jpnj)$. For example, run the model on 40 nodes with ln\_list activated and $jpni = 10000$ and $jpnj = 1$, will print the list of optimum domains decomposition from 1 to about 10000. 320 321 Processors are numbered from 0 to $N_{mpi} - 1$. Subdomains containning some ocean points are numbered first from 0 to $jpni * jpnj - N_{land} -1$. The remaining $N_{useless}$ land subdomains are numbered next, which means that, for a given (\np{jpni}{jpni}, \np{jpnj}{jpnj}), the numbers attributed to he ocean subdomains do not vary with $N_{useless}$. 322 323 When land processors are eliminated, the value corresponding to these locations in the model output files is undefined. \np{ln_mskland}{ln\_mskland} must be activated in order avoid Not a Number values in output files. Note that it is better to not eliminate land processors when creating a meshmask file (\ie\ when setting a non-zero value to \np{nn_msh}{nn\_msh}). 324 360 325 \begin{figure}[!ht] 361 \begin{center} 362 \includegraphics[width=0.90\textwidth]{Fig_mppini2} 363 \caption { 364 \protect\label{fig:mppini2} 365 Example of Atlantic domain defined for the CLIPPER projet. 366 Initial grid is composed of 773 x 1236 horizontal points. 367 (a) the domain is split onto 9 \time 20 subdomains (jpni=9, jpnj=20). 368 52 subdomains are land areas. 369 (b) 52 subdomains are eliminated (white rectangles) and 370 the resulting number of processors really used during the computation is jpnij=128. 371 } 372 \end{center} 326 \centering 327 \includegraphics[width=0.66\textwidth]{LBC_mppini2} 328 \caption[Atlantic domain defined for the CLIPPER projet]{ 329 Example of Atlantic domain defined for the CLIPPER projet. 330 Initial grid is composed of 773 x 1236 horizontal points. 331 (a) the domain is split onto 9 $times$ 20 subdomains (jpni=9, jpnj=20). 332 52 subdomains are land areas. 333 (b) 52 subdomains are eliminated (white rectangles) and 334 the resulting number of processors really used during the computation is jpnij=128.} 335 \label{fig:LBC_mppini2} 373 336 \end{figure} 374 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 375 376 377 % ==================================================================== 378 % Unstructured open boundaries BDY 379 % ==================================================================== 337 338 %% ================================================================================================= 380 339 \section{Unstructured open boundary conditions (BDY)} 381 340 \label{sec:LBC_bdy} 382 341 383 %-----------------------------------------nambdy-------------------------------------------- 384 385 \nlst{nambdy} 386 %----------------------------------------------------------------------------------------------- 387 %-----------------------------------------nambdy_dta-------------------------------------------- 388 389 \nlst{nambdy_dta} 390 %----------------------------------------------------------------------------------------------- 391 392 Options are defined through the \ngn{nambdy} \ngn{nambdy\_dta} namelist variables. 393 The BDY module is the core implementation of open boundary conditions for regional configurations on 394 temperature, salinity, barotropic and baroclinic velocities, as well as ice concentration, ice and snow thicknesses). 395 396 The BDY module was modelled on the OBC module (see NEMO 3.4) and shares many features and 397 a similar coding structure \citep{Chanut2005}. 342 \begin{listing} 343 \nlst{nambdy} 344 \caption{\forcode{&nambdy}} 345 \label{lst:nambdy} 346 \end{listing} 347 348 \begin{listing} 349 \nlst{nambdy_dta} 350 \caption{\forcode{&nambdy_dta}} 351 \label{lst:nambdy_dta} 352 \end{listing} 353 354 Options are defined through the \nam{bdy}{bdy} and \nam{bdy_dta}{bdy\_dta} namelist variables. 355 The BDY module is the core implementation of open boundary conditions for regional configurations on 356 ocean temperature, salinity, barotropic-baroclinic velocities, ice-snow concentration, thicknesses, temperatures, salinity and melt ponds concentration and thickness. 357 358 The BDY module was modelled on the OBC module (see \NEMO\ 3.4) and shares many features and 359 a similar coding structure \citep{chanut_rpt05}. 398 360 The specification of the location of the open boundary is completely flexible and 399 allows for example the open boundary to follow an isobath or other irregular contour.400 Boundary data files used with versions of NEMOprior to Version 3.4 may need to be re-ordered to work with this version.361 allows any type of setup, from regular boundaries to irregular contour (it includes the possibility to set an open boundary able to follow an isobath). 362 Boundary data files used with versions of \NEMO\ prior to Version 3.4 may need to be re-ordered to work with this version. 401 363 See the section on the Input Boundary Data Files for details. 402 364 403 % ----------------------------------------------365 %% ================================================================================================= 404 366 \subsection{Namelists} 405 \label{subsec: BDY_namelist}406 407 The BDY module is activated by setting \np {ln\_bdy}\forcode{ = .true.} .367 \label{subsec:LBC_bdy_namelist} 368 369 The BDY module is activated by setting \np[=.true.]{ln_bdy}{ln\_bdy} . 408 370 It is possible to define more than one boundary ``set'' and apply different boundary conditions to each set. 409 The number of boundary sets is defined by \np{nb\_bdy}. 410 Each boundary set may be defined as a set of straight line segments in a namelist 411 (\np{ln\_coords\_file}\forcode{ = .false.}) or read in from a file (\np{ln\_coords\_file}\forcode{ = .true.}). 412 If the set is defined in a namelist, then the namelists \ngn{nambdy\_index} must be included separately, one for each set. 413 If the set is defined by a file, then a ``\ifile{coordinates.bdy}'' file must be provided. 414 The coordinates.bdy file is analagous to the usual NEMO ``\ifile{coordinates}'' file. 371 The number of boundary sets is defined by \np{nb_bdy}{nb\_bdy}. 372 Each boundary set can be either defined as a series of straight line segments directly in the namelist 373 (\np[=.false.]{ln_coords_file}{ln\_coords\_file}, and a namelist block \nam{bdy_index}{bdy\_index} must be included for each set) or read in from a file (\np[=.true.]{ln_coords_file}{ln\_coords\_file}, and a ``\ifile{coordinates.bdy}'' file must be provided). 374 The coordinates.bdy file is analagous to the usual \NEMO\ ``\ifile{coordinates}'' file. 415 375 In the example above, there are two boundary sets, the first of which is defined via a file and 416 the second is defined in anamelist.417 For more details of the definition of the boundary geometry see section \autoref{subsec: BDY_geometry}.376 the second is defined in the namelist. 377 For more details of the definition of the boundary geometry see section \autoref{subsec:LBC_bdy_geometry}. 418 378 419 379 For each boundary set a boundary condition has to be chosen for the barotropic solution 420 (``u2d'':sea-surface height and barotropic velocities), for the baroclinic velocities (``u3d''), 421 for the active tracers \footnote{The BDY module does not deal with passive tracers at this version} (``tra''), and sea-ice (``ice''). 422 For each set of variables there is a choice of algorithm and a choice for the data, 423 eg. for the active tracers the algorithm is set by \np{cn\_tra} and the choice of data is set by \np{nn\_tra\_dta}.\\ 380 (``u2d'':sea-surface height and barotropic velocities), for the baroclinic velocities (``u3d''), 381 for the active tracers \footnote{The BDY module does not deal with passive tracers at this version} (``tra''), and for sea-ice (``ice''). 382 For each set of variables one has to choose an algorithm and the boundary data (set resp. by \np{cn_tra}{cn\_tra} and \np{nn_tra_dta}{nn\_tra\_dta} for tracers).\\ 424 383 425 384 The choice of algorithm is currently as follows: 426 385 427 386 \begin{description} 428 \item [\forcode{'none'}:] No boundary condition applied.387 \item [\forcode{'none'}:] No boundary condition applied. 429 388 So the solution will ``see'' the land points around the edge of the edge of the domain. 430 \item [\forcode{'specified'}:] Specified boundary condition applied (only available for baroclinic velocity and tracer variables).431 \item [\forcode{'neumann'}:] Value at the boundary are duplicated (No gradient). Only available for baroclinic velocity and tracer variables.432 \item [\forcode{'frs'}:] Flow Relaxation Scheme (FRS) available for all variables.433 \item [\forcode{'Orlanski'}:] Orlanski radiation scheme (fully oblique) for barotropic, baroclinic and tracer variables.434 \item [\forcode{'Orlanski_npo'}:] Orlanski radiation scheme for barotropic, baroclinic and tracer variables.435 \item [\forcode{'flather'}:] Flather radiation scheme for the barotropic variables only.389 \item [\forcode{'specified'}:] Specified boundary condition applied (only available for baroclinic velocity and tracer variables). 390 \item [\forcode{'neumann'}:] Value at the boundary are duplicated (No gradient). Only available for baroclinic velocity and tracer variables. 391 \item [\forcode{'frs'}:] Flow Relaxation Scheme (FRS) available for all variables. 392 \item [\forcode{'Orlanski'}:] Orlanski radiation scheme (fully oblique) for barotropic, baroclinic and tracer variables. 393 \item [\forcode{'Orlanski_npo'}:] Orlanski radiation scheme for barotropic, baroclinic and tracer variables. 394 \item [\forcode{'flather'}:] Flather radiation scheme for the barotropic variables only. 436 395 \end{description} 437 396 438 The main choice for the boundary data is to use initial conditions as boundary data439 (\np {nn\_tra\_dta}\forcode{ = 0}) or to use external data from a file (\np{nn\_tra\_dta}\forcode{ = 1}).440 In case the 3d velocity data contain the total velocity (ie, baroclinic and barotropic velocity), 441 the bdy code can derived baroclinic and barotropic velocities by setting \np {ln\_full\_vel}\forcode{ = .true.}397 The boundary data is either set to initial conditions 398 (\np[=0]{nn_tra_dta}{nn\_tra\_dta}) or forced with external data from a file (\np[=1]{nn_tra_dta}{nn\_tra\_dta}). 399 In case the 3d velocity data contain the total velocity (ie, baroclinic and barotropic velocity), 400 the bdy code can derived baroclinic and barotropic velocities by setting \np[=.true.]{ln_full_vel}{ln\_full\_vel} 442 401 For the barotropic solution there is also the option to use tidal harmonic forcing either by 443 itself (\np{nn\_dyn2d\_dta}\forcode{ = 2}) or in addition to other external data (\np{nn\_dyn2d\_dta}\forcode{ = 3}).\\ 444 Sea-ice salinity, temperature and age data at the boundary are constant and defined repectively by \np{rn\_ice\_sal}, \np{rn\_ice\_tem} and \np{rn\_ice\_age}. 445 446 If external boundary data is required then the \ngn{nambdy\_dta} namelist must be defined. 447 One \ngn{nambdy\_dta} namelist is required for each boundary set in the order in which 448 the boundary sets are defined in nambdy. 449 In the example given, two boundary sets have been defined. The first one is reading data file in the \ngn{nambdy\_dta} namelist shown above 450 and the second one is using data from intial condition (no namelist bloc needed). 402 itself (\np[=2]{nn_dyn2d_dta}{nn\_dyn2d\_dta}) or in addition to other external data (\np[=3]{nn_dyn2d_dta}{nn\_dyn2d\_dta}).\\ 403 If not set to initial conditions, sea-ice salinity, temperatures and melt ponds data at the boundary can either be read in a file or defined as constant (by \np{rn_ice_sal}{rn\_ice\_sal}, \np{rn_ice_tem}{rn\_ice\_tem}, \np{rn_ice_apnd}{rn\_ice\_apnd}, \np{rn_ice_hpnd}{rn\_ice\_hpnd}). Ice age is constant and defined by \np{rn_ice_age}{rn\_ice\_age}. 404 405 If external boundary data is required then the \nam{bdy_dta}{bdy\_dta} namelist must be defined. 406 One \nam{bdy_dta}{bdy\_dta} namelist is required for each boundary set, adopting the same order of indexes in which the boundary sets are defined in nambdy. 407 In the example given, two boundary sets have been defined. The first one is reading data file in the \nam{bdy_dta}{bdy\_dta} namelist shown above 408 and the second one is using data from intial condition (no namelist block needed). 451 409 The boundary data is read in using the fldread module, 452 so the \ngn{nambdy\_dta} namelist is in the format required for fldread. 453 For each variable required, the filename, the frequency of the files and 454 the frequency of the data in the files is given. 455 Also whether or not time-interpolation is required and whether the data is climatological (time-cyclic) data.\\ 410 so the \nam{bdy_dta}{bdy\_dta} namelist is in the format required for fldread. 411 For each required variable, the filename, the frequency of the files and 412 the frequency of the data in the files are given. 413 Also whether or not time-interpolation is required and whether the data is climatological (time-cyclic) data. 414 For sea-ice salinity, temperatures and melt ponds, reading the files are skipped and constant values are used if filenames are defined as {'NOT USED'}.\\ 456 415 457 416 There is currently an option to vertically interpolate the open boundary data onto the native grid at run-time. 458 If \np{nn \_bdy\_jpk} $< -1$, it is assumed that the lateral boundary data are already on the native grid.459 However, if \np{nn \_bdy\_jpk} is set to the number of vertical levels present in the boundary data,460 a bilinear interpolation onto the native grid will be triggered at runtime. 461 For this to be successful the additional variables: $gdept$, $gdepu$, $gdepv$, $e3t$, $e3u$ and $e3v$, are required to be present in the lateral boundary files. 462 These correspond to the depths and scale factors of the input data, 417 If \np{nn_bdy_jpk}{nn\_bdy\_jpk}$<-1$, it is assumed that the lateral boundary data are already on the native grid. 418 However, if \np{nn_bdy_jpk}{nn\_bdy\_jpk} is set to the number of vertical levels present in the boundary data, 419 a bilinear interpolation onto the native grid will be triggered at runtime. 420 For this to be successful the additional variables: $gdept$, $gdepu$, $gdepv$, $e3t$, $e3u$ and $e3v$, are required to be present in the lateral boundary files. 421 These correspond to the depths and scale factors of the input data, 463 422 the latter used to make any adjustment to the velocity fields due to differences in the total water depths between the two vertical grids.\\ 464 423 465 In the example namelists given, two boundary sets are defined.424 In the example of given namelists, two boundary sets are defined. 466 425 The first set is defined via a file and applies FRS conditions to temperature and salinity and 467 426 Flather conditions to the barotropic variables. No condition specified for the baroclinic velocity and sea-ice. … … 469 428 Tidal harmonic forcing is also used. 470 429 The second set is defined in a namelist. 471 FRS conditions are applied on temperature and salinity and climatological data is read from initial condition files. 472 473 % ----------------------------------------------430 FRS conditions are applied on temperature and salinity and climatological data is read from initial condition files. 431 432 %% ================================================================================================= 474 433 \subsection{Flow relaxation scheme} 475 \label{subsec: BDY_FRS_scheme}476 477 The Flow Relaxation Scheme (FRS) \citep{ Davies_QJRMS76,Engerdahl_Tel95},434 \label{subsec:LBC_bdy_FRS_scheme} 435 436 The Flow Relaxation Scheme (FRS) \citep{davies_QJRMS76,engedahl_T95}, 478 437 applies a simple relaxation of the model fields to externally-specified values over 479 438 a zone next to the edge of the model domain. 480 439 Given a model prognostic variable $\Phi$ 481 440 \[ 482 % \label{eq: bdy_frs1}441 % \label{eq:LBC_bdy_frs1} 483 442 \Phi(d) = \alpha(d)\Phi_{e}(d) + (1-\alpha(d))\Phi_{m}(d)\;\;\;\;\; d=1,N 484 443 \] … … 489 448 the prognostic equation for $\Phi$ of the form: 490 449 \[ 491 % \label{eq: bdy_frs2}450 % \label{eq:LBC_bdy_frs2} 492 451 -\frac{1}{\tau}\left(\Phi - \Phi_{e}\right) 493 452 \] 494 453 where the relaxation time scale $\tau$ is given by a function of $\alpha$ and the model time step $\Delta t$: 495 454 \[ 496 % \label{eq: bdy_frs3}455 % \label{eq:LBC_bdy_frs3} 497 456 \tau = \frac{1-\alpha}{\alpha} \,\rdt 498 457 \] … … 500 459 is relaxed towards the external conditions over the rest of the FRS zone. 501 460 The application of a relaxation zone helps to prevent spurious reflection of 502 outgoing signals from the model boundary. 461 outgoing signals from the model boundary. 503 462 504 463 The function $\alpha$ is specified as a $tanh$ function: 505 464 \[ 506 % \label{eq: bdy_frs4}465 % \label{eq:LBC_bdy_frs4} 507 466 \alpha(d) = 1 - \tanh\left(\frac{d-1}{2}\right), \quad d=1,N 508 467 \] 509 The width of the FRS zone is specified in the namelist as \np{nn \_rimwidth}.468 The width of the FRS zone is specified in the namelist as \np{nn_rimwidth}{nn\_rimwidth}. 510 469 This is typically set to a value between 8 and 10. 511 470 512 % ----------------------------------------------471 %% ================================================================================================= 513 472 \subsection{Flather radiation scheme} 514 \label{subsec: BDY_flather_scheme}515 516 The \citet{ Flather_JPO94} scheme is a radiation condition on the normal,473 \label{subsec:LBC_bdy_flather_scheme} 474 475 The \citet{flather_JPO94} scheme is a radiation condition on the normal, 517 476 depth-mean transport across the open boundary. 518 477 It takes the form 519 \begin{equation} \label{eq:bdy_fla1} 520 U = U_{e} + \frac{c}{h}\left(\eta - \eta_{e}\right), 478 \begin{equation} 479 \label{eq:LBC_bdy_fla1} 480 U = U_{e} + \frac{c}{h}\left(\eta - \eta_{e}\right), 521 481 \end{equation} 522 482 where $U$ is the depth-mean velocity normal to the boundary and $\eta$ is the sea surface height, … … 527 487 the external depth-mean normal velocity, 528 488 plus a correction term that allows gravity waves generated internally to exit the model boundary. 529 Note that the sea-surface height gradient in \autoref{eq: bdy_fla1} is a spatial gradient across the model boundary,489 Note that the sea-surface height gradient in \autoref{eq:LBC_bdy_fla1} is a spatial gradient across the model boundary, 530 490 so that $\eta_{e}$ is defined on the $T$ points with $nbr=1$ and $\eta$ is defined on the $T$ points with $nbr=2$. 531 $U$ and $U_{e}$ are defined on the $U$ or $V$ points with $nbr=1$, \ie between the two $T$ grid points.532 533 % ----------------------------------------------491 $U$ and $U_{e}$ are defined on the $U$ or $V$ points with $nbr=1$, \ie\ between the two $T$ grid points. 492 493 %% ================================================================================================= 534 494 \subsection{Orlanski radiation scheme} 535 \label{subsec: BDY_orlanski_scheme}536 537 The Orlanski scheme is based on the algorithm described by \citep{ Marchesiello2001}, hereafter MMS.495 \label{subsec:LBC_bdy_orlanski_scheme} 496 497 The Orlanski scheme is based on the algorithm described by \citep{marchesiello.mcwilliams.ea_OM01}, hereafter MMS. 538 498 539 499 The adaptive Orlanski condition solves a wave plus relaxation equation at the boundary: 540 500 \begin{equation} 541 \frac{\partial\phi}{\partial t} + c_x \frac{\partial\phi}{\partial x} + c_y \frac{\partial\phi}{\partial y} = 542 -\frac{1}{\tau}(\phi - \phi^{ext})543 \label{eq:wave_continuous} 501 \label{eq:LBC_wave_continuous} 502 \frac{\partial\phi}{\partial t} + c_x \frac{\partial\phi}{\partial x} + c_y \frac{\partial\phi}{\partial y} = 503 -\frac{1}{\tau}(\phi - \phi^{ext}) 544 504 \end{equation} 545 505 … … 547 507 velocities are diagnosed from the model fields as: 548 508 549 \begin{equation} \label{eq:cx} 550 c_x = -\frac{\partial\phi}{\partial t}\frac{\partial\phi / \partial x}{(\partial\phi /\partial x)^2 + (\partial\phi /\partial y)^2} 509 \begin{equation} 510 \label{eq:LBC_cx} 511 c_x = -\frac{\partial\phi}{\partial t}\frac{\partial\phi / \partial x}{(\partial\phi /\partial x)^2 + (\partial\phi /\partial y)^2} 551 512 \end{equation} 552 513 \begin{equation} 553 \label{eq:cy}554 c_y = -\frac{\partial\phi}{\partial t}\frac{\partial\phi / \partial y}{(\partial\phi /\partial x)^2 + (\partial\phi /\partial y)^2}514 \label{eq:LBC_cy} 515 c_y = -\frac{\partial\phi}{\partial t}\frac{\partial\phi / \partial y}{(\partial\phi /\partial x)^2 + (\partial\phi /\partial y)^2} 555 516 \end{equation} 556 517 557 518 (As noted by MMS, this is a circular diagnosis of the phase speeds which only makes sense on a discrete grid). 558 Equation (\autoref{eq: wave_continuous}) is defined adaptively depending on the sign of the phase velocity normal to the boundary $c_x$.519 Equation (\autoref{eq:LBC_wave_continuous}) is defined adaptively depending on the sign of the phase velocity normal to the boundary $c_x$. 559 520 For $c_x$ outward, we have 560 521 … … 566 527 567 528 \begin{equation} 568 \tau = \tau_{in}\,\,\,;\,\,\, c_x = c_y = 0 569 \label{eq:tau_in} 529 \label{eq:LBC_tau_in} 530 \tau = \tau_{in}\,\,\,;\,\,\, c_x = c_y = 0 570 531 \end{equation} 571 532 572 Generally the relaxation time scale at inward propagation points \np{(rn\_time\_dmp}) is set much shorter than the time scale at outward propagation573 points (\np{rn \_time\_dmp\_out}) so that the solution is constrained more strongly by the external data at inward propagation points.574 See \autoref{subsec: BDY_relaxation} for detailed on the spatial shape of the scaling.\\575 The ``normal propagation of oblique radiation'' or NPO approximation (called \forcode{'orlanski_npo'}) involves assuming 576 that $c_y$ is zero in equation (\autoref{eq: wave_continuous}), but including577 this term in the denominator of equation (\autoref{eq: cx}). Both versions of the scheme are options in BDY. Equations578 (\autoref{eq: wave_continuous}) - (\autoref{eq:tau_in}) correspond to equations (13) - (15) and (2) - (3) in MMS.\\579 580 % ----------------------------------------------533 Generally the relaxation time scale at inward propagation points (\np{rn_time_dmp}{rn\_time\_dmp}) is set much shorter than the time scale at outward propagation 534 points (\np{rn_time_dmp_out}{rn\_time\_dmp\_out}) so that the solution is constrained more strongly by the external data at inward propagation points. 535 See \autoref{subsec:LBC_bdy_relaxation} for detailed on the spatial shape of the scaling.\\ 536 The ``normal propagation of oblique radiation'' or NPO approximation (called \forcode{'orlanski_npo'}) involves assuming 537 that $c_y$ is zero in equation (\autoref{eq:LBC_wave_continuous}), but including 538 this term in the denominator of equation (\autoref{eq:LBC_cx}). Both versions of the scheme are options in BDY. Equations 539 (\autoref{eq:LBC_wave_continuous}) - (\autoref{eq:LBC_tau_in}) correspond to equations (13) - (15) and (2) - (3) in MMS.\\ 540 541 %% ================================================================================================= 581 542 \subsection{Relaxation at the boundary} 582 \label{subsec: BDY_relaxation}583 584 In addition to a specific boundary condition specified as \np{cn \_tra} and \np{cn\_dyn3d}, relaxation on baroclinic velocities and tracers variables are available.585 It is control by the namelist parameter \np{ln \_tra\_dmp} and \np{ln\_dyn3d\_dmp} for each boundary set.586 587 The relaxation time scale value (\np{rn \_time\_dmp} and \np{rn\_time\_dmp\_out}, $\tau$) are defined at the boundaries itself.588 This time scale ($\alpha$) is weighted by the distance ($d$) from the boundary over \np{nn \_rimwidth} cells ($N$):543 \label{subsec:LBC_bdy_relaxation} 544 545 In addition to a specific boundary condition specified as \np{cn_tra}{cn\_tra} and \np{cn_dyn3d}{cn\_dyn3d}, relaxation on baroclinic velocities and tracers variables are available. 546 It is control by the namelist parameter \np{ln_tra_dmp}{ln\_tra\_dmp} and \np{ln_dyn3d_dmp}{ln\_dyn3d\_dmp} for each boundary set. 547 548 The relaxation time scale value (\np{rn_time_dmp}{rn\_time\_dmp} and \np{rn_time_dmp_out}{rn\_time\_dmp\_out}, $\tau$) are defined at the boundaries itself. 549 This time scale ($\alpha$) is weighted by the distance ($d$) from the boundary over \np{nn_rimwidth}{nn\_rimwidth} cells ($N$): 589 550 590 551 \[ … … 592 553 \] 593 554 594 The same scaling is applied in the Orlanski damping. 595 596 % ----------------------------------------------555 The same scaling is applied in the Orlanski damping. 556 557 %% ================================================================================================= 597 558 \subsection{Boundary geometry} 598 \label{subsec: BDY_geometry}559 \label{subsec:LBC_bdy_geometry} 599 560 600 561 Each open boundary set is defined as a list of points. 601 562 The information is stored in the arrays $nbi$, $nbj$, and $nbr$ in the $idx\_bdy$ structure. 602 The $nbi$ and $nbj$ arrays define the local $(i,j)$ ind ices of each point in the boundary zone and603 the $nbr$ array defines the discrete distance from the boundary with $nbr=1$ meaningthat604 the point is next to the edge of the model domain and $nbr>1$ showingthat605 the point is increasingly further away from the edge of the model domain.563 The $nbi$ and $nbj$ arrays define the local $(i,j)$ indexes of each point in the boundary zone and 564 the $nbr$ array defines the discrete distance from the boundary: $nbr=1$ means that 565 the boundary point is next to the edge of the model domain, while $nbr>1$ means that 566 the boundary point is increasingly further away from the edge of the model domain. 606 567 A set of $nbi$, $nbj$, and $nbr$ arrays is defined for each of the $T$, $U$ and $V$ grids. 607 Figure \autoref{fig:LBC_bdy_geom} shows an example of an irregular boundary. 568 \autoref{fig:LBC_bdy_geom} shows an example of an irregular boundary. 608 569 609 570 The boundary geometry for each set may be defined in a namelist nambdy\_index or 610 571 by reading in a ``\ifile{coordinates.bdy}'' file. 611 572 The nambdy\_index namelist defines a series of straight-line segments for north, east, south and west boundaries. 612 One nambdy\_index namelist bloc is needed for each boundary condition defined by indexes.613 For the northern boundary, \ np{nbdysegn} gives the number of segments,614 \ np{jpjnob} gives the $j$ index for each segment and \np{jpindt} and615 \ np{jpinft} give the start and end $i$ indices for each segment with similar for the other boundaries.573 One nambdy\_index namelist block is needed for each boundary condition defined by indexes. 574 For the northern boundary, \texttt{nbdysegn} gives the number of segments, 575 \jp{jpjnob} gives the $j$ index for each segment and \jp{jpindt} and 576 \jp{jpinft} give the start and end $i$ indices for each segment with similar for the other boundaries. 616 577 These segments define a list of $T$ grid points along the outermost row of the boundary ($nbr\,=\, 1$). 617 The code deduces the $U$ and $V$ points and also the points for $nbr\,>\, 1$ if \np {nn\_rimwidth}\forcode{ > 1}.578 The code deduces the $U$ and $V$ points and also the points for $nbr\,>\, 1$ if \np[>1]{nn_rimwidth}{nn\_rimwidth}. 618 579 619 580 The boundary geometry may also be defined from a ``\ifile{coordinates.bdy}'' file. 620 Figure \autoref{fig:LBC_nc_header} gives an example of the header information from such a file.581 \autoref{fig:LBC_nc_header} gives an example of the header information from such a file, based on the description of geometrical setup given above. 621 582 The file should contain the index arrays for each of the $T$, $U$ and $V$ grids. 622 583 The arrays must be in order of increasing $nbr$. … … 624 585 Typically this file will be used to generate external boundary data via interpolation and so 625 586 will also contain the latitudes and longitudes of each point as shown. 626 However, this is not necessary to run the model. 587 However, this is not necessary to run the model. 627 588 628 589 For some choices of irregular boundary the model domain may contain areas of ocean which 629 590 are not part of the computational domain. 630 For example if an open boundary is defined along an isobath, say at the shelf break,591 For example, if an open boundary is defined along an isobath, say at the shelf break, 631 592 then the areas of ocean outside of this boundary will need to be masked out. 632 This can be done by reading a mask file defined as \np{cn \_mask\_file} in the nam\_bdy namelist.593 This can be done by reading a mask file defined as \np{cn_mask_file}{cn\_mask\_file} in the nam\_bdy namelist. 633 594 Only one mask file is used even if multiple boundary sets are defined. 634 595 635 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>636 596 \begin{figure}[!t] 637 \begin{center} 638 \includegraphics[width=1.0\textwidth]{Fig_LBC_bdy_geom} 639 \caption { 640 \protect\label{fig:LBC_bdy_geom} 641 Example of geometry of unstructured open boundary 642 } 643 \end{center} 597 \centering 598 \includegraphics[width=0.66\textwidth]{LBC_bdy_geom} 599 \caption[Geometry of unstructured open boundary]{Example of geometry of unstructured open boundary} 600 \label{fig:LBC_bdy_geom} 644 601 \end{figure} 645 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 646 647 %---------------------------------------------- 602 603 %% ================================================================================================= 648 604 \subsection{Input boundary data files} 649 \label{subsec: BDY_data}605 \label{subsec:LBC_bdy_data} 650 606 651 607 The data files contain the data arrays in the order in which the points are defined in the $nbi$ and $nbj$ arrays. … … 653 609 a time dimension; 654 610 $xb$ which is the index of the boundary data point in the horizontal; 655 and $yb$ which is a degenerate dimension of 1 to enable the file to be read by the standard NEMOI/O routines.656 The 3D fields also have a depth dimension. 611 and $yb$ which is a degenerate dimension of 1 to enable the file to be read by the standard \NEMO\ I/O routines. 612 The 3D fields also have a depth dimension. 657 613 658 614 From Version 3.4 there are new restrictions on the order in which the boundary points are defined … … 665 621 \item All the data for a particular boundary set must be in the same order. 666 622 (Prior to 3.4 it was possible to define barotropic data in a different order to 667 the data for tracers and baroclinic velocities). 623 the data for tracers and baroclinic velocities). 668 624 \end{enumerate} 669 625 670 626 These restrictions mean that data files used with versions of the 671 627 model prior to Version 3.4 may not work with Version 3.4 onwards. 672 A \fortran utility {\itbdy\_reorder} exists in the TOOLS directory which628 A \fortran\ utility {\itshape bdy\_reorder} exists in the TOOLS directory which 673 629 will re-order the data in old BDY data files. 674 630 675 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>676 631 \begin{figure}[!t] 677 \begin{center} 678 \includegraphics[width=1.0\textwidth]{Fig_LBC_nc_header} 679 \caption { 680 \protect\label{fig:LBC_nc_header} 681 Example of the header for a \protect\ifile{coordinates.bdy} file 682 } 683 \end{center} 632 \centering 633 \includegraphics[width=0.66\textwidth]{LBC_nc_header} 634 \caption[Header for a \protect\ifile{coordinates.bdy} file]{ 635 Example of the header for a \protect\ifile{coordinates.bdy} file} 636 \label{fig:LBC_nc_header} 684 637 \end{figure} 685 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 686 687 %---------------------------------------------- 638 639 %% ================================================================================================= 688 640 \subsection{Volume correction} 689 \label{subsec: BDY_vol_corr}641 \label{subsec:LBC_bdy_vol_corr} 690 642 691 643 There is an option to force the total volume in the regional model to be constant. 692 This is controlled by the \np{ln \_vol} parameter in the namelist.693 A value of \np {ln\_vol}\forcode{ = .false.} indicates that this option is not used.694 Two options to control the volume are available (\np{nn \_volctl}).695 If \np {nn\_volctl}\forcode{ = 0} then a correction is applied to the normal barotropic velocities around the boundary at644 This is controlled by the \np{ln_vol}{ln\_vol} parameter in the namelist. 645 A value of \np[=.false.]{ln_vol}{ln\_vol} indicates that this option is not used. 646 Two options to control the volume are available (\np{nn_volctl}{nn\_volctl}). 647 If \np[=0]{nn_volctl}{nn\_volctl} then a correction is applied to the normal barotropic velocities around the boundary at 696 648 each timestep to ensure that the integrated volume flow through the boundary is zero. 697 If \np {nn\_volctl}\forcode{ = 1} then the calculation of the volume change on649 If \np[=1]{nn_volctl}{nn\_volctl} then the calculation of the volume change on 698 650 the timestep includes the change due to the freshwater flux across the surface and 699 651 the correction velocity corrects for this as well. … … 702 654 applied to all boundaries at once. 703 655 704 % ----------------------------------------------656 %% ================================================================================================= 705 657 \subsection{Tidal harmonic forcing} 706 \label{subsec:BDY_tides} 707 708 %-----------------------------------------nambdy_tide-------------------------------------------- 709 710 \nlst{nambdy_tide} 711 %----------------------------------------------------------------------------------------------- 658 \label{subsec:LBC_bdy_tides} 659 660 \begin{listing} 661 \nlst{nambdy_tide} 662 \caption{\forcode{&nambdy_tide}} 663 \label{lst:nambdy_tide} 664 \end{listing} 712 665 713 666 Tidal forcing at open boundaries requires the activation of surface 714 tides (i.e., in \n gn{nam\_tide}, \np{ln\_tide} needs to be set to667 tides (i.e., in \nam{_tide}{\_tide}, \np{ln_tide}{ln\_tide} needs to be set to 715 668 \forcode{.true.} and the required constituents need to be activated by 716 including their names in the \np{c name} array; see669 including their names in the \np{clname}{clname} array; see 717 670 \autoref{sec:SBC_tide}). Specific options related to the reading in of 718 671 the complex harmonic amplitudes of elevation (SSH) and barotropic 719 672 velocity (u,v) at open boundaries are defined through the 720 \n gn{nambdy\_tide} namelist parameters.\\673 \nam{bdy_tide}{bdy\_tide} namelist parameters.\\ 721 674 722 675 The tidal harmonic data at open boundaries can be specified in two 723 676 different ways, either on a two-dimensional grid covering the entire 724 677 model domain or along open boundary segments; these two variants can 725 be selected by setting \np{ln \_bdytide\_2ddta } to \forcode{.true.} or678 be selected by setting \np{ln_bdytide_2ddta }{ln\_bdytide\_2ddta } to \forcode{.true.} or 726 679 \forcode{.false.}, respectively. In either case, the real and 727 680 imaginary parts of SSH and the two barotropic velocity components for … … 729 682 separately: when two-dimensional data is used, variables 730 683 \textit{tcname\_z1} and \textit{tcname\_z2} for real and imaginary SSH, 731 respectively, are expected in input file \np{filtide} with suffix684 respectively, are expected in input file \np{filtide}{filtide} with suffix 732 685 \ifile{\_grid\_T}, variables \textit{tcname\_u1} and 733 686 \textit{tcname\_u2} for real and imaginary u, respectively, are 734 expected in input file \np{filtide} with suffix \ifile{\_grid\_U}, and687 expected in input file \np{filtide}{filtide} with suffix \ifile{\_grid\_U}, and 735 688 \textit{tcname\_v1} and \textit{tcname\_v2} for real and imaginary v, 736 respectively, are expected in input file \np{filtide} with suffix689 respectively, are expected in input file \np{filtide}{filtide} with suffix 737 690 \ifile{\_grid\_V}; when data along open boundary segments is used, 738 691 variables \textit{z1} and \textit{z2} (real and imaginary part of SSH) 739 are expected to be available from file \np{filtide} with suffix692 are expected to be available from file \np{filtide}{filtide} with suffix 740 693 \ifile{tcname\_grid\_T}, variables \textit{u1} and \textit{u2} (real 741 694 and imaginary part of u) are expected to be available from file 742 \np{filtide} with suffix \ifile{tcname\_grid\_U}, and variables695 \np{filtide}{filtide} with suffix \ifile{tcname\_grid\_U}, and variables 743 696 \textit{v1} and \textit{v2} (real and imaginary part of v) are 744 expected to be available from file \np{filtide} with suffix745 \ifile{tcname\_grid\_V}. If \np{ln \_bdytide\_conj} is set to697 expected to be available from file \np{filtide}{filtide} with suffix 698 \ifile{tcname\_grid\_V}. If \np{ln_bdytide_conj}{ln\_bdytide\_conj} is set to 746 699 \forcode{.true.}, the data is expected to be in complex conjugate 747 700 form. … … 755 708 direction of rotation). %, e.g. anticlockwise or clockwise. 756 709 757 \biblio 758 759 \pindex 710 \subinc{\input{../../global/epilogue}} 760 711 761 712 \end{document} -
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_LDF.tex
r10442 r11831 3 3 \begin{document} 4 4 5 % ================================================================6 % Chapter Lateral Ocean Physics (LDF)7 % ================================================================8 5 \chapter{Lateral Ocean Physics (LDF)} 9 6 \label{chap:LDF} 10 7 11 \minitoc 12 13 \newpage 14 15 The lateral physics terms in the momentum and tracer equations have been described in \autoref{eq:PE_zdf} and 8 \thispagestyle{plain} 9 10 \chaptertoc 11 12 \paragraph{Changes record} ~\\ 13 14 {\footnotesize 15 \begin{tabularx}{\textwidth}{l||X|X} 16 Release & Author(s) & Modifications \\ 17 \hline 18 {\em 4.0} & {\em ...} & {\em ...} \\ 19 {\em 3.6} & {\em ...} & {\em ...} \\ 20 {\em 3.4} & {\em ...} & {\em ...} \\ 21 {\em <=3.4} & {\em ...} & {\em ...} 22 \end{tabularx} 23 } 24 25 \clearpage 26 27 The lateral physics terms in the momentum and tracer equations have been described in \autoref{eq:MB_zdf} and 16 28 their discrete formulation in \autoref{sec:TRA_ldf} and \autoref{sec:DYN_ldf}). 17 29 In this section we further discuss each lateral physics option. … … 22 34 (3) the space and time variations of the eddy coefficients. 23 35 These three aspects of the lateral diffusion are set through namelist parameters 24 (see the \ngn{nam\_traldf} and \ngn{nam\_dynldf} below). 25 Note that this chapter describes the standard implementation of iso-neutral tracer mixing, 26 and Griffies's implementation, which is used if \np{traldf\_grif}\forcode{ = .true.}, 27 is described in Appdx\autoref{apdx:triad} 28 29 %-----------------------------------nam_traldf - nam_dynldf-------------------------------------------- 30 31 \nlst{namtra_ldf} 32 33 \nlst{namdyn_ldf} 34 %-------------------------------------------------------------------------------------------------------------- 35 36 37 % ================================================================ 38 % Direction of lateral Mixing 39 % ================================================================ 40 \section{Direction of lateral mixing (\protect\mdl{ldfslp})} 36 (see the \nam{tra_ldf}{tra\_ldf} and \nam{dyn_ldf}{dyn\_ldf} below). 37 Note that this chapter describes the standard implementation of iso-neutral tracer mixing. 38 Griffies's implementation, which is used if \np[=.true.]{ln_traldf_triad}{ln\_traldf\_triad}, 39 is described in \autoref{apdx:TRIADS} 40 41 %% ================================================================================================= 42 \section[Lateral mixing operators]{Lateral mixing operators} 43 \label{sec:LDF_op} 44 We remind here the different lateral mixing operators that can be used. Further details can be found in \autoref{subsec:TRA_ldf_op} and \autoref{sec:DYN_ldf}. 45 46 %% ================================================================================================= 47 \subsection[No lateral mixing (\forcode{ln_traldf_OFF} \& \forcode{ln_dynldf_OFF})]{No lateral mixing (\protect\np{ln_traldf_OFF}{ln\_traldf\_OFF} \& \protect\np{ln_dynldf_OFF}{ln\_dynldf\_OFF})} 48 49 It is possible to run without explicit lateral diffusion on tracers (\protect\np[=.true.]{ln_traldf_OFF}{ln\_traldf\_OFF}) and/or 50 momentum (\protect\np[=.true.]{ln_dynldf_OFF}{ln\_dynldf\_OFF}). The latter option is even recommended if using the 51 UBS advection scheme on momentum (\np[=.true.]{ln_dynadv_ubs}{ln\_dynadv\_ubs}, 52 see \autoref{subsec:DYN_adv_ubs}) and can be useful for testing purposes. 53 54 %% ================================================================================================= 55 \subsection[Laplacian mixing (\forcode{ln_traldf_lap} \& \forcode{ln_dynldf_lap})]{Laplacian mixing (\protect\np{ln_traldf_lap}{ln\_traldf\_lap} \& \protect\np{ln_dynldf_lap}{ln\_dynldf\_lap})} 56 Setting \protect\np[=.true.]{ln_traldf_lap}{ln\_traldf\_lap} and/or \protect\np[=.true.]{ln_dynldf_lap}{ln\_dynldf\_lap} enables 57 a second order diffusion on tracers and momentum respectively. Note that in \NEMO\ 4, one can not combine 58 Laplacian and Bilaplacian operators for the same variable. 59 60 %% ================================================================================================= 61 \subsection[Bilaplacian mixing (\forcode{ln_traldf_blp} \& \forcode{ln_dynldf_blp})]{Bilaplacian mixing (\protect\np{ln_traldf_blp}{ln\_traldf\_blp} \& \protect\np{ln_dynldf_blp}{ln\_dynldf\_blp})} 62 Setting \protect\np[=.true.]{ln_traldf_blp}{ln\_traldf\_blp} and/or \protect\np[=.true.]{ln_dynldf_blp}{ln\_dynldf\_blp} enables 63 a fourth order diffusion on tracers and momentum respectively. It is implemented by calling the above Laplacian operator twice. 64 We stress again that from \NEMO\ 4, the simultaneous use Laplacian and Bilaplacian operators is not allowed. 65 66 %% ================================================================================================= 67 \section[Direction of lateral mixing (\textit{ldfslp.F90})]{Direction of lateral mixing (\protect\mdl{ldfslp})} 41 68 \label{sec:LDF_slp} 42 69 43 %%% 44 \gmcomment{ 70 \cmtgm{ 45 71 we should emphasize here that the implementation is a rather old one. 46 Better work can be achieved by using \citet{ Griffies_al_JPO98, Griffies_Bk04} iso-neutral scheme.72 Better work can be achieved by using \citet{griffies.gnanadesikan.ea_JPO98, griffies_bk04} iso-neutral scheme. 47 73 } 48 74 49 75 A direction for lateral mixing has to be defined when the desired operator does not act along the model levels. 50 76 This occurs when $(a)$ horizontal mixing is required on tracer or momentum 51 (\np{ln \_traldf\_hor} or \np{ln\_dynldf\_hor}) in $s$- or mixed $s$-$z$- coordinates,77 (\np{ln_traldf_hor}{ln\_traldf\_hor} or \np{ln_dynldf_hor}{ln\_dynldf\_hor}) in $s$- or mixed $s$-$z$- coordinates, 52 78 and $(b)$ isoneutral mixing is required whatever the vertical coordinate is. 53 79 This direction of mixing is defined by its slopes in the \textbf{i}- and \textbf{j}-directions at the face of 54 80 the cell of the quantity to be diffused. 55 81 For a tracer, this leads to the following four slopes: 56 $r_{1u}$, $r_{1w}$, $r_{2v}$, $r_{2w}$ (see \autoref{eq: tra_ldf_iso}),82 $r_{1u}$, $r_{1w}$, $r_{2v}$, $r_{2w}$ (see \autoref{eq:TRA_ldf_iso}), 57 83 while for momentum the slopes are $r_{1t}$, $r_{1uw}$, $r_{2f}$, $r_{2uw}$ for $u$ and 58 $r_{1f}$, $r_{1vw}$, $r_{2t}$, $r_{2vw}$ for $v$. 59 60 %gm% add here afigure of the slope in i-direction 61 84 $r_{1f}$, $r_{1vw}$, $r_{2t}$, $r_{2vw}$ for $v$. 85 86 \cmtgm{Add here afigure of the slope in i-direction} 87 88 %% ================================================================================================= 62 89 \subsection{Slopes for tracer geopotential mixing in the $s$-coordinate} 63 90 64 In $s$-coordinates, geopotential mixing (\ie horizontal mixing) $r_1$ and $r_2$ are the slopes between91 In $s$-coordinates, geopotential mixing (\ie\ horizontal mixing) $r_1$ and $r_2$ are the slopes between 65 92 the geopotential and computational surfaces. 66 Their discrete formulation is found by locally solving \autoref{eq: tra_ldf_iso} when93 Their discrete formulation is found by locally solving \autoref{eq:TRA_ldf_iso} when 67 94 the diffusive fluxes in the three directions are set to zero and $T$ is assumed to be horizontally uniform, 68 \ie a linear function of $z_T$, the depth of a $T$-point. 69 %gm { Steven : My version is obviously wrong since I'm left with an arbitrary constant which is the local vertical temperature gradient} 70 71 \begin{equation} 72 \label{eq:ldfslp_geo} 95 \ie\ a linear function of $z_T$, the depth of a $T$-point. 96 \cmtgm{Steven : My version is obviously wrong since 97 I'm left with an arbitrary constant which is the local vertical temperature gradient} 98 99 \begin{equation} 100 \label{eq:LDF_slp_geo} 73 101 \begin{aligned} 74 102 r_{1u} &= \frac{e_{3u}}{ \left( e_{1u}\;\overline{\overline{e_{3w}}}^{\,i+1/2,\,k} \right)} … … 85 113 \end{equation} 86 114 87 %gm% caution I'm not sure the simplification was a good idea! 88 89 These slopes are computed once in \rou{ldfslp\_init} when \np{ln\_sco}\forcode{ = .true.}rue, 90 and either \np{ln\_traldf\_hor}\forcode{ = .true.} or \np{ln\_dynldf\_hor}\forcode{ = .true.}. 91 115 \cmtgm{Caution I'm not sure the simplification was a good idea!} 116 117 These slopes are computed once in \rou{ldf\_slp\_init} when \np[=.true.]{ln_sco}{ln\_sco}, 118 and either \np[=.true.]{ln_traldf_hor}{ln\_traldf\_hor} or \np[=.true.]{ln_dynldf_hor}{ln\_dynldf\_hor}. 119 120 %% ================================================================================================= 92 121 \subsection{Slopes for tracer iso-neutral mixing} 93 122 \label{subsec:LDF_slp_iso} … … 96 125 Their formulation does not depend on the vertical coordinate used. 97 126 Their discrete formulation is found using the fact that the diffusive fluxes of 98 locally referenced potential density (\ie $in situ$ density) vanish.99 So, substituting $T$ by $\rho$ in \autoref{eq: tra_ldf_iso} and setting the diffusive fluxes in127 locally referenced potential density (\ie\ $in situ$ density) vanish. 128 So, substituting $T$ by $\rho$ in \autoref{eq:TRA_ldf_iso} and setting the diffusive fluxes in 100 129 the three directions to zero leads to the following definition for the neutral slopes: 101 130 102 131 \begin{equation} 103 \label{eq: ldfslp_iso}132 \label{eq:LDF_slp_iso} 104 133 \begin{split} 105 134 r_{1u} &= \frac{e_{3u}}{e_{1u}}\; \frac{\delta_{i+1/2}[\rho]} … … 116 145 \end{equation} 117 146 118 %gm% rewrite this as the explanation is not very clear !!! 119 %In practice, \autoref{eq: ldfslp_iso} is of little help in evaluating the neutral surface slopes. Indeed, for an unsimplified equation of state, the density has a strong dependancy on pressure (here approximated as the depth), therefore applying \autoref{eq:ldfslp_iso} using the $in situ$ density, $\rho$, computed at T-points leads to a flattening of slopes as the depth increases. This is due to the strong increase of the $in situ$ density with depth.120 121 %By definition, neutral surfaces are tangent to the local $in situ$ density \citep{ McDougall1987}, therefore in \autoref{eq:ldfslp_iso}, all the derivatives have to be evaluated at the same local pressure (which in decibars is approximated by the depth in meters).122 123 %In the $z$-coordinate, the derivative of the \autoref{eq: ldfslp_iso} numerator is evaluated at the same depth \nocite{as what?} ($T$-level, which is the same as the $u$- and $v$-levels), so the $in situ$ density can be used for its evaluation.124 125 As the mixing is performed along neutral surfaces, the gradient of $\rho$ in \autoref{eq: ldfslp_iso} has to147 \cmtgm{rewrite this as the explanation is not very clear !!!} 148 %In practice, \autoref{eq:LDF_slp_iso} is of little help in evaluating the neutral surface slopes. Indeed, for an unsimplified equation of state, the density has a strong dependancy on pressure (here approximated as the depth), therefore applying \autoref{eq:LDF_slp_iso} using the $in situ$ density, $\rho$, computed at T-points leads to a flattening of slopes as the depth increases. This is due to the strong increase of the $in situ$ density with depth. 149 150 %By definition, neutral surfaces are tangent to the local $in situ$ density \citep{mcdougall_JPO87}, therefore in \autoref{eq:LDF_slp_iso}, all the derivatives have to be evaluated at the same local pressure (which in decibars is approximated by the depth in meters). 151 152 %In the $z$-coordinate, the derivative of the \autoref{eq:LDF_slp_iso} numerator is evaluated at the same depth \nocite{as what?} ($T$-level, which is the same as the $u$- and $v$-levels), so the $in situ$ density can be used for its evaluation. 153 154 As the mixing is performed along neutral surfaces, the gradient of $\rho$ in \autoref{eq:LDF_slp_iso} has to 126 155 be evaluated at the same local pressure 127 156 (which, in decibars, is approximated by the depth in meters in the model). 128 Therefore \autoref{eq: ldfslp_iso} cannot be used as such,157 Therefore \autoref{eq:LDF_slp_iso} cannot be used as such, 129 158 but further transformation is needed depending on the vertical coordinate used: 130 159 131 160 \begin{description} 132 133 \item[$z$-coordinate with full step: ] 134 in \autoref{eq:ldfslp_iso} the densities appearing in the $i$ and $j$ derivatives are taken at the same depth, 161 \item [$z$-coordinate with full step:] in \autoref{eq:LDF_slp_iso} the densities appearing in the $i$ and $j$ derivatives are taken at the same depth, 135 162 thus the $in situ$ density can be used. 136 163 This is not the case for the vertical derivatives: $\delta_{k+1/2}[\rho]$ is replaced by $-\rho N^2/g$, 137 where $N^2$ is the local Brunt-Vais\"{a}l\"{a} frequency evaluated following \citet{McDougall1987} 138 (see \autoref{subsec:TRA_bn2}). 139 140 \item[$z$-coordinate with partial step: ] 141 this case is identical to the full step case except that at partial step level, 164 where $N^2$ is the local Brunt-Vais\"{a}l\"{a} frequency evaluated following \citet{mcdougall_JPO87} 165 (see \autoref{subsec:TRA_bn2}). 166 \item [$z$-coordinate with partial step:] this case is identical to the full step case except that at partial step level, 142 167 the \emph{horizontal} density gradient is evaluated as described in \autoref{sec:TRA_zpshde}. 143 144 \item[$s$- or hybrid $s$-$z$- coordinate: ] 145 in the current release of \NEMO, iso-neutral mixing is only employed for $s$-coordinates if 146 the Griffies scheme is used (\np{traldf\_grif}\forcode{ = .true.}; 147 see Appdx \autoref{apdx:triad}). 168 \item [$s$- or hybrid $s$-$z$- coordinate:] in the current release of \NEMO, iso-neutral mixing is only employed for $s$-coordinates if 169 the Griffies scheme is used (\np[=.true.]{ln_traldf_triad}{ln\_traldf\_triad}; 170 see \autoref{apdx:TRIADS}). 148 171 In other words, iso-neutral mixing will only be accurately represented with a linear equation of state 149 (\np {nn\_eos}\forcode{ = 1..2}).150 In the case of a "true" equation of state, the evaluation of $i$ and $j$ derivatives in \autoref{eq: ldfslp_iso}172 (\np[=.true.]{ln_seos}{ln\_seos}). 173 In the case of a "true" equation of state, the evaluation of $i$ and $j$ derivatives in \autoref{eq:LDF_slp_iso} 151 174 will include a pressure dependent part, leading to the wrong evaluation of the neutral slopes. 152 175 153 %gm%154 176 Note: The solution for $s$-coordinate passes trough the use of different (and better) expression for 155 177 the constraint on iso-neutral fluxes. 156 Following \citet{ Griffies_Bk04}, instead of specifying directly that there is a zero neutral diffusive flux of178 Following \citet{griffies_bk04}, instead of specifying directly that there is a zero neutral diffusive flux of 157 179 locally referenced potential density, we stay in the $T$-$S$ plane and consider the balance between 158 180 the neutral direction diffusive fluxes of potential temperature and salinity: … … 160 182 \alpha \ \textbf{F}(T) = \beta \ \textbf{F}(S) 161 183 \] 162 % gm{where vector F is ....}184 \cmtgm{where vector F is ....} 163 185 164 186 This constraint leads to the following definition for the slopes: 165 187 166 188 \[ 167 % \label{eq: ldfslp_iso2}189 % \label{eq:LDF_slp_iso2} 168 190 \begin{split} 169 191 r_{1u} &= \frac{e_{3u}}{e_{1u}}\; \frac … … 193 215 194 216 Note that such a formulation could be also used in the $z$-coordinate and $z$-coordinate with partial steps cases. 195 196 217 \end{description} 197 218 198 219 This implementation is a rather old one. 199 It is similar to the one proposed by Cox [1987], except for the background horizontal diffusion.200 Indeed, the Coximplementation of isopycnal diffusion in GFDL-type models requires220 It is similar to the one proposed by \citet{cox_OM87}, except for the background horizontal diffusion. 221 Indeed, the \citet{cox_OM87} implementation of isopycnal diffusion in GFDL-type models requires 201 222 a minimum background horizontal diffusion for numerical stability reasons. 202 223 To overcome this problem, several techniques have been proposed in which the numerical schemes of 203 the ocean model are modified \citep{ Weaver_Eby_JPO97, Griffies_al_JPO98}.204 Griffies's scheme is now available in \NEMO if \np{traldf\_grif\_iso} is set true; see Appdx \autoref{apdx:triad}.205 Here, another strategy is presented \citep{ Lazar_PhD97}:224 the ocean model are modified \citep{weaver.eby_JPO97, griffies.gnanadesikan.ea_JPO98}. 225 Griffies's scheme is now available in \NEMO\ if \np[=.true.]{ln_traldf_triad}{ln\_traldf\_triad}; see \autoref{apdx:TRIADS}. 226 Here, another strategy is presented \citep{lazar_phd97}: 206 227 a local filtering of the iso-neutral slopes (made on 9 grid-points) prevents the development of 207 228 grid point noise generated by the iso-neutral diffusion operator (\autoref{fig:LDF_ZDF1}). 208 229 This allows an iso-neutral diffusion scheme without additional background horizontal mixing. 209 230 This technique can be viewed as a diffusion operator that acts along large-scale 210 (2~$\Delta$x) \ gmcomment{2deltax doesnt seem very large scale} iso-neutral surfaces.231 (2~$\Delta$x) \cmtgm{2deltax doesnt seem very large scale} iso-neutral surfaces. 211 232 The diapycnal diffusion required for numerical stability is thus minimized and its net effect on the flow is quite small when compared to the effect of an horizontal background mixing. 212 233 213 234 Nevertheless, this iso-neutral operator does not ensure that variance cannot increase, 214 contrary to the \citet{Griffies_al_JPO98} operator which has that property. 215 216 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 235 contrary to the \citet{griffies.gnanadesikan.ea_JPO98} operator which has that property. 236 217 237 \begin{figure}[!ht] 218 \begin{center} 219 \includegraphics[width=0.70\textwidth]{Fig_LDF_ZDF1} 220 \caption { 221 \protect\label{fig:LDF_ZDF1} 222 averaging procedure for isopycnal slope computation. 223 } 224 \end{center} 238 \centering 239 \includegraphics[width=0.66\textwidth]{LDF_ZDF1} 240 \caption{Averaging procedure for isopycnal slope computation} 241 \label{fig:LDF_ZDF1} 225 242 \end{figure} 226 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 227 228 %There are three additional questions about the slope calculation. 229 %First the expression for the rotation tensor has been obtain assuming the "small slope" approximation, so a bound has to be imposed on slopes. 230 %Second, numerical stability issues also require a bound on slopes. 243 244 %There are three additional questions about the slope calculation. 245 %First the expression for the rotation tensor has been obtain assuming the "small slope" approximation, so a bound has to be imposed on slopes. 246 %Second, numerical stability issues also require a bound on slopes. 231 247 %Third, the question of boundary condition specified on slopes... 232 248 233 249 %from griffies: chapter 13.1.... 234 250 235 236 237 % In addition and also for numerical stability reasons \citep{Cox1987, Griffies_Bk04}, 238 % the slopes are bounded by $1/100$ everywhere. This limit is decreasing linearly 239 % to zero fom $70$ meters depth and the surface (the fact that the eddies "feel" the 251 % In addition and also for numerical stability reasons \citep{cox_OM87, griffies_bk04}, 252 % the slopes are bounded by $1/100$ everywhere. This limit is decreasing linearly 253 % to zero fom $70$ meters depth and the surface (the fact that the eddies "feel" the 240 254 % surface motivates this flattening of isopycnals near the surface). 241 255 242 For numerical stability reasons \citep{ Cox1987, Griffies_Bk04}, the slopes must also be bounded by243 $1/100$everywhere.256 For numerical stability reasons \citep{cox_OM87, griffies_bk04}, the slopes must also be bounded by 257 the namelist scalar \np{rn_slpmax}{rn\_slpmax} (usually $1/100$) everywhere. 244 258 This constraint is applied in a piecewise linear fashion, increasing from zero at the surface to 245 259 $1/100$ at $70$ metres and thereafter decreasing to zero at the bottom of the ocean 246 260 (the fact that the eddies "feel" the surface motivates this flattening of isopycnals near the surface). 247 248 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 261 \colorbox{yellow}{The way slopes are tapered has be checked. Not sure that this is still what is actually done.} 262 249 263 \begin{figure}[!ht] 250 \begin{center} 251 \includegraphics[width=0.70\textwidth]{Fig_eiv_slp} 252 \caption{ 253 \protect\label{fig:eiv_slp} 254 Vertical profile of the slope used for lateral mixing in the mixed layer: 255 \textit{(a)} in the real ocean the slope is the iso-neutral slope in the ocean interior, 256 which has to be adjusted at the surface boundary 257 \ie it must tend to zero at the surface since there is no mixing across the air-sea interface: 258 wall boundary condition). 259 Nevertheless, the profile between the surface zero value and the interior iso-neutral one is unknown, 260 and especially the value at the base of the mixed layer; 261 \textit{(b)} profile of slope using a linear tapering of the slope near the surface and 262 imposing a maximum slope of 1/100; 263 \textit{(c)} profile of slope actually used in \NEMO: a linear decrease of the slope from 264 zero at the surface to its ocean interior value computed just below the mixed layer. 265 Note the huge change in the slope at the base of the mixed layer between \textit{(b)} and \textit{(c)}. 266 } 267 \end{center} 264 \centering 265 \includegraphics[width=0.66\textwidth]{LDF_eiv_slp} 266 \caption[Vertical profile of the slope used for lateral mixing in the mixed layer]{ 267 Vertical profile of the slope used for lateral mixing in the mixed layer: 268 \textit{(a)} in the real ocean the slope is the iso-neutral slope in the ocean interior, 269 which has to be adjusted at the surface boundary 270 \ie\ it must tend to zero at the surface since there is no mixing across the air-sea interface: 271 wall boundary condition). 272 Nevertheless, 273 the profile between the surface zero value and the interior iso-neutral one is unknown, 274 and especially the value at the base of the mixed layer; 275 \textit{(b)} profile of slope using a linear tapering of the slope near the surface and 276 imposing a maximum slope of 1/100; 277 \textit{(c)} profile of slope actually used in \NEMO: 278 a linear decrease of the slope from zero at the surface to 279 its ocean interior value computed just below the mixed layer. 280 Note the huge change in the slope at the base of the mixed layer between 281 \textit{(b)} and \textit{(c)}.} 282 \label{fig:LDF_eiv_slp} 268 283 \end{figure} 269 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>270 284 271 285 \colorbox{yellow}{add here a discussion about the flattening of the slopes, vs tapering the coefficient.} 272 286 287 %% ================================================================================================= 273 288 \subsection{Slopes for momentum iso-neutral mixing} 274 289 275 290 The iso-neutral diffusion operator on momentum is the same as the one used on tracers but 276 291 applied to each component of the velocity separately 277 (see \autoref{eq: dyn_ldf_iso} in section~\autoref{subsec:DYN_ldf_iso}).292 (see \autoref{eq:DYN_ldf_iso} in section~\autoref{subsec:DYN_ldf_iso}). 278 293 The slopes between the surface along which the diffusion operator acts and the surface of computation 279 294 ($z$- or $s$-surfaces) are defined at $T$-, $f$-, and \textit{uw}- points for the $u$-component, and $T$-, $f$- and 280 295 \textit{vw}- points for the $v$-component. 281 296 They are computed from the slopes used for tracer diffusion, 282 \ie \autoref{eq:ldfslp_geo} and \autoref{eq:ldfslp_iso}:297 \ie\ \autoref{eq:LDF_slp_geo} and \autoref{eq:LDF_slp_iso}: 283 298 284 299 \[ 285 % \label{eq: ldfslp_dyn}300 % \label{eq:LDF_slp_dyn} 286 301 \begin{aligned} 287 302 &r_{1t}\ \ = \overline{r_{1u}}^{\,i} &&& r_{1f}\ \ &= \overline{r_{1u}}^{\,i+1/2} \\ … … 294 309 The major issue remaining is in the specification of the boundary conditions. 295 310 The same boundary conditions are chosen as those used for lateral diffusion along model level surfaces, 296 \ie using the shear computed along the model levels and with no additional friction at the ocean bottom311 \ie\ using the shear computed along the model levels and with no additional friction at the ocean bottom 297 312 (see \autoref{sec:LBC_coast}). 298 313 299 300 % ================================================================ 301 % Lateral Mixing Operator 302 % ================================================================ 303 \section{Lateral mixing operators (\protect\mdl{traldf}, \protect\mdl{traldf}) } 304 \label{sec:LDF_op} 305 306 307 308 % ================================================================ 309 % Lateral Mixing Coefficients 310 % ================================================================ 311 \section{Lateral mixing coefficient (\protect\mdl{ldftra}, \protect\mdl{ldfdyn}) } 314 %% ================================================================================================= 315 \section[Lateral mixing coefficient (\forcode{nn_aht_ijk_t} \& \forcode{nn_ahm_ijk_t})]{Lateral mixing coefficient (\protect\np{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})} 312 316 \label{sec:LDF_coef} 313 317 314 Introducing a space variation in the lateral eddy mixing coefficients changes the model core memory requirement, 315 adding up to four extra three-dimensional arrays for the geopotential or isopycnal second order operator applied to 316 momentum. 317 Six CPP keys control the space variation of eddy coefficients: three for momentum and three for tracer. 318 The three choices allow: 319 a space variation in the three space directions (\key{traldf\_c3d}, \key{dynldf\_c3d}), 320 in the horizontal plane (\key{traldf\_c2d}, \key{dynldf\_c2d}), 321 or in the vertical only (\key{traldf\_c1d}, \key{dynldf\_c1d}). 322 The default option is a constant value over the whole ocean on both momentum and tracers. 323 324 The number of additional arrays that have to be defined and the gridpoint position at which 325 they are defined depend on both the space variation chosen and the type of operator used. 326 The resulting eddy viscosity and diffusivity coefficients can be a function of more than one variable. 327 Changes in the computer code when switching from one option to another have been minimized by 328 introducing the eddy coefficients as statement functions 329 (include file \textit{ldftra\_substitute.h90} and \textit{ldfdyn\_substitute.h90}). 330 The functions are replaced by their actual meaning during the preprocessing step (CPP). 331 The specification of the space variation of the coefficient is made in \mdl{ldftra} and \mdl{ldfdyn}, 332 or more precisely in include files \textit{traldf\_cNd.h90} and \textit{dynldf\_cNd.h90}, with N=1, 2 or 3. 333 The user can modify these include files as he/she wishes. 334 The way the mixing coefficient are set in the reference version can be briefly described as follows: 335 336 \subsubsection{Constant mixing coefficients (default option)} 337 When none of the \key{dynldf\_...} and \key{traldf\_...} keys are defined, 338 a constant value is used over the whole ocean for momentum and tracers, 339 which is specified through the \np{rn\_ahm0} and \np{rn\_aht0} namelist parameters. 340 341 \subsubsection{Vertically varying mixing coefficients (\protect\key{traldf\_c1d} and \key{dynldf\_c1d})} 342 The 1D option is only available when using the $z$-coordinate with full step. 343 Indeed in all the other types of vertical coordinate, 344 the depth is a 3D function of (\textbf{i},\textbf{j},\textbf{k}) and therefore, 345 introducing depth-dependent mixing coefficients will require 3D arrays. 346 In the 1D option, a hyperbolic variation of the lateral mixing coefficient is introduced in which 347 the surface value is \np{rn\_aht0} (\np{rn\_ahm0}), the bottom value is 1/4 of the surface value, 348 and the transition takes place around z=300~m with a width of 300~m 349 (\ie both the depth and the width of the inflection point are set to 300~m). 350 This profile is hard coded in file \textit{traldf\_c1d.h90}, but can be easily modified by users. 351 352 \subsubsection{Horizontally varying mixing coefficients (\protect\key{traldf\_c2d} and \protect\key{dynldf\_c2d})} 353 By default the horizontal variation of the eddy coefficient depends on the local mesh size and 318 The specification of the space variation of the coefficient is made in modules \mdl{ldftra} and \mdl{ldfdyn}. 319 The way the mixing coefficients are set in the reference version can be described as follows: 320 321 %% ================================================================================================= 322 \subsection[Mixing coefficients read from file (\forcode{=-20, -30})]{ Mixing coefficients read from file (\protect\np[=-20, -30]{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np[=-20, -30]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})} 323 324 Mixing coefficients can be read from file if a particular geographical variation is needed. For example, in the ORCA2 global ocean model, 325 the laplacian viscosity operator uses $A^l$~= 4.10$^4$ m$^2$/s poleward of 20$^{\circ}$ north and south and 326 decreases linearly to $A^l$~= 2.10$^3$ m$^2$/s at the equator \citep{madec.delecluse.ea_JPO96, delecluse.madec_icol99}. 327 Similar modified horizontal variations can be found with the Antarctic or Arctic sub-domain options of ORCA2 and ORCA05. 328 The provided fields can either be 2d (\np[=-20]{nn_aht_ijk_t}{nn\_aht\_ijk\_t}, \np[=-20]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t}) or 3d (\np[=-30]{nn_aht_ijk_t}{nn\_aht\_ijk\_t}, \np[=-30]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t}). They must be given at U, V points for tracers and T, F points for momentum (see \autoref{tab:LDF_files}). 329 330 \begin{table}[htb] 331 \centering 332 \begin{tabular}{|l|l|l|l|} 333 \hline 334 Namelist parameter & Input filename & dimensions & variable names \\ \hline 335 \np[=-20]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t} & \forcode{eddy_viscosity_2D.nc } & $(i,j)$ & \forcode{ahmt_2d, ahmf_2d} \\ \hline 336 \np[=-20]{nn_aht_ijk_t}{nn\_aht\_ijk\_t} & \forcode{eddy_diffusivity_2D.nc } & $(i,j)$ & \forcode{ahtu_2d, ahtv_2d} \\ \hline 337 \np[=-30]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t} & \forcode{eddy_viscosity_3D.nc } & $(i,j,k)$ & \forcode{ahmt_3d, ahmf_3d} \\ \hline 338 \np[=-30]{nn_aht_ijk_t}{nn\_aht\_ijk\_t} & \forcode{eddy_diffusivity_3D.nc } & $(i,j,k)$ & \forcode{ahtu_3d, ahtv_3d} \\ \hline 339 \end{tabular} 340 \caption{Description of expected input files if mixing coefficients are read from NetCDF files} 341 \label{tab:LDF_files} 342 \end{table} 343 344 %% ================================================================================================= 345 \subsection[Constant mixing coefficients (\forcode{=0})]{ Constant mixing coefficients (\protect\np[=0]{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np[=0]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})} 346 347 If constant, mixing coefficients are set thanks to a velocity and a length scales ($U_{scl}$, $L_{scl}$) such that: 348 349 \begin{equation} 350 \label{eq:LDF_constantah} 351 A_o^l = \left\{ 352 \begin{aligned} 353 & \frac{1}{2} U_{scl} L_{scl} & \text{for laplacian operator } \\ 354 & \frac{1}{12} U_{scl} L_{scl}^3 & \text{for bilaplacian operator } 355 \end{aligned} 356 \right. 357 \end{equation} 358 359 $U_{scl}$ and $L_{scl}$ are given by the namelist parameters \np{rn_Ud}{rn\_Ud}, \np{rn_Uv}{rn\_Uv}, \np{rn_Ld}{rn\_Ld} and \np{rn_Lv}{rn\_Lv}. 360 361 %% ================================================================================================= 362 \subsection[Vertically varying mixing coefficients (\forcode{=10})]{Vertically varying mixing coefficients (\protect\np[=10]{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np[=10]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})} 363 364 In the vertically varying case, a hyperbolic variation of the lateral mixing coefficient is introduced in which 365 the surface value is given by \autoref{eq:LDF_constantah}, the bottom value is 1/4 of the surface value, 366 and the transition takes place around z=500~m with a width of 200~m. 367 This profile is hard coded in module \mdl{ldfc1d\_c2d}, but can be easily modified by users. 368 369 %% ================================================================================================= 370 \subsection[Mesh size dependent mixing coefficients (\forcode{=20})]{Mesh size dependent mixing coefficients (\protect\np[=20]{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np[=20]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})} 371 372 In that case, the horizontal variation of the eddy coefficient depends on the local mesh size and 354 373 the type of operator used: 355 374 \begin{equation} 356 \label{eq: title}375 \label{eq:LDF_title} 357 376 A_l = \left\{ 358 377 \begin{aligned} 359 & \frac{ \max(e_1,e_2)}{e_{max}} A_o^l& \text{for laplacian operator } \\360 & \frac{ \max(e_1,e_2)^{3}}{e_{max}^{3}} A_o^l& \text{for bilaplacian operator }378 & \frac{1}{2} U_{scl} \max(e_1,e_2) & \text{for laplacian operator } \\ 379 & \frac{1}{12} U_{scl} \max(e_1,e_2)^{3} & \text{for bilaplacian operator } 361 380 \end{aligned} 362 381 \right. 363 382 \end{equation} 364 where $e_{max}$ is the maximum of $e_1$ and $e_2$ taken over the whole masked ocean domain, 365 and $A_o^l$ is the \np{rn\_ahm0} (momentum) or \np{rn\_aht0} (tracer) namelist parameter. 383 where $U_{scl}$ is a user defined velocity scale (\np{rn_Ud}{rn\_Ud}, \np{rn_Uv}{rn\_Uv}). 366 384 This variation is intended to reflect the lesser need for subgrid scale eddy mixing where 367 385 the grid size is smaller in the domain. 368 It was introduced in the context of the DYNAMO modelling project \citep{ Willebrand_al_PO01}.369 Note that such a grid scale dependance of mixing coefficients significantly increase the range of stability of370 model configurations presenting large changes in grid pacing such as global ocean models.386 It was introduced in the context of the DYNAMO modelling project \citep{willebrand.barnier.ea_PO01}. 387 Note that such a grid scale dependance of mixing coefficients significantly increases the range of stability of 388 model configurations presenting large changes in grid spacing such as global ocean models. 371 389 Indeed, in such a case, a constant mixing coefficient can lead to a blow up of the model due to 372 large coefficient compare to the smallest grid size (see \autoref{sec: STP_forward_imp}),390 large coefficient compare to the smallest grid size (see \autoref{sec:TD_forward_imp}), 373 391 especially when using a bilaplacian operator. 374 392 375 Other formulations can be introduced by the user for a given configuration. 376 For example, in the ORCA2 global ocean model (see Configurations), 377 the laplacian viscosity operator uses \np{rn\_ahm0}~= 4.10$^4$ m$^2$/s poleward of 20$^{\circ}$ north and south and 378 decreases linearly to \np{rn\_aht0}~= 2.10$^3$ m$^2$/s at the equator \citep{Madec_al_JPO96, Delecluse_Madec_Bk00}. 379 This modification can be found in routine \rou{ldf\_dyn\_c2d\_orca} defined in \mdl{ldfdyn\_c2d}. 380 Similar modified horizontal variations can be found with the Antarctic or Arctic sub-domain options of 381 ORCA2 and ORCA05 (see \&namcfg namelist). 382 383 \subsubsection{Space varying mixing coefficients (\protect\key{traldf\_c3d} and \key{dynldf\_c3d})} 384 385 The 3D space variation of the mixing coefficient is simply the combination of the 1D and 2D cases, 386 \ie a hyperbolic tangent variation with depth associated with a grid size dependence of 387 the magnitude of the coefficient. 388 389 \subsubsection{Space and time varying mixing coefficients} 390 391 There is no default specification of space and time varying mixing coefficient. 392 The only case available is specific to the ORCA2 and ORCA05 global ocean configurations. 393 It provides only a tracer mixing coefficient for eddy induced velocity (ORCA2) or both iso-neutral and 394 eddy induced velocity (ORCA05) that depends on the local growth rate of baroclinic instability. 395 This specification is actually used when an ORCA key and both \key{traldf\_eiv} and \key{traldf\_c2d} are defined. 393 \colorbox{yellow}{CASE \np{nn_aht_ijk_t}{nn\_aht\_ijk\_t} = 21 to be added} 394 395 %% ================================================================================================= 396 \subsection[Mesh size and depth dependent mixing coefficients (\forcode{=30})]{Mesh size and depth dependent mixing coefficients (\protect\np[=30]{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np[=30]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})} 397 398 The 3D space variation of the mixing coefficient is simply the combination of the 1D and 2D cases above, 399 \ie\ a hyperbolic tangent variation with depth associated with a grid size dependence of 400 the magnitude of the coefficient. 401 402 %% ================================================================================================= 403 \subsection[Velocity dependent mixing coefficients (\forcode{=31})]{Flow dependent mixing coefficients (\protect\np[=31]{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np[=31]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})} 404 In that case, the eddy coefficient is proportional to the local velocity magnitude so that the Reynolds number $Re = \lvert U \rvert e / A_l$ is constant (and here hardcoded to $12$): 405 \colorbox{yellow}{JC comment: The Reynolds is effectively set to 12 in the code for both operators but shouldn't it be 2 for Laplacian ?} 406 407 \begin{equation} 408 \label{eq:LDF_flowah} 409 A_l = \left\{ 410 \begin{aligned} 411 & \frac{1}{12} \lvert U \rvert e & \text{for laplacian operator } \\ 412 & \frac{1}{12} \lvert U \rvert e^3 & \text{for bilaplacian operator } 413 \end{aligned} 414 \right. 415 \end{equation} 416 417 %% ================================================================================================= 418 \subsection[Deformation rate dependent viscosities (\forcode{nn_ahm_ijk_t=32})]{Deformation rate dependent viscosities (\protect\np[=32]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})} 419 420 This option refers to the \citep{smagorinsky_MW63} scheme which is here implemented for momentum only. Smagorinsky chose as a 421 characteristic time scale $T_{smag}$ the deformation rate and for the lengthscale $L_{smag}$ the maximum wavenumber possible on the horizontal grid, e.g.: 422 423 \begin{equation} 424 \label{eq:LDF_smag1} 425 \begin{split} 426 T_{smag}^{-1} & = \sqrt{\left( \partial_x u - \partial_y v\right)^2 + \left( \partial_y u + \partial_x v\right)^2 } \\ 427 L_{smag} & = \frac{1}{\pi}\frac{e_1 e_2}{e_1 + e_2} 428 \end{split} 429 \end{equation} 430 431 Introducing a user defined constant $C$ (given in the namelist as \np{rn_csmc}{rn\_csmc}), one can deduce the mixing coefficients as follows: 432 433 \begin{equation} 434 \label{eq:LDF_smag2} 435 A_{smag} = \left\{ 436 \begin{aligned} 437 & C^2 T_{smag}^{-1} L_{smag}^2 & \text{for laplacian operator } \\ 438 & \frac{C^2}{8} T_{smag}^{-1} L_{smag}^4 & \text{for bilaplacian operator } 439 \end{aligned} 440 \right. 441 \end{equation} 442 443 For stability reasons, upper and lower limits are applied on the resulting coefficient (see \autoref{sec:TD_forward_imp}) so that: 444 \begin{equation} 445 \label{eq:LDF_smag3} 446 \begin{aligned} 447 & C_{min} \frac{1}{2} \lvert U \rvert e < A_{smag} < C_{max} \frac{e^2}{ 8\rdt} & \text{for laplacian operator } \\ 448 & C_{min} \frac{1}{12} \lvert U \rvert e^3 < A_{smag} < C_{max} \frac{e^4}{64 \rdt} & \text{for bilaplacian operator } 449 \end{aligned} 450 \end{equation} 451 452 where $C_{min}$ and $C_{max}$ are adimensional namelist parameters given by \np{rn_minfac}{rn\_minfac} and \np{rn_maxfac}{rn\_maxfac} respectively. 453 454 %% ================================================================================================= 455 \subsection{About space and time varying mixing coefficients} 396 456 397 457 The following points are relevant when the eddy coefficient varies spatially: 398 458 399 459 (1) the momentum diffusion operator acting along model level surfaces is written in terms of curl and 400 divergent components of the horizontal current (see \autoref{subsec: PE_ldf}).460 divergent components of the horizontal current (see \autoref{subsec:MB_ldf}). 401 461 Although the eddy coefficient could be set to different values in these two terms, 402 this option is not currently available. 462 this option is not currently available. 403 463 404 464 (2) with an horizontally varying viscosity, the quadratic integral constraints on enstrophy and on the square of 405 465 the horizontal divergence for operators acting along model-surfaces are no longer satisfied 406 (\autoref{sec:dynldf_properties}). 407 408 (3) for isopycnal diffusion on momentum or tracers, an additional purely horizontal background diffusion with 409 uniform coefficient can be added by setting a non zero value of \np{rn\_ahmb0} or \np{rn\_ahtb0}, 410 a background horizontal eddy viscosity or diffusivity coefficient 411 (namelist parameters whose default values are $0$). 412 However, the technique used to compute the isopycnal slopes is intended to get rid of such a background diffusion, 413 since it introduces spurious diapycnal diffusion (see \autoref{sec:LDF_slp}). 414 415 (4) when an eddy induced advection term is used (\key{traldf\_eiv}), 416 $A^{eiv}$, the eddy induced coefficient has to be defined. 417 Its space variations are controlled by the same CPP variable as for the eddy diffusivity coefficient 418 (\ie \key{traldf\_cNd}). 419 420 (5) the eddy coefficient associated with a biharmonic operator must be set to a \emph{negative} value. 421 422 (6) it is possible to use both the laplacian and biharmonic operators concurrently. 423 424 (7) it is possible to run without explicit lateral diffusion on momentum 425 (\np{ln\_dynldf\_lap}\forcode{ = .?.}\np{ln\_dynldf\_bilap}\forcode{ = .false.}). 426 This is recommended when using the UBS advection scheme on momentum (\np{ln\_dynadv\_ubs}\forcode{ = .true.}, 427 see \autoref{subsec:DYN_adv_ubs}) and can be useful for testing purposes. 428 429 % ================================================================ 430 % Eddy Induced Mixing 431 % ================================================================ 432 \section{Eddy induced velocity (\protect\mdl{traadv\_eiv}, \protect\mdl{ldfeiv})} 466 (\autoref{sec:INVARIANTS_dynldf_properties}). 467 468 %% ================================================================================================= 469 \section[Eddy induced velocity (\forcode{ln_ldfeiv})]{Eddy induced velocity (\protect\np{ln_ldfeiv}{ln\_ldfeiv})} 470 433 471 \label{sec:LDF_eiv} 434 472 473 \begin{listing} 474 \nlst{namtra_eiv} 475 \caption{\forcode{&namtra_eiv}} 476 \label{lst:namtra_eiv} 477 \end{listing} 478 435 479 %%gm from Triad appendix : to be incorporated.... 436 \ gmcomment{480 \cmtgm{ 437 481 Values of iso-neutral diffusivity and GM coefficient are set as described in \autoref{sec:LDF_coef}. 438 482 If none of the keys \key{traldf\_cNd}, N=1,2,3 is set (the default), spatially constant iso-neutral $A_l$ and 439 GM diffusivity $A_e$ are directly set by \np{rn \_aeih\_0} and \np{rn\_aeiv\_0}.483 GM diffusivity $A_e$ are directly set by \np{rn_aeih_0}{rn\_aeih\_0} and \np{rn_aeiv_0}{rn\_aeiv\_0}. 440 484 If 2D-varying coefficients are set with \key{traldf\_c2d} then $A_l$ is reduced in proportion with horizontal 441 485 scale factor according to \autoref{eq:title} … … 450 494 In this case, $A_e$ at low latitudes $|\theta|<20^{\circ}$ is further reduced by a factor $|f/f_{20}|$, 451 495 where $f_{20}$ is the value of $f$ at $20^{\circ}$~N 452 } (\mdl{ldfeiv}) and \np{rn \_aeiv\_0} is ignored unless it is zero.496 } (\mdl{ldfeiv}) and \np{rn_aeiv_0}{rn\_aeiv\_0} is ignored unless it is zero. 453 497 } 454 498 455 When Gent and McWilliams [1990] diffusion is used (\key{traldf\_eiv} defined),499 When \citet{gent.mcwilliams_JPO90} diffusion is used (\np[=.true.]{ln_ldfeiv}{ln\_ldfeiv}), 456 500 an eddy induced tracer advection term is added, 457 501 the formulation of which depends on the slopes of iso-neutral surfaces. 458 502 Contrary to the case of iso-neutral mixing, the slopes used here are referenced to the geopotential surfaces, 459 \ie \autoref{eq:ldfslp_geo} is used in $z$-coordinates, 460 and the sum \autoref{eq:ldfslp_geo} + \autoref{eq:ldfslp_iso} in $s$-coordinates. 461 The eddy induced velocity is given by: 462 \begin{equation} 463 \label{eq:ldfeiv} 503 \ie\ \autoref{eq:LDF_slp_geo} is used in $z$-coordinates, 504 and the sum \autoref{eq:LDF_slp_geo} + \autoref{eq:LDF_slp_iso} in $s$-coordinates. 505 506 If isopycnal mixing is used in the standard way, \ie\ \np[=.false.]{ln_traldf_triad}{ln\_traldf\_triad}, the eddy induced velocity is given by: 507 \begin{equation} 508 \label{eq:LDF_eiv} 464 509 \begin{split} 465 510 u^* & = \frac{1}{e_{2u}e_{3u}}\; \delta_k \left[e_{2u} \, A_{uw}^{eiv} \; \overline{r_{1w}}^{\,i+1/2} \right]\\ … … 468 513 \end{split} 469 514 \end{equation} 470 where $A^{eiv}$ is the eddy induced velocity coefficient whose value is set through \np{rn\_aeiv}, 471 a \textit{nam\_traldf} namelist parameter. 472 The three components of the eddy induced velocity are computed and 473 add to the eulerian velocity in \mdl{traadv\_eiv}. 515 where $A^{eiv}$ is the eddy induced velocity coefficient whose value is set through \np{nn_aei_ijk_t}{nn\_aei\_ijk\_t} \nam{tra_eiv}{tra\_eiv} namelist parameter. 516 The three components of the eddy induced velocity are computed in \rou{ldf\_eiv\_trp} and 517 added to the eulerian velocity in \rou{tra\_adv} where tracer advection is performed. 474 518 This has been preferred to a separate computation of the advective trends associated with the eiv velocity, 475 519 since it allows us to take advantage of all the advection schemes offered for the tracers 476 520 (see \autoref{sec:TRA_adv}) and not just the $2^{nd}$ order advection scheme as in 477 previous releases of OPA \citep{ Madec1998}.521 previous releases of OPA \citep{madec.delecluse.ea_NPM98}. 478 522 This is particularly useful for passive tracers where \emph{positivity} of the advection scheme is of 479 paramount importance. 523 paramount importance. 480 524 481 525 At the surface, lateral and bottom boundaries, the eddy induced velocity, 482 and thus the advective eddy fluxes of heat and salt, are set to zero. 483 484 \biblio 485 486 \pindex 526 and thus the advective eddy fluxes of heat and salt, are set to zero. 527 The value of the eddy induced mixing coefficient and its space variation is controlled in a similar way as for lateral mixing coefficient described in the preceding subsection (\np{nn_aei_ijk_t}{nn\_aei\_ijk\_t}, \np{rn_Ue}{rn\_Ue}, \np{rn_Le}{rn\_Le} namelist parameters). 528 \colorbox{yellow}{CASE \np{nn_aei_ijk_t}{nn\_aei\_ijk\_t} = 21 to be added} 529 530 In case of setting \np[=.true.]{ln_traldf_triad}{ln\_traldf\_triad}, a skew form of the eddy induced advective fluxes is used, which is described in \autoref{apdx:TRIADS}. 531 532 %% ================================================================================================= 533 \section[Mixed layer eddies (\forcode{ln_mle})]{Mixed layer eddies (\protect\np{ln_mle}{ln\_mle})} 534 \label{sec:LDF_mle} 535 536 \begin{listing} 537 \nlst{namtra_mle} 538 \caption{\forcode{&namtra_mle}} 539 \label{lst:namtra_mle} 540 \end{listing} 541 542 If \np[=.true.]{ln_mle}{ln\_mle} in \nam{tra_mle}{tra\_mle} namelist, a parameterization of the mixing due to unresolved mixed layer instabilities is activated (\citet{foxkemper.ferrari_JPO08}). Additional transport is computed in \rou{ldf\_mle\_trp} and added to the eulerian transport in \rou{tra\_adv} as done for eddy induced advection. 543 544 \colorbox{yellow}{TBC} 545 546 \subinc{\input{../../global/epilogue}} 487 547 488 548 \end{document} -
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_OBS.tex
r10442 r11831 2 2 3 3 \begin{document} 4 % ================================================================ 5 % Chapter observation operator (OBS) 6 % ================================================================ 4 7 5 \chapter{Observation and Model Comparison (OBS)} 8 6 \label{chap:OBS} 9 7 10 Authors: D. Lea, M. Martin, K. Mogensen, A. Vidard, A. Weaver, A. Ryan, ... % do we keep that ? 11 12 \minitoc 13 14 \newpage 15 16 The observation and model comparison code (OBS) reads in observation files 17 (profile temperature and salinity, sea surface temperature, sea level anomaly, sea ice concentration, and velocity) and calculates an interpolated model equivalent value at the observation location and nearest model timestep. 8 %\subsubsection*{Changes record} 9 %\begin{tabular}{l||l|m{0.65\linewidth}} 10 % Release & Author & Modifications \\ 11 % {\em 4.0} & {\em D. J. Lea} & {\em \NEMO\ 4.0 updates} \\ 12 % {\em 3.6} & {\em M. Martin, A. Ryan} & {\em Add averaging operator, standalone obs oper} \\ 13 % {\em 3.4} & {\em D. J. Lea, M. Martin, ...} & {\em Initial version} \\ 14 % {\em --\texttt{"}--} & {\em ... K. Mogensen, A. Vidard, A. Weaver} & {\em ---\texttt{"}---} \\ 15 %\end{tabular} 16 17 \thispagestyle{plain} 18 19 \chaptertoc 20 21 \paragraph{Changes record} ~\\ 22 23 {\footnotesize 24 \begin{tabularx}{\textwidth}{l||X|X} 25 Release & Author(s) & Modifications \\ 26 \hline 27 {\em 4.0} & {\em ...} & {\em ...} \\ 28 {\em 3.6} & {\em ...} & {\em ...} \\ 29 {\em 3.4} & {\em ...} & {\em ...} \\ 30 {\em <=3.4} & {\em ...} & {\em ...} 31 \end{tabularx} 32 } 33 34 \clearpage 35 36 The observation and model comparison code, the observation operator (OBS), reads in observation files 37 (profile temperature and salinity, sea surface temperature, sea level anomaly, sea ice concentration, and velocity) and calculates an interpolated model equivalent value at the observation location and nearest model time step. 18 38 The resulting data are saved in a ``feedback'' file (or files). 19 39 The code was originally developed for use with the NEMOVAR data assimilation code, 20 40 but can be used for validation or verification of the model or with any other data assimilation system. 21 41 22 The OBS code is called from \mdl{nemogcm} for model initialisation and to calculate the model equivalent values for observations on the 0th time step.23 The code is then called again after each time step from \mdl{step}.24 The code is only activated if the namelist logical \np{ln\_diaobs} is set to true.42 The OBS code is called from \mdl{nemogcm} for model initialisation and to calculate the model equivalent values for observations on the 0th time step. 43 The code is then called again after each time step from \mdl{step}. 44 The code is only activated if the \nam{obs}{obs} namelist logical \np{ln_diaobs}{ln\_diaobs} is set to true. 25 45 26 46 For all data types a 2D horizontal interpolator or averager is needed to … … 28 48 For {\em in situ} profiles, a 1D vertical interpolator is needed in addition to 29 49 provide model fields at the observation depths. 30 This now works in a generalised vertical coordinate system. 31 32 Some profile observation types (\eg tropical moored buoys) are made available as daily averaged quantities.50 This now works in a generalised vertical coordinate system. 51 52 Some profile observation types (\eg\ tropical moored buoys) are made available as daily averaged quantities. 33 53 The observation operator code can be set-up to calculate the equivalent daily average model temperature fields using 34 the \np{nn \_profdavtypes} namelist array.54 the \np{nn_profdavtypes}{nn\_profdavtypes} namelist array. 35 55 Some SST observations are equivalent to a night-time average value and 36 56 the observation operator code can calculate equivalent night-time average model SST fields by 37 setting the namelist value \np{ln \_sstnight} to true.38 Otherwise the model value from the nearest timestep to the observation time is used.39 40 The code is controlled by the namelist \ textit{namobs}.57 setting the namelist value \np{ln_sstnight}{ln\_sstnight} to true. 58 Otherwise (by default) the model value from the nearest time step to the observation time is used. 59 60 The code is controlled by the namelist \nam{obs}{obs}. 41 61 See the following sections for more details on setting up the namelist. 42 62 43 \autoref{sec:OBS_example} introduces a test example of the observation operator codeincluding63 In \autoref{sec:OBS_example} a test example of the observation operator code is introduced, including 44 64 where to obtain data and how to setup the namelist. 45 \autoref{sec:OBS_details} introduces some more technical details of the different observation types used and 46 also show sa more complete namelist.47 \autoref{sec:OBS_theory} introduces some of the theoretical aspects of the observation operatorincluding65 In \autoref{sec:OBS_details} some more technical details of the different observation types used are introduced, and we 66 also show a more complete namelist. 67 In \autoref{sec:OBS_theory} some of the theoretical aspects of the observation operator are described including 48 68 interpolation methods and running on multiple processors. 49 \autoref{sec:OBS_ooo} describes the offline observation operator code. 50 \autoref{sec:OBS_obsutils} introduces some utilities to help working with the files produced by the OBS code. 51 52 % ================================================================ 53 % Example 54 % ================================================================ 69 In \autoref{sec:OBS_sao} the standalone observation operator code is described. 70 In \autoref{sec:OBS_obsutils} we describe some utilities to help work with the files produced by the OBS code. 71 72 %% ================================================================================================= 55 73 \section{Running the observation operator code example} 56 74 \label{sec:OBS_example} 57 75 58 This section describes an example of running the observation operator codeusing59 profile data which can be freely downloaded.60 It shows how to adapt an existing run and build of NEMO to run the observation operator.76 In this section an example of running the observation operator code is described using 77 profile observation data which can be freely downloaded. 78 It shows how to adapt an existing run and build of \NEMO\ to run the observation operator. Note also the observation operator and the assimilation increments code are run in the ORCA2\_ICE\_OBS SETTE test. 61 79 62 80 \begin{enumerate} 63 \item Compile NEMO.81 \item Compile \NEMO. 64 82 65 83 \item Download some EN4 data from \href{http://www.metoffice.gov.uk/hadobs}{www.metoffice.gov.uk/hadobs}. 66 84 Choose observations which are valid for the period of your test run because 67 the observation operator compares the model and observations for a matching date and time. 68 69 \item Compile the OBSTOOLS code using:85 the observation operator compares the model and observations for a matching date and time. 86 87 \item Compile the OBSTOOLS code in the \path{tools} directory using: 70 88 \begin{cmds} 71 ./maketools -n OBSTOOLS -m [ARCH] .89 ./maketools -n OBSTOOLS -m [ARCH] 72 90 \end{cmds} 73 91 74 \item Convert the EN4 data into feedback format: 92 replacing \texttt{[ARCH]} with the build architecture file for your machine. Note the tools are checked out from a separate location of the repository (under \path{/utils/tools}). 93 94 \item Convert the EN4 data into feedback format: 75 95 \begin{cmds} 76 96 enact2fb.exe profiles_01.nc EN.4.1.1.f.profiles.g10.YYYYMM.nc 77 97 \end{cmds} 78 98 79 \item Include the following in the NEMOnamelist to run the observation operator on this data:99 \item Include the following in the \NEMO\ namelist to run the observation operator on this data: 80 100 \end{enumerate} 81 101 82 Options are defined through the \n gn{namobs} namelist variables.83 The options \np{ln \_t3d} and \np{ln\_s3d} switch on the temperature and salinity profile observation operator code.84 The filename or array of filenames are specified using the \np{cn \_profbfiles} variable.102 Options are defined through the \nam{obs}{obs} namelist variables. 103 The options \np{ln_t3d}{ln\_t3d} and \np{ln_s3d}{ln\_s3d} switch on the temperature and salinity profile observation operator code. 104 The filename or array of filenames are specified using the \np{cn_profbfiles}{cn\_profbfiles} variable. 85 105 The model grid points for a particular observation latitude and longitude are found using 86 106 the grid searching part of the code. 87 107 This can be expensive, particularly for large numbers of observations, 88 setting \np{ln \_grid\_search\_lookup} allows the use of a lookup table which89 is saved into an ``xypos``file (or files).108 setting \np{ln_grid_search_lookup}{ln\_grid\_search\_lookup} allows the use of a lookup table which 109 is saved into an \np{cn_gridsearch}{cn\_gridsearch} file (or files). 90 110 This will need to be generated the first time if it does not exist in the run directory. 91 111 However, once produced it will significantly speed up future grid searches. 92 Setting \np{ln \_grid\_global} means that the code distributes the observations evenly between processors.112 Setting \np{ln_grid_global}{ln\_grid\_global} means that the code distributes the observations evenly between processors. 93 113 Alternatively each processor will work with observations located within the model subdomain 94 (see section~\autoref{subsec:OBS_parallel}).114 (see \autoref{subsec:OBS_parallel}). 95 115 96 116 A number of utilities are now provided to plot the feedback files, convert and recombine the files. 97 These are explained in more detail in section~\autoref{sec:OBS_obsutils}. 98 Utilites to convert other input data formats into the feedback format are also described in 99 section~\autoref{sec:OBS_obsutils}. 100 117 These are explained in more detail in \autoref{sec:OBS_obsutils}. 118 Utilities to convert other input data formats into the feedback format are also described in 119 \autoref{sec:OBS_obsutils}. 120 121 %% ================================================================================================= 101 122 \section{Technical details (feedback type observation file headers)} 102 123 \label{sec:OBS_details} 103 124 104 Here we show a more complete example namelist \n gn{namobs} and also show the NetCDF headers of125 Here we show a more complete example namelist \nam{obs}{obs} and also show the NetCDF headers of 105 126 the observation files that may be used with the observation operator. 106 127 107 %------------------------------------------namobs-------------------------------------------------------- 108 109 \nlst{namobs} 110 %------------------------------------------------------------------------------------------------------------- 111 112 The observation operator code uses the "feedback" observation file format for all data types. 128 \begin{listing} 129 \nlst{namobs} 130 \caption{\forcode{&namobs}} 131 \label{lst:namobs} 132 \end{listing} 133 134 The observation operator code uses the feedback observation file format for all data types. 113 135 All the observation files must be in NetCDF format. 114 136 Some example headers (produced using \mbox{\textit{ncdump~-h}}) for profile data, sea level anomaly and 115 137 sea surface temperature are in the following subsections. 116 138 117 \subsection{Profile feedback} 139 %% ================================================================================================= 140 \subsection{Profile feedback file} 118 141 119 142 \begin{clines} … … 271 294 \end{clines} 272 295 273 \subsection{Sea level anomaly feedback} 296 %% ================================================================================================= 297 \subsection{Sea level anomaly feedback file} 274 298 275 299 \begin{clines} … … 395 419 \end{clines} 396 420 397 T he mean dynamic topography (MDT) must be provided in a separate file defined on421 To use Sea Level Anomaly (SLA) data the mean dynamic topography (MDT) must be provided in a separate file defined on 398 422 the model grid called \ifile{slaReferenceLevel}. 399 423 The MDT is required in order to produce the model equivalent sea level anomaly from the model sea surface height. … … 417 441 \end{clines} 418 442 419 \subsection{Sea surface temperature feedback} 443 %% ================================================================================================= 444 \subsection{Sea surface temperature feedback file} 420 445 421 446 \begin{clines} … … 534 559 \end{clines} 535 560 561 %% ================================================================================================= 536 562 \section{Theoretical details} 537 563 \label{sec:OBS_theory} 538 564 565 %% ================================================================================================= 539 566 \subsection{Horizontal interpolation and averaging methods} 540 567 … … 542 569 the model equivalent of the observation is calculated by interpolating from 543 570 the four surrounding grid points to the observation location. 544 Some satellite observations (\eg microwave satellite SST data, or satellite SSS data) have a footprint which571 Some satellite observations (\eg\ microwave satellite SST data, or satellite SSS data) have a footprint which 545 572 is similar in size or larger than the model grid size (particularly when the grid size is small). 546 573 In those cases the model counterpart should be calculated by averaging the model grid points over 547 574 the same size as the footprint. 548 NEMOtherefore has the capability to specify either an interpolation or an averaging549 (for surface observation types only). 550 551 The main namelist option associated with the interpolation/averaging is \np{nn \_2dint}.575 \NEMO\ therefore has the capability to specify either an interpolation or an averaging 576 (for surface observation types only). 577 578 The main namelist option associated with the interpolation/averaging is \np{nn_2dint}{nn\_2dint}. 552 579 This default option can be set to values from 0 to 6. 553 580 Values between 0 to 4 are associated with interpolation while values 5 or 6 are associated with averaging. 554 581 \begin{itemize} 555 \item \np {nn\_2dint}\forcode{ = 0}: Distance-weighted interpolation556 \item \np {nn\_2dint}\forcode{ = 1}: Distance-weighted interpolation (small angle)557 \item \np {nn\_2dint}\forcode{ = 2}: Bilinear interpolation (geographical grid)558 \item \np {nn\_2dint}\forcode{ = 3}: Bilinear remapping interpolation (general grid)559 \item \np {nn\_2dint}\forcode{ = 4}: Polynomial interpolation560 \item \np {nn\_2dint}\forcode{ = 5}: Radial footprint averaging with diameter specified in the namelist as561 \ np{rn\_???\_avglamscl} in degrees or metres (set using \np{ln\_???\_fp\_indegs})562 \item \np {nn\_2dint}\forcode{ = 6}: Rectangular footprint averaging with E/W and N/S size specified in563 the namelist as \ np{rn\_???\_avglamscl} and \np{rn\_???\_avgphiscl} in degrees or metres564 (set using \ np{ln\_???\_fp\_indegs})582 \item \np[=0]{nn_2dint}{nn\_2dint}: Distance-weighted interpolation 583 \item \np[=1]{nn_2dint}{nn\_2dint}: Distance-weighted interpolation (small angle) 584 \item \np[=2]{nn_2dint}{nn\_2dint}: Bilinear interpolation (geographical grid) 585 \item \np[=3]{nn_2dint}{nn\_2dint}: Bilinear remapping interpolation (general grid) 586 \item \np[=4]{nn_2dint}{nn\_2dint}: Polynomial interpolation 587 \item \np[=5]{nn_2dint}{nn\_2dint}: Radial footprint averaging with diameter specified in the namelist as 588 \texttt{rn\_[var]\_avglamscl} in degrees or metres (set using \texttt{ln\_[var]\_fp\_indegs}) 589 \item \np[=6]{nn_2dint}{nn\_2dint}: Rectangular footprint averaging with E/W and N/S size specified in 590 the namelist as \texttt{rn\_[var]\_avglamscl} and \texttt{rn\_[var]\_avgphiscl} in degrees or metres 591 (set using \texttt{ln\_[var]\_fp\_indegs}) 565 592 \end{itemize} 566 The ??? in the last two options indicate these options should be specified for each observation typefor593 Replace \texttt{[var]} in the last two options with the observation type (sla, sst, sss or sic) for 567 594 which the averaging is to be performed (see namelist example above). 568 The \np{nn\_2dint} default option can be overridden for surface observation types using 569 namelist values \np{nn\_2dint\_???} where ??? is one of sla,sst,sss,sic. 570 571 Below is some more detail on the various options for interpolation and averaging available in NEMO. 572 595 The \np{nn_2dint}{nn\_2dint} default option can be overridden for surface observation types using 596 namelist values \texttt{nn\_2dint\_[var]} where \texttt{[var]} is the observation type. 597 598 Below is some more detail on the various options for interpolation and averaging available in \NEMO. 599 600 %% ================================================================================================= 573 601 \subsubsection{Horizontal interpolation} 574 602 575 Consider an observation point ${\rm P}$ with with longitude and latitude $({\lambda_{}}_{\rm P}, \phi_{\rm P})$ and 576 the four nearest neighbouring model grid points ${\rm A}$, ${\rm B}$, ${\rm C}$ and ${\rm D}$ with 577 longitude and latitude ($\lambda_{\rm A}$, $\phi_{\rm A}$),($\lambda_{\rm B}$, $\phi_{\rm B}$) etc. 578 All horizontal interpolation methods implemented in NEMO estimate the value of a model variable $x$ at point $P$ as 579 a weighted linear combination of the values of the model variables at the grid points ${\rm A}$, ${\rm B}$ etc.: 603 Consider an observation point ${\mathrm P}$ with longitude and latitude (${\lambda_{}}_{\mathrm P}$, $\phi_{\mathrm P}$) and 604 the four nearest neighbouring model grid points ${\mathrm A}$, ${\mathrm B}$, ${\mathrm C}$ and ${\mathrm D}$ with 605 longitude and latitude ($\lambda_{\mathrm A}$, $\phi_{\mathrm A}$),($\lambda_{\mathrm B}$, $\phi_{\mathrm B}$) etc. 606 All horizontal interpolation methods implemented in \NEMO\ estimate the value of a model variable $x$ at point $P$ as 607 a weighted linear combination of the values of the model variables at the grid points ${\mathrm A}$, ${\mathrm B}$ etc.: 608 580 609 \begin{align*} 581 {x_{}}_{\ rm P} & \hspace{-2mm} = \hspace{-2mm} &582 \frac{1}{w} \left( {w_{}}_{\rm A} {x_{}}_{\rm A} +583 {w_{}}_{\rm B} {x_{}}_{\rm B} +584 {w_{}}_{\rm C} {x_{}}_{\rm C} +585 {w_{}}_{\rm D} {x_{}}_{\rm D} \right)610 {x_{}}_{\mathrm P} = 611 \frac{1}{w} \left( {w_{}}_{\mathrm A} {x_{}}_{\mathrm A} + 612 {w_{}}_{\mathrm B} {x_{}}_{\mathrm B} + 613 {w_{}}_{\mathrm C} {x_{}}_{\mathrm C} + 614 {w_{}}_{\mathrm D} {x_{}}_{\mathrm D} \right) 586 615 \end{align*} 587 where ${w_{}}_{\rm A}$, ${w_{}}_{\rm B}$ etc. are the respective weights for the model field at 588 points ${\rm A}$, ${\rm B}$ etc., and $w = {w_{}}_{\rm A} + {w_{}}_{\rm B} + {w_{}}_{\rm C} + {w_{}}_{\rm D}$. 616 617 where ${w_{}}_{\mathrm A}$, ${w_{}}_{\mathrm B}$ etc. are the respective weights for the model field at 618 points ${\mathrm A}$, ${\mathrm B}$ etc., and $w = {w_{}}_{\mathrm A} + {w_{}}_{\mathrm B} + {w_{}}_{\mathrm C} + {w_{}}_{\mathrm D}$. 589 619 590 620 Four different possibilities are available for computing the weights. 591 621 592 622 \begin{enumerate} 593 594 \item[1.] {\bf Great-Circle distance-weighted interpolation.} 623 \item {\bfseries Great-Circle distance-weighted interpolation.} 595 624 The weights are computed as a function of the great-circle distance $s(P, \cdot)$ between $P$ and 596 625 the model grid points $A$, $B$ etc. 597 For example, the weight given to the field ${x_{}}_{\rm A}$ is specified as the product of the distances 598 from ${\rm P}$ to the other points: 599 \begin{align*} 600 {w_{}}_{\rm A} = s({\rm P}, {\rm B}) \, s({\rm P}, {\rm C}) \, s({\rm P}, {\rm D}) 601 \end{align*} 602 where 603 \begin{align*} 604 s\left ({\rm P}, {\rm M} \right ) 605 & \hspace{-2mm} = \hspace{-2mm} & 606 \cos^{-1} \! \left\{ 607 \sin {\phi_{}}_{\rm P} \sin {\phi_{}}_{\rm M} 608 + \cos {\phi_{}}_{\rm P} \cos {\phi_{}}_{\rm M} 609 \cos ({\lambda_{}}_{\rm M} - {\lambda_{}}_{\rm P}) 626 For example, the weight given to the field ${x_{}}_{\mathrm A}$ is specified as the product of the distances 627 from ${\mathrm P}$ to the other points: 628 629 \begin{alignat*}{2} 630 {w_{}}_{\mathrm A} = s({\mathrm P}, {\mathrm B}) \, s({\mathrm P}, {\mathrm C}) \, s({\mathrm P}, {\mathrm D}) 631 \end{alignat*} 632 633 where 634 635 \begin{alignat*}{2} 636 s\left({\mathrm P}, {\mathrm M} \right) & = & \hspace{0.25em} \cos^{-1} \! \left\{ 637 \sin {\phi_{}}_{\mathrm P} \sin {\phi_{}}_{\mathrm M} 638 + \cos {\phi_{}}_{\mathrm P} \cos {\phi_{}}_{\mathrm M} 639 \cos ({\lambda_{}}_{\mathrm M} - {\lambda_{}}_{\mathrm P}) 610 640 \right\} 611 \end{align*} 641 \end{alignat*} 642 612 643 and $M$ corresponds to $B$, $C$ or $D$. 613 644 A more stable form of the great-circle distance formula for small distances ($x$ near 1) 614 involves the arcsine function (\eg see p.~101 of \citet{Daley_Barker_Bk01}: 615 \begin{align*} 616 s\left( {\rm P}, {\rm M} \right) & \hspace{-2mm} = \hspace{-2mm} & \sin^{-1} \! \left\{ \sqrt{ 1 - x^2 } \right\} 617 \end{align*} 645 involves the arcsine function (\eg\ see p.~101 of \citet{daley.barker_bk01}: 646 647 \begin{alignat*}{2} 648 s\left( {\mathrm P}, {\mathrm M} \right) = \sin^{-1} \! \left\{ \sqrt{ 1 - x^2 } \right\} 649 \end{alignat*} 650 618 651 where 619 \begin{align*} 620 x & \hspace{-2mm} = \hspace{-2mm} & 621 {a_{}}_{\rm M} {a_{}}_{\rm P} + {b_{}}_{\rm M} {b_{}}_{\rm P} + {c_{}}_{\rm M} {c_{}}_{\rm P} 622 \end{align*} 623 and 624 \begin{align*} 625 {a_{}}_{\rm M} & \hspace{-2mm} = \hspace{-2mm} & \sin {\phi_{}}_{\rm M}, \\ 626 {a_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & \sin {\phi_{}}_{\rm P}, \\ 627 {b_{}}_{\rm M} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm M} \cos {\phi_{}}_{\rm M}, \\ 628 {b_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm P} \cos {\phi_{}}_{\rm P}, \\ 629 {c_{}}_{\rm M} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm M} \sin {\phi_{}}_{\rm M}, \\ 630 {c_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm P} \sin {\phi_{}}_{\rm P}. 631 \end{align*} 632 633 \item[2.] {\bf Great-Circle distance-weighted interpolation with small angle approximation.} 652 653 \begin{alignat*}{2} 654 x = {a_{}}_{\mathrm M} {a_{}}_{\mathrm P} + {b_{}}_{\mathrm M} {b_{}}_{\mathrm P} + {c_{}}_{\mathrm M} {c_{}}_{\mathrm P} 655 \end{alignat*} 656 657 and 658 659 \begin{alignat*}{3} 660 & {a_{}}_{\mathrm M} & = && \quad \sin {\phi_{}}_{\mathrm M}, \\ 661 & {a_{}}_{\mathrm P} & = && \quad \sin {\phi_{}}_{\mathrm P}, \\ 662 & {b_{}}_{\mathrm M} & = && \quad \cos {\phi_{}}_{\mathrm M} \cos {\phi_{}}_{\mathrm M}, \\ 663 & {b_{}}_{\mathrm P} & = && \quad \cos {\phi_{}}_{\mathrm P} \cos {\phi_{}}_{\mathrm P}, \\ 664 & {c_{}}_{\mathrm M} & = && \quad \cos {\phi_{}}_{\mathrm M} \sin {\phi_{}}_{\mathrm M}, \\ 665 & {c_{}}_{\mathrm P} & = && \quad \cos {\phi_{}}_{\mathrm P} \sin {\phi_{}}_{\mathrm P}. 666 \end{alignat*} 667 668 \item {\bfseries Great-Circle distance-weighted interpolation with small angle approximation.} 634 669 Similar to the previous interpolation but with the distance $s$ computed as 635 \begin{align*} 636 s\left( {\rm P}, {\rm M} \right) 637 & \hspace{-2mm} = \hspace{-2mm} & 638 \sqrt{ \left( {\phi_{}}_{\rm M} - {\phi_{}}_{\rm P} \right)^{2} 639 + \left( {\lambda_{}}_{\rm M} - {\lambda_{}}_{\rm P} \right)^{2} 640 \cos^{2} {\phi_{}}_{\rm M} } 641 \end{align*} 670 \begin{alignat*}{2} 671 s\left( {\mathrm P}, {\mathrm M} \right) 672 & = & \sqrt{ \left( {\phi_{}}_{\mathrm M} - {\phi_{}}_{\mathrm P} \right)^{2} 673 + \left( {\lambda_{}}_{\mathrm M} - {\lambda_{}}_{\mathrm P} \right)^{2} 674 \cos^{2} {\phi_{}}_{\mathrm M} } 675 \end{alignat*} 642 676 where $M$ corresponds to $A$, $B$, $C$ or $D$. 643 677 644 \item [3.] {\bfBilinear interpolation for a regular spaced grid.}678 \item {\bfseries Bilinear interpolation for a regular spaced grid.} 645 679 The interpolation is split into two 1D interpolations in the longitude and latitude directions, respectively. 646 680 647 \item [4.] {\bfBilinear remapping interpolation for a general grid.}681 \item {\bfseries Bilinear remapping interpolation for a general grid.} 648 682 An iterative scheme that involves first mapping a quadrilateral cell into 649 683 a cell with coordinates (0,0), (1,0), (0,1) and (1,1). 650 This method is based on the SCRIP interpolation package \citep{Jones_1998}.651 684 This method is based on the \href{https://github.com/SCRIP-Project/SCRIP}{SCRIP interpolation package}. 685 652 686 \end{enumerate} 653 687 688 %% ================================================================================================= 654 689 \subsubsection{Horizontal averaging} 655 690 … … 658 693 \item The standard grid-searching code is used to find the nearest model grid point to the observation location 659 694 (see next subsection). 660 \item The maximum number of grid points is calculated in the local grid domain for which 661 the averaging is likely need to cover. 662 \item The lats/longs of the grid points surrounding the nearest model grid box are extracted using 663 existing mpi routines. 695 \item The maximum number of grid points required for that observation in each local grid domain is calculated. Some of these points may later turn out to have zero weight depending on the shape of the footprint. 696 \item The longitudes and latitudes of the grid points surrounding the nearest model grid box are extracted using 697 existing MPI routines. 664 698 \item The weights for each grid point associated with each observation are calculated, 665 699 either for radial or rectangular footprints. … … 673 707 674 708 Examples of the weights calculated for an observation with rectangular and radial footprints are shown in 675 Figs.~\autoref{fig:obsavgrec} and~\autoref{fig:obsavgrad}. 676 677 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 709 \autoref{fig:OBS_avgrec} and~\autoref{fig:OBS_avgrad}. 710 678 711 \begin{figure} 679 \begin{center} 680 \includegraphics[width=0.90\textwidth]{Fig_OBS_avg_rec} 681 \caption{ 682 \protect\label{fig:obsavgrec} 683 Weights associated with each model grid box (blue lines and numbers) 684 for an observation at -170.5\deg{E}, 56.0\deg{N} with a rectangular footprint of 1\deg x 1\deg. 685 } 686 \end{center} 712 \centering 713 \includegraphics[width=0.66\textwidth]{OBS_avg_rec} 714 \caption[Observational weights with a rectangular footprint]{ 715 Weights associated with each model grid box (blue lines and numbers) 716 for an observation at -170.5\deg{E}, 56.0\deg{N} with a rectangular footprint of 1\deg\ x 1\deg.} 717 \label{fig:OBS_avgrec} 687 718 \end{figure} 688 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 689 690 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 719 691 720 \begin{figure} 692 \begin{center} 693 \includegraphics[width=0.90\textwidth]{Fig_OBS_avg_rad} 694 \caption{ 695 \protect\label{fig:obsavgrad} 696 Weights associated with each model grid box (blue lines and numbers) 697 for an observation at -170.5\deg{E}, 56.0\deg{N} with a radial footprint with diameter 1\deg. 698 } 699 \end{center} 721 \centering 722 \includegraphics[width=0.66\textwidth]{OBS_avg_rad} 723 \caption[Observational weights with a radial footprint]{ 724 Weights associated with each model grid box (blue lines and numbers) 725 for an observation at -170.5\deg{E}, 56.0\deg{N} with a radial footprint with diameter 1\deg.} 726 \label{fig:OBS_avgrad} 700 727 \end{figure} 701 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 702 703 728 729 %% ================================================================================================= 704 730 \subsection{Grid search} 705 731 706 For many grids used by the NEMOmodel, such as the ORCA family, the horizontal grid coordinates $i$ and $j$ are not simple functions of latitude and longitude.732 For many grids used by the \NEMO\ model, such as the ORCA family, the horizontal grid coordinates $i$ and $j$ are not simple functions of latitude and longitude. 707 733 Therefore, it is not always straightforward to determine the grid points surrounding any given observational position. 708 Before the interpolation can be performed, a search algorithm is then required to determine the corner points of 734 Before the interpolation can be performed, a search algorithm is then required to determine the corner points of 709 735 the quadrilateral cell in which the observation is located. 710 This is the most difficult and time consuming part of the 2D interpolation procedure. 736 This is the most difficult and time consuming part of the 2D interpolation procedure. 711 737 A robust test for determining if an observation falls within a given quadrilateral cell is as follows. 712 Let ${\ rm P}({\lambda_{}}_{\rm P} ,{\phi_{}}_{\rm P} )$ denote the observation point,713 and let ${\ rm A}({\lambda_{}}_{\rm A} ,{\phi_{}}_{\rm A} )$, ${\rm B}({\lambda_{}}_{\rm B} ,{\phi_{}}_{\rm B} )$,714 ${\ rm C}({\lambda_{}}_{\rm C} ,{\phi_{}}_{\rm C} )$ and ${\rm D}({\lambda_{}}_{\rm D} ,{\phi_{}}_{\rm D} )$715 denote the bottom left, bottom right, top left and top right corner points of the cell, respectively. 716 To determine if P is inside the cell, we verify that the cross-products 738 Let ${\mathrm P}({\lambda_{}}_{\mathrm P} ,{\phi_{}}_{\mathrm P} )$ denote the observation point, 739 and let ${\mathrm A}({\lambda_{}}_{\mathrm A} ,{\phi_{}}_{\mathrm A} )$, ${\mathrm B}({\lambda_{}}_{\mathrm B} ,{\phi_{}}_{\mathrm B} )$, 740 ${\mathrm C}({\lambda_{}}_{\mathrm C} ,{\phi_{}}_{\mathrm C} )$ and ${\mathrm D}({\lambda_{}}_{\mathrm D} ,{\phi_{}}_{\mathrm D} )$ 741 denote the bottom left, bottom right, top left and top right corner points of the cell, respectively. 742 To determine if P is inside the cell, we verify that the cross-products 717 743 \begin{align*} 718 744 \begin{array}{lllll} 719 {{\ bf r}_{}}_{\rm PA} \times {{\bf r}_{}}_{\rm PC}720 & = & [({\lambda_{}}_{\ rm A}\; -\; {\lambda_{}}_{\rm P} )721 ({\phi_{}}_{\ rm C} \; -\; {\phi_{}}_{\rm P} )722 - ({\lambda_{}}_{\ rm C}\; -\; {\lambda_{}}_{\rm P} )723 ({\phi_{}}_{\ rm A} \; -\; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\724 {{\ bf r}_{}}_{\rm PB} \times {{\bf r}_{}}_{\rm PA}725 & = & [({\lambda_{}}_{\ rm B}\; -\; {\lambda_{}}_{\rm P} )726 ({\phi_{}}_{\ rm A} \; -\; {\phi_{}}_{\rm P} )727 - ({\lambda_{}}_{\ rm A}\; -\; {\lambda_{}}_{\rm P} )728 ({\phi_{}}_{\ rm B} \; -\; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\729 {{\ bf r}_{}}_{\rm PC} \times {{\bf r}_{}}_{\rm PD}730 & = & [({\lambda_{}}_{\ rm C}\; -\; {\lambda_{}}_{\rm P} )731 ({\phi_{}}_{\ rm D} \; -\; {\phi_{}}_{\rm P} )732 - ({\lambda_{}}_{\ rm D}\; -\; {\lambda_{}}_{\rm P} )733 ({\phi_{}}_{\ rm C} \; -\; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\734 {{\ bf r}_{}}_{\rm PD} \times {{\bf r}_{}}_{\rm PB}735 & = & [({\lambda_{}}_{\ rm D}\; -\; {\lambda_{}}_{\rm P} )736 ({\phi_{}}_{\ rm B} \; -\; {\phi_{}}_{\rm P} )737 - ({\lambda_{}}_{\ rm B}\; -\; {\lambda_{}}_{\rm P} )738 ({\phi_{}}_{\ rm D} \; - \; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\745 {{\mathbf r}_{}}_{\mathrm PA} \times {{\mathbf r}_{}}_{\mathrm PC} 746 & = & [({\lambda_{}}_{\mathrm A}\; -\; {\lambda_{}}_{\mathrm P} ) 747 ({\phi_{}}_{\mathrm C} \; -\; {\phi_{}}_{\mathrm P} ) 748 - ({\lambda_{}}_{\mathrm C}\; -\; {\lambda_{}}_{\mathrm P} ) 749 ({\phi_{}}_{\mathrm A} \; -\; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\ 750 {{\mathbf r}_{}}_{\mathrm PB} \times {{\mathbf r}_{}}_{\mathrm PA} 751 & = & [({\lambda_{}}_{\mathrm B}\; -\; {\lambda_{}}_{\mathrm P} ) 752 ({\phi_{}}_{\mathrm A} \; -\; {\phi_{}}_{\mathrm P} ) 753 - ({\lambda_{}}_{\mathrm A}\; -\; {\lambda_{}}_{\mathrm P} ) 754 ({\phi_{}}_{\mathrm B} \; -\; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\ 755 {{\mathbf r}_{}}_{\mathrm PC} \times {{\mathbf r}_{}}_{\mathrm PD} 756 & = & [({\lambda_{}}_{\mathrm C}\; -\; {\lambda_{}}_{\mathrm P} ) 757 ({\phi_{}}_{\mathrm D} \; -\; {\phi_{}}_{\mathrm P} ) 758 - ({\lambda_{}}_{\mathrm D}\; -\; {\lambda_{}}_{\mathrm P} ) 759 ({\phi_{}}_{\mathrm C} \; -\; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\ 760 {{\mathbf r}_{}}_{\mathrm PD} \times {{\mathbf r}_{}}_{\mathrm PB} 761 & = & [({\lambda_{}}_{\mathrm D}\; -\; {\lambda_{}}_{\mathrm P} ) 762 ({\phi_{}}_{\mathrm B} \; -\; {\phi_{}}_{\mathrm P} ) 763 - ({\lambda_{}}_{\mathrm B}\; -\; {\lambda_{}}_{\mathrm P} ) 764 ({\phi_{}}_{\mathrm D} \; - \; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\ 739 765 \end{array} 740 % \label{eq: cross}766 % \label{eq:OBS_cross} 741 767 \end{align*} 742 point in the opposite direction to the unit normal $\widehat{\ bf k}$743 (\ie that the coefficients of $\widehat{\bf k}$ are negative),744 where ${{\ bf r}_{}}_{\rm PA}$, ${{\bf r}_{}}_{\rm PB}$, etc. correspond to768 point in the opposite direction to the unit normal $\widehat{\mathbf k}$ 769 (\ie\ that the coefficients of $\widehat{\mathbf k}$ are negative), 770 where ${{\mathbf r}_{}}_{\mathrm PA}$, ${{\mathbf r}_{}}_{\mathrm PB}$, etc. correspond to 745 771 the vectors between points P and A, P and B, etc.. 746 The method used is similar to the method used in the SCRIP interpolation package \citep{Jones_1998}.772 The method used is similar to the method used in the \href{https://github.com/SCRIP-Project/SCRIP}{SCRIP interpolation package}. 747 773 748 774 In order to speed up the grid search, there is the possibility to construct a lookup table for a user specified resolution. … … 750 776 be searched for on a regular grid. 751 777 For each observation position, the closest point on the regular grid of this position is computed and 752 the $i$ and $j$ ranges of this point searched to determine the precise four points surrounding the observation. 753 778 the $i$ and $j$ ranges of this point searched to determine the precise four points surrounding the observation. 779 780 %% ================================================================================================= 754 781 \subsection{Parallel aspects of horizontal interpolation} 755 782 \label{subsec:OBS_parallel} … … 757 784 For horizontal interpolation, there is the basic problem that 758 785 the observations are unevenly distributed on the globe. 759 In numerical models, it is common to divide the model grid into subgrids (or domains) where786 In \NEMO\ the model grid is divided into subgrids (or domains) where 760 787 each subgrid is executed on a single processing element with explicit message passing for 761 788 exchange of information along the domain boundaries when running on a massively parallel processor (MPP) system. 762 This approach is used by \NEMO. 763 764 For observations there is no natural distribution since the observations are not equally distributed on the globe. 789 790 For observations there is no natural distribution since the observations are not equally distributed on the globe. 765 791 Two options have been made available: 766 792 1) geographical distribution; 767 793 and 2) round-robin. 768 794 795 %% ================================================================================================= 769 796 \subsubsection{Geographical distribution of observations among processors} 770 797 771 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>772 798 \begin{figure} 773 \begin{center} 774 \includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_ASM_obsdist_local} 775 \caption{ 776 \protect\label{fig:obslocal} 777 Example of the distribution of observations with the geographical distribution of observational data. 778 } 779 \end{center} 799 \centering 800 \includegraphics[width=0.66\textwidth]{OBS_obsdist_local} 801 \caption[Observations with the geographical distribution]{ 802 Example of the distribution of observations with 803 the geographical distribution of observational data} 804 \label{fig:OBS_local} 780 805 \end{figure} 781 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>782 806 783 807 This is the simplest option in which the observations are distributed according to 784 808 the domain of the grid-point parallelization. 785 \autoref{fig: obslocal} shows an example of the distribution of the {\em in situ} data on processors with786 a different colour for each observation on a given processor for a 4 $\times$ 2 decomposition with ORCA2. 809 \autoref{fig:OBS_local} shows an example of the distribution of the {\em in situ} data on processors with 810 a different colour for each observation on a given processor for a 4 $\times$ 2 decomposition with ORCA2. 787 811 The grid-point domain decomposition is clearly visible on the plot. 788 812 789 813 The advantage of this approach is that all information needed for horizontal interpolation is available without 790 814 any MPP communication. 791 Of course, this is under the assumption that we areonly using a $2 \times 2$ grid-point stencil for792 the interpolation (\eg bilinear interpolation).815 This is under the assumption that we are dealing with point observations and only using a $2 \times 2$ grid-point stencil for 816 the interpolation (\eg\ bilinear interpolation). 793 817 For higher order interpolation schemes this is no longer valid. 794 818 A disadvantage with the above scheme is that the number of observations on each processor can be very different. … … 796 820 this could lead to load imbalance. 797 821 822 %% ================================================================================================= 798 823 \subsubsection{Round-robin distribution of observations among processors} 799 824 800 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>801 825 \begin{figure} 802 \begin{center} 803 \includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_ASM_obsdist_global} 804 \caption{ 805 \protect\label{fig:obsglobal} 806 Example of the distribution of observations with the round-robin distribution of observational data. 807 } 808 \end{center} 826 \centering 827 \includegraphics[width=0.66\textwidth]{OBS_obsdist_global} 828 \caption[Observations with the round-robin distribution]{ 829 Example of the distribution of observations with 830 the round-robin distribution of observational data.} 831 \label{fig:OBS_global} 809 832 \end{figure} 810 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>811 833 812 834 An alternative approach is to distribute the observations equally among processors and 813 835 use message passing in order to retrieve the stencil for interpolation. 814 836 The simplest distribution of the observations is to distribute them using a round-robin scheme. 815 \autoref{fig: obsglobal} shows the distribution of the {\em in situ} data on processors for837 \autoref{fig:OBS_global} shows the distribution of the {\em in situ} data on processors for 816 838 the round-robin distribution of observations with a different colour for each observation on a given processor for 817 a 4 $\times$ 2 decomposition with ORCA2 for the same input data as in \autoref{fig: obslocal}.839 a 4 $\times$ 2 decomposition with ORCA2 for the same input data as in \autoref{fig:OBS_local}. 818 840 The observations are now clearly randomly distributed on the globe. 819 841 In order to be able to perform horizontal interpolation in this case, 820 842 a subroutine has been developed that retrieves any grid points in the global space. 821 843 844 %% ================================================================================================= 822 845 \subsection{Vertical interpolation operator} 823 846 … … 827 850 At the bottom boundary, this is done using the land-ocean mask. 828 851 829 \newpage 830 831 % ================================================================ 832 % Offline observation operator documentation 833 % ================================================================ 852 For profile observation types we do both vertical and horizontal interpolation. \NEMO\ has a generalised vertical coordinate system this means the vertical level depths can vary with location. Therefore, it is necessary first to perform vertical interpolation of the model value to the observation depths for each of the four surrounding grid points. After this the model values, at these points, at the observation depth, are horizontally interpolated to the observation location. 834 853 835 854 %\usepackage{framed} 836 855 837 \section{Offline observation operator} 838 \label{sec:OBS_ooo} 839 856 %% ================================================================================================= 857 \section{Standalone observation operator (\texttt{SAO})} 858 \label{sec:OBS_sao} 859 860 %% ================================================================================================= 840 861 \subsection{Concept} 841 862 842 The obs oper maps model variables to observation space. 843 It is possible to apply this mapping without running the model. 844 The software which performs this functionality is known as the \textbf{offline obs oper}. 845 The obs oper is divided into three stages. 846 An initialisation phase, an interpolation phase and an output phase. 847 The implementation of which is outlined in the previous sections. 848 During the interpolation phase the offline obs oper populates the model arrays by 849 reading saved model fields from disk. 850 851 There are two ways of exploiting this offline capacity. 863 The observation operator maps model variables to observation space. This is normally done while the model is running, i.e. online, it is possible to apply this mapping offline without running the model with the \textbf{standalone observation operator} (SAO). The process is divided into an initialisation phase, an interpolation phase and an output phase. 864 During the interpolation phase the SAO populates the model arrays by 865 reading saved model fields from disk. The interpolation and the output phases use the same OBS code described in the preceding sections. 866 867 There are two ways of exploiting the standalone capacity. 852 868 The first is to mimic the behaviour of the online system by supplying model fields at 853 869 regular intervals between the start and the end of the run. 854 870 This approach results in a single model counterpart per observation. 855 This kind of usage produces feedback files the same file format as the online obs oper.856 The second is to take advantage of the offline setting in which857 multiple model counterparts can be calculated perobservation.871 This kind of usage produces feedback files the same file format as the online observation operator. 872 The second is to take advantage of the ability to run offline by calculating 873 multiple model counterparts for each observation. 858 874 In this case it is possible to consider all forecasts verifying at the same time. 859 By forecast, I mean any method which produces an estimate of physical reality which is not an observed value. 860 In the case of class 4 files this means forecasts, analyses, persisted analyses and 861 climatological values verifying at the same time. 862 Although the class 4 file format doesn't account for multiple ensemble members or 863 multiple experiments per observation, it is possible to include these components in the same or multiple files. 864 865 %-------------------------------------------------------------------------------------------------------- 866 % offline_oper.exe 867 %-------------------------------------------------------------------------------------------------------- 868 869 \subsection{Using the offline observation operator} 870 875 By forecast, we mean any method which produces an estimate of physical reality which is not an observed value. 876 877 % sao.exe 878 879 %% ================================================================================================= 880 \subsection{Using the standalone observation operator} 881 882 %% ================================================================================================= 871 883 \subsubsection{Building} 872 884 873 In addition to \emph{OPA\_SRC} the offline obs oper requires the inclusion of the \emph{OOO\_SRC} directory.874 \emph{ OOO\_SRC} contains a replacement \mdl{nemo} and \mdl{nemogcm} which885 In addition to \emph{OPA\_SRC} the SAO requires the inclusion of the \emph{SAO\_SRC} directory. 886 \emph{SAO\_SRC} contains a replacement \mdl{nemo} and \mdl{nemogcm} which 875 887 overwrites the resultant \textbf{nemo.exe}. 876 This is the approach taken by \emph{SAS\_SRC} and \emph{OFF\_SRC}. 877 878 %-------------------------------------------------------------------------------------------------------- 879 % Running 880 %-------------------------------------------------------------------------------------------------------- 888 Note this a similar approach to that taken by the standalone surface scheme \emph{SAS\_SRC} and the offline TOP model \emph{OFF\_SRC}. 889 890 % Running 891 %% ================================================================================================= 881 892 \subsubsection{Running} 882 893 883 The simplest way to use the executable is to edit and append the \textbf{ooo.nml} namelist to 884 a full NEMO namelist and then to run the executable as if it were nemo.exe. 885 886 \subsubsection{Quick script} 887 888 A useful Python utility to control the namelist options can be found in \textbf{OBSTOOLS/OOO}. 889 The functions which locate model fields and observation files can be manually specified. 890 The package can be installed by appropriate use of the included setup.py script. 891 892 Documentation can be auto-generated by Sphinx by running \emph{make html} in the \textbf{doc} directory. 893 894 %-------------------------------------------------------------------------------------------------------- 894 The simplest way to use the executable is to edit and append the \textbf{sao.nml} namelist to 895 a full \NEMO\ namelist and then to run the executable as if it were nemo.exe. 896 895 897 % Configuration section 896 %-------------------------------------------------------------------------------------------------------- 897 \subsection{Configuring the offline observation operator} 898 The observation files and settings understood by \textbf{namobs} have been outlined in the online obs oper section. 899 In addition there are two further namelists wich control the operation of the offline obs oper. 900 \textbf{namooo} which controls the input model fields and \textbf{namcl4} which 901 controls the production of class 4 files. 902 898 %% ================================================================================================= 899 \subsection{Configuring the standalone observation operator} 900 The observation files and settings understood by \nam{obs}{obs} have been outlined in the online observation operator section. 901 In addition is a further namelist \nam{sao}{sao} which used to set the input model fields for the SAO 902 903 %% ================================================================================================= 903 904 \subsubsection{Single field} 904 905 905 In offline mode model arrays are populated at appropriate time steps via input files.906 At present, \textbf{tsn} and \textbf{sshn} are populated by the default read routines. 906 In the SAO the model arrays are populated at appropriate time steps via input files. 907 At present, \textbf{tsn} and \textbf{sshn} are populated by the default read routines. 907 908 These routines will be expanded upon in future versions to allow the specification of any model variable. 908 909 As such, input files must be global versions of the model domain with 909 910 \textbf{votemper}, \textbf{vosaline} and optionally \textbf{sshn} present. 910 911 911 For each field read there must be an entry in the \ textbf{namooo} namelist specifying912 For each field read there must be an entry in the \nam{sao}{sao} namelist specifying 912 913 the name of the file to read and the index along the \emph{time\_counter}. 913 914 For example, to read the second time counter from a single file the namelist would be. … … 915 916 \begin{forlines} 916 917 !---------------------------------------------------------------------- 917 ! nam ooo Offline obs_oper namelist918 ! namsao Standalone obs_oper namelist 918 919 !---------------------------------------------------------------------- 919 ! ooo_files specifies the files containing the model counterpart920 ! nn_ ooo_idx specifies the time_counter index within the model file921 &nam ooo922 ooo_files = "foo.nc"923 nn_ ooo_idx = 2920 ! sao_files specifies the files containing the model counterpart 921 ! nn_sao_idx specifies the time_counter index within the model file 922 &namsao 923 sao_files = "foo.nc" 924 nn_sao_idx = 2 924 925 / 925 926 \end{forlines} 926 927 928 %% ================================================================================================= 927 929 \subsubsection{Multiple fields per run} 928 930 929 Model field iteration is controlled via \textbf{nn\_ ooo\_freq} which931 Model field iteration is controlled via \textbf{nn\_sao\_freq} which 930 932 specifies the number of model steps at which the next field gets read. 931 933 For example, if 12 hourly fields are to be interpolated in a setup where 288 steps equals 24 hours. … … 933 935 \begin{forlines} 934 936 !---------------------------------------------------------------------- 935 ! nam ooo Offline obs_oper namelist937 ! namsao Standalone obs_oper namelist 936 938 !---------------------------------------------------------------------- 937 ! ooo_files specifies the files containing the model counterpart938 ! nn_ ooo_idx specifies the time_counter index within the model file939 ! nn_ ooo_freq specifies number of time steps between read operations940 &nam ooo941 ooo_files = "foo.nc" "foo.nc"942 nn_ ooo_idx = 1 2943 nn_ ooo_freq = 144939 ! sao_files specifies the files containing the model counterpart 940 ! nn_sao_idx specifies the time_counter index within the model file 941 ! nn_sao_freq specifies number of time steps between read operations 942 &namsao 943 sao_files = "foo.nc" "foo.nc" 944 nn_sao_idx = 1 2 945 nn_sao_freq = 144 944 946 / 945 947 \end{forlines} … … 952 954 %\end{framed} 953 955 954 It is easy to see how a collection of fields taken frona number of files at different indices can be combined at956 A collection of fields taken from a number of files at different indices can be combined at 955 957 a particular frequency in time to generate a pseudo model evolution. 956 As long as all that is needed is a single model counterpart at a regular interval then 957 namooo is all that needs to be edited. 958 However, a far more interesting approach can be taken in which multiple forecasts, analyses, persisted analyses and 959 climatologies are considered against the same set of observations. 960 For this a slightly more complicated approach is needed. 961 It is referred to as \emph{Class 4} since it is the fourth metric defined by the GODAE intercomparison project. 962 963 %-------------------------------------------------------------------------------------------------------- 964 % Class 4 file section 965 %-------------------------------------------------------------------------------------------------------- 966 \subsubsection{Multiple model counterparts per observation a.k.a Class 4} 967 968 A generalisation of feedback files to allow multiple model components per observation. 969 For a single observation, as well as previous forecasts verifying at the same time 970 there are also analyses, persisted analyses and climatologies. 971 972 973 The above namelist performs two basic functions. 974 It organises the fields given in \textbf{namooo} into groups so that observations can be matched up multiple times. 975 It also controls the metadata and the output variable of the class 4 file when a write routine is called. 976 977 %\begin{framed} 978 \textbf{Note: ln\_cl4} must be set to \forcode{.true.} in \textbf{namobs} to use class 4 outputs. 979 %\end{framed} 980 981 \subsubsection{Class 4 naming convention} 982 983 The standard class 4 file naming convention is as follows. 984 985 \noindent 986 \linebreak 987 \textbf{\$\{prefix\}\_\$\{yyyymmdd\}\_\$\{sys\}\_\$\{cfg\}\_\$\{vn\}\_\$\{kind\}\_\$\{nproc\}}.nc 988 989 \noindent 990 \linebreak 991 Much of the namelist is devoted to specifying this convention. 992 The following namelist settings control the elements of the output file names. 993 Each should be specified as a single string of character data. 994 995 \begin{description} 996 \item[cl4\_prefix] 997 Prefix for class 4 files \eg class4 998 \item[cl4\_date] 999 YYYYMMDD validity date 1000 \item[cl4\_sys] 1001 The name of the class 4 model system \eg FOAM 1002 \item[cl4\_cfg] 1003 The name of the class 4 model configuration \eg orca025 1004 \item[cl4\_vn] 1005 The name of the class 4 model version \eg 12.0 1006 \end{description} 1007 1008 \noindent 1009 The kind is specified by the observation type internally to the obs oper. 1010 The processor number is specified internally in NEMO. 1011 1012 \subsubsection{Class 4 file global attributes} 1013 1014 Global attributes necessary to fulfill the class 4 file definition. 1015 These are also useful pieces of information when collaborating with external partners. 1016 1017 \begin{description} 1018 \item[cl4\_contact] 1019 Contact email for class 4 files. 1020 \item[cl4\_inst] 1021 The name of the producers institution. 1022 \item[cl4\_cfg] 1023 The name of the class 4 model configuration \eg orca025 1024 \item[cl4\_vn] 1025 The name of the class 4 model version \eg 12.0 1026 \end{description} 1027 1028 \noindent 1029 The obs\_type, creation date and validity time are specified internally to the obs oper. 1030 1031 \subsubsection{Class 4 model counterpart configuration} 1032 1033 As seen previously it is possible to perform a single sweep of the obs oper and 1034 specify a collection of model fields equally spaced along that sweep. 1035 In the class 4 case the single sweep is replaced with multiple sweeps and 1036 a certain ammount of book keeping is needed to ensure each model counterpart makes its way to 1037 the correct piece of memory in the output files. 1038 1039 \noindent 1040 \linebreak 1041 In terms of book keeping, the offline obs oper needs to know how many full sweeps need to be performed. 1042 This is specified via the \textbf{cl4\_match\_len} variable and 1043 is the total number of model counterparts per observation. 1044 For example, a 3 forecasts plus 3 persistence fields plus an analysis field would be 7 counterparts per observation. 1045 1046 \begin{forlines} 1047 cl4_match_len = 7 1048 \end{forlines} 1049 1050 Then to correctly allocate a class 4 file the forecast axis must be defined. 1051 This is controlled via \textbf{cl4\_fcst\_len}, which in out above example would be 3. 1052 1053 \begin{forlines} 1054 cl4_fcst_len = 3 1055 \end{forlines} 1056 1057 Then for each model field it is necessary to designate what class 4 variable and index along 1058 the forecast dimension the model counterpart should be stored in the output file. 1059 As well as a value for that lead time in hours, this will be useful when interpreting the data afterwards. 1060 1061 \begin{forlines} 1062 cl4_vars = "forecast" "forecast" "forecast" "persistence" "persistence" 1063 "persistence" "best_estimate" 1064 cl4_fcst_idx = 1 2 3 1 2 3 1 1065 cl4_leadtime = 12 36 60 1066 \end{forlines} 1067 1068 In terms of files and indices of fields inside each file the class 4 approach makes use of 1069 the \textbf{namooo} namelist. 1070 If our fields are in separate files with a single field per file our example inputs will be specified. 1071 1072 \begin{forlines} 1073 ooo_files = "F.1.nc" "F.2.nc" "F.3.nc" "P.1.nc" "P.2.nc" "P.3.nc" "A.1.nc" 1074 nn_ooo_idx = 1 1 1 1 1 1 1 1075 \end{forlines} 1076 1077 When we combine all of the naming conventions, global attributes and i/o instructions the class 4 namelist becomes. 1078 1079 \begin{forlines} 1080 !---------------------------------------------------------------------- 1081 ! namooo Offline obs_oper namelist 1082 !---------------------------------------------------------------------- 1083 ! ooo_files specifies the files containing the model counterpart 1084 ! nn_ooo_idx specifies the time_counter index within the model file 1085 ! nn_ooo_freq specifies number of time steps between read operations 1086 &namooo 1087 ooo_files = "F.1.nc" "F.2.nc" "F.3.nc" "P.1.nc" "P.2.nc" "P.3.nc" "A.1.nc" 1088 nn_ooo_idx = 1 1 1 1 1 1 1 1089 / 1090 !---------------------------------------------------------------------- 1091 ! namcl4 Offline obs_oper class 4 namelist 1092 !---------------------------------------------------------------------- 1093 ! 1094 ! Naming convention 1095 ! ----------------- 1096 ! cl4_prefix specifies the output file prefix 1097 ! cl4_date specifies the output file validity date 1098 ! cl4_sys specifies the model counterpart system 1099 ! cl4_cfg specifies the model counterpart configuration 1100 ! cl4_vn specifies the model counterpart version 1101 ! cl4_inst specifies the model counterpart institute 1102 ! cl4_contact specifies the file producers contact details 1103 ! 1104 ! I/O specification 1105 ! ----------------- 1106 ! cl4_vars specifies the names of the output file netcdf variable 1107 ! cl4_fcst_idx specifies output file forecast index 1108 ! cl4_fcst_len specifies forecast axis length 1109 ! cl4_match_len specifies number of unique matches per observation 1110 ! cl4_leadtime specifies the forecast axis lead time 1111 ! 1112 &namcl4 1113 cl4_match_len = 7 1114 cl4_fcst_len = 3 1115 cl4_fcst_idx = 1 2 3 1 2 3 1 1116 cl4_vars = "forecast" "forecast" "forecast" "persistence" "persistence" 1117 "persistence" "best_estimate" 1118 cl4_leadtime = 12 36 60 1119 cl4_prefix = "class4" 1120 cl4_date = "20130101" 1121 cl4_vn = "12.0" 1122 cl4_sys = "FOAM" 1123 cl4_cfg = "AMM7" 1124 cl4_contact = "example@example.com" 1125 cl4_inst = "UK Met Office" 1126 / 1127 \end{forlines} 1128 1129 \subsubsection{Climatology interpolation} 1130 1131 The climatological counterpart is generated at the start of the run by 1132 restarting the model from climatology through appropriate use of \textbf{namtsd}. 1133 To override the offline observation operator read routine and to take advantage of the restart settings, 1134 specify the first entry in \textbf{cl4\_vars} as "climatology". 1135 This will then pipe the restart from climatology into the output class 4 file. 1136 As in every other class 4 matchup the input file, input index and output index must be specified. 1137 These can be replaced with dummy data since they are not used but 1138 they must be present to cycle through the matchups correctly. 1139 1140 \subsection{Advanced usage} 1141 1142 In certain cases it may be desirable to include both multiple model fields per observation window with 1143 multiple match ups per observation. 1144 This can be achieved by specifying \textbf{nn\_ooo\_freq} as well as the class 4 settings. 1145 Care must be taken in generating the ooo\_files list such that the files are arranged into 1146 consecutive blocks of single match ups. 1147 For example, 2 forecast fields of 12 hourly data would result in 4 separate read operations but 1148 only 2 write operations, 1 per forecast. 1149 1150 \begin{forlines} 1151 ooo_files = "F1.nc" "F1.nc" "F2.nc" "F2.nc" 1152 ... 1153 cl4_fcst_idx = 1 2 1154 \end{forlines} 1155 1156 The above notation reveals the internal split between match up iterators and file iterators. 1157 This technique has not been used before so experimentation is needed before results can be trusted. 1158 1159 \newpage 1160 958 If all that is needed is a single model counterpart at a regular interval then 959 the standard SAO is all that is required. 960 However, just to note, it is possible to extend this approach by comparing multiple forecasts, analyses, persisted analyses and 961 climatologies with the same set of observations. 962 This approach is referred to as \emph{Class 4} since it is the fourth metric defined by the GODAE intercomparison project. This requires multiple runs of the SAO and running an additional utility (not currently in the \NEMO\ repository) to combine the feedback files into one class 4 file. 963 964 %% ================================================================================================= 1161 965 \section{Observation utilities} 1162 966 \label{sec:OBS_obsutils} 1163 967 1164 Some tools for viewing and processing of observation and feedback files are provided in1165 the NEMO repository for convenience.1166 These include OBSTOOLS which are a collection of \fortranprograms which are helpful to deal with feedback files.968 For convenience some tools for viewing and processing of observation and feedback files are provided in 969 the \NEMO\ repository. 970 These tools include OBSTOOLS which are a collection of \fortran\ programs which are helpful to deal with feedback files. 1167 971 They do such tasks as observation file conversion, printing of file contents, 1168 972 some basic statistical analysis of feedback files. 1169 The other tool is an IDL program called dataplot which uses a graphical interface to973 The other main tool is an IDL program called dataplot which uses a graphical interface to 1170 974 visualise observations and feedback files. 1171 975 OBSTOOLS and dataplot are described in more detail below. 1172 976 977 %% ================================================================================================= 1173 978 \subsection{Obstools} 1174 979 1175 A series of \fortran utilities is provided with NEMO called OBSTOOLS. 1176 This are helpful in handling observation files and the feedback file output from the NEMO observation operator. 1177 The utilities are as follows 1178 1179 \subsubsection{c4comb} 1180 1181 The program c4comb combines multiple class 4 files produced by individual processors in 1182 an MPI run of NEMO offline obs\_oper into a single class 4 file. 1183 The program is called in the following way: 1184 1185 1186 \footnotesize 1187 \begin{cmds} 1188 c4comb.exe outputfile inputfile1 inputfile2 ... 1189 \end{cmds} 1190 980 A series of \fortran\ utilities is provided with \NEMO\ called OBSTOOLS. 981 This are helpful in handling observation files and the feedback file output from the observation operator. A brief description of some of the utilities follows 982 983 %% ================================================================================================= 1191 984 \subsubsection{corio2fb} 1192 985 1193 986 The program corio2fb converts profile observation files from the Coriolis format to the standard feedback format. 1194 The program is called in the following way: 1195 1196 \footnotesize 987 It is called in the following way: 988 1197 989 \begin{cmds} 1198 990 corio2fb.exe outputfile inputfile1 inputfile2 ... 1199 991 \end{cmds} 1200 992 993 %% ================================================================================================= 1201 994 \subsubsection{enact2fb} 1202 995 1203 996 The program enact2fb converts profile observation files from the ENACT format to the standard feedback format. 1204 The program is called in the following way: 1205 1206 \footnotesize 997 It is called in the following way: 998 1207 999 \begin{cmds} 1208 1000 enact2fb.exe outputfile inputfile1 inputfile2 ... 1209 1001 \end{cmds} 1210 1002 1003 %% ================================================================================================= 1211 1004 \subsubsection{fbcomb} 1212 1005 1213 1006 The program fbcomb combines multiple feedback files produced by individual processors in 1214 an MPI run of NEMO into a single feedback file. 1215 The program is called in the following way: 1216 1217 \footnotesize 1007 an MPI run of \NEMO\ into a single feedback file. 1008 It is called in the following way: 1009 1218 1010 \begin{cmds} 1219 1011 fbcomb.exe outputfile inputfile1 inputfile2 ... 1220 1012 \end{cmds} 1221 1013 1014 %% ================================================================================================= 1222 1015 \subsubsection{fbmatchup} 1223 1016 1224 1017 The program fbmatchup will match observations from two feedback files. 1225 The program is called in the following way: 1226 1227 \footnotesize 1018 It is called in the following way: 1019 1228 1020 \begin{cmds} 1229 1021 fbmatchup.exe outputfile inputfile1 varname1 inputfile2 varname2 ... 1230 1022 \end{cmds} 1231 1023 1024 %% ================================================================================================= 1232 1025 \subsubsection{fbprint} 1233 1026 1234 1027 The program fbprint will print the contents of a feedback file or files to standard output. 1235 1028 Selected information can be output using optional arguments. 1236 The program is called in the following way: 1237 1238 \footnotesize 1029 It is called in the following way: 1030 1239 1031 \begin{cmds} 1240 1032 fbprint.exe [options] inputfile … … 1246 1038 -B Select observations based on QC flags 1247 1039 -u unsorted 1248 -s ID select station ID 1040 -s ID select station ID 1249 1041 -t TYPE select observation type 1250 -v NUM1-NUM2 select variable range to print by number 1042 -v NUM1-NUM2 select variable range to print by number 1251 1043 (default all) 1252 -a NUM1-NUM2 select additional variable range to print by number 1044 -a NUM1-NUM2 select additional variable range to print by number 1253 1045 (default all) 1254 -e NUM1-NUM2 select extra variable range to print by number 1046 -e NUM1-NUM2 select extra variable range to print by number 1255 1047 (default all) 1256 1048 -d output date range … … 1259 1051 \end{cmds} 1260 1052 1053 %% ================================================================================================= 1261 1054 \subsubsection{fbsel} 1262 1055 1263 1056 The program fbsel will select or subsample observations. 1264 The program is called in the following way: 1265 1266 \footnotesize 1057 It is called in the following way: 1058 1267 1059 \begin{cmds} 1268 1060 fbsel.exe <input filename> <output filename> 1269 1061 \end{cmds} 1270 1062 1063 %% ================================================================================================= 1271 1064 \subsubsection{fbstat} 1272 1065 1273 1066 The program fbstat will output summary statistics in different global areas into a number of files. 1274 The program is called in the following way: 1275 1276 \footnotesize 1067 It is called in the following way: 1068 1277 1069 \begin{cmds} 1278 1070 fbstat.exe [-nmlev] <filenames> 1279 1071 \end{cmds} 1280 1072 1073 %% ================================================================================================= 1281 1074 \subsubsection{fbthin} 1282 1075 1283 1076 The program fbthin will thin the data to 1 degree resolution. 1284 1077 The code could easily be modified to thin to a different resolution. 1285 The program is called in the following way: 1286 1287 \footnotesize 1078 It is called in the following way: 1079 1288 1080 \begin{cmds} 1289 1081 fbthin.exe inputfile outputfile 1290 1082 \end{cmds} 1291 1083 1084 %% ================================================================================================= 1292 1085 \subsubsection{sla2fb} 1293 1086 1294 1087 The program sla2fb will convert an AVISO SLA format file to feedback format. 1295 The program is called in the following way: 1296 1297 \footnotesize 1088 It is called in the following way: 1089 1298 1090 \begin{cmds} 1299 1091 sla2fb.exe [-s type] outputfile inputfile1 inputfile2 ... … … 1303 1095 \end{cmds} 1304 1096 1097 %% ================================================================================================= 1305 1098 \subsubsection{vel2fb} 1306 1099 1307 1100 The program vel2fb will convert TAO/PIRATA/RAMA currents files to feedback format. 1308 The program is called in the following way: 1309 1310 \footnotesize 1101 It is called in the following way: 1102 1311 1103 \begin{cmds} 1312 1104 vel2fb.exe outputfile inputfile1 inputfile2 ... 1313 1105 \end{cmds} 1314 1106 1107 %% ================================================================================================= 1315 1108 \subsection{Building the obstools} 1316 1109 1317 1110 To build the obstools use in the tools directory use ./maketools -n OBSTOOLS -m [ARCH]. 1318 1111 1112 %% ================================================================================================= 1319 1113 \subsection{Dataplot} 1320 1114 1321 1115 An IDL program called dataplot is included which uses a graphical interface to 1322 visualise observations and feedback files. 1116 visualise observations and feedback files. Note a similar package has recently developed in python (also called dataplot) which does some of the same things that the IDL dataplot does. Please contact the authors of the this chapter if you are interested in this. 1117 1323 1118 It is possible to zoom in, plot individual profiles and calculate some basic statistics. 1324 1119 To plot some data run IDL and then: 1325 \footnotesize 1120 1326 1121 \begin{minted}{idl} 1327 1122 IDL> dataplot, "filename" … … 1331 1126 for example multiple feedback files from different processors or from different days, 1332 1127 the easiest method is to use the spawn command to generate a list of files which can then be passed to dataplot. 1333 \footnotesize 1128 1334 1129 \begin{minted}{idl} 1335 1130 IDL> spawn, 'ls profb*.nc', files … … 1337 1132 \end{minted} 1338 1133 1339 \autoref{fig: obsdataplotmain} shows the main window which is launched when dataplot starts.1134 \autoref{fig:OBS_dataplotmain} shows the main window which is launched when dataplot starts. 1340 1135 This is split into three parts. 1341 1136 At the top there is a menu bar which contains a variety of drop down menus. … … 1350 1145 The plotting colour range can be changed by clicking on the colour bar. 1351 1146 The title of the plot gives some basic information about the date range and depth range shown, 1352 the extreme values, and the mean and rmsvalues.1147 the extreme values, and the mean and RMS values. 1353 1148 It is possible to zoom in using a drag-box. 1354 1149 You may also zoom in or out using the mouse wheel. … … 1362 1157 observation minus background value. 1363 1158 The next group of radio buttons selects the map projection. 1364 This can either be regular l atitude longitude grid, or north or south polar stereographic.1159 This can either be regular longitude latitude grid, or north or south polar stereographic. 1365 1160 The next group of radio buttons will plot bad observations, switch to salinity and 1366 1161 plot density for profile observations. 1367 1162 The rightmost group of buttons will print the plot window as a postscript, save it as png, or exit from dataplot. 1368 1163 1369 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>1370 1164 \begin{figure} 1371 \begin{center} 1372 % \includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_OBS_dataplot_main} 1373 \includegraphics[width=9cm,angle=-90.]{Fig_OBS_dataplot_main} 1374 \caption{ 1375 \protect\label{fig:obsdataplotmain} 1376 Main window of dataplot. 1377 } 1378 \end{center} 1165 \centering 1166 \includegraphics[width=0.66\textwidth]{OBS_dataplot_main} 1167 \caption{Main window of dataplot} 1168 \label{fig:OBS_dataplotmain} 1379 1169 \end{figure} 1380 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>1381 1170 1382 1171 If a profile point is clicked with the mouse button a plot of the observation and background values as 1383 a function of depth (\autoref{fig:obsdataplotprofile}). 1384 1385 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1172 a function of depth (\autoref{fig:OBS_dataplotprofile}). 1173 1386 1174 \begin{figure} 1387 \begin{center} 1388 % \includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_OBS_dataplot_prof} 1389 \includegraphics[width=7cm,angle=-90.]{Fig_OBS_dataplot_prof} 1390 \caption{ 1391 \protect\label{fig:obsdataplotprofile} 1392 Profile plot from dataplot produced by right clicking on a point in the main window. 1393 } 1394 \end{center} 1175 \centering 1176 \includegraphics[width=0.66\textwidth]{OBS_dataplot_prof} 1177 \caption[Profile plot from dataplot]{ 1178 Profile plot from dataplot produced by right clicking on a point in the main window} 1179 \label{fig:OBS_dataplotprofile} 1395 1180 \end{figure} 1396 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1397 1398 \biblio 1399 1400 \pindex 1181 1182 \subinc{\input{../../global/epilogue}} 1401 1183 1402 1184 \end{document} -
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_SBC.tex
r10614 r11831 2 2 3 3 \begin{document} 4 % ================================================================ 5 % Chapter —— Surface Boundary Condition (SBC, ISF, ICB) 6 % ================================================================ 7 \chapter{Surface Boundary Condition (SBC, ISF, ICB) } 4 5 \chapter{Surface Boundary Condition (SBC, SAS, ISF, ICB)} 8 6 \label{chap:SBC} 9 \minitoc 10 11 \newpage 12 13 %---------------------------------------namsbc-------------------------------------------------- 14 15 \nlst{namsbc} 16 %-------------------------------------------------------------------------------------------------------------- 17 18 The ocean needs six fields as surface boundary condition: 7 8 \thispagestyle{plain} 9 10 \chaptertoc 11 12 \paragraph{Changes record} ~\\ 13 14 {\footnotesize 15 \begin{tabularx}{\textwidth}{l||X|X} 16 Release & Author(s) & Modifications \\ 17 \hline 18 {\em 4.0} & {\em ...} & {\em ...} \\ 19 {\em 3.6} & {\em ...} & {\em ...} \\ 20 {\em 3.4} & {\em ...} & {\em ...} \\ 21 {\em <=3.4} & {\em ...} & {\em ...} 22 \end{tabularx} 23 } 24 25 \clearpage 26 27 \begin{listing} 28 \nlst{namsbc} 29 \caption{\forcode{&namsbc}} 30 \label{lst:namsbc} 31 \end{listing} 32 33 The ocean needs seven fields as surface boundary condition: 34 19 35 \begin{itemize} 20 \item 21 the two components of the surface ocean stress $\left( {\tau_u \;,\;\tau_v} \right)$ 22 \item 23 the incoming solar and non solar heat fluxes $\left( {Q_{ns} \;,\;Q_{sr} } \right)$ 24 \item 25 the surface freshwater budget $\left( {\textit{emp}} \right)$ 26 \item 27 the surface salt flux associated with freezing/melting of seawater $\left( {\textit{sfx}} \right)$ 36 \item the two components of the surface ocean stress $\left( {\tau_u \;,\;\tau_v} \right)$ 37 \item the incoming solar and non solar heat fluxes $\left( {Q_{ns} \;,\;Q_{sr} } \right)$ 38 \item the surface freshwater budget $\left( {\textit{emp}} \right)$ 39 \item the surface salt flux associated with freezing/melting of seawater $\left( {\textit{sfx}} \right)$ 40 \item the atmospheric pressure at the ocean surface $\left( p_a \right)$ 28 41 \end{itemize} 29 plus an optional field: 42 43 Four different ways are available to provide the seven fields to the ocean. They are controlled by 44 namelist \nam{sbc}{sbc} variables: 45 30 46 \begin{itemize} 31 \item the atmospheric pressure at the ocean surface $\left( p_a \right)$ 47 \item a bulk formulation (\np[=.true.]{ln_blk}{ln\_blk} with four possible bulk algorithms), 48 \item a flux formulation (\np[=.true.]{ln_flx}{ln\_flx}), 49 \item a coupled or mixed forced/coupled formulation (exchanges with a atmospheric model via the OASIS coupler), 50 (\np{ln_cpl}{ln\_cpl} or \np[=.true.]{ln_mixcpl}{ln\_mixcpl}), 51 \item a user defined formulation (\np[=.true.]{ln_usr}{ln\_usr}). 32 52 \end{itemize} 33 53 34 Four different ways to provide the first six fields to the ocean are available which are controlled by 35 namelist \ngn{namsbc} variables: 36 an analytical formulation (\np{ln\_ana}\forcode{ = .true.}), 37 a flux formulation (\np{ln\_flx}\forcode{ = .true.}), 38 a bulk formulae formulation (CORE (\np{ln\_blk\_core}\forcode{ = .true.}), 39 CLIO (\np{ln\_blk\_clio}\forcode{ = .true.}) bulk formulae) and 40 a coupled or mixed forced/coupled formulation (exchanges with a atmospheric model via the OASIS coupler) 41 (\np{ln\_cpl} or \np{ln\_mixcpl}\forcode{ = .true.}). 42 When used (\ie \np{ln\_apr\_dyn}\forcode{ = .true.}), 43 the atmospheric pressure forces both ocean and ice dynamics. 44 45 The frequency at which the forcing fields have to be updated is given by the \np{nn\_fsbc} namelist parameter. 46 When the fields are supplied from data files (flux and bulk formulations), 47 the input fields need not be supplied on the model grid. 48 Instead a file of coordinates and weights can be supplied which maps the data from the supplied grid to 54 The frequency at which the forcing fields have to be updated is given by the \np{nn_fsbc}{nn\_fsbc} namelist parameter. 55 56 When the fields are supplied from data files (bulk, flux and mixed formulations), 57 the input fields do not need to be supplied on the model grid. 58 Instead, a file of coordinates and weights can be supplied to map the data from the input fields grid to 49 59 the model points (so called "Interpolation on the Fly", see \autoref{subsec:SBC_iof}). 50 If the Interpolation on the Fly option is used, input data belonging to land points (in the native grid),51 can be masked to avoid spurious results in proximity of the coastsas60 If the "Interpolation on the Fly" option is used, input data belonging to land points (in the native grid) 61 should be masked or filled to avoid spurious results in proximity of the coasts, as 52 62 large sea-land gradients characterize most of the atmospheric variables. 53 63 54 64 In addition, the resulting fields can be further modified using several namelist options. 55 These options control 65 These options control: 66 56 67 \begin{itemize} 57 \item 58 the rotation of vector components supplied relative to an east-north coordinate system onto 59 the local grid directions in the model; 60 \item 61 the addition of a surface restoring term to observed SST and/or SSS (\np{ln\_ssr}\forcode{ = .true.}); 62 \item 63 the modification of fluxes below ice-covered areas (using observed ice-cover or a sea-ice model) 64 (\np{nn\_ice}\forcode{ = 0..3}); 65 \item 66 the addition of river runoffs as surface freshwater fluxes or lateral inflow (\np{ln\_rnf}\forcode{ = .true.}); 67 \item 68 the addition of isf melting as lateral inflow (parameterisation) or 69 as fluxes applied at the land-ice ocean interface (\np{ln\_isf}) ; 70 \item 71 the addition of a freshwater flux adjustment in order to avoid a mean sea-level drift 72 (\np{nn\_fwb}\forcode{ = 0..2}); 73 \item 74 the transformation of the solar radiation (if provided as daily mean) into a diurnal cycle 75 (\np{ln\_dm2dc}\forcode{ = .true.}); 76 \item 77 a neutral drag coefficient can be read from an external wave model (\np{ln\_cdgw}\forcode{ = .true.}); 78 \item 79 the Stokes drift rom an external wave model can be accounted (\np{ln\_sdw}\forcode{ = .true.}); 80 \item 81 the Stokes-Coriolis term can be included (\np{ln\_stcor}\forcode{ = .true.}); 82 \item 83 the surface stress felt by the ocean can be modified by surface waves (\np{ln\_tauwoc}\forcode{ = .true.}). 68 \item the rotation of vector components supplied relative to an east-north coordinate system onto 69 the local grid directions in the model, 70 \item the use of a land/sea mask for input fields (\np[=.true.]{nn_lsm}{nn\_lsm}), 71 \item the addition of a surface restoring term to observed SST and/or SSS (\np[=.true.]{ln_ssr}{ln\_ssr}), 72 \item the modification of fluxes below ice-covered areas (using climatological ice-cover or a sea-ice model) 73 (\np[=0..3]{nn_ice}{nn\_ice}), 74 \item the addition of river runoffs as surface freshwater fluxes or lateral inflow (\np[=.true.]{ln_rnf}{ln\_rnf}), 75 \item the addition of ice-shelf melting as lateral inflow (parameterisation) or 76 as fluxes applied at the land-ice ocean interface (\np[=.true.]{ln_isf}{ln\_isf}), 77 \item the addition of a freshwater flux adjustment in order to avoid a mean sea-level drift 78 (\np[=0..2]{nn_fwb}{nn\_fwb}), 79 \item the transformation of the solar radiation (if provided as daily mean) into an analytical diurnal cycle 80 (\np[=.true.]{ln_dm2dc}{ln\_dm2dc}), 81 \item the activation of wave effects from an external wave model (\np[=.true.]{ln_wave}{ln\_wave}), 82 \item a neutral drag coefficient is read from an external wave model (\np[=.true.]{ln_cdgw}{ln\_cdgw}), 83 \item the Stokes drift from an external wave model is accounted for (\np[=.true.]{ln_sdw}{ln\_sdw}), 84 \item the choice of the Stokes drift profile parameterization (\np[=0..2]{nn_sdrift}{nn\_sdrift}), 85 \item the surface stress given to the ocean is modified by surface waves (\np[=.true.]{ln_tauwoc}{ln\_tauwoc}), 86 \item the surface stress given to the ocean is read from an external wave model (\np[=.true.]{ln_tauw}{ln\_tauw}), 87 \item the Stokes-Coriolis term is included (\np[=.true.]{ln_stcor}{ln\_stcor}), 88 \item the light penetration in the ocean (\np[=.true.]{ln_traqsr}{ln\_traqsr} with namelist \nam{tra_qsr}{tra\_qsr}), 89 \item the atmospheric surface pressure gradient effect on ocean and ice dynamics (\np[=.true.]{ln_apr_dyn}{ln\_apr\_dyn} with namelist \nam{sbc_apr}{sbc\_apr}), 90 \item the effect of sea-ice pressure on the ocean (\np[=.true.]{ln_ice_embd}{ln\_ice\_embd}). 84 91 \end{itemize} 85 92 86 In this chapter, we first discuss where the surface boundary condition appearsin the model equations.87 Then we present the five ways of providing the surface boundary condition,88 followed by the description of the atmospheric pressure and the river runoff. 89 Next the scheme for interpolation on the fly is described.93 In this chapter, we first discuss where the surface boundary conditions appear in the model equations. 94 Then we present the three ways of providing the surface boundary conditions, 95 followed by the description of the atmospheric pressure and the river runoff. 96 Next, the scheme for interpolation on the fly is described. 90 97 Finally, the different options that further modify the fluxes applied to the ocean are discussed. 91 One of these is modification by icebergs (see \autoref{sec: ICB_icebergs}),98 One of these is modification by icebergs (see \autoref{sec:SBC_ICB_icebergs}), 92 99 which act as drifting sources of fresh water. 93 Another example of modification is that due to the ice shelf melting/freezing (see \autoref{sec:SBC_isf}), 100 Another example of modification is that due to the ice shelf melting/freezing (see \autoref{sec:SBC_isf}), 94 101 which provides additional sources of fresh water. 95 102 96 97 % ================================================================ 98 % Surface boundary condition for the ocean 99 % ================================================================ 103 %% ================================================================================================= 100 104 \section{Surface boundary condition for the ocean} 101 \label{sec:SBC_ general}105 \label{sec:SBC_ocean} 102 106 103 107 The surface ocean stress is the stress exerted by the wind and the sea-ice on the ocean. 104 108 It is applied in \mdl{dynzdf} module as a surface boundary condition of the computation of 105 the momentum vertical mixing trend (see \autoref{eq: dynzdf_sbc} in \autoref{sec:DYN_zdf}).109 the momentum vertical mixing trend (see \autoref{eq:DYN_zdf_sbc} in \autoref{sec:DYN_zdf}). 106 110 As such, it has to be provided as a 2D vector interpolated onto the horizontal velocity ocean mesh, 107 \ie resolved onto the model (\textbf{i},\textbf{j}) direction at $u$- and $v$-points.111 \ie\ resolved onto the model (\textbf{i},\textbf{j}) direction at $u$- and $v$-points. 108 112 109 113 The surface heat flux is decomposed into two parts, a non solar and a solar heat flux, 110 114 $Q_{ns}$ and $Q_{sr}$, respectively. 111 115 The former is the non penetrative part of the heat flux 112 (\ie the sum of sensible, latent and long wave heat fluxes plus113 the heat content of the mass exchange with the atmosphereand sea-ice).116 (\ie\ the sum of sensible, latent and long wave heat fluxes plus 117 the heat content of the mass exchange between the ocean and sea-ice). 114 118 It is applied in \mdl{trasbc} module as a surface boundary condition trend of 115 119 the first level temperature time evolution equation 116 (see \autoref{eq: tra_sbc} and \autoref{eq:tra_sbc_lin} in \autoref{subsec:TRA_sbc}).120 (see \autoref{eq:TRA_sbc} and \autoref{eq:TRA_sbc_lin} in \autoref{subsec:TRA_sbc}). 117 121 The latter is the penetrative part of the heat flux. 118 It is applied as a 3D trend sof the temperature equation (\mdl{traqsr} module) when119 \np {ln\_traqsr}\forcode{ = .true.}.122 It is applied as a 3D trend of the temperature equation (\mdl{traqsr} module) when 123 \np[=.true.]{ln_traqsr}{ln\_traqsr}. 120 124 The way the light penetrates inside the water column is generally a sum of decreasing exponentials 121 (see \autoref{subsec:TRA_qsr}). 125 (see \autoref{subsec:TRA_qsr}). 122 126 123 127 The surface freshwater budget is provided by the \textit{emp} field. 124 128 It represents the mass flux exchanged with the atmosphere (evaporation minus precipitation) and 125 129 possibly with the sea-ice and ice shelves (freezing minus melting of ice). 126 It affects boththe ocean in two different ways:127 $(i)$ it changes the volume of the ocean and therefore appears in the sea surface height equation as128 a volume flux, and 130 It affects the ocean in two different ways: 131 $(i)$ it changes the volume of the ocean, and therefore appears in the sea surface height equation as %GS: autoref ssh equation to be added 132 a volume flux, and 129 133 $(ii)$ it changes the surface temperature and salinity through the heat and salt contents of 130 the mass exchanged with the atmosphere, the sea-ice and the ice shelves. 131 134 the mass exchanged with atmosphere, sea-ice and ice shelves. 132 135 133 136 %\colorbox{yellow}{Miss: } 134 % 135 %A extensive description of all namsbc namelist (parameter that have to be 137 %A extensive description of all namsbc namelist (parameter that have to be 136 138 %created!) 137 % 138 %Especially the \np{nn\_fsbc}, the \mdl{sbc\_oce} module (fluxes + mean sst sss ssu 139 %ssv) \ie information required by flux computation or sea-ice 140 % 141 %\mdl{sbc\_oce} containt the definition in memory of the 7 fields (6+runoff), add 139 %Especially the \np{nn_fsbc}{nn\_fsbc}, the \mdl{sbc\_oce} module (fluxes + mean sst sss ssu 140 %ssv) \ie\ information required by flux computation or sea-ice 141 %\mdl{sbc\_oce} containt the definition in memory of the 7 fields (6+runoff), add 142 142 %a word on runoff: included in surface bc or add as lateral obc{\ldots}. 143 %144 143 %Sbcmod manage the ``providing'' (fourniture) to the ocean the 7 fields 145 % 146 %Fluxes update only each nf{\_}sbc time step (namsbc) explain relation 147 %between nf{\_}sbc and nf{\_}ice, do we define nf{\_}blk??? ? only one 148 %nf{\_}sbc 149 % 144 %Fluxes update only each nf\_sbc time step (namsbc) explain relation 145 %between nf\_sbc and nf\_ice, do we define nf\_blk??? ? only one 146 %nf\_sbc 150 147 %Explain here all the namlist namsbc variable{\ldots}. 151 %152 148 % explain : use or not of surface currents 153 %154 149 %\colorbox{yellow}{End Miss } 155 150 156 151 The ocean model provides, at each time step, to the surface module (\mdl{sbcmod}) 157 the surface currents, temperature and salinity. 158 These variables are averaged over \np{nn\_fsbc} time-step (\autoref{tab:ssm}), and 159 it is these averaged fields which are used to computes the surface fluxes at a frequency of \np{nn\_fsbc} time-step. 160 161 162 %-------------------------------------------------TABLE--------------------------------------------------- 152 the surface currents, temperature and salinity. 153 These variables are averaged over \np{nn_fsbc}{nn\_fsbc} time-step (\autoref{tab:SBC_ssm}), and 154 these averaged fields are used to compute the surface fluxes at the frequency of \np{nn_fsbc}{nn\_fsbc} time-steps. 155 163 156 \begin{table}[tb] 164 \begin{center} 165 \begin{tabular}{|l|l|l|l|} 166 \hline 167 Variable description & Model variable & Units & point \\ \hline 168 i-component of the surface current & ssu\_m & $m.s^{-1}$ & U \\ \hline 169 j-component of the surface current & ssv\_m & $m.s^{-1}$ & V \\ \hline 170 Sea surface temperature & sst\_m & \r{}$K$ & T \\ \hline 171 Sea surface salinty & sss\_m & $psu$ & T \\ \hline 172 \end{tabular} 173 \caption{ 174 \protect\label{tab:ssm} 175 Ocean variables provided by the ocean to the surface module (SBC). 176 The variable are averaged over nn{\_}fsbc time step, 177 \ie the frequency of computation of surface fluxes. 178 } 179 \end{center} 157 \centering 158 \begin{tabular}{|l|l|l|l|} 159 \hline 160 Variable description & Model variable & Units & point \\ 161 \hline 162 i-component of the surface current & ssu\_m & $m.s^{-1}$ & U \\ 163 \hline 164 j-component of the surface current & ssv\_m & $m.s^{-1}$ & V \\ 165 \hline 166 Sea surface temperature & sst\_m & \r{}$K$ & T \\\hline 167 Sea surface salinty & sss\_m & $psu$ & T \\ \hline 168 \end{tabular} 169 \caption[Ocean variables provided to the surface module)]{ 170 Ocean variables provided to the surface module (\texttt{SBC}). 171 The variable are averaged over \protect\np{nn_fsbc}{nn\_fsbc} time-step, 172 \ie\ the frequency of computation of surface fluxes.} 173 \label{tab:SBC_ssm} 180 174 \end{table} 181 %-------------------------------------------------------------------------------------------------------------- 182 183 %\colorbox{yellow}{Penser a} mettre dans le restant l'info nn{\_}fsbc ET nn{\_}fsbc*rdt de sorte de reinitialiser la moyenne si on change la frequence ou le pdt 184 185 186 % ================================================================ 187 % Input Data 188 % ================================================================ 175 176 %\colorbox{yellow}{Penser a} mettre dans le restant l'info nn\_fsbc ET nn\_fsbc*rdt de sorte de reinitialiser la moyenne si on change la frequence ou le pdt 177 178 %% ================================================================================================= 189 179 \section{Input data generic interface} 190 180 \label{sec:SBC_input} 191 181 192 182 A generic interface has been introduced to manage the way input data 193 (2D or 3D fields, like surface forcing or ocean T and S) are specif yin \NEMO.194 This task is a rchieved by \mdl{fldread}.195 The module was design with four main objectives in mind:183 (2D or 3D fields, like surface forcing or ocean T and S) are specified in \NEMO. 184 This task is achieved by \mdl{fldread}. 185 The module is designed with four main objectives in mind: 196 186 \begin{enumerate} 197 \item 198 optionally provide a time interpolation of the input data at model time-step, whatever their input frequency is, 187 \item optionally provide a time interpolation of the input data every specified model time-step, whatever their input frequency is, 199 188 and according to the different calendars available in the model. 200 \item 201 optionally provide an on-the-fly space interpolation from the native input data grid to the model grid. 202 \item 203 make the run duration independent from the period cover by the input files. 204 \item 205 provide a simple user interface and a rather simple developer interface by 206 limiting the number of prerequisite information. 207 \end{enumerate} 208 209 As a results the user have only to fill in for each variable a structure in the namelist file to 189 \item optionally provide an on-the-fly space interpolation from the native input data grid to the model grid. 190 \item make the run duration independent from the period cover by the input files. 191 \item provide a simple user interface and a rather simple developer interface by 192 limiting the number of prerequisite informations. 193 \end{enumerate} 194 195 As a result, the user has only to fill in for each variable a structure in the namelist file to 210 196 define the input data file and variable names, the frequency of the data (in hours or months), 211 197 whether its is climatological data or not, the period covered by the input file (one year, month, week or day), 212 and three additional parameters for on-the-fly interpolation.198 and three additional parameters for the on-the-fly interpolation. 213 199 When adding a new input variable, the developer has to add the associated structure in the namelist, 214 200 read this information by mirroring the namelist read in \rou{sbc\_blk\_init} for example, 215 201 and simply call \rou{fld\_read} to obtain the desired input field at the model time-step and grid points. 216 202 217 The only constraints are that the input file is a NetCDF file, the file name follows a nomenclature 203 The only constraints are that the input file is a NetCDF file, the file name follows a nomenclature 218 204 (see \autoref{subsec:SBC_fldread}), the period it cover is one year, month, week or day, and, 219 205 if on-the-fly interpolation is used, a file of weights must be supplied (see \autoref{subsec:SBC_iof}). 220 206 221 207 Note that when an input data is archived on a disc which is accessible directly from the workspace where 222 the code is executed, then the use can set the \np{cn\_dir} to the pathway leading to the data. 223 By default, the data are assumed to have been copied so that cn\_dir='./'. 224 225 % ------------------------------------------------------------------------------------------------------------- 226 % Input Data specification (\mdl{fldread}) 227 % ------------------------------------------------------------------------------------------------------------- 228 \subsection{Input data specification (\protect\mdl{fldread})} 208 the code is executed, then the user can set the \np{cn_dir}{cn\_dir} to the pathway leading to the data. 209 By default, the data are assumed to be in the same directory as the executable, so that cn\_dir='./'. 210 211 %% ================================================================================================= 212 \subsection[Input data specification (\textit{fldread.F90})]{Input data specification (\protect\mdl{fldread})} 229 213 \label{subsec:SBC_fldread} 230 214 231 215 The structure associated with an input variable contains the following information: 232 216 \begin{forlines} 233 ! file name ! frequency (hours) ! variable ! time interp. ! clim ! 'yearly'/ ! weights ! rotation ! land/sea mask ! 217 ! file name ! frequency (hours) ! variable ! time interp. ! clim ! 'yearly'/ ! weights ! rotation ! land/sea mask ! 234 218 ! ! (if <0 months) ! name ! (logical) ! (T/F) ! 'monthly' ! filename ! pairing ! filename ! 235 219 \end{forlines} 236 where 237 \begin{description} 238 \item[File name]: 239 the stem name of the NetCDF file to be open. 220 where 221 \begin{description} 222 \item [File name]: the stem name of the NetCDF file to be opened. 240 223 This stem will be completed automatically by the model, with the addition of a '.nc' at its end and 241 224 by date information and possibly a prefix (when using AGRIF). 242 Tab.\autoref{tab:fldread} provides the resulting file name in all possible cases according to225 \autoref{tab:SBC_fldread} provides the resulting file name in all possible cases according to 243 226 whether it is a climatological file or not, and to the open/close frequency (see below for definition). 244 245 %--------------------------------------------------TABLE--------------------------------------------------246 227 \begin{table}[htbp] 247 \begin{center} 248 \begin{tabular}{|l|c|c|c|} 249 \hline 250 & daily or weekLLL & monthly & yearly \\ \hline 251 \np{clim}\forcode{ = .false.} & fn\_yYYYYmMMdDD.nc & fn\_yYYYYmMM.nc & fn\_yYYYY.nc \\ \hline 252 \np{clim}\forcode{ = .true.} & not possible & fn\_m??.nc & fn \\ \hline 253 \end{tabular} 254 \end{center} 255 \caption{ 256 \protect\label{tab:fldread} 257 naming nomenclature for climatological or interannual input file, as a function of the Open/close frequency. 228 \centering 229 \begin{tabular}{|l|c|c|c|} 230 \hline 231 & daily or weekLL & monthly & yearly \\ 232 \hline 233 \np[=.false.]{clim}{clim} & fn\_yYYYYmMMdDD.nc & fn\_yYYYYmMM.nc & fn\_yYYYY.nc \\ 234 \hline 235 \np[=.true.]{clim}{clim} & not possible & fn\_m??.nc & fn \\ 236 \hline 237 \end{tabular} 238 \caption[Naming nomenclature for climatological or interannual input file]{ 239 Naming nomenclature for climatological or interannual input file, 240 as a function of the open/close frequency. 258 241 The stem name is assumed to be 'fn'. 259 242 For weekly files, the 'LLL' corresponds to the first three letters of the first day of the week 260 (\ie 'sun','sat','fri','thu','wed','tue','mon'). 261 The 'YYYY', 'MM' and 'DD' should be replaced by the actual year/month/day, always coded with 4 or 2 digits. 262 Note that (1) in mpp, if the file is split over each subdomain, the suffix '.nc' is replaced by '\_PPPP.nc', 243 (\ie\ 'sun','sat','fri','thu','wed','tue','mon'). 244 The 'YYYY', 'MM' and 'DD' should be replaced by the actual year/month/day, 245 always coded with 4 or 2 digits. 246 Note that (1) in mpp, if the file is split over each subdomain, 247 the suffix '.nc' is replaced by '\_PPPP.nc', 263 248 where 'PPPP' is the process number coded with 4 digits; 264 (2) when using AGRIF, the prefix '\_N' is added to files, where 'N' 249 (2) when using AGRIF, the prefix '\_N' is added to files, where 'N' is the child grid number. 265 250 } 251 \label{tab:SBC_fldread} 266 252 \end{table} 267 %-------------------------------------------------------------------------------------------------------------- 268 269 270 \item[Record frequency]: 271 the frequency of the records contained in the input file. 253 \item [Record frequency]: the frequency of the records contained in the input file. 272 254 Its unit is in hours if it is positive (for example 24 for daily forcing) or in months if negative 273 255 (for example -1 for monthly forcing or -12 for annual forcing). 274 Note that this frequency must really be an integer and not a real. 275 On some computers, seting it to '24.' can be interpreted as 240! 276 277 \item[Variable name]: 278 the name of the variable to be read in the input NetCDF file. 279 280 \item[Time interpolation]: 281 a logical to activate, or not, the time interpolation. 256 Note that this frequency must REALLY be an integer and not a real. 257 On some computers, setting it to '24.' can be interpreted as 240! 258 \item [Variable name]: the name of the variable to be read in the input NetCDF file. 259 \item [Time interpolation]: a logical to activate, or not, the time interpolation. 282 260 If set to 'false', the forcing will have a steplike shape remaining constant during each forcing period. 283 261 For example, when using a daily forcing without time interpolation, the forcing remaining constant from 284 262 00h00'00'' to 23h59'59". 285 263 If set to 'true', the forcing will have a broken line shape. 286 Records are assumed to be dated the middle of the forcing period.264 Records are assumed to be dated at the middle of the forcing period. 287 265 For example, when using a daily forcing with time interpolation, 288 linear interpolation will be performed between mid-day of two consecutive days. 289 290 \item[Climatological forcing]: 291 a logical to specify if a input file contains climatological forcing which can be cycle in time, 266 linear interpolation will be performed between mid-day of two consecutive days. 267 \item [Climatological forcing]: a logical to specify if a input file contains climatological forcing which can be cycle in time, 292 268 or an interannual forcing which will requires additional files if 293 the period covered by the simulation exceed the one of the file. 294 See the above the file naming strategy which impacts the expected name of the file to be opened. 295 296 \item[Open/close frequency]: 297 the frequency at which forcing files must be opened/closed. 269 the period covered by the simulation exceeds the one of the file. 270 See the above file naming strategy which impacts the expected name of the file to be opened. 271 \item [Open/close frequency]: the frequency at which forcing files must be opened/closed. 298 272 Four cases are coded: 299 273 'daily', 'weekLLL' (with 'LLL' the first 3 letters of the first day of the week), 'monthly' and 'yearly' which … … 301 275 Files are assumed to contain data from the beginning of the open/close period. 302 276 For example, the first record of a yearly file containing daily data is Jan 1st even if 303 the experiment is not starting at the beginning of the year. 304 305 \item[Others]: 306 'weights filename', 'pairing rotation' and 'land/sea mask' are associated with 277 the experiment is not starting at the beginning of the year. 278 \item [Others]: 'weights filename', 'pairing rotation' and 'land/sea mask' are associated with 307 279 on-the-fly interpolation which is described in \autoref{subsec:SBC_iof}. 308 309 280 \end{description} 310 281 … … 313 284 The only tricky point is therefore to specify the date at which we need to do the interpolation and 314 285 the date of the records read in the input files. 315 Following \citet{ Leclair_Madec_OM09}, the date of a time step is set at the middle of the time step.316 For example, for an experiment starting at 0h00'00" with a one 286 Following \citet{leclair.madec_OM09}, the date of a time step is set at the middle of the time step. 287 For example, for an experiment starting at 0h00'00" with a one-hour time-step, 317 288 a time interpolation will be performed at the following time: 0h30'00", 1h30'00", 2h30'00", etc. 318 289 However, for forcing data related to the surface module, 319 values are not needed at every time-step but at every \np{nn \_fsbc} time-step.320 For example with \np {nn\_fsbc}\forcode{ = 3}, the surface module will be called at time-steps 1, 4, 7, etc.321 The date used for the time interpolation is thus redefined to be at the middle of \np{nn\_fsbc} time-step period.322 In the previous example, this leads to: 1h30'00", 4h30'00", 7h30'00", etc. \\ 290 values are not needed at every time-step but at every \np{nn_fsbc}{nn\_fsbc} time-step. 291 For example with \np[=3]{nn_fsbc}{nn\_fsbc}, the surface module will be called at time-steps 1, 4, 7, etc. 292 The date used for the time interpolation is thus redefined to the middle of \np{nn_fsbc}{nn\_fsbc} time-step period. 293 In the previous example, this leads to: 1h30'00", 4h30'00", 7h30'00", etc. \\ 323 294 (2) For code readablility and maintenance issues, we don't take into account the NetCDF input file calendar. 324 295 The calendar associated with the forcing field is build according to the information provided by 325 296 user in the record frequency, the open/close frequency and the type of temporal interpolation. 326 297 For example, the first record of a yearly file containing daily data that will be interpolated in time is assumed to 327 bestart Jan 1st at 12h00'00" and end Dec 31st at 12h00'00". \\298 start Jan 1st at 12h00'00" and end Dec 31st at 12h00'00". \\ 328 299 (3) If a time interpolation is requested, the code will pick up the needed data in the previous (next) file when 329 300 interpolating data with the first (last) record of the open/close period. 330 For example, if the input file specifications are ''yearly, containing daily data to be interpolated in time'', 301 For example, if the input file specifications are ''yearly, containing daily data to be interpolated in time'', 331 302 the values given by the code between 00h00'00" and 11h59'59" on Jan 1st will be interpolated values between 332 303 Dec 31st 12h00'00" and Jan 1st 12h00'00". 333 304 If the forcing is climatological, Dec and Jan will be keep-up from the same year. 334 305 However, if the forcing is not climatological, at the end of 335 the open/close period the code will automatically close the current file and open the next one.306 the open/close period, the code will automatically close the current file and open the next one. 336 307 Note that, if the experiment is starting (ending) at the beginning (end) of 337 an open/close period we do accept that the previous (next) file is not existing.308 an open/close period, we do accept that the previous (next) file is not existing. 338 309 In this case, the time interpolation will be performed between two identical values. 339 310 For example, when starting an experiment on Jan 1st of year Y with yearly files and daily data to be interpolated, 340 311 we do accept that the file related to year Y-1 is not existing. 341 312 The value of Jan 1st will be used as the missing one for Dec 31st of year Y-1. 342 If the file of year Y-1 exists, the code will read its last record. 313 If the file of year Y-1 exists, the code will read its last record. 343 314 Therefore, this file can contain only one record corresponding to Dec 31st, 344 315 a useful feature for user considering that it is too heavy to manipulate the complete file for year Y-1. 345 316 346 347 % ------------------------------------------------------------------------------------------------------------- 348 % Interpolation on the Fly 349 % ------------------------------------------------------------------------------------------------------------- 317 %% ================================================================================================= 350 318 \subsection{Interpolation on-the-fly} 351 319 \label{subsec:SBC_iof} … … 353 321 Interpolation on the Fly allows the user to supply input files required for the surface forcing on 354 322 grids other than the model grid. 355 To do this he or she must supply, in addition to the source data file, a file of weights to be used to323 To do this, he or she must supply, in addition to the source data file(s), a file of weights to be used to 356 324 interpolate from the data grid to the model grid. 357 325 The original development of this code used the SCRIP package 358 326 (freely available \href{http://climate.lanl.gov/Software/SCRIP}{here} under a copyright agreement). 359 In principle, any package can be used to generate the weights, but the variables in327 In principle, any package such as CDO can be used to generate the weights, but the variables in 360 328 the input weights file must have the same names and meanings as assumed by the model. 361 Two methods are currently available: bilinear and bicubic interpolation .329 Two methods are currently available: bilinear and bicubic interpolations. 362 330 Prior to the interpolation, providing a land/sea mask file, the user can decide to remove land points from 363 331 the input file and substitute the corresponding values with the average of the 8 neighbouring points in … … 365 333 Only "sea points" are considered for the averaging. 366 334 The land/sea mask file must be provided in the structure associated with the input variable. 367 The netcdf land/sea mask variable name must be 'LSM' it must have the same horizontal and vertical dimensions of 368 the associated variable and should be equal to 1 over land and 0 elsewhere. 369 The procedure can be recursively applied setting nn\_lsm > 1 in namsbc namelist. 370 Note that nn\_lsm=0 forces the code to not apply the procedure even if a file for land/sea mask is supplied. 371 335 The netcdf land/sea mask variable name must be 'LSM' and must have the same horizontal and vertical dimensions as 336 the associated variables and should be equal to 1 over land and 0 elsewhere. 337 The procedure can be recursively applied by setting nn\_lsm > 1 in namsbc namelist. 338 Note that nn\_lsm=0 forces the code to not apply the procedure, even if a land/sea mask file is supplied. 339 340 %% ================================================================================================= 372 341 \subsubsection{Bilinear interpolation} 373 342 \label{subsec:SBC_iof_bilinear} … … 375 344 The input weights file in this case has two sets of variables: 376 345 src01, src02, src03, src04 and wgt01, wgt02, wgt03, wgt04. 377 The "src" variables correspond to the point in the input grid to which the weight "wgt" is to beapplied.346 The "src" variables correspond to the point in the input grid to which the weight "wgt" is applied. 378 347 Each src value is an integer corresponding to the index of a point in the input grid when 379 348 written as a one dimensional array. … … 391 360 and wgt(1) corresponds to variable "wgt01" for example. 392 361 362 %% ================================================================================================= 393 363 \subsubsection{Bicubic interpolation} 394 364 \label{subsec:SBC_iof_bicubic} 395 365 396 Again there are two sets of variables: "src" and "wgt".397 But in this case there are 16 of each.366 Again, there are two sets of variables: "src" and "wgt". 367 But in this case, there are 16 of each. 398 368 The symbolic algorithm used to calculate values on the model grid is now: 399 369 … … 401 371 \begin{split} 402 372 f_{m}(i,j) = f_{m}(i,j) +& \sum_{k=1}^{4} {wgt(k)f(idx(src(k)))} 403 + \sum_{k=5}^{8} {wgt(k)\left.\frac{\partial f}{\partial i}\right| _{idx(src(k))} } \\404 +& \sum_{k=9 }^{12} {wgt(k)\left.\frac{\partial f}{\partial j}\right| _{idx(src(k))} }405 + 373 + \sum_{k=5 }^{8 } {wgt(k)\left.\frac{\partial f}{\partial i}\right| _{idx(src(k))} } \\ 374 +& \sum_{k=9 }^{12} {wgt(k)\left.\frac{\partial f}{\partial j}\right| _{idx(src(k))} } 375 + \sum_{k=13}^{16} {wgt(k)\left.\frac{\partial ^2 f}{\partial i \partial j}\right| _{idx(src(k))} } 406 376 \end{split} 407 377 \] 408 378 The gradients here are taken with respect to the horizontal indices and not distances since 409 the spatial dependency has been absorbed into the weights. 410 379 the spatial dependency has been included into the weights. 380 381 %% ================================================================================================= 411 382 \subsubsection{Implementation} 412 383 \label{subsec:SBC_iof_imp} … … 420 391 inspecting a global attribute stored in the weights input file. 421 392 This attribute must be called "ew\_wrap" and be of integer type. 422 If it is negative, the input non-model grid is assumed not to becyclic.393 If it is negative, the input non-model grid is assumed to be not cyclic. 423 394 If zero or greater, then the value represents the number of columns that overlap. 424 395 $E.g.$ if the input grid has columns at longitudes 0, 1, 2, .... , 359, then ew\_wrap should be set to 0; 425 396 if longitudes are 0.5, 2.5, .... , 358.5, 360.5, 362.5, ew\_wrap should be 2. 426 397 If the model does not find attribute ew\_wrap, then a value of -999 is assumed. 427 In this case the \rou{fld\_read} routine defaults ew\_wrap to value 0 and398 In this case, the \rou{fld\_read} routine defaults ew\_wrap to value 0 and 428 399 therefore the grid is assumed to be cyclic with no overlapping columns. 429 (In fact this only matters when bicubic interpolation is required.)400 (In fact, this only matters when bicubic interpolation is required.) 430 401 Note that no testing is done to check the validity in the model, 431 402 since there is no way of knowing the name used for the longitude variable, … … 444 415 or is a copy of one from the first few columns on the opposite side of the grid (cyclical case). 445 416 417 %% ================================================================================================= 446 418 \subsubsection{Limitations} 447 419 \label{subsec:SBC_iof_lim} 448 420 449 \begin{enumerate} 450 \item 451 The case where input data grids are not logically rectangular has not been tested. 452 \item 453 This code is not guaranteed to produce positive definite answers from positive definite inputs when 421 \begin{enumerate} 422 \item The case where input data grids are not logically rectangular (irregular grid case) has not been tested. 423 \item This code is not guaranteed to produce positive definite answers from positive definite inputs when 454 424 a bicubic interpolation method is used. 455 \item 456 The cyclic condition is only applied on left and right columns, and not to top and bottom rows. 457 \item 458 The gradients across the ends of a cyclical grid assume that the grid spacing between 425 \item The cyclic condition is only applied on left and right columns, and not to top and bottom rows. 426 \item The gradients across the ends of a cyclical grid assume that the grid spacing between 459 427 the two columns involved are consistent with the weights used. 460 \item 461 Neither interpolation scheme is conservative. (There is a conservative scheme available in SCRIP, 428 \item Neither interpolation scheme is conservative. (There is a conservative scheme available in SCRIP, 462 429 but this has not been implemented.) 463 430 \end{enumerate} 464 431 432 %% ================================================================================================= 465 433 \subsubsection{Utilities} 466 434 \label{subsec:SBC_iof_util} … … 470 438 (see the directory NEMOGCM/TOOLS/WEIGHTS). 471 439 472 % ------------------------------------------------------------------------------------------------------------- 473 % Standalone Surface Boundary Condition Scheme 474 % ------------------------------------------------------------------------------------------------------------- 475 \subsection{Standalone surface boundary condition scheme} 476 \label{subsec:SAS_iof} 477 478 %---------------------------------------namsbc_ana-------------------------------------------------- 479 480 \nlst{namsbc_sas} 481 %-------------------------------------------------------------------------------------------------------------- 482 483 In some circumstances it may be useful to avoid calculating the 3D temperature, 484 salinity and velocity fields and simply read them in from a previous run or receive them from OASIS. 440 %% ================================================================================================= 441 \subsection{Standalone surface boundary condition scheme (SAS)} 442 \label{subsec:SBC_SAS} 443 444 \begin{listing} 445 \nlst{namsbc_sas} 446 \caption{\forcode{&namsbc_sas}} 447 \label{lst:namsbc_sas} 448 \end{listing} 449 450 In some circumstances, it may be useful to avoid calculating the 3D temperature, 451 salinity and velocity fields and simply read them in from a previous run or receive them from OASIS. 485 452 For example: 486 453 487 454 \begin{itemize} 488 \item 489 Multiple runs of the model are required in code development to 455 \item Multiple runs of the model are required in code development to 490 456 see the effect of different algorithms in the bulk formulae. 491 \item 492 The effect of different parameter sets in the ice model is to be examined. 493 \item 494 Development of sea-ice algorithms or parameterizations. 495 \item 496 Spinup of the iceberg floats 497 \item 498 Ocean/sea-ice simulation with both media running in parallel (\np{ln\_mixcpl}\forcode{ = .true.}) 457 \item The effect of different parameter sets in the ice model is to be examined. 458 \item Development of sea-ice algorithms or parameterizations. 459 \item Spinup of the iceberg floats 460 \item Ocean/sea-ice simulation with both models running in parallel (\np[=.true.]{ln_mixcpl}{ln\_mixcpl}) 499 461 \end{itemize} 500 462 501 The Stand Alone Surface scheme provides this utility.502 Its options are defined through the \n gn{namsbc\_sas} namelist variables.463 The Standalone Surface scheme provides this capacity. 464 Its options are defined through the \nam{sbc_sas}{sbc\_sas} namelist variables. 503 465 A new copy of the model has to be compiled with a configuration based on ORCA2\_SAS\_LIM. 504 However no namelist parameters need be changed from the settings of the previous run (except perhaps nn{\_}date0).466 However, no namelist parameters need be changed from the settings of the previous run (except perhaps nn\_date0). 505 467 In this configuration, a few routines in the standard model are overriden by new versions. 506 468 Routines replaced are: 507 469 508 470 \begin{itemize} 509 \item 510 \mdl{nemogcm}: 511 This routine initialises the rest of the model and repeatedly calls the stp time stepping routine (\mdl{step}). 471 \item \mdl{nemogcm}: This routine initialises the rest of the model and repeatedly calls the stp time stepping routine (\mdl{step}). 512 472 Since the ocean state is not calculated all associated initialisations have been removed. 513 \item 514 \mdl{step}: 515 The main time stepping routine now only needs to call the sbc routine (and a few utility functions). 516 \item 517 \mdl{sbcmod}: 518 This has been cut down and now only calculates surface forcing and the ice model required. 473 \item \mdl{step}: The main time stepping routine now only needs to call the sbc routine (and a few utility functions). 474 \item \mdl{sbcmod}: This has been cut down and now only calculates surface forcing and the ice model required. 519 475 New surface modules that can function when only the surface level of the ocean state is defined can also be added 520 (\eg icebergs). 521 \item 522 \mdl{daymod}: 523 No ocean restarts are read or written (though the ice model restarts are retained), 476 (\eg\ icebergs). 477 \item \mdl{daymod}: No ocean restarts are read or written (though the ice model restarts are retained), 524 478 so calls to restart functions have been removed. 525 479 This also means that the calendar cannot be controlled by time in a restart file, 526 so the user must make sure that nn{\_}date0 in the model namelist is correct for his or her purposes. 527 \item 528 \mdl{stpctl}: 529 Since there is no free surface solver, references to it have been removed from \rou{stp\_ctl} module. 530 \item 531 \mdl{diawri}: 532 All 3D data have been removed from the output. 480 so the user must check that nn\_date0 in the model namelist is correct for his or her purposes. 481 \item \mdl{stpctl}: Since there is no free surface solver, references to it have been removed from \rou{stp\_ctl} module. 482 \item \mdl{diawri}: All 3D data have been removed from the output. 533 483 The surface temperature, salinity and velocity components (which have been read in) are written along with 534 484 relevant forcing and ice data. … … 538 488 539 489 \begin{itemize} 540 \item 541 \mdl{sbcsas}: 542 This module initialises the input files needed for reading temperature, salinity and 490 \item \mdl{sbcsas}: This module initialises the input files needed for reading temperature, salinity and 543 491 velocity arrays at the surface. 544 These filenames are supplied in namelist namsbc {\_}sas.545 Unfortunately because of limitations with the \mdl{iom} module,492 These filenames are supplied in namelist namsbc\_sas. 493 Unfortunately, because of limitations with the \mdl{iom} module, 546 494 the full 3D fields from the mean files have to be read in and interpolated in time, 547 495 before using just the top level. … … 549 497 \end{itemize} 550 498 551 552 % Missing the description of the 2 following variables: 553 % ln_3d_uve = .true. ! specify whether we are supplying a 3D u,v and e3 field 554 % ln_read_frq = .false. ! specify whether we must read frq or not 555 556 557 558 % ================================================================ 559 % Analytical formulation (sbcana module) 560 % ================================================================ 561 \section{Analytical formulation (\protect\mdl{sbcana})} 562 \label{sec:SBC_ana} 563 564 %---------------------------------------namsbc_ana-------------------------------------------------- 565 % 566 %\nlst{namsbc_ana} 567 %-------------------------------------------------------------------------------------------------------------- 568 569 The analytical formulation of the surface boundary condition is the default scheme. 570 In this case, all the six fluxes needed by the ocean are assumed to be uniform in space. 571 They take constant values given in the namelist \ngn{namsbc{\_}ana} by 572 the variables \np{rn\_utau0}, \np{rn\_vtau0}, \np{rn\_qns0}, \np{rn\_qsr0}, and \np{rn\_emp0} 573 ($\textit{emp}=\textit{emp}_S$). 574 The runoff is set to zero. 575 In addition, the wind is allowed to reach its nominal value within a given number of time steps (\np{nn\_tau000}). 576 577 If a user wants to apply a different analytical forcing, 578 the \mdl{sbcana} module can be modified to use another scheme. 579 As an example, the \mdl{sbc\_ana\_gyre} routine provides the analytical forcing for the GYRE configuration 580 (see GYRE configuration manual, in preparation). 581 582 583 % ================================================================ 584 % Flux formulation 585 % ================================================================ 586 \section{Flux formulation (\protect\mdl{sbcflx})} 499 The user can also choose in the \nam{sbc_sas}{sbc\_sas} namelist to read the mean (nn\_fsbc time-step) fraction of solar net radiation absorbed in the 1st T level using 500 (\np[=.true.]{ln_flx}{ln\_flx}) and to provide 3D oceanic velocities instead of 2D ones (\np{ln_flx}{ln\_flx}\forcode{=.true.}). In that last case, only the 1st level will be read in. 501 502 %% ================================================================================================= 503 \section[Flux formulation (\textit{sbcflx.F90})]{Flux formulation (\protect\mdl{sbcflx})} 587 504 \label{sec:SBC_flx} 588 %------------------------------------------namsbc_flx---------------------------------------------------- 589 590 \nlst{namsbc_flx} 591 %------------------------------------------------------------------------------------------------------------- 592 593 In the flux formulation (\np{ln\_flx}\forcode{ = .true.}), 505 506 \begin{listing} 507 \nlst{namsbc_flx} 508 \caption{\forcode{&namsbc_flx}} 509 \label{lst:namsbc_flx} 510 \end{listing} 511 512 In the flux formulation (\np[=.true.]{ln_flx}{ln\_flx}), 594 513 the surface boundary condition fields are directly read from input files. 595 The user has to define in the namelist \n gn{namsbc{\_}flx} the name of the file,514 The user has to define in the namelist \nam{sbc_flx}{sbc\_flx} the name of the file, 596 515 the name of the variable read in the file, the time frequency at which it is given (in hours), 597 516 and a logical setting whether a time interpolation to the model time step is required for this field. … … 601 520 See \autoref{subsec:SBC_ssr} for its specification. 602 521 603 604 % ================================================================ 605 % Bulk formulation 606 % ================================================================ 607 \section[Bulk formulation {(\textit{sbcblk\{\_core,\_clio\}.F90})}] 608 {Bulk formulation {(\protect\mdl{sbcblk\_core}, \protect\mdl{sbcblk\_clio})}} 522 %% ================================================================================================= 523 \section[Bulk formulation (\textit{sbcblk.F90})]{Bulk formulation (\protect\mdl{sbcblk})} 609 524 \label{sec:SBC_blk} 610 525 611 In the bulk formulation, the surface boundary condition fields are computed using bulk formulae and atmospheric fields and ocean (and ice) variables. 526 \begin{listing} 527 \nlst{namsbc_blk} 528 \caption{\forcode{&namsbc_blk}} 529 \label{lst:namsbc_blk} 530 \end{listing} 531 532 In the bulk formulation, the surface boundary condition fields are computed with bulk formulae using atmospheric fields 533 and ocean (and sea-ice) variables averaged over \np{nn_fsbc}{nn\_fsbc} time-step. 612 534 613 535 The atmospheric fields used depend on the bulk formulae used. 614 Two bulk formulations are available: 615 the CORE and the CLIO bulk formulea. 536 In forced mode, when a sea-ice model is used, a specific bulk formulation is used. 537 Therefore, different bulk formulae are used for the turbulent fluxes computation 538 over the ocean and over sea-ice surface. 539 For the ocean, four bulk formulations are available thanks to the \href{https://brodeau.github.io/aerobulk/}{Aerobulk} package (\citet{brodeau.barnier.ea_JPO16}): 540 the NCAR (formerly named CORE), COARE 3.0, COARE 3.5 and ECMWF bulk formulae. 616 541 The choice is made by setting to true one of the following namelist variable: 617 \np{ln\_core} or \np{ln\_clio}. 618 619 Note: 620 in forced mode, when a sea-ice model is used, a bulk formulation (CLIO or CORE) have to be used. 621 Therefore the two bulk (CLIO and CORE) formulea include the computation of the fluxes over 622 both an ocean and an ice surface. 623 624 % ------------------------------------------------------------------------------------------------------------- 625 % CORE Bulk formulea 626 % ------------------------------------------------------------------------------------------------------------- 627 \subsection{CORE formulea (\protect\mdl{sbcblk\_core}, \protect\np{ln\_core}\forcode{ = .true.})} 628 \label{subsec:SBC_blk_core} 629 %------------------------------------------namsbc_core---------------------------------------------------- 630 % 631 %\nlst{namsbc_core} 632 %------------------------------------------------------------------------------------------------------------- 633 634 The CORE bulk formulae have been developed by \citet{Large_Yeager_Rep04}. 635 They have been designed to handle the CORE forcing, a mixture of NCEP reanalysis and satellite data. 636 They use an inertial dissipative method to compute the turbulent transfer coefficients 637 (momentum, sensible heat and evaporation) from the 10 metre wind speed, air temperature and specific humidity. 638 This \citet{Large_Yeager_Rep04} dataset is available through 639 the \href{http://nomads.gfdl.noaa.gov/nomads/forms/mom4/CORE.html}{GFDL web site}. 640 641 Note that substituting ERA40 to NCEP reanalysis fields does not require changes in the bulk formulea themself. 642 This is the so-called DRAKKAR Forcing Set (DFS) \citep{Brodeau_al_OM09}. 643 644 Options are defined through the \ngn{namsbc\_core} namelist variables. 645 The required 8 input fields are: 646 647 %--------------------------------------------------TABLE-------------------------------------------------- 542 \np{ln_NCAR}{ln\_NCAR}, \np{ln_COARE_3p0}{ln\_COARE\_3p0}, \np{ln_COARE_3p5}{ln\_COARE\_3p5} and \np{ln_ECMWF}{ln\_ECMWF}. 543 For sea-ice, three possibilities can be selected: 544 a constant transfer coefficient (1.4e-3; default value), \citet{lupkes.gryanik.ea_JGR12} (\np{ln_Cd_L12}{ln\_Cd\_L12}), and \citet{lupkes.gryanik_JGR15} (\np{ln_Cd_L15}{ln\_Cd\_L15}) parameterizations 545 546 Common options are defined through the \nam{sbc_blk}{sbc\_blk} namelist variables. 547 The required 9 input fields are: 548 648 549 \begin{table}[htbp] 649 \label{tab:CORE} 650 \begin{center} 651 \begin{tabular}{|l|c|c|c|} 652 \hline 653 Variable desciption & Model variable & Units & point \\ \hline 654 i-component of the 10m air velocity & utau & $m.s^{-1}$ & T \\ \hline 655 j-component of the 10m air velocity & vtau & $m.s^{-1}$ & T \\ \hline 656 10m air temperature & tair & \r{}$K$ & T \\ \hline 657 Specific humidity & humi & \% & T \\ \hline 658 Incoming long wave radiation & qlw & $W.m^{-2}$ & T \\ \hline 659 Incoming short wave radiation & qsr & $W.m^{-2}$ & T \\ \hline 660 Total precipitation (liquid + solid) & precip & $Kg.m^{-2}.s^{-1}$ & T \\ \hline 661 Solid precipitation & snow & $Kg.m^{-2}.s^{-1}$ & T \\ \hline 550 \centering 551 \begin{tabular}{|l|c|c|c|} 552 \hline 553 Variable description & Model variable & Units & point \\ 554 \hline 555 i-component of the 10m air velocity & utau & $m.s^{-1}$ & T \\ 556 \hline 557 j-component of the 10m air velocity & vtau & $m.s^{-1}$ & T \\ 558 \hline 559 10m air temperature & tair & \r{}$K$ & T \\ 560 \hline 561 Specific humidity & humi & \% & T \\ 562 \hline 563 Incoming long wave radiation & qlw & $W.m^{-2}$ & T \\ 564 \hline 565 Incoming short wave radiation & qsr & $W.m^{-2}$ & T \\ 566 \hline 567 Total precipitation (liquid + solid) & precip & $Kg.m^{-2}.s^{-1}$ & T \\ 568 \hline 569 Solid precipitation & snow & $Kg.m^{-2}.s^{-1}$ & T \\ 570 \hline 571 Mean sea-level pressure & slp & $hPa$ & T \\ 572 \hline 662 573 \end{tabular} 663 \ end{center}574 \label{tab:SBC_BULK} 664 575 \end{table} 665 %--------------------------------------------------------------------------------------------------------------666 576 667 577 Note that the air velocity is provided at a tracer ocean point, not at a velocity ocean point ($u$- and $v$-points). … … 669 579 the ocean grid size is the same or larger than the one of the input atmospheric fields. 670 580 671 The \np{sn \_wndi}, \np{sn\_wndj}, \np{sn\_qsr}, \np{sn\_qlw}, \np{sn\_tair}, \np{sn\_humi}, \np{sn\_prec},672 \np{sn \_snow}, \np{sn\_tdif} parameters describe the fields and the way they have to be used673 (spatial and temporal interpolations). 674 675 \np{cn \_dir} is the directory of location of bulk files676 \np{ln \_taudif} is the flag to specify if we use Hight Frequency (HF) tau information (.true.) or not (.false.)677 \np{rn \_zqt}: is the height of humidity and temperature measurements (m)678 \np{rn \_zu}: is the height of wind measurements (m)679 680 Three multiplicative factors are available s:681 \np{rn \_pfac} and \np{rn\_efac} allowsto adjust (if necessary) the global freshwater budget by581 The \np{sn_wndi}{sn\_wndi}, \np{sn_wndj}{sn\_wndj}, \np{sn_qsr}{sn\_qsr}, \np{sn_qlw}{sn\_qlw}, \np{sn_tair}{sn\_tair}, \np{sn_humi}{sn\_humi}, \np{sn_prec}{sn\_prec}, 582 \np{sn_snow}{sn\_snow}, \np{sn_tdif}{sn\_tdif} parameters describe the fields and the way they have to be used 583 (spatial and temporal interpolations). 584 585 \np{cn_dir}{cn\_dir} is the directory of location of bulk files 586 \np{ln_taudif}{ln\_taudif} is the flag to specify if we use Hight Frequency (HF) tau information (.true.) or not (.false.) 587 \np{rn_zqt}{rn\_zqt}: is the height of humidity and temperature measurements (m) 588 \np{rn_zu}{rn\_zu}: is the height of wind measurements (m) 589 590 Three multiplicative factors are available: 591 \np{rn_pfac}{rn\_pfac} and \np{rn_efac}{rn\_efac} allow to adjust (if necessary) the global freshwater budget by 682 592 increasing/reducing the precipitations (total and snow) and or evaporation, respectively. 683 The third one,\np{rn \_vfac}, control to which extend the ice/ocean velocities are taken into account in593 The third one,\np{rn_vfac}{rn\_vfac}, control to which extend the ice/ocean velocities are taken into account in 684 594 the calculation of surface wind stress. 685 Its range should be between zero and one, and it is recommended to set it to 0. 686 687 % ------------------------------------------------------------------------------------------------------------- 688 % CLIO Bulk formulea 689 % ------------------------------------------------------------------------------------------------------------- 690 \subsection{CLIO formulea (\protect\mdl{sbcblk\_clio}, \protect\np{ln\_clio}\forcode{ = .true.})} 691 \label{subsec:SBC_blk_clio} 692 %------------------------------------------namsbc_clio---------------------------------------------------- 693 % 694 %\nlst{namsbc_clio} 695 %------------------------------------------------------------------------------------------------------------- 696 697 The CLIO bulk formulae were developed several years ago for the Louvain-la-neuve coupled ice-ocean model 698 (CLIO, \cite{Goosse_al_JGR99}). 699 They are simpler bulk formulae. 700 They assume the stress to be known and compute the radiative fluxes from a climatological cloud cover. 701 702 Options are defined through the \ngn{namsbc\_clio} namelist variables. 703 The required 7 input fields are: 704 705 %--------------------------------------------------TABLE-------------------------------------------------- 706 \begin{table}[htbp] 707 \label{tab:CLIO} 708 \begin{center} 709 \begin{tabular}{|l|l|l|l|} 710 \hline 711 Variable desciption & Model variable & Units & point \\ \hline 712 i-component of the ocean stress & utau & $N.m^{-2}$ & U \\ \hline 713 j-component of the ocean stress & vtau & $N.m^{-2}$ & V \\ \hline 714 Wind speed module & vatm & $m.s^{-1}$ & T \\ \hline 715 10m air temperature & tair & \r{}$K$ & T \\ \hline 716 Specific humidity & humi & \% & T \\ \hline 717 Cloud cover & & \% & T \\ \hline 718 Total precipitation (liquid + solid) & precip & $Kg.m^{-2}.s^{-1}$ & T \\ \hline 719 Solid precipitation & snow & $Kg.m^{-2}.s^{-1}$ & T \\ \hline 720 \end{tabular} 721 \end{center} 722 \end{table} 723 %-------------------------------------------------------------------------------------------------------------- 595 Its range must be between zero and one, and it is recommended to set it to 0 at low-resolution (ORCA2 configuration). 724 596 725 597 As for the flux formulation, information about the input data required by the model is provided in 726 the namsbc\_blk\_core or namsbc\_blk\_clio namelist (see \autoref{subsec:SBC_fldread}). 727 728 % ================================================================ 729 % Coupled formulation 730 % ================================================================ 731 \section{Coupled formulation (\protect\mdl{sbccpl})} 598 the namsbc\_blk namelist (see \autoref{subsec:SBC_fldread}). 599 600 %% ================================================================================================= 601 \subsection[Ocean-Atmosphere Bulk formulae (\textit{sbcblk\_algo\_coare.F90, sbcblk\_algo\_coare3p5.F90, sbcblk\_algo\_ecmwf.F90, sbcblk\_algo\_ncar.F90})]{Ocean-Atmosphere Bulk formulae (\mdl{sbcblk\_algo\_coare}, \mdl{sbcblk\_algo\_coare3p5}, \mdl{sbcblk\_algo\_ecmwf}, \mdl{sbcblk\_algo\_ncar})} 602 \label{subsec:SBC_blk_ocean} 603 604 Four different bulk algorithms are available to compute surface turbulent momentum and heat fluxes over the ocean. 605 COARE 3.0, COARE 3.5 and ECMWF schemes mainly differ by their roughness lenghts computation and consequently 606 their neutral transfer coefficients relationships with neutral wind. 607 \begin{itemize} 608 \item NCAR (\np[=.true.]{ln_NCAR}{ln\_NCAR}): The NCAR bulk formulae have been developed by \citet{large.yeager_rpt04}. 609 They have been designed to handle the NCAR forcing, a mixture of NCEP reanalysis and satellite data. 610 They use an inertial dissipative method to compute the turbulent transfer coefficients 611 (momentum, sensible heat and evaporation) from the 10m wind speed, air temperature and specific humidity. 612 This \citet{large.yeager_rpt04} dataset is available through 613 the \href{http://nomads.gfdl.noaa.gov/nomads/forms/mom4/NCAR.html}{GFDL web site}. 614 Note that substituting ERA40 to NCEP reanalysis fields does not require changes in the bulk formulea themself. 615 This is the so-called DRAKKAR Forcing Set (DFS) \citep{brodeau.barnier.ea_OM10}. 616 \item COARE 3.0 (\np[=.true.]{ln_COARE_3p0}{ln\_COARE\_3p0}): See \citet{fairall.bradley.ea_JC03} for more details 617 \item COARE 3.5 (\np[=.true.]{ln_COARE_3p5}{ln\_COARE\_3p5}): See \citet{edson.jampana.ea_JPO13} for more details 618 \item ECMWF (\np[=.true.]{ln_ECMWF}{ln\_ECMWF}): Based on \href{https://www.ecmwf.int/node/9221}{IFS (Cy31)} implementation and documentation. 619 Surface roughness lengths needed for the Obukhov length are computed following \citet{beljaars_QJRMS95}. 620 \end{itemize} 621 622 %% ================================================================================================= 623 \subsection{Ice-Atmosphere Bulk formulae} 624 \label{subsec:SBC_blk_ice} 625 626 Surface turbulent fluxes between sea-ice and the atmosphere can be computed in three different ways: 627 628 \begin{itemize} 629 \item Constant value (\np[ Cd_ice=1.4e-3 ]{constant value}{constant\ value}): 630 default constant value used for momentum and heat neutral transfer coefficients 631 \item \citet{lupkes.gryanik.ea_JGR12} (\np[=.true.]{ln_Cd_L12}{ln\_Cd\_L12}): 632 This scheme adds a dependency on edges at leads, melt ponds and flows 633 of the constant neutral air-ice drag. After some approximations, 634 this can be resumed to a dependency on ice concentration (A). 635 This drag coefficient has a parabolic shape (as a function of ice concentration) 636 starting at 1.5e-3 for A=0, reaching 1.97e-3 for A=0.5 and going down 1.4e-3 for A=1. 637 It is theoretically applicable to all ice conditions (not only MIZ). 638 \item \citet{lupkes.gryanik_JGR15} (\np[=.true.]{ln_Cd_L15}{ln\_Cd\_L15}): 639 Alternative turbulent transfer coefficients formulation between sea-ice 640 and atmosphere with distinct momentum and heat coefficients depending 641 on sea-ice concentration and atmospheric stability (no melt-ponds effect for now). 642 The parameterization is adapted from ECHAM6 atmospheric model. 643 Compared to Lupkes2012 scheme, it considers specific skin and form drags 644 to compute neutral transfer coefficients for both heat and momentum fluxes. 645 Atmospheric stability effect on transfer coefficient is also taken into account. 646 \end{itemize} 647 648 %% ================================================================================================= 649 \section[Coupled formulation (\textit{sbccpl.F90})]{Coupled formulation (\protect\mdl{sbccpl})} 732 650 \label{sec:SBC_cpl} 733 %------------------------------------------namsbc_cpl---------------------------------------------------- 734 735 \nlst{namsbc_cpl} 736 %------------------------------------------------------------------------------------------------------------- 651 652 \begin{listing} 653 \nlst{namsbc_cpl} 654 \caption{\forcode{&namsbc_cpl}} 655 \label{lst:namsbc_cpl} 656 \end{listing} 737 657 738 658 In the coupled formulation of the surface boundary condition, 739 the fluxes are provided by the OASIS coupler at a frequency which is defined in the OASIS coupler ,659 the fluxes are provided by the OASIS coupler at a frequency which is defined in the OASIS coupler namelist, 740 660 while sea and ice surface temperature, ocean and ice albedo, and ocean currents are sent to 741 661 the atmospheric component. 742 662 743 663 A generalised coupled interface has been developed. 744 It is currently interfaced with OASIS-3-MCT (\key{oasis3}). 745 It has been successfully used to interface \NEMO to most of the European atmospheric GCM 664 It is currently interfaced with OASIS-3-MCT versions 1 to 4 (\key{oasis3}). 665 An additional specific CPP key (\key{oa3mct\_v1v2}) is needed for OASIS-3-MCT versions 1 and 2. 666 It has been successfully used to interface \NEMO\ to most of the European atmospheric GCM 746 667 (ARPEGE, ECHAM, ECMWF, HadAM, HadGAM, LMDz), as well as to \href{http://wrf-model.org/}{WRF} 747 668 (Weather Research and Forecasting Model). 748 669 749 Note that in addition to the setting of \np{ln\_cpl} to true, the \key{coupled} have to be defined. 750 The CPP key is mainly used in sea-ice to ensure that the atmospheric fluxes are actually received by 751 the ice-ocean system (no calculation of ice sublimation in coupled mode). 752 When PISCES biogeochemical model (\key{top} and \key{pisces}) is also used in the coupled system, 753 the whole carbon cycle is computed by defining \key{cpl\_carbon\_cycle}. 670 When PISCES biogeochemical model (\key{top}) is also used in the coupled system, 671 the whole carbon cycle is computed. 754 672 In this case, CO$_2$ fluxes will be exchanged between the atmosphere and the ice-ocean system 755 (and need to be activated in \n gn{namsbc{\_}cpl} ).673 (and need to be activated in \nam{sbc_cpl}{sbc\_cpl} ). 756 674 757 675 The namelist above allows control of various aspects of the coupling fields (particularly for vectors) and 758 676 now allows for any coupling fields to have multiple sea ice categories (as required by LIM3 and CICE). 759 When indicating a multi-category coupling field in namsbc{\_}cplthe number of categories will be determined by677 When indicating a multi-category coupling field in \nam{sbc_cpl}{sbc\_cpl}, the number of categories will be determined by 760 678 the number used in the sea ice model. 761 In some limited cases it may be possible to specify single category coupling fields even when679 In some limited cases, it may be possible to specify single category coupling fields even when 762 680 the sea ice model is running with multiple categories - 763 in this case the user should examine the code to be sure the assumptions made are satisfactory. 764 In cases where this is definitely not possible the model should abort with an error message. 765 The new code has been tested using ECHAM with LIM2, and HadGAM3 with CICE but 766 although it will compile with \key{lim3} additional minor code changes may be required to run using LIM3. 767 768 769 % ================================================================ 770 % Atmospheric pressure 771 % ================================================================ 772 \section{Atmospheric pressure (\protect\mdl{sbcapr})} 681 in this case, the user should examine the code to be sure the assumptions made are satisfactory. 682 In cases where this is definitely not possible, the model should abort with an error message. 683 684 %% ================================================================================================= 685 \section[Atmospheric pressure (\textit{sbcapr.F90})]{Atmospheric pressure (\protect\mdl{sbcapr})} 773 686 \label{sec:SBC_apr} 774 %------------------------------------------namsbc_apr---------------------------------------------------- 775 776 \nlst{namsbc_apr} 777 %------------------------------------------------------------------------------------------------------------- 687 688 \begin{listing} 689 \nlst{namsbc_apr} 690 \caption{\forcode{&namsbc_apr}} 691 \label{lst:namsbc_apr} 692 \end{listing} 778 693 779 694 The optional atmospheric pressure can be used to force ocean and ice dynamics 780 (\np {ln\_apr\_dyn}\forcode{ = .true.}, \textit{\ngn{namsbc}} namelist).781 The input atmospheric forcing defined via \np{sn \_apr} structure (\textit{namsbc\_apr} namelist)695 (\np[=.true.]{ln_apr_dyn}{ln\_apr\_dyn}, \nam{sbc}{sbc} namelist). 696 The input atmospheric forcing defined via \np{sn_apr}{sn\_apr} structure (\nam{sbc_apr}{sbc\_apr} namelist) 782 697 can be interpolated in time to the model time step, and even in space when the interpolation on-the-fly is used. 783 698 When used to force the dynamics, the atmospheric pressure is further transformed into … … 788 703 \] 789 704 where $P_{atm}$ is the atmospheric pressure and $P_o$ a reference atmospheric pressure. 790 A value of $101,000~N/m^2$ is used unless \np{ln \_ref\_apr} is set to true.791 In this case $P_o$ is set to the value of $P_{atm}$ averaged over the ocean domain,792 \ie the mean value of $\eta_{ib}$ is kept to zero at all time step.705 A value of $101,000~N/m^2$ is used unless \np{ln_ref_apr}{ln\_ref\_apr} is set to true. 706 In this case, $P_o$ is set to the value of $P_{atm}$ averaged over the ocean domain, 707 \ie\ the mean value of $\eta_{ib}$ is kept to zero at all time steps. 793 708 794 709 The gradient of $\eta_{ib}$ is added to the RHS of the ocean momentum equation (see \mdl{dynspg} for the ocean). 795 710 For sea-ice, the sea surface height, $\eta_m$, which is provided to the sea ice model is set to $\eta - \eta_{ib}$ 796 711 (see \mdl{sbcssr} module). 797 $\eta_{ib}$ can be setin the output.712 $\eta_{ib}$ can be written in the output. 798 713 This can simplify altimetry data and model comparison as 799 714 inverse barometer sea surface height is usually removed from these date prior to their distribution. 800 715 801 716 When using time-splitting and BDY package for open boundaries conditions, 802 the equivalent inverse barometer sea surface height $\eta_{ib}$ can be added to BDY ssh data: 803 \np{ln\_apr\_obc} might be set to true. 804 805 % ================================================================ 806 % Surface Tides Forcing 807 % ================================================================ 808 \section{Surface tides (\protect\mdl{sbctide})} 717 the equivalent inverse barometer sea surface height $\eta_{ib}$ can be added to BDY ssh data: 718 \np{ln_apr_obc}{ln\_apr\_obc} might be set to true. 719 720 %% ================================================================================================= 721 \section[Surface tides (\textit{sbctide.F90})]{Surface tides (\protect\mdl{sbctide})} 809 722 \label{sec:SBC_tide} 810 723 811 %------------------------------------------nam_tide--------------------------------------- 812 813 \nlst{nam_tide} 814 %----------------------------------------------------------------------------------------- 724 \begin{listing} 725 \nlst{nam_tide} 726 \caption{\forcode{&nam_tide}} 727 \label{lst:nam_tide} 728 \end{listing} 815 729 816 730 The tidal forcing, generated by the gravity forces of the Earth-Moon and Earth-Sun sytems, 817 is activated if \np{ln \_tide} and \np{ln\_tide\_pot} are both set to \forcode{.true.} in \ngn{nam\_tide}.818 This translates as an additional barotropic force in the momentum equations \ref{eq:PE_dyn} such that:731 is activated if \np{ln_tide}{ln\_tide} and \np{ln_tide_pot}{ln\_tide\_pot} are both set to \forcode{.true.} in \nam{_tide}{\_tide}. 732 This translates as an additional barotropic force in the momentum \autoref{eq:MB_PE_dyn} such that: 819 733 \[ 820 % \label{eq: PE_dyn_tides}821 \frac{\partial {\ rm {\bf U}}_h }{\partial t}= ...734 % \label{eq:SBC_PE_dyn_tides} 735 \frac{\partial {\mathrm {\mathbf U}}_h }{\partial t}= ... 822 736 +g\nabla (\Pi_{eq} + \Pi_{sal}) 823 737 \] 824 738 where $\Pi_{eq}$ stands for the equilibrium tidal forcing and 825 739 $\Pi_{sal}$ is a self-attraction and loading term (SAL). 826 740 827 741 The equilibrium tidal forcing is expressed as a sum over a subset of 828 742 constituents chosen from the set of available tidal constituents 829 defined in file \ rou{SBC/tide.h90} (this comprises the tidal743 defined in file \hf{SBC/tide} (this comprises the tidal 830 744 constituents \textit{M2, N2, 2N2, S2, K2, K1, O1, Q1, P1, M4, Mf, Mm, 831 745 Msqm, Mtm, S1, MU2, NU2, L2}, and \textit{T2}). Individual 832 746 constituents are selected by including their names in the array 833 \np{clname} in \ngn{nam\_tide} (e.g., \np{clname(1) = 'M2',834 clname(2)='S2'} to select solely the tidal consituents \textit{M2}835 and \textit{S2}). Optionally, when \np{ln \_tide\_ramp} is set to747 \np{clname}{clname} in \nam{_tide}{\_tide} (e.g., \np{clname}{clname}\forcode{(1)='M2', } 748 \np{clname}{clname}\forcode{(2)='S2'} to select solely the tidal consituents \textit{M2} 749 and \textit{S2}). Optionally, when \np{ln_tide_ramp}{ln\_tide\_ramp} is set to 836 750 \forcode{.true.}, the equilibrium tidal forcing can be ramped up 837 linearly from zero during the initial \np{rdttideramp} days of the751 linearly from zero during the initial \np{rdttideramp}{rdttideramp} days of the 838 752 model run. 839 753 840 754 The SAL term should in principle be computed online as it depends on 841 the model tidal prediction itself (see \citet{ Arbic2004} for a755 the model tidal prediction itself (see \citet{arbic.garner.ea_DSR04} for a 842 756 discussion about the practical implementation of this term). 843 757 Nevertheless, the complex calculations involved would make this 844 computationally too expensive. 758 computationally too expensive. Here, two options are available: 845 759 $\Pi_{sal}$ generated by an external model can be read in 846 (\np {ln\_read\_load=.true.}), or a ``scalar approximation'' can be847 used (\np {ln\_scal\_load=.true.}). In the latter case760 (\np[=.true.]{ln_read_load}{ln\_read\_load}), or a ``scalar approximation'' can be 761 used (\np[=.true.]{ln_scal_load}{ln\_scal\_load}). In the latter case 848 762 \[ 849 763 \Pi_{sal} = \beta \eta, 850 764 \] 851 where $\beta$ (\np{rn \_scal\_load} with a default value of 0.094) is a765 where $\beta$ (\np{rn_scal_load}{rn\_scal\_load} with a default value of 0.094) is a 852 766 spatially constant scalar, often chosen to minimize tidal prediction 853 errors. Setting both \np{ln \_read\_load} and \np{ln\_scal\_load} to767 errors. Setting both \np{ln_read_load}{ln\_read\_load} and \np{ln_scal_load}{ln\_scal\_load} to 854 768 \forcode{.false.} removes the SAL contribution. 855 769 856 % ================================================================ 857 % River runoffs 858 % ================================================================ 859 \section{River runoffs (\protect\mdl{sbcrnf})} 770 %% ================================================================================================= 771 \section[River runoffs (\textit{sbcrnf.F90})]{River runoffs (\protect\mdl{sbcrnf})} 860 772 \label{sec:SBC_rnf} 861 %------------------------------------------namsbc_rnf---------------------------------------------------- 862 863 \nlst{namsbc_rnf} 864 %------------------------------------------------------------------------------------------------------------- 865 866 %River runoff generally enters the ocean at a nonzero depth rather than through the surface. 773 774 \begin{listing} 775 \nlst{namsbc_rnf} 776 \caption{\forcode{&namsbc_rnf}} 777 \label{lst:namsbc_rnf} 778 \end{listing} 779 780 %River runoff generally enters the ocean at a nonzero depth rather than through the surface. 867 781 %Many models, however, have traditionally inserted river runoff to the top model cell. 868 %This was the case in \NEMO prior to the version 3.3. The switch toward a input of runoff869 %throughout a nonzero depth has been motivated by the numerical and physical problems 870 %that arise when the top grid cells are of the order of one meter. This situation is common in 871 %coastal modelling and becomes more and more often open ocean and climate modelling 782 %This was the case in \NEMO\ prior to the version 3.3. The switch toward a input of runoff 783 %throughout a nonzero depth has been motivated by the numerical and physical problems 784 %that arise when the top grid cells are of the order of one meter. This situation is common in 785 %coastal modelling and becomes more and more often open ocean and climate modelling 872 786 %\footnote{At least a top cells thickness of 1~meter and a 3 hours forcing frequency are 873 %required to properly represent the diurnal cycle \citep{Bernie_al_JC05}. see also \autoref{fig:SBC_dcy}.}. 874 875 876 %To do this we need to treat evaporation/precipitation fluxes and river runoff differently in the 877 %\mdl{tra\_sbc} module. We decided to separate them throughout the code, so that the variable 878 %\textit{emp} represented solely evaporation minus precipitation fluxes, and a new 2d variable 879 %rnf was added which represents the volume flux of river runoff (in kg/m2s to remain consistent with 880 %emp). This meant many uses of emp and emps needed to be changed, a list of all modules which use 787 %required to properly represent the diurnal cycle \citep{bernie.woolnough.ea_JC05}. see also \autoref{fig:SBC_dcy}.}. 788 789 %To do this we need to treat evaporation/precipitation fluxes and river runoff differently in the 790 %\mdl{tra\_sbc} module. We decided to separate them throughout the code, so that the variable 791 %\textit{emp} represented solely evaporation minus precipitation fluxes, and a new 2d variable 792 %rnf was added which represents the volume flux of river runoff (in kg/m2s to remain consistent with 793 %emp). This meant many uses of emp and emps needed to be changed, a list of all modules which use 881 794 %emp or emps and the changes made are below: 882 883 795 884 796 %Rachel: 885 797 River runoff generally enters the ocean at a nonzero depth rather than through the surface. 886 798 Many models, however, have traditionally inserted river runoff to the top model cell. 887 This was the case in \NEMO prior to the version 3.3,799 This was the case in \NEMO\ prior to the version 3.3, 888 800 and was combined with an option to increase vertical mixing near the river mouth. 889 801 890 802 However, with this method numerical and physical problems arise when the top grid cells are of the order of one meter. 891 This situation is common in coastal modelling and is becoming more common in open ocean and climate modelling 803 This situation is common in coastal modelling and is becoming more common in open ocean and climate modelling 892 804 \footnote{ 893 805 At least a top cells thickness of 1~meter and a 3 hours forcing frequency are required to 894 properly represent the diurnal cycle \citep{ Bernie_al_JC05}.806 properly represent the diurnal cycle \citep{bernie.woolnough.ea_JC05}. 895 807 see also \autoref{fig:SBC_dcy}.}. 896 808 … … 900 812 along with the depth (in metres) which the river should be added to. 901 813 902 Namelist variables in \n gn{namsbc\_rnf}, \np{ln\_rnf\_depth}, \np{ln\_rnf\_sal} and903 \np{ln \_rnf\_temp} control whether the river attributes (depth, salinity and temperature) are read in and used.814 Namelist variables in \nam{sbc_rnf}{sbc\_rnf}, \np{ln_rnf_depth}{ln\_rnf\_depth}, \np{ln_rnf_sal}{ln\_rnf\_sal} and 815 \np{ln_rnf_temp}{ln\_rnf\_temp} control whether the river attributes (depth, salinity and temperature) are read in and used. 904 816 If these are set as false the river is added to the surface box only, assumed to be fresh (0~psu), 905 817 and/or taken as surface temperature respectively. 906 818 907 The runoff value and attributes are read in in sbcrnf. 819 The runoff value and attributes are read in in sbcrnf. 908 820 For temperature -999 is taken as missing data and the river temperature is taken to 909 821 be the surface temperatue at the river point. 910 For the depth parameter a value of -1 means the river is added to the surface box only, 911 and a value of -999 means the river is added through the entire water column. 822 For the depth parameter a value of -1 means the river is added to the surface box only, 823 and a value of -999 means the river is added through the entire water column. 912 824 After being read in the temperature and salinity variables are multiplied by the amount of runoff 913 825 (converted into m/s) to give the heat and salt content of the river runoff. 914 826 After the user specified depth is read ini, 915 the number of grid boxes this corresponds to is calculated and stored in the variable \np{nz \_rnf}.827 the number of grid boxes this corresponds to is calculated and stored in the variable \np{nz_rnf}{nz\_rnf}. 916 828 The variable \textit{h\_dep} is then calculated to be the depth (in metres) of 917 829 the bottom of the lowest box the river water is being added to 918 (\ie the total depth that river water is being added to in the model).830 (\ie\ the total depth that river water is being added to in the model). 919 831 920 832 The mass/volume addition due to the river runoff is, at each relevant depth level, added to … … 922 834 This increases the diffusion term in the vicinity of the river, thereby simulating a momentum flux. 923 835 The sea surface height is calculated using the sum of the horizontal divergence terms, 924 and so the river runoff indirectly forces an increase in sea surface height. 836 and so the river runoff indirectly forces an increase in sea surface height. 925 837 926 838 The \textit{hdivn} terms are used in the tracer advection modules to force vertical velocities. … … 935 847 As such the volume of water does not change, but the water is diluted. 936 848 937 For the non-linear free surface case (\key{vvl}), no flux is allowed through the surface.849 For the non-linear free surface case, no flux is allowed through the surface. 938 850 Instead in the surface box (as well as water moving up from the boxes below) a volume of runoff water is added with 939 851 no corresponding heat and salt addition and so as happens in the lower boxes there is a dilution effect. … … 944 856 This is done in the same way for both vvl and non-vvl. 945 857 The temperature and salinity are increased through the specified depth according to 946 the heat and salt content of the river. 858 the heat and salt content of the river. 947 859 948 860 In the non-linear free surface case (vvl), … … 953 865 954 866 It is also possible for runnoff to be specified as a negative value for modelling flow through straits, 955 \ie modelling the Baltic flow in and out of the North Sea.867 \ie\ modelling the Baltic flow in and out of the North Sea. 956 868 When the flow is out of the domain there is no change in temperature and salinity, 957 869 regardless of the namelist options used, 958 as the ocean water leaving the domain removes heat and salt (at the same concentration) with it. 959 960 961 %\colorbox{yellow}{Nevertheless, Pb of vertical resolution and 3D input : increase vertical mixing near river mouths to mimic a 3D river 870 as the ocean water leaving the domain removes heat and salt (at the same concentration) with it. 871 872 %\colorbox{yellow}{Nevertheless, Pb of vertical resolution and 3D input : increase vertical mixing near river mouths to mimic a 3D river 962 873 963 874 %All river runoff and emp fluxes are assumed to be fresh water (zero salinity) and at the same temperature as the sea surface.} … … 969 880 %ENDIF 970 881 971 %\gmcomment{ word doc of runoffs: 972 % 973 %In the current \NEMO setup river runoff is added to emp fluxes, these are then applied at just the sea surface as a volume change (in the variable volume case this is a literal volume change, and in the linear free surface case the free surface is moved) and a salt flux due to the concentration/dilution effect. There is also an option to increase vertical mixing near river mouths; this gives the effect of having a 3d river. All river runoff and emp fluxes are assumed to be fresh water (zero salinity) and at the same temperature as the sea surface. 974 %Our aim was to code the option to specify the temperature and salinity of river runoff, (as well as the amount), along with the depth that the river water will affect. This would make it possible to model low salinity outflow, such as the Baltic, and would allow the ocean temperature to be affected by river runoff. 975 976 %The depth option makes it possible to have the river water affecting just the surface layer, throughout depth, or some specified point in between. 977 978 %To do this we need to treat evaporation/precipitation fluxes and river runoff differently in the tra_sbc module. We decided to separate them throughout the code, so that the variable emp represented solely evaporation minus precipitation fluxes, and a new 2d variable rnf was added which represents the volume flux of river runoff (in kg/m2s to remain consistent with emp). This meant many uses of emp and emps needed to be changed, a list of all modules which use emp or emps and the changes made are below: 979 980 %} 981 % ================================================================ 982 % Ice shelf melting 983 % ================================================================ 984 \section{Ice shelf melting (\protect\mdl{sbcisf})} 882 \cmtgm{ word doc of runoffs: 883 In the current \NEMO\ setup river runoff is added to emp fluxes, 884 these are then applied at just the sea surface as a volume change (in the variable volume case 885 this is a literal volume change, and in the linear free surface case the free surface is moved) 886 and a salt flux due to the concentration/dilution effect. 887 There is also an option to increase vertical mixing near river mouths; 888 this gives the effect of having a 3d river. 889 All river runoff and emp fluxes are assumed to be fresh water (zero salinity) and 890 at the same temperature as the sea surface. 891 Our aim was to code the option to specify the temperature and salinity of river runoff, 892 (as well as the amount), along with the depth that the river water will affect. 893 This would make it possible to model low salinity outflow, such as the Baltic, 894 and would allow the ocean temperature to be affected by river runoff. 895 896 The depth option makes it possible to have the river water affecting just the surface layer, 897 throughout depth, or some specified point in between. 898 899 To do this we need to treat evaporation/precipitation fluxes and river runoff differently in 900 the \mdl{tra_sbc} module. 901 We decided to separate them throughout the code, 902 so that the variable emp represented solely evaporation minus precipitation fluxes, 903 and a new 2d variable rnf was added which represents the volume flux of river runoff 904 (in $kg/m^2s$ to remain consistent with $emp$). 905 This meant many uses of emp and emps needed to be changed, 906 a list of all modules which use $emp$ or $emps$ and the changes made are below:} 907 908 %% ================================================================================================= 909 \section[Ice shelf melting (\textit{sbcisf.F90})]{Ice shelf melting (\protect\mdl{sbcisf})} 985 910 \label{sec:SBC_isf} 986 %------------------------------------------namsbc_isf---------------------------------------------------- 987 988 \nlst{namsbc_isf} 989 %-------------------------------------------------------------------------------------------------------- 990 The namelist variable in \ngn{namsbc}, \np{nn\_isf}, controls the ice shelf representation. 991 Description and result of sensitivity test to \np{nn\_isf} are presented in \citet{Mathiot2017}. 911 912 \begin{listing} 913 \nlst{namsbc_isf} 914 \caption{\forcode{&namsbc_isf}} 915 \label{lst:namsbc_isf} 916 \end{listing} 917 918 The namelist variable in \nam{sbc}{sbc}, \np{nn_isf}{nn\_isf}, controls the ice shelf representation. 919 Description and result of sensitivity test to \np{nn_isf}{nn\_isf} are presented in \citet{mathiot.jenkins.ea_GMD17}. 992 920 The different options are illustrated in \autoref{fig:SBC_isf}. 993 921 994 922 \begin{description} 995 \item[\np{nn\_isf}\forcode{ = 1}]: 996 The ice shelf cavity is represented (\np{ln\_isfcav}\forcode{ = .true.} needed). 923 \item [{\np[=1]{nn_isf}{nn\_isf}}]: The ice shelf cavity is represented (\np[=.true.]{ln_isfcav}{ln\_isfcav} needed). 997 924 The fwf and heat flux are depending of the local water properties. 925 998 926 Two different bulk formulae are available: 999 927 1000 \begin{description} 1001 \item[\np{nn\_isfblk}\forcode{ = 1}]: 1002 The melt rate is based on a balance between the upward ocean heat flux and 1003 the latent heat flux at the ice shelf base. A complete description is available in \citet{Hunter2006}. 1004 \item[\np{nn\_isfblk}\forcode{ = 2}]: 1005 The melt rate and the heat flux are based on a 3 equations formulation 1006 (a heat flux budget at the ice base, a salt flux budget at the ice base and a linearised freezing point temperature equation). 1007 A complete description is available in \citet{Jenkins1991}. 1008 \end{description} 1009 1010 Temperature and salinity used to compute the melt are the average temperature in the top boundary layer \citet{Losch2008}. 1011 Its thickness is defined by \np{rn\_hisf\_tbl}. 1012 The fluxes and friction velocity are computed using the mean temperature, salinity and velocity in the the first \np{rn\_hisf\_tbl} m. 1013 Then, the fluxes are spread over the same thickness (ie over one or several cells). 1014 If \np{rn\_hisf\_tbl} larger than top $e_{3}t$, there is no more feedback between the freezing point at the interface and the the top cell temperature. 1015 This can lead to super-cool temperature in the top cell under melting condition. 1016 If \np{rn\_hisf\_tbl} smaller than top $e_{3}t$, the top boundary layer thickness is set to the top cell thickness.\\ 1017 1018 Each melt bulk formula depends on a exchange coeficient ($\Gamma^{T,S}$) between the ocean and the ice. 1019 There are 3 different ways to compute the exchange coeficient: 1020 \begin{description} 1021 \item[\np{nn\_gammablk}\forcode{ = 0}]: 1022 The salt and heat exchange coefficients are constant and defined by \np{rn\_gammas0} and \np{rn\_gammat0}. 1023 \[ 1024 % \label{eq:sbc_isf_gamma_iso} 1025 \gamma^{T} = \np{rn\_gammat0} 1026 \] 1027 \[ 1028 \gamma^{S} = \np{rn\_gammas0} 1029 \] 1030 This is the recommended formulation for ISOMIP. 1031 \item[\np{nn\_gammablk}\forcode{ = 1}]: 1032 The salt and heat exchange coefficients are velocity dependent and defined as 1033 \[ 1034 \gamma^{T} = \np{rn\_gammat0} \times u_{*} 1035 \] 1036 \[ 1037 \gamma^{S} = \np{rn\_gammas0} \times u_{*} 1038 \] 1039 where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn\_hisf\_tbl} meters). 1040 See \citet{Jenkins2010} for all the details on this formulation. It is the recommended formulation for realistic application. 1041 \item[\np{nn\_gammablk}\forcode{ = 2}]: 1042 The salt and heat exchange coefficients are velocity and stability dependent and defined as: 1043 \[ 1044 \gamma^{T,S} = \frac{u_{*}}{\Gamma_{Turb} + \Gamma^{T,S}_{Mole}} 1045 \] 1046 where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn\_hisf\_tbl} meters), 1047 $\Gamma_{Turb}$ the contribution of the ocean stability and 1048 $\Gamma^{T,S}_{Mole}$ the contribution of the molecular diffusion. 1049 See \citet{Holland1999} for all the details on this formulation. 1050 This formulation has not been extensively tested in NEMO (not recommended). 1051 \end{description} 1052 \item[\np{nn\_isf}\forcode{ = 2}]: 1053 The ice shelf cavity is not represented. 1054 The fwf and heat flux are computed using the \citet{Beckmann2003} parameterisation of isf melting. 1055 The fluxes are distributed along the ice shelf edge between the depth of the average grounding line (GL) 1056 (\np{sn\_depmax\_isf}) and the base of the ice shelf along the calving front 1057 (\np{sn\_depmin\_isf}) as in (\np{nn\_isf}\forcode{ = 3}). 1058 The effective melting length (\np{sn\_Leff\_isf}) is read from a file. 1059 \item[\np{nn\_isf}\forcode{ = 3}]: 1060 The ice shelf cavity is not represented. 1061 The fwf (\np{sn\_rnfisf}) is prescribed and distributed along the ice shelf edge between 1062 the depth of the average grounding line (GL) (\np{sn\_depmax\_isf}) and 1063 the base of the ice shelf along the calving front (\np{sn\_depmin\_isf}). 1064 The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$. 1065 \item[\np{nn\_isf}\forcode{ = 4}]: 1066 The ice shelf cavity is opened (\np{ln\_isfcav}\forcode{ = .true.} needed). 1067 However, the fwf is not computed but specified from file \np{sn\_fwfisf}). 1068 The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$. 1069 As in \np{nn\_isf}\forcode{ = 1}, the fluxes are spread over the top boundary layer thickness (\np{rn\_hisf\_tbl})\\ 928 \begin{description} 929 \item [{\np[=1]{nn_isfblk}{nn\_isfblk}}]: The melt rate is based on a balance between the upward ocean heat flux and 930 the latent heat flux at the ice shelf base. A complete description is available in \citet{hunter_rpt06}. 931 \item [{\np[=2]{nn_isfblk}{nn\_isfblk}}]: The melt rate and the heat flux are based on a 3 equations formulation 932 (a heat flux budget at the ice base, a salt flux budget at the ice base and a linearised freezing point temperature equation). 933 A complete description is available in \citet{jenkins_JGR91}. 934 \end{description} 935 936 Temperature and salinity used to compute the melt are the average temperature in the top boundary layer \citet{losch_JGR08}. 937 Its thickness is defined by \np{rn_hisf_tbl}{rn\_hisf\_tbl}. 938 The fluxes and friction velocity are computed using the mean temperature, salinity and velocity in the the first \np{rn_hisf_tbl}{rn\_hisf\_tbl} m. 939 Then, the fluxes are spread over the same thickness (ie over one or several cells). 940 If \np{rn_hisf_tbl}{rn\_hisf\_tbl} larger than top $e_{3}t$, there is no more feedback between the freezing point at the interface and the the top cell temperature. 941 This can lead to super-cool temperature in the top cell under melting condition. 942 If \np{rn_hisf_tbl}{rn\_hisf\_tbl} smaller than top $e_{3}t$, the top boundary layer thickness is set to the top cell thickness.\\ 943 944 Each melt bulk formula depends on a exchange coeficient ($\Gamma^{T,S}$) between the ocean and the ice. 945 There are 3 different ways to compute the exchange coeficient: 946 \begin{description} 947 \item [{\np[=0]{nn_gammablk}{nn\_gammablk}}]: The salt and heat exchange coefficients are constant and defined by \np{rn_gammas0}{rn\_gammas0} and \np{rn_gammat0}{rn\_gammat0}. 948 \begin{gather*} 949 % \label{eq:SBC_isf_gamma_iso} 950 \gamma^{T} = rn\_gammat0 \\ 951 \gamma^{S} = rn\_gammas0 952 \end{gather*} 953 This is the recommended formulation for ISOMIP. 954 \item [{\np[=1]{nn_gammablk}{nn\_gammablk}}]: The salt and heat exchange coefficients are velocity dependent and defined as 955 \begin{gather*} 956 \gamma^{T} = rn\_gammat0 \times u_{*} \\ 957 \gamma^{S} = rn\_gammas0 \times u_{*} 958 \end{gather*} 959 where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn_hisf_tbl}{rn\_hisf\_tbl} meters). 960 See \citet{jenkins.nicholls.ea_JPO10} for all the details on this formulation. It is the recommended formulation for realistic application. 961 \item [{\np[=2]{nn_gammablk}{nn\_gammablk}}]: The salt and heat exchange coefficients are velocity and stability dependent and defined as: 962 \[ 963 \gamma^{T,S} = \frac{u_{*}}{\Gamma_{Turb} + \Gamma^{T,S}_{Mole}} 964 \] 965 where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn_hisf_tbl}{rn\_hisf\_tbl} meters), 966 $\Gamma_{Turb}$ the contribution of the ocean stability and 967 $\Gamma^{T,S}_{Mole}$ the contribution of the molecular diffusion. 968 See \citet{holland.jenkins_JPO99} for all the details on this formulation. 969 This formulation has not been extensively tested in \NEMO\ (not recommended). 970 \end{description} 971 \item [{\np[=2]{nn_isf}{nn\_isf}}]: The ice shelf cavity is not represented. 972 The fwf and heat flux are computed using the \citet{beckmann.goosse_OM03} parameterisation of isf melting. 973 The fluxes are distributed along the ice shelf edge between the depth of the average grounding line (GL) 974 (\np{sn_depmax_isf}{sn\_depmax\_isf}) and the base of the ice shelf along the calving front 975 (\np{sn_depmin_isf}{sn\_depmin\_isf}) as in (\np[=3]{nn_isf}{nn\_isf}). 976 The effective melting length (\np{sn_Leff_isf}{sn\_Leff\_isf}) is read from a file. 977 \item [{\np[=3]{nn_isf}{nn\_isf}}]: The ice shelf cavity is not represented. 978 The fwf (\np{sn_rnfisf}{sn\_rnfisf}) is prescribed and distributed along the ice shelf edge between 979 the depth of the average grounding line (GL) (\np{sn_depmax_isf}{sn\_depmax\_isf}) and 980 the base of the ice shelf along the calving front (\np{sn_depmin_isf}{sn\_depmin\_isf}). 981 The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$. 982 \item [{\np[=4]{nn_isf}{nn\_isf}}]: The ice shelf cavity is opened (\np[=.true.]{ln_isfcav}{ln\_isfcav} needed). 983 However, the fwf is not computed but specified from file \np{sn_fwfisf}{sn\_fwfisf}). 984 The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$. 985 As in \np[=1]{nn_isf}{nn\_isf}, the fluxes are spread over the top boundary layer thickness (\np{rn_hisf_tbl}{rn\_hisf\_tbl}) 1070 986 \end{description} 1071 987 1072 $\bullet$ \np {nn\_isf}\forcode{ = 1} and \np{nn\_isf}\forcode{ = 2} compute a melt rate based on988 $\bullet$ \np[=1]{nn_isf}{nn\_isf} and \np[=2]{nn_isf}{nn\_isf} compute a melt rate based on 1073 989 the water mass properties, ocean velocities and depth. 1074 990 This flux is thus highly dependent of the model resolution (horizontal and vertical), 1075 991 realism of the water masses onto the shelf ...\\ 1076 992 1077 $\bullet$ \np {nn\_isf}\forcode{ = 3} and \np{nn\_isf}\forcode{ = 4} read the melt rate from a file.993 $\bullet$ \np[=3]{nn_isf}{nn\_isf} and \np[=4]{nn_isf}{nn\_isf} read the melt rate from a file. 1078 994 You have total control of the fwf forcing. 1079 995 This can be useful if the water masses on the shelf are not realistic or 1080 996 the resolution (horizontal/vertical) are too coarse to have realistic melting or 1081 for studies where you need to control your heat and fw input.\\ 997 for studies where you need to control your heat and fw input.\\ 1082 998 1083 999 The ice shelf melt is implemented as a volume flux as for the runoff. … … 1086 1002 See the runoff section \autoref{sec:SBC_rnf} for all the details about the divergence correction.\\ 1087 1003 1088 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>1089 1004 \begin{figure}[!t] 1090 \begin{center} 1091 \includegraphics[width=0.8\textwidth]{Fig_SBC_isf} 1092 \caption{ 1093 \protect\label{fig:SBC_isf} 1094 Illustration the location where the fwf is injected and whether or not the fwf is interactif or not depending of \np{nn\_isf}. 1095 } 1096 \end{center} 1005 \centering 1006 \includegraphics[width=0.66\textwidth]{SBC_isf} 1007 \caption[Ice shelf location and fresh water flux definition]{ 1008 Illustration of the location where the fwf is injected and 1009 whether or not the fwf is interactif or not depending of \protect\np{nn_isf}{nn\_isf}.} 1010 \label{fig:SBC_isf} 1097 1011 \end{figure} 1098 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1099 1012 1013 %% ================================================================================================= 1100 1014 \section{Ice sheet coupling} 1101 1015 \label{sec:SBC_iscpl} 1102 %------------------------------------------namsbc_iscpl---------------------------------------------------- 1103 1104 \nlst{namsbc_iscpl} 1105 %-------------------------------------------------------------------------------------------------------- 1016 1017 \begin{listing} 1018 \nlst{namsbc_iscpl} 1019 \caption{\forcode{&namsbc_iscpl}} 1020 \label{lst:namsbc_iscpl} 1021 \end{listing} 1022 1106 1023 Ice sheet/ocean coupling is done through file exchange at the restart step. 1107 1024 At each restart step: 1108 \begin{description} 1109 \item[Step 1]: the ice sheet model send a new bathymetry and ice shelf draft netcdf file. 1110 \item[Step 2]: a new domcfg.nc file is built using the DOMAINcfg tools. 1111 \item[Step 3]: NEMO run for a specific period and output the average melt rate over the period. 1112 \item[Step 4]: the ice sheet model run using the melt rate outputed in step 4. 1113 \item[Step 5]: go back to 1. 1114 \end{description} 1115 1116 If \np{ln\_iscpl}\forcode{ = .true.}, the isf draft is assume to be different at each restart step with 1025 1026 \begin{enumerate} 1027 \item the ice sheet model send a new bathymetry and ice shelf draft netcdf file. 1028 \item a new domcfg.nc file is built using the DOMAINcfg tools. 1029 \item \NEMO\ run for a specific period and output the average melt rate over the period. 1030 \item the ice sheet model run using the melt rate outputed in step 4. 1031 \item go back to 1. 1032 \end{enumerate} 1033 1034 If \np[=.true.]{ln_iscpl}{ln\_iscpl}, the isf draft is assume to be different at each restart step with 1117 1035 potentially some new wet/dry cells due to the ice sheet dynamics/thermodynamics. 1118 1036 The wetting and drying scheme applied on the restart is very simple and described below for the 6 different possible cases: 1037 1119 1038 \begin{description} 1120 \item[Thin a cell down]: 1121 T/S/ssh are unchanged and U/V in the top cell are corrected to keep the barotropic transport (bt) constant 1039 \item [Thin a cell down]: T/S/ssh are unchanged and U/V in the top cell are corrected to keep the barotropic transport (bt) constant 1122 1040 ($bt_b=bt_n$). 1123 \item[Enlarge a cell]: 1124 See case "Thin a cell down" 1125 \item[Dry a cell]: 1126 mask, T/S, U/V and ssh are set to 0. 1041 \item [Enlarge a cell]: See case "Thin a cell down" 1042 \item [Dry a cell]: mask, T/S, U/V and ssh are set to 0. 1127 1043 Furthermore, U/V into the water column are modified to satisfy ($bt_b=bt_n$). 1128 \item[Wet a cell]: 1129 mask is set to 1, T/S is extrapolated from neighbours, $ssh_n = ssh_b$ and U/V set to 0. 1130 If no neighbours, T/S is extrapolated from old top cell value. 1044 \item [Wet a cell]: mask is set to 1, T/S is extrapolated from neighbours, $ssh_n = ssh_b$ and U/V set to 0. 1045 If no neighbours, T/S is extrapolated from old top cell value. 1131 1046 If no neighbours along i,j and k (both previous test failed), T/S/U/V/ssh and mask are set to 0. 1132 \item[Dry a column]: 1133 mask, T/S, U/V are set to 0 everywhere in the column and ssh set to 0. 1134 \item[Wet a column]: 1135 set mask to 1, T/S is extrapolated from neighbours, ssh is extrapolated from neighbours and U/V set to 0. 1047 \item [Dry a column]: mask, T/S, U/V are set to 0 everywhere in the column and ssh set to 0. 1048 \item [Wet a column]: set mask to 1, T/S is extrapolated from neighbours, ssh is extrapolated from neighbours and U/V set to 0. 1136 1049 If no neighbour, T/S/U/V and mask set to 0. 1137 1050 \end{description} … … 1140 1053 the restart time step is prescribed to be an euler time step instead of a leap frog and $fields_b = fields_n$.\\ 1141 1054 1142 The horizontal extrapolation to fill new cell with realistic value is called \np{nn \_drown} times.1143 It means that if the grounding line retreat by more than \np{nn \_drown} cells between 2 coupling steps,1055 The horizontal extrapolation to fill new cell with realistic value is called \np{nn_drown}{nn\_drown} times. 1056 It means that if the grounding line retreat by more than \np{nn_drown}{nn\_drown} cells between 2 coupling steps, 1144 1057 the code will be unable to fill all the new wet cells properly. 1145 1058 The default number is set up for the MISOMIP idealised experiments. 1146 1059 This coupling procedure is able to take into account grounding line and calving front migration. 1147 However, it is a non-conservative processe. 1060 However, it is a non-conservative processe. 1148 1061 This could lead to a trend in heat/salt content and volume.\\ 1149 1062 1150 1063 In order to remove the trend and keep the conservation level as close to 0 as possible, 1151 a simple conservation scheme is available with \np {ln\_hsb}\forcode{ = .true.}.1064 a simple conservation scheme is available with \np[=.true.]{ln_hsb}{ln\_hsb}. 1152 1065 The heat/salt/vol. gain/loss is diagnosed, as well as the location. 1153 A correction increment is computed and apply each time step during the next \np{rn \_fiscpl} time steps.1154 For safety, it is advised to set \np{rn \_fiscpl} equal to the coupling period (smallest increment possible).1066 A correction increment is computed and apply each time step during the next \np{rn_fiscpl}{rn\_fiscpl} time steps. 1067 For safety, it is advised to set \np{rn_fiscpl}{rn\_fiscpl} equal to the coupling period (smallest increment possible). 1155 1068 The corrective increment is apply into the cell itself (if it is a wet cell), the neigbouring cells or the closest wet cell (if the cell is now dry). 1156 1069 1157 % 1158 % ================================================================ 1159 % Handling of icebergs 1160 % ================================================================ 1070 %% ================================================================================================= 1161 1071 \section{Handling of icebergs (ICB)} 1162 \label{sec:ICB_icebergs} 1163 %------------------------------------------namberg---------------------------------------------------- 1164 1165 \nlst{namberg} 1166 %------------------------------------------------------------------------------------------------------------- 1167 1168 Icebergs are modelled as lagrangian particles in NEMO \citep{Marsh_GMD2015}. 1169 Their physical behaviour is controlled by equations as described in \citet{Martin_Adcroft_OM10} ). 1170 (Note that the authors kindly provided a copy of their code to act as a basis for implementation in NEMO). 1072 \label{sec:SBC_ICB_icebergs} 1073 1074 \begin{listing} 1075 \nlst{namberg} 1076 \caption{\forcode{&namberg}} 1077 \label{lst:namberg} 1078 \end{listing} 1079 1080 Icebergs are modelled as lagrangian particles in \NEMO\ \citep{marsh.ivchenko.ea_GMD15}. 1081 Their physical behaviour is controlled by equations as described in \citet{martin.adcroft_OM10} ). 1082 (Note that the authors kindly provided a copy of their code to act as a basis for implementation in \NEMO). 1171 1083 Icebergs are initially spawned into one of ten classes which have specific mass and thickness as 1172 described in the \n gn{namberg} namelist: \np{rn\_initial\_mass} and \np{rn\_initial\_thickness}.1173 Each class has an associated scaling (\np{rn \_mass\_scaling}),1084 described in the \nam{berg}{berg} namelist: \np{rn_initial_mass}{rn\_initial\_mass} and \np{rn_initial_thickness}{rn\_initial\_thickness}. 1085 Each class has an associated scaling (\np{rn_mass_scaling}{rn\_mass\_scaling}), 1174 1086 which is an integer representing how many icebergs of this class are being described as one lagrangian point 1175 1087 (this reduces the numerical problem of tracking every single iceberg). 1176 They are enabled by setting \np {ln\_icebergs}\forcode{ = .true.}.1088 They are enabled by setting \np[=.true.]{ln_icebergs}{ln\_icebergs}. 1177 1089 1178 1090 Two initialisation schemes are possible. 1179 1091 \begin{description} 1180 \item[\np{nn\_test\_icebergs}~$>$~0] 1181 In this scheme, the value of \np{nn\_test\_icebergs} represents the class of iceberg to generate 1182 (so between 1 and 10), and \np{nn\_test\_icebergs} provides a lon/lat box in the domain at each grid point of 1092 \item [{\np{nn_test_icebergs}{nn\_test\_icebergs}~$>$~0}] In this scheme, the value of \np{nn_test_icebergs}{nn\_test\_icebergs} represents the class of iceberg to generate 1093 (so between 1 and 10), and \np{nn_test_icebergs}{nn\_test\_icebergs} provides a lon/lat box in the domain at each grid point of 1183 1094 which an iceberg is generated at the beginning of the run. 1184 (Note that this happens each time the timestep equals \np{nn \_nit000}.)1185 \np{nn \_test\_icebergs} is defined by four numbers in \np{nn\_test\_box} representing the corners of1095 (Note that this happens each time the timestep equals \np{nn_nit000}{nn\_nit000}.) 1096 \np{nn_test_icebergs}{nn\_test\_icebergs} is defined by four numbers in \np{nn_test_box}{nn\_test\_box} representing the corners of 1186 1097 the geographical box: lonmin,lonmax,latmin,latmax 1187 \item[\np{nn\_test\_icebergs}\forcode{ = -1}] 1188 In this scheme the model reads a calving file supplied in the \np{sn\_icb} parameter. 1098 \item [{\np[=-1]{nn_test_icebergs}{nn\_test\_icebergs}}] In this scheme, the model reads a calving file supplied in the \np{sn_icb}{sn\_icb} parameter. 1189 1099 This should be a file with a field on the configuration grid (typically ORCA) 1190 1100 representing ice accumulation rate at each model point. … … 1194 1104 At each time step, a test is performed to see if there is enough ice mass to 1195 1105 calve an iceberg of each class in order (1 to 10). 1196 Note that this is the initial mass multiplied by the number each particle represents (\ie the scaling).1106 Note that this is the initial mass multiplied by the number each particle represents (\ie\ the scaling). 1197 1107 If there is enough ice, a new iceberg is spawned and the total available ice reduced accordingly. 1198 1108 \end{description} … … 1201 1111 The latter act to disintegrate the iceberg. 1202 1112 This is either all melted freshwater, 1203 or (if \np{rn \_bits\_erosion\_fraction}~$>$~0) into melt and additionally small ice bits1113 or (if \np{rn_bits_erosion_fraction}{rn\_bits\_erosion\_fraction}~$>$~0) into melt and additionally small ice bits 1204 1114 which are assumed to propagate with their larger parent and thus delay fluxing into the ocean. 1205 Melt water (and other variables on the configuration grid) are written into the main NEMOmodel output files.1115 Melt water (and other variables on the configuration grid) are written into the main \NEMO\ model output files. 1206 1116 1207 1117 Extensive diagnostics can be produced. 1208 1118 Separate output files are maintained for human-readable iceberg information. 1209 A separate file is produced for each processor (independent of \np{ln \_ctl}).1119 A separate file is produced for each processor (independent of \np{ln_ctl}{ln\_ctl}). 1210 1120 The amount of information is controlled by two integer parameters: 1211 1121 \begin{description} 1212 \item [\np{nn\_verbose\_level}] takes a value between one and four and1122 \item [{\np{nn_verbose_level}{nn\_verbose\_level}}] takes a value between one and four and 1213 1123 represents an increasing number of points in the code at which variables are written, 1214 1124 and an increasing level of obscurity. 1215 \item [\np{nn\_verbose\_write}] is the number of timesteps between writes1125 \item [{\np{nn_verbose_write}{nn\_verbose\_write}}] is the number of timesteps between writes 1216 1126 \end{description} 1217 1127 1218 Iceberg trajectories can also be written out and this is enabled by setting \np{nn \_sample\_rate}~$>$~0.1128 Iceberg trajectories can also be written out and this is enabled by setting \np{nn_sample_rate}{nn\_sample\_rate}~$>$~0. 1219 1129 A non-zero value represents how many timesteps between writes of information into the output file. 1220 1130 These output files are in NETCDF format. … … 1224 1134 since its trajectory data may be spread across multiple files. 1225 1135 1226 % ------------------------------------------------------------------------------------------------------------- 1227 % Interactions with waves (sbcwave.F90, ln_wave) 1228 % ------------------------------------------------------------------------------------------------------------- 1229 \section{Interactions with waves (\protect\mdl{sbcwave}, \protect\np{ln\_wave})} 1136 %% ================================================================================================= 1137 \section[Interactions with waves (\textit{sbcwave.F90}, \forcode{ln_wave})]{Interactions with waves (\protect\mdl{sbcwave}, \protect\np{ln_wave}{ln\_wave})} 1230 1138 \label{sec:SBC_wave} 1231 %------------------------------------------namsbc_wave-------------------------------------------------------- 1232 1233 \nlst{namsbc_wave} 1234 %------------------------------------------------------------------------------------------------------------- 1235 1236 Ocean waves represent the interface between the ocean and the atmosphere, so NEMO is extended to incorporate 1237 physical processes related to ocean surface waves, namely the surface stress modified by growth and 1238 dissipation of the oceanic wave field, the Stokes-Coriolis force and the Stokes drift impact on mass and 1239 tracer advection; moreover the neutral surface drag coefficient from a wave model can be used to evaluate 1139 1140 \begin{listing} 1141 \nlst{namsbc_wave} 1142 \caption{\forcode{&namsbc_wave}} 1143 \label{lst:namsbc_wave} 1144 \end{listing} 1145 1146 Ocean waves represent the interface between the ocean and the atmosphere, so \NEMO\ is extended to incorporate 1147 physical processes related to ocean surface waves, namely the surface stress modified by growth and 1148 dissipation of the oceanic wave field, the Stokes-Coriolis force and the Stokes drift impact on mass and 1149 tracer advection; moreover the neutral surface drag coefficient from a wave model can be used to evaluate 1240 1150 the wind stress. 1241 1151 1242 Physical processes related to ocean surface waves can be accounted by setting the logical variable 1243 \np {ln\_wave}\forcode{= .true.} in \ngn{namsbc} namelist. In addition, specific flags accounting for1244 different p orcesses should be activated as explained in the following sections.1152 Physical processes related to ocean surface waves can be accounted by setting the logical variable 1153 \np[=.true.]{ln_wave}{ln\_wave} in \nam{sbc}{sbc} namelist. In addition, specific flags accounting for 1154 different processes should be activated as explained in the following sections. 1245 1155 1246 1156 Wave fields can be provided either in forced or coupled mode: 1247 1157 \begin{description} 1248 \item [forced mode]: wave fields should be defined through the \ngn{namsbc\_wave} namelist1249 for external data names, locations, frequency, interpolation and all the miscellanous options allowed by 1250 Input Data generic Interface (see \autoref{sec:SBC_input}). 1251 \item [coupled mode]: NEMO and an external wave model can be coupled by setting \np{ln\_cpl} \forcode{= .true.}1252 in \n gn{namsbc} namelist and filling the \ngn{namsbc\_cpl} namelist.1158 \item [forced mode]: wave fields should be defined through the \nam{sbc_wave}{sbc\_wave} namelist 1159 for external data names, locations, frequency, interpolation and all the miscellanous options allowed by 1160 Input Data generic Interface (see \autoref{sec:SBC_input}). 1161 \item [coupled mode]: \NEMO\ and an external wave model can be coupled by setting \np[=.true.]{ln_cpl}{ln\_cpl} 1162 in \nam{sbc}{sbc} namelist and filling the \nam{sbc_cpl}{sbc\_cpl} namelist. 1253 1163 \end{description} 1254 1164 1255 1256 % ================================================================ 1257 % Neutral drag coefficient from wave model (ln_cdgw) 1258 1259 % ================================================================ 1260 \subsection{Neutral drag coefficient from wave model (\protect\np{ln\_cdgw})} 1165 %% ================================================================================================= 1166 \subsection[Neutral drag coefficient from wave model (\forcode{ln_cdgw})]{Neutral drag coefficient from wave model (\protect\np{ln_cdgw}{ln\_cdgw})} 1261 1167 \label{subsec:SBC_wave_cdgw} 1262 1168 1263 The neutral surface drag coefficient provided from an external data source (\ie a wave model), 1264 can be used by setting the logical variable \np{ln\_cdgw} \forcode{= .true.} in \ngn{namsbc} namelist. 1265 Then using the routine \rou{turb\_ncar} and starting from the neutral drag coefficent provided, 1266 the drag coefficient is computed according to the stable/unstable conditions of the 1267 air-sea interface following \citet{Large_Yeager_Rep04}. 1268 1269 1270 % ================================================================ 1271 % 3D Stokes Drift (ln_sdw, nn_sdrift) 1272 % ================================================================ 1273 \subsection{3D Stokes Drift (\protect\np{ln\_sdw, nn\_sdrift})} 1169 The neutral surface drag coefficient provided from an external data source (\ie\ a wave model), 1170 can be used by setting the logical variable \np[=.true.]{ln_cdgw}{ln\_cdgw} in \nam{sbc}{sbc} namelist. 1171 Then using the routine \rou{sbcblk\_algo\_ncar} and starting from the neutral drag coefficent provided, 1172 the drag coefficient is computed according to the stable/unstable conditions of the 1173 air-sea interface following \citet{large.yeager_rpt04}. 1174 1175 %% ================================================================================================= 1176 \subsection[3D Stokes Drift (\forcode{ln_sdw} \& \forcode{nn_sdrift})]{3D Stokes Drift (\protect\np{ln_sdw}{ln\_sdw} \& \np{nn_sdrift}{nn\_sdrift})} 1274 1177 \label{subsec:SBC_wave_sdw} 1275 1178 1276 The Stokes drift is a wave driven mechanism of mass and momentum transport \citep{ Stokes_1847}.1277 It is defined as the difference between the average velocity of a fluid parcel (Lagrangian velocity) 1278 and the current measured at a fixed point (Eulerian velocity). 1279 As waves travel, the water particles that make up the waves travel in orbital motions but 1280 without a closed path. Their movement is enhanced at the top of the orbit and slowed slightly 1281 at the bottom so the result is a net forward motion of water particles, referred to as the Stokes drift.1282 An accurate evaluation of the Stokes drift and the inclusion of related processes may lead to improved 1283 representation of surface physics in ocean general circulation models. 1284 The Stokes drift velocity $\mathbf{U}_{st}$ in deep water can be computed from the wave spectrum and may be written as: 1179 The Stokes drift is a wave driven mechanism of mass and momentum transport \citep{stokes_ibk09}. 1180 It is defined as the difference between the average velocity of a fluid parcel (Lagrangian velocity) 1181 and the current measured at a fixed point (Eulerian velocity). 1182 As waves travel, the water particles that make up the waves travel in orbital motions but 1183 without a closed path. Their movement is enhanced at the top of the orbit and slowed slightly 1184 at the bottom, so the result is a net forward motion of water particles, referred to as the Stokes drift. 1185 An accurate evaluation of the Stokes drift and the inclusion of related processes may lead to improved 1186 representation of surface physics in ocean general circulation models. %GS: reference needed 1187 The Stokes drift velocity $\mathbf{U}_{st}$ in deep water can be computed from the wave spectrum and may be written as: 1285 1188 1286 1189 \[ 1287 % \label{eq: sbc_wave_sdw}1190 % \label{eq:SBC_wave_sdw} 1288 1191 \mathbf{U}_{st} = \frac{16{\pi^3}} {g} 1289 1192 \int_0^\infty \int_{-\pi}^{\pi} (cos{\theta},sin{\theta}) {f^3} … … 1291 1194 \] 1292 1195 1293 where: ${\theta}$ is the wave direction, $f$ is the wave intrinsic frequency, 1294 $\mathrm{S}($f$,\theta)$ is the 2D frequency-direction spectrum, 1295 $k$ is the mean wavenumber defined as: 1196 where: ${\theta}$ is the wave direction, $f$ is the wave intrinsic frequency, 1197 $\mathrm{S}($f$,\theta)$ is the 2D frequency-direction spectrum, 1198 $k$ is the mean wavenumber defined as: 1296 1199 $k=\frac{2\pi}{\lambda}$ (being $\lambda$ the wavelength). \\ 1297 1200 1298 In order to evaluate the Stokes drift in a realistic ocean wave field the wave spectral shape is required1299 and its computation quickly becomes expensive as the 2D spectrum must be integrated for each vertical level. 1201 In order to evaluate the Stokes drift in a realistic ocean wave field, the wave spectral shape is required 1202 and its computation quickly becomes expensive as the 2D spectrum must be integrated for each vertical level. 1300 1203 To simplify, it is customary to use approximations to the full Stokes profile. 1301 Three possible parameterizations for the calculation for the approximate Stokes drift velocity profile 1302 are included in the code through the \np{nn \_sdrift} parameter once provided the surface Stokes drift1303 $\mathbf{U}_{st |_{z=0}}$ which is evaluated by an external wave model that accurately reproduces the wave spectra 1304 and makes possible the estimation of the surface Stokes drift for random directional waves in 1204 Three possible parameterizations for the calculation for the approximate Stokes drift velocity profile 1205 are included in the code through the \np{nn_sdrift}{nn\_sdrift} parameter once provided the surface Stokes drift 1206 $\mathbf{U}_{st |_{z=0}}$ which is evaluated by an external wave model that accurately reproduces the wave spectra 1207 and makes possible the estimation of the surface Stokes drift for random directional waves in 1305 1208 realistic wave conditions: 1306 1209 1307 1210 \begin{description} 1308 \item [\np{nn\_sdrift} = 0]: exponential integral profile parameterization proposed by1309 \citet{ Breivik_al_JPO2014}:1211 \item [{\np{nn_sdrift}{nn\_sdrift} = 0}]: exponential integral profile parameterization proposed by 1212 \citet{breivik.janssen.ea_JPO14}: 1310 1213 1311 1214 \[ 1312 % \label{eq: sbc_wave_sdw_0a}1313 \mathbf{U}_{st} \cong \mathbf{U}_{st |_{z=0}} \frac{\mathrm{e}^{-2k_ez}} {1-8k_ez} 1215 % \label{eq:SBC_wave_sdw_0a} 1216 \mathbf{U}_{st} \cong \mathbf{U}_{st |_{z=0}} \frac{\mathrm{e}^{-2k_ez}} {1-8k_ez} 1314 1217 \] 1315 1218 … … 1317 1220 1318 1221 \[ 1319 % \label{eq: sbc_wave_sdw_0b}1222 % \label{eq:SBC_wave_sdw_0b} 1320 1223 k_e = \frac{|\mathbf{U}_{\left.st\right|_{z=0}}|} {|T_{st}|} 1321 1224 \quad \text{and }\ 1322 T_{st} = \frac{1}{16} \bar{\omega} H_s^2 1225 T_{st} = \frac{1}{16} \bar{\omega} H_s^2 1323 1226 \] 1324 1227 1325 1228 where $H_s$ is the significant wave height and $\omega$ is the wave frequency. 1326 1229 1327 \item [\np{nn\_sdrift} = 1]: velocity profile based on the Phillips spectrum which is considered to be a1328 reasonable estimate of the part of the spectrum most contributing to the Stokes drift velocity near the surface1329 \citep{ Breivik_al_OM2016}:1230 \item [{\np{nn_sdrift}{nn\_sdrift} = 1}]: velocity profile based on the Phillips spectrum which is considered to be a 1231 reasonable estimate of the part of the spectrum mostly contributing to the Stokes drift velocity near the surface 1232 \citep{breivik.bidlot.ea_OM16}: 1330 1233 1331 1234 \[ 1332 % \label{eq: sbc_wave_sdw_1}1235 % \label{eq:SBC_wave_sdw_1} 1333 1236 \mathbf{U}_{st} \cong \mathbf{U}_{st |_{z=0}} \Big[exp(2k_pz)-\beta \sqrt{-2 \pi k_pz} 1334 1237 \textit{ erf } \Big(\sqrt{-2 k_pz}\Big)\Big] … … 1337 1240 where $erf$ is the complementary error function and $k_p$ is the peak wavenumber. 1338 1241 1339 \item [\np{nn\_sdrift} = 2]: velocity profile based on the Phillips spectrum as for \np{nn\_sdrift} = 11242 \item [{\np{nn_sdrift}{nn\_sdrift} = 2}]: velocity profile based on the Phillips spectrum as for \np{nn_sdrift}{nn\_sdrift} = 1 1340 1243 but using the wave frequency from a wave model. 1341 1244 1342 1245 \end{description} 1343 1246 1344 The Stokes drift enters the wave-averaged momentum equation, as well as the tracer advection equations 1345 and its effect on the evolution of the sea-surface height ${\eta}$ is considered as follows: 1247 The Stokes drift enters the wave-averaged momentum equation, as well as the tracer advection equations 1248 and its effect on the evolution of the sea-surface height ${\eta}$ is considered as follows: 1346 1249 1347 1250 \[ 1348 % \label{eq: sbc_wave_eta_sdw}1251 % \label{eq:SBC_wave_eta_sdw} 1349 1252 \frac{\partial{\eta}}{\partial{t}} = 1350 1253 -\nabla_h \int_{-H}^{\eta} (\mathbf{U} + \mathbf{U}_{st}) dz 1351 1254 \] 1352 1255 1353 The tracer advection equation is also modified in order for Eulerian ocean models to properly account 1354 for unresolved wave effect. The divergence of the wave tracer flux equals the mean tracer advection 1355 that is induced by the three-dimensional Stokes velocity. 1356 The advective equation for a tracer $c$ combining the effects of the mean current and sea surface waves 1357 can be formulated as follows: 1256 The tracer advection equation is also modified in order for Eulerian ocean models to properly account 1257 for unresolved wave effect. The divergence of the wave tracer flux equals the mean tracer advection 1258 that is induced by the three-dimensional Stokes velocity. 1259 The advective equation for a tracer $c$ combining the effects of the mean current and sea surface waves 1260 can be formulated as follows: 1358 1261 1359 1262 \[ 1360 % \label{eq: sbc_wave_tra_sdw}1263 % \label{eq:SBC_wave_tra_sdw} 1361 1264 \frac{\partial{c}}{\partial{t}} = 1362 1265 - (\mathbf{U} + \mathbf{U}_{st}) \cdot \nabla{c} 1363 1266 \] 1364 1267 1365 1366 % ================================================================ 1367 % Stokes-Coriolis term (ln_stcor) 1368 % ================================================================ 1369 \subsection{Stokes-Coriolis term (\protect\np{ln\_stcor})} 1268 %% ================================================================================================= 1269 \subsection[Stokes-Coriolis term (\forcode{ln_stcor})]{Stokes-Coriolis term (\protect\np{ln_stcor}{ln\_stcor})} 1370 1270 \label{subsec:SBC_wave_stcor} 1371 1271 1372 In a rotating ocean, waves exert a wave-induced stress on the mean ocean circulation which results 1373 in a force equal to $\mathbf{U}_{st}$×$f$, where $f$ is the Coriolis parameter. 1374 This additional force may have impact on the Ekman turning of the surface current. 1375 In order to include this term, once evaluated the Stokes drift (using one of the 3 possible 1376 approximations described in \autoref{subsec:SBC_wave_sdw}), 1377 \np{ln\_stcor}\forcode{ = .true.} has to be set. 1378 1379 1380 % ================================================================ 1381 % Waves modified stress (ln_tauwoc, ln_tauw) 1382 % ================================================================ 1383 \subsection{Wave modified sress (\protect\np{ln\_tauwoc, ln\_tauw})} 1272 In a rotating ocean, waves exert a wave-induced stress on the mean ocean circulation which results 1273 in a force equal to $\mathbf{U}_{st}$×$f$, where $f$ is the Coriolis parameter. 1274 This additional force may have impact on the Ekman turning of the surface current. 1275 In order to include this term, once evaluated the Stokes drift (using one of the 3 possible 1276 approximations described in \autoref{subsec:SBC_wave_sdw}), 1277 \np[=.true.]{ln_stcor}{ln\_stcor} has to be set. 1278 1279 %% ================================================================================================= 1280 \subsection[Wave modified stress (\forcode{ln_tauwoc} \& \forcode{ln_tauw})]{Wave modified sress (\protect\np{ln_tauwoc}{ln\_tauwoc} \& \np{ln_tauw}{ln\_tauw})} 1384 1281 \label{subsec:SBC_wave_tauw} 1385 1282 1386 The surface stress felt by the ocean is the atmospheric stress minus the net stress going 1387 into the waves \citep{ Janssen_al_TM13}. Therefore, when waves are growing, momentum and energy is spent and is not1388 available for forcing the mean circulation, while in the opposite case of a decaying sea 1389 state more momentum is available for forcing the ocean.1390 Only when the sea state is in equilibrium the ocean is forced by the atmospheric stress,1391 but in practice an equilibrium sea state is a fairly rare event.1392 So the atmospheric stress felt by the ocean circulation $\tau_{oc,a}$ can be expressed as: 1283 The surface stress felt by the ocean is the atmospheric stress minus the net stress going 1284 into the waves \citep{janssen.breivik.ea_rpt13}. Therefore, when waves are growing, momentum and energy is spent and is not 1285 available for forcing the mean circulation, while in the opposite case of a decaying sea 1286 state, more momentum is available for forcing the ocean. 1287 Only when the sea state is in equilibrium, the ocean is forced by the atmospheric stress, 1288 but in practice, an equilibrium sea state is a fairly rare event. 1289 So the atmospheric stress felt by the ocean circulation $\tau_{oc,a}$ can be expressed as: 1393 1290 1394 1291 \[ 1395 % \label{eq: sbc_wave_tauoc}1292 % \label{eq:SBC_wave_tauoc} 1396 1293 \tau_{oc,a} = \tau_a - \tau_w 1397 1294 \] … … 1401 1298 1402 1299 \[ 1403 % \label{eq: sbc_wave_tauw}1300 % \label{eq:SBC_wave_tauw} 1404 1301 \tau_w = \rho g \int {\frac{dk}{c_p} (S_{in}+S_{nl}+S_{diss})} 1405 1302 \] 1406 1303 1407 1304 where: $c_p$ is the phase speed of the gravity waves, 1408 $S_{in}$, $S_{nl}$ and $S_{diss}$ are three source terms that represent 1409 the physics of ocean waves. The first one, $S_{in}$, describes the generation 1410 of ocean waves by wind and therefore represents the momentum and energy transfer 1411 from air to ocean waves; the second term $S_{nl}$ denotes 1412 the nonlinear transfer by resonant four-wave interactions; while the third term $S_{diss}$ 1413 describes the dissipation of waves by processes such as white-capping, large scale breaking 1305 $S_{in}$, $S_{nl}$ and $S_{diss}$ are three source terms that represent 1306 the physics of ocean waves. The first one, $S_{in}$, describes the generation 1307 of ocean waves by wind and therefore represents the momentum and energy transfer 1308 from air to ocean waves; the second term $S_{nl}$ denotes 1309 the nonlinear transfer by resonant four-wave interactions; while the third term $S_{diss}$ 1310 describes the dissipation of waves by processes such as white-capping, large scale breaking 1414 1311 eddy-induced damping. 1415 1312 1416 The wave stress derived from an external wave model can be provided either through the normalized 1417 wave stress into the ocean by setting \np{ln\_tauwoc}\forcode{ = .true.}, or through the zonal and 1418 meridional stress components by setting \np{ln\_tauw}\forcode{ = .true.}. 1419 1420 1421 % ================================================================ 1422 % Miscellanea options 1423 % ================================================================ 1313 The wave stress derived from an external wave model can be provided either through the normalized 1314 wave stress into the ocean by setting \np[=.true.]{ln_tauwoc}{ln\_tauwoc}, or through the zonal and 1315 meridional stress components by setting \np[=.true.]{ln_tauw}{ln\_tauw}. 1316 1317 %% ================================================================================================= 1424 1318 \section{Miscellaneous options} 1425 1319 \label{sec:SBC_misc} 1426 1320 1427 % ------------------------------------------------------------------------------------------------------------- 1428 % Diurnal cycle 1429 % ------------------------------------------------------------------------------------------------------------- 1430 \subsection{Diurnal cycle (\protect\mdl{sbcdcy})} 1321 %% ================================================================================================= 1322 \subsection[Diurnal cycle (\textit{sbcdcy.F90})]{Diurnal cycle (\protect\mdl{sbcdcy})} 1431 1323 \label{subsec:SBC_dcy} 1432 %------------------------------------------namsbc_rnf---------------------------------------------------- 1433 % 1434 \nlst{namsbc} 1435 %------------------------------------------------------------------------------------------------------------- 1436 1437 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1324 1438 1325 \begin{figure}[!t] 1439 \begin{center} 1440 \includegraphics[width=0.8\textwidth]{Fig_SBC_diurnal} 1441 \caption{ 1442 \protect\label{fig:SBC_diurnal} 1443 Example of recontruction of the diurnal cycle variation of short wave flux from daily mean values. 1444 The reconstructed diurnal cycle (black line) is chosen as 1445 the mean value of the analytical cycle (blue line) over a time step, 1446 not as the mid time step value of the analytically cycle (red square). 1447 From \citet{Bernie_al_CD07}. 1448 } 1449 \end{center} 1326 \centering 1327 \includegraphics[width=0.66\textwidth]{SBC_diurnal} 1328 \caption[Reconstruction of the diurnal cycle variation of short wave flux]{ 1329 Example of reconstruction of the diurnal cycle variation of short wave flux from 1330 daily mean values. 1331 The reconstructed diurnal cycle (black line) is chosen as 1332 the mean value of the analytical cycle (blue line) over a time step, 1333 not as the mid time step value of the analytically cycle (red square). 1334 From \citet{bernie.guilyardi.ea_CD07}.} 1335 \label{fig:SBC_diurnal} 1450 1336 \end{figure} 1451 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1452 1453 \cite{Bernie_al_JC05} have shown that to capture 90$\%$ of the diurnal variability of SST requires a vertical resolution in upper ocean of 1~m or better and a temporal resolution of the surface fluxes of 3~h or less. 1454 Unfortunately high frequency forcing fields are rare, not to say inexistent. 1455 Nevertheless, it is possible to obtain a reasonable diurnal cycle of the SST knowning only short wave flux (SWF) at 1456 high frequency \citep{Bernie_al_CD07}. 1337 1338 \cite{bernie.woolnough.ea_JC05} have shown that to capture 90$\%$ of the diurnal variability of SST requires a vertical resolution in upper ocean of 1~m or better and a temporal resolution of the surface fluxes of 3~h or less. 1339 %Unfortunately high frequency forcing fields are rare, not to say inexistent. GS: not true anymore ! 1340 Nevertheless, it is possible to obtain a reasonable diurnal cycle of the SST knowning only short wave flux (SWF) at high frequency \citep{bernie.guilyardi.ea_CD07}. 1457 1341 Furthermore, only the knowledge of daily mean value of SWF is needed, 1458 1342 as higher frequency variations can be reconstructed from them, 1459 1343 assuming that the diurnal cycle of SWF is a scaling of the top of the atmosphere diurnal cycle of incident SWF. 1460 The \cite{ Bernie_al_CD07} reconstruction algorithm is available in \NEMOby1461 setting \np {ln\_dm2dc}\forcode{ = .true.} (a \textit{\ngn{namsbc}} namelist variable) when1462 using CORE bulk formulea (\np{ln\_blk\_core}\forcode{ = .true.}) or1463 the flux formulation (\np {ln\_flx}\forcode{ = .true.}).1344 The \cite{bernie.guilyardi.ea_CD07} reconstruction algorithm is available in \NEMO\ by 1345 setting \np[=.true.]{ln_dm2dc}{ln\_dm2dc} (a \textit{\nam{sbc}{sbc}} namelist variable) when 1346 using a bulk formulation (\np[=.true.]{ln_blk}{ln\_blk}) or 1347 the flux formulation (\np[=.true.]{ln_flx}{ln\_flx}). 1464 1348 The reconstruction is performed in the \mdl{sbcdcy} module. 1465 The detail of the algoritm used can be found in the appendix~A of \cite{ Bernie_al_CD07}.1466 The algorithm preserve the daily mean incoming SWF as the reconstructed SWF at1349 The detail of the algoritm used can be found in the appendix~A of \cite{bernie.guilyardi.ea_CD07}. 1350 The algorithm preserves the daily mean incoming SWF as the reconstructed SWF at 1467 1351 a given time step is the mean value of the analytical cycle over this time step (\autoref{fig:SBC_diurnal}). 1468 1352 The use of diurnal cycle reconstruction requires the input SWF to be daily 1469 (\ie a frequency of 24 and a time interpolation set to true in \np{sn\_qsr} namelist parameter).1470 Furthermore, it is recommended to have a least 8 surface module time step per day,1353 (\ie\ a frequency of 24 hours and a time interpolation set to true in \np{sn_qsr}{sn\_qsr} namelist parameter). 1354 Furthermore, it is recommended to have a least 8 surface module time steps per day, 1471 1355 that is $\rdt \ nn\_fsbc < 10,800~s = 3~h$. 1472 1356 An example of recontructed SWF is given in \autoref{fig:SBC_dcy} for a 12 reconstructed diurnal cycle, 1473 1357 one every 2~hours (from 1am to 11pm). 1474 1358 1475 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>1476 1359 \begin{figure}[!t] 1477 \begin{center} 1478 \includegraphics[width=0.7\textwidth]{Fig_SBC_dcy} 1479 \caption{ 1480 \protect\label{fig:SBC_dcy} 1481 Example of recontruction of the diurnal cycle variation of short wave flux from 1482 daily mean values on an ORCA2 grid with a time sampling of 2~hours (from 1am to 11pm). 1483 The display is on (i,j) plane. 1484 } 1485 \end{center} 1360 \centering 1361 \includegraphics[width=0.66\textwidth]{SBC_dcy} 1362 \caption[Reconstruction of the diurnal cycle variation of short wave flux on an ORCA2 grid]{ 1363 Example of reconstruction of the diurnal cycle variation of short wave flux from 1364 daily mean values on an ORCA2 grid with a time sampling of 2~hours (from 1am to 11pm). 1365 The display is on (i,j) plane.} 1366 \label{fig:SBC_dcy} 1486 1367 \end{figure} 1487 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>1488 1368 1489 1369 Note also that the setting a diurnal cycle in SWF is highly recommended when … … 1491 1371 an inconsistency between the scale of the vertical resolution and the forcing acting on that scale. 1492 1372 1493 % ------------------------------------------------------------------------------------------------------------- 1494 % Rotation of vector pairs onto the model grid directions 1495 % ------------------------------------------------------------------------------------------------------------- 1373 %% ================================================================================================= 1496 1374 \subsection{Rotation of vector pairs onto the model grid directions} 1497 1375 \label{subsec:SBC_rotation} 1498 1376 1499 When using a flux (\np{ln\_flx}\forcode{ = .true.}) or 1500 bulk (\np{ln\_clio}\forcode{ = .true.} or \np{ln\_core}\forcode{ = .true.}) formulation, 1377 When using a flux (\np[=.true.]{ln_flx}{ln\_flx}) or bulk (\np[=.true.]{ln_blk}{ln\_blk}) formulation, 1501 1378 pairs of vector components can be rotated from east-north directions onto the local grid directions. 1502 1379 This is particularly useful when interpolation on the fly is used since here any vectors are likely to 1503 1380 be defined relative to a rectilinear grid. 1504 To activate this option a non-empty string is supplied in the rotation pair column of the relevant namelist.1505 The eastward component must start with "U" and the northward component with "V". 1381 To activate this option, a non-empty string is supplied in the rotation pair column of the relevant namelist. 1382 The eastward component must start with "U" and the northward component with "V". 1506 1383 The remaining characters in the strings are used to identify which pair of components go together. 1507 1384 So for example, strings "U1" and "V1" next to "utau" and "vtau" would pair the wind stress components together and … … 1511 1388 The rot\_rep routine from the \mdl{geo2ocean} module is used to perform the rotation. 1512 1389 1513 % ------------------------------------------------------------------------------------------------------------- 1514 % Surface restoring to observed SST and/or SSS 1515 % ------------------------------------------------------------------------------------------------------------- 1516 \subsection{Surface restoring to observed SST and/or SSS (\protect\mdl{sbcssr})} 1390 %% ================================================================================================= 1391 \subsection[Surface restoring to observed SST and/or SSS (\textit{sbcssr.F90})]{Surface restoring to observed SST and/or SSS (\protect\mdl{sbcssr})} 1517 1392 \label{subsec:SBC_ssr} 1518 %------------------------------------------namsbc_ssr---------------------------------------------------- 1519 1520 \nlst{namsbc_ssr} 1521 %------------------------------------------------------------------------------------------------------------- 1522 1523 IOptions are defined through the \ngn{namsbc\_ssr} namelist variables. 1524 On forced mode using a flux formulation (\np{ln\_flx}\forcode{ = .true.}), 1393 1394 \begin{listing} 1395 \nlst{namsbc_ssr} 1396 \caption{\forcode{&namsbc_ssr}} 1397 \label{lst:namsbc_ssr} 1398 \end{listing} 1399 1400 Options are defined through the \nam{sbc_ssr}{sbc\_ssr} namelist variables. 1401 On forced mode using a flux formulation (\np[=.true.]{ln_flx}{ln\_flx}), 1525 1402 a feedback term \emph{must} be added to the surface heat flux $Q_{ns}^o$: 1526 1403 \[ 1527 % \label{eq: sbc_dmp_q}1404 % \label{eq:SBC_dmp_q} 1528 1405 Q_{ns} = Q_{ns}^o + \frac{dQ}{dT} \left( \left. T \right|_{k=1} - SST_{Obs} \right) 1529 1406 \] … … 1531 1408 $T$ is the model surface layer temperature and 1532 1409 $\frac{dQ}{dT}$ is a negative feedback coefficient usually taken equal to $-40~W/m^2/K$. 1533 For a $50~m$ mixed-layer depth, this value corresponds to a relaxation time scale of two months. 1534 This term ensures that if $T$ perfectly matches the supplied SST, then $Q$ is equal to $Q_o$. 1410 For a $50~m$ mixed-layer depth, this value corresponds to a relaxation time scale of two months. 1411 This term ensures that if $T$ perfectly matches the supplied SST, then $Q$ is equal to $Q_o$. 1535 1412 1536 1413 In the fresh water budget, a feedback term can also be added. … … 1538 1415 1539 1416 \begin{equation} 1540 \label{eq: sbc_dmp_emp}1417 \label{eq:SBC_dmp_emp} 1541 1418 \textit{emp} = \textit{emp}_o + \gamma_s^{-1} e_{3t} \frac{ \left(\left.S\right|_{k=1}-SSS_{Obs}\right)} 1542 1419 {\left.S\right|_{k=1}} … … 1546 1423 (observed, climatological or an atmospheric model product), 1547 1424 \textit{SSS}$_{Obs}$ is a sea surface salinity 1548 (usually a time interpolation of the monthly mean Polar Hydrographic Climatology \citep{ Steele2001}),1425 (usually a time interpolation of the monthly mean Polar Hydrographic Climatology \citep{steele.morley.ea_JC01}), 1549 1426 $\left.S\right|_{k=1}$ is the model surface layer salinity and 1550 1427 $\gamma_s$ is a negative feedback coefficient which is provided as a namelist parameter. 1551 Unlike heat flux, there is no physical justification for the feedback term in \autoref{eq: sbc_dmp_emp} as1552 the atmosphere does not care about ocean surface salinity \citep{ Madec1997}.1428 Unlike heat flux, there is no physical justification for the feedback term in \autoref{eq:SBC_dmp_emp} as 1429 the atmosphere does not care about ocean surface salinity \citep{madec.delecluse_IWN97}. 1553 1430 The SSS restoring term should be viewed as a flux correction on freshwater fluxes to 1554 1431 reduce the uncertainties we have on the observed freshwater budget. 1555 1432 1556 % ------------------------------------------------------------------------------------------------------------- 1557 % Handling of ice-covered area 1558 % ------------------------------------------------------------------------------------------------------------- 1433 %% ================================================================================================= 1559 1434 \subsection{Handling of ice-covered area (\textit{sbcice\_...})} 1560 1435 \label{subsec:SBC_ice-cover} … … 1562 1437 The presence at the sea surface of an ice covered area modifies all the fluxes transmitted to the ocean. 1563 1438 There are several way to handle sea-ice in the system depending on 1564 the value of the \np{nn \_ice} namelist parameter found in \ngn{namsbc} namelist.1439 the value of the \np{nn_ice}{nn\_ice} namelist parameter found in \nam{sbc}{sbc} namelist. 1565 1440 \begin{description} 1566 \item[nn{\_}ice = 0] 1567 there will never be sea-ice in the computational domain. 1441 \item [nn\_ice = 0] there will never be sea-ice in the computational domain. 1568 1442 This is a typical namelist value used for tropical ocean domain. 1569 1443 The surface fluxes are simply specified for an ice-free ocean. 1570 1444 No specific things is done for sea-ice. 1571 \item[nn{\_}ice = 1] 1572 sea-ice can exist in the computational domain, but no sea-ice model is used. 1445 \item [nn\_ice = 1] sea-ice can exist in the computational domain, but no sea-ice model is used. 1573 1446 An observed ice covered area is read in a file. 1574 1447 Below this area, the SST is restored to the freezing point and … … 1578 1451 This prevents deep convection to occur when trying to reach the freezing point 1579 1452 (and so ice covered area condition) while the SSS is too large. 1580 This manner of managing sea-ice area, just by using siIF case,1453 This manner of managing sea-ice area, just by using a IF case, 1581 1454 is usually referred as the \textit{ice-if} model. 1582 It can be found in the \mdl{sbcice{\_}if} module. 1583 \item[nn{\_}ice = 2 or more] 1584 A full sea ice model is used. 1455 It can be found in the \mdl{sbcice\_if} module. 1456 \item [nn\_ice = 2 or more] A full sea ice model is used. 1585 1457 This model computes the ice-ocean fluxes, 1586 1458 that are combined with the air-sea fluxes using the ice fraction of each model cell to 1587 provide the surface ocean fluxes.1588 Note that the activation of a sea-ice model is is done by defining a CPP key (\key{lim3} or \key{cice}).1589 The activation automatically overwrites the read value of nn {\_}ice to its appropriate value1590 (\ie $2$ for LIM-3 or $3$ for CICE).1459 provide the surface averaged ocean fluxes. 1460 Note that the activation of a sea-ice model is done by defining a CPP key (\key{si3} or \key{cice}). 1461 The activation automatically overwrites the read value of nn\_ice to its appropriate value 1462 (\ie\ $2$ for SI3 or $3$ for CICE). 1591 1463 \end{description} 1592 1464 1593 1465 % {Description of Ice-ocean interface to be added here or in LIM 2 and 3 doc ?} 1594 1595 \subsection{Interface to CICE (\protect\mdl{sbcice\_cice})} 1466 %GS: ocean-ice (SI3) interface is not located in SBC directory anymore, so it should be included in SI3 doc 1467 1468 %% ================================================================================================= 1469 \subsection[Interface to CICE (\textit{sbcice\_cice.F90})]{Interface to CICE (\protect\mdl{sbcice\_cice})} 1596 1470 \label{subsec:SBC_cice} 1597 1471 1598 It is now possible to couple a regional or global NEMOconfiguration (without AGRIF)1472 It is possible to couple a regional or global \NEMO\ configuration (without AGRIF) 1599 1473 to the CICE sea-ice model by using \key{cice}. 1600 1474 The CICE code can be obtained from \href{http://oceans11.lanl.gov/trac/CICE/}{LANL} and 1601 1475 the additional 'hadgem3' drivers will be required, even with the latest code release. 1602 Input grid files consistent with those used in NEMOwill also be needed,1476 Input grid files consistent with those used in \NEMO\ will also be needed, 1603 1477 and CICE CPP keys \textbf{ORCA\_GRID}, \textbf{CICE\_IN\_NEMO} and \textbf{coupled} should be used 1604 1478 (seek advice from UKMO if necessary). 1605 Currently the code is only designed to work when using the CORE forcing option for NEMO1606 (with \textit{calc\_strair}\forcode{ = .true.} and \textit{calc\_Tsfc}\forcode{ =.true.} in the CICE name-list),1607 or alternatively when NEMOis coupled to the HadGAM3 atmosphere model1608 (with \textit{calc\_strair}\forcode{ = .false.} and \textit{calc\_Tsfc}\forcode{ =false}).1609 The code is intended to be used with \np{nn \_fsbc} set to 11479 Currently, the code is only designed to work when using the NCAR forcing option for \NEMO\ %GS: still true ? 1480 (with \textit{calc\_strair}\forcode{=.true.} and \textit{calc\_Tsfc}\forcode{=.true.} in the CICE name-list), 1481 or alternatively when \NEMO\ is coupled to the HadGAM3 atmosphere model 1482 (with \textit{calc\_strair}\forcode{=.false.} and \textit{calc\_Tsfc}\forcode{=false}). 1483 The code is intended to be used with \np{nn_fsbc}{nn\_fsbc} set to 1 1610 1484 (although coupling ocean and ice less frequently should work, 1611 1485 it is possible the calculation of some of the ocean-ice fluxes needs to be modified slightly - 1612 1486 the user should check that results are not significantly different to the standard case). 1613 1487 1614 There are two options for the technical coupling between NEMOand CICE.1488 There are two options for the technical coupling between \NEMO\ and CICE. 1615 1489 The standard version allows complete flexibility for the domain decompositions in the individual models, 1616 1490 but this is at the expense of global gather and scatter operations in the coupling which 1617 1491 become very expensive on larger numbers of processors. 1618 The alternative option (using \key{nemocice\_decomp} for both NEMOand CICE) ensures that1492 The alternative option (using \key{nemocice\_decomp} for both \NEMO\ and CICE) ensures that 1619 1493 the domain decomposition is identical in both models (provided domain parameters are set appropriately, 1620 1494 and \textit{processor\_shape~=~square-ice} and \textit{distribution\_wght~=~block} in the CICE name-list) and … … 1623 1497 there is no sea ice. 1624 1498 1625 % ------------------------------------------------------------------------------------------------------------- 1626 % Freshwater budget control 1627 % ------------------------------------------------------------------------------------------------------------- 1628 \subsection{Freshwater budget control (\protect\mdl{sbcfwb})} 1499 %% ================================================================================================= 1500 \subsection[Freshwater budget control (\textit{sbcfwb.F90})]{Freshwater budget control (\protect\mdl{sbcfwb})} 1629 1501 \label{subsec:SBC_fwb} 1630 1502 1631 For global ocean simulation it can be useful to introduce a control of the mean sea level in order to1503 For global ocean simulation, it can be useful to introduce a control of the mean sea level in order to 1632 1504 prevent unrealistic drift of the sea surface height due to inaccuracy in the freshwater fluxes. 1633 In \NEMO, two way of controlling the the freshwater budget. 1505 In \NEMO, two way of controlling the freshwater budget are proposed: 1506 1634 1507 \begin{description} 1635 \item[\np{nn\_fwb}\forcode{ = 0}] 1636 no control at all. 1508 \item [{\np[=0]{nn_fwb}{nn\_fwb}}] no control at all. 1637 1509 The mean sea level is free to drift, and will certainly do so. 1638 \item[\np{nn\_fwb}\forcode{ = 1}] 1639 global mean \textit{emp} set to zero at each model time step. 1640 %Note that with a sea-ice model, this technique only control the mean sea level with linear free surface (\key{vvl} not defined) and no mass flux between ocean and ice (as it is implemented in the current ice-ocean coupling). 1641 \item[\np{nn\_fwb}\forcode{ = 2}] 1642 freshwater budget is adjusted from the previous year annual mean budget which 1510 \item [{\np[=1]{nn_fwb}{nn\_fwb}}] global mean \textit{emp} set to zero at each model time step. 1511 %GS: comment below still relevant ? 1512 %Note that with a sea-ice model, this technique only controls the mean sea level with linear free surface and no mass flux between ocean and ice (as it is implemented in the current ice-ocean coupling). 1513 \item [{\np[=2]{nn_fwb}{nn\_fwb}}] freshwater budget is adjusted from the previous year annual mean budget which 1643 1514 is read in the \textit{EMPave\_old.dat} file. 1644 1515 As the model uses the Boussinesq approximation, the annual mean fresh water budget is simply evaluated from 1645 the change in the mean sea level at January the first and saved in the \textit{EMPav.dat} file. 1516 the change in the mean sea level at January the first and saved in the \textit{EMPav.dat} file. 1646 1517 \end{description} 1647 1518 1648 1649 1650 1519 % Griffies doc: 1651 % When running ocean-ice simulations, we are not explicitly representing land processes, 1652 % such as rivers, catchment areas, snow accumulation, etc. However, to reduce model drift, 1653 % it is important to balance the hydrological cycle in ocean-ice models. 1654 % We thus need to prescribe some form of global normalization to the precipitation minus evaporation plus river runoff. 1655 % The result of the normalization should be a global integrated zero net water input to the ocean-ice system over 1656 % a chosen time scale. 1657 %How often the normalization is done is a matter of choice. In mom4p1, we choose to do so at each model time step, 1658 % so that there is always a zero net input of water to the ocean-ice system. 1659 % Others choose to normalize over an annual cycle, in which case the net imbalance over an annual cycle is used 1660 % to alter the subsequent year�s water budget in an attempt to damp the annual water imbalance. 1661 % Note that the annual budget approach may be inappropriate with interannually varying precipitation forcing. 1662 % When running ocean-ice coupled models, it is incorrect to include the water transport between the ocean 1663 % and ice models when aiming to balance the hydrological cycle. 1664 % The reason is that it is the sum of the water in the ocean plus ice that should be balanced when running ocean-ice models, 1665 % not the water in any one sub-component. As an extreme example to illustrate the issue, 1666 % consider an ocean-ice model with zero initial sea ice. As the ocean-ice model spins up, 1667 % there should be a net accumulation of water in the growing sea ice, and thus a net loss of water from the ocean. 1668 % The total water contained in the ocean plus ice system is constant, but there is an exchange of water between 1669 % the subcomponents. This exchange should not be part of the normalization used to balance the hydrological cycle 1670 % in ocean-ice models. 1671 1672 \biblio 1673 1674 \pindex 1520 % When running ocean-ice simulations, we are not explicitly representing land processes, 1521 % such as rivers, catchment areas, snow accumulation, etc. However, to reduce model drift, 1522 % it is important to balance the hydrological cycle in ocean-ice models. 1523 % We thus need to prescribe some form of global normalization to the precipitation minus evaporation plus river runoff. 1524 % The result of the normalization should be a global integrated zero net water input to the ocean-ice system over 1525 % a chosen time scale. 1526 % How often the normalization is done is a matter of choice. In mom4p1, we choose to do so at each model time step, 1527 % so that there is always a zero net input of water to the ocean-ice system. 1528 % Others choose to normalize over an annual cycle, in which case the net imbalance over an annual cycle is used 1529 % to alter the subsequent year�s water budget in an attempt to damp the annual water imbalance. 1530 % Note that the annual budget approach may be inappropriate with interannually varying precipitation forcing. 1531 % When running ocean-ice coupled models, it is incorrect to include the water transport between the ocean 1532 % and ice models when aiming to balance the hydrological cycle. 1533 % The reason is that it is the sum of the water in the ocean plus ice that should be balanced when running ocean-ice models, 1534 % not the water in any one sub-component. As an extreme example to illustrate the issue, 1535 % consider an ocean-ice model with zero initial sea ice. As the ocean-ice model spins up, 1536 % there should be a net accumulation of water in the growing sea ice, and thus a net loss of water from the ocean. 1537 % The total water contained in the ocean plus ice system is constant, but there is an exchange of water between 1538 % the subcomponents. This exchange should not be part of the normalization used to balance the hydrological cycle 1539 % in ocean-ice models. 1540 1541 \subinc{\input{../../global/epilogue}} 1675 1542 1676 1543 \end{document} -
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_STO.tex
r10442 r11831 2 2 3 3 \begin{document} 4 % ================================================================ 5 % Chapter stochastic parametrization of EOS (STO) 6 % ================================================================ 4 7 5 \chapter{Stochastic Parametrization of EOS (STO)} 8 6 \label{chap:STO} 9 7 10 Authors: P.-A. Bouttier 11 12 \minitoc 13 14 \newpage 15 16 The stochastic parametrization module aims to explicitly simulate uncertainties in the model. 17 More particularly, \cite{Brankart_OM2013} has shown that, 18 because of the nonlinearity of the seawater equation of state, unresolved scales represent a major source of 19 uncertainties in the computation of the large scale horizontal density gradient (from T/S large scale fields), 20 and that the impact of these uncertainties can be simulated by 21 random processes representing unresolved T/S fluctuations. 22 23 The stochastic formulation of the equation of state can be written as: 8 \thispagestyle{plain} 9 10 \chaptertoc 11 12 \paragraph{Changes record} ~\\ 13 14 {\footnotesize 15 \begin{tabularx}{\textwidth}{l||X|X} 16 Release & Author(s) & Modifications \\ 17 \hline 18 {\em 4.0} & {\em ...} & {\em ...} \\ 19 {\em 3.6} & {\em ...} & {\em ...} \\ 20 {\em 3.4} & {\em ...} & {\em ...} \\ 21 {\em <=3.4} & {\em ...} & {\em ...} 22 \end{tabularx} 23 } 24 25 % \vfill 26 % \begin{figure}[b] 27 %% ================================================================================================= 28 % \subsubsection*{Changes record} 29 % \begin{tabular}{l||l|m{0.65\linewidth}} 30 % Release & Author & Modifications \\ 31 % {\em 4.0.1} & {\em C. Levy} & {\em 4.0.1 update} \\ 32 % {\em 3.6} & {\em P.-A. Bouttier} & {\em initial version} \\ 33 % \end{tabular} 34 % \end{figure} 35 36 \clearpage 37 38 As a result of the nonlinearity of the seawater equation of state, unresolved scales represent a major source of uncertainties in the computation of the large-scale horizontal density gradient from the large-scale temperature and salinity fields. Following \cite{brankart_OM13}, the impact of these uncertainties can be simulated by random processes representing unresolved T/S fluctuations. The Stochastic Parametrization of EOS (STO) module implements this parametrization. 39 40 As detailed in \cite{brankart_OM13}, the stochastic formulation of the equation of state can be written as: 24 41 \begin{equation} 25 \label{eq: eos_sto}42 \label{eq:STO_eos_sto} 26 43 \rho = \frac{1}{2} \sum_{i=1}^m\{ \rho[T+\Delta T_i,S+\Delta S_i,p_o(z)] + \rho[T-\Delta T_i,S-\Delta S_i,p_o(z)] \} 27 44 \end{equation} 28 45 where $p_o(z)$ is the reference pressure depending on the depth and, 29 $\Delta T_i$ and $\Delta S_i$ area set of T/S perturbations defined as46 $\Delta T_i$ and $\Delta S_i$ (i=1,m) is a set of T/S perturbations defined as 30 47 the scalar product of the respective local T/S gradients with random walks $\mathbf{\xi}$: 31 48 \begin{equation} 32 \label{eq: sto_pert}49 \label{eq:STO_sto_pert} 33 50 \Delta T_i = \mathbf{\xi}_i \cdot \nabla T \qquad \hbox{and} \qquad \Delta S_i = \mathbf{\xi}_i \cdot \nabla S 34 51 \end{equation} 35 $\mathbf{\xi}_i$ are produced by a first-order autoregressive process es(AR-1) with52 $\mathbf{\xi}_i$ are produced by a first-order autoregressive process (AR-1) with 36 53 a parametrized decorrelation time scale, and horizontal and vertical standard deviations $\sigma_s$. 37 54 $\mathbf{\xi}$ are uncorrelated over the horizontal and fully correlated along the vertical. 38 55 39 56 %% ================================================================================================= 40 57 \section{Stochastic processes} 41 58 \label{sec:STO_the_details} 42 59 43 The starting point of our implementation of stochastic parameterizations in NEMO is to observe that 44 many existing parameterizations are based on autoregressive processes, 60 There are many existing parameterizations based on autoregressive processes, 45 61 which are used as a basic source of randomness to transform a deterministic model into a probabilistic model. 46 A generic approach is thus to add one single new module in NEMO,47 generating processes with appropriate statistics to simulate each kind of uncertaintyin the model48 (see \cite{ Brankart_al_GMD2015} for more details).49 50 In practice, at e verymodel grid point,62 The generic approach here is to a new STO module, 63 generating processes features with appropriate statistics to simulate these uncertainties in the model 64 (see \cite{brankart.candille.ea_GMD15} for more details). 65 66 In practice, at each model grid point, 51 67 independent Gaussian autoregressive processes~$\xi^{(i)},\,i=1,\ldots,m$ are first generated using 52 68 the same basic equation: 53 69 54 70 \begin{equation} 55 \label{eq: autoreg}71 \label{eq:STO_autoreg} 56 72 \xi^{(i)}_{k+1} = a^{(i)} \xi^{(i)}_k + b^{(i)} w^{(i)} + c^{(i)} 57 73 \end{equation} … … 63 79 64 80 \begin{itemize} 65 \item 66 for order~1 processes, $w^{(i)}$ is a Gaussian white noise, with zero mean and standard deviation equal to~1, 81 \item for order~1 processes, $w^{(i)}$ is a Gaussian white noise, with zero mean and standard deviation equal to~1, 67 82 and the parameters $a^{(i)}$, $b^{(i)}$, $c^{(i)}$ are given by: 68 83 69 84 \[ 70 % \label{eq: ord1}85 % \label{eq:STO_ord1} 71 86 \left\{ 72 87 \begin{array}{l} … … 78 93 \] 79 94 80 \item 81 for order~$n>1$ processes, $w^{(i)}$ is an order~$n-1$ autoregressive process, with zero mean, 95 \item for order~$n>1$ processes, $w^{(i)}$ is an order~$n-1$ autoregressive process, with zero mean, 82 96 standard deviation equal to~$\sigma^{(i)}$; 83 97 correlation timescale equal to~$\tau^{(i)}$; … … 85 99 86 100 \begin{equation} 87 \label{eq: ord2}101 \label{eq:STO_ord2} 88 102 \left\{ 89 103 \begin{array}{l} … … 101 115 \noindent 102 116 In this way, higher order processes can be easily generated recursively using the same piece of code implementing 103 (\autoref{eq:autoreg}), and using succesivelyprocesses from order $0$ to~$n-1$ as~$w^{(i)}$.104 The parameters in (\autoref{eq:ord2})are computed so that this recursive application of105 (\autoref{eq:autoreg})leads to processes with the required standard deviation and correlation timescale,117 \autoref{eq:STO_autoreg}, and using successive processes from order $0$ to~$n-1$ as~$w^{(i)}$. 118 The parameters in \autoref{eq:STO_ord2} are computed so that this recursive application of 119 \autoref{eq:STO_autoreg} leads to processes with the required standard deviation and correlation timescale, 106 120 with the additional condition that the $n-1$ first derivatives of the autocorrelation function are equal to 107 zero at~$t=0$, so that the resulting processes become smoother and smoother as $n$ i s increased.121 zero at~$t=0$, so that the resulting processes become smoother and smoother as $n$ increases. 108 122 109 123 Overall, this method provides quite a simple and generic way of generating a wide class of stochastic processes. 110 124 However, this also means that new model parameters are needed to specify each of these stochastic processes. 111 As in any parameterization of lacking physics, a very important issues then to tune these newparameters using125 As in any parameterization, the main issue is to tune the parameters using 112 126 either first principles, model simulations, or real-world observations. 113 127 The parameters are set by default as described in \cite{brankart_OM13}, which has been shown in the paper 128 to give good results for a global low resolution (2°) \NEMO\ configuration. where this parametrization produces a major effect on the average large-scale circulation, especilally in regions of intense mesoscale activity. 129 The set of parameters will need further investigation to find appropriate values 130 for any other configuration or resolution of the model. 131 132 %% ================================================================================================= 114 133 \section{Implementation details} 115 134 \label{sec:STO_thech_details} 116 135 117 %---------------------------------------namsbc-------------------------------------------------- 118 119 \nlst{namsto} 120 %-------------------------------------------------------------------------------------------------------------- 121 122 The computer code implementing stochastic parametrisations can be found in the STO directory. 123 It involves three modules : 124 \begin{description} 125 \item[\mdl{stopar}:] 126 define the Stochastic parameters and their time evolution. 127 \item[\mdl{storng}:] 128 a random number generator based on (and includes) the 64-bit KISS (Keep It Simple Stupid) random number generator 129 distributed by George Marsaglia 130 (see \href{https://groups.google.com/forum/#!searchin/comp.lang.fortran/64-bit$20KISS$20RNGs}{here}) 131 \item[\mdl{stopts}:] 132 stochastic parametrisation associated with the non-linearity of the equation of seawater, 133 implementing \autoref{eq:sto_pert} and specific piece of code in 134 the equation of state implementing \autoref{eq:eos_sto}. 135 \end{description} 136 137 The \mdl{stopar} module has 3 public routines to be called by the model (in our case, NEMO): 138 139 The first routine (\rou{sto\_par}) is a direct implementation of (\autoref{eq:autoreg}), 136 The code implementing stochastic parametrisation is located in the src/OCE/STO directory. 137 It contains three modules : 138 % \begin{description} 139 140 \mdl{stopar} : define the Stochastic parameters and their time evolution 141 142 \mdl{storng} : random number generator based on and including the 64-bit KISS (Keep It Simple Stupid) random number generator distributed by George Marsaglia 143 144 \mdl{stopts} : stochastic parametrisation associated with the non-linearity of the equation of 145 seawater, implementing \autoref{eq:STO_sto_pert} so as specifics in the equation of state 146 implementing \autoref{eq:STO_eos_sto}. 147 % \end{description} 148 149 The \mdl{stopar} module includes three public routines called in the model: 150 151 (\rou{sto\_par}) is a direct implementation of \autoref{eq:STO_autoreg}, 140 152 applied at each model grid point (in 2D or 3D), and called at each model time step ($k$) to 141 153 update every autoregressive process ($i=1,\ldots,m$). … … 143 155 to introduce a spatial correlation between the stochastic processes. 144 156 145 The second routine (\rou{sto\_par\_init}) is an initialization routine mainly dedicated to 146 the computation of parameters $a^{(i)}, b^{(i)}, c^{(i)}$ for each autoregressive process,157 (\rou{sto\_par\_init}) is the initialization routine computing 158 the values $a^{(i)}, b^{(i)}, c^{(i)}$ for each autoregressive process, 147 159 as a function of the statistical properties required by the model user 148 (mean, standard deviation, time correlation, order of the process,\ldots). 149 150 Parameters for the processes can be specified through the following \ngn{namsto} namelist parameters: 151 \begin{description} 152 \item[\np{nn\_sto\_eos}:] number of independent random walks 153 \item[\np{rn\_eos\_stdxy}:] random walk horz. standard deviation (in grid points) 154 \item[\np{rn\_eos\_stdz}:] random walk vert. standard deviation (in grid points) 155 \item[\np{rn\_eos\_tcor}:] random walk time correlation (in timesteps) 156 \item[\np{nn\_eos\_ord}:] order of autoregressive processes 157 \item[\np{nn\_eos\_flt}:] passes of Laplacian filter 158 \item[\np{rn\_eos\_lim}:] limitation factor (default = 3.0) 159 \end{description} 160 (mean, standard deviation, time correlation, order of the process,\ldots). 160 161 This routine also includes the initialization (seeding) of the random number generator. 161 162 162 The third routine(\rou{sto\_rst\_write}) writes a restart file163 (which suffix name is given by \np{cn \_storst\_out} namelist parameter) containing the current value of164 all autoregressive processes to allow restarting a simulation from where it has been interrupted.165 This file also contains the current state of the random number generator.166 When \np{ln \_rststo} is set to \forcode{.true.}),167 the restart file (which suffix name is given by \np{cn \_storst\_in} namelist parameter) is read by163 (\rou{sto\_rst\_write}) writes a restart file 164 (which suffix name is given by \np{cn_storst_out}{cn\_storst\_out} namelist parameter) containing the current value of 165 all autoregressive processes to allow creating the file needed for a restart. 166 This restart file also contains the current state of the random number generator. 167 When \np{ln_rststo}{ln\_rststo} is set to \forcode{.true.}), 168 the restart file (which suffix name is given by \np{cn_storst_in}{cn\_storst\_in} namelist parameter) is read by 168 169 the initialization routine (\rou{sto\_par\_init}). 169 170 The simulation will continue exactly as if it was not interrupted only 170 when \np{ln\_rstseed} is set to \forcode{.true.}, 171 \ie when the state of the random number generator is read in the restart file. 172 173 \biblio 174 175 \pindex 171 when \np{ln_rstseed}{ln\_rstseed} is set to \forcode{.true.}, 172 \ie\ when the state of the random number generator is read in the restart file.\\ 173 174 The implementation includes the basics for a few possible stochastic parametrisations including equation of state, 175 lateral diffusion, horizontal pressure gradient, ice strength, trend, tracers dynamics. 176 As for this release, only the stochastic parametrisation of equation of state is fully available and tested. \\ 177 178 Options and parameters \\ 179 180 The \np{ln_sto_eos}{ln\_sto\_eos} namelist variable activates stochastic parametrisation of equation of state. 181 By default it set to \forcode{.false.}) and not active. 182 The set of parameters is available in \nam{sto}{sto} namelist 183 (only the subset for equation of state stochastic parametrisation is listed below): 184 185 \begin{listing} 186 \nlst{namsto} 187 \caption{\forcode{&namsto}} 188 \label{lst:namsto} 189 \end{listing} 190 191 The variables of stochastic paramtetrisation itself (based on the global 2° experiments as in \cite{brankart_OM13} are: 192 193 \begin{description} 194 \item [{\np{nn_sto_eos}{nn\_sto\_eos}:}] number of independent random walks 195 \item [{\np{rn_eos_stdxy}{rn\_eos\_stdxy}:}] random walk horizontal standard deviation 196 (in grid points) 197 \item [{\np{rn_eos_stdz}{rn\_eos\_stdz}:}] random walk vertical standard deviation 198 (in grid points) 199 \item [{\np{rn_eos_tcor}{rn\_eos\_tcor}:}] random walk time correlation (in timesteps) 200 \item [{\np{nn_eos_ord}{nn\_eos\_ord}:}] order of autoregressive processes 201 \item [{\np{nn_eos_flt}{nn\_eos\_flt}:}] passes of Laplacian filter 202 \item [{\np{rn_eos_lim}{rn\_eos\_lim}:}] limitation factor (default = 3.0) 203 \end{description} 204 205 The first four parameters define the stochastic part of equation of state. 206 207 \subinc{\input{../../global/epilogue}} 176 208 177 209 \end{document} -
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_TRA.tex
r10544 r11831 2 2 3 3 \begin{document} 4 % ================================================================ 5 % Chapter 1 ——— Ocean Tracers (TRA) 6 % ================================================================ 4 7 5 \chapter{Ocean Tracers (TRA)} 8 6 \label{chap:TRA} 9 7 10 \minitoc 11 12 % missing/update 8 \thispagestyle{plain} 9 10 \chaptertoc 11 12 \paragraph{Changes record} ~\\ 13 14 {\footnotesize 15 \begin{tabularx}{\textwidth}{l||X|X} 16 Release & Author(s) & Modifications \\ 17 \hline 18 {\em 4.0} & {\em Christian \'{E}th\'{e} } & {\em Review } \\ 19 {\em 3.6} & {\em Gurvan Madec } & {\em Update } \\ 20 {\em $\leq$ 3.4} & {\em Gurvan Madec and S\'{e}bastien Masson} & {\em First version} \\ 21 \end{tabularx} 22 } 23 24 \clearpage 25 26 % missing/update 13 27 % traqsr: need to coordinate with SBC module 14 28 15 %STEVEN : is the use of the word "positive" to describe a scheme enough, or should it be "positive definite"? I added a comment to this effect on some instances of this below 29 %STEVEN : is the use of the word "positive" to describe a scheme enough, or should it be "positive definite"? 30 %I added a comment to this effect on some instances of this below 16 31 17 32 Using the representation described in \autoref{chap:DOM}, several semi -discrete space forms of 18 33 the tracer equations are available depending on the vertical coordinate used and on the physics used. 19 34 In all the equations presented here, the masking has been omitted for simplicity. 20 One must be aware that all the quantities are masked fields and that each time a mean or21 difference operator is used, the resulting field is multiplied by a mask.35 One must be aware that all the quantities are masked fields and that 36 each time a mean or difference operator is used, the resulting field is multiplied by a mask. 22 37 23 38 The two active tracers are potential temperature and salinity. … … 30 45 NXT stands for next, referring to the time-stepping. 31 46 From left to right, the terms on the rhs of the tracer equations are the advection (ADV), 32 the lateral diffusion (LDF), the vertical diffusion (ZDF), the contributions from the external forcings 33 (SBC: Surface Boundary Condition, QSR: penetrative Solar Radiation, and BBC: Bottom Boundary Condition), 34 the contribution from the bottom boundary Layer (BBL) parametrisation, and an internal damping (DMP) term. 47 the lateral diffusion (LDF), the vertical diffusion (ZDF), 48 the contributions from the external forcings (SBC: Surface Boundary Condition, 49 QSR: penetrative Solar Radiation, and BBC: Bottom Boundary Condition), 50 the contribution from the bottom boundary Layer (BBL) parametrisation, 51 and an internal damping (DMP) term. 35 52 The terms QSR, BBC, BBL and DMP are optional. 36 53 The external forcings and parameterisations require complex inputs and complex calculations 37 (\eg bulk formulae, estimation of mixing coefficients) that are carried out in the SBC,54 (\eg\ bulk formulae, estimation of mixing coefficients) that are carried out in the SBC, 38 55 LDF and ZDF modules and described in \autoref{chap:SBC}, \autoref{chap:LDF} and 39 56 \autoref{chap:ZDF}, respectively. 40 Note that \mdl{tranpc}, the non-penetrative convection module, although located in41 the \path{./src/OCE/TRA} directory as it directly modifies the tracer fields,57 Note that \mdl{tranpc}, the non-penetrative convection module, 58 although located in the \path{./src/OCE/TRA} directory as it directly modifies the tracer fields, 42 59 is described with the model vertical physics (ZDF) together with 43 60 other available parameterization of convection. 44 61 45 In the present chapter we also describe the diagnostic equations used to compute the sea-water properties46 (density, Brunt-V\"{a}is\"{a}l\"{a} frequency, specific heat and freezing point with 47 associated modules \mdl{eosbn2} and \mdl{phycst}).48 49 The different options available to the user are managed by namelist logicals or CPP keys.62 In the present chapter we also describe the diagnostic equations used to 63 compute the sea-water properties (density, Brunt-V\"{a}is\"{a}l\"{a} frequency, specific heat and 64 freezing point with associated modules \mdl{eosbn2} and \mdl{phycst}). 65 66 The different options available to the user are managed by namelist logicals. 50 67 For each equation term \textit{TTT}, the namelist logicals are \textit{ln\_traTTT\_xxx}, 51 68 where \textit{xxx} is a 3 or 4 letter acronym corresponding to each optional scheme. 52 The CPP key (when it exists) is \key{traTTT}.53 69 The equivalent code can be found in the \textit{traTTT} or \textit{traTTT\_xxx} module, 54 70 in the \path{./src/OCE/TRA} directory. 55 71 56 72 The user has the option of extracting each tendency term on the RHS of the tracer equation for output 57 (\np{ln\_tra\_trd} or \np{ln\_tra\_mxl}~\forcode{= .true.}), as described in \autoref{chap:DIA}. 58 59 % ================================================================ 60 % Tracer Advection 61 % ================================================================ 62 \section{Tracer advection (\protect\mdl{traadv})} 73 (\np{ln_tra_trd}{ln\_tra\_trd} or \np[=.true.]{ln_tra_mxl}{ln\_tra\_mxl}), 74 as described in \autoref{chap:DIA}. 75 76 %% ================================================================================================= 77 \section[Tracer advection (\textit{traadv.F90})]{Tracer advection (\protect\mdl{traadv})} 63 78 \label{sec:TRA_adv} 64 %------------------------------------------namtra_adv----------------------------------------------------- 65 66 \nlst{namtra_adv} 67 %------------------------------------------------------------------------------------------------------------- 68 69 When considered (\ie when \np{ln\_traadv\_NONE} is not set to \forcode{.true.}), 79 80 \begin{listing} 81 \nlst{namtra_adv} 82 \caption{\forcode{&namtra_adv}} 83 \label{lst:namtra_adv} 84 \end{listing} 85 86 When considered (\ie\ when \np{ln_traadv_OFF}{ln\_traadv\_OFF} is not set to \forcode{.true.}), 70 87 the advection tendency of a tracer is expressed in flux form, 71 \ie as the divergence of the advective fluxes.72 Its discrete expression is given by 73 \begin{equation} 74 \label{eq: tra_adv}88 \ie\ as the divergence of the advective fluxes. 89 Its discrete expression is given by: 90 \begin{equation} 91 \label{eq:TRA_adv} 75 92 ADV_\tau = - \frac{1}{b_t} \Big( \delta_i [ e_{2u} \, e_{3u} \; u \; \tau_u] 76 93 + \delta_j [ e_{1v} \, e_{3v} \; v \; \tau_v] \Big) … … 78 95 \end{equation} 79 96 where $\tau$ is either T or S, and $b_t = e_{1t} \, e_{2t} \, e_{3t}$ is the volume of $T$-cells. 80 The flux form in \autoref{eq:tra_adv} implicitly requires the use of the continuity equation. 81 Indeed, it is obtained by using the following equality: $\nabla \cdot (\vect U \, T) = \vect U \cdot \nabla T$ which 82 results from the use of the continuity equation, $\partial_t e_3 + e_3 \; \nabla \cdot \vect U = 0$ 83 (which reduces to $\nabla \cdot \vect U = 0$ in linear free surface, \ie \np{ln\_linssh}~\forcode{= .true.}). 84 Therefore it is of paramount importance to design the discrete analogue of the advection tendency so that 85 it is consistent with the continuity equation in order to enforce the conservation properties of 86 the continuous equations. 87 In other words, by setting $\tau = 1$ in (\autoref{eq:tra_adv}) we recover the discrete form of 88 the continuity equation which is used to calculate the vertical velocity. 89 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 90 \begin{figure}[!t] 91 \begin{center} 92 \includegraphics[]{Fig_adv_scheme} 93 \caption{ 94 \protect\label{fig:adv_scheme} 95 Schematic representation of some ways used to evaluate the tracer value at $u$-point and 96 the amount of tracer exchanged between two neighbouring grid points. 97 Upsteam biased scheme (ups): 98 the upstream value is used and the black area is exchanged. 99 Piecewise parabolic method (ppm): 100 a parabolic interpolation is used and the black and dark grey areas are exchanged. 101 Monotonic upstream scheme for conservative laws (muscl): 102 a parabolic interpolation is used and black, dark grey and grey areas are exchanged. 103 Second order scheme (cen2): 104 the mean value is used and black, dark grey, grey and light grey areas are exchanged. 105 Note that this illustration does not include the flux limiter used in ppm and muscl schemes. 106 } 107 \end{center} 97 The flux form in \autoref{eq:TRA_adv} implicitly requires the use of the continuity equation. 98 Indeed, it is obtained by using the following equality: 99 $\nabla \cdot (\vect U \, T) = \vect U \cdot \nabla T$ which 100 results from the use of the continuity equation, 101 $\partial_t e_3 + e_3 \; \nabla \cdot \vect U = 0$ 102 (which reduces to $\nabla \cdot \vect U = 0$ in linear free surface, 103 \ie\ \np[=.true.]{ln_linssh}{ln\_linssh}). 104 Therefore it is of paramount importance to 105 design the discrete analogue of the advection tendency so that 106 it is consistent with the continuity equation in order to 107 enforce the conservation properties of the continuous equations. 108 In other words, by setting $\tau = 1$ in (\autoref{eq:TRA_adv}) we recover 109 the discrete form of the continuity equation which is used to calculate the vertical velocity. 110 \begin{figure} 111 \centering 112 \includegraphics[width=0.66\textwidth]{TRA_adv_scheme} 113 \caption[Ways to evaluate the tracer value and the amount of tracer exchanged]{ 114 Schematic representation of some ways used to evaluate the tracer value at $u$-point and 115 the amount of tracer exchanged between two neighbouring grid points. 116 Upsteam biased scheme (ups): 117 the upstream value is used and the black area is exchanged. 118 Piecewise parabolic method (ppm): 119 a parabolic interpolation is used and the black and dark grey areas are exchanged. 120 Monotonic upstream scheme for conservative laws (muscl): 121 a parabolic interpolation is used and black, dark grey and grey areas are exchanged. 122 Second order scheme (cen2): 123 the mean value is used and black, dark grey, grey and light grey areas are exchanged. 124 Note that this illustration does not include the flux limiter used in ppm and muscl schemes.} 125 \label{fig:TRA_adv_scheme} 108 126 \end{figure} 109 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 110 111 The key difference between the advection schemes available in \NEMO is the choice made in space and 112 time interpolation to define the value of the tracer at the velocity points 113 (\autoref{fig:adv_scheme}). 127 128 The key difference between the advection schemes available in \NEMO\ is the choice made in 129 space and time interpolation to define the value of the tracer at the velocity points 130 (\autoref{fig:TRA_adv_scheme}). 114 131 115 132 Along solid lateral and bottom boundaries a zero tracer flux is automatically specified, … … 118 135 119 136 \begin{description} 120 \item[linear free surface:] 121 (\np{ln\_linssh}~\forcode{= .true.}) 137 \item [linear free surface] (\np[=.true.]{ln_linssh}{ln\_linssh}) 122 138 the first level thickness is constant in time: 123 the vertical boundary condition is applied at the fixed surface $z = 0$ rather than on 124 the moving surface $z = \eta$. 125 There is a non-zero advective flux which is set for all advection schemes as 126 $\tau_w|_{k = 1/2} = T_{k = 1}$, \ie the product of surface velocity (at $z = 0$) by 127 the first level tracer value. 128 \item[non-linear free surface:] 129 (\np{ln\_linssh}~\forcode{= .false.}) 139 the vertical boundary condition is applied at the fixed surface $z = 0$ rather than 140 on the moving surface $z = \eta$. 141 There is a non-zero advective flux which is set for 142 all advection schemes as $\tau_w|_{k = 1/2} = T_{k = 1}$, 143 \ie\ the product of surface velocity (at $z = 0$) by the first level tracer value. 144 \item [non-linear free surface] (\np[=.false.]{ln_linssh}{ln\_linssh}) 130 145 convergence/divergence in the first ocean level moves the free surface up/down. 131 There is no tracer advection through it so that the advective fluxes through the surface are also zero. 146 There is no tracer advection through it so that 147 the advective fluxes through the surface are also zero. 132 148 \end{description} 133 149 134 150 In all cases, this boundary condition retains local conservation of tracer. 135 Global conservation is obtained in non-linear free surface case, but \textit{not} in the linear free surface case. 136 Nevertheless, in the latter case, it is achieved to a good approximation since 137 the non-conservative term is the product of the time derivative of the tracer and the free surface height, 138 two quantities that are not correlated \citep{Roullet_Madec_JGR00, Griffies_al_MWR01, Campin2004}. 139 140 The velocity field that appears in (\autoref{eq:tra_adv} and \autoref{eq:tra_adv_zco}) is 141 the centred (\textit{now}) \textit{effective} ocean velocity, \ie the \textit{eulerian} velocity 151 Global conservation is obtained in non-linear free surface case, 152 but \textit{not} in the linear free surface case. 153 Nevertheless, in the latter case, 154 it is achieved to a good approximation since the non-conservative term is 155 the product of the time derivative of the tracer and the free surface height, 156 two quantities that are not correlated 157 \citep{roullet.madec_JGR00, griffies.pacanowski.ea_MWR01, campin.adcroft.ea_OM04}. 158 159 The velocity field that appears in (\autoref{eq:TRA_adv} is 160 the centred (\textit{now}) \textit{effective} ocean velocity, \ie\ the \textit{eulerian} velocity 142 161 (see \autoref{chap:DYN}) plus the eddy induced velocity (\textit{eiv}) and/or 143 162 the mixed layer eddy induced velocity (\textit{eiv}) when those parameterisations are used 144 163 (see \autoref{chap:LDF}). 145 164 146 Several tracer advection scheme are proposed, namely a $2^{nd}$ or $4^{th}$ order centred schemes (CEN), 147 a $2^{nd}$ or $4^{th}$ order Flux Corrected Transport scheme (FCT), a Monotone Upstream Scheme for 148 Conservative Laws scheme (MUSCL), a $3^{rd}$ Upstream Biased Scheme (UBS, also often called UP3), 149 and a Quadratic Upstream Interpolation for Convective Kinematics with Estimated Streaming Terms scheme (QUICKEST). 150 The choice is made in the \ngn{namtra\_adv} namelist, by setting to \forcode{.true.} one of 151 the logicals \textit{ln\_traadv\_xxx}. 152 The corresponding code can be found in the \textit{traadv\_xxx.F90} module, where 153 \textit{xxx} is a 3 or 4 letter acronym corresponding to each scheme. 154 By default (\ie in the reference namelist, \textit{namelist\_ref}), all the logicals are set to \forcode{.false.}. 155 If the user does not select an advection scheme in the configuration namelist (\textit{namelist\_cfg}), 156 the tracers will \textit{not} be advected! 165 Several tracer advection scheme are proposed, 166 namely a $2^{nd}$ or $4^{th}$ order \textbf{CEN}tred schemes (CEN), 167 a $2^{nd}$ or $4^{th}$ order \textbf{F}lux \textbf{C}orrected \textbf{T}ransport scheme (FCT), 168 a \textbf{M}onotone \textbf{U}pstream \textbf{S}cheme for 169 \textbf{C}onservative \textbf{L}aws scheme (MUSCL), 170 a $3^{rd}$ \textbf{U}pstream \textbf{B}iased \textbf{S}cheme (UBS, also often called UP3), 171 and a \textbf{Q}uadratic \textbf{U}pstream \textbf{I}nterpolation for 172 \textbf{C}onvective \textbf{K}inematics with 173 \textbf{E}stimated \textbf{S}treaming \textbf{T}erms scheme (QUICKEST). 174 The choice is made in the \nam{tra_adv}{tra\_adv} namelist, 175 by setting to \forcode{.true.} one of the logicals \textit{ln\_traadv\_xxx}. 176 The corresponding code can be found in the \textit{traadv\_xxx.F90} module, 177 where \textit{xxx} is a 3 or 4 letter acronym corresponding to each scheme. 178 By default (\ie\ in the reference namelist, \textit{namelist\_ref}), 179 all the logicals are set to \forcode{.false.}. 180 If the user does not select an advection scheme in the configuration namelist 181 (\textit{namelist\_cfg}), the tracers will \textit{not} be advected! 157 182 158 183 Details of the advection schemes are given below. 159 The choosing an advection scheme is a complex matter which depends on the model physics, model resolution, 160 type of tracer, as well as the issue of numerical cost. In particular, we note that 184 The choosing an advection scheme is a complex matter which depends on the 185 model physics, model resolution, type of tracer, as well as the issue of numerical cost. 186 In particular, we note that 161 187 162 188 \begin{enumerate} 163 \item 164 CEN and FCT schemes require an explicit diffusion operator while the other schemes are diffusive enough so that 165 they do not necessarily need additional diffusion; 166 \item 167 CEN and UBS are not \textit{positive} schemes 168 \footnote{negative values can appear in an initially strictly positive tracer field which is advected}, 189 \item CEN and FCT schemes require an explicit diffusion operator while 190 the other schemes are diffusive enough so that they do not necessarily need additional diffusion; 191 \item CEN and UBS are not \textit{positive} schemes \footnote{negative values can appear in 192 an initially strictly positive tracer field which is advected}, 169 193 implying that false extrema are permitted. 170 194 Their use is not recommended on passive tracers; 171 \item 172 It is recommended that the same advection-diffusion scheme is used onboth active and passive tracers.195 \item It is recommended that the same advection-diffusion scheme is used on 196 both active and passive tracers. 173 197 \end{enumerate} 174 198 175 Indeed, if a source or sink of a passive tracer depends on an active one, the difference of treatment of active and 176 passive tracers can create very nice-looking frontal structures that are pure numerical artefacts. 199 Indeed, if a source or sink of a passive tracer depends on an active one, 200 the difference of treatment of active and passive tracers can create 201 very nice-looking frontal structures that are pure numerical artefacts. 177 202 Nevertheless, most of our users set a different treatment on passive and active tracers, 178 203 that's the reason why this possibility is offered. 179 We strongly suggest them to perform a sensitivity experiment using a same treatment to assess the robustness of 180 their results. 181 182 % ------------------------------------------------------------------------------------------------------------- 183 % 2nd and 4th order centred schemes 184 % ------------------------------------------------------------------------------------------------------------- 185 \subsection{CEN: Centred scheme (\protect\np{ln\_traadv\_cen}~\forcode{= .true.})} 204 We strongly suggest them to perform a sensitivity experiment using a same treatment to 205 assess the robustness of their results. 206 207 %% ================================================================================================= 208 \subsection[CEN: Centred scheme (\forcode{ln_traadv_cen})]{CEN: Centred scheme (\protect\np{ln_traadv_cen}{ln\_traadv\_cen})} 186 209 \label{subsec:TRA_adv_cen} 187 210 188 % 2nd order centred scheme 189 190 The centred advection scheme (CEN) is used when \np{ln\_traadv\_cen}~\forcode{= .true.}. 191 Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on horizontal (iso-level) and vertical direction by 192 setting \np{nn\_cen\_h} and \np{nn\_cen\_v} to $2$ or $4$. 211 % 2nd order centred scheme 212 213 The \textbf{CEN}tred advection scheme (CEN) is used when \np[=.true.]{ln_traadv_cen}{ln\_traadv\_cen}. 214 Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on 215 horizontal (iso-level) and vertical direction by 216 setting \np{nn_cen_h}{nn\_cen\_h} and \np{nn_cen_v}{nn\_cen\_v} to $2$ or $4$. 193 217 CEN implementation can be found in the \mdl{traadv\_cen} module. 194 218 195 In the $2^{nd}$ order centred formulation (CEN2), the tracer at velocity points is evaluated as the mean of196 the two neighbouring $T$-point values.219 In the $2^{nd}$ order centred formulation (CEN2), the tracer at velocity points is evaluated as 220 the mean of the two neighbouring $T$-point values. 197 221 For example, in the $i$-direction : 198 222 \begin{equation} 199 \label{eq: tra_adv_cen2}223 \label{eq:TRA_adv_cen2} 200 224 \tau_u^{cen2} = \overline T ^{i + 1/2} 201 225 \end{equation} 202 226 203 CEN2 is non diffusive (\ie it conserves the tracer variance, $\tau^2$) but dispersive 204 (\ie it may create false extrema). 205 It is therefore notoriously noisy and must be used in conjunction with an explicit diffusion operator to 206 produce a sensible solution. 207 The associated time-stepping is performed using a leapfrog scheme in conjunction with an Asselin time-filter, 208 so $T$ in (\autoref{eq:tra_adv_cen2}) is the \textit{now} tracer value. 227 CEN2 is non diffusive (\ie\ it conserves the tracer variance, $\tau^2$) but 228 dispersive (\ie\ it may create false extrema). 229 It is therefore notoriously noisy and must be used in conjunction with 230 an explicit diffusion operator to produce a sensible solution. 231 The associated time-stepping is performed using 232 a leapfrog scheme in conjunction with an Asselin time-filter, 233 so $T$ in (\autoref{eq:TRA_adv_cen2}) is the \textit{now} tracer value. 209 234 210 235 Note that using the CEN2, the overall tracer advection is of second order accuracy since 211 both (\autoref{eq:tra_adv}) and (\autoref{eq:tra_adv_cen2}) have this order of accuracy. 212 213 % 4nd order centred scheme 214 215 In the $4^{th}$ order formulation (CEN4), tracer values are evaluated at u- and v-points as 216 a $4^{th}$ order interpolation, and thus depend on the four neighbouring $T$-points. 236 both (\autoref{eq:TRA_adv}) and (\autoref{eq:TRA_adv_cen2}) have this order of accuracy. 237 238 % 4nd order centred scheme 239 240 In the $4^{th}$ order formulation (CEN4), 241 tracer values are evaluated at u- and v-points as a $4^{th}$ order interpolation, 242 and thus depend on the four neighbouring $T$-points. 217 243 For example, in the $i$-direction: 218 244 \begin{equation} 219 \label{eq: tra_adv_cen4}245 \label{eq:TRA_adv_cen4} 220 246 \tau_u^{cen4} = \overline{T - \frac{1}{6} \, \delta_i \Big[ \delta_{i + 1/2}[T] \, \Big]}^{\,i + 1/2} 221 247 \end{equation} 222 In the vertical direction (\np{nn\_cen\_v}~\forcode{= 4}), 223 a $4^{th}$ COMPACT interpolation has been prefered \citep{Demange_PhD2014}. 224 In the COMPACT scheme, both the field and its derivative are interpolated, which leads, after a matrix inversion, 225 spectral characteristics similar to schemes of higher order \citep{Lele_JCP1992}. 248 In the vertical direction (\np[=4]{nn_cen_v}{nn\_cen\_v}), 249 a $4^{th}$ COMPACT interpolation has been prefered \citep{demange_phd14}. 250 In the COMPACT scheme, both the field and its derivative are interpolated, 251 which leads, after a matrix inversion, spectral characteristics similar to schemes of higher order 252 \citep{lele_JCP92}. 226 253 227 254 Strictly speaking, the CEN4 scheme is not a $4^{th}$ order advection scheme but 228 255 a $4^{th}$ order evaluation of advective fluxes, 229 since the divergence of advective fluxes \autoref{eq: tra_adv} is kept at $2^{nd}$ order.230 The expression \textit{$4^{th}$ order scheme} used in oceanographic literature is usually associated with231 the scheme presented here.232 Introducing a \forcode{.true.}$4^{th}$ order advection scheme is feasible but, for consistency reasons,233 it requires changes in the discretisation of the tracer advection together with changes in the continuity equation,234 and the momentum advection and pressure terms.256 since the divergence of advective fluxes \autoref{eq:TRA_adv} is kept at $2^{nd}$ order. 257 The expression \textit{$4^{th}$ order scheme} used in oceanographic literature is 258 usually associated with the scheme presented here. 259 Introducing a ``true'' $4^{th}$ order advection scheme is feasible but, for consistency reasons, 260 it requires changes in the discretisation of the tracer advection together with 261 changes in the continuity equation, and the momentum advection and pressure terms. 235 262 236 263 A direct consequence of the pseudo-fourth order nature of the scheme is that it is not non-diffusive, 237 \ie the global variance of a tracer is not preserved using CEN4. 238 Furthermore, it must be used in conjunction with an explicit diffusion operator to produce a sensible solution. 239 As in CEN2 case, the time-stepping is performed using a leapfrog scheme in conjunction with an Asselin time-filter, 240 so $T$ in (\autoref{eq:tra_adv_cen4}) is the \textit{now} tracer. 264 \ie\ the global variance of a tracer is not preserved using CEN4. 265 Furthermore, it must be used in conjunction with an explicit diffusion operator to 266 produce a sensible solution. 267 As in CEN2 case, the time-stepping is performed using a leapfrog scheme in conjunction with 268 an Asselin time-filter, so $T$ in (\autoref{eq:TRA_adv_cen4}) is the \textit{now} tracer. 241 269 242 270 At a $T$-grid cell adjacent to a boundary (coastline, bottom and surface), … … 244 272 This hypothesis usually reduces the order of the scheme. 245 273 Here we choose to set the gradient of $T$ across the boundary to zero. 246 Alternative conditions can be specified, such as a reduction to a second order scheme for 247 these near boundary grid points. 248 249 % ------------------------------------------------------------------------------------------------------------- 250 % FCT scheme 251 % ------------------------------------------------------------------------------------------------------------- 252 \subsection{FCT: Flux Corrected Transport scheme (\protect\np{ln\_traadv\_fct}~\forcode{= .true.})} 274 Alternative conditions can be specified, 275 such as a reduction to a second order scheme for these near boundary grid points. 276 277 %% ================================================================================================= 278 \subsection[FCT: Flux Corrected Transport scheme (\forcode{ln_traadv_fct})]{FCT: Flux Corrected Transport scheme (\protect\np{ln_traadv_fct}{ln\_traadv\_fct})} 253 279 \label{subsec:TRA_adv_tvd} 254 280 255 The Flux Corrected Transport schemes (FCT) is used when \np{ln\_traadv\_fct}~\forcode{= .true.}. 256 Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on horizontal (iso-level) and vertical direction by 257 setting \np{nn\_fct\_h} and \np{nn\_fct\_v} to $2$ or $4$. 281 The \textbf{F}lux \textbf{C}orrected \textbf{T}ransport schemes (FCT) is used when 282 \np[=.true.]{ln_traadv_fct}{ln\_traadv\_fct}. 283 Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on 284 horizontal (iso-level) and vertical direction by 285 setting \np{nn_fct_h}{nn\_fct\_h} and \np{nn_fct_v}{nn\_fct\_v} to $2$ or $4$. 258 286 FCT implementation can be found in the \mdl{traadv\_fct} module. 259 287 260 In FCT formulation, the tracer at velocity points is evaluated using a combination of an upstream and261 a c entred scheme.288 In FCT formulation, the tracer at velocity points is evaluated using 289 a combination of an upstream and a centred scheme. 262 290 For example, in the $i$-direction : 263 291 \begin{equation} 264 \label{eq: tra_adv_fct}292 \label{eq:TRA_adv_fct} 265 293 \begin{split} 266 294 \tau_u^{ups} &= … … 268 296 T_{i + 1} & \text{if~} u_{i + 1/2} < 0 \\ 269 297 T_i & \text{if~} u_{i + 1/2} \geq 0 \\ 270 \end{cases} 271 \\ 298 \end{cases} \\ 272 299 \tau_u^{fct} &= \tau_u^{ups} + c_u \, \big( \tau_u^{cen} - \tau_u^{ups} \big) 273 300 \end{split} … … 275 302 where $c_u$ is a flux limiter function taking values between 0 and 1. 276 303 The FCT order is the one of the centred scheme used 277 (\ie it depends on the setting of \np{nn\_fct\_h} and \np{nn\_fct\_v}).304 (\ie\ it depends on the setting of \np{nn_fct_h}{nn\_fct\_h} and \np{nn_fct_v}{nn\_fct\_v}). 278 305 There exist many ways to define $c_u$, each corresponding to a different FCT scheme. 279 The one chosen in \NEMO is described in \citet{Zalesak_JCP79}.306 The one chosen in \NEMO\ is described in \citet{zalesak_JCP79}. 280 307 $c_u$ only departs from $1$ when the advective term produces a local extremum in the tracer field. 281 308 The resulting scheme is quite expensive but \textit{positive}. 282 309 It can be used on both active and passive tracers. 283 A comparison of FCT-2 with MUSCL and a MPDATA scheme can be found in \citet{Levy_al_GRL01}. 284 285 An additional option has been added controlled by \np{nn\_fct\_zts}. 286 By setting this integer to a value larger than zero, 287 a $2^{nd}$ order FCT scheme is used on both horizontal and vertical direction, but on the latter, 288 a split-explicit time stepping is used, with a number of sub-timestep equals to \np{nn\_fct\_zts}. 289 This option can be useful when the size of the timestep is limited by vertical advection \citep{Lemarie_OM2015}. 290 Note that in this case, a similar split-explicit time stepping should be used on vertical advection of momentum to 291 insure a better stability (see \autoref{subsec:DYN_zad}). 292 293 For stability reasons (see \autoref{chap:STP}), 294 $\tau_u^{cen}$ is evaluated in (\autoref{eq:tra_adv_fct}) using the \textit{now} tracer while 310 A comparison of FCT-2 with MUSCL and a MPDATA scheme can be found in \citet{levy.estublier.ea_GRL01}. 311 312 For stability reasons (see \autoref{chap:TD}), 313 $\tau_u^{cen}$ is evaluated in (\autoref{eq:TRA_adv_fct}) using the \textit{now} tracer while 295 314 $\tau_u^{ups}$ is evaluated using the \textit{before} tracer. 296 In other words, the advective part of the scheme is time stepped with a leap-frog scheme 297 while a forward scheme is used for the diffusive part. 298 299 % ------------------------------------------------------------------------------------------------------------- 300 % MUSCL scheme 301 % ------------------------------------------------------------------------------------------------------------- 302 \subsection{MUSCL: Monotone Upstream Scheme for Conservative Laws (\protect\np{ln\_traadv\_mus}~\forcode{= .true.})} 315 In other words, the advective part of the scheme is time stepped with a leap-frog scheme while 316 a forward scheme is used for the diffusive part. 317 318 %% ================================================================================================= 319 \subsection[MUSCL: Monotone Upstream Scheme for Conservative Laws (\forcode{ln_traadv_mus})]{MUSCL: Monotone Upstream Scheme for Conservative Laws (\protect\np{ln_traadv_mus}{ln\_traadv\_mus})} 303 320 \label{subsec:TRA_adv_mus} 304 321 305 The Monotone Upstream Scheme for Conservative Laws (MUSCL) is used when \np{ln\_traadv\_mus}~\forcode{= .true.}. 322 The \textbf{M}onotone \textbf{U}pstream \textbf{S}cheme for \textbf{C}onservative \textbf{L}aws 323 (MUSCL) is used when \np[=.true.]{ln_traadv_mus}{ln\_traadv\_mus}. 306 324 MUSCL implementation can be found in the \mdl{traadv\_mus} module. 307 325 308 MUSCL has been first implemented in \NEMO by \citet{Levy_al_GRL01}.309 In its formulation, the tracer at velocity points is evaluated assuming a linear tracer variation between310 two $T$-points (\autoref{fig:adv_scheme}).326 MUSCL has been first implemented in \NEMO\ by \citet{levy.estublier.ea_GRL01}. 327 In its formulation, the tracer at velocity points is evaluated assuming 328 a linear tracer variation between two $T$-points (\autoref{fig:TRA_adv_scheme}). 311 329 For example, in the $i$-direction : 312 \ begin{equation}313 % \label{eq: tra_adv_mus}330 \[ 331 % \label{eq:TRA_adv_mus} 314 332 \tau_u^{mus} = \lt\{ 315 333 \begin{split} 316 \tau_i&+ \frac{1}{2} \lt( 1 - \frac{u_{i + 1/2} \, \rdt}{e_{1u}} \rt)317 \widetilde{\partial_i\tau} & \text{if~} u_{i + 1/2} \geqslant 0 \\318 319 334 \tau_i &+ \frac{1}{2} \lt( 1 - \frac{u_{i + 1/2} \, \rdt}{e_{1u}} \rt) 335 \widetilde{\partial_i \tau} & \text{if~} u_{i + 1/2} \geqslant 0 \\ 336 \tau_{i + 1/2} &+ \frac{1}{2} \lt( 1 + \frac{u_{i + 1/2} \, \rdt}{e_{1u}} \rt) 337 \widetilde{\partial_{i + 1/2} \tau} & \text{if~} u_{i + 1/2} < 0 320 338 \end{split} 321 339 \rt. 322 \ end{equation}323 where $\widetilde{\partial_i \tau}$ is the slope of the tracer on which a limitation is imposed to324 ensure the \textit{positive} character of the scheme.325 326 The time stepping is performed using a forward scheme, that is the \textit{before} tracer field is used to327 evaluate $\tau_u^{mus}$.340 \] 341 where $\widetilde{\partial_i \tau}$ is the slope of the tracer on which 342 a limitation is imposed to ensure the \textit{positive} character of the scheme. 343 344 The time stepping is performed using a forward scheme, 345 that is the \textit{before} tracer field is used to evaluate $\tau_u^{mus}$. 328 346 329 347 For an ocean grid point adjacent to land and where the ocean velocity is directed toward land, 330 348 an upstream flux is used. 331 349 This choice ensure the \textit{positive} character of the scheme. 332 In addition, fluxes round a grid-point where a runoff is applied can optionally be computed using upstream fluxes 333 (\np{ln\_mus\_ups}~\forcode{= .true.}). 334 335 % ------------------------------------------------------------------------------------------------------------- 336 % UBS scheme 337 % ------------------------------------------------------------------------------------------------------------- 338 \subsection{UBS a.k.a. UP3: Upstream-Biased Scheme (\protect\np{ln\_traadv\_ubs}~\forcode{= .true.})} 350 In addition, fluxes round a grid-point where a runoff is applied can optionally be computed using 351 upstream fluxes (\np[=.true.]{ln_mus_ups}{ln\_mus\_ups}). 352 353 %% ================================================================================================= 354 \subsection[UBS a.k.a. UP3: Upstream-Biased Scheme (\forcode{ln_traadv_ubs})]{UBS a.k.a. UP3: Upstream-Biased Scheme (\protect\np{ln_traadv_ubs}{ln\_traadv\_ubs})} 339 355 \label{subsec:TRA_adv_ubs} 340 356 341 The Upstream-Biased Scheme (UBS) is used when \np{ln\_traadv\_ubs}~\forcode{= .true.}. 357 The \textbf{U}pstream-\textbf{B}iased \textbf{S}cheme (UBS) is used when 358 \np[=.true.]{ln_traadv_ubs}{ln\_traadv\_ubs}. 342 359 UBS implementation can be found in the \mdl{traadv\_mus} module. 343 360 344 361 The UBS scheme, often called UP3, is also known as the Cell Averaged QUICK scheme 345 (Quadratic Upstream Interpolation for Convective Kinematics). 362 (\textbf{Q}uadratic \textbf{U}pstream \textbf{I}nterpolation for 363 \textbf{C}onvective \textbf{K}inematics). 346 364 It is an upstream-biased third order scheme based on an upstream-biased parabolic interpolation. 347 365 For example, in the $i$-direction: 348 366 \begin{equation} 349 \label{eq: tra_adv_ubs}367 \label{eq:TRA_adv_ubs} 350 368 \tau_u^{ubs} = \overline T ^{i + 1/2} - \frac{1}{6} 351 369 \begin{cases} 352 353 370 \tau"_i & \text{if~} u_{i + 1/2} \geqslant 0 \\ 371 \tau"_{i + 1} & \text{if~} u_{i + 1/2} < 0 354 372 \end{cases} 355 \quad 356 \text{where~} \tau"_i = \delta_i \lt[ \delta_{i + 1/2} [\tau] \rt] 373 \quad \text{where~} \tau"_i = \delta_i \lt[ \delta_{i + 1/2} [\tau] \rt] 357 374 \end{equation} 358 375 359 376 This results in a dissipatively dominant (i.e. hyper-diffusive) truncation error 360 \citep{Shchepetkin_McWilliams_OM05}. 361 The overall performance of the advection scheme is similar to that reported in \cite{Farrow1995}. 377 \citep{shchepetkin.mcwilliams_OM05}. 378 The overall performance of the advection scheme is similar to that reported in 379 \cite{farrow.stevens_JPO95}. 362 380 It is a relatively good compromise between accuracy and smoothness. 363 381 Nevertheless the scheme is not \textit{positive}, meaning that false extrema are permitted, 364 382 but the amplitude of such are significantly reduced over the centred second or fourth order method. 365 Therefore it is not recommended that it should be applied to a passive tracer that requires positivity. 383 Therefore it is not recommended that it should be applied to 384 a passive tracer that requires positivity. 366 385 367 386 The intrinsic diffusion of UBS makes its use risky in the vertical direction where 368 387 the control of artificial diapycnal fluxes is of paramount importance 369 \citep{ Shchepetkin_McWilliams_OM05, Demange_PhD2014}.370 Therefore the vertical flux is evaluated using either a $2^nd$ order FCT scheme or a $4^th$ order COMPACT scheme371 (\np{nn\_cen\_v}~\forcode{= 2 or 4}).372 373 For stability reasons (see \autoref{chap: STP}), the first term in \autoref{eq:tra_adv_ubs}374 (which corresponds to a second order centred scheme)375 is evaluated using the \textit{now} tracer (centred in time) while the second term376 (which is the diffusive part of the scheme),388 \citep{shchepetkin.mcwilliams_OM05, demange_phd14}. 389 Therefore the vertical flux is evaluated using either a $2^nd$ order FCT scheme or 390 a $4^th$ order COMPACT scheme (\np[=2 or 4]{nn_ubs_v}{nn\_ubs\_v}). 391 392 For stability reasons (see \autoref{chap:TD}), 393 the first term in \autoref{eq:TRA_adv_ubs} (which corresponds to a second order centred scheme) 394 is evaluated using the \textit{now} tracer (centred in time) while 395 the second term (which is the diffusive part of the scheme), 377 396 is evaluated using the \textit{before} tracer (forward in time). 378 This choice is discussed by \citet{Webb_al_JAOT98} in the context of the QUICK advection scheme. 397 This choice is discussed by \citet{webb.de-cuevas.ea_JAOT98} in 398 the context of the QUICK advection scheme. 379 399 UBS and QUICK schemes only differ by one coefficient. 380 Replacing 1/6 with 1/8 in \autoref{eq:tra_adv_ubs} leads to the QUICK advection scheme \citep{Webb_al_JAOT98}. 400 Replacing 1/6 with 1/8 in \autoref{eq:TRA_adv_ubs} leads to the QUICK advection scheme 401 \citep{webb.de-cuevas.ea_JAOT98}. 381 402 This option is not available through a namelist parameter, since the 1/6 coefficient is hard coded. 382 Nevertheless it is quite easy to make the substitution in the \mdl{traadv\_ubs} module and obtain a QUICK scheme. 383 384 Note that it is straightforward to rewrite \autoref{eq:tra_adv_ubs} as follows: 403 Nevertheless it is quite easy to make the substitution in the \mdl{traadv\_ubs} module and 404 obtain a QUICK scheme. 405 406 Note that it is straightforward to rewrite \autoref{eq:TRA_adv_ubs} as follows: 385 407 \begin{gather} 386 \label{eq: traadv_ubs2}408 \label{eq:TRA_adv_ubs2} 387 409 \tau_u^{ubs} = \tau_u^{cen4} + \frac{1}{12} 388 410 \begin{cases} … … 391 413 \end{cases} 392 414 \intertext{or equivalently} 393 % \label{eq: traadv_ubs2b}415 % \label{eq:TRA_adv_ubs2b} 394 416 u_{i + 1/2} \ \tau_u^{ubs} = u_{i + 1/2} \, \overline{T - \frac{1}{6} \, \delta_i \Big[ \delta_{i + 1/2}[T] \Big]}^{\,i + 1/2} 395 417 - \frac{1}{2} |u|_{i + 1/2} \, \frac{1}{6} \, \delta_{i + 1/2} [\tau"_i] \nonumber 396 418 \end{gather} 397 419 398 \autoref{eq: traadv_ubs2} has several advantages.420 \autoref{eq:TRA_adv_ubs2} has several advantages. 399 421 Firstly, it clearly reveals that the UBS scheme is based on the fourth order scheme to which 400 422 an upstream-biased diffusion term is added. 401 Secondly, this emphasises that the $4^{th}$ order part (as well as the $2^{nd}$ order part as stated above) has to402 be evaluated at the \textit{now} time step using \autoref{eq:tra_adv_ubs}.403 Thirdly, the diffusion term is in fact a biharmonic operator with an eddy coefficient which404 is simply proportional to the velocity: $A_u^{lm} = \frac{1}{12} \, {e_{1u}}^3 \, |u|$. 405 Note the current version of NEMO uses the computationally more efficient formulation \autoref{eq:tra_adv_ubs}.406 407 % ------------------------------------------------------------------------------------------------------------- 408 % QCK scheme 409 % -------------------------------------------------------------------------------------------------------------410 \subsection {QCK: QuiCKest scheme (\protect\np{ln\_traadv\_qck}~\forcode{= .true.})}423 Secondly, 424 this emphasises that the $4^{th}$ order part (as well as the $2^{nd}$ order part as stated above) has to be evaluated at the \textit{now} time step using \autoref{eq:TRA_adv_ubs}. 425 Thirdly, the diffusion term is in fact a biharmonic operator with 426 an eddy coefficient which is simply proportional to the velocity: 427 $A_u^{lm} = \frac{1}{12} \, {e_{1u}}^3 \, |u|$. 428 Note the current version of \NEMO\ uses the computationally more efficient formulation 429 \autoref{eq:TRA_adv_ubs}. 430 431 %% ================================================================================================= 432 \subsection[QCK: QuiCKest scheme (\forcode{ln_traadv_qck})]{QCK: QuiCKest scheme (\protect\np{ln_traadv_qck}{ln\_traadv\_qck})} 411 433 \label{subsec:TRA_adv_qck} 412 434 413 The Quadratic Upstream Interpolation for Convective Kinematics with Estimated Streaming Terms (QUICKEST) scheme 414 proposed by \citet{Leonard1979} is used when \np{ln\_traadv\_qck}~\forcode{= .true.}. 435 The \textbf{Q}uadratic \textbf{U}pstream \textbf{I}nterpolation for 436 \textbf{C}onvective \textbf{K}inematics with \textbf{E}stimated \textbf{S}treaming \textbf{T}erms 437 (QUICKEST) scheme proposed by \citet{leonard_CMAME79} is used when 438 \np[=.true.]{ln_traadv_qck}{ln\_traadv\_qck}. 415 439 QUICKEST implementation can be found in the \mdl{traadv\_qck} module. 416 440 417 441 QUICKEST is the third order Godunov scheme which is associated with the ULTIMATE QUICKEST limiter 418 \citep{Leonard1991}. 419 It has been implemented in NEMO by G. Reffray (MERCATOR-ocean) and can be found in the \mdl{traadv\_qck} module. 442 \citep{leonard_CMAME91}. 443 It has been implemented in \NEMO\ by G. Reffray (Mercator Ocean) and 444 can be found in the \mdl{traadv\_qck} module. 420 445 The resulting scheme is quite expensive but \textit{positive}. 421 446 It can be used on both active and passive tracers. … … 424 449 Therefore the vertical flux is evaluated using the CEN2 scheme. 425 450 This no longer guarantees the positivity of the scheme. 426 The use of FCT in the vertical direction (as for the UBS case) should be implemented to restore this property. 427 428 %%%gmcomment : Cross term are missing in the current implementation.... 429 430 % ================================================================ 431 % Tracer Lateral Diffusion 432 % ================================================================ 433 \section{Tracer lateral diffusion (\protect\mdl{traldf})} 451 The use of FCT in the vertical direction (as for the UBS case) should be implemented to 452 restore this property. 453 454 \cmtgm{Cross term are missing in the current implementation....} 455 456 %% ================================================================================================= 457 \section[Tracer lateral diffusion (\textit{traldf.F90})]{Tracer lateral diffusion (\protect\mdl{traldf})} 434 458 \label{sec:TRA_ldf} 435 %-----------------------------------------nam_traldf------------------------------------------------------ 436 437 \nlst{namtra_ldf} 438 %------------------------------------------------------------------------------------------------------------- 439 440 Options are defined through the \ngn{namtra\_ldf} namelist variables. 441 They are regrouped in four items, allowing to specify 442 $(i)$ the type of operator used (none, laplacian, bilaplacian), 443 $(ii)$ the direction along which the operator acts (iso-level, horizontal, iso-neutral), 444 $(iii)$ some specific options related to the rotated operators (\ie non-iso-level operator), and 445 $(iv)$ the specification of eddy diffusivity coefficient (either constant or variable in space and time). 446 Item $(iv)$ will be described in \autoref{chap:LDF}. 459 460 \begin{listing} 461 \nlst{namtra_ldf} 462 \caption{\forcode{&namtra_ldf}} 463 \label{lst:namtra_ldf} 464 \end{listing} 465 466 Options are defined through the \nam{tra_ldf}{tra\_ldf} namelist variables. 467 They are regrouped in four items, allowing to specify 468 \begin{enumerate*}[label=(\textit{\roman*})] 469 \item the type of operator used (none, laplacian, bilaplacian), 470 \item the direction along which the operator acts (iso-level, horizontal, iso-neutral), 471 \item some specific options related to the rotated operators (\ie\ non-iso-level operator), and 472 \item the specification of eddy diffusivity coefficient 473 (either constant or variable in space and time). 474 \end{enumerate*} 475 Item (iv) will be described in \autoref{chap:LDF}. 447 476 The direction along which the operators act is defined through the slope between 448 477 this direction and the iso-level surfaces. … … 450 479 451 480 The lateral diffusion of tracers is evaluated using a forward scheme, 452 \ie the tracers appearing in its expression are the \textit{before} tracers in time,481 \ie\ the tracers appearing in its expression are the \textit{before} tracers in time, 453 482 except for the pure vertical component that appears when a rotation tensor is used. 454 This latter component is solved implicitly together with the vertical diffusion term (see \autoref{chap:STP}).455 When \np{ln\_traldf\_msc}~\forcode{= .true.}, a Method of Stabilizing Correction is used in which 456 the pure vertical component is split into an explicit and an implicit part \citep{Lemarie_OM2012}. 457 458 % ------------------------------------------------------------------------------------------------------------- 459 % Type of operator 460 % -------------------------------------------------------------------------------------------------------------461 \subsection[Type of operator (\ protect\np{ln\_traldf}\{\_NONE,\_lap,\_blp\}\})]{Type of operator (\protect\np{ln\_traldf\_NONE}, \protect\np{ln\_traldf\_lap}, or \protect\np{ln\_traldf\_blp}) }483 This latter component is solved implicitly together with the vertical diffusion term 484 (see \autoref{chap:TD}). 485 When \np[=.true.]{ln_traldf_msc}{ln\_traldf\_msc}, 486 a Method of Stabilizing Correction is used in which the pure vertical component is split into 487 an explicit and an implicit part \citep{lemarie.debreu.ea_OM12}. 488 489 %% ================================================================================================= 490 \subsection[Type of operator (\forcode{ln_traldf_}\{\forcode{OFF,lap,blp}\})]{Type of operator (\protect\np{ln_traldf_OFF}{ln\_traldf\_OFF}, \protect\np{ln_traldf_lap}{ln\_traldf\_lap}, or \protect\np{ln_traldf_blp}{ln\_traldf\_blp})} 462 491 \label{subsec:TRA_ldf_op} 463 492 … … 465 494 466 495 \begin{description} 467 \item[\np{ln\_traldf\_NONE}~\forcode{= .true.}:] 468 no operator selected, the lateral diffusive tendency will not be applied to the tracer equation. 469 This option can be used when the selected advection scheme is diffusive enough (MUSCL scheme for example). 470 \item[\np{ln\_traldf\_lap}~\forcode{= .true.}:] 471 a laplacian operator is selected. 472 This harmonic operator takes the following expression: $\mathpzc{L}(T) = \nabla \cdot A_{ht} \; \nabla T $, 496 \item [{\np[=.true.]{ln_traldf_OFF}{ln\_traldf\_OFF}}] no operator selected, 497 the lateral diffusive tendency will not be applied to the tracer equation. 498 This option can be used when the selected advection scheme is diffusive enough 499 (MUSCL scheme for example). 500 \item [{\np[=.true.]{ln_traldf_lap}{ln\_traldf\_lap}}] a laplacian operator is selected. 501 This harmonic operator takes the following expression: 502 $\mathcal{L}(T) = \nabla \cdot A_{ht} \; \nabla T $, 473 503 where the gradient operates along the selected direction (see \autoref{subsec:TRA_ldf_dir}), 474 504 and $A_{ht}$ is the eddy diffusivity coefficient expressed in $m^2/s$ (see \autoref{chap:LDF}). 475 \item[\np{ln\_traldf\_blp}~\forcode{= .true.}]: 476 a bilaplacian operator is selected. 505 \item [{\np[=.true.]{ln_traldf_blp}{ln\_traldf\_blp}}] a bilaplacian operator is selected. 477 506 This biharmonic operator takes the following expression: 478 $\math pzc{B} = - \mathpzc{L}(\mathpzc{L}(T)) = - \nabla \cdot b \nabla (\nabla \cdot b \nabla T)$507 $\mathcal{B} = - \mathcal{L}(\mathcal{L}(T)) = - \nabla \cdot b \nabla (\nabla \cdot b \nabla T)$ 479 508 where the gradient operats along the selected direction, 480 and $b^2 = B_{ht}$ is the eddy diffusivity coefficient expressed in $m^4/s$ (see \autoref{chap:LDF}). 509 and $b^2 = B_{ht}$ is the eddy diffusivity coefficient expressed in $m^4/s$ 510 (see \autoref{chap:LDF}). 481 511 In the code, the bilaplacian operator is obtained by calling the laplacian twice. 482 512 \end{description} … … 486 516 minimizing the impact on the larger scale features. 487 517 The main difference between the two operators is the scale selectiveness. 488 The bilaplacian damping time (\ie its spin down time) scales like $\lambda^{-4}$ for 489 disturbances of wavelength $\lambda$ (so that short waves damped more rapidelly than long ones), 518 The bilaplacian damping time (\ie\ its spin down time) scales like 519 $\lambda^{-4}$ for disturbances of wavelength $\lambda$ 520 (so that short waves damped more rapidelly than long ones), 490 521 whereas the laplacian damping time scales only like $\lambda^{-2}$. 491 522 492 % ------------------------------------------------------------------------------------------------------------- 493 % Direction of action 494 % ------------------------------------------------------------------------------------------------------------- 495 \subsection[Action direction (\protect\np{ln\_traldf}\{\_lev,\_hor,\_iso,\_triad\})]{Direction of action (\protect\np{ln\_traldf\_lev}, \protect\np{ln\_traldf\_hor}, \protect\np{ln\_traldf\_iso}, or \protect\np{ln\_traldf\_triad}) } 523 %% ================================================================================================= 524 \subsection[Action direction (\forcode{ln_traldf_}\{\forcode{lev,hor,iso,triad}\})]{Direction of action (\protect\np{ln_traldf_lev}{ln\_traldf\_lev}, \protect\np{ln_traldf_hor}{ln\_traldf\_hor}, \protect\np{ln_traldf_iso}{ln\_traldf\_iso}, or \protect\np{ln_traldf_triad}{ln\_traldf\_triad})} 496 525 \label{subsec:TRA_ldf_dir} 497 526 498 527 The choice of a direction of action determines the form of operator used. 499 528 The operator is a simple (re-entrant) laplacian acting in the (\textbf{i},\textbf{j}) plane when 500 iso-level option is used (\np {ln\_traldf\_lev}~\forcode{= .true.}) or501 when a horizontal (\iegeopotential) operator is demanded in \textit{z}-coordinate502 (\np{ln \_traldf\_hor} and \np{ln\_zco} equal \forcode{.true.}).529 iso-level option is used (\np[=.true.]{ln_traldf_lev}{ln\_traldf\_lev}) or when 530 a horizontal (\ie\ geopotential) operator is demanded in \textit{z}-coordinate 531 (\np{ln_traldf_hor}{ln\_traldf\_hor} and \np[=.true.]{ln_zco}{ln\_zco}). 503 532 The associated code can be found in the \mdl{traldf\_lap\_blp} module. 504 533 The operator is a rotated (re-entrant) laplacian when 505 534 the direction along which it acts does not coincide with the iso-level surfaces, 506 535 that is when standard or triad iso-neutral option is used 507 (\np{ln \_traldf\_iso} or \np{ln\_traldf\_triad} equals\forcode{.true.},536 (\np{ln_traldf_iso}{ln\_traldf\_iso} or \np{ln_traldf_triad}{ln\_traldf\_triad} = \forcode{.true.}, 508 537 see \mdl{traldf\_iso} or \mdl{traldf\_triad} module, resp.), or 509 when a horizontal (\ie geopotential) operator is demanded in \textit{s}-coordinate510 (\np{ln \_traldf\_hor} and \np{ln\_sco} equal \forcode{.true.})511 \footnote{In this case, the standard iso-neutral operator will be automatically selected}.538 when a horizontal (\ie\ geopotential) operator is demanded in \textit{s}-coordinate 539 (\np{ln_traldf_hor}{ln\_traldf\_hor} and \np{ln_sco}{ln\_sco} = \forcode{.true.}) \footnote{ 540 In this case, the standard iso-neutral operator will be automatically selected}. 512 541 In that case, a rotation is applied to the gradient(s) that appears in the operator so that 513 542 diffusive fluxes acts on the three spatial direction. … … 516 545 the next two sub-sections. 517 546 518 % ------------------------------------------------------------------------------------------------------------- 519 % iso-level operator 520 % ------------------------------------------------------------------------------------------------------------- 521 \subsection{Iso-level (bi -)laplacian operator ( \protect\np{ln\_traldf\_iso}) } 547 %% ================================================================================================= 548 \subsection[Iso-level (bi-)laplacian operator (\forcode{ln_traldf_iso})]{Iso-level (bi-)laplacian operator ( \protect\np{ln_traldf_iso}{ln\_traldf\_iso})} 522 549 \label{subsec:TRA_ldf_lev} 523 550 524 The laplacian diffusion operator acting along the model (\textit{i,j})-surfaces is given by: 525 \begin{equation} 526 \label{eq: tra_ldf_lap}551 The laplacian diffusion operator acting along the model (\textit{i,j})-surfaces is given by: 552 \begin{equation} 553 \label{eq:TRA_ldf_lap} 527 554 D_t^{lT} = \frac{1}{b_t} \Bigg( \delta_{i} \lt[ A_u^{lT} \; \frac{e_{2u} \, e_{3u}}{e_{1u}} \; \delta_{i + 1/2} [T] \rt] 528 555 + \delta_{j} \lt[ A_v^{lT} \; \frac{e_{1v} \, e_{3v}}{e_{2v}} \; \delta_{j + 1/2} [T] \rt] \Bigg) … … 531 558 where zero diffusive fluxes is assumed across solid boundaries, 532 559 first (and third in bilaplacian case) horizontal tracer derivative are masked. 533 It is implemented in the \rou{traldf\_lap} subroutine found in the \mdl{traldf\_lap} module. 534 The module also contains \rou{traldf\_blp}, the subroutine calling twice \rou{traldf\_lap} in order to 560 It is implemented in the \rou{tra\_ldf\_lap} subroutine found in the \mdl{traldf\_lap\_blp} module. 561 The module also contains \rou{tra\_ldf\_blp}, 562 the subroutine calling twice \rou{tra\_ldf\_lap} in order to 535 563 compute the iso-level bilaplacian operator. 536 564 537 565 It is a \textit{horizontal} operator (\ie acting along geopotential surfaces) in 538 the $z$-coordinate with or without partial steps, but is simply an iso-level operator in the $s$-coordinate. 539 It is thus used when, in addition to \np{ln\_traldf\_lap} or \np{ln\_traldf\_blp}~\forcode{= .true.}, 540 we have \np{ln\_traldf\_lev}~\forcode{= .true.} or \np{ln\_traldf\_hor}~=~\np{ln\_zco}~\forcode{= .true.}. 566 the $z$-coordinate with or without partial steps, 567 but is simply an iso-level operator in the $s$-coordinate. 568 It is thus used when, 569 in addition to \np{ln_traldf_lap}{ln\_traldf\_lap} or \np[=.true.]{ln_traldf_blp}{ln\_traldf\_blp}, 570 we have \np[=.true.]{ln_traldf_lev}{ln\_traldf\_lev} or 571 \np[=]{ln_traldf_hor}{ln\_traldf\_hor}\np[=.true.]{ln_zco}{ln\_zco}. 541 572 In both cases, it significantly contributes to diapycnal mixing. 542 573 It is therefore never recommended, even when using it in the bilaplacian case. 543 574 544 Note that in the partial step $z$-coordinate (\np {ln\_zps}~\forcode{= .true.}),575 Note that in the partial step $z$-coordinate (\np[=.true.]{ln_zps}{ln\_zps}), 545 576 tracers in horizontally adjacent cells are located at different depths in the vicinity of the bottom. 546 In this case, horizontal derivatives in (\autoref{eq:tra_ldf_lap}) at the bottom level require a specific treatment. 577 In this case, 578 horizontal derivatives in (\autoref{eq:TRA_ldf_lap}) at the bottom level require a specific treatment. 547 579 They are calculated in the \mdl{zpshde} module, described in \autoref{sec:TRA_zpshde}. 548 580 549 % ------------------------------------------------------------------------------------------------------------- 550 % Rotated laplacian operator 551 % ------------------------------------------------------------------------------------------------------------- 552 \subsection{Standard and triad (bi -)laplacian operator} 581 %% ================================================================================================= 582 \subsection{Standard and triad (bi-)laplacian operator} 553 583 \label{subsec:TRA_ldf_iso_triad} 554 584 555 %&& Standard rotated (bi -)laplacian operator 556 %&& ---------------------------------------------- 557 \subsubsection{Standard rotated (bi -)laplacian operator (\protect\mdl{traldf\_iso})} 585 %% ================================================================================================= 586 \subsubsection[Standard rotated (bi-)laplacian operator (\textit{traldf\_iso.F90})]{Standard rotated (bi-)laplacian operator (\protect\mdl{traldf\_iso})} 558 587 \label{subsec:TRA_ldf_iso} 559 The general form of the second order lateral tracer subgrid scale physics (\autoref{eq:PE_zdf}) 560 takes the following semi -discrete space form in $z$- and $s$-coordinates: 561 \begin{equation} 562 \label{eq:tra_ldf_iso} 588 589 The general form of the second order lateral tracer subgrid scale physics (\autoref{eq:MB_zdf}) 590 takes the following semi-discrete space form in $z$- and $s$-coordinates: 591 \begin{equation} 592 \label{eq:TRA_ldf_iso} 563 593 \begin{split} 564 594 D_T^{lT} = \frac{1}{b_t} \Bigg[ \quad &\delta_i A_u^{lT} \lt( \frac{e_{2u} e_{3u}}{e_{1u}} \, \delta_{i + 1/2} [T] … … 573 603 where $b_t = e_{1t} \, e_{2t} \, e_{3t}$ is the volume of $T$-cells, 574 604 $r_1$ and $r_2$ are the slopes between the surface of computation ($z$- or $s$-surfaces) and 575 the surface along which the diffusion operator acts (\ie horizontal or iso-neutral surfaces).576 It is thus used when, in addition to \np {ln\_traldf\_lap}~\forcode{= .true.},577 we have \np {ln\_traldf\_iso}~\forcode{= .true.},578 or both \np {ln\_traldf\_hor}~\forcode{= .true.} and \np{ln\_zco}~\forcode{= .true.}.605 the surface along which the diffusion operator acts (\ie\ horizontal or iso-neutral surfaces). 606 It is thus used when, in addition to \np[=.true.]{ln_traldf_lap}{ln\_traldf\_lap}, 607 we have \np[=.true.]{ln_traldf_iso}{ln\_traldf\_iso}, 608 or both \np[=.true.]{ln_traldf_hor}{ln\_traldf\_hor} and \np[=.true.]{ln_zco}{ln\_zco}. 579 609 The way these slopes are evaluated is given in \autoref{sec:LDF_slp}. 580 At the surface, bottom and lateral boundaries, the turbulent fluxes of heat and salt are set to zero using 581 the mask technique (see \autoref{sec:LBC_coast}). 582 583 The operator in \autoref{eq:tra_ldf_iso} involves both lateral and vertical derivatives. 584 For numerical stability, the vertical second derivative must be solved using the same implicit time scheme as that 585 used in the vertical physics (see \autoref{sec:TRA_zdf}). 610 At the surface, bottom and lateral boundaries, 611 the turbulent fluxes of heat and salt are set to zero using the mask technique 612 (see \autoref{sec:LBC_coast}). 613 614 The operator in \autoref{eq:TRA_ldf_iso} involves both lateral and vertical derivatives. 615 For numerical stability, the vertical second derivative must be solved using 616 the same implicit time scheme as that used in the vertical physics (see \autoref{sec:TRA_zdf}). 586 617 For computer efficiency reasons, this term is not computed in the \mdl{traldf\_iso} module, 587 618 but in the \mdl{trazdf} module where, if iso-neutral mixing is used, 588 the vertical mixing coefficient is simply increased by $\frac{e_{1w} e_{2w}}{e_{3w}}(r_{1w}^2 + r_{2w}^2)$. 619 the vertical mixing coefficient is simply increased by 620 $\frac{e_{1w} e_{2w}}{e_{3w}}(r_{1w}^2 + r_{2w}^2)$. 589 621 590 622 This formulation conserves the tracer but does not ensure the decrease of the tracer variance. 591 Nevertheless the treatment performed on the slopes (see \autoref{chap:LDF}) allows the model to run safely without 592 any additional background horizontal diffusion \citep{Guilyardi_al_CD01}. 593 594 Note that in the partial step $z$-coordinate (\np{ln\_zps}~\forcode{= .true.}), 595 the horizontal derivatives at the bottom level in \autoref{eq:tra_ldf_iso} require a specific treatment. 623 Nevertheless the treatment performed on the slopes (see \autoref{chap:LDF}) allows the model to 624 run safely without any additional background horizontal diffusion \citep{guilyardi.madec.ea_CD01}. 625 626 Note that in the partial step $z$-coordinate (\np[=.true.]{ln_zps}{ln\_zps}), 627 the horizontal derivatives at the bottom level in \autoref{eq:TRA_ldf_iso} require 628 a specific treatment. 596 629 They are calculated in module zpshde, described in \autoref{sec:TRA_zpshde}. 597 630 598 %&& Triad rotated (bi -)laplacian operator 599 %&& ------------------------------------------- 600 \subsubsection{Triad rotated (bi -)laplacian operator (\protect\np{ln\_traldf\_triad})} 631 %% ================================================================================================= 632 \subsubsection[Triad rotated (bi-)laplacian operator (\forcode{ln_traldf_triad})]{Triad rotated (bi-)laplacian operator (\protect\np{ln_traldf_triad}{ln\_traldf\_triad})} 601 633 \label{subsec:TRA_ldf_triad} 602 634 603 If the Griffies triad scheme is employed (\np{ln\_traldf\_triad}~\forcode{= .true.}; see \autoref{apdx:triad}) 604 605 An alternative scheme developed by \cite{Griffies_al_JPO98} which ensures tracer variance decreases 606 is also available in \NEMO (\np{ln\_traldf\_grif}~\forcode{= .true.}).607 A complete description of the algorithm is given in \autoref{apdx:triad}. 608 609 The lateral fourth order bilaplacian operator on tracers is obtained by applying (\autoref{eq:tra_ldf_lap}) twice.635 An alternative scheme developed by \cite{griffies.gnanadesikan.ea_JPO98} which 636 ensures tracer variance decreases is also available in \NEMO\ 637 (\np[=.true.]{ln_traldf_triad}{ln\_traldf\_triad}). 638 A complete description of the algorithm is given in \autoref{apdx:TRIADS}. 639 640 The lateral fourth order bilaplacian operator on tracers is obtained by 641 applying (\autoref{eq:TRA_ldf_lap}) twice. 610 642 The operator requires an additional assumption on boundary conditions: 611 643 both first and third derivative terms normal to the coast are set to zero. 612 644 613 The lateral fourth order operator formulation on tracers is obtained by applying (\autoref{eq:tra_ldf_iso}) twice. 645 The lateral fourth order operator formulation on tracers is obtained by 646 applying (\autoref{eq:TRA_ldf_iso}) twice. 614 647 It requires an additional assumption on boundary conditions: 615 648 first and third derivative terms normal to the coast, 616 649 normal to the bottom and normal to the surface are set to zero. 617 650 618 %&& Option for the rotated operators 619 %&& ---------------------------------------------- 651 %% ================================================================================================= 620 652 \subsubsection{Option for the rotated operators} 621 653 \label{subsec:TRA_ldf_options} 622 654 623 \begin{itemize} 624 \item \np{ln\_traldf\_msc} = Method of Stabilizing Correction (both operators) 625 \item \np{rn\_slpmax} = slope limit (both operators) 626 \item \np{ln\_triad\_iso} = pure horizontal mixing in ML (triad only) 627 \item \np{rn\_sw\_triad} $= 1$ switching triad; $= 0$ all 4 triads used (triad only) 628 \item \np{ln\_botmix\_triad} = lateral mixing on bottom (triad only) 629 \end{itemize} 630 631 % ================================================================ 632 % Tracer Vertical Diffusion 633 % ================================================================ 634 \section{Tracer vertical diffusion (\protect\mdl{trazdf})} 655 \begin{labeling}{{\np{ln_botmix_triad}{ln\_botmix\_triad}}} 656 \item [{\np{ln_traldf_msc}{ln\_traldf\_msc} }] Method of Stabilizing Correction (both operators) 657 \item [{\np{rn_slpmax}{rn\_slpmax} }] Slope limit (both operators) 658 \item [{\np{ln_triad_iso}{ln\_triad\_iso} }] Pure horizontal mixing in ML (triad only) 659 \item [{\np{rn_sw_triad}{rn\_sw\_triad} }] \forcode{=1} switching triad; 660 \forcode{= 0} all 4 triads used (triad only) 661 \item [{\np{ln_botmix_triad}{ln\_botmix\_triad}}] Lateral mixing on bottom (triad only) 662 \end{labeling} 663 664 %% ================================================================================================= 665 \section[Tracer vertical diffusion (\textit{trazdf.F90})]{Tracer vertical diffusion (\protect\mdl{trazdf})} 635 666 \label{sec:TRA_zdf} 636 %--------------------------------------------namzdf--------------------------------------------------------- 637 638 \nlst{namzdf} 639 %-------------------------------------------------------------------------------------------------------------- 640 641 Options are defined through the \ngn{namzdf} namelist variables. 642 The formulation of the vertical subgrid scale tracer physics is the same for all the vertical coordinates, 643 and is based on a laplacian operator. 644 The vertical diffusion operator given by (\autoref{eq:PE_zdf}) takes the following semi -discrete space form: 645 \begin{gather*} 646 % \label{eq:tra_zdf} 647 D^{vT}_T = \frac{1}{e_{3t}} \, \delta_k \lt[ \, \frac{A^{vT}_w}{e_{3w}} \delta_{k + 1/2}[T] \, \rt] \\ 648 D^{vS}_T = \frac{1}{e_{3t}} \; \delta_k \lt[ \, \frac{A^{vS}_w}{e_{3w}} \delta_{k + 1/2}[S] \, \rt] 649 \end{gather*} 650 where $A_w^{vT}$ and $A_w^{vS}$ are the vertical eddy diffusivity coefficients on temperature and salinity, 651 respectively. 667 668 Options are defined through the \nam{zdf}{zdf} namelist variables. 669 The formulation of the vertical subgrid scale tracer physics is the same for 670 all the vertical coordinates, and is based on a laplacian operator. 671 The vertical diffusion operator given by (\autoref{eq:MB_zdf}) takes 672 the following semi-discrete space form: 673 \[ 674 % \label{eq:TRA_zdf} 675 D^{vT}_T = \frac{1}{e_{3t}} \, \delta_k \lt[ \, \frac{A^{vT}_w}{e_{3w}} \delta_{k + 1/2}[T] \, \rt] \quad 676 D^{vS}_T = \frac{1}{e_{3t}} \; \delta_k \lt[ \, \frac{A^{vS}_w}{e_{3w}} \delta_{k + 1/2}[S] \, \rt] 677 \] 678 where $A_w^{vT}$ and $A_w^{vS}$ are the vertical eddy diffusivity coefficients on 679 temperature and salinity, respectively. 652 680 Generally, $A_w^{vT} = A_w^{vS}$ except when double diffusive mixing is parameterised 653 (\ie \key{zdfddm} is defined).681 (\ie\ \np[=.true.]{ln_zdfddm}{ln\_zdfddm},). 654 682 The way these coefficients are evaluated is given in \autoref{chap:ZDF} (ZDF). 655 Furthermore, when iso-neutral mixing is used, both mixing coefficients are increased by656 $\frac{e_{1w} e_{2w}}{e_{3w} }({r_{1w}^2 + r_{2w}^2})$ to account for the vertical second derivative of 657 \autoref{eq:tra_ldf_iso}.683 Furthermore, when iso-neutral mixing is used, 684 both mixing coefficients are increased by $\frac{e_{1w} e_{2w}}{e_{3w} }({r_{1w}^2 + r_{2w}^2})$ to 685 account for the vertical second derivative of \autoref{eq:TRA_ldf_iso}. 658 686 659 687 At the surface and bottom boundaries, the turbulent fluxes of heat and salt must be specified. … … 662 690 a geothermal flux forcing is prescribed as a bottom boundary condition (see \autoref{subsec:TRA_bbc}). 663 691 664 The large eddy coefficient found in the mixed layer together with high vertical resolution implies that 665 in the case of explicit time stepping (\np{ln\_zdfexp}~\forcode{= .true.}) 666 there would be too restrictive a constraint on the time step. 667 Therefore, the default implicit time stepping is preferred for the vertical diffusion since 692 The large eddy coefficient found in the mixed layer together with high vertical resolution implies 693 that there would be too restrictive constraint on the time step if we use explicit time stepping. 694 Therefore an implicit time stepping is preferred for the vertical diffusion since 668 695 it overcomes the stability constraint. 669 A forward time differencing scheme (\np{ln\_zdfexp}~\forcode{= .true.}) using 670 a time splitting technique (\np{nn\_zdfexp} $> 1$) is provided as an alternative. 671 Namelist variables \np{ln\_zdfexp} and \np{nn\_zdfexp} apply to both tracers and dynamics. 672 673 % ================================================================ 674 % External Forcing 675 % ================================================================ 696 697 %% ================================================================================================= 676 698 \section{External forcing} 677 699 \label{sec:TRA_sbc_qsr_bbc} 678 700 679 % ------------------------------------------------------------------------------------------------------------- 680 % surface boundary condition 681 % ------------------------------------------------------------------------------------------------------------- 682 \subsection{Surface boundary condition (\protect\mdl{trasbc})} 701 %% ================================================================================================= 702 \subsection[Surface boundary condition (\textit{trasbc.F90})]{Surface boundary condition (\protect\mdl{trasbc})} 683 703 \label{subsec:TRA_sbc} 684 704 … … 690 710 691 711 Due to interactions and mass exchange of water ($F_{mass}$) with other Earth system components 692 (\ie atmosphere, sea-ice, land), the change in the heat and salt content of the surface layer of the ocean is due 693 both to the heat and salt fluxes crossing the sea surface (not linked with $F_{mass}$) and 712 (\ie\ atmosphere, sea-ice, land), 713 the change in the heat and salt content of the surface layer of the ocean is due both to 714 the heat and salt fluxes crossing the sea surface (not linked with $F_{mass}$) and 694 715 to the heat and salt content of the mass exchange. 695 716 They are both included directly in $Q_{ns}$, the surface heat flux, 696 717 and $F_{salt}$, the surface salt flux (see \autoref{chap:SBC} for further details). 697 By doing this, the forcing formulation is the same for any tracer (including temperature and salinity). 698 699 The surface module (\mdl{sbcmod}, see \autoref{chap:SBC}) provides the following forcing fields (used on tracers): 700 701 \begin{itemize} 702 \item 703 $Q_{ns}$, the non-solar part of the net surface heat flux that crosses the sea surface 704 (\ie the difference between the total surface heat flux and the fraction of the short wave flux that 705 penetrates into the water column, see \autoref{subsec:TRA_qsr}) 718 By doing this, the forcing formulation is the same for any tracer 719 (including temperature and salinity). 720 721 The surface module (\mdl{sbcmod}, see \autoref{chap:SBC}) provides the following forcing fields 722 (used on tracers): 723 724 \begin{labeling}{\textit{fwfisf}} 725 \item [$Q_{ns}$] The non-solar part of the net surface heat flux that crosses the sea surface 726 (\ie\ the difference between the total surface heat flux and 727 the fraction of the short wave flux that penetrates into the water column, 728 see \autoref{subsec:TRA_qsr}) 706 729 plus the heat content associated with of the mass exchange with the atmosphere and lands. 707 \item 708 $\textit{sfx}$, the salt flux resulting from ice-ocean mass exchange (freezing, melting, ridging...) 709 \item 710 \textit{emp}, the mass flux exchanged with the atmosphere (evaporation minus precipitation) and 730 \item [\textit{sfx}] The salt flux resulting from ice-ocean mass exchange 731 (freezing, melting, ridging...) 732 \item [\textit{emp}] The mass flux exchanged with the atmosphere (evaporation minus precipitation) and 711 733 possibly with the sea-ice and ice-shelves. 712 \item 713 \textit{rnf}, the mass flux associated with runoff 734 \item [\textit{rnf}] The mass flux associated with runoff 714 735 (see \autoref{sec:SBC_rnf} for further detail of how it acts on temperature and salinity tendencies) 715 \item 716 \textit{fwfisf}, the mass flux associated with ice shelf melt, 736 \item [\textit{fwfisf}] The mass flux associated with ice shelf melt, 717 737 (see \autoref{sec:SBC_isf} for further details on how the ice shelf melt is computed and applied). 718 \end{ itemize}738 \end{labeling} 719 739 720 740 The surface boundary condition on temperature and salinity is applied as follows: 721 741 \begin{equation} 722 \label{eq:tra_sbc} 723 \begin{alignedat}{2} 724 F^T &= \frac{1}{C_p} &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} &\overline{Q_{ns} }^t \\ 725 F^S &= &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} &\overline{\textit{sfx}}^t 726 \end{alignedat} 742 \label{eq:TRA_sbc} 743 F^T = \frac{1}{C_p} \frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} \overline{Q_{ns} }^t \qquad 744 F^S = \frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} \overline{\textit{sfx}}^t 727 745 \end{equation} 728 746 where $\overline x^t$ means that $x$ is averaged over two consecutive time steps 729 747 ($t - \rdt / 2$ and $t + \rdt / 2$). 730 Such time averaging prevents the divergence of odd and even time step (see \autoref{chap:STP}). 731 732 In the linear free surface case (\np{ln\_linssh}~\forcode{= .true.}), an additional term has to be added on 733 both temperature and salinity. 734 On temperature, this term remove the heat content associated with mass exchange that has been added to $Q_{ns}$. 735 On salinity, this term mimics the concentration/dilution effect that would have resulted from a change in 736 the volume of the first level. 748 Such time averaging prevents the divergence of odd and even time step (see \autoref{chap:TD}). 749 750 In the linear free surface case (\np[=.true.]{ln_linssh}{ln\_linssh}), 751 an additional term has to be added on both temperature and salinity. 752 On temperature, this term remove the heat content associated with 753 mass exchange that has been added to $Q_{ns}$. 754 On salinity, this term mimics the concentration/dilution effect that would have resulted from 755 a change in the volume of the first level. 737 756 The resulting surface boundary condition is applied as follows: 738 757 \begin{equation} 739 \label{eq:tra_sbc_lin} 740 \begin{alignedat}{2} 741 F^T &= \frac{1}{C_p} &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} 742 &\overline{(Q_{ns} - C_p \, \textit{emp} \lt. T \rt|_{k = 1})}^t \\ 743 F^S &= &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} 744 &\overline{(\textit{sfx} - \textit{emp} \lt. S \rt|_{k = 1})}^t 745 \end{alignedat} 746 \end{equation} 747 Note that an exact conservation of heat and salt content is only achieved with non-linear free surface. 758 \label{eq:TRA_sbc_lin} 759 F^T = \frac{1}{C_p} \frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} 760 \overline{(Q_{ns} - C_p \, \textit{emp} \lt. T \rt|_{k = 1})}^t \qquad 761 F^S = \frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} 762 \overline{(\textit{sfx} - \textit{emp} \lt. S \rt|_{k = 1})}^t 763 \end{equation} 764 Note that an exact conservation of heat and salt content is only achieved with 765 non-linear free surface. 748 766 In the linear free surface case, there is a small imbalance. 749 The imbalance is larger than the imbalance associated with the Asselin time filter \citep{Leclair_Madec_OM09}.750 This is the reason why the modified filter is not applied in the linear free surface case (see \autoref{chap:STP}).751 752 % ------------------------------------------------------------------------------------------------------------- 753 % Solar Radiation Penetration 754 % -------------------------------------------------------------------------------------------------------------755 \subsection {Solar radiation penetration (\protect\mdl{traqsr})}767 The imbalance is larger than the imbalance associated with the Asselin time filter 768 \citep{leclair.madec_OM09}. 769 This is the reason why the modified filter is not applied in the linear free surface case 770 (see \autoref{chap:TD}). 771 772 %% ================================================================================================= 773 \subsection[Solar radiation penetration (\textit{traqsr.F90})]{Solar radiation penetration (\protect\mdl{traqsr})} 756 774 \label{subsec:TRA_qsr} 757 %--------------------------------------------namqsr-------------------------------------------------------- 758 759 \nlst{namtra_qsr} 760 %-------------------------------------------------------------------------------------------------------------- 761 762 Options are defined through the \ngn{namtra\_qsr} namelist variables. 763 When the penetrative solar radiation option is used (\np{ln\_flxqsr}~\forcode{= .true.}), 775 776 \begin{listing} 777 \nlst{namtra_qsr} 778 \caption{\forcode{&namtra_qsr}} 779 \label{lst:namtra_qsr} 780 \end{listing} 781 782 Options are defined through the \nam{tra_qsr}{tra\_qsr} namelist variables. 783 When the penetrative solar radiation option is used (\np[=.true.]{ln_traqsr}{ln\_traqsr}), 764 784 the solar radiation penetrates the top few tens of meters of the ocean. 765 If it is not used (\np{ln\_flxqsr}~\forcode{= .false.}) all the heat flux is absorbed in the first ocean level. 766 Thus, in the former case a term is added to the time evolution equation of temperature \autoref{eq:PE_tra_T} and 767 the surface boundary condition is modified to take into account only the non-penetrative part of the surface 768 heat flux: 769 \begin{equation} 770 \label{eq:PE_qsr} 785 If it is not used (\np[=.false.]{ln_traqsr}{ln\_traqsr}) all the heat flux is absorbed in 786 the first ocean level. 787 Thus, in the former case a term is added to the time evolution equation of temperature 788 \autoref{eq:MB_PE_tra_T} and the surface boundary condition is modified to 789 take into account only the non-penetrative part of the surface heat flux: 790 \begin{equation} 791 \label{eq:TRA_PE_qsr} 771 792 \begin{gathered} 772 793 \pd[T]{t} = \ldots + \frac{1}{\rho_o \, C_p \, e_3} \; \pd[I]{k} \\ … … 774 795 \end{gathered} 775 796 \end{equation} 776 where $Q_{sr}$ is the penetrative part of the surface heat flux (\ie the shortwave radiation) and797 where $Q_{sr}$ is the penetrative part of the surface heat flux (\ie\ the shortwave radiation) and 777 798 $I$ is the downward irradiance ($\lt. I \rt|_{z = \eta} = Q_{sr}$). 778 The additional term in \autoref{eq: PE_qsr} is discretized as follows:779 \begin{equation} 780 \label{eq: tra_qsr}799 The additional term in \autoref{eq:TRA_PE_qsr} is discretized as follows: 800 \begin{equation} 801 \label{eq:TRA_qsr} 781 802 \frac{1}{\rho_o \, C_p \, e_3} \, \pd[I]{k} \equiv \frac{1}{\rho_o \, C_p \, e_{3t}} \delta_k [I_w] 782 803 \end{equation} 783 804 784 805 The shortwave radiation, $Q_{sr}$, consists of energy distributed across a wide spectral range. 785 The ocean is strongly absorbing for wavelengths longer than 700~nm and these wavelengths contribute to 786 heating the upper few tens of centimetres. 787 The fraction of $Q_{sr}$ that resides in these almost non-penetrative wavebands, $R$, is $\sim 58\%$ 788 (specified through namelist parameter \np{rn\_abs}). 789 It is assumed to penetrate the ocean with a decreasing exponential profile, with an e-folding depth scale, $\xi_0$, 790 of a few tens of centimetres (typically $\xi_0 = 0.35~m$ set as \np{rn\_si0} in the \ngn{namtra\_qsr} namelist). 791 For shorter wavelengths (400-700~nm), the ocean is more transparent, and solar energy propagates to 792 larger depths where it contributes to local heating. 793 The way this second part of the solar energy penetrates into the ocean depends on which formulation is chosen. 794 In the simple 2-waveband light penetration scheme (\np{ln\_qsr\_2bd}~\forcode{= .true.}) 806 The ocean is strongly absorbing for wavelengths longer than 700 $nm$ and 807 these wavelengths contribute to heat the upper few tens of centimetres. 808 The fraction of $Q_{sr}$ that resides in these almost non-penetrative wavebands, $R$, is $\sim$ 58\% 809 (specified through namelist parameter \np{rn_abs}{rn\_abs}). 810 It is assumed to penetrate the ocean with a decreasing exponential profile, 811 with an e-folding depth scale, $\xi_0$, of a few tens of centimetres 812 (typically $\xi_0 = 0.35~m$ set as \np{rn_si0}{rn\_si0} in the \nam{tra_qsr}{tra\_qsr} namelist). 813 For shorter wavelengths (400-700 $nm$), the ocean is more transparent, 814 and solar energy propagates to larger depths where it contributes to local heating. 815 The way this second part of the solar energy penetrates into 816 the ocean depends on which formulation is chosen. 817 In the simple 2-waveband light penetration scheme (\np[=.true.]{ln_qsr_2bd}{ln\_qsr\_2bd}) 795 818 a chlorophyll-independent monochromatic formulation is chosen for the shorter wavelengths, 796 leading to the following expression \citep{ Paulson1977}:819 leading to the following expression \citep{paulson.simpson_JPO77}: 797 820 \[ 798 % \label{eq: traqsr_iradiance}821 % \label{eq:TRA_qsr_iradiance} 799 822 I(z) = Q_{sr} \lt[ Re^{- z / \xi_0} + (1 - R) e^{- z / \xi_1} \rt] 800 823 \] 801 824 where $\xi_1$ is the second extinction length scale associated with the shorter wavelengths. 802 It is usually chosen to be 23~m by setting the \np{rn \_si0} namelist parameter.803 The set of default values ($\xi_0, \xi_1, R$) corresponds to a Type I water in Jerlov's (1968) classification804 (oligotrophic waters).825 It is usually chosen to be 23~m by setting the \np{rn_si0}{rn\_si0} namelist parameter. 826 The set of default values ($\xi_0, \xi_1, R$) corresponds to 827 a Type I water in Jerlov's (1968) classification (oligotrophic waters). 805 828 806 829 Such assumptions have been shown to provide a very crude and simplistic representation of 807 observed light penetration profiles (\cite{ Morel_JGR88}, see also \autoref{fig:traqsr_irradiance}).830 observed light penetration profiles (\cite{morel_JGR88}, see also \autoref{fig:TRA_qsr_irradiance}). 808 831 Light absorption in the ocean depends on particle concentration and is spectrally selective. 809 \cite{ Morel_JGR88} has shown that an accurate representation of light penetration can be provided by832 \cite{morel_JGR88} has shown that an accurate representation of light penetration can be provided by 810 833 a 61 waveband formulation. 811 834 Unfortunately, such a model is very computationally expensive. 812 Thus, \cite{Lengaigne_al_CD07} have constructed a simplified version of this formulation in which 813 visible light is split into three wavebands: blue (400-500 nm), green (500-600 nm) and red (600-700nm). 814 For each wave-band, the chlorophyll-dependent attenuation coefficient is fitted to the coefficients computed from 815 the full spectral model of \cite{Morel_JGR88} (as modified by \cite{Morel_Maritorena_JGR01}), 816 assuming the same power-law relationship. 817 As shown in \autoref{fig:traqsr_irradiance}, this formulation, called RGB (Red-Green-Blue), 835 Thus, \cite{lengaigne.menkes.ea_CD07} have constructed a simplified version of 836 this formulation in which visible light is split into three wavebands: 837 blue (400-500 $nm$), green (500-600 $nm$) and red (600-700 $nm$). 838 For each wave-band, the chlorophyll-dependent attenuation coefficient is fitted to 839 the coefficients computed from the full spectral model of \cite{morel_JGR88} 840 (as modified by \cite{morel.maritorena_JGR01}), assuming the same power-law relationship. 841 As shown in \autoref{fig:TRA_qsr_irradiance}, this formulation, 842 called RGB (\textbf{R}ed-\textbf{G}reen-\textbf{B}lue), 818 843 reproduces quite closely the light penetration profiles predicted by the full spectal model, 819 844 but with much greater computational efficiency. 820 845 The 2-bands formulation does not reproduce the full model very well. 821 846 822 The RGB formulation is used when \np {ln\_qsr\_rgb}~\forcode{= .true.}.823 The RGB attenuation coefficients (\ie the inverses of the extinction length scales) are tabulated over824 61 nonuniform chlorophyll classes ranging from 0.01 to 10 g.Chl/L 847 The RGB formulation is used when \np[=.true.]{ln_qsr_rgb}{ln\_qsr\_rgb}. 848 The RGB attenuation coefficients (\ie\ the inverses of the extinction length scales) are 849 tabulated over 61 nonuniform chlorophyll classes ranging from 0.01 to 10 $g.Chl/L$ 825 850 (see the routine \rou{trc\_oce\_rgb} in \mdl{trc\_oce} module). 826 851 Four types of chlorophyll can be chosen in the RGB formulation: 827 852 828 853 \begin{description} 829 \item[\np{nn\_chdta}~\forcode{= 0}] 830 a constant 0.05 g.Chl/L value everywhere ; 831 \item[\np{nn\_chdta}~\forcode{= 1}] 832 an observed time varying chlorophyll deduced from satellite surface ocean color measurement spread uniformly in 833 the vertical direction; 834 \item[\np{nn\_chdta}~\forcode{= 2}] 835 same as previous case except that a vertical profile of chlorophyl is used. 836 Following \cite{Morel_Berthon_LO89}, the profile is computed from the local surface chlorophyll value; 837 \item[\np{ln\_qsr\_bio}~\forcode{= .true.}] 838 simulated time varying chlorophyll by TOP biogeochemical model. 839 In this case, the RGB formulation is used to calculate both the phytoplankton light limitation in 840 PISCES or LOBSTER and the oceanic heating rate. 841 \end{description} 842 843 The trend in \autoref{eq:tra_qsr} associated with the penetration of the solar radiation is added to 854 \item [{\np[=0]{nn_chldta}{nn\_chldta}}] a constant 0.05 $g.Chl/L$ value everywhere; 855 \item [{\np[=1]{nn_chldta}{nn\_chldta}}] an observed time varying chlorophyll deduced from 856 satellite surface ocean color measurement spread uniformly in the vertical direction; 857 \item [{\np[=2]{nn_chldta}{nn\_chldta}}] same as previous case except that 858 a vertical profile of chlorophyl is used. 859 Following \cite{morel.berthon_LO89}, 860 the profile is computed from the local surface chlorophyll value; 861 \item [{\np[=.true.]{ln_qsr_bio}{ln\_qsr\_bio}}] simulated time varying chlorophyll by 862 \TOP\ biogeochemical model. 863 In this case, the RGB formulation is used to calculate both 864 the phytoplankton light limitation in \PISCES\ and the oceanic heating rate. 865 \end{description} 866 867 The trend in \autoref{eq:TRA_qsr} associated with the penetration of the solar radiation is added to 844 868 the temperature trend, and the surface heat flux is modified in routine \mdl{traqsr}. 845 869 … … 847 871 the depth of $w-$levels does not significantly vary with location. 848 872 The level at which the light has been totally absorbed 849 (\ie it is less than the computer precision) is computed once,873 (\ie\ it is less than the computer precision) is computed once, 850 874 and the trend associated with the penetration of the solar radiation is only added down to that level. 851 Finally, note that when the ocean is shallow ($<$ 200~m), part of the solar radiation can reach the ocean floor. 875 Finally, note that when the ocean is shallow ($<$ 200~m), 876 part of the solar radiation can reach the ocean floor. 852 877 In this case, we have chosen that all remaining radiation is absorbed in the last ocean level 853 (\ie $I$ is masked). 854 855 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 856 \begin{figure}[!t] 857 \begin{center} 858 \includegraphics[]{Fig_TRA_Irradiance} 859 \caption{ 860 \protect\label{fig:traqsr_irradiance} 861 Penetration profile of the downward solar irradiance calculated by four models. 862 Two waveband chlorophyll-independent formulation (blue), 863 a chlorophyll-dependent monochromatic formulation (green), 864 4 waveband RGB formulation (red), 865 61 waveband Morel (1988) formulation (black) for a chlorophyll concentration of 866 (a) Chl=0.05 mg/m$^3$ and (b) Chl=0.5 mg/m$^3$. 867 From \citet{Lengaigne_al_CD07}. 868 } 869 \end{center} 878 (\ie\ $I$ is masked). 879 880 \begin{figure} 881 \centering 882 \includegraphics[width=0.66\textwidth]{TRA_Irradiance} 883 \caption[Penetration profile of the downward solar irradiance calculated by four models]{ 884 Penetration profile of the downward solar irradiance calculated by four models. 885 Two waveband chlorophyll-independent formulation (blue), 886 a chlorophyll-dependent monochromatic formulation (green), 887 4 waveband RGB formulation (red), 888 61 waveband Morel (1988) formulation (black) for a chlorophyll concentration of 889 (a) Chl=0.05 $mg/m^3$ and (b) Chl=0.5 $mg/m^3$. 890 From \citet{lengaigne.menkes.ea_CD07}.} 891 \label{fig:TRA_qsr_irradiance} 870 892 \end{figure} 871 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 872 873 % ------------------------------------------------------------------------------------------------------------- 874 % Bottom Boundary Condition 875 % ------------------------------------------------------------------------------------------------------------- 876 \subsection{Bottom boundary condition (\protect\mdl{trabbc})} 893 894 %% ================================================================================================= 895 \subsection[Bottom boundary condition (\textit{trabbc.F90}) - \forcode{ln_trabbc})]{Bottom boundary condition (\protect\mdl{trabbc} - \protect\np{ln_trabbc}{ln\_trabbc})} 877 896 \label{subsec:TRA_bbc} 878 %--------------------------------------------nambbc-------------------------------------------------------- 879 880 \nlst{nambbc}881 %-------------------------------------------------------------------------------------------------------------- 882 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 883 \ begin{figure}[!t]884 \begin{center} 885 \includegraphics[]{Fig_TRA_geoth}886 \caption{887 \protect\label{fig:geothermal}888 Geothermal Heat flux (in $mW.m^{-2}$) used by \cite{Emile-Geay_Madec_OS09}.889 It is inferred from the age of the sea floor and the formulae of \citet{Stein_Stein_Nat92}.890 }891 \ end{center}897 898 \begin{listing} 899 \nlst{nambbc} 900 \caption{\forcode{&nambbc}} 901 \label{lst:nambbc} 902 \end{listing} 903 904 \begin{figure} 905 \centering 906 \includegraphics[width=0.66\textwidth]{TRA_geoth} 907 \caption[Geothermal heat flux]{ 908 Geothermal Heat flux (in $mW.m^{-2}$) used by \cite{emile-geay.madec_OS09}. 909 It is inferred from the age of the sea floor and the formulae of \citet{stein.stein_N92}.} 910 \label{fig:TRA_geothermal} 892 911 \end{figure} 893 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>894 912 895 913 Usually it is assumed that there is no exchange of heat or salt through the ocean bottom, 896 \ie a no flux boundary condition is applied on active tracers at the bottom.914 \ie\ a no flux boundary condition is applied on active tracers at the bottom. 897 915 This is the default option in \NEMO, and it is implemented using the masking technique. 898 However, there is a non-zero heat flux across the seafloor that is associated with solid earth cooling. 899 This flux is weak compared to surface fluxes (a mean global value of $\sim 0.1 \, W/m^2$ \citep{Stein_Stein_Nat92}), 916 However, there is a non-zero heat flux across the seafloor that 917 is associated with solid earth cooling. 918 This flux is weak compared to surface fluxes 919 (a mean global value of $\sim 0.1 \, W/m^2$ \citep{stein.stein_N92}), 900 920 but it warms systematically the ocean and acts on the densest water masses. 901 921 Taking this flux into account in a global ocean model increases the deepest overturning cell 902 (\ie the one associated with the Antarctic Bottom Water) by a few Sverdrups \citep{Emile-Geay_Madec_OS09}. 903 904 Options are defined through the \ngn{namtra\_bbc} namelist variables. 905 The presence of geothermal heating is controlled by setting the namelist parameter \np{ln\_trabbc} to true. 906 Then, when \np{nn\_geoflx} is set to 1, a constant geothermal heating is introduced whose value is given by 907 the \np{nn\_geoflx\_cst}, which is also a namelist parameter. 908 When \np{nn\_geoflx} is set to 2, a spatially varying geothermal heat flux is introduced which is provided in 909 the \ifile{geothermal\_heating} NetCDF file (\autoref{fig:geothermal}) \citep{Emile-Geay_Madec_OS09}. 910 911 % ================================================================ 912 % Bottom Boundary Layer 913 % ================================================================ 914 \section{Bottom boundary layer (\protect\mdl{trabbl} - \protect\key{trabbl})} 922 (\ie\ the one associated with the Antarctic Bottom Water) by 923 a few Sverdrups \citep{emile-geay.madec_OS09}. 924 925 Options are defined through the \nam{bbc}{bbc} namelist variables. 926 The presence of geothermal heating is controlled by 927 setting the namelist parameter \np{ln_trabbc}{ln\_trabbc} to true. 928 Then, when \np{nn_geoflx}{nn\_geoflx} is set to 1, a constant geothermal heating is introduced whose 929 value is given by the \np{rn_geoflx_cst}{rn\_geoflx\_cst}, which is also a namelist parameter. 930 When \np{nn_geoflx}{nn\_geoflx} is set to 2, 931 a spatially varying geothermal heat flux is introduced which is provided in 932 the \ifile{geothermal\_heating} NetCDF file 933 (\autoref{fig:TRA_geothermal}) \citep{emile-geay.madec_OS09}. 934 935 %% ================================================================================================= 936 \section[Bottom boundary layer (\textit{trabbl.F90} - \forcode{ln_trabbl})]{Bottom boundary layer (\protect\mdl{trabbl} - \protect\np{ln_trabbl}{ln\_trabbl})} 915 937 \label{sec:TRA_bbl} 916 %--------------------------------------------nambbl--------------------------------------------------------- 917 918 \nlst{nambbl} 919 %-------------------------------------------------------------------------------------------------------------- 920 921 Options are defined through the \ngn{nambbl} namelist variables. 938 939 \begin{listing} 940 \nlst{nambbl} 941 \caption{\forcode{&nambbl}} 942 \label{lst:nambbl} 943 \end{listing} 944 945 Options are defined through the \nam{bbl}{bbl} namelist variables. 922 946 In a $z$-coordinate configuration, the bottom topography is represented by a series of discrete steps. 923 947 This is not adequate to represent gravity driven downslope flows. … … 925 949 where dense water formed in marginal seas flows into a basin filled with less dense water, 926 950 or along the continental slope when dense water masses are formed on a continental shelf. 927 The amount of entrainment that occurs in these gravity plumes is critical in determining the density and 928 volume flux of the densest waters of the ocean, such as Antarctic Bottom Water, or North Atlantic Deep Water. 951 The amount of entrainment that occurs in these gravity plumes is critical in 952 determining the density and volume flux of the densest waters of the ocean, 953 such as Antarctic Bottom Water, or North Atlantic Deep Water. 929 954 $z$-coordinate models tend to overestimate the entrainment, 930 because the gravity flow is mixed vertically by convection as it goes ''downstairs'' following the step topography, 955 because the gravity flow is mixed vertically by convection as 956 it goes ''downstairs'' following the step topography, 931 957 sometimes over a thickness much larger than the thickness of the observed gravity plume. 932 A similar problem occurs in the $s$-coordinate when the thickness of the bottom level varies rapidly downstream of 933 a sill \citep{Willebrand_al_PO01}, and the thickness of the plume is not resolved. 934 935 The idea of the bottom boundary layer (BBL) parameterisation, first introduced by \citet{Beckmann_Doscher1997}, 958 A similar problem occurs in the $s$-coordinate when 959 the thickness of the bottom level varies rapidly downstream of a sill 960 \citep{willebrand.barnier.ea_PO01}, and the thickness of the plume is not resolved. 961 962 The idea of the bottom boundary layer (BBL) parameterisation, first introduced by 963 \citet{beckmann.doscher_JPO97}, 936 964 is to allow a direct communication between two adjacent bottom cells at different levels, 937 965 whenever the densest water is located above the less dense water. 938 The communication can be by a diffusive flux (diffusive BBL), an advective flux (advective BBL), or both. 966 The communication can be by a diffusive flux (diffusive BBL), 967 an advective flux (advective BBL), or both. 939 968 In the current implementation of the BBL, only the tracers are modified, not the velocities. 940 Furthermore, it only connects ocean bottom cells, and therefore does not include all the improvements introduced by 941 \citet{Campin_Goosse_Tel99}. 942 943 % ------------------------------------------------------------------------------------------------------------- 944 % Diffusive BBL 945 % ------------------------------------------------------------------------------------------------------------- 946 \subsection{Diffusive bottom boundary layer (\protect\np{nn\_bbl\_ldf}~\forcode{= 1})} 969 Furthermore, it only connects ocean bottom cells, 970 and therefore does not include all the improvements introduced by \citet{campin.goosse_T99}. 971 972 %% ================================================================================================= 973 \subsection[Diffusive bottom boundary layer (\forcode{nn_bbl_ldf=1})]{Diffusive bottom boundary layer (\protect\np[=1]{nn_bbl_ldf}{nn\_bbl\_ldf})} 947 974 \label{subsec:TRA_bbl_diff} 948 975 949 When applying sigma-diffusion (\key{trabbl} defined and \np{nn\_bbl\_ldf} set to 1), 950 the diffusive flux between two adjacent cells at the ocean floor is given by 976 When applying sigma-diffusion 977 (\np[=.true.]{ln_trabbl}{ln\_trabbl} and \np{nn_bbl_ldf}{nn\_bbl\_ldf} set to 1), 978 the diffusive flux between two adjacent cells at the ocean floor is given by 951 979 \[ 952 % \label{eq: tra_bbl_diff}980 % \label{eq:TRA_bbl_diff} 953 981 \vect F_\sigma = A_l^\sigma \, \nabla_\sigma T 954 982 \] 955 with $\nabla_\sigma$ the lateral gradient operator taken between bottom cells, and956 $A_l^\sigma$ the lateral diffusivity in the BBL.957 Following \citet{ Beckmann_Doscher1997}, the latter is prescribed with a spatial dependence,958 \ie in the conditional form959 \begin{equation} 960 \label{eq: tra_bbl_coef}983 with $\nabla_\sigma$ the lateral gradient operator taken between bottom cells, 984 and $A_l^\sigma$ the lateral diffusivity in the BBL. 985 Following \citet{beckmann.doscher_JPO97}, the latter is prescribed with a spatial dependence, 986 \ie\ in the conditional form 987 \begin{equation} 988 \label{eq:TRA_bbl_coef} 961 989 A_l^\sigma (i,j,t) = 962 990 \begin{cases} 963 991 A_{bbl} & \text{if~} \nabla_\sigma \rho \cdot \nabla H < 0 \\ 964 \\ 965 0 & \text{otherwise} \\ 992 0 & \text{otherwise} 966 993 \end{cases} 967 994 \end{equation} 968 where $A_{bbl}$ is the BBL diffusivity coefficient, given by the namelist parameter \np{rn\_ahtbbl} and 995 where $A_{bbl}$ is the BBL diffusivity coefficient, 996 given by the namelist parameter \np{rn_ahtbbl}{rn\_ahtbbl} and 969 997 usually set to a value much larger than the one used for lateral mixing in the open ocean. 970 The constraint in \autoref{eq: tra_bbl_coef} implies that sigma-like diffusion only occurs when998 The constraint in \autoref{eq:TRA_bbl_coef} implies that sigma-like diffusion only occurs when 971 999 the density above the sea floor, at the top of the slope, is larger than in the deeper ocean 972 (see green arrow in \autoref{fig: bbl}).1000 (see green arrow in \autoref{fig:TRA_bbl}). 973 1001 In practice, this constraint is applied separately in the two horizontal directions, 974 and the density gradient in \autoref{eq: tra_bbl_coef} is evaluated with the log gradient formulation:1002 and the density gradient in \autoref{eq:TRA_bbl_coef} is evaluated with the log gradient formulation: 975 1003 \[ 976 % \label{eq: tra_bbl_Drho}1004 % \label{eq:TRA_bbl_Drho} 977 1005 \nabla_\sigma \rho / \rho = \alpha \, \nabla_\sigma T + \beta \, \nabla_\sigma S 978 1006 \] 979 where $\rho$, $\alpha$ and $\beta$ are functions of $\overline T^\sigma$, $\overline S^\sigma$ and 980 $\overline H^\sigma$, the along bottom mean temperature, salinity and depth, respectively. 981 982 % ------------------------------------------------------------------------------------------------------------- 983 % Advective BBL 984 % ------------------------------------------------------------------------------------------------------------- 985 \subsection{Advective bottom boundary layer (\protect\np{nn\_bbl\_adv}~\forcode{= 1..2})} 1007 where $\rho$, $\alpha$ and $\beta$ are functions of 1008 $\overline T^\sigma$, $\overline S^\sigma$ and $\overline H^\sigma$, 1009 the along bottom mean temperature, salinity and depth, respectively. 1010 1011 %% ================================================================================================= 1012 \subsection[Advective bottom boundary layer (\forcode{nn_bbl_adv=1,2})]{Advective bottom boundary layer (\protect\np[=1,2]{nn_bbl_adv}{nn\_bbl\_adv})} 986 1013 \label{subsec:TRA_bbl_adv} 987 1014 … … 991 1018 %} 992 1019 993 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 994 \begin{figure}[!t] 995 \begin{center} 996 \includegraphics[]{Fig_BBL_adv} 997 \caption{ 998 \protect\label{fig:bbl} 999 Advective/diffusive Bottom Boundary Layer. 1000 The BBL parameterisation is activated when $\rho^i_{kup}$ is larger than $\rho^{i + 1}_{kdnw}$. 1001 Red arrows indicate the additional overturning circulation due to the advective BBL. 1002 The transport of the downslope flow is defined either as the transport of the bottom ocean cell (black arrow), 1003 or as a function of the along slope density gradient. 1004 The green arrow indicates the diffusive BBL flux directly connecting $kup$ and $kdwn$ ocean bottom cells. 1005 } 1006 \end{center} 1020 \begin{figure} 1021 \centering 1022 \includegraphics[width=0.33\textwidth]{TRA_BBL_adv} 1023 \caption[Advective/diffusive bottom boundary layer]{ 1024 Advective/diffusive Bottom Boundary Layer. 1025 The BBL parameterisation is activated when $\rho^i_{kup}$ is larger than $\rho^{i + 1}_{kdnw}$. 1026 Red arrows indicate the additional overturning circulation due to the advective BBL. 1027 The transport of the downslope flow is defined either 1028 as the transport of the bottom ocean cell (black arrow), 1029 or as a function of the along slope density gradient. 1030 The green arrow indicates the diffusive BBL flux directly connecting 1031 $kup$ and $kdwn$ ocean bottom cells.} 1032 \label{fig:TRA_bbl} 1007 1033 \end{figure} 1008 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>1009 1034 1010 1035 %!! nn_bbl_adv = 1 use of the ocean velocity as bbl velocity … … 1012 1037 %!! i.e. transport proportional to the along-slope density gradient 1013 1038 1014 %%%gmcomment : this section has to be really written 1015 1016 When applying an advective BBL (\np{nn\_bbl\_adv}~\forcode{= 1..2}), an overturning circulation is added which 1017 connects two adjacent bottom grid-points only if dense water overlies less dense water on the slope. 1039 \cmtgm{This section has to be really written} 1040 1041 When applying an advective BBL (\np[=1..2]{nn_bbl_adv}{nn\_bbl\_adv}), 1042 an overturning circulation is added which connects two adjacent bottom grid-points only if 1043 dense water overlies less dense water on the slope. 1018 1044 The density difference causes dense water to move down the slope. 1019 1045 1020 \np{nn\_bbl\_adv}~\forcode{= 1}: 1021 the downslope velocity is chosen to be the Eulerian ocean velocity just above the topographic step 1022 (see black arrow in \autoref{fig:bbl}) \citep{Beckmann_Doscher1997}. 1023 It is a \textit{conditional advection}, that is, advection is allowed only 1024 if dense water overlies less dense water on the slope (\ie $\nabla_\sigma \rho \cdot \nabla H < 0$) and 1025 if the velocity is directed towards greater depth (\ie $\vect U \cdot \nabla H > 0$). 1026 1027 \np{nn\_bbl\_adv}~\forcode{= 2}: 1028 the downslope velocity is chosen to be proportional to $\Delta \rho$, 1029 the density difference between the higher cell and lower cell densities \citep{Campin_Goosse_Tel99}. 1030 The advection is allowed only if dense water overlies less dense water on the slope 1031 (\ie $\nabla_\sigma \rho \cdot \nabla H < 0$). 1032 For example, the resulting transport of the downslope flow, here in the $i$-direction (\autoref{fig:bbl}), 1033 is simply given by the following expression: 1034 \[ 1035 % \label{eq:bbl_Utr} 1036 u^{tr}_{bbl} = \gamma g \frac{\Delta \rho}{\rho_o} e_{1u} \, min ({e_{3u}}_{kup},{e_{3u}}_{kdwn}) 1037 \] 1038 where $\gamma$, expressed in seconds, is the coefficient of proportionality provided as \np{rn\_gambbl}, 1039 a namelist parameter, and \textit{kup} and \textit{kdwn} are the vertical index of the higher and lower cells, 1040 respectively. 1041 The parameter $\gamma$ should take a different value for each bathymetric step, but for simplicity, 1042 and because no direct estimation of this parameter is available, a uniform value has been assumed. 1043 The possible values for $\gamma$ range between 1 and $10~s$ \citep{Campin_Goosse_Tel99}. 1044 1045 Scalar properties are advected by this additional transport $(u^{tr}_{bbl},v^{tr}_{bbl})$ using the upwind scheme. 1046 Such a diffusive advective scheme has been chosen to mimic the entrainment between the downslope plume and 1047 the surrounding water at intermediate depths. 1046 \begin{description} 1047 \item [{\np[=1]{nn_bbl_adv}{nn\_bbl\_adv}}] the downslope velocity is chosen to 1048 be the Eulerian ocean velocity just above the topographic step 1049 (see black arrow in \autoref{fig:TRA_bbl}) \citep{beckmann.doscher_JPO97}. 1050 It is a \textit{conditional advection}, that is, 1051 advection is allowed only if dense water overlies less dense water on the slope 1052 (\ie\ $\nabla_\sigma \rho \cdot \nabla H < 0$) and if the velocity is directed towards greater depth 1053 (\ie\ $\vect U \cdot \nabla H > 0$). 1054 \item [{\np[=2]{nn_bbl_adv}{nn\_bbl\_adv}}] the downslope velocity is chosen to be proportional to 1055 $\Delta \rho$, the density difference between the higher cell and lower cell densities 1056 \citep{campin.goosse_T99}. 1057 The advection is allowed only if dense water overlies less dense water on the slope 1058 (\ie\ $\nabla_\sigma \rho \cdot \nabla H < 0$). 1059 For example, the resulting transport of the downslope flow, here in the $i$-direction 1060 (\autoref{fig:TRA_bbl}), is simply given by the following expression: 1061 \[ 1062 % \label{eq:TRA_bbl_Utr} 1063 u^{tr}_{bbl} = \gamma g \frac{\Delta \rho}{\rho_o} e_{1u} \, min ({e_{3u}}_{kup},{e_{3u}}_{kdwn}) 1064 \] 1065 where $\gamma$, expressed in seconds, is the coefficient of proportionality provided as 1066 \np{rn_gambbl}{rn\_gambbl}, a namelist parameter, and 1067 \textit{kup} and \textit{kdwn} are the vertical index of the higher and lower cells, respectively. 1068 The parameter $\gamma$ should take a different value for each bathymetric step, but for simplicity, 1069 and because no direct estimation of this parameter is available, a uniform value has been assumed. 1070 The possible values for $\gamma$ range between 1 and $10~s$ \citep{campin.goosse_T99}. 1071 \end{description} 1072 1073 Scalar properties are advected by this additional transport $(u^{tr}_{bbl},v^{tr}_{bbl})$ using 1074 the upwind scheme. 1075 Such a diffusive advective scheme has been chosen to mimic the entrainment between 1076 the downslope plume and the surrounding water at intermediate depths. 1048 1077 The entrainment is replaced by the vertical mixing implicit in the advection scheme. 1049 Let us consider as an example the case displayed in \autoref{fig: bbl} where1078 Let us consider as an example the case displayed in \autoref{fig:TRA_bbl} where 1050 1079 the density at level $(i,kup)$ is larger than the one at level $(i,kdwn)$. 1051 The advective BBL scheme modifies the tracer time tendency of the ocean cells near the topographic step by 1052 the downslope flow \autoref{eq:bbl_dw}, the horizontal \autoref{eq:bbl_hor} and 1053 the upward \autoref{eq:bbl_up} return flows as follows: 1054 \begin{alignat}{3} 1055 \label{eq:bbl_dw} 1056 \partial_t T^{do}_{kdw} &\equiv \partial_t T^{do}_{kdw} 1057 &&+ \frac{u^{tr}_{bbl}}{{b_t}^{do}_{kdw}} &&\lt( T^{sh}_{kup} - T^{do}_{kdw} \rt) \\ 1058 \label{eq:bbl_hor} 1059 \partial_t T^{sh}_{kup} &\equiv \partial_t T^{sh}_{kup} 1060 &&+ \frac{u^{tr}_{bbl}}{{b_t}^{sh}_{kup}} &&\lt( T^{do}_{kup} - T^{sh}_{kup} \rt) \\ 1061 % 1062 \intertext{and for $k =kdw-1,\;..., \; kup$ :} 1063 % 1064 \label{eq:bbl_up} 1065 \partial_t T^{do}_{k} &\equiv \partial_t S^{do}_{k} 1066 &&+ \frac{u^{tr}_{bbl}}{{b_t}^{do}_{k}} &&\lt( T^{do}_{k +1} - T^{sh}_{k} \rt) 1080 The advective BBL scheme modifies the tracer time tendency of 1081 the ocean cells near the topographic step by the downslope flow \autoref{eq:TRA_bbl_dw}, 1082 the horizontal \autoref{eq:TRA_bbl_hor} and the upward \autoref{eq:TRA_bbl_up} return flows as follows: 1083 \begin{alignat}{5} 1084 \label{eq:TRA_bbl_dw} 1085 \partial_t T^{do}_{kdw} &\equiv \partial_t T^{do}_{kdw} &&+ \frac{u^{tr}_{bbl}}{{b_t}^{do}_{kdw}} &&\lt( T^{sh}_{kup} - T^{do}_{kdw} \rt) \\ 1086 \label{eq:TRA_bbl_hor} 1087 \partial_t T^{sh}_{kup} &\equiv \partial_t T^{sh}_{kup} &&+ \frac{u^{tr}_{bbl}}{{b_t}^{sh}_{kup}} &&\lt( T^{do}_{kup} - T^{sh}_{kup} \rt) \\ 1088 \shortintertext{and for $k =kdw-1,\;..., \; kup$ :} 1089 \label{eq:TRA_bbl_up} 1090 \partial_t T^{do}_{k} &\equiv \partial_t S^{do}_{k} &&+ \frac{u^{tr}_{bbl}}{{b_t}^{do}_{k}} &&\lt( T^{do}_{k +1} - T^{sh}_{k} \rt) 1067 1091 \end{alignat} 1068 1092 where $b_t$ is the $T$-cell volume. … … 1071 1095 It has to be used to compute the effective velocity as well as the effective overturning circulation. 1072 1096 1073 % ================================================================ 1074 % Tracer damping 1075 % ================================================================ 1076 \section{Tracer damping (\protect\mdl{tradmp})} 1097 %% ================================================================================================= 1098 \section[Tracer damping (\textit{tradmp.F90})]{Tracer damping (\protect\mdl{tradmp})} 1077 1099 \label{sec:TRA_dmp} 1078 %--------------------------------------------namtra_dmp------------------------------------------------- 1079 1080 \nlst{namtra_dmp} 1081 %-------------------------------------------------------------------------------------------------------------- 1082 1083 In some applications it can be useful to add a Newtonian damping term into the temperature and salinity equations: 1084 \begin{equation} 1085 \label{eq:tra_dmp} 1086 \begin{gathered} 1087 \pd[T]{t} = \cdots - \gamma (T - T_o) \\ 1088 \pd[S]{t} = \cdots - \gamma (S - S_o) 1089 \end{gathered} 1090 \end{equation} 1091 where $\gamma$ is the inverse of a time scale, and $T_o$ and $S_o$ are given temperature and salinity fields 1092 (usually a climatology). 1093 Options are defined through the \ngn{namtra\_dmp} namelist variables. 1094 The restoring term is added when the namelist parameter \np{ln\_tradmp} is set to true. 1095 It also requires that both \np{ln\_tsd\_init} and \np{ln\_tsd\_tradmp} are set to true in 1096 \ngn{namtsd} namelist as well as \np{sn\_tem} and \np{sn\_sal} structures are correctly set 1097 (\ie that $T_o$ and $S_o$ are provided in input files and read using \mdl{fldread}, 1100 1101 \begin{listing} 1102 \nlst{namtra_dmp} 1103 \caption{\forcode{&namtra_dmp}} 1104 \label{lst:namtra_dmp} 1105 \end{listing} 1106 1107 In some applications it can be useful to add a Newtonian damping term into 1108 the temperature and salinity equations: 1109 \begin{equation} 1110 \label{eq:TRA_dmp} 1111 \pd[T]{t} = \cdots - \gamma (T - T_o) \qquad \pd[S]{t} = \cdots - \gamma (S - S_o) 1112 \end{equation} 1113 where $\gamma$ is the inverse of a time scale, 1114 and $T_o$ and $S_o$ are given temperature and salinity fields (usually a climatology). 1115 Options are defined through the \nam{tra_dmp}{tra\_dmp} namelist variables. 1116 The restoring term is added when the namelist parameter \np{ln_tradmp}{ln\_tradmp} is set to true. 1117 It also requires that both \np{ln_tsd_init}{ln\_tsd\_init} and 1118 \np{ln_tsd_dmp}{ln\_tsd\_dmp} are set to true in \nam{tsd}{tsd} namelist as well as 1119 \np{sn_tem}{sn\_tem} and \np{sn_sal}{sn\_sal} structures are correctly set 1120 (\ie\ that $T_o$ and $S_o$ are provided in input files and read using \mdl{fldread}, 1098 1121 see \autoref{subsec:SBC_fldread}). 1099 The restoring coefficient $\gamma$ is a three-dimensional array read in during the \rou{tra\_dmp\_init} routine. 1100 The file name is specified by the namelist variable \np{cn\_resto}. 1101 The DMP\_TOOLS tool is provided to allow users to generate the netcdf file. 1102 1103 The two main cases in which \autoref{eq:tra_dmp} is used are 1104 \textit{(a)} the specification of the boundary conditions along artificial walls of a limited domain basin and 1105 \textit{(b)} the computation of the velocity field associated with a given $T$-$S$ field 1106 (for example to build the initial state of a prognostic simulation, 1107 or to use the resulting velocity field for a passive tracer study). 1122 The restoring coefficient $\gamma$ is a three-dimensional array read in during 1123 the \rou{tra\_dmp\_init} routine. 1124 The file name is specified by the namelist variable \np{cn_resto}{cn\_resto}. 1125 The \texttt{DMP\_TOOLS} are provided to allow users to generate the netcdf file. 1126 1127 The two main cases in which \autoref{eq:TRA_dmp} is used are 1128 \begin{enumerate*}[label=(\textit{\alph*})] 1129 \item the specification of the boundary conditions along 1130 artificial walls of a limited domain basin and 1131 \item the computation of the velocity field associated with a given $T$-$S$ field 1132 (for example to build the initial state of a prognostic simulation, 1133 or to use the resulting velocity field for a passive tracer study). 1134 \end{enumerate*} 1108 1135 The first case applies to regional models that have artificial walls instead of open boundaries. 1109 In the vicinity of these walls, $\gamma$ takes large values (equivalent to a time scale of a few days) whereas1110 it is zero in the interior of the model domain.1111 The second case corresponds to the use of the robust diagnostic method \citep{ Sarmiento1982}.1136 In the vicinity of these walls, $\gamma$ takes large values (equivalent to a time scale of a few days) 1137 whereas it is zero in the interior of the model domain. 1138 The second case corresponds to the use of the robust diagnostic method \citep{sarmiento.bryan_JGR82}. 1112 1139 It allows us to find the velocity field consistent with the model dynamics whilst 1113 1140 having a $T$, $S$ field close to a given climatological field ($T_o$, $S_o$). 1114 1141 1115 The robust diagnostic method is very efficient in preventing temperature drift in intermediate waters but1116 i t produces artificial sources of heat and salt within the ocean.1142 The robust diagnostic method is very efficient in preventing temperature drift in 1143 intermediate waters but it produces artificial sources of heat and salt within the ocean. 1117 1144 It also has undesirable effects on the ocean convection. 1118 It tends to prevent deep convection and subsequent deep-water formation, by stabilising the water column too much. 1119 1120 The namelist parameter \np{nn\_zdmp} sets whether the damping should be applied in the whole water column or 1121 only below the mixed layer (defined either on a density or $S_o$ criterion). 1145 It tends to prevent deep convection and subsequent deep-water formation, 1146 by stabilising the water column too much. 1147 1148 The namelist parameter \np{nn_zdmp}{nn\_zdmp} sets whether the damping should be applied in 1149 the whole water column or only below the mixed layer (defined either on a density or $S_o$ criterion). 1122 1150 It is common to set the damping to zero in the mixed layer as the adjustment time scale is short here 1123 \citep{Madec_al_JPO96}. 1124 1125 For generating \ifile{resto}, see the documentation for the DMP tool provided with the source code under 1126 \path{./tools/DMP_TOOLS}. 1127 1128 % ================================================================ 1129 % Tracer time evolution 1130 % ================================================================ 1131 \section{Tracer time evolution (\protect\mdl{tranxt})} 1151 \citep{madec.delecluse.ea_JPO96}. 1152 1153 For generating \ifile{resto}, 1154 see the documentation for the DMP tools provided with the source code under \path{./tools/DMP_TOOLS}. 1155 1156 %% ================================================================================================= 1157 \section[Tracer time evolution (\textit{tranxt.F90})]{Tracer time evolution (\protect\mdl{tranxt})} 1132 1158 \label{sec:TRA_nxt} 1133 %--------------------------------------------namdom----------------------------------------------------- 1134 1135 \nlst{namdom} 1136 %-------------------------------------------------------------------------------------------------------------- 1137 1138 Options are defined through the \ngn{namdom} namelist variables. 1139 The general framework for tracer time stepping is a modified leap-frog scheme \citep{Leclair_Madec_OM09}, 1140 \ie a three level centred time scheme associated with a Asselin time filter (cf. \autoref{sec:STP_mLF}): 1141 \begin{equation} 1142 \label{eq:tra_nxt} 1143 \begin{alignedat}{3} 1159 1160 Options are defined through the \nam{dom}{dom} namelist variables. 1161 The general framework for tracer time stepping is a modified leap-frog scheme 1162 \citep{leclair.madec_OM09}, \ie\ a three level centred time scheme associated with 1163 a Asselin time filter (cf. \autoref{sec:TD_mLF}): 1164 \begin{equation} 1165 \label{eq:TRA_nxt} 1166 \begin{alignedat}{5} 1144 1167 &(e_{3t}T)^{t + \rdt} &&= (e_{3t}T)_f^{t - \rdt} &&+ 2 \, \rdt \,e_{3t}^t \ \text{RHS}^t \\ 1145 1168 &(e_{3t}T)_f^t &&= (e_{3t}T)^t &&+ \, \gamma \, \lt[ (e_{3t}T)_f^{t - \rdt} - 2(e_{3t}T)^t + (e_{3t}T)^{t + \rdt} \rt] \\ 1146 & && &&- \, \gamma \, \rdt \, \lt[ Q^{t + \rdt/2} - Q^{t - \rdt/2} \rt] 1169 & && &&- \, \gamma \, \rdt \, \lt[ Q^{t + \rdt/2} - Q^{t - \rdt/2} \rt] 1147 1170 \end{alignedat} 1148 \end{equation} 1149 where RHS is the right hand side of the temperature equation, the subscript $f$ denotes filtered values, 1150 $\gamma$ is the Asselin coefficient, and $S$ is the total forcing applied on $T$ 1151 (\ie fluxes plus content in mass exchanges). 1152 $\gamma$ is initialized as \np{rn\_atfp} (\textbf{namelist} parameter). 1153 Its default value is \np{rn\_atfp}~\forcode{= 10.e-3}. 1171 \end{equation} 1172 where RHS is the right hand side of the temperature equation, 1173 the subscript $f$ denotes filtered values, $\gamma$ is the Asselin coefficient, 1174 and $S$ is the total forcing applied on $T$ (\ie\ fluxes plus content in mass exchanges). 1175 $\gamma$ is initialized as \np{rn_atfp}{rn\_atfp}, its default value is \forcode{10.e-3}. 1154 1176 Note that the forcing correction term in the filter is not applied in linear free surface 1155 (\jp{lk\_vvl}~\forcode{= .false.}) (see \autoref{subsec:TRA_sbc}). 1156 Not also that in constant volume case, the time stepping is performed on $T$, not on its content, $e_{3t}T$. 1157 1158 When the vertical mixing is solved implicitly, the update of the \textit{next} tracer fields is done in 1159 \mdl{trazdf} module. 1177 (\jp{ln\_linssh}\forcode{=.true.}) (see \autoref{subsec:TRA_sbc}). 1178 Not also that in constant volume case, the time stepping is performed on $T$, 1179 not on its content, $e_{3t}T$. 1180 1181 When the vertical mixing is solved implicitly, 1182 the update of the \textit{next} tracer fields is done in \mdl{trazdf} module. 1160 1183 In this case only the swapping of arrays and the Asselin filtering is done in the \mdl{tranxt} module. 1161 1184 1162 In order to prepare for the computation of the \textit{next} time step, a swap of tracer arrays is performed: 1163 $T^{t - \rdt} = T^t$ and $T^t = T_f$. 1164 1165 % ================================================================ 1166 % Equation of State (eosbn2) 1167 % ================================================================ 1168 \section{Equation of state (\protect\mdl{eosbn2}) } 1185 In order to prepare for the computation of the \textit{next} time step, 1186 a swap of tracer arrays is performed: $T^{t - \rdt} = T^t$ and $T^t = T_f$. 1187 1188 %% ================================================================================================= 1189 \section[Equation of state (\textit{eosbn2.F90})]{Equation of state (\protect\mdl{eosbn2})} 1169 1190 \label{sec:TRA_eosbn2} 1170 %--------------------------------------------nameos----------------------------------------------------- 1171 1172 \nlst{nameos}1173 %-------------------------------------------------------------------------------------------------------------- 1174 1175 % ------------------------------------------------------------------------------------------------------------- 1176 % Equation of State 1177 % -------------------------------------------------------------------------------------------------------------1178 \subsection {Equation of seawater (\protect\np{nn\_eos}~\forcode{= -1..1})}1191 1192 \begin{listing} 1193 \nlst{nameos} 1194 \caption{\forcode{&nameos}} 1195 \label{lst:nameos} 1196 \end{listing} 1197 1198 %% ================================================================================================= 1199 \subsection[Equation of seawater (\forcode{ln_}\{\forcode{teos10,eos80,seos}\})]{Equation of seawater (\protect\np{ln_teos10}{ln\_teos10}, \protect\np{ln_teos80}{ln\_teos80}, or \protect\np{ln_seos}{ln\_seos})} 1179 1200 \label{subsec:TRA_eos} 1180 1201 1181 The Equation Of Seawater (EOS) is an empirical nonlinear thermodynamic relationship linking seawater density, 1182 $\rho$, to a number of state variables, most typically temperature, salinity and pressure. 1202 The \textbf{E}quation \textbf{O}f \textbf{S}eawater (EOS) is 1203 an empirical nonlinear thermodynamic relationship linking 1204 seawater density, $\rho$, to a number of state variables, 1205 most typically temperature, salinity and pressure. 1183 1206 Because density gradients control the pressure gradient force through the hydrostatic balance, 1184 the equation of state provides a fundamental bridge between the distribution of active tracers and1185 the fluid dynamics.1207 the equation of state provides a fundamental bridge between 1208 the distribution of active tracers and the fluid dynamics. 1186 1209 Nonlinearities of the EOS are of major importance, in particular influencing the circulation through 1187 1210 determination of the static stability below the mixed layer, 1188 thus controlling rates of exchange between the atmosphere and the ocean interior \citep{Roquet_JPO2015}. 1189 Therefore an accurate EOS based on either the 1980 equation of state (EOS-80, \cite{UNESCO1983}) or 1190 TEOS-10 \citep{TEOS10} standards should be used anytime a simulation of the real ocean circulation is attempted 1191 \citep{Roquet_JPO2015}. 1211 thus controlling rates of exchange between the atmosphere and the ocean interior 1212 \citep{roquet.madec.ea_JPO15}. 1213 Therefore an accurate EOS based on either the 1980 equation of state 1214 (EOS-80, \cite{fofonoff.millard_bk83}) or TEOS-10 \citep{ioc.iapso_bk10} standards should 1215 be used anytime a simulation of the real ocean circulation is attempted \citep{roquet.madec.ea_JPO15}. 1192 1216 The use of TEOS-10 is highly recommended because 1193 \textit{(i)} it is the new official EOS, 1194 \textit{(ii)} it is more accurate, being based on an updated database of laboratory measurements, and 1195 \textit{(iii)} it uses Conservative Temperature and Absolute Salinity (instead of potential temperature and 1196 practical salinity for EOS-980, both variables being more suitable for use as model variables 1197 \citep{TEOS10, Graham_McDougall_JPO13}. 1198 EOS-80 is an obsolescent feature of the NEMO system, kept only for backward compatibility. 1217 \begin{enumerate*}[label=(\textit{\roman*})] 1218 \item it is the new official EOS, 1219 \item it is more accurate, being based on an updated database of laboratory measurements, and 1220 \item it uses Conservative Temperature and Absolute Salinity 1221 (instead of potential temperature and practical salinity for EOS-80), 1222 both variables being more suitable for use as model variables 1223 \citep{ioc.iapso_bk10, graham.mcdougall_JPO13}. 1224 \end{enumerate*} 1225 EOS-80 is an obsolescent feature of the \NEMO\ system, kept only for backward compatibility. 1199 1226 For process studies, it is often convenient to use an approximation of the EOS. 1200 To that purposed, a simplified EOS (S-EOS) inspired by \citet{Vallis06} is also available. 1201 1202 In the computer code, a density anomaly, $d_a = \rho / \rho_o - 1$, is computed, with $\rho_o$ a reference density. 1203 Called \textit{rau0} in the code, $\rho_o$ is set in \mdl{phycst} to a value of $1,026~Kg/m^3$. 1204 This is a sensible choice for the reference density used in a Boussinesq ocean climate model, as, 1205 with the exception of only a small percentage of the ocean, 1206 density in the World Ocean varies by no more than 2$\%$ from that value \citep{Gill1982}. 1207 1208 Options are defined through the \ngn{nameos} namelist variables, and in particular \np{nn\_eos} which 1209 controls the EOS used (\forcode{= -1} for TEOS10 ; \forcode{= 0} for EOS-80 ; \forcode{= 1} for S-EOS). 1227 To that purposed, a simplified EOS (S-EOS) inspired by \citet{vallis_bk06} is also available. 1228 1229 In the computer code, a density anomaly, $d_a = \rho / \rho_o - 1$, is computed, 1230 with $\rho_o$ a reference density. 1231 Called \textit{rau0} in the code, 1232 $\rho_o$ is set in \mdl{phycst} to a value of \texttt{1,026} $Kg/m^3$. 1233 This is a sensible choice for the reference density used in a Boussinesq ocean climate model, 1234 as, with the exception of only a small percentage of the ocean, 1235 density in the World Ocean varies by no more than 2\% from that value \citep{gill_bk82}. 1236 1237 Options which control the EOS used are defined through the \nam{eos}{eos} namelist variables. 1210 1238 1211 1239 \begin{description} 1212 \item [\np{nn\_eos}~\forcode{= -1}]1213 the polyTEOS10-bsq equation of seawater \citep{Roquet_OM2015} is used.1240 \item [{\np[=.true.]{ln_teos10}{ln\_teos10}}] the polyTEOS10-bsq equation of seawater 1241 \citep{roquet.madec.ea_OM15} is used. 1214 1242 The accuracy of this approximation is comparable to the TEOS-10 rational function approximation, 1215 but it is optimized for a boussinesq fluid and the polynomial expressions have simpler and 1216 more computationally efficient expressions for their derived quantities which make them more adapted for 1217 use in ocean models. 1218 Note that a slightly higher precision polynomial form is now used replacement of 1219 the TEOS-10 rational function approximation for hydrographic data analysis \citep{TEOS10}. 1243 but it is optimized for a Boussinesq fluid and 1244 the polynomial expressions have simpler and more computationally efficient expressions for 1245 their derived quantities which make them more adapted for use in ocean models. 1246 Note that a slightly higher precision polynomial form is now used 1247 replacement of the TEOS-10 rational function approximation for hydrographic data analysis 1248 \citep{ioc.iapso_bk10}. 1220 1249 A key point is that conservative state variables are used: 1221 Absolute Salinity (unit: g/kg, notation: $S_A$) and Conservative Temperature (unit: \deg{C}, notation: $\Theta$). 1250 Absolute Salinity (unit: $g/kg$, notation: $S_A$) and 1251 Conservative Temperature (unit: $\deg{C}$, notation: $\Theta$). 1222 1252 The pressure in decibars is approximated by the depth in meters. 1223 1253 With TEOS10, the specific heat capacity of sea water, $C_p$, is a constant. 1224 It is set to $C_p = 3991.86795711963~J\,Kg^{-1}\,^{\circ}K^{-1}$, according to \citet{TEOS10}. 1254 It is set to $C_p$ = 3991.86795711963 $J.Kg^{-1}.\deg{K}^{-1}$, 1255 according to \citet{ioc.iapso_bk10}. 1225 1256 Choosing polyTEOS10-bsq implies that the state variables used by the model are $\Theta$ and $S_A$. 1226 In particular, the initial state de ined by the user have to be given as \textit{Conservative} Temperature and1227 \textit{ Absolute} Salinity.1228 In addition, setting \np{ln\_useCT} to \forcode{.true.} convert the Conservative SSTto potential SST prior to1257 In particular, the initial state defined by the user have to be given as 1258 \textit{Conservative} Temperature and \textit{Absolute} Salinity. 1259 In addition, when using TEOS10, the Conservative SST is converted to potential SST prior to 1229 1260 either computing the air-sea and ice-sea fluxes (forced mode) or 1230 1261 sending the SST field to the atmosphere (coupled mode). 1231 \item[\np{nn\_eos}~\forcode{= 0}] 1232 the polyEOS80-bsq equation of seawater is used. 1233 It takes the same polynomial form as the polyTEOS10, but the coefficients have been optimized to 1234 accurately fit EOS80 (Roquet, personal comm.). 1262 \item [{\np[=.true.]{ln_eos80}{ln\_eos80}}] the polyEOS80-bsq equation of seawater is used. 1263 It takes the same polynomial form as the polyTEOS10, 1264 but the coefficients have been optimized to accurately fit EOS80 (Roquet, personal comm.). 1235 1265 The state variables used in both the EOS80 and the ocean model are: 1236 the Practical Salinity ( (unit: psu, notation: $S_p$)) and1237 Potential Temperature (unit: $ ^{\circ}C$, notation: $\theta$).1266 the Practical Salinity (unit: $psu$, notation: $S_p$) and 1267 Potential Temperature (unit: $\deg{C}$, notation: $\theta$). 1238 1268 The pressure in decibars is approximated by the depth in meters. 1239 With thsi EOS, the specific heat capacity of sea water, $C_p$, is a function of temperature, salinity and1240 pressure \citep{UNESCO1983}.1269 With EOS, the specific heat capacity of sea water, $C_p$, is a function of 1270 temperature, salinity and pressure \citep{fofonoff.millard_bk83}. 1241 1271 Nevertheless, a severe assumption is made in order to have a heat content ($C_p T_p$) which 1242 1272 is conserved by the model: $C_p$ is set to a constant value, the TEOS10 value. 1243 \item [\np{nn\_eos}~\forcode{= 1}]1244 a simplified EOS (S-EOS) inspired by \citet{Vallis06} is chosen,1245 the coefficients of which has been optimized to fit the behavior of TEOS10 1246 ( Roquet, personal comm.) (see also \citet{Roquet_JPO2015}).1273 \item [{\np[=.true.]{ln_seos}{ln\_seos}}] a simplified EOS (S-EOS) inspired by 1274 \citet{vallis_bk06} is chosen, 1275 the coefficients of which has been optimized to fit the behavior of TEOS10 (Roquet, personal comm.) 1276 (see also \citet{roquet.madec.ea_JPO15}). 1247 1277 It provides a simplistic linear representation of both cabbeling and thermobaricity effects which 1248 is enough for a proper treatment of the EOS in theoretical studies \citep{ Roquet_JPO2015}.1249 With such an equation of state there is no longer a distinction between 1250 \textit{ conservative} and \textit{potential} temperature,1251 as well as between \textit{absolute} and\textit{practical} salinity.1278 is enough for a proper treatment of the EOS in theoretical studies \citep{roquet.madec.ea_JPO15}. 1279 With such an equation of state there is no longer a distinction between \textit{conservative} and 1280 \textit{potential} temperature, as well as between \textit{absolute} and 1281 \textit{practical} salinity. 1252 1282 S-EOS takes the following expression: 1253 1283 \begin{gather*} 1254 % \label{eq:tra_S-EOS} 1255 \begin{alignedat}{2} 1256 &d_a(T,S,z) = \frac{1}{\rho_o} \big[ &- a_0 \; ( 1 + 0.5 \; \lambda_1 \; T_a + \mu_1 \; z ) * &T_a \big. \\ 1257 & &+ b_0 \; ( 1 - 0.5 \; \lambda_2 \; S_a - \mu_2 \; z ) * &S_a \\ 1258 & \big. &- \nu \; T_a &S_a \big] \\ 1259 \end{alignedat} 1260 \\ 1284 % \label{eq:TRA_S-EOS} 1285 d_a(T,S,z) = \frac{1}{\rho_o} \big[ - a_0 \; ( 1 + 0.5 \; \lambda_1 \; T_a + \mu_1 \; z ) * T_a \big. 1286 + b_0 \; ( 1 - 0.5 \; \lambda_2 \; S_a - \mu_2 \; z ) * S_a 1287 \big. - \nu \; T_a S_a \big] \\ 1261 1288 \text{with~} T_a = T - 10 \, ; \, S_a = S - 35 \, ; \, \rho_o = 1026~Kg/m^3 1262 1289 \end{gather*} 1263 where the computer name of the coefficients as well as their standard value are given in \autoref{tab:SEOS}. 1290 where the computer name of the coefficients as well as their standard value are given in 1291 \autoref{tab:TRA_SEOS}. 1264 1292 In fact, when choosing S-EOS, various approximation of EOS can be specified simply by 1265 1293 changing the associated coefficients. 1266 Setting to zero the two thermobaric coefficients $(\mu_1,\mu_2)$ remove thermobaric effect from S-EOS. 1267 setting to zero the three cabbeling coefficients $(\lambda_1,\lambda_2,\nu)$ remove cabbeling effect from 1268 S-EOS. 1294 Setting to zero the two thermobaric coefficients $(\mu_1,\mu_2)$ 1295 remove thermobaric effect from S-EOS. 1296 Setting to zero the three cabbeling coefficients $(\lambda_1,\lambda_2,\nu)$ 1297 remove cabbeling effect from S-EOS. 1269 1298 Keeping non-zero value to $a_0$ and $b_0$ provide a linear EOS function of T and S. 1270 1299 \end{description} 1271 1300 1272 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1273 \begin{table}[!tb] 1274 \begin{center} 1275 \begin{tabular}{|l|l|l|l|} 1276 \hline 1277 coeff. & computer name & S-EOS & description \\ 1278 \hline 1279 $a_0$ & \np{rn\_a0} & $1.6550~10^{-1}$ & linear thermal expansion coeff. \\ 1280 \hline 1281 $b_0$ & \np{rn\_b0} & $7.6554~10^{-1}$ & linear haline expansion coeff. \\ 1282 \hline 1283 $\lambda_1$ & \np{rn\_lambda1}& $5.9520~10^{-2}$ & cabbeling coeff. in $T^2$ \\ 1284 \hline 1285 $\lambda_2$ & \np{rn\_lambda2}& $5.4914~10^{-4}$ & cabbeling coeff. in $S^2$ \\ 1286 \hline 1287 $\nu$ & \np{rn\_nu} & $2.4341~10^{-3}$ & cabbeling coeff. in $T \, S$ \\ 1288 \hline 1289 $\mu_1$ & \np{rn\_mu1} & $1.4970~10^{-4}$ & thermobaric coeff. in T \\ 1290 \hline 1291 $\mu_2$ & \np{rn\_mu2} & $1.1090~10^{-5}$ & thermobaric coeff. in S \\ 1292 \hline 1293 \end{tabular} 1294 \caption{ 1295 \protect\label{tab:SEOS} 1296 Standard value of S-EOS coefficients. 1297 } 1298 \end{center} 1301 \begin{table} 1302 \centering 1303 \begin{tabular}{|l|l|l|l|} 1304 \hline 1305 coeff. & computer name & S-EOS & description \\ 1306 \hline 1307 $a_0 $ & \np{rn_a0}{rn\_a0} & $1.6550~10^{-1}$ & linear thermal expansion coeff. \\ 1308 \hline 1309 $b_0 $ & \np{rn_b0}{rn\_b0} & $7.6554~10^{-1}$ & linear haline expansion coeff. \\ 1310 \hline 1311 $\lambda_1$ & \np{rn_lambda1}{rn\_lambda1} & $5.9520~10^{-2}$ & cabbeling coeff. in $T^2$ \\ 1312 \hline 1313 $\lambda_2$ & \np{rn_lambda2}{rn\_lambda2} & $5.4914~10^{-4}$ & cabbeling coeff. in $S^2$ \\ 1314 \hline 1315 $\nu $ & \np{rn_nu}{rn\_nu} & $2.4341~10^{-3}$ & cabbeling coeff. in $T \, S$ \\ 1316 \hline 1317 $\mu_1 $ & \np{rn_mu1}{rn\_mu1} & $1.4970~10^{-4}$ & thermobaric coeff. in T \\ 1318 \hline 1319 $\mu_2 $ & \np{rn_mu2}{rn\_mu2} & $1.1090~10^{-5}$ & thermobaric coeff. in S \\ 1320 \hline 1321 \end{tabular} 1322 \caption{Standard value of S-EOS coefficients} 1323 \label{tab:TRA_SEOS} 1299 1324 \end{table} 1300 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1301 1302 % ------------------------------------------------------------------------------------------------------------- 1303 % Brunt-V\"{a}is\"{a}l\"{a} Frequency 1304 % ------------------------------------------------------------------------------------------------------------- 1305 \subsection{Brunt-V\"{a}is\"{a}l\"{a} frequency (\protect\np{nn\_eos}~\forcode{= 0..2})} 1325 1326 %% ================================================================================================= 1327 \subsection[Brunt-V\"{a}is\"{a}l\"{a} frequency]{Brunt-V\"{a}is\"{a}l\"{a} frequency} 1306 1328 \label{subsec:TRA_bn2} 1307 1329 1308 An accurate computation of the ocean stability (i.e. of $N$, the brunt-V\"{a}is\"{a}l\"{a} frequency) is of1309 paramount importance as determine the ocean stratification andis used in several ocean parameterisations1330 An accurate computation of the ocean stability (i.e. of $N$, the Brunt-V\"{a}is\"{a}l\"{a} frequency) is of paramount importance as determine the ocean stratification and 1331 is used in several ocean parameterisations 1310 1332 (namely TKE, GLS, Richardson number dependent vertical diffusion, enhanced vertical diffusion, 1311 1333 non-penetrative convection, tidal mixing parameterisation, iso-neutral diffusion). 1312 1334 In particular, $N^2$ has to be computed at the local pressure 1313 1335 (pressure in decibar being approximated by the depth in meters). 1314 The expression for $N^2$ is given by: 1336 The expression for $N^2$ is given by: 1315 1337 \[ 1316 % \label{eq: tra_bn2}1338 % \label{eq:TRA_bn2} 1317 1339 N^2 = \frac{g}{e_{3w}} \lt( \beta \; \delta_{k + 1/2}[S] - \alpha \; \delta_{k + 1/2}[T] \rt) 1318 1340 \] 1319 1341 where $(T,S) = (\Theta,S_A)$ for TEOS10, $(\theta,S_p)$ for TEOS-80, or $(T,S)$ for S-EOS, and, 1320 1342 $\alpha$ and $\beta$ are the thermal and haline expansion coefficients. 1321 The coefficients are a polynomial function of temperature, salinity and depth which expression depends on 1322 the chosen EOS. 1323 They are computed through \textit{eos\_rab}, a \fortran function that can be found in \mdl{eosbn2}. 1324 1325 % ------------------------------------------------------------------------------------------------------------- 1326 % Freezing Point of Seawater 1327 % ------------------------------------------------------------------------------------------------------------- 1343 The coefficients are a polynomial function of temperature, salinity and depth which 1344 expression depends on the chosen EOS. 1345 They are computed through \textit{eos\_rab}, a \fortran\ function that can be found in \mdl{eosbn2}. 1346 1347 %% ================================================================================================= 1328 1348 \subsection{Freezing point of seawater} 1329 1349 \label{subsec:TRA_fzp} 1330 1350 1331 The freezing point of seawater is a function of salinity and pressure \citep{UNESCO1983}: 1332 \begin{equation} 1333 \label{eq:tra_eos_fzp} 1334 \begin{split} 1335 &T_f (S,p) = \lt( a + b \, \sqrt{S} + c \, S \rt) \, S + d \, p \\ 1336 &\text{where~} a = -0.0575, \, b = 1.710523~10^{-3}, \, c = -2.154996~10^{-4} \\ 1337 &\text{and~} d = -7.53~10^{-3} 1338 \end{split} 1339 \end{equation} 1340 1341 \autoref{eq:tra_eos_fzp} is only used to compute the potential freezing point of sea water 1342 (\ie referenced to the surface $p = 0$), 1343 thus the pressure dependent terms in \autoref{eq:tra_eos_fzp} (last term) have been dropped. 1351 The freezing point of seawater is a function of salinity and pressure \citep{fofonoff.millard_bk83}: 1352 \begin{equation} 1353 \label{eq:TRA_eos_fzp} 1354 \begin{gathered} 1355 T_f (S,p) = \lt( a + b \, \sqrt{S} + c \, S \rt) \, S + d \, p \\ 1356 \text{where~} a = -0.0575, \, b = 1.710523~10^{-3}, \, c = -2.154996~10^{-4} \text{and~} d = -7.53~10^{-3} 1357 \end{gathered} 1358 \end{equation} 1359 1360 \autoref{eq:TRA_eos_fzp} is only used to compute the potential freezing point of sea water 1361 (\ie\ referenced to the surface $p = 0$), 1362 thus the pressure dependent terms in \autoref{eq:TRA_eos_fzp} (last term) have been dropped. 1344 1363 The freezing point is computed through \textit{eos\_fzp}, 1345 a \fortran function that can be found in \mdl{eosbn2}. 1346 1347 % ------------------------------------------------------------------------------------------------------------- 1348 % Potential Energy 1349 % ------------------------------------------------------------------------------------------------------------- 1364 a \fortran\ function that can be found in \mdl{eosbn2}. 1365 1366 %% ================================================================================================= 1350 1367 %\subsection{Potential Energy anomalies} 1351 1368 %\label{subsec:TRA_bn2} 1352 1369 1353 1370 % =====>>>>> TO BE written 1354 % 1355 1356 % ================================================================ 1357 % Horizontal Derivative in zps-coordinate 1358 % ================================================================ 1359 \section{Horizontal derivative in \textit{zps}-coordinate (\protect\mdl{zpshde})} 1371 1372 %% ================================================================================================= 1373 \section[Horizontal derivative in \textit{zps}-coordinate (\textit{zpshde.F90})]{Horizontal derivative in \textit{zps}-coordinate (\protect\mdl{zpshde})} 1360 1374 \label{sec:TRA_zpshde} 1361 1375 1362 \ gmcomment{STEVEN: to be consistent with earlier discussion of differencing and averaging operators,1376 \cmtgm{STEVEN: to be consistent with earlier discussion of differencing and averaging operators, 1363 1377 I've changed "derivative" to "difference" and "mean" to "average"} 1364 1378 1365 With partial cells (\np{ln\_zps}~\forcode{= .true.}) at bottom and top (\np{ln\_isfcav}~\forcode{= .true.}), 1379 With partial cells (\np[=.true.]{ln_zps}{ln\_zps}) at bottom and top 1380 (\np[=.true.]{ln_isfcav}{ln\_isfcav}), 1366 1381 in general, tracers in horizontally adjacent cells live at different depths. 1367 Horizontal gradients of tracers are needed for horizontal diffusion (\mdl{traldf} module) and1368 the hydrostatic pressure gradient calculations (\mdl{dynhpg} module).1369 The partial cell properties at the top (\np {ln\_isfcav}~\forcode{= .true.}) are computed in the same way as1370 for the bottom.1382 Horizontal gradients of tracers are needed for horizontal diffusion 1383 (\mdl{traldf} module) and the hydrostatic pressure gradient calculations (\mdl{dynhpg} module). 1384 The partial cell properties at the top (\np[=.true.]{ln_isfcav}{ln\_isfcav}) are computed in 1385 the same way as for the bottom. 1371 1386 So, only the bottom interpolation is explained below. 1372 1387 1373 1388 Before taking horizontal gradients between the tracers next to the bottom, 1374 1389 a linear interpolation in the vertical is used to approximate the deeper tracer as if 1375 it actually lived at the depth of the shallower tracer point (\autoref{fig:Partial_step_scheme}). 1376 For example, for temperature in the $i$-direction the needed interpolated temperature, $\widetilde T$, is: 1377 1378 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1379 \begin{figure}[!p] 1380 \begin{center} 1381 \includegraphics[]{Fig_partial_step_scheme} 1382 \caption{ 1383 \protect\label{fig:Partial_step_scheme} 1384 Discretisation of the horizontal difference and average of tracers in the $z$-partial step coordinate 1385 (\protect\np{ln\_zps}~\forcode{= .true.}) in the case $(e3w_k^{i + 1} - e3w_k^i) > 0$. 1386 A linear interpolation is used to estimate $\widetilde T_k^{i + 1}$, 1387 the tracer value at the depth of the shallower tracer point of the two adjacent bottom $T$-points. 1388 The horizontal difference is then given by: $\delta_{i + 1/2} T_k = \widetilde T_k^{\, i + 1} -T_k^{\, i}$ and 1389 the average by: $\overline T_k^{\, i + 1/2} = (\widetilde T_k^{\, i + 1/2} - T_k^{\, i}) / 2$. 1390 } 1391 \end{center} 1390 it actually lived at the depth of the shallower tracer point (\autoref{fig:TRA_Partial_step_scheme}). 1391 For example, for temperature in the $i$-direction the needed interpolated temperature, 1392 $\widetilde T$, is: 1393 1394 \begin{figure} 1395 \centering 1396 \includegraphics[width=0.33\textwidth]{TRA_partial_step_scheme} 1397 \caption[Discretisation of the horizontal difference and average of tracers in 1398 the $z$-partial step coordinate]{ 1399 Discretisation of the horizontal difference and average of tracers in 1400 the $z$-partial step coordinate (\protect\np[=.true.]{ln_zps}{ln\_zps}) in 1401 the case $(e3w_k^{i + 1} - e3w_k^i) > 0$. 1402 A linear interpolation is used to estimate $\widetilde T_k^{i + 1}$, 1403 the tracer value at the depth of the shallower tracer point of the two adjacent bottom $T$-points. 1404 The horizontal difference is then given by: 1405 $\delta_{i + 1/2} T_k = \widetilde T_k^{\, i + 1} -T_k^{\, i}$ and the average by: 1406 $\overline T_k^{\, i + 1/2} = (\widetilde T_k^{\, i + 1/2} - T_k^{\, i}) / 2$.} 1407 \label{fig:TRA_Partial_step_scheme} 1392 1408 \end{figure} 1393 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1409 1394 1410 \[ 1395 1411 \widetilde T = \lt\{ 1396 1412 \begin{alignedat}{2} 1397 1413 &T^{\, i + 1} &-\frac{ \lt( e_{3w}^{i + 1} -e_{3w}^i \rt) }{ e_{3w}^{i + 1} } \; \delta_k T^{i + 1} 1398 & \quad \text{if $e_{3w}^{i + 1} \geq e_{3w}^i$} \\ \\1414 & \quad \text{if $e_{3w}^{i + 1} \geq e_{3w}^i$} \\ 1399 1415 &T^{\, i} &+\frac{ \lt( e_{3w}^{i + 1} -e_{3w}^i \rt )}{e_{3w}^i } \; \delta_k T^{i + 1} 1400 1416 & \quad \text{if $e_{3w}^{i + 1} < e_{3w}^i$} … … 1402 1418 \rt. 1403 1419 \] 1404 and the resulting forms for the horizontal difference and the horizontal average value of $T$ at a $U$-point are: 1405 \begin{equation} 1406 \label{eq:zps_hde} 1420 and the resulting forms for the horizontal difference and the horizontal average value of 1421 $T$ at a $U$-point are: 1422 \begin{equation} 1423 \label{eq:TRA_zps_hde} 1407 1424 \begin{split} 1408 1425 \delta_{i + 1/2} T &= 1409 1426 \begin{cases} 1410 \widetilde T - T^i & \text{if~} e_{3w}^{i + 1} \geq e_{3w}^i \\ 1411 \\ 1412 T^{\, i + 1} - \widetilde T & \text{if~} e_{3w}^{i + 1} < e_{3w}^i 1413 \end{cases} 1414 \\ 1427 \widetilde T - T^i & \text{if~} e_{3w}^{i + 1} \geq e_{3w}^i \\ 1428 T^{\, i + 1} - \widetilde T & \text{if~} e_{3w}^{i + 1} < e_{3w}^i 1429 \end{cases} \\ 1415 1430 \overline T^{\, i + 1/2} &= 1416 1431 \begin{cases} 1417 (\widetilde T - T^{\, i} ) / 2 & \text{if~} e_{3w}^{i + 1} \geq e_{3w}^i \\ 1418 \\ 1419 (T^{\, i + 1} - \widetilde T) / 2 & \text{if~} e_{3w}^{i + 1} < e_{3w}^i 1432 (\widetilde T - T^{\, i} ) / 2 & \text{if~} e_{3w}^{i + 1} \geq e_{3w}^i \\ 1433 (T^{\, i + 1} - \widetilde T) / 2 & \text{if~} e_{3w}^{i + 1} < e_{3w}^i 1420 1434 \end{cases} 1421 1435 \end{split} … … 1424 1438 The computation of horizontal derivative of tracers as well as of density is performed once for all at 1425 1439 each time step in \mdl{zpshde} module and stored in shared arrays to be used when needed. 1426 It has to be emphasized that the procedure used to compute the interpolated density, $\widetilde \rho$, 1427 is not the same as that used for $T$ and $S$. 1428 Instead of forming a linear approximation of density, we compute $\widetilde \rho$ from the interpolated values of 1429 $T$ and $S$, and the pressure at a $u$-point 1430 (in the equation of state pressure is approximated by depth, see \autoref{subsec:TRA_eos}): 1440 It has to be emphasized that the procedure used to compute the interpolated density, 1441 $\widetilde \rho$, is not the same as that used for $T$ and $S$. 1442 Instead of forming a linear approximation of density, 1443 we compute $\widetilde \rho$ from the interpolated values of $T$ and $S$, 1444 and the pressure at a $u$-point 1445 (in the equation of state pressure is approximated by depth, see \autoref{subsec:TRA_eos}): 1431 1446 \[ 1432 % \label{eq: zps_hde_rho}1447 % \label{eq:TRA_zps_hde_rho} 1433 1448 \widetilde \rho = \rho (\widetilde T,\widetilde S,z_u) \quad \text{where~} z_u = \min \lt( z_T^{i + 1},z_T^i \rt) 1434 1449 \] 1435 1450 1436 1451 This is a much better approximation as the variation of $\rho$ with depth (and thus pressure) 1437 is highly non-linear with a true equation of state and thus is badly approximated with a linear interpolation. 1438 This approximation is used to compute both the horizontal pressure gradient (\autoref{sec:DYN_hpg}) and 1439 the slopes of neutral surfaces (\autoref{sec:LDF_slp}). 1440 1441 Note that in almost all the advection schemes presented in this Chapter, 1452 is highly non-linear with a true equation of state and thus is badly approximated with 1453 a linear interpolation. 1454 This approximation is used to compute both the horizontal pressure gradient (\autoref{sec:DYN_hpg}) 1455 and the slopes of neutral surfaces (\autoref{sec:LDF_slp}). 1456 1457 Note that in almost all the advection schemes presented in this chapter, 1442 1458 both averaging and differencing operators appear. 1443 Yet \autoref{eq: zps_hde} has not been used in these schemes:1459 Yet \autoref{eq:TRA_zps_hde} has not been used in these schemes: 1444 1460 in contrast to diffusion and pressure gradient computations, 1445 1461 no correction for partial steps is applied for advection. 1446 1462 The main motivation is to preserve the domain averaged mean variance of the advected field when 1447 1463 using the $2^{nd}$ order centred scheme. 1448 Sensitivity of the advection schemes to the way horizontal averages are performed in the vicinity of 1449 partial cells should be further investigated in the near future. 1450 %%% 1451 \gmcomment{gm : this last remark has to be done} 1452 %%% 1453 1454 \biblio 1455 1456 \pindex 1464 Sensitivity of the advection schemes to the way horizontal averages are performed in 1465 the vicinity of partial cells should be further investigated in the near future. 1466 \cmtgm{gm : this last remark has to be done} 1467 1468 \subinc{\input{../../global/epilogue}} 1457 1469 1458 1470 \end{document} -
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_ZDF.tex
r10442 r11831 1 1 \documentclass[../main/NEMO_manual]{subfiles} 2 2 3 %% Custom aliases 4 \newcommand{\cf}{\ensuremath{C\kern-0.14em f}} 5 3 6 \begin{document} 4 % ================================================================ 5 % Chapter Vertical Ocean Physics (ZDF) 6 % ================================================================ 7 7 8 \chapter{Vertical Ocean Physics (ZDF)} 8 9 \label{chap:ZDF} 9 10 10 \minitoc 11 12 %gm% Add here a small introduction to ZDF and naming of the different physics (similar to what have been written for TRA and DYN. 13 14 \newpage 15 16 % ================================================================ 17 % Vertical Mixing 18 % ================================================================ 11 \thispagestyle{plain} 12 13 \chaptertoc 14 15 \paragraph{Changes record} ~\\ 16 17 {\footnotesize 18 \begin{tabularx}{\textwidth}{l||X|X} 19 Release & Author(s) & Modifications \\ 20 \hline 21 {\em 4.0} & {\em ...} & {\em ...} \\ 22 {\em 3.6} & {\em ...} & {\em ...} \\ 23 {\em 3.4} & {\em ...} & {\em ...} \\ 24 {\em <=3.4} & {\em ...} & {\em ...} 25 \end{tabularx} 26 } 27 28 \clearpage 29 30 \cmtgm{ Add here a small introduction to ZDF and naming of the different physics 31 (similar to what have been written for TRA and DYN).} 32 33 %% ================================================================================================= 19 34 \section{Vertical mixing} 20 \label{sec:ZDF _zdf}35 \label{sec:ZDF} 21 36 22 37 The discrete form of the ocean subgrid scale physics has been presented in … … 25 40 At the surface they are prescribed from the surface forcing (see \autoref{chap:SBC}), 26 41 while at the bottom they are set to zero for heat and salt, 27 unless a geothermal flux forcing is prescribed as a bottom boundary condition (\ie \key{trabbl} defined,42 unless a geothermal flux forcing is prescribed as a bottom boundary condition (\ie\ \np{ln_trabbc}{ln\_trabbc} defined, 28 43 see \autoref{subsec:TRA_bbc}), and specified through a bottom friction parameterisation for momentum 29 (see \autoref{sec:ZDF_ bfr}).44 (see \autoref{sec:ZDF_drg}). 30 45 31 46 In this section we briefly discuss the various choices offered to compute the vertical eddy viscosity and … … 33 48 respectively (see \autoref{sec:TRA_zdf} and \autoref{sec:DYN_zdf}). 34 49 These coefficients can be assumed to be either constant, or a function of the local Richardson number, 35 or computed from a turbulent closure model (either TKE or GLS formulation).36 The computation of these coefficients is initialized in the \mdl{zdf ini} module and performed in37 the \mdl{zdfric}, \mdl{zdftke} or \mdl{zdfgls} modules.50 or computed from a turbulent closure model (either TKE or GLS or OSMOSIS formulation). 51 The computation of these coefficients is initialized in the \mdl{zdfphy} module and performed in 52 the \mdl{zdfric}, \mdl{zdftke} or \mdl{zdfgls} or \mdl{zdfosm} modules. 38 53 The trends due to the vertical momentum and tracer diffusion, including the surface forcing, 39 are computed and added to the general trend in the \mdl{dynzdf} and \mdl{trazdf} modules, respectively. 40 These trends can be computed using either a forward time stepping scheme 41 (namelist parameter \np{ln\_zdfexp}\forcode{ = .true.}) or a backward time stepping scheme 42 (\np{ln\_zdfexp}\forcode{ = .false.}) depending on the magnitude of the mixing coefficients, 43 and thus of the formulation used (see \autoref{chap:STP}). 44 45 % ------------------------------------------------------------------------------------------------------------- 46 % Constant 47 % ------------------------------------------------------------------------------------------------------------- 48 \subsection{Constant (\protect\key{zdfcst})} 54 are computed and added to the general trend in the \mdl{dynzdf} and \mdl{trazdf} modules, respectively. 55 %These trends can be computed using either a forward time stepping scheme 56 %(namelist parameter \np[=.true.]{ln_zdfexp}{ln\_zdfexp}) or a backward time stepping scheme 57 %(\np[=.false.]{ln_zdfexp}{ln\_zdfexp}) depending on the magnitude of the mixing coefficients, 58 %and thus of the formulation used (see \autoref{chap:TD}). 59 60 \begin{listing} 61 \nlst{namzdf} 62 \caption{\forcode{&namzdf}} 63 \label{lst:namzdf} 64 \end{listing} 65 66 %% ================================================================================================= 67 \subsection[Constant (\forcode{ln_zdfcst})]{Constant (\protect\np{ln_zdfcst}{ln\_zdfcst})} 49 68 \label{subsec:ZDF_cst} 50 %--------------------------------------------namzdf--------------------------------------------------------- 51 52 \nlst{namzdf} 53 %-------------------------------------------------------------------------------------------------------------- 54 55 Options are defined through the \ngn{namzdf} namelist variables. 56 When \key{zdfcst} is defined, the momentum and tracer vertical eddy coefficients are set to 69 70 Options are defined through the \nam{zdf}{zdf} namelist variables. 71 When \np{ln_zdfcst}{ln\_zdfcst} is defined, the momentum and tracer vertical eddy coefficients are set to 57 72 constant values over the whole ocean. 58 73 This is the crudest way to define the vertical ocean physics. 59 It is recommended t hat this option is only usedin process studies, not in basin scale simulations.74 It is recommended to use this option only in process studies, not in basin scale simulations. 60 75 Typical values used in this case are: 61 76 \begin{align*} … … 64 79 \end{align*} 65 80 66 These values are set through the \np{rn \_avm0} and \np{rn\_avt0} namelist parameters.81 These values are set through the \np{rn_avm0}{rn\_avm0} and \np{rn_avt0}{rn\_avt0} namelist parameters. 67 82 In all cases, do not use values smaller that those associated with the molecular viscosity and diffusivity, 68 83 that is $\sim10^{-6}~m^2.s^{-1}$ for momentum, $\sim10^{-7}~m^2.s^{-1}$ for temperature and 69 84 $\sim10^{-9}~m^2.s^{-1}$ for salinity. 70 85 71 % ------------------------------------------------------------------------------------------------------------- 72 % Richardson Number Dependent 73 % ------------------------------------------------------------------------------------------------------------- 74 \subsection{Richardson number dependent (\protect\key{zdfric})} 86 %% ================================================================================================= 87 \subsection[Richardson number dependent (\forcode{ln_zdfric})]{Richardson number dependent (\protect\np{ln_zdfric}{ln\_zdfric})} 75 88 \label{subsec:ZDF_ric} 76 89 77 %--------------------------------------------namric--------------------------------------------------------- 78 79 \nlst{namzdf_ric} 80 %-------------------------------------------------------------------------------------------------------------- 81 82 When \key{zdfric} is defined, a local Richardson number dependent formulation for the vertical momentum and 83 tracer eddy coefficients is set through the \ngn{namzdf\_ric} namelist variables. 84 The vertical mixing coefficients are diagnosed from the large scale variables computed by the model. 90 \begin{listing} 91 \nlst{namzdf_ric} 92 \caption{\forcode{&namzdf_ric}} 93 \label{lst:namzdf_ric} 94 \end{listing} 95 96 When \np[=.true.]{ln_zdfric}{ln\_zdfric}, a local Richardson number dependent formulation for the vertical momentum and 97 tracer eddy coefficients is set through the \nam{zdf_ric}{zdf\_ric} namelist variables. 98 The vertical mixing coefficients are diagnosed from the large scale variables computed by the model. 85 99 \textit{In situ} measurements have been used to link vertical turbulent activity to large scale ocean structures. 86 100 The hypothesis of a mixing mainly maintained by the growth of Kelvin-Helmholtz like instabilities leads to 87 101 a dependency between the vertical eddy coefficients and the local Richardson number 88 (\ie the ratio of stratification to vertical shear).89 Following \citet{ Pacanowski_Philander_JPO81}, the following formulation has been implemented:90 \[ 91 % \label{eq: zdfric}102 (\ie\ the ratio of stratification to vertical shear). 103 Following \citet{pacanowski.philander_JPO81}, the following formulation has been implemented: 104 \[ 105 % \label{eq:ZDF_ric} 92 106 \left\{ 93 107 \begin{aligned} … … 98 112 \] 99 113 where $Ri = N^2 / \left(\partial_z \textbf{U}_h \right)^2$ is the local Richardson number, 100 $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}), 114 $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}), 101 115 $A_b^{vT} $ and $A_b^{vm}$ are the constant background values set as in the constant case 102 116 (see \autoref{subsec:ZDF_cst}), and $A_{ric}^{vT} = 10^{-4}~m^2.s^{-1}$ is the maximum value that 103 117 can be reached by the coefficient when $Ri\leq 0$, $a=5$ and $n=2$. 104 The last three values can be modified by setting the \np{rn \_avmri}, \np{rn\_alp} and105 \np{nn \_ric} namelist parameters, respectively.118 The last three values can be modified by setting the \np{rn_avmri}{rn\_avmri}, \np{rn_alp}{rn\_alp} and 119 \np{nn_ric}{nn\_ric} namelist parameters, respectively. 106 120 107 121 A simple mixing-layer model to transfer and dissipate the atmospheric forcings 108 (wind-stress and buoyancy fluxes) can be activated setting the \np {ln\_mldw}\forcode{ = .true.} in the namelist.122 (wind-stress and buoyancy fluxes) can be activated setting the \np[=.true.]{ln_mldw}{ln\_mldw} in the namelist. 109 123 110 124 In this case, the local depth of turbulent wind-mixing or "Ekman depth" $h_{e}(x,y,t)$ is evaluated and … … 122 136 \] 123 137 is computed from the wind stress vector $|\tau|$ and the reference density $ \rho_o$. 124 The final $h_{e}$ is further constrained by the adjustable bounds \np{rn \_mldmin} and \np{rn\_mldmax}.138 The final $h_{e}$ is further constrained by the adjustable bounds \np{rn_mldmin}{rn\_mldmin} and \np{rn_mldmax}{rn\_mldmax}. 125 139 Once $h_{e}$ is computed, the vertical eddy coefficients within $h_{e}$ are set to 126 the empirical values \np{rn\_wtmix} and \np{rn\_wvmix} \citep{Lermusiaux2001}. 127 128 % ------------------------------------------------------------------------------------------------------------- 129 % TKE Turbulent Closure Scheme 130 % ------------------------------------------------------------------------------------------------------------- 131 \subsection{TKE turbulent closure scheme (\protect\key{zdftke})} 140 the empirical values \np{rn_wtmix}{rn\_wtmix} and \np{rn_wvmix}{rn\_wvmix} \citep{lermusiaux_JMS01}. 141 142 %% ================================================================================================= 143 \subsection[TKE turbulent closure scheme (\forcode{ln_zdftke})]{TKE turbulent closure scheme (\protect\np{ln_zdftke}{ln\_zdftke})} 132 144 \label{subsec:ZDF_tke} 133 145 134 %--------------------------------------------namzdf_tke-------------------------------------------------- 135 136 \nlst{namzdf_tke} 137 %-------------------------------------------------------------------------------------------------------------- 146 \begin{listing} 147 \nlst{namzdf_tke} 148 \caption{\forcode{&namzdf_tke}} 149 \label{lst:namzdf_tke} 150 \end{listing} 138 151 139 152 The vertical eddy viscosity and diffusivity coefficients are computed from a TKE turbulent closure model based on 140 153 a prognostic equation for $\bar{e}$, the turbulent kinetic energy, 141 154 and a closure assumption for the turbulent length scales. 142 This turbulent closure model has been developed by \citet{ Bougeault1989} in the atmospheric case,143 adapted by \citet{ Gaspar1990} for the oceanic case, and embedded in OPA, the ancestor ofNEMO,144 by \citet{ Blanke1993} for equatorial Atlantic simulations.145 Since then, significant modifications have been introduced by \citet{ Madec1998} in both the implementation and155 This turbulent closure model has been developed by \citet{bougeault.lacarrere_MWR89} in the atmospheric case, 156 adapted by \citet{gaspar.gregoris.ea_JGR90} for the oceanic case, and embedded in OPA, the ancestor of \NEMO, 157 by \citet{blanke.delecluse_JPO93} for equatorial Atlantic simulations. 158 Since then, significant modifications have been introduced by \citet{madec.delecluse.ea_NPM98} in both the implementation and 146 159 the formulation of the mixing length scale. 147 160 The time evolution of $\bar{e}$ is the result of the production of $\bar{e}$ through vertical shear, 148 its destruction through stratification, its vertical diffusion, and its dissipation of \citet{ Kolmogorov1942} type:161 its destruction through stratification, its vertical diffusion, and its dissipation of \citet{kolmogorov_IANS42} type: 149 162 \begin{equation} 150 \label{eq: zdftke_e}163 \label{eq:ZDF_tke_e} 151 164 \frac{\partial \bar{e}}{\partial t} = 152 165 \frac{K_m}{{e_3}^2 }\;\left[ {\left( {\frac{\partial u}{\partial k}} \right)^2 … … 158 171 \end{equation} 159 172 \[ 160 % \label{eq: zdftke_kz}173 % \label{eq:ZDF_tke_kz} 161 174 \begin{split} 162 175 K_m &= C_k\ l_k\ \sqrt {\bar{e}\; } \\ … … 164 177 \end{split} 165 178 \] 166 where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}), 167 $l_{\epsilon }$ and $l_{\kappa }$ are the dissipation and mixing length scales, 179 where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}), 180 $l_{\epsilon }$ and $l_{\kappa }$ are the dissipation and mixing length scales, 168 181 $P_{rt}$ is the Prandtl number, $K_m$ and $K_\rho$ are the vertical eddy viscosity and diffusivity coefficients. 169 182 The constants $C_k = 0.1$ and $C_\epsilon = \sqrt {2} /2$ $\approx 0.7$ are designed to deal with 170 vertical mixing at any depth \citep{ Gaspar1990}.171 They are set through namelist parameters \np{nn \_ediff} and \np{nn\_ediss}.172 $P_{rt}$ can be set to unity or, following \citet{ Blanke1993}, be a function of the local Richardson number, $R_i$:183 vertical mixing at any depth \citep{gaspar.gregoris.ea_JGR90}. 184 They are set through namelist parameters \np{nn_ediff}{nn\_ediff} and \np{nn_ediss}{nn\_ediss}. 185 $P_{rt}$ can be set to unity or, following \citet{blanke.delecluse_JPO93}, be a function of the local Richardson number, $R_i$: 173 186 \begin{align*} 174 % \label{eq: prt}187 % \label{eq:ZDF_prt} 175 188 P_{rt} = 176 189 \begin{cases} … … 180 193 \end{cases} 181 194 \end{align*} 182 Options are defined through the \ngn{namzdfy\_tke} namelist variables. 183 The choice of $P_{rt}$ is controlled by the \np{nn\_pdl} namelist variable. 195 The choice of $P_{rt}$ is controlled by the \np{nn_pdl}{nn\_pdl} namelist variable. 184 196 185 197 At the sea surface, the value of $\bar{e}$ is prescribed from the wind stress field as 186 $\bar{e}_o = e_{bb} |\tau| / \rho_o$, with $e_{bb}$ the \np{rn \_ebb} namelist parameter.187 The default value of $e_{bb}$ is 3.75. \citep{ Gaspar1990}), however a much larger value can be used when198 $\bar{e}_o = e_{bb} |\tau| / \rho_o$, with $e_{bb}$ the \np{rn_ebb}{rn\_ebb} namelist parameter. 199 The default value of $e_{bb}$ is 3.75. \citep{gaspar.gregoris.ea_JGR90}), however a much larger value can be used when 188 200 taking into account the surface wave breaking (see below Eq. \autoref{eq:ZDF_Esbc}). 189 201 The bottom value of TKE is assumed to be equal to the value of the level just above. 190 202 The time integration of the $\bar{e}$ equation may formally lead to negative values because 191 203 the numerical scheme does not ensure its positivity. 192 To overcome this problem, a cut-off in the minimum value of $\bar{e}$ is used (\np{rn \_emin} namelist parameter).193 Following \citet{ Gaspar1990}, the cut-off value is set to $\sqrt{2}/2~10^{-6}~m^2.s^{-2}$.194 This allows the subsequent formulations to match that of \citet{ Gargett1984} for the diffusion in204 To overcome this problem, a cut-off in the minimum value of $\bar{e}$ is used (\np{rn_emin}{rn\_emin} namelist parameter). 205 Following \citet{gaspar.gregoris.ea_JGR90}, the cut-off value is set to $\sqrt{2}/2~10^{-6}~m^2.s^{-2}$. 206 This allows the subsequent formulations to match that of \citet{gargett_JMR84} for the diffusion in 195 207 the thermocline and deep ocean : $K_\rho = 10^{-3} / N$. 196 208 In addition, a cut-off is applied on $K_m$ and $K_\rho$ to avoid numerical instabilities associated with 197 209 too weak vertical diffusion. 198 They must be specified at least larger than the molecular values, and are set through \np{rn\_avm0} and 199 \np{rn\_avt0} (namzdf namelist, see \autoref{subsec:ZDF_cst}). 200 210 They must be specified at least larger than the molecular values, and are set through \np{rn_avm0}{rn\_avm0} and 211 \np{rn_avt0}{rn\_avt0} (\nam{zdf}{zdf} namelist, see \autoref{subsec:ZDF_cst}). 212 213 %% ================================================================================================= 201 214 \subsubsection{Turbulent length scale} 202 215 203 216 For computational efficiency, the original formulation of the turbulent length scales proposed by 204 \citet{ Gaspar1990} has been simplified.205 Four formulations are proposed, the choice of which is controlled by the \np{nn \_mxl} namelist parameter.206 The first two are based on the following first order approximation \citep{ Blanke1993}:217 \citet{gaspar.gregoris.ea_JGR90} has been simplified. 218 Four formulations are proposed, the choice of which is controlled by the \np{nn_mxl}{nn\_mxl} namelist parameter. 219 The first two are based on the following first order approximation \citep{blanke.delecluse_JPO93}: 207 220 \begin{equation} 208 \label{eq: tke_mxl0_1}221 \label{eq:ZDF_tke_mxl0_1} 209 222 l_k = l_\epsilon = \sqrt {2 \bar{e}\; } / N 210 223 \end{equation} 211 224 which is valid in a stable stratified region with constant values of the Brunt-Vais\"{a}l\"{a} frequency. 212 225 The resulting length scale is bounded by the distance to the surface or to the bottom 213 (\np {nn\_mxl}\forcode{ = 0}) or by the local vertical scale factor (\np{nn\_mxl}\forcode{ = 1}).214 \citet{ Blanke1993} notice that this simplification has two major drawbacks:226 (\np[=0]{nn_mxl}{nn\_mxl}) or by the local vertical scale factor (\np[=1]{nn_mxl}{nn\_mxl}). 227 \citet{blanke.delecluse_JPO93} notice that this simplification has two major drawbacks: 215 228 it makes no sense for locally unstable stratification and the computation no longer uses all 216 229 the information contained in the vertical density profile. 217 To overcome these drawbacks, \citet{ Madec1998} introduces the \np{nn\_mxl}\forcode{ = 2..3} cases,230 To overcome these drawbacks, \citet{madec.delecluse.ea_NPM98} introduces the \np[=2, 3]{nn_mxl}{nn\_mxl} cases, 218 231 which add an extra assumption concerning the vertical gradient of the computed length scale. 219 So, the length scales are first evaluated as in \autoref{eq: tke_mxl0_1} and then bounded such that:232 So, the length scales are first evaluated as in \autoref{eq:ZDF_tke_mxl0_1} and then bounded such that: 220 233 \begin{equation} 221 \label{eq: tke_mxl_constraint}234 \label{eq:ZDF_tke_mxl_constraint} 222 235 \frac{1}{e_3 }\left| {\frac{\partial l}{\partial k}} \right| \leq 1 223 236 \qquad \text{with }\ l = l_k = l_\epsilon 224 237 \end{equation} 225 \autoref{eq: tke_mxl_constraint} means that the vertical variations of the length scale cannot be larger than238 \autoref{eq:ZDF_tke_mxl_constraint} means that the vertical variations of the length scale cannot be larger than 226 239 the variations of depth. 227 It provides a better approximation of the \citet{ Gaspar1990} formulation while being much less240 It provides a better approximation of the \citet{gaspar.gregoris.ea_JGR90} formulation while being much less 228 241 time consuming. 229 242 In particular, it allows the length scale to be limited not only by the distance to the surface or 230 243 to the ocean bottom but also by the distance to a strongly stratified portion of the water column such as 231 the thermocline (\autoref{fig: mixing_length}).232 In order to impose the \autoref{eq: tke_mxl_constraint} constraint, we introduce two additional length scales:244 the thermocline (\autoref{fig:ZDF_mixing_length}). 245 In order to impose the \autoref{eq:ZDF_tke_mxl_constraint} constraint, we introduce two additional length scales: 233 246 $l_{up}$ and $l_{dwn}$, the upward and downward length scales, and 234 247 evaluate the dissipation and mixing length scales as 235 248 (and note that here we use numerical indexing): 236 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>237 249 \begin{figure}[!t] 238 \begin{center} 239 \includegraphics[width=1.00\textwidth]{Fig_mixing_length} 240 \caption{ 241 \protect\label{fig:mixing_length} 242 Illustration of the mixing length computation. 243 } 244 \end{center} 250 \centering 251 \includegraphics[width=0.66\textwidth]{ZDF_mixing_length} 252 \caption[Mixing length computation]{Illustration of the mixing length computation} 253 \label{fig:ZDF_mixing_length} 245 254 \end{figure} 246 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 247 \[ 248 % \label{eq:tke_mxl2} 255 \[ 256 % \label{eq:ZDF_tke_mxl2} 249 257 \begin{aligned} 250 258 l_{up\ \ }^{(k)} &= \min \left( l^{(k)} \ , \ l_{up}^{(k+1)} + e_{3t}^{(k)}\ \ \ \; \right) … … 254 262 \end{aligned} 255 263 \] 256 where $l^{(k)}$ is computed using \autoref{eq: tke_mxl0_1}, \ie$l^{(k)} = \sqrt {2 {\bar e}^{(k)} / {N^2}^{(k)} }$.257 258 In the \np {nn\_mxl}\forcode{ = 2} case, the dissipation and mixing length scales take the same value:259 $ l_k= l_\epsilon = \min \left(\ l_{up} \;,\; l_{dwn}\ \right)$, while in the \np {nn\_mxl}\forcode{ = 3} case,260 the dissipation and mixing turbulent length scales are give as in \citet{ Gaspar1990}:261 \[ 262 % \label{eq: tke_mxl_gaspar}264 where $l^{(k)}$ is computed using \autoref{eq:ZDF_tke_mxl0_1}, \ie\ $l^{(k)} = \sqrt {2 {\bar e}^{(k)} / {N^2}^{(k)} }$. 265 266 In the \np[=2]{nn_mxl}{nn\_mxl} case, the dissipation and mixing length scales take the same value: 267 $ l_k= l_\epsilon = \min \left(\ l_{up} \;,\; l_{dwn}\ \right)$, while in the \np[=3]{nn_mxl}{nn\_mxl} case, 268 the dissipation and mixing turbulent length scales are give as in \citet{gaspar.gregoris.ea_JGR90}: 269 \[ 270 % \label{eq:ZDF_tke_mxl_gaspar} 263 271 \begin{aligned} 264 272 & l_k = \sqrt{\ l_{up} \ \ l_{dwn}\ } \\ … … 267 275 \] 268 276 269 At the ocean surface, a non zero length scale is set through the \np{rn \_mxl0} namelist parameter.277 At the ocean surface, a non zero length scale is set through the \np{rn_mxl0}{rn\_mxl0} namelist parameter. 270 278 Usually the surface scale is given by $l_o = \kappa \,z_o$ where $\kappa = 0.4$ is von Karman's constant and 271 279 $z_o$ the roughness parameter of the surface. 272 Assuming $z_o=0.1$~m \citep{ Craig_Banner_JPO94} leads to a 0.04~m, the default value of \np{rn\_mxl0}.280 Assuming $z_o=0.1$~m \citep{craig.banner_JPO94} leads to a 0.04~m, the default value of \np{rn_mxl0}{rn\_mxl0}. 273 281 In the ocean interior a minimum length scale is set to recover the molecular viscosity when 274 282 $\bar{e}$ reach its minimum value ($1.10^{-6}= C_k\, l_{min} \,\sqrt{\bar{e}_{min}}$ ). 275 283 284 %% ================================================================================================= 276 285 \subsubsection{Surface wave breaking parameterization} 277 %-----------------------------------------------------------------------% 278 279 Following \citet{Mellor_Blumberg_JPO04}, the TKE turbulence closure model has been modified to 286 287 Following \citet{mellor.blumberg_JPO04}, the TKE turbulence closure model has been modified to 280 288 include the effect of surface wave breaking energetics. 281 289 This results in a reduction of summertime surface temperature when the mixed layer is relatively shallow. 282 The \citet{ Mellor_Blumberg_JPO04} modifications acts on surface length scale and TKE values and283 air-sea drag coefficient. 284 The latter concerns the bulk formul ea and is not discussed here.285 286 Following \citet{ Craig_Banner_JPO94}, the boundary condition on surface TKE value is :290 The \citet{mellor.blumberg_JPO04} modifications acts on surface length scale and TKE values and 291 air-sea drag coefficient. 292 The latter concerns the bulk formulae and is not discussed here. 293 294 Following \citet{craig.banner_JPO94}, the boundary condition on surface TKE value is : 287 295 \begin{equation} 288 296 \label{eq:ZDF_Esbc} 289 297 \bar{e}_o = \frac{1}{2}\,\left( 15.8\,\alpha_{CB} \right)^{2/3} \,\frac{|\tau|}{\rho_o} 290 298 \end{equation} 291 where $\alpha_{CB}$ is the \citet{ Craig_Banner_JPO94} constant of proportionality which depends on the ''wave age'',292 ranging from 57 for mature waves to 146 for younger waves \citep{ Mellor_Blumberg_JPO04}.299 where $\alpha_{CB}$ is the \citet{craig.banner_JPO94} constant of proportionality which depends on the ''wave age'', 300 ranging from 57 for mature waves to 146 for younger waves \citep{mellor.blumberg_JPO04}. 293 301 The boundary condition on the turbulent length scale follows the Charnock's relation: 294 302 \begin{equation} … … 297 305 \end{equation} 298 306 where $\kappa=0.40$ is the von Karman constant, and $\beta$ is the Charnock's constant. 299 \citet{ Mellor_Blumberg_JPO04} suggest $\beta = 2.10^{5}$ the value chosen by300 \citet{ Stacey_JPO99} citing observation evidence, and307 \citet{mellor.blumberg_JPO04} suggest $\beta = 2.10^{5}$ the value chosen by 308 \citet{stacey_JPO99} citing observation evidence, and 301 309 $\alpha_{CB} = 100$ the Craig and Banner's value. 302 310 As the surface boundary condition on TKE is prescribed through $\bar{e}_o = e_{bb} |\tau| / \rho_o$, 303 with $e_{bb}$ the \np{rn \_ebb} namelist parameter, setting \np{rn\_ebb}\forcode{ = 67.83} corresponds311 with $e_{bb}$ the \np{rn_ebb}{rn\_ebb} namelist parameter, setting \np[=67.83]{rn_ebb}{rn\_ebb} corresponds 304 312 to $\alpha_{CB} = 100$. 305 Further setting \np {ln\_mxl0} to true applies \autoref{eq:ZDF_Lsbc} as surface boundary condition onlength scale,313 Further setting \np[=.true.]{ln_mxl0}{ln\_mxl0}, applies \autoref{eq:ZDF_Lsbc} as the surface boundary condition on the length scale, 306 314 with $\beta$ hard coded to the Stacey's value. 307 Note that a minimal threshold of \np{rn \_emin0}$=10^{-4}~m^2.s^{-2}$ (namelist parameters) is applied on315 Note that a minimal threshold of \np{rn_emin0}{rn\_emin0}$=10^{-4}~m^2.s^{-2}$ (namelist parameters) is applied on the 308 316 surface $\bar{e}$ value. 309 317 318 %% ================================================================================================= 310 319 \subsubsection{Langmuir cells} 311 %--------------------------------------%312 320 313 321 Langmuir circulations (LC) can be described as ordered large-scale vertical motions in … … 315 323 Although LC have nothing to do with convection, the circulation pattern is rather similar to 316 324 so-called convective rolls in the atmospheric boundary layer. 317 The detailed physics behind LC is described in, for example, \citet{ Craik_Leibovich_JFM76}.325 The detailed physics behind LC is described in, for example, \citet{craik.leibovich_JFM76}. 318 326 The prevailing explanation is that LC arise from a nonlinear interaction between the Stokes drift and 319 wind drift currents. 327 wind drift currents. 320 328 321 329 Here we introduced in the TKE turbulent closure the simple parameterization of Langmuir circulations proposed by 322 \citep{ Axell_JGR02} for a $k-\epsilon$ turbulent closure.330 \citep{axell_JGR02} for a $k-\epsilon$ turbulent closure. 323 331 The parameterization, tuned against large-eddy simulation, includes the whole effect of LC in 324 an extra source term sof TKE, $P_{LC}$.325 The presence of $P_{LC}$ in \autoref{eq: zdftke_e}, the TKE equation, is controlled by setting \np{ln\_lc} to326 \forcode{.true.} in the namtkenamelist.327 328 By making an analogy with the characteristic convective velocity scale (\eg, \citet{ D'Alessio_al_JPO98}),329 $P_{LC}$ is assumed to be : 332 an extra source term of TKE, $P_{LC}$. 333 The presence of $P_{LC}$ in \autoref{eq:ZDF_tke_e}, the TKE equation, is controlled by setting \np{ln_lc}{ln\_lc} to 334 \forcode{.true.} in the \nam{zdf_tke}{zdf\_tke} namelist. 335 336 By making an analogy with the characteristic convective velocity scale (\eg, \citet{dalessio.abdella.ea_JPO98}), 337 $P_{LC}$ is assumed to be : 330 338 \[ 331 339 P_{LC}(z) = \frac{w_{LC}^3(z)}{H_{LC}} 332 340 \] 333 341 where $w_{LC}(z)$ is the vertical velocity profile of LC, and $H_{LC}$ is the LC depth. 334 With no information about the wave field, $w_{LC}$ is assumed to be proportional to 335 the Stokes drift $u_s = 0.377\,\,|\tau|^{1/2}$, where $|\tau|$ is the surface wind stress module 336 \footnote{Following \citet{ Li_Garrett_JMR93}, the surface Stoke drift velocity may be expressed as342 With no information about the wave field, $w_{LC}$ is assumed to be proportional to 343 the Stokes drift $u_s = 0.377\,\,|\tau|^{1/2}$, where $|\tau|$ is the surface wind stress module 344 \footnote{Following \citet{li.garrett_JMR93}, the surface Stoke drift velocity may be expressed as 337 345 $u_s = 0.016 \,|U_{10m}|$. 338 346 Assuming an air density of $\rho_a=1.22 \,Kg/m^3$ and a drag coefficient of … … 341 349 For the vertical variation, $w_{LC}$ is assumed to be zero at the surface as well as at 342 350 a finite depth $H_{LC}$ (which is often close to the mixed layer depth), 343 and simply varies as a sine function in between (a first-order profile for the Langmuir cell structures). 351 and simply varies as a sine function in between (a first-order profile for the Langmuir cell structures). 344 352 The resulting expression for $w_{LC}$ is : 345 353 \[ … … 350 358 \end{cases} 351 359 \] 352 where $c_{LC} = 0.15$ has been chosen by \citep{ Axell_JGR02} as a good compromise to fit LES data.360 where $c_{LC} = 0.15$ has been chosen by \citep{axell_JGR02} as a good compromise to fit LES data. 353 361 The chosen value yields maximum vertical velocities $w_{LC}$ of the order of a few centimeters per second. 354 The value of $c_{LC}$ is set through the \np{rn \_lc} namelist parameter,355 having in mind that it should stay between 0.15 and 0.54 \citep{ Axell_JGR02}.362 The value of $c_{LC}$ is set through the \np{rn_lc}{rn\_lc} namelist parameter, 363 having in mind that it should stay between 0.15 and 0.54 \citep{axell_JGR02}. 356 364 357 365 The $H_{LC}$ is estimated in a similar way as the turbulent length scale of TKE equations: 358 $H_{LC}$ is depth to which a water parcel with kinetic energy due to Stoke drift can reach on its own by359 converting its kinetic energy to potential energy, according to 366 $H_{LC}$ is the depth to which a water parcel with kinetic energy due to Stoke drift can reach on its own by 367 converting its kinetic energy to potential energy, according to 360 368 \[ 361 369 - \int_{-H_{LC}}^0 { N^2\;z \;dz} = \frac{1}{2} u_s^2 362 370 \] 363 371 372 %% ================================================================================================= 364 373 \subsubsection{Mixing just below the mixed layer} 365 %--------------------------------------------------------------%366 374 367 375 Vertical mixing parameterizations commonly used in ocean general circulation models tend to 368 376 produce mixed-layer depths that are too shallow during summer months and windy conditions. 369 377 This bias is particularly acute over the Southern Ocean. 370 To overcome this systematic bias, an ad hoc parameterization is introduced into the TKE scheme \cite{ Rodgers_2014}.371 The parameterization is an empirical one, \ie not derived from theoretical considerations,372 but rather is meant to account for observed processes that affect the density structure of 373 the ocean’s planetary boundary layer that are not explicitly captured by default in the TKE scheme 374 (\ie near-inertial oscillations and ocean swells and waves).375 376 When using this parameterization (\ie when \np{nn\_etau}\forcode{ = 1}),378 To overcome this systematic bias, an ad hoc parameterization is introduced into the TKE scheme \cite{rodgers.aumont.ea_B14}. 379 The parameterization is an empirical one, \ie\ not derived from theoretical considerations, 380 but rather is meant to account for observed processes that affect the density structure of 381 the ocean’s planetary boundary layer that are not explicitly captured by default in the TKE scheme 382 (\ie\ near-inertial oscillations and ocean swells and waves). 383 384 When using this parameterization (\ie\ when \np[=1]{nn_etau}{nn\_etau}), 377 385 the TKE input to the ocean ($S$) imposed by the winds in the form of near-inertial oscillations, 378 386 swell and waves is parameterized by \autoref{eq:ZDF_Esbc} the standard TKE surface boundary condition, … … 383 391 \end{equation} 384 392 where $z$ is the depth, $e_s$ is TKE surface boundary condition, $f_r$ is the fraction of the surface TKE that 385 penetrate in the ocean, $h_\tau$ is a vertical mixing length scale that controls exponential shape of393 penetrates in the ocean, $h_\tau$ is a vertical mixing length scale that controls exponential shape of 386 394 the penetration, and $f_i$ is the ice concentration 387 (no penetration if $f_i=1$, that isif the ocean is entirely covered by sea-ice).388 The value of $f_r$, usually a few percents, is specified through \np{rn \_efr} namelist parameter.389 The vertical mixing length scale, $h_\tau$, can be set as a 10~m uniform value (\np {nn\_etau}\forcode{ = 0}) or395 (no penetration if $f_i=1$, \ie\ if the ocean is entirely covered by sea-ice). 396 The value of $f_r$, usually a few percents, is specified through \np{rn_efr}{rn\_efr} namelist parameter. 397 The vertical mixing length scale, $h_\tau$, can be set as a 10~m uniform value (\np[=0]{nn_etau}{nn\_etau}) or 390 398 a latitude dependent value (varying from 0.5~m at the Equator to a maximum value of 30~m at high latitudes 391 (\np {nn\_etau}\forcode{ = 1}).392 393 Note that two other option exist e, \np{nn\_etau}\forcode{ = 2..3}.399 (\np[=1]{nn_etau}{nn\_etau}). 400 401 Note that two other option exist, \np[=2, 3]{nn_etau}{nn\_etau}. 394 402 They correspond to applying \autoref{eq:ZDF_Ehtau} only at the base of the mixed layer, 395 or to using the high frequency part of the stress to evaluate the fraction of TKE that penetrate the ocean.403 or to using the high frequency part of the stress to evaluate the fraction of TKE that penetrates the ocean. 396 404 Those two options are obsolescent features introduced for test purposes. 397 They will be removed in the next release. 398 399 % from Burchard et al OM 2008 : 400 % the most critical process not reproduced by statistical turbulence models is the activity of 401 % internal waves and their interaction with turbulence. After the Reynolds decomposition, 402 % internal waves are in principle included in the RANS equations, but later partially 403 % excluded by the hydrostatic assumption and the model resolution. 404 % Thus far, the representation of internal wave mixing in ocean models has been relatively crude 405 % (\eg Mellor, 1989; Large et al., 1994; Meier, 2001; Axell, 2002; St. Laurent and Garrett, 2002). 405 They will be removed in the next release. 406 407 % This should be explain better below what this rn_eice parameter is meant for: 408 In presence of Sea Ice, the value of this mixing can be modulated by the \np{rn_eice}{rn\_eice} namelist parameter. 409 This parameter varies from \forcode{0} for no effect to \forcode{4} to suppress the TKE input into the ocean when Sea Ice concentration 410 is greater than 25\%. 411 412 % from Burchard et al OM 2008 : 413 % the most critical process not reproduced by statistical turbulence models is the activity of 414 % internal waves and their interaction with turbulence. After the Reynolds decomposition, 415 % internal waves are in principle included in the RANS equations, but later partially 416 % excluded by the hydrostatic assumption and the model resolution. 417 % Thus far, the representation of internal wave mixing in ocean models has been relatively crude 418 % (\eg\ Mellor, 1989; Large et al., 1994; Meier, 2001; Axell, 2002; St. Laurent and Garrett, 2002). 419 420 %% ================================================================================================= 421 \subsection[GLS: Generic Length Scale (\forcode{ln_zdfgls})]{GLS: Generic Length Scale (\protect\np{ln_zdfgls}{ln\_zdfgls})} 422 \label{subsec:ZDF_gls} 423 424 \begin{listing} 425 \nlst{namzdf_gls} 426 \caption{\forcode{&namzdf_gls}} 427 \label{lst:namzdf_gls} 428 \end{listing} 429 430 The Generic Length Scale (GLS) scheme is a turbulent closure scheme based on two prognostic equations: 431 one for the turbulent kinetic energy $\bar {e}$, and another for the generic length scale, 432 $\psi$ \citep{umlauf.burchard_JMR03, umlauf.burchard_CSR05}. 433 This later variable is defined as: $\psi = {C_{0\mu}}^{p} \ {\bar{e}}^{m} \ l^{n}$, 434 where the triplet $(p, m, n)$ value given in Tab.\autoref{tab:ZDF_GLS} allows to recover a number of 435 well-known turbulent closures ($k$-$kl$ \citep{mellor.yamada_RG82}, $k$-$\epsilon$ \citep{rodi_JGR87}, 436 $k$-$\omega$ \citep{wilcox_AJ88} among others \citep{umlauf.burchard_JMR03,kantha.carniel_JMR03}). 437 The GLS scheme is given by the following set of equations: 438 \begin{equation} 439 \label{eq:ZDF_gls_e} 440 \frac{\partial \bar{e}}{\partial t} = 441 \frac{K_m}{\sigma_e e_3 }\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2 442 +\left( \frac{\partial v}{\partial k} \right)^2} \right] 443 -K_\rho \,N^2 444 +\frac{1}{e_3}\,\frac{\partial}{\partial k} \left[ \frac{K_m}{e_3}\,\frac{\partial \bar{e}}{\partial k} \right] 445 - \epsilon 446 \end{equation} 447 448 \[ 449 % \label{eq:ZDF_gls_psi} 450 \begin{split} 451 \frac{\partial \psi}{\partial t} =& \frac{\psi}{\bar{e}} \left\{ 452 \frac{C_1\,K_m}{\sigma_{\psi} {e_3}}\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2 453 +\left( \frac{\partial v}{\partial k} \right)^2} \right] 454 - C_3 \,K_\rho\,N^2 - C_2 \,\epsilon \,Fw \right\} \\ 455 &+\frac{1}{e_3} \;\frac{\partial }{\partial k}\left[ {\frac{K_m}{e_3 } 456 \;\frac{\partial \psi}{\partial k}} \right]\; 457 \end{split} 458 \] 459 460 \[ 461 % \label{eq:ZDF_gls_kz} 462 \begin{split} 463 K_m &= C_{\mu} \ \sqrt {\bar{e}} \ l \\ 464 K_\rho &= C_{\mu'}\ \sqrt {\bar{e}} \ l 465 \end{split} 466 \] 467 468 \[ 469 % \label{eq:ZDF_gls_eps} 470 {\epsilon} = C_{0\mu} \,\frac{\bar {e}^{3/2}}{l} \; 471 \] 472 where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}) and 473 $\epsilon$ the dissipation rate. 474 The constants $C_1$, $C_2$, $C_3$, ${\sigma_e}$, ${\sigma_{\psi}}$ and the wall function ($Fw$) depends of 475 the choice of the turbulence model. 476 Four different turbulent models are pre-defined (\autoref{tab:ZDF_GLS}). 477 They are made available through the \np{nn_clo}{nn\_clo} namelist parameter. 478 479 \begin{table}[htbp] 480 \centering 481 % \begin{tabular}{cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}c} 482 \begin{tabular}{ccccc} 483 & $k-kl$ & $k-\epsilon$ & $k-\omega$ & generic \\ 484 % & \citep{mellor.yamada_RG82} & \citep{rodi_JGR87} & \citep{wilcox_AJ88} & \\ 485 \hline 486 \hline 487 \np{nn_clo}{nn\_clo} & \textbf{0} & \textbf{1} & \textbf{2} & \textbf{3} \\ 488 \hline 489 $( p , n , m )$ & ( 0 , 1 , 1 ) & ( 3 , 1.5 , -1 ) & ( -1 , 0.5 , -1 ) & ( 2 , 1 , -0.67 ) \\ 490 $\sigma_k$ & 2.44 & 1. & 2. & 0.8 \\ 491 $\sigma_\psi$ & 2.44 & 1.3 & 2. & 1.07 \\ 492 $C_1$ & 0.9 & 1.44 & 0.555 & 1. \\ 493 $C_2$ & 0.5 & 1.92 & 0.833 & 1.22 \\ 494 $C_3$ & 1. & 1. & 1. & 1. \\ 495 $F_{wall}$ & Yes & -- & -- & -- \\ 496 \hline 497 \hline 498 \end{tabular} 499 \caption[Set of predefined GLS parameters or equivalently predefined turbulence models available]{ 500 Set of predefined GLS parameters, or equivalently predefined turbulence models available with 501 \protect\np[=.true.]{ln_zdfgls}{ln\_zdfgls} and controlled by 502 the \protect\np{nn_clos}{nn\_clos} namelist variable in \protect\nam{zdf_gls}{zdf\_gls}.} 503 \label{tab:ZDF_GLS} 504 \end{table} 505 506 In the Mellor-Yamada model, the negativity of $n$ allows to use a wall function to force the convergence of 507 the mixing length towards $\kappa z_b$ ($\kappa$ is the Von Karman constant and $z_b$ the rugosity length scale) value near physical boundaries 508 (logarithmic boundary layer law). 509 $C_{\mu}$ and $C_{\mu'}$ are calculated from stability function proposed by \citet{galperin.kantha.ea_JAS88}, 510 or by \citet{kantha.clayson_JGR94} or one of the two functions suggested by \citet{canuto.howard.ea_JPO01} 511 (\np[=0, 3]{nn_stab_func}{nn\_stab\_func}, resp.). 512 The value of $C_{0\mu}$ depends on the choice of the stability function. 513 514 The surface and bottom boundary condition on both $\bar{e}$ and $\psi$ can be calculated thanks to Dirichlet or 515 Neumann condition through \np{nn_bc_surf}{nn\_bc\_surf} and \np{nn_bc_bot}{nn\_bc\_bot}, resp. 516 As for TKE closure, the wave effect on the mixing is considered when 517 \np[ > 0.]{rn_crban}{rn\_crban} \citep{craig.banner_JPO94, mellor.blumberg_JPO04}. 518 The \np{rn_crban}{rn\_crban} namelist parameter is $\alpha_{CB}$ in \autoref{eq:ZDF_Esbc} and 519 \np{rn_charn}{rn\_charn} provides the value of $\beta$ in \autoref{eq:ZDF_Lsbc}. 520 521 The $\psi$ equation is known to fail in stably stratified flows, and for this reason 522 almost all authors apply a clipping of the length scale as an \textit{ad hoc} remedy. 523 With this clipping, the maximum permissible length scale is determined by $l_{max} = c_{lim} \sqrt{2\bar{e}}/ N$. 524 A value of $c_{lim} = 0.53$ is often used \citep{galperin.kantha.ea_JAS88}. 525 \cite{umlauf.burchard_CSR05} show that the value of the clipping factor is of crucial importance for 526 the entrainment depth predicted in stably stratified situations, 527 and that its value has to be chosen in accordance with the algebraic model for the turbulent fluxes. 528 The clipping is only activated if \np[=.true.]{ln_length_lim}{ln\_length\_lim}, 529 and the $c_{lim}$ is set to the \np{rn_clim_galp}{rn\_clim\_galp} value. 530 531 The time and space discretization of the GLS equations follows the same energetic consideration as for 532 the TKE case described in \autoref{subsec:ZDF_tke_ene} \citep{burchard_OM02}. 533 Evaluation of the 4 GLS turbulent closure schemes can be found in \citet{warner.sherwood.ea_OM05} in ROMS model and 534 in \citet{reffray.guillaume.ea_GMD15} for the \NEMO\ model. 406 535 407 536 % ------------------------------------------------------------------------------------------------------------- 408 % TKE discretization considerations537 % OSM OSMOSIS BL Scheme 409 538 % ------------------------------------------------------------------------------------------------------------- 410 \subsection{TKE discretization considerations (\protect\key{zdftke})} 411 \label{subsec:ZDF_tke_ene} 412 413 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 539 \subsection[OSM: OSMOSIS boundary layer scheme (\forcode{ln_zdfosm = .true.})] 540 {OSM: OSMOSIS boundary layer scheme (\protect\np{ln_zdfosm}{ln\_zdfosm})} 541 \label{subsec:ZDF_osm} 542 543 \begin{listing} 544 \nlst{namzdf_osm} 545 \caption{\forcode{&namzdf_osm}} 546 \label{lst:namzdf_osm} 547 \end{listing} 548 549 %-------------------------------------------------------------------------------------------------------------- 550 \paragraph{Namelist choices} 551 Most of the namelist options refer to how to specify the Stokes 552 surface drift and penetration depth. There are three options: 553 \begin{description} 554 \item \protect\np[=0]{nn_osm_wave}{nn\_osm\_wave} Default value in \texttt{namelist\_ref}. In this case the Stokes drift is 555 assumed to be parallel to the surface wind stress, with 556 magnitude consistent with a constant turbulent Langmuir number 557 $\mathrm{La}_t=$ \protect\np{rn_m_la} {rn\_m\_la} i.e.\ 558 $u_{s0}=\tau/(\mathrm{La}_t^2\rho_0)$. Default value of 559 \protect\np{rn_m_la}{rn\_m\_la} is 0.3. The Stokes penetration 560 depth $\delta = $ \protect\np{rn_osm_dstokes}{rn\_osm\_dstokes}; this has default value 561 of 5~m. 562 563 \item \protect\np[=1]{nn_osm_wave}{nn\_osm\_wave} In this case the Stokes drift is 564 assumed to be parallel to the surface wind stress, with 565 magnitude as in the classical Pierson-Moskowitz wind-sea 566 spectrum. Significant wave height and 567 wave-mean period taken from this spectrum are used to calculate the Stokes penetration 568 depth, following the approach set out in \citet{breivik.janssen.ea_JPO14}. 569 570 \item \protect\np[=2]{nn_osm_wave}{nn\_osm\_wave} In this case the Stokes drift is 571 taken from ECMWF wave model output, though only the component parallel 572 to the wind stress is retained. Significant wave height and 573 wave-mean period from ECMWF wave model output are used to calculate the Stokes penetration 574 depth, again following \citet{breivik.janssen.ea_JPO14}. 575 576 \end{description} 577 578 Others refer to the treatment of diffusion and viscosity beneath 579 the surface boundary layer: 580 \begin{description} 581 \item \protect\np{ln_kpprimix} {ln\_kpprimix} Default is \np{.true.}. Switches on KPP-style Ri \#-dependent 582 mixing below the surface boundary layer. If this is set 583 \texttt{.true.} the following variable settings are honoured: 584 \item \protect\np{rn_riinfty}{rn\_riinfty} Critical value of local Ri \# below which 585 shear instability increases vertical mixing from background value. 586 \item \protect\np{rn_difri} {rn\_difri} Maximum value of Ri \#-dependent mixing at $\mathrm{Ri}=0$. 587 \item \protect\np{ln_convmix}{ln\_convmix} If \texttt{.true.} then, where water column is unstable, specify 588 diffusivity equal to \protect\np{rn_dif_conv}{rn\_dif\_conv} (default value is 1 m~s$^{-2}$). 589 \end{description} 590 Diagnostic output is controlled by: 591 \begin{description} 592 \item \protect\np{ln_dia_osm}{ln\_dia\_osm} Default is \np{.false.}; allows XIOS output of OSMOSIS internal fields. 593 \end{description} 594 Obsolete namelist parameters include: 595 \begin{description} 596 \item \protect\np{ln_use_osm_la}\np{ln\_use\_osm\_la} With \protect\np[=0]{nn_osm_wave}{nn\_osm\_wave}, 597 \protect\np{rn_osm_dstokes} {rn\_osm\_dstokes} is always used to specify the Stokes 598 penetration depth. 599 \item \protect\np{nn_ave} {nn\_ave} Choice of averaging method for KPP-style Ri \# 600 mixing. Not taken account of. 601 \item \protect\np{rn_osm_hbl0} {rn\_osm\_hbl0} Depth of initial boundary layer is now set 602 by a density criterion similar to that used in calculating \emph{hmlp} (output as \texttt{mldr10\_1}) in \mdl{zdfmxl}. 603 \end{description} 604 605 \subsubsection{Summary} 606 Much of the time the turbulent motions in the ocean surface boundary 607 layer (OSBL) are not given by 608 classical shear turbulence. Instead they are in a regime known as 609 `Langmuir turbulence', dominated by an 610 interaction between the currents and the Stokes drift of the surface waves \citep[e.g.][]{mcwilliams.ea_JFM97}. 611 This regime is characterised by strong vertical turbulent motion, and appears when the surface Stokes drift $u_{s0}$ is much greater than the friction velocity $u_{\ast}$. More specifically Langmuir turbulence is thought to be crucial where the turbulent Langmuir number $\mathrm{La}_{t}=(u_{\ast}/u_{s0}) > 0.4$. 612 613 The OSMOSIS model is fundamentally based on results of Large Eddy 614 Simulations (LES) of Langmuir turbulence and aims to fully describe 615 this Langmuir regime. The description in this section is of necessity incomplete and further details are available in Grant. A (2019); in prep. 616 617 The OSMOSIS turbulent closure scheme is a similarity-scale scheme in 618 the same spirit as the K-profile 619 parameterization (KPP) scheme of \citet{large.ea_RG97}. 620 A specified shape of diffusivity, scaled by the (OSBL) depth 621 $h_{\mathrm{BL}}$ and a turbulent velocity scale, is imposed throughout the 622 boundary layer 623 $-h_{\mathrm{BL}}<z<\eta$. The turbulent closure model 624 also includes fluxes of tracers and momentum that are``non-local'' (independent of the local property gradient). 625 626 Rather than the OSBL 627 depth being diagnosed in terms of a bulk Richardson number criterion, 628 as in KPP, it is set by a prognostic equation that is informed by 629 energy budget considerations reminiscent of the classical mixed layer 630 models of \citet{kraus.turner_tellus67}. 631 The model also includes an explicit parametrization of the structure 632 of the pycnocline (the stratified region at the bottom of the OSBL). 633 634 Presently, mixing below the OSBL is handled by the Richardson 635 number-dependent mixing scheme used in \citet{large.ea_RG97}. 636 637 Convective parameterizations such as described in \ref{sec:ZDF_conv} 638 below should not be used with the OSMOSIS-OBL model: instabilities 639 within the OSBL are part of the model, while instabilities below the 640 ML are handled by the Ri \# dependent scheme. 641 642 \subsubsection{Depth and velocity scales} 643 The model supposes a boundary layer of thickness $h_{\mathrm{bl}}$ enclosing a well-mixed layer of thickness $h_{\mathrm{ml}}$ and a relatively thin pycnocline at the base of thickness $\Delta h$; Fig.~\ref{fig: OSBL_structure} shows typical (a) buoyancy structure and (b) turbulent buoyancy flux profile for the unstable boundary layer (losing buoyancy at the surface; e.g.\ cooling). 414 644 \begin{figure}[!t] 415 645 \begin{center} 416 \includegraphics[width=1.00\textwidth]{Fig_ZDF_TKE_time_scheme}646 %\includegraphics[width=0.7\textwidth]{ZDF_OSM_structure_of_OSBL} 417 647 \caption{ 418 \protect\label{fig: TKE_time_scheme}419 Illustration of the TKE time integration and its links to the momentum and tracer time integration.648 \protect\label{fig: OSBL_structure} 649 The structure of the entraining boundary layer. (a) Mean buoyancy profile. (b) Profile of the buoyancy flux. 420 650 } 421 \end{center} 651 \end{center} 422 652 \end{figure} 423 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 653 The pycnocline in the OSMOSIS scheme is assumed to have a finite thickness, and may include a number of model levels. This means that the OSMOSIS scheme must parametrize both the thickness of the pycnocline, and the turbulent fluxes within the pycnocline. 654 655 Consideration of the power input by wind acting on the Stokes drift suggests that the Langmuir turbulence has velocity scale: 656 \begin{equation}\label{eq:w_La} 657 w_{*L}= \left(u_*^2 u_{s\,0}\right)^{1/3}; 658 \end{equation} 659 but at times the Stokes drift may be weak due to e.g.\ ice cover, short fetch, misalignment with the surface stress, etc.\ so a composite velocity scale is assumed for the stable (warming) boundary layer: 660 \begin{equation}\label{eq:composite-nu} 661 \nu_{\ast}= \left\{ u_*^3 \left[1-\exp(-.5 \mathrm{La}_t^2)\right]+w_{*L}^3\right\}^{1/3}. 662 \end{equation} 663 For the unstable boundary layer this is merged with the standard convective velocity scale $w_{*C}=\left(\overline{w^\prime b^\prime}_0 \,h_\mathrm{ml}\right)^{1/3}$, where $\overline{w^\prime b^\prime}_0$ is the upwards surface buoyancy flux, to give: 664 \begin{equation}\label{eq:vel-scale-unstable} 665 \omega_* = \left(\nu_*^3 + 0.5 w_{*C}^3\right)^{1/3}. 666 \end{equation} 667 668 \subsubsection{The flux gradient model} 669 The flux-gradient relationships used in the OSMOSIS scheme take the form: 670 % 671 \begin{equation}\label{eq:flux-grad-gen} 672 \overline{w^\prime\chi^\prime}=-K\frac{\partial\overline{\chi}}{\partial z} + N_{\chi,s} +N_{\chi,b} +N_{\chi,t}, 673 \end{equation} 674 % 675 where $\chi$ is a general variable and $N_{\chi,s}, N_{\chi,b} \mathrm{and} N_{\chi,t}$ are the non-gradient terms, and represent the effects of the different terms in the turbulent flux-budget on the transport of $\chi$. $N_{\chi,s}$ represents the effects that the Stokes shear has on the transport of $\chi$, $N_{\chi,b}$ the effect of buoyancy, and $N_{\chi,t}$ the effect of the turbulent transport. The same general form for the flux-gradient relationship is used to parametrize the transports of momentum, heat and salinity. 676 677 In terms of the non-dimensionalized depth variables 678 % 679 \begin{equation}\label{eq:sigma} 680 \sigma_{\mathrm{ml}}= -z/h_{\mathrm{ml}}; \;\sigma_{\mathrm{bl}}= -z/h_{\mathrm{bl}}, 681 \end{equation} 682 % 683 in unstable conditions the eddy diffusivity ($K_d$) and eddy viscosity ($K_\nu$) profiles are parametrized as: 684 % 685 \begin{align}\label{eq:diff-unstable} 686 K_d=&0.8\, \omega_*\, h_{\mathrm{ml}} \, \sigma_{\mathrm{ml}} \left(1-\beta_d \sigma_{\mathrm{ml}}\right)^{3/2} 687 \\\label{eq:visc-unstable} 688 K_\nu =& 0.3\, \omega_* \,h_{\mathrm{ml}}\, \sigma_{\mathrm{ml}} \left(1-\beta_\nu \sigma_{\mathrm{ml}}\right)\left(1-\tfrac{1}{2}\sigma_{\mathrm{ml}}^2\right) 689 \end{align} 690 % 691 where $\beta_d$ and $\beta_\nu$ are parameters that are determined by matching Eqs \ref{eq:diff-unstable} and \ref{eq:visc-unstable} to the eddy diffusivity and viscosity at the base of the well-mixed layer, given by 692 % 693 \begin{equation}\label{eq:diff-wml-base} 694 K_{d,\mathrm{ml}}=K_{\nu,\mathrm{ml}}=\,0.16\,\omega_* \Delta h. 695 \end{equation} 696 % 697 For stable conditions the eddy diffusivity/viscosity profiles are given by: 698 % 699 \begin{align}\label{diff-stable} 700 K_d= & 0.75\,\, \nu_*\, h_{\mathrm{ml}}\,\, \exp\left[-2.8 \left(h_{\mathrm{bl}}/L_L\right)^2\right]\sigma_{\mathrm{ml}} \left(1-\sigma_{\mathrm{ml}}\right)^{3/2} \\\label{eq:visc-stable} 701 K_\nu = & 0.375\,\, \nu_*\, h_{\mathrm{ml}} \,\, \exp\left[-2.8 \left(h_{\mathrm{bl}}/L_L\right)^2\right] \sigma_{\mathrm{ml}} \left(1-\sigma_{\mathrm{ml}}\right)\left(1-\tfrac{1}{2}\sigma_{\mathrm{ml}}^2\right). 702 \end{align} 703 % 704 The shape of the eddy viscosity and diffusivity profiles is the same as the shape in the unstable OSBL. The eddy diffusivity/viscosity depends on the stability parameter $h_{\mathrm{bl}}/{L_L}$ where $ L_L$ is analogous to the Obukhov length, but for Langmuir turbulence: 705 \begin{equation}\label{eq:L_L} 706 L_L=-w_{*L}^3/\left<\overline{w^\prime b^\prime}\right>_L, 707 \end{equation} 708 with the mean turbulent buoyancy flux averaged over the boundary layer given in terms of its surface value $\overline{w^\prime b^\prime}_0$ and (downwards) )solar irradiance $I(z)$ by 709 \begin{equation} \label{eq:stable-av-buoy-flux} 710 \left<\overline{w^\prime b^\prime}\right>_L = \tfrac{1}{2} {\overline{w^\prime b^\prime}}_0-g\alpha_E\left[\tfrac{1}{2}(I(0)+I(-h))-\left<I\right>\right]. 711 \end{equation} 712 % 713 In unstable conditions the eddy diffusivity and viscosity depend on stability through the velocity scale $\omega_*$, which depends on the two velocity scales $\nu_*$ and $w_{*C}$. 714 715 Details of the non-gradient terms in \eqref{eq:flux-grad-gen} and of the fluxes within the pycnocline $-h_{\mathrm{bl}}<z<h_{\mathrm{ml}}$ can be found in Grant (2019). 716 717 \subsubsection{Evolution of the boundary layer depth} 718 719 The prognostic equation for the depth of the neutral/unstable boundary layer is given by \citep{grant+etal18}, 720 721 \begin{equation} \label{eq:dhdt-unstable} 722 %\frac{\partial h_\mathrm{bl}}{\partial t} + \mathbf{U}_b\cdot\nabla h_\mathrm{bl}= W_b - \frac{{\overline{w^\prime b^\prime}}_\mathrm{ent}}{\Delta B_\mathrm{bl}} 723 \frac{\partial h_\mathrm{bl}}{\partial t} = W_b - \frac{{\overline{w^\prime b^\prime}}_\mathrm{ent}}{\Delta B_\mathrm{bl}} 724 \end{equation} 725 where $h_\mathrm{bl}$ is the horizontally-varying depth of the OSBL, 726 $\mathbf{U}_b$ and $W_b$ are the mean horizontal and vertical 727 velocities at the base of the OSBL, ${\overline{w^\prime 728 b^\prime}}_\mathrm{ent}$ is the buoyancy flux due to entrainment 729 and $\Delta B_\mathrm{bl}$ is the difference between the buoyancy 730 averaged over the depth of the OSBL (i.e.\ including the ML and 731 pycnocline) and the buoyancy just below the base of the OSBL. This 732 equation for the case when the pycnocline has a finite thickness, 733 based on the potential energy budget of the OSBL, is the leading term 734 \citep{grant+etal18} of a generalization of that used in mixed-layer 735 models e.g.\ \citet{kraus.turner_tellus67}, in which the thickness of the pycnocline is taken to be zero. 736 737 The entrainment flux for the combination of convective and Langmuir turbulence is given by 738 \begin{equation} \label{eq:entrain-flux} 739 {\overline{w^\prime b^\prime}}_\mathrm{ent} = -\alpha_{\mathrm{B}} {\overline{w^\prime b^\prime}}_0 - \alpha_{\mathrm{S}} \frac{u_*^3}{h_{\mathrm{ml}}} 740 + G\left(\delta/h_{\mathrm{ml}} \right)\left[\alpha_{\mathrm{S}}e^{-1.5\, \mathrm{La}_t}-\alpha_{\mathrm{L}} \frac{w_{\mathrm{*L}}^3}{h_{\mathrm{ml}}}\right] 741 \end{equation} 742 where the factor $G\equiv 1 - \mathrm{e}^ {-25\delta/h_{\mathrm{bl}}}(1-4\delta/h_{\mathrm{bl}})$ models the lesser efficiency of Langmuir mixing when the boundary-layer depth is much greater than the Stokes depth, and $\alpha_{\mathrm{B}}$, $\alpha_{S}$ and $\alpha_{\mathrm{L}}$ depend on the ratio of the appropriate eddy turnover time to the inertial timescale $f^{-1}$. Results from the LES suggest $\alpha_{\mathrm{B}}=0.18 F(fh_{\mathrm{bl}}/w_{*C})$, $\alpha_{S}=0.15 F(fh_{\mathrm{bl}}/u_*$ and $\alpha_{\mathrm{L}}=0.035 F(fh_{\mathrm{bl}}/u_{*L})$, where $F(x)\equiv\tanh(x^{-1})^{0.69}$. 743 744 For the stable boundary layer, the equation for the depth of the OSBL is: 745 746 \begin{equation}\label{eq:dhdt-stable} 747 \max\left(\Delta B_{bl},\frac{w_{*L}^2}{h_\mathrm{bl}}\right)\frac{\partial h_\mathrm{bl}}{\partial t} = \left(0.06 + 0.52\,\frac{ h_\mathrm{bl}}{L_L}\right) \frac{w_{*L}^3}{h_\mathrm{bl}} +\left<\overline{w^\prime b^\prime}\right>_L. 748 \end{equation} 749 750 Equation. \ref{eq:dhdt-unstable} always leads to the depth of the entraining OSBL increasing (ignoring the effect of the mean vertical motion), but the change in the thickness of the stable OSBL given by Eq. \ref{eq:dhdt-stable} can be positive or negative, depending on the magnitudes of $\left<\overline{w^\prime b^\prime}\right>_L$ and $h_\mathrm{bl}/L_L$. The rate at which the depth of the OSBL can decrease is limited by choosing an effective buoyancy $w_{*L}^2/h_\mathrm{bl}$, in place of $\Delta B_{bl}$ which will be $\approx 0$ for the collapsing OSBL. 751 752 753 %% ================================================================================================= 754 \subsection[ Discrete energy conservation for TKE and GLS schemes]{Discrete energy conservation for TKE and GLS schemes} 755 \label{subsec:ZDF_tke_ene} 756 757 \begin{figure}[!t] 758 \centering 759 \includegraphics[width=0.66\textwidth]{ZDF_TKE_time_scheme} 760 \caption[Subgrid kinetic energy integration in GLS and TKE schemes]{ 761 Illustration of the subgrid kinetic energy integration in GLS and TKE schemes and 762 its links to the momentum and tracer time integration.} 763 \label{fig:ZDF_TKE_time_scheme} 764 \end{figure} 424 765 425 766 The production of turbulence by vertical shear (the first term of the right hand side of 426 \autoref{eq: zdftke_e}) should balance the loss of kinetic energy associated with the vertical momentum diffusion427 (first line in \autoref{eq: PE_zdf}).428 To do so a special care ha veto be taken for both the time and space discretization of429 the TKE equation \citep{Burchard_OM02,Marsaleix_al_OM08}.430 431 Let us first address the time stepping issue. \autoref{fig: TKE_time_scheme} shows how767 \autoref{eq:ZDF_tke_e}) and \autoref{eq:ZDF_gls_e}) should balance the loss of kinetic energy associated with the vertical momentum diffusion 768 (first line in \autoref{eq:MB_zdf}). 769 To do so a special care has to be taken for both the time and space discretization of 770 the kinetic energy equation \citep{burchard_OM02,marsaleix.auclair.ea_OM08}. 771 772 Let us first address the time stepping issue. \autoref{fig:ZDF_TKE_time_scheme} shows how 432 773 the two-level Leap-Frog time stepping of the momentum and tracer equations interplays with 433 the one-level forward time stepping of TKE equation.774 the one-level forward time stepping of the equation for $\bar{e}$. 434 775 With this framework, the total loss of kinetic energy (in 1D for the demonstration) due to 435 776 the vertical momentum diffusion is obtained by multiplying this quantity by $u^t$ and 436 summing the result vertically: 777 summing the result vertically: 437 778 \begin{equation} 438 \label{eq: energ1}779 \label{eq:ZDF_energ1} 439 780 \begin{split} 440 781 \int_{-H}^{\eta} u^t \,\partial_z &\left( {K_m}^t \,(\partial_z u)^{t+\rdt} \right) \,dz \\ … … 444 785 \end{equation} 445 786 Here, the vertical diffusion of momentum is discretized backward in time with a coefficient, $K_m$, 446 known at time $t$ (\autoref{fig: TKE_time_scheme}), as it is required when using the TKE scheme447 (see \autoref{sec: STP_forward_imp}).448 The first term of the right hand side of \autoref{eq: energ1} represents the kinetic energy transfer at787 known at time $t$ (\autoref{fig:ZDF_TKE_time_scheme}), as it is required when using the TKE scheme 788 (see \autoref{sec:TD_forward_imp}). 789 The first term of the right hand side of \autoref{eq:ZDF_energ1} represents the kinetic energy transfer at 449 790 the surface (atmospheric forcing) and at the bottom (friction effect). 450 791 The second term is always negative. 451 792 It is the dissipation rate of kinetic energy, and thus minus the shear production rate of $\bar{e}$. 452 \autoref{eq: energ1} implies that, to be energetically consistent,793 \autoref{eq:ZDF_energ1} implies that, to be energetically consistent, 453 794 the production rate of $\bar{e}$ used to compute $(\bar{e})^t$ (and thus ${K_m}^t$) should be expressed as 454 795 ${K_m}^{t-\rdt}\,(\partial_z u)^{t-\rdt} \,(\partial_z u)^t$ … … 456 797 457 798 A similar consideration applies on the destruction rate of $\bar{e}$ due to stratification 458 (second term of the right hand side of \autoref{eq: zdftke_e}).799 (second term of the right hand side of \autoref{eq:ZDF_tke_e} and \autoref{eq:ZDF_gls_e}). 459 800 This term must balance the input of potential energy resulting from vertical mixing. 460 The rate of change of potential energy (in 1D for the demonstration) due vertical mixing is obtained by461 multiplying vertical density diffusion tendency by $g\,z$ and and summing the result vertically:801 The rate of change of potential energy (in 1D for the demonstration) due to vertical mixing is obtained by 802 multiplying the vertical density diffusion tendency by $g\,z$ and and summing the result vertically: 462 803 \begin{equation} 463 \label{eq: energ2}804 \label{eq:ZDF_energ2} 464 805 \begin{split} 465 806 \int_{-H}^{\eta} g\,z\,\partial_z &\left( {K_\rho}^t \,(\partial_k \rho)^{t+\rdt} \right) \,dz \\ … … 470 811 \end{split} 471 812 \end{equation} 472 where we use $N^2 = -g \,\partial_k \rho / (e_3 \rho)$. 473 The first term of the right hand side of \autoref{eq: energ2} is always zero because813 where we use $N^2 = -g \,\partial_k \rho / (e_3 \rho)$. 814 The first term of the right hand side of \autoref{eq:ZDF_energ2} is always zero because 474 815 there is no diffusive flux through the ocean surface and bottom). 475 816 The second term is minus the destruction rate of $\bar{e}$ due to stratification. 476 Therefore \autoref{eq: energ1} implies that, to be energetically consistent,477 the product ${K_\rho}^{t-\rdt}\,(N^2)^t$ should be used in \autoref{eq: zdftke_e}, the TKE equation.817 Therefore \autoref{eq:ZDF_energ1} implies that, to be energetically consistent, 818 the product ${K_\rho}^{t-\rdt}\,(N^2)^t$ should be used in \autoref{eq:ZDF_tke_e} and \autoref{eq:ZDF_gls_e}. 478 819 479 820 Let us now address the space discretization issue. 480 821 The vertical eddy coefficients are defined at $w$-point whereas the horizontal velocity components are in 481 the centre of the side faces of a $t$-box in staggered C-grid (\autoref{fig: cell}).822 the centre of the side faces of a $t$-box in staggered C-grid (\autoref{fig:DOM_cell}). 482 823 A space averaging is thus required to obtain the shear TKE production term. 483 By redoing the \autoref{eq: energ1} in the 3D case, it can be shown that the product of eddy coefficient by824 By redoing the \autoref{eq:ZDF_energ1} in the 3D case, it can be shown that the product of eddy coefficient by 484 825 the shear at $t$ and $t-\rdt$ must be performed prior to the averaging. 485 Furthermore, the possible time variation of $e_3$ (\key{vvl} case) have tobe taken into account.826 Furthermore, the time variation of $e_3$ has be taken into account. 486 827 487 828 The above energetic considerations leads to the following final discrete form for the TKE equation: 488 829 \begin{equation} 489 \label{eq: zdftke_ene}830 \label{eq:ZDF_tke_ene} 490 831 \begin{split} 491 832 \frac { (\bar{e})^t - (\bar{e})^{t-\rdt} } {\rdt} \equiv … … 504 845 \end{split} 505 846 \end{equation} 506 where the last two terms in \autoref{eq: zdftke_ene} (vertical diffusion and Kolmogorov dissipation)507 are time stepped using a backward scheme (see\autoref{sec: STP_forward_imp}).847 where the last two terms in \autoref{eq:ZDF_tke_ene} (vertical diffusion and Kolmogorov dissipation) 848 are time stepped using a backward scheme (see\autoref{sec:TD_forward_imp}). 508 849 Note that the Kolmogorov term has been linearized in time in order to render the implicit computation possible. 509 The restart of the TKE scheme requires the storage of $\bar {e}$, $K_m$, $K_\rho$ and $l_\epsilon$ as 510 they all appear in the right hand side of \autoref{eq:zdftke_ene}. 511 For the latter, it is in fact the ratio $\sqrt{\bar{e}}/l_\epsilon$ which is stored. 512 513 % ------------------------------------------------------------------------------------------------------------- 514 % GLS Generic Length Scale Scheme 515 % ------------------------------------------------------------------------------------------------------------- 516 \subsection{GLS: Generic Length Scale (\protect\key{zdfgls})} 517 \label{subsec:ZDF_gls} 518 519 %--------------------------------------------namzdf_gls--------------------------------------------------------- 520 521 \nlst{namzdf_gls} 522 %-------------------------------------------------------------------------------------------------------------- 523 524 The Generic Length Scale (GLS) scheme is a turbulent closure scheme based on two prognostic equations: 525 one for the turbulent kinetic energy $\bar {e}$, and another for the generic length scale, 526 $\psi$ \citep{Umlauf_Burchard_JMS03, Umlauf_Burchard_CSR05}. 527 This later variable is defined as: $\psi = {C_{0\mu}}^{p} \ {\bar{e}}^{m} \ l^{n}$, 528 where the triplet $(p, m, n)$ value given in Tab.\autoref{tab:GLS} allows to recover a number of 529 well-known turbulent closures ($k$-$kl$ \citep{Mellor_Yamada_1982}, $k$-$\epsilon$ \citep{Rodi_1987}, 530 $k$-$\omega$ \citep{Wilcox_1988} among others \citep{Umlauf_Burchard_JMS03,Kantha_Carniel_CSR05}). 531 The GLS scheme is given by the following set of equations: 532 \begin{equation} 533 \label{eq:zdfgls_e} 534 \frac{\partial \bar{e}}{\partial t} = 535 \frac{K_m}{\sigma_e e_3 }\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2 536 +\left( \frac{\partial v}{\partial k} \right)^2} \right] 537 -K_\rho \,N^2 538 +\frac{1}{e_3}\,\frac{\partial}{\partial k} \left[ \frac{K_m}{e_3}\,\frac{\partial \bar{e}}{\partial k} \right] 539 - \epsilon 540 \end{equation} 541 542 \[ 543 % \label{eq:zdfgls_psi} 544 \begin{split} 545 \frac{\partial \psi}{\partial t} =& \frac{\psi}{\bar{e}} \left\{ 546 \frac{C_1\,K_m}{\sigma_{\psi} {e_3}}\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2 547 +\left( \frac{\partial v}{\partial k} \right)^2} \right] 548 - C_3 \,K_\rho\,N^2 - C_2 \,\epsilon \,Fw \right\} \\ 549 &+\frac{1}{e_3} \;\frac{\partial }{\partial k}\left[ {\frac{K_m}{e_3 } 550 \;\frac{\partial \psi}{\partial k}} \right]\; 551 \end{split} 552 \] 553 554 \[ 555 % \label{eq:zdfgls_kz} 556 \begin{split} 557 K_m &= C_{\mu} \ \sqrt {\bar{e}} \ l \\ 558 K_\rho &= C_{\mu'}\ \sqrt {\bar{e}} \ l 559 \end{split} 560 \] 561 562 \[ 563 % \label{eq:zdfgls_eps} 564 {\epsilon} = C_{0\mu} \,\frac{\bar {e}^{3/2}}{l} \; 565 \] 566 where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}) and 567 $\epsilon$ the dissipation rate. 568 The constants $C_1$, $C_2$, $C_3$, ${\sigma_e}$, ${\sigma_{\psi}}$ and the wall function ($Fw$) depends of 569 the choice of the turbulence model. 570 Four different turbulent models are pre-defined (Tab.\autoref{tab:GLS}). 571 They are made available through the \np{nn\_clo} namelist parameter. 572 573 %--------------------------------------------------TABLE-------------------------------------------------- 574 \begin{table}[htbp] 575 \begin{center} 576 % \begin{tabular}{cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}c} 577 \begin{tabular}{ccccc} 578 & $k-kl$ & $k-\epsilon$ & $k-\omega$ & generic \\ 579 % & \citep{Mellor_Yamada_1982} & \citep{Rodi_1987} & \citep{Wilcox_1988} & \\ 580 \hline 581 \hline 582 \np{nn\_clo} & \textbf{0} & \textbf{1} & \textbf{2} & \textbf{3} \\ 583 \hline 584 $( p , n , m )$ & ( 0 , 1 , 1 ) & ( 3 , 1.5 , -1 ) & ( -1 , 0.5 , -1 ) & ( 2 , 1 , -0.67 ) \\ 585 $\sigma_k$ & 2.44 & 1. & 2. & 0.8 \\ 586 $\sigma_\psi$ & 2.44 & 1.3 & 2. & 1.07 \\ 587 $C_1$ & 0.9 & 1.44 & 0.555 & 1. \\ 588 $C_2$ & 0.5 & 1.92 & 0.833 & 1.22 \\ 589 $C_3$ & 1. & 1. & 1. & 1. \\ 590 $F_{wall}$ & Yes & -- & -- & -- \\ 591 \hline 592 \hline 593 \end{tabular} 594 \caption{ 595 \protect\label{tab:GLS} 596 Set of predefined GLS parameters, or equivalently predefined turbulence models available with 597 \protect\key{zdfgls} and controlled by the \protect\np{nn\_clos} namelist variable in \protect\ngn{namzdf\_gls}. 598 } 599 \end{center} 600 \end{table} 601 %-------------------------------------------------------------------------------------------------------------- 602 603 In the Mellor-Yamada model, the negativity of $n$ allows to use a wall function to force the convergence of 604 the mixing length towards $K z_b$ ($K$: Kappa and $z_b$: rugosity length) value near physical boundaries 605 (logarithmic boundary layer law). 606 $C_{\mu}$ and $C_{\mu'}$ are calculated from stability function proposed by \citet{Galperin_al_JAS88}, 607 or by \citet{Kantha_Clayson_1994} or one of the two functions suggested by \citet{Canuto_2001} 608 (\np{nn\_stab\_func}\forcode{ = 0..3}, resp.). 609 The value of $C_{0\mu}$ depends of the choice of the stability function. 610 611 The surface and bottom boundary condition on both $\bar{e}$ and $\psi$ can be calculated thanks to Dirichlet or 612 Neumann condition through \np{nn\_tkebc\_surf} and \np{nn\_tkebc\_bot}, resp. 613 As for TKE closure, the wave effect on the mixing is considered when 614 \np{ln\_crban}\forcode{ = .true.} \citep{Craig_Banner_JPO94, Mellor_Blumberg_JPO04}. 615 The \np{rn\_crban} namelist parameter is $\alpha_{CB}$ in \autoref{eq:ZDF_Esbc} and 616 \np{rn\_charn} provides the value of $\beta$ in \autoref{eq:ZDF_Lsbc}. 617 618 The $\psi$ equation is known to fail in stably stratified flows, and for this reason 619 almost all authors apply a clipping of the length scale as an \textit{ad hoc} remedy. 620 With this clipping, the maximum permissible length scale is determined by $l_{max} = c_{lim} \sqrt{2\bar{e}}/ N$. 621 A value of $c_{lim} = 0.53$ is often used \citep{Galperin_al_JAS88}. 622 \cite{Umlauf_Burchard_CSR05} show that the value of the clipping factor is of crucial importance for 623 the entrainment depth predicted in stably stratified situations, 624 and that its value has to be chosen in accordance with the algebraic model for the turbulent fluxes. 625 The clipping is only activated if \np{ln\_length\_lim}\forcode{ = .true.}, 626 and the $c_{lim}$ is set to the \np{rn\_clim\_galp} value. 627 628 The time and space discretization of the GLS equations follows the same energetic consideration as for 629 the TKE case described in \autoref{subsec:ZDF_tke_ene} \citep{Burchard_OM02}. 630 Examples of performance of the 4 turbulent closure scheme can be found in \citet{Warner_al_OM05}. 631 632 % ------------------------------------------------------------------------------------------------------------- 633 % OSM OSMOSIS BL Scheme 634 % ------------------------------------------------------------------------------------------------------------- 635 \subsection{OSM: OSMOSIS boundary layer scheme (\protect\key{zdfosm})} 636 \label{subsec:ZDF_osm} 637 638 %--------------------------------------------namzdf_osm--------------------------------------------------------- 639 640 \nlst{namzdf_osm} 641 %-------------------------------------------------------------------------------------------------------------- 642 643 The OSMOSIS turbulent closure scheme is based on...... TBC 644 645 % ================================================================ 646 % Convection 647 % ================================================================ 850 %The restart of the TKE scheme requires the storage of $\bar {e}$, $K_m$, $K_\rho$ and $l_\epsilon$ as 851 %they all appear in the right hand side of \autoref{eq:ZDF_tke_ene}. 852 %For the latter, it is in fact the ratio $\sqrt{\bar{e}}/l_\epsilon$ which is stored. 853 854 %% ================================================================================================= 648 855 \section{Convection} 649 856 \label{sec:ZDF_conv} 650 857 651 %--------------------------------------------namzdf-------------------------------------------------------- 652 653 \nlst{namzdf} 654 %-------------------------------------------------------------------------------------------------------------- 655 656 Static instabilities (\ie light potential densities under heavy ones) may occur at particular ocean grid points. 858 Static instabilities (\ie\ light potential densities under heavy ones) may occur at particular ocean grid points. 657 859 In nature, convective processes quickly re-establish the static stability of the water column. 658 860 These processes have been removed from the model via the hydrostatic assumption so they must be parameterized. … … 661 863 or/and the use of a turbulent closure scheme. 662 864 663 % ------------------------------------------------------------------------------------------------------------- 664 % Non-Penetrative Convective Adjustment 665 % ------------------------------------------------------------------------------------------------------------- 666 \subsection[Non-penetrative convective adjmt (\protect\np{ln\_tranpc}\forcode{ = .true.})] 667 {Non-penetrative convective adjustment (\protect\np{ln\_tranpc}\forcode{ = .true.})} 865 %% ================================================================================================= 866 \subsection[Non-penetrative convective adjustment (\forcode{ln_tranpc})]{Non-penetrative convective adjustment (\protect\np{ln_tranpc}{ln\_tranpc})} 668 867 \label{subsec:ZDF_npc} 669 868 670 %--------------------------------------------namzdf--------------------------------------------------------671 672 \nlst{namzdf}673 %--------------------------------------------------------------------------------------------------------------674 675 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>676 869 \begin{figure}[!htb] 677 \begin{center} 678 \includegraphics[width=0.90\textwidth]{Fig_npc} 679 \caption{ 680 \protect\label{fig:npc} 681 Example of an unstable density profile treated by the non penetrative convective adjustment algorithm. 682 $1^{st}$ step: the initial profile is checked from the surface to the bottom. 683 It is found to be unstable between levels 3 and 4. 684 They are mixed. 685 The resulting $\rho$ is still larger than $\rho$(5): levels 3 to 5 are mixed. 686 The resulting $\rho$ is still larger than $\rho$(6): levels 3 to 6 are mixed. 687 The $1^{st}$ step ends since the density profile is then stable below the level 3. 688 $2^{nd}$ step: the new $\rho$ profile is checked following the same procedure as in $1^{st}$ step: 689 levels 2 to 5 are mixed. 690 The new density profile is checked. 691 It is found stable: end of algorithm. 692 } 693 \end{center} 870 \centering 871 \includegraphics[width=0.66\textwidth]{ZDF_npc} 872 \caption[Unstable density profile treated by the non penetrative convective adjustment algorithm]{ 873 Example of an unstable density profile treated by 874 the non penetrative convective adjustment algorithm. 875 $1^{st}$ step: the initial profile is checked from the surface to the bottom. 876 It is found to be unstable between levels 3 and 4. 877 They are mixed. 878 The resulting $\rho$ is still larger than $\rho$(5): levels 3 to 5 are mixed. 879 The resulting $\rho$ is still larger than $\rho$(6): levels 3 to 6 are mixed. 880 The $1^{st}$ step ends since the density profile is then stable below the level 3. 881 $2^{nd}$ step: the new $\rho$ profile is checked following the same procedure as in $1^{st}$ step: 882 levels 2 to 5 are mixed. 883 The new density profile is checked. 884 It is found stable: end of algorithm.} 885 \label{fig:ZDF_npc} 694 886 \end{figure} 695 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 696 697 Options are defined through the \ngn{namzdf} namelist variables. 698 The non-penetrative convective adjustment is used when \np{ln\_zdfnpc}\forcode{ = .true.}. 699 It is applied at each \np{nn\_npc} time step and mixes downwards instantaneously the statically unstable portion of 887 888 Options are defined through the \nam{zdf}{zdf} namelist variables. 889 The non-penetrative convective adjustment is used when \np[=.true.]{ln_zdfnpc}{ln\_zdfnpc}. 890 It is applied at each \np{nn_npc}{nn\_npc} time step and mixes downwards instantaneously the statically unstable portion of 700 891 the water column, but only until the density structure becomes neutrally stable 701 (\ie until the mixed portion of the water column has \textit{exactly} the density of the water just below)702 \citep{ Madec_al_JPO91}.703 The associated algorithm is an iterative process used in the following way (\autoref{fig: npc}):892 (\ie\ until the mixed portion of the water column has \textit{exactly} the density of the water just below) 893 \citep{madec.delecluse.ea_JPO91}. 894 The associated algorithm is an iterative process used in the following way (\autoref{fig:ZDF_npc}): 704 895 starting from the top of the ocean, the first instability is found. 705 896 Assume in the following that the instability is located between levels $k$ and $k+1$. … … 716 907 This algorithm is significantly different from mixing statically unstable levels two by two. 717 908 The latter procedure cannot converge with a finite number of iterations for some vertical profiles while 718 the algorithm used in \NEMO converges for any profile in a number of iterations which is less than909 the algorithm used in \NEMO\ converges for any profile in a number of iterations which is less than 719 910 the number of vertical levels. 720 This property is of paramount importance as pointed out by \citet{ Killworth1989}:911 This property is of paramount importance as pointed out by \citet{killworth_iprc89}: 721 912 it avoids the existence of permanent and unrealistic static instabilities at the sea surface. 722 913 This non-penetrative convective algorithm has been proved successful in studies of the deep water formation in 723 the north-western Mediterranean Sea \citep{ Madec_al_JPO91, Madec_al_DAO91, Madec_Crepon_Bk91}.914 the north-western Mediterranean Sea \citep{madec.delecluse.ea_JPO91, madec.chartier.ea_DAO91, madec.crepon_iprc91}. 724 915 725 916 The current implementation has been modified in order to deal with any non linear equation of seawater 726 917 (L. Brodeau, personnal communication). 727 918 Two main differences have been introduced compared to the original algorithm: 728 $(i)$ the stability is now checked using the Brunt-V\"{a}is\"{a}l\"{a} frequency 729 (not the the difference in potential density);919 $(i)$ the stability is now checked using the Brunt-V\"{a}is\"{a}l\"{a} frequency 920 (not the difference in potential density); 730 921 $(ii)$ when two levels are found unstable, their thermal and haline expansion coefficients are vertically mixed in 731 922 the same way their temperature and salinity has been mixed. … … 733 924 having to recompute the expansion coefficients at each mixing iteration. 734 925 735 % ------------------------------------------------------------------------------------------------------------- 736 % Enhanced Vertical Diffusion 737 % ------------------------------------------------------------------------------------------------------------- 738 \subsection{Enhanced vertical diffusion (\protect\np{ln\_zdfevd}\forcode{ = .true.})} 926 %% ================================================================================================= 927 \subsection[Enhanced vertical diffusion (\forcode{ln_zdfevd})]{Enhanced vertical diffusion (\protect\np{ln_zdfevd}{ln\_zdfevd})} 739 928 \label{subsec:ZDF_evd} 740 929 741 %--------------------------------------------namzdf-------------------------------------------------------- 742 743 \nlst{namzdf} 744 %-------------------------------------------------------------------------------------------------------------- 745 746 Options are defined through the \ngn{namzdf} namelist variables. 747 The enhanced vertical diffusion parameterisation is used when \np{ln\_zdfevd}\forcode{ = .true.}. 930 Options are defined through the \nam{zdf}{zdf} namelist variables. 931 The enhanced vertical diffusion parameterisation is used when \np[=.true.]{ln_zdfevd}{ln\_zdfevd}. 748 932 In this case, the vertical eddy mixing coefficients are assigned very large values 749 (a typical value is $10\;m^2s^{-1})$in regions where the stratification is unstable750 (\ie when $N^2$ the Brunt-Vais\"{a}l\"{a} frequency is negative) \citep{Lazar_PhD97, Lazar_al_JPO99}.751 This is done either on tracers only (\np {nn\_evdm}\forcode{ = 0}) or752 on both momentum and tracers (\np {nn\_evdm}\forcode{ = 1}).753 754 In practice, where $N^2\leq 10^{-12}$, $A_T^{vT}$ and $A_T^{vS}$, and if \np {nn\_evdm}\forcode{ = 1},933 in regions where the stratification is unstable 934 (\ie\ when $N^2$ the Brunt-Vais\"{a}l\"{a} frequency is negative) \citep{lazar_phd97, lazar.madec.ea_JPO99}. 935 This is done either on tracers only (\np[=0]{nn_evdm}{nn\_evdm}) or 936 on both momentum and tracers (\np[=1]{nn_evdm}{nn\_evdm}). 937 938 In practice, where $N^2\leq 10^{-12}$, $A_T^{vT}$ and $A_T^{vS}$, and if \np[=1]{nn_evdm}{nn\_evdm}, 755 939 the four neighbouring $A_u^{vm} \;\mbox{and}\;A_v^{vm}$ values also, are set equal to 756 the namelist parameter \np{rn \_avevd}.940 the namelist parameter \np{rn_avevd}{rn\_avevd}. 757 941 A typical value for $rn\_avevd$ is between 1 and $100~m^2.s^{-1}$. 758 942 This parameterisation of convective processes is less time consuming than 759 943 the convective adjustment algorithm presented above when mixing both tracers and 760 944 momentum in the case of static instabilities. 761 It requires the use of an implicit time stepping on vertical diffusion terms762 (\ie np{ln\_zdfexp}\forcode{ = .false.}).763 945 764 946 Note that the stability test is performed on both \textit{before} and \textit{now} values of $N^2$. 765 947 This removes a potential source of divergence of odd and even time step in 766 a leapfrog environment \citep{Leclair_PhD2010} (see \autoref{sec:STP_mLF}). 767 768 % ------------------------------------------------------------------------------------------------------------- 769 % Turbulent Closure Scheme 770 % ------------------------------------------------------------------------------------------------------------- 771 \subsection[Turbulent closure scheme (\protect\key{zdf}\{tke,gls,osm\})]{Turbulent Closure Scheme (\protect\key{zdftke}, \protect\key{zdfgls} or \protect\key{zdfosm})} 948 a leapfrog environment \citep{leclair_phd10} (see \autoref{sec:TD_mLF}). 949 950 %% ================================================================================================= 951 \subsection[Handling convection with turbulent closure schemes (\forcode{ln_zdf_}\{\forcode{tke,gls,osm}\})]{Handling convection with turbulent closure schemes (\forcode{ln_zdf{tke,gls,osm}})} 772 952 \label{subsec:ZDF_tcs} 773 953 774 The turbulent closure scheme presented in \autoref{subsec:ZDF_tke} and \autoref{subsec:ZDF_gls} 775 (\key{zdftke} or \key{zdftke} is defined) in theory solves the problem of statically unstable density profiles. 954 The turbulent closure schemes presented in \autoref{subsec:ZDF_tke}, \autoref{subsec:ZDF_gls} and 955 \autoref{subsec:ZDF_osm} (\ie\ \np{ln_zdftke}{ln\_zdftke} or \np{ln_zdfgls}{ln\_zdfgls} or \np{ln_zdfosm}{ln\_zdfosm} defined) deal, in theory, 956 with statically unstable density profiles. 776 957 In such a case, the term corresponding to the destruction of turbulent kinetic energy through stratification in 777 \autoref{eq: zdftke_e} or \autoref{eq:zdfgls_e} becomes a source term, since $N^2$ is negative.778 It results in large values of $A_T^{vT}$ and $A_T^{vT}$, and also the four neighbouring $A_u^{vm} {and}\;A_v^{vm}$779 (up to $1\;m^2s^{-1}$).958 \autoref{eq:ZDF_tke_e} or \autoref{eq:ZDF_gls_e} becomes a source term, since $N^2$ is negative. 959 It results in large values of $A_T^{vT}$ and $A_T^{vT}$, and also of the four neighboring values at 960 velocity points $A_u^{vm} {and}\;A_v^{vm}$ (up to $1\;m^2s^{-1}$). 780 961 These large values restore the static stability of the water column in a way similar to that of 781 962 the enhanced vertical diffusion parameterisation (\autoref{subsec:ZDF_evd}). … … 784 965 because the mixing length scale is bounded by the distance to the sea surface. 785 966 It can thus be useful to combine the enhanced vertical diffusion with the turbulent closure scheme, 786 \ie setting the \np{ln\_zdfnpc} namelist parameter to true and787 defining the turbulent closure CPP keyall together.788 789 The KPPturbulent closure scheme already includes enhanced vertical diffusion in the case of convection,790 as governed by the variables $bvsqcon$ and $difcon$ found in \mdl{zdfkpp},791 therefore \np {ln\_zdfevd}\forcode{ = .false.} should be used with the KPPscheme.967 \ie\ setting the \np{ln_zdfnpc}{ln\_zdfnpc} namelist parameter to true and 968 defining the turbulent closure (\np{ln_zdftke}{ln\_zdftke} or \np{ln_zdfgls}{ln\_zdfgls} = \forcode{.true.}) all together. 969 970 The OSMOSIS turbulent closure scheme already includes enhanced vertical diffusion in the case of convection, 971 %as governed by the variables $bvsqcon$ and $difcon$ found in \mdl{zdfkpp}, 972 therefore \np[=.false.]{ln_zdfevd}{ln\_zdfevd} should be used with the OSMOSIS scheme. 792 973 % gm% + one word on non local flux with KPP scheme trakpp.F90 module... 793 974 794 % ================================================================ 795 % Double Diffusion Mixing 796 % ================================================================ 797 \section{Double diffusion mixing (\protect\key{zdfddm})} 798 \label{sec:ZDF_ddm} 799 800 %-------------------------------------------namzdf_ddm------------------------------------------------- 801 % 975 %% ================================================================================================= 976 \section[Double diffusion mixing (\forcode{ln_zdfddm})]{Double diffusion mixing (\protect\np{ln_zdfddm}{ln\_zdfddm})} 977 \label{subsec:ZDF_ddm} 978 802 979 %\nlst{namzdf_ddm} 803 %-------------------------------------------------------------------------------------------------------------- 804 805 Options are defined through the \ngn{namzdf\_ddm} namelist variables.980 981 This parameterisation has been introduced in \mdl{zdfddm} module and is controlled by the namelist parameter 982 \np{ln_zdfddm}{ln\_zdfddm} in \nam{zdf}{zdf}. 806 983 Double diffusion occurs when relatively warm, salty water overlies cooler, fresher water, or vice versa. 807 984 The former condition leads to salt fingering and the latter to diffusive convection. 808 985 Double-diffusive phenomena contribute to diapycnal mixing in extensive regions of the ocean. 809 \citet{ Merryfield1999} include a parameterisation of such phenomena in a global ocean model and show that986 \citet{merryfield.holloway.ea_JPO99} include a parameterisation of such phenomena in a global ocean model and show that 810 987 it leads to relatively minor changes in circulation but exerts significant regional influences on 811 988 temperature and salinity. 812 This parameterisation has been introduced in \mdl{zdfddm} module and is controlled by the \key{zdfddm} CPP key. 813 814 Diapycnal mixing of S and T are described by diapycnal diffusion coefficients 989 990 Diapycnal mixing of S and T are described by diapycnal diffusion coefficients 815 991 \begin{align*} 816 % \label{eq: zdfddm_Kz}992 % \label{eq:ZDF_ddm_Kz} 817 993 &A^{vT} = A_o^{vT}+A_f^{vT}+A_d^{vT} \\ 818 994 &A^{vS} = A_o^{vS}+A_f^{vS}+A_d^{vS} … … 826 1002 (1981): 827 1003 \begin{align} 828 \label{eq: zdfddm_f}1004 \label{eq:ZDF_ddm_f} 829 1005 A_f^{vS} &= 830 1006 \begin{cases} … … 832 1008 0 &\text{otherwise} 833 1009 \end{cases} 834 \\ \label{eq: zdfddm_f_T}835 A_f^{vT} &= 0.7 \ A_f^{vS} / R_\rho 1010 \\ \label{eq:ZDF_ddm_f_T} 1011 A_f^{vT} &= 0.7 \ A_f^{vS} / R_\rho 836 1012 \end{align} 837 1013 838 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>839 1014 \begin{figure}[!t] 840 \begin{center} 841 \includegraphics[width=0.99\textwidth]{Fig_zdfddm} 842 \caption{ 843 \protect\label{fig:zdfddm} 844 From \citet{Merryfield1999} : 845 (a) Diapycnal diffusivities $A_f^{vT}$ and $A_f^{vS}$ for temperature and salt in regions of salt fingering. 846 Heavy curves denote $A^{\ast v} = 10^{-3}~m^2.s^{-1}$ and thin curves $A^{\ast v} = 10^{-4}~m^2.s^{-1}$; 847 (b) diapycnal diffusivities $A_d^{vT}$ and $A_d^{vS}$ for temperature and salt in regions of 848 diffusive convection. 849 Heavy curves denote the Federov parameterisation and thin curves the Kelley parameterisation. 850 The latter is not implemented in \NEMO. 851 } 852 \end{center} 1015 \centering 1016 \includegraphics[width=0.66\textwidth]{ZDF_ddm} 1017 \caption[Diapycnal diffusivities for temperature and salt in regions of salt fingering and 1018 diffusive convection]{ 1019 From \citet{merryfield.holloway.ea_JPO99}: 1020 (a) Diapycnal diffusivities $A_f^{vT}$ and $A_f^{vS}$ for temperature and salt in 1021 regions of salt fingering. 1022 Heavy curves denote $A^{\ast v} = 10^{-3}~m^2.s^{-1}$ and 1023 thin curves $A^{\ast v} = 10^{-4}~m^2.s^{-1}$; 1024 (b) diapycnal diffusivities $A_d^{vT}$ and $A_d^{vS}$ for temperature and salt in 1025 regions of diffusive convection. 1026 Heavy curves denote the Federov parameterisation and thin curves the Kelley parameterisation. 1027 The latter is not implemented in \NEMO.} 1028 \label{fig:ZDF_ddm} 853 1029 \end{figure} 854 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 855 856 The factor 0.7 in \autoref{eq:zdfddm_f_T} reflects the measured ratio $\alpha F_T /\beta F_S \approx 0.7$ of 857 buoyancy flux of heat to buoyancy flux of salt (\eg, \citet{McDougall_Taylor_JMR84}). 858 Following \citet{Merryfield1999}, we adopt $R_c = 1.6$, $n = 6$, and $A^{\ast v} = 10^{-4}~m^2.s^{-1}$. 1030 1031 The factor 0.7 in \autoref{eq:ZDF_ddm_f_T} reflects the measured ratio $\alpha F_T /\beta F_S \approx 0.7$ of 1032 buoyancy flux of heat to buoyancy flux of salt (\eg, \citet{mcdougall.taylor_JMR84}). 1033 Following \citet{merryfield.holloway.ea_JPO99}, we adopt $R_c = 1.6$, $n = 6$, and $A^{\ast v} = 10^{-4}~m^2.s^{-1}$. 859 1034 860 1035 To represent mixing of S and T by diffusive layering, the diapycnal diffusivities suggested by 861 Federov (1988) is used: 1036 Federov (1988) is used: 862 1037 \begin{align} 863 % \label{eq: zdfddm_d}1038 % \label{eq:ZDF_ddm_d} 864 1039 A_d^{vT} &= 865 1040 \begin{cases} … … 869 1044 \end{cases} 870 1045 \nonumber \\ 871 \label{eq: zdfddm_d_S}1046 \label{eq:ZDF_ddm_d_S} 872 1047 A_d^{vS} &= 873 1048 \begin{cases} … … 878 1053 \end{align} 879 1054 880 The dependencies of \autoref{eq: zdfddm_f} to \autoref{eq:zdfddm_d_S} on $R_\rho$ are illustrated in881 \autoref{fig: zdfddm}.1055 The dependencies of \autoref{eq:ZDF_ddm_f} to \autoref{eq:ZDF_ddm_d_S} on $R_\rho$ are illustrated in 1056 \autoref{fig:ZDF_ddm}. 882 1057 Implementing this requires computing $R_\rho$ at each grid point on every time step. 883 1058 This is done in \mdl{eosbn2} at the same time as $N^2$ is computed. 884 1059 This avoids duplication in the computation of $\alpha$ and $\beta$ (which is usually quite expensive). 885 1060 886 % ================================================================ 887 % Bottom Friction 888 % ================================================================ 889 \section{Bottom and top friction (\protect\mdl{zdfbfr})} 890 \label{sec:ZDF_bfr} 891 892 %--------------------------------------------nambfr-------------------------------------------------------- 893 % 894 %\nlst{nambfr} 895 %-------------------------------------------------------------------------------------------------------------- 896 897 Options to define the top and bottom friction are defined through the \ngn{nambfr} namelist variables. 1061 %% ================================================================================================= 1062 \section[Bottom and top friction (\textit{zdfdrg.F90})]{Bottom and top friction (\protect\mdl{zdfdrg})} 1063 \label{sec:ZDF_drg} 1064 1065 \begin{listing} 1066 \nlst{namdrg} 1067 \caption{\forcode{&namdrg}} 1068 \label{lst:namdrg} 1069 \end{listing} 1070 \begin{listing} 1071 \nlst{namdrg_top} 1072 \caption{\forcode{&namdrg_top}} 1073 \label{lst:namdrg_top} 1074 \end{listing} 1075 \begin{listing} 1076 \nlst{namdrg_bot} 1077 \caption{\forcode{&namdrg_bot}} 1078 \label{lst:namdrg_bot} 1079 \end{listing} 1080 1081 Options to define the top and bottom friction are defined through the \nam{drg}{drg} namelist variables. 898 1082 The bottom friction represents the friction generated by the bathymetry. 899 1083 The top friction represents the friction generated by the ice shelf/ocean interface. 900 As the friction processes at the top and bottom are treated in similar way, 901 only the bottom friction is described in detail below. 902 1084 As the friction processes at the top and the bottom are treated in and identical way, 1085 the description below considers mostly the bottom friction case, if not stated otherwise. 903 1086 904 1087 Both the surface momentum flux (wind stress) and the bottom momentum flux (bottom friction) enter the equations as 905 1088 a condition on the vertical diffusive flux. 906 1089 For the bottom boundary layer, one has: 907 \[908 % \label{eq:zdfbfr_flux}909 A^{vm} \left( \partial {\textbf U}_h / \partial z \right) = {{\cal F}}_h^{\textbf U}910 \]1090 \[ 1091 % \label{eq:ZDF_bfr_flux} 1092 A^{vm} \left( \partial {\textbf U}_h / \partial z \right) = {{\cal F}}_h^{\textbf U} 1093 \] 911 1094 where ${\cal F}_h^{\textbf U}$ is represents the downward flux of horizontal momentum outside 912 1095 the logarithmic turbulent boundary layer (thickness of the order of 1~m in the ocean). … … 916 1099 one needs a vertical diffusion coefficient $A^{vm} = 0.125$~m$^2$s$^{-1}$ 917 1100 (for a Coriolis frequency $f = 10^{-4}$~m$^2$s$^{-1}$). 918 With a background diffusion coefficient $A^{vm} = 10^{-4}$~m$^2$s$^{-1}$, the Ekman layer depth is only 1.4~m. 1101 With a background diffusion coefficient $A^{vm} = 10^{-4}$~m$^2$s$^{-1}$, the Ekman layer depth is only 1.4~m. 919 1102 When the vertical mixing coefficient is this small, using a flux condition is equivalent to 920 1103 entering the viscous forces (either wind stress or bottom friction) as a body force over the depth of the top or … … 922 1105 To illustrate this, consider the equation for $u$ at $k$, the last ocean level: 923 1106 \begin{equation} 924 \label{eq: zdfbfr_flux2}1107 \label{eq:ZDF_drg_flux2} 925 1108 \frac{\partial u_k}{\partial t} = \frac{1}{e_{3u}} \left[ \frac{A_{uw}^{vm}}{e_{3uw}} \delta_{k+1/2}\;[u] - {\cal F}^u_h \right] \approx - \frac{{\cal F}^u_{h}}{e_{3u}} 926 1109 \end{equation} … … 935 1118 936 1119 In the code, the bottom friction is imposed by adding the trend due to the bottom friction to 937 the general momentum trend in \mdl{dynbfr}.1120 the general momentum trend in \mdl{dynzdf}. 938 1121 For the time-split surface pressure gradient algorithm, the momentum trend due to 939 1122 the barotropic component needs to be handled separately. 940 1123 For this purpose it is convenient to compute and store coefficients which can be simply combined with 941 1124 bottom velocities and geometric values to provide the momentum trend due to bottom friction. 942 These coefficients are computed in \mdl{zdfbfr} and generally take the form $c_b^{\textbf U}$ where:1125 These coefficients are computed in \mdl{zdfdrg} and generally take the form $c_b^{\textbf U}$ where: 943 1126 \begin{equation} 944 \label{eq: zdfbfr_bdef}1127 \label{eq:ZDF_bfr_bdef} 945 1128 \frac{\partial {\textbf U_h}}{\partial t} = 946 1129 - \frac{{\cal F}^{\textbf U}_{h}}{e_{3u}} = \frac{c_b^{\textbf U}}{e_{3u}} \;{\textbf U}_h^b 947 1130 \end{equation} 948 1131 where $\textbf{U}_h^b = (u_b\;,\;v_b)$ is the near-bottom, horizontal, ocean velocity. 949 950 % ------------------------------------------------------------------------------------------------------------- 951 % Linear Bottom Friction 952 % ------------------------------------------------------------------------------------------------------------- 953 \subsection{Linear bottom friction (\protect\np{nn\_botfr}\forcode{ = 0..1})} 954 \label{subsec:ZDF_bfr_linear} 955 956 The linear bottom friction parameterisation (including the special case of a free-slip condition) assumes that 957 the bottom friction is proportional to the interior velocity (\ie the velocity of the last model level): 958 \[ 959 % \label{eq:zdfbfr_linear} 1132 Note than from \NEMO\ 4.0, drag coefficients are only computed at cell centers (\ie\ at T-points) and refer to as $c_b^T$ in the following. These are then linearly interpolated in space to get $c_b^\textbf{U}$ at velocity points. 1133 1134 %% ================================================================================================= 1135 \subsection[Linear top/bottom friction (\forcode{ln_lin})]{Linear top/bottom friction (\protect\np{ln_lin}{ln\_lin})} 1136 \label{subsec:ZDF_drg_linear} 1137 1138 The linear friction parameterisation (including the special case of a free-slip condition) assumes that 1139 the friction is proportional to the interior velocity (\ie\ the velocity of the first/last model level): 1140 \[ 1141 % \label{eq:ZDF_bfr_linear} 960 1142 {\cal F}_h^\textbf{U} = \frac{A^{vm}}{e_3} \; \frac{\partial \textbf{U}_h}{\partial k} = r \; \textbf{U}_h^b 961 1143 \] 962 where $r$ is a friction coefficient expressed in ms$^{-1}$.963 This coefficient is generally estimated by setting a typical decay time $\tau$ in the deep ocean, 1144 where $r$ is a friction coefficient expressed in $m s^{-1}$. 1145 This coefficient is generally estimated by setting a typical decay time $\tau$ in the deep ocean, 964 1146 and setting $r = H / \tau$, where $H$ is the ocean depth. 965 Commonly accepted values of $\tau$ are of the order of 100 to 200 days \citep{ Weatherly_JMR84}.1147 Commonly accepted values of $\tau$ are of the order of 100 to 200 days \citep{weatherly_JMR84}. 966 1148 A value $\tau^{-1} = 10^{-7}$~s$^{-1}$ equivalent to 115 days, is usually used in quasi-geostrophic models. 967 1149 One may consider the linear friction as an approximation of quadratic friction, $r \approx 2\;C_D\;U_{av}$ 968 (\citet{ Gill1982}, Eq. 9.6.6).1150 (\citet{gill_bk82}, Eq. 9.6.6). 969 1151 For example, with a drag coefficient $C_D = 0.002$, a typical speed of tidal currents of $U_{av} =0.1$~m\;s$^{-1}$, 970 1152 and assuming an ocean depth $H = 4000$~m, the resulting friction coefficient is $r = 4\;10^{-4}$~m\;s$^{-1}$. 971 1153 This is the default value used in \NEMO. It corresponds to a decay time scale of 115~days. 972 It can be changed by specifying \np{rn\_bfri1} (namelist parameter). 973 974 For the linear friction case the coefficients defined in the general expression \autoref{eq:zdfbfr_bdef} are: 975 \[ 976 % \label{eq:zdfbfr_linbfr_b} 977 \begin{split} 978 c_b^u &= - r\\ 979 c_b^v &= - r\\ 980 \end{split} 981 \] 982 When \np{nn\_botfr}\forcode{ = 1}, the value of $r$ used is \np{rn\_bfri1}. 983 Setting \np{nn\_botfr}\forcode{ = 0} is equivalent to setting $r=0$ and 984 leads to a free-slip bottom boundary condition. 985 These values are assigned in \mdl{zdfbfr}. 986 From v3.2 onwards there is support for local enhancement of these values via an externally defined 2D mask array 987 (\np{ln\_bfr2d}\forcode{ = .true.}) given in the \ifile{bfr\_coef} input NetCDF file. 1154 It can be changed by specifying \np{rn_Uc0}{rn\_Uc0} (namelist parameter). 1155 1156 For the linear friction case the drag coefficient used in the general expression \autoref{eq:ZDF_bfr_bdef} is: 1157 \[ 1158 % \label{eq:ZDF_bfr_linbfr_b} 1159 c_b^T = - r 1160 \] 1161 When \np[=.true.]{ln_lin}{ln\_lin}, the value of $r$ used is \np{rn_Uc0}{rn\_Uc0}*\np{rn_Cd0}{rn\_Cd0}. 1162 Setting \np[=.true.]{ln_OFF}{ln\_OFF} (and \forcode{ln_lin=.true.}) is equivalent to setting $r=0$ and leads to a free-slip boundary condition. 1163 1164 These values are assigned in \mdl{zdfdrg}. 1165 Note that there is support for local enhancement of these values via an externally defined 2D mask array 1166 (\np[=.true.]{ln_boost}{ln\_boost}) given in the \ifile{bfr\_coef} input NetCDF file. 988 1167 The mask values should vary from 0 to 1. 989 1168 Locations with a non-zero mask value will have the friction coefficient increased by 990 $mask\_value$*\np{rn\_bfrien}*\np{rn\_bfri1}. 991 992 % ------------------------------------------------------------------------------------------------------------- 993 % Non-Linear Bottom Friction 994 % ------------------------------------------------------------------------------------------------------------- 995 \subsection{Non-linear bottom friction (\protect\np{nn\_botfr}\forcode{ = 2})} 996 \label{subsec:ZDF_bfr_nonlinear} 997 998 The non-linear bottom friction parameterisation assumes that the bottom friction is quadratic: 999 \[ 1000 % \label{eq:zdfbfr_nonlinear} 1169 $mask\_value$ * \np{rn_boost}{rn\_boost} * \np{rn_Cd0}{rn\_Cd0}. 1170 1171 %% ================================================================================================= 1172 \subsection[Non-linear top/bottom friction (\forcode{ln_non_lin})]{Non-linear top/bottom friction (\protect\np{ln_non_lin}{ln\_non\_lin})} 1173 \label{subsec:ZDF_drg_nonlinear} 1174 1175 The non-linear bottom friction parameterisation assumes that the top/bottom friction is quadratic: 1176 \[ 1177 % \label{eq:ZDF_drg_nonlinear} 1001 1178 {\cal F}_h^\textbf{U} = \frac{A^{vm}}{e_3 }\frac{\partial \textbf {U}_h 1002 1179 }{\partial k}=C_D \;\sqrt {u_b ^2+v_b ^2+e_b } \;\; \textbf {U}_h^b 1003 1180 \] 1004 where $C_D$ is a drag coefficient, and $e_b $ a bottom turbulent kinetic energy due to tides,1181 where $C_D$ is a drag coefficient, and $e_b $ a top/bottom turbulent kinetic energy due to tides, 1005 1182 internal waves breaking and other short time scale currents. 1006 1183 A typical value of the drag coefficient is $C_D = 10^{-3} $. 1007 As an example, the CME experiment \citep{ Treguier_JGR92} uses $C_D = 10^{-3}$ and1008 $e_b = 2.5\;10^{-3}$m$^2$\;s$^{-2}$, while the FRAM experiment \citep{ Killworth1992} uses $C_D = 1.4\;10^{-3}$ and1184 As an example, the CME experiment \citep{treguier_JGR92} uses $C_D = 10^{-3}$ and 1185 $e_b = 2.5\;10^{-3}$m$^2$\;s$^{-2}$, while the FRAM experiment \citep{killworth_JPO92} uses $C_D = 1.4\;10^{-3}$ and 1009 1186 $e_b =2.5\;\;10^{-3}$m$^2$\;s$^{-2}$. 1010 The CME choices have been set as default values (\np{rn\_bfri2} and \np{rn\_bfeb2} namelist parameters). 1011 1012 As for the linear case, the bottom friction is imposed in the code by adding the trend due to 1013 the bottom friction to the general momentum trend in \mdl{dynbfr}. 1014 For the non-linear friction case the terms computed in \mdl{zdfbfr} are: 1015 \[ 1016 % \label{eq:zdfbfr_nonlinbfr} 1017 \begin{split} 1018 c_b^u &= - \; C_D\;\left[ u^2 + \left(\bar{\bar{v}}^{i+1,j}\right)^2 + e_b \right]^{1/2}\\ 1019 c_b^v &= - \; C_D\;\left[ \left(\bar{\bar{u}}^{i,j+1}\right)^2 + v^2 + e_b \right]^{1/2}\\ 1020 \end{split} 1021 \] 1022 1023 The coefficients that control the strength of the non-linear bottom friction are initialised as namelist parameters: 1024 $C_D$= \np{rn\_bfri2}, and $e_b$ =\np{rn\_bfeb2}. 1025 Note for applications which treat tides explicitly a low or even zero value of \np{rn\_bfeb2} is recommended. 1026 From v3.2 onwards a local enhancement of $C_D$ is possible via an externally defined 2D mask array 1027 (\np{ln\_bfr2d}\forcode{ = .true.}). 1028 This works in the same way as for the linear bottom friction case with non-zero masked locations increased by 1029 $mask\_value$*\np{rn\_bfrien}*\np{rn\_bfri2}. 1030 1031 % ------------------------------------------------------------------------------------------------------------- 1032 % Bottom Friction Log-layer 1033 % ------------------------------------------------------------------------------------------------------------- 1034 \subsection[Log-layer btm frict enhncmnt (\protect\np{nn\_botfr}\forcode{ = 2}, \protect\np{ln\_loglayer}\forcode{ = .true.})] 1035 {Log-layer bottom friction enhancement (\protect\np{nn\_botfr}\forcode{ = 2}, \protect\np{ln\_loglayer}\forcode{ = .true.})} 1036 \label{subsec:ZDF_bfr_loglayer} 1037 1038 In the non-linear bottom friction case, the drag coefficient, $C_D$, can be optionally enhanced using 1039 a "law of the wall" scaling. 1040 If \np{ln\_loglayer} = .true., $C_D$ is no longer constant but is related to the thickness of 1041 the last wet layer in each column by: 1042 \[ 1043 C_D = \left ( {\kappa \over {\rm log}\left ( 0.5e_{3t}/rn\_bfrz0 \right ) } \right )^2 1044 \] 1045 1046 \noindent where $\kappa$ is the von-Karman constant and \np{rn\_bfrz0} is a roughness length provided via 1047 the namelist. 1048 1049 For stability, the drag coefficient is bounded such that it is kept greater or equal to 1050 the base \np{rn\_bfri2} value and it is not allowed to exceed the value of an additional namelist parameter: 1051 \np{rn\_bfri2\_max}, \ie 1052 \[ 1053 rn\_bfri2 \leq C_D \leq rn\_bfri2\_max 1054 \] 1055 1056 \noindent Note also that a log-layer enhancement can also be applied to the top boundary friction if 1057 under ice-shelf cavities are in use (\np{ln\_isfcav}\forcode{ = .true.}). 1058 In this case, the relevant namelist parameters are \np{rn\_tfrz0}, \np{rn\_tfri2} and \np{rn\_tfri2\_max}. 1059 1060 % ------------------------------------------------------------------------------------------------------------- 1061 % Bottom Friction stability 1062 % ------------------------------------------------------------------------------------------------------------- 1063 \subsection{Bottom friction stability considerations} 1064 \label{subsec:ZDF_bfr_stability} 1065 1066 Some care needs to exercised over the choice of parameters to ensure that the implementation of 1067 bottom friction does not induce numerical instability. 1068 For the purposes of stability analysis, an approximation to \autoref{eq:zdfbfr_flux2} is: 1187 The CME choices have been set as default values (\np{rn_Cd0}{rn\_Cd0} and \np{rn_ke0}{rn\_ke0} namelist parameters). 1188 1189 As for the linear case, the friction is imposed in the code by adding the trend due to 1190 the friction to the general momentum trend in \mdl{dynzdf}. 1191 For the non-linear friction case the term computed in \mdl{zdfdrg} is: 1192 \[ 1193 % \label{eq:ZDF_drg_nonlinbfr} 1194 c_b^T = - \; C_D\;\left[ \left(\bar{u_b}^{i}\right)^2 + \left(\bar{v_b}^{j}\right)^2 + e_b \right]^{1/2} 1195 \] 1196 1197 The coefficients that control the strength of the non-linear friction are initialised as namelist parameters: 1198 $C_D$= \np{rn_Cd0}{rn\_Cd0}, and $e_b$ =\np{rn_bfeb2}{rn\_bfeb2}. 1199 Note that for applications which consider tides explicitly, a low or even zero value of \np{rn_bfeb2}{rn\_bfeb2} is recommended. A local enhancement of $C_D$ is again possible via an externally defined 2D mask array 1200 (\np[=.true.]{ln_boost}{ln\_boost}). 1201 This works in the same way as for the linear friction case with non-zero masked locations increased by 1202 $mask\_value$ * \np{rn_boost}{rn\_boost} * \np{rn_Cd0}{rn\_Cd0}. 1203 1204 %% ================================================================================================= 1205 \subsection[Log-layer top/bottom friction (\forcode{ln_loglayer})]{Log-layer top/bottom friction (\protect\np{ln_loglayer}{ln\_loglayer})} 1206 \label{subsec:ZDF_drg_loglayer} 1207 1208 In the non-linear friction case, the drag coefficient, $C_D$, can be optionally enhanced using 1209 a "law of the wall" scaling. This assumes that the model vertical resolution can capture the logarithmic layer which typically occur for layers thinner than 1 m or so. 1210 If \np[=.true.]{ln_loglayer}{ln\_loglayer}, $C_D$ is no longer constant but is related to the distance to the wall (or equivalently to the half of the top/bottom layer thickness): 1211 \[ 1212 C_D = \left ( {\kappa \over {\mathrm log}\left ( 0.5 \; e_{3b} / rn\_{z0} \right ) } \right )^2 1213 \] 1214 1215 \noindent where $\kappa$ is the von-Karman constant and \np{rn_z0}{rn\_z0} is a roughness length provided via the namelist. 1216 1217 The drag coefficient is bounded such that it is kept greater or equal to 1218 the base \np{rn_Cd0}{rn\_Cd0} value which occurs where layer thicknesses become large and presumably logarithmic layers are not resolved at all. For stability reason, it is also not allowed to exceed the value of an additional namelist parameter: 1219 \np{rn_Cdmax}{rn\_Cdmax}, \ie 1220 \[ 1221 rn\_Cd0 \leq C_D \leq rn\_Cdmax 1222 \] 1223 1224 \noindent The log-layer enhancement can also be applied to the top boundary friction if 1225 under ice-shelf cavities are activated (\np[=.true.]{ln_isfcav}{ln\_isfcav}). 1226 %In this case, the relevant namelist parameters are \np{rn_tfrz0}{rn\_tfrz0}, \np{rn_tfri2}{rn\_tfri2} and \np{rn_tfri2_max}{rn\_tfri2\_max}. 1227 1228 %% ================================================================================================= 1229 \subsection[Explicit top/bottom friction (\forcode{ln_drgimp=.false.})]{Explicit top/bottom friction (\protect\np[=.false.]{ln_drgimp}{ln\_drgimp})} 1230 \label{subsec:ZDF_drg_stability} 1231 1232 Setting \np[=.false.]{ln_drgimp}{ln\_drgimp} means that bottom friction is treated explicitly in time, which has the advantage of simplifying the interaction with the split-explicit free surface (see \autoref{subsec:ZDF_drg_ts}). The latter does indeed require the knowledge of bottom stresses in the course of the barotropic sub-iteration, which becomes less straightforward in the implicit case. In the explicit case, top/bottom stresses can be computed using \textit{before} velocities and inserted in the overall momentum tendency budget. This reads: 1233 1234 At the top (below an ice shelf cavity): 1235 \[ 1236 \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{t} 1237 = c_{t}^{\textbf{U}}\textbf{u}^{n-1}_{t} 1238 \] 1239 1240 At the bottom (above the sea floor): 1241 \[ 1242 \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{b} 1243 = c_{b}^{\textbf{U}}\textbf{u}^{n-1}_{b} 1244 \] 1245 1246 Since this is conditionally stable, some care needs to exercised over the choice of parameters to ensure that the implementation of explicit top/bottom friction does not induce numerical instability. 1247 For the purposes of stability analysis, an approximation to \autoref{eq:ZDF_drg_flux2} is: 1069 1248 \begin{equation} 1070 \label{eq: Eqn_bfrstab}1249 \label{eq:ZDF_Eqn_drgstab} 1071 1250 \begin{split} 1072 1251 \Delta u &= -\frac{{{\cal F}_h}^u}{e_{3u}}\;2 \rdt \\ … … 1074 1253 \end{split} 1075 1254 \end{equation} 1076 \noindent where linear bottomfriction and a leapfrog timestep have been assumed.1077 To ensure that the bottomfriction cannot reverse the direction of flow it is necessary to have:1078 \[ 1079 |\Delta u| < \;|u| 1080 \] 1081 \noindent which, using \autoref{eq: Eqn_bfrstab}, gives:1255 \noindent where linear friction and a leapfrog timestep have been assumed. 1256 To ensure that the friction cannot reverse the direction of flow it is necessary to have: 1257 \[ 1258 |\Delta u| < \;|u| 1259 \] 1260 \noindent which, using \autoref{eq:ZDF_Eqn_drgstab}, gives: 1082 1261 \[ 1083 1262 r\frac{2\rdt}{e_{3u}} < 1 \qquad \Rightarrow \qquad r < \frac{e_{3u}}{2\rdt}\\ … … 1092 1271 For example, if $|u| = 1$ m.s$^{-1}$, $rdt = 1800$ s, $r = 10^{-3}$ then $e_{3u}$ should be greater than 3.6 m. 1093 1272 For most applications, with physically sensible parameters these restrictions should not be of concern. 1094 But caution may be necessary if attempts are made to locally enhance the bottom friction parameters. 1095 To ensure stability limits are imposed on the bottom friction coefficients both1273 But caution may be necessary if attempts are made to locally enhance the bottom friction parameters. 1274 To ensure stability limits are imposed on the top/bottom friction coefficients both 1096 1275 during initialisation and at each time step. 1097 Checks at initialisation are made in \mdl{zdf bfr} (assuming a 1 m.s$^{-1}$ velocity in the non-linear case).1276 Checks at initialisation are made in \mdl{zdfdrg} (assuming a 1 m.s$^{-1}$ velocity in the non-linear case). 1098 1277 The number of breaches of the stability criterion are reported as well as 1099 1278 the minimum and maximum values that have been set. 1100 The criterion is also checked at each time step, using the actual velocity, in \mdl{dyn bfr}.1101 Values of the bottomfriction coefficient are reduced as necessary to ensure stability;1279 The criterion is also checked at each time step, using the actual velocity, in \mdl{dynzdf}. 1280 Values of the friction coefficient are reduced as necessary to ensure stability; 1102 1281 these changes are not reported. 1103 1282 1104 Limits on the bottom friction coefficient are not imposed if the user has elected to1105 handle the bottom friction implicitly (see \autoref{subsec:ZDF_bfr_imp}).1283 Limits on the top/bottom friction coefficient are not imposed if the user has elected to 1284 handle the friction implicitly (see \autoref{subsec:ZDF_drg_imp}). 1106 1285 The number of potential breaches of the explicit stability criterion are still reported for information purposes. 1107 1286 1108 % ------------------------------------------------------------------------------------------------------------- 1109 % Implicit Bottom Friction 1110 % ------------------------------------------------------------------------------------------------------------- 1111 \subsection{Implicit bottom friction (\protect\np{ln\_bfrimp}\forcode{ = .true.})} 1112 \label{subsec:ZDF_bfr_imp} 1287 %% ================================================================================================= 1288 \subsection[Implicit top/bottom friction (\forcode{ln_drgimp=.true.})]{Implicit top/bottom friction (\protect\np[=.true.]{ln_drgimp}{ln\_drgimp})} 1289 \label{subsec:ZDF_drg_imp} 1113 1290 1114 1291 An optional implicit form of bottom friction has been implemented to improve model stability. 1115 We recommend this option for shelf sea and coastal ocean applications, especially for split-explicit time splitting. 1116 This option can be invoked by setting \np{ln\_bfrimp} to \forcode{.true.} in the \textit{nambfr} namelist. 1117 This option requires \np{ln\_zdfexp} to be \forcode{.false.} in the \textit{namzdf} namelist. 1118 1119 This implementation is realised in \mdl{dynzdf\_imp} and \mdl{dynspg\_ts}. In \mdl{dynzdf\_imp}, 1120 the bottom boundary condition is implemented implicitly. 1121 1122 \[ 1123 % \label{eq:dynzdf_bfr} 1124 \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{mbk} 1125 = \binom{c_{b}^{u}u^{n+1}_{mbk}}{c_{b}^{v}v^{n+1}_{mbk}} 1126 \] 1127 1128 where $mbk$ is the layer number of the bottom wet layer. 1129 Superscript $n+1$ means the velocity used in the friction formula is to be calculated, so, it is implicit. 1130 1131 If split-explicit time splitting is used, care must be taken to avoid the double counting of the bottom friction in 1132 the 2-D barotropic momentum equations. 1133 As NEMO only updates the barotropic pressure gradient and Coriolis' forcing terms in the 2-D barotropic calculation, 1134 we need to remove the bottom friction induced by these two terms which has been included in the 3-D momentum trend 1135 and update it with the latest value. 1136 On the other hand, the bottom friction contributed by the other terms 1137 (\eg the advection term, viscosity term) has been included in the 3-D momentum equations and 1138 should not be added in the 2-D barotropic mode. 1139 1140 The implementation of the implicit bottom friction in \mdl{dynspg\_ts} is done in two steps as the following: 1141 1142 \[ 1143 % \label{eq:dynspg_ts_bfr1} 1144 \frac{\textbf{U}_{med}-\textbf{U}^{m-1}}{2\Delta t}=-g\nabla\eta-f\textbf{k}\times\textbf{U}^{m}+c_{b} 1145 \left(\textbf{U}_{med}-\textbf{U}^{m-1}\right) 1146 \] 1147 \[ 1148 \frac{\textbf{U}^{m+1}-\textbf{U}_{med}}{2\Delta t}=\textbf{T}+ 1149 \left(g\nabla\eta^{'}+f\textbf{k}\times\textbf{U}^{'}\right)- 1150 2\Delta t_{bc}c_{b}\left(g\nabla\eta^{'}+f\textbf{k}\times\textbf{u}_{b}\right) 1151 \] 1152 1153 where $\textbf{T}$ is the vertical integrated 3-D momentum trend. 1154 We assume the leap-frog time-stepping is used here. 1155 $\Delta t$ is the barotropic mode time step and $\Delta t_{bc}$ is the baroclinic mode time step. 1156 $c_{b}$ is the friction coefficient. 1157 $\eta$ is the sea surface level calculated in the barotropic loops while $\eta^{'}$ is the sea surface level used in 1158 the 3-D baroclinic mode. 1159 $\textbf{u}_{b}$ is the bottom layer horizontal velocity. 1160 1161 % ------------------------------------------------------------------------------------------------------------- 1162 % Bottom Friction with split-explicit time splitting 1163 % ------------------------------------------------------------------------------------------------------------- 1164 \subsection[Bottom friction w/ split-explicit time splitting (\protect\np{ln\_bfrimp})] 1165 {Bottom friction with split-explicit time splitting (\protect\np{ln\_bfrimp})} 1166 \label{subsec:ZDF_bfr_ts} 1167 1168 When calculating the momentum trend due to bottom friction in \mdl{dynbfr}, 1169 the bottom velocity at the before time step is used. 1170 This velocity includes both the baroclinic and barotropic components which is appropriate when 1171 using either the explicit or filtered surface pressure gradient algorithms 1172 (\key{dynspg\_exp} or \key{dynspg\_flt}). 1173 Extra attention is required, however, when using split-explicit time stepping (\key{dynspg\_ts}). 1174 In this case the free surface equation is solved with a small time step \np{rn\_rdt}/\np{nn\_baro}, 1175 while the three dimensional prognostic variables are solved with the longer time step of \np{rn\_rdt} seconds. 1176 The trend in the barotropic momentum due to bottom friction appropriate to this method is that given by 1177 the selected parameterisation (\ie linear or non-linear bottom friction) computed with 1178 the evolving velocities at each barotropic timestep. 1179 1180 In the case of non-linear bottom friction, we have elected to partially linearise the problem by 1181 keeping the coefficients fixed throughout the barotropic time-stepping to those computed in 1182 \mdl{zdfbfr} using the now timestep. 1183 This decision allows an efficient use of the $c_b^{\vect{U}}$ coefficients to: 1184 1292 We recommend this option for shelf sea and coastal ocean applications. %, especially for split-explicit time splitting. 1293 This option can be invoked by setting \np{ln_drgimp}{ln\_drgimp} to \forcode{.true.} in the \nam{drg}{drg} namelist. 1294 %This option requires \np{ln_zdfexp}{ln\_zdfexp} to be \forcode{.false.} in the \nam{zdf}{zdf} namelist. 1295 1296 This implementation is performed in \mdl{dynzdf} where the following boundary conditions are set while solving the fully implicit diffusion step: 1297 1298 At the top (below an ice shelf cavity): 1299 \[ 1300 % \label{eq:ZDF_dynZDF__drg_top} 1301 \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{t} 1302 = c_{t}^{\textbf{U}}\textbf{u}^{n+1}_{t} 1303 \] 1304 1305 At the bottom (above the sea floor): 1306 \[ 1307 % \label{eq:ZDF_dynZDF__drg_bot} 1308 \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{b} 1309 = c_{b}^{\textbf{U}}\textbf{u}^{n+1}_{b} 1310 \] 1311 1312 where $t$ and $b$ refers to top and bottom layers respectively. 1313 Superscript $n+1$ means the velocity used in the friction formula is to be calculated, so it is implicit. 1314 1315 %% ================================================================================================= 1316 \subsection[Bottom friction with split-explicit free surface]{Bottom friction with split-explicit free surface} 1317 \label{subsec:ZDF_drg_ts} 1318 1319 With split-explicit free surface, the sub-stepping of barotropic equations needs the knowledge of top/bottom stresses. An obvious way to satisfy this is to take them as constant over the course of the barotropic integration and equal to the value used to update the baroclinic momentum trend. Provided \np[=.false.]{ln_drgimp}{ln\_drgimp} and a centred or \textit{leap-frog} like integration of barotropic equations is used (\ie\ \forcode{ln_bt_fw=.false.}, cf \autoref{subsec:DYN_spg_ts}), this does ensure that barotropic and baroclinic dynamics feel the same stresses during one leapfrog time step. However, if \np[=.true.]{ln_drgimp}{ln\_drgimp}, stresses depend on the \textit{after} value of the velocities which themselves depend on the barotropic iteration result. This cyclic dependency makes difficult obtaining consistent stresses in 2d and 3d dynamics. Part of this mismatch is then removed when setting the final barotropic component of 3d velocities to the time splitting estimate. This last step can be seen as a necessary evil but should be minimized since it interferes with the adjustment to the boundary conditions. 1320 1321 The strategy to handle top/bottom stresses with split-explicit free surface in \NEMO\ is as follows: 1185 1322 \begin{enumerate} 1186 \item On entry to \rou{dyn\_spg\_ts}, remove the contribution of the before barotropic velocity to 1187 the bottom friction component of the vertically integrated momentum trend. 1188 Note the same stability check that is carried out on the bottom friction coefficient in \mdl{dynbfr} has to 1189 be applied here to ensure that the trend removed matches that which was added in \mdl{dynbfr}. 1190 \item At each barotropic step, compute the contribution of the current barotropic velocity to 1191 the trend due to bottom friction. 1192 Add this contribution to the vertically integrated momentum trend. 1193 This contribution is handled implicitly which eliminates the need to impose a stability criteria on 1194 the values of the bottom friction coefficient within the barotropic loop. 1323 \item To extend the stability of the barotropic sub-stepping, bottom stresses are refreshed at each sub-iteration. The baroclinic part of the flow entering the stresses is frozen at the initial time of the barotropic iteration. In case of non-linear friction, the drag coefficient is also constant. 1324 \item In case of an implicit drag, specific computations are performed in \mdl{dynzdf} which renders the overall scheme mixed explicit/implicit: the barotropic components of 3d velocities are removed before seeking for the implicit vertical diffusion result. Top/bottom stresses due to the barotropic components are explicitly accounted for thanks to the updated values of barotropic velocities. Then the implicit solution of 3d velocities is obtained. Lastly, the residual barotropic component is replaced by the time split estimate. 1195 1325 \end{enumerate} 1196 1326 1197 Note that the use of an implicit formulation within the barotropic loop for the bottom friction trend means that 1198 any limiting of the bottom friction coefficient in \mdl{dynbfr} does not adversely affect the solution when 1199 using split-explicit time splitting. 1200 This is because the major contribution to bottom friction is likely to come from the barotropic component which 1201 uses the unrestricted value of the coefficient. 1202 However, if the limiting is thought to be having a major effect 1203 (a more likely prospect in coastal and shelf seas applications) then 1204 the fully implicit form of the bottom friction should be used (see \autoref{subsec:ZDF_bfr_imp}) 1205 which can be selected by setting \np{ln\_bfrimp} $=$ \forcode{.true.}. 1206 1207 Otherwise, the implicit formulation takes the form: 1208 \[ 1209 % \label{eq:zdfbfr_implicitts} 1210 \bar{U}^{t+ \rdt} = \; \left [ \bar{U}^{t-\rdt}\; + 2 \rdt\;RHS \right ] / \left [ 1 - 2 \rdt \;c_b^{u} / H_e \right ] 1211 \] 1212 where $\bar U$ is the barotropic velocity, $H_e$ is the full depth (including sea surface height), 1213 $c_b^u$ is the bottom friction coefficient as calculated in \rou{zdf\_bfr} and 1214 $RHS$ represents all the components to the vertically integrated momentum trend except for 1215 that due to bottom friction. 1216 1217 % ================================================================ 1218 % Tidal Mixing 1219 % ================================================================ 1220 \section{Tidal mixing (\protect\key{zdftmx})} 1221 \label{sec:ZDF_tmx} 1222 1223 %--------------------------------------------namzdf_tmx-------------------------------------------------- 1224 % 1225 %\nlst{namzdf_tmx} 1226 %-------------------------------------------------------------------------------------------------------------- 1227 1228 1229 % ------------------------------------------------------------------------------------------------------------- 1230 % Bottom intensified tidal mixing 1231 % ------------------------------------------------------------------------------------------------------------- 1232 \subsection{Bottom intensified tidal mixing} 1233 \label{subsec:ZDF_tmx_bottom} 1234 1235 Options are defined through the \ngn{namzdf\_tmx} namelist variables. 1236 The parameterization of tidal mixing follows the general formulation for the vertical eddy diffusivity proposed by 1237 \citet{St_Laurent_al_GRL02} and first introduced in an OGCM by \citep{Simmons_al_OM04}. 1238 In this formulation an additional vertical diffusivity resulting from internal tide breaking, 1239 $A^{vT}_{tides}$ is expressed as a function of $E(x,y)$, 1240 the energy transfer from barotropic tides to baroclinic tides: 1241 \begin{equation} 1242 \label{eq:Ktides} 1243 A^{vT}_{tides} = q \,\Gamma \,\frac{ E(x,y) \, F(z) }{ \rho \, N^2 } 1244 \end{equation} 1245 where $\Gamma$ is the mixing efficiency, $N$ the Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}), 1246 $\rho$ the density, $q$ the tidal dissipation efficiency, and $F(z)$ the vertical structure function. 1247 1248 The mixing efficiency of turbulence is set by $\Gamma$ (\np{rn\_me} namelist parameter) and 1249 is usually taken to be the canonical value of $\Gamma = 0.2$ (Osborn 1980). 1250 The tidal dissipation efficiency is given by the parameter $q$ (\np{rn\_tfe} namelist parameter) 1251 represents the part of the internal wave energy flux $E(x, y)$ that is dissipated locally, 1252 with the remaining $1-q$ radiating away as low mode internal waves and 1253 contributing to the background internal wave field. 1254 A value of $q=1/3$ is typically used \citet{St_Laurent_al_GRL02}. 1255 The vertical structure function $F(z)$ models the distribution of the turbulent mixing in the vertical. 1256 It is implemented as a simple exponential decaying upward away from the bottom, 1257 with a vertical scale of $h_o$ (\np{rn\_htmx} namelist parameter, 1258 with a typical value of $500\,m$) \citep{St_Laurent_Nash_DSR04}, 1259 \[ 1260 % \label{eq:Fz} 1261 F(i,j,k) = \frac{ e^{ -\frac{H+z}{h_o} } }{ h_o \left( 1- e^{ -\frac{H}{h_o} } \right) } 1262 \] 1263 and is normalized so that vertical integral over the water column is unity. 1264 1265 The associated vertical viscosity is calculated from the vertical diffusivity assuming a Prandtl number of 1, 1266 \ie $A^{vm}_{tides}=A^{vT}_{tides}$. 1267 In the limit of $N \rightarrow 0$ (or becoming negative), the vertical diffusivity is capped at $300\,cm^2/s$ and 1268 impose a lower limit on $N^2$ of \np{rn\_n2min} usually set to $10^{-8} s^{-2}$. 1269 These bounds are usually rarely encountered. 1270 1271 The internal wave energy map, $E(x, y)$ in \autoref{eq:Ktides}, is derived from a barotropic model of 1272 the tides utilizing a parameterization of the conversion of barotropic tidal energy into internal waves. 1273 The essential goal of the parameterization is to represent the momentum exchange between the barotropic tides and 1274 the unrepresented internal waves induced by the tidal flow over rough topography in a stratified ocean. 1275 In the current version of \NEMO, the map is built from the output of 1276 the barotropic global ocean tide model MOG2D-G \citep{Carrere_Lyard_GRL03}. 1277 This model provides the dissipation associated with internal wave energy for the M2 and K1 tides component 1278 (\autoref{fig:ZDF_M2_K1_tmx}). 1279 The S2 dissipation is simply approximated as being $1/4$ of the M2 one. 1280 The internal wave energy is thus : $E(x, y) = 1.25 E_{M2} + E_{K1}$. 1281 Its global mean value is $1.1$ TW, 1282 in agreement with independent estimates \citep{Egbert_Ray_Nat00, Egbert_Ray_JGR01}. 1283 1284 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1285 \begin{figure}[!t] 1286 \begin{center} 1287 \includegraphics[width=0.90\textwidth]{Fig_ZDF_M2_K1_tmx} 1288 \caption{ 1289 \protect\label{fig:ZDF_M2_K1_tmx} 1290 (a) M2 and (b) K1 internal wave drag energy from \citet{Carrere_Lyard_GRL03} ($W/m^2$). 1291 } 1292 \end{center} 1293 \end{figure} 1294 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1295 1296 % ------------------------------------------------------------------------------------------------------------- 1297 % Indonesian area specific treatment 1298 % ------------------------------------------------------------------------------------------------------------- 1299 \subsection{Indonesian area specific treatment (\protect\np{ln\_zdftmx\_itf})} 1300 \label{subsec:ZDF_tmx_itf} 1301 1302 When the Indonesian Through Flow (ITF) area is included in the model domain, 1303 a specific treatment of tidal induced mixing in this area can be used. 1304 It is activated through the namelist logical \np{ln\_tmx\_itf}, and the user must provide an input NetCDF file, 1305 \ifile{mask\_itf}, which contains a mask array defining the ITF area where the specific treatment is applied. 1306 1307 When \np{ln\_tmx\_itf}\forcode{ = .true.}, the two key parameters $q$ and $F(z)$ are adjusted following 1308 the parameterisation developed by \citet{Koch-Larrouy_al_GRL07}: 1309 1310 First, the Indonesian archipelago is a complex geographic region with a series of 1311 large, deep, semi-enclosed basins connected via numerous narrow straits. 1312 Once generated, internal tides remain confined within this semi-enclosed area and hardly radiate away. 1313 Therefore all the internal tides energy is consumed within this area. 1314 So it is assumed that $q = 1$, \ie all the energy generated is available for mixing. 1315 Note that for test purposed, the ITF tidal dissipation efficiency is a namelist parameter (\np{rn\_tfe\_itf}). 1316 A value of $1$ or close to is this recommended for this parameter. 1317 1318 Second, the vertical structure function, $F(z)$, is no more associated with a bottom intensification of the mixing, 1319 but with a maximum of energy available within the thermocline. 1320 \citet{Koch-Larrouy_al_GRL07} have suggested that the vertical distribution of 1321 the energy dissipation proportional to $N^2$ below the core of the thermocline and to $N$ above. 1322 The resulting $F(z)$ is: 1323 \[ 1324 % \label{eq:Fz_itf} 1325 F(i,j,k) \sim \left\{ 1326 \begin{aligned} 1327 \frac{q\,\Gamma E(i,j) } {\rho N \, \int N dz} \qquad \text{when $\partial_z N < 0$} \\ 1328 \frac{q\,\Gamma E(i,j) } {\rho \, \int N^2 dz} \qquad \text{when $\partial_z N > 0$} 1329 \end{aligned} 1330 \right. 1331 \] 1332 1333 Averaged over the ITF area, the resulting tidal mixing coefficient is $1.5\,cm^2/s$, 1334 which agrees with the independent estimates inferred from observations. 1335 Introduced in a regional OGCM, the parameterization improves the water mass characteristics in 1336 the different Indonesian seas, suggesting that the horizontal and vertical distributions of 1337 the mixing are adequately prescribed \citep{Koch-Larrouy_al_GRL07, Koch-Larrouy_al_OD08a, Koch-Larrouy_al_OD08b}. 1338 Note also that such a parameterisation has a significant impact on the behaviour of 1339 global coupled GCMs \citep{Koch-Larrouy_al_CD10}. 1340 1341 % ================================================================ 1342 % Internal wave-driven mixing 1343 % ================================================================ 1344 \section{Internal wave-driven mixing (\protect\key{zdftmx\_new})} 1345 \label{sec:ZDF_tmx_new} 1346 1347 %--------------------------------------------namzdf_tmx_new------------------------------------------ 1348 % 1349 %\nlst{namzdf_tmx_new} 1350 %-------------------------------------------------------------------------------------------------------------- 1327 Note that other strategies are possible, like considering vertical diffusion step in advance, \ie\ prior barotropic integration. 1328 1329 %% ================================================================================================= 1330 \section[Internal wave-driven mixing (\forcode{ln_zdfiwm})]{Internal wave-driven mixing (\protect\np{ln_zdfiwm}{ln\_zdfiwm})} 1331 \label{subsec:ZDF_tmx_new} 1332 1333 \begin{listing} 1334 \nlst{namzdf_iwm} 1335 \caption{\forcode{&namzdf_iwm}} 1336 \label{lst:namzdf_iwm} 1337 \end{listing} 1351 1338 1352 1339 The parameterization of mixing induced by breaking internal waves is a generalization of 1353 the approach originally proposed by \citet{ St_Laurent_al_GRL02}.1340 the approach originally proposed by \citet{st-laurent.simmons.ea_GRL02}. 1354 1341 A three-dimensional field of internal wave energy dissipation $\epsilon(x,y,z)$ is first constructed, 1355 and the resulting diffusivity is obtained as 1356 \[ 1357 % \label{eq: Kwave}1342 and the resulting diffusivity is obtained as 1343 \[ 1344 % \label{eq:ZDF_Kwave} 1358 1345 A^{vT}_{wave} = R_f \,\frac{ \epsilon }{ \rho \, N^2 } 1359 1346 \] 1360 1347 where $R_f$ is the mixing efficiency and $\epsilon$ is a specified three dimensional distribution of 1361 1348 the energy available for mixing. 1362 If the \np{ln \_mevar} namelist parameter is set to false, the mixing efficiency is taken as constant and1363 equal to 1/6 \citep{ Osborn_JPO80}.1349 If the \np{ln_mevar}{ln\_mevar} namelist parameter is set to \forcode{.false.}, the mixing efficiency is taken as constant and 1350 equal to 1/6 \citep{osborn_JPO80}. 1364 1351 In the opposite (recommended) case, $R_f$ is instead a function of 1365 1352 the turbulence intensity parameter $Re_b = \frac{ \epsilon}{\nu \, N^2}$, 1366 with $\nu$ the molecular viscosity of seawater, following the model of \cite{ Bouffard_Boegman_DAO2013} and1367 the implementation of \cite{de _lavergne_JPO2016_efficiency}.1353 with $\nu$ the molecular viscosity of seawater, following the model of \cite{bouffard.boegman_DAO13} and 1354 the implementation of \cite{de-lavergne.madec.ea_JPO16}. 1368 1355 Note that $A^{vT}_{wave}$ is bounded by $10^{-2}\,m^2/s$, a limit that is often reached when 1369 1356 the mixing efficiency is constant. 1370 1357 1371 In addition to the mixing efficiency, the ratio of salt to heat diffusivities can chosen to vary 1372 as a function of $Re_b$ by setting the \np{ln \_tsdiff} parameter to true, a recommended choice.1373 This parameterization of differential mixing, due to \cite{ Jackson_Rehmann_JPO2014},1374 is implemented as in \cite{de _lavergne_JPO2016_efficiency}.1358 In addition to the mixing efficiency, the ratio of salt to heat diffusivities can chosen to vary 1359 as a function of $Re_b$ by setting the \np{ln_tsdiff}{ln\_tsdiff} parameter to \forcode{.true.}, a recommended choice. 1360 This parameterization of differential mixing, due to \cite{jackson.rehmann_JPO14}, 1361 is implemented as in \cite{de-lavergne.madec.ea_JPO16}. 1375 1362 1376 1363 The three-dimensional distribution of the energy available for mixing, $\epsilon(i,j,k)$, 1377 1364 is constructed from three static maps of column-integrated internal wave energy dissipation, 1378 $E_{cri}(i,j)$, $E_{pyc}(i,j)$, and $E_{bot}(i,j)$, combined to three corresponding vertical structures 1379 (de Lavergne et al., in prep): 1365 $E_{cri}(i,j)$, $E_{pyc}(i,j)$, and $E_{bot}(i,j)$, combined to three corresponding vertical structures: 1366 1380 1367 \begin{align*} 1381 1368 F_{cri}(i,j,k) &\propto e^{-h_{ab} / h_{cri} }\\ 1382 F_{pyc}(i,j,k) &\propto N^{n \_p}\\1369 F_{pyc}(i,j,k) &\propto N^{n_p}\\ 1383 1370 F_{bot}(i,j,k) &\propto N^2 \, e^{- h_{wkb} / h_{bot} } 1384 \end{align*} 1371 \end{align*} 1385 1372 In the above formula, $h_{ab}$ denotes the height above bottom, 1386 1373 $h_{wkb}$ denotes the WKB-stretched height above bottom, defined by … … 1388 1375 h_{wkb} = H \, \frac{ \int_{-H}^{z} N \, dz' } { \int_{-H}^{\eta} N \, dz' } \; , 1389 1376 \] 1390 The $n_p$ parameter (given by \np{nn \_zpyc} in \ngn{namzdf\_tmx\_new} namelist)1377 The $n_p$ parameter (given by \np{nn_zpyc}{nn\_zpyc} in \nam{zdf_iwm}{zdf\_iwm} namelist) 1391 1378 controls the stratification-dependence of the pycnocline-intensified dissipation. 1392 It can take values of 1 (recommended) or 2.1379 It can take values of $1$ (recommended) or $2$. 1393 1380 Finally, the vertical structures $F_{cri}$ and $F_{bot}$ require the specification of 1394 1381 the decay scales $h_{cri}(i,j)$ and $h_{bot}(i,j)$, which are defined by two additional input maps. 1395 1382 $h_{cri}$ is related to the large-scale topography of the ocean (etopo2) and 1396 1383 $h_{bot}$ is a function of the energy flux $E_{bot}$, the characteristic horizontal scale of 1397 the abyssal hill topography \citep{Goff_JGR2010} and the latitude. 1398 1399 % ================================================================ 1400 1401 \biblio 1402 1403 \pindex 1384 the abyssal hill topography \citep{goff_JGR10} and the latitude. 1385 % Jc: input files names ? 1386 1387 %% ================================================================================================= 1388 \section[Surface wave-induced mixing (\forcode{ln_zdfswm})]{Surface wave-induced mixing (\protect\np{ln_zdfswm}{ln\_zdfswm})} 1389 \label{subsec:ZDF_swm} 1390 1391 Surface waves produce an enhanced mixing through wave-turbulence interaction. 1392 In addition to breaking waves induced turbulence (\autoref{subsec:ZDF_tke}), 1393 the influence of non-breaking waves can be accounted introducing 1394 wave-induced viscosity and diffusivity as a function of the wave number spectrum. 1395 Following \citet{qiao.yuan.ea_OD10}, a formulation of wave-induced mixing coefficient 1396 is provided as a function of wave amplitude, Stokes Drift and wave-number: 1397 1398 \begin{equation} 1399 \label{eq:ZDF_Bv} 1400 B_{v} = \alpha {A} {U}_{st} {exp(3kz)} 1401 \end{equation} 1402 1403 Where $B_{v}$ is the wave-induced mixing coefficient, $A$ is the wave amplitude, 1404 ${U}_{st}$ is the Stokes Drift velocity, $k$ is the wave number and $\alpha$ 1405 is a constant which should be determined by observations or 1406 numerical experiments and is set to be 1. 1407 1408 The coefficient $B_{v}$ is then directly added to the vertical viscosity 1409 and diffusivity coefficients. 1410 1411 In order to account for this contribution set: \forcode{ln_zdfswm=.true.}, 1412 then wave interaction has to be activated through \forcode{ln_wave=.true.}, 1413 the Stokes Drift can be evaluated by setting \forcode{ln_sdw=.true.} 1414 (see \autoref{subsec:SBC_wave_sdw}) 1415 and the needed wave fields can be provided either in forcing or coupled mode 1416 (for more information on wave parameters and settings see \autoref{sec:SBC_wave}) 1417 1418 %% ================================================================================================= 1419 \section[Adaptive-implicit vertical advection (\forcode{ln_zad_Aimp})]{Adaptive-implicit vertical advection(\protect\np{ln_zad_Aimp}{ln\_zad\_Aimp})} 1420 \label{subsec:ZDF_aimp} 1421 1422 The adaptive-implicit vertical advection option in NEMO is based on the work of 1423 \citep{shchepetkin_OM15}. In common with most ocean models, the timestep used with NEMO 1424 needs to satisfy multiple criteria associated with different physical processes in order 1425 to maintain numerical stability. \citep{shchepetkin_OM15} pointed out that the vertical 1426 CFL criterion is commonly the most limiting. \citep{lemarie.debreu.ea_OM15} examined the 1427 constraints for a range of time and space discretizations and provide the CFL stability 1428 criteria for a range of advection schemes. The values for the Leap-Frog with Robert 1429 asselin filter time-stepping (as used in NEMO) are reproduced in 1430 \autoref{tab:ZDF_zad_Aimp_CFLcrit}. Treating the vertical advection implicitly can avoid these 1431 restrictions but at the cost of large dispersive errors and, possibly, large numerical 1432 viscosity. The adaptive-implicit vertical advection option provides a targetted use of the 1433 implicit scheme only when and where potential breaches of the vertical CFL condition 1434 occur. In many practical applications these events may occur remote from the main area of 1435 interest or due to short-lived conditions such that the extra numerical diffusion or 1436 viscosity does not greatly affect the overall solution. With such applications, setting: 1437 \forcode{ln_zad_Aimp=.true.} should allow much longer model timesteps to be used whilst 1438 retaining the accuracy of the high order explicit schemes over most of the domain. 1439 1440 \begin{table}[htbp] 1441 \centering 1442 % \begin{tabular}{cp{70pt}cp{70pt}cp{70pt}cp{70pt}} 1443 \begin{tabular}{r|ccc} 1444 \hline 1445 spatial discretization & 2$^nd$ order centered & 3$^rd$ order upwind & 4$^th$ order compact \\ 1446 advective CFL criterion & 0.904 & 0.472 & 0.522 \\ 1447 \hline 1448 \end{tabular} 1449 \caption[Advective CFL criteria for the leapfrog with Robert Asselin filter time-stepping]{ 1450 The advective CFL criteria for a range of spatial discretizations for 1451 the leapfrog with Robert Asselin filter time-stepping 1452 ($\nu=0.1$) as given in \citep{lemarie.debreu.ea_OM15}.} 1453 \label{tab:ZDF_zad_Aimp_CFLcrit} 1454 \end{table} 1455 1456 In particular, the advection scheme remains explicit everywhere except where and when 1457 local vertical velocities exceed a threshold set just below the explicit stability limit. 1458 Once the threshold is reached a tapered transition towards an implicit scheme is used by 1459 partitioning the vertical velocity into a part that can be treated explicitly and any 1460 excess that must be treated implicitly. The partitioning is achieved via a Courant-number 1461 dependent weighting algorithm as described in \citep{shchepetkin_OM15}. 1462 1463 The local cell Courant number ($Cu$) used for this partitioning is: 1464 1465 \begin{equation} 1466 \label{eq:ZDF_Eqn_zad_Aimp_Courant} 1467 \begin{split} 1468 Cu &= {2 \rdt \over e^n_{3t_{ijk}}} \bigg (\big [ \texttt{Max}(w^n_{ijk},0.0) - \texttt{Min}(w^n_{ijk+1},0.0) \big ] \\ 1469 &\phantom{=} +\big [ \texttt{Max}(e_{{2_u}ij}e^n_{{3_{u}}ijk}u^n_{ijk},0.0) - \texttt{Min}(e_{{2_u}i-1j}e^n_{{3_{u}}i-1jk}u^n_{i-1jk},0.0) \big ] 1470 \big / e_{{1_t}ij}e_{{2_t}ij} \\ 1471 &\phantom{=} +\big [ \texttt{Max}(e_{{1_v}ij}e^n_{{3_{v}}ijk}v^n_{ijk},0.0) - \texttt{Min}(e_{{1_v}ij-1}e^n_{{3_{v}}ij-1k}v^n_{ij-1k},0.0) \big ] 1472 \big / e_{{1_t}ij}e_{{2_t}ij} \bigg ) \\ 1473 \end{split} 1474 \end{equation} 1475 1476 \noindent and the tapering algorithm follows \citep{shchepetkin_OM15} as: 1477 1478 \begin{align} 1479 \label{eq:ZDF_Eqn_zad_Aimp_partition} 1480 Cu_{min} &= 0.15 \nonumber \\ 1481 Cu_{max} &= 0.3 \nonumber \\ 1482 Cu_{cut} &= 2Cu_{max} - Cu_{min} \nonumber \\ 1483 Fcu &= 4Cu_{max}*(Cu_{max}-Cu_{min}) \nonumber \\ 1484 \cf &= 1485 \begin{cases} 1486 0.0 &\text{if $Cu \leq Cu_{min}$} \\ 1487 (Cu - Cu_{min})^2 / (Fcu + (Cu - Cu_{min})^2) &\text{else if $Cu < Cu_{cut}$} \\ 1488 (Cu - Cu_{max}) / Cu &\text{else} 1489 \end{cases} 1490 \end{align} 1491 1492 \begin{figure}[!t] 1493 \centering 1494 \includegraphics[width=0.66\textwidth]{ZDF_zad_Aimp_coeff} 1495 \caption[Partitioning coefficient used to partition vertical velocities into parts]{ 1496 The value of the partitioning coefficient (\cf) used to partition vertical velocities into 1497 parts to be treated implicitly and explicitly for a range of typical Courant numbers 1498 (\forcode{ln_zad_Aimp=.true.}).} 1499 \label{fig:ZDF_zad_Aimp_coeff} 1500 \end{figure} 1501 1502 \noindent The partitioning coefficient is used to determine the part of the vertical 1503 velocity that must be handled implicitly ($w_i$) and to subtract this from the total 1504 vertical velocity ($w_n$) to leave that which can continue to be handled explicitly: 1505 1506 \begin{align} 1507 \label{eq:ZDF_Eqn_zad_Aimp_partition2} 1508 w_{i_{ijk}} &= \cf_{ijk} w_{n_{ijk}} \nonumber \\ 1509 w_{n_{ijk}} &= (1-\cf_{ijk}) w_{n_{ijk}} 1510 \end{align} 1511 1512 \noindent Note that the coefficient is such that the treatment is never fully implicit; 1513 the three cases from \autoref{eq:ZDF_Eqn_zad_Aimp_partition} can be considered as: 1514 fully-explicit; mixed explicit/implicit and mostly-implicit. With the settings shown the 1515 coefficient (\cf) varies as shown in \autoref{fig:ZDF_zad_Aimp_coeff}. Note with these values 1516 the $Cu_{cut}$ boundary between the mixed implicit-explicit treatment and 'mostly 1517 implicit' is 0.45 which is just below the stability limited given in 1518 \autoref{tab:ZDF_zad_Aimp_CFLcrit} for a 3rd order scheme. 1519 1520 The $w_i$ component is added to the implicit solvers for the vertical mixing in 1521 \mdl{dynzdf} and \mdl{trazdf} in a similar way to \citep{shchepetkin_OM15}. This is 1522 sufficient for the flux-limited advection scheme (\forcode{ln_traadv_mus}) but further 1523 intervention is required when using the flux-corrected scheme (\forcode{ln_traadv_fct}). 1524 For these schemes the implicit upstream fluxes must be added to both the monotonic guess 1525 and to the higher order solution when calculating the antidiffusive fluxes. The implicit 1526 vertical fluxes are then removed since they are added by the implicit solver later on. 1527 1528 The adaptive-implicit vertical advection option is new to NEMO at v4.0 and has yet to be 1529 used in a wide range of simulations. The following test simulation, however, does illustrate 1530 the potential benefits and will hopefully encourage further testing and feedback from users: 1531 1532 \begin{figure}[!t] 1533 \centering 1534 \includegraphics[width=0.66\textwidth]{ZDF_zad_Aimp_overflow_frames} 1535 \caption[OVERFLOW: time-series of temperature vertical cross-sections]{ 1536 A time-series of temperature vertical cross-sections for the OVERFLOW test case. 1537 These results are for the default settings with \forcode{nn_rdt=10.0} and 1538 without adaptive implicit vertical advection (\forcode{ln_zad_Aimp=.false.}).} 1539 \label{fig:ZDF_zad_Aimp_overflow_frames} 1540 \end{figure} 1541 1542 %% ================================================================================================= 1543 \subsection{Adaptive-implicit vertical advection in the OVERFLOW test-case} 1544 1545 The \href{https://forge.ipsl.jussieu.fr/nemo/chrome/site/doc/NEMO/guide/html/test\_cases.html\#overflow}{OVERFLOW test case} 1546 provides a simple illustration of the adaptive-implicit advection in action. The example here differs from the basic test case 1547 by only a few extra physics choices namely: 1548 1549 \begin{verbatim} 1550 ln_dynldf_OFF = .false. 1551 ln_dynldf_lap = .true. 1552 ln_dynldf_hor = .true. 1553 ln_zdfnpc = .true. 1554 ln_traadv_fct = .true. 1555 nn_fct_h = 2 1556 nn_fct_v = 2 1557 \end{verbatim} 1558 1559 \noindent which were chosen to provide a slightly more stable and less noisy solution. The 1560 result when using the default value of \forcode{nn_rdt=10.} without adaptive-implicit 1561 vertical velocity is illustrated in \autoref{fig:ZDF_zad_Aimp_overflow_frames}. The mass of 1562 cold water, initially sitting on the shelf, moves down the slope and forms a 1563 bottom-trapped, dense plume. Even with these extra physics choices the model is close to 1564 stability limits and attempts with \forcode{nn_rdt=30.} will fail after about 5.5 hours 1565 with excessively high horizontal velocities. This time-scale corresponds with the time the 1566 plume reaches the steepest part of the topography and, although detected as a horizontal 1567 CFL breach, the instability originates from a breach of the vertical CFL limit. This is a good 1568 candidate, therefore, for use of the adaptive-implicit vertical advection scheme. 1569 1570 The results with \forcode{ln_zad_Aimp=.true.} and a variety of model timesteps 1571 are shown in \autoref{fig:ZDF_zad_Aimp_overflow_all_rdt} (together with the equivalent 1572 frames from the base run). In this simple example the use of the adaptive-implicit 1573 vertcal advection scheme has enabled a 12x increase in the model timestep without 1574 significantly altering the solution (although at this extreme the plume is more diffuse 1575 and has not travelled so far). Notably, the solution with and without the scheme is 1576 slightly different even with \forcode{nn_rdt=10.}; suggesting that the base run was 1577 close enough to instability to trigger the scheme despite completing successfully. 1578 To assist in diagnosing how active the scheme is, in both location and time, the 3D 1579 implicit and explicit components of the vertical velocity are available via XIOS as 1580 \texttt{wimp} and \texttt{wexp} respectively. Likewise, the partitioning coefficient 1581 (\cf) is also available as \texttt{wi\_cff}. For a quick oversight of 1582 the schemes activity the global maximum values of the absolute implicit component 1583 of the vertical velocity and the partitioning coefficient are written to the netCDF 1584 version of the run statistics file (\texttt{run.stat.nc}) if this is active (see 1585 \autoref{sec:MISC_opt} for activation details). 1586 1587 \autoref{fig:ZDF_zad_Aimp_maxCf} shows examples of the maximum partitioning coefficient for 1588 the various overflow tests. Note that the adaptive-implicit vertical advection scheme is 1589 active even in the base run with \forcode{nn_rdt=10.0s} adding to the evidence that the 1590 test case is close to stability limits even with this value. At the larger timesteps, the 1591 vertical velocity is treated mostly implicitly at some location throughout the run. The 1592 oscillatory nature of this measure appears to be linked to the progress of the plume front 1593 as each cusp is associated with the location of the maximum shifting to the adjacent cell. 1594 This is illustrated in \autoref{fig:ZDF_zad_Aimp_maxCf_loc} where the i- and k- locations of the 1595 maximum have been overlaid for the base run case. 1596 1597 \medskip 1598 \noindent Only limited tests have been performed in more realistic configurations. In the 1599 ORCA2\_ICE\_PISCES reference configuration the scheme does activate and passes 1600 restartability and reproducibility tests but it is unable to improve the model's stability 1601 enough to allow an increase in the model time-step. A view of the time-series of maximum 1602 partitioning coefficient (not shown here) suggests that the default time-step of 5400s is 1603 already pushing at stability limits, especially in the initial start-up phase. The 1604 time-series does not, however, exhibit any of the 'cuspiness' found with the overflow 1605 tests. 1606 1607 \medskip 1608 \noindent A short test with an eORCA1 configuration promises more since a test using a 1609 time-step of 3600s remains stable with \forcode{ln_zad_Aimp=.true.} whereas the 1610 time-step is limited to 2700s without. 1611 1612 \begin{figure}[!t] 1613 \centering 1614 \includegraphics[width=0.66\textwidth]{ZDF_zad_Aimp_overflow_all_rdt} 1615 \caption[OVERFLOW: sample temperature vertical cross-sections from mid- and end-run]{ 1616 Sample temperature vertical cross-sections from mid- and end-run using 1617 different values for \forcode{nn_rdt} and with or without adaptive implicit vertical advection. 1618 Without the adaptive implicit vertical advection 1619 only the run with the shortest timestep is able to run to completion. 1620 Note also that the colour-scale has been chosen to confirm that 1621 temperatures remain within the original range of 10$^o$ to 20$^o$.} 1622 \label{fig:ZDF_zad_Aimp_overflow_all_rdt} 1623 \end{figure} 1624 1625 \begin{figure}[!t] 1626 \centering 1627 \includegraphics[width=0.66\textwidth]{ZDF_zad_Aimp_maxCf} 1628 \caption[OVERFLOW: maximum partitioning coefficient during a series of test runs]{ 1629 The maximum partitioning coefficient during a series of test runs with 1630 increasing model timestep length. 1631 At the larger timesteps, 1632 the vertical velocity is treated mostly implicitly at some location throughout the run.} 1633 \label{fig:ZDF_zad_Aimp_maxCf} 1634 \end{figure} 1635 1636 \begin{figure}[!t] 1637 \centering 1638 \includegraphics[width=0.66\textwidth]{ZDF_zad_Aimp_maxCf_loc} 1639 \caption[OVERFLOW: maximum partitioning coefficient for the case overlaid]{ 1640 The maximum partitioning coefficient for the \forcode{nn_rdt=10.0} case overlaid with 1641 information on the gridcell i- and k-locations of the maximum value.} 1642 \label{fig:ZDF_zad_Aimp_maxCf_loc} 1643 \end{figure} 1644 1645 \subinc{\input{../../global/epilogue}} 1404 1646 1405 1647 \end{document} -
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_conservation.tex
r10442 r11831 3 3 \begin{document} 4 4 5 % ================================================================6 % Invariant of the Equations7 % ================================================================8 5 \chapter{Invariants of the Primitive Equations} 9 \label{chap:Invariant} 10 \minitoc 6 \label{chap:CONS} 7 8 \thispagestyle{plain} 9 10 \chaptertoc 11 12 \paragraph{Changes record} ~\\ 13 14 {\footnotesize 15 \begin{tabularx}{\textwidth}{l||X|X} 16 Release & Author(s) & Modifications \\ 17 \hline 18 {\em 4.0} & {\em ...} & {\em ...} \\ 19 {\em 3.6} & {\em ...} & {\em ...} \\ 20 {\em 3.4} & {\em ...} & {\em ...} \\ 21 {\em <=3.4} & {\em ...} & {\em ...} 22 \end{tabularx} 23 } 24 25 \clearpage 11 26 12 27 The continuous equations of motion have many analytic properties. … … 21 36 horizontal kinetic energy and/or potential enstrophy of horizontally non-divergent flow, 22 37 and variance of temperature and salinity will be conserved in the absence of dissipative effects and forcing. 23 \citet{ Arakawa1966} has first pointed out the advantage of this approach.38 \citet{arakawa_JCP66} has first pointed out the advantage of this approach. 24 39 He showed that if integral constraints on energy are maintained, 25 40 the computation will be free of the troublesome "non linear" instability originally pointed out by 26 \citet{ Phillips1959}.41 \citet{phillips_TAMS59}. 27 42 A consistent formulation of the energetic properties is also extremely important in carrying out 28 43 long-term numerical simulations for an oceanographic model. 29 Such a formulation avoids systematic errors that accumulate with time \citep{ Bryan1997}.44 Such a formulation avoids systematic errors that accumulate with time \citep{bryan_JCP97}. 30 45 31 46 The general philosophy of OPA which has led to the discrete formulation presented in {\S}II.2 and II.3 is to … … 35 50 The alternative is to use diffusive schemes such as upstream or flux corrected schemes. 36 51 This last option was rejected because we prefer a complete handling of the model diffusion, 37 \ie of the model physics rather than letting the advective scheme produces its own implicit diffusion without52 \ie\ of the model physics rather than letting the advective scheme produces its own implicit diffusion without 38 53 controlling the space and time structure of this implicit diffusion. 39 54 Note that in some very specific cases as passive tracer studies, the positivity of the advective scheme is required. 40 55 In that case, and in that case only, the advective scheme used for passive tracer is a flux correction scheme 41 \citep{Marti1992, Levy1996, Levy1998}. 42 43 % ------------------------------------------------------------------------------------------------------------- 44 % Conservation Properties on Ocean Dynamics 45 % ------------------------------------------------------------------------------------------------------------- 56 \citep{Marti1992?, Levy1996?, Levy1998?}. 57 58 %% ================================================================================================= 46 59 \section{Conservation properties on ocean dynamics} 47 \label{sec: Invariant_dyn}60 \label{sec:CONS_Invariant_dyn} 48 61 49 62 The non linear term of the momentum equations has been split into a vorticity term, … … 63 76 The continuous formulation of the vorticity term satisfies following integral constraints: 64 77 \[ 65 % \label{eq: vor_vorticity}78 % \label{eq:CONS_vor_vorticity} 66 79 \int_D {{\textbf {k}}\cdot \frac{1}{e_3 }\nabla \times \left( {\varsigma 67 \;{\ rm {\bf k}}\times {\textbf {U}}_h } \right)\;dv} =068 \] 69 70 \[ 71 % \label{eq: vor_enstrophy}80 \;{\mathrm {\mathbf k}}\times {\textbf {U}}_h } \right)\;dv} =0 81 \] 82 83 \[ 84 % \label{eq:CONS_vor_enstrophy} 72 85 if\quad \chi =0\quad \quad \int\limits_D {\varsigma \;{\textbf{k}}\cdot 73 86 \frac{1}{e_3 }\nabla \times \left( {\varsigma {\textbf{k}}\times {\textbf{U}}_h } \right)\;dv} =-\int\limits_D {\frac{1}{2}\varsigma ^2\,\chi \;dv} … … 76 89 77 90 \[ 78 % \label{eq: vor_energy}91 % \label{eq:CONS_vor_energy} 79 92 \int_D {{\textbf{U}}_h \times \left( {\varsigma \;{\textbf{k}}\times {\textbf{U}}_h } \right)\;dv} =0 80 93 \] … … 88 101 Using the symmetry or anti-symmetry properties of the operators (Eqs II.1.10 and 11), 89 102 it can be shown that the scheme (II.2.11) satisfies (II.4.1b) but not (II.4.1c), 90 while scheme (II.2.12) satisfies (II.4.1c) but not (II.4.1b) (see appendix C). 103 while scheme (II.2.12) satisfies (II.4.1c) but not (II.4.1b) (see appendix C). 91 104 Note that the enstrophy conserving scheme on total vorticity has been chosen as the standard discrete form of 92 105 the vorticity term. … … 102 115 the horizontal gradient of horizontal kinetic energy: 103 116 104 \begin{equation} \label{eq: keg_zad}105 \int_D {{\textbf{U}}_h \cdot \nabla _h \left( {1/2\;{\textbf{U}}_h ^2} \right)\;dv} =-\int_D {{\textbf{U}}_h \cdot \frac{w}{e_3 }\;\frac{\partial 117 \begin{equation} \label{eq:CONS_keg_zad} 118 \int_D {{\textbf{U}}_h \cdot \nabla _h \left( {1/2\;{\textbf{U}}_h ^2} \right)\;dv} =-\int_D {{\textbf{U}}_h \cdot \frac{w}{e_3 }\;\frac{\partial 106 119 {\textbf{U}}_h }{\partial k}\;dv} 107 120 \end{equation} 108 121 109 122 Using the discrete form given in {\S}II.2-a and the symmetry or anti-symmetry properties of 110 the mean and difference operators, \autoref{eq: keg_zad} is demonstrated in the Appendix C.111 The main point here is that satisfying \autoref{eq: keg_zad} links the choice of the discrete forms of123 the mean and difference operators, \autoref{eq:CONS_keg_zad} is demonstrated in the Appendix C. 124 The main point here is that satisfying \autoref{eq:CONS_keg_zad} links the choice of the discrete forms of 112 125 the vertical advection and of the horizontal gradient of horizontal kinetic energy. 113 126 Choosing one imposes the other. … … 122 135 This properties is satisfied locally with the choice of discretization we have made (property (II.1.9)~). 123 136 In addition, when the equation of state is linear 124 (\ie when an advective-diffusive equation for density can be derived from those of temperature and salinity)137 (\ie\ when an advective-diffusive equation for density can be derived from those of temperature and salinity) 125 138 the change of horizontal kinetic energy due to the work of pressure forces is balanced by the change of 126 139 potential energy due to buoyancy forces: 127 140 128 141 \[ 129 % \label{eq: hpg_pe}142 % \label{eq:CONS_hpg_pe} 130 143 \int_D {-\frac{1}{\rho_o }\left. {\nabla p^h} \right|_z \cdot {\textbf {U}}_h \;dv} \;=\;\int_D {\nabla .\left( {\rho \,{\textbf{U}}} \right)\;g\;z\;\;dv} 131 144 \] … … 133 146 Using the discrete form given in {\S}~II.2-a and the symmetry or anti-symmetry properties of 134 147 the mean and difference operators, (II.4.3) is demonstrated in the Appendix C. 135 The main point here is that satisfying (II.4.3) strongly constraints the discrete expression of the depth of 148 The main point here is that satisfying (II.4.3) strongly constraints the discrete expression of the depth of 136 149 $T$-points and of the term added to the pressure gradient in $s-$coordinates: the depth of a $T$-point, $z_T$, 137 150 is defined as the sum the vertical scale factors at $w$-points starting from the surface. … … 145 158 Nevertheless, the $\psi$-equation is solved numerically by an iterative solver (see {\S}~III.5), 146 159 thus the property is only satisfied with the accuracy required on the solver. 147 In addition, with the rigid-lid approximation, the change of horizontal kinetic energy due to the work of 160 In addition, with the rigid-lid approximation, the change of horizontal kinetic energy due to the work of 148 161 surface pressure forces is exactly zero: 149 162 \[ 150 % \label{eq: spg}163 % \label{eq:CONS_spg} 151 164 \int_D {-\frac{1}{\rho_o }\nabla _h } \left( {p_s } \right)\cdot {\textbf{U}}_h \;dv=0 152 165 \] … … 157 170 otherwise there is no guarantee that the surface pressure force work vanishes. 158 171 159 % ------------------------------------------------------------------------------------------------------------- 160 % Conservation Properties on Ocean Thermodynamics 161 % ------------------------------------------------------------------------------------------------------------- 172 %% ================================================================================================= 162 173 \section{Conservation properties on ocean thermodynamics} 163 \label{sec: Invariant_tra}174 \label{sec:CONS_Invariant_tra} 164 175 165 176 In continuous formulation, the advective terms of the tracer equations conserve the tracer content and 166 177 the quadratic form of the tracer, \ie 167 178 \[ 168 % \label{eq: tra_tra2}179 % \label{eq:CONS_tra_tra2} 169 180 \int_D {\nabla .\left( {T\;{\textbf{U}}} \right)\;dv} =0 170 181 \;\text{and} … … 176 187 Note that in both continuous and discrete formulations, there is generally no strict conservation of mass, 177 188 since the equation of state is non linear with respect to $T$ and $S$. 178 In practice, the mass is conserved with a very good accuracy. 179 180 % ------------------------------------------------------------------------------------------------------------- 181 % Conservation Properties on Momentum Physics 182 % ------------------------------------------------------------------------------------------------------------- 189 In practice, the mass is conserved with a very good accuracy. 190 191 %% ================================================================================================= 183 192 \subsection{Conservation properties on momentum physics} 184 \label{subsec: Invariant_dyn_physics}193 \label{subsec:CONS_Invariant_dyn_physics} 185 194 186 195 \textbf{* lateral momentum diffusion term} … … 188 197 The continuous formulation of the horizontal diffusion of momentum satisfies the following integral constraints~: 189 198 \[ 190 % \label{eq: dynldf_dyn}191 \int\limits_D {\frac{1}{e_3 }{\ rm {\bf k}}\cdot \nabla \times \left[ {\nabla199 % \label{eq:CONS_dynldf_dyn} 200 \int\limits_D {\frac{1}{e_3 }{\mathrm {\mathbf k}}\cdot \nabla \times \left[ {\nabla 192 201 _h \left( {A^{lm}\;\chi } \right)-\nabla _h \times \left( {A^{lm}\;\zeta 193 \;{\ rm {\bf k}}} \right)} \right]\;dv} =0194 \] 195 196 \[ 197 % \label{eq: dynldf_div}202 \;{\mathrm {\mathbf k}}} \right)} \right]\;dv} =0 203 \] 204 205 \[ 206 % \label{eq:CONS_dynldf_div} 198 207 \int\limits_D {\nabla _h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi } 199 \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\ rm {\bf k}}} \right)}208 \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} 200 209 \right]\;dv} =0 201 210 \] 202 211 203 212 \[ 204 % \label{eq: dynldf_curl}205 \int_D {{\ rm {\bf U}}_h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi }206 \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\ rm {\bf k}}} \right)}213 % \label{eq:CONS_dynldf_curl} 214 \int_D {{\mathrm {\mathbf U}}_h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi } 215 \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} 207 216 \right]\;dv} \leqslant 0 208 217 \] 209 218 210 219 \[ 211 % \label{eq: dynldf_curl2}212 \mbox{if}\quad A^{lm}=cste\quad \quad \int_D {\zeta \;{\ rm {\bf k}}\cdot220 % \label{eq:CONS_dynldf_curl2} 221 \mbox{if}\quad A^{lm}=cste\quad \quad \int_D {\zeta \;{\mathrm {\mathbf k}}\cdot 213 222 \nabla \times \left[ {\nabla _h \left( {A^{lm}\;\chi } \right)-\nabla _h 214 \times \left( {A^{lm}\;\zeta \;{\ rm {\bf k}}} \right)} \right]\;dv}223 \times \left( {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} \right]\;dv} 215 224 \leqslant 0 216 225 \] 217 226 218 227 \[ 219 % \label{eq: dynldf_div2}228 % \label{eq:CONS_dynldf_div2} 220 229 \mbox{if}\quad A^{lm}=cste\quad \quad \int_D {\chi \;\nabla _h \cdot \left[ 221 230 {\nabla _h \left( {A^{lm}\;\chi } \right)-\nabla _h \times \left( 222 {A^{lm}\;\zeta \;{\rm {\bf k}}} \right)} \right]\;dv} \leqslant 0 223 \] 224 231 {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} \right]\;dv} \leqslant 0 232 \] 225 233 226 234 (II.4.6a) and (II.4.6b) means that the horizontal diffusion of momentum conserve both the potential vorticity and … … 250 258 251 259 \[ 252 % \label{eq: dynzdf_dyn}260 % \label{eq:CONS_dynzdf_dyn} 253 261 \begin{aligned} 254 262 & \int_D {\frac{1}{e_3 }} \frac{\partial }{\partial k}\left( \frac{A^{vm}}{e_3 }\frac{\partial {\textbf{U}}_h }{\partial k} \right) \;dv = \overrightarrow{\textbf{0}} \\ … … 258 266 conservation of vorticity, dissipation of enstrophy 259 267 \[ 260 % \label{eq: dynzdf_vor}261 \begin{aligned} 262 & \int_D {\frac{1}{e_3 }{\ rm {\bf k}}\cdot \nabla \times \left( {\frac{1}{e_3263 }\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\ rm264 {\ bf U}}_h }{\partial k}} \right)} \right)\;dv} =0 \\265 & \int_D {\zeta \,{\ rm {\bf k}}\cdot \nabla \times \left( {\frac{1}{e_3266 }\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\ rm267 {\ bf U}}_h }{\partial k}} \right)} \right)\;dv} \leq 0 \\268 % \label{eq:CONS_dynzdf_vor} 269 \begin{aligned} 270 & \int_D {\frac{1}{e_3 }{\mathrm {\mathbf k}}\cdot \nabla \times \left( {\frac{1}{e_3 271 }\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\mathrm 272 {\mathbf U}}_h }{\partial k}} \right)} \right)\;dv} =0 \\ 273 & \int_D {\zeta \,{\mathrm {\mathbf k}}\cdot \nabla \times \left( {\frac{1}{e_3 274 }\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\mathrm 275 {\mathbf U}}_h }{\partial k}} \right)} \right)\;dv} \leq 0 \\ 268 276 \end{aligned} 269 277 \] 270 278 conservation of horizontal divergence, dissipation of square of the horizontal divergence 271 279 \[ 272 % \label{eq: dynzdf_div}280 % \label{eq:CONS_dynzdf_div} 273 281 \begin{aligned} 274 282 &\int_D {\nabla \cdot \left( {\frac{1}{e_3 }\frac{\partial }{\partial 275 k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\ rm {\bf U}}_h }{\partial k}}283 k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\mathrm {\mathbf U}}_h }{\partial k}} 276 284 \right)} \right)\;dv} =0 \\ 277 285 & \int_D {\chi \;\nabla \cdot \left( {\frac{1}{e_3 }\frac{\partial }{\partial 278 k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\ rm {\bf U}}_h }{\partial k}}286 k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\mathrm {\mathbf U}}_h }{\partial k}} 279 287 \right)} \right)\;dv} \leq 0 \\ 280 288 \end{aligned} … … 283 291 In discrete form, all these properties are satisfied in $z$-coordinate (see Appendix C). 284 292 In $s$-coordinates, only first order properties can be demonstrated, 285 \ie the vertical momentum physics conserve momentum, potential vorticity, and horizontal divergence. 286 287 % ------------------------------------------------------------------------------------------------------------- 288 % Conservation Properties on Tracer Physics 289 % ------------------------------------------------------------------------------------------------------------- 293 \ie\ the vertical momentum physics conserve momentum, potential vorticity, and horizontal divergence. 294 295 %% ================================================================================================= 290 296 \subsection{Conservation properties on tracer physics} 291 \label{subsec: Invariant_tra_physics}297 \label{subsec:CONS_Invariant_tra_physics} 292 298 293 299 The numerical schemes used for tracer subgridscale physics are written in such a way that 294 300 the heat and salt contents are conserved (equations in flux form, second order centred finite differences). 295 301 As a form flux is used to compute the temperature and salinity, 296 the quadratic form of these quantities (\ie their variance) globally tends to diminish.302 the quadratic form of these quantities (\ie\ their variance) globally tends to diminish. 297 303 As for the advective term, there is generally no strict conservation of mass even if, 298 in practice, the mass is conserved with a very good accuracy. 299 300 \textbf{* lateral physics: }conservation of tracer, dissipation of tracer 304 in practice, the mass is conserved with a very good accuracy. 305 306 \textbf{* lateral physics: }conservation of tracer, dissipation of tracer 301 307 variance, i.e. 302 308 303 309 \[ 304 % \label{eq: traldf_t_t2}310 % \label{eq:CONS_traldf_t_t2} 305 311 \begin{aligned} 306 312 &\int_D \nabla\, \cdot\, \left( A^{lT} \,\Re \,\nabla \,T \right)\;dv = 0 \\ … … 312 318 313 319 \[ 314 % \label{eq: trazdf_t_t2}320 % \label{eq:CONS_trazdf_t_t2} 315 321 \begin{aligned} 316 322 & \int_D \frac{1}{e_3 } \frac{\partial }{\partial k}\left( \frac{A^{vT}}{e_3 } \frac{\partial T}{\partial k} \right)\;dv = 0 \\ … … 328 334 It has not been implemented. 329 335 330 \biblio 331 332 \pindex 336 \subinc{\input{../../global/epilogue}} 333 337 334 338 \end{document} -
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_misc.tex
r10601 r11831 2 2 3 3 \begin{document} 4 % ================================================================ 5 % Chapter --- Miscellaneous Topics 6 % ================================================================ 4 7 5 \chapter{Miscellaneous Topics} 8 6 \label{chap:MISC} 9 7 10 \minitoc 11 12 \newpage 13 14 % ================================================================ 15 % Representation of Unresolved Straits 16 % ================================================================ 8 \thispagestyle{plain} 9 10 \chaptertoc 11 12 \paragraph{Changes record} ~\\ 13 14 {\footnotesize 15 \begin{tabularx}{\textwidth}{l||X|X} 16 Release & Author(s) & Modifications \\ 17 \hline 18 {\em 4.0} & {\em ...} & {\em ...} \\ 19 {\em 3.6} & {\em ...} & {\em ...} \\ 20 {\em 3.4} & {\em ...} & {\em ...} \\ 21 {\em <=3.4} & {\em ...} & {\em ...} 22 \end{tabularx} 23 } 24 25 \clearpage 26 27 %% ================================================================================================= 17 28 \section{Representation of unresolved straits} 18 29 \label{sec:MISC_strait} … … 27 38 balance the net evaporation occurring over the Mediterranean region. 28 39 This problem occurs even in eddy permitting simulations. 29 For example, in ORCA 1/4\deg several straits of the Indonesian archipelago (Ombai, Lombok...)40 For example, in ORCA 1/4\deg\ several straits of the Indonesian archipelago (Ombai, Lombok...) 30 41 are much narrow than even a single ocean grid-point. 31 42 32 We describe briefly here the three methods that can be used in \NEMO to handle such improperly resolved straits. 33 The first two consist of opening the strait by hand while ensuring that the mass exchanges through 34 the strait are not too large by either artificially reducing the surface of the strait grid-cells or, 35 locally increasing the lateral friction. 36 In the third one, the strait is closed but exchanges of mass, heat and salt across the land are allowed. 37 Note that such modifications are so specific to a given configuration that no attempt has been made to 38 set them in a generic way. 39 However, examples of how they can be set up is given in the ORCA 2\deg and 0.5\deg configurations. 40 For example, for details of implementation in ORCA2, search: \texttt{IF( cp\_cfg == "orca" .AND. jp\_cfg == 2 )} 41 42 % ------------------------------------------------------------------------------------------------------------- 43 % Hand made geometry changes 44 % ------------------------------------------------------------------------------------------------------------- 43 We describe briefly here the two methods that can be used in \NEMO\ to handle such 44 improperly resolved straits. The methods consist of opening the strait while ensuring 45 that the mass exchanges through the strait are not too large by either artificially 46 reducing the cross-sectional area of the strait grid-cells or, locally increasing the 47 lateral friction. 48 49 %% ================================================================================================= 45 50 \subsection{Hand made geometry changes} 46 51 \label{subsec:MISC_strait_hand} 47 52 48 $\bullet$ reduced scale factor in the cross-strait direction to a value in better agreement with 49 the true mean width of the strait (\autoref{fig:MISC_strait_hand}). 50 This technique is sometime called "partially open face" or "partially closed cells". 51 The key issue here is only to reduce the faces of $T$-cell 52 (\ie change the value of the horizontal scale factors at $u$- or $v$-point) but not the volume of the $T$-cell. 53 Indeed, reducing the volume of strait $T$-cell can easily produce a numerical instability at 54 that grid point that would require a reduction of the model time step. 55 The changes associated with strait management are done in \mdl{domhgr}, 56 just after the definition or reading of the horizontal scale factors. 57 58 $\bullet$ increase of the viscous boundary layer thickness by local increase of the fmask value at the coast 59 (\autoref{fig:MISC_strait_hand}). 60 This is done in \mdl{dommsk} together with the setting of the coastal value of fmask (see \autoref{sec:LBC_coast}). 61 62 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 53 The first method involves reducing the scale factor in the cross-strait direction to a 54 value in better agreement with the true mean width of the strait 55 (\autoref{fig:MISC_strait_hand}). This technique is sometime called "partially open face" 56 or "partially closed cells". The key issue here is only to reduce the faces of $T$-cell 57 (\ie\ change the value of the horizontal scale factors at $u$- or $v$-point) but not the 58 volume of the $T$-cell. Indeed, reducing the volume of strait $T$-cell can easily produce 59 a numerical instability at that grid point which would require a reduction of the model 60 time step. Thus to instigate a local change in the width of a Strait requires two steps: 61 62 \begin{itemize} 63 64 \item Add \texttt{e1e2u} and \texttt{e1e2v} arrays to the \np{cn_domcfg}{cn\_domcfg} file. These 2D 65 arrays should contain the products of the unaltered values of: $\texttt{e1u}*\texttt{e2u}$ 66 and $\texttt{e1u}*\texttt{e2v}$ respectively. That is the original surface areas of $u$- 67 and $v$- cells respectively. These areas are usually defined by the corresponding product 68 within the \NEMO\ code but the presence of \texttt{e1e2u} and \texttt{e1e2v} in the 69 \np{cn_domcfg}{cn\_domcfg} file will suppress this calculation and use the supplied fields instead. 70 If the model domain is provided by user-supplied code in \mdl{usrdef\_hgr}, then this 71 routine should also return \texttt{e1e2u} and \texttt{e1e2v} and set the integer return 72 argument \texttt{ie1e2u\_v} to a non-zero value. Values other than 0 for this argument 73 will suppress the calculation of the areas. 74 75 \item Change values of \texttt{e2u} or \texttt{e1v} (either in the \np{cn_domcfg}{cn\_domcfg} file or 76 via code in \mdl{usrdef\_hgr}), whereever a Strait reduction is required. The choice of 77 whether to alter \texttt{e2u} or \texttt{e1v} depends. respectively, on whether the 78 Strait in question is North-South orientated (\eg\ Gibraltar) or East-West orientated (\eg 79 Lombok). 80 81 \end{itemize} 82 83 The second method is to increase the viscous boundary layer thickness by a local increase 84 of the fmask value at the coast. This method can also be effective in wider passages. The 85 concept is illustarted in the second part of \autoref{fig:MISC_strait_hand} and changes 86 to specific locations can be coded in \mdl{usrdef\_fmask}. The \forcode{usr_def_fmask} 87 routine is always called after \texttt{fmask} has been defined according to the choice of 88 lateral boundary condition as discussed in \autoref{sec:LBC_coast}. The default version of 89 \mdl{usrdef\_fmask} contains settings specific to ORCA2 and ORCA1 configurations. These are 90 meant as examples only; it is up to the user to verify settings and provide alternatives 91 for their own configurations. The default \forcode{usr_def_fmask} makes no changes to 92 \texttt{fmask} for any other configuration. 93 63 94 \begin{figure}[!tbp] 64 \begin{center} 65 \includegraphics[width=0.80\textwidth]{Fig_Gibraltar} 66 \includegraphics[width=0.80\textwidth]{Fig_Gibraltar2} 67 \caption{ 68 \protect\label{fig:MISC_strait_hand} 69 Example of the Gibraltar strait defined in a $1^{\circ} \times 1^{\circ}$ mesh. 70 \textit{Top}: using partially open cells. 71 The meridional scale factor at $v$-point is reduced on both sides of the strait to account for 72 the real width of the strait (about 20 km). 73 Note that the scale factors of the strait $T$-point remains unchanged. 74 \textit{Bottom}: using viscous boundary layers. 75 The four fmask parameters along the strait coastlines are set to a value larger than 4, 76 \ie "strong" no-slip case (see \autoref{fig:LBC_shlat}) creating a large viscous boundary layer that 77 allows a reduced transport through the strait. 78 } 79 \end{center} 95 \centering 96 \includegraphics[width=0.66\textwidth]{MISC_Gibraltar} 97 \includegraphics[width=0.66\textwidth]{MISC_Gibraltar2} 98 \caption[Two methods to defined the Gibraltar strait]{ 99 Example of the Gibraltar strait defined in a 1\deg\ $\times$ 1\deg\ mesh. 100 \textit{Top}: using partially open cells. 101 The meridional scale factor at $v$-point is reduced on both sides of the strait to 102 account for the real width of the strait (about 20 km). 103 Note that the scale factors of the strait $T$-point remains unchanged. 104 \textit{Bottom}: using viscous boundary layers. 105 The four fmask parameters along the strait coastlines are set to a value larger than 4, 106 \ie\ "strong" no-slip case (see \autoref{fig:LBC_shlat}) creating a large viscous boundary layer 107 that allows a reduced transport through the strait.} 108 \label{fig:MISC_strait_hand} 80 109 \end{figure} 81 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 82 83 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 110 84 111 \begin{figure}[!tbp] 85 \begin{center} 86 \includegraphics[width=1.0\textwidth]{Fig_closea_mask_example} 87 \caption{ 88 \protect\label{fig:closea_mask_example} 89 Example of mask fields for the closea module. \textit{Left}: a 90 closea\_mask field; \textit{Right}: a closea\_mask\_rnf 91 field. In this example, if ln\_closea is set to .true., the mean 92 freshwater flux over each of the American Great Lakes will be 93 set to zero, and the total residual for all the lakes, if 94 negative, will be put into the St Laurence Seaway in the area 95 shown. 96 } 97 \end{center} 112 \centering 113 \includegraphics[width=0.66\textwidth]{MISC_closea_mask_example} 114 \caption[Mask fields for the \protect\mdl{closea} module]{ 115 Example of mask fields for the \protect\mdl{closea} module. 116 \textit{Left}: a closea\_mask field; 117 \textit{Right}: a closea\_mask\_rnf field. 118 In this example, if \protect\np{ln_closea}{ln\_closea} is set to \forcode{.true.}, 119 the mean freshwater flux over each of the American Great Lakes will be set to zero, 120 and the total residual for all the lakes, if negative, will be put into 121 the St Laurence Seaway in the area shown.} 122 \label{fig:MISC_closea_mask_example} 98 123 \end{figure} 99 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 100 101 % ================================================================ 102 % Closed seas 103 % ================================================================ 104 \section{Closed seas (\protect\mdl{closea})} 124 125 %% ================================================================================================= 126 \section[Closed seas (\textit{closea.F90})]{Closed seas (\protect\mdl{closea})} 105 127 \label{sec:MISC_closea} 106 128 … … 116 138 to zero and put the residual flux into the ocean. 117 139 118 Prior to NEMO4 the locations of inland seas and lakes was set via119 hardcoded indices for various ORCA configurations. From NEMO4 onwards140 Prior to \NEMO\ 4 the locations of inland seas and lakes was set via 141 hardcoded indices for various ORCA configurations. From \NEMO\ 4 onwards 120 142 the inland seas and lakes are defined using mask fields in the 121 143 domain configuration file. The options are as follows. 122 144 123 145 \begin{enumerate} 124 \item {{\bfNo ``closea\_mask'' field is included in domain configuration146 \item {{\bfseries No ``closea\_mask'' field is included in domain configuration 125 147 file.} In this case the closea module does nothing.} 126 148 127 \item {{\bfA field called closea\_mask is included in the domain149 \item {{\bfseries A field called closea\_mask is included in the domain 128 150 configuration file and ln\_closea=.false. in namelist namcfg.} In this 129 151 case the inland seas defined by the closea\_mask field are filled in … … 131 153 closea\_mask that is nonzero is set to be a land point.} 132 154 133 \item {{\bfA field called closea\_mask is included in the domain155 \item {{\bfseries A field called closea\_mask is included in the domain 134 156 configuration file and ln\_closea=.true. in namelist namcfg.} Each 135 157 inland sea or group of inland seas is set to a positive integer value 136 in the closea\_mask field (see Figure \ref{fig:closea_mask_example}158 in the closea\_mask field (see \autoref{fig:MISC_closea_mask_example} 137 159 for an example). The net surface flux over each inland sea or group of 138 160 inland seas is set to zero each timestep and the residual flux is … … 140 162 closea\_mask is zero).} 141 163 142 \item {{\bfFields called closea\_mask and closea\_mask\_rnf are164 \item {{\bfseries Fields called closea\_mask and closea\_mask\_rnf are 143 165 included in the domain configuration file and ln\_closea=.true. in 144 166 namelist namcfg.} This option works as for option 3, except that if … … 149 171 by the closea\_mask\_rnf field. Each mapping is defined by a positive 150 172 integer value for the inland sea(s) and the corresponding runoff 151 points. An example is given in Figure152 \ ref{fig:closea_mask_example}. If no mapping is provided for a173 points. An example is given in 174 \autoref{fig:MISC_closea_mask_example}. If no mapping is provided for a 153 175 particular inland sea then the residual is spread over the global 154 176 ocean.} 155 177 156 \item {{\bfFields called closea\_mask and closea\_mask\_emp are178 \item {{\bfseries Fields called closea\_mask and closea\_mask\_emp are 157 179 included in the domain configuration file and ln\_closea=.true. in 158 180 namelist namcfg.} This option works the same as option 4 except that … … 164 186 165 187 There is a python routine to create the closea\_mask fields and append 166 them to the domain configuration file in the utils/tools/DOMAINcfg directory. 167 168 % ================================================================ 169 % Sub-Domain Functionality 170 % ================================================================ 188 them to the domain configuration file in the utils/tools/DOMAINcfg directory. 189 190 %% ================================================================================================= 171 191 \section{Sub-domain functionality} 172 192 \label{sec:MISC_zoom} 173 193 194 %% ================================================================================================= 174 195 \subsection{Simple subsetting of input files via NetCDF attributes} 175 196 176 The extended grids for use with the under-shelf ice cavities will result in redundant rows around Antarctica if 177 the ice cavities are not active. 178 A simple mechanism for subsetting input files associated with the extended domains has been implemented to 179 avoid the need to maintain different sets of input fields for use with or without active ice cavities. 180 The existing 'zoom' options are overly complex for this task and marked for deletion anyway. 181 This alternative subsetting operates for the j-direction only and works by optionally looking for and 182 using a global file attribute (named: \np{open\_ocean\_jstart}) to determine the starting j-row for input. 183 The use of this option is best explained with an example: 184 consider an ORCA1 configuration using the extended grid bathymetry and coordinate files: 185 \vspace{-10pt} 186 \ifile{eORCA1\_bathymetry\_v2} 187 \ifile{eORCA1\_coordinates} 188 \noindent These files define a horizontal domain of 362x332. 189 Assuming the first row with open ocean wet points in the non-isf bathymetry for this set is row 42 190 (\fortran indexing) then the formally correct setting for \np{open\_ocean\_jstart} is 41. 191 Using this value as the first row to be read will result in a 362x292 domain which is the same size as 192 the original ORCA1 domain. 193 Thus the extended coordinates and bathymetry files can be used with all the original input files for ORCA1 if 194 the ice cavities are not active (\np{ln\_isfcav = .false.}). 195 Full instructions for achieving this are: 196 197 \noindent Add the new attribute to any input files requiring a j-row offset, i.e: 198 \vspace{-10pt} 197 The extended grids for use with the under-shelf ice cavities will result in redundant rows 198 around Antarctica if the ice cavities are not active. A simple mechanism for subsetting 199 input files associated with the extended domains has been implemented to avoid the need to 200 maintain different sets of input fields for use with or without active ice cavities. This 201 subsetting operates for the j-direction only and works by optionally looking for and using 202 a global file attribute (named: \np{open_ocean_jstart}{open\_ocean\_jstart}) to determine the starting j-row 203 for input. The use of this option is best explained with an example: 204 \medskip 205 206 \noindent Consider an ORCA1 207 configuration using the extended grid domain configuration file: \ifile{eORCA1\_domcfg.nc} 208 This file define a horizontal domain of 362x332. The first row with 209 open ocean wet points in the non-isf bathymetry for this set is row 42 (\fortran\ indexing) 210 then the formally correct setting for \np{open_ocean_jstart}{open\_ocean\_jstart} is 41. Using this value as 211 the first row to be read will result in a 362x292 domain which is the same size as the 212 original ORCA1 domain. Thus the extended domain configuration file can be used with all 213 the original input files for ORCA1 if the ice cavities are not active (\np{ln\_isfcav = 214 .false.}). Full instructions for achieving this are: 215 216 \begin{itemize} 217 \item Add the new attribute to any input files requiring a j-row offset, i.e: 199 218 \begin{cmds} 200 ncatted -a open_ocean_jstart,global,a,d,41 eORCA1_coordinates.nc 201 ncatted -a open_ocean_jstart,global,a,d,41 eORCA1_bathymetry_v2.nc 219 ncatted -a open_ocean_jstart,global,a,d,41 eORCA1_domcfg.nc 202 220 \end{cmds} 203 204 \noindent Add the logical switch to \ngn{namcfg} in the configuration namelist and set true: 205 %--------------------------------------------namcfg-------------------------------------------------------- 206 207 \nlst{namcfg} 208 %-------------------------------------------------------------------------------------------------------------- 209 210 \noindent Note the j-size of the global domain is the (extended j-size minus \np{open\_ocean\_jstart} + 1 ) and 211 this must match the size of all datasets other than bathymetry and coordinates currently. 212 However the option can be extended to any global, 2D and 3D, netcdf, input field by adding the: 213 \vspace{-10pt} 221 222 \item Add the logical switch \np{ln_use_jattr}{ln\_use\_jattr} to \nam{cfg}{cfg} in the configuration 223 namelist (if it is not already there) and set \forcode{.true.} 224 \end{itemize} 225 226 \noindent Note that with this option, the j-size of the global domain is (extended 227 j-size minus \np{open_ocean_jstart}{open\_ocean\_jstart} + 1 ) and this must match the \texttt{jpjglo} value 228 for the configuration. This means an alternative version of \ifile{eORCA1\_domcfg.nc} must 229 be created for when \np{ln_use_jattr}{ln\_use\_jattr} is active. The \texttt{ncap2} tool provides a 230 convenient way of achieving this: 231 232 \begin{cmds} 233 ncap2 -s 'jpjglo=292' eORCA1_domcfg.nc nORCA1_domcfg.nc 234 \end{cmds} 235 236 The domain configuration file is unique in this respect since it also contains the value of \jp{jpjglo} 237 that is read and used by the model. 238 Any other global, 2D and 3D, netcdf, input field can be prepared for use in a reduced domain by adding the 239 \texttt{open\_ocean\_jstart} attribute to the file's global attributes. 240 In particular this is true for any field that is read by \NEMO\ using the following optional argument to 241 the appropriate call to \np{iom_get}{iom\_get}. 242 214 243 \begin{forlines} 215 244 lrowattr=ln_use_jattr 216 245 \end{forlines} 217 optional argument to the appropriate \np{iom\_get} call and the \np{open\_ocean\_jstart} attribute to 218 the corresponding input files. 219 It remains the users responsibility to set \np{jpjdta} and \np{jpjglo} values in 220 the \np{namelist\_cfg} file according to their needs. 221 222 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 223 \begin{figure}[!ht] 224 \begin{center} 225 \includegraphics[width=0.90\textwidth]{Fig_LBC_zoom} 226 \caption{ 227 \protect\label{fig:LBC_zoom} 228 Position of a model domain compared to the data input domain when the zoom functionality is used. 229 } 230 \end{center} 231 \end{figure} 232 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 233 234 235 % ================================================================ 236 % Accuracy and Reproducibility 237 % ================================================================ 238 \section{Accuracy and reproducibility (\protect\mdl{lib\_fortran})} 246 247 Currently, only the domain configuration variables make use of this optional argument so 248 this facility is of little practical use except for tests where no other external input 249 files are needed or you wish to use an extended domain configuration with inputs from 250 earlier, non-extended configurations. Alternatively, it should be possible to exclude 251 empty rows for extended domain, forced ocean runs using interpolation on the fly, by 252 adding the optional argument to \texttt{iom\_get} calls for the weights and initial 253 conditions. Experimenting with this remains an exercise for the user. 254 255 %% ================================================================================================= 256 \section[Accuracy and reproducibility (\textit{lib\_fortran.F90})]{Accuracy and reproducibility (\protect\mdl{lib\_fortran})} 239 257 \label{sec:MISC_fortran} 240 258 241 \subsection{Issues with intrinsinc SIGN function (\protect\key{nosignedzero})} 259 %% ================================================================================================= 260 \subsection[Issues with intrinsinc SIGN function (\texttt{\textbf{key\_nosignedzero}})]{Issues with intrinsinc SIGN function (\protect\key{nosignedzero})} 242 261 \label{subsec:MISC_sign} 243 262 244 The SIGN(A, B) is the \fortran intrinsic function delivers the magnitude of A with the sign of B.263 The SIGN(A, B) is the \fortran\ intrinsic function delivers the magnitude of A with the sign of B. 245 264 For example, SIGN(-3.0,2.0) has the value 3.0. 246 265 The problematic case is when the second argument is zero, because, on platforms that support IEEE arithmetic, … … 254 273 and the processor is capable of distinguishing between positive and negative zero, 255 274 and B is negative real zero. 256 Then SIGN delivers a negative result where, under \fninety rules, it used to return a positive result.275 Then SIGN delivers a negative result where, under \fninety\ rules, it used to return a positive result. 257 276 This change may be especially sensitive for the ice model, 258 277 so we overwrite the intrinsinc function with our own function simply performing : \\ … … 264 283 some computers/compilers. 265 284 266 285 %% ================================================================================================= 267 286 \subsection{MPP reproducibility} 268 287 \label{subsec:MISC_glosum} 269 288 270 289 The numerical reproducibility of simulations on distributed memory parallel computers is a critical issue. 271 In particular, within NEMOglobal summation of distributed arrays is most susceptible to rounding errors,290 In particular, within \NEMO\ global summation of distributed arrays is most susceptible to rounding errors, 272 291 and their propagation and accumulation cause uncertainty in final simulation reproducibility on 273 292 different numbers of processors. 274 To avoid so, based on \citet{ He_Ding_JSC01} review of different technics,293 To avoid so, based on \citet{he.ding_JS01} review of different technics, 275 294 we use a so called self-compensated summation method. 276 The idea is to estimate the roundoff error, store it in a buffer, and then add it back in the next addition. 295 The idea is to estimate the roundoff error, store it in a buffer, and then add it back in the next addition. 277 296 278 297 Suppose we need to calculate $b = a_1 + a_2 + a_3$. … … 292 311 The self-compensated summation method should be used in all summation in i- and/or j-direction. 293 312 See \mdl{closea} module for an example. 294 Note also that this implementation may be sensitive to the optimization level. 295 313 Note also that this implementation may be sensitive to the optimization level. 314 315 %% ================================================================================================= 296 316 \subsection{MPP scalability} 297 317 \label{subsec:MISC_mppsca} … … 313 333 be set at all the locations actually required by each individual for the fold operation. 314 334 This alternative method should give identical results to the default \textsc{ALLGATHER} method and 315 is recommended for large values of \np{jpni} .316 The new method is activated by setting \np{ln \_nnogather} to be true ({\bf nammpp}).335 is recommended for large values of \np{jpni}{jpni}. 336 The new method is activated by setting \np{ln_nnogather}{ln\_nnogather} to be true (\nam{mpp}{mpp}). 317 337 The reproducibility of results using the two methods should be confirmed for each new, 318 338 non-reference configuration. 319 339 320 % ================================================================ 321 % Model optimisation, Control Print and Benchmark 322 % ================================================================ 340 %% ================================================================================================= 323 341 \section{Model optimisation, control print and benchmark} 324 342 \label{sec:MISC_opt} 325 %--------------------------------------------namctl------------------------------------------------------- 326 327 \nlst{namctl} 328 %-------------------------------------------------------------------------------------------------------------- 329 330 Options are defined through the \ngn{namctl} namelist variables. 331 343 344 \begin{listing} 345 \nlst{namctl} 346 \caption{\forcode{&namctl}} 347 \label{lst:namctl} 348 \end{listing} 349 350 Options are defined through the \nam{ctl}{ctl} namelist variables. 351 352 %% ================================================================================================= 332 353 \subsection{Vector optimisation} 333 354 … … 335 356 This is very a very efficient way to increase the length of vector calculations and thus 336 357 to speed up the model on vector computers. 337 358 338 359 % Add here also one word on NPROMA technique that has been found useless, since compiler have made significant progress during the last decade. 339 360 340 361 % Add also one word on NEC specific optimisation (Novercheck option for example) 341 362 363 %% ================================================================================================= 342 364 \subsection{Control print} 343 365 344 The \np{ln \_ctl} switch was originally used as a debugging option in two modes:366 The \np{ln_ctl}{ln\_ctl} switch was originally used as a debugging option in two modes: 345 367 346 368 \begin{enumerate} 347 \item {\np{ln\_ctl}: compute and print the trends averaged over the interior domain in all TRA, DYN, LDF and369 \item {\np{ln_ctl}{ln\_ctl}: compute and print the trends averaged over the interior domain in all TRA, DYN, LDF and 348 370 ZDF modules. 349 371 This option is very helpful when diagnosing the origin of an undesired change in model results. } 350 372 351 \item {also \np{ln\_ctl} but using the nictl and njctl namelist parameters to check the source of differences between373 \item {also \np{ln_ctl}{ln\_ctl} but using the nictl and njctl namelist parameters to check the source of differences between 352 374 mono and multi processor runs.} 353 375 \end{enumerate} 354 376 355 377 However, in recent versions it has also been used to force all processors to assume the 356 reporting role. Thus when \np{ln \_ctl} is true all processors produce their own versions378 reporting role. Thus when \np{ln_ctl}{ln\_ctl} is true all processors produce their own versions 357 379 of files such as: ocean.output, layout.dat, etc. All such files, beyond the the normal 358 380 reporting processor (narea == 1), are named with a \_XXXX extension to their name, where … … 360 382 such as run.stat (and its netCDF counterpart: run.stat.nc) and tracer.stat contain global 361 383 information and are only ever produced by the reporting master (narea == 1). For version 362 4.0 a start has been made to return \np{ln \_ctl} to its original function by introducing384 4.0 a start has been made to return \np{ln_ctl}{ln\_ctl} to its original function by introducing 363 385 a new control structure which allows finer control over which files are produced. This 364 386 feature is still evolving but it does already allow the user to: select individually the … … 386 408 at a suitably long interval. For example: 387 409 388 \begin{verbatim} 410 \begin{verbatim} 389 411 sn_cfctl%ptimincr = 25 390 412 \end{verbatim} 391 413 392 will carry out the global communications and write the information every 25 timesteps. This 414 will carry out the global communications and write the information every 25 timesteps. This 393 415 increment also applies to the time.step file which is otherwise updated every timestep. 394 416 395 % ================================================================ 396 \biblio 397 398 \pindex 417 \subinc{\input{../../global/epilogue}} 399 418 400 419 \end{document} -
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_model_basics.tex
r10544 r11831 3 3 \begin{document} 4 4 5 % ================================================================6 % Chapter 1 Model Basics7 % ================================================================8 5 \chapter{Model Basics} 9 \label{chap:PE} 10 \minitoc 11 12 \newpage 13 14 % ================================================================ 15 % Primitive Equations 16 % ================================================================ 6 \label{chap:MB} 7 8 \thispagestyle{plain} 9 10 \chaptertoc 11 12 \paragraph{Changes record} ~\\ 13 14 {\footnotesize 15 \begin{tabular}{l||l|l} 16 Release & Author(s) & Modifications \\ 17 \hline 18 {\em 4.0} & {\em Mike Bell } & {\em Review } \\ 19 {\em 3.6} & {\em Tim Graham and Gurvan Madec } & {\em Updates } \\ 20 {\em $\leq$ 3.4} & {\em Gurvan Madec and S\'{e}bastien Masson} & {\em First version} \\ 21 \end{tabular} 22 } 23 24 \clearpage 25 26 %% ================================================================================================= 17 27 \section{Primitive equations} 18 \label{sec:PE_PE} 19 20 % ------------------------------------------------------------------------------------------------------------- 21 % Vector Invariant Formulation 22 % ------------------------------------------------------------------------------------------------------------- 23 28 \label{sec:MB_PE} 29 30 %% ================================================================================================= 24 31 \subsection{Vector invariant formulation} 25 \label{subsec: PE_Vector}32 \label{subsec:MB_PE_vector} 26 33 27 34 The ocean is a fluid that can be described to a good approximation by the primitive equations, 28 \ie the Navier-Stokes equations along with a nonlinear equation of state which35 \ie\ the Navier-Stokes equations along with a nonlinear equation of state which 29 36 couples the two active tracers (temperature and salinity) to the fluid velocity, 30 37 plus the following additional assumptions made from scale considerations: 31 38 32 \begin{ enumerate}33 \item 34 \textit{spherical earth approximation}: the geopotential surfaces are assumed to be spheres so that35 gravity (local vertical) is parallel to the earth's radius36 \item 37 \ textit{thin-shell approximation}: the ocean depth is neglected compared to the earth's radius38 \item 39 \textit{turbulent closure hypothesis}: the turbulent fluxes39 \begin{labeling}{Neglect of additional Coriolis terms} 40 \item [\textit{Spherical Earth approximation}] The geopotential surfaces are assumed to 41 be oblate spheroids that follow the Earth's bulge; 42 these spheroids are approximated by spheres with gravity locally vertical 43 (parallel to the Earth's radius) and independent of latitude 44 \citep[][section 2]{white.hoskins.ea_QJRMS05}. 45 \item [\textit{Thin-shell approximation}] The ocean depth is neglected compared to the earth's radius 46 \item [\textit{Turbulent closure hypothesis}] The turbulent fluxes 40 47 (which represent the effect of small scale processes on the large-scale) 41 48 are expressed in terms of large-scale features 42 \item 43 \textit{Boussinesq hypothesis}: density variations are neglected except in their contribution to 44 the buoyancy force 49 \item [\textit{Boussinesq hypothesis}] Density variations are neglected except in 50 their contribution to the buoyancy force 45 51 \begin{equation} 46 \label{eq: PE_eos}52 \label{eq:MB_PE_eos} 47 53 \rho = \rho \ (T,S,p) 48 54 \end{equation} 49 \item 50 \textit{Hydrostatic hypothesis}: the vertical momentum equation is reduced to a balance between 51 the vertical pressure gradient and the buoyancy force 55 \item [\textit{Hydrostatic hypothesis}] The vertical momentum equation is reduced to 56 a balance between the vertical pressure gradient and the buoyancy force 52 57 (this removes convective processes from the initial Navier-Stokes equations and so 53 58 convective processes must be parameterized instead) 54 59 \begin{equation} 55 \label{eq: PE_hydrostatic}60 \label{eq:MB_PE_hydrostatic} 56 61 \pd[p]{z} = - \rho \ g 57 62 \end{equation} 58 \item 59 \textit{Incompressibility hypothesis}: the three dimensional divergence of the velocity vector $\vect U$ 60 is assumed to be zero. 63 \item [\textit{Incompressibility hypothesis}] The three dimensional divergence of 64 the velocity vector $\vect U$ is assumed to be zero. 61 65 \begin{equation} 62 \label{eq: PE_continuity}66 \label{eq:MB_PE_continuity} 63 67 \nabla \cdot \vect U = 0 64 68 \end{equation} 65 \end{enumerate} 69 \item [\textit{Neglect of additional Coriolis terms}] The Coriolis terms that vary with 70 the cosine of latitude are neglected. 71 These terms may be non-negligible where the Brunt-V\"{a}is\"{a}l\"{a} frequency $N$ is small, 72 either in the deep ocean or in the sub-mesoscale motions of the mixed layer, 73 or near the equator \citep[][section 1]{white.hoskins.ea_QJRMS05}. 74 They can be consistently included as part of the ocean dynamics 75 \citep[][section 3(d)]{white.hoskins.ea_QJRMS05} and are retained in the MIT ocean model. 76 \end{labeling} 66 77 67 78 Because the gravitational force is so dominant in the equations of large-scale motions, 68 it is useful to choose an orthogonal set of unit vectors $(i,j,k)$ linked to the earth such that79 it is useful to choose an orthogonal set of unit vectors $(i,j,k)$ linked to the Earth such that 69 80 $k$ is the local upward vector and $(i,j)$ are two vectors orthogonal to $k$, 70 \ie tangent to the geopotential surfaces. 71 Let us define the following variables: $\vect U$ the vector velocity, $\vect U = \vect U_h + w \, \vect k$ 72 (the subscript $h$ denotes the local horizontal vector, \ie over the $(i,j)$ plane), 81 \ie\ tangent to the geopotential surfaces. 82 Let us define the following variables: 83 $\vect U$ the vector velocity, $\vect U = \vect U_h + w \, \vect k$ 84 (the subscript $h$ denotes the local horizontal vector, \ie\ over the $(i,j)$ plane), 73 85 $T$ the potential temperature, $S$ the salinity, $\rho$ the \textit{in situ} density. 74 86 The vector invariant form of the primitive equations in the $(i,j,k)$ vector system provides 75 87 the following equations: 76 88 \begin{subequations} 77 \label{eq: PE}89 \label{eq:MB_PE} 78 90 \begin{gather} 79 \intertext{$-$ the momentum balance} 80 \label{eq:PE_dyn} 81 \pd[\vect U_h]{t} = - \lt[ (\nabla \times \vect U) \times \vect U + \frac{1}{2} \nabla \lt( \vect U^2 \rt) \rt]_h 82 - f \; k \times \vect U_h - \frac{1}{\rho_o} \nabla_h p 83 + \vect D^{\vect U} + \vect F^{\vect U} \\ 84 \intertext{$-$ the heat and salt conservation equations} 85 \label{eq:PE_tra_T} 91 \shortintertext{$-$ the momentum balance} 92 \label{eq:MB_PE_dyn} 93 \pd[\vect U_h]{t} = - \lt[ (\nabla \times \vect U) \times \vect U + \frac{1}{2} \nabla \lt( \vect U^2 \rt) \rt]_h - f \; k \times \vect U_h - \frac{1}{\rho_o} \nabla_h p + \vect D^{\vect U} + \vect F^{\vect U} 94 \shortintertext{$-$ the heat and salt conservation equations} 95 \label{eq:MB_PE_tra_T} 86 96 \pd[T]{t} = - \nabla \cdot (T \ \vect U) + D^T + F^T \\ 87 \label{eq: PE_tra_S}97 \label{eq:MB_PE_tra_S} 88 98 \pd[S]{t} = - \nabla \cdot (S \ \vect U) + D^S + F^S 89 99 \end{gather} … … 91 101 where $\nabla$ is the generalised derivative vector operator in $(i,j,k)$ directions, $t$ is the time, 92 102 $z$ is the vertical coordinate, $\rho$ is the \textit{in situ} density given by the equation of state 93 (\autoref{eq: PE_eos}), $\rho_o$ is a reference density, $p$ the pressure,103 (\autoref{eq:MB_PE_eos}), $\rho_o$ is a reference density, $p$ the pressure, 94 104 $f = 2 \vect \Omega \cdot k$ is the Coriolis acceleration 95 (where $\vect \Omega$ is the Earth's angular velocity vector), and $g$ is the gravitational acceleration. 105 (where $\vect \Omega$ is the Earth's angular velocity vector), 106 and $g$ is the gravitational acceleration. 96 107 $\vect D^{\vect U}$, $D^T$ and $D^S$ are the parameterisations of small-scale physics for momentum, 97 108 temperature and salinity, and $\vect F^{\vect U}$, $F^T$ and $F^S$ surface forcing terms. 98 Their nature and formulation are discussed in \autoref{sec:PE_zdf_ldf} and \autoref{subsec:PE_boundary_condition}. 99 100 % ------------------------------------------------------------------------------------------------------------- 101 % Boundary condition 102 % ------------------------------------------------------------------------------------------------------------- 109 Their nature and formulation are discussed in \autoref{sec:MB_zdf_ldf} and 110 \autoref{subsec:MB_boundary_condition}. 111 112 %% ================================================================================================= 103 113 \subsection{Boundary conditions} 104 \label{subsec: PE_boundary_condition}114 \label{subsec:MB_boundary_condition} 105 115 106 116 An ocean is bounded by complex coastlines, bottom topography at its base and 107 117 an air-sea or ice-sea interface at its top. 108 118 These boundaries can be defined by two surfaces, $z = - H(i,j)$ and $z = \eta(i,j,k,t)$, 109 where $H$ is the depth of the ocean bottom and $\eta$ is the height of the sea surface. 110 Both $H$ and $\eta$ are usually referenced to a given surface, $z = 0$, chosen as a mean sea surface 111 (\autoref{fig:ocean_bc}). 112 Through these two boundaries, the ocean can exchange fluxes of heat, fresh water, salt, and momentum with 113 the solid earth, the continental margins, the sea ice and the atmosphere. 114 However, some of these fluxes are so weak that even on climatic time scales of thousands of years 115 they can be neglected. 119 where $H$ is the depth of the ocean bottom and $\eta$ is the height of the sea surface 120 (discretisation can introduce additional artificial ``side-wall'' boundaries). 121 Both $H$ and $\eta$ are referenced to a surface of constant geopotential 122 (\ie\ a mean sea surface height) on which $z = 0$ (\autoref{fig:MB_ocean_bc}). 123 Through these two boundaries, the ocean can exchange fluxes of heat, fresh water, salt, 124 and momentum with the solid earth, the continental margins, the sea ice and the atmosphere. 125 However, some of these fluxes are so weak that 126 even on climatic time scales of thousands of years they can be neglected. 116 127 In the following, we briefly review the fluxes exchanged at the interfaces between the ocean and 117 128 the other components of the earth system. 118 129 119 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 120 \begin{figure}[!ht] 121 \begin{center} 122 \includegraphics[]{Fig_I_ocean_bc} 123 \caption{ 124 \protect\label{fig:ocean_bc} 125 The ocean is bounded by two surfaces, $z = - H(i,j)$ and $z = \eta(i,j,t)$, 126 where $H$ is the depth of the sea floor and $\eta$ the height of the sea surface. 127 Both $H$ and $\eta$ are referenced to $z = 0$. 128 } 129 \end{center} 130 \begin{figure} 131 \centering 132 \includegraphics[width=0.66\textwidth]{MB_ocean_bc} 133 \caption[Ocean boundary conditions]{ 134 The ocean is bounded by two surfaces, $z = - H(i,j)$ and $z = \eta(i,j,t)$, 135 where $H$ is the depth of the sea floor and $\eta$ the height of the sea surface. 136 Both $H$ and $\eta$ are referenced to $z = 0$.} 137 \label{fig:MB_ocean_bc} 130 138 \end{figure} 131 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>132 139 133 140 \begin{description} 134 \item [Land - ocean interface:]135 the major flux between continental margins and the ocean is a mass exchange offresh water through river runoff.141 \item [Land - ocean] The major flux between continental margins and the ocean is a mass exchange of 142 fresh water through river runoff. 136 143 Such an exchange modifies the sea surface salinity especially in the vicinity of major river mouths. 137 It can be neglected for short range integrations but has to be taken into account for long term integrations as 144 It can be neglected for short range integrations but 145 has to be taken into account for long term integrations as 138 146 it influences the characteristics of water masses formed (especially at high latitudes). 139 147 It is required in order to close the water cycle of the climate system. 140 It is usually specified as a fresh water flux at the air-sea interface in the vicinity of river mouths.141 \item[Solid earth - ocean interface:] 142 heat and salt fluxes through the sea floor are small, except in special areas of little extent. 143 They are usually neglected in the model144 \footnote{148 It is usually specified as a fresh water flux at the air-sea interface in 149 the vicinity of river mouths. 150 \item [Solid earth - ocean] Heat and salt fluxes through the sea floor are small, 151 except in special areas of little extent. 152 They are usually neglected in the model \footnote{ 145 153 In fact, it has been shown that the heat flux associated with the solid Earth cooling 146 (\ie the geothermal heating) is not negligible for the thermohaline circulation of the world ocean147 (see \autoref{subsec:TRA_bbc}).154 (\ie\ the geothermal heating) is not negligible for 155 the thermohaline circulation of the world ocean (see \autoref{subsec:TRA_bbc}). 148 156 }. 149 157 The boundary condition is thus set to no flux of heat and salt across solid boundaries. 150 For momentum, the situation is different. There is no flow across solid boundaries, 151 \ie the velocity normal to the ocean bottom and coastlines is zero (in other words, 152 the bottom velocity is parallel to solid boundaries). This kinematic boundary condition 153 can be expressed as: 158 For momentum, the situation is different. 159 There is no flow across solid boundaries, 160 \ie\ the velocity normal to the ocean bottom and coastlines is zero 161 (in other words, the bottom velocity is parallel to solid boundaries). 162 This kinematic boundary condition can be expressed as: 154 163 \begin{equation} 155 \label{eq: PE_w_bbc}164 \label{eq:MB_w_bbc} 156 165 w = - \vect U_h \cdot \nabla_h (H) 157 166 \end{equation} 158 167 In addition, the ocean exchanges momentum with the earth through frictional processes. 159 168 Such momentum transfer occurs at small scales in a boundary layer. 160 It must be parameterized in terms of turbulent fluxes using bottom and/or lateral boundary conditions. 169 It must be parameterized in terms of turbulent fluxes using 170 bottom and/or lateral boundary conditions. 161 171 Its specification depends on the nature of the physical parameterisation used for 162 $\vect D^{\vect U}$ in \autoref{eq:PE_dyn}. 163 It is discussed in \autoref{eq:PE_zdf}.% and Chap. III.6 to 9. 164 \item[Atmosphere - ocean interface:] 165 the kinematic surface condition plus the mass flux of fresh water PE (the precipitation minus evaporation budget) 166 leads to: 172 $\vect D^{\vect U}$ in \autoref{eq:MB_PE_dyn}. 173 It is discussed in \autoref{eq:MB_zdf}. % and Chap. III.6 to 9. 174 \item [Atmosphere - ocean] The kinematic surface condition plus the mass flux of fresh water PE 175 (the precipitation minus evaporation budget) leads to: 167 176 \[ 168 % \label{eq: PE_w_sbc}177 % \label{eq:MB_w_sbc} 169 178 w = \pd[\eta]{t} + \lt. \vect U_h \rt|_{z = \eta} \cdot \nabla_h (\eta) + P - E 170 179 \] 171 The dynamic boundary condition, neglecting the surface tension (which removes capillary waves from the system) 172 leads to the continuity of pressure across the interface $z = \eta$. 180 The dynamic boundary condition, neglecting the surface tension 181 (which removes capillary waves from the system) leads to 182 the continuity of pressure across the interface $z = \eta$. 173 183 The atmosphere and ocean also exchange horizontal momentum (wind stress), and heat. 174 \item[Sea ice - ocean interface:] 175 the ocean and sea ice exchange heat, salt, fresh water and momentum. 184 \item [Sea ice - ocean] The ocean and sea ice exchange heat, salt, fresh water and momentum. 176 185 The sea surface temperature is constrained to be at the freezing point at the interface. 177 186 Sea ice salinity is very low ($\sim4-6 \, psu$) compared to those of the ocean ($\sim34 \, psu$). 178 The cycle of freezing/melting is associated with fresh water and salt fluxes that cannot be neglected. 187 The cycle of freezing/melting is associated with fresh water and salt fluxes that 188 cannot be neglected. 179 189 \end{description} 180 190 181 % ================================================================ 182 % The Horizontal Pressure Gradient 183 % ================================================================ 191 %% ================================================================================================= 184 192 \section{Horizontal pressure gradient} 185 \label{sec:PE_hor_pg} 186 187 % ------------------------------------------------------------------------------------------------------------- 188 % Pressure Formulation 189 % ------------------------------------------------------------------------------------------------------------- 193 \label{sec:MB_hor_pg} 194 195 %% ================================================================================================= 190 196 \subsection{Pressure formulation} 191 \label{subsec: PE_p_formulation}197 \label{subsec:MB_p_formulation} 192 198 193 199 The total pressure at a given depth $z$ is composed of a surface pressure $p_s$ at 194 200 a reference geopotential surface ($z = 0$) and a hydrostatic pressure $p_h$ such that: 195 201 $p(i,j,k,t) = p_s(i,j,t) + p_h(i,j,k,t)$. 196 The latter is computed by integrating (\autoref{eq: PE_hydrostatic}),197 assuming that pressure in decibars can be approximated by depth in meters in (\autoref{eq: PE_eos}).202 The latter is computed by integrating (\autoref{eq:MB_PE_hydrostatic}), 203 assuming that pressure in decibars can be approximated by depth in meters in (\autoref{eq:MB_PE_eos}). 198 204 The hydrostatic pressure is then given by: 199 205 \[ 200 % \label{eq: PE_pressure}206 % \label{eq:MB_pressure} 201 207 p_h (i,j,z,t) = \int_{\varsigma = z}^{\varsigma = 0} g \; \rho (T,S,\varsigma) \; d \varsigma 202 208 \] 203 209 Two strategies can be considered for the surface pressure term: 204 $(a)$ introduce of a new variable $\eta$, the free-surface elevation, 210 \begin{enumerate*}[label=(\textit{\alph*})] 211 \item introduce of a new variable $\eta$, the free-surface elevation, 205 212 for which a prognostic equation can be established and solved; 206 $(b)$assume that the ocean surface is a rigid lid,213 \item assume that the ocean surface is a rigid lid, 207 214 on which the pressure (or its horizontal gradient) can be diagnosed. 215 \end{enumerate*} 208 216 When the former strategy is used, one solution of the free-surface elevation consists of 209 217 the excitation of external gravity waves. 210 218 The flow is barotropic and the surface moves up and down with gravity as the restoring force. 211 219 The phase speed of such waves is high (some hundreds of metres per second) so that 212 the time step would have to be very short if they were present in the model.220 the time step has to be very short when they are present in the model. 213 221 The latter strategy filters out these waves since the rigid lid approximation implies $\eta = 0$, 214 \ie the sea surface is the surface $z = 0$.222 \ie\ the sea surface is the surface $z = 0$. 215 223 This well known approximation increases the surface wave speed to infinity and 216 modifies certain other longwave dynamics (\eg barotropic Rossby or planetary waves).224 modifies certain other longwave dynamics (\eg\ barotropic Rossby or planetary waves). 217 225 The rigid-lid hypothesis is an obsolescent feature in modern OGCMs. 218 It has been available until the release 3.1 of \NEMO, and it has been removed in release 3.2 and followings. 219 Only the free surface formulation is now described in the this document (see the next sub-section). 220 221 % ------------------------------------------------------------------------------------------------------------- 222 % Free Surface Formulation 223 % ------------------------------------------------------------------------------------------------------------- 226 It has been available until the release 3.1 of \NEMO, 227 and it has been removed in release 3.2 and followings. 228 Only the free surface formulation is now described in this document (see the next sub-section). 229 230 %% ================================================================================================= 224 231 \subsection{Free surface formulation} 225 \label{subsec: PE_free_surface}232 \label{subsec:MB_free_surface} 226 233 227 234 In the free surface formulation, a variable $\eta$, the sea-surface height, 228 235 is introduced which describes the shape of the air-sea interface. 229 This variable is solution of a prognostic equation which is established by forming the vertical average of230 the kinematic surface condition (\autoref{eq:PE_w_bbc}):236 This variable is solution of a prognostic equation which is established by 237 forming the vertical average of the kinematic surface condition (\autoref{eq:MB_w_bbc}): 231 238 \begin{equation} 232 \label{eq: PE_ssh}239 \label{eq:MB_ssh} 233 240 \pd[\eta]{t} = - D + P - E \quad \text{where} \quad D = \nabla \cdot \lt[ (H + \eta) \; \overline{U}_h \, \rt] 234 241 \end{equation} 235 and using (\autoref{eq:PE_hydrostatic}) the surface pressure is given by: $p_s = \rho \, g \, \eta$. 236 237 Allowing the air-sea interface to move introduces the external gravity waves (EGWs) as 242 and using (\autoref{eq:MB_PE_hydrostatic}) the surface pressure is given by: 243 $p_s = \rho \, g \, \eta$. 244 245 Allowing the air-sea interface to move introduces 246 the \textbf{E}xternal \textbf{G}ravity \textbf{W}aves (EGWs) as 238 247 a class of solution of the primitive equations. 239 These waves are barotropic because of hydrostatic assumption,and their phase speed is quite high.248 These waves are barotropic (\ie\ nearly independent of depth) and their phase speed is quite high. 240 249 Their time scale is short with respect to the other processes described by the primitive equations. 241 250 242 251 Two choices can be made regarding the implementation of the free surface in the model, 243 252 depending on the physical processes of interest. 244 245 $\bullet$ If one is interested in EGWs, in particular the tides and their interaction with 246 the baroclinic structure of the ocean (internal waves) possibly in shallow seas, 247 then a non linear free surface is the most appropriate. 248 This means that no approximation is made in \autoref{eq:PE_ssh} and that 249 the variation of the ocean volume is fully taken into account. 250 Note that in order to study the fast time scales associated with EGWs it is necessary to 251 minimize time filtering effects 252 (use an explicit time scheme with very small time step, or a split-explicit scheme with reasonably small time step, 253 see \autoref{subsec:DYN_spg_exp} or \autoref{subsec:DYN_spg_ts}). 254 255 $\bullet$ If one is not interested in EGW but rather sees them as high frequency noise, 256 it is possible to apply an explicit filter to slow down the fastest waves while 257 not altering the slow barotropic Rossby waves. 258 If further, an approximative conservation of heat and salt contents is sufficient for the problem solved, 259 then it is sufficient to solve a linearized version of \autoref{eq:PE_ssh}, 260 which still allows to take into account freshwater fluxes applied at the ocean surface \citep{Roullet_Madec_JGR00}. 261 Nevertheless, with the linearization, an exact conservation of heat and salt contents is lost. 262 263 The filtering of EGWs in models with a free surface is usually a matter of discretisation of 264 the temporal derivatives, 265 using a split-explicit method \citep{Killworth_al_JPO91, Zhang_Endoh_JGR92} or 266 the implicit scheme \citep{Dukowicz1994} or 267 the addition of a filtering force in the momentum equation \citep{Roullet_Madec_JGR00}. 268 With the present release, \NEMO offers the choice between 269 an explicit free surface (see \autoref{subsec:DYN_spg_exp}) or 270 a split-explicit scheme strongly inspired the one proposed by \citet{Shchepetkin_McWilliams_OM05} 271 (see \autoref{subsec:DYN_spg_ts}). 272 273 % ================================================================ 274 % Curvilinear z-coordinate System 275 % ================================================================ 276 \section{Curvilinear \textit{z-}coordinate system} 277 \label{sec:PE_zco} 278 279 % ------------------------------------------------------------------------------------------------------------- 280 % Tensorial Formalism 281 % ------------------------------------------------------------------------------------------------------------- 253 \begin{itemize} 254 \item If one is interested in EGWs, in particular the tides and their interaction with 255 the baroclinic structure of the ocean (internal waves) possibly in shallow seas, 256 then a non linear free surface is the most appropriate. 257 This means that no approximation is made in \autoref{eq:MB_ssh} and that 258 the variation of the ocean volume is fully taken into account. 259 Note that in order to study the fast time scales associated with EGWs it is necessary to 260 minimize time filtering effects 261 (use an explicit time scheme with very small time step, 262 or a split-explicit scheme with reasonably small time step, 263 see \autoref{subsec:DYN_spg_exp} or \autoref{subsec:DYN_spg_ts}). 264 \item If one is not interested in EGWs but rather sees them as high frequency noise, 265 it is possible to apply an explicit filter to slow down the fastest waves while 266 not altering the slow barotropic Rossby waves. 267 If further, an approximative conservation of heat and salt contents is sufficient for 268 the problem solved, then it is sufficient to solve a linearized version of \autoref{eq:MB_ssh}, 269 which still allows to take into account freshwater fluxes applied at the ocean surface 270 \citep{roullet.madec_JGR00}. 271 Nevertheless, with the linearization, an exact conservation of heat and salt contents is lost. 272 \end{itemize} 273 The filtering of EGWs in models with a free surface is usually 274 a matter of discretisation of the temporal derivatives, 275 using a split-explicit method \citep{killworth.webb.ea_JPO91, zhang.endoh_JGR92} or 276 the implicit scheme \citep{dukowicz.smith_JGR94} or the addition of a filtering force in 277 the momentum equation \citep{roullet.madec_JGR00}. 278 With the present release, \NEMO\ offers the choice between an explicit free surface 279 (see \autoref{subsec:DYN_spg_exp}) or a split-explicit scheme strongly inspired the one proposed by 280 \citet{shchepetkin.mcwilliams_OM05} (see \autoref{subsec:DYN_spg_ts}). 281 282 %% ================================================================================================= 283 \section{Curvilinear \textit{z}-coordinate system} 284 \label{sec:MB_zco} 285 286 %% ================================================================================================= 282 287 \subsection{Tensorial formalism} 283 \label{subsec: PE_tensorial}288 \label{subsec:MB_tensorial} 284 289 285 290 In many ocean circulation problems, the flow field has regions of enhanced dynamics 286 (\ie surface layers, western boundary currents, equatorial currents, or ocean fronts).291 (\ie\ surface layers, western boundary currents, equatorial currents, or ocean fronts). 287 292 The representation of such dynamical processes can be improved by 288 293 specifically increasing the model resolution in these regions. … … 292 297 cannot be easily treated in a global model without filtering. 293 298 A solution consists of introducing an appropriate coordinate transformation that 294 shifts the singular point onto land \citep{Madec_Imbard_CD96, Murray_JCP96}. 295 As a consequence, it is important to solve the primitive equations in various curvilinear coordinate systems. 296 An efficient way of introducing an appropriate coordinate transform can be found when using a tensorial formalism. 299 shifts the singular point onto land \citep{madec.imbard_CD96, murray_JCP96}. 300 As a consequence, 301 it is important to solve the primitive equations in various curvilinear coordinate systems. 302 An efficient way of introducing an appropriate coordinate transform can be found when 303 using a tensorial formalism. 297 304 This formalism is suited to any multidimensional curvilinear coordinate system. 298 Ocean modellers mainly use three-dimensional orthogonal grids on the sphere (spherical earth approximation), 299 with preservation of the local vertical. Here we give the simplified equations for this particular case. 300 The general case is detailed by \citet{Eiseman1980} in their survey of the conservation laws of fluid dynamics. 305 Ocean modellers mainly use three-dimensional orthogonal grids on the sphere 306 (spherical earth approximation), with preservation of the local vertical. 307 Here we give the simplified equations for this particular case. 308 The general case is detailed by \citet{eiseman.stone_SR80} in 309 their survey of the conservation laws of fluid dynamics. 301 310 302 311 Let $(i,j,k)$ be a set of orthogonal curvilinear coordinates on … … 304 313 $(i,j,k)$ linked to the earth such that 305 314 $k$ is the local upward vector and $(i,j)$ are two vectors orthogonal to $k$, 306 \ie along geopotential surfaces (\autoref{fig:referential}).315 \ie\ along geopotential surfaces (\autoref{fig:MB_referential}). 307 316 Let $(\lambda,\varphi,z)$ be the geographical coordinate system in which a position is defined by 308 317 the latitude $\varphi(i,j)$, the longitude $\lambda(i,j)$ and 309 318 the distance from the centre of the earth $a + z(k)$ where $a$ is the earth's radius and 310 $z$ the altitude above a reference sea level (\autoref{fig: referential}).319 $z$ the altitude above a reference sea level (\autoref{fig:MB_referential}). 311 320 The local deformation of the curvilinear coordinate system is given by $e_1$, $e_2$ and $e_3$, 312 321 the three scale factors: 313 322 \begin{equation} 314 \label{eq:scale_factors} 315 \begin{aligned} 316 e_1 &= (a + z) \lt[ \lt( \pd[\lambda]{i} \cos \varphi \rt)^2 + \lt( \pd[\varphi]{i} \rt)^2 \rt]^{1/2} \\ 317 e_2 &= (a + z) \lt[ \lt( \pd[\lambda]{j} \cos \varphi \rt)^2 + \lt( \pd[\varphi]{j} \rt)^2 \rt]^{1/2} \\ 318 e_3 &= \lt( \pd[z]{k} \rt) 319 \end{aligned} 323 \label{eq:MB_scale_factors} 324 e_1 = (a + z) \lt[ \lt( \pd[\lambda]{i} \cos \varphi \rt)^2 + \lt( \pd[\varphi]{i} \rt)^2 \rt]^{1/2} \quad e_2 = (a + z) \lt[ \lt( \pd[\lambda]{j} \cos \varphi \rt)^2 + \lt( \pd[\varphi]{j} \rt)^2 \rt]^{1/2} \quad e_3 = \lt( \pd[z]{k} \rt) 320 325 \end{equation} 321 326 322 % >>>>>>>>>>>>>>>>>>>>>>>>>>>> 323 \begin{figure}[!tb] 324 \begin{center} 325 \includegraphics[]{Fig_I_earth_referential} 326 \caption{ 327 \protect\label{fig:referential} 328 the geographical coordinate system $(\lambda,\varphi,z)$ and the curvilinear 329 coordinate system $(i,j,k)$. 330 } 331 \end{center} 327 \begin{figure} 328 \centering 329 \includegraphics[width=0.33\textwidth]{MB_earth_referential} 330 \caption[Geographical and curvilinear coordinate systems]{ 331 the geographical coordinate system $(\lambda,\varphi,z)$ and the curvilinear 332 coordinate system $(i,j,k)$.} 333 \label{fig:MB_referential} 332 334 \end{figure} 333 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>334 335 335 336 Since the ocean depth is far smaller than the earth's radius, $a + z$, can be replaced by $a$ in 336 (\autoref{eq: scale_factors}) (thin-shell approximation).337 (\autoref{eq:MB_scale_factors}) (thin-shell approximation). 337 338 The resulting horizontal scale factors $e_1$, $e_2$ are independent of $k$ while 338 339 the vertical scale factor is a single function of $k$ as $k$ is parallel to $z$. 339 340 The scalar and vector operators that appear in the primitive equations 340 (\autoref{eq: PE_dyn} to \autoref{eq:PE_eos}) can be written in the tensorial form,341 (\autoref{eq:MB_PE_dyn} to \autoref{eq:MB_PE_eos}) can then be written in the tensorial form, 341 342 invariant in any orthogonal horizontal curvilinear coordinate system transformation: 342 343 \begin{subequations} 343 % \label{eq:PE_discrete_operators} 344 \begin{gather} 345 \label{eq:PE_grad} 346 \nabla q = \frac{1}{e_1} \pd[q]{i} \; \vect i 347 + \frac{1}{e_2} \pd[q]{j} \; \vect j 348 + \frac{1}{e_3} \pd[q]{k} \; \vect k \\ 349 \label{eq:PE_div} 350 \nabla \cdot \vect A = \frac{1}{e_1 \; e_2} \lt[ \pd[(e_2 \; a_1)]{\partial i} + \pd[(e_1 \; a_2)]{j} \rt] 351 + \frac{1}{e_3} \lt[ \pd[a_3]{k} \rt] 352 \end{gather} 353 \begin{multline} 354 \label{eq:PE_curl} 355 \nabla \times \vect{A} = \lt[ \frac{1}{e_2} \pd[a_3]{j} - \frac{1}{e_3} \pd[a_2]{k} \rt] \vect i \\ 356 + \lt[ \frac{1}{e_3} \pd[a_1]{k} - \frac{1}{e_1} \pd[a_3]{i} \rt] \vect j \\ 357 + \frac{1}{e_1 e_2} \lt[ \pd[(e_2 a_2)]{i} - \pd[(e_1 a_1)]{j} \rt] \vect k 358 \end{multline} 359 \begin{gather} 360 \label{eq:PE_lap} 361 \Delta q = \nabla \cdot (\nabla q) \\ 362 \label{eq:PE_lap_vector} 363 \Delta \vect A = \nabla (\nabla \cdot \vect A) - \nabla \times (\nabla \times \vect A) 364 \end{gather} 344 % \label{eq:MB_discrete_operators} 345 \begin{align} 346 \label{eq:MB_grad} 347 \nabla q &= \frac{1}{e_1} \pd[q]{i} \; \vect i + \frac{1}{e_2} \pd[q]{j} \; \vect j + \frac{1}{e_3} \pd[q]{k} \; \vect k \\ 348 \label{eq:MB_div} 349 \nabla \cdot \vect A &= \frac{1}{e_1 \; e_2} \lt[ \pd[(e_2 \; a_1)]{\partial i} + \pd[(e_1 \; a_2)]{j} \rt] + \frac{1}{e_3} \lt[ \pd[a_3]{k} \rt] \\ 350 \label{eq:MB_curl} 351 \nabla \times \vect{A} &= \lt[ \frac{1}{e_2} \pd[a_3]{j} - \frac{1}{e_3} \pd[a_2]{k} \rt] \vect i + \lt[ \frac{1}{e_3} \pd[a_1]{k} - \frac{1}{e_1} \pd[a_3]{i} \rt] \vect j + \frac{1}{e_1 e_2} \lt[ \pd[(e_2 a_2)]{i} - \pd[(e_1 a_1)]{j} \rt] \vect k \\ 352 \label{eq:MB_lap} 353 \Delta q &= \nabla \cdot (\nabla q) \\ 354 \label{eq:MB_lap_vector} 355 \Delta \vect A &= \nabla (\nabla \cdot \vect A) - \nabla \times (\nabla \times \vect A) 356 \end{align} 365 357 \end{subequations} 366 where $q$ is a scalar quantity and $\vect A = (a_1,a_2,a_3)$ a vector in the $(i,j,k)$ coordinates system. 367 368 % ------------------------------------------------------------------------------------------------------------- 369 % Continuous Model Equations 370 % ------------------------------------------------------------------------------------------------------------- 358 where $q$ is a scalar quantity and 359 $\vect A = (a_1,a_2,a_3)$ a vector in the $(i,j,k)$ coordinates system. 360 361 %% ================================================================================================= 371 362 \subsection{Continuous model equations} 372 \label{subsec: PE_zco_Eq}363 \label{subsec:MB_zco_Eq} 373 364 374 365 In order to express the Primitive Equations in tensorial formalism, 375 it is necessary to compute the horizontal component of the non-linear and viscous terms of the equation using 376 \autoref{eq:PE_grad}) to \autoref{eq:PE_lap_vector}. 377 Let us set $\vect U = (u,v,w) = \vect U_h + w \; \vect k $, the velocity in the $(i,j,k)$ coordinates system and 378 define the relative vorticity $\zeta$ and the divergence of the horizontal velocity field $\chi$, by: 366 it is necessary to compute the horizontal component of the non-linear and viscous terms of 367 the equation using \autoref{eq:MB_grad}) to \autoref{eq:MB_lap_vector}. 368 Let us set $\vect U = (u,v,w) = \vect U_h + w \; \vect k $, 369 the velocity in the $(i,j,k)$ coordinates system, 370 and define the relative vorticity $\zeta$ and the divergence of the horizontal velocity field $\chi$, 371 by: 379 372 \begin{gather} 380 \label{eq: PE_curl_Uh}373 \label{eq:MB_curl_Uh} 381 374 \zeta = \frac{1}{e_1 e_2} \lt[ \pd[(e_2 \, v)]{i} - \pd[(e_1 \, u)]{j} \rt] \\ 382 \label{eq: PE_div_Uh}375 \label{eq:MB_div_Uh} 383 376 \chi = \frac{1}{e_1 e_2} \lt[ \pd[(e_2 \, u)]{i} + \pd[(e_1 \, v)]{j} \rt] 384 377 \end{gather} 385 378 386 Using the fact that the horizontal scale factors $e_1$ and $e_2$ are independent of $k$ and that379 Using again the fact that the horizontal scale factors $e_1$ and $e_2$ are independent of $k$ and that 387 380 $e_3$ is a function of the single variable $k$, 388 $NLT$ the nonlinear term of \autoref{eq:PE_dyn} can be transformed as follows: 389 \begin{alignat*}{2} 390 &NLT &= &\lt[ (\nabla \times {\vect U}) \times {\vect U} + \frac{1}{2} \nabla \lt( {\vect U}^2 \rt) \rt]_h \\ 391 & &= &\lt( 392 \begin{array}{*{20}c} 393 \lt[ \frac{1}{e_3} \pd[u]{k} - \frac{1}{e_1} \pd[w]{i} \rt] w - \zeta \; v \\ 394 \zeta \; u - \lt[ \frac{1}{e_2} \pd[w]{j} - \frac{1}{e_3} \pd[v]{k} \rt] \ w 395 \end{array} 396 \rt) 397 + \frac{1}{2} \lt( 398 \begin{array}{*{20}c} 399 \frac{1}{e_1} \pd[(u^2 + v^2 + w^2)]{i} \\ 400 \frac{1}{e_2} \pd[(u^2 + v^2 + w^2)]{j} 401 \end{array} 402 \rt) \\ 403 & &= &\lt( 404 \begin{array}{*{20}c} 405 -\zeta \; v \\ 406 \zeta \; u 407 \end{array} 408 \rt) 409 + \frac{1}{2} \lt( 410 \begin{array}{*{20}c} 411 \frac{1}{e_1} \pd[(u^2 + v^2)]{i} \\ 412 \frac{1}{e_2} \pd[(u^2 + v^2)]{j} 413 \end{array} 414 \rt) \\ 415 & & &+ \frac{1}{e_3} \lt( 416 \begin{array}{*{20}c} 417 w \; \pd[u]{k} \\ 418 w \; \pd[v]{k} 419 \end{array} 420 \rt) 421 - \lt( 422 \begin{array}{*{20}c} 423 \frac{w}{e_1} \pd[w]{i} - \frac{1}{2 e_1} \pd[w^2]{i} \\ 424 \frac{w}{e_2} \pd[w]{j} - \frac{1}{2 e_2} \pd[w^2]{j} 425 \end{array} 426 \rt) 427 \end{alignat*} 428 The last term of the right hand side is obviously zero, and thus the nonlinear term of 429 \autoref{eq:PE_dyn} is written in the $(i,j,k)$ coordinate system: 381 $NLT$ the nonlinear term of \autoref{eq:MB_PE_dyn} can be transformed as follows: 382 \begin{align*} 383 NLT &= \lt[ (\nabla \times {\vect U}) \times {\vect U} + \frac{1}{2} \nabla \lt( {\vect U}^2 \rt) \rt]_h \\ 384 &= \lt( 385 \begin{array}{*{20}c} 386 \lt[ \frac{1}{e_3} \pd[u]{k} - \frac{1}{e_1} \pd[w]{i} \rt] w - \zeta \; v \\ 387 \zeta \; u - \lt[ \frac{1}{e_2} \pd[w]{j} - \frac{1}{e_3} \pd[v]{k} \rt] \ w 388 \end{array} 389 \rt) 390 + \frac{1}{2} \lt( 391 \begin{array}{*{20}c} 392 \frac{1}{e_1} \pd[(u^2 + v^2 + w^2)]{i} \\ 393 \frac{1}{e_2} \pd[(u^2 + v^2 + w^2)]{j} 394 \end{array} 395 \rt) \\ 396 &= \lt( 397 \begin{array}{*{20}c} 398 -\zeta \; v \\ 399 \zeta \; u 400 \end{array} 401 \rt) 402 + \frac{1}{2} \lt( 403 \begin{array}{*{20}c} 404 \frac{1}{e_1} \pd[(u^2 + v^2)]{i} \\ 405 \frac{1}{e_2} \pd[(u^2 + v^2)]{j} 406 \end{array} 407 \rt) 408 + \frac{1}{e_3} \lt( 409 \begin{array}{*{20}c} 410 w \; \pd[u]{k} \\ 411 w \; \pd[v]{k} 412 \end{array} 413 \rt) 414 - \lt( 415 \begin{array}{*{20}c} 416 \frac{w}{e_1} \pd[w]{i} - \frac{1}{2 e_1} \pd[w^2]{i} \\ 417 \frac{w}{e_2} \pd[w]{j} - \frac{1}{2 e_2} \pd[w^2]{j} 418 \end{array} 419 \rt) 420 \end{align*} 421 The last term of the right hand side is obviously zero, 422 and thus the \textbf{N}on\textbf{L}inear \textbf{T}erm ($NLT$) of \autoref{eq:MB_PE_dyn} is written in 423 the $(i,j,k)$ coordinate system: 430 424 \begin{equation} 431 \label{eq:PE_vector_form} 432 NLT = \zeta \; \vect k \times \vect U_h + \frac{1}{2} \nabla_h \lt( \vect U_h^2 \rt) 433 + \frac{1}{e_3} w \pd[\vect U_h]{k} 425 \label{eq:MB_vector_form} 426 NLT = \zeta \; \vect k \times \vect U_h + \frac{1}{2} \nabla_h \lt( \vect U_h^2 \rt) + \frac{1}{e_3} w \pd[\vect U_h]{k} 434 427 \end{equation} 435 428 436 429 This is the so-called \textit{vector invariant form} of the momentum advection term. 437 430 For some purposes, it can be advantageous to write this term in the so-called flux form, 438 \ie to write it as the divergence of fluxes. 439 For example, the first component of \autoref{eq:PE_vector_form} (the $i$-component) is transformed as follows: 440 \begin{alignat*}{2} 431 \ie\ to write it as the divergence of fluxes. 432 For example, 433 the first component of \autoref{eq:MB_vector_form} (the $i$-component) is transformed as follows: 434 \begin{alignat*}{3} 441 435 &NLT_i &= &- \zeta \; v + \frac{1}{2 \; e_1} \pd[ (u^2 + v^2) ]{i} + \frac{1}{e_3} w \ \pd[u]{k} \\ 442 & &= &\frac{1}{e_1 \; e_2} \lt( -v \pd[(e_2 \, v)]{i} + v \pd[(e_1 \, u)]{j} \rt) 443 + \frac{1}{e_1 e_2} \lt( e_2 \; u \pd[u]{i} + e_2 \; v \pd[v]{i} \rt) \\ 444 & & &+ \frac{1}{e_3} \lt( w \; \pd[u]{k} \rt) \\ 445 & &= &\frac{1}{e_1 \; e_2} \lt[ - \lt( v^2 \pd[e_2]{i} + e_2 \, v \pd[v]{i} \rt) 446 + \lt( \pd[ \lt( e_1 \, u \, v \rt)]{j} - e_1 \, u \pd[v]{j} \rt) \rt. \\ 447 & & &\lt. + \lt( \pd[ \lt( e_2 \, u \, u \rt)]{i} - u \pd[ \lt( e_2 u \rt)]{i} \rt) 448 + e_2 v \pd[v]{i} \rt] \\ 436 & &= &\frac{1}{e_1 \; e_2} \lt( -v \pd[(e_2 \, v)]{i} + v \pd[(e_1 \, u)]{j} \rt) + \frac{1}{e_1 e_2} \lt( e_2 \; u \pd[u]{i} + e_2 \; v \pd[v]{i} \rt) + \frac{1}{e_3} \lt( w \; \pd[u]{k} \rt) \\ 437 & &= &\frac{1}{e_1 \; e_2} \lt[ - \lt( v^2 \pd[e_2]{i} + e_2 \, v \pd[v]{i} \rt) + \lt( \pd[ \lt( e_1 \, u \, v \rt)]{j} - e_1 \, u \pd[v]{j} \rt) \rt. \lt. + \lt( \pd[ \lt( e_2 \, u \, u \rt)]{i} - u \pd[ \lt( e_2 u \rt)]{i} \rt) + e_2 v \pd[v]{i} \rt] \\ 449 438 & & &+ \frac{1}{e_3} \lt( \pd[(w \, u)]{k} - u \pd[w]{k} \rt) \\ 450 & &= &\frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, u)]{i} + \pd[(e_1 \, u \, v)]{j} \rt) 451 + \frac{1}{e_3} \pd[(w \, u)]{k} \\ 452 & & &+ \frac{1}{e_1 e_2} \lt[ - u \lt( \pd[(e_1 v)]{j} - v \, \pd[e_1]{j} \rt) 453 - u \pd[(e_2 u)]{i} \rt] 454 - \frac{1}{e_3} \pd[w]{k} u \\ 439 & &= &\frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, u)]{i} + \pd[(e_1 \, u \, v)]{j} \rt) + \frac{1}{e_3} \pd[(w \, u)]{k} + \frac{1}{e_1 e_2} \lt[ - u \lt( \pd[(e_1 v)]{j} - v \, \pd[e_1]{j} \rt) - u \pd[(e_2 u)]{i} \rt] - \frac{1}{e_3} \pd[w]{k} u \\ 455 440 & & &+ \frac{1}{e_1 e_2} \lt( - v^2 \pd[e_2]{i} \rt) \\ 456 & &= &\nabla \cdot (\vect U \, u) - (\nabla \cdot \vect U) \ u 457 + \frac{1}{e_1 e_2} \lt( -v^2 \pd[e_2]{i} + u v \, \pd[e_1]{j} \rt) \\ 458 \intertext{as $\nabla \cdot {\vect U} \; = 0$ (incompressibility) it comes:} 441 & &= &\nabla \cdot (\vect U \, u) - (\nabla \cdot \vect U) \ u + \frac{1}{e_1 e_2} \lt( -v^2 \pd[e_2]{i} + u v \, \pd[e_1]{j} \rt) \\ 442 \shortintertext{as $\nabla \cdot {\vect U} \; = 0$ (incompressibility) it becomes:} 459 443 & &= &\, \nabla \cdot (\vect U \, u) + \frac{1}{e_1 e_2} \lt( v \; \pd[e_2]{i} - u \; \pd[e_1]{j} \rt) (-v) 460 444 \end{alignat*} … … 462 446 The flux form of the momentum advection term is therefore given by: 463 447 \begin{equation} 464 \label{eq: PE_flux_form}465 NLT = 466 467 468 469 470 471 448 \label{eq:MB_flux_form} 449 NLT = \nabla \cdot \lt( 450 \begin{array}{*{20}c} 451 \vect U \, u \\ 452 \vect U \, v 453 \end{array} 454 \rt) 455 + \frac{1}{e_1 e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \vect k \times \vect U_h 472 456 \end{equation} 473 457 474 458 The flux form has two terms, 475 the first one is expressed as the divergence of momentum fluxes (hence the flux form name given to this formulation) 476 and the second one is due to the curvilinear nature of the coordinate system used. 477 The latter is called the \textit{metric} term and can be viewed as a modification of the Coriolis parameter: 459 the first one is expressed as the divergence of momentum fluxes 460 (hence the flux form name given to this formulation) and 461 the second one is due to the curvilinear nature of the coordinate system used. 462 The latter is called the \textit{metric} term and can be viewed as 463 a modification of the Coriolis parameter: 478 464 \[ 479 % \label{eq: PE_cor+metric}465 % \label{eq:MB_cor+metric} 480 466 f \to f + \frac{1}{e_1 e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) 481 467 \] 482 468 483 469 Note that in the case of geographical coordinate, 484 \ie when $(i,j) \to (\lambda,\varphi)$ and $(e_1,e_2) \to (a \, \cos \varphi,a)$,470 \ie\ when $(i,j) \to (\lambda,\varphi)$ and $(e_1,e_2) \to (a \, \cos \varphi,a)$, 485 471 we recover the commonly used modification of the Coriolis parameter $f \to f + (u / a) \tan \varphi$. 486 472 … … 488 474 the following tensorial formalism: 489 475 490 \begin{itemize} 491 \item 492 \textbf{Vector invariant form of the momentum equations}: 476 \begin{description} 477 \item [Vector invariant form of the momentum equations] 493 478 \begin{equation} 494 \label{eq:PE_dyn_vect} 495 \begin{split} 496 % \label{eq:PE_dyn_vect_u} 497 \pd[u]{t} = &+ (\zeta + f) \, v - \frac{1}{2 e_1} \pd[]{i} (u^2 + v^2) 498 - \frac{1}{e_3} w \pd[u]{k} - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) \\ 499 &+ D_u^{\vect U} + F_u^{\vect U} \\ 500 \pd[v]{t} = &- (\zeta + f) \, u - \frac{1}{2 e_2} \pd[]{j} (u^2 + v^2) 501 - \frac{1}{e_3} w \pd[v]{k} - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) \\ 502 &+ D_v^{\vect U} + F_v^{\vect U} 503 \end{split} 479 \label{eq:MB_dyn_vect} 480 \begin{gathered} 481 % \label{eq:MB_dyn_vect_u} 482 \pd[u]{t} = + (\zeta + f) \, v - \frac{1}{2 e_1} \pd[]{i} (u^2 + v^2) - \frac{1}{e_3} w \pd[u]{k} - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) + D_u^{\vect U} + F_u^{\vect U} \\ 483 \pd[v]{t} = - (\zeta + f) \, u - \frac{1}{2 e_2} \pd[]{j} (u^2 + v^2) - \frac{1}{e_3} w \pd[v]{k} - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) + D_v^{\vect U} + F_v^{\vect U} 484 \end{gathered} 504 485 \end{equation} 505 \item 506 \textbf{flux form of the momentum equations}: 507 % \label{eq:PE_dyn_flux} 508 \begin{multline*} 509 % \label{eq:PE_dyn_flux_u} 510 \pd[u]{t} = + \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, v \\ 511 - \frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, u)]{i} + \pd[(e_1 \, v \, u)]{j} \rt) \\ 512 - \frac{1}{e_3} \pd[(w \, u)]{k} - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) 513 + D_u^{\vect U} + F_u^{\vect U} 514 \end{multline*} 515 \begin{multline*} 516 % \label{eq:PE_dyn_flux_v} 517 \pd[v]{t} = - \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, u \\ 518 + \frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, v)]{i} + \pd[(e_1 \, v \, v)]{j} \rt) \\ 519 - \frac{1}{e_3} \pd[(w \, v)]{k} - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) 520 + D_v^{\vect U} + F_v^{\vect U} 521 \end{multline*} 522 where $\zeta$, the relative vorticity, is given by \autoref{eq:PE_curl_Uh} and $p_s$, the surface pressure, 523 is given by: 486 \item [Flux form of the momentum equations] 487 % \label{eq:MB_dyn_flux} 488 \begin{alignat*}{2} 489 % \label{eq:MB_dyn_flux_u} 490 \pd[u]{t} = &+ \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, v - \frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, u)]{i} + \pd[(e_1 \, v \, u)]{j} \rt) - \frac{1}{e_3} \pd[(w \, u)]{k} \\ 491 &- \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) + D_u^{\vect U} + F_u^{\vect U} 492 \end{alignat*} 493 \begin{alignat*}{2} 494 % \label{eq:MB_dyn_flux_v} 495 \pd[v]{t} = &- \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, u - \frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, v)]{i} + \pd[(e_1 \, v \, v)]{j} \rt) - \frac{1}{e_3} \pd[(w \, v)]{k} \\ 496 &- \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) + D_v^{\vect U} + F_v^{\vect U} 497 \end{alignat*} 498 where $\zeta$, the relative vorticity, is given by \autoref{eq:MB_curl_Uh} and 499 $p_s$, the surface pressure, is given by: 524 500 \[ 525 % \label{eq: PE_spg}501 % \label{eq:MB_spg} 526 502 p_s = \rho \,g \, \eta 527 503 \] 528 with $\eta$ is solution of \autoref{eq:PE_ssh}.504 and $\eta$ is the solution of \autoref{eq:MB_ssh}. 529 505 530 506 The vertical velocity and the hydrostatic pressure are diagnosed from the following equations: 531 507 \[ 532 % \label{eq: w_diag}533 \pd[w]{k} = - \chi \; e_3 \qquad 534 % \label{eq: hp_diag}508 % \label{eq:MB_w_diag} 509 \pd[w]{k} = - \chi \; e_3 \qquad 510 % \label{eq:MB_hp_diag} 535 511 \pd[p_h]{k} = - \rho \; g \; e_3 536 512 \] 537 where the divergence of the horizontal velocity, $\chi$ is given by \autoref{eq:PE_div_Uh}. 538 \item \textit{tracer equations}: 539 \[ 540 %\label{eq:S} 541 \pd[T]{t} = - \frac{1}{e_1 e_2} \lt[ \pd[(e_2 T \, u)]{i} + \pd[(e_1 T \, v)]{j} \rt] 542 - \frac{1}{e_3} \pd[(T \, w)]{k} + D^T + F^T \\ 543 %\label{eq:T} 544 \pd[S]{t} = - \frac{1}{e_1 e_2} \lt[ \pd[(e_2 S \, u)]{i} + \pd[(e_1 S \, v)]{j} \rt] 545 - \frac{1}{e_3} \pd[(S \, w)]{k} + D^S + F^S 546 %\label{eq:rho} 513 where the divergence of the horizontal velocity, $\chi$ is given by \autoref{eq:MB_div_Uh}. 514 \item [Tracer equations] 515 \begin{gather*} 516 \pd[T]{t} = - \frac{1}{e_1 e_2} \lt[ \pd[(e_2 T \, u)]{i} + \pd[(e_1 T \, v)]{j} \rt] - \frac{1}{e_3} \pd[(T \, w)]{k} + D^T + F^T \\ 517 \pd[S]{t} = - \frac{1}{e_1 e_2} \lt[ \pd[(e_2 S \, u)]{i} + \pd[(e_1 S \, v)]{j} \rt] - \frac{1}{e_3} \pd[(S \, w)]{k} + D^S + F^S \\ 547 518 \rho = \rho \big( T,S,z(k) \big) 548 \] 549 \end{itemize} 550 551 The expression of $\vect D^{U}$, $D^{S}$ and $D^{T}$ depends on the subgrid scale parameterisation used. 552 It will be defined in \autoref{eq:PE_zdf}. 519 \end{gather*} 520 \end{description} 521 522 The expression of $\vect D^{U}$, $D^{S}$ and $D^{T}$ depends on 523 the subgrid scale parameterisation used. 524 It will be defined in \autoref{eq:MB_zdf}. 553 525 The nature and formulation of $\vect F^{\vect U}$, $F^T$ and $F^S$, the surface forcing terms, 554 526 are discussed in \autoref{chap:SBC}. 555 527 556 \newpage 557 558 % ================================================================ 559 % Curvilinear generalised vertical coordinate System 560 % ================================================================ 528 %% ================================================================================================= 561 529 \section{Curvilinear generalised vertical coordinate system} 562 \label{sec: PE_gco}530 \label{sec:MB_gco} 563 531 564 532 The ocean domain presents a huge diversity of situation in the vertical. … … 567 535 varying from more than 6,000 meters in abyssal trenches to zero at the coast. 568 536 Last but not least, the ocean stratification exerts a strong barrier to vertical motions and mixing. 569 Therefore, in order to represent the ocean with respect to 570 the first point a space and time dependent vertical coordinate that follows the variation of the sea surface height 571 \eg an \zstar-coordinate; 572 for the second point, a space variation to fit the change of bottom topography 573 \eg a terrain-following or $\sigma$-coordinate; 574 and for the third point, one will be tempted to use a space and time dependent coordinate that 575 follows the isopycnal surfaces, \eg an isopycnic coordinate. 576 577 In order to satisfy two or more constrains one can even be tempted to mixed these coordinate systems, as in 578 HYCOM (mixture of $z$-coordinate at the surface, isopycnic coordinate in the ocean interior and $\sigma$ at 579 the ocean bottom) \citep{Chassignet_al_JPO03} or 580 OPA (mixture of $z$-coordinate in vicinity the surface and steep topography areas and $\sigma$-coordinate elsewhere) 581 \citep{Madec_al_JPO96} among others. 537 Therefore, in order to represent the ocean with respect to the first point 538 a space and time dependent vertical coordinate that follows the variation of the sea surface height 539 \eg\ an \zstar-coordinate; 540 for the second point, 541 a space variation to fit the change of bottom topography 542 \eg\ a terrain-following or $\sigma$-coordinate; 543 and for the third point, 544 one will be tempted to use a space and time dependent coordinate that follows the isopycnal surfaces, 545 \eg\ an isopycnic coordinate. 546 547 In order to satisfy two or more constraints one can even be tempted to mixed these coordinate systems, 548 as in HYCOM (mixture of $z$-coordinate at the surface, isopycnic coordinate in the ocean interior and 549 $\sigma$ at the ocean bottom) \citep{chassignet.smith.ea_JPO03} or 550 OPA (mixture of $z$-coordinate in vicinity the surface and steep topography areas and 551 $\sigma$-coordinate elsewhere) \citep{madec.delecluse.ea_JPO96} among others. 582 552 583 553 In fact one is totally free to choose any space and time vertical coordinate by 584 554 introducing an arbitrary vertical coordinate : 585 555 \begin{equation} 586 \label{eq: PE_s}556 \label{eq:MB_s} 587 557 s = s(i,j,k,t) 588 558 \end{equation} 589 with the restriction that the above equation gives a single-valued monotonic relationship between $s$ and $k$, 590 when $i$, $j$ and $t$ are held fixed. 591 \autoref{eq:PE_s} is a transformation from the $(i,j,k,t)$ coordinate system with independent variables into 559 with the restriction that the above equation gives a single-valued monotonic relationship between 560 $s$ and $k$, when $i$, $j$ and $t$ are held fixed. 561 \autoref{eq:MB_s} is a transformation from 562 the $(i,j,k,t)$ coordinate system with independent variables into 592 563 the $(i,j,s,t)$ generalised coordinate system with $s$ depending on the other three variables through 593 \autoref{eq:PE_s}. 594 This so-called \textit{generalised vertical coordinate} \citep{Kasahara_MWR74} is in fact 595 an Arbitrary Lagrangian--Eulerian (ALE) coordinate. 596 Indeed, choosing an expression for $s$ is an arbitrary choice that determines 597 which part of the vertical velocity (defined from a fixed referential) will cross the levels (Eulerian part) and 598 which part will be used to move them (Lagrangian part). 599 The coordinate is also sometime referenced as an adaptive coordinate \citep{Hofmeister_al_OM09}, 600 since the coordinate system is adapted in the course of the simulation. 564 \autoref{eq:MB_s}. 565 This so-called \textit{generalised vertical coordinate} \citep{kasahara_MWR74} is in fact 566 an \textbf{A}rbitrary \textbf{L}agrangian--\textbf{E}ulerian (ALE) coordinate. 567 Indeed, one has a great deal of freedom in the choice of expression for $s$. 568 The choice determines which part of the vertical velocity (defined from a fixed referential) 569 will cross the levels (Eulerian part) and which part will be used to move them (Lagrangian part). 570 The coordinate is also sometimes referenced as an adaptive coordinate 571 \citep{hofmeister.burchard.ea_OM10}, since the coordinate system is adapted in 572 the course of the simulation. 601 573 Its most often used implementation is via an ALE algorithm, 602 574 in which a pure lagrangian step is followed by regridding and remapping steps, 603 the lat er step implicitly embedding the vertical advection604 \citep{ Hirt_al_JCP74, Chassignet_al_JPO03, White_al_JCP09}.605 Here we follow the \citep{ Kasahara_MWR74} strategy:606 a regridding step (an update of the vertical coordinate) followed by an eulerian step with575 the latter step implicitly embedding the vertical advection 576 \citep{hirt.amsden.ea_JCP74, chassignet.smith.ea_JPO03, white.adcroft.ea_JCP09}. 577 Here we follow the \citep{kasahara_MWR74} strategy: 578 a regridding step (an update of the vertical coordinate) followed by an Eulerian step with 607 579 an explicit computation of vertical advection relative to the moving s-surfaces. 608 580 609 %\gmcomment{ 610 %A key point here is that the $s$-coordinate depends on $(i,j)$ ==> horizontal pressure gradient... 611 the generalized vertical coordinates used in ocean modelling are not orthogonal,581 \cmtgm{A key point here is that the $s$-coordinate depends on $(i,j)$ 582 ==> horizontal pressure gradient...} 583 The generalized vertical coordinates used in ocean modelling are not orthogonal, 612 584 which contrasts with many other applications in mathematical physics. 613 585 Hence, it is useful to keep in mind the following properties that may seem odd on initial encounter. … … 615 587 The horizontal velocity in ocean models measures motions in the horizontal plane, 616 588 perpendicular to the local gravitational field. 617 That is, horizontal velocity is mathematically the same regardless the vertical coordinate, be it geopotential,618 isopycnal, pressure, or terrain following.589 That is, horizontal velocity is mathematically the same regardless of the vertical coordinate, 590 be it geopotential, isopycnal, pressure, or terrain following. 619 591 The key motivation for maintaining the same horizontal velocity component is that 620 592 the hydrostatic and geostrophic balances are dominant in the large-scale ocean. 621 Use of an alternative quasi -horizontal velocity, for example one oriented parallel to the generalized surface, 593 Use of an alternative quasi -horizontal velocity, 594 for example one oriented parallel to the generalized surface, 622 595 would lead to unacceptable numerical errors. 623 596 Correspondingly, the vertical direction is anti -parallel to the gravitational force in … … 626 599 the surface of a constant generalized vertical coordinate. 627 600 628 It is the method used to measure transport across the generalized vertical coordinate surfaces which differs between 629 the vertical coordinate choices. 630 That is, computation of the dia-surface velocity component represents the fundamental distinction between 601 It is the method used to measure transport across the generalized vertical coordinate surfaces which 602 differs between the vertical coordinate choices. 603 That is, 604 computation of the dia-surface velocity component represents the fundamental distinction between 631 605 the various coordinates. 632 In some models, such as geopotential, pressure, and terrain following, this transport is typically diagnosed from 633 volume or mass conservation. 634 In other models, such as isopycnal layered models, this transport is prescribed based on assumptions about 635 the physical processes producing a flux across the layer interfaces. 606 In some models, such as geopotential, pressure, and terrain following, 607 this transport is typically diagnosed from volume or mass conservation. 608 In other models, such as isopycnal layered models, 609 this transport is prescribed based on assumptions about the physical processes producing 610 a flux across the layer interfaces. 636 611 637 612 In this section we first establish the PE in the generalised vertical $s$-coordinate, … … 639 614 %} 640 615 641 % ------------------------------------------------------------------------------------------------------------- 642 % The s-coordinate Formulation 643 % ------------------------------------------------------------------------------------------------------------- 616 %% ================================================================================================= 644 617 \subsection{\textit{S}-coordinate formulation} 645 618 646 Starting from the set of equations established in \autoref{sec:PE_zco} for the special case $k = z$ and 647 thus $e_3 = 1$, we introduce an arbitrary vertical coordinate $s = s(i,j,k,t)$, 619 Starting from the set of equations established in \autoref{sec:MB_zco} for 620 the special case $k = z$ and thus $e_3 = 1$, 621 we introduce an arbitrary vertical coordinate $s = s(i,j,k,t)$, 648 622 which includes $z$-, \zstar- and $\sigma$-coordinates as special cases 649 623 ($s = z$, $s = \zstar$, and $s = \sigma = z / H$ or $ = z / \lt( H + \eta \rt)$, resp.). 650 A formal derivation of the transformed equations is given in \autoref{apdx:A}. 651 Let us define the vertical scale factor by $e_3 = \partial_s z$ ($e_3$ is now a function of $(i,j,k,t)$ ), 624 A formal derivation of the transformed equations is given in \autoref{apdx:SCOORD}. 625 Let us define the vertical scale factor by $e_3 = \partial_s z$ 626 ($e_3$ is now a function of $(i,j,k,t)$ ), 652 627 and the slopes in the $(i,j)$ directions between $s$- and $z$-surfaces by: 653 628 \begin{equation} 654 \label{eq: PE_sco_slope}629 \label{eq:MB_sco_slope} 655 630 \sigma_1 = \frac{1}{e_1} \; \lt. \pd[z]{i} \rt|_s \quad \text{and} \quad 656 631 \sigma_2 = \frac{1}{e_2} \; \lt. \pd[z]{j} \rt|_s 657 632 \end{equation} 658 We also introduce $\omega$, a dia-surface velocity component, defined as the velocity659 relative to the moving $s$-surfaces and normal to them:633 We also introduce $\omega$, a dia-surface velocity component, 634 defined as the velocity relative to the moving $s$-surfaces and normal to them: 660 635 \[ 661 % \label{eq: PE_sco_w}662 \omega = w - e_3 \, \pd[s]{t}- \sigma_1 \, u - \sigma_2 \, v636 % \label{eq:MB_sco_w} 637 \omega = w - \, \lt. \pd[z]{t} \rt|_s - \sigma_1 \, u - \sigma_2 \, v 663 638 \] 664 639 665 The equations solved by the ocean model \autoref{eq:PE} in $s$-coordinate can be written as follows 666 (see \autoref{sec:A_momentum}): 667 668 \begin{itemize} 669 \item \textbf{Vector invariant form of the momentum equation}: 670 \begin{multline*} 671 % \label{eq:PE_sco_u_vector} 672 \pd[u]{t} = + (\zeta + f) \, v - \frac{1}{2 \, e_1} \pd[]{i} (u^2 + v^2) - \frac{1}{e_3} \omega \pd[u]{k} \\ 673 - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) + g \frac{\rho}{\rho_o} \sigma_1 674 + D_u^{\vect U} + F_u^{\vect U} 675 \end{multline*} 676 \begin{multline*} 677 % \label{eq:PE_sco_v_vector} 678 \pd[v]{t} = - (\zeta + f) \, u - \frac{1}{2 \, e_2} \pd[]{j}(u^2 + v^2) - \frac{1}{e_3} \omega \pd[v]{k} \\ 679 - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) + g \frac{\rho}{\rho_o} \sigma_2 680 + D_v^{\vect U} + F_v^{\vect U} 681 \end{multline*} 682 \item \textbf{Flux form of the momentum equation}: 683 \begin{multline*} 684 % \label{eq:PE_sco_u_flux} 685 \frac{1}{e_3} \pd[(e_3 \, u)]{t} = + \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, v \\ 686 - \frac{1}{e_1 \; e_2 \; e_3} \lt( \pd[(e_2 \, e_3 \, u \, u)]{i} + \pd[(e_1 \, e_3 \, v \, u)]{j} \rt) \\ 687 - \frac{1}{e_3} \pd[(\omega \, u)]{k} 688 - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) 689 + g \frac{\rho}{\rho_o} \sigma_1 + D_u^{\vect U} + F_u^{\vect U} 690 \end{multline*} 691 \begin{multline*} 692 % \label{eq:PE_sco_v_flux} 693 \frac{1}{e_3} \pd[(e_3 \, v)]{t} = - \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, u \\ 694 - \frac{1}{e_1 \; e_2 \; e_3} \lt( \pd[( e_2 \; e_3 \, u \, v)]{i} + \pd[(e_1 \; e_3 \, v \, v)]{j} \rt) \\ 695 - \frac{1}{e_3} \pd[(\omega \, v)]{k} 696 - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) 697 + g \frac{\rho}{\rho_o}\sigma_2 + D_v^{\vect U} + F_v^{\vect U} 698 \end{multline*} 640 The equations solved by the ocean model \autoref{eq:MB_PE} in $s$-coordinate can be written as follows 641 (see \autoref{sec:SCOORD_momentum}): 642 643 \begin{description} 644 \item [Vector invariant form of the momentum equation] 645 \begin{gather*} 646 % \label{eq:MB_sco_u_vector} 647 \pd[u]{t} = + (\zeta + f) \, v - \frac{1}{2 \, e_1} \pd[]{i} (u^2 + v^2) - \frac{1}{e_3} \omega \pd[u]{k} - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) - g \frac{\rho}{\rho_o} \sigma_1 + D_u^{\vect U} + F_u^{\vect U} \\ 648 % \label{eq:MB_sco_v_vector} 649 \pd[v]{t} = - (\zeta + f) \, u - \frac{1}{2 \, e_2} \pd[]{j} (u^2 + v^2) - \frac{1}{e_3} \omega \pd[v]{k} - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) - g \frac{\rho}{\rho_o} \sigma_2 + D_v^{\vect U} + F_v^{\vect U} 650 \end{gather*} 651 \item [Flux form of the momentum equation] 652 \begin{alignat*}{2} 653 % \label{eq:MB_sco_u_flux} 654 \frac{1}{e_3} \pd[(e_3 \, u)]{t} = &+ \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, v - \frac{1}{e_1 \; e_2 \; e_3} \lt( \pd[(e_2 \, e_3 \, u \, u)]{i} + \pd[(e_1 \, e_3 \, v \, u)]{j} \rt) - \frac{1}{e_3} \pd[(\omega \, u)]{k} \\ 655 &- \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) - g \frac{\rho}{\rho_o} \sigma_1 + D_u^{\vect U} + F_u^{\vect U} 656 \end{alignat*} 657 \begin{alignat*}{2} 658 % \label{eq:MB_sco_v_flux} 659 \frac{1}{e_3} \pd[(e_3 \, v)]{t} = &- \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, u - \frac{1}{e_1 \; e_2 \; e_3} \lt( \pd[( e_2 \; e_3 \, u \, v)]{i} + \pd[(e_1 \; e_3 \, v \, v)]{j} \rt) - \frac{1}{e_3} \pd[(\omega \, v)]{k} \\ 660 &- \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) - g \frac{\rho}{\rho_o}\sigma_2 + D_v^{\vect U} + F_v^{\vect U} 661 \end{alignat*} 699 662 where the relative vorticity, $\zeta$, the surface pressure gradient, 700 663 and the hydrostatic pressure have the same expressions as in $z$-coordinates although 701 664 they do not represent exactly the same quantities. 702 $\omega$ is provided by the continuity equation (see \autoref{apdx: A}):665 $\omega$ is provided by the continuity equation (see \autoref{apdx:SCOORD}): 703 666 \[ 704 % \label{eq: PE_sco_continuity}667 % \label{eq:MB_sco_continuity} 705 668 \pd[e_3]{t} + e_3 \; \chi + \pd[\omega]{s} = 0 \quad \text{with} \quad 706 669 \chi = \frac{1}{e_1 e_2 e_3} \lt( \pd[(e_2 e_3 \, u)]{i} + \pd[(e_1 e_3 \, v)]{j} \rt) 707 670 \] 708 \item \textit{tracer equations}: 709 \begin{multline*} 710 % \label{eq:PE_sco_t} 711 \frac{1}{e_3} \pd[(e_3 \, T)]{t} = - \frac{1}{e_1 e_2 e_3} \lt( \pd[(e_2 e_3 \, u \, T)]{i} 712 + \pd[(e_1 e_3 \, v \, T)]{j} \rt) \\ 713 - \frac{1}{e_3} \pd[(T \, \omega)]{k} + D^T + F^S 714 \end{multline*} 715 \begin{multline} 716 % \label{eq:PE_sco_s} 717 \frac{1}{e_3} \pd[(e_3 \, S)]{t} = - \frac{1}{e_1 e_2 e_3} \lt( \pd[(e_2 e_3 \, u \, S)]{i} 718 + \pd[(e_1 e_3 \, v \, S)]{j} \rt) \\ 719 - \frac{1}{e_3} \pd[(S \, \omega)]{k} + D^S + F^S 720 \end{multline} 721 \end{itemize} 671 \item [Tracer equations] 672 \begin{gather*} 673 % \label{eq:MB_sco_t} 674 \frac{1}{e_3} \pd[(e_3 \, T)]{t} = - \frac{1}{e_1 e_2 e_3} \lt( \pd[(e_2 e_3 \, u \, T)]{i} + \pd[(e_1 e_3 \, v \, T)]{j} \rt) - \frac{1}{e_3} \pd[(T \, \omega)]{k} + D^T + F^S \\ 675 % \label{eq:MB_sco_s} 676 \frac{1}{e_3} \pd[(e_3 \, S)]{t} = - \frac{1}{e_1 e_2 e_3} \lt( \pd[(e_2 e_3 \, u \, S)]{i} + \pd[(e_1 e_3 \, v \, S)]{j} \rt) - \frac{1}{e_3} \pd[(S \, \omega)]{k} + D^S + F^S 677 \end{gather*} 678 \end{description} 722 679 The equation of state has the same expression as in $z$-coordinate, 723 680 and similar expressions are used for mixing and forcing terms. 724 681 725 \ gmcomment{682 \cmtgm{ 726 683 \colorbox{yellow}{ to be updated $= = >$} 727 684 Add a few works on z and zps and s and underlies the differences between all of them … … 729 686 } 730 687 731 % ------------------------------------------------------------------------------------------------------------- 732 % Curvilinear \zstar-coordinate System 733 % ------------------------------------------------------------------------------------------------------------- 688 %% ================================================================================================= 734 689 \subsection{Curvilinear \zstar-coordinate system} 735 \label{subsec: PE_zco_star}736 737 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 738 \begin{figure}[!b] 739 \ begin{center}740 \includegraphics[]{Fig_z_zstar}741 \ caption{742 \protect\label{fig:z_zstar}743 (a) $z$-coordinate in linear free-surface case;744 (b) $z$-coordinate in non-linear free surface case ;745 ( c) re-scaled height coordinate746 (become popular as the \zstar-coordinate \citep{Adcroft_Campin_OM04}).747 748 \ end{center}690 \label{subsec:MB_zco_star} 691 692 \begin{figure} 693 \centering 694 \includegraphics[width=0.66\textwidth]{MB_z_zstar} 695 \caption[Curvilinear z-coordinate systems (\{non-\}linear free-surface cases and re-scaled \zstar)]{ 696 \begin{enumerate*}[label=(\textit{\alph*})] 697 \item $z$-coordinate in linear free-surface case; 698 \item $z$-coordinate in non-linear free surface case; 699 \item re-scaled height coordinate 700 (become popular as the \zstar-coordinate \citep{adcroft.campin_OM04}). 701 \end{enumerate*} 702 } 703 \label{fig:MB_z_zstar} 749 704 \end{figure} 750 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 751 752 In that case, the free surface equation is nonlinear, and the variations of volume are fully taken into account. 753 These coordinates systems is presented in a report \citep{Levier2007} available on the \NEMO web site. 754 755 The \zstar coordinate approach is an unapproximated, non-linear free surface implementation which allows one to 756 deal with large amplitude free-surface variations relative to the vertical resolution \citep{Adcroft_Campin_OM04}. 757 In the \zstar formulation, 758 the variation of the column thickness due to sea-surface undulations is not concentrated in the surface level, 759 as in the $z$-coordinate formulation, but is equally distributed over the full water column. 705 706 In this case, the free surface equation is nonlinear, 707 and the variations of volume are fully taken into account. 708 These coordinates systems is presented in a report \citep{levier.treguier.ea_rpt07} available on 709 the \NEMO\ web site. 710 711 The \zstar\ coordinate approach is an unapproximated, non-linear free surface implementation which 712 allows one to deal with large amplitude free-surface variations relative to the vertical resolution 713 \citep{adcroft.campin_OM04}. 714 In the \zstar\ formulation, the variation of the column thickness due to sea-surface undulations is 715 not concentrated in the surface level, as in the $z$-coordinate formulation, 716 but is equally distributed over the full water column. 760 717 Thus vertical levels naturally follow sea-surface variations, with a linear attenuation with depth, 761 as illustrated by \autoref{fig:z_zstar}. 762 Note that with a flat bottom, such as in \autoref{fig:z_zstar}, the bottom-following $z$ coordinate and \zstar are equivalent. 718 as illustrated by \autoref{fig:MB_z_zstar}. 719 Note that with a flat bottom, such as in \autoref{fig:MB_z_zstar}, 720 the bottom-following $z$ coordinate and \zstar\ are equivalent. 763 721 The definition and modified oceanic equations for the rescaled vertical coordinate \zstar, 764 722 including the treatment of fresh-water flux at the surface, are detailed in Adcroft and Campin (2004). 765 723 The major points are summarized here. 766 The position (\zstar) and vertical discretization ( \zstar) are expressed as:724 The position (\zstar) and vertical discretization ($\delta \zstar$) are expressed as: 767 725 \[ 768 % \label{eq:z-star} 769 H + \zstar = (H + z) / r \quad \text{and} \quad \delta \zstar 770 = \delta z / r \quad \text{with} \quad r 771 = \frac{H + \eta}{H} 726 % \label{eq:MB_z-star} 727 H + \zstar = (H + z) / r \quad \text{and} \quad \delta \zstar = \delta z / r \quad \text{with} \quad r = \frac{H + \eta}{H} 728 \] 729 Simple re-organisation of the above expressions gives 730 \[ 731 % \label{eq:MB_zstar_2} 732 \zstar = H \lt( \frac{z - \eta}{H + \eta} \rt) 772 733 \] 773 734 Since the vertical displacement of the free surface is incorporated in the vertical coordinate \zstar, 774 the upper and lower boundaries are at fixed \zstarposition,735 the upper and lower boundaries are at fixed \zstar\ position, 775 736 $\zstar = 0$ and $\zstar = -H$ respectively. 776 737 Also the divergence of the flow field is no longer zero as shown by the continuity equation: 777 738 \[ 778 \pd[r]{t} = \nabla_{\zstar} \cdot \lt( r \; \vect U_h \rt) (r \; w *)= 0739 \pd[r]{t} = \nabla_{\zstar} \cdot \lt( r \; \vect U_h \rt) + \pd[r \; w^*]{\zstar} = 0 779 740 \] 780 781 % from MOM4p1 documentation 782 To overcome problems with vanishing surface and/or bottom cells, we consider the zstar coordinate 783 \[ 784 % \label{eq:PE_} 785 \zstar = H \lt( \frac{z - \eta}{H + \eta} \rt) 786 \] 787 788 This coordinate is closely related to the "eta" coordinate used in many atmospheric models 789 (see Black (1994) for a review of eta coordinate atmospheric models). 741 This \zstar\ coordinate is closely related to the $\eta$ coordinate used in many atmospheric models 742 (see Black (1994) for a review of $\eta$ coordinate atmospheric models). 790 743 It was originally used in ocean models by Stacey et al. (1995) for studies of tides next to shelves, 791 744 and it has been recently promoted by Adcroft and Campin (2004) for global climate modelling. 792 745 793 The surfaces of constant \zstar are quasi-horizontal.794 Indeed, the \zstar coordinate reduces to $z$ when $\eta$ is zero.746 The surfaces of constant \zstar\ are quasi-horizontal. 747 Indeed, the \zstar\ coordinate reduces to $z$ when $\eta$ is zero. 795 748 In general, when noting the large differences between 796 749 undulations of the bottom topography versus undulations in the surface height, 797 it is clear that surfaces constant \zstar are very similar to the depth surfaces.750 it is clear that surfaces constant \zstar\ are very similar to the depth surfaces. 798 751 These properties greatly reduce difficulties of computing the horizontal pressure gradient relative to 799 terrain following sigma models discussed in \autoref{subsec:PE_sco}. 800 Additionally, since \zstar when $\eta = 0$, 801 no flow is spontaneously generated in an unforced ocean starting from rest, regardless the bottom topography. 802 This behaviour is in contrast to the case with "s"-models, where pressure gradient errors in the presence of 803 nontrivial topographic variations can generate nontrivial spontaneous flow from a resting state, 752 terrain following sigma models discussed in \autoref{subsec:MB_sco}. 753 Additionally, since $\zstar = z$ when $\eta = 0$, 754 no flow is spontaneously generated in an unforced ocean starting from rest, 755 regardless the bottom topography. 756 This behaviour is in contrast to the case with ``s''-models, 757 where pressure gradient errors in the presence of nontrivial topographic variations can generate 758 nontrivial spontaneous flow from a resting state, 804 759 depending on the sophistication of the pressure gradient solver. 805 The quasi 806 neutral physics parameterizations in \zstar models using the same techniques as in $z$-models807 (see Chapters 13-16 of \cite{ Griffies_Bk04}) for a discussion of neutral physics in $z$-models,760 The quasi-horizontal nature of the coordinate surfaces also facilitates the implementation of 761 neutral physics parameterizations in \zstar\ models using the same techniques as in $z$-models 762 (see Chapters 13-16 of \cite{griffies_bk04}) for a discussion of neutral physics in $z$-models, 808 763 as well as \autoref{sec:LDF_slp} in this document for treatment in \NEMO). 809 764 810 The range over which \zstar varies is time independent $-H \leq \zstar \leq 0$. 811 Hence, all cells remain nonvanishing, so long as the surface height maintains $\eta > ?H$. 812 This is a minor constraint relative to that encountered on the surface height when using $s = z$ or $s = z - \eta$. 813 814 Because \zstar has a time independent range, all grid cells have static increments ds, 815 and the sum of the ver tical increments yields the time independent ocean depth. %k ds = H. 816 The \zstar coordinate is therefore invisible to undulations of the free surface, 765 The range over which \zstar\ varies is time independent $-H \leq \zstar \leq 0$. 766 Hence, all cells remain nonvanishing, so long as the surface height maintains $\eta > -H$. 767 This is a minor constraint relative to that encountered on the surface height when 768 using $s = z$ or $s = z - \eta$. 769 770 Because \zstar\ has a time independent range, all grid cells have static increments ds, 771 and the sum of the vertical increments yields the time independent ocean depth. %k ds = H. 772 The \zstar\ coordinate is therefore invisible to undulations of the free surface, 817 773 since it moves along with the free surface. 818 This proper ty means that no spurious vertical transport is induced across surfaces of constant \zstar by 819 the motion of external gravity waves. 820 Such spurious transpor t can be a problem in z-models, especially those with tidal forcing. 821 Quite generally, the time independent range for the \zstar coordinate is a very convenient property that 822 allows for a nearly arbitrary ver tical resolution even in the presence of large amplitude fluctuations of 823 the surface height, again so long as $\eta > -H$. 774 This property means that no spurious vertical transport is induced across 775 surfaces of constant \zstar\ by the motion of external gravity waves. 776 Such spurious transport can be a problem in z-models, especially those with tidal forcing. 777 Quite generally, 778 the time independent range for the \zstar\ coordinate is a very convenient property that 779 allows for a nearly arbitrary vertical resolution even in 780 the presence of large amplitude fluctuations of the surface height, again so long as $\eta > -H$. 824 781 %end MOM doc %%% 825 782 826 \newpage 827 828 % ------------------------------------------------------------------------------------------------------------- 829 % Terrain following coordinate System 830 % ------------------------------------------------------------------------------------------------------------- 783 %% ================================================================================================= 831 784 \subsection{Curvilinear terrain-following \textit{s}--coordinate} 832 \label{subsec:PE_sco} 833 834 % ------------------------------------------------------------------------------------------------------------- 835 % Introduction 836 % ------------------------------------------------------------------------------------------------------------- 837 \subsubsection{Introduction} 785 \label{subsec:MB_sco} 838 786 839 787 Several important aspects of the ocean circulation are influenced by bottom topography. 840 Of course, the most important is that bottom topography determines deep ocean sub-basins, barriers, sills and 841 channels that strongly constrain the path of water masses, but more subtle effects exist. 842 For example, the topographic $\beta$-effect is usually larger than the planetary one along continental slopes. 788 Of course, the most important is that bottom topography determines deep ocean sub-basins, barriers, 789 sills and channels that strongly constrain the path of water masses, but more subtle effects exist. 790 For example, 791 the topographic $\beta$-effect is usually larger than the planetary one along continental slopes. 843 792 Topographic Rossby waves can be excited and can interact with the mean current. 844 In the $z$-coordinate system presented in the previous section (\autoref{sec: PE_zco}),793 In the $z$-coordinate system presented in the previous section (\autoref{sec:MB_zco}), 845 794 $z$-surfaces are geopotential surfaces. 846 795 The bottom topography is discretised by steps. … … 848 797 large localized depth gradients associated with large localized vertical velocities. 849 798 The response to such a velocity field often leads to numerical dispersion effects. 850 One solution to strongly reduce this error is to use a partial step representation of bottom topography instead of851 a full step one \cite{Pacanowski_Gnanadesikan_MWR98}.799 One solution to strongly reduce this error is to use a partial step representation of 800 bottom topography instead of a full step one \cite{pacanowski.gnanadesikan_MWR98}. 852 801 Another solution is to introduce a terrain-following coordinate system (hereafter $s$-coordinate). 853 802 854 The $s$-coordinate avoids the discretisation error in the depth field since the layers of 855 computation are gradually adjusted with depth to the ocean bottom. 856 Relatively small topographic features as well as gentle, large-scale slopes of the sea floor in the deep ocean, 857 which would be ignored in typical $z$-model applications with the largest grid spacing at greatest depths, 803 The $s$-coordinate avoids the discretisation error in the depth field since 804 the layers of computation are gradually adjusted with depth to the ocean bottom. 805 Relatively small topographic features as well as 806 gentle, large-scale slopes of the sea floor in the deep ocean, 807 which would be ignored in typical $z$-model applications with 808 the largest grid spacing at greatest depths, 858 809 can easily be represented (with relatively low vertical resolution). 859 A terrain-following model (hereafter $s$-model) also facilitates the modelling of the boundary layer flows over 860 a large depth range, which in the framework of the $z$-model would require high vertical resolution over 810 A terrain-following model (hereafter $s$-model) also facilitates 811 the modelling of the boundary layer flows over a large depth range, 812 which in the framework of the $z$-model would require high vertical resolution over 861 813 the whole depth range. 862 Moreover, with a $s$-coordinate it is possible, at least in principle, to have the bottom and the sea surface as 814 Moreover, 815 with a $s$-coordinate it is possible, at least in principle, to have the bottom and the sea surface as 863 816 the only boundaries of the domain (no more lateral boundary condition to specify). 864 Nevertheless, a $s$-coordinate also has its drawbacks. Perfectly adapted to a homogeneous ocean, 817 Nevertheless, a $s$-coordinate also has its drawbacks. 818 Perfectly adapted to a homogeneous ocean, 865 819 it has strong limitations as soon as stratification is introduced. 866 820 The main two problems come from the truncation error in the horizontal pressure gradient and 867 821 a possibly increased diapycnal diffusion. 868 The horizontal pressure force in $s$-coordinate consists of two terms (see \autoref{apdx:A}), 869 822 The horizontal pressure force in $s$-coordinate consists of two terms (see \autoref{apdx:SCOORD}), 870 823 \begin{equation} 871 \label{eq: PE_p_sco}872 \nabla p |_z = \nabla p |_s - \ pd[p]{s} \nabla z |_s824 \label{eq:MB_p_sco} 825 \nabla p |_z = \nabla p |_s - \frac{1}{e_3} \pd[p]{s} \nabla z |_s 873 826 \end{equation} 874 827 875 The second term in \autoref{eq:PE_p_sco} depends on the tilt of the coordinate surface and 876 introduces a truncation error that is not present in a $z$-model. 877 In the special case of a $\sigma$-coordinate (i.e. a depth-normalised coordinate system $\sigma = z/H$), 878 \citet{Haney1991} and \citet{Beckmann1993} have given estimates of the magnitude of this truncation error. 879 It depends on topographic slope, stratification, horizontal and vertical resolution, the equation of state, 880 and the finite difference scheme. 828 The second term in \autoref{eq:MB_p_sco} depends on the tilt of the coordinate surface and 829 leads to a truncation error that is not present in a $z$-model. 830 In the special case of a $\sigma$-coordinate 831 (i.e. a depth-normalised coordinate system $\sigma = z/H$), 832 \citet{haney_JPO91} and \citet{beckmann.haidvogel_JPO93} have given estimates of 833 the magnitude of this truncation error. 834 It depends on topographic slope, stratification, horizontal and vertical resolution, 835 the equation of state, and the finite difference scheme. 881 836 This error limits the possible topographic slopes that a model can handle at 882 837 a given horizontal and vertical resolution. 883 838 This is a severe restriction for large-scale applications using realistic bottom topography. 884 The large-scale slopes require high horizontal resolution, and the computational cost becomes prohibitive. 839 The large-scale slopes require high horizontal resolution, 840 and the computational cost becomes prohibitive. 885 841 This problem can be at least partially overcome by mixing $s$-coordinate and 886 step-like representation of bottom topography \citep{Gerdes1993a,Gerdes1993b,Madec_al_JPO96}. 842 step-like representation of bottom topography 843 \citep{gerdes_JGR93*a,gerdes_JGR93*b,madec.delecluse.ea_JPO96}. 887 844 However, the definition of the model domain vertical coordinate becomes then a non-trivial thing for 888 845 a realistic bottom topography: 889 a envelope topography is defined in $s$-coordinate on which a full or890 partial step bottom topography is then applied in order to adjust the model depth to the observed one 891 (see \autoref{sec:DOM_zgr}.892 893 For numerical reasons a minimum of diffusion is required along the coordinate surfaces of894 any finite difference model.846 an envelope topography is defined in $s$-coordinate on which 847 a full or partial step bottom topography is then applied in order to 848 adjust the model depth to the observed one (see \autoref{subsec:DOM_zgr}). 849 850 For numerical reasons a minimum of diffusion is required along 851 the coordinate surfaces of any finite difference model. 895 852 It causes spurious diapycnal mixing when coordinate surfaces do not coincide with isoneutral surfaces. 896 853 This is the case for a $z$-model as well as for a $s$-model. 897 However, density varies more strongly on $s$-surfaces than on horizontal surfaces in regions of 898 large topographic slopes, implying larger diapycnal diffusion in a $s$-model than in a $z$-model. 899 Whereas such a diapycnal diffusion in a $z$-model tends to weaken horizontal density (pressure) gradients and thus 900 the horizontal circulation, it usually reinforces these gradients in a $s$-model, creating spurious circulation. 901 For example, imagine an isolated bump of topography in an ocean at rest with a horizontally uniform stratification. 854 However, density varies more strongly on $s$-surfaces than on horizontal surfaces in 855 regions of large topographic slopes, 856 implying larger diapycnal diffusion in a $s$-model than in a $z$-model. 857 Whereas such a diapycnal diffusion in a $z$-model tends to 858 weaken horizontal density (pressure) gradients and thus the horizontal circulation, 859 it usually reinforces these gradients in a $s$-model, creating spurious circulation. 860 For example, imagine an isolated bump of topography in 861 an ocean at rest with a horizontally uniform stratification. 902 862 Spurious diffusion along $s$-surfaces will induce a bump of isoneutral surfaces over the topography, 903 863 and thus will generate there a baroclinic eddy. 904 864 In contrast, the ocean will stay at rest in a $z$-model. 905 As for the truncation error, the problem can be reduced by introducing the terrain-following coordinate below 906 the strongly stratified portion of the water column (\ie the main thermocline) \citep{Madec_al_JPO96}. 907 An alternate solution consists of rotating the lateral diffusive tensor to geopotential or to isoneutral surfaces 908 (see \autoref{subsec:PE_ldf}). 865 As for the truncation error, the problem can be reduced by 866 introducing the terrain-following coordinate below the strongly stratified portion of the water column 867 (\ie\ the main thermocline) \citep{madec.delecluse.ea_JPO96}. 868 An alternate solution consists of rotating the lateral diffusive tensor to 869 geopotential or to isoneutral surfaces (see \autoref{subsec:MB_ldf}). 909 870 Unfortunately, the slope of isoneutral surfaces relative to the $s$-surfaces can very large, 910 strongly exceeding the stability limit of such a operator when it is discretized (see \autoref{chap:LDF}). 911 912 The $s$-coordinates introduced here \citep{Lott_al_OM90,Madec_al_JPO96} differ mainly in two aspects from 913 similar models: 914 it allows a representation of bottom topography with mixed full or partial step-like/terrain following topography; 871 strongly exceeding the stability limit of such a operator when it is discretized 872 (see \autoref{chap:LDF}). 873 874 The $s$-coordinates introduced here \citep{lott.madec.ea_OM90,madec.delecluse.ea_JPO96} 875 differ mainly in two aspects from similar models: 876 it allows a representation of bottom topography with 877 mixed full or partial step-like/terrain following topography; 915 878 It also offers a completely general transformation, $s=s(i,j,z)$ for the vertical coordinate. 916 879 917 % ------------------------------------------------------------------------------------------------------------- 918 % Curvilinear z-tilde coordinate System 919 % ------------------------------------------------------------------------------------------------------------- 920 \subsection{\texorpdfstring{Curvilinear \ztilde-coordinate}{}} 921 \label{subsec:PE_zco_tilde} 922 923 The \ztilde -coordinate has been developed by \citet{Leclair_Madec_OM11}. 924 It is available in \NEMO since the version 3.4. 880 %% ================================================================================================= 881 \subsection{Curvilinear \ztilde-coordinate} 882 \label{subsec:MB_zco_tilde} 883 884 The \ztilde-coordinate has been developed by \citet{leclair.madec_OM11}. 885 It is available in \NEMO\ since the version 3.4 and is more robust in version 4.0 than previously. 925 886 Nevertheless, it is currently not robust enough to be used in all possible configurations. 926 887 Its use is therefore not recommended. 927 888 928 \newpage 929 930 % ================================================================ 931 % Subgrid Scale Physics 932 % ================================================================ 889 %% ================================================================================================= 933 890 \section{Subgrid scale physics} 934 \label{sec:PE_zdf_ldf} 935 936 The primitive equations describe the behaviour of a geophysical fluid at space and time scales larger than 937 a few kilometres in the horizontal, a few meters in the vertical and a few minutes. 938 They are usually solved at larger scales: the specified grid spacing and time step of the numerical model. 891 \label{sec:MB_zdf_ldf} 892 893 The hydrostatic primitive equations describe the behaviour of a geophysical fluid at 894 space and time scales larger than a few kilometres in the horizontal, 895 a few meters in the vertical and a few minutes. 896 They are usually solved at larger scales: the specified grid spacing and time step of 897 the numerical model. 939 898 The effects of smaller scale motions (coming from the advective terms in the Navier-Stokes equations) 940 899 must be represented entirely in terms of large-scale patterns to close the equations. 941 900 These effects appear in the equations as the divergence of turbulent fluxes 942 (\ie fluxes associated with the mean correlation of small scale perturbations).901 (\ie\ fluxes associated with the mean correlation of small scale perturbations). 943 902 Assuming a turbulent closure hypothesis is equivalent to choose a formulation for these fluxes. 944 903 It is usually called the subgrid scale physics. … … 947 906 small scale processes \textit{in fine} balance the surface input of kinetic energy and heat. 948 907 949 The control exerted by gravity on the flow induces a strong anisotropy between the lateral and vertical motions. 908 The control exerted by gravity on the flow induces a strong anisotropy between 909 the lateral and vertical motions. 950 910 Therefore subgrid-scale physics \textbf{D}$^{\vect U}$, $D^{S}$ and $D^{T}$ in 951 \autoref{eq: PE_dyn}, \autoref{eq:PE_tra_T} and \autoref{eq:PE_tra_S} are divided into952 a lateral part \textbf{D}$^{l \vect U}$, $D^{l S}$ and $D^{l T}$ and911 \autoref{eq:MB_PE_dyn}, \autoref{eq:MB_PE_tra_T} and \autoref{eq:MB_PE_tra_S} are divided into 912 a lateral part \textbf{D}$^{l \vect U}$, $D^{l S}$ and $D^{l T}$ and 953 913 a vertical part \textbf{D}$^{v \vect U}$, $D^{v S}$ and $D^{v T}$. 954 The formulation of these terms and their underlying physics are briefly discussed in the next two subsections. 955 956 % ------------------------------------------------------------------------------------------------------------- 957 % Vertical Subgrid Scale Physics 958 % ------------------------------------------------------------------------------------------------------------- 914 The formulation of these terms and their underlying physics are briefly discussed in 915 the next two subsections. 916 917 %% ================================================================================================= 959 918 \subsection{Vertical subgrid scale physics} 960 \label{subsec: PE_zdf}961 962 The model resolution is always larger than the scale at which the major sources of vertical turbulence occur963 (shear instability, internal wave breaking...).919 \label{subsec:MB_zdf} 920 921 The model resolution is always larger than the scale at which 922 the major sources of vertical turbulence occur (shear instability, internal wave breaking...). 964 923 Turbulent motions are thus never explicitly solved, even partially, but always parameterized. 965 The vertical turbulent fluxes are assumed to depend linearly on the gradients of large-scale quantities 966 (for example, the turbulent heat flux is given by $\overline{T' w'} = -A^{v T} \partial_z \overline T$, 924 The vertical turbulent fluxes are assumed to depend linearly on 925 the gradients of large-scale quantities (for example, 926 the turbulent heat flux is given by $\overline{T' w'} = -A^{v T} \partial_z \overline T$, 967 927 where $A^{v T}$ is an eddy coefficient). 968 928 This formulation is analogous to that of molecular diffusion and dissipation. … … 972 932 The resulting vertical momentum and tracer diffusive operators are of second order: 973 933 \begin{equation} 974 \label{eq: PE_zdf}934 \label{eq:MB_zdf} 975 935 \begin{gathered} 976 \vect D^{v \vect U} = \pd[]{z} \lt( A^{vm} \pd[\vect U_h]{z} \rt) \ , \\977 D^{vT} = \pd[]{z} \lt( A^{vT} \pd[T]{z} \rt) \ quad \text{and} \quad936 \vect D^{v \vect U} = \pd[]{z} \lt( A^{vm} \pd[\vect U_h]{z} \rt) \text{,} \ 937 D^{vT} = \pd[]{z} \lt( A^{vT} \pd[T]{z} \rt) \ \text{and} \ 978 938 D^{vS} = \pd[]{z} \lt( A^{vT} \pd[S]{z} \rt) 979 939 \end{gathered} 980 940 \end{equation} 981 where $A^{vm}$ and $A^{vT}$ are the vertical eddy viscosity and diffusivity coefficients, respectively. 941 where $A^{vm}$ and $A^{vT}$ are the vertical eddy viscosity and diffusivity coefficients, 942 respectively. 982 943 At the sea surface and at the bottom, turbulent fluxes of momentum, heat and salt must be specified 983 944 (see \autoref{chap:SBC} and \autoref{chap:ZDF} and \autoref{sec:TRA_bbl}). 984 945 All the vertical physics is embedded in the specification of the eddy coefficients. 985 946 They can be assumed to be either constant, or function of the local fluid properties 986 (\eg Richardson number, Brunt-Vais\"{a}l\"{a} frequency...),947 (\eg\ Richardson number, Brunt-V\"{a}is\"{a}l\"{a} frequency, distance from the boundary ...), 987 948 or computed from a turbulent closure model. 988 The choices available in \NEMO are discussed in \autoref{chap:ZDF}). 989 990 % ------------------------------------------------------------------------------------------------------------- 991 % Lateral Diffusive and Viscous Operators Formulation 992 % ------------------------------------------------------------------------------------------------------------- 949 The choices available in \NEMO\ are discussed in \autoref{chap:ZDF}). 950 951 %% ================================================================================================= 993 952 \subsection{Formulation of the lateral diffusive and viscous operators} 994 \label{subsec: PE_ldf}953 \label{subsec:MB_ldf} 995 954 996 955 Lateral turbulence can be roughly divided into a mesoscale turbulence associated with eddies 997 956 (which can be solved explicitly if the resolution is sufficient since 998 957 their underlying physics are included in the primitive equations), 999 and a sub mesoscale turbulence which is never explicitly solved even partially, but always parameterized. 1000 The formulation of lateral eddy fluxes depends on whether the mesoscale is below or above the grid-spacing 1001 (\ie the model is eddy-resolving or not). 958 and a sub mesoscale turbulence which is never explicitly solved even partially, 959 but always parameterized. 960 The formulation of lateral eddy fluxes depends on whether 961 the mesoscale is below or above the grid-spacing (\ie\ the model is eddy-resolving or not). 1002 962 1003 963 In non-eddy-resolving configurations, the closure is similar to that used for the vertical physics. 1004 The lateral turbulent fluxes are assumed to depend linearly on the lateral gradients of large-scale quantities. 964 The lateral turbulent fluxes are assumed to depend linearly on 965 the lateral gradients of large-scale quantities. 1005 966 The resulting lateral diffusive and dissipative operators are of second order. 1006 Observations show that lateral mixing induced by mesoscale turbulence tends to be along isopycnal surfaces 1007 (or more precisely neutral surfaces \cite{McDougall1987}) rather than across them. 1008 As the slope of neutral surfaces is small in the ocean, a common approximation is to assume that 1009 the `lateral' direction is the horizontal, \ie the lateral mixing is performed along geopotential surfaces. 967 Observations show that 968 lateral mixing induced by mesoscale turbulence tends to be along isopycnal surfaces 969 (or more precisely neutral surfaces \cite{mcdougall_JPO87}) rather than across them. 970 As the slope of neutral surfaces is small in the ocean, 971 a common approximation is to assume that the ``lateral'' direction is the horizontal, 972 \ie\ the lateral mixing is performed along geopotential surfaces. 1010 973 This leads to a geopotential second order operator for lateral subgrid scale physics. 1011 This assumption can be relaxed: the eddy-induced turbulent fluxes can be better approached by assuming that 974 This assumption can be relaxed: 975 the eddy-induced turbulent fluxes can be better approached by assuming that 1012 976 they depend linearly on the gradients of large-scale quantities computed along neutral surfaces. 1013 977 In such a case, the diffusive operator is an isoneutral second order operator and 1014 978 it has components in the three space directions. 1015 However, 1016 both horizontal and isoneutral operators have no effect on mean (\ielarge scale) potential energy whereas979 However, both horizontal and isoneutral operators have no effect on 980 mean (\ie\ large scale) potential energy whereas 1017 981 potential energy is a main source of turbulence (through baroclinic instabilities). 1018 \citet{ Gent1990} haveproposed a parameterisation of mesoscale eddy-induced turbulence which982 \citet{gent.mcwilliams_JPO90} proposed a parameterisation of mesoscale eddy-induced turbulence which 1019 983 associates an eddy-induced velocity to the isoneutral diffusion. 1020 984 Its mean effect is to reduce the mean potential energy of the ocean. 1021 This leads to a formulation of lateral subgrid-scale physics made up of an isoneutral second order operator and1022 an eddy induced advective part.985 This leads to a formulation of lateral subgrid-scale physics made up of 986 an isoneutral second order operator and an eddy induced advective part. 1023 987 In all these lateral diffusive formulations, 1024 988 the specification of the lateral eddy coefficients remains the problematic point as 1025 there is no really satisfactory formulation of these coefficients as a function of large-scale features. 989 there is no really satisfactory formulation of these coefficients as 990 a function of large-scale features. 1026 991 1027 992 In eddy-resolving configurations, a second order operator can be used, … … 1032 997 not interfering with the resolved mesoscale activity. 1033 998 Another approach is becoming more and more popular: 1034 instead of specifying explicitly a sub-grid scale term in the momentum and tracer time evolution equations, 1035 one uses a advective scheme which is diffusive enough to maintain the model stability. 1036 It must be emphasised that then, all the sub-grid scale physics is included in the formulation of 1037 the advection scheme. 999 instead of specifying explicitly a sub-grid scale term in 1000 the momentum and tracer time evolution equations, 1001 one uses an advective scheme which is diffusive enough to maintain the model stability. 1002 It must be emphasised that then, 1003 all the sub-grid scale physics is included in the formulation of the advection scheme. 1038 1004 1039 1005 All these parameterisations of subgrid scale physics have advantages and drawbacks. 1040 There are not all available in \NEMO. For active tracers (temperature and salinity) the main ones are: 1006 They are not all available in \NEMO. 1007 For active tracers (temperature and salinity) the main ones are: 1041 1008 Laplacian and bilaplacian operators acting along geopotential or iso-neutral surfaces, 1042 \citet{Gent1990} parameterisation, and various slightly diffusive advection schemes. 1043 For momentum, the main ones are: Laplacian and bilaplacian operators acting along geopotential surfaces, 1009 \citet{gent.mcwilliams_JPO90} parameterisation, and various slightly diffusive advection schemes. 1010 For momentum, the main ones are: 1011 Laplacian and bilaplacian operators acting along geopotential surfaces, 1044 1012 and UBS advection schemes when flux form is chosen for the momentum advection. 1045 1013 1014 %% ================================================================================================= 1046 1015 \subsubsection{Lateral laplacian tracer diffusive operator} 1047 1016 1048 The lateral Laplacian tracer diffusive operator is defined by (see \autoref{apdx: B}):1017 The lateral Laplacian tracer diffusive operator is defined by (see \autoref{apdx:DIFFOPERS}): 1049 1018 \begin{equation} 1050 \label{eq:PE_iso_tensor} 1051 D^{lT} = \nabla \vect . \lt( A^{lT} \; \Re \; \nabla T \rt) \quad \text{with} \quad 1052 \Re = 1053 \begin{pmatrix} 1054 1 & 0 & -r_1 \\ 1055 0 & 1 & -r_2 \\ 1056 -r_1 & -r_2 & r_1^2 + r_2^2 \\ 1057 \end{pmatrix} 1019 \label{eq:MB_iso_tensor} 1020 D^{lT} = \nabla \vect . \lt( A^{lT} \; \Re \; \nabla T \rt) \quad \text{with} \quad \Re = 1021 \begin{pmatrix} 1022 1 & 0 & -r_1 \\ 1023 0 & 1 & -r_2 \\ 1024 -r_1 & -r_2 & r_1^2 + r_2^2 \\ 1025 \end{pmatrix} 1058 1026 \end{equation} 1059 1027 where $r_1$ and $r_2$ are the slopes between the surface along which the diffusive operator acts and 1060 the model level (\eg $z$- or $s$-surfaces).1061 Note that the formulation \autoref{eq: PE_iso_tensor} is exact for1028 the model level (\eg\ $z$- or $s$-surfaces). 1029 Note that the formulation \autoref{eq:MB_iso_tensor} is exact for 1062 1030 the rotation between geopotential and $s$-surfaces, 1063 1031 while it is only an approximation for the rotation between isoneutral and $z$- or $s$-surfaces. 1064 Indeed, in the latter case, two assumptions are made to simplify \autoref{eq:PE_iso_tensor} \citep{Cox1987}. 1065 First, the horizontal contribution of the dianeutral mixing is neglected since the ratio between iso and 1066 dia-neutral diffusive coefficients is known to be several orders of magnitude smaller than unity. 1032 Indeed, in the latter case, two assumptions are made to simplify \autoref{eq:MB_iso_tensor} 1033 \citep{cox_OM87}. 1034 First, the horizontal contribution of the dianeutral mixing is neglected since 1035 the ratio between iso and dia-neutral diffusive coefficients is known to be 1036 several orders of magnitude smaller than unity. 1067 1037 Second, the two isoneutral directions of diffusion are assumed to be independent since 1068 the slopes are generally less than $10^{-2}$ in the ocean (see \autoref{apdx: B}).1038 the slopes are generally less than $10^{-2}$ in the ocean (see \autoref{apdx:DIFFOPERS}). 1069 1039 1070 1040 For \textit{iso-level} diffusion, $r_1$ and $r_2 $ are zero. … … 1073 1043 For \textit{geopotential} diffusion, 1074 1044 $r_1$ and $r_2 $ are the slopes between the geopotential and computational surfaces: 1075 they are equal to $\sigma_1$ and $\sigma_2$, respectively (see \autoref{eq:PE_sco_slope}). 1076 1077 For \textit{isoneutral} diffusion $r_1$ and $r_2$ are the slopes between the isoneutral and computational surfaces. 1045 they are equal to $\sigma_1$ and $\sigma_2$, respectively (see \autoref{eq:MB_sco_slope}). 1046 1047 For \textit{isoneutral} diffusion $r_1$ and $r_2$ are the slopes between 1048 the isoneutral and computational surfaces. 1078 1049 Therefore, they are different quantities, but have similar expressions in $z$- and $s$-coordinates. 1079 1050 In $z$-coordinates: 1080 1051 \begin{equation} 1081 \label{eq: PE_iso_slopes}1082 r_1 = \frac{e_3}{e_1} 1083 r_2 = \frac{e_3}{e_2} 1052 \label{eq:MB_iso_slopes} 1053 r_1 = \frac{e_3}{e_1} \lt( \pd[\rho]{i} \rt) \lt( \pd[\rho]{k} \rt)^{-1} \quad 1054 r_2 = \frac{e_3}{e_2} \lt( \pd[\rho]{j} \rt) \lt( \pd[\rho]{k} \rt)^{-1} 1084 1055 \end{equation} 1085 1056 while in $s$-coordinates $\pd[]{k}$ is replaced by $\pd[]{s}$. 1086 1057 1058 %% ================================================================================================= 1087 1059 \subsubsection{Eddy induced velocity} 1088 1060 1089 When the \textit{eddy induced velocity} parametrisation (eiv) \citep{ Gent1990} is used,1061 When the \textit{eddy induced velocity} parametrisation (eiv) \citep{gent.mcwilliams_JPO90} is used, 1090 1062 an additional tracer advection is introduced in combination with the isoneutral diffusion of tracers: 1091 1063 \[ 1092 % \label{eq: PE_iso+eiv}1064 % \label{eq:MB_iso+eiv} 1093 1065 D^{lT} = \nabla \cdot \lt( A^{lT} \; \Re \; \nabla T \rt) + \nabla \cdot \lt( \vect U^\ast \, T \rt) 1094 1066 \] 1095 1067 where $ \vect U^\ast = \lt( u^\ast,v^\ast,w^\ast \rt)$ is a non-divergent, 1096 1068 eddy-induced transport velocity. This velocity field is defined by: 1097 \ begin{gather}1098 % \label{eq: PE_eiv}1099 u^\ast = \frac{1}{e_3} \pd[]{k} \lt( A^{eiv} \; \tilde{r}_1 \rt) \ \1100 v^\ast = \frac{1}{e_3} \pd[]{k} \lt( A^{eiv} \; \tilde{r}_2 \rt) \ \1069 \[ 1070 % \label{eq:MB_eiv} 1071 u^\ast = \frac{1}{e_3} \pd[]{k} \lt( A^{eiv} \; \tilde{r}_1 \rt) \quad 1072 v^\ast = \frac{1}{e_3} \pd[]{k} \lt( A^{eiv} \; \tilde{r}_2 \rt) \quad 1101 1073 w^\ast = - \frac{1}{e_1 e_2} \lt[ \pd[]{i} \lt( A^{eiv} \; e_2 \, \tilde{r}_1 \rt) 1102 1074 + \pd[]{j} \lt( A^{eiv} \; e_1 \, \tilde{r}_2 \rt) \rt] 1103 \ end{gather}1075 \] 1104 1076 where $A^{eiv}$ is the eddy induced velocity coefficient 1105 1077 (or equivalently the isoneutral thickness diffusivity coefficient), 1106 and $\tilde r_1$ and $\tilde r_2$ are the slopes between isoneutral and \textit{geopotential} surfaces. 1107 Their values are thus independent of the vertical coordinate, but their expression depends on the coordinate: 1108 \begin{align} 1109 \label{eq:PE_slopes_eiv} 1078 and $\tilde r_1$ and $\tilde r_2$ are the slopes between 1079 isoneutral and \textit{geopotential} surfaces. 1080 Their values are thus independent of the vertical coordinate, 1081 but their expression depends on the coordinate: 1082 \begin{equation} 1083 \label{eq:MB_slopes_eiv} 1110 1084 \tilde{r}_n = 1111 1085 \begin{cases} … … 1114 1088 \end{cases} 1115 1089 \quad \text{where~} n = 1, 2 1116 \end{ align}1090 \end{equation} 1117 1091 1118 1092 The normal component of the eddy induced velocity is zero at all the boundaries. 1119 This can be achieved in a model by tapering either the eddy coefficient or the slopes to zero in the vicinity of 1120 the boundaries. 1121 The latter strategy is used in \NEMO (cf. \autoref{chap:LDF}). 1122 1093 This can be achieved in a model by tapering either the eddy coefficient or the slopes to zero in 1094 the vicinity of the boundaries. 1095 The latter strategy is used in \NEMO\ (cf. \autoref{chap:LDF}). 1096 1097 %% ================================================================================================= 1123 1098 \subsubsection{Lateral bilaplacian tracer diffusive operator} 1124 1099 1125 1100 The lateral bilaplacian tracer diffusive operator is defined by: 1126 1101 \[ 1127 % \label{eq: PE_bilapT}1102 % \label{eq:MB_bilapT} 1128 1103 D^{lT}= - \Delta \; (\Delta T) \quad \text{where} \quad 1129 1104 \Delta \bullet = \nabla \lt( \sqrt{B^{lT}} \; \Re \; \nabla \bullet \rt) 1130 1105 \] 1131 It is the Laplacian operator given by \autoref{eq: PE_iso_tensor} applied twice with1106 It is the Laplacian operator given by \autoref{eq:MB_iso_tensor} applied twice with 1132 1107 the harmonic eddy diffusion coefficient set to the square root of the biharmonic one. 1133 1108 1109 %% ================================================================================================= 1134 1110 \subsubsection{Lateral Laplacian momentum diffusive operator} 1135 1111 1136 1112 The Laplacian momentum diffusive operator along $z$- or $s$-surfaces is found by 1137 applying \autoref{eq: PE_lap_vector} to the horizontal velocity vector (see \autoref{apdx:B}):1113 applying \autoref{eq:MB_lap_vector} to the horizontal velocity vector (see \autoref{apdx:DIFFOPERS}): 1138 1114 \begin{align*} 1139 % \label{eq: PE_lapU}1115 % \label{eq:MB_lapU} 1140 1116 \vect D^{l \vect U} &= \nabla_h \big( A^{lm} \chi \big) 1141 1117 - \nabla_h \times \big( A^{lm} \, \zeta \; \vect k \big) \\ 1142 1118 &= \lt( \frac{1}{e_1} \pd[ \lt( A^{lm} \chi \rt) ]{i} \rt. 1143 - \frac{1}{e_2 e_3} \pd[ \lt( A^{lm} \; e_3 \zeta \rt) ]{j} 1119 - \frac{1}{e_2 e_3} \pd[ \lt( A^{lm} \; e_3 \zeta \rt) ]{j} , 1144 1120 \frac{1}{e_2} \pd[ \lt( A^{lm} \chi \rt) ]{j} 1145 1121 \lt. + \frac{1}{e_1 e_3} \pd[ \lt( A^{lm} \; e_3 \zeta \rt) ]{i} \rt) 1146 1122 \end{align*} 1147 1123 1148 Such a formulation ensures a complete separation between the vorticity and horizontal divergence fields1149 (see \autoref{apdx:C}).1124 Such a formulation ensures a complete separation between 1125 the vorticity and horizontal divergence fields (see \autoref{apdx:INVARIANTS}). 1150 1126 Unfortunately, it is only available in \textit{iso-level} direction. 1151 1127 When a rotation is required 1152 (\ie geopotential diffusion in $s$-coordinates or isoneutral diffusion in both $z$- and $s$-coordinates), 1153 the $u$ and $v$-fields are considered as independent scalar fields, so that the diffusive operator is given by: 1154 \begin{gather*} 1155 % \label{eq:PE_lapU_iso} 1156 D_u^{l \vect U} = \nabla . \lt( A^{lm} \; \Re \; \nabla u \rt) \\ 1128 (\ie\ geopotential diffusion in $s$-coordinates or 1129 isoneutral diffusion in both $z$- and $s$-coordinates), 1130 the $u$ and $v$-fields are considered as independent scalar fields, 1131 so that the diffusive operator is given by: 1132 \[ 1133 % \label{eq:MB_lapU_iso} 1134 D_u^{l \vect U} = \nabla . \lt( A^{lm} \; \Re \; \nabla u \rt) \quad 1157 1135 D_v^{l \vect U} = \nabla . \lt( A^{lm} \; \Re \; \nabla v \rt) 1158 \ end{gather*}1159 where $\Re$ is given by \autoref{eq: PE_iso_tensor}.1136 \] 1137 where $\Re$ is given by \autoref{eq:MB_iso_tensor}. 1160 1138 It is the same expression as those used for diffusive operator on tracers. 1161 1139 It must be emphasised that such a formulation is only exact in a Cartesian coordinate system, 1162 \ie on a $f$- or $\beta$-plane, not on the sphere.1140 \ie\ on a $f$- or $\beta$-plane, not on the sphere. 1163 1141 It is also a very good approximation in vicinity of the Equator in 1164 a geographical coordinate system \citep{Lengaigne_al_JGR03}. 1165 1166 \subsubsection{lateral bilaplacian momentum diffusive operator} 1167 1168 As for tracers, the bilaplacian order momentum diffusive operator is a re-entering Laplacian operator with 1142 a geographical coordinate system \citep{lengaigne.madec.ea_JGR03}. 1143 1144 %% ================================================================================================= 1145 \subsubsection{Lateral bilaplacian momentum diffusive operator} 1146 1147 As for tracers, 1148 the bilaplacian order momentum diffusive operator is a re-entering Laplacian operator with 1169 1149 the harmonic eddy diffusion coefficient set to the square root of the biharmonic one. 1170 1150 Nevertheless it is currently not available in the iso-neutral case. 1171 1151 1172 \biblio 1173 1174 \pindex 1152 \subinc{\input{../../global/epilogue}} 1175 1153 1176 1154 \end{document} -
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_model_basics_zstar.tex
r10544 r11831 2 2 3 3 \begin{document} 4 % ================================================================ 5 % Chapter 1 Model Basics 6 % ================================================================ 7 % ================================================================ 8 % Curvilinear \zstar- \sstar-coordinate System 9 % ================================================================ 4 10 5 \chapter{ essai \zstar \sstar} 6 7 \thispagestyle{plain} 8 9 \chaptertoc 10 11 \paragraph{Changes record} ~\\ 12 13 {\footnotesize 14 \begin{tabularx}{\textwidth}{l||X|X} 15 Release & Author(s) & Modifications \\ 16 \hline 17 {\em 4.0} & {\em ...} & {\em ...} \\ 18 {\em 3.6} & {\em ...} & {\em ...} \\ 19 {\em 3.4} & {\em ...} & {\em ...} \\ 20 {\em <=3.4} & {\em ...} & {\em ...} 21 \end{tabularx} 22 } 23 24 \clearpage 25 26 %% ================================================================================================= 11 27 \section{Curvilinear \zstar- or \sstar coordinate system} 12 28 13 % -------------------------------------------------------------------------------------------------------------14 % ????15 % -------------------------------------------------------------------------------------------------------------16 17 29 \colorbox{yellow}{ to be updated } 18 30 19 31 In that case, the free surface equation is nonlinear, and the variations of volume are fully taken into account. 20 These coordinates systems is presented in a report \citep{ Levier2007} available on the \NEMO web site.32 These coordinates systems is presented in a report \citep{levier.treguier.ea_rpt07} available on the \NEMO\ web site. 21 33 22 34 \colorbox{yellow}{ end of to be updated} … … 24 36 % from MOM4p1 documentation 25 37 26 To overcome problems with vanishing surface and/or bottom cells, we consider the zstar coordinate 27 \[ 28 % \label{eq: PE_}38 To overcome problems with vanishing surface and/or bottom cells, we consider the zstar coordinate 39 \[ 40 % \label{eq:MBZ_PE_} 29 41 z^\star = H \left( \frac{z-\eta}{H+\eta} \right) 30 42 \] … … 40 52 the surface height, it is clear that surfaces constant $z^\star$ are very similar to the depth surfaces. 41 53 These properties greatly reduce difficulties of computing the horizontal pressure gradient relative to 42 terrain following sigma models discussed in \autoref{subsec: PE_sco}.54 terrain following sigma models discussed in \autoref{subsec:MB_sco}. 43 55 Additionally, since $z^\star$ when $\eta = 0$, no flow is spontaneously generated in 44 56 an unforced ocean starting from rest, regardless the bottom topography. … … 49 61 neutral physics parameterizations in $z^\star$ models using the same techniques as in $z$-models 50 62 (see Chapters 13-16 of Griffies (2004) for a discussion of neutral physics in $z$-models, 51 as well as \autoref{sec:LDF_slp} in this document for treatment in \NEMO). 63 as well as \autoref{sec:LDF_slp} in this document for treatment in \NEMO). 52 64 53 65 The range over which $z^\star$ varies is time independent $-H \leq z^\star \leq 0$. 54 66 Hence, all cells remain nonvanishing, so long as the surface height maintains $\eta > ?H$. 55 This is a minor constraint relative to that encountered on the surface height when using $s = z$ or $s = z - \eta$. 67 This is a minor constraint relative to that encountered on the surface height when using $s = z$ or $s = z - \eta$. 56 68 57 69 Because $z^\star$ has a time independent range, all grid cells have static increments ds, 58 and the sum of the ver tical increments yields the time independent ocean depth %�k ds = H. 70 and the sum of the ver tical increments yields the time independent ocean depth %�k ds = H. 59 71 The $z^\star$ coordinate is therefore invisible to undulations of the free surface, 60 72 since it moves along with the free surface. … … 64 76 Quite generally, the time independent range for the $z^\star$ coordinate is a very convenient property that 65 77 allows for a nearly arbitrary vertical resolution even in the presence of large amplitude fluctuations of 66 the surface height, again so long as $\eta > -H$. 67 68 %%% 78 the surface height, again so long as $\eta > -H$. 79 69 80 % essai update time splitting... 70 %%% 71 72 % ================================================================ 73 % Surface Pressure Gradient and Sea Surface Height 74 % ================================================================ 75 \section{Surface pressure gradient and sea surface heigth (\protect\mdl{dynspg})} 76 \label{sec:DYN_hpg_spg} 77 %-----------------------------------------nam_dynspg---------------------------------------------------- 78 79 %\nlst{nam_dynspg} 80 %------------------------------------------------------------------------------------------------------------ 81 Options are defined through the \ngn{nam\_dynspg} namelist variables. 82 The surface pressure gradient term is related to the representation of the free surface (\autoref{sec:PE_hor_pg}). 81 82 %% ================================================================================================= 83 \section[Surface pressure gradient and sea surface heigth (\textit{dynspg.F90})]{Surface pressure gradient and sea surface heigth (\protect\mdl{dynspg})} 84 \label{sec:MBZ_dyn_hpg_spg} 85 86 %\nlst{nam_dynspg} 87 Options are defined through the \nam{_dynspg}{\_dynspg} namelist variables. 88 The surface pressure gradient term is related to the representation of the free surface (\autoref{sec:MB_hor_pg}). 83 89 The main distinction is between the fixed volume case (linear free surface or rigid lid) and 84 90 the variable volume case (nonlinear free surface, \key{vvl} is active). 85 In the linear free surface case (\autoref{subsec: PE_free_surface}) and rigid lid (\autoref{PE_rigid_lid}),91 In the linear free surface case (\autoref{subsec:MB_free_surface}) and rigid lid (\autoref{PE_rigid_lid}), 86 92 the vertical scale factors $e_{3}$ are fixed in time, 87 while in the nonlinear case (\autoref{subsec: PE_free_surface}) they are time-dependent.93 while in the nonlinear case (\autoref{subsec:MB_free_surface}) they are time-dependent. 88 94 With both linear and nonlinear free surface, external gravity waves are allowed in the equations, 89 95 which imposes a very small time step when an explicit time stepping is used. 90 96 Two methods are proposed to allow a longer time step for the three-dimensional equations: 91 the filtered free surface, which is a modification of the continuous equations %(see \autoref{eq: PE_flt}),97 the filtered free surface, which is a modification of the continuous equations %(see \autoref{eq:MB_flt?}), 92 98 and the split-explicit free surface described below. 93 99 The extra term introduced in the filtered method is calculated implicitly, 94 100 so that the update of the next velocities is done in module \mdl{dynspg\_flt} and not in \mdl{dynnxt}. 95 101 96 %-------------------------------------------------------------97 102 % Explicit 98 % -------------------------------------------------------------99 \subsubsection {Explicit (\protect\key{dynspg\_exp})}100 \label{subsec: DYN_spg_exp}103 %% ================================================================================================= 104 \subsubsection[Explicit (\texttt{\textbf{key\_dynspg\_exp}})]{Explicit (\protect\key{dynspg\_exp})} 105 \label{subsec:MBZ_dyn_spg_exp} 101 106 102 107 In the explicit free surface formulation, the model time step is chosen small enough to … … 104 109 The sea surface height is given by: 105 110 \begin{equation} 106 \label{eq: dynspg_ssh}111 \label{eq:MBZ_dynspg_ssh} 107 112 \frac{\partial \eta }{\partial t}\equiv \frac{\text{EMP}}{\rho_w }+\frac{1}{e_{1T} 108 113 e_{2T} }\sum\limits_k {\left( {\delta_i \left[ {e_{2u} e_{3u} u} … … 114 119 and $\rho_w =1,000\,Kg.m^{-3}$ is the volumic mass of pure water. 115 120 The sea-surface height is evaluated using a leapfrog scheme in combination with an Asselin time filter, 116 (\ie the velocity appearing in (\autoref{eq:dynspg_ssh}) is centred in time (\textit{now} velocity).121 (\ie\ the velocity appearing in (\autoref{eq:DYN_spg_ssh}) is centred in time (\textit{now} velocity). 117 122 118 123 The surface pressure gradient, also evaluated using a leap-frog scheme, is then simply given by: 119 124 \begin{equation} 120 \label{eq: dynspg_exp}125 \label{eq:MBZ_dynspg_exp} 121 126 \left\{ 122 127 \begin{aligned} … … 125 130 \end{aligned} 126 131 \right. 127 \end{equation} 132 \end{equation} 128 133 129 134 Consistent with the linearization, a $\left. \rho \right|_{k=1} / \rho_o$ factor is omitted in 130 (\autoref{eq:dynspg_exp}). 131 132 %------------------------------------------------------------- 135 (\autoref{eq:DYN_spg_exp}). 136 133 137 % Split-explicit time-stepping 134 %------------------------------------------------------------- 135 \subsubsection{Split-explicit time-stepping (\protect\key{dynspg\_ts})} 136 \label{subsec:DYN_spg_ts} 137 %--------------------------------------------namdom---------------------------------------------------- 138 139 \nlst{namdom} 140 %-------------------------------------------------------------------------------------------------------------- 141 The split-explicit free surface formulation used in OPA follows the one proposed by \citet{Griffies2004}. 138 %% ================================================================================================= 139 \subsubsection[Split-explicit time-stepping (\texttt{\textbf{key\_dynspg\_ts}})]{Split-explicit time-stepping (\protect\key{dynspg\_ts})} 140 \label{subsec:MBZ_dyn_spg_ts} 141 142 The split-explicit free surface formulation used in OPA follows the one proposed by \citet{Griffies2004?}. 142 143 The general idea is to solve the free surface equation with a small time step, 143 144 while the three dimensional prognostic variables are solved with a longer time step that 144 is a multiple of \np{rdtbt} in the \ngn{namdom} namelist (Figure III.3). 145 146 %> > > > > > > > > > > > > > > > > > > > > > > > > > > > 145 is a multiple of \np{rdtbt}{rdtbt} in the \nam{dom}{dom} namelist (Figure III.3). 146 147 147 \begin{figure}[!t] 148 \ begin{center}149 \includegraphics[width=0.90\textwidth]{Fig_DYN_dynspg_ts}150 \caption{151 \protect\label{fig:DYN_dynspg_ts}152 153 after \citet{Griffies2004}.154 155 156 157 158 159 160 161 162 163 164 165 A baroclinic leap-frog time step carries the surface height to $t+\Delta t$ using the convergence of166 the time averaged vertically integrated velocity taken from baroclinic time step t.167 }168 \ end{center}148 \centering 149 %\includegraphics[width=0.66\textwidth]{MBZ_DYN_dynspg_ts} 150 \caption[Schematic of the split-explicit time stepping scheme for 151 the barotropic and baroclinic modes, after \citet{Griffies2004?}]{ 152 Schematic of the split-explicit time stepping scheme for the barotropic and baroclinic modes, 153 after \citet{Griffies2004?}. 154 Time increases to the right. 155 Baroclinic time steps are denoted by $t-\Delta t$, $t, t+\Delta t$, and $t+2\Delta t$. 156 The curved line represents a leap-frog time step, 157 and the smaller barotropic time steps $N \Delta t=2\Delta t$ are denoted by the zig-zag line. 158 The vertically integrated forcing \textbf{M}(t) computed at 159 baroclinic time step t represents the interaction between the barotropic and baroclinic motions. 160 While keeping the total depth, tracer, and freshwater forcing fields fixed, 161 a leap-frog integration carries the surface height and vertically integrated velocity from 162 t to $t+2 \Delta t$ using N barotropic time steps of length $\Delta t$. 163 Time averaging the barotropic fields over the N+1 time steps (endpoints included) 164 centers the vertically integrated velocity at the baroclinic timestep $t+\Delta t$. 165 A baroclinic leap-frog time step carries the surface height to $t+\Delta t$ using 166 the convergence of the time averaged vertically integrated velocity taken from 167 baroclinic time step t.} 168 \label{fig:MBZ_dyn_dynspg_ts} 169 169 \end{figure} 170 %> > > > > > > > > > > > > > > > > > > > > > > > > > > >171 170 172 171 The split-explicit formulation has a damping effect on external gravity waves, 173 which is weaker than the filtered free surface but still significant as shown by \citet{ Levier2007} in174 the case of an analytical barotropic Kelvin wave. 172 which is weaker than the filtered free surface but still significant as shown by \citet{levier.treguier.ea_rpt07} in 173 the case of an analytical barotropic Kelvin wave. 175 174 176 175 %from griffies book: ..... copy past ! … … 183 182 We have 184 183 \[ 185 % \label{eq: DYN_spg_ts_eta}184 % \label{eq:MBZ_dyn_spg_ts_eta} 186 185 \eta^{(b)}(\tau,t_{n+1}) - \eta^{(b)}(\tau,t_{n+1}) (\tau,t_{n-1}) 187 = 2 \Delta t \left[-\nabla \cdot \textbf{U}^{(b)}(\tau,t_n) + \text{EMP}_w(\tau) \right] 186 = 2 \Delta t \left[-\nabla \cdot \textbf{U}^{(b)}(\tau,t_n) + \text{EMP}_w(\tau) \right] 188 187 \] 189 188 \begin{multline*} 190 % \label{eq: DYN_spg_ts_u}189 % \label{eq:MBZ_dyn_spg_ts_u} 191 190 \textbf{U}^{(b)}(\tau,t_{n+1}) - \textbf{U}^{(b)}(\tau,t_{n-1}) \\ 192 191 = 2\Delta t \left[ - f \textbf{k} \times \textbf{U}^{(b)}(\tau,t_{n}) … … 202 201 the freshwater flux $\text{EMP}_w(\tau)$, and total depth of the ocean $H(\tau)$ are held for 203 202 the duration of the barotropic time stepping over a single cycle. 204 This is also the time that sets the barotropic time steps via 205 \[ 206 % \label{eq: DYN_spg_ts_t}207 t_n=\tau+n\Delta t 203 This is also the time that sets the barotropic time steps via 204 \[ 205 % \label{eq:MBZ_dyn_spg_ts_t} 206 t_n=\tau+n\Delta t 208 207 \] 209 208 with $n$ an integer. 210 The density scaled surface pressure is evaluated via 211 \[ 212 % \label{eq: DYN_spg_ts_ps}209 The density scaled surface pressure is evaluated via 210 \[ 211 % \label{eq:MBZ_dyn_spg_ts_ps} 213 212 p_s^{(b)}(\tau,t_{n}) = 214 213 \begin{cases} … … 217 216 \end{cases} 218 217 \] 219 To get started, we assume the following initial conditions 220 \[ 221 % \label{eq: DYN_spg_ts_eta}218 To get started, we assume the following initial conditions 219 \[ 220 % \label{eq:MBZ_dyn_spg_ts_eta} 222 221 \begin{split} 223 222 \eta^{(b)}(\tau,t_{n=0}) &= \overline{\eta^{(b)}(\tau)} \\ … … 225 224 \end{split} 226 225 \] 227 with 228 \[ 229 % \label{eq: DYN_spg_ts_etaF}226 with 227 \[ 228 % \label{eq:MBZ_dyn_spg_ts_etaF} 230 229 \overline{\eta^{(b)}(\tau)} = \frac{1}{N+1} \sum\limits_{n=0}^N \eta^{(b)}(\tau-\Delta t,t_{n}) 231 230 \] … … 233 232 Likewise, 234 233 \[ 235 % \label{eq: DYN_spg_ts_u}234 % \label{eq:MBZ_dyn_spg_ts_u} 236 235 \textbf{U}^{(b)}(\tau,t_{n=0}) = \overline{\textbf{U}^{(b)}(\tau)} \\ \\ 237 236 \textbf{U}(\tau,t_{n=1}) = \textbf{U}^{(b)}(\tau,t_{n=0}) + \Delta t \ \text{RHS}_{n=0} 238 237 \] 239 with 240 \[ 241 % \label{eq: DYN_spg_ts_u}238 with 239 \[ 240 % \label{eq:MBZ_dyn_spg_ts_u} 242 241 \overline{\textbf{U}^{(b)}(\tau)} = \frac{1}{N+1} \sum\limits_{n=0}^N\textbf{U}^{(b)}(\tau-\Delta t,t_{n}) 243 242 \] 244 243 the time averaged vertically integrated transport. 245 Notably, there is no Robert-Asselin time filter used in the barotropic portion of the integration. 244 Notably, there is no Robert-Asselin time filter used in the barotropic portion of the integration. 246 245 247 246 Upon reaching $t_{n=N} = \tau + 2\Delta \tau$ , the vertically integrated velocity is time averaged to 248 produce the updated vertically integrated velocity at baroclinic time $\tau + \Delta \tau$ 249 \[ 250 % \label{eq: DYN_spg_ts_u}247 produce the updated vertically integrated velocity at baroclinic time $\tau + \Delta \tau$ 248 \[ 249 % \label{eq:MBZ_dyn_spg_ts_u} 251 250 \textbf{U}(\tau+\Delta t) = \overline{\textbf{U}^{(b)}(\tau+\Delta t)} 252 251 = \frac{1}{N+1} \sum\limits_{n=0}^N\textbf{U}^{(b)}(\tau,t_{n}) 253 252 \] 254 253 The surface height on the new baroclinic time step is then determined via 255 a baroclinic leap-frog using the following form 254 a baroclinic leap-frog using the following form 256 255 \begin{equation} 257 \label{eq: DYN_spg_ts_ssh}256 \label{eq:MBZ_dyn_spg_ts_ssh} 258 257 \eta(\tau+\Delta) - \eta^{F}(\tau-\Delta) = 2\Delta t \ \left[ - \nabla \cdot \textbf{U}(\tau) + \text{EMP}_w \right] 259 258 \end{equation} … … 261 260 The use of this "big-leap-frog" scheme for the surface height ensures compatibility between 262 261 the mass/volume budgets and the tracer budgets. 263 More discussion of this point is provided in Chapter 10 (see in particular Section 10.2). 264 262 More discussion of this point is provided in Chapter 10 (see in particular Section 10.2). 263 265 264 In general, some form of time filter is needed to maintain integrity of the surface height field due to 266 the leap-frog splitting mode in equation \autoref{eq: DYN_spg_ts_ssh}.265 the leap-frog splitting mode in equation \autoref{eq:MBZ_dyn_spg_ts_ssh}. 267 266 We have tried various forms of such filtering, 268 267 with the following method discussed in Griffies et al. (2001) chosen due to its stability and 269 reasonably good maintenance of tracer conservation properties (see ??) 268 reasonably good maintenance of tracer conservation properties (see ??) 270 269 271 270 \begin{equation} 272 \label{eq: DYN_spg_ts_sshf}271 \label{eq:MBZ_dyn_spg_ts_sshf} 273 272 \eta^{F}(\tau-\Delta) = \overline{\eta^{(b)}(\tau)} 274 273 \end{equation} 275 Another approach tried was 276 277 \[ 278 % \label{eq: DYN_spg_ts_sshf2}274 Another approach tried was 275 276 \[ 277 % \label{eq:MBZ_dyn_spg_ts_sshf2} 279 278 \eta^{F}(\tau-\Delta) = \eta(\tau) 280 279 + (\alpha/2) \left[\overline{\eta^{(b)}}(\tau+\Delta t) … … 285 284 This isolation allows for an easy check that tracer conservation is exact when eliminating tracer and 286 285 surface height time filtering (see ?? for more complete discussion). 287 However, in the general case with a non-zero $\alpha$, the filter \autoref{eq:DYN_spg_ts_sshf} was found to 288 be more conservative, and so is recommended. 289 290 %------------------------------------------------------------- 291 % Filtered formulation 292 %------------------------------------------------------------- 293 \subsubsection{Filtered formulation (\protect\key{dynspg\_flt})} 294 \label{subsec:DYN_spg_flt} 295 296 The filtered formulation follows the \citet{Roullet2000} implementation. 286 However, in the general case with a non-zero $\alpha$, the filter \autoref{eq:MBZ_dyn_spg_ts_sshf} was found to 287 be more conservative, and so is recommended. 288 289 % Filtered formulation 290 %% ================================================================================================= 291 \subsubsection[Filtered formulation (\texttt{\textbf{key\_dynspg\_flt}})]{Filtered formulation (\protect\key{dynspg\_flt})} 292 \label{subsec:MBZ_dyn_spg_flt} 293 294 The filtered formulation follows the \citet{Roullet2000?} implementation. 297 295 The extra term introduced in the equations (see {\S}I.2.2) is solved implicitly. 298 296 The elliptic solvers available in the code are documented in \autoref{chap:MISC}. 299 The amplitude of the extra term is given by the namelist variable \np{rnu}. 300 The default value is 1, as recommended by \citet{Roullet2000} 301 302 \colorbox{red}{\np{rnu}\forcode{ = 1} to be suppressed from namelist !} 303 304 %------------------------------------------------------------- 305 % Non-linear free surface formulation 306 %------------------------------------------------------------- 307 \subsection{Non-linear free surface formulation (\protect\key{vvl})} 308 \label{subsec:DYN_spg_vvl} 297 The amplitude of the extra term is given by the namelist variable \np{rnu}{rnu}. 298 The default value is 1, as recommended by \citet{Roullet2000?} 299 300 \colorbox{red}{\np[=1]{rnu}{rnu} to be suppressed from namelist !} 301 302 % Non-linear free surface formulation 303 %% ================================================================================================= 304 \subsection[Non-linear free surface formulation (\texttt{\textbf{key\_vvl}})]{Non-linear free surface formulation (\protect\key{vvl})} 305 \label{subsec:MBZ_dyn_spg_vvl} 309 306 310 307 In the non-linear free surface formulation, the variations of volume are fully taken into account. 311 This option is presented in a report \citep{ Levier2007} available on the NEMOweb site.308 This option is presented in a report \citep{levier.treguier.ea_rpt07} available on the \NEMO\ web site. 312 309 The three time-stepping methods (explicit, split-explicit and filtered) are the same as in 313 \autoref{ DYN_spg_linear} except that the ocean depth is now time-dependent.310 \autoref{?:DYN_spg_linear?} except that the ocean depth is now time-dependent. 314 311 In particular, this means that in filtered case, the matrix to be inverted has to be recomputed at each time-step. 315 312 316 \biblio 317 318 \pindex 313 \subinc{\input{../../global/epilogue}} 319 314 320 315 \end{document} -
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_time_domain.tex
r10501 r11831 3 3 \begin{document} 4 4 5 % ================================================================ 6 % Chapter 2 ——— Time Domain (step.F90) 7 % ================================================================ 8 \chapter{Time Domain (STP)} 9 \label{chap:STP} 10 \minitoc 5 \chapter{Time Domain} 6 \label{chap:TD} 7 8 \thispagestyle{plain} 9 10 \chaptertoc 11 12 \paragraph{Changes record} ~\\ 13 14 {\footnotesize 15 \begin{tabularx}{0.5\textwidth}{l||X|X} 16 Release & Author(s) & 17 Modifications \\ 18 \hline 19 {\em 4.0} & {\em J\'{e}r\^{o}me Chanut \newline Tim Graham} & 20 {\em Review \newline Update } \\ 21 {\em 3.6} & {\em Christian \'{E}th\'{e} } & 22 {\em Update } \\ 23 {\em $\leq$ 3.4} & {\em Gurvan Madec } & 24 {\em First version } \\ 25 \end{tabularx} 26 } 27 28 \clearpage 11 29 12 30 % Missing things: 13 % - daymod: definition of the time domain (nit000, nitend andd the calendar) 14 15 \gmcomment{STEVEN :maybe a picture of the directory structure in the introduction which could be referred to here, 16 would help ==> to be added} 17 %%%% 18 19 \newpage 20 21 Having defined the continuous equations in \autoref{chap:PE}, we need now to choose a time discretization, 31 % - daymod: definition of the time domain (nit000, nitend and the calendar) 32 33 \cmtgm{STEVEN :maybe a picture of the directory structure in the introduction which 34 could be referred to here, would help ==> to be added} 35 36 Having defined the continuous equations in \autoref{chap:MB}, 37 we need now to choose a time discretization, 22 38 a key feature of an ocean model as it exerts a strong influence on the structure of the computer code 23 (\ie on its flowchart).24 In the present chapter, we provide a general description of the \NEMO time stepping strategy and39 (\ie\ on its flowchart). 40 In the present chapter, we provide a general description of the \NEMO\ time stepping strategy and 25 41 the consequences for the order in which the equations are solved. 26 42 27 % ================================================================ 28 % Time Discretisation 29 % ================================================================ 43 %% ================================================================================================= 30 44 \section{Time stepping environment} 31 \label{sec: STP_environment}32 33 The time stepping used in \NEMO is a three level scheme that can be represented as follows:45 \label{sec:TD_environment} 46 47 The time stepping used in \NEMO\ is a three level scheme that can be represented as follows: 34 48 \begin{equation} 35 \label{eq: STP}49 \label{eq:TD} 36 50 x^{t + \rdt} = x^{t - \rdt} + 2 \, \rdt \ \text{RHS}_x^{t - \rdt, \, t, \, t + \rdt} 37 \end{equation} 51 \end{equation} 38 52 where $x$ stands for $u$, $v$, $T$ or $S$; 39 RHS is the Right-Hand-Side of the corresponding time evolution equation;53 RHS is the \textbf{R}ight-\textbf{H}and-\textbf{S}ide of the corresponding time evolution equation; 40 54 $\rdt$ is the time step; 41 55 and the superscripts indicate the time at which a quantity is evaluated. 42 Each term of the RHS is evaluated at a specific time step depending on the physics with which it is associated. 43 44 The choice of the time step used for this evaluation is discussed below as well as 56 Each term of the RHS is evaluated at a specific time stepping depending on 57 the physics with which it is associated. 58 59 The choice of the time stepping used for this evaluation is discussed below as well as 45 60 the implications for starting or restarting a model simulation. 46 61 Note that the time stepping calculation is generally performed in a single operation. 47 With such a complex and nonlinear system of equations it would be dangerous to let a prognostic variable evolve in48 time for each term separately.62 With such a complex and nonlinear system of equations it would be dangerous to 63 let a prognostic variable evolve in time for each term separately. 49 64 50 65 The three level scheme requires three arrays for each prognostic variable. … … 52 67 The third array, although referred to as $x_a$ (after) in the code, 53 68 is usually not the variable at the after time step; 54 but rather it is used to store the time derivative (RHS in \autoref{eq:STP}) prior to time-stepping the equation. 55 Generally, the time stepping is performed once at each time step in the \mdl{tranxt} and \mdl{dynnxt} modules, 56 except when using implicit vertical diffusion or calculating sea surface height in which 57 case time-splitting options are used. 58 59 % ------------------------------------------------------------------------------------------------------------- 60 % Non-Diffusive Part---Leapfrog Scheme 61 % ------------------------------------------------------------------------------------------------------------- 69 but rather it is used to store the time derivative (RHS in \autoref{eq:TD}) 70 prior to time-stepping the equation. 71 The time stepping itself is performed once at each time step where 72 implicit vertical diffusion is computed, 73 \ie\ in the \mdl{trazdf} and \mdl{dynzdf} modules. 74 75 %% ================================================================================================= 62 76 \section{Non-diffusive part --- Leapfrog scheme} 63 \label{sec: STP_leap_frog}64 65 The time stepping used for processes other than diffusion is the well-known leapfrog scheme66 \citep{Mesinger_Arakawa_Bk76}.77 \label{sec:TD_leap_frog} 78 79 The time stepping used for processes other than diffusion is 80 the well-known \textbf{L}eap\textbf{F}rog (LF) scheme \citep{mesinger.arakawa_bk76}. 67 81 This scheme is widely used for advection processes in low-viscosity fluids. 68 It is a time centred scheme, \ie the RHS in \autoref{eq:STP} is evaluated at time step $t$, the now time step. 82 It is a time centred scheme, \ie\ the RHS in \autoref{eq:TD} is evaluated at 83 time step $t$, the now time step. 69 84 It may be used for momentum and tracer advection, pressure gradient, and Coriolis terms, 70 85 but not for diffusion terms. 71 86 It is an efficient method that achieves second-order accuracy with 72 87 just one right hand side evaluation per time step. 73 Moreover, it does not artificially damp linear oscillatory motion nor does it produce instability by74 amplifying the oscillations.88 Moreover, it does not artificially damp linear oscillatory motion 89 nor does it produce instability by amplifying the oscillations. 75 90 These advantages are somewhat diminished by the large phase-speed error of the leapfrog scheme, 76 and the unsuitability of leapfrog differencing for the representation of diffusion and Rayleigh damping processes. 91 and the unsuitability of leapfrog differencing for the representation of diffusion and 92 Rayleigh damping processes. 77 93 However, the scheme allows the coexistence of a numerical and a physical mode due to 78 94 its leading third order dispersive error. 79 95 In other words a divergence of odd and even time steps may occur. 80 To prevent it, the leapfrog scheme is often used in association with a Robert-Asselin time filter 81 (hereafter the LF-RA scheme). 82 This filter, first designed by \citet{Robert_JMSJ66} and more comprehensively studied by \citet{Asselin_MWR72}, 96 To prevent it, the leapfrog scheme is often used in association with 97 a \textbf{R}obert-\textbf{A}sselin time filter (hereafter the LF-RA scheme). 98 This filter, 99 first designed by \citet{robert_JMSJ66} and more comprehensively studied by \citet{asselin_MWR72}, 83 100 is a kind of laplacian diffusion in time that mixes odd and even time steps: 84 101 \begin{equation} 85 \label{eq: STP_asselin}102 \label{eq:TD_asselin} 86 103 x_F^t = x^t + \gamma \, \lt[ x_F^{t - \rdt} - 2 x^t + x^{t + \rdt} \rt] 87 104 \end{equation} 88 105 where the subscript $F$ denotes filtered values and $\gamma$ is the Asselin coefficient. 89 $\gamma$ is initialized as \np{rn \_atfp} (namelist parameter).90 Its default value is \np {rn\_atfp}~\forcode{= 10.e-3} (see \autoref{sec:STP_mLF}),91 causing only a weak dissipation of high frequency motions (\citep{ Farge1987}).106 $\gamma$ is initialized as \np{rn_atfp}{rn\_atfp} (namelist parameter). 107 Its default value is \np[=10.e-3]{rn_atfp}{rn\_atfp} (see \autoref{sec:TD_mLF}), 108 causing only a weak dissipation of high frequency motions (\citep{farge-coulombier_phd87}). 92 109 The addition of a time filter degrades the accuracy of the calculation from second to first order. 93 110 However, the second order truncation error is proportional to $\gamma$, which is small compared to 1. 94 111 Therefore, the LF-RA is a quasi second order accurate scheme. 95 The LF-RA scheme is preferred to other time differencing schemes such as predictor corrector or trapezoidal schemes, 96 because the user has an explicit and simple control of the magnitude of the time diffusion of the scheme. 97 When used with the 2nd order space centred discretisation of the advection terms in 112 The LF-RA scheme is preferred to other time differencing schemes such as 113 predictor corrector or trapezoidal schemes, because the user has an explicit and simple control of 114 the magnitude of the time diffusion of the scheme. 115 When used with the 2$^nd$ order space centred discretisation of the advection terms in 98 116 the momentum and tracer equations, LF-RA avoids implicit numerical diffusion: 99 diffusion is set explicitly by the user through the Robert-Asselin 100 filter parameter and the viscosity and diffusion coefficients. 101 102 % ------------------------------------------------------------------------------------------------------------- 103 % Diffusive Part---Forward or Backward Scheme 104 % ------------------------------------------------------------------------------------------------------------- 117 diffusion is set explicitly by the user through the Robert-Asselin filter parameter and 118 the viscosity and diffusion coefficients. 119 120 %% ================================================================================================= 105 121 \section{Diffusive part --- Forward or backward scheme} 106 \label{sec:STP_forward_imp} 107 108 The leapfrog differencing scheme is unsuitable for the representation of diffusion and damping processes. 109 For a tendancy $D_x$, representing a diffusion term or a restoring term to a tracer climatology 122 \label{sec:TD_forward_imp} 123 124 The leapfrog differencing scheme is unsuitable for 125 the representation of diffusion and damping processes. 126 For a tendency $D_x$, representing a diffusion term or a restoring term to a tracer climatology 110 127 (when present, see \autoref{sec:TRA_dmp}), a forward time differencing scheme is used : 111 128 \[ 112 %\label{eq: STP_euler}129 %\label{eq:TD_euler} 113 130 x^{t + \rdt} = x^{t - \rdt} + 2 \, \rdt \ D_x^{t - \rdt} 114 131 \] 115 132 116 133 This is diffusive in time and conditionally stable. 117 The conditions for stability of second and fourth order horizontal diffusion schemes are \citep{Griffies_Bk04}: 134 The conditions for stability of second and fourth order horizontal diffusion schemes are 135 \citep{griffies_bk04}: 118 136 \begin{equation} 119 \label{eq: STP_euler_stability}137 \label{eq:TD_euler_stability} 120 138 A^h < 121 139 \begin{cases} … … 124 142 \end{cases} 125 143 \end{equation} 126 where $e$ is the smallest grid size in the two horizontal directions and $A^h$ is the mixing coefficient. 127 The linear constraint \autoref{eq:STP_euler_stability} is a necessary condition, but not sufficient. 144 where $e$ is the smallest grid size in the two horizontal directions and 145 $A^h$ is the mixing coefficient. 146 The linear constraint \autoref{eq:TD_euler_stability} is a necessary condition, but not sufficient. 128 147 If it is not satisfied, even mildly, then the model soon becomes wildly unstable. 129 The instability can be removed by either reducing the length of the time steps or reducing the mixing coefficient. 148 The instability can be removed by either reducing the length of the time steps or 149 reducing the mixing coefficient. 130 150 131 151 For the vertical diffusion terms, a forward time differencing scheme can be used, 132 152 but usually the numerical stability condition imposes a strong constraint on the time step. 133 Two solutions are available in \NEMO to overcome the stability constraint: 134 $(a)$ a forward time differencing scheme using a time splitting technique (\np{ln\_zdfexp}~\forcode{= .true.}) or 135 $(b)$ a backward (or implicit) time differencing scheme (\np{ln\_zdfexp}~\forcode{= .false.}). 136 In $(a)$, the master time step $\Delta$t is cut into $N$ fractional time steps so that 137 the stability criterion is reduced by a factor of $N$. 138 The computation is performed as follows: 139 \begin{alignat*}{2} 140 % \label{eq:STP_ts} 141 &x_\ast^{t - \rdt} &= &x^{t - \rdt} \\ 142 &x_\ast^{t - \rdt + L \frac{2 \rdt}{N}} &= &x_\ast ^{t - \rdt + (L - 1) \frac{2 \rdt}{N}} 143 + \frac{2 \rdt}{N} \; DF^{t - \rdt + (L - 1) \frac{2 \rdt}{N}} 144 \quad \text{for $L = 1$ to $N$} \\ 145 &x^{t + \rdt} &= &x_\ast^{t + \rdt} 146 \end{alignat*} 147 with DF a vertical diffusion term. 148 The number of fractional time steps, $N$, is given by setting \np{nn\_zdfexp}, (namelist parameter). 149 The scheme $(b)$ is unconditionally stable but diffusive. It can be written as follows: 153 To overcome the stability constraint, a backward (or implicit) time differencing scheme is used. 154 This scheme is unconditionally stable but diffusive and can be written as follows: 150 155 \begin{equation} 151 \label{eq: STP_imp}156 \label{eq:TD_imp} 152 157 x^{t + \rdt} = x^{t - \rdt} + 2 \, \rdt \ \text{RHS}_x^{t + \rdt} 153 158 \end{equation} 154 159 155 %%gm 156 %%gm UPDATE the next paragraphs with time varying thickness ... 157 %%gm 158 159 This scheme is rather time consuming since it requires a matrix inversion, 160 but it becomes attractive since a value of 3 or more is needed for N in the forward time differencing scheme. 160 \cmtgm{UPDATE the next paragraphs with time varying thickness ...} 161 162 This scheme is rather time consuming since it requires a matrix inversion. 161 163 For example, the finite difference approximation of the temperature equation is: 162 164 \[ 163 % \label{eq: STP_imp_zdf}165 % \label{eq:TD_imp_zdf} 164 166 \frac{T(k)^{t + 1} - T(k)^{t - 1}}{2 \; \rdt} 165 167 \equiv … … 167 169 \] 168 170 where RHS is the right hand side of the equation except for the vertical diffusion term. 169 We rewrite \autoref{eq: STP_imp} as:171 We rewrite \autoref{eq:TD_imp} as: 170 172 \begin{equation} 171 \label{eq: STP_imp_mat}173 \label{eq:TD_imp_mat} 172 174 -c(k + 1) \; T^{t + 1}(k + 1) + d(k) \; T^{t + 1}(k) - \; c(k) \; T^{t + 1}(k - 1) \equiv b(k) 173 175 \end{equation} 174 where 175 \begin{align*} 176 c(k) &= A_w^{vT} (k) \, / \, e_{3w} (k) \\ 177 d(k) &= e_{3t} (k) \, / \, (2 \rdt) + c_k + c_{k + 1} \\ 178 b(k) &= e_{3t} (k) \; \lt( T^{t - 1}(k) \, / \, (2 \rdt) + \text{RHS} \rt) 179 \end{align*} 180 181 \autoref{eq:STP_imp_mat} is a linear system of equations with an associated matrix which is tridiagonal. 182 Moreover, 183 $c(k)$ and $d(k)$ are positive and the diagonal term is greater than the sum of the two extra-diagonal terms, 176 where 177 \[ 178 c(k) = A_w^{vT} (k) \, / \, e_{3w} (k) \text{,} \quad 179 d(k) = e_{3t} (k) \, / \, (2 \rdt) + c_k + c_{k + 1} \quad \text{and} \quad 180 b(k) = e_{3t} (k) \; \lt( T^{t - 1}(k) \, / \, (2 \rdt) + \text{RHS} \rt) 181 \] 182 183 \autoref{eq:TD_imp_mat} is a linear system of equations with 184 an associated matrix which is tridiagonal. 185 Moreover, $c(k)$ and $d(k)$ are positive and 186 the diagonal term is greater than the sum of the two extra-diagonal terms, 184 187 therefore a special adaptation of the Gauss elimination procedure is used to find the solution 185 (see for example \citet{Richtmyer1967}). 186 187 % ------------------------------------------------------------------------------------------------------------- 188 % Surface Pressure gradient 189 % ------------------------------------------------------------------------------------------------------------- 188 (see for example \citet{richtmyer.morton_bk67}). 189 190 %% ================================================================================================= 190 191 \section{Surface pressure gradient} 191 \label{sec:STP_spg_ts} 192 193 ===>>>> TO BE written.... :-) 194 195 %\gmcomment{ 196 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 197 \begin{figure}[!t] 198 \begin{center} 199 \includegraphics[]{Fig_TimeStepping_flowchart} 200 \caption{ 201 \protect\label{fig:TimeStep_flowchart} 202 Sketch of the leapfrog time stepping sequence in \NEMO from \citet{Leclair_Madec_OM09}. 203 The use of a semi -implicit computation of the hydrostatic pressure gradient requires the tracer equation to 204 be stepped forward prior to the momentum equation. 205 The need for knowledge of the vertical scale factor (here denoted as $h$) requires the sea surface height and 206 the continuity equation to be stepped forward prior to the computation of the tracer equation. 207 Note that the method for the evaluation of the surface pressure gradient $\nabla p_s$ is not presented here 208 (see \autoref{sec:DYN_spg}). 209 } 210 \end{center} 192 \label{sec:TD_spg_ts} 193 194 The leapfrog environment supports a centred in time computation of the surface pressure, 195 \ie\ evaluated at \textit{now} time step. 196 This refers to as the explicit free surface case in the code 197 (\np[=.true.]{ln_dynspg_exp}{ln\_dynspg\_exp}). 198 This choice however imposes a strong constraint on the time step which 199 should be small enough to resolve the propagation of external gravity waves. 200 As a matter of fact, one rather use in a realistic setup, 201 a split-explicit free surface (\np[=.true.]{ln_dynspg_ts}{ln\_dynspg\_ts}) in which 202 barotropic and baroclinic dynamical equations are solved separately with ad-hoc time steps. 203 The use of the time-splitting (in combination with non-linear free surface) imposes 204 some constraints on the design of the overall flowchart, 205 in particular to ensure exact tracer conservation (see \autoref{fig:TD_TimeStep_flowchart}). 206 207 Compared to the former use of the filtered free surface in \NEMO\ v3.6 (\citet{roullet.madec_JGR00}), 208 the use of a split-explicit free surface is advantageous on massively parallel computers. 209 Indeed, no global computations are anymore required by the elliptic solver which 210 saves a substantial amount of communication time. 211 Fast barotropic motions (such as tides) are also simulated with a better accuracy. 212 213 %\cmtgm{ 214 \begin{figure} 215 \centering 216 \includegraphics[width=0.66\textwidth]{TD_TimeStepping_flowchart_v4} 217 \caption[Leapfrog time stepping sequence with split-explicit free surface]{ 218 Sketch of the leapfrog time stepping sequence in \NEMO\ with split-explicit free surface. 219 The latter combined with non-linear free surface requires 220 the dynamical tendency being updated prior tracers tendency to ensure conservation. 221 Note the use of time integrated fluxes issued from the barotropic loop in 222 subsequent calculations of tracer advection and in the continuity equation. 223 Details about the time-splitting scheme can be found in \autoref{subsec:DYN_spg_ts}.} 224 \label{fig:TD_TimeStep_flowchart} 211 225 \end{figure} 212 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>213 226 %} 214 227 215 % ------------------------------------------------------------------------------------------------------------- 216 % The Modified Leapfrog -- Asselin Filter scheme 217 % ------------------------------------------------------------------------------------------------------------- 218 \section{Modified Leapfrog -- Asselin filter scheme} 219 \label{sec:STP_mLF} 220 221 Significant changes have been introduced by \cite{Leclair_Madec_OM09} in the LF-RA scheme in order to 222 ensure tracer conservation and to allow the use of a much smaller value of the Asselin filter parameter. 228 %% ================================================================================================= 229 \section{Modified LeapFrog -- Robert Asselin filter scheme (LF-RA)} 230 \label{sec:TD_mLF} 231 232 Significant changes have been introduced by \cite{leclair.madec_OM09} in 233 the LF-RA scheme in order to ensure tracer conservation and to 234 allow the use of a much smaller value of the Asselin filter parameter. 223 235 The modifications affect both the forcing and filtering treatments in the LF-RA scheme. 224 236 225 In a classical LF-RA environment, the forcing term is centred in time,226 \ieit is time-stepped over a $2 \rdt$ period:237 In a classical LF-RA environment, 238 the forcing term is centred in time, \ie\ it is time-stepped over a $2 \rdt$ period: 227 239 $x^t = x^t + 2 \rdt Q^t$ where $Q$ is the forcing applied to $x$, 228 and the time filter is given by \autoref{eq:STP_asselin} so that $Q$ is redistributed over several time step. 240 and the time filter is given by \autoref{eq:TD_asselin} so that 241 $Q$ is redistributed over several time step. 229 242 In the modified LF-RA environment, these two formulations have been replaced by: 230 243 \begin{gather} 231 \label{eq: STP_forcing}244 \label{eq:TD_forcing} 232 245 x^{t + \rdt} = x^{t - \rdt} + \rdt \lt( Q^{t - \rdt / 2} + Q^{t + \rdt / 2} \rt) \\ 233 \label{eq: STP_RA}246 \label{eq:TD_RA} 234 247 x_F^t = x^t + \gamma \, \lt( x_F^{t - \rdt} - 2 x^t + x^{t + \rdt} \rt) 235 248 - \gamma \, \rdt \, \lt( Q^{t + \rdt / 2} - Q^{t - \rdt / 2} \rt) 236 249 \end{gather} 237 The change in the forcing formulation given by \autoref{eq:STP_forcing} (see \autoref{fig:MLF_forcing}) 238 has a significant effect: 239 the forcing term no longer excites the divergence of odd and even time steps \citep{Leclair_Madec_OM09}. 250 The change in the forcing formulation given by \autoref{eq:TD_forcing} 251 (see \autoref{fig:TD_MLF_forcing}) has a significant effect: 252 the forcing term no longer excites the divergence of odd and even time steps 253 \citep{leclair.madec_OM09}. 240 254 % forcing seen by the model.... 241 This property improves the LF-RA scheme in two respects.255 This property improves the LF-RA scheme in two aspects. 242 256 First, the LF-RA can now ensure the local and global conservation of tracers. 243 257 Indeed, time filtering is no longer required on the forcing part. 244 The influence of the Asselin filter on the forcing is be removed by adding a new term in the filter245 (last term in \autoref{eq:STP_RA} compared to \autoref{eq:STP_asselin}).258 The influence of the Asselin filter on the forcing is explicitly removed by 259 adding a new term in the filter (last term in \autoref{eq:TD_RA} compared to \autoref{eq:TD_asselin}). 246 260 Since the filtering of the forcing was the source of non-conservation in the classical LF-RA scheme, 247 the modified formulation becomes conservative \citep{ Leclair_Madec_OM09}.248 Second, the LF-RA becomes a truly quasi 249 Indeed, \autoref{eq: STP_forcing} used in combination with a careful treatment of static instability250 (\autoref{subsec:ZDF_evd}) and of the TKE physics (\autoref{subsec:ZDF_tke_ene}) ,251 the two other main sources of time step divergence,261 the modified formulation becomes conservative \citep{leclair.madec_OM09}. 262 Second, the LF-RA becomes a truly quasi-second order scheme. 263 Indeed, \autoref{eq:TD_forcing} used in combination with a careful treatment of static instability 264 (\autoref{subsec:ZDF_evd}) and of the TKE physics (\autoref{subsec:ZDF_tke_ene}) 265 (the two other main sources of time step divergence), 252 266 allows a reduction by two orders of magnitude of the Asselin filter parameter. 253 267 254 268 Note that the forcing is now provided at the middle of a time step: 255 269 $Q^{t + \rdt / 2}$ is the forcing applied over the $[t,t + \rdt]$ time interval. 256 This and the change in the time filter, \autoref{eq: STP_RA},257 allows an exact evaluation of the contribution due to the forcing term between any two time steps,270 This and the change in the time filter, \autoref{eq:TD_RA}, 271 allows for an exact evaluation of the contribution due to the forcing term between any two time steps, 258 272 even if separated by only $\rdt$ since the time filter is no longer applied to the forcing term. 259 273 260 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 261 \begin{figure}[!t] 262 \begin{center} 263 \includegraphics[]{Fig_MLF_forcing} 264 \caption{ 265 \protect\label{fig:MLF_forcing} 266 Illustration of forcing integration methods. 267 (top) ''Traditional'' formulation: 268 the forcing is defined at the same time as the variable to which it is applied 269 (integer value of the time step index) and it is applied over a $2 \rdt$ period. 270 (bottom) modified formulation: 271 the forcing is defined in the middle of the time (integer and a half value of the time step index) and 272 the mean of two successive forcing values ($n - 1 / 2$, $n + 1 / 2$) is applied over a $2 \rdt$ period. 273 } 274 \end{center} 274 \begin{figure} 275 \centering 276 \includegraphics[width=0.66\textwidth]{TD_MLF_forcing} 277 \caption[Forcing integration methods for modified leapfrog (top and bottom)]{ 278 Illustration of forcing integration methods. 279 (top) ''Traditional'' formulation: 280 the forcing is defined at the same time as the variable to which it is applied 281 (integer value of the time step index) and it is applied over a $2 \rdt$ period. 282 (bottom) modified formulation: 283 the forcing is defined in the middle of the time 284 (integer and a half value of the time step index) and 285 the mean of two successive forcing values ($n - 1 / 2$, $n + 1 / 2$) is applied over 286 a $2 \rdt$ period.} 287 \label{fig:TD_MLF_forcing} 275 288 \end{figure} 276 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 277 278 % ------------------------------------------------------------------------------------------------------------- 279 % Start/Restart strategy 280 % ------------------------------------------------------------------------------------------------------------- 289 290 %% ================================================================================================= 281 291 \section{Start/Restart strategy} 282 \label{sec:STP_rst} 283 284 %--------------------------------------------namrun------------------------------------------- 285 \nlst{namrun} 286 %-------------------------------------------------------------------------------------------------------------- 287 288 The first time step of this three level scheme when starting from initial conditions is a forward step 289 (Euler time integration): 292 \label{sec:TD_rst} 293 294 \begin{listing} 295 \nlst{namrun} 296 \caption{\forcode{&namrun}} 297 \label{lst:namrun} 298 \end{listing} 299 300 The first time step of this three level scheme when starting from initial conditions is 301 a forward step (Euler time integration): 290 302 \[ 291 % \label{eq: DOM_euler}303 % \label{eq:TD_DOM_euler} 292 304 x^1 = x^0 + \rdt \ \text{RHS}^0 293 305 \] 294 This is done simply by keeping the leapfrog environment (\ie the \autoref{eq:STP} three level time stepping) but 306 This is done simply by keeping the leapfrog environment 307 (\ie\ the \autoref{eq:TD} three level time stepping) but 295 308 setting all $x^0$ (\textit{before}) and $x^1$ (\textit{now}) fields equal at the first time step and 296 using half the value of $\rdt$.309 using half the value of a leapfrog time step ($2 \rdt$). 297 310 298 311 It is also possible to restart from a previous computation, by using a restart file. … … 301 314 running the model for $2N$ time steps in one go, 302 315 or by performing two consecutive experiments of $N$ steps with a restart. 303 This requires saving two time levels and many auxiliary data in the restart files in machine precision. 304 305 Note that when a semi -implicit scheme is used to evaluate the hydrostatic pressure gradient 306 (see \autoref{subsec:DYN_hpg_imp}), an extra three-dimensional field has to 307 be added to the restart file to ensure an exact restartability. 308 This is done optionally via the \np{nn\_dynhpg\_rst} namelist parameter, 309 so that the size of the restart file can be reduced when restartability is not a key issue 310 (operational oceanography or in ensemble simulations for seasonal forecasting). 311 312 Note the size of the time step used, $\rdt$, is also saved in the restart file. 313 When restarting, if the the time step has been changed, a restart using an Euler time stepping scheme is imposed. 314 Options are defined through the \ngn{namrun} namelist variables. 315 %%% 316 \gmcomment{ 316 This requires saving two time levels and many auxiliary data in 317 the restart files in machine precision. 318 319 Note that the time step $\rdt$, is also saved in the restart file. 320 When restarting, if the time step has been changed, or 321 one of the prognostic variables at \textit{before} time step is missing, 322 an Euler time stepping scheme is imposed. 323 A forward initial step can still be enforced by the user by 324 setting the namelist variable \np[=0]{nn_euler}{nn\_euler}. 325 Other options to control the time integration of the model are defined through 326 the \nam{run}{run} namelist variables. 327 328 \cmtgm{ 317 329 add here how to force the restart to contain only one time step for operational purposes 318 330 319 331 add also the idea of writing several restart for seasonal forecast : how is it done ? 320 332 321 verify that all namelist para rmeters are truly described333 verify that all namelist parameters are truly described 322 334 323 335 a word on the check of restart ..... 324 336 } 325 %%% 326 327 \gmcomment{ % add a subsection here 328 329 %------------------------------------------------------------------------------------------------------------- 330 % Time Domain 331 % ------------------------------------------------------------------------------------------------------------- 337 338 \cmtgm{ % add a subsection here 339 340 %% ================================================================================================= 332 341 \subsection{Time domain} 333 \label{subsec:STP_time} 334 %--------------------------------------------namrun------------------------------------------- 335 336 \nlst{namdom} 337 %-------------------------------------------------------------------------------------------------------------- 338 339 Options are defined through the \ngn{namdom} namelist variables. 342 \label{subsec:TD_time} 343 344 Options are defined through the\nam{dom}{dom} namelist variables. 340 345 \colorbox{yellow}{add here a few word on nit000 and nitend} 341 346 342 347 \colorbox{yellow}{Write documentation on the calendar and the key variable adatrj} 343 348 344 add a description of daymod, and the model calandar (leap-year and co) 345 346 } %% end add 347 348 349 350 %% 351 \gmcomment{ % add implicit in vvl case and Crant-Nicholson scheme 349 add a description of daymod, and the model calendar (leap-year and co) 350 351 } %% end add 352 353 \cmtgm{ % add implicit in vvl case and Crant-Nicholson scheme 352 354 353 355 Implicit time stepping in case of variable volume thickness. … … 398 400 \end{flalign*} 399 401 400 %%401 402 } 402 403 403 \biblio 404 405 \pindex 404 \subinc{\input{../../global/epilogue}} 406 405 407 406 \end{document}
Note: See TracChangeset
for help on using the changeset viewer.