- Timestamp:
- 2019-12-10T15:03:24+01:00 (4 years ago)
- Location:
- NEMO/branches/2019/ENHANCE-03_closea/doc
- Files:
-
- 8 deleted
- 21 edited
- 12 copied
Legend:
- Unmodified
- Added
- Removed
-
NEMO/branches/2019/ENHANCE-03_closea/doc
-
Property
svn:externals
set to
^/utils/badges badges
^/utils/logos logos
-
Property
svn:externals
set to
-
NEMO/branches/2019/ENHANCE-03_closea/doc/latex
- Property svn:ignore deleted
-
NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO
-
Property
svn:externals
set to
^/utils/figures/NEMO figures
-
Property
svn:externals
set to
-
NEMO/branches/2019/ENHANCE-03_closea/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/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_ASM.tex
r11151 r12149 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} … … 39 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 57 With IAU, the model state trajectory ${\mathbf x}$ in the assimilation window ($t_{0} \leq t_{i} \leq t_{N}$) … … 45 59 additional tendency terms to the prognostic equations: 46 60 \begin{align*} 47 % \label{eq: wa_traj_iau}61 % \label{eq:ASM_wa_traj_iau} 48 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*} … … 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\{ … … 66 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\{ … … 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 … … 120 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/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_DIA.tex
r11179 r12149 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 {\ttfamily using\_server} setting determines whether or not the server will be used in \textit{attached mode} 171 (as a library) [{\ttfamily> false <}] or in \textit{detached mode} 172 (as an external executable on N additional, dedicated cpus) [{\ttfamily > 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 {\ttfamily 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 ("\ttfamily{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 ("\ttfamily{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 ("\ttfamily{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 ("\ttfamily{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 ("\ttfamily{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 ("\ttfamily{*\_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 ("\ttfamily{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 (\texttt{\textbf{key\_netcdf4}})] 1335 {NetCDF4 support (\protect\key{netcdf4})} 1327 %% ================================================================================================= 1328 \section[NetCDF4 support (\texttt{\textbf{key\_netcdf4}})]{NetCDF4 support (\protect\key{netcdf4})} 1336 1329 \label{sec:DIA_nc4} 1337 1330 … … 1341 1334 Chunking and compression can lead to significant reductions in file sizes for a small runtime overhead. 1342 1335 For a fuller discussion on chunking and other performance issues the reader is referred to 1343 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}. 1344 1337 1345 1338 The new features are only available when the code has been linked with a NetCDF4 library … … 1347 1340 Datasets created with chunking and compression are not backwards compatible with NetCDF3 "classic" format but 1348 1341 most analysis codes can be relinked simply with the new libraries and will then read both NetCDF3 and NetCDF4 files. 1349 NEMO executables linked with NetCDF4 libraries can be made to produce NetCDF3 files by 1350 setting the \np{ln\_nc4zip} logical to false in the \textit{namnc4} namelist: 1351 1352 %------------------------------------------namnc4---------------------------------------------------- 1353 1354 \nlst{namnc4} 1355 %------------------------------------------------------------------------------------------------------------- 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} 1356 1350 1357 1351 If \key{netcdf4} has not been defined, these namelist parameters are not read. 1358 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. 1359 1353 These functions will not be used but need to be included so that compilation is possible with NetCDF3 libraries. 1360 1354 … … 1390 1384 \end{forlines} 1391 1385 1392 \noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\t tfamily46x38x1} respectively in1393 the mono-processor case (\ie global domain of {\small\ttfamily182x149x31}).1394 An illustration of the potential space savings that NetCDF4 chunking and compression provides is given in 1395 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 1396 1390 a 4x2 mpi partitioning. 1397 1391 Note the variation in the compression ratio achieved which reflects chiefly the dry to wet volume ratio of 1398 1392 each processing region. 1399 1393 1400 %------------------------------------------TABLE----------------------------------------------------1401 1394 \begin{table} 1402 \scriptsize1403 1395 \centering 1404 1396 \begin{tabular}{lrrr} … … 1432 1424 ORCA2\_2d\_grid\_W\_0007.nc & 4416 & 1368 & 70\% \\ 1433 1425 \end{tabular} 1434 \caption{ 1435 \protect\label{tab:NC4} 1436 Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression 1437 } 1426 \caption{Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression} 1427 \label{tab:DIA_NC4} 1438 1428 \end{table} 1439 %----------------------------------------------------------------------------------------------------1440 1429 1441 1430 When \key{iomput} is activated with \key{netcdf4} chunking and compression parameters for fields produced via 1442 \ np{iom\_put} calls are set via an equivalent and identically named namelist to \textit{namnc4} in1443 \ np{xmlio\_server.def}.1444 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 1445 1434 serve the restart files. 1446 1435 This duplication is unfortunate but appropriate since, if using io\_servers, the domain sizes of 1447 1436 the individual files produced by the io\_server processes may be different to those produced by 1448 1437 the invidual processing regions and different chunking choices may be desired. 1449 1450 % ------------------------------------------------------------------------------------------------------------- 1451 % Tracer/Dynamics Trends 1452 % ------------------------------------------------------------------------------------------------------------- 1453 \section[Tracer/Dynamics trends (\texttt{namtrd})] 1454 {Tracer/Dynamics trends (\protect\ngn{namtrd})} 1438 1439 %% ================================================================================================= 1440 \section[Tracer/Dynamics trends (\forcode{&namtrd})]{Tracer/Dynamics trends (\protect\nam{trd}{trd})} 1455 1441 \label{sec:DIA_trd} 1456 1442 1457 %------------------------------------------namtrd---------------------------------------------------- 1458 1459 \nlst{namtrd} 1460 %------------------------------------------------------------------------------------------------------------- 1443 \begin{listing} 1444 \nlst{namtrd} 1445 \caption{\forcode{&namtrd}} 1446 \label{lst:namtrd} 1447 \end{listing} 1461 1448 1462 1449 Each trend of the dynamics and/or temperature and salinity time evolution equations can be send to 1463 1450 \mdl{trddyn} and/or \mdl{trdtra} modules (see TRD directory) just after their computation 1464 (\ie at the end of each $dyn\cdots.F90$ and/or $tra\cdots.F90$routines).1465 This capability is controlled by options offered in \n gn{namtrd} namelist.1466 Note that the output are done with xIOS, and therefore the \key{IOM} is required.1467 1468 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.}: 1469 1456 1470 1457 \begin{description} 1471 \item[\np{ln\_glo\_trd}]: 1472 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 1473 1459 the momentum and tracer equations is performed. 1474 1460 This also includes a check of $T^2$, $S^2$, $\tfrac{1}{2} (u^2+v2)$, 1475 1461 and potential energy time evolution equations properties; 1476 \item[\np{ln\_dyn\_trd}]: 1477 each 3D trend of the evolution of the two momentum components is output; 1478 \item[\np{ln\_dyn\_mxl}]: 1479 each 3D trend of the evolution of the two momentum components averaged over the mixed layer is output; 1480 \item[\np{ln\_vor\_trd}]: 1481 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, 1482 1465 then the curl is computed to obtain the barotropic vorticity tendencies which are output; 1483 \item[\np{ln\_KE\_trd}] : 1484 each 3D trend of the Kinetic Energy equation is output; 1485 \item[\np{ln\_tra\_trd}]: 1486 each 3D trend of the evolution of temperature and salinity is output; 1487 \item[\np{ln\_tra\_mxl}]: 1488 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; 1489 1469 \end{description} 1490 1470 1491 Note that the mixed layer tendency diagnostic can also be used on biogeochemical models via 1492 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. 1493 1473 1494 1474 \textbf{Note that} in the current version (v3.6), many changes has been introduced but not fully tested. 1495 In particular, options associated with \np{ln\_dyn\_mxl}, \np{ln\_vor\_trd}, and \np{ln\_tra\_mxl} are not working, 1496 and none of the options have been tested with variable volume (\ie \key{vvl} defined). 1497 1498 % ------------------------------------------------------------------------------------------------------------- 1499 % On-line Floats trajectories 1500 % ------------------------------------------------------------------------------------------------------------- 1501 \section[FLO: On-Line Floats trajectories (\texttt{\textbf{key\_floats}})] 1502 {FLO: On-Line Floats trajectories (\protect\key{floats})} 1503 \label{sec:FLO} 1504 %--------------------------------------------namflo------------------------------------------------------- 1505 1506 \nlst{namflo} 1507 %-------------------------------------------------------------------------------------------------------------- 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} 1508 1487 1509 1488 The on-line computation of floats advected either by the three dimensional velocity field or constraint to 1510 1489 remain at a given depth ($w = 0$ in the computation) have been introduced in the system during the CLIPPER project. 1511 Options are defined by \n gn{namflo} namelisvariables.1490 Options are defined by \nam{flo}{flo} namelist variables. 1512 1491 The algorithm used is based either on the work of \cite{blanke.raynaud_JPO97} (default option), 1513 or on a $4^th$ Runge-Hutta algorithm (\np {ln\_flork4}\forcode{ = .true.}).1492 or on a $4^th$ Runge-Hutta algorithm (\np[=.true.]{ln_flork4}{ln\_flork4}). 1514 1493 Note that the \cite{blanke.raynaud_JPO97} algorithm have the advantage of providing trajectories which 1515 1494 are consistent with the numeric of the code, so that the trajectories never intercept the bathymetry. 1516 1495 1496 %% ================================================================================================= 1517 1497 \subsubsection{Input data: initial coordinates} 1518 1498 1519 1499 Initial coordinates can be given with Ariane Tools convention 1520 (IJK coordinates, (\np {ln\_ariane}\forcode{ = .true.}) ) or with longitude and latitude.1521 1522 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}. 1523 1503 Its format is: \\ 1524 { \scriptsize \texttt{I J K nisobfl itrashitrash}}1504 { \texttt{I J K nisobfl itrash}} 1525 1505 1526 1506 \noindent with: … … 1528 1508 - I,J,K : indexes of initial position 1529 1509 1530 - 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 1531 1511 1532 1512 - itrash : set to zero; it is a dummy variable to respect Ariane Tools convention … … 1534 1514 \noindent Example: \\ 1535 1515 \noindent 1536 { \scriptsize1516 { 1537 1517 \texttt{ 1538 1518 100.00000 90.00000 -1.50000 1.00000 0.00000 \\ … … 1545 1525 In the other case (longitude and latitude), input filename is init\_float. 1546 1526 Its format is: \\ 1547 { \scriptsize\texttt{Long Lat depth nisobfl ngrpfl itrash}}1527 { \texttt{Long Lat depth nisobfl ngrpfl itrash}} 1548 1528 1549 1529 \noindent with: … … 1559 1539 \noindent Example: \\ 1560 1540 \noindent 1561 { \scriptsize1541 { 1562 1542 \texttt{ 1563 1543 20.0 0.0 0.0 0 1 1 \\ … … 1568 1548 } \\ 1569 1549 1570 \np{jpnfl} is the total number of floats during the run. 1571 When initial positions are read in a restart file (\np{ln\_rstflo}\forcode{ = .true.} ), 1572 \np{jpnflnewflo} can be added in the initialization file. 1573 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 %% ================================================================================================= 1574 1555 \subsubsection{Output data} 1575 1556 1576 \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 1577 1558 creation of the float restart file. 1578 1559 1579 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}). 1580 1561 In that case, output filename is trajec\_float. 1581 1562 1582 Another possiblity of writing format is Netcdf (\np{ln\_flo\_ascii}\forcode{ = .false.}). 1583 There are 2 possibilities: 1584 1585 - 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. 1586 1565 Here it is an example of specification to put in files description section: 1587 1566 … … 1600 1579 \end{xmllines} 1601 1580 1602 - if (\key{iomput}) is not used, a file called \ifile{trajec\_float} will be created by IOIPSL library. 1603 1604 See also \href{http://stockage.univ-brest.fr/~grima/Ariane/}{here} the web site describing the off-line use of 1605 this marvellous diagnostic tool. 1606 1607 % ------------------------------------------------------------------------------------------------------------- 1608 % Harmonic analysis of tidal constituents 1609 % ------------------------------------------------------------------------------------------------------------- 1610 \section[Harmonic analysis of tidal constituents (\texttt{\textbf{key\_diaharm}})] 1611 {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})} 1612 1583 \label{sec:DIA_diag_harm} 1613 1584 1614 %------------------------------------------namdia_harm---------------------------------------------------- 1615 % 1616 \nlst{nam_diaharm} 1617 %---------------------------------------------------------------------------------------------------------- 1585 \begin{listing} 1586 \nlst{nam_diaharm} 1587 \caption{\forcode{&nam_diaharm}} 1588 \label{lst:nam_diaharm} 1589 \end{listing} 1618 1590 1619 1591 A module is available to compute the amplitude and phase of tidal waves. 1620 1592 This on-line Harmonic analysis is actived with \key{diaharm}. 1621 1593 1622 Some parameters are available in namelist \n gn{namdia\_harm}:1623 1624 - \np{nit000 \_han} is the first time step used for harmonic analysis1625 1626 - \np{nitend \_han} is the last time step used for harmonic analysis1627 1628 - \np{nstep \_han} is the time step frequency for harmonic analysis1629 1630 - \np{nb\_ana} is the number of harmonics to analyse1631 1632 - \np{tname} is an array with names of tidal constituents to analyse1633 1634 \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. 1635 1607 The restart capability is not implemented. 1636 1608 … … 1653 1625 We obtain in output $C_{j}$ and $S_{j}$ for each tidal wave. 1654 1626 1655 % ------------------------------------------------------------------------------------------------------------- 1656 % Sections transports 1657 % ------------------------------------------------------------------------------------------------------------- 1658 \section[Transports across sections (\texttt{\textbf{key\_diadct}})] 1659 {Transports across sections (\protect\key{diadct})} 1627 %% ================================================================================================= 1628 \section[Transports across sections (\texttt{\textbf{key\_diadct}})]{Transports across sections (\protect\key{diadct})} 1660 1629 \label{sec:DIA_diag_dct} 1661 1630 1662 %------------------------------------------namdct---------------------------------------------------- 1663 1664 \nlst{namdct} 1665 %------------------------------------------------------------------------------------------------------------- 1631 \begin{listing} 1632 \nlst{nam_diadct} 1633 \caption{\forcode{&nam_diadct}} 1634 \label{lst:nam_diadct} 1635 \end{listing} 1666 1636 1667 1637 A module is available to compute the transport of volume, heat and salt through sections. … … 1669 1639 1670 1640 Each section is defined by the coordinates of its 2 extremities. 1671 The pathways between them are contructed using tools which can be found in \texttt{ NEMOGCM/TOOLS/SECTIONS\_DIADCT}1672 and are written in a binary file \texttt{section\_ijglobal.diadct \_ORCA2\_LIM} which is later read in by1673 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. 1674 1644 1675 1645 The on-line transports module creates three output ascii files: … … 1681 1651 - \texttt{salt\_transport} for salt transports (unit: $10^{9}Kg s^{-1}$) \\ 1682 1652 1683 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 1684 1654 they are averaged, as well as the level of output for debugging: 1685 \np{nn\_dct} : frequency of instantaneous transports computing 1686 \np{nn\_dctwri}: frequency of writing ( mean of instantaneous transports ) 1687 \np{nn\_debug} : debugging of the section 1688 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 %% ================================================================================================= 1689 1660 \subsubsection{Creating a binary file containing the pathway of each section} 1690 1661 1691 In \texttt{ NEMOGCM/TOOLS/SECTIONS\_DIADCT/run},1662 In \texttt{tools/SECTIONS\_DIADCT/run}, 1692 1663 the file \textit{ {list\_sections.ascii\_global}} contains a list of all the sections that are to be computed 1693 1664 (this list of sections is based on MERSEA project metrics). … … 1696 1667 1697 1668 Each section is defined by: \\ 1698 \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}} \\ 1699 1670 with: 1700 1671 … … 1703 1674 - \texttt{long2 lat2}, coordinates of the second extremity of the section; 1704 1675 1705 - \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); 1706 1677 1707 1678 - \texttt{okstrpond} to compute heat and salt transports, \texttt{nostrpond} if no; … … 1713 1684 1714 1685 \noindent If nclass $\neq$ 0, the next lines contain the class type and the nclass bounds: \\ 1715 { \scriptsize1686 { 1716 1687 \texttt{ 1717 1688 long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name \\ … … 1736 1707 1737 1708 - \texttt{zsigp} for potential density classes \\ 1738 1709 1739 1710 The script \texttt{job.ksh} computes the pathway for each section and creates a binary file 1740 \texttt{section\_ijglobal.diadct \_ORCA2\_LIM} which is read byNEMO. \\1711 \texttt{section\_ijglobal.diadct} which is read by \NEMO. \\ 1741 1712 1742 1713 It is possible to use this tools for new configuations: \texttt{job.ksh} has to be updated with … … 1746 1717 and the ATL\_Cuba\_Florida with 4 temperature clases (5 class bounds), are shown: \\ 1747 1718 \noindent 1748 { \scriptsize1719 { 1749 1720 \texttt{ 1750 1721 -68. -54.5 -60. -64.7 00 okstrpond noice ACC\_Drake\_Passage \\ … … 1758 1729 } 1759 1730 1731 %% ================================================================================================= 1760 1732 \subsubsection{To read the output files} 1761 1733 1762 1734 The output format is: \\ 1763 { \scriptsize1735 { 1764 1736 \texttt{ 1765 1737 date, time-step number, section number, \\ … … 1783 1755 1784 1756 \begin{table} 1785 \scriptsize1786 1757 \begin{tabular}{|l|l|l|l|l|} 1787 1758 \hline … … 1797 1768 \end{table} 1798 1769 1799 % ================================================================ 1800 % Steric effect in sea surface height 1801 % ================================================================ 1770 %% ================================================================================================= 1802 1771 \section{Diagnosing the steric effect in sea surface height} 1803 1772 \label{sec:DIA_steric} 1804 1805 1773 1806 1774 Changes in steric sea level are caused when changes in the density of the water column imply an expansion or … … 1824 1792 1825 1793 Let denote 1826 $\mathcal{M}$ the total mass of liquid seawater ($\mathcal{M} = \int_D \rho dv$), 1827 $\mathcal{V}$ the total volume of seawater ($\mathcal{V} = \int_D dv$), 1828 $\mathcal{A}$ the total surface of the ocean ($\mathcal{A} = \int_S ds$), 1829 $\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 1830 1798 ($\bar{\rho} = 1/\mathcal{V} \int_D \rho \,dv$), and 1831 $\bar{\eta}$ the global mean sea level 1799 $\bar{\eta}$ the global mean sea level 1832 1800 ($\bar{\eta} = 1/\mathcal{A} \int_S \eta \,ds$). 1833 1801 … … 1839 1807 \mathcal{V} &= \mathcal{A} \;\bar{\eta} 1840 1808 \end{split} 1841 \label{eq: MV_nBq}1809 \label{eq:DIA_MV_nBq} 1842 1810 \end{equation} 1843 1811 … … 1847 1815 \frac{1}{e_3} \partial_t ( e_3\,\rho) + \nabla( \rho \, \textbf{U} ) 1848 1816 = \left. \frac{\textit{emp}}{e_3}\right|_\textit{surface} 1849 \label{eq: Co_nBq}1817 \label{eq:DIA_Co_nBq} 1850 1818 \end{equation} 1851 1819 1852 1820 where $\rho$ is the \textit{in situ} density, and \textit{emp} the surface mass exchanges with the other media of 1853 1821 the Earth system (atmosphere, sea-ice, land). 1854 Its global averaged leads to the total mass change 1822 Its global averaged leads to the total mass change 1855 1823 1856 1824 \begin{equation} 1857 1825 \partial_t \mathcal{M} = \mathcal{A} \;\overline{\textit{emp}} 1858 \label{eq: Mass_nBq}1826 \label{eq:DIA_Mass_nBq} 1859 1827 \end{equation} 1860 1828 1861 1829 where $\overline{\textit{emp}} = \int_S \textit{emp}\,ds$ is the net mass flux through the ocean surface. 1862 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 1863 1831 the evolution equation of the mean sea level 1864 1832 … … 1866 1834 \partial_t \bar{\eta} = \frac{\overline{\textit{emp}}}{ \bar{\rho}} 1867 1835 - \frac{\mathcal{V}}{\mathcal{A}} \;\frac{\partial_t \bar{\rho} }{\bar{\rho}} 1868 \label{eq: ssh_nBq}1836 \label{eq:DIA_ssh_nBq} 1869 1837 \end{equation} 1870 1838 1871 The first term in equation \autoref{eq: ssh_nBq} alters sea level by adding or subtracting mass from the ocean.1872 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. 1873 1841 1874 1842 In a Boussinesq fluid, $\rho$ is replaced by $\rho_o$ in all the equation except when $\rho$ appears multiplied by 1875 the gravity (\ie in the hydrostatic balance of the primitive Equations).1876 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: 1877 1845 1878 1846 \[ 1879 1847 \frac{1}{e_3} \partial_t ( e_3 ) + \nabla( \textbf{U} ) = \left. \frac{\textit{emp}}{\rho_o \,e_3}\right|_ \textit{surface} 1880 % \label{eq: Co_Bq}1848 % \label{eq:DIA_Co_Bq} 1881 1849 \] 1882 1850 … … 1885 1853 \[ 1886 1854 \partial_t \mathcal{V} = \mathcal{A} \;\frac{\overline{\textit{emp}}}{\rho_o} 1887 % \label{eq: V_Bq}1855 % \label{eq:DIA_V_Bq} 1888 1856 \] 1889 1857 … … 1894 1862 1895 1863 Nevertheless, following \citep{greatbatch_JGR94}, the steric effect on the volume can be diagnosed by 1896 considering the mass budget of the ocean. 1864 considering the mass budget of the ocean. 1897 1865 The apparent changes in $\mathcal{M}$, mass of the ocean, which are not induced by surface mass flux 1898 1866 must be compensated by a spatially uniform change in the mean sea level due to expansion/contraction of the ocean … … 1904 1872 \begin{equation} 1905 1873 \mathcal{M}_o = \mathcal{M} + \rho_o \,\eta_s \,\mathcal{A} 1906 \label{eq: M_Bq}1874 \label{eq:DIA_M_Bq} 1907 1875 \end{equation} 1908 1876 … … 1910 1878 is converted into a mean change in sea level. 1911 1879 Introducing the total density anomaly, $\mathcal{D}= \int_D d_a \,dv$, 1912 where $d_a = (\rho -\rho_o ) / \rho_o$ is the density anomaly used in \NEMO (cf. \autoref{subsec:TRA_eos})1913 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: 1914 1882 1915 1883 \begin{equation} 1916 1884 \eta_s = - \frac{1}{\mathcal{A}} \mathcal{D} 1917 \label{eq: steric_Bq}1885 \label{eq:DIA_steric_Bq} 1918 1886 \end{equation} 1919 1887 1920 1888 The above formulation of the steric height of a Boussinesq ocean requires four remarks. 1921 1889 First, one can be tempted to define $\rho_o$ as the initial value of $\mathcal{M}/\mathcal{V}$, 1922 \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. 1923 1891 We do not recommend that. 1924 1892 Indeed, in this case $\rho_o$ depends on the initial state of the ocean. … … 1934 1902 does not change when the sea level is changing as it is the case in all global ocean GCMs 1935 1903 (wetting and drying of grid point is not allowed). 1936 1937 Third, the discretisation of \autoref{eq: steric_Bq} depends on the type of free surface which is considered.1938 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 1939 1907 1940 1908 \[ 1941 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} } 1942 % \label{eq: discrete_steric_Bq_nfs}1910 % \label{eq:DIA_discrete_steric_Bq_nfs} 1943 1911 \] 1944 1912 … … 1950 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 } 1951 1919 { \sum_{i,\,j,\,k} e_{1t}e_{2t}e_{3t} + \sum_{i,\,j} e_{1t}e_{2t} \eta } 1952 % \label{eq: discrete_steric_Bq_fs}1920 % \label{eq:DIA_discrete_steric_Bq_fs} 1953 1921 \] 1954 1922 … … 1959 1927 so that there are no associated ocean currents. 1960 1928 Hence, the dynamically relevant sea level is the effective sea level, 1961 \ie the sea level as if sea ice (and snow) were converted to liquid seawater \citep{campin.marshall.ea_OM08}.1962 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 1963 1931 ice and ocean. 1964 1932 Therefore the model effective sea level is always given by $\eta + \eta_s$, whether or not there is sea ice present. … … 1970 1938 \[ 1971 1939 \eta_s = - \frac{1}{\mathcal{A}} \int_D d_a(T,S_o,p_o) \,dv 1972 % \label{eq: thermosteric_Bq}1940 % \label{eq:DIA_thermosteric_Bq} 1973 1941 \] 1974 1942 1975 1943 where $S_o$ and $p_o$ are the initial salinity and pressure, respectively. 1976 1944 1977 Both steric and thermosteric sea level are computed in \mdl{diaar5} which needs the \key{diaar5} defined to 1978 be called. 1979 1980 % ------------------------------------------------------------------------------------------------------------- 1981 % Other Diagnostics 1982 % ------------------------------------------------------------------------------------------------------------- 1983 \section[Other diagnostics (\texttt{\textbf{key\_diahth}}, \texttt{\textbf{key\_diaar5}})] 1984 {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} 1985 1949 \label{sec:DIA_diag_others} 1986 1950 … … 1988 1952 The available ready-to-add diagnostics modules can be found in directory DIA. 1989 1953 1990 \subsection[Depth of various quantities (\textit{diahth.F90})] 1991 {Depth of various quantities (\protect\mdl{diahth})}1954 %% ================================================================================================= 1955 \subsection[Depth of various quantities (\textit{diahth.F90})]{Depth of various quantities (\protect\mdl{diahth})} 1992 1956 1993 1957 Among the available diagnostics the following ones are obtained when defining the \key{diahth} CPP key: … … 2001 1965 - the depth of the thermocline (maximum of the vertical temperature gradient) (\mdl{diahth}) 2002 1966 2003 % ----------------------------------------------------------- 2004 % Poleward heat and salt transports 2005 % ----------------------------------------------------------- 2006 2007 \subsection[Poleward heat and salt transports (\textit{diaptr.F90})] 2008 {Poleward heat and salt transports (\protect\mdl{diaptr})} 2009 2010 %------------------------------------------namptr----------------------------------------- 2011 2012 \nlst{namptr} 2013 %----------------------------------------------------------------------------------------- 2014 2015 The poleward heat and salt transports, their advective and diffusive component, 2016 and the meriodional stream function can be computed on-line in \mdl{diaptr} \np{ln\_diaptr} to true 2017 (see the \textit{\ngn{namptr} } namelist below). 2018 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, 2019 1999 Pacific and Indo-Pacific Oceans (defined north of 30\deg{S}) as well as for the World Ocean. 2020 2000 The sub-basin decomposition requires an input file (\ifile{subbasins}) which contains three 2D mask arrays, 2021 the Indo-Pacific mask been deduced from the sum of the Indian and Pacific mask (\autoref{fig:mask_subasins}). 2022 2023 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 2024 \begin{figure}[!t] 2025 \begin{center} 2026 \includegraphics[width=\textwidth]{Fig_mask_subasins} 2027 \caption{ 2028 \protect\label{fig:mask_subasins} 2029 Decomposition of the World Ocean (here ORCA2) into sub-basin used in to 2030 compute the heat and salt transports as well as the meridional stream-function: 2031 Atlantic basin (red), Pacific basin (green), Indian basin (bleue), Indo-Pacific basin (bleue+green). 2032 Note that semi-enclosed seas (Red, Med and Baltic seas) as well as Hudson Bay are removed from the sub-basins. 2033 Note also that the Arctic Ocean has been split into Atlantic and Pacific basins along the North fold line. 2034 } 2035 \end{center} 2036 \end{figure} 2037 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 2038 2039 % ----------------------------------------------------------- 2040 % CMIP specific diagnostics 2041 % ----------------------------------------------------------- 2042 \subsection[CMIP specific diagnostics (\textit{diaar5.F90})] 2043 {CMIP specific diagnostics (\protect\mdl{diaar5})} 2044 2045 A series of diagnostics has been added in the \mdl{diaar5}. 2046 They corresponds to outputs that are required for AR5 simulations (CMIP5) 2047 (see also \autoref{sec:DIA_steric} for one of them). 2048 Activating those outputs requires to define the \key{diaar5} CPP key. 2049 2050 % ----------------------------------------------------------- 2051 % 25 hour mean and hourly Surface, Mid and Bed 2052 % ----------------------------------------------------------- 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 %% ================================================================================================= 2053 2010 \subsection{25 hour mean output for tidal models} 2054 2011 2055 %------------------------------------------nam_dia25h------------------------------------- 2056 2057 \nlst{nam_dia25h} 2058 %----------------------------------------------------------------------------------------- 2012 \begin{listing} 2013 \nlst{nam_dia25h} 2014 \caption{\forcode{&nam_dia25h}} 2015 \label{lst:nam_dia25h} 2016 \end{listing} 2059 2017 2060 2018 A module is available to compute a crudely detided M2 signal by obtaining a 25 hour mean. … … 2063 2021 This diagnostic is actived with the logical $ln\_dia25h$. 2064 2022 2065 % ----------------------------------------------------------- 2066 % Top Middle and Bed hourly output 2067 % ----------------------------------------------------------- 2023 %% ================================================================================================= 2068 2024 \subsection{Top middle and bed hourly output} 2069 2025 2070 %------------------------------------------nam_diatmb----------------------------------------------------- 2071 2072 \nlst{nam_diatmb} 2073 %---------------------------------------------------------------------------------------------------------- 2026 \begin{listing} 2027 \nlst{nam_diatmb} 2028 \caption{\forcode{&nam_diatmb}} 2029 \label{lst:nam_diatmb} 2030 \end{listing} 2074 2031 2075 2032 A module is available to output the surface (top), mid water and bed diagnostics of a set of standard variables. … … 2079 2036 This diagnostic is actived with the logical $ln\_diatmb$. 2080 2037 2081 % ----------------------------------------------------------- 2082 % Courant numbers 2083 % ----------------------------------------------------------- 2038 %% ================================================================================================= 2084 2039 \subsection{Courant numbers} 2085 2040 … … 2089 2044 \[ 2090 2045 C_u = |u|\frac{\rdt}{e_{1u}}, \quad C_v = |v|\frac{\rdt}{e_{2v}}, \quad C_w = |w|\frac{\rdt}{e_{3w}} 2091 % \label{eq: CFL}2046 % \label{eq:DIA_CFL} 2092 2047 \] 2093 2048 … … 2098 2053 Values greater than 1 indicate that information is propagated across more than one grid cell in a single time step. 2099 2054 2100 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. 2101 2056 The diagnostics will be written out to an ascii file named cfl\_diagnostics.ascii. 2102 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 … … 2104 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 2105 2060 with the coordinates of each. 2106 The maximum values from the run are also copied to the ocean.output file. 2107 2108 % ================================================================ 2109 2110 \biblio 2111 2112 \pindex 2061 The maximum values from the run are also copied to the ocean.output file. 2062 2063 \subinc{\input{../../global/epilogue}} 2113 2064 2114 2065 \end{document} -
NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_DIU.tex
r11151 r12149 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 42 ($\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 71 The warm layer is calculated using the model of \citet{takaya.bidlot.ea_JGR10} (TAKAYA10 model hereafter). … … 65 74 \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 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. 71 In equation (\autoref{eq: ecmwf1}) $\alpha_w=2\times10^{-4}$ is the thermal expansion coefficient of water,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. … … 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 93 Q = Q_{\mathrm{sol}} + Q_{\mathrm{lw}} + Q_{\mathrm{h}}\mbox{,} 85 % \label{eq: e_flux_eqn}94 % \label{eq:DIU_e_flux_eqn} 86 95 \] 87 96 where $Q_{\mathrm{h}}$ is the sensible and latent heat flux, $Q_{\mathrm{lw}}$ is the long wave flux, 88 97 and $Q_{\mathrm{sol}}$ is the solar flux absorbed within the diurnal warm layer. 89 98 For $Q_{\mathrm{sol}}$ the 9 term representation of \citet{gentemann.minnett.ea_JGR09} is used. 90 In equation \autoref{eq: ecmwf1} the function $f(L_a)=\max(1,L_a^{\frac{2}{3}})$,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 %=============================================================== 114 122 %% ================================================================================================= 115 123 \section{Cool skin model} 116 \label{sec:cool_skin_sec} 117 118 %=============================================================== 124 \label{sec:DIU_cool_skin_sec} 119 125 120 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}$. 121 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}129 % \label{eq:DIU_sunders_eqn} 124 130 \Delta T_{\mathrm{cs}}=\frac{Q_{\mathrm{ns}}\delta}{k_t} \mbox{,} 125 131 \] … … 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} … … 134 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.iudicone.ea_JGR02},142 The value of $\lambda$ used in equation (\autoref{eq:DIU_sunders_thick_eqn}) is that of \citet{artale.iudicone.ea_JGR02}, 137 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/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_DOM.tex
r11179 r12149 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[width=\textwidth]{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[width=\textwidth]{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[width=\textwidth]{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 (\textit{domhgr.F90})] 348 {Horizontal grid mesh (\protect\mdl{domhgr})} 349 \label{sec:DOM_hgr} 350 351 % ------------------------------------------------------------------------------------------------------------- 352 % Coordinates and scale factors 353 % ------------------------------------------------------------------------------------------------------------- 354 \subsection{Coordinates and scale factors} 355 \label{subsec:DOM_hgr_coord_e} 356 357 The ocean mesh (\ie the position of all the scalar and vector points) is defined by 358 the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. 359 The grid-points are located at integer or integer and a half values of as indicated in \autoref{tab:cell}. 360 The associated scale factors are defined using the analytical first derivative of the transformation 361 \autoref{eq:scale_factors}. 362 These definitions are done in two modules, \mdl{domhgr} and \mdl{domzgr}, 363 which provide the horizontal and vertical meshes, respectively. 364 This section deals with the horizontal mesh parameters. 365 366 In a horizontal plane, the location of all the model grid points is defined from 367 the analytical expressions of the longitude $\lambda$ and latitude $\varphi$ as a function of $(i,j)$. 368 The horizontal scale factors are calculated using \autoref{eq:scale_factors}. 369 For example, when the longitude and latitude are function of a single value 370 ($i$ and $j$, respectively) (geographical configuration of the mesh), 371 the horizontal mesh definition reduces to define the wanted $\lambda(i)$, $\varphi(j)$, 372 and their derivatives $\lambda'(i) \ \varphi'(j)$ in the \mdl{domhgr} module. 373 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: 374 597 \begin{align*} 375 \lambda_t &\equiv \text{glamt} = \lambda (i ) 376 &\varphi_t &\equiv \text{gphit} = \varphi (j ) \\ 377 \lambda_u &\equiv \text{glamu} = \lambda (i + 1/2) 378 &\varphi_u &\equiv \text{gphiu} = \varphi (j ) \\ 379 \lambda_v &\equiv \text{glamv} = \lambda (i ) 380 &\varphi_v &\equiv \text{gphiv} = \varphi (j + 1/2) \\ 381 \lambda_f &\equiv \text{glamf} = \lambda (i + 1/2) 382 &\varphi_f &\equiv \text{gphif} = \varphi (j + 1/2) \\ 383 e_{1t} &\equiv \text{e1t} = r_a |\lambda'(i ) \; \cos\varphi(j ) | 384 &e_{2t} &\equiv \text{e2t} = r_a |\varphi'(j ) | \\ 385 e_{1u} &\equiv \text{e1t} = r_a |\lambda'(i + 1/2) \; \cos\varphi(j ) | 386 &e_{2u} &\equiv \text{e2t} = r_a |\varphi'(j ) | \\ 387 e_{1v} &\equiv \text{e1t} = r_a |\lambda'(i ) \; \cos\varphi(j + 1/2) | 388 &e_{2v} &\equiv \text{e2t} = r_a |\varphi'(j + 1/2) | \\ 389 e_{1f} &\equiv \text{e1t} = r_a |\lambda'(i + 1/2) \; \cos\varphi(j + 1/2) | 390 &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) 391 609 \end{align*} 392 where the last letter of each computational name indicates the grid point considered and 393 $r_a$ is the earth radius (defined in \mdl{phycst} along with all universal constants). 394 Note that the horizontal position of and scale factors at $w$-points are exactly equal to those of $t$-points, 395 thus no specific arrays are defined at $w$-points. 396 397 Note that the definition of the scale factors 398 (\ie as the analytical first derivative of the transformation that 399 gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$) 400 is specific to the \NEMO model \citep{marti.madec.ea_JGR92}. 401 As an example, $e_{1t}$ is defined locally at a $t$-point, 402 whereas many other models on a C grid choose to define such a scale factor as 403 the distance between the $U$-points on each side of the $t$-point. 404 Relying on an analytical transformation has two advantages: 405 firstly, there is no ambiguity in the scale factors appearing in the discrete equations, 406 since they are first introduced in the continuous equations; 407 secondly, analytical transformations encourage good practice by the definition of smoothly varying grids 408 (rather than allowing the user to set arbitrary jumps in thickness between adjacent layers) \citep{treguier.dukowicz.ea_JGR96}. 409 An example of the effect of such a choice is shown in \autoref{fig:zgr_e3}. 410 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 411 \begin{figure}[!t] 412 \begin{center} 413 \includegraphics[width=\textwidth]{Fig_zgr_e3} 414 \caption{ 415 \protect\label{fig:zgr_e3} 416 Comparison of (a) traditional definitions of grid-point position and grid-size in the vertical, 417 and (b) analytically derived grid-point position and scale factors. 418 For both grids here, the same $w$-point depth has been chosen but 419 in (a) the $t$-points are set half way between $w$-points while 420 in (b) they are defined from an analytical function: 421 $z(k) = 5 \, (k - 1/2)^3 - 45 \, (k - 1/2)^2 + 140 \, (k - 1/2) - 150$. 422 Note the resulting difference between the value of the grid-size $\Delta_k$ and 423 those of the scale factor $e_k$. 424 } 425 \end{center} 426 \end{figure} 427 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 428 429 % ------------------------------------------------------------------------------------------------------------- 430 % Choice of horizontal grid 431 % ------------------------------------------------------------------------------------------------------------- 432 \subsection{Choice of horizontal grid} 433 \label{subsec:DOM_hgr_msh_choice} 434 435 % ------------------------------------------------------------------------------------------------------------- 436 % Grid files 437 % ------------------------------------------------------------------------------------------------------------- 438 \subsection{Output grid files} 439 \label{subsec:DOM_hgr_files} 440 441 All the arrays relating to a particular ocean model configuration (grid-point position, scale factors, masks) 442 can be saved in files if \np{nn\_msh} $\not = 0$ (namelist variable in \ngn{namdom}). 443 This can be particularly useful for plots and off-line diagnostics. 444 In some cases, the user may choose to make a local modification of a scale factor in the code. 445 This is the case in global configurations when restricting the width of a specific strait 446 (usually a one-grid-point strait that happens to be too wide due to insufficient model resolution). 447 An example is Gibraltar Strait in the ORCA2 configuration. 448 When such modifications are done, 449 the output grid written when \np{nn\_msh} $\not = 0$ is no more equal to the input grid. 450 451 % ================================================================ 452 % Domain: Vertical Grid (domzgr) 453 % ================================================================ 454 \section[Vertical grid (\textit{domzgr.F90})] 455 {Vertical grid (\protect\mdl{domzgr})} 456 \label{sec:DOM_zgr} 457 %-----------------------------------------nam_zgr & namdom------------------------------------------- 458 % 459 %\nlst{namzgr} 460 461 \nlst{namdom} 462 %------------------------------------------------------------------------------------------------------------- 463 464 Variables are defined through the \ngn{namzgr} and \ngn{namdom} namelists. 465 In the vertical, the model mesh is determined by four things: 466 (1) the bathymetry given in meters; 467 (2) the number of levels of the model (\jp{jpk}); 468 (3) the analytical transformation $z(i,j,k)$ and the vertical scale factors (derivatives of the transformation); and 469 (4) the masking system, \ie the number of wet model levels at each 470 $(i,j)$ column of points. 471 472 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 473 \begin{figure}[!tb] 474 \begin{center} 475 \includegraphics[width=\textwidth]{Fig_z_zps_s_sps} 476 \caption{ 477 \protect\label{fig:z_zps_s_sps} 478 The ocean bottom as seen by the model: 479 (a) $z$-coordinate with full step, 480 (b) $z$-coordinate with partial step, 481 (c) $s$-coordinate: terrain following representation, 482 (d) hybrid $s-z$ coordinate, 483 (e) hybrid $s-z$ coordinate with partial step, and 484 (f) same as (e) but in the non-linear free surface (\protect\np{ln\_linssh}\forcode{ = .false.}). 485 Note that the non-linear free surface can be used with any of the 5 coordinates (a) to (e). 486 } 487 \end{center} 488 \end{figure} 489 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 490 491 The choice of a vertical coordinate, even if it is made through \ngn{namzgr} namelist parameters, 492 must be done once of all at the beginning of an experiment. 493 It is not intended as an option which can be enabled or disabled in the middle of an experiment. 494 Three main choices are offered (\autoref{fig:z_zps_s_sps}): 495 $z$-coordinate with full step bathymetry (\np{ln\_zco}\forcode{ = .true.}), 496 $z$-coordinate with partial step bathymetry (\np{ln\_zps}\forcode{ = .true.}), 497 or generalized, $s$-coordinate (\np{ln\_sco}\forcode{ = .true.}). 498 Hybridation of the three main coordinates are available: 499 $s-z$ or $s-zps$ coordinate (\autoref{fig:z_zps_s_sps} and \autoref{fig:z_zps_s_sps}). 500 By default a non-linear free surface is used: the coordinate follow the time-variation of the free surface so that 501 the transformation is time dependent: $z(i,j,k,t)$ (\autoref{fig:z_zps_s_sps}). 502 When a linear free surface is assumed (\np{ln\_linssh}\forcode{ = .true.}), 503 the vertical coordinate are fixed in time, but the seawater can move up and down across the $z_0$ surface 504 (in other words, the top of the ocean in not a rigid-lid). 505 The last choice in terms of vertical coordinate concerns the presence (or not) in 506 the model domain of ocean cavities beneath ice shelves. 507 Setting \np{ln\_isfcav} to true allows to manage ocean cavities, otherwise they are filled in. 508 This option is currently only available in $z$- or $zps$-coordinate, 509 and partial step are also applied at the ocean/ice shelf interface. 510 511 Contrary to the horizontal grid, the vertical grid is computed in the code and no provision is made for 512 reading it from a file. 513 The only input file is the bathymetry (in meters) (\ifile{bathy\_meter}) 514 \footnote{ 515 N.B. in full step $z$-coordinate, a \ifile{bathy\_level} file can replace the \ifile{bathy\_meter} file, 516 so that the computation of the number of wet ocean point in each water column is by-passed}. 517 If \np{ln\_isfcav}\forcode{ = .true.}, an extra file input file (\ifile{isf\_draft\_meter}) describing 518 the ice shelf draft (in meters) is needed. 519 520 After reading the bathymetry, the algorithm for vertical grid definition differs between the different options: 521 \begin{description} 522 \item[\textit{zco}] 523 set a reference coordinate transformation $z_0(k)$, and set $z(i,j,k,t) = z_0(k)$. 524 \item[\textit{zps}] 525 set a reference coordinate transformation $z_0(k)$, and calculate the thickness of the deepest level at 526 each $(i,j)$ point using the bathymetry, to obtain the final three-dimensional depth and scale factor arrays. 527 \item[\textit{sco}] 528 smooth the bathymetry to fulfill the hydrostatic consistency criteria and 529 set the three-dimensional transformation. 530 \item[\textit{s-z} and \textit{s-zps}] 531 smooth the bathymetry to fulfill the hydrostatic consistency criteria and 532 set the three-dimensional transformation $z(i,j,k)$, 533 and possibly introduce masking of extra land points to better fit the original bathymetry file. 534 \end{description} 535 %%% 536 \gmcomment{ add the description of the smoothing: envelop topography...} 537 %%% 538 539 Unless a linear free surface is used (\np{ln\_linssh}\forcode{ = .false.}), 540 the arrays describing the grid point depths and vertical scale factors are three set of 541 three dimensional arrays $(i,j,k)$ defined at \textit{before}, \textit{now} and \textit{after} time step. 542 The time at which they are defined is indicated by a suffix: $\_b$, $\_n$, or $\_a$, respectively. 543 They are updated at each model time step using a fixed reference coordinate system which 544 computer names have a $\_0$ suffix. 545 When the linear free surface option is used (\np{ln\_linssh}\forcode{ = .true.}), \textit{before}, 546 \textit{now} and \textit{after} arrays are simply set one for all to their reference counterpart. 547 548 % ------------------------------------------------------------------------------------------------------------- 549 % Meter Bathymetry 550 % ------------------------------------------------------------------------------------------------------------- 551 \subsection{Meter bathymetry} 552 \label{subsec:DOM_bathy} 553 554 Three options are possible for defining the bathymetry, according to the namelist variable \np{nn\_bathy} 555 (found in \ngn{namdom} namelist): 556 \begin{description} 557 \item[\np{nn\_bathy}\forcode{ = 0}]: 558 a flat-bottom domain is defined. 559 The total depth $z_w (jpk)$ is given by the coordinate transformation. 560 The domain can either be a closed basin or a periodic channel depending on the parameter \np{jperio}. 561 \item[\np{nn\_bathy}\forcode{ = -1}]: 562 a domain with a bump of topography one third of the domain width at the central latitude. 563 This is meant for the "EEL-R5" configuration, a periodic or open boundary channel with a seamount. 564 \item[\np{nn\_bathy}\forcode{ = 1}]: 565 read a bathymetry and ice shelf draft (if needed). 566 The \ifile{bathy\_meter} file (Netcdf format) provides the ocean depth (positive, in meters) at 567 each grid point of the model grid. 568 The bathymetry is usually built by interpolating a standard bathymetry product (\eg ETOPO2) onto 569 the horizontal ocean mesh. 570 Defining the bathymetry also defines the coastline: where the bathymetry is zero, 571 no model levels are defined (all levels are masked). 572 573 The \ifile{isfdraft\_meter} file (Netcdf format) provides the ice shelf draft (positive, in meters) at 574 each grid point of the model grid. 575 This file is only needed if \np{ln\_isfcav}\forcode{ = .true.}. 576 Defining the ice shelf draft will also define the ice shelf edge and the grounding line position. 577 \end{description} 578 579 When a global ocean is coupled to an atmospheric model it is better to represent all large water bodies 580 (\eg great lakes, Caspian sea...) even if the model resolution does not allow their communication with 581 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. 582 632 This is unnecessary when the ocean is forced by fixed atmospheric conditions, 583 633 so these seas can be removed from the ocean domain. 584 The user has the option to set the bathymetry in closed seas to zero (see \autoref{sec:MISC_closea}), 585 but the code has to be adapted to the user's configuration. 586 587 % ------------------------------------------------------------------------------------------------------------- 588 % z-coordinate and reference coordinate transformation 589 % ------------------------------------------------------------------------------------------------------------- 590 \subsection[$Z$-coordinate (\forcode{ln_zco = .true.}) and ref. coordinate] 591 {$Z$-coordinate (\protect\np{ln\_zco}\forcode{ = .true.}) and reference coordinate} 592 \label{subsec:DOM_zco} 593 594 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 595 \begin{figure}[!tb] 596 \begin{center} 597 \includegraphics[width=\textwidth]{Fig_zgr} 598 \caption{ 599 \protect\label{fig:zgr} 600 Default vertical mesh for ORCA2: 30 ocean levels (L30). 601 Vertical level functions for (a) T-point depth and (b) the associated scale factor as computed from 602 \autoref{eq:DOM_zgr_ana_1} using \autoref{eq:DOM_zgr_coef} in $z$-coordinate. 603 } 604 \end{center} 605 \end{figure} 606 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 607 608 The reference coordinate transformation $z_0(k)$ defines the arrays $gdept_0$ and $gdepw_0$ for $t$- and $w$-points, 609 respectively. 610 As indicated on \autoref{fig:index_vert} \jp{jpk} is the number of $w$-levels. 611 $gdepw_0(1)$ is the ocean surface. 612 There are at most \jp{jpk}-1 $t$-points inside the ocean, 613 the additional $t$-point at $jk = jpk$ is below the sea floor and is not used. 614 The vertical location of $w$- and $t$-levels is defined from the analytic expression of the depth $z_0(k)$ whose 615 analytical derivative with respect to $k$ provides the vertical scale factors. 616 The user must provide the analytical expression of both $z_0$ and its first derivative with respect to $k$. 617 This is done in routine \mdl{domzgr} through statement functions, 618 using parameters provided in the \ngn{namcfg} namelist. 619 620 It is possible to define a simple regular vertical grid by giving zero stretching (\np{ppacr}\forcode{ = 0}). 621 In that case, the parameters \jp{jpk} (number of $w$-levels) and 622 \np{pphmax} (total ocean depth in meters) fully define the grid. 623 624 For climate-related studies it is often desirable to concentrate the vertical resolution near the ocean surface. 625 The following function is proposed as a standard for a $z$-coordinate (with either full or partial steps): 626 \begin{gather} 627 \label{eq:DOM_zgr_ana_1} 628 z_0 (k) = h_{sur} - h_0 \; k - \; h_1 \; \log \big[ \cosh ((k - h_{th}) / h_{cr}) \big] \\ 629 e_3^0(k) = \lt| - h_0 - h_1 \; \tanh \big[ (k - h_{th}) / h_{cr} \big] \rt| 630 \end{gather} 631 where $k = 1$ to \jp{jpk} for $w$-levels and $k = 1$ to $k = 1$ for $T-$levels. 632 Such an expression allows us to define a nearly uniform vertical location of levels at the ocean top and bottom with 633 a smooth hyperbolic tangent transition in between (\autoref{fig:zgr}). 634 635 If the ice shelf cavities are opened (\np{ln\_isfcav}\forcode{ = .true.}), the definition of $z_0$ is the same. 636 However, definition of $e_3^0$ at $t$- and $w$-points is respectively changed to: 637 \begin{equation} 638 \label{eq:DOM_zgr_ana_2} 639 \begin{split} 640 e_3^T(k) &= z_W (k + 1) - z_W (k ) \\ 641 e_3^W(k) &= z_T (k ) - z_T (k - 1) 642 \end{split} 643 \end{equation} 644 This formulation decrease the self-generated circulation into the ice shelf cavity 645 (which can, in extreme case, leads to blow up).\\ 646 647 The most used vertical grid for ORCA2 has $10~m$ ($500~m$) resolution in the surface (bottom) layers and 648 a depth which varies from 0 at the sea surface to a minimum of $-5000~m$. 649 This leads to the following conditions: 650 \begin{equation} 651 \label{eq:DOM_zgr_coef} 652 \begin{array}{ll} 653 e_3 (1 + 1/2) = 10. & z(1 ) = 0. \\ 654 e_3 (jpk - 1/2) = 500. & z(jpk) = -5000. 655 \end{array} 656 \end{equation} 657 658 With the choice of the stretching $h_{cr} = 3$ and the number of levels \jp{jpk}~$= 31$, 659 the four coefficients $h_{sur}$, $h_0$, $h_1$, and $h_{th}$ in 660 \autoref{eq:DOM_zgr_ana_2} have been determined such that 661 \autoref{eq:DOM_zgr_coef} is satisfied, through an optimisation procedure using a bisection method. 662 For the first standard ORCA2 vertical grid this led to the following values: 663 $h_{sur} = 4762.96$, $h_0 = 255.58, h_1 = 245.5813$, and $h_{th} = 21.43336$. 664 The resulting depths and scale factors as a function of the model levels are shown in 665 \autoref{fig:zgr} and given in \autoref{tab:orca_zgr}. 666 Those values correspond to the parameters \np{ppsur}, \np{ppa0}, \np{ppa1}, \np{ppkth} in \ngn{namcfg} namelist. 667 668 Rather than entering parameters $h_{sur}$, $h_0$, and $h_1$ directly, it is possible to recalculate them. 669 In that case the user sets \np{ppsur}~$=$~\np{ppa0}~$=$~\np{ppa1}~$= 999999$., 670 in \ngn{namcfg} namelist, and specifies instead the four following parameters: 671 \begin{itemize} 672 \item 673 \np{ppacr}~$= h_{cr}$: stretching factor (nondimensional). 674 The larger \np{ppacr}, the smaller the stretching. 675 Values from $3$ to $10$ are usual. 676 \item 677 \np{ppkth}~$= h_{th}$: is approximately the model level at which maximum stretching occurs 678 (nondimensional, usually of order 1/2 or 2/3 of \jp{jpk}) 679 \item 680 \np{ppdzmin}: minimum thickness for the top layer (in meters). 681 \item 682 \np{pphmax}: total depth of the ocean (meters). 683 \end{itemize} 684 As an example, for the $45$ layers used in the DRAKKAR configuration those parameters are: 685 \jp{jpk}~$= 46$, \np{ppacr}~$= 9$, \np{ppkth}~$= 23.563$, \np{ppdzmin}~$= 6~m$, \np{pphmax}~$= 5750~m$. 686 687 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 688 \begin{table} 689 \begin{center} 690 \begin{tabular}{c||r|r|r|r} 691 \hline 692 \textbf{LEVEL} & \textbf{gdept\_1d} & \textbf{gdepw\_1d} & \textbf{e3t\_1d } & \textbf{e3w\_1d} \\ 693 \hline 694 1 & \textbf{ 5.00} & 0.00 & \textbf{ 10.00} & 10.00 \\ 695 \hline 696 2 & \textbf{ 15.00} & 10.00 & \textbf{ 10.00} & 10.00 \\ 697 \hline 698 3 & \textbf{ 25.00} & 20.00 & \textbf{ 10.00} & 10.00 \\ 699 \hline 700 4 & \textbf{ 35.01} & 30.00 & \textbf{ 10.01} & 10.00 \\ 701 \hline 702 5 & \textbf{ 45.01} & 40.01 & \textbf{ 10.01} & 10.01 \\ 703 \hline 704 6 & \textbf{ 55.03} & 50.02 & \textbf{ 10.02} & 10.02 \\ 705 \hline 706 7 & \textbf{ 65.06} & 60.04 & \textbf{ 10.04} & 10.03 \\ 707 \hline 708 8 & \textbf{ 75.13} & 70.09 & \textbf{ 10.09} & 10.06 \\ 709 \hline 710 9 & \textbf{ 85.25} & 80.18 & \textbf{ 10.17} & 10.12 \\ 711 \hline 712 10 & \textbf{ 95.49} & 90.35 & \textbf{ 10.33} & 10.24 \\ 713 \hline 714 11 & \textbf{ 105.97} & 100.69 & \textbf{ 10.65} & 10.47 \\ 715 \hline 716 12 & \textbf{ 116.90} & 111.36 & \textbf{ 11.27} & 10.91 \\ 717 \hline 718 13 & \textbf{ 128.70} & 122.65 & \textbf{ 12.47} & 11.77 \\ 719 \hline 720 14 & \textbf{ 142.20} & 135.16 & \textbf{ 14.78} & 13.43 \\ 721 \hline 722 15 & \textbf{ 158.96} & 150.03 & \textbf{ 19.23} & 16.65 \\ 723 \hline 724 16 & \textbf{ 181.96} & 169.42 & \textbf{ 27.66} & 22.78 \\ 725 \hline 726 17 & \textbf{ 216.65} & 197.37 & \textbf{ 43.26} & 34.30 \\ 727 \hline 728 18 & \textbf{ 272.48} & 241.13 & \textbf{ 70.88} & 55.21 \\ 729 \hline 730 19 & \textbf{ 364.30} & 312.74 & \textbf{ 116.11} & 90.99 \\ 731 \hline 732 20 & \textbf{ 511.53} & 429.72 & \textbf{ 181.55} & 146.43 \\ 733 \hline 734 21 & \textbf{ 732.20} & 611.89 & \textbf{ 261.03} & 220.35 \\ 735 \hline 736 22 & \textbf{ 1033.22} & 872.87 & \textbf{ 339.39} & 301.42 \\ 737 \hline 738 23 & \textbf{ 1405.70} & 1211.59 & \textbf{ 402.26} & 373.31 \\ 739 \hline 740 24 & \textbf{ 1830.89} & 1612.98 & \textbf{ 444.87} & 426.00 \\ 741 \hline 742 25 & \textbf{ 2289.77} & 2057.13 & \textbf{ 470.55} & 459.47 \\ 743 \hline 744 26 & \textbf{ 2768.24} & 2527.22 & \textbf{ 484.95} & 478.83 \\ 745 \hline 746 27 & \textbf{ 3257.48} & 3011.90 & \textbf{ 492.70} & 489.44 \\ 747 \hline 748 28 & \textbf{ 3752.44} & 3504.46 & \textbf{ 496.78} & 495.07 \\ 749 \hline 750 29 & \textbf{ 4250.40} & 4001.16 & \textbf{ 498.90} & 498.02 \\ 751 \hline 752 30 & \textbf{ 4749.91} & 4500.02 & \textbf{ 500.00} & 499.54 \\ 753 \hline 754 31 & \textbf{ 5250.23} & 5000.00 & \textbf{ 500.56} & 500.33 \\ 755 \hline 756 \end{tabular} 757 \end{center} 758 \caption{ 759 \protect\label{tab:orca_zgr} 760 Default vertical mesh in $z$-coordinate for 30 layers ORCA2 configuration as computed from 761 \autoref{eq:DOM_zgr_ana_2} using the coefficients given in \autoref{eq:DOM_zgr_coef} 762 } 763 \end{table} 764 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 765 766 % ------------------------------------------------------------------------------------------------------------- 767 % z-coordinate with partial step 768 % ------------------------------------------------------------------------------------------------------------- 769 \subsection[$Z$-coordinate with partial step (\forcode{ln_zps = .true.})] 770 {$Z$-coordinate with partial step (\protect\np{ln\_zps}\forcode{ = .true.})} 771 \label{subsec:DOM_zps} 772 %--------------------------------------------namdom------------------------------------------------------- 773 774 \nlst{namdom} 775 %-------------------------------------------------------------------------------------------------------------- 776 777 In $z$-coordinate partial step, 778 the depths of the model levels are defined by the reference analytical function $z_0(k)$ as described in 779 the previous section, \textit{except} in the bottom layer. 780 The thickness of the bottom layer is allowed to vary as a function of geographical location $(\lambda,\varphi)$ to 781 allow a better representation of the bathymetry, especially in the case of small slopes 782 (where the bathymetry varies by less than one level thickness from one grid point to the next). 783 The reference layer thicknesses $e_{3t}^0$ have been defined in the absence of bathymetry. 784 With partial steps, layers from 1 to \jp{jpk}-2 can have a thickness smaller than $e_{3t}(jk)$. 785 The model deepest layer (\jp{jpk}-1) is allowed to have either a smaller or larger thickness than $e_{3t}(jpk)$: 786 the maximum thickness allowed is $2*e_{3t}(jpk - 1)$. 787 This has to be kept in mind when specifying values in \ngn{namdom} namelist, 788 as the maximum depth \np{pphmax} in partial steps: 789 for example, with \np{pphmax}~$= 5750~m$ for the DRAKKAR 45 layer grid, 790 the maximum ocean depth allowed is actually $6000~m$ (the default thickness $e_{3t}(jpk - 1)$ being $250~m$). 791 Two variables in the namdom namelist are used to define the partial step vertical grid. 792 The mimimum water thickness (in meters) allowed for a cell partially filled with bathymetry at level jk is 793 the minimum of \np{rn\_e3zps\_min} (thickness in meters, usually $20~m$) or $e_{3t}(jk)*$\np{rn\_e3zps\_rat} 794 (a fraction, usually 10\%, of the default thickness $e_{3t}(jk)$). 795 796 \gmcomment{ \colorbox{yellow}{Add a figure here of pstep especially at last ocean level } } 797 798 % ------------------------------------------------------------------------------------------------------------- 799 % s-coordinate 800 % ------------------------------------------------------------------------------------------------------------- 801 \subsection[$S$-coordinate (\forcode{ln_sco = .true.})] 802 {$S$-coordinate (\protect\np{ln\_sco}\forcode{ = .true.})} 803 \label{subsec:DOM_sco} 804 %------------------------------------------nam_zgr_sco--------------------------------------------------- 805 % 806 %\nlst{namzgr_sco} 807 %-------------------------------------------------------------------------------------------------------------- 808 Options are defined in \ngn{namzgr\_sco}. 809 In $s$-coordinate (\np{ln\_sco}\forcode{ = .true.}), the depth and thickness of the model levels are defined from 810 the product of a depth field and either a stretching function or its derivative, respectively: 811 812 \begin{align*} 813 % \label{eq:DOM_sco_ana} 814 z(k) &= h(i,j) \; z_0 (k) \\ 815 e_3(k) &= h(i,j) \; z_0'(k) 816 \end{align*} 817 818 where $h$ is the depth of the last $w$-level ($z_0(k)$) defined at the $t$-point location in the horizontal and 819 $z_0(k)$ is a function which varies from $0$ at the sea surface to $1$ at the ocean bottom. 820 The depth field $h$ is not necessary the ocean depth, 821 since a mixed step-like and bottom-following representation of the topography can be used 822 (\autoref{fig:z_zps_s_sps}) or an envelop bathymetry can be defined (\autoref{fig:z_zps_s_sps}). 823 The namelist parameter \np{rn\_rmax} determines the slope at which 824 the terrain-following coordinate intersects the sea bed and becomes a pseudo z-coordinate. 825 The coordinate can also be hybridised by specifying \np{rn\_sbot\_min} and \np{rn\_sbot\_max} as 826 the minimum and maximum depths at which the terrain-following vertical coordinate is calculated. 827 828 Options for stretching the coordinate are provided as examples, 829 but care must be taken to ensure that the vertical stretch used is appropriate for the application. 830 831 The original default NEMO s-coordinate stretching is available if neither of the other options are specified as true 832 (\np{ln\_s\_SH94}\forcode{ = .false.} and \np{ln\_s\_SF12}\forcode{ = .false.}). 833 This uses a depth independent $\tanh$ function for the stretching \citep{madec.delecluse.ea_JPO96}: 834 835 \[ 836 z = s_{min} + C (s) (H - s_{min}) 837 % \label{eq:SH94_1} 838 \] 839 840 where $s_{min}$ is the depth at which the $s$-coordinate stretching starts and 841 allows a $z$-coordinate to placed on top of the stretched coordinate, 842 and $z$ is the depth (negative down from the asea surface). 843 \begin{gather*} 844 s = - \frac{k}{n - 1} \quad \text{and} \quad 0 \leq k \leq n - 1 845 % \label{eq:DOM_s} 846 \\ 847 % \label{eq:DOM_sco_function} 848 C(s) = \frac{[\tanh(\theta \, (s + b)) - \tanh(\theta \, b)]}{2 \; \sinh(\theta)} 849 \end{gather*} 850 851 A stretching function, 852 modified from the commonly used \citet{song.haidvogel_JCP94} stretching (\np{ln\_s\_SH94}\forcode{ = .true.}), 853 is also available and is more commonly used for shelf seas modelling: 854 855 \[ 856 C(s) = (1 - b) \frac{\sinh(\theta s)}{\sinh(\theta)} 857 + b \frac{\tanh \lt[ \theta \lt(s + \frac{1}{2} \rt) \rt] - \tanh \lt( \frac{\theta}{2} \rt)} 858 { 2 \tanh \lt( \frac{\theta}{2} \rt)} 859 % \label{eq:SH94_2} 860 \] 861 862 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 863 \begin{figure}[!ht] 864 \begin{center} 865 \includegraphics[width=\textwidth]{Fig_sco_function} 866 \caption{ 867 \protect\label{fig:sco_function} 868 Examples of the stretching function applied to a seamount; 869 from left to right: surface, surface and bottom, and bottom intensified resolutions 870 } 871 \end{center} 872 \end{figure} 873 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 874 875 where $H_c$ is the critical depth (\np{rn\_hc}) at which the coordinate transitions from pure $\sigma$ to 876 the stretched coordinate, and $\theta$ (\np{rn\_theta}) and $b$ (\np{rn\_bb}) are the surface and 877 bottom control parameters such that $0 \leqslant \theta \leqslant 20$, and $0 \leqslant b \leqslant 1$. 878 $b$ has been designed to allow surface and/or bottom increase of the vertical resolution 879 (\autoref{fig:sco_function}). 880 881 Another example has been provided at version 3.5 (\np{ln\_s\_SF12}) that allows a fixed surface resolution in 882 an analytical terrain-following stretching \citet{siddorn.furner_OM13}. 883 In this case the a stretching function $\gamma$ is defined such that: 884 885 \begin{equation} 886 z = - \gamma h \quad \text{with} \quad 0 \leq \gamma \leq 1 887 % \label{eq:z} 888 \end{equation} 889 890 The function is defined with respect to $\sigma$, the unstretched terrain-following coordinate: 891 892 \begin{gather*} 893 % \label{eq:DOM_gamma_deriv} 894 \gamma = A \lt( \sigma - \frac{1}{2} (\sigma^2 + f (\sigma)) \rt) 895 + B \lt( \sigma^3 - f (\sigma) \rt) + f (\sigma) \\ 896 \intertext{Where:} 897 % \label{eq:DOM_gamma} 898 f(\sigma) = (\alpha + 2) \sigma^{\alpha + 1} - (\alpha + 1) \sigma^{\alpha + 2} 899 \quad \text{and} \quad \sigma = \frac{k}{n - 1} 900 \end{gather*} 901 902 This gives an analytical stretching of $\sigma$ that is solvable in $A$ and $B$ as a function of 903 the user prescribed stretching parameter $\alpha$ (\np{rn\_alpha}) that stretches towards 904 the surface ($\alpha > 1.0$) or the bottom ($\alpha < 1.0$) and 905 user prescribed surface (\np{rn\_zs}) and bottom depths. 906 The bottom cell depth in this example is given as a function of water depth: 907 908 \[ 909 % \label{eq:DOM_zb} 910 Z_b = h a + b 911 \] 912 913 where the namelist parameters \np{rn\_zb\_a} and \np{rn\_zb\_b} are $a$ and $b$ respectively. 914 915 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 916 \begin{figure}[!ht] 917 \includegraphics[width=\textwidth]{Fig_DOM_compare_coordinates_surface} 918 \caption{ 919 A comparison of the \citet{song.haidvogel_JCP94} $S$-coordinate (solid lines), 920 a 50 level $Z$-coordinate (contoured surfaces) and 921 the \citet{siddorn.furner_OM13} $S$-coordinate (dashed lines) in the surface $100~m$ for 922 a idealised bathymetry that goes from $50~m$ to $5500~m$ depth. 923 For clarity every third coordinate surface is shown. 924 } 925 \label{fig:fig_compare_coordinates_surface} 926 \end{figure} 927 % >>>>>>>>>>>>>>>>>>>>>>>>>>>> 928 929 This gives a smooth analytical stretching in computational space that is constrained to 930 given specified surface and bottom grid cell thicknesses in real space. 931 This is not to be confused with the hybrid schemes that 932 superimpose geopotential coordinates on terrain following coordinates thus 933 creating a non-analytical vertical coordinate that 934 therefore may suffer from large gradients in the vertical resolutions. 935 This stretching is less straightforward to implement than the \citet{song.haidvogel_JCP94} stretching, 936 but has the advantage of resolving diurnal processes in deep water and has generally flatter slopes. 937 938 As with the \citet{song.haidvogel_JCP94} stretching the stretch is only applied at depths greater than 939 the critical depth $h_c$. 940 In this example two options are available in depths shallower than $h_c$, 941 with pure sigma being applied if the \np{ln\_sigcrit} is true and pure z-coordinates if it is false 942 (the z-coordinate being equal to the depths of the stretched coordinate at $h_c$). 943 944 Minimising the horizontal slope of the vertical coordinate is important in terrain-following systems as 945 large slopes lead to hydrostatic consistency. 946 A hydrostatic consistency parameter diagnostic following \citet{haney_JPO91} has been implemented, 947 and is output as part of the model mesh file at the start of the run. 948 949 % ------------------------------------------------------------------------------------------------------------- 950 % z*- or s*-coordinate 951 % ------------------------------------------------------------------------------------------------------------- 952 \subsection[\zstar- or \sstar-coordinate (\forcode{ln_linssh = .false.})] 953 {\zstar- or \sstar-coordinate (\protect\np{ln\_linssh}\forcode{ = .false.})} 954 \label{subsec:DOM_zgr_star} 955 956 This option is described in the Report by Levier \textit{et al.} (2007), available on the \NEMO web site. 957 958 %gm% key advantage: minimise the diffusion/dispertion associated with advection in response to high frequency surface disturbances 959 960 % ------------------------------------------------------------------------------------------------------------- 961 % level bathymetry and mask 962 % ------------------------------------------------------------------------------------------------------------- 963 \subsection{Level bathymetry and mask} 964 \label{subsec:DOM_msk} 965 966 Whatever the vertical coordinate used, the model offers the possibility of representing the bottom topography with 967 steps that follow the face of the model cells (step like topography) \citep{madec.delecluse.ea_JPO96}. 968 The distribution of the steps in the horizontal is defined in a 2D integer array, mbathy, which 969 gives the number of ocean levels (\ie those that are not masked) at each $t$-point. 970 mbathy is computed from the meter bathymetry using the definiton of gdept as the number of $t$-points which 971 gdept $\leq$ bathy. 972 973 Modifications of the model bathymetry are performed in the \textit{bat\_ctl} routine (see \mdl{domzgr} module) after 974 mbathy is computed. 975 Isolated grid points that do not communicate with another ocean point at the same level are eliminated. 976 977 As for the representation of bathymetry, a 2D integer array, misfdep, is created. 978 misfdep defines the level of the first wet $t$-point. 979 All the cells between $k = 1$ and $misfdep(i,j) - 1$ are masked. 980 By default, $misfdep(:,:) = 1$ and no cells are masked. 981 982 In case of ice shelf cavities, modifications of the model bathymetry and ice shelf draft into 983 the cavities are performed in the \textit{zgr\_isf} routine. 984 The compatibility between ice shelf draft and bathymetry is checked. 985 All the locations where the isf cavity is thinnest than \np{rn\_isfhmin} meters are grounded (\ie masked). 986 If only one cell on the water column is opened at $t$-, $u$- or $v$-points, 987 the bathymetry or the ice shelf draft is dug to fit this constrain. 988 If the incompatibility is too strong (need to dig more than 1 cell), the cell is masked. 989 990 From the \textit{mbathy} and \textit{misfdep} array, the mask fields are defined as follows: 991 \begin{alignat*}{2} 992 tmask(i,j,k) &= & & 993 \begin{cases} 994 0 &\text{if $ k < misfdep(i,j)$} \\ 995 1 &\text{if $misfdep(i,j) \leq k \leq mbathy(i,j)$} \\ 996 0 &\text{if $ k > mbathy(i,j)$} 997 \end{cases} 998 \\ 999 umask(i,j,k) &= & &tmask(i,j,k) * tmask(i + 1,j, k) \\ 1000 vmask(i,j,k) &= & &tmask(i,j,k) * tmask(i ,j + 1,k) \\ 1001 fmask(i,j,k) &= & &tmask(i,j,k) * tmask(i + 1,j, k) \\ 1002 & &* &tmask(i,j,k) * tmask(i + 1,j, k) \\ 1003 wmask(i,j,k) &= & &tmask(i,j,k) * tmask(i ,j,k - 1) \\ 1004 \text{with~} wmask(i,j,1) &= & &tmask(i,j,1) 1005 \end{alignat*} 1006 1007 Note that, without ice shelves cavities, 1008 masks at $t-$ and $w-$points are identical with the numerical indexing used (\autoref{subsec:DOM_Num_Index}). 1009 Nevertheless, $wmask$ are required with ocean cavities to deal with the top boundary (ice shelf/ocean interface) 1010 exactly in the same way as for the bottom boundary. 1011 1012 The specification of closed lateral boundaries requires that at least 1013 the first and last rows and columns of the \textit{mbathy} array are set to zero. 1014 In the particular case of an east-west cyclical boundary condition, \textit{mbathy} has its last column equal to 1015 the second one and its first column equal to the last but one (and so too the mask arrays) 1016 (see \autoref{fig:LBC_jperio}). 1017 1018 % ================================================================ 1019 % Domain: Initial State (dtatsd & istate) 1020 % ================================================================ 1021 \section[Initial state (\textit{istate.F90} and \textit{dtatsd.F90})] 1022 {Initial state (\protect\mdl{istate} and \protect\mdl{dtatsd})} 1023 \label{sec:DTA_tsd} 1024 %-----------------------------------------namtsd------------------------------------------- 1025 1026 \nlst{namtsd} 1027 %------------------------------------------------------------------------------------------ 1028 1029 Options are defined in \ngn{namtsd}. 1030 By default, the ocean start from rest (the velocity field is set to zero) and the initialization of temperature and 1031 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 1032 682 \begin{description} 1033 \item [\np{ln\_tsd\_init}\forcode{ = .true.}]1034 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. 1035 685 In the latter case, 1036 686 the data will be interpolated on-the-fly both in the horizontal and the vertical to the model grid 1037 687 (see \autoref{subsec:SBC_iof}). 1038 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. 1039 690 The computation is done in the \mdl{dtatsd} module. 1040 \item[\np{ln\_tsd\_init}\forcode{ = .false.}] 1041 use constant salinity value of $35.5~psu$ and an analytical profile of temperature 1042 (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}). 1043 695 \end{description} 1044 696 1045 \biblio 1046 1047 \pindex 697 \subinc{\input{../../global/epilogue}} 1048 698 1049 699 \end{document} -
NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_DYN.tex
r11187 r12149 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 (\textit{divcur.F90})] 68 {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})} 69 78 \label{subsec:DYN_divcur} 70 79 71 The vorticity is defined at an $f$-point (\ie corner point) as follows:72 \begin{equation} 73 \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} 74 83 \zeta =\frac{1}{e_{1f}\,e_{2f} }\left( {\;\delta_{i+1/2} \left[ {e_{2v}\;v} \right] 75 84 -\delta_{j+1/2} \left[ {e_{1u}\;u} \right]\;} \right) 76 \end{equation} 85 \end{equation} 77 86 78 87 The horizontal divergence is defined at a $T$-point. 79 88 It is given by: 80 89 \[ 81 % \label{eq: divcur_div}90 % \label{eq:DYN_divcur_div} 82 91 \chi =\frac{1}{e_{1t}\,e_{2t}\,e_{3t} } 83 92 \left( {\delta_i \left[ {e_{2u}\,e_{3u}\,u} \right] … … 97 106 ensure perfect restartability. 98 107 The vorticity and divergence at the \textit{now} time step are used for the computation of 99 the nonlinear advection and of the vertical velocity respectively. 100 101 %-------------------------------------------------------------------------------------------------------------- 102 % Sea Surface Height evolution 103 %-------------------------------------------------------------------------------------------------------------- 104 \subsection[Horizontal divergence and relative vorticity (\textit{sshwzv.F90})] 105 {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})} 106 112 \label{subsec:DYN_sshwzv} 107 113 108 114 The sea surface height is given by: 109 115 \begin{equation} 110 \label{eq: dynspg_ssh}116 \label{eq:DYN_spg_ssh} 111 117 \begin{aligned} 112 118 \frac{\partial \eta }{\partial t} … … 117 123 \end{aligned} 118 124 \end{equation} 119 where \textit{emp} is the surface freshwater budget (evaporation minus precipitation), 125 where \textit{emp} is the surface freshwater budget (evaporation minus precipitation), 120 126 expressed in Kg/m$^2$/s (which is equal to mm/s), 121 127 and $\rho_w$=1,035~Kg/m$^3$ is the reference density of sea water (Boussinesq approximation). 122 128 If river runoff is expressed as a surface freshwater flux (see \autoref{chap:SBC}) then 123 \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. 124 130 The sea-surface height is evaluated using exactly the same time stepping scheme as 125 the tracer equation \autoref{eq: tra_nxt}:131 the tracer equation \autoref{eq:TRA_nxt}: 126 132 a leapfrog scheme in combination with an Asselin time filter, 127 \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). 128 134 This is of paramount importance. 129 135 Replacing $T$ by the number $1$ in the tracer equation and summing over the water column must lead to … … 134 140 taking into account the change of the thickness of the levels: 135 141 \begin{equation} 136 \label{eq: wzv}142 \label{eq:DYN_wzv} 137 143 \left\{ 138 144 \begin{aligned} … … 144 150 \end{equation} 145 151 146 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$, 147 153 as changes in the divergence of the barotropic transport are absorbed into the change of the level thicknesses, 148 154 re-orientated downward. 149 \ gmcomment{not sure of this... to be modified with the change in emp setting}150 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. 151 157 The upper boundary condition applies at a fixed level $z=0$. 152 158 The top vertical velocity is thus equal to the divergence of the barotropic transport 153 (\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}). 154 160 155 161 Note also that whereas the vertical velocity has the same discrete expression in $z$- and $s$-coordinates, 156 162 its physical meaning is not the same: 157 163 in the second case, $w$ is the velocity normal to the $s$-surfaces. 158 Note also that the $k$-axis is re-orientated downwards in the \fortran code compared to 159 the indexing used in the semi-discrete equations such as \autoref{eq:wzv} 160 (see \autoref{subsec:DOM_Num_Index_vertical}). 161 162 163 % ================================================================ 164 % Coriolis and Advection terms: vector invariant form 165 % ================================================================ 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 %% ================================================================================================= 166 169 \section{Coriolis and advection: vector invariant form} 167 170 \label{sec:DYN_adv_cor_vect} 168 %-----------------------------------------nam_dynadv---------------------------------------------------- 169 170 \nlst{namdyn_adv} 171 %------------------------------------------------------------------------------------------------------------- 171 172 \begin{listing} 173 \nlst{namdyn_adv} 174 \caption{\forcode{&namdyn_adv}} 175 \label{lst:namdyn_adv} 176 \end{listing} 172 177 173 178 The vector invariant form of the momentum equations is the one most often used in 174 applications of the \NEMO ocean model.179 applications of the \NEMO\ ocean model. 175 180 The flux form option (see next section) has been present since version $2$. 176 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 177 182 momentum advection terms are evaluated using a leapfrog scheme, 178 \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). 179 184 At the lateral boundaries either free slip, no slip or partial slip boundary conditions are applied following 180 185 \autoref{chap:LBC}. 181 186 182 % ------------------------------------------------------------------------------------------------------------- 183 % Vorticity term 184 % ------------------------------------------------------------------------------------------------------------- 185 \subsection[Vorticity term (\textit{dynvor.F90})] 186 {Vorticity term (\protect\mdl{dynvor})} 187 %% ================================================================================================= 188 \subsection[Vorticity term (\textit{dynvor.F90})]{Vorticity term (\protect\mdl{dynvor})} 187 189 \label{subsec:DYN_vor} 188 %------------------------------------------nam_dynvor---------------------------------------------------- 189 190 \nlst{namdyn_vor} 191 %------------------------------------------------------------------------------------------------------------- 192 193 Options are defined through the \ngn{namdyn\_vor} namelist variables. 194 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: 195 199 conserving potential enstrophy of horizontally non-divergent flow (ENS scheme); 196 200 conserving horizontal kinetic energy (ENE scheme); … … 198 202 horizontal kinetic energy for the planetary vorticity term (MIX scheme); 199 203 or conserving both the potential enstrophy of horizontally non-divergent flow and horizontal kinetic energy 200 (EEN scheme) (see \autoref{subsec: C_vorEEN}).204 (EEN scheme) (see \autoref{subsec:INVARIANTS_vorEEN}). 201 205 In the case of ENS, ENE or MIX schemes the land sea mask may be slightly modified to ensure the consistency of 202 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}). 203 207 The vorticity terms are all computed in dedicated routines that can be found in the \mdl{dynvor} module. 204 208 205 %-------------------------------------------------------------206 209 % enstrophy conserving scheme 207 %------------------------------------------------------------- 208 \subsubsection[Enstrophy conserving scheme (\forcode{ln_dynvor_ens = .true.})] 209 {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})} 210 212 \label{subsec:DYN_vor_ens} 211 213 212 214 In the enstrophy conserving case (ENS scheme), 213 215 the discrete formulation of the vorticity term provides a global conservation of the enstrophy 214 ($ [ (\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$), 215 217 but does not conserve the total kinetic energy. 216 218 It is given by: 217 219 \begin{equation} 218 \label{eq: dynvor_ens}220 \label{eq:DYN_vor_ens} 219 221 \left\{ 220 222 \begin{aligned} … … 225 227 \end{aligned} 226 228 \right. 227 \end{equation} 228 229 %------------------------------------------------------------- 229 \end{equation} 230 230 231 % energy conserving scheme 231 %------------------------------------------------------------- 232 \subsubsection[Energy conserving scheme (\forcode{ln_dynvor_ene = .true.})] 233 {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})} 234 234 \label{subsec:DYN_vor_ene} 235 235 … … 237 237 It is given by: 238 238 \begin{equation} 239 \label{eq: dynvor_ene}239 \label{eq:DYN_vor_ene} 240 240 \left\{ 241 241 \begin{aligned} … … 246 246 \end{aligned} 247 247 \right. 248 \end{equation} 249 250 %------------------------------------------------------------- 248 \end{equation} 249 251 250 % mix energy/enstrophy conserving scheme 252 %------------------------------------------------------------- 253 \subsubsection[Mixed energy/enstrophy conserving scheme (\forcode{ln_dynvor_mix = .true.})] 254 {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})} 255 253 \label{subsec:DYN_vor_mix} 256 254 257 255 For the mixed energy/enstrophy conserving scheme (MIX scheme), a mixture of the two previous schemes is used. 258 It consists of the ENS scheme (\autoref{eq: dynvor_ens}) for the relative vorticity term,259 and of the ENE scheme (\autoref{eq: dynvor_ene}) applied to the planetary vorticity term.260 \[ 261 % \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} 262 260 \left\{ { 263 261 \begin{aligned} … … 274 272 \] 275 273 276 %-------------------------------------------------------------277 274 % energy and enstrophy conserving scheme 278 %------------------------------------------------------------- 279 \subsubsection[Energy and enstrophy conserving scheme (\forcode{ln_dynvor_een = .true.})] 280 {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})} 281 277 \label{subsec:DYN_vor_een} 282 278 … … 285 281 the presence of grid point oscillation structures that will be invisible to the operator. 286 282 These structures are \textit{computational modes} that will be at least partly damped by 287 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. 288 284 The ENS and ENE schemes therefore do not contribute to dump any grid point noise in the horizontal velocity field. 289 285 Such noise would result in more noise in the vertical velocity field, an undesirable feature. … … 291 287 $u$ and $v$ are located at different grid points, 292 288 a price worth paying to avoid a double averaging in the pressure gradient term as in the $B$-grid. 293 \ gmcomment{ To circumvent this, Adcroft (ADD REF HERE)289 \cmtgm{ To circumvent this, Adcroft (ADD REF HERE) 294 290 Nevertheless, this technique strongly distort the phase and group velocity of Rossby waves....} 295 291 … … 297 293 The idea is to get rid of the double averaging by considering triad combinations of vorticity. 298 294 It is noteworthy that this solution is conceptually quite similar to the one proposed by 299 \citep{griffies.gnanadesikan.ea_JPO98} for the discretization of the iso-neutral diffusion operator (see \autoref{apdx: C}).300 301 The \citet{arakawa.hsu_MWR90} vorticity advection scheme for a single layer is modified 302 for spherical coordinates as described by \citet{arakawa.lamb_MWR81} to obtain the EEN scheme. 303 First consider the discrete expression of the potential vorticity, $q$, defined at an $f$-point: 304 \[ 305 % \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} 306 302 q = \frac{\zeta +f} {e_{3f} } 307 303 \] 308 where the relative vorticity is defined by (\autoref{eq: divcur_cur}),309 the Coriolis parameter is given by $f=2 \,\Omega \;\sin \varphi _f $ and the layer thickness at $f$-points is: 310 \begin{equation} 311 \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} 312 308 e_{3f} = \overline{\overline {e_{3t} }} ^{\,i+1/2,j+1/2} 313 309 \end{equation} 314 310 315 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>316 311 \begin{figure}[!ht] 317 \begin{center} 318 \includegraphics[width=\textwidth]{Fig_DYN_een_triad} 319 \caption{ 320 \protect\label{fig:DYN_een_triad} 321 Triads used in the energy and enstrophy conserving scheme (een) for 322 $u$-component (upper panel) and $v$-component (lower panel). 323 } 324 \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} 325 318 \end{figure} 326 % >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 327 328 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. 329 321 It uses the sum of masked t-point vertical scale factor divided either by the sum of the four t-point masks 330 (\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}). 331 323 The latter case preserves the continuity of $e_{3f}$ when one or more of the neighbouring $e_{3t}$ tends to zero and 332 324 extends by continuity the value of $e_{3f}$ into the land areas. … … 334 326 (with a systematic reduction of $e_{3f}$ when a model level intercept the bathymetry) 335 327 that tends to reinforce the topostrophy of the flow 336 (\ie the tendency of the flow to follow the isobaths) \citep{penduff.le-sommer.ea_OS07}.328 (\ie\ the tendency of the flow to follow the isobaths) \citep{penduff.le-sommer.ea_OS07}. 337 329 338 330 Next, the vorticity triads, $ {^i_j}\mathbb{Q}^{i_p}_{j_p}$ can be defined at a $T$-point as 339 331 the following triad combinations of the neighbouring potential vorticities defined at f-points 340 (\autoref{fig:DYN_een_triad}): 341 \begin{equation} 342 \label{eq: Q_triads}332 (\autoref{fig:DYN_een_triad}): 333 \begin{equation} 334 \label{eq:DYN_Q_triads} 343 335 _i^j \mathbb{Q}^{i_p}_{j_p} 344 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) 345 337 \end{equation} 346 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$. 347 348 Finally, the vorticity terms are represented as: 349 \begin{equation} 350 \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} 351 343 \left\{ { 352 344 \begin{aligned} … … 357 349 \end{aligned} 358 350 } \right. 359 \end{equation} 351 \end{equation} 360 352 361 353 This EEN scheme in fact combines the conservation properties of the ENS and ENE schemes. 362 354 It conserves both total energy and potential enstrophy in the limit of horizontally nondivergent flow 363 (\ie $\chi$=$0$) (see \autoref{subsec:C_vorEEN}).355 (\ie\ $\chi$=$0$) (see \autoref{subsec:INVARIANTS_vorEEN}). 364 356 Applied to a realistic ocean configuration, it has been shown that it leads to a significant reduction of 365 357 the noise in the vertical velocity field \citep{le-sommer.penduff.ea_OM09}. 366 358 Furthermore, used in combination with a partial steps representation of bottom topography, 367 359 it improves the interaction between current and topography, 368 leading to a larger topostrophy of the flow \citep{barnier.madec.ea_OD06, penduff.le-sommer.ea_OS07}. 369 370 %-------------------------------------------------------------------------------------------------------------- 371 % Kinetic Energy Gradient term 372 %-------------------------------------------------------------------------------------------------------------- 373 \subsection[Kinetic energy gradient term (\textit{dynkeg.F90})] 374 {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})} 375 364 \label{subsec:DYN_keg} 376 365 377 As demonstrated in \autoref{apdx: C},366 As demonstrated in \autoref{apdx:INVARIANTS}, 378 367 there is a single discrete formulation of the kinetic energy gradient term that, 379 368 together with the formulation chosen for the vertical advection (see below), 380 369 conserves the total kinetic energy: 381 370 \[ 382 % \label{eq: dynkeg}371 % \label{eq:DYN_keg} 383 372 \left\{ 384 373 \begin{aligned} … … 389 378 \] 390 379 391 %-------------------------------------------------------------------------------------------------------------- 392 % Vertical advection term 393 %-------------------------------------------------------------------------------------------------------------- 394 \subsection[Vertical advection term (\textit{dynzad.F90})] 395 {Vertical advection term (\protect\mdl{dynzad})} 380 %% ================================================================================================= 381 \subsection[Vertical advection term (\textit{dynzad.F90})]{Vertical advection term (\protect\mdl{dynzad})} 396 382 \label{subsec:DYN_zad} 397 383 … … 400 386 conserves the total kinetic energy. 401 387 Indeed, the change of KE due to the vertical advection is exactly balanced by 402 the change of KE due to the gradient of KE (see \autoref{apdx: C}).403 \[ 404 % \label{eq: dynzad}388 the change of KE due to the gradient of KE (see \autoref{apdx:INVARIANTS}). 389 \[ 390 % \label{eq:DYN_zad} 405 391 \left\{ 406 392 \begin{aligned} … … 410 396 \right. 411 397 \] 412 When \np {ln\_dynzad\_zts}\forcode{ = .true.},398 When \np[=.true.]{ln_dynzad_zts}{ln\_dynzad\_zts}, 413 399 a split-explicit time stepping with 5 sub-timesteps is used on the vertical advection term. 414 This option can be useful when the value of the timestep is limited by vertical advection \citep{lemarie.debreu.ea_OM15}. 400 This option can be useful when the value of the timestep is limited by vertical advection \citep{lemarie.debreu.ea_OM15}. 415 401 Note that in this case, 416 402 a similar split-explicit time stepping should be used on vertical advection of tracer to ensure a better stability, 417 an option which is only available with a TVD scheme (see \np{ln\_traadv\_tvd\_zts} in \autoref{subsec:TRA_adv_tvd}). 418 419 420 % ================================================================ 421 % Coriolis and Advection : flux form 422 % ================================================================ 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 %% ================================================================================================= 423 406 \section{Coriolis and advection: flux form} 424 407 \label{sec:DYN_adv_cor_flux} 425 %------------------------------------------nam_dynadv---------------------------------------------------- 426 427 \nlst{namdyn_adv} 428 %------------------------------------------------------------------------------------------------------------- 429 430 Options are defined through the \ngn{namdyn\_adv} namelist variables. 408 409 Options are defined through the \nam{dyn_adv}{dyn\_adv} namelist variables. 431 410 In the flux form (as in the vector invariant form), 432 411 the Coriolis and momentum advection terms are evaluated using a leapfrog scheme, 433 \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). 434 413 At the lateral boundaries either free slip, 435 414 no slip or partial slip boundary conditions are applied following \autoref{chap:LBC}. 436 415 437 438 %-------------------------------------------------------------------------------------------------------------- 439 % Coriolis plus curvature metric terms 440 %-------------------------------------------------------------------------------------------------------------- 441 \subsection[Coriolis plus curvature metric terms (\textit{dynvor.F90})] 442 {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})} 443 418 \label{subsec:DYN_cor_flux} 444 419 445 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. 446 421 This altered Coriolis parameter is thus discretised at $f$-points. 447 It is given by: 422 It is given by: 448 423 \begin{multline*} 449 % \label{eq: dyncor_metric}424 % \label{eq:DYN_cor_metric} 450 425 f+\frac{1}{e_1 e_2 }\left( {v\frac{\partial e_2 }{\partial i} - u\frac{\partial e_1 }{\partial j}} \right) \\ 451 426 \equiv f + \frac{1}{e_{1f} e_{2f} } \left( { \ \overline v ^{i+1/2}\delta_{i+1/2} \left[ {e_{2u} } \right] 452 427 - \overline u ^{j+1/2}\delta_{j+1/2} \left[ {e_{1u} } \right] } \ \right) 453 \end{multline*} 454 455 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 456 431 compute the product of the Coriolis parameter and the vorticity. 457 However, the energy-conserving scheme (\autoref{eq:dynvor_een}) has exclusively been used to date. 458 This term is evaluated using a leapfrog scheme, \ie the velocity is centred in time (\textit{now} velocity). 459 460 %-------------------------------------------------------------------------------------------------------------- 461 % Flux form Advection term 462 %-------------------------------------------------------------------------------------------------------------- 463 \subsection[Flux form advection term (\textit{dynadv.F90})] 464 {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})} 465 437 \label{subsec:DYN_adv_flux} 466 438 467 439 The discrete expression of the advection term is given by: 468 440 \[ 469 % \label{eq: dynadv}441 % \label{eq:DYN_adv} 470 442 \left\{ 471 443 \begin{aligned} … … 487 459 or a $3^{rd}$ order upstream biased scheme, UBS. 488 460 The latter is described in \citet{shchepetkin.mcwilliams_OM05}. 489 The schemes are selected using the namelist logicals \np{ln \_dynadv\_cen2} and \np{ln\_dynadv\_ubs}.461 The schemes are selected using the namelist logicals \np{ln_dynadv_cen2}{ln\_dynadv\_cen2} and \np{ln_dynadv_ubs}{ln\_dynadv\_ubs}. 490 462 In flux form, the schemes differ by the choice of a space and time interpolation to define the value of 491 $u$ and $v$ at the centre of each face of $u$- and $v$-cells, \ie at the $T$-, $f$-, 492 and $uw$-points for $u$ and at the $f$-, $T$- and $vw$-points for $v$. 493 494 %------------------------------------------------------------- 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 495 466 % 2nd order centred scheme 496 %------------------------------------------------------------- 497 \subsubsection[CEN2: $2^{nd}$ order centred scheme (\forcode{ln_dynadv_cen2 = .true.})] 498 {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})} 499 469 \label{subsec:DYN_adv_cen2} 500 470 501 471 In the centered $2^{nd}$ order formulation, the velocity is evaluated as the mean of the two neighbouring points: 502 472 \begin{equation} 503 \label{eq: dynadv_cen2}473 \label{eq:DYN_adv_cen2} 504 474 \left\{ 505 475 \begin{aligned} … … 508 478 \end{aligned} 509 479 \right. 510 \end{equation} 511 512 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). 513 483 It is therefore notoriously noisy and must be used in conjunction with an explicit diffusion operator to 514 484 produce a sensible solution. … … 516 486 so $u$ and $v$ are the \emph{now} velocities. 517 487 518 %-------------------------------------------------------------519 488 % UBS scheme 520 %------------------------------------------------------------- 521 \subsubsection[UBS: Upstream Biased Scheme (\forcode{ln_dynadv_ubs = .true.})] 522 {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})} 523 491 \label{subsec:DYN_adv_ubs} 524 492 … … 527 495 For example, the evaluation of $u_T^{ubs} $ is done as follows: 528 496 \begin{equation} 529 \label{eq: dynadv_ubs}497 \label{eq:DYN_adv_ubs} 530 498 u_T^{ubs} =\overline u ^i-\;\frac{1}{6} 531 499 \begin{cases} … … 535 503 \end{equation} 536 504 where $u"_{i+1/2} =\delta_{i+1/2} \left[ {\delta_i \left[ u \right]} \right]$. 537 This results in a dissipatively dominant (\ie hyper-diffusive) truncation error505 This results in a dissipatively dominant (\ie\ hyper-diffusive) truncation error 538 506 \citep{shchepetkin.mcwilliams_OM05}. 539 507 The overall performance of the advection scheme is similar to that reported in \citet{farrow.stevens_JPO95}. … … 541 509 It is not a \emph{positive} scheme, meaning that false extrema are permitted. 542 510 But the amplitudes of the false extrema are significantly reduced over those in the centred second order method. 543 As the scheme already includes a diffusion component, it can be used without explicit lateral diffusion on momentum 544 (\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}), 545 513 and it is recommended to do so. 546 514 547 515 The UBS scheme is not used in all directions. 548 In the vertical, the centred $2^{nd}$ order evaluation of the advection is preferred, \ie $u_{uw}^{ubs}$ and549 $u_{vw}^{ubs}$ in \autoref{eq: dynadv_cen2} are used.550 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 551 519 sentence:Since vertical mixing of momentum is a source term of the TKE equation... } 552 520 553 For stability reasons, the first term in (\autoref{eq: dynadv_ubs}),521 For stability reasons, the first term in (\autoref{eq:DYN_adv_ubs}), 554 522 which corresponds to a second order centred scheme, is evaluated using the \textit{now} velocity (centred in time), 555 523 while the second term, which is the diffusion part of the scheme, … … 559 527 Note that the UBS and QUICK (Quadratic Upstream Interpolation for Convective Kinematics) schemes only differ by 560 528 one coefficient. 561 Replacing $1/6$ by $1/8$ in (\autoref{eq: dynadv_ubs}) leads to the QUICK advection scheme \citep{webb.de-cuevas.ea_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}. 562 530 This option is not available through a namelist parameter, since the $1/6$ coefficient is hard coded. 563 531 Nevertheless it is quite easy to make the substitution in the \mdl{dynadv\_ubs} module and obtain a QUICK scheme. … … 566 534 there is also the possibility of using a $4^{th}$ order evaluation of the advective velocity as in ROMS. 567 535 This is an error and should be suppressed soon. 568 %%% 569 \gmcomment{action : this have to be done} 570 %%% 571 572 % ================================================================ 573 % Hydrostatic pressure gradient term 574 % ================================================================ 575 \section[Hydrostatic pressure gradient (\textit{dynhpg.F90})] 576 {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})} 577 540 \label{sec:DYN_hpg} 578 %------------------------------------------nam_dynhpg--------------------------------------------------- 579 580 \nlst{namdyn_hpg} 581 %------------------------------------------------------------------------------------------------------------- 582 583 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. 584 549 The key distinction between the different algorithms used for 585 550 the hydrostatic pressure gradient is the vertical coordinate used, 586 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. 587 552 As a result, any tilt of the surface of the computational levels will require a specific treatment to 588 553 compute the hydrostatic pressure gradient. 589 554 590 555 The hydrostatic pressure gradient term is evaluated either using a leapfrog scheme, 591 \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$), 592 557 or a semi-implcit scheme. 593 558 At the lateral boundaries either free slip, no slip or partial slip boundary conditions are applied. 594 559 595 %-------------------------------------------------------------------------------------------------------------- 596 % z-coordinate with full step 597 %-------------------------------------------------------------------------------------------------------------- 598 \subsection[Full step $Z$-coordinate (\forcode{ln_dynhpg_zco = .true.})] 599 {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})} 600 562 \label{subsec:DYN_hpg_zco} 601 563 … … 607 569 for $k=km$ (surface layer, $jk=1$ in the code) 608 570 \begin{equation} 609 \label{eq: dynhpg_zco_surf}571 \label{eq:DYN_hpg_zco_surf} 610 572 \left\{ 611 573 \begin{aligned} … … 616 578 \end{aligned} 617 579 \right. 618 \end{equation} 580 \end{equation} 619 581 620 582 for $1<k<km$ (interior layer) 621 583 \begin{equation} 622 \label{eq: dynhpg_zco}584 \label{eq:DYN_hpg_zco} 623 585 \left\{ 624 586 \begin{aligned} … … 631 593 \end{aligned} 632 594 \right. 633 \end{equation} 634 635 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 636 598 the vertical derivative of the scale factor at the surface level ($z=0$). 637 Note also that in case of variable volume level (\key{vvl} defined), 638 the surface pressure gradient is included in \autoref{eq:dynhpg_zco_surf} and 639 \autoref{eq:dynhpg_zco} through the space and time variations of the vertical scale factor $e_{3w}$. 640 641 %-------------------------------------------------------------------------------------------------------------- 642 % z-coordinate with partial step 643 %-------------------------------------------------------------------------------------------------------------- 644 \subsection[Partial step $Z$-coordinate (\forcode{ln_dynhpg_zps = .true.})] 645 {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})} 646 605 \label{subsec:DYN_hpg_zps} 647 606 … … 649 608 Before taking horizontal gradients between these tracer points, 650 609 a linear interpolation is used to approximate the deeper tracer as if 651 it actually lived at the depth of the shallower tracer point. 610 it actually lived at the depth of the shallower tracer point. 652 611 653 612 Apart from this modification, … … 661 620 module \mdl{zpsdhe} located in the TRA directory and described in \autoref{sec:TRA_zpshde}. 662 621 663 %-------------------------------------------------------------------------------------------------------------- 664 % s- and s-z-coordinates 665 %-------------------------------------------------------------------------------------------------------------- 622 %% ================================================================================================= 666 623 \subsection{$S$- and $Z$-$S$-coordinates} 667 624 \label{subsec:DYN_hpg_sco} 668 625 669 626 Pressure gradient formulations in an $s$-coordinate have been the subject of a vast number of papers 670 (\eg, \citet{song_MWR98, shchepetkin.mcwilliams_OM05}). 627 (\eg, \citet{song_MWR98, shchepetkin.mcwilliams_OM05}). 671 628 A number of different pressure gradient options are coded but the ROMS-like, 672 629 density Jacobian with cubic polynomial method is currently disabled whilst known bugs are under investigation. 673 630 674 $\bullet$ Traditional coding (see for example \citet{madec.delecluse.ea_JPO96}: (\np {ln\_dynhpg\_sco}\forcode{ = .true.})675 \begin{equation} 676 \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} 677 634 \left\{ 678 635 \begin{aligned} … … 683 640 \end{aligned} 684 641 \right. 685 \end{equation} 642 \end{equation} 686 643 687 644 Where the first term is the pressure gradient along coordinates, 688 computed as in \autoref{eq: dynhpg_zco_surf} - \autoref{eq:dynhpg_zco},689 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 690 647 ($e_{3w}$). 691 692 $\bullet$ Traditional coding with adaptation for ice shelf cavities (\np {ln\_dynhpg\_isf}\forcode{ = .true.}).693 This scheme need the activation of ice shelf cavities (\np {ln\_isfcav}\forcode{ = .true.}).694 695 $\bullet$ Pressure Jacobian scheme (prj) (a research paper in preparation) (\np {ln\_dynhpg\_prj}\forcode{ = .true.})696 697 $\bullet$ Density Jacobian with cubic polynomial scheme (DJC) \citep{shchepetkin.mcwilliams_OM05} 698 (\np {ln\_dynhpg\_djc}\forcode{ = .true.}) (currently disabled; under development)699 700 Note that expression \autoref{eq: dynhpg_sco} is commonly used when the variable volume formulation is activated701 (\ key{vvl}) because in that case, even with a flat bottom,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, 702 659 the coordinate surfaces are not horizontal but follow the free surface \citep{levier.treguier.ea_rpt07}. 703 The pressure jacobian scheme (\np {ln\_dynhpg\_prj}\forcode{ = .true.}) is available as704 an improved option to \np {ln\_dynhpg\_sco}\forcode{ = .true.} when \key{vvl} is active.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. 705 662 The pressure Jacobian scheme uses a constrained cubic spline to 706 663 reconstruct the density profile across the water column. … … 710 667 This method can provide a more accurate calculation of the horizontal pressure gradient than the standard scheme. 711 668 669 %% ================================================================================================= 712 670 \subsection{Ice shelf cavity} 713 671 \label{subsec:DYN_hpg_isf} 672 714 673 Beneath an ice shelf, the total pressure gradient is the sum of the pressure gradient due to the ice shelf load and 715 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}).\\ 716 675 717 676 The main hypothesis to compute the ice shelf load is that the ice shelf is in an isostatic equilibrium. … … 722 681 A detailed description of this method is described in \citet{losch_JGR08}.\\ 723 682 724 The pressure gradient due to ocean load is computed using the expression \autoref{eq:dynhpg_sco} described in 725 \autoref{subsec:DYN_hpg_sco}. 726 727 %-------------------------------------------------------------------------------------------------------------- 728 % Time-scheme 729 %-------------------------------------------------------------------------------------------------------------- 730 \subsection[Time-scheme (\forcode{ln_dynhpg_imp = .{true,false}.})] 731 {Time-scheme (\protect\np{ln\_dynhpg\_imp}\forcode{ = .\{true,false\}}.)} 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})} 732 688 \label{subsec:DYN_hpg_imp} 733 689 … … 742 698 It involves the evaluation of the hydrostatic pressure gradient as 743 699 an average over the three time levels $t-\rdt$, $t$, and $t+\rdt$ 744 (\ie \textit{before}, \textit{now} and \textit{after} time-steps),745 rather than at the central time level $t$ only, as in the standard leapfrog scheme. 746 747 $\bullet$ leapfrog scheme (\np {ln\_dynhpg\_imp}\forcode{ = .true.}):748 749 \begin{equation} 750 \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} 751 707 \frac{u^{t+\rdt}-u^{t-\rdt}}{2\rdt} = \;\cdots \; 752 708 -\frac{1}{\rho_o \,e_{1u} }\delta_{i+1/2} \left[ {p_h^t } \right] 753 709 \end{equation} 754 710 755 $\bullet$ semi-implicit scheme (\np {ln\_dynhpg\_imp}\forcode{ = .true.}):756 \begin{equation} 757 \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} 758 714 \frac{u^{t+\rdt}-u^{t-\rdt}}{2\rdt} = \;\cdots \; 759 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] 760 716 \end{equation} 761 717 762 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 763 719 significant additional computation since the density can be updated to time level $t+\rdt$ before 764 720 computing the horizontal hydrostatic pressure gradient. 765 721 It can be easily shown that the stability limit associated with the hydrostatic pressure gradient doubles using 766 \autoref{eq: dynhpg_imp} compared to that using the standard leapfrog scheme \autoref{eq:dynhpg_lf}.767 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 768 724 eliminate high frequency IGWs. 769 Obviously, when using \autoref{eq: dynhpg_imp},725 Obviously, when using \autoref{eq:DYN_hpg_imp}, 770 726 the doubling of the time-step is achievable only if no other factors control the time-step, 771 727 such as the stability limits associated with advection or diffusion. 772 728 773 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}. 774 730 In this case, we choose to apply the time filter to temperature and salinity used in the equation of state, 775 731 instead of applying it to the hydrostatic pressure or to the density, … … 777 733 The density used to compute the hydrostatic pressure gradient (whatever the formulation) is evaluated as follows: 778 734 \[ 779 % \label{eq: rho_flt}735 % \label{eq:DYN_rho_flt} 780 736 \rho^t = \rho( \widetilde{T},\widetilde {S},z_t) 781 737 \quad \text{with} \quad … … 785 741 Note that in the semi-implicit case, it is necessary to save the filtered density, 786 742 an extra three-dimensional field, in the restart file to restart the model with exact reproducibility. 787 This option is controlled by \np{nn\_dynhpg\_rst}, a namelist parameter. 788 789 % ================================================================ 790 % Surface Pressure Gradient 791 % ================================================================ 792 \section[Surface pressure gradient (\textit{dynspg.F90})] 793 {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})} 794 747 \label{sec:DYN_spg} 795 %-----------------------------------------nam_dynspg---------------------------------------------------- 796 797 \nlst{namdyn_spg} 798 %------------------------------------------------------------------------------------------------------------ 799 800 Options are defined through the \ngn{namdyn\_spg} namelist variables. 801 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}). 802 757 The main distinction is between the fixed volume case (linear free surface) and 803 the variable volume case (nonlinear free surface, \ key{vvl} is defined).804 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}) 805 760 the vertical scale factors $e_{3}$ are fixed in time, 806 while they are time-dependent in the nonlinear case (\autoref{subsec: PE_free_surface}).807 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, 808 763 which imposes a very small time step when an explicit time stepping is used. 809 Two methods are proposed to allow a longer time step for the three-dimensional equations: 810 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?}), 811 766 and the split-explicit free surface described below. 812 The extra term introduced in the filtered method is calculated implicitly, 767 The extra term introduced in the filtered method is calculated implicitly, 813 768 so that the update of the next velocities is done in module \mdl{dynspg\_flt} and not in \mdl{dynnxt}. 814 769 815 816 770 The form of the surface pressure gradient term depends on how the user wants to 817 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}). 818 772 Three formulations are available, all controlled by a CPP key (ln\_dynspg\_xxx): 819 773 an explicit formulation which requires a small time step; 820 774 a filtered free surface formulation which allows a larger time step by 821 adding a filtering term into the momentum equation; 775 adding a filtering term into the momentum equation; 822 776 and a split-explicit free surface formulation, described below, which also allows a larger time step. 823 777 … … 825 779 As a consequence the update of the $next$ velocities is done in module \mdl{dynspg\_flt} and not in \mdl{dynnxt}. 826 780 827 828 %-------------------------------------------------------------------------------------------------------------- 829 % Explicit free surface formulation 830 %-------------------------------------------------------------------------------------------------------------- 831 \subsection[Explicit free surface (\texttt{\textbf{key\_dynspg\_exp}})] 832 {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})} 833 783 \label{subsec:DYN_spg_exp} 834 784 835 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), 836 786 the model time step is chosen to be small enough to resolve the external gravity waves 837 787 (typically a few tens of seconds). 838 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), 839 789 is thus simply given by : 840 790 \begin{equation} 841 \label{eq: dynspg_exp}791 \label{eq:DYN_spg_exp} 842 792 \left\{ 843 793 \begin{aligned} … … 846 796 \end{aligned} 847 797 \right. 848 \end{equation} 849 850 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), 851 801 the surface pressure gradient is already included in the momentum tendency through 852 802 the level thickness variation allowed in the computation of the hydrostatic pressure gradient. 853 803 Thus, nothing is done in the \mdl{dynspg\_exp} module. 854 804 855 %-------------------------------------------------------------------------------------------------------------- 856 % Split-explict free surface formulation 857 %-------------------------------------------------------------------------------------------------------------- 858 \subsection[Split-explicit free surface (\texttt{\textbf{key\_dynspg\_ts}})] 859 {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})} 860 807 \label{subsec:DYN_spg_ts} 861 %------------------------------------------namsplit-----------------------------------------------------------862 %863 808 %\nlst{namsplit} 864 %------------------------------------------------------------------------------------------------------------- 865 866 The split-explicit free surface formulation used in \NEMO (\key{dynspg\_ts} defined), 809 810 The split-explicit free surface formulation used in \NEMO\ (\np{ln_dynspg_ts}{ln\_dynspg\_ts} set to true), 867 811 also called the time-splitting formulation, follows the one proposed by \citet{shchepetkin.mcwilliams_OM05}. 868 812 The general idea is to solve the free surface equation and the associated barotropic velocity equations with 869 813 a smaller time step than $\rdt$, the time step used for the three dimensional prognostic variables 870 (\autoref{fig:DYN_ dynspg_ts}).814 (\autoref{fig:DYN_spg_ts}). 871 815 The size of the small time step, $\rdt_e$ (the external mode or barotropic time step) is provided through 872 the \np{nn \_baro} namelist parameter as: $\rdt_e = \rdt / nn\_baro$.873 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 874 818 the stability of the barotropic system is essentially controled by external waves propagation. 875 819 Maximum Courant number is in that case time independent, and easily computed online from the input bathymetry. 876 Therefore, $\rdt_e$ is adjusted so that the Maximum allowed Courant number is smaller than \np{rn\_bt\_cmax}. 877 878 %%% 820 Therefore, $\rdt_e$ is adjusted so that the Maximum allowed Courant number is smaller than \np{rn_bt_cmax}{rn\_bt\_cmax}. 821 879 822 The barotropic mode solves the following equations: 880 823 % \begin{subequations} 881 % \label{eq: BT}882 \begin{equation} 883 \label{eq: BT_dyn}824 % \label{eq:DYN_BT} 825 \begin{equation} 826 \label{eq:DYN_BT_dyn} 884 827 \frac{\partial {\mathrm \overline{{\mathbf U}}_h} }{\partial t}= 885 828 -f\;{\mathrm {\mathbf k}}\times {\mathrm \overline{{\mathbf U}}_h} … … 887 830 \end{equation} 888 831 \[ 889 % \label{eq: BT_ssh}832 % \label{eq:DYN_BT_ssh} 890 833 \frac{\partial \eta }{\partial t}=-\nabla \cdot \left[ {\left( {H+\eta } \right) \; {\mathrm{\mathbf \overline{U}}}_h \,} \right]+P-E 891 834 \] … … 893 836 where $\mathrm {\overline{\mathbf G}}$ is a forcing term held constant, containing coupling term between modes, 894 837 surface atmospheric forcing as well as slowly varying barotropic terms not explicitly computed to gain efficiency. 895 The third term on the right hand side of \autoref{eq: BT_dyn} represents the bottom stress896 (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. 897 840 Temporal discretization of the system above follows a three-time step Generalized Forward Backward algorithm 898 841 detailed in \citet{shchepetkin.mcwilliams_OM05}. 899 AB3-AM4 coefficients used in \NEMO follow the second-order accurate,842 AB3-AM4 coefficients used in \NEMO\ follow the second-order accurate, 900 843 "multi-purpose" stability compromise as defined in \citet{shchepetkin.mcwilliams_ibk09} 901 (see their figure 12, lower left). 902 903 %> > > > > > > > > > > > > > > > > > > > > > > > > > > > 844 (see their figure 12, lower left). 845 904 846 \begin{figure}[!t] 905 \begin{center} 906 \includegraphics[width=\textwidth]{Fig_DYN_dynspg_ts} 907 \caption{ 908 \protect\label{fig:DYN_dynspg_ts} 909 Schematic of the split-explicit time stepping scheme for the external and internal modes. 910 Time increases to the right. In this particular exemple, 911 a boxcar averaging window over $nn\_baro$ barotropic time steps is used ($nn\_bt\_flt=1$) and $nn\_baro=5$. 912 Internal mode time steps (which are also the model time steps) are denoted by $t-\rdt$, $t$ and $t+\rdt$. 913 Variables with $k$ superscript refer to instantaneous barotropic variables, 914 $< >$ and $<< >>$ operator refer to time filtered variables using respectively primary (red vertical bars) and 915 secondary weights (blue vertical bars). 916 The former are used to obtain time filtered quantities at $t+\rdt$ while 917 the latter are used to obtain time averaged transports to advect tracers. 918 a) Forward time integration: \protect\np{ln\_bt\_fw}\forcode{ = .true.}, 919 \protect\np{ln\_bt\_av}\forcode{ = .true.}. 920 b) Centred time integration: \protect\np{ln\_bt\_fw}\forcode{ = .false.}, 921 \protect\np{ln\_bt\_av}\forcode{ = .true.}. 922 c) Forward time integration with no time filtering (POM-like scheme): 923 \protect\np{ln\_bt\_fw}\forcode{ = .true.}, \protect\np{ln\_bt\_av}\forcode{ = .false.}. 924 } 925 \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} 926 869 \end{figure} 927 %> > > > > > > > > > > > > > > > > > > > > > > > > > > > 928 929 In the default case (\np{ln\_bt\_fw}\forcode{ = .true.}), 870 871 In the default case (\np[=.true.]{ln_bt_fw}{ln\_bt\_fw}), 930 872 the external mode is integrated between \textit{now} and \textit{after} baroclinic time-steps 931 (\autoref{fig:DYN_ dynspg_ts}a).873 (\autoref{fig:DYN_spg_ts}a). 932 874 To avoid aliasing of fast barotropic motions into three dimensional equations, 933 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}). 934 876 In that case, the integration is extended slightly beyond \textit{after} time step to 935 877 provide time filtered quantities. 936 878 These are used for the subsequent initialization of the barotropic mode in the following baroclinic step. 937 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, 938 880 asselin filtering is not applied to barotropic quantities.\\ 939 881 Alternatively, one can choose to integrate barotropic equations starting from \textit{before} time step 940 (\np {ln\_bt\_fw}\forcode{ = .false.}).941 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), 942 884 the baroclinic to barotropic forcing term given at \textit{now} time step become centred in 943 885 the middle of the integration window. … … 946 888 %references to Patrick Marsaleix' work here. Also work done by SHOM group. 947 889 948 %%%949 890 950 891 As far as tracer conservation is concerned, … … 960 901 obtain exact conservation. 961 902 962 %%%963 903 964 904 One can eventually choose to feedback instantaneous values by not using any time filter 965 (\np {ln\_bt\_av}\forcode{ = .false.}).905 (\np[=.false.]{ln_bt_av}{ln\_bt\_av}). 966 906 In that case, external mode equations are continuous in time, 967 \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. 968 908 This is the method used so far in the POM model, the stability being maintained by 969 909 refreshing at (almost) each barotropic time step advection and horizontal diffusion terms. 970 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, 971 911 removing time filtering is not recommended except for debugging purposes. 972 912 This may be used for instance to appreciate the damping effect of the standard formulation on … … 975 915 it is still significant as shown by \citet{levier.treguier.ea_rpt07} in the case of an analytical barotropic Kelvin wave. 976 916 977 %>>>>>=============== 978 \gmcomment{ %%% copy from griffies Book 917 \cmtgm{ %%% copy from griffies Book 979 918 980 919 \textbf{title: Time stepping the barotropic system } … … 983 922 Hence, we can update the surface height and vertically integrated velocity with a leap-frog scheme using 984 923 the small barotropic time step $\rdt$. 985 We have 924 We have 986 925 987 926 \[ … … 1006 945 and total depth of the ocean $H(\tau)$ are held for the duration of the barotropic time stepping over 1007 946 a single cycle. 1008 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 1009 948 \[ 1010 949 % \label{eq:DYN_spg_ts_t} … … 1012 951 \] 1013 952 with $n$ an integer. 1014 The density scaled surface pressure is evaluated via 953 The density scaled surface pressure is evaluated via 1015 954 \[ 1016 955 % \label{eq:DYN_spg_ts_ps} … … 1021 960 \end{cases} 1022 961 \] 1023 To get started, we assume the following initial conditions 962 To get started, we assume the following initial conditions 1024 963 \[ 1025 964 % \label{eq:DYN_spg_ts_eta} … … 1029 968 \end{split} 1030 969 \] 1031 with 970 with 1032 971 \[ 1033 972 % \label{eq:DYN_spg_ts_etaF} … … 1035 974 \] 1036 975 the time averaged surface height taken from the previous barotropic cycle. 1037 Likewise, 976 Likewise, 1038 977 \[ 1039 978 % \label{eq:DYN_spg_ts_u} … … 1041 980 \textbf{U}(\tau,t_{n=1}) = \textbf{U}^{(b)}(\tau,t_{n=0}) + \rdt \ \text{RHS}_{n=0} 1042 981 \] 1043 with 982 with 1044 983 \[ 1045 984 % \label{eq:DYN_spg_ts_u} … … 1047 986 \] 1048 987 the time averaged vertically integrated transport. 1049 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. 1050 989 1051 990 Upon reaching $t_{n=N} = \tau + 2\rdt \tau$ , 1052 991 the vertically integrated velocity is time averaged to produce the updated vertically integrated velocity at 1053 baroclinic time $\tau + \rdt \tau$ 992 baroclinic time $\tau + \rdt \tau$ 1054 993 \[ 1055 994 % \label{eq:DYN_spg_ts_u} … … 1057 996 \] 1058 997 The surface height on the new baroclinic time step is then determined via a baroclinic leap-frog using 1059 the following form 998 the following form 1060 999 1061 1000 \begin{equation} 1062 1001 \label{eq:DYN_spg_ts_ssh} 1063 \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] 1064 1003 \end{equation} 1065 1004 1066 1005 The use of this "big-leap-frog" scheme for the surface height ensures compatibility between 1067 1006 the mass/volume budgets and the tracer budgets. 1068 More discussion of this point is provided in Chapter 10 (see in particular Section 10.2). 1069 1007 More discussion of this point is provided in Chapter 10 (see in particular Section 10.2). 1008 1070 1009 In general, some form of time filter is needed to maintain integrity of the surface height field due to 1071 1010 the leap-frog splitting mode in equation \autoref{eq:DYN_spg_ts_ssh}. … … 1078 1017 \eta^{F}(\tau-\Delta) = \overline{\eta^{(b)}(\tau)} 1079 1018 \end{equation} 1080 Another approach tried was 1019 Another approach tried was 1081 1020 1082 1021 \[ … … 1091 1030 eliminating tracer and surface height time filtering (see ?? for more complete discussion). 1092 1031 However, in the general case with a non-zero $\alpha$, 1093 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. 1094 1033 1095 1034 } %%end gm comment (copy of griffies book) 1096 1035 1097 %>>>>>=============== 1098 1099 1100 %-------------------------------------------------------------------------------------------------------------- 1101 % Filtered free surface formulation 1102 %-------------------------------------------------------------------------------------------------------------- 1103 \subsection[Filtered free surface (\texttt{\textbf{key\_dynspg\_flt}})] 1104 {Filtered free surface (\protect\key{dynspg\_flt})} 1036 %% ================================================================================================= 1037 \subsection{Filtered free surface (\forcode{dynspg_flt?})} 1105 1038 \label{subsec:DYN_spg_fltp} 1106 1039 1107 The filtered formulation follows the \citet{roullet.madec_JGR00} implementation. 1108 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. 1109 1042 The elliptic solvers available in the code are documented in \autoref{chap:MISC}. 1110 1043 1111 1044 %% gm %%======>>>> given here the discrete eqs provided to the solver 1112 \ gmcomment{ %%% copy from chap-model basics1045 \cmtgm{ %%% copy from chap-model basics 1113 1046 \[ 1114 % \label{eq: spg_flt}1047 % \label{eq:DYN_spg_flt} 1115 1048 \frac{\partial {\mathrm {\mathbf U}}_h }{\partial t}= {\mathrm {\mathbf M}} 1116 1049 - g \nabla \left( \tilde{\rho} \ \eta \right) … … 1120 1053 $\widetilde{\rho} = \rho / \rho_o$ is the dimensionless density, 1121 1054 and $\mathrm {\mathbf M}$ represents the collected contributions of the Coriolis, hydrostatic pressure gradient, 1122 non-linear and viscous terms in \autoref{eq: PE_dyn}.1123 } %end gmcomment1124 1125 Note that in the linear free surface formulation (\ key{vvl} not defined),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), 1126 1059 the ocean depth is time-independent and so is the matrix to be inverted. 1127 It is computed once and for all and applies to all ocean time steps. 1128 1129 % ================================================================ 1130 % Lateral diffusion term 1131 % ================================================================ 1132 \section[Lateral diffusion term and operators (\textit{dynldf.F90})] 1133 {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})} 1134 1064 \label{sec:DYN_ldf} 1135 %------------------------------------------nam_dynldf---------------------------------------------------- 1136 1137 \nlst{namdyn_ldf} 1138 %------------------------------------------------------------------------------------------------------------- 1139 1140 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. 1141 1073 The options available for lateral diffusion are to use either laplacian (rotated or not) or biharmonic operators. 1142 1074 The coefficients may be constant or spatially variable; 1143 1075 the description of the coefficients is found in the chapter on lateral physics (\autoref{chap:LDF}). 1144 1076 The lateral diffusion of momentum is evaluated using a forward scheme, 1145 \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, 1146 1078 except for the pure vertical component that appears when a tensor of rotation is used. 1147 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}). 1148 1080 1149 1081 At the lateral boundaries either free slip, 1150 1082 no slip or partial slip boundary conditions are applied according to the user's choice (see \autoref{chap:LBC}). 1151 1083 1152 \ gmcomment{1084 \cmtgm{ 1153 1085 Hyperviscous operators are frequently used in the simulation of turbulent flows to 1154 1086 control the dissipation of unresolved small scale features. … … 1159 1091 In finite difference methods, 1160 1092 the biharmonic operator is frequently the method of choice to achieve this scale selective dissipation since 1161 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$ 1162 1094 (so that short waves damped more rapidelly than long ones), 1163 1095 whereas the Laplace operator damping time scales only like $\lambda^{-2}$. 1164 1096 } 1165 1097 1166 % ================================================================ 1167 \subsection[Iso-level laplacian (\forcode{ln_dynldf_lap = .true.})] 1168 {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})} 1169 1100 \label{subsec:DYN_ldf_lap} 1170 1101 1171 For lateral iso-level diffusion, the discrete operator is: 1172 \begin{equation} 1173 \label{eq: dynldf_lap}1102 For lateral iso-level diffusion, the discrete operator is: 1103 \begin{equation} 1104 \label{eq:DYN_ldf_lap} 1174 1105 \left\{ 1175 1106 \begin{aligned} 1176 1107 D_u^{l{\mathrm {\mathbf U}}} =\frac{1}{e_{1u} }\delta_{i+1/2} \left[ {A_T^{lm} 1177 \;\chi } \right]-\frac{1}{e_{2u} {\kern 1pt}e_{3u} }\delta_j \left[ 1108 \;\chi } \right]-\frac{1}{e_{2u} {\kern 1pt}e_{3u} }\delta_j \left[ 1178 1109 {A_f^{lm} \;e_{3f} \zeta } \right] \\ \\ 1179 1110 D_v^{l{\mathrm {\mathbf U}}} =\frac{1}{e_{2v} }\delta_{j+1/2} \left[ {A_T^{lm} 1180 \;\chi } \right]+\frac{1}{e_{1v} {\kern 1pt}e_{3v} }\delta_i \left[ 1111 \;\chi } \right]+\frac{1}{e_{1v} {\kern 1pt}e_{3v} }\delta_i \left[ 1181 1112 {A_f^{lm} \;e_{3f} \zeta } \right] 1182 1113 \end{aligned} 1183 1114 \right. 1184 \end{equation} 1185 1186 As explained in \autoref{subsec: PE_ldf},1115 \end{equation} 1116 1117 As explained in \autoref{subsec:MB_ldf}, 1187 1118 this formulation (as the gradient of a divergence and curl of the vorticity) preserves symmetry and 1188 ensures a complete separation between the vorticity and divergence parts of the momentum diffusion. 1189 1190 %-------------------------------------------------------------------------------------------------------------- 1191 % Rotated laplacian operator 1192 %-------------------------------------------------------------------------------------------------------------- 1193 \subsection[Rotated laplacian (\forcode{ln_dynldf_iso = .true.})] 1194 {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})} 1195 1123 \label{subsec:DYN_ldf_iso} 1196 1124 1197 1125 A rotation of the lateral momentum diffusion operator is needed in several cases: 1198 for iso-neutral diffusion in the $z$-coordinate (\np {ln\_dynldf\_iso}\forcode{ = .true.}) and1199 for either iso-neutral (\np {ln\_dynldf\_iso}\forcode{ = .true.}) or1200 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. 1201 1129 In the partial step case, coordinates are horizontal except at the deepest level and 1202 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}. 1203 1131 The diffusion operator is defined simply as the divergence of down gradient momentum fluxes on 1204 1132 each momentum component. … … 1206 1134 The resulting discrete representation is: 1207 1135 \begin{equation} 1208 \label{eq: dyn_ldf_iso}1136 \label{eq:DYN_ldf_iso} 1209 1137 \begin{split} 1210 1138 D_u^{l\textbf{U}} &= \frac{1}{e_{1u} \, e_{2u} \, e_{3u} } \\ … … 1230 1158 -e_{2f} \; r_{1f} \,\overline{\overline {\delta_{k+1/2}[v]}}^{\,i+1/2,\,k}} 1231 1159 \right)} \right]} \right. \\ 1232 & \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} 1233 1161 }\,\delta_{j} [v] - e_{1t}\, r_{2t} 1234 1162 \,\overline{\overline {\delta_{k+1/2} [v]}} ^{\,j,\,k}} 1235 1163 \right)} \right] \\ 1236 & \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 1237 1165 {\delta_{i+1/2} [v]}}^{\,i+1/2,\,k+1/2} }\right.} \right. \\ 1238 1166 & \ \qquad \qquad \qquad \quad\ 1239 1167 - e_{1v} \, r_{2vw} \,\overline{\overline {\delta_{j+1/2} [v]}} ^{\,j+1/2,\,k+1/2} \\ 1240 & \left. {\left. { \ \qquad \qquad \qquad \ \ \ \left. {\ 1168 & \left. {\left. { \ \qquad \qquad \qquad \ \ \ \left. {\ 1241 1169 +\frac{e_{1v}\, e_{2v} }{e_{3vw} }\,\left( {r_{1vw}^2+r_{2vw}^2} 1242 \right)\,\delta_{k+1/2} [v]} \right)} \right]\;\;\;} \right\} 1170 \right)\,\delta_{k+1/2} [v]} \right)} \right]\;\;\;} \right\} 1243 1171 \end{split} 1244 1172 \end{equation} 1245 1173 where $r_1$ and $r_2$ are the slopes between the surface along which the diffusion operator acts and 1246 the surface of computation ($z$- or $s$-surfaces). 1174 the surface of computation ($z$- or $s$-surfaces). 1247 1175 The way these slopes are evaluated is given in the lateral physics chapter (\autoref{chap:LDF}). 1248 1176 1249 %-------------------------------------------------------------------------------------------------------------- 1250 % Iso-level bilaplacian operator 1251 %-------------------------------------------------------------------------------------------------------------- 1252 \subsection[Iso-level bilaplacian (\forcode{ln_dynldf_bilap = .true.})] 1253 {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})} 1254 1179 \label{subsec:DYN_ldf_bilap} 1255 1180 1256 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. 1257 1182 It requires an additional assumption on boundary conditions: 1258 1183 the first derivative term normal to the coast depends on the free or no-slip lateral boundary conditions chosen, 1259 1184 while the third derivative terms normal to the coast are set to zero (see \autoref{chap:LBC}). 1260 %%% 1261 \gmcomment{add a remark on the the change in the position of the coefficient} 1262 %%% 1263 1264 % ================================================================ 1265 % Vertical diffusion term 1266 % ================================================================ 1267 \section[Vertical diffusion term (\textit{dynzdf.F90})] 1268 {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})} 1269 1189 \label{sec:DYN_zdf} 1270 %----------------------------------------------namzdf------------------------------------------------------ 1271 1272 \nlst{namzdf} 1273 %------------------------------------------------------------------------------------------------------------- 1274 1275 Options are defined through the \ngn{namzdf} namelist variables. 1190 1191 Options are defined through the \nam{zdf}{zdf} namelist variables. 1276 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. 1277 1193 Two time stepping schemes can be used for the vertical diffusion term: 1278 1194 $(a)$ a forward time differencing scheme 1279 (\np {ln\_zdfexp}\forcode{ = .true.}) using a time splitting technique (\np{nn\_zdfexp} $>$ 1) or1280 $(b)$ a backward (or implicit) time differencing scheme (\np {ln\_zdfexp}\forcode{ = .false.})1281 (see \autoref{chap: STP}).1282 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. 1283 1199 1284 1200 The formulation of the vertical subgrid scale physics is the same whatever the vertical coordinate is. 1285 The vertical diffusion operators given by \autoref{eq: PE_zdf} take the following semi-discrete space form:1286 \[ 1287 % \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} 1288 1204 \left\{ 1289 1205 \begin{aligned} … … 1303 1219 the vertical turbulent momentum fluxes, 1304 1220 \begin{equation} 1305 \label{eq: dynzdf_sbc}1221 \label{eq:DYN_zdf_sbc} 1306 1222 \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{z=1} 1307 1223 = \frac{1}{\rho_o} \binom{\tau_u}{\tau_v } … … 1309 1225 where $\left( \tau_u ,\tau_v \right)$ are the two components of the wind stress vector in 1310 1226 the (\textbf{i},\textbf{j}) coordinate system. 1311 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 1312 1228 the vertical over the mixed layer depth. 1313 1229 If the vertical mixing coefficient is small (when no mixed layer scheme is used) … … 1316 1232 1317 1233 The turbulent flux of momentum at the bottom of the ocean is specified through a bottom friction parameterisation 1318 (see \autoref{sec:ZDF_bfr}) 1319 1320 % ================================================================ 1321 % External Forcing 1322 % ================================================================ 1234 (see \autoref{sec:ZDF_drg}) 1235 1236 %% ================================================================================================= 1323 1237 \section{External forcings} 1324 1238 \label{sec:DYN_forcing} … … 1326 1240 Besides the surface and bottom stresses (see the above section) 1327 1241 which are introduced as boundary conditions on the vertical mixing, 1328 three other forcings may enter the dynamical equations by affecting the surface pressure gradient. 1329 1330 (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}), 1331 1245 the atmospheric pressure is taken into account when computing the surface pressure gradient. 1332 1246 1333 (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}), 1334 1248 the tidal potential is taken into account when computing the surface pressure gradient. 1335 1249 1336 (3) When \np {nn\_ice\_embd}\forcode{ = 2} and LIM or CICE is used1337 (\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), 1338 1252 the snow-ice mass is taken into account when computing the surface pressure gradient. 1339 1253 1340 1341 \gmcomment{ missing : the lateral boundary condition !!! another external forcing 1254 \cmtgm{ missing : the lateral boundary condition !!! another external forcing 1342 1255 } 1343 1256 1344 % ================================================================ 1345 % Wetting and drying 1346 % ================================================================ 1257 %% ================================================================================================= 1347 1258 \section{Wetting and drying } 1348 1259 \label{sec:DYN_wetdry} 1260 1349 1261 There are two main options for wetting and drying code (wd): 1350 1262 (a) an iterative limiter (il) and (b) a directional limiter (dl). … … 1356 1268 by setting $\mathrm{ln\_wd\_dl} = \mathrm{.true.}$ and $\mathrm{ln\_wd\_il} = \mathrm{.false.}$. 1357 1269 1358 \nlst{namwad} 1270 \begin{listing} 1271 \nlst{namwad} 1272 \caption{\forcode{&namwad}} 1273 \label{lst:namwad} 1274 \end{listing} 1359 1275 1360 1276 The following terminology is used. The depth of the topography (positive downwards) 1361 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. 1362 1278 The height of the free surface (positive upwards) is denoted by $ \mathrm{ssh}$. Given the sign 1363 1279 conventions used, the water depth, $h$, is the height of the free surface plus the depth of the … … 1367 1283 covered by water. They require the topography specified with a model 1368 1284 configuration to have negative depths at points where the land is higher than the 1369 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 1370 1286 initial state with zero sea surface height elevation. 1371 1287 The user can choose to compute the vertical grid and heights in the model relative to … … 1386 1302 All these configurations have used pure sigma coordinates. It is expected that 1387 1303 the wetting and drying code will work in domains with more general s-coordinates provided 1388 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. 1389 1305 1390 1306 The next sub-section descrbies the directional limiter and the following sub-section the iterative limiter. 1391 1307 The final sub-section covers some additional considerations that are relevant to both schemes. 1392 1308 1393 1394 %-----------------------------------------------------------------------------------------1395 1309 % Iterative limiters 1396 %----------------------------------------------------------------------------------------- 1397 \subsection[Directional limiter (\textit{wet\_dry.F90})] 1398 {Directional limiter (\mdl{wet\_dry})} 1310 %% ================================================================================================= 1311 \subsection[Directional limiter (\textit{wet\_dry.F90})]{Directional limiter (\mdl{wet\_dry})} 1399 1312 \label{subsec:DYN_wd_directional_limiter} 1313 1400 1314 The principal idea of the directional limiter is that 1401 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}). 1402 1316 1403 1317 All the changes associated with this option are made to the barotropic solver for the non-linear … … 1409 1323 1410 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). 1411 If the user sets ln\_wd\_dl\_ramp = .False.then zuwdmask is 1 when the1412 flux is from a cell with water depth greater than rn\_wdmin1and 0 otherwise. If the user sets1413 ln\_wd\_dl\_ramp = .True.the flux across the face is ramped down as the water depth decreases1414 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. 1415 1329 1416 1330 At the point where the flux across a $u$-face is multiplied by zuwdmask , we have chosen … … 1422 1336 treatment in the calculation of the flux of mass across the cell face. 1423 1337 1424 1425 1338 \cite{warner.defne.ea_CG13} state that in their scheme the velocity masks at the cell faces for the baroclinic 1426 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 … … 1428 1341 fields (tracers independent of $x$, $y$ and $z$). Our scheme conserves constant tracers because 1429 1342 the velocities used at the tracer cell faces on the baroclinic timesteps are carefully calculated by dynspg\_ts 1430 to equal their mean value during the barotropic steps. If the user sets ln\_wd\_dl\_bc = .True., the 1431 baroclinic velocities are also multiplied by a suitably weighted average of zuwdmask. 1432 1433 %----------------------------------------------------------------------------------------- 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 1434 1346 % Iterative limiters 1435 %----------------------------------------------------------------------------------------- 1436 1437 \subsection[Iterative limiter (\textit{wet\_dry.F90})] 1438 {Iterative limiter (\mdl{wet\_dry})} 1347 1348 %% ================================================================================================= 1349 \subsection[Iterative limiter (\textit{wet\_dry.F90})]{Iterative limiter (\mdl{wet\_dry})} 1439 1350 \label{subsec:DYN_wd_iterative_limiter} 1440 1351 1441 \subsubsection[Iterative flux limiter (\textit{wet\_dry.F90})] 1442 {Iterative flux limiter (\mdl{wet\_dry})}1443 \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} 1444 1355 1445 1356 The iterative limiter modifies the fluxes across the faces of cells that are either already ``dry'' … … 1449 1360 1450 1361 The continuity equation for the total water depth in a column 1451 \begin{equation} \label{dyn_wd_continuity} 1452 \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 . 1453 1365 \end{equation} 1454 1366 can be written in discrete form as 1455 1367 1456 \begin{align} \label{dyn_wd_continuity_2} 1457 \frac{e_1 e_2}{\Delta t} ( h_{i,j}(t_{n+1}) - h_{i,j}(t_e) ) 1458 &= - ( \mathrm{flxu}_{i+1,j} - \mathrm{flxu}_{i,j} + \mathrm{flxv}_{i,j+1} - \mathrm{flxv}_{i,j} ) \\ 1459 &= \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} . 1460 1373 \end{align} 1461 1374 … … 1470 1383 (zzflxp) and fluxes that are into the cell (zzflxn). Clearly 1471 1384 1472 \begin{equation} \label{dyn_wd_zzflx_p_n_1} 1473 \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} . 1474 1388 \end{equation} 1475 1389 … … 1482 1396 $\mathrm{zcoef}_{i,j}^{(m)}$ such that: 1483 1397 1484 \begin{equation} \label{dyn_wd_continuity_coef} 1485 \begin{split} 1486 \mathrm{zzflxp}^{(m)}_{i,j} =& \mathrm{zcoef}_{i,j}^{(m)} \mathrm{zzflxp}^{(0)}_{i,j} \\ 1487 \mathrm{zzflxn}^{(m)}_{i,j} =& \mathrm{zcoef}_{i,j}^{(m)} \mathrm{zzflxn}^{(0)}_{i,j} 1488 \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} 1489 1404 \end{equation} 1490 1405 … … 1494 1409 The iteration is initialised by setting 1495 1410 1496 \begin{equation} \label{dyn_wd_zzflx_initial} 1497 \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} . 1498 1414 \end{equation} 1499 1415 1500 1416 The fluxes out of cell $(i,j)$ are updated at the $m+1$th iteration if the depth of the 1501 1417 cell on timestep $t_e$, namely $h_{i,j}(t_e)$, is less than the total flux out of the cell 1502 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 1503 1419 condition is 1504 1420 1505 \begin{equation} \label{dyn_wd_continuity_if} 1506 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} ) . 1507 \end{equation} 1508 1509 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 1510 1427 outward flux that can be allowed and still maintain the minimum wet depth: 1511 1428 1512 \begin{equation} \label{dyn_wd_max_flux} 1513 \begin{split} 1514 \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{]} \\ 1515 \phantom{[} & - \mathrm{zzflxn}^{(m)}_{i,j} \Big] 1516 \end{split} 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} 1517 1435 \end{equation} 1518 1436 1519 1437 Note a small tolerance ($\mathrm{rn\_wdmin2}$) has been introduced here {\itshape [Q: Why is 1520 this necessary/desirable?]}. Substituting from (\ ref{dyn_wd_continuity_coef}) gives an1438 this necessary/desirable?]}. Substituting from (\autoref{eq:DYN_wd_continuity_coef}) gives an 1521 1439 expression for the coefficient needed to multiply the outward flux at this cell in order 1522 1440 to avoid drying. 1523 1441 1524 \begin{equation} \label{dyn_wd_continuity_nxtcoef} 1525 \begin{split} 1526 \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{]} \\ 1527 \phantom{[} & - \mathrm{zzflxn}^{(m)}_{i,j} \Big] \frac{1}{ \mathrm{zzflxp}^{(0)}_{i,j} } 1528 \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} 1529 1448 \end{equation} 1530 1449 … … 1541 1460 directional limiter does. 1542 1461 1543 1544 %----------------------------------------------------------------------------------------1545 1462 % Surface pressure gradients 1546 %---------------------------------------------------------------------------------------- 1547 \subsubsection[Modification of surface pressure gradients (\textit{dynhpg.F90})] 1548 {Modification of surface pressure gradients (\mdl{dynhpg})} 1549 \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} 1550 1466 1551 1467 At ``dry'' points the water depth is usually close to $\mathrm{rn\_wdmin1}$. If the … … 1560 1476 neighbouring $(i+1,j)$ and $(i,j)$ tracer points. zcpx is calculated using two logicals 1561 1477 variables, $\mathrm{ll\_tmp1}$ and $\mathrm{ll\_tmp2}$ which are evaluated for each grid 1562 column. The three possible combinations are illustrated in figure \ref{Fig_WAD_dynhpg}. 1563 1564 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1565 \begin{figure}[!ht] \begin{center} 1566 \includegraphics[width=\textwidth]{Fig_WAD_dynhpg} 1567 \caption{ \label{Fig_WAD_dynhpg} 1568 Illustrations of the three possible combinations of the logical variables controlling the 1569 limiting of the horizontal pressure gradient in wetting and drying regimes} 1570 \end{center}\end{figure} 1571 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 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} 1572 1489 1573 1490 The first logical, $\mathrm{ll\_tmp1}$, is set to true if and only if the water depth at … … 1576 1493 of the topography at the two points: 1577 1494 1578 \begin{equation} \label{dyn_ll_tmp1} 1579 \begin{split} 1580 \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))} > \\ 1581 1499 & \quad \mathrm{MAX(-ht\_wd(ji,jj), -ht\_wd(ji+1,jj))\ .and.} \\ 1582 & \mathrm{MAX(sshn(ji,jj) + ht\_wd(ji,jj),} \\1583 & \mathrm{\phantom{MAX(}sshn(ji+1,jj) + ht\_wd(ji+1,jj))} >\\1584 & \quad\quad\mathrm{rn\_wdmin1 + rn\_wdmin2 }1585 \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} 1586 1504 \end{equation} 1587 1505 … … 1590 1508 at the two points plus $\mathrm{rn\_wdmin1} + \mathrm{rn\_wdmin2}$ 1591 1509 1592 \begin{equation} \label{dyn_ll_tmp2} 1593 \begin{split} 1594 \mathrm{ ll\_tmp2 } = & \mathrm{( ABS( sshn(ji,jj) - sshn(ji+1,jj) ) > 1.E-12 )\ .AND.}\\ 1595 & \mathrm{( MAX(sshn(ji,jj), sshn(ji+1,jj)) > } \\ 1596 & \mathrm{\phantom{(} MAX(-ht\_wd(ji,jj), -ht\_wd(ji+1,jj)) + rn\_wdmin1 + rn\_wdmin2}) . 1597 \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} 1598 1517 \end{equation} 1599 1518 … … 1611 1530 conditions. 1612 1531 1613 \subsubsection[Additional considerations (\textit{usrdef\_zgr.F90})] 1614 {Additional considerations (\mdl{usrdef\_zgr})}1615 \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} 1616 1535 1617 1536 In the very shallow water where wetting and drying occurs the parametrisation of … … 1623 1542 in uncoupled integrations the net surface heat fluxes need to be appropriately limited. 1624 1543 1625 %----------------------------------------------------------------------------------------1626 1544 % The WAD test cases 1627 %---------------------------------------------------------------------------------------- 1628 \subsection[The WAD test cases (\textit{usrdef\_zgr.F90})] 1629 {The WAD test cases (\mdl{usrdef\_zgr})} 1630 \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} 1631 1548 1632 1549 See the WAD tests MY\_DOC documention for details of the WAD test cases. 1633 1550 1634 1635 1636 % ================================================================ 1637 % Time evolution term 1638 % ================================================================ 1639 \section[Time evolution term (\textit{dynnxt.F90})] 1640 {Time evolution term (\protect\mdl{dynnxt})} 1551 %% ================================================================================================= 1552 \section[Time evolution term (\textit{dynnxt.F90})]{Time evolution term (\protect\mdl{dynnxt})} 1641 1553 \label{sec:DYN_nxt} 1642 1554 1643 %----------------------------------------------namdom---------------------------------------------------- 1644 1645 \nlst{namdom} 1646 %------------------------------------------------------------------------------------------------------------- 1647 1648 Options are defined through the \ngn{namdom} namelist variables. 1555 Options are defined through the \nam{dom}{dom} namelist variables. 1649 1556 The general framework for dynamics time stepping is a leap-frog scheme, 1650 \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}). 1651 1558 The scheme is applied to the velocity, except when 1652 1559 using the flux form of momentum advection (cf. \autoref{sec:DYN_adv_cor_flux}) 1653 in the variable volume case (\ key{vvl} defined),1654 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}) 1655 1562 1656 1563 $\bullet$ vector invariant form or linear free surface 1657 (\np {ln\_dynhpg\_vec}\forcode{ = .true.} ; \key{vvl} not defined):1658 \[ 1659 % \label{eq: dynnxt_vec}1564 (\np[=.true.]{ln_dynhpg_vec}{ln\_dynhpg\_vec} ; \texttt{vvl?} not defined): 1565 \[ 1566 % \label{eq:DYN_nxt_vec} 1660 1567 \left\{ 1661 1568 \begin{aligned} … … 1667 1574 1668 1575 $\bullet$ flux form and nonlinear free surface 1669 (\np {ln\_dynhpg\_vec}\forcode{ = .false.} ; \key{vvl} defined):1670 \[ 1671 % \label{eq: dynnxt_flux}1576 (\np[=.false.]{ln_dynhpg_vec}{ln\_dynhpg\_vec} ; \texttt{vvl?} defined): 1577 \[ 1578 % \label{eq:DYN_nxt_flux} 1672 1579 \left\{ 1673 1580 \begin{aligned} … … 1680 1587 where RHS is the right hand side of the momentum equation, 1681 1588 the subscript $f$ denotes filtered values and $\gamma$ is the Asselin coefficient. 1682 $\gamma$ is initialized as \np{nn \_atfp} (namelist parameter).1683 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}. 1684 1591 In both cases, the modified Asselin filter is not applied since perfect conservation is not an issue for 1685 1592 the momentum equations. … … 1689 1596 and only array swapping and Asselin filtering is done in \mdl{dynnxt}. 1690 1597 1691 % ================================================================ 1692 \biblio 1693 1694 \pindex 1598 \subinc{\input{../../global/epilogue}} 1695 1599 1696 1600 \end{document} -
NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_LBC.tex
r11179 r12149 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 (\texttt{rn\_shlat})] 20 {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})} 21 31 \label{sec:LBC_coast} 22 %--------------------------------------------nam_lbc------------------------------------------------------- 23 24 \nlst{namlbc} 25 %-------------------------------------------------------------------------------------------------------------- 26 27 %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}). 28 29 %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}. 30 31 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. 32 55 The discrete representation of a domain with complex boundaries (coastlines and bottom topography) leads to 33 56 arrays that include large portions where a computation is not required as the model variables remain at zero. … … 41 64 Since most of the boundary conditions consist of a zero flux across the solid boundaries, 42 65 they can be simply applied by multiplying variables by the correct mask arrays, 43 \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. 44 67 For example, the heat flux in the \textbf{i}-direction is evaluated at $u$-points. 45 68 Evaluating this quantity as, 46 69 47 70 \[ 48 % \label{eq: lbc_aaaa}71 % \label{eq:LBC_aaaa} 49 72 \frac{A^{lT} }{e_1 }\frac{\partial T}{\partial i}\equiv \frac{A_u^{lT} 50 73 }{e_{1u} } \; \delta_{i+1 / 2} \left[ T \right]\;\;mask_u … … 52 75 (where mask$_{u}$ is the mask array at a $u$-point) ensures that the heat flux is zero inside land and 53 76 at the boundaries, since mask$_{u}$ is zero at solid boundaries which in this case are defined at $u$-points 54 (normal velocity $u$ remains zero at the coast) (\autoref{fig:LBC_uv}). 55 56 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 77 (normal velocity $u$ remains zero at the coast) (\autoref{fig:LBC_uv}). 78 57 79 \begin{figure}[!t] 58 \begin{center} 59 \includegraphics[width=\textwidth]{Fig_LBC_uv} 60 \caption{ 61 \protect\label{fig:LBC_uv} 62 Lateral boundary (thick line) at T-level. 63 The velocity normal to the boundary is set to zero. 64 } 65 \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} 66 86 \end{figure} 67 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>68 87 69 88 For momentum the situation is a bit more complex as two boundary conditions must be provided along the coast … … 79 98 and is required in order to compute the vorticity at the coast. 80 99 Four different types of lateral boundary condition are available, 81 controlled by the value of the \np{rn \_shlat} namelist parameter100 controlled by the value of the \np{rn_shlat}{rn\_shlat} namelist parameter 82 101 (The value of the mask$_{f}$ array along the coastline is set equal to this parameter). 83 102 These are: 84 103 85 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>86 104 \begin{figure}[!p] 87 \begin{center} 88 \includegraphics[width=\textwidth]{Fig_LBC_shlat} 89 \caption{ 90 \protect\label{fig:LBC_shlat} 91 lateral boundary condition 92 (a) free-slip ($rn\_shlat=0$); 93 (b) no-slip ($rn\_shlat=2$); 94 (c) "partial" free-slip ($0<rn\_shlat<2$) and 95 (d) "strong" no-slip ($2<rn\_shlat$). 96 Implied "ghost" velocity inside land area is display in grey. 97 } 98 \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} 99 115 \end{figure} 100 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>101 116 102 117 \begin{description} 103 118 104 \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 105 120 the coastline is equal to the offshore velocity, 106 \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, 107 122 so the vorticity: mask$_{f}$ array is set to zero inside the land and just at the coast 108 123 (\autoref{fig:LBC_shlat}-a). 109 124 110 \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. 111 126 Assuming that the tangential velocity decreases linearly from 112 127 the closest ocean velocity grid point to the coastline, … … 114 129 the closest ocean velocity gridpoint were of the same magnitude but in the opposite direction 115 130 (\autoref{fig:LBC_shlat}-b). 116 Therefore, the vorticity along the coastlines is given by: 131 Therefore, the vorticity along the coastlines is given by: 117 132 118 133 \[ … … 123 138 the no-slip boundary condition, simply by multiplying it by the mask$_{f}$ : 124 139 \[ 125 % \label{eq: lbc_bbbb}140 % \label{eq:LBC_bbbb} 126 141 \zeta \equiv \frac{1}{e_{1f} {\kern 1pt}e_{2f} }\left( {\delta_{i+1/2} 127 142 \left[ {e_{2v} \,v} \right]-\delta_{j+1/2} \left[ {e_{1u} \,u} \right]} … … 129 144 \] 130 145 131 \item ["partial" free-slip boundary condition (0$<$\np{rn\_shlat}$<$2):] the tangential velocity at132 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 133 148 not strong enough to make the tangential velocity at the coast vanish (\autoref{fig:LBC_shlat}-c). 134 149 This can be selected by providing a value of mask$_{f}$ strictly inbetween $0$ and $2$. 135 150 136 \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 137 152 be smaller than half the grid size (\autoref{fig:LBC_shlat}-d). 138 153 The friction is thus larger than in the no-slip case. … … 140 155 \end{description} 141 156 142 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), 143 158 the lateral boundary condition on tangential velocity is of much less importance as 144 159 it is only applied next to the coast where the minimum water depth can be quite shallow. 145 160 146 147 % ================================================================ 148 % Boundary Condition around the Model Domain 149 % ================================================================ 150 \section[Model domain boundary condition (\texttt{jperio})] 151 {Model domain boundary condition (\protect\np{jperio})} 161 %% ================================================================================================= 162 \section[Model domain boundary condition (\forcode{jperio})]{Model domain boundary condition (\protect\jp{jperio})} 152 163 \label{sec:LBC_jperio} 153 164 … … 155 166 closed, cyclic east-west, cyclic north-south, a north-fold, and combination closed-north fold or 156 167 bi-cyclic east-west and north-fold. 157 The north-fold boundary condition is associated with the 3-pole ORCA mesh. 158 159 % ------------------------------------------------------------------------------------------------------------- 160 % Closed, cyclic (\np{jperio}\forcode{ = 0..2}) 161 % ------------------------------------------------------------------------------------------------------------- 162 \subsection[Closed, cyclic (\forcode{jperio = [0127]})] 163 {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})} 164 172 \label{subsec:LBC_jperio012} 165 173 166 174 The choice of closed or cyclic model domain boundary condition is made by 167 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}. 168 176 Each time such a boundary condition is needed, it is set by a call to routine \mdl{lbclnk}. 169 177 The computation of momentum and tracer trends proceeds from $i=2$ to $i=jpi-1$ and from $j=2$ to $j=jpj-1$, 170 \ie in the model interior.178 \ie\ in the model interior. 171 179 To choose a lateral model boundary condition is to specify the first and last rows and columns of 172 the model variables. 180 the model variables. 173 181 174 182 \begin{description} 175 183 176 \item[For closed boundary (\np{jperio}\forcode{ = 0})], 177 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: 178 185 first and last rows and columns are set to zero. 179 186 180 \item[For cyclic east-west boundary (\np{jperio}\forcode{ = 1})], 181 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 182 188 the value of the last-but-one column and the last column to the value of the second one 183 189 (\autoref{fig:LBC_jperio}-a). 184 190 Whatever flows out of the eastern (western) end of the basin enters the western (eastern) end. 185 191 186 \item[For cyclic north-south boundary (\np{jperio}\forcode{ = 2})], 187 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 188 193 the value of the last-but-one row and the last row to the value of the second one 189 194 (\autoref{fig:LBC_jperio}-a). 190 195 Whatever flows out of the northern (southern) end of the basin enters the southern (northern) end. 191 196 192 \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. 193 198 194 199 \end{description} 195 200 196 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>197 201 \begin{figure}[!t] 198 \begin{center} 199 \includegraphics[width=\textwidth]{Fig_LBC_jperio} 200 \caption{ 201 \protect\label{fig:LBC_jperio} 202 setting of (a) east-west cyclic (b) symmetric across the equator boundary conditions. 203 } 204 \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} 205 207 \end{figure} 206 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 207 208 % ------------------------------------------------------------------------------------------------------------- 209 % North fold (\textit{jperio = 3 }to $6)$ 210 % ------------------------------------------------------------------------------------------------------------- 211 \subsection[North-fold (\forcode{jperio = [3-6]})] 212 {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})} 213 211 \label{subsec:LBC_north_fold} 214 212 215 213 The north fold boundary condition has been introduced in order to handle the north boundary of 216 214 a three-polar ORCA grid. 217 Such a grid has two poles in the northern hemisphere (\autoref{fig: MISC_ORCA_msh},218 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}. 219 217 Further information can be found in \mdl{lbcnfd} module which applies the north fold boundary condition. 220 218 221 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>222 219 \begin{figure}[!t] 223 \begin{center} 224 \includegraphics[width=\textwidth]{Fig_North_Fold_T} 225 \caption{ 226 \protect\label{fig:North_Fold_T} 227 North fold boundary with a $T$-point pivot and cyclic east-west boundary condition ($jperio=4$), 228 as used in ORCA 2, 1/4, and 1/12. 229 Pink shaded area corresponds to the inner domain mask (see text). 230 } 231 \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} 232 227 \end{figure} 233 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 234 235 % ==================================================================== 236 % Exchange with neighbouring processors 237 % ==================================================================== 238 \section[Exchange with neighbouring processors (\textit{lbclnk.F90}, \textit{lib\_mpp.F90})] 239 {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})} 240 231 \label{sec:LBC_mpp} 241 232 233 \begin{listing} 234 \nlst{nammpp} 235 \caption{\forcode{&nammpp}} 236 \label{lst:nammpp} 237 \end{listing} 238 242 239 For massively parallel processing (mpp), a domain decomposition method is used. 243 The basic idea of the method is to split the large computation domain of a numerical experiment into 244 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. 245 242 Each processor has its own local memory and computes the model equation over a subdomain of the whole model domain. 246 The subdomain boundary conditions are specified through communications between processors which 247 are organized by explicit statements (message passing method). 248 249 A big advantage is that the method does not need many modifications of the initial \fortran code. 250 From the modeller's point of view, each sub domain running on a processor is identical to the "mono-domain" code. 251 In addition, the programmer manages the communications between subdomains, 252 and the code is faster when the number of processors is increased. 253 The porting of OPA code on an iPSC860 was achieved during Guyon's PhD [Guyon et al. 1994, 1995] 254 in collaboration with CETIIS and ONERA. 255 The implementation in the operational context and the studies of performance on 256 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). 257 245 The present implementation is largely inspired by Guyon's work [Guyon 1995]. 258 246 … … 261 249 depend at the very most on one neighbouring point. 262 250 The only non-local computations concern the vertical physics 263 (implicit diffusion, turbulent closure scheme, ...) (delocalization over the whole water column), 264 and the solving of the elliptic equation associated with the surface pressure gradient computation 265 (delocalization over the whole horizontal domain). 251 (implicit diffusion, turbulent closure scheme, ...). 266 252 Therefore, a pencil strategy is used for the data sub-structuration: 267 253 the 3D initial domain is laid out on local processor memories following a 2D horizontal topological splitting. … … 272 258 After a computation, a communication phase starts: 273 259 each processor sends to its neighbouring processors the update values of the points corresponding to 274 the interior overlapping area to its neighbouring sub-domain (\ie the innermost of the two overlapping rows). 275 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. 276 265 The data exchanges between processors are required at the very place where 277 266 lateral domain boundary conditions are set in the mono-domain computation: 278 267 the \rou{lbc\_lnk} routine (found in \mdl{lbclnk} module) which manages such conditions is interfaced with 279 routines found in \mdl{lib\_mpp} module when running on an MPP computer (\ie when \key{mpp\_mpi} defined). 280 It has to be pointed out that when using the MPP version of the model, 281 the east-west cyclic boundary condition is done implicitly, 282 whilst the south-symmetric boundary condition option is not available. 283 284 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 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 285 272 \begin{figure}[!t] 286 \begin{center} 287 \includegraphics[width=\textwidth]{Fig_mpp} 288 \caption{ 289 \protect\label{fig:mpp} 290 Positioning of a sub-domain when massively parallel processing is used. 291 } 292 \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} 293 277 \end{figure} 294 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 295 296 In the standard version of \NEMO, the splitting is regular and arithmetic. 297 The i-axis is divided by \jp{jpni} and 298 the j-axis by \jp{jpnj} for a number of processors \jp{jpnij} most often equal to $jpni \times jpnj$ 299 (parameters set in \ngn{nammpp} namelist). 300 Each processor is independent and without message passing or synchronous process, 301 programs run alone and access just its own local memory. 302 For this reason, the main model dimensions are now the local dimensions of the subdomain (pencil) that 303 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}. 304 290 These dimensions include the internal domain and the overlapping rows. 305 The number of rows to exchange (known as the halo) is usually set to one (\jp{jpreci}=1, in \mdl{par\_oce}). 306 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}. 307 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: 308 304 \[ 309 jpi = ( jpiglo-2*jpreci + (jpni-1) ) / jpni + 2*jpreci 310 jpj = ( jpjglo-2*jprecj + (jpnj-1) ) / jpnj + 2*jprecj 311 \] 312 where \jp{jpni}, \jp{jpnj} are the number of processors following the i- and j-axis. 313 314 One also defines variables nldi and nlei which correspond to the internal domain bounds, 315 and the variables nimpp and njmpp which are the position of the (1,1) grid-point in the global domain. 316 An element of $T_{l}$, a local array (subdomain) corresponds to an element of $T_{g}$, 317 a global array (whole domain) by the relationship: 318 \[ 319 % \label{eq:lbc_nimpp} 305 % \label{eq:LBC_nimpp} 320 306 T_{g} (i+nimpp-1,j+njmpp-1,k) = T_{l} (i,j,k), 321 307 \] 322 with $1 \leq i \leq jpi$, $1 \leq j \leq jpj $ , and $1 \leq k \leq jpk$. 323 324 Processors are numbered from 0 to $jpnij-1$, the number is saved in the variable nproc. 325 In the standard version, a processor has no more than 326 four neighbouring processors named nono (for north), noea (east), noso (south) and nowe (west) and 327 two variables, nbondi and nbondj, indicate the relative position of the processor: 328 \begin{itemize} 329 \item nbondi = -1 an east neighbour, no west processor, 330 \item nbondi = 0 an east neighbour, a west neighbour, 331 \item nbondi = 1 no east processor, a west neighbour, 332 \item nbondi = 2 no splitting following the i-axis. 333 \end{itemize} 334 During the simulation, processors exchange data with their neighbours. 335 If there is effectively a neighbour, the processor receives variables from this processor on its overlapping row, 336 and sends the data issued from internal domain corresponding to the overlapping row of the other processor. 337 338 339 The \NEMO model computes equation terms with the help of mask arrays (0 on land points and 1 on sea points). 340 It is easily readable and very efficient in the context of a computer with vectorial architecture. 341 However, in the case of a scalar processor, computations over the land regions become more expensive in 342 terms of CPU time. 343 It is worse when we use a complex configuration with a realistic bathymetry like the global ocean where 344 more than 50 \% of points are land points. 345 For this reason, a pre-processing tool can be used to choose the mpp domain decomposition with a maximum number of 346 only land points processors, which can then be eliminated (\autoref{fig:mppini2}) 347 (For example, the mpp\_optimiz tools, available from the DRAKKAR web site). 348 This optimisation is dependent on the specific bathymetry employed. 349 The user then chooses optimal parameters \jp{jpni}, \jp{jpnj} and \jp{jpnij} with $jpnij < jpni \times jpnj$, 350 leading to the elimination of $jpni \times jpnj - jpnij$ land processors. 351 When those parameters are specified in \ngn{nammpp} namelist, 352 the algorithm in the \rou{inimpp2} routine sets each processor's parameters (nbound, nono, noea,...) so that 353 the land-only processors are not taken into account. 354 355 \gmcomment{Note that the inimpp2 routine is general so that the original inimpp 356 routine should be suppressed from the code.} 357 358 When land processors are eliminated, 359 the value corresponding to these locations in the model output files is undefined. 360 Note that this is a problem for the meshmask file which requires to be defined over the whole domain. 361 Therefore, user should not eliminate land processors when creating a meshmask file 362 (\ie when setting a non-zero value to \np{nn\_msh}). 363 364 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 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 365 325 \begin{figure}[!ht] 366 \begin{center} 367 \includegraphics[width=\textwidth]{Fig_mppini2} 368 \caption { 369 \protect\label{fig:mppini2} 370 Example of Atlantic domain defined for the CLIPPER projet. 371 Initial grid is composed of 773 x 1236 horizontal points. 372 (a) the domain is split onto 9 \time 20 subdomains (jpni=9, jpnj=20). 373 52 subdomains are land areas. 374 (b) 52 subdomains are eliminated (white rectangles) and 375 the resulting number of processors really used during the computation is jpnij=128. 376 } 377 \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} 378 336 \end{figure} 379 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 380 381 382 % ==================================================================== 383 % Unstructured open boundaries BDY 384 % ==================================================================== 337 338 %% ================================================================================================= 385 339 \section{Unstructured open boundary conditions (BDY)} 386 340 \label{sec:LBC_bdy} 387 341 388 %-----------------------------------------nambdy-------------------------------------------- 389 390 \nlst{nambdy} 391 %----------------------------------------------------------------------------------------------- 392 %-----------------------------------------nambdy_dta-------------------------------------------- 393 394 \nlst{nambdy_dta} 395 %----------------------------------------------------------------------------------------------- 396 397 Options are defined through the \ngn{nambdy} \ngn{nambdy\_dta} namelist variables. 398 The BDY module is the core implementation of open boundary conditions for regional configurations on 399 temperature, salinity, barotropic and baroclinic velocities, as well as ice concentration, ice and snow thicknesses). 400 401 The BDY module was modelled on the OBC module (see NEMO 3.4) and shares many features and 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 402 359 a similar coding structure \citep{chanut_rpt05}. 403 360 The specification of the location of the open boundary is completely flexible and 404 allows for example the open boundary to follow an isobath or other irregular contour.405 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. 406 363 See the section on the Input Boundary Data Files for details. 407 364 408 % ----------------------------------------------365 %% ================================================================================================= 409 366 \subsection{Namelists} 410 \label{subsec: BDY_namelist}411 412 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} . 413 370 It is possible to define more than one boundary ``set'' and apply different boundary conditions to each set. 414 The number of boundary sets is defined by \np{nb\_bdy}. 415 Each boundary set may be defined as a set of straight line segments in a namelist 416 (\np{ln\_coords\_file}\forcode{ = .false.}) or read in from a file (\np{ln\_coords\_file}\forcode{ = .true.}). 417 If the set is defined in a namelist, then the namelists \ngn{nambdy\_index} must be included separately, one for each set. 418 If the set is defined by a file, then a ``\ifile{coordinates.bdy}'' file must be provided. 419 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. 420 375 In the example above, there are two boundary sets, the first of which is defined via a file and 421 the second is defined in anamelist.422 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}. 423 378 424 379 For each boundary set a boundary condition has to be chosen for the barotropic solution 425 (``u2d'':sea-surface height and barotropic velocities), for the baroclinic velocities (``u3d''), 426 for the active tracers \footnote{The BDY module does not deal with passive tracers at this version} (``tra''), and sea-ice (``ice''). 427 For each set of variables there is a choice of algorithm and a choice for the data, 428 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).\\ 429 383 430 384 The choice of algorithm is currently as follows: 431 385 432 386 \begin{description} 433 \item [\forcode{'none'}:] No boundary condition applied.387 \item [\forcode{'none'}:] No boundary condition applied. 434 388 So the solution will ``see'' the land points around the edge of the edge of the domain. 435 \item [\forcode{'specified'}:] Specified boundary condition applied (only available for baroclinic velocity and tracer variables).436 \item [\forcode{'neumann'}:] Value at the boundary are duplicated (No gradient). Only available for baroclinic velocity and tracer variables.437 \item [\forcode{'frs'}:] Flow Relaxation Scheme (FRS) available for all variables.438 \item [\forcode{'Orlanski'}:] Orlanski radiation scheme (fully oblique) for barotropic, baroclinic and tracer variables.439 \item [\forcode{'Orlanski_npo'}:] Orlanski radiation scheme for barotropic, baroclinic and tracer variables.440 \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. 441 395 \end{description} 442 396 443 The main choice for the boundary data is to use initial conditions as boundary data444 (\np {nn\_tra\_dta}\forcode{ = 0}) or to use external data from a file (\np{nn\_tra\_dta}\forcode{ = 1}).445 In case the 3d velocity data contain the total velocity (ie, baroclinic and barotropic velocity), 446 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} 447 401 For the barotropic solution there is also the option to use tidal harmonic forcing either by 448 itself (\np{nn\_dyn2d\_dta}\forcode{ = 2}) or in addition to other external data (\np{nn\_dyn2d\_dta}\forcode{ = 3}).\\ 449 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}. 450 451 If external boundary data is required then the \ngn{nambdy\_dta} namelist must be defined. 452 One \ngn{nambdy\_dta} namelist is required for each boundary set in the order in which 453 the boundary sets are defined in nambdy. 454 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 455 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). 456 409 The boundary data is read in using the fldread module, 457 so the \ngn{nambdy\_dta} namelist is in the format required for fldread. 458 For each variable required, the filename, the frequency of the files and 459 the frequency of the data in the files is given. 460 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'}.\\ 461 415 462 416 There is currently an option to vertically interpolate the open boundary data onto the native grid at run-time. 463 If \np{nn \_bdy\_jpk} $< -1$, it is assumed that the lateral boundary data are already on the native grid.464 However, if \np{nn \_bdy\_jpk} is set to the number of vertical levels present in the boundary data,465 a bilinear interpolation onto the native grid will be triggered at runtime. 466 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. 467 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, 468 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.\\ 469 423 470 In the example namelists given, two boundary sets are defined.424 In the example of given namelists, two boundary sets are defined. 471 425 The first set is defined via a file and applies FRS conditions to temperature and salinity and 472 426 Flather conditions to the barotropic variables. No condition specified for the baroclinic velocity and sea-ice. … … 474 428 Tidal harmonic forcing is also used. 475 429 The second set is defined in a namelist. 476 FRS conditions are applied on temperature and salinity and climatological data is read from initial condition files. 477 478 % ----------------------------------------------430 FRS conditions are applied on temperature and salinity and climatological data is read from initial condition files. 431 432 %% ================================================================================================= 479 433 \subsection{Flow relaxation scheme} 480 \label{subsec: BDY_FRS_scheme}434 \label{subsec:LBC_bdy_FRS_scheme} 481 435 482 436 The Flow Relaxation Scheme (FRS) \citep{davies_QJRMS76,engedahl_T95}, … … 485 439 Given a model prognostic variable $\Phi$ 486 440 \[ 487 % \label{eq: bdy_frs1}441 % \label{eq:LBC_bdy_frs1} 488 442 \Phi(d) = \alpha(d)\Phi_{e}(d) + (1-\alpha(d))\Phi_{m}(d)\;\;\;\;\; d=1,N 489 443 \] … … 494 448 the prognostic equation for $\Phi$ of the form: 495 449 \[ 496 % \label{eq: bdy_frs2}450 % \label{eq:LBC_bdy_frs2} 497 451 -\frac{1}{\tau}\left(\Phi - \Phi_{e}\right) 498 452 \] 499 453 where the relaxation time scale $\tau$ is given by a function of $\alpha$ and the model time step $\Delta t$: 500 454 \[ 501 % \label{eq: bdy_frs3}455 % \label{eq:LBC_bdy_frs3} 502 456 \tau = \frac{1-\alpha}{\alpha} \,\rdt 503 457 \] … … 505 459 is relaxed towards the external conditions over the rest of the FRS zone. 506 460 The application of a relaxation zone helps to prevent spurious reflection of 507 outgoing signals from the model boundary. 461 outgoing signals from the model boundary. 508 462 509 463 The function $\alpha$ is specified as a $tanh$ function: 510 464 \[ 511 % \label{eq: bdy_frs4}465 % \label{eq:LBC_bdy_frs4} 512 466 \alpha(d) = 1 - \tanh\left(\frac{d-1}{2}\right), \quad d=1,N 513 467 \] 514 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}. 515 469 This is typically set to a value between 8 and 10. 516 470 517 % ----------------------------------------------471 %% ================================================================================================= 518 472 \subsection{Flather radiation scheme} 519 \label{subsec: BDY_flather_scheme}473 \label{subsec:LBC_bdy_flather_scheme} 520 474 521 475 The \citet{flather_JPO94} scheme is a radiation condition on the normal, 522 476 depth-mean transport across the open boundary. 523 477 It takes the form 524 \begin{equation} \label{eq:bdy_fla1} 525 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), 526 481 \end{equation} 527 482 where $U$ is the depth-mean velocity normal to the boundary and $\eta$ is the sea surface height, … … 532 487 the external depth-mean normal velocity, 533 488 plus a correction term that allows gravity waves generated internally to exit the model boundary. 534 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, 535 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$. 536 $U$ and $U_{e}$ are defined on the $U$ or $V$ points with $nbr=1$, \ie between the two $T$ grid points.537 538 % ----------------------------------------------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 %% ================================================================================================= 539 494 \subsection{Orlanski radiation scheme} 540 \label{subsec: BDY_orlanski_scheme}495 \label{subsec:LBC_bdy_orlanski_scheme} 541 496 542 497 The Orlanski scheme is based on the algorithm described by \citep{marchesiello.mcwilliams.ea_OM01}, hereafter MMS. … … 544 499 The adaptive Orlanski condition solves a wave plus relaxation equation at the boundary: 545 500 \begin{equation} 546 \frac{\partial\phi}{\partial t} + c_x \frac{\partial\phi}{\partial x} + c_y \frac{\partial\phi}{\partial y} = 547 -\frac{1}{\tau}(\phi - \phi^{ext})548 \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}) 549 504 \end{equation} 550 505 … … 552 507 velocities are diagnosed from the model fields as: 553 508 554 \begin{equation} \label{eq:cx} 555 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} 556 512 \end{equation} 557 513 \begin{equation} 558 \label{eq:cy}559 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} 560 516 \end{equation} 561 517 562 518 (As noted by MMS, this is a circular diagnosis of the phase speeds which only makes sense on a discrete grid). 563 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$. 564 520 For $c_x$ outward, we have 565 521 … … 571 527 572 528 \begin{equation} 573 \tau = \tau_{in}\,\,\,;\,\,\, c_x = c_y = 0 574 \label{eq:tau_in} 529 \label{eq:LBC_tau_in} 530 \tau = \tau_{in}\,\,\,;\,\,\, c_x = c_y = 0 575 531 \end{equation} 576 532 577 Generally the relaxation time scale at inward propagation points \np{(rn\_time\_dmp}) is set much shorter than the time scale at outward propagation578 points (\np{rn \_time\_dmp\_out}) so that the solution is constrained more strongly by the external data at inward propagation points.579 See \autoref{subsec: BDY_relaxation} for detailed on the spatial shape of the scaling.\\580 The ``normal propagation of oblique radiation'' or NPO approximation (called \forcode{'orlanski_npo'}) involves assuming 581 that $c_y$ is zero in equation (\autoref{eq: wave_continuous}), but including582 this term in the denominator of equation (\autoref{eq: cx}). Both versions of the scheme are options in BDY. Equations583 (\autoref{eq: wave_continuous}) - (\autoref{eq:tau_in}) correspond to equations (13) - (15) and (2) - (3) in MMS.\\584 585 % ----------------------------------------------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 %% ================================================================================================= 586 542 \subsection{Relaxation at the boundary} 587 \label{subsec: BDY_relaxation}588 589 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.590 It is control by the namelist parameter \np{ln \_tra\_dmp} and \np{ln\_dyn3d\_dmp} for each boundary set.591 592 The relaxation time scale value (\np{rn \_time\_dmp} and \np{rn\_time\_dmp\_out}, $\tau$) are defined at the boundaries itself.593 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$): 594 550 595 551 \[ … … 597 553 \] 598 554 599 The same scaling is applied in the Orlanski damping. 600 601 % ----------------------------------------------555 The same scaling is applied in the Orlanski damping. 556 557 %% ================================================================================================= 602 558 \subsection{Boundary geometry} 603 \label{subsec: BDY_geometry}559 \label{subsec:LBC_bdy_geometry} 604 560 605 561 Each open boundary set is defined as a list of points. 606 562 The information is stored in the arrays $nbi$, $nbj$, and $nbr$ in the $idx\_bdy$ structure. 607 The $nbi$ and $nbj$ arrays define the local $(i,j)$ ind ices of each point in the boundary zone and608 the $nbr$ array defines the discrete distance from the boundary with $nbr=1$ meaningthat609 the point is next to the edge of the model domain and $nbr>1$ showingthat610 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. 611 567 A set of $nbi$, $nbj$, and $nbr$ arrays is defined for each of the $T$, $U$ and $V$ grids. 612 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. 613 569 614 570 The boundary geometry for each set may be defined in a namelist nambdy\_index or 615 571 by reading in a ``\ifile{coordinates.bdy}'' file. 616 572 The nambdy\_index namelist defines a series of straight-line segments for north, east, south and west boundaries. 617 One nambdy\_index namelist bloc is needed for each boundary condition defined by indexes.618 For the northern boundary, \ np{nbdysegn} gives the number of segments,619 \ np{jpjnob} gives the $j$ index for each segment and \np{jpindt} and620 \ 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. 621 577 These segments define a list of $T$ grid points along the outermost row of the boundary ($nbr\,=\, 1$). 622 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}. 623 579 624 580 The boundary geometry may also be defined from a ``\ifile{coordinates.bdy}'' file. 625 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. 626 582 The file should contain the index arrays for each of the $T$, $U$ and $V$ grids. 627 583 The arrays must be in order of increasing $nbr$. … … 629 585 Typically this file will be used to generate external boundary data via interpolation and so 630 586 will also contain the latitudes and longitudes of each point as shown. 631 However, this is not necessary to run the model. 587 However, this is not necessary to run the model. 632 588 633 589 For some choices of irregular boundary the model domain may contain areas of ocean which 634 590 are not part of the computational domain. 635 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, 636 592 then the areas of ocean outside of this boundary will need to be masked out. 637 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. 638 594 Only one mask file is used even if multiple boundary sets are defined. 639 595 640 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>641 596 \begin{figure}[!t] 642 \begin{center} 643 \includegraphics[width=\textwidth]{Fig_LBC_bdy_geom} 644 \caption { 645 \protect\label{fig:LBC_bdy_geom} 646 Example of geometry of unstructured open boundary 647 } 648 \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} 649 601 \end{figure} 650 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 651 652 %---------------------------------------------- 602 603 %% ================================================================================================= 653 604 \subsection{Input boundary data files} 654 \label{subsec: BDY_data}605 \label{subsec:LBC_bdy_data} 655 606 656 607 The data files contain the data arrays in the order in which the points are defined in the $nbi$ and $nbj$ arrays. … … 658 609 a time dimension; 659 610 $xb$ which is the index of the boundary data point in the horizontal; 660 and $yb$ which is a degenerate dimension of 1 to enable the file to be read by the standard NEMOI/O routines.661 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. 662 613 663 614 From Version 3.4 there are new restrictions on the order in which the boundary points are defined … … 670 621 \item All the data for a particular boundary set must be in the same order. 671 622 (Prior to 3.4 it was possible to define barotropic data in a different order to 672 the data for tracers and baroclinic velocities). 623 the data for tracers and baroclinic velocities). 673 624 \end{enumerate} 674 625 675 626 These restrictions mean that data files used with versions of the 676 627 model prior to Version 3.4 may not work with Version 3.4 onwards. 677 A \fortran utility {\itshape bdy\_reorder} exists in the TOOLS directory which628 A \fortran\ utility {\itshape bdy\_reorder} exists in the TOOLS directory which 678 629 will re-order the data in old BDY data files. 679 630 680 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>681 631 \begin{figure}[!t] 682 \begin{center} 683 \includegraphics[width=\textwidth]{Fig_LBC_nc_header} 684 \caption { 685 \protect\label{fig:LBC_nc_header} 686 Example of the header for a \protect\ifile{coordinates.bdy} file 687 } 688 \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} 689 637 \end{figure} 690 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 691 692 %---------------------------------------------- 638 639 %% ================================================================================================= 693 640 \subsection{Volume correction} 694 \label{subsec: BDY_vol_corr}641 \label{subsec:LBC_bdy_vol_corr} 695 642 696 643 There is an option to force the total volume in the regional model to be constant. 697 This is controlled by the \np{ln \_vol} parameter in the namelist.698 A value of \np {ln\_vol}\forcode{ = .false.} indicates that this option is not used.699 Two options to control the volume are available (\np{nn \_volctl}).700 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 701 648 each timestep to ensure that the integrated volume flow through the boundary is zero. 702 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 703 650 the timestep includes the change due to the freshwater flux across the surface and 704 651 the correction velocity corrects for this as well. … … 707 654 applied to all boundaries at once. 708 655 709 % ----------------------------------------------656 %% ================================================================================================= 710 657 \subsection{Tidal harmonic forcing} 711 \label{subsec:BDY_tides} 712 713 %-----------------------------------------nambdy_tide-------------------------------------------- 714 715 \nlst{nambdy_tide} 716 %----------------------------------------------------------------------------------------------- 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} 717 665 718 666 Tidal forcing at open boundaries requires the activation of surface 719 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 720 668 \forcode{.true.} and the required constituents need to be activated by 721 including their names in the \np{c name} array; see669 including their names in the \np{clname}{clname} array; see 722 670 \autoref{sec:SBC_tide}). Specific options related to the reading in of 723 671 the complex harmonic amplitudes of elevation (SSH) and barotropic 724 672 velocity (u,v) at open boundaries are defined through the 725 \n gn{nambdy\_tide} namelist parameters.\\673 \nam{bdy_tide}{bdy\_tide} namelist parameters.\\ 726 674 727 675 The tidal harmonic data at open boundaries can be specified in two 728 676 different ways, either on a two-dimensional grid covering the entire 729 677 model domain or along open boundary segments; these two variants can 730 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 731 679 \forcode{.false.}, respectively. In either case, the real and 732 680 imaginary parts of SSH and the two barotropic velocity components for … … 734 682 separately: when two-dimensional data is used, variables 735 683 \textit{tcname\_z1} and \textit{tcname\_z2} for real and imaginary SSH, 736 respectively, are expected in input file \np{filtide} with suffix684 respectively, are expected in input file \np{filtide}{filtide} with suffix 737 685 \ifile{\_grid\_T}, variables \textit{tcname\_u1} and 738 686 \textit{tcname\_u2} for real and imaginary u, respectively, are 739 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 740 688 \textit{tcname\_v1} and \textit{tcname\_v2} for real and imaginary v, 741 respectively, are expected in input file \np{filtide} with suffix689 respectively, are expected in input file \np{filtide}{filtide} with suffix 742 690 \ifile{\_grid\_V}; when data along open boundary segments is used, 743 691 variables \textit{z1} and \textit{z2} (real and imaginary part of SSH) 744 are expected to be available from file \np{filtide} with suffix692 are expected to be available from file \np{filtide}{filtide} with suffix 745 693 \ifile{tcname\_grid\_T}, variables \textit{u1} and \textit{u2} (real 746 694 and imaginary part of u) are expected to be available from file 747 \np{filtide} with suffix \ifile{tcname\_grid\_U}, and variables695 \np{filtide}{filtide} with suffix \ifile{tcname\_grid\_U}, and variables 748 696 \textit{v1} and \textit{v2} (real and imaginary part of v) are 749 expected to be available from file \np{filtide} with suffix750 \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 751 699 \forcode{.true.}, the data is expected to be in complex conjugate 752 700 form. … … 760 708 direction of rotation). %, e.g. anticlockwise or clockwise. 761 709 762 \biblio 763 764 \pindex 710 \subinc{\input{../../global/epilogue}} 765 711 766 712 \end{document} -
NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_LDF.tex
r11179 r12149 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 (\textit{ldfslp.F90})] 41 {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})} 42 68 \label{sec:LDF_slp} 43 69 44 %%% 45 \gmcomment{ 70 \cmtgm{ 46 71 we should emphasize here that the implementation is a rather old one. 47 72 Better work can be achieved by using \citet{griffies.gnanadesikan.ea_JPO98, griffies_bk04} iso-neutral scheme. … … 50 75 A direction for lateral mixing has to be defined when the desired operator does not act along the model levels. 51 76 This occurs when $(a)$ horizontal mixing is required on tracer or momentum 52 (\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, 53 78 and $(b)$ isoneutral mixing is required whatever the vertical coordinate is. 54 79 This direction of mixing is defined by its slopes in the \textbf{i}- and \textbf{j}-directions at the face of 55 80 the cell of the quantity to be diffused. 56 81 For a tracer, this leads to the following four slopes: 57 $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}), 58 83 while for momentum the slopes are $r_{1t}$, $r_{1uw}$, $r_{2f}$, $r_{2uw}$ for $u$ and 59 $r_{1f}$, $r_{1vw}$, $r_{2t}$, $r_{2vw}$ for $v$. 60 61 %gm% add here afigure of the slope in i-direction 62 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 %% ================================================================================================= 63 89 \subsection{Slopes for tracer geopotential mixing in the $s$-coordinate} 64 90 65 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 66 92 the geopotential and computational surfaces. 67 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 68 94 the diffusive fluxes in the three directions are set to zero and $T$ is assumed to be horizontally uniform, 69 \ie a linear function of $z_T$, the depth of a $T$-point. 70 %gm { Steven : My version is obviously wrong since I'm left with an arbitrary constant which is the local vertical temperature gradient} 71 72 \begin{equation} 73 \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} 74 101 \begin{aligned} 75 102 r_{1u} &= \frac{e_{3u}}{ \left( e_{1u}\;\overline{\overline{e_{3w}}}^{\,i+1/2,\,k} \right)} … … 86 113 \end{equation} 87 114 88 %gm% caution I'm not sure the simplification was a good idea! 89 90 These slopes are computed once in \rou{ldfslp\_init} when \np{ln\_sco}\forcode{ = .true.}rue, 91 and either \np{ln\_traldf\_hor}\forcode{ = .true.} or \np{ln\_dynldf\_hor}\forcode{ = .true.}. 92 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 %% ================================================================================================= 93 121 \subsection{Slopes for tracer iso-neutral mixing} 94 122 \label{subsec:LDF_slp_iso} … … 97 125 Their formulation does not depend on the vertical coordinate used. 98 126 Their discrete formulation is found using the fact that the diffusive fluxes of 99 locally referenced potential density (\ie $in situ$ density) vanish.100 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 101 129 the three directions to zero leads to the following definition for the neutral slopes: 102 130 103 131 \begin{equation} 104 \label{eq: ldfslp_iso}132 \label{eq:LDF_slp_iso} 105 133 \begin{split} 106 134 r_{1u} &= \frac{e_{3u}}{e_{1u}}\; \frac{\delta_{i+1/2}[\rho]} … … 117 145 \end{equation} 118 146 119 %gm% rewrite this as the explanation is not very clear !!! 120 %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.121 122 %By definition, neutral surfaces are tangent to the local $in situ$ density \citep{mcdougall_JPO87}, 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).123 124 %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.125 126 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 127 155 be evaluated at the same local pressure 128 156 (which, in decibars, is approximated by the depth in meters in the model). 129 Therefore \autoref{eq: ldfslp_iso} cannot be used as such,157 Therefore \autoref{eq:LDF_slp_iso} cannot be used as such, 130 158 but further transformation is needed depending on the vertical coordinate used: 131 159 132 160 \begin{description} 133 134 \item[$z$-coordinate with full step: ] 135 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, 136 162 thus the $in situ$ density can be used. 137 163 This is not the case for the vertical derivatives: $\delta_{k+1/2}[\rho]$ is replaced by $-\rho N^2/g$, 138 164 where $N^2$ is the local Brunt-Vais\"{a}l\"{a} frequency evaluated following \citet{mcdougall_JPO87} 139 (see \autoref{subsec:TRA_bn2}). 140 141 \item[$z$-coordinate with partial step: ] 142 this case is identical to the full step case except that at partial step level, 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, 143 167 the \emph{horizontal} density gradient is evaluated as described in \autoref{sec:TRA_zpshde}. 144 145 \item[$s$- or hybrid $s$-$z$- coordinate: ] 146 in the current release of \NEMO, iso-neutral mixing is only employed for $s$-coordinates if 147 the Griffies scheme is used (\np{traldf\_grif}\forcode{ = .true.}; 148 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}). 149 171 In other words, iso-neutral mixing will only be accurately represented with a linear equation of state 150 (\np {nn\_eos}\forcode{ = 1..2}).151 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} 152 174 will include a pressure dependent part, leading to the wrong evaluation of the neutral slopes. 153 175 154 %gm%155 176 Note: The solution for $s$-coordinate passes trough the use of different (and better) expression for 156 177 the constraint on iso-neutral fluxes. … … 161 182 \alpha \ \textbf{F}(T) = \beta \ \textbf{F}(S) 162 183 \] 163 % gm{where vector F is ....}184 \cmtgm{where vector F is ....} 164 185 165 186 This constraint leads to the following definition for the slopes: 166 187 167 188 \[ 168 % \label{eq: ldfslp_iso2}189 % \label{eq:LDF_slp_iso2} 169 190 \begin{split} 170 191 r_{1u} &= \frac{e_{3u}}{e_{1u}}\; \frac … … 194 215 195 216 Note that such a formulation could be also used in the $z$-coordinate and $z$-coordinate with partial steps cases. 196 197 217 \end{description} 198 218 199 219 This implementation is a rather old one. 200 It is similar to the one proposed by Cox [1987], except for the background horizontal diffusion.201 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 202 222 a minimum background horizontal diffusion for numerical stability reasons. 203 223 To overcome this problem, several techniques have been proposed in which the numerical schemes of 204 224 the ocean model are modified \citep{weaver.eby_JPO97, griffies.gnanadesikan.ea_JPO98}. 205 Griffies's scheme is now available in \NEMO if \np{traldf\_grif\_iso} is set true; see Appdx \autoref{apdx:triad}.225 Griffies's scheme is now available in \NEMO\ if \np[=.true.]{ln_traldf_triad}{ln\_traldf\_triad}; see \autoref{apdx:TRIADS}. 206 226 Here, another strategy is presented \citep{lazar_phd97}: 207 227 a local filtering of the iso-neutral slopes (made on 9 grid-points) prevents the development of … … 209 229 This allows an iso-neutral diffusion scheme without additional background horizontal mixing. 210 230 This technique can be viewed as a diffusion operator that acts along large-scale 211 (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. 212 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. 213 233 214 234 Nevertheless, this iso-neutral operator does not ensure that variance cannot increase, 215 contrary to the \citet{griffies.gnanadesikan.ea_JPO98} operator which has that property. 216 217 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 235 contrary to the \citet{griffies.gnanadesikan.ea_JPO98} operator which has that property. 236 218 237 \begin{figure}[!ht] 219 \begin{center} 220 \includegraphics[width=\textwidth]{Fig_LDF_ZDF1} 221 \caption { 222 \protect\label{fig:LDF_ZDF1} 223 averaging procedure for isopycnal slope computation. 224 } 225 \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} 226 242 \end{figure} 227 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 228 229 %There are three additional questions about the slope calculation. 230 %First the expression for the rotation tensor has been obtain assuming the "small slope" approximation, so a bound has to be imposed on slopes. 231 %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. 232 247 %Third, the question of boundary condition specified on slopes... 233 248 234 249 %from griffies: chapter 13.1.... 235 250 236 237 238 % In addition and also for numerical stability reasons \citep{cox_OM87, griffies_bk04}, 239 % the slopes are bounded by $1/100$ everywhere. This limit is decreasing linearly 240 % 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 241 254 % surface motivates this flattening of isopycnals near the surface). 242 255 243 256 For numerical stability reasons \citep{cox_OM87, griffies_bk04}, the slopes must also be bounded by 244 $1/100$everywhere.257 the namelist scalar \np{rn_slpmax}{rn\_slpmax} (usually $1/100$) everywhere. 245 258 This constraint is applied in a piecewise linear fashion, increasing from zero at the surface to 246 259 $1/100$ at $70$ metres and thereafter decreasing to zero at the bottom of the ocean 247 260 (the fact that the eddies "feel" the surface motivates this flattening of isopycnals near the surface). 248 249 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 261 \colorbox{yellow}{The way slopes are tapered has be checked. Not sure that this is still what is actually done.} 262 250 263 \begin{figure}[!ht] 251 \begin{center} 252 \includegraphics[width=\textwidth]{Fig_eiv_slp} 253 \caption{ 254 \protect\label{fig:eiv_slp} 255 Vertical profile of the slope used for lateral mixing in the mixed layer: 256 \textit{(a)} in the real ocean the slope is the iso-neutral slope in the ocean interior, 257 which has to be adjusted at the surface boundary 258 \ie it must tend to zero at the surface since there is no mixing across the air-sea interface: 259 wall boundary condition). 260 Nevertheless, the profile between the surface zero value and the interior iso-neutral one is unknown, 261 and especially the value at the base of the mixed layer; 262 \textit{(b)} profile of slope using a linear tapering of the slope near the surface and 263 imposing a maximum slope of 1/100; 264 \textit{(c)} profile of slope actually used in \NEMO: a linear decrease of the slope from 265 zero at the surface to its ocean interior value computed just below the mixed layer. 266 Note the huge change in the slope at the base of the mixed layer between \textit{(b)} and \textit{(c)}. 267 } 268 \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} 269 283 \end{figure} 270 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>271 284 272 285 \colorbox{yellow}{add here a discussion about the flattening of the slopes, vs tapering the coefficient.} 273 286 287 %% ================================================================================================= 274 288 \subsection{Slopes for momentum iso-neutral mixing} 275 289 276 290 The iso-neutral diffusion operator on momentum is the same as the one used on tracers but 277 291 applied to each component of the velocity separately 278 (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}). 279 293 The slopes between the surface along which the diffusion operator acts and the surface of computation 280 294 ($z$- or $s$-surfaces) are defined at $T$-, $f$-, and \textit{uw}- points for the $u$-component, and $T$-, $f$- and 281 295 \textit{vw}- points for the $v$-component. 282 296 They are computed from the slopes used for tracer diffusion, 283 \ie \autoref{eq:ldfslp_geo} and \autoref{eq:ldfslp_iso}:297 \ie\ \autoref{eq:LDF_slp_geo} and \autoref{eq:LDF_slp_iso}: 284 298 285 299 \[ 286 % \label{eq: ldfslp_dyn}300 % \label{eq:LDF_slp_dyn} 287 301 \begin{aligned} 288 302 &r_{1t}\ \ = \overline{r_{1u}}^{\,i} &&& r_{1f}\ \ &= \overline{r_{1u}}^{\,i+1/2} \\ … … 295 309 The major issue remaining is in the specification of the boundary conditions. 296 310 The same boundary conditions are chosen as those used for lateral diffusion along model level surfaces, 297 \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 298 312 (see \autoref{sec:LBC_coast}). 299 313 300 301 % ================================================================ 302 % Lateral Mixing Operator 303 % ================================================================ 304 \section[Lateral mixing operators (\textit{traldf.F90})] 305 {Lateral mixing operators (\protect\mdl{traldf}, \protect\mdl{traldf})} 306 \label{sec:LDF_op} 307 308 309 310 % ================================================================ 311 % Lateral Mixing Coefficients 312 % ================================================================ 313 \section[Lateral mixing coefficient (\textit{ldftra.F90}, \textit{ldfdyn.F90})] 314 {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})} 315 316 \label{sec:LDF_coef} 316 317 317 Introducing a space variation in the lateral eddy mixing coefficients changes the model core memory requirement, 318 adding up to four extra three-dimensional arrays for the geopotential or isopycnal second order operator applied to 319 momentum. 320 Six CPP keys control the space variation of eddy coefficients: three for momentum and three for tracer. 321 The three choices allow: 322 a space variation in the three space directions (\key{traldf\_c3d}, \key{dynldf\_c3d}), 323 in the horizontal plane (\key{traldf\_c2d}, \key{dynldf\_c2d}), 324 or in the vertical only (\key{traldf\_c1d}, \key{dynldf\_c1d}). 325 The default option is a constant value over the whole ocean on both momentum and tracers. 326 327 The number of additional arrays that have to be defined and the gridpoint position at which 328 they are defined depend on both the space variation chosen and the type of operator used. 329 The resulting eddy viscosity and diffusivity coefficients can be a function of more than one variable. 330 Changes in the computer code when switching from one option to another have been minimized by 331 introducing the eddy coefficients as statement functions 332 (include file \textit{ldftra\_substitute.h90} and \textit{ldfdyn\_substitute.h90}). 333 The functions are replaced by their actual meaning during the preprocessing step (CPP). 334 The specification of the space variation of the coefficient is made in \mdl{ldftra} and \mdl{ldfdyn}, 335 or more precisely in include files \textit{traldf\_cNd.h90} and \textit{dynldf\_cNd.h90}, with N=1, 2 or 3. 336 The user can modify these include files as he/she wishes. 337 The way the mixing coefficient are set in the reference version can be briefly described as follows: 338 339 \subsubsection{Constant mixing coefficients (default option)} 340 When none of the \key{dynldf\_...} and \key{traldf\_...} keys are defined, 341 a constant value is used over the whole ocean for momentum and tracers, 342 which is specified through the \np{rn\_ahm0} and \np{rn\_aht0} namelist parameters. 343 344 \subsubsection[Vertically varying mixing coefficients (\texttt{\textbf{key\_traldf\_c1d}} and \texttt{\textbf{key\_dynldf\_c1d}})] 345 {Vertically varying mixing coefficients (\protect\key{traldf\_c1d} and \key{dynldf\_c1d})} 346 The 1D option is only available when using the $z$-coordinate with full step. 347 Indeed in all the other types of vertical coordinate, 348 the depth is a 3D function of (\textbf{i},\textbf{j},\textbf{k}) and therefore, 349 introducing depth-dependent mixing coefficients will require 3D arrays. 350 In the 1D option, a hyperbolic variation of the lateral mixing coefficient is introduced in which 351 the surface value is \np{rn\_aht0} (\np{rn\_ahm0}), the bottom value is 1/4 of the surface value, 352 and the transition takes place around z=300~m with a width of 300~m 353 (\ie both the depth and the width of the inflection point are set to 300~m). 354 This profile is hard coded in file \textit{traldf\_c1d.h90}, but can be easily modified by users. 355 356 \subsubsection[Horizontally varying mixing coefficients (\texttt{\textbf{key\_traldf\_c2d}} and \texttt{\textbf{key\_dynldf\_c2d}})] 357 {Horizontally varying mixing coefficients (\protect\key{traldf\_c2d} and \protect\key{dynldf\_c2d})} 358 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 359 373 the type of operator used: 360 374 \begin{equation} 361 \label{eq: title}375 \label{eq:LDF_title} 362 376 A_l = \left\{ 363 377 \begin{aligned} 364 & \frac{ \max(e_1,e_2)}{e_{max}} A_o^l& \text{for laplacian operator } \\365 & \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 } 366 380 \end{aligned} 367 381 \right. 368 382 \end{equation} 369 where $e_{max}$ is the maximum of $e_1$ and $e_2$ taken over the whole masked ocean domain, 370 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}). 371 384 This variation is intended to reflect the lesser need for subgrid scale eddy mixing where 372 385 the grid size is smaller in the domain. 373 386 It was introduced in the context of the DYNAMO modelling project \citep{willebrand.barnier.ea_PO01}. 374 Note that such a grid scale dependance of mixing coefficients significantly increase the range of stability of375 model configurations presenting large changes in grid pacing such as global ocean models.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. 376 389 Indeed, in such a case, a constant mixing coefficient can lead to a blow up of the model due to 377 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}), 378 391 especially when using a bilaplacian operator. 379 392 380 Other formulations can be introduced by the user for a given configuration. 381 For example, in the ORCA2 global ocean model (see Configurations), 382 the laplacian viscosity operator uses \np{rn\_ahm0}~= 4.10$^4$ m$^2$/s poleward of 20$^{\circ}$ north and south and 383 decreases linearly to \np{rn\_aht0}~= 2.10$^3$ m$^2$/s at the equator \citep{madec.delecluse.ea_JPO96, delecluse.madec_icol99}. 384 This modification can be found in routine \rou{ldf\_dyn\_c2d\_orca} defined in \mdl{ldfdyn\_c2d}. 385 Similar modified horizontal variations can be found with the Antarctic or Arctic sub-domain options of 386 ORCA2 and ORCA05 (see \&namcfg namelist). 387 388 \subsubsection[Space varying mixing coefficients (\texttt{\textbf{key\_traldf\_c3d}} and \texttt{\textbf{key\_dynldf\_c3d}})] 389 {Space varying mixing coefficients (\protect\key{traldf\_c3d} and \key{dynldf\_c3d})} 390 391 The 3D space variation of the mixing coefficient is simply the combination of the 1D and 2D cases, 392 \ie a hyperbolic tangent variation with depth associated with a grid size dependence of 393 the magnitude of the coefficient. 394 395 \subsubsection{Space and time varying mixing coefficients} 396 397 There is no default specification of space and time varying mixing coefficient. 398 The only case available is specific to the ORCA2 and ORCA05 global ocean configurations. 399 It provides only a tracer mixing coefficient for eddy induced velocity (ORCA2) or both iso-neutral and 400 eddy induced velocity (ORCA05) that depends on the local growth rate of baroclinic instability. 401 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} 402 456 403 457 The following points are relevant when the eddy coefficient varies spatially: 404 458 405 459 (1) the momentum diffusion operator acting along model level surfaces is written in terms of curl and 406 divergent components of the horizontal current (see \autoref{subsec: PE_ldf}).460 divergent components of the horizontal current (see \autoref{subsec:MB_ldf}). 407 461 Although the eddy coefficient could be set to different values in these two terms, 408 this option is not currently available. 462 this option is not currently available. 409 463 410 464 (2) with an horizontally varying viscosity, the quadratic integral constraints on enstrophy and on the square of 411 465 the horizontal divergence for operators acting along model-surfaces are no longer satisfied 412 (\autoref{sec:dynldf_properties}). 413 414 (3) for isopycnal diffusion on momentum or tracers, an additional purely horizontal background diffusion with 415 uniform coefficient can be added by setting a non zero value of \np{rn\_ahmb0} or \np{rn\_ahtb0}, 416 a background horizontal eddy viscosity or diffusivity coefficient 417 (namelist parameters whose default values are $0$). 418 However, the technique used to compute the isopycnal slopes is intended to get rid of such a background diffusion, 419 since it introduces spurious diapycnal diffusion (see \autoref{sec:LDF_slp}). 420 421 (4) when an eddy induced advection term is used (\key{traldf\_eiv}), 422 $A^{eiv}$, the eddy induced coefficient has to be defined. 423 Its space variations are controlled by the same CPP variable as for the eddy diffusivity coefficient 424 (\ie \key{traldf\_cNd}). 425 426 (5) the eddy coefficient associated with a biharmonic operator must be set to a \emph{negative} value. 427 428 (6) it is possible to use both the laplacian and biharmonic operators concurrently. 429 430 (7) it is possible to run without explicit lateral diffusion on momentum 431 (\np{ln\_dynldf\_lap}\forcode{ = .?.}\np{ln\_dynldf\_bilap}\forcode{ = .false.}). 432 This is recommended when using the UBS advection scheme on momentum (\np{ln\_dynadv\_ubs}\forcode{ = .true.}, 433 see \autoref{subsec:DYN_adv_ubs}) and can be useful for testing purposes. 434 435 % ================================================================ 436 % Eddy Induced Mixing 437 % ================================================================ 438 \section[Eddy induced velocity (\textit{traadv\_eiv.F90}, \textit{ldfeiv.F90})] 439 {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 440 471 \label{sec:LDF_eiv} 441 472 473 \begin{listing} 474 \nlst{namtra_eiv} 475 \caption{\forcode{&namtra_eiv}} 476 \label{lst:namtra_eiv} 477 \end{listing} 478 442 479 %%gm from Triad appendix : to be incorporated.... 443 \ gmcomment{480 \cmtgm{ 444 481 Values of iso-neutral diffusivity and GM coefficient are set as described in \autoref{sec:LDF_coef}. 445 482 If none of the keys \key{traldf\_cNd}, N=1,2,3 is set (the default), spatially constant iso-neutral $A_l$ and 446 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}. 447 484 If 2D-varying coefficients are set with \key{traldf\_c2d} then $A_l$ is reduced in proportion with horizontal 448 485 scale factor according to \autoref{eq:title} … … 457 494 In this case, $A_e$ at low latitudes $|\theta|<20^{\circ}$ is further reduced by a factor $|f/f_{20}|$, 458 495 where $f_{20}$ is the value of $f$ at $20^{\circ}$~N 459 } (\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. 460 497 } 461 498 462 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}), 463 500 an eddy induced tracer advection term is added, 464 501 the formulation of which depends on the slopes of iso-neutral surfaces. 465 502 Contrary to the case of iso-neutral mixing, the slopes used here are referenced to the geopotential surfaces, 466 \ie \autoref{eq:ldfslp_geo} is used in $z$-coordinates, 467 and the sum \autoref{eq:ldfslp_geo} + \autoref{eq:ldfslp_iso} in $s$-coordinates. 468 The eddy induced velocity is given by: 469 \begin{equation} 470 \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} 471 509 \begin{split} 472 510 u^* & = \frac{1}{e_{2u}e_{3u}}\; \delta_k \left[e_{2u} \, A_{uw}^{eiv} \; \overline{r_{1w}}^{\,i+1/2} \right]\\ … … 475 513 \end{split} 476 514 \end{equation} 477 where $A^{eiv}$ is the eddy induced velocity coefficient whose value is set through \np{rn\_aeiv}, 478 a \textit{nam\_traldf} namelist parameter. 479 The three components of the eddy induced velocity are computed and 480 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. 481 518 This has been preferred to a separate computation of the advective trends associated with the eiv velocity, 482 519 since it allows us to take advantage of all the advection schemes offered for the tracers … … 484 521 previous releases of OPA \citep{madec.delecluse.ea_NPM98}. 485 522 This is particularly useful for passive tracers where \emph{positivity} of the advection scheme is of 486 paramount importance. 523 paramount importance. 487 524 488 525 At the surface, lateral and bottom boundaries, the eddy induced velocity, 489 and thus the advective eddy fluxes of heat and salt, are set to zero. 490 491 \biblio 492 493 \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}} 494 547 495 548 \end{document} -
NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_OBS.tex
r11151 r12149 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 ${\mathrm P}$ with with longitude and latitude $({\lambda_{}}_{\mathrm P}, \phi_{\mathrm P})$and603 Consider an observation point ${\mathrm P}$ with longitude and latitude (${\lambda_{}}_{\mathrm P}$, $\phi_{\mathrm P}$) and 576 604 the four nearest neighbouring model grid points ${\mathrm A}$, ${\mathrm B}$, ${\mathrm C}$ and ${\mathrm D}$ with 577 605 longitude and latitude ($\lambda_{\mathrm A}$, $\phi_{\mathrm A}$),($\lambda_{\mathrm B}$, $\phi_{\mathrm B}$) etc. 578 All horizontal interpolation methods implemented in NEMOestimate the value of a model variable $x$ at point $P$ as606 All horizontal interpolation methods implemented in \NEMO\ estimate the value of a model variable $x$ at point $P$ as 579 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_{}}_{\mathrm P} & \hspace{-2mm} = \hspace{-2mm} &582 583 584 585 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*} 616 587 617 where ${w_{}}_{\mathrm A}$, ${w_{}}_{\mathrm B}$ etc. are the respective weights for the model field at 588 618 points ${\mathrm A}$, ${\mathrm B}$ etc., and $w = {w_{}}_{\mathrm A} + {w_{}}_{\mathrm B} + {w_{}}_{\mathrm C} + {w_{}}_{\mathrm D}$. … … 591 621 592 622 \begin{enumerate} 593 594 \item[1.] {\bfseries 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 626 For example, the weight given to the field ${x_{}}_{\mathrm A}$ is specified as the product of the distances 598 627 from ${\mathrm P}$ to the other points: 599 \begin{align*} 628 629 \begin{alignat*}{2} 600 630 {w_{}}_{\mathrm A} = s({\mathrm P}, {\mathrm B}) \, s({\mathrm P}, {\mathrm C}) \, s({\mathrm P}, {\mathrm D}) 601 \end{align *}602 where 603 \begin{align*}604 s\left ({\mathrm P}, {\mathrm M} \right ) 605 & \hspace{-2mm} = \hspace{-2mm} &606 \cos^{-1} \! \left\{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\{ 607 637 \sin {\phi_{}}_{\mathrm P} \sin {\phi_{}}_{\mathrm M} 608 + \cos {\phi_{}}_{\mathrm P} \cos {\phi_{}}_{\mathrm M} 609 \cos ({\lambda_{}}_{\mathrm M} - {\lambda_{}}_{\mathrm P}) 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( {\mathrm P}, {\mathrm 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_{}}_{\mathrm M} {a_{}}_{\mathrm P} + {b_{}}_{\mathrm M} {b_{}}_{\mathrm P} + {c_{}}_{\mathrm M} {c_{}}_{\mathrm P} 622 \end{align*} 623 and 624 \begin{align*} 625 {a_{}}_{\mathrm M} & \hspace{-2mm} = \hspace{-2mm} & \sin {\phi_{}}_{\mathrm M}, \\ 626 {a_{}}_{\mathrm P} & \hspace{-2mm} = \hspace{-2mm} & \sin {\phi_{}}_{\mathrm P}, \\ 627 {b_{}}_{\mathrm M} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\mathrm M} \cos {\phi_{}}_{\mathrm M}, \\ 628 {b_{}}_{\mathrm P} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\mathrm P} \cos {\phi_{}}_{\mathrm P}, \\ 629 {c_{}}_{\mathrm M} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\mathrm M} \sin {\phi_{}}_{\mathrm M}, \\ 630 {c_{}}_{\mathrm P} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\mathrm P} \sin {\phi_{}}_{\mathrm P}. 631 \end{align*} 632 633 \item[2.] {\bfseries 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 *}670 \begin{alignat*}{2} 636 671 s\left( {\mathrm P}, {\mathrm M} \right) 637 & \hspace{-2mm} = \hspace{-2mm} & 638 \sqrt{ \left( {\phi_{}}_{\mathrm M} - {\phi_{}}_{\mathrm P} \right)^{2} 672 & = & \sqrt{ \left( {\phi_{}}_{\mathrm M} - {\phi_{}}_{\mathrm P} \right)^{2} 639 673 + \left( {\lambda_{}}_{\mathrm M} - {\lambda_{}}_{\mathrm P} \right)^{2} 640 674 \cos^{2} {\phi_{}}_{\mathrm M} } 641 \end{align *}675 \end{alignat*} 642 676 where $M$ corresponds to $A$, $B$, $C$ or $D$. 643 677 644 \item [3.]{\bfseries Bilinear 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.]{\bfseries Bilinear 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 684 This method is based on the \href{https://github.com/SCRIP-Project/SCRIP}{SCRIP interpolation package}. 651 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=\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=\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 738 Let ${\mathrm P}({\lambda_{}}_{\mathrm P} ,{\phi_{}}_{\mathrm P} )$ denote the observation point, 713 739 and let ${\mathrm A}({\lambda_{}}_{\mathrm A} ,{\phi_{}}_{\mathrm A} )$, ${\mathrm B}({\lambda_{}}_{\mathrm B} ,{\phi_{}}_{\mathrm B} )$, 714 740 ${\mathrm C}({\lambda_{}}_{\mathrm C} ,{\phi_{}}_{\mathrm C} )$ and ${\mathrm D}({\lambda_{}}_{\mathrm D} ,{\phi_{}}_{\mathrm 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 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} … … 738 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 768 point in the opposite direction to the unit normal $\widehat{\mathbf k}$ 743 (\ie that the coefficients of $\widehat{\mathbf k}$ are negative),769 (\ie\ that the coefficients of $\widehat{\mathbf k}$ are negative), 744 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.. … … 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=\textwidth]{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=\textwidth]{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=\textwidth]{Fig_OBS_dataplot_main} 1373 \includegraphics[width=\textwidth]{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=\textwidth]{Fig_OBS_dataplot_prof} 1389 \includegraphics[width=\textwidth]{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/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_SBC.tex
r11179 r12149 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 (\textit{fldread.F90})] 229 {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})} 230 213 \label{subsec:SBC_fldread} 231 214 232 215 The structure associated with an input variable contains the following information: 233 216 \begin{forlines} 234 ! 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 ! 235 218 ! ! (if <0 months) ! name ! (logical) ! (T/F) ! 'monthly' ! filename ! pairing ! filename ! 236 219 \end{forlines} 237 where 238 \begin{description} 239 \item[File name]: 240 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. 241 223 This stem will be completed automatically by the model, with the addition of a '.nc' at its end and 242 224 by date information and possibly a prefix (when using AGRIF). 243 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 244 226 whether it is a climatological file or not, and to the open/close frequency (see below for definition). 245 246 %--------------------------------------------------TABLE--------------------------------------------------247 227 \begin{table}[htbp] 248 \begin{center} 249 \begin{tabular}{|l|c|c|c|} 250 \hline 251 & daily or weekLLL & monthly & yearly \\ \hline 252 \np{clim}\forcode{ = .false.} & fn\_yYYYYmMMdDD.nc & fn\_yYYYYmMM.nc & fn\_yYYYY.nc \\ \hline 253 \np{clim}\forcode{ = .true.} & not possible & fn\_m??.nc & fn \\ \hline 254 \end{tabular} 255 \end{center} 256 \caption{ 257 \protect\label{tab:fldread} 258 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. 259 241 The stem name is assumed to be 'fn'. 260 242 For weekly files, the 'LLL' corresponds to the first three letters of the first day of the week 261 (\ie 'sun','sat','fri','thu','wed','tue','mon'). 262 The 'YYYY', 'MM' and 'DD' should be replaced by the actual year/month/day, always coded with 4 or 2 digits. 263 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', 264 248 where 'PPPP' is the process number coded with 4 digits; 265 (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. 266 250 } 251 \label{tab:SBC_fldread} 267 252 \end{table} 268 %-------------------------------------------------------------------------------------------------------------- 269 270 271 \item[Record frequency]: 272 the frequency of the records contained in the input file. 253 \item [Record frequency]: the frequency of the records contained in the input file. 273 254 Its unit is in hours if it is positive (for example 24 for daily forcing) or in months if negative 274 255 (for example -1 for monthly forcing or -12 for annual forcing). 275 Note that this frequency must really be an integer and not a real. 276 On some computers, seting it to '24.' can be interpreted as 240! 277 278 \item[Variable name]: 279 the name of the variable to be read in the input NetCDF file. 280 281 \item[Time interpolation]: 282 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. 283 260 If set to 'false', the forcing will have a steplike shape remaining constant during each forcing period. 284 261 For example, when using a daily forcing without time interpolation, the forcing remaining constant from 285 262 00h00'00'' to 23h59'59". 286 263 If set to 'true', the forcing will have a broken line shape. 287 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. 288 265 For example, when using a daily forcing with time interpolation, 289 linear interpolation will be performed between mid-day of two consecutive days. 290 291 \item[Climatological forcing]: 292 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, 293 268 or an interannual forcing which will requires additional files if 294 the period covered by the simulation exceed the one of the file. 295 See the above the file naming strategy which impacts the expected name of the file to be opened. 296 297 \item[Open/close frequency]: 298 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. 299 272 Four cases are coded: 300 273 'daily', 'weekLLL' (with 'LLL' the first 3 letters of the first day of the week), 'monthly' and 'yearly' which … … 302 275 Files are assumed to contain data from the beginning of the open/close period. 303 276 For example, the first record of a yearly file containing daily data is Jan 1st even if 304 the experiment is not starting at the beginning of the year. 305 306 \item[Others]: 307 '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 308 279 on-the-fly interpolation which is described in \autoref{subsec:SBC_iof}. 309 310 280 \end{description} 311 281 … … 315 285 the date of the records read in the input files. 316 286 Following \citet{leclair.madec_OM09}, the date of a time step is set at the middle of the time step. 317 For example, for an experiment starting at 0h00'00" with a one 287 For example, for an experiment starting at 0h00'00" with a one-hour time-step, 318 288 a time interpolation will be performed at the following time: 0h30'00", 1h30'00", 2h30'00", etc. 319 289 However, for forcing data related to the surface module, 320 values are not needed at every time-step but at every \np{nn \_fsbc} time-step.321 For example with \np {nn\_fsbc}\forcode{ = 3}, the surface module will be called at time-steps 1, 4, 7, etc.322 The date used for the time interpolation is thus redefined to be at the middle of \np{nn\_fsbc} time-step period.323 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. \\ 324 294 (2) For code readablility and maintenance issues, we don't take into account the NetCDF input file calendar. 325 295 The calendar associated with the forcing field is build according to the information provided by 326 296 user in the record frequency, the open/close frequency and the type of temporal interpolation. 327 297 For example, the first record of a yearly file containing daily data that will be interpolated in time is assumed to 328 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". \\ 329 299 (3) If a time interpolation is requested, the code will pick up the needed data in the previous (next) file when 330 300 interpolating data with the first (last) record of the open/close period. 331 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'', 332 302 the values given by the code between 00h00'00" and 11h59'59" on Jan 1st will be interpolated values between 333 303 Dec 31st 12h00'00" and Jan 1st 12h00'00". 334 304 If the forcing is climatological, Dec and Jan will be keep-up from the same year. 335 305 However, if the forcing is not climatological, at the end of 336 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. 337 307 Note that, if the experiment is starting (ending) at the beginning (end) of 338 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. 339 309 In this case, the time interpolation will be performed between two identical values. 340 310 For example, when starting an experiment on Jan 1st of year Y with yearly files and daily data to be interpolated, 341 311 we do accept that the file related to year Y-1 is not existing. 342 312 The value of Jan 1st will be used as the missing one for Dec 31st of year Y-1. 343 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. 344 314 Therefore, this file can contain only one record corresponding to Dec 31st, 345 315 a useful feature for user considering that it is too heavy to manipulate the complete file for year Y-1. 346 316 347 348 % ------------------------------------------------------------------------------------------------------------- 349 % Interpolation on the Fly 350 % ------------------------------------------------------------------------------------------------------------- 317 %% ================================================================================================= 351 318 \subsection{Interpolation on-the-fly} 352 319 \label{subsec:SBC_iof} … … 354 321 Interpolation on the Fly allows the user to supply input files required for the surface forcing on 355 322 grids other than the model grid. 356 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 357 324 interpolate from the data grid to the model grid. 358 325 The original development of this code used the SCRIP package 359 326 (freely available \href{http://climate.lanl.gov/Software/SCRIP}{here} under a copyright agreement). 360 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 361 328 the input weights file must have the same names and meanings as assumed by the model. 362 Two methods are currently available: bilinear and bicubic interpolation .329 Two methods are currently available: bilinear and bicubic interpolations. 363 330 Prior to the interpolation, providing a land/sea mask file, the user can decide to remove land points from 364 331 the input file and substitute the corresponding values with the average of the 8 neighbouring points in … … 366 333 Only "sea points" are considered for the averaging. 367 334 The land/sea mask file must be provided in the structure associated with the input variable. 368 The netcdf land/sea mask variable name must be 'LSM' it must have the same horizontal and vertical dimensions of 369 the associated variable and should be equal to 1 over land and 0 elsewhere. 370 The procedure can be recursively applied setting nn\_lsm > 1 in namsbc namelist. 371 Note that nn\_lsm=0 forces the code to not apply the procedure even if a file for land/sea mask is supplied. 372 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 %% ================================================================================================= 373 341 \subsubsection{Bilinear interpolation} 374 342 \label{subsec:SBC_iof_bilinear} … … 376 344 The input weights file in this case has two sets of variables: 377 345 src01, src02, src03, src04 and wgt01, wgt02, wgt03, wgt04. 378 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. 379 347 Each src value is an integer corresponding to the index of a point in the input grid when 380 348 written as a one dimensional array. … … 392 360 and wgt(1) corresponds to variable "wgt01" for example. 393 361 362 %% ================================================================================================= 394 363 \subsubsection{Bicubic interpolation} 395 364 \label{subsec:SBC_iof_bicubic} 396 365 397 Again there are two sets of variables: "src" and "wgt".398 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. 399 368 The symbolic algorithm used to calculate values on the model grid is now: 400 369 … … 402 371 \begin{split} 403 372 f_{m}(i,j) = f_{m}(i,j) +& \sum_{k=1}^{4} {wgt(k)f(idx(src(k)))} 404 + \sum_{k=5}^{8} {wgt(k)\left.\frac{\partial f}{\partial i}\right| _{idx(src(k))} } \\405 +& \sum_{k=9 }^{12} {wgt(k)\left.\frac{\partial f}{\partial j}\right| _{idx(src(k))} }406 + 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))} } 407 376 \end{split} 408 377 \] 409 378 The gradients here are taken with respect to the horizontal indices and not distances since 410 the spatial dependency has been absorbed into the weights. 411 379 the spatial dependency has been included into the weights. 380 381 %% ================================================================================================= 412 382 \subsubsection{Implementation} 413 383 \label{subsec:SBC_iof_imp} … … 421 391 inspecting a global attribute stored in the weights input file. 422 392 This attribute must be called "ew\_wrap" and be of integer type. 423 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. 424 394 If zero or greater, then the value represents the number of columns that overlap. 425 395 $E.g.$ if the input grid has columns at longitudes 0, 1, 2, .... , 359, then ew\_wrap should be set to 0; 426 396 if longitudes are 0.5, 2.5, .... , 358.5, 360.5, 362.5, ew\_wrap should be 2. 427 397 If the model does not find attribute ew\_wrap, then a value of -999 is assumed. 428 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 429 399 therefore the grid is assumed to be cyclic with no overlapping columns. 430 (In fact this only matters when bicubic interpolation is required.)400 (In fact, this only matters when bicubic interpolation is required.) 431 401 Note that no testing is done to check the validity in the model, 432 402 since there is no way of knowing the name used for the longitude variable, … … 445 415 or is a copy of one from the first few columns on the opposite side of the grid (cyclical case). 446 416 417 %% ================================================================================================= 447 418 \subsubsection{Limitations} 448 419 \label{subsec:SBC_iof_lim} 449 420 450 \begin{enumerate} 451 \item 452 The case where input data grids are not logically rectangular has not been tested. 453 \item 454 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 455 424 a bicubic interpolation method is used. 456 \item 457 The cyclic condition is only applied on left and right columns, and not to top and bottom rows. 458 \item 459 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 460 427 the two columns involved are consistent with the weights used. 461 \item 462 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, 463 429 but this has not been implemented.) 464 430 \end{enumerate} 465 431 432 %% ================================================================================================= 466 433 \subsubsection{Utilities} 467 434 \label{subsec:SBC_iof_util} … … 471 438 (see the directory NEMOGCM/TOOLS/WEIGHTS). 472 439 473 % ------------------------------------------------------------------------------------------------------------- 474 % Standalone Surface Boundary Condition Scheme 475 % ------------------------------------------------------------------------------------------------------------- 476 \subsection{Standalone surface boundary condition scheme} 477 \label{subsec:SAS_iof} 478 479 %---------------------------------------namsbc_ana-------------------------------------------------- 480 481 \nlst{namsbc_sas} 482 %-------------------------------------------------------------------------------------------------------------- 483 484 In some circumstances it may be useful to avoid calculating the 3D temperature, 485 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. 486 452 For example: 487 453 488 454 \begin{itemize} 489 \item 490 Multiple runs of the model are required in code development to 455 \item Multiple runs of the model are required in code development to 491 456 see the effect of different algorithms in the bulk formulae. 492 \item 493 The effect of different parameter sets in the ice model is to be examined. 494 \item 495 Development of sea-ice algorithms or parameterizations. 496 \item 497 Spinup of the iceberg floats 498 \item 499 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}) 500 461 \end{itemize} 501 462 502 The Stand Alone Surface scheme provides this utility.503 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. 504 465 A new copy of the model has to be compiled with a configuration based on ORCA2\_SAS\_LIM. 505 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). 506 467 In this configuration, a few routines in the standard model are overriden by new versions. 507 468 Routines replaced are: 508 469 509 470 \begin{itemize} 510 \item 511 \mdl{nemogcm}: 512 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}). 513 472 Since the ocean state is not calculated all associated initialisations have been removed. 514 \item 515 \mdl{step}: 516 The main time stepping routine now only needs to call the sbc routine (and a few utility functions). 517 \item 518 \mdl{sbcmod}: 519 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. 520 475 New surface modules that can function when only the surface level of the ocean state is defined can also be added 521 (\eg icebergs). 522 \item 523 \mdl{daymod}: 524 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), 525 478 so calls to restart functions have been removed. 526 479 This also means that the calendar cannot be controlled by time in a restart file, 527 so the user must make sure that nn{\_}date0 in the model namelist is correct for his or her purposes. 528 \item 529 \mdl{stpctl}: 530 Since there is no free surface solver, references to it have been removed from \rou{stp\_ctl} module. 531 \item 532 \mdl{diawri}: 533 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. 534 483 The surface temperature, salinity and velocity components (which have been read in) are written along with 535 484 relevant forcing and ice data. … … 539 488 540 489 \begin{itemize} 541 \item 542 \mdl{sbcsas}: 543 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 544 491 velocity arrays at the surface. 545 These filenames are supplied in namelist namsbc {\_}sas.546 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, 547 494 the full 3D fields from the mean files have to be read in and interpolated in time, 548 495 before using just the top level. … … 550 497 \end{itemize} 551 498 552 553 % Missing the description of the 2 following variables: 554 % ln_3d_uve = .true. ! specify whether we are supplying a 3D u,v and e3 field 555 % ln_read_frq = .false. ! specify whether we must read frq or not 556 557 558 559 % ================================================================ 560 % Analytical formulation (sbcana module) 561 % ================================================================ 562 \section[Analytical formulation (\textit{sbcana.F90})] 563 {Analytical formulation (\protect\mdl{sbcana})} 564 \label{sec:SBC_ana} 565 566 %---------------------------------------namsbc_ana-------------------------------------------------- 567 % 568 %\nlst{namsbc_ana} 569 %-------------------------------------------------------------------------------------------------------------- 570 571 The analytical formulation of the surface boundary condition is the default scheme. 572 In this case, all the six fluxes needed by the ocean are assumed to be uniform in space. 573 They take constant values given in the namelist \ngn{namsbc{\_}ana} by 574 the variables \np{rn\_utau0}, \np{rn\_vtau0}, \np{rn\_qns0}, \np{rn\_qsr0}, and \np{rn\_emp0} 575 ($\textit{emp}=\textit{emp}_S$). 576 The runoff is set to zero. 577 In addition, the wind is allowed to reach its nominal value within a given number of time steps (\np{nn\_tau000}). 578 579 If a user wants to apply a different analytical forcing, 580 the \mdl{sbcana} module can be modified to use another scheme. 581 As an example, the \mdl{sbc\_ana\_gyre} routine provides the analytical forcing for the GYRE configuration 582 (see GYRE configuration manual, in preparation). 583 584 585 % ================================================================ 586 % Flux formulation 587 % ================================================================ 588 \section[Flux formulation (\textit{sbcflx.F90})] 589 {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})} 590 504 \label{sec:SBC_flx} 591 %------------------------------------------namsbc_flx---------------------------------------------------- 592 593 \nlst{namsbc_flx} 594 %------------------------------------------------------------------------------------------------------------- 595 596 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}), 597 513 the surface boundary condition fields are directly read from input files. 598 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, 599 515 the name of the variable read in the file, the time frequency at which it is given (in hours), 600 516 and a logical setting whether a time interpolation to the model time step is required for this field. … … 604 520 See \autoref{subsec:SBC_ssr} for its specification. 605 521 606 607 % ================================================================ 608 % Bulk formulation 609 % ================================================================ 610 \section[Bulk formulation {(\textit{sbcblk\{\_core,\_clio\}.F90})}] 611 {Bulk formulation {(\protect\mdl{sbcblk\_core}, \protect\mdl{sbcblk\_clio})}} 522 %% ================================================================================================= 523 \section[Bulk formulation (\textit{sbcblk.F90})]{Bulk formulation (\protect\mdl{sbcblk})} 612 524 \label{sec:SBC_blk} 613 525 614 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. 615 534 616 535 The atmospheric fields used depend on the bulk formulae used. 617 Two bulk formulations are available: 618 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. 619 541 The choice is made by setting to true one of the following namelist variable: 620 \np{ln\_core} or \np{ln\_clio}. 621 622 Note: 623 in forced mode, when a sea-ice model is used, a bulk formulation (CLIO or CORE) have to be used. 624 Therefore the two bulk (CLIO and CORE) formulea include the computation of the fluxes over 625 both an ocean and an ice surface. 626 627 % ------------------------------------------------------------------------------------------------------------- 628 % CORE Bulk formulea 629 % ------------------------------------------------------------------------------------------------------------- 630 \subsection[CORE formulea (\textit{sbcblk\_core.F90}, \forcode{ln_core = .true.})] 631 {CORE formulea (\protect\mdl{sbcblk\_core}, \protect\np{ln\_core}\forcode{ = .true.})} 632 \label{subsec:SBC_blk_core} 633 %------------------------------------------namsbc_core---------------------------------------------------- 634 % 635 %\nlst{namsbc_core} 636 %------------------------------------------------------------------------------------------------------------- 637 638 The CORE bulk formulae have been developed by \citet{large.yeager_rpt04}. 639 They have been designed to handle the CORE forcing, a mixture of NCEP reanalysis and satellite data. 640 They use an inertial dissipative method to compute the turbulent transfer coefficients 641 (momentum, sensible heat and evaporation) from the 10 metre wind speed, air temperature and specific humidity. 642 This \citet{large.yeager_rpt04} dataset is available through 643 the \href{http://nomads.gfdl.noaa.gov/nomads/forms/mom4/CORE.html}{GFDL web site}. 644 645 Note that substituting ERA40 to NCEP reanalysis fields does not require changes in the bulk formulea themself. 646 This is the so-called DRAKKAR Forcing Set (DFS) \citep{brodeau.barnier.ea_OM10}. 647 648 Options are defined through the \ngn{namsbc\_core} namelist variables. 649 The required 8 input fields are: 650 651 %--------------------------------------------------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 652 549 \begin{table}[htbp] 653 \label{tab:CORE} 654 \begin{center} 655 \begin{tabular}{|l|c|c|c|} 656 \hline 657 Variable desciption & Model variable & Units & point \\ \hline 658 i-component of the 10m air velocity & utau & $m.s^{-1}$ & T \\ \hline 659 j-component of the 10m air velocity & vtau & $m.s^{-1}$ & T \\ \hline 660 10m air temperature & tair & \r{}$K$ & T \\ \hline 661 Specific humidity & humi & \% & T \\ \hline 662 Incoming long wave radiation & qlw & $W.m^{-2}$ & T \\ \hline 663 Incoming short wave radiation & qsr & $W.m^{-2}$ & T \\ \hline 664 Total precipitation (liquid + solid) & precip & $Kg.m^{-2}.s^{-1}$ & T \\ \hline 665 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 666 573 \end{tabular} 667 \ end{center}574 \label{tab:SBC_BULK} 668 575 \end{table} 669 %--------------------------------------------------------------------------------------------------------------670 576 671 577 Note that the air velocity is provided at a tracer ocean point, not at a velocity ocean point ($u$- and $v$-points). … … 673 579 the ocean grid size is the same or larger than the one of the input atmospheric fields. 674 580 675 The \np{sn \_wndi}, \np{sn\_wndj}, \np{sn\_qsr}, \np{sn\_qlw}, \np{sn\_tair}, \np{sn\_humi}, \np{sn\_prec},676 \np{sn \_snow}, \np{sn\_tdif} parameters describe the fields and the way they have to be used677 (spatial and temporal interpolations). 678 679 \np{cn \_dir} is the directory of location of bulk files680 \np{ln \_taudif} is the flag to specify if we use Hight Frequency (HF) tau information (.true.) or not (.false.)681 \np{rn \_zqt}: is the height of humidity and temperature measurements (m)682 \np{rn \_zu}: is the height of wind measurements (m)683 684 Three multiplicative factors are available s:685 \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 686 592 increasing/reducing the precipitations (total and snow) and or evaporation, respectively. 687 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 688 594 the calculation of surface wind stress. 689 Its range should be between zero and one, and it is recommended to set it to 0. 690 691 % ------------------------------------------------------------------------------------------------------------- 692 % CLIO Bulk formulea 693 % ------------------------------------------------------------------------------------------------------------- 694 \subsection[CLIO formulea (\textit{sbcblk\_clio.F90}, \forcode{ln_clio = .true.})] 695 {CLIO formulea (\protect\mdl{sbcblk\_clio}, \protect\np{ln\_clio}\forcode{ = .true.})} 696 \label{subsec:SBC_blk_clio} 697 %------------------------------------------namsbc_clio---------------------------------------------------- 698 % 699 %\nlst{namsbc_clio} 700 %------------------------------------------------------------------------------------------------------------- 701 702 The CLIO bulk formulae were developed several years ago for the Louvain-la-neuve coupled ice-ocean model 703 (CLIO, \cite{goosse.deleersnijder.ea_JGR99}). 704 They are simpler bulk formulae. 705 They assume the stress to be known and compute the radiative fluxes from a climatological cloud cover. 706 707 Options are defined through the \ngn{namsbc\_clio} namelist variables. 708 The required 7 input fields are: 709 710 %--------------------------------------------------TABLE-------------------------------------------------- 711 \begin{table}[htbp] 712 \label{tab:CLIO} 713 \begin{center} 714 \begin{tabular}{|l|l|l|l|} 715 \hline 716 Variable desciption & Model variable & Units & point \\ \hline 717 i-component of the ocean stress & utau & $N.m^{-2}$ & U \\ \hline 718 j-component of the ocean stress & vtau & $N.m^{-2}$ & V \\ \hline 719 Wind speed module & vatm & $m.s^{-1}$ & T \\ \hline 720 10m air temperature & tair & \r{}$K$ & T \\ \hline 721 Specific humidity & humi & \% & T \\ \hline 722 Cloud cover & & \% & T \\ \hline 723 Total precipitation (liquid + solid) & precip & $Kg.m^{-2}.s^{-1}$ & T \\ \hline 724 Solid precipitation & snow & $Kg.m^{-2}.s^{-1}$ & T \\ \hline 725 \end{tabular} 726 \end{center} 727 \end{table} 728 %-------------------------------------------------------------------------------------------------------------- 595 Its range must be between zero and one, and it is recommended to set it to 0 at low-resolution (ORCA2 configuration). 729 596 730 597 As for the flux formulation, information about the input data required by the model is provided in 731 the namsbc\_blk\_core or namsbc\_blk\_clio namelist (see \autoref{subsec:SBC_fldread}). 732 733 % ================================================================ 734 % Coupled formulation 735 % ================================================================ 736 \section[Coupled formulation (\textit{sbccpl.F90})] 737 {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})} 738 650 \label{sec:SBC_cpl} 739 %------------------------------------------namsbc_cpl---------------------------------------------------- 740 741 \nlst{namsbc_cpl} 742 %------------------------------------------------------------------------------------------------------------- 651 652 \begin{listing} 653 \nlst{namsbc_cpl} 654 \caption{\forcode{&namsbc_cpl}} 655 \label{lst:namsbc_cpl} 656 \end{listing} 743 657 744 658 In the coupled formulation of the surface boundary condition, 745 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, 746 660 while sea and ice surface temperature, ocean and ice albedo, and ocean currents are sent to 747 661 the atmospheric component. 748 662 749 663 A generalised coupled interface has been developed. 750 It is currently interfaced with OASIS-3-MCT (\key{oasis3}). 751 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 752 667 (ARPEGE, ECHAM, ECMWF, HadAM, HadGAM, LMDz), as well as to \href{http://wrf-model.org/}{WRF} 753 668 (Weather Research and Forecasting Model). 754 669 755 Note that in addition to the setting of \np{ln\_cpl} to true, the \key{coupled} have to be defined. 756 The CPP key is mainly used in sea-ice to ensure that the atmospheric fluxes are actually received by 757 the ice-ocean system (no calculation of ice sublimation in coupled mode). 758 When PISCES biogeochemical model (\key{top} and \key{pisces}) is also used in the coupled system, 759 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. 760 672 In this case, CO$_2$ fluxes will be exchanged between the atmosphere and the ice-ocean system 761 (and need to be activated in \n gn{namsbc{\_}cpl} ).673 (and need to be activated in \nam{sbc_cpl}{sbc\_cpl} ). 762 674 763 675 The namelist above allows control of various aspects of the coupling fields (particularly for vectors) and 764 676 now allows for any coupling fields to have multiple sea ice categories (as required by LIM3 and CICE). 765 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 766 678 the number used in the sea ice model. 767 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 768 680 the sea ice model is running with multiple categories - 769 in this case the user should examine the code to be sure the assumptions made are satisfactory. 770 In cases where this is definitely not possible the model should abort with an error message. 771 The new code has been tested using ECHAM with LIM2, and HadGAM3 with CICE but 772 although it will compile with \key{lim3} additional minor code changes may be required to run using LIM3. 773 774 775 % ================================================================ 776 % Atmospheric pressure 777 % ================================================================ 778 \section[Atmospheric pressure (\textit{sbcapr.F90})] 779 {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})} 780 686 \label{sec:SBC_apr} 781 %------------------------------------------namsbc_apr---------------------------------------------------- 782 783 \nlst{namsbc_apr} 784 %------------------------------------------------------------------------------------------------------------- 687 688 \begin{listing} 689 \nlst{namsbc_apr} 690 \caption{\forcode{&namsbc_apr}} 691 \label{lst:namsbc_apr} 692 \end{listing} 785 693 786 694 The optional atmospheric pressure can be used to force ocean and ice dynamics 787 (\np {ln\_apr\_dyn}\forcode{ = .true.}, \textit{\ngn{namsbc}} namelist).788 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) 789 697 can be interpolated in time to the model time step, and even in space when the interpolation on-the-fly is used. 790 698 When used to force the dynamics, the atmospheric pressure is further transformed into … … 795 703 \] 796 704 where $P_{atm}$ is the atmospheric pressure and $P_o$ a reference atmospheric pressure. 797 A value of $101,000~N/m^2$ is used unless \np{ln \_ref\_apr} is set to true.798 In this case $P_o$ is set to the value of $P_{atm}$ averaged over the ocean domain,799 \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. 800 708 801 709 The gradient of $\eta_{ib}$ is added to the RHS of the ocean momentum equation (see \mdl{dynspg} for the ocean). 802 710 For sea-ice, the sea surface height, $\eta_m$, which is provided to the sea ice model is set to $\eta - \eta_{ib}$ 803 711 (see \mdl{sbcssr} module). 804 $\eta_{ib}$ can be setin the output.712 $\eta_{ib}$ can be written in the output. 805 713 This can simplify altimetry data and model comparison as 806 714 inverse barometer sea surface height is usually removed from these date prior to their distribution. 807 715 808 716 When using time-splitting and BDY package for open boundaries conditions, 809 the equivalent inverse barometer sea surface height $\eta_{ib}$ can be added to BDY ssh data: 810 \np{ln\_apr\_obc} might be set to true. 811 812 % ================================================================ 813 % Surface Tides Forcing 814 % ================================================================ 815 \section[Surface tides (\textit{sbctide.F90})] 816 {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})} 817 722 \label{sec:SBC_tide} 818 723 819 %------------------------------------------nam_tide--------------------------------------- 820 821 \nlst{nam_tide} 822 %----------------------------------------------------------------------------------------- 724 \begin{listing} 725 \nlst{nam_tide} 726 \caption{\forcode{&nam_tide}} 727 \label{lst:nam_tide} 728 \end{listing} 823 729 824 730 The tidal forcing, generated by the gravity forces of the Earth-Moon and Earth-Sun sytems, 825 is activated if \np{ln \_tide} and \np{ln\_tide\_pot} are both set to \forcode{.true.} in \ngn{nam\_tide}.826 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: 827 733 \[ 828 % \label{eq: PE_dyn_tides}734 % \label{eq:SBC_PE_dyn_tides} 829 735 \frac{\partial {\mathrm {\mathbf U}}_h }{\partial t}= ... 830 736 +g\nabla (\Pi_{eq} + \Pi_{sal}) … … 832 738 where $\Pi_{eq}$ stands for the equilibrium tidal forcing and 833 739 $\Pi_{sal}$ is a self-attraction and loading term (SAL). 834 740 835 741 The equilibrium tidal forcing is expressed as a sum over a subset of 836 742 constituents chosen from the set of available tidal constituents 837 defined in file \ rou{SBC/tide.h90} (this comprises the tidal743 defined in file \hf{SBC/tide} (this comprises the tidal 838 744 constituents \textit{M2, N2, 2N2, S2, K2, K1, O1, Q1, P1, M4, Mf, Mm, 839 745 Msqm, Mtm, S1, MU2, NU2, L2}, and \textit{T2}). Individual 840 746 constituents are selected by including their names in the array 841 \np{clname} in \ngn{nam\_tide} (e.g., \np{clname(1) = 'M2',842 clname(2)='S2'} to select solely the tidal consituents \textit{M2}843 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 844 750 \forcode{.true.}, the equilibrium tidal forcing can be ramped up 845 linearly from zero during the initial \np{rdttideramp} days of the751 linearly from zero during the initial \np{rdttideramp}{rdttideramp} days of the 846 752 model run. 847 753 … … 850 756 discussion about the practical implementation of this term). 851 757 Nevertheless, the complex calculations involved would make this 852 computationally too expensive. 758 computationally too expensive. Here, two options are available: 853 759 $\Pi_{sal}$ generated by an external model can be read in 854 (\np {ln\_read\_load=.true.}), or a ``scalar approximation'' can be855 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 856 762 \[ 857 763 \Pi_{sal} = \beta \eta, 858 764 \] 859 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 860 766 spatially constant scalar, often chosen to minimize tidal prediction 861 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 862 768 \forcode{.false.} removes the SAL contribution. 863 769 864 % ================================================================ 865 % River runoffs 866 % ================================================================ 867 \section[River runoffs (\textit{sbcrnf.F90})] 868 {River runoffs (\protect\mdl{sbcrnf})} 770 %% ================================================================================================= 771 \section[River runoffs (\textit{sbcrnf.F90})]{River runoffs (\protect\mdl{sbcrnf})} 869 772 \label{sec:SBC_rnf} 870 %------------------------------------------namsbc_rnf---------------------------------------------------- 871 872 \nlst{namsbc_rnf} 873 %------------------------------------------------------------------------------------------------------------- 874 875 %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. 876 781 %Many models, however, have traditionally inserted river runoff to the top model cell. 877 %This was the case in \NEMO prior to the version 3.3. The switch toward a input of runoff878 %throughout a nonzero depth has been motivated by the numerical and physical problems 879 %that arise when the top grid cells are of the order of one meter. This situation is common in 880 %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 881 786 %\footnote{At least a top cells thickness of 1~meter and a 3 hours forcing frequency are 882 787 %required to properly represent the diurnal cycle \citep{bernie.woolnough.ea_JC05}. see also \autoref{fig:SBC_dcy}.}. 883 788 884 885 %To do this we need to treat evaporation/precipitation fluxes and river runoff differently in the 886 %\mdl{tra\_sbc} module. We decided to separate them throughout the code, so that the variable 887 %\textit{emp} represented solely evaporation minus precipitation fluxes, and a new 2d variable 888 %rnf was added which represents the volume flux of river runoff (in kg/m2s to remain consistent with 889 %emp). This meant many uses of emp and emps needed to be changed, a list of all modules which use 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 890 794 %emp or emps and the changes made are below: 891 892 795 893 796 %Rachel: 894 797 River runoff generally enters the ocean at a nonzero depth rather than through the surface. 895 798 Many models, however, have traditionally inserted river runoff to the top model cell. 896 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, 897 800 and was combined with an option to increase vertical mixing near the river mouth. 898 801 899 802 However, with this method numerical and physical problems arise when the top grid cells are of the order of one meter. 900 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 901 804 \footnote{ 902 805 At least a top cells thickness of 1~meter and a 3 hours forcing frequency are required to … … 909 812 along with the depth (in metres) which the river should be added to. 910 813 911 Namelist variables in \n gn{namsbc\_rnf}, \np{ln\_rnf\_depth}, \np{ln\_rnf\_sal} and912 \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. 913 816 If these are set as false the river is added to the surface box only, assumed to be fresh (0~psu), 914 817 and/or taken as surface temperature respectively. 915 818 916 The runoff value and attributes are read in in sbcrnf. 819 The runoff value and attributes are read in in sbcrnf. 917 820 For temperature -999 is taken as missing data and the river temperature is taken to 918 821 be the surface temperatue at the river point. 919 For the depth parameter a value of -1 means the river is added to the surface box only, 920 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. 921 824 After being read in the temperature and salinity variables are multiplied by the amount of runoff 922 825 (converted into m/s) to give the heat and salt content of the river runoff. 923 826 After the user specified depth is read ini, 924 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}. 925 828 The variable \textit{h\_dep} is then calculated to be the depth (in metres) of 926 829 the bottom of the lowest box the river water is being added to 927 (\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). 928 831 929 832 The mass/volume addition due to the river runoff is, at each relevant depth level, added to … … 931 834 This increases the diffusion term in the vicinity of the river, thereby simulating a momentum flux. 932 835 The sea surface height is calculated using the sum of the horizontal divergence terms, 933 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. 934 837 935 838 The \textit{hdivn} terms are used in the tracer advection modules to force vertical velocities. … … 944 847 As such the volume of water does not change, but the water is diluted. 945 848 946 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. 947 850 Instead in the surface box (as well as water moving up from the boxes below) a volume of runoff water is added with 948 851 no corresponding heat and salt addition and so as happens in the lower boxes there is a dilution effect. … … 953 856 This is done in the same way for both vvl and non-vvl. 954 857 The temperature and salinity are increased through the specified depth according to 955 the heat and salt content of the river. 858 the heat and salt content of the river. 956 859 957 860 In the non-linear free surface case (vvl), … … 962 865 963 866 It is also possible for runnoff to be specified as a negative value for modelling flow through straits, 964 \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. 965 868 When the flow is out of the domain there is no change in temperature and salinity, 966 869 regardless of the namelist options used, 967 as the ocean water leaving the domain removes heat and salt (at the same concentration) with it. 968 969 970 %\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 971 873 972 874 %All river runoff and emp fluxes are assumed to be fresh water (zero salinity) and at the same temperature as the sea surface.} … … 978 880 %ENDIF 979 881 980 %\gmcomment{ word doc of runoffs: 981 % 982 %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. 983 %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. 984 985 %The depth option makes it possible to have the river water affecting just the surface layer, throughout depth, or some specified point in between. 986 987 %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: 988 989 %} 990 % ================================================================ 991 % Ice shelf melting 992 % ================================================================ 993 \section[Ice shelf melting (\textit{sbcisf.F90})] 994 {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})} 995 910 \label{sec:SBC_isf} 996 %------------------------------------------namsbc_isf---------------------------------------------------- 997 998 \nlst{namsbc_isf} 999 %-------------------------------------------------------------------------------------------------------- 1000 The namelist variable in \ngn{namsbc}, \np{nn\_isf}, controls the ice shelf representation. 1001 Description and result of sensitivity test to \np{nn\_isf} are presented in \citet{mathiot.jenkins.ea_GMD17}. 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}. 1002 920 The different options are illustrated in \autoref{fig:SBC_isf}. 1003 921 1004 922 \begin{description} 1005 \item[\np{nn\_isf}\forcode{ = 1}]: 1006 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). 1007 924 The fwf and heat flux are depending of the local water properties. 925 1008 926 Two different bulk formulae are available: 1009 927 1010 \begin{description} 1011 \item[\np{nn\_isfblk}\forcode{ = 1}]: 1012 The melt rate is based on a balance between the upward ocean heat flux and 1013 the latent heat flux at the ice shelf base. A complete description is available in \citet{hunter_rpt06}. 1014 \item[\np{nn\_isfblk}\forcode{ = 2}]: 1015 The melt rate and the heat flux are based on a 3 equations formulation 1016 (a heat flux budget at the ice base, a salt flux budget at the ice base and a linearised freezing point temperature equation). 1017 A complete description is available in \citet{jenkins_JGR91}. 1018 \end{description} 1019 1020 Temperature and salinity used to compute the melt are the average temperature in the top boundary layer \citet{losch_JGR08}. 1021 Its thickness is defined by \np{rn\_hisf\_tbl}. 1022 The fluxes and friction velocity are computed using the mean temperature, salinity and velocity in the the first \np{rn\_hisf\_tbl} m. 1023 Then, the fluxes are spread over the same thickness (ie over one or several cells). 1024 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. 1025 This can lead to super-cool temperature in the top cell under melting condition. 1026 If \np{rn\_hisf\_tbl} smaller than top $e_{3}t$, the top boundary layer thickness is set to the top cell thickness.\\ 1027 1028 Each melt bulk formula depends on a exchange coeficient ($\Gamma^{T,S}$) between the ocean and the ice. 1029 There are 3 different ways to compute the exchange coeficient: 1030 \begin{description} 1031 \item[\np{nn\_gammablk}\forcode{ = 0}]: 1032 The salt and heat exchange coefficients are constant and defined by \np{rn\_gammas0} and \np{rn\_gammat0}. 1033 \[ 1034 % \label{eq:sbc_isf_gamma_iso} 1035 \gamma^{T} = \np{rn\_gammat0} 1036 \] 1037 \[ 1038 \gamma^{S} = \np{rn\_gammas0} 1039 \] 1040 This is the recommended formulation for ISOMIP. 1041 \item[\np{nn\_gammablk}\forcode{ = 1}]: 1042 The salt and heat exchange coefficients are velocity dependent and defined as 1043 \[ 1044 \gamma^{T} = \np{rn\_gammat0} \times u_{*} 1045 \] 1046 \[ 1047 \gamma^{S} = \np{rn\_gammas0} \times u_{*} 1048 \] 1049 where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn\_hisf\_tbl} meters). 1050 See \citet{jenkins.nicholls.ea_JPO10} for all the details on this formulation. It is the recommended formulation for realistic application. 1051 \item[\np{nn\_gammablk}\forcode{ = 2}]: 1052 The salt and heat exchange coefficients are velocity and stability dependent and defined as: 1053 \[ 1054 \gamma^{T,S} = \frac{u_{*}}{\Gamma_{Turb} + \Gamma^{T,S}_{Mole}} 1055 \] 1056 where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn\_hisf\_tbl} meters), 1057 $\Gamma_{Turb}$ the contribution of the ocean stability and 1058 $\Gamma^{T,S}_{Mole}$ the contribution of the molecular diffusion. 1059 See \citet{holland.jenkins_JPO99} for all the details on this formulation. 1060 This formulation has not been extensively tested in NEMO (not recommended). 1061 \end{description} 1062 \item[\np{nn\_isf}\forcode{ = 2}]: 1063 The ice shelf cavity is not represented. 1064 The fwf and heat flux are computed using the \citet{beckmann.goosse_OM03} parameterisation of isf melting. 1065 The fluxes are distributed along the ice shelf edge between the depth of the average grounding line (GL) 1066 (\np{sn\_depmax\_isf}) and the base of the ice shelf along the calving front 1067 (\np{sn\_depmin\_isf}) as in (\np{nn\_isf}\forcode{ = 3}). 1068 The effective melting length (\np{sn\_Leff\_isf}) is read from a file. 1069 \item[\np{nn\_isf}\forcode{ = 3}]: 1070 The ice shelf cavity is not represented. 1071 The fwf (\np{sn\_rnfisf}) is prescribed and distributed along the ice shelf edge between 1072 the depth of the average grounding line (GL) (\np{sn\_depmax\_isf}) and 1073 the base of the ice shelf along the calving front (\np{sn\_depmin\_isf}). 1074 The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$. 1075 \item[\np{nn\_isf}\forcode{ = 4}]: 1076 The ice shelf cavity is opened (\np{ln\_isfcav}\forcode{ = .true.} needed). 1077 However, the fwf is not computed but specified from file \np{sn\_fwfisf}). 1078 The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$. 1079 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}) 1080 986 \end{description} 1081 987 1082 $\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 1083 989 the water mass properties, ocean velocities and depth. 1084 990 This flux is thus highly dependent of the model resolution (horizontal and vertical), 1085 991 realism of the water masses onto the shelf ...\\ 1086 992 1087 $\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. 1088 994 You have total control of the fwf forcing. 1089 995 This can be useful if the water masses on the shelf are not realistic or 1090 996 the resolution (horizontal/vertical) are too coarse to have realistic melting or 1091 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.\\ 1092 998 1093 999 The ice shelf melt is implemented as a volume flux as for the runoff. … … 1096 1002 See the runoff section \autoref{sec:SBC_rnf} for all the details about the divergence correction.\\ 1097 1003 1098 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>1099 1004 \begin{figure}[!t] 1100 \begin{center} 1101 \includegraphics[width=\textwidth]{Fig_SBC_isf} 1102 \caption{ 1103 \protect\label{fig:SBC_isf} 1104 Illustration the location where the fwf is injected and whether or not the fwf is interactif or not depending of \np{nn\_isf}. 1105 } 1106 \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} 1107 1011 \end{figure} 1108 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1109 1012 1013 %% ================================================================================================= 1110 1014 \section{Ice sheet coupling} 1111 1015 \label{sec:SBC_iscpl} 1112 %------------------------------------------namsbc_iscpl---------------------------------------------------- 1113 1114 \nlst{namsbc_iscpl} 1115 %-------------------------------------------------------------------------------------------------------- 1016 1017 \begin{listing} 1018 \nlst{namsbc_iscpl} 1019 \caption{\forcode{&namsbc_iscpl}} 1020 \label{lst:namsbc_iscpl} 1021 \end{listing} 1022 1116 1023 Ice sheet/ocean coupling is done through file exchange at the restart step. 1117 1024 At each restart step: 1118 \begin{description} 1119 \item[Step 1]: the ice sheet model send a new bathymetry and ice shelf draft netcdf file. 1120 \item[Step 2]: a new domcfg.nc file is built using the DOMAINcfg tools. 1121 \item[Step 3]: NEMO run for a specific period and output the average melt rate over the period. 1122 \item[Step 4]: the ice sheet model run using the melt rate outputed in step 4. 1123 \item[Step 5]: go back to 1. 1124 \end{description} 1125 1126 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 1127 1035 potentially some new wet/dry cells due to the ice sheet dynamics/thermodynamics. 1128 1036 The wetting and drying scheme applied on the restart is very simple and described below for the 6 different possible cases: 1037 1129 1038 \begin{description} 1130 \item[Thin a cell down]: 1131 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 1132 1040 ($bt_b=bt_n$). 1133 \item[Enlarge a cell]: 1134 See case "Thin a cell down" 1135 \item[Dry a cell]: 1136 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. 1137 1043 Furthermore, U/V into the water column are modified to satisfy ($bt_b=bt_n$). 1138 \item[Wet a cell]: 1139 mask is set to 1, T/S is extrapolated from neighbours, $ssh_n = ssh_b$ and U/V set to 0. 1140 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. 1141 1046 If no neighbours along i,j and k (both previous test failed), T/S/U/V/ssh and mask are set to 0. 1142 \item[Dry a column]: 1143 mask, T/S, U/V are set to 0 everywhere in the column and ssh set to 0. 1144 \item[Wet a column]: 1145 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. 1146 1049 If no neighbour, T/S/U/V and mask set to 0. 1147 1050 \end{description} … … 1150 1053 the restart time step is prescribed to be an euler time step instead of a leap frog and $fields_b = fields_n$.\\ 1151 1054 1152 The horizontal extrapolation to fill new cell with realistic value is called \np{nn \_drown} times.1153 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, 1154 1057 the code will be unable to fill all the new wet cells properly. 1155 1058 The default number is set up for the MISOMIP idealised experiments. 1156 1059 This coupling procedure is able to take into account grounding line and calving front migration. 1157 However, it is a non-conservative processe. 1060 However, it is a non-conservative processe. 1158 1061 This could lead to a trend in heat/salt content and volume.\\ 1159 1062 1160 1063 In order to remove the trend and keep the conservation level as close to 0 as possible, 1161 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}. 1162 1065 The heat/salt/vol. gain/loss is diagnosed, as well as the location. 1163 A correction increment is computed and apply each time step during the next \np{rn \_fiscpl} time steps.1164 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). 1165 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). 1166 1069 1167 % 1168 % ================================================================ 1169 % Handling of icebergs 1170 % ================================================================ 1070 %% ================================================================================================= 1171 1071 \section{Handling of icebergs (ICB)} 1172 \label{sec:ICB_icebergs} 1173 %------------------------------------------namberg---------------------------------------------------- 1174 1175 \nlst{namberg} 1176 %------------------------------------------------------------------------------------------------------------- 1177 1178 Icebergs are modelled as lagrangian particles in NEMO \citep{marsh.ivchenko.ea_GMD15}. 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}. 1179 1081 Their physical behaviour is controlled by equations as described in \citet{martin.adcroft_OM10} ). 1180 (Note that the authors kindly provided a copy of their code to act as a basis for implementation in NEMO).1082 (Note that the authors kindly provided a copy of their code to act as a basis for implementation in \NEMO). 1181 1083 Icebergs are initially spawned into one of ten classes which have specific mass and thickness as 1182 described in the \n gn{namberg} namelist: \np{rn\_initial\_mass} and \np{rn\_initial\_thickness}.1183 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}), 1184 1086 which is an integer representing how many icebergs of this class are being described as one lagrangian point 1185 1087 (this reduces the numerical problem of tracking every single iceberg). 1186 They are enabled by setting \np {ln\_icebergs}\forcode{ = .true.}.1088 They are enabled by setting \np[=.true.]{ln_icebergs}{ln\_icebergs}. 1187 1089 1188 1090 Two initialisation schemes are possible. 1189 1091 \begin{description} 1190 \item[\np{nn\_test\_icebergs}~$>$~0] 1191 In this scheme, the value of \np{nn\_test\_icebergs} represents the class of iceberg to generate 1192 (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 1193 1094 which an iceberg is generated at the beginning of the run. 1194 (Note that this happens each time the timestep equals \np{nn \_nit000}.)1195 \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 1196 1097 the geographical box: lonmin,lonmax,latmin,latmax 1197 \item[\np{nn\_test\_icebergs}\forcode{ = -1}] 1198 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. 1199 1099 This should be a file with a field on the configuration grid (typically ORCA) 1200 1100 representing ice accumulation rate at each model point. … … 1204 1104 At each time step, a test is performed to see if there is enough ice mass to 1205 1105 calve an iceberg of each class in order (1 to 10). 1206 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). 1207 1107 If there is enough ice, a new iceberg is spawned and the total available ice reduced accordingly. 1208 1108 \end{description} … … 1211 1111 The latter act to disintegrate the iceberg. 1212 1112 This is either all melted freshwater, 1213 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 1214 1114 which are assumed to propagate with their larger parent and thus delay fluxing into the ocean. 1215 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. 1216 1116 1217 1117 Extensive diagnostics can be produced. 1218 1118 Separate output files are maintained for human-readable iceberg information. 1219 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}). 1220 1120 The amount of information is controlled by two integer parameters: 1221 1121 \begin{description} 1222 \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 1223 1123 represents an increasing number of points in the code at which variables are written, 1224 1124 and an increasing level of obscurity. 1225 \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 1226 1126 \end{description} 1227 1127 1228 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. 1229 1129 A non-zero value represents how many timesteps between writes of information into the output file. 1230 1130 These output files are in NETCDF format. … … 1234 1134 since its trajectory data may be spread across multiple files. 1235 1135 1236 % ------------------------------------------------------------------------------------------------------------- 1237 % Interactions with waves (sbcwave.F90, ln_wave) 1238 % ------------------------------------------------------------------------------------------------------------- 1239 \section[Interactions with waves (\textit{sbcwave.F90}, \texttt{ln\_wave})] 1240 {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})} 1241 1138 \label{sec:SBC_wave} 1242 %------------------------------------------namsbc_wave-------------------------------------------------------- 1243 1244 \nlst{namsbc_wave} 1245 %------------------------------------------------------------------------------------------------------------- 1246 1247 Ocean waves represent the interface between the ocean and the atmosphere, so NEMO is extended to incorporate 1248 physical processes related to ocean surface waves, namely the surface stress modified by growth and 1249 dissipation of the oceanic wave field, the Stokes-Coriolis force and the Stokes drift impact on mass and 1250 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 1251 1150 the wind stress. 1252 1151 1253 Physical processes related to ocean surface waves can be accounted by setting the logical variable 1254 \np {ln\_wave}\forcode{= .true.} in \ngn{namsbc} namelist. In addition, specific flags accounting for1255 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. 1256 1155 1257 1156 Wave fields can be provided either in forced or coupled mode: 1258 1157 \begin{description} 1259 \item [forced mode]: wave fields should be defined through the \ngn{namsbc\_wave} namelist1260 for external data names, locations, frequency, interpolation and all the miscellanous options allowed by 1261 Input Data generic Interface (see \autoref{sec:SBC_input}). 1262 \item [coupled mode]: NEMO and an external wave model can be coupled by setting \np{ln\_cpl} \forcode{= .true.}1263 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. 1264 1163 \end{description} 1265 1164 1266 1267 % ================================================================ 1268 % Neutral drag coefficient from wave model (ln_cdgw) 1269 1270 % ================================================================ 1271 \subsection[Neutral drag coefficient from wave model (\texttt{ln\_cdgw})] 1272 {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})} 1273 1167 \label{subsec:SBC_wave_cdgw} 1274 1168 1275 The neutral surface drag coefficient provided from an external data source (\ie a wave model), 1276 can be used by setting the logical variable \np{ln\_cdgw} \forcode{= .true.} in \ngn{namsbc} namelist. 1277 Then using the routine \rou{turb\_ncar} and starting from the neutral drag coefficent provided, 1278 the drag coefficient is computed according to the stable/unstable conditions of the 1279 air-sea interface following \citet{large.yeager_rpt04}. 1280 1281 1282 % ================================================================ 1283 % 3D Stokes Drift (ln_sdw, nn_sdrift) 1284 % ================================================================ 1285 \subsection[3D Stokes Drift (\texttt{ln\_sdw}, \texttt{nn\_sdrift})] 1286 {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})} 1287 1177 \label{subsec:SBC_wave_sdw} 1288 1178 1289 The Stokes drift is a wave driven mechanism of mass and momentum transport \citep{stokes_ibk09}. 1290 It is defined as the difference between the average velocity of a fluid parcel (Lagrangian velocity) 1291 and the current measured at a fixed point (Eulerian velocity). 1292 As waves travel, the water particles that make up the waves travel in orbital motions but 1293 without a closed path. Their movement is enhanced at the top of the orbit and slowed slightly 1294 at the bottom so the result is a net forward motion of water particles, referred to as the Stokes drift.1295 An accurate evaluation of the Stokes drift and the inclusion of related processes may lead to improved 1296 representation of surface physics in ocean general circulation models. 1297 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: 1298 1188 1299 1189 \[ 1300 % \label{eq: sbc_wave_sdw}1190 % \label{eq:SBC_wave_sdw} 1301 1191 \mathbf{U}_{st} = \frac{16{\pi^3}} {g} 1302 1192 \int_0^\infty \int_{-\pi}^{\pi} (cos{\theta},sin{\theta}) {f^3} … … 1304 1194 \] 1305 1195 1306 where: ${\theta}$ is the wave direction, $f$ is the wave intrinsic frequency, 1307 $\mathrm{S}($f$,\theta)$ is the 2D frequency-direction spectrum, 1308 $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: 1309 1199 $k=\frac{2\pi}{\lambda}$ (being $\lambda$ the wavelength). \\ 1310 1200 1311 In order to evaluate the Stokes drift in a realistic ocean wave field the wave spectral shape is required1312 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. 1313 1203 To simplify, it is customary to use approximations to the full Stokes profile. 1314 Three possible parameterizations for the calculation for the approximate Stokes drift velocity profile 1315 are included in the code through the \np{nn \_sdrift} parameter once provided the surface Stokes drift1316 $\mathbf{U}_{st |_{z=0}}$ which is evaluated by an external wave model that accurately reproduces the wave spectra 1317 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 1318 1208 realistic wave conditions: 1319 1209 1320 1210 \begin{description} 1321 \item [\np{nn\_sdrift} = 0]: exponential integral profile parameterization proposed by1211 \item [{\np{nn_sdrift}{nn\_sdrift} = 0}]: exponential integral profile parameterization proposed by 1322 1212 \citet{breivik.janssen.ea_JPO14}: 1323 1213 1324 1214 \[ 1325 % \label{eq: sbc_wave_sdw_0a}1326 \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} 1327 1217 \] 1328 1218 … … 1330 1220 1331 1221 \[ 1332 % \label{eq: sbc_wave_sdw_0b}1222 % \label{eq:SBC_wave_sdw_0b} 1333 1223 k_e = \frac{|\mathbf{U}_{\left.st\right|_{z=0}}|} {|T_{st}|} 1334 1224 \quad \text{and }\ 1335 T_{st} = \frac{1}{16} \bar{\omega} H_s^2 1225 T_{st} = \frac{1}{16} \bar{\omega} H_s^2 1336 1226 \] 1337 1227 1338 1228 where $H_s$ is the significant wave height and $\omega$ is the wave frequency. 1339 1229 1340 \item [\np{nn\_sdrift} = 1]: velocity profile based on the Phillips spectrum which is considered to be a1341 reasonable estimate of the part of the spectrum most contributing to the Stokes drift velocity near the surface1230 \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 1342 1232 \citep{breivik.bidlot.ea_OM16}: 1343 1233 1344 1234 \[ 1345 % \label{eq: sbc_wave_sdw_1}1235 % \label{eq:SBC_wave_sdw_1} 1346 1236 \mathbf{U}_{st} \cong \mathbf{U}_{st |_{z=0}} \Big[exp(2k_pz)-\beta \sqrt{-2 \pi k_pz} 1347 1237 \textit{ erf } \Big(\sqrt{-2 k_pz}\Big)\Big] … … 1350 1240 where $erf$ is the complementary error function and $k_p$ is the peak wavenumber. 1351 1241 1352 \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 1353 1243 but using the wave frequency from a wave model. 1354 1244 1355 1245 \end{description} 1356 1246 1357 The Stokes drift enters the wave-averaged momentum equation, as well as the tracer advection equations 1358 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: 1359 1249 1360 1250 \[ 1361 % \label{eq: sbc_wave_eta_sdw}1251 % \label{eq:SBC_wave_eta_sdw} 1362 1252 \frac{\partial{\eta}}{\partial{t}} = 1363 1253 -\nabla_h \int_{-H}^{\eta} (\mathbf{U} + \mathbf{U}_{st}) dz 1364 1254 \] 1365 1255 1366 The tracer advection equation is also modified in order for Eulerian ocean models to properly account 1367 for unresolved wave effect. The divergence of the wave tracer flux equals the mean tracer advection 1368 that is induced by the three-dimensional Stokes velocity. 1369 The advective equation for a tracer $c$ combining the effects of the mean current and sea surface waves 1370 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: 1371 1261 1372 1262 \[ 1373 % \label{eq: sbc_wave_tra_sdw}1263 % \label{eq:SBC_wave_tra_sdw} 1374 1264 \frac{\partial{c}}{\partial{t}} = 1375 1265 - (\mathbf{U} + \mathbf{U}_{st}) \cdot \nabla{c} 1376 1266 \] 1377 1267 1378 1379 % ================================================================ 1380 % Stokes-Coriolis term (ln_stcor) 1381 % ================================================================ 1382 \subsection[Stokes-Coriolis term (\texttt{ln\_stcor})] 1383 {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})} 1384 1270 \label{subsec:SBC_wave_stcor} 1385 1271 1386 In a rotating ocean, waves exert a wave-induced stress on the mean ocean circulation which results 1387 in a force equal to $\mathbf{U}_{st}$×$f$, where $f$ is the Coriolis parameter. 1388 This additional force may have impact on the Ekman turning of the surface current. 1389 In order to include this term, once evaluated the Stokes drift (using one of the 3 possible 1390 approximations described in \autoref{subsec:SBC_wave_sdw}), 1391 \np{ln\_stcor}\forcode{ = .true.} has to be set. 1392 1393 1394 % ================================================================ 1395 % Waves modified stress (ln_tauwoc, ln_tauw) 1396 % ================================================================ 1397 \subsection[Wave modified sress (\texttt{ln\_tauwoc}, \texttt{ln\_tauw})] 1398 {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})} 1399 1281 \label{subsec:SBC_wave_tauw} 1400 1282 1401 The surface stress felt by the ocean is the atmospheric stress minus the net stress going 1402 into the waves \citep{janssen.breivik.ea_rpt13}. Therefore, when waves are growing, momentum and energy is spent and is not 1403 available for forcing the mean circulation, while in the opposite case of a decaying sea 1404 state more momentum is available for forcing the ocean.1405 Only when the sea state is in equilibrium the ocean is forced by the atmospheric stress,1406 but in practice an equilibrium sea state is a fairly rare event.1407 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: 1408 1290 1409 1291 \[ 1410 % \label{eq: sbc_wave_tauoc}1292 % \label{eq:SBC_wave_tauoc} 1411 1293 \tau_{oc,a} = \tau_a - \tau_w 1412 1294 \] … … 1416 1298 1417 1299 \[ 1418 % \label{eq: sbc_wave_tauw}1300 % \label{eq:SBC_wave_tauw} 1419 1301 \tau_w = \rho g \int {\frac{dk}{c_p} (S_{in}+S_{nl}+S_{diss})} 1420 1302 \] 1421 1303 1422 1304 where: $c_p$ is the phase speed of the gravity waves, 1423 $S_{in}$, $S_{nl}$ and $S_{diss}$ are three source terms that represent 1424 the physics of ocean waves. The first one, $S_{in}$, describes the generation 1425 of ocean waves by wind and therefore represents the momentum and energy transfer 1426 from air to ocean waves; the second term $S_{nl}$ denotes 1427 the nonlinear transfer by resonant four-wave interactions; while the third term $S_{diss}$ 1428 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 1429 1311 eddy-induced damping. 1430 1312 1431 The wave stress derived from an external wave model can be provided either through the normalized 1432 wave stress into the ocean by setting \np{ln\_tauwoc}\forcode{ = .true.}, or through the zonal and 1433 meridional stress components by setting \np{ln\_tauw}\forcode{ = .true.}. 1434 1435 1436 % ================================================================ 1437 % Miscellanea options 1438 % ================================================================ 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 %% ================================================================================================= 1439 1318 \section{Miscellaneous options} 1440 1319 \label{sec:SBC_misc} 1441 1320 1442 % ------------------------------------------------------------------------------------------------------------- 1443 % Diurnal cycle 1444 % ------------------------------------------------------------------------------------------------------------- 1445 \subsection[Diurnal cycle (\textit{sbcdcy.F90})] 1446 {Diurnal cycle (\protect\mdl{sbcdcy})} 1321 %% ================================================================================================= 1322 \subsection[Diurnal cycle (\textit{sbcdcy.F90})]{Diurnal cycle (\protect\mdl{sbcdcy})} 1447 1323 \label{subsec:SBC_dcy} 1448 %------------------------------------------namsbc_rnf---------------------------------------------------- 1449 % 1450 \nlst{namsbc} 1451 %------------------------------------------------------------------------------------------------------------- 1452 1453 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1324 1454 1325 \begin{figure}[!t] 1455 \begin{center} 1456 \includegraphics[width=\textwidth]{Fig_SBC_diurnal} 1457 \caption{ 1458 \protect\label{fig:SBC_diurnal} 1459 Example of recontruction of the diurnal cycle variation of short wave flux from daily mean values. 1460 The reconstructed diurnal cycle (black line) is chosen as 1461 the mean value of the analytical cycle (blue line) over a time step, 1462 not as the mid time step value of the analytically cycle (red square). 1463 From \citet{bernie.guilyardi.ea_CD07}. 1464 } 1465 \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} 1466 1336 \end{figure} 1467 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>1468 1337 1469 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. 1470 Unfortunately high frequency forcing fields are rare, not to say inexistent. 1471 Nevertheless, it is possible to obtain a reasonable diurnal cycle of the SST knowning only short wave flux (SWF) at 1472 high frequency \citep{bernie.guilyardi.ea_CD07}. 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}. 1473 1341 Furthermore, only the knowledge of daily mean value of SWF is needed, 1474 1342 as higher frequency variations can be reconstructed from them, 1475 1343 assuming that the diurnal cycle of SWF is a scaling of the top of the atmosphere diurnal cycle of incident SWF. 1476 The \cite{bernie.guilyardi.ea_CD07} reconstruction algorithm is available in \NEMO by1477 setting \np {ln\_dm2dc}\forcode{ = .true.} (a \textit{\ngn{namsbc}} namelist variable) when1478 using CORE bulk formulea (\np{ln\_blk\_core}\forcode{ = .true.}) or1479 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}). 1480 1348 The reconstruction is performed in the \mdl{sbcdcy} module. 1481 1349 The detail of the algoritm used can be found in the appendix~A of \cite{bernie.guilyardi.ea_CD07}. 1482 The algorithm preserve the daily mean incoming SWF as the reconstructed SWF at1350 The algorithm preserves the daily mean incoming SWF as the reconstructed SWF at 1483 1351 a given time step is the mean value of the analytical cycle over this time step (\autoref{fig:SBC_diurnal}). 1484 1352 The use of diurnal cycle reconstruction requires the input SWF to be daily 1485 (\ie a frequency of 24 and a time interpolation set to true in \np{sn\_qsr} namelist parameter).1486 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, 1487 1355 that is $\rdt \ nn\_fsbc < 10,800~s = 3~h$. 1488 1356 An example of recontructed SWF is given in \autoref{fig:SBC_dcy} for a 12 reconstructed diurnal cycle, 1489 1357 one every 2~hours (from 1am to 11pm). 1490 1358 1491 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>1492 1359 \begin{figure}[!t] 1493 \begin{center} 1494 \includegraphics[width=\textwidth]{Fig_SBC_dcy} 1495 \caption{ 1496 \protect\label{fig:SBC_dcy} 1497 Example of recontruction of the diurnal cycle variation of short wave flux from 1498 daily mean values on an ORCA2 grid with a time sampling of 2~hours (from 1am to 11pm). 1499 The display is on (i,j) plane. 1500 } 1501 \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} 1502 1367 \end{figure} 1503 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>1504 1368 1505 1369 Note also that the setting a diurnal cycle in SWF is highly recommended when … … 1507 1371 an inconsistency between the scale of the vertical resolution and the forcing acting on that scale. 1508 1372 1509 % ------------------------------------------------------------------------------------------------------------- 1510 % Rotation of vector pairs onto the model grid directions 1511 % ------------------------------------------------------------------------------------------------------------- 1373 %% ================================================================================================= 1512 1374 \subsection{Rotation of vector pairs onto the model grid directions} 1513 1375 \label{subsec:SBC_rotation} 1514 1376 1515 When using a flux (\np{ln\_flx}\forcode{ = .true.}) or 1516 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, 1517 1378 pairs of vector components can be rotated from east-north directions onto the local grid directions. 1518 1379 This is particularly useful when interpolation on the fly is used since here any vectors are likely to 1519 1380 be defined relative to a rectilinear grid. 1520 To activate this option a non-empty string is supplied in the rotation pair column of the relevant namelist.1521 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". 1522 1383 The remaining characters in the strings are used to identify which pair of components go together. 1523 1384 So for example, strings "U1" and "V1" next to "utau" and "vtau" would pair the wind stress components together and … … 1527 1388 The rot\_rep routine from the \mdl{geo2ocean} module is used to perform the rotation. 1528 1389 1529 % ------------------------------------------------------------------------------------------------------------- 1530 % Surface restoring to observed SST and/or SSS 1531 % ------------------------------------------------------------------------------------------------------------- 1532 \subsection[Surface restoring to observed SST and/or SSS (\textit{sbcssr.F90})] 1533 {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})} 1534 1392 \label{subsec:SBC_ssr} 1535 %------------------------------------------namsbc_ssr---------------------------------------------------- 1536 1537 \nlst{namsbc_ssr} 1538 %------------------------------------------------------------------------------------------------------------- 1539 1540 IOptions are defined through the \ngn{namsbc\_ssr} namelist variables. 1541 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}), 1542 1402 a feedback term \emph{must} be added to the surface heat flux $Q_{ns}^o$: 1543 1403 \[ 1544 % \label{eq: sbc_dmp_q}1404 % \label{eq:SBC_dmp_q} 1545 1405 Q_{ns} = Q_{ns}^o + \frac{dQ}{dT} \left( \left. T \right|_{k=1} - SST_{Obs} \right) 1546 1406 \] … … 1548 1408 $T$ is the model surface layer temperature and 1549 1409 $\frac{dQ}{dT}$ is a negative feedback coefficient usually taken equal to $-40~W/m^2/K$. 1550 For a $50~m$ mixed-layer depth, this value corresponds to a relaxation time scale of two months. 1551 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$. 1552 1412 1553 1413 In the fresh water budget, a feedback term can also be added. … … 1555 1415 1556 1416 \begin{equation} 1557 \label{eq: sbc_dmp_emp}1417 \label{eq:SBC_dmp_emp} 1558 1418 \textit{emp} = \textit{emp}_o + \gamma_s^{-1} e_{3t} \frac{ \left(\left.S\right|_{k=1}-SSS_{Obs}\right)} 1559 1419 {\left.S\right|_{k=1}} … … 1566 1426 $\left.S\right|_{k=1}$ is the model surface layer salinity and 1567 1427 $\gamma_s$ is a negative feedback coefficient which is provided as a namelist parameter. 1568 Unlike heat flux, there is no physical justification for the feedback term in \autoref{eq: sbc_dmp_emp} as1428 Unlike heat flux, there is no physical justification for the feedback term in \autoref{eq:SBC_dmp_emp} as 1569 1429 the atmosphere does not care about ocean surface salinity \citep{madec.delecluse_IWN97}. 1570 1430 The SSS restoring term should be viewed as a flux correction on freshwater fluxes to 1571 1431 reduce the uncertainties we have on the observed freshwater budget. 1572 1432 1573 % ------------------------------------------------------------------------------------------------------------- 1574 % Handling of ice-covered area 1575 % ------------------------------------------------------------------------------------------------------------- 1433 %% ================================================================================================= 1576 1434 \subsection{Handling of ice-covered area (\textit{sbcice\_...})} 1577 1435 \label{subsec:SBC_ice-cover} … … 1579 1437 The presence at the sea surface of an ice covered area modifies all the fluxes transmitted to the ocean. 1580 1438 There are several way to handle sea-ice in the system depending on 1581 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. 1582 1440 \begin{description} 1583 \item[nn{\_}ice = 0] 1584 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. 1585 1442 This is a typical namelist value used for tropical ocean domain. 1586 1443 The surface fluxes are simply specified for an ice-free ocean. 1587 1444 No specific things is done for sea-ice. 1588 \item[nn{\_}ice = 1] 1589 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. 1590 1446 An observed ice covered area is read in a file. 1591 1447 Below this area, the SST is restored to the freezing point and … … 1595 1451 This prevents deep convection to occur when trying to reach the freezing point 1596 1452 (and so ice covered area condition) while the SSS is too large. 1597 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, 1598 1454 is usually referred as the \textit{ice-if} model. 1599 It can be found in the \mdl{sbcice{\_}if} module. 1600 \item[nn{\_}ice = 2 or more] 1601 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. 1602 1457 This model computes the ice-ocean fluxes, 1603 1458 that are combined with the air-sea fluxes using the ice fraction of each model cell to 1604 provide the surface ocean fluxes.1605 Note that the activation of a sea-ice model is is done by defining a CPP key (\key{lim3} or \key{cice}).1606 The activation automatically overwrites the read value of nn {\_}ice to its appropriate value1607 (\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). 1608 1463 \end{description} 1609 1464 1610 1465 % {Description of Ice-ocean interface to be added here or in LIM 2 and 3 doc ?} 1611 1612 \subsection[Interface to CICE (\textit{sbcice\_cice.F90})] 1613 {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})} 1614 1470 \label{subsec:SBC_cice} 1615 1471 1616 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) 1617 1473 to the CICE sea-ice model by using \key{cice}. 1618 1474 The CICE code can be obtained from \href{http://oceans11.lanl.gov/trac/CICE/}{LANL} and 1619 1475 the additional 'hadgem3' drivers will be required, even with the latest code release. 1620 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, 1621 1477 and CICE CPP keys \textbf{ORCA\_GRID}, \textbf{CICE\_IN\_NEMO} and \textbf{coupled} should be used 1622 1478 (seek advice from UKMO if necessary). 1623 Currently the code is only designed to work when using the CORE forcing option for NEMO1624 (with \textit{calc\_strair}\forcode{ = .true.} and \textit{calc\_Tsfc}\forcode{ =.true.} in the CICE name-list),1625 or alternatively when NEMOis coupled to the HadGAM3 atmosphere model1626 (with \textit{calc\_strair}\forcode{ = .false.} and \textit{calc\_Tsfc}\forcode{ =false}).1627 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 1628 1484 (although coupling ocean and ice less frequently should work, 1629 1485 it is possible the calculation of some of the ocean-ice fluxes needs to be modified slightly - 1630 1486 the user should check that results are not significantly different to the standard case). 1631 1487 1632 There are two options for the technical coupling between NEMOand CICE.1488 There are two options for the technical coupling between \NEMO\ and CICE. 1633 1489 The standard version allows complete flexibility for the domain decompositions in the individual models, 1634 1490 but this is at the expense of global gather and scatter operations in the coupling which 1635 1491 become very expensive on larger numbers of processors. 1636 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 1637 1493 the domain decomposition is identical in both models (provided domain parameters are set appropriately, 1638 1494 and \textit{processor\_shape~=~square-ice} and \textit{distribution\_wght~=~block} in the CICE name-list) and … … 1641 1497 there is no sea ice. 1642 1498 1643 % ------------------------------------------------------------------------------------------------------------- 1644 % Freshwater budget control 1645 % ------------------------------------------------------------------------------------------------------------- 1646 \subsection[Freshwater budget control (\textit{sbcfwb.F90})] 1647 {Freshwater budget control (\protect\mdl{sbcfwb})} 1499 %% ================================================================================================= 1500 \subsection[Freshwater budget control (\textit{sbcfwb.F90})]{Freshwater budget control (\protect\mdl{sbcfwb})} 1648 1501 \label{subsec:SBC_fwb} 1649 1502 1650 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 1651 1504 prevent unrealistic drift of the sea surface height due to inaccuracy in the freshwater fluxes. 1652 In \NEMO, two way of controlling the the freshwater budget. 1505 In \NEMO, two way of controlling the freshwater budget are proposed: 1506 1653 1507 \begin{description} 1654 \item[\np{nn\_fwb}\forcode{ = 0}] 1655 no control at all. 1508 \item [{\np[=0]{nn_fwb}{nn\_fwb}}] no control at all. 1656 1509 The mean sea level is free to drift, and will certainly do so. 1657 \item[\np{nn\_fwb}\forcode{ = 1}] 1658 global mean \textit{emp} set to zero at each model time step. 1659 %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). 1660 \item[\np{nn\_fwb}\forcode{ = 2}] 1661 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 1662 1514 is read in the \textit{EMPave\_old.dat} file. 1663 1515 As the model uses the Boussinesq approximation, the annual mean fresh water budget is simply evaluated from 1664 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. 1665 1517 \end{description} 1666 1518 1667 1668 1669 1519 % Griffies doc: 1670 % When running ocean-ice simulations, we are not explicitly representing land processes, 1671 % such as rivers, catchment areas, snow accumulation, etc. However, to reduce model drift, 1672 % it is important to balance the hydrological cycle in ocean-ice models. 1673 % We thus need to prescribe some form of global normalization to the precipitation minus evaporation plus river runoff. 1674 % The result of the normalization should be a global integrated zero net water input to the ocean-ice system over 1675 % a chosen time scale. 1676 %How often the normalization is done is a matter of choice. In mom4p1, we choose to do so at each model time step, 1677 % so that there is always a zero net input of water to the ocean-ice system. 1678 % Others choose to normalize over an annual cycle, in which case the net imbalance over an annual cycle is used 1679 % to alter the subsequent year�s water budget in an attempt to damp the annual water imbalance. 1680 % Note that the annual budget approach may be inappropriate with interannually varying precipitation forcing. 1681 % When running ocean-ice coupled models, it is incorrect to include the water transport between the ocean 1682 % and ice models when aiming to balance the hydrological cycle. 1683 % 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, 1684 % not the water in any one sub-component. As an extreme example to illustrate the issue, 1685 % consider an ocean-ice model with zero initial sea ice. As the ocean-ice model spins up, 1686 % there should be a net accumulation of water in the growing sea ice, and thus a net loss of water from the ocean. 1687 % The total water contained in the ocean plus ice system is constant, but there is an exchange of water between 1688 % the subcomponents. This exchange should not be part of the normalization used to balance the hydrological cycle 1689 % in ocean-ice models. 1690 1691 \biblio 1692 1693 \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}} 1694 1542 1695 1543 \end{document} -
NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_STO.tex
r11123 r12149 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_OM13} 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 model62 The generic approach here is to a new STO module, 63 generating processes features with appropriate statistics to simulate these uncertainties in the model 48 64 (see \cite{brankart.candille.ea_GMD15} for more details). 49 65 50 In practice, at e verymodel grid point,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/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_TRA.tex
r11179 r12149 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 (\textit{traadv.F90})] 63 {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})} 64 78 \label{sec:TRA_adv} 65 %------------------------------------------namtra_adv----------------------------------------------------- 66 67 \nlst{namtra_adv} 68 %------------------------------------------------------------------------------------------------------------- 69 70 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.}), 71 87 the advection tendency of a tracer is expressed in flux form, 72 \ie as the divergence of the advective fluxes.73 Its discrete expression is given by 74 \begin{equation} 75 \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} 76 92 ADV_\tau = - \frac{1}{b_t} \Big( \delta_i [ e_{2u} \, e_{3u} \; u \; \tau_u] 77 93 + \delta_j [ e_{1v} \, e_{3v} \; v \; \tau_v] \Big) … … 79 95 \end{equation} 80 96 where $\tau$ is either T or S, and $b_t = e_{1t} \, e_{2t} \, e_{3t}$ is the volume of $T$-cells. 81 The flux form in \autoref{eq:tra_adv} implicitly requires the use of the continuity equation. 82 Indeed, it is obtained by using the following equality: $\nabla \cdot (\vect U \, T) = \vect U \cdot \nabla T$ which 83 results from the use of the continuity equation, $\partial_t e_3 + e_3 \; \nabla \cdot \vect U = 0$ 84 (which reduces to $\nabla \cdot \vect U = 0$ in linear free surface, \ie \np{ln\_linssh}\forcode{ = .true.}). 85 Therefore it is of paramount importance to design the discrete analogue of the advection tendency so that 86 it is consistent with the continuity equation in order to enforce the conservation properties of 87 the continuous equations. 88 In other words, by setting $\tau = 1$ in (\autoref{eq:tra_adv}) we recover the discrete form of 89 the continuity equation which is used to calculate the vertical velocity. 90 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 91 \begin{figure}[!t] 92 \begin{center} 93 \includegraphics[width=\textwidth]{Fig_adv_scheme} 94 \caption{ 95 \protect\label{fig:adv_scheme} 96 Schematic representation of some ways used to evaluate the tracer value at $u$-point and 97 the amount of tracer exchanged between two neighbouring grid points. 98 Upsteam biased scheme (ups): 99 the upstream value is used and the black area is exchanged. 100 Piecewise parabolic method (ppm): 101 a parabolic interpolation is used and the black and dark grey areas are exchanged. 102 Monotonic upstream scheme for conservative laws (muscl): 103 a parabolic interpolation is used and black, dark grey and grey areas are exchanged. 104 Second order scheme (cen2): 105 the mean value is used and black, dark grey, grey and light grey areas are exchanged. 106 Note that this illustration does not include the flux limiter used in ppm and muscl schemes. 107 } 108 \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} 109 126 \end{figure} 110 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 111 112 The key difference between the advection schemes available in \NEMO is the choice made in space and 113 time interpolation to define the value of the tracer at the velocity points 114 (\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}). 115 131 116 132 Along solid lateral and bottom boundaries a zero tracer flux is automatically specified, … … 119 135 120 136 \begin{description} 121 \item[linear free surface:] 122 (\np{ln\_linssh}\forcode{ = .true.}) 137 \item [linear free surface] (\np[=.true.]{ln_linssh}{ln\_linssh}) 123 138 the first level thickness is constant in time: 124 the vertical boundary condition is applied at the fixed surface $z = 0$ rather than on 125 the moving surface $z = \eta$. 126 There is a non-zero advective flux which is set for all advection schemes as 127 $\tau_w|_{k = 1/2} = T_{k = 1}$, \ie the product of surface velocity (at $z = 0$) by 128 the first level tracer value. 129 \item[non-linear free surface:] 130 (\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}) 131 145 convergence/divergence in the first ocean level moves the free surface up/down. 132 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. 133 148 \end{description} 134 149 135 150 In all cases, this boundary condition retains local conservation of tracer. 136 Global conservation is obtained in non-linear free surface case, but \textit{not} in the linear free surface case. 137 Nevertheless, in the latter case, it is achieved to a good approximation since 138 the non-conservative term is the product of the time derivative of the tracer and the free surface height, 139 two quantities that are not correlated \citep{roullet.madec_JGR00, griffies.pacanowski.ea_MWR01, campin.adcroft.ea_OM04}. 140 141 The velocity field that appears in (\autoref{eq:tra_adv} and \autoref{eq:tra_adv_zco?}) is 142 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 143 161 (see \autoref{chap:DYN}) plus the eddy induced velocity (\textit{eiv}) and/or 144 162 the mixed layer eddy induced velocity (\textit{eiv}) when those parameterisations are used 145 163 (see \autoref{chap:LDF}). 146 164 147 Several tracer advection scheme are proposed, namely a $2^{nd}$ or $4^{th}$ order centred schemes (CEN), 148 a $2^{nd}$ or $4^{th}$ order Flux Corrected Transport scheme (FCT), a Monotone Upstream Scheme for 149 Conservative Laws scheme (MUSCL), a $3^{rd}$ Upstream Biased Scheme (UBS, also often called UP3), 150 and a Quadratic Upstream Interpolation for Convective Kinematics with Estimated Streaming Terms scheme (QUICKEST). 151 The choice is made in the \ngn{namtra\_adv} namelist, by setting to \forcode{.true.} one of 152 the logicals \textit{ln\_traadv\_xxx}. 153 The corresponding code can be found in the \textit{traadv\_xxx.F90} module, where 154 \textit{xxx} is a 3 or 4 letter acronym corresponding to each scheme. 155 By default (\ie in the reference namelist, \textit{namelist\_ref}), all the logicals are set to \forcode{.false.}. 156 If the user does not select an advection scheme in the configuration namelist (\textit{namelist\_cfg}), 157 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! 158 182 159 183 Details of the advection schemes are given below. 160 The choosing an advection scheme is a complex matter which depends on the model physics, model resolution, 161 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 162 187 163 188 \begin{enumerate} 164 \item 165 CEN and FCT schemes require an explicit diffusion operator while the other schemes are diffusive enough so that 166 they do not necessarily need additional diffusion; 167 \item 168 CEN and UBS are not \textit{positive} schemes 169 \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}, 170 193 implying that false extrema are permitted. 171 194 Their use is not recommended on passive tracers; 172 \item 173 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. 174 197 \end{enumerate} 175 198 176 Indeed, if a source or sink of a passive tracer depends on an active one, the difference of treatment of active and 177 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. 178 202 Nevertheless, most of our users set a different treatment on passive and active tracers, 179 203 that's the reason why this possibility is offered. 180 We strongly suggest them to perform a sensitivity experiment using a same treatment to assess the robustness of 181 their results. 182 183 % ------------------------------------------------------------------------------------------------------------- 184 % 2nd and 4th order centred schemes 185 % ------------------------------------------------------------------------------------------------------------- 186 \subsection[CEN: Centred scheme (\forcode{ln_traadv_cen = .true.})] 187 {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})} 188 209 \label{subsec:TRA_adv_cen} 189 210 190 % 2nd order centred scheme 191 192 The centred advection scheme (CEN) is used when \np{ln\_traadv\_cen}\forcode{ = .true.}. 193 Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on horizontal (iso-level) and vertical direction by 194 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$. 195 217 CEN implementation can be found in the \mdl{traadv\_cen} module. 196 218 197 In the $2^{nd}$ order centred formulation (CEN2), the tracer at velocity points is evaluated as the mean of198 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. 199 221 For example, in the $i$-direction : 200 222 \begin{equation} 201 \label{eq: tra_adv_cen2}223 \label{eq:TRA_adv_cen2} 202 224 \tau_u^{cen2} = \overline T ^{i + 1/2} 203 225 \end{equation} 204 226 205 CEN2 is non diffusive (\ie it conserves the tracer variance, $\tau^2$) but dispersive 206 (\ie it may create false extrema). 207 It is therefore notoriously noisy and must be used in conjunction with an explicit diffusion operator to 208 produce a sensible solution. 209 The associated time-stepping is performed using a leapfrog scheme in conjunction with an Asselin time-filter, 210 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. 211 234 212 235 Note that using the CEN2, the overall tracer advection is of second order accuracy since 213 both (\autoref{eq:tra_adv}) and (\autoref{eq:tra_adv_cen2}) have this order of accuracy. 214 215 % 4nd order centred scheme 216 217 In the $4^{th}$ order formulation (CEN4), tracer values are evaluated at u- and v-points as 218 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. 219 243 For example, in the $i$-direction: 220 244 \begin{equation} 221 \label{eq: tra_adv_cen4}245 \label{eq:TRA_adv_cen4} 222 246 \tau_u^{cen4} = \overline{T - \frac{1}{6} \, \delta_i \Big[ \delta_{i + 1/2}[T] \, \Big]}^{\,i + 1/2} 223 247 \end{equation} 224 In the vertical direction (\np {nn\_cen\_v}\forcode{ = 4}),248 In the vertical direction (\np[=4]{nn_cen_v}{nn\_cen\_v}), 225 249 a $4^{th}$ COMPACT interpolation has been prefered \citep{demange_phd14}. 226 In the COMPACT scheme, both the field and its derivative are interpolated, which leads, after a matrix inversion, 227 spectral characteristics similar to schemes of higher order \citep{lele_JCP92}. 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}. 228 253 229 254 Strictly speaking, the CEN4 scheme is not a $4^{th}$ order advection scheme but 230 255 a $4^{th}$ order evaluation of advective fluxes, 231 since the divergence of advective fluxes \autoref{eq: tra_adv} is kept at $2^{nd}$ order.232 The expression \textit{$4^{th}$ order scheme} used in oceanographic literature is usually associated with233 the scheme presented here.234 Introducing a \forcode{.true.}$4^{th}$ order advection scheme is feasible but, for consistency reasons,235 it requires changes in the discretisation of the tracer advection together with changes in the continuity equation,236 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. 237 262 238 263 A direct consequence of the pseudo-fourth order nature of the scheme is that it is not non-diffusive, 239 \ie the global variance of a tracer is not preserved using CEN4. 240 Furthermore, it must be used in conjunction with an explicit diffusion operator to produce a sensible solution. 241 As in CEN2 case, the time-stepping is performed using a leapfrog scheme in conjunction with an Asselin time-filter, 242 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. 243 269 244 270 At a $T$-grid cell adjacent to a boundary (coastline, bottom and surface), … … 246 272 This hypothesis usually reduces the order of the scheme. 247 273 Here we choose to set the gradient of $T$ across the boundary to zero. 248 Alternative conditions can be specified, such as a reduction to a second order scheme for 249 these near boundary grid points. 250 251 % ------------------------------------------------------------------------------------------------------------- 252 % FCT scheme 253 % ------------------------------------------------------------------------------------------------------------- 254 \subsection[FCT: Flux Corrected Transport scheme (\forcode{ln_traadv_fct = .true.})] 255 {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})} 256 279 \label{subsec:TRA_adv_tvd} 257 280 258 The Flux Corrected Transport schemes (FCT) is used when \np{ln\_traadv\_fct}\forcode{ = .true.}. 259 Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on horizontal (iso-level) and vertical direction by 260 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$. 261 286 FCT implementation can be found in the \mdl{traadv\_fct} module. 262 287 263 In FCT formulation, the tracer at velocity points is evaluated using a combination of an upstream and264 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. 265 290 For example, in the $i$-direction : 266 291 \begin{equation} 267 \label{eq: tra_adv_fct}292 \label{eq:TRA_adv_fct} 268 293 \begin{split} 269 294 \tau_u^{ups} &= … … 271 296 T_{i + 1} & \text{if~} u_{i + 1/2} < 0 \\ 272 297 T_i & \text{if~} u_{i + 1/2} \geq 0 \\ 273 \end{cases} 274 \\ 298 \end{cases} \\ 275 299 \tau_u^{fct} &= \tau_u^{ups} + c_u \, \big( \tau_u^{cen} - \tau_u^{ups} \big) 276 300 \end{split} … … 278 302 where $c_u$ is a flux limiter function taking values between 0 and 1. 279 303 The FCT order is the one of the centred scheme used 280 (\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}). 281 305 There exist many ways to define $c_u$, each corresponding to a different FCT scheme. 282 The one chosen in \NEMO is described in \citet{zalesak_JCP79}.306 The one chosen in \NEMO\ is described in \citet{zalesak_JCP79}. 283 307 $c_u$ only departs from $1$ when the advective term produces a local extremum in the tracer field. 284 308 The resulting scheme is quite expensive but \textit{positive}. … … 286 310 A comparison of FCT-2 with MUSCL and a MPDATA scheme can be found in \citet{levy.estublier.ea_GRL01}. 287 311 288 An additional option has been added controlled by \np{nn\_fct\_zts}. 289 By setting this integer to a value larger than zero, 290 a $2^{nd}$ order FCT scheme is used on both horizontal and vertical direction, but on the latter, 291 a split-explicit time stepping is used, with a number of sub-timestep equals to \np{nn\_fct\_zts}. 292 This option can be useful when the size of the timestep is limited by vertical advection \citep{lemarie.debreu.ea_OM15}. 293 Note that in this case, a similar split-explicit time stepping should be used on vertical advection of momentum to 294 insure a better stability (see \autoref{subsec:DYN_zad}). 295 296 For stability reasons (see \autoref{chap:STP}), 297 $\tau_u^{cen}$ is evaluated in (\autoref{eq:tra_adv_fct}) using the \textit{now} tracer while 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 298 314 $\tau_u^{ups}$ is evaluated using the \textit{before} tracer. 299 In other words, the advective part of the scheme is time stepped with a leap-frog scheme 300 while a forward scheme is used for the diffusive part. 301 302 % ------------------------------------------------------------------------------------------------------------- 303 % MUSCL scheme 304 % ------------------------------------------------------------------------------------------------------------- 305 \subsection[MUSCL: Monotone Upstream Scheme for Conservative Laws (\forcode{ln_traadv_mus = .true.})] 306 {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})} 307 320 \label{subsec:TRA_adv_mus} 308 321 309 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}. 310 324 MUSCL implementation can be found in the \mdl{traadv\_mus} module. 311 325 312 MUSCL has been first implemented in \NEMO by \citet{levy.estublier.ea_GRL01}.313 In its formulation, the tracer at velocity points is evaluated assuming a linear tracer variation between314 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}). 315 329 For example, in the $i$-direction : 316 \ begin{equation}317 % \label{eq: tra_adv_mus}330 \[ 331 % \label{eq:TRA_adv_mus} 318 332 \tau_u^{mus} = \lt\{ 319 333 \begin{split} 320 \tau_i&+ \frac{1}{2} \lt( 1 - \frac{u_{i + 1/2} \, \rdt}{e_{1u}} \rt)321 \widetilde{\partial_i\tau} & \text{if~} u_{i + 1/2} \geqslant 0 \\322 323 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 324 338 \end{split} 325 339 \rt. 326 \ end{equation}327 where $\widetilde{\partial_i \tau}$ is the slope of the tracer on which a limitation is imposed to328 ensure the \textit{positive} character of the scheme.329 330 The time stepping is performed using a forward scheme, that is the \textit{before} tracer field is used to331 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}$. 332 346 333 347 For an ocean grid point adjacent to land and where the ocean velocity is directed toward land, 334 348 an upstream flux is used. 335 349 This choice ensure the \textit{positive} character of the scheme. 336 In addition, fluxes round a grid-point where a runoff is applied can optionally be computed using upstream fluxes 337 (\np{ln\_mus\_ups}\forcode{ = .true.}). 338 339 % ------------------------------------------------------------------------------------------------------------- 340 % UBS scheme 341 % ------------------------------------------------------------------------------------------------------------- 342 \subsection[UBS a.k.a. UP3: Upstream-Biased Scheme (\forcode{ln_traadv_ubs = .true.})] 343 {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})} 344 355 \label{subsec:TRA_adv_ubs} 345 356 346 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}. 347 359 UBS implementation can be found in the \mdl{traadv\_mus} module. 348 360 349 361 The UBS scheme, often called UP3, is also known as the Cell Averaged QUICK scheme 350 (Quadratic Upstream Interpolation for Convective Kinematics). 362 (\textbf{Q}uadratic \textbf{U}pstream \textbf{I}nterpolation for 363 \textbf{C}onvective \textbf{K}inematics). 351 364 It is an upstream-biased third order scheme based on an upstream-biased parabolic interpolation. 352 365 For example, in the $i$-direction: 353 366 \begin{equation} 354 \label{eq: tra_adv_ubs}367 \label{eq:TRA_adv_ubs} 355 368 \tau_u^{ubs} = \overline T ^{i + 1/2} - \frac{1}{6} 356 369 \begin{cases} 357 358 370 \tau"_i & \text{if~} u_{i + 1/2} \geqslant 0 \\ 371 \tau"_{i + 1} & \text{if~} u_{i + 1/2} < 0 359 372 \end{cases} 360 \quad 361 \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] 362 374 \end{equation} 363 375 364 376 This results in a dissipatively dominant (i.e. hyper-diffusive) truncation error 365 377 \citep{shchepetkin.mcwilliams_OM05}. 366 The overall performance of the advection scheme is similar to that reported in \cite{farrow.stevens_JPO95}. 378 The overall performance of the advection scheme is similar to that reported in 379 \cite{farrow.stevens_JPO95}. 367 380 It is a relatively good compromise between accuracy and smoothness. 368 381 Nevertheless the scheme is not \textit{positive}, meaning that false extrema are permitted, 369 382 but the amplitude of such are significantly reduced over the centred second or fourth order method. 370 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. 371 385 372 386 The intrinsic diffusion of UBS makes its use risky in the vertical direction where 373 387 the control of artificial diapycnal fluxes is of paramount importance 374 388 \citep{shchepetkin.mcwilliams_OM05, demange_phd14}. 375 Therefore the vertical flux is evaluated using either a $2^nd$ order FCT scheme or a $4^th$ order COMPACT scheme376 (\np{nn\_cen\_v}\forcode{ = 2 or 4}).377 378 For stability reasons (see \autoref{chap: STP}), the first term in \autoref{eq:tra_adv_ubs}379 (which corresponds to a second order centred scheme)380 is evaluated using the \textit{now} tracer (centred in time) while the second term381 (which is the diffusive part of the scheme),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), 382 396 is evaluated using the \textit{before} tracer (forward in time). 383 This choice is discussed by \citet{webb.de-cuevas.ea_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. 384 399 UBS and QUICK schemes only differ by one coefficient. 385 Replacing 1/6 with 1/8 in \autoref{eq:tra_adv_ubs} leads to the QUICK advection scheme \citep{webb.de-cuevas.ea_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}. 386 402 This option is not available through a namelist parameter, since the 1/6 coefficient is hard coded. 387 Nevertheless it is quite easy to make the substitution in the \mdl{traadv\_ubs} module and obtain a QUICK scheme. 388 389 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: 390 407 \begin{gather} 391 \label{eq: traadv_ubs2}408 \label{eq:TRA_adv_ubs2} 392 409 \tau_u^{ubs} = \tau_u^{cen4} + \frac{1}{12} 393 410 \begin{cases} … … 396 413 \end{cases} 397 414 \intertext{or equivalently} 398 % \label{eq: traadv_ubs2b}415 % \label{eq:TRA_adv_ubs2b} 399 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} 400 417 - \frac{1}{2} |u|_{i + 1/2} \, \frac{1}{6} \, \delta_{i + 1/2} [\tau"_i] \nonumber 401 418 \end{gather} 402 419 403 \autoref{eq: traadv_ubs2} has several advantages.420 \autoref{eq:TRA_adv_ubs2} has several advantages. 404 421 Firstly, it clearly reveals that the UBS scheme is based on the fourth order scheme to which 405 422 an upstream-biased diffusion term is added. 406 Secondly, this emphasises that the $4^{th}$ order part (as well as the $2^{nd}$ order part as stated above) has to 407 be evaluated at the \textit{now} time step using \autoref{eq:tra_adv_ubs}. 408 Thirdly, the diffusion term is in fact a biharmonic operator with an eddy coefficient which 409 is simply proportional to the velocity: $A_u^{lm} = \frac{1}{12} \, {e_{1u}}^3 \, |u|$. 410 Note the current version of NEMO uses the computationally more efficient formulation \autoref{eq:tra_adv_ubs}. 411 412 % ------------------------------------------------------------------------------------------------------------- 413 % QCK scheme 414 % ------------------------------------------------------------------------------------------------------------- 415 \subsection[QCK: QuiCKest scheme (\forcode{ln_traadv_qck = .true.})] 416 {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})} 417 433 \label{subsec:TRA_adv_qck} 418 434 419 The Quadratic Upstream Interpolation for Convective Kinematics with Estimated Streaming Terms (QUICKEST) scheme 420 proposed by \citet{leonard_CMAME79} 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}. 421 439 QUICKEST implementation can be found in the \mdl{traadv\_qck} module. 422 440 423 441 QUICKEST is the third order Godunov scheme which is associated with the ULTIMATE QUICKEST limiter 424 442 \citep{leonard_CMAME91}. 425 It has been implemented in NEMO by G. Reffray (MERCATOR-ocean) and can be found in the \mdl{traadv\_qck} module. 443 It has been implemented in \NEMO\ by G. Reffray (Mercator Ocean) and 444 can be found in the \mdl{traadv\_qck} module. 426 445 The resulting scheme is quite expensive but \textit{positive}. 427 446 It can be used on both active and passive tracers. … … 430 449 Therefore the vertical flux is evaluated using the CEN2 scheme. 431 450 This no longer guarantees the positivity of the scheme. 432 The use of FCT in the vertical direction (as for the UBS case) should be implemented to restore this property. 433 434 %%%gmcomment : Cross term are missing in the current implementation.... 435 436 % ================================================================ 437 % Tracer Lateral Diffusion 438 % ================================================================ 439 \section[Tracer lateral diffusion (\textit{traldf.F90})] 440 {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})} 441 458 \label{sec:TRA_ldf} 442 %-----------------------------------------nam_traldf------------------------------------------------------ 443 444 \nlst{namtra_ldf} 445 %------------------------------------------------------------------------------------------------------------- 446 447 Options are defined through the \ngn{namtra\_ldf} namelist variables. 448 They are regrouped in four items, allowing to specify 449 $(i)$ the type of operator used (none, laplacian, bilaplacian), 450 $(ii)$ the direction along which the operator acts (iso-level, horizontal, iso-neutral), 451 $(iii)$ some specific options related to the rotated operators (\ie non-iso-level operator), and 452 $(iv)$ the specification of eddy diffusivity coefficient (either constant or variable in space and time). 453 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}. 454 476 The direction along which the operators act is defined through the slope between 455 477 this direction and the iso-level surfaces. … … 457 479 458 480 The lateral diffusion of tracers is evaluated using a forward scheme, 459 \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, 460 482 except for the pure vertical component that appears when a rotation tensor is used. 461 This latter component is solved implicitly together with the vertical diffusion term (see \autoref{chap:STP}). 462 When \np{ln\_traldf\_msc}\forcode{ = .true.}, a Method of Stabilizing Correction is used in which 463 the pure vertical component is split into an explicit and an implicit part \citep{lemarie.debreu.ea_OM12}. 464 465 % ------------------------------------------------------------------------------------------------------------- 466 % Type of operator 467 % ------------------------------------------------------------------------------------------------------------- 468 \subsection[Type of operator (\texttt{ln\_traldf}\{\texttt{\_NONE,\_lap,\_blp}\})] 469 {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})} 470 491 \label{subsec:TRA_ldf_op} 471 492 … … 473 494 474 495 \begin{description} 475 \item[\np{ln\_traldf\_NONE}\forcode{ = .true.}:] 476 no operator selected, the lateral diffusive tendency will not be applied to the tracer equation. 477 This option can be used when the selected advection scheme is diffusive enough (MUSCL scheme for example). 478 \item[\np{ln\_traldf\_lap}\forcode{ = .true.}:] 479 a laplacian operator is selected. 480 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 $, 481 503 where the gradient operates along the selected direction (see \autoref{subsec:TRA_ldf_dir}), 482 504 and $A_{ht}$ is the eddy diffusivity coefficient expressed in $m^2/s$ (see \autoref{chap:LDF}). 483 \item[\np{ln\_traldf\_blp}\forcode{ = .true.}]: 484 a bilaplacian operator is selected. 505 \item [{\np[=.true.]{ln_traldf_blp}{ln\_traldf\_blp}}] a bilaplacian operator is selected. 485 506 This biharmonic operator takes the following expression: 486 $\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)$ 487 508 where the gradient operats along the selected direction, 488 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}). 489 511 In the code, the bilaplacian operator is obtained by calling the laplacian twice. 490 512 \end{description} … … 494 516 minimizing the impact on the larger scale features. 495 517 The main difference between the two operators is the scale selectiveness. 496 The bilaplacian damping time (\ie its spin down time) scales like $\lambda^{-4}$ for 497 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), 498 521 whereas the laplacian damping time scales only like $\lambda^{-2}$. 499 522 500 % ------------------------------------------------------------------------------------------------------------- 501 % Direction of action 502 % ------------------------------------------------------------------------------------------------------------- 503 \subsection[Action direction (\texttt{ln\_traldf}\{\texttt{\_lev,\_hor,\_iso,\_triad}\})] 504 {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})} 505 525 \label{subsec:TRA_ldf_dir} 506 526 507 527 The choice of a direction of action determines the form of operator used. 508 528 The operator is a simple (re-entrant) laplacian acting in the (\textbf{i},\textbf{j}) plane when 509 iso-level option is used (\np {ln\_traldf\_lev}\forcode{ = .true.}) or510 when a horizontal (\iegeopotential) operator is demanded in \textit{z}-coordinate511 (\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}). 512 532 The associated code can be found in the \mdl{traldf\_lap\_blp} module. 513 533 The operator is a rotated (re-entrant) laplacian when 514 534 the direction along which it acts does not coincide with the iso-level surfaces, 515 535 that is when standard or triad iso-neutral option is used 516 (\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.}, 517 537 see \mdl{traldf\_iso} or \mdl{traldf\_triad} module, resp.), or 518 when a horizontal (\ie geopotential) operator is demanded in \textit{s}-coordinate519 (\np{ln \_traldf\_hor} and \np{ln\_sco} equal \forcode{.true.})520 \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}. 521 541 In that case, a rotation is applied to the gradient(s) that appears in the operator so that 522 542 diffusive fluxes acts on the three spatial direction. … … 525 545 the next two sub-sections. 526 546 527 % ------------------------------------------------------------------------------------------------------------- 528 % iso-level operator 529 % ------------------------------------------------------------------------------------------------------------- 530 \subsection[Iso-level (bi-)laplacian operator (\texttt{ln\_traldf\_iso})] 531 {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})} 532 549 \label{subsec:TRA_ldf_lev} 533 550 534 The laplacian diffusion operator acting along the model (\textit{i,j})-surfaces is given by: 535 \begin{equation} 536 \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} 537 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] 538 555 + \delta_{j} \lt[ A_v^{lT} \; \frac{e_{1v} \, e_{3v}}{e_{2v}} \; \delta_{j + 1/2} [T] \rt] \Bigg) … … 541 558 where zero diffusive fluxes is assumed across solid boundaries, 542 559 first (and third in bilaplacian case) horizontal tracer derivative are masked. 543 It is implemented in the \rou{traldf\_lap} subroutine found in the \mdl{traldf\_lap} module. 544 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 545 563 compute the iso-level bilaplacian operator. 546 564 547 565 It is a \textit{horizontal} operator (\ie acting along geopotential surfaces) in 548 the $z$-coordinate with or without partial steps, but is simply an iso-level operator in the $s$-coordinate. 549 It is thus used when, in addition to \np{ln\_traldf\_lap} or \np{ln\_traldf\_blp}\forcode{ = .true.}, 550 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}. 551 572 In both cases, it significantly contributes to diapycnal mixing. 552 573 It is therefore never recommended, even when using it in the bilaplacian case. 553 574 554 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}), 555 576 tracers in horizontally adjacent cells are located at different depths in the vicinity of the bottom. 556 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. 557 579 They are calculated in the \mdl{zpshde} module, described in \autoref{sec:TRA_zpshde}. 558 580 559 % ------------------------------------------------------------------------------------------------------------- 560 % Rotated laplacian operator 561 % ------------------------------------------------------------------------------------------------------------- 581 %% ================================================================================================= 562 582 \subsection{Standard and triad (bi-)laplacian operator} 563 583 \label{subsec:TRA_ldf_iso_triad} 564 584 565 %&& Standard rotated (bi-)laplacian operator 566 %&& ---------------------------------------------- 567 \subsubsection[Standard rotated (bi-)laplacian operator (\textit{traldf\_iso.F90})] 568 {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})} 569 587 \label{subsec:TRA_ldf_iso} 570 The general form of the second order lateral tracer subgrid scale physics (\autoref{eq:PE_zdf}) 571 takes the following semi -discrete space form in $z$- and $s$-coordinates: 572 \begin{equation} 573 \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} 574 593 \begin{split} 575 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] … … 584 603 where $b_t = e_{1t} \, e_{2t} \, e_{3t}$ is the volume of $T$-cells, 585 604 $r_1$ and $r_2$ are the slopes between the surface of computation ($z$- or $s$-surfaces) and 586 the surface along which the diffusion operator acts (\ie horizontal or iso-neutral surfaces).587 It is thus used when, in addition to \np {ln\_traldf\_lap}\forcode{ = .true.},588 we have \np {ln\_traldf\_iso}\forcode{ = .true.},589 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}. 590 609 The way these slopes are evaluated is given in \autoref{sec:LDF_slp}. 591 At the surface, bottom and lateral boundaries, the turbulent fluxes of heat and salt are set to zero using 592 the mask technique (see \autoref{sec:LBC_coast}). 593 594 The operator in \autoref{eq:tra_ldf_iso} involves both lateral and vertical derivatives. 595 For numerical stability, the vertical second derivative must be solved using the same implicit time scheme as that 596 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}). 597 617 For computer efficiency reasons, this term is not computed in the \mdl{traldf\_iso} module, 598 618 but in the \mdl{trazdf} module where, if iso-neutral mixing is used, 599 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)$. 600 621 601 622 This formulation conserves the tracer but does not ensure the decrease of the tracer variance. 602 Nevertheless the treatment performed on the slopes (see \autoref{chap:LDF}) allows the model to run safely without 603 any additional background horizontal diffusion \citep{guilyardi.madec.ea_CD01}. 604 605 Note that in the partial step $z$-coordinate (\np{ln\_zps}\forcode{ = .true.}), 606 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. 607 629 They are calculated in module zpshde, described in \autoref{sec:TRA_zpshde}. 608 630 609 %&& Triad rotated (bi-)laplacian operator 610 %&& ------------------------------------------- 611 \subsubsection[Triad rotated (bi-)laplacian operator (\textit{ln\_traldf\_triad})] 612 {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})} 613 633 \label{subsec:TRA_ldf_triad} 614 634 615 If the Griffies triad scheme is employed (\np{ln\_traldf\_triad}\forcode{ = .true.}; see \autoref{apdx:triad}) 616 617 An alternative scheme developed by \cite{griffies.gnanadesikan.ea_JPO98} which ensures tracer variance decreases 618 is also available in \NEMO (\np{ln\_traldf\_grif}\forcode{ = .true.}).619 A complete description of the algorithm is given in \autoref{apdx:triad}. 620 621 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. 622 642 The operator requires an additional assumption on boundary conditions: 623 643 both first and third derivative terms normal to the coast are set to zero. 624 644 625 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. 626 647 It requires an additional assumption on boundary conditions: 627 648 first and third derivative terms normal to the coast, 628 649 normal to the bottom and normal to the surface are set to zero. 629 650 630 %&& Option for the rotated operators 631 %&& ---------------------------------------------- 651 %% ================================================================================================= 632 652 \subsubsection{Option for the rotated operators} 633 653 \label{subsec:TRA_ldf_options} 634 654 635 \begin{itemize} 636 \item \np{ln\_traldf\_msc} = Method of Stabilizing Correction (both operators) 637 \item \np{rn\_slpmax} = slope limit (both operators) 638 \item \np{ln\_triad\_iso} = pure horizontal mixing in ML (triad only) 639 \item \np{rn\_sw\_triad} $= 1$ switching triad; $= 0$ all 4 triads used (triad only) 640 \item \np{ln\_botmix\_triad} = lateral mixing on bottom (triad only) 641 \end{itemize} 642 643 % ================================================================ 644 % Tracer Vertical Diffusion 645 % ================================================================ 646 \section[Tracer vertical diffusion (\textit{trazdf.F90})] 647 {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})} 648 666 \label{sec:TRA_zdf} 649 %--------------------------------------------namzdf--------------------------------------------------------- 650 651 \nlst{namzdf} 652 %-------------------------------------------------------------------------------------------------------------- 653 654 Options are defined through the \ngn{namzdf} namelist variables. 655 The formulation of the vertical subgrid scale tracer physics is the same for all the vertical coordinates, 656 and is based on a laplacian operator. 657 The vertical diffusion operator given by (\autoref{eq:PE_zdf}) takes the following semi -discrete space form: 658 \begin{gather*} 659 % \label{eq:tra_zdf} 660 D^{vT}_T = \frac{1}{e_{3t}} \, \delta_k \lt[ \, \frac{A^{vT}_w}{e_{3w}} \delta_{k + 1/2}[T] \, \rt] \\ 661 D^{vS}_T = \frac{1}{e_{3t}} \; \delta_k \lt[ \, \frac{A^{vS}_w}{e_{3w}} \delta_{k + 1/2}[S] \, \rt] 662 \end{gather*} 663 where $A_w^{vT}$ and $A_w^{vS}$ are the vertical eddy diffusivity coefficients on temperature and salinity, 664 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. 665 680 Generally, $A_w^{vT} = A_w^{vS}$ except when double diffusive mixing is parameterised 666 (\ie \key{zdfddm} is defined).681 (\ie\ \np[=.true.]{ln_zdfddm}{ln\_zdfddm},). 667 682 The way these coefficients are evaluated is given in \autoref{chap:ZDF} (ZDF). 668 Furthermore, when iso-neutral mixing is used, both mixing coefficients are increased by669 $\frac{e_{1w} e_{2w}}{e_{3w} }({r_{1w}^2 + r_{2w}^2})$ to account for the vertical second derivative of 670 \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}. 671 686 672 687 At the surface and bottom boundaries, the turbulent fluxes of heat and salt must be specified. … … 675 690 a geothermal flux forcing is prescribed as a bottom boundary condition (see \autoref{subsec:TRA_bbc}). 676 691 677 The large eddy coefficient found in the mixed layer together with high vertical resolution implies that 678 in the case of explicit time stepping (\np{ln\_zdfexp}\forcode{ = .true.}) 679 there would be too restrictive a constraint on the time step. 680 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 681 695 it overcomes the stability constraint. 682 A forward time differencing scheme (\np{ln\_zdfexp}\forcode{ = .true.}) using 683 a time splitting technique (\np{nn\_zdfexp} $> 1$) is provided as an alternative. 684 Namelist variables \np{ln\_zdfexp} and \np{nn\_zdfexp} apply to both tracers and dynamics. 685 686 % ================================================================ 687 % External Forcing 688 % ================================================================ 696 697 %% ================================================================================================= 689 698 \section{External forcing} 690 699 \label{sec:TRA_sbc_qsr_bbc} 691 700 692 % ------------------------------------------------------------------------------------------------------------- 693 % surface boundary condition 694 % ------------------------------------------------------------------------------------------------------------- 695 \subsection[Surface boundary condition (\textit{trasbc.F90})] 696 {Surface boundary condition (\protect\mdl{trasbc})} 701 %% ================================================================================================= 702 \subsection[Surface boundary condition (\textit{trasbc.F90})]{Surface boundary condition (\protect\mdl{trasbc})} 697 703 \label{subsec:TRA_sbc} 698 704 … … 704 710 705 711 Due to interactions and mass exchange of water ($F_{mass}$) with other Earth system components 706 (\ie atmosphere, sea-ice, land), the change in the heat and salt content of the surface layer of the ocean is due 707 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 708 715 to the heat and salt content of the mass exchange. 709 716 They are both included directly in $Q_{ns}$, the surface heat flux, 710 717 and $F_{salt}$, the surface salt flux (see \autoref{chap:SBC} for further details). 711 By doing this, the forcing formulation is the same for any tracer (including temperature and salinity). 712 713 The surface module (\mdl{sbcmod}, see \autoref{chap:SBC}) provides the following forcing fields (used on tracers): 714 715 \begin{itemize} 716 \item 717 $Q_{ns}$, the non-solar part of the net surface heat flux that crosses the sea surface 718 (\ie the difference between the total surface heat flux and the fraction of the short wave flux that 719 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}) 720 729 plus the heat content associated with of the mass exchange with the atmosphere and lands. 721 \item 722 $\textit{sfx}$, the salt flux resulting from ice-ocean mass exchange (freezing, melting, ridging...) 723 \item 724 \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 725 733 possibly with the sea-ice and ice-shelves. 726 \item 727 \textit{rnf}, the mass flux associated with runoff 734 \item [\textit{rnf}] The mass flux associated with runoff 728 735 (see \autoref{sec:SBC_rnf} for further detail of how it acts on temperature and salinity tendencies) 729 \item 730 \textit{fwfisf}, the mass flux associated with ice shelf melt, 736 \item [\textit{fwfisf}] The mass flux associated with ice shelf melt, 731 737 (see \autoref{sec:SBC_isf} for further details on how the ice shelf melt is computed and applied). 732 \end{ itemize}738 \end{labeling} 733 739 734 740 The surface boundary condition on temperature and salinity is applied as follows: 735 741 \begin{equation} 736 \label{eq:tra_sbc} 737 \begin{alignedat}{2} 738 F^T &= \frac{1}{C_p} &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} &\overline{Q_{ns} }^t \\ 739 F^S &= &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} &\overline{\textit{sfx}}^t 740 \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 741 745 \end{equation} 742 746 where $\overline x^t$ means that $x$ is averaged over two consecutive time steps 743 747 ($t - \rdt / 2$ and $t + \rdt / 2$). 744 Such time averaging prevents the divergence of odd and even time step (see \autoref{chap:STP}). 745 746 In the linear free surface case (\np{ln\_linssh}\forcode{ = .true.}), an additional term has to be added on 747 both temperature and salinity. 748 On temperature, this term remove the heat content associated with mass exchange that has been added to $Q_{ns}$. 749 On salinity, this term mimics the concentration/dilution effect that would have resulted from a change in 750 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. 751 756 The resulting surface boundary condition is applied as follows: 752 757 \begin{equation} 753 \label{eq:tra_sbc_lin} 754 \begin{alignedat}{2} 755 F^T &= \frac{1}{C_p} &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} 756 &\overline{(Q_{ns} - C_p \, \textit{emp} \lt. T \rt|_{k = 1})}^t \\ 757 F^S &= &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} 758 &\overline{(\textit{sfx} - \textit{emp} \lt. S \rt|_{k = 1})}^t 759 \end{alignedat} 760 \end{equation} 761 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. 762 766 In the linear free surface case, there is a small imbalance. 763 The imbalance is larger than the imbalance associated with the Asselin time filter \citep{leclair.madec_OM09}. 764 This is the reason why the modified filter is not applied in the linear free surface case (see \autoref{chap:STP}). 765 766 % ------------------------------------------------------------------------------------------------------------- 767 % Solar Radiation Penetration 768 % ------------------------------------------------------------------------------------------------------------- 769 \subsection[Solar radiation penetration (\textit{traqsr.F90})] 770 {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})} 771 774 \label{subsec:TRA_qsr} 772 %--------------------------------------------namqsr-------------------------------------------------------- 773 774 \nlst{namtra_qsr} 775 %-------------------------------------------------------------------------------------------------------------- 776 777 Options are defined through the \ngn{namtra\_qsr} namelist variables. 778 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}), 779 784 the solar radiation penetrates the top few tens of meters of the ocean. 780 If it is not used (\np{ln\_flxqsr}\forcode{ = .false.}) all the heat flux is absorbed in the first ocean level. 781 Thus, in the former case a term is added to the time evolution equation of temperature \autoref{eq:PE_tra_T} and 782 the surface boundary condition is modified to take into account only the non-penetrative part of the surface 783 heat flux: 784 \begin{equation} 785 \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} 786 792 \begin{gathered} 787 793 \pd[T]{t} = \ldots + \frac{1}{\rho_o \, C_p \, e_3} \; \pd[I]{k} \\ … … 789 795 \end{gathered} 790 796 \end{equation} 791 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 792 798 $I$ is the downward irradiance ($\lt. I \rt|_{z = \eta} = Q_{sr}$). 793 The additional term in \autoref{eq: PE_qsr} is discretized as follows:794 \begin{equation} 795 \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} 796 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] 797 803 \end{equation} 798 804 799 805 The shortwave radiation, $Q_{sr}$, consists of energy distributed across a wide spectral range. 800 The ocean is strongly absorbing for wavelengths longer than 700~nm and these wavelengths contribute to 801 heating the upper few tens of centimetres. 802 The fraction of $Q_{sr}$ that resides in these almost non-penetrative wavebands, $R$, is $\sim 58\%$ 803 (specified through namelist parameter \np{rn\_abs}). 804 It is assumed to penetrate the ocean with a decreasing exponential profile, with an e-folding depth scale, $\xi_0$, 805 of a few tens of centimetres (typically $\xi_0 = 0.35~m$ set as \np{rn\_si0} in the \ngn{namtra\_qsr} namelist). 806 For shorter wavelengths (400-700~nm), the ocean is more transparent, and solar energy propagates to 807 larger depths where it contributes to local heating. 808 The way this second part of the solar energy penetrates into the ocean depends on which formulation is chosen. 809 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}) 810 818 a chlorophyll-independent monochromatic formulation is chosen for the shorter wavelengths, 811 819 leading to the following expression \citep{paulson.simpson_JPO77}: 812 820 \[ 813 % \label{eq: traqsr_iradiance}821 % \label{eq:TRA_qsr_iradiance} 814 822 I(z) = Q_{sr} \lt[ Re^{- z / \xi_0} + (1 - R) e^{- z / \xi_1} \rt] 815 823 \] 816 824 where $\xi_1$ is the second extinction length scale associated with the shorter wavelengths. 817 It is usually chosen to be 23~m by setting the \np{rn \_si0} namelist parameter.818 The set of default values ($\xi_0, \xi_1, R$) corresponds to a Type I water in Jerlov's (1968) classification819 (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). 820 828 821 829 Such assumptions have been shown to provide a very crude and simplistic representation of 822 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}). 823 831 Light absorption in the ocean depends on particle concentration and is spectrally selective. 824 832 \cite{morel_JGR88} has shown that an accurate representation of light penetration can be provided by 825 833 a 61 waveband formulation. 826 834 Unfortunately, such a model is very computationally expensive. 827 Thus, \cite{lengaigne.menkes.ea_CD07} have constructed a simplified version of this formulation in which 828 visible light is split into three wavebands: blue (400-500 nm), green (500-600 nm) and red (600-700nm). 829 For each wave-band, the chlorophyll-dependent attenuation coefficient is fitted to the coefficients computed from 830 the full spectral model of \cite{morel_JGR88} (as modified by \cite{morel.maritorena_JGR01}), 831 assuming the same power-law relationship. 832 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), 833 843 reproduces quite closely the light penetration profiles predicted by the full spectal model, 834 844 but with much greater computational efficiency. 835 845 The 2-bands formulation does not reproduce the full model very well. 836 846 837 The RGB formulation is used when \np {ln\_qsr\_rgb}\forcode{ = .true.}.838 The RGB attenuation coefficients (\ie the inverses of the extinction length scales) are tabulated over839 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$ 840 850 (see the routine \rou{trc\_oce\_rgb} in \mdl{trc\_oce} module). 841 851 Four types of chlorophyll can be chosen in the RGB formulation: 842 852 843 853 \begin{description} 844 \item[\np{nn\_chdta}\forcode{ = 0}] 845 a constant 0.05 g.Chl/L value everywhere ; 846 \item[\np{nn\_chdta}\forcode{ = 1}] 847 an observed time varying chlorophyll deduced from satellite surface ocean color measurement spread uniformly in 848 the vertical direction; 849 \item[\np{nn\_chdta}\forcode{ = 2}] 850 same as previous case except that a vertical profile of chlorophyl is used. 851 Following \cite{morel.berthon_LO89}, the profile is computed from the local surface chlorophyll value; 852 \item[\np{ln\_qsr\_bio}\forcode{ = .true.}] 853 simulated time varying chlorophyll by TOP biogeochemical model. 854 In this case, the RGB formulation is used to calculate both the phytoplankton light limitation in 855 PISCES or LOBSTER and the oceanic heating rate. 856 \end{description} 857 858 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 859 868 the temperature trend, and the surface heat flux is modified in routine \mdl{traqsr}. 860 869 … … 862 871 the depth of $w-$levels does not significantly vary with location. 863 872 The level at which the light has been totally absorbed 864 (\ie it is less than the computer precision) is computed once,873 (\ie\ it is less than the computer precision) is computed once, 865 874 and the trend associated with the penetration of the solar radiation is only added down to that level. 866 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. 867 877 In this case, we have chosen that all remaining radiation is absorbed in the last ocean level 868 (\ie $I$ is masked). 869 870 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 871 \begin{figure}[!t] 872 \begin{center} 873 \includegraphics[width=\textwidth]{Fig_TRA_Irradiance} 874 \caption{ 875 \protect\label{fig:traqsr_irradiance} 876 Penetration profile of the downward solar irradiance calculated by four models. 877 Two waveband chlorophyll-independent formulation (blue), 878 a chlorophyll-dependent monochromatic formulation (green), 879 4 waveband RGB formulation (red), 880 61 waveband Morel (1988) formulation (black) for a chlorophyll concentration of 881 (a) Chl=0.05 mg/m$^3$ and (b) Chl=0.5 mg/m$^3$. 882 From \citet{lengaigne.menkes.ea_CD07}. 883 } 884 \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} 885 892 \end{figure} 886 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 887 888 % ------------------------------------------------------------------------------------------------------------- 889 % Bottom Boundary Condition 890 % ------------------------------------------------------------------------------------------------------------- 891 \subsection[Bottom boundary condition (\textit{trabbc.F90})] 892 {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})} 893 896 \label{subsec:TRA_bbc} 894 %--------------------------------------------nambbc-------------------------------------------------------- 895 896 \nlst{nambbc}897 %-------------------------------------------------------------------------------------------------------------- 898 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 899 \ begin{figure}[!t]900 \begin{center} 901 \includegraphics[width=\textwidth]{Fig_TRA_geoth}902 \caption{903 \protect\label{fig:geothermal}904 Geothermal Heat flux (in $mW.m^{-2}$) used by \cite{emile-geay.madec_OS09}.905 It is inferred from the age of the sea floor and the formulae of \citet{stein.stein_N92}.906 }907 \ 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} 908 911 \end{figure} 909 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>910 912 911 913 Usually it is assumed that there is no exchange of heat or salt through the ocean bottom, 912 \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. 913 915 This is the default option in \NEMO, and it is implemented using the masking technique. 914 However, there is a non-zero heat flux across the seafloor that is associated with solid earth cooling. 915 This flux is weak compared to surface fluxes (a mean global value of $\sim 0.1 \, W/m^2$ \citep{stein.stein_N92}), 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}), 916 920 but it warms systematically the ocean and acts on the densest water masses. 917 921 Taking this flux into account in a global ocean model increases the deepest overturning cell 918 (\ie the one associated with the Antarctic Bottom Water) by a few Sverdrups \citep{emile-geay.madec_OS09}. 919 920 Options are defined through the \ngn{namtra\_bbc} namelist variables. 921 The presence of geothermal heating is controlled by setting the namelist parameter \np{ln\_trabbc} to true. 922 Then, when \np{nn\_geoflx} is set to 1, a constant geothermal heating is introduced whose value is given by 923 the \np{nn\_geoflx\_cst}, which is also a namelist parameter. 924 When \np{nn\_geoflx} is set to 2, a spatially varying geothermal heat flux is introduced which is provided in 925 the \ifile{geothermal\_heating} NetCDF file (\autoref{fig:geothermal}) \citep{emile-geay.madec_OS09}. 926 927 % ================================================================ 928 % Bottom Boundary Layer 929 % ================================================================ 930 \section[Bottom boundary layer (\textit{trabbl.F90} - \texttt{\textbf{key\_trabbl}})] 931 {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})} 932 937 \label{sec:TRA_bbl} 933 %--------------------------------------------nambbl--------------------------------------------------------- 934 935 \nlst{nambbl} 936 %-------------------------------------------------------------------------------------------------------------- 937 938 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. 939 946 In a $z$-coordinate configuration, the bottom topography is represented by a series of discrete steps. 940 947 This is not adequate to represent gravity driven downslope flows. … … 942 949 where dense water formed in marginal seas flows into a basin filled with less dense water, 943 950 or along the continental slope when dense water masses are formed on a continental shelf. 944 The amount of entrainment that occurs in these gravity plumes is critical in determining the density and 945 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. 946 954 $z$-coordinate models tend to overestimate the entrainment, 947 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, 948 957 sometimes over a thickness much larger than the thickness of the observed gravity plume. 949 A similar problem occurs in the $s$-coordinate when the thickness of the bottom level varies rapidly downstream of 950 a sill \citep{willebrand.barnier.ea_PO01}, and the thickness of the plume is not resolved. 951 952 The idea of the bottom boundary layer (BBL) parameterisation, first introduced by \citet{beckmann.doscher_JPO97}, 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}, 953 964 is to allow a direct communication between two adjacent bottom cells at different levels, 954 965 whenever the densest water is located above the less dense water. 955 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. 956 968 In the current implementation of the BBL, only the tracers are modified, not the velocities. 957 Furthermore, it only connects ocean bottom cells, and therefore does not include all the improvements introduced by 958 \citet{campin.goosse_T99}. 959 960 % ------------------------------------------------------------------------------------------------------------- 961 % Diffusive BBL 962 % ------------------------------------------------------------------------------------------------------------- 963 \subsection[Diffusive bottom boundary layer (\forcode{nn_bbl_ldf = 1})] 964 {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})} 965 974 \label{subsec:TRA_bbl_diff} 966 975 967 When applying sigma-diffusion (\key{trabbl} defined and \np{nn\_bbl\_ldf} set to 1), 968 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 969 979 \[ 970 % \label{eq: tra_bbl_diff}980 % \label{eq:TRA_bbl_diff} 971 981 \vect F_\sigma = A_l^\sigma \, \nabla_\sigma T 972 982 \] 973 with $\nabla_\sigma$ the lateral gradient operator taken between bottom cells, and974 $A_l^\sigma$ the lateral diffusivity in the BBL.983 with $\nabla_\sigma$ the lateral gradient operator taken between bottom cells, 984 and $A_l^\sigma$ the lateral diffusivity in the BBL. 975 985 Following \citet{beckmann.doscher_JPO97}, the latter is prescribed with a spatial dependence, 976 \ie in the conditional form977 \begin{equation} 978 \label{eq: tra_bbl_coef}986 \ie\ in the conditional form 987 \begin{equation} 988 \label{eq:TRA_bbl_coef} 979 989 A_l^\sigma (i,j,t) = 980 990 \begin{cases} 981 991 A_{bbl} & \text{if~} \nabla_\sigma \rho \cdot \nabla H < 0 \\ 982 \\ 983 0 & \text{otherwise} \\ 992 0 & \text{otherwise} 984 993 \end{cases} 985 994 \end{equation} 986 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 987 997 usually set to a value much larger than the one used for lateral mixing in the open ocean. 988 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 989 999 the density above the sea floor, at the top of the slope, is larger than in the deeper ocean 990 (see green arrow in \autoref{fig: bbl}).1000 (see green arrow in \autoref{fig:TRA_bbl}). 991 1001 In practice, this constraint is applied separately in the two horizontal directions, 992 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: 993 1003 \[ 994 % \label{eq: tra_bbl_Drho}1004 % \label{eq:TRA_bbl_Drho} 995 1005 \nabla_\sigma \rho / \rho = \alpha \, \nabla_\sigma T + \beta \, \nabla_\sigma S 996 1006 \] 997 where $\rho$, $\alpha$ and $\beta$ are functions of $\overline T^\sigma$, $\overline S^\sigma$ and 998 $\overline H^\sigma$, the along bottom mean temperature, salinity and depth, respectively. 999 1000 % ------------------------------------------------------------------------------------------------------------- 1001 % Advective BBL 1002 % ------------------------------------------------------------------------------------------------------------- 1003 \subsection[Advective bottom boundary layer (\forcode{nn_bbl_adv = [12]})] 1004 {Advective bottom boundary layer (\protect\np{nn\_bbl\_adv}\forcode{ = [12]})} 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})} 1005 1013 \label{subsec:TRA_bbl_adv} 1006 1014 … … 1010 1018 %} 1011 1019 1012 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1013 \begin{figure}[!t] 1014 \begin{center} 1015 \includegraphics[width=\textwidth]{Fig_BBL_adv} 1016 \caption{ 1017 \protect\label{fig:bbl} 1018 Advective/diffusive Bottom Boundary Layer. 1019 The BBL parameterisation is activated when $\rho^i_{kup}$ is larger than $\rho^{i + 1}_{kdnw}$. 1020 Red arrows indicate the additional overturning circulation due to the advective BBL. 1021 The transport of the downslope flow is defined either as the transport of the bottom ocean cell (black arrow), 1022 or as a function of the along slope density gradient. 1023 The green arrow indicates the diffusive BBL flux directly connecting $kup$ and $kdwn$ ocean bottom cells. 1024 } 1025 \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} 1026 1033 \end{figure} 1027 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>1028 1034 1029 1035 %!! nn_bbl_adv = 1 use of the ocean velocity as bbl velocity … … 1031 1037 %!! i.e. transport proportional to the along-slope density gradient 1032 1038 1033 %%%gmcomment : this section has to be really written 1034 1035 When applying an advective BBL (\np{nn\_bbl\_adv}\forcode{ = 1..2}), an overturning circulation is added which 1036 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. 1037 1044 The density difference causes dense water to move down the slope. 1038 1045 1039 \np{nn\_bbl\_adv}\forcode{ = 1}: 1040 the downslope velocity is chosen to be the Eulerian ocean velocity just above the topographic step 1041 (see black arrow in \autoref{fig:bbl}) \citep{beckmann.doscher_JPO97}. 1042 It is a \textit{conditional advection}, that is, advection is allowed only 1043 if dense water overlies less dense water on the slope (\ie $\nabla_\sigma \rho \cdot \nabla H < 0$) and 1044 if the velocity is directed towards greater depth (\ie $\vect U \cdot \nabla H > 0$). 1045 1046 \np{nn\_bbl\_adv}\forcode{ = 2}: 1047 the downslope velocity is chosen to be proportional to $\Delta \rho$, 1048 the density difference between the higher cell and lower cell densities \citep{campin.goosse_T99}. 1049 The advection is allowed only if dense water overlies less dense water on the slope 1050 (\ie $\nabla_\sigma \rho \cdot \nabla H < 0$). 1051 For example, the resulting transport of the downslope flow, here in the $i$-direction (\autoref{fig:bbl}), 1052 is simply given by the following expression: 1053 \[ 1054 % \label{eq:bbl_Utr} 1055 u^{tr}_{bbl} = \gamma g \frac{\Delta \rho}{\rho_o} e_{1u} \, min ({e_{3u}}_{kup},{e_{3u}}_{kdwn}) 1056 \] 1057 where $\gamma$, expressed in seconds, is the coefficient of proportionality provided as \np{rn\_gambbl}, 1058 a namelist parameter, and \textit{kup} and \textit{kdwn} are the vertical index of the higher and lower cells, 1059 respectively. 1060 The parameter $\gamma$ should take a different value for each bathymetric step, but for simplicity, 1061 and because no direct estimation of this parameter is available, a uniform value has been assumed. 1062 The possible values for $\gamma$ range between 1 and $10~s$ \citep{campin.goosse_T99}. 1063 1064 Scalar properties are advected by this additional transport $(u^{tr}_{bbl},v^{tr}_{bbl})$ using the upwind scheme. 1065 Such a diffusive advective scheme has been chosen to mimic the entrainment between the downslope plume and 1066 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. 1067 1077 The entrainment is replaced by the vertical mixing implicit in the advection scheme. 1068 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 1069 1079 the density at level $(i,kup)$ is larger than the one at level $(i,kdwn)$. 1070 The advective BBL scheme modifies the tracer time tendency of the ocean cells near the topographic step by 1071 the downslope flow \autoref{eq:bbl_dw}, the horizontal \autoref{eq:bbl_hor} and 1072 the upward \autoref{eq:bbl_up} return flows as follows: 1073 \begin{alignat}{3} 1074 \label{eq:bbl_dw} 1075 \partial_t T^{do}_{kdw} &\equiv \partial_t T^{do}_{kdw} 1076 &&+ \frac{u^{tr}_{bbl}}{{b_t}^{do}_{kdw}} &&\lt( T^{sh}_{kup} - T^{do}_{kdw} \rt) \\ 1077 \label{eq:bbl_hor} 1078 \partial_t T^{sh}_{kup} &\equiv \partial_t T^{sh}_{kup} 1079 &&+ \frac{u^{tr}_{bbl}}{{b_t}^{sh}_{kup}} &&\lt( T^{do}_{kup} - T^{sh}_{kup} \rt) \\ 1080 % 1081 \intertext{and for $k =kdw-1,\;..., \; kup$ :} 1082 % 1083 \label{eq:bbl_up} 1084 \partial_t T^{do}_{k} &\equiv \partial_t S^{do}_{k} 1085 &&+ \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) 1086 1091 \end{alignat} 1087 1092 where $b_t$ is the $T$-cell volume. … … 1090 1095 It has to be used to compute the effective velocity as well as the effective overturning circulation. 1091 1096 1092 % ================================================================ 1093 % Tracer damping 1094 % ================================================================ 1095 \section[Tracer damping (\textit{tradmp.F90})] 1096 {Tracer damping (\protect\mdl{tradmp})} 1097 %% ================================================================================================= 1098 \section[Tracer damping (\textit{tradmp.F90})]{Tracer damping (\protect\mdl{tradmp})} 1097 1099 \label{sec:TRA_dmp} 1098 %--------------------------------------------namtra_dmp------------------------------------------------- 1099 1100 \nlst{namtra_dmp} 1101 %-------------------------------------------------------------------------------------------------------------- 1102 1103 In some applications it can be useful to add a Newtonian damping term into the temperature and salinity equations: 1104 \begin{equation} 1105 \label{eq:tra_dmp} 1106 \begin{gathered} 1107 \pd[T]{t} = \cdots - \gamma (T - T_o) \\ 1108 \pd[S]{t} = \cdots - \gamma (S - S_o) 1109 \end{gathered} 1110 \end{equation} 1111 where $\gamma$ is the inverse of a time scale, and $T_o$ and $S_o$ are given temperature and salinity fields 1112 (usually a climatology). 1113 Options are defined through the \ngn{namtra\_dmp} namelist variables. 1114 The restoring term is added when the namelist parameter \np{ln\_tradmp} is set to true. 1115 It also requires that both \np{ln\_tsd\_init} and \np{ln\_tsd\_tradmp} are set to true in 1116 \ngn{namtsd} namelist as well as \np{sn\_tem} and \np{sn\_sal} structures are correctly set 1117 (\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}, 1118 1121 see \autoref{subsec:SBC_fldread}). 1119 The restoring coefficient $\gamma$ is a three-dimensional array read in during the \rou{tra\_dmp\_init} routine. 1120 The file name is specified by the namelist variable \np{cn\_resto}. 1121 The DMP\_TOOLS tool is provided to allow users to generate the netcdf file. 1122 1123 The two main cases in which \autoref{eq:tra_dmp} is used are 1124 \textit{(a)} the specification of the boundary conditions along artificial walls of a limited domain basin and 1125 \textit{(b)} the computation of the velocity field associated with a given $T$-$S$ field 1126 (for example to build the initial state of a prognostic simulation, 1127 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*} 1128 1135 The first case applies to regional models that have artificial walls instead of open boundaries. 1129 In the vicinity of these walls, $\gamma$ takes large values (equivalent to a time scale of a few days) whereas1130 it is zero in the interior of the model domain.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. 1131 1138 The second case corresponds to the use of the robust diagnostic method \citep{sarmiento.bryan_JGR82}. 1132 1139 It allows us to find the velocity field consistent with the model dynamics whilst 1133 1140 having a $T$, $S$ field close to a given climatological field ($T_o$, $S_o$). 1134 1141 1135 The robust diagnostic method is very efficient in preventing temperature drift in intermediate waters but1136 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. 1137 1144 It also has undesirable effects on the ocean convection. 1138 It tends to prevent deep convection and subsequent deep-water formation, by stabilising the water column too much. 1139 1140 The namelist parameter \np{nn\_zdmp} sets whether the damping should be applied in the whole water column or 1141 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). 1142 1150 It is common to set the damping to zero in the mixed layer as the adjustment time scale is short here 1143 1151 \citep{madec.delecluse.ea_JPO96}. 1144 1152 1145 For generating \ifile{resto}, see the documentation for the DMP tool provided with the source code under 1146 \path{./tools/DMP_TOOLS}. 1147 1148 % ================================================================ 1149 % Tracer time evolution 1150 % ================================================================ 1151 \section[Tracer time evolution (\textit{tranxt.F90})] 1152 {Tracer time evolution (\protect\mdl{tranxt})} 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})} 1153 1158 \label{sec:TRA_nxt} 1154 %--------------------------------------------namdom----------------------------------------------------- 1155 1156 \nlst{namdom} 1157 %-------------------------------------------------------------------------------------------------------------- 1158 1159 Options are defined through the \ngn{namdom} namelist variables. 1160 The general framework for tracer time stepping is a modified leap-frog scheme \citep{leclair.madec_OM09}, 1161 \ie a three level centred time scheme associated with a Asselin time filter (cf. \autoref{sec:STP_mLF}): 1162 \begin{equation} 1163 \label{eq:tra_nxt} 1164 \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} 1165 1167 &(e_{3t}T)^{t + \rdt} &&= (e_{3t}T)_f^{t - \rdt} &&+ 2 \, \rdt \,e_{3t}^t \ \text{RHS}^t \\ 1166 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] \\ 1167 & && &&- \, \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] 1168 1170 \end{alignedat} 1169 \end{equation} 1170 where RHS is the right hand side of the temperature equation, the subscript $f$ denotes filtered values, 1171 $\gamma$ is the Asselin coefficient, and $S$ is the total forcing applied on $T$ 1172 (\ie fluxes plus content in mass exchanges). 1173 $\gamma$ is initialized as \np{rn\_atfp} (\textbf{namelist} parameter). 1174 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}. 1175 1176 Note that the forcing correction term in the filter is not applied in linear free surface 1176 (\jp{lk\_vvl}\forcode{ = .false.}) (see \autoref{subsec:TRA_sbc}). 1177 Not also that in constant volume case, the time stepping is performed on $T$, not on its content, $e_{3t}T$. 1178 1179 When the vertical mixing is solved implicitly, the update of the \textit{next} tracer fields is done in 1180 \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. 1181 1183 In this case only the swapping of arrays and the Asselin filtering is done in the \mdl{tranxt} module. 1182 1184 1183 In order to prepare for the computation of the \textit{next} time step, a swap of tracer arrays is performed: 1184 $T^{t - \rdt} = T^t$ and $T^t = T_f$. 1185 1186 % ================================================================ 1187 % Equation of State (eosbn2) 1188 % ================================================================ 1189 \section[Equation of state (\textit{eosbn2.F90})] 1190 {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})} 1191 1190 \label{sec:TRA_eosbn2} 1192 %--------------------------------------------nameos----------------------------------------------------- 1193 1194 \nlst{nameos} 1195 %-------------------------------------------------------------------------------------------------------------- 1196 1197 % ------------------------------------------------------------------------------------------------------------- 1198 % Equation of State 1199 % ------------------------------------------------------------------------------------------------------------- 1200 \subsection[Equation of seawater (\forcode{nn_eos = {-1,1}})] 1201 {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})} 1202 1200 \label{subsec:TRA_eos} 1203 1201 1204 The Equation Of Seawater (EOS) is an empirical nonlinear thermodynamic relationship linking seawater density, 1205 $\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. 1206 1206 Because density gradients control the pressure gradient force through the hydrostatic balance, 1207 the equation of state provides a fundamental bridge between the distribution of active tracers and1208 the fluid dynamics.1207 the equation of state provides a fundamental bridge between 1208 the distribution of active tracers and the fluid dynamics. 1209 1209 Nonlinearities of the EOS are of major importance, in particular influencing the circulation through 1210 1210 determination of the static stability below the mixed layer, 1211 thus controlling rates of exchange between the atmosphere and the ocean interior \citep{roquet.madec.ea_JPO15}. 1212 Therefore an accurate EOS based on either the 1980 equation of state (EOS-80, \cite{fofonoff.millard_bk83}) or 1213 TEOS-10 \citep{ioc.iapso_bk10} standards should be used anytime a simulation of the real ocean circulation is attempted 1211 thus controlling rates of exchange between the atmosphere and the ocean interior 1214 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}. 1215 1216 The use of TEOS-10 is highly recommended because 1216 \textit{(i)} it is the new official EOS, 1217 \textit{(ii)} it is more accurate, being based on an updated database of laboratory measurements, and 1218 \textit{(iii)} it uses Conservative Temperature and Absolute Salinity (instead of potential temperature and 1219 practical salinity for EOS-980, both variables being more suitable for use as model variables 1220 \citep{ioc.iapso_bk10, graham.mcdougall_JPO13}. 1221 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. 1222 1226 For process studies, it is often convenient to use an approximation of the EOS. 1223 1227 To that purposed, a simplified EOS (S-EOS) inspired by \citet{vallis_bk06} is also available. 1224 1228 1225 In the computer code, a density anomaly, $d_a = \rho / \rho_o - 1$, is computed, with $\rho_o$ a reference density. 1226 Called \textit{rau0} in the code, $\rho_o$ is set in \mdl{phycst} to a value of $1,026~Kg/m^3$. 1227 This is a sensible choice for the reference density used in a Boussinesq ocean climate model, as, 1228 with the exception of only a small percentage of the ocean, 1229 density in the World Ocean varies by no more than 2$\%$ from that value \citep{gill_bk82}. 1230 1231 Options are defined through the \ngn{nameos} namelist variables, and in particular \np{nn\_eos} which 1232 controls the EOS used (\forcode{= -1} for TEOS10 ; \forcode{= 0} for EOS-80 ; \forcode{= 1} for S-EOS). 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. 1233 1238 1234 1239 \begin{description} 1235 \item [\np{nn\_eos}\forcode{ = -1}]1236 the polyTEOS10-bsq equation of seawater\citep{roquet.madec.ea_OM15} is used.1240 \item [{\np[=.true.]{ln_teos10}{ln\_teos10}}] the polyTEOS10-bsq equation of seawater 1241 \citep{roquet.madec.ea_OM15} is used. 1237 1242 The accuracy of this approximation is comparable to the TEOS-10 rational function approximation, 1238 but it is optimized for a boussinesq fluid and the polynomial expressions have simpler and 1239 more computationally efficient expressions for their derived quantities which make them more adapted for 1240 use in ocean models. 1241 Note that a slightly higher precision polynomial form is now used replacement of 1242 the TEOS-10 rational function approximation for hydrographic data analysis \citep{ioc.iapso_bk10}. 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}. 1243 1249 A key point is that conservative state variables are used: 1244 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$). 1245 1252 The pressure in decibars is approximated by the depth in meters. 1246 1253 With TEOS10, the specific heat capacity of sea water, $C_p$, is a constant. 1247 It is set to $C_p = 3991.86795711963~J\,Kg^{-1}\,^{\circ}K^{-1}$, according to \citet{ioc.iapso_bk10}. 1254 It is set to $C_p$ = 3991.86795711963 $J.Kg^{-1}.\deg{K}^{-1}$, 1255 according to \citet{ioc.iapso_bk10}. 1248 1256 Choosing polyTEOS10-bsq implies that the state variables used by the model are $\Theta$ and $S_A$. 1249 In particular, the initial state de ined by the user have to be given as \textit{Conservative} Temperature and1250 \textit{ Absolute} Salinity.1251 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 1252 1260 either computing the air-sea and ice-sea fluxes (forced mode) or 1253 1261 sending the SST field to the atmosphere (coupled mode). 1254 \item[\np{nn\_eos}\forcode{ = 0}] 1255 the polyEOS80-bsq equation of seawater is used. 1256 It takes the same polynomial form as the polyTEOS10, but the coefficients have been optimized to 1257 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.). 1258 1265 The state variables used in both the EOS80 and the ocean model are: 1259 the Practical Salinity ( (unit: psu, notation: $S_p$)) and1260 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$). 1261 1268 The pressure in decibars is approximated by the depth in meters. 1262 With thsi EOS, the specific heat capacity of sea water, $C_p$, is a function of temperature, salinity and1263 pressure \citep{fofonoff.millard_bk83}.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}. 1264 1271 Nevertheless, a severe assumption is made in order to have a heat content ($C_p T_p$) which 1265 1272 is conserved by the model: $C_p$ is set to a constant value, the TEOS10 value. 1266 \item [\np{nn\_eos}\forcode{ = 1}]1267 a simplified EOS (S-EOS) inspired by\citet{vallis_bk06} is chosen,1268 the coefficients of which has been optimized to fit the behavior of TEOS10 1269 ( Roquet, personal comm.) (see also \citet{roquet.madec.ea_JPO15}).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}). 1270 1277 It provides a simplistic linear representation of both cabbeling and thermobaricity effects which 1271 1278 is enough for a proper treatment of the EOS in theoretical studies \citep{roquet.madec.ea_JPO15}. 1272 With such an equation of state there is no longer a distinction between 1273 \textit{ conservative} and \textit{potential} temperature,1274 as well as between \textit{absolute} and\textit{practical} salinity.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. 1275 1282 S-EOS takes the following expression: 1276 1283 \begin{gather*} 1277 % \label{eq:tra_S-EOS} 1278 \begin{alignedat}{2} 1279 &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. \\ 1280 & &+ b_0 \; ( 1 - 0.5 \; \lambda_2 \; S_a - \mu_2 \; z ) * &S_a \\ 1281 & \big. &- \nu \; T_a &S_a \big] \\ 1282 \end{alignedat} 1283 \\ 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] \\ 1284 1288 \text{with~} T_a = T - 10 \, ; \, S_a = S - 35 \, ; \, \rho_o = 1026~Kg/m^3 1285 1289 \end{gather*} 1286 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}. 1287 1292 In fact, when choosing S-EOS, various approximation of EOS can be specified simply by 1288 1293 changing the associated coefficients. 1289 Setting to zero the two thermobaric coefficients $(\mu_1,\mu_2)$ remove thermobaric effect from S-EOS. 1290 setting to zero the three cabbeling coefficients $(\lambda_1,\lambda_2,\nu)$ remove cabbeling effect from 1291 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. 1292 1298 Keeping non-zero value to $a_0$ and $b_0$ provide a linear EOS function of T and S. 1293 1299 \end{description} 1294 1300 1295 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1296 \begin{table}[!tb] 1297 \begin{center} 1298 \begin{tabular}{|l|l|l|l|} 1299 \hline 1300 coeff. & computer name & S-EOS & description \\ 1301 \hline 1302 $a_0$ & \np{rn\_a0} & $1.6550~10^{-1}$ & linear thermal expansion coeff. \\ 1303 \hline 1304 $b_0$ & \np{rn\_b0} & $7.6554~10^{-1}$ & linear haline expansion coeff. \\ 1305 \hline 1306 $\lambda_1$ & \np{rn\_lambda1}& $5.9520~10^{-2}$ & cabbeling coeff. in $T^2$ \\ 1307 \hline 1308 $\lambda_2$ & \np{rn\_lambda2}& $5.4914~10^{-4}$ & cabbeling coeff. in $S^2$ \\ 1309 \hline 1310 $\nu$ & \np{rn\_nu} & $2.4341~10^{-3}$ & cabbeling coeff. in $T \, S$ \\ 1311 \hline 1312 $\mu_1$ & \np{rn\_mu1} & $1.4970~10^{-4}$ & thermobaric coeff. in T \\ 1313 \hline 1314 $\mu_2$ & \np{rn\_mu2} & $1.1090~10^{-5}$ & thermobaric coeff. in S \\ 1315 \hline 1316 \end{tabular} 1317 \caption{ 1318 \protect\label{tab:SEOS} 1319 Standard value of S-EOS coefficients. 1320 } 1321 \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} 1322 1324 \end{table} 1323 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1324 1325 % ------------------------------------------------------------------------------------------------------------- 1326 % Brunt-V\"{a}is\"{a}l\"{a} Frequency 1327 % ------------------------------------------------------------------------------------------------------------- 1328 \subsection[Brunt-V\"{a}is\"{a}l\"{a} frequency (\forcode{nn_eos = [0-2]})] 1329 {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} 1330 1328 \label{subsec:TRA_bn2} 1331 1329 1332 An accurate computation of the ocean stability (i.e. of $N$, the brunt-V\"{a}is\"{a}l\"{a} frequency) is of1333 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 1334 1332 (namely TKE, GLS, Richardson number dependent vertical diffusion, enhanced vertical diffusion, 1335 1333 non-penetrative convection, tidal mixing parameterisation, iso-neutral diffusion). 1336 1334 In particular, $N^2$ has to be computed at the local pressure 1337 1335 (pressure in decibar being approximated by the depth in meters). 1338 The expression for $N^2$ is given by: 1336 The expression for $N^2$ is given by: 1339 1337 \[ 1340 % \label{eq: tra_bn2}1338 % \label{eq:TRA_bn2} 1341 1339 N^2 = \frac{g}{e_{3w}} \lt( \beta \; \delta_{k + 1/2}[S] - \alpha \; \delta_{k + 1/2}[T] \rt) 1342 1340 \] 1343 1341 where $(T,S) = (\Theta,S_A)$ for TEOS10, $(\theta,S_p)$ for TEOS-80, or $(T,S)$ for S-EOS, and, 1344 1342 $\alpha$ and $\beta$ are the thermal and haline expansion coefficients. 1345 The coefficients are a polynomial function of temperature, salinity and depth which expression depends on 1346 the chosen EOS. 1347 They are computed through \textit{eos\_rab}, a \fortran function that can be found in \mdl{eosbn2}. 1348 1349 % ------------------------------------------------------------------------------------------------------------- 1350 % Freezing Point of Seawater 1351 % ------------------------------------------------------------------------------------------------------------- 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 %% ================================================================================================= 1352 1348 \subsection{Freezing point of seawater} 1353 1349 \label{subsec:TRA_fzp} … … 1355 1351 The freezing point of seawater is a function of salinity and pressure \citep{fofonoff.millard_bk83}: 1356 1352 \begin{equation} 1357 \label{eq:tra_eos_fzp} 1358 \begin{split} 1359 &T_f (S,p) = \lt( a + b \, \sqrt{S} + c \, S \rt) \, S + d \, p \\ 1360 &\text{where~} a = -0.0575, \, b = 1.710523~10^{-3}, \, c = -2.154996~10^{-4} \\ 1361 &\text{and~} d = -7.53~10^{-3} 1362 \end{split} 1363 \end{equation} 1364 1365 \autoref{eq:tra_eos_fzp} is only used to compute the potential freezing point of sea water 1366 (\ie referenced to the surface $p = 0$), 1367 thus the pressure dependent terms in \autoref{eq:tra_eos_fzp} (last term) have been dropped. 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. 1368 1363 The freezing point is computed through \textit{eos\_fzp}, 1369 a \fortran function that can be found in \mdl{eosbn2}. 1370 1371 % ------------------------------------------------------------------------------------------------------------- 1372 % Potential Energy 1373 % ------------------------------------------------------------------------------------------------------------- 1364 a \fortran\ function that can be found in \mdl{eosbn2}. 1365 1366 %% ================================================================================================= 1374 1367 %\subsection{Potential Energy anomalies} 1375 1368 %\label{subsec:TRA_bn2} 1376 1369 1377 1370 % =====>>>>> TO BE written 1378 % 1379 1380 % ================================================================ 1381 % Horizontal Derivative in zps-coordinate 1382 % ================================================================ 1383 \section[Horizontal derivative in \textit{zps}-coordinate (\textit{zpshde.F90})] 1384 {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})} 1385 1374 \label{sec:TRA_zpshde} 1386 1375 1387 \ 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, 1388 1377 I've changed "derivative" to "difference" and "mean" to "average"} 1389 1378 1390 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}), 1391 1381 in general, tracers in horizontally adjacent cells live at different depths. 1392 Horizontal gradients of tracers are needed for horizontal diffusion (\mdl{traldf} module) and1393 the hydrostatic pressure gradient calculations (\mdl{dynhpg} module).1394 The partial cell properties at the top (\np {ln\_isfcav}\forcode{ = .true.}) are computed in the same way as1395 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. 1396 1386 So, only the bottom interpolation is explained below. 1397 1387 1398 1388 Before taking horizontal gradients between the tracers next to the bottom, 1399 1389 a linear interpolation in the vertical is used to approximate the deeper tracer as if 1400 it actually lived at the depth of the shallower tracer point (\autoref{fig:Partial_step_scheme}). 1401 For example, for temperature in the $i$-direction the needed interpolated temperature, $\widetilde T$, is: 1402 1403 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1404 \begin{figure}[!p] 1405 \begin{center} 1406 \includegraphics[width=\textwidth]{Fig_partial_step_scheme} 1407 \caption{ 1408 \protect\label{fig:Partial_step_scheme} 1409 Discretisation of the horizontal difference and average of tracers in the $z$-partial step coordinate 1410 (\protect\np{ln\_zps}\forcode{ = .true.}) in the case $(e3w_k^{i + 1} - e3w_k^i) > 0$. 1411 A linear interpolation is used to estimate $\widetilde T_k^{i + 1}$, 1412 the tracer value at the depth of the shallower tracer point of the two adjacent bottom $T$-points. 1413 The horizontal difference is then given by: $\delta_{i + 1/2} T_k = \widetilde T_k^{\, i + 1} -T_k^{\, i}$ and 1414 the average by: $\overline T_k^{\, i + 1/2} = (\widetilde T_k^{\, i + 1/2} - T_k^{\, i}) / 2$. 1415 } 1416 \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} 1417 1408 \end{figure} 1418 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1409 1419 1410 \[ 1420 1411 \widetilde T = \lt\{ 1421 1412 \begin{alignedat}{2} 1422 1413 &T^{\, i + 1} &-\frac{ \lt( e_{3w}^{i + 1} -e_{3w}^i \rt) }{ e_{3w}^{i + 1} } \; \delta_k T^{i + 1} 1423 & \quad \text{if $e_{3w}^{i + 1} \geq e_{3w}^i$} \\ \\1414 & \quad \text{if $e_{3w}^{i + 1} \geq e_{3w}^i$} \\ 1424 1415 &T^{\, i} &+\frac{ \lt( e_{3w}^{i + 1} -e_{3w}^i \rt )}{e_{3w}^i } \; \delta_k T^{i + 1} 1425 1416 & \quad \text{if $e_{3w}^{i + 1} < e_{3w}^i$} … … 1427 1418 \rt. 1428 1419 \] 1429 and the resulting forms for the horizontal difference and the horizontal average value of $T$ at a $U$-point are: 1430 \begin{equation} 1431 \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} 1432 1424 \begin{split} 1433 1425 \delta_{i + 1/2} T &= 1434 1426 \begin{cases} 1435 \widetilde T - T^i & \text{if~} e_{3w}^{i + 1} \geq e_{3w}^i \\ 1436 \\ 1437 T^{\, i + 1} - \widetilde T & \text{if~} e_{3w}^{i + 1} < e_{3w}^i 1438 \end{cases} 1439 \\ 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} \\ 1440 1430 \overline T^{\, i + 1/2} &= 1441 1431 \begin{cases} 1442 (\widetilde T - T^{\, i} ) / 2 & \text{if~} e_{3w}^{i + 1} \geq e_{3w}^i \\ 1443 \\ 1444 (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 1445 1434 \end{cases} 1446 1435 \end{split} … … 1449 1438 The computation of horizontal derivative of tracers as well as of density is performed once for all at 1450 1439 each time step in \mdl{zpshde} module and stored in shared arrays to be used when needed. 1451 It has to be emphasized that the procedure used to compute the interpolated density, $\widetilde \rho$, 1452 is not the same as that used for $T$ and $S$. 1453 Instead of forming a linear approximation of density, we compute $\widetilde \rho$ from the interpolated values of 1454 $T$ and $S$, and the pressure at a $u$-point 1455 (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}): 1456 1446 \[ 1457 % \label{eq: zps_hde_rho}1447 % \label{eq:TRA_zps_hde_rho} 1458 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) 1459 1449 \] 1460 1450 1461 1451 This is a much better approximation as the variation of $\rho$ with depth (and thus pressure) 1462 is highly non-linear with a true equation of state and thus is badly approximated with a linear interpolation. 1463 This approximation is used to compute both the horizontal pressure gradient (\autoref{sec:DYN_hpg}) and 1464 the slopes of neutral surfaces (\autoref{sec:LDF_slp}). 1465 1466 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, 1467 1458 both averaging and differencing operators appear. 1468 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: 1469 1460 in contrast to diffusion and pressure gradient computations, 1470 1461 no correction for partial steps is applied for advection. 1471 1462 The main motivation is to preserve the domain averaged mean variance of the advected field when 1472 1463 using the $2^{nd}$ order centred scheme. 1473 Sensitivity of the advection schemes to the way horizontal averages are performed in the vicinity of 1474 partial cells should be further investigated in the near future. 1475 %%% 1476 \gmcomment{gm : this last remark has to be done} 1477 %%% 1478 1479 \biblio 1480 1481 \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}} 1482 1469 1483 1470 \end{document} -
NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_ZDF.tex
r11179 r12149 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 (\texttt{\textbf{key\_zdfcst}})] 49 {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})} 50 68 \label{subsec:ZDF_cst} 51 %--------------------------------------------namzdf--------------------------------------------------------- 52 53 \nlst{namzdf} 54 %-------------------------------------------------------------------------------------------------------------- 55 56 Options are defined through the \ngn{namzdf} namelist variables. 57 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 58 72 constant values over the whole ocean. 59 73 This is the crudest way to define the vertical ocean physics. 60 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. 61 75 Typical values used in this case are: 62 76 \begin{align*} … … 65 79 \end{align*} 66 80 67 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. 68 82 In all cases, do not use values smaller that those associated with the molecular viscosity and diffusivity, 69 83 that is $\sim10^{-6}~m^2.s^{-1}$ for momentum, $\sim10^{-7}~m^2.s^{-1}$ for temperature and 70 84 $\sim10^{-9}~m^2.s^{-1}$ for salinity. 71 85 72 % ------------------------------------------------------------------------------------------------------------- 73 % Richardson Number Dependent 74 % ------------------------------------------------------------------------------------------------------------- 75 \subsection[Richardson number dependent (\texttt{\textbf{key\_zdfric}})] 76 {Richardson number dependent (\protect\key{zdfric})} 86 %% ================================================================================================= 87 \subsection[Richardson number dependent (\forcode{ln_zdfric})]{Richardson number dependent (\protect\np{ln_zdfric}{ln\_zdfric})} 77 88 \label{subsec:ZDF_ric} 78 89 79 %--------------------------------------------namric--------------------------------------------------------- 80 81 \nlst{namzdf_ric} 82 %-------------------------------------------------------------------------------------------------------------- 83 84 When \key{zdfric} is defined, a local Richardson number dependent formulation for the vertical momentum and 85 tracer eddy coefficients is set through the \ngn{namzdf\_ric} namelist variables. 86 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. 87 99 \textit{In situ} measurements have been used to link vertical turbulent activity to large scale ocean structures. 88 100 The hypothesis of a mixing mainly maintained by the growth of Kelvin-Helmholtz like instabilities leads to 89 101 a dependency between the vertical eddy coefficients and the local Richardson number 90 (\ie the ratio of stratification to vertical shear).102 (\ie\ the ratio of stratification to vertical shear). 91 103 Following \citet{pacanowski.philander_JPO81}, the following formulation has been implemented: 92 104 \[ 93 % \label{eq: zdfric}105 % \label{eq:ZDF_ric} 94 106 \left\{ 95 107 \begin{aligned} … … 100 112 \] 101 113 where $Ri = N^2 / \left(\partial_z \textbf{U}_h \right)^2$ is the local Richardson number, 102 $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}), 103 115 $A_b^{vT} $ and $A_b^{vm}$ are the constant background values set as in the constant case 104 116 (see \autoref{subsec:ZDF_cst}), and $A_{ric}^{vT} = 10^{-4}~m^2.s^{-1}$ is the maximum value that 105 117 can be reached by the coefficient when $Ri\leq 0$, $a=5$ and $n=2$. 106 The last three values can be modified by setting the \np{rn \_avmri}, \np{rn\_alp} and107 \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. 108 120 109 121 A simple mixing-layer model to transfer and dissipate the atmospheric forcings 110 (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. 111 123 112 124 In this case, the local depth of turbulent wind-mixing or "Ekman depth" $h_{e}(x,y,t)$ is evaluated and … … 124 136 \] 125 137 is computed from the wind stress vector $|\tau|$ and the reference density $ \rho_o$. 126 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}. 127 139 Once $h_{e}$ is computed, the vertical eddy coefficients within $h_{e}$ are set to 128 the empirical values \np{rn\_wtmix} and \np{rn\_wvmix} \citep{lermusiaux_JMS01}. 129 130 % ------------------------------------------------------------------------------------------------------------- 131 % TKE Turbulent Closure Scheme 132 % ------------------------------------------------------------------------------------------------------------- 133 \subsection[TKE turbulent closure scheme (\texttt{\textbf{key\_zdftke}})] 134 {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})} 135 144 \label{subsec:ZDF_tke} 136 145 137 %--------------------------------------------namzdf_tke-------------------------------------------------- 138 139 \nlst{namzdf_tke} 140 %-------------------------------------------------------------------------------------------------------------- 146 \begin{listing} 147 \nlst{namzdf_tke} 148 \caption{\forcode{&namzdf_tke}} 149 \label{lst:namzdf_tke} 150 \end{listing} 141 151 142 152 The vertical eddy viscosity and diffusivity coefficients are computed from a TKE turbulent closure model based on … … 144 154 and a closure assumption for the turbulent length scales. 145 155 This turbulent closure model has been developed by \citet{bougeault.lacarrere_MWR89} in the atmospheric case, 146 adapted by \citet{gaspar.gregoris.ea_JGR90} for the oceanic case, and embedded in OPA, the ancestor of NEMO,156 adapted by \citet{gaspar.gregoris.ea_JGR90} for the oceanic case, and embedded in OPA, the ancestor of \NEMO, 147 157 by \citet{blanke.delecluse_JPO93} for equatorial Atlantic simulations. 148 158 Since then, significant modifications have been introduced by \citet{madec.delecluse.ea_NPM98} in both the implementation and … … 151 161 its destruction through stratification, its vertical diffusion, and its dissipation of \citet{kolmogorov_IANS42} type: 152 162 \begin{equation} 153 \label{eq: zdftke_e}163 \label{eq:ZDF_tke_e} 154 164 \frac{\partial \bar{e}}{\partial t} = 155 165 \frac{K_m}{{e_3}^2 }\;\left[ {\left( {\frac{\partial u}{\partial k}} \right)^2 … … 161 171 \end{equation} 162 172 \[ 163 % \label{eq: zdftke_kz}173 % \label{eq:ZDF_tke_kz} 164 174 \begin{split} 165 175 K_m &= C_k\ l_k\ \sqrt {\bar{e}\; } \\ … … 167 177 \end{split} 168 178 \] 169 where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}), 170 $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, 171 181 $P_{rt}$ is the Prandtl number, $K_m$ and $K_\rho$ are the vertical eddy viscosity and diffusivity coefficients. 172 182 The constants $C_k = 0.1$ and $C_\epsilon = \sqrt {2} /2$ $\approx 0.7$ are designed to deal with 173 vertical mixing at any depth \citep{gaspar.gregoris.ea_JGR90}. 174 They are set through namelist parameters \np{nn \_ediff} and \np{nn\_ediss}.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}. 175 185 $P_{rt}$ can be set to unity or, following \citet{blanke.delecluse_JPO93}, be a function of the local Richardson number, $R_i$: 176 186 \begin{align*} 177 % \label{eq: prt}187 % \label{eq:ZDF_prt} 178 188 P_{rt} = 179 189 \begin{cases} … … 183 193 \end{cases} 184 194 \end{align*} 185 Options are defined through the \ngn{namzdfy\_tke} namelist variables. 186 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. 187 196 188 197 At the sea surface, the value of $\bar{e}$ is prescribed from the wind stress field as 189 $\bar{e}_o = e_{bb} |\tau| / \rho_o$, with $e_{bb}$ the \np{rn \_ebb} namelist parameter.198 $\bar{e}_o = e_{bb} |\tau| / \rho_o$, with $e_{bb}$ the \np{rn_ebb}{rn\_ebb} namelist parameter. 190 199 The default value of $e_{bb}$ is 3.75. \citep{gaspar.gregoris.ea_JGR90}), however a much larger value can be used when 191 200 taking into account the surface wave breaking (see below Eq. \autoref{eq:ZDF_Esbc}). … … 193 202 The time integration of the $\bar{e}$ equation may formally lead to negative values because 194 203 the numerical scheme does not ensure its positivity. 195 To overcome this problem, a cut-off in the minimum value of $\bar{e}$ is used (\np{rn \_emin} namelist parameter).204 To overcome this problem, a cut-off in the minimum value of $\bar{e}$ is used (\np{rn_emin}{rn\_emin} namelist parameter). 196 205 Following \citet{gaspar.gregoris.ea_JGR90}, the cut-off value is set to $\sqrt{2}/2~10^{-6}~m^2.s^{-2}$. 197 206 This allows the subsequent formulations to match that of \citet{gargett_JMR84} for the diffusion in … … 199 208 In addition, a cut-off is applied on $K_m$ and $K_\rho$ to avoid numerical instabilities associated with 200 209 too weak vertical diffusion. 201 They must be specified at least larger than the molecular values, and are set through \np{rn\_avm0} and 202 \np{rn\_avt0} (namzdf namelist, see \autoref{subsec:ZDF_cst}). 203 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 %% ================================================================================================= 204 214 \subsubsection{Turbulent length scale} 205 215 206 216 For computational efficiency, the original formulation of the turbulent length scales proposed by 207 217 \citet{gaspar.gregoris.ea_JGR90} has been simplified. 208 Four formulations are proposed, the choice of which is controlled by the \np{nn \_mxl} namelist parameter.218 Four formulations are proposed, the choice of which is controlled by the \np{nn_mxl}{nn\_mxl} namelist parameter. 209 219 The first two are based on the following first order approximation \citep{blanke.delecluse_JPO93}: 210 220 \begin{equation} 211 \label{eq: tke_mxl0_1}221 \label{eq:ZDF_tke_mxl0_1} 212 222 l_k = l_\epsilon = \sqrt {2 \bar{e}\; } / N 213 223 \end{equation} 214 224 which is valid in a stable stratified region with constant values of the Brunt-Vais\"{a}l\"{a} frequency. 215 225 The resulting length scale is bounded by the distance to the surface or to the bottom 216 (\np {nn\_mxl}\forcode{ = 0}) or by the local vertical scale factor (\np{nn\_mxl}\forcode{ = 1}).226 (\np[=0]{nn_mxl}{nn\_mxl}) or by the local vertical scale factor (\np[=1]{nn_mxl}{nn\_mxl}). 217 227 \citet{blanke.delecluse_JPO93} notice that this simplification has two major drawbacks: 218 228 it makes no sense for locally unstable stratification and the computation no longer uses all 219 229 the information contained in the vertical density profile. 220 To overcome these drawbacks, \citet{madec.delecluse.ea_NPM98} 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, 221 231 which add an extra assumption concerning the vertical gradient of the computed length scale. 222 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: 223 233 \begin{equation} 224 \label{eq: tke_mxl_constraint}234 \label{eq:ZDF_tke_mxl_constraint} 225 235 \frac{1}{e_3 }\left| {\frac{\partial l}{\partial k}} \right| \leq 1 226 236 \qquad \text{with }\ l = l_k = l_\epsilon 227 237 \end{equation} 228 \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 229 239 the variations of depth. 230 It provides a better approximation of the \citet{gaspar.gregoris.ea_JGR90} formulation while being much less 240 It provides a better approximation of the \citet{gaspar.gregoris.ea_JGR90} formulation while being much less 231 241 time consuming. 232 242 In particular, it allows the length scale to be limited not only by the distance to the surface or 233 243 to the ocean bottom but also by the distance to a strongly stratified portion of the water column such as 234 the thermocline (\autoref{fig: mixing_length}).235 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: 236 246 $l_{up}$ and $l_{dwn}$, the upward and downward length scales, and 237 247 evaluate the dissipation and mixing length scales as 238 248 (and note that here we use numerical indexing): 239 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>240 249 \begin{figure}[!t] 241 \begin{center} 242 \includegraphics[width=\textwidth]{Fig_mixing_length} 243 \caption{ 244 \protect\label{fig:mixing_length} 245 Illustration of the mixing length computation. 246 } 247 \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} 248 254 \end{figure} 249 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 250 \[ 251 % \label{eq:tke_mxl2} 255 \[ 256 % \label{eq:ZDF_tke_mxl2} 252 257 \begin{aligned} 253 258 l_{up\ \ }^{(k)} &= \min \left( l^{(k)} \ , \ l_{up}^{(k+1)} + e_{3t}^{(k)}\ \ \ \; \right) … … 257 262 \end{aligned} 258 263 \] 259 where $l^{(k)}$ is computed using \autoref{eq: tke_mxl0_1}, \ie$l^{(k)} = \sqrt {2 {\bar e}^{(k)} / {N^2}^{(k)} }$.260 261 In the \np {nn\_mxl}\forcode{ = 2} case, the dissipation and mixing length scales take the same value:262 $ l_k= l_\epsilon = \min \left(\ l_{up} \;,\; l_{dwn}\ \right)$, while in the \np {nn\_mxl}\forcode{ = 3} case,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, 263 268 the dissipation and mixing turbulent length scales are give as in \citet{gaspar.gregoris.ea_JGR90}: 264 269 \[ 265 % \label{eq: tke_mxl_gaspar}270 % \label{eq:ZDF_tke_mxl_gaspar} 266 271 \begin{aligned} 267 272 & l_k = \sqrt{\ l_{up} \ \ l_{dwn}\ } \\ … … 270 275 \] 271 276 272 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. 273 278 Usually the surface scale is given by $l_o = \kappa \,z_o$ where $\kappa = 0.4$ is von Karman's constant and 274 279 $z_o$ the roughness parameter of the surface. 275 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}. 276 281 In the ocean interior a minimum length scale is set to recover the molecular viscosity when 277 282 $\bar{e}$ reach its minimum value ($1.10^{-6}= C_k\, l_{min} \,\sqrt{\bar{e}_{min}}$ ). 278 283 284 %% ================================================================================================= 279 285 \subsubsection{Surface wave breaking parameterization} 280 %-----------------------------------------------------------------------%281 286 282 287 Following \citet{mellor.blumberg_JPO04}, the TKE turbulence closure model has been modified to … … 284 289 This results in a reduction of summertime surface temperature when the mixed layer is relatively shallow. 285 290 The \citet{mellor.blumberg_JPO04} modifications acts on surface length scale and TKE values and 286 air-sea drag coefficient. 287 The latter concerns the bulk formul ea and is not discussed here.291 air-sea drag coefficient. 292 The latter concerns the bulk formulae and is not discussed here. 288 293 289 294 Following \citet{craig.banner_JPO94}, the boundary condition on surface TKE value is : … … 293 298 \end{equation} 294 299 where $\alpha_{CB}$ is the \citet{craig.banner_JPO94} constant of proportionality which depends on the ''wave age'', 295 ranging from 57 for mature waves to 146 for younger waves \citep{mellor.blumberg_JPO04}. 300 ranging from 57 for mature waves to 146 for younger waves \citep{mellor.blumberg_JPO04}. 296 301 The boundary condition on the turbulent length scale follows the Charnock's relation: 297 302 \begin{equation} … … 304 309 $\alpha_{CB} = 100$ the Craig and Banner's value. 305 310 As the surface boundary condition on TKE is prescribed through $\bar{e}_o = e_{bb} |\tau| / \rho_o$, 306 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 307 312 to $\alpha_{CB} = 100$. 308 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, 309 314 with $\beta$ hard coded to the Stacey's value. 310 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 311 316 surface $\bar{e}$ value. 312 317 318 %% ================================================================================================= 313 319 \subsubsection{Langmuir cells} 314 %--------------------------------------%315 320 316 321 Langmuir circulations (LC) can be described as ordered large-scale vertical motions in … … 320 325 The detailed physics behind LC is described in, for example, \citet{craik.leibovich_JFM76}. 321 326 The prevailing explanation is that LC arise from a nonlinear interaction between the Stokes drift and 322 wind drift currents. 327 wind drift currents. 323 328 324 329 Here we introduced in the TKE turbulent closure the simple parameterization of Langmuir circulations proposed by 325 330 \citep{axell_JGR02} for a $k-\epsilon$ turbulent closure. 326 331 The parameterization, tuned against large-eddy simulation, includes the whole effect of LC in 327 an extra source term sof TKE, $P_{LC}$.328 The presence of $P_{LC}$ in \autoref{eq: zdftke_e}, the TKE equation, is controlled by setting \np{ln\_lc} to329 \forcode{.true.} in the namtkenamelist.330 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 331 336 By making an analogy with the characteristic convective velocity scale (\eg, \citet{dalessio.abdella.ea_JPO98}), 332 $P_{LC}$ is assumed to be : 337 $P_{LC}$ is assumed to be : 333 338 \[ 334 339 P_{LC}(z) = \frac{w_{LC}^3(z)}{H_{LC}} 335 340 \] 336 341 where $w_{LC}(z)$ is the vertical velocity profile of LC, and $H_{LC}$ is the LC depth. 337 With no information about the wave field, $w_{LC}$ is assumed to be proportional to 338 the Stokes drift $u_s = 0.377\,\,|\tau|^{1/2}$, where $|\tau|$ is the surface wind stress module 342 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 339 344 \footnote{Following \citet{li.garrett_JMR93}, the surface Stoke drift velocity may be expressed as 340 345 $u_s = 0.016 \,|U_{10m}|$. … … 344 349 For the vertical variation, $w_{LC}$ is assumed to be zero at the surface as well as at 345 350 a finite depth $H_{LC}$ (which is often close to the mixed layer depth), 346 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). 347 352 The resulting expression for $w_{LC}$ is : 348 353 \[ … … 355 360 where $c_{LC} = 0.15$ has been chosen by \citep{axell_JGR02} as a good compromise to fit LES data. 356 361 The chosen value yields maximum vertical velocities $w_{LC}$ of the order of a few centimeters per second. 357 The value of $c_{LC}$ is set through the \np{rn \_lc} namelist parameter,358 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}. 359 364 360 365 The $H_{LC}$ is estimated in a similar way as the turbulent length scale of TKE equations: 361 $H_{LC}$ is depth to which a water parcel with kinetic energy due to Stoke drift can reach on its own by362 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 363 368 \[ 364 369 - \int_{-H_{LC}}^0 { N^2\;z \;dz} = \frac{1}{2} u_s^2 365 370 \] 366 371 372 %% ================================================================================================= 367 373 \subsubsection{Mixing just below the mixed layer} 368 %--------------------------------------------------------------%369 374 370 375 Vertical mixing parameterizations commonly used in ocean general circulation models tend to 371 376 produce mixed-layer depths that are too shallow during summer months and windy conditions. 372 377 This bias is particularly acute over the Southern Ocean. 373 To overcome this systematic bias, an ad hoc parameterization is introduced into the TKE scheme \cite{rodgers.aumont.ea_B14}. 374 The parameterization is an empirical one, \ie not derived from theoretical considerations,375 but rather is meant to account for observed processes that affect the density structure of 376 the ocean’s planetary boundary layer that are not explicitly captured by default in the TKE scheme 377 (\ie near-inertial oscillations and ocean swells and waves).378 379 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}), 380 385 the TKE input to the ocean ($S$) imposed by the winds in the form of near-inertial oscillations, 381 386 swell and waves is parameterized by \autoref{eq:ZDF_Esbc} the standard TKE surface boundary condition, … … 386 391 \end{equation} 387 392 where $z$ is the depth, $e_s$ is TKE surface boundary condition, $f_r$ is the fraction of the surface TKE that 388 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 389 394 the penetration, and $f_i$ is the ice concentration 390 (no penetration if $f_i=1$, that isif the ocean is entirely covered by sea-ice).391 The value of $f_r$, usually a few percents, is specified through \np{rn \_efr} namelist parameter.392 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 393 398 a latitude dependent value (varying from 0.5~m at the Equator to a maximum value of 30~m at high latitudes 394 (\np {nn\_etau}\forcode{ = 1}).395 396 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}. 397 402 They correspond to applying \autoref{eq:ZDF_Ehtau} only at the base of the mixed layer, 398 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. 399 404 Those two options are obsolescent features introduced for test purposes. 400 They will be removed in the next release. 401 402 % from Burchard et al OM 2008 : 403 % the most critical process not reproduced by statistical turbulence models is the activity of 404 % internal waves and their interaction with turbulence. After the Reynolds decomposition, 405 % internal waves are in principle included in the RANS equations, but later partially 406 % excluded by the hydrostatic assumption and the model resolution. 407 % Thus far, the representation of internal wave mixing in ocean models has been relatively crude 408 % (\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. 409 535 410 536 % ------------------------------------------------------------------------------------------------------------- 411 % TKE discretization considerations537 % OSM OSMOSIS BL Scheme 412 538 % ------------------------------------------------------------------------------------------------------------- 413 \subsection[TKE discretization considerations (\texttt{\textbf{key\_zdftke}})] 414 {TKE discretization considerations (\protect\key{zdftke})} 415 \label{subsec:ZDF_tke_ene} 416 417 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 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). 418 644 \begin{figure}[!t] 419 645 \begin{center} 420 \includegraphics[width=\textwidth]{Fig_ZDF_TKE_time_scheme}646 %\includegraphics[width=0.7\textwidth]{ZDF_OSM_structure_of_OSBL} 421 647 \caption{ 422 \protect\label{fig: TKE_time_scheme}423 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. 424 650 } 425 \end{center} 651 \end{center} 426 652 \end{figure} 427 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 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} 428 765 429 766 The production of turbulence by vertical shear (the first term of the right hand side of 430 \autoref{eq: zdftke_e}) should balance the loss of kinetic energy associated with the vertical momentum diffusion431 (first line in \autoref{eq: PE_zdf}).432 To do so a special care ha veto be taken for both the time and space discretization of433 the TKEequation \citep{burchard_OM02,marsaleix.auclair.ea_OM08}.434 435 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 436 773 the two-level Leap-Frog time stepping of the momentum and tracer equations interplays with 437 the one-level forward time stepping of TKE equation.774 the one-level forward time stepping of the equation for $\bar{e}$. 438 775 With this framework, the total loss of kinetic energy (in 1D for the demonstration) due to 439 776 the vertical momentum diffusion is obtained by multiplying this quantity by $u^t$ and 440 summing the result vertically: 777 summing the result vertically: 441 778 \begin{equation} 442 \label{eq: energ1}779 \label{eq:ZDF_energ1} 443 780 \begin{split} 444 781 \int_{-H}^{\eta} u^t \,\partial_z &\left( {K_m}^t \,(\partial_z u)^{t+\rdt} \right) \,dz \\ … … 448 785 \end{equation} 449 786 Here, the vertical diffusion of momentum is discretized backward in time with a coefficient, $K_m$, 450 known at time $t$ (\autoref{fig: TKE_time_scheme}), as it is required when using the TKE scheme451 (see \autoref{sec: STP_forward_imp}).452 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 453 790 the surface (atmospheric forcing) and at the bottom (friction effect). 454 791 The second term is always negative. 455 792 It is the dissipation rate of kinetic energy, and thus minus the shear production rate of $\bar{e}$. 456 \autoref{eq: energ1} implies that, to be energetically consistent,793 \autoref{eq:ZDF_energ1} implies that, to be energetically consistent, 457 794 the production rate of $\bar{e}$ used to compute $(\bar{e})^t$ (and thus ${K_m}^t$) should be expressed as 458 795 ${K_m}^{t-\rdt}\,(\partial_z u)^{t-\rdt} \,(\partial_z u)^t$ … … 460 797 461 798 A similar consideration applies on the destruction rate of $\bar{e}$ due to stratification 462 (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}). 463 800 This term must balance the input of potential energy resulting from vertical mixing. 464 The rate of change of potential energy (in 1D for the demonstration) due vertical mixing is obtained by465 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: 466 803 \begin{equation} 467 \label{eq: energ2}804 \label{eq:ZDF_energ2} 468 805 \begin{split} 469 806 \int_{-H}^{\eta} g\,z\,\partial_z &\left( {K_\rho}^t \,(\partial_k \rho)^{t+\rdt} \right) \,dz \\ … … 474 811 \end{split} 475 812 \end{equation} 476 where we use $N^2 = -g \,\partial_k \rho / (e_3 \rho)$. 477 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 478 815 there is no diffusive flux through the ocean surface and bottom). 479 816 The second term is minus the destruction rate of $\bar{e}$ due to stratification. 480 Therefore \autoref{eq: energ1} implies that, to be energetically consistent,481 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}. 482 819 483 820 Let us now address the space discretization issue. 484 821 The vertical eddy coefficients are defined at $w$-point whereas the horizontal velocity components are in 485 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}). 486 823 A space averaging is thus required to obtain the shear TKE production term. 487 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 488 825 the shear at $t$ and $t-\rdt$ must be performed prior to the averaging. 489 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. 490 827 491 828 The above energetic considerations leads to the following final discrete form for the TKE equation: 492 829 \begin{equation} 493 \label{eq: zdftke_ene}830 \label{eq:ZDF_tke_ene} 494 831 \begin{split} 495 832 \frac { (\bar{e})^t - (\bar{e})^{t-\rdt} } {\rdt} \equiv … … 508 845 \end{split} 509 846 \end{equation} 510 where the last two terms in \autoref{eq: zdftke_ene} (vertical diffusion and Kolmogorov dissipation)511 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}). 512 849 Note that the Kolmogorov term has been linearized in time in order to render the implicit computation possible. 513 The restart of the TKE scheme requires the storage of $\bar {e}$, $K_m$, $K_\rho$ and $l_\epsilon$ as 514 they all appear in the right hand side of \autoref{eq:zdftke_ene}. 515 For the latter, it is in fact the ratio $\sqrt{\bar{e}}/l_\epsilon$ which is stored. 516 517 % ------------------------------------------------------------------------------------------------------------- 518 % GLS Generic Length Scale Scheme 519 % ------------------------------------------------------------------------------------------------------------- 520 \subsection[GLS: Generic Length Scale (\texttt{\textbf{key\_zdfgls}})] 521 {GLS: Generic Length Scale (\protect\key{zdfgls})} 522 \label{subsec:ZDF_gls} 523 524 %--------------------------------------------namzdf_gls--------------------------------------------------------- 525 526 \nlst{namzdf_gls} 527 %-------------------------------------------------------------------------------------------------------------- 528 529 The Generic Length Scale (GLS) scheme is a turbulent closure scheme based on two prognostic equations: 530 one for the turbulent kinetic energy $\bar {e}$, and another for the generic length scale, 531 $\psi$ \citep{umlauf.burchard_JMR03, umlauf.burchard_CSR05}. 532 This later variable is defined as: $\psi = {C_{0\mu}}^{p} \ {\bar{e}}^{m} \ l^{n}$, 533 where the triplet $(p, m, n)$ value given in Tab.\autoref{tab:GLS} allows to recover a number of 534 well-known turbulent closures ($k$-$kl$ \citep{mellor.yamada_RG82}, $k$-$\epsilon$ \citep{rodi_JGR87}, 535 $k$-$\omega$ \citep{wilcox_AJ88} among others \citep{umlauf.burchard_JMR03,kantha.carniel_JMR03}). 536 The GLS scheme is given by the following set of equations: 537 \begin{equation} 538 \label{eq:zdfgls_e} 539 \frac{\partial \bar{e}}{\partial t} = 540 \frac{K_m}{\sigma_e e_3 }\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2 541 +\left( \frac{\partial v}{\partial k} \right)^2} \right] 542 -K_\rho \,N^2 543 +\frac{1}{e_3}\,\frac{\partial}{\partial k} \left[ \frac{K_m}{e_3}\,\frac{\partial \bar{e}}{\partial k} \right] 544 - \epsilon 545 \end{equation} 546 547 \[ 548 % \label{eq:zdfgls_psi} 549 \begin{split} 550 \frac{\partial \psi}{\partial t} =& \frac{\psi}{\bar{e}} \left\{ 551 \frac{C_1\,K_m}{\sigma_{\psi} {e_3}}\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2 552 +\left( \frac{\partial v}{\partial k} \right)^2} \right] 553 - C_3 \,K_\rho\,N^2 - C_2 \,\epsilon \,Fw \right\} \\ 554 &+\frac{1}{e_3} \;\frac{\partial }{\partial k}\left[ {\frac{K_m}{e_3 } 555 \;\frac{\partial \psi}{\partial k}} \right]\; 556 \end{split} 557 \] 558 559 \[ 560 % \label{eq:zdfgls_kz} 561 \begin{split} 562 K_m &= C_{\mu} \ \sqrt {\bar{e}} \ l \\ 563 K_\rho &= C_{\mu'}\ \sqrt {\bar{e}} \ l 564 \end{split} 565 \] 566 567 \[ 568 % \label{eq:zdfgls_eps} 569 {\epsilon} = C_{0\mu} \,\frac{\bar {e}^{3/2}}{l} \; 570 \] 571 where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}) and 572 $\epsilon$ the dissipation rate. 573 The constants $C_1$, $C_2$, $C_3$, ${\sigma_e}$, ${\sigma_{\psi}}$ and the wall function ($Fw$) depends of 574 the choice of the turbulence model. 575 Four different turbulent models are pre-defined (Tab.\autoref{tab:GLS}). 576 They are made available through the \np{nn\_clo} namelist parameter. 577 578 %--------------------------------------------------TABLE-------------------------------------------------- 579 \begin{table}[htbp] 580 \begin{center} 581 % \begin{tabular}{cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}c} 582 \begin{tabular}{ccccc} 583 & $k-kl$ & $k-\epsilon$ & $k-\omega$ & generic \\ 584 % & \citep{mellor.yamada_RG82} & \citep{rodi_JGR87} & \citep{wilcox_AJ88} & \\ 585 \hline 586 \hline 587 \np{nn\_clo} & \textbf{0} & \textbf{1} & \textbf{2} & \textbf{3} \\ 588 \hline 589 $( p , n , m )$ & ( 0 , 1 , 1 ) & ( 3 , 1.5 , -1 ) & ( -1 , 0.5 , -1 ) & ( 2 , 1 , -0.67 ) \\ 590 $\sigma_k$ & 2.44 & 1. & 2. & 0.8 \\ 591 $\sigma_\psi$ & 2.44 & 1.3 & 2. & 1.07 \\ 592 $C_1$ & 0.9 & 1.44 & 0.555 & 1. \\ 593 $C_2$ & 0.5 & 1.92 & 0.833 & 1.22 \\ 594 $C_3$ & 1. & 1. & 1. & 1. \\ 595 $F_{wall}$ & Yes & -- & -- & -- \\ 596 \hline 597 \hline 598 \end{tabular} 599 \caption{ 600 \protect\label{tab:GLS} 601 Set of predefined GLS parameters, or equivalently predefined turbulence models available with 602 \protect\key{zdfgls} and controlled by the \protect\np{nn\_clos} namelist variable in \protect\ngn{namzdf\_gls}. 603 } 604 \end{center} 605 \end{table} 606 %-------------------------------------------------------------------------------------------------------------- 607 608 In the Mellor-Yamada model, the negativity of $n$ allows to use a wall function to force the convergence of 609 the mixing length towards $K z_b$ ($K$: Kappa and $z_b$: rugosity length) value near physical boundaries 610 (logarithmic boundary layer law). 611 $C_{\mu}$ and $C_{\mu'}$ are calculated from stability function proposed by \citet{galperin.kantha.ea_JAS88}, 612 or by \citet{kantha.clayson_JGR94} or one of the two functions suggested by \citet{canuto.howard.ea_JPO01} 613 (\np{nn\_stab\_func}\forcode{ = 0..3}, resp.). 614 The value of $C_{0\mu}$ depends of the choice of the stability function. 615 616 The surface and bottom boundary condition on both $\bar{e}$ and $\psi$ can be calculated thanks to Dirichlet or 617 Neumann condition through \np{nn\_tkebc\_surf} and \np{nn\_tkebc\_bot}, resp. 618 As for TKE closure, the wave effect on the mixing is considered when 619 \np{ln\_crban}\forcode{ = .true.} \citep{craig.banner_JPO94, mellor.blumberg_JPO04}. 620 The \np{rn\_crban} namelist parameter is $\alpha_{CB}$ in \autoref{eq:ZDF_Esbc} and 621 \np{rn\_charn} provides the value of $\beta$ in \autoref{eq:ZDF_Lsbc}. 622 623 The $\psi$ equation is known to fail in stably stratified flows, and for this reason 624 almost all authors apply a clipping of the length scale as an \textit{ad hoc} remedy. 625 With this clipping, the maximum permissible length scale is determined by $l_{max} = c_{lim} \sqrt{2\bar{e}}/ N$. 626 A value of $c_{lim} = 0.53$ is often used \citep{galperin.kantha.ea_JAS88}. 627 \cite{umlauf.burchard_CSR05} show that the value of the clipping factor is of crucial importance for 628 the entrainment depth predicted in stably stratified situations, 629 and that its value has to be chosen in accordance with the algebraic model for the turbulent fluxes. 630 The clipping is only activated if \np{ln\_length\_lim}\forcode{ = .true.}, 631 and the $c_{lim}$ is set to the \np{rn\_clim\_galp} value. 632 633 The time and space discretization of the GLS equations follows the same energetic consideration as for 634 the TKE case described in \autoref{subsec:ZDF_tke_ene} \citep{burchard_OM02}. 635 Examples of performance of the 4 turbulent closure scheme can be found in \citet{warner.sherwood.ea_OM05}. 636 637 % ------------------------------------------------------------------------------------------------------------- 638 % OSM OSMOSIS BL Scheme 639 % ------------------------------------------------------------------------------------------------------------- 640 \subsection[OSM: OSMosis boundary layer scheme (\texttt{\textbf{key\_zdfosm}})] 641 {OSM: OSMosis boundary layer scheme (\protect\key{zdfosm})} 642 \label{subsec:ZDF_osm} 643 644 %--------------------------------------------namzdf_osm--------------------------------------------------------- 645 646 \nlst{namzdf_osm} 647 %-------------------------------------------------------------------------------------------------------------- 648 649 The OSMOSIS turbulent closure scheme is based on...... TBC 650 651 % ================================================================ 652 % Convection 653 % ================================================================ 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 %% ================================================================================================= 654 855 \section{Convection} 655 856 \label{sec:ZDF_conv} 656 857 657 %--------------------------------------------namzdf-------------------------------------------------------- 658 659 \nlst{namzdf} 660 %-------------------------------------------------------------------------------------------------------------- 661 662 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. 663 859 In nature, convective processes quickly re-establish the static stability of the water column. 664 860 These processes have been removed from the model via the hydrostatic assumption so they must be parameterized. … … 667 863 or/and the use of a turbulent closure scheme. 668 864 669 % ------------------------------------------------------------------------------------------------------------- 670 % Non-Penetrative Convective Adjustment 671 % ------------------------------------------------------------------------------------------------------------- 672 \subsection[Non-penetrative convective adjustment (\forcode{ln_tranpc = .true.})] 673 {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})} 674 867 \label{subsec:ZDF_npc} 675 868 676 %--------------------------------------------namzdf--------------------------------------------------------677 678 \nlst{namzdf}679 %--------------------------------------------------------------------------------------------------------------680 681 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>682 869 \begin{figure}[!htb] 683 \begin{center} 684 \includegraphics[width=\textwidth]{Fig_npc} 685 \caption{ 686 \protect\label{fig:npc} 687 Example of an unstable density profile treated by the non penetrative convective adjustment algorithm. 688 $1^{st}$ step: the initial profile is checked from the surface to the bottom. 689 It is found to be unstable between levels 3 and 4. 690 They are mixed. 691 The resulting $\rho$ is still larger than $\rho$(5): levels 3 to 5 are mixed. 692 The resulting $\rho$ is still larger than $\rho$(6): levels 3 to 6 are mixed. 693 The $1^{st}$ step ends since the density profile is then stable below the level 3. 694 $2^{nd}$ step: the new $\rho$ profile is checked following the same procedure as in $1^{st}$ step: 695 levels 2 to 5 are mixed. 696 The new density profile is checked. 697 It is found stable: end of algorithm. 698 } 699 \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} 700 886 \end{figure} 701 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 702 703 Options are defined through the \ngn{namzdf} namelist variables. 704 The non-penetrative convective adjustment is used when \np{ln\_zdfnpc}\forcode{ = .true.}. 705 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 706 891 the water column, but only until the density structure becomes neutrally stable 707 (\ie until the mixed portion of the water column has \textit{exactly} the density of the water just below)892 (\ie\ until the mixed portion of the water column has \textit{exactly} the density of the water just below) 708 893 \citep{madec.delecluse.ea_JPO91}. 709 The associated algorithm is an iterative process used in the following way (\autoref{fig: npc}):894 The associated algorithm is an iterative process used in the following way (\autoref{fig:ZDF_npc}): 710 895 starting from the top of the ocean, the first instability is found. 711 896 Assume in the following that the instability is located between levels $k$ and $k+1$. … … 722 907 This algorithm is significantly different from mixing statically unstable levels two by two. 723 908 The latter procedure cannot converge with a finite number of iterations for some vertical profiles while 724 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 725 910 the number of vertical levels. 726 911 This property is of paramount importance as pointed out by \citet{killworth_iprc89}: … … 732 917 (L. Brodeau, personnal communication). 733 918 Two main differences have been introduced compared to the original algorithm: 734 $(i)$ the stability is now checked using the Brunt-V\"{a}is\"{a}l\"{a} frequency 735 (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); 736 921 $(ii)$ when two levels are found unstable, their thermal and haline expansion coefficients are vertically mixed in 737 922 the same way their temperature and salinity has been mixed. … … 739 924 having to recompute the expansion coefficients at each mixing iteration. 740 925 741 % ------------------------------------------------------------------------------------------------------------- 742 % Enhanced Vertical Diffusion 743 % ------------------------------------------------------------------------------------------------------------- 744 \subsection[Enhanced vertical diffusion (\forcode{ln_zdfevd = .true.})] 745 {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})} 746 928 \label{subsec:ZDF_evd} 747 929 748 %--------------------------------------------namzdf-------------------------------------------------------- 749 750 \nlst{namzdf} 751 %-------------------------------------------------------------------------------------------------------------- 752 753 Options are defined through the \ngn{namzdf} namelist variables. 754 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}. 755 932 In this case, the vertical eddy mixing coefficients are assigned very large values 756 (a typical value is $10\;m^2s^{-1})$in regions where the stratification is unstable757 (\ie when $N^2$ the Brunt-Vais\"{a}l\"{a} frequency is negative) \citep{lazar_phd97, lazar.madec.ea_JPO99}.758 This is done either on tracers only (\np {nn\_evdm}\forcode{ = 0}) or759 on both momentum and tracers (\np {nn\_evdm}\forcode{ = 1}).760 761 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}, 762 939 the four neighbouring $A_u^{vm} \;\mbox{and}\;A_v^{vm}$ values also, are set equal to 763 the namelist parameter \np{rn \_avevd}.940 the namelist parameter \np{rn_avevd}{rn\_avevd}. 764 941 A typical value for $rn\_avevd$ is between 1 and $100~m^2.s^{-1}$. 765 942 This parameterisation of convective processes is less time consuming than 766 943 the convective adjustment algorithm presented above when mixing both tracers and 767 944 momentum in the case of static instabilities. 768 It requires the use of an implicit time stepping on vertical diffusion terms769 (\ie np{ln\_zdfexp}\forcode{ = .false.}).770 945 771 946 Note that the stability test is performed on both \textit{before} and \textit{now} values of $N^2$. 772 947 This removes a potential source of divergence of odd and even time step in 773 a leapfrog environment \citep{leclair_phd10} (see \autoref{sec:STP_mLF}). 774 775 % ------------------------------------------------------------------------------------------------------------- 776 % Turbulent Closure Scheme 777 % ------------------------------------------------------------------------------------------------------------- 778 \subsection[Turbulent closure scheme (\texttt{\textbf{key\_zdf}}\texttt{\textbf{\{tke,gls,osm\}}})] 779 {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}})} 780 952 \label{subsec:ZDF_tcs} 781 953 782 The turbulent closure scheme presented in \autoref{subsec:ZDF_tke} and \autoref{subsec:ZDF_gls} 783 (\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. 784 957 In such a case, the term corresponding to the destruction of turbulent kinetic energy through stratification in 785 \autoref{eq: zdftke_e} or \autoref{eq:zdfgls_e} becomes a source term, since $N^2$ is negative.786 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}$787 (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}$). 788 961 These large values restore the static stability of the water column in a way similar to that of 789 962 the enhanced vertical diffusion parameterisation (\autoref{subsec:ZDF_evd}). … … 792 965 because the mixing length scale is bounded by the distance to the sea surface. 793 966 It can thus be useful to combine the enhanced vertical diffusion with the turbulent closure scheme, 794 \ie setting the \np{ln\_zdfnpc} namelist parameter to true and795 defining the turbulent closure CPP keyall together.796 797 The KPPturbulent closure scheme already includes enhanced vertical diffusion in the case of convection,798 as governed by the variables $bvsqcon$ and $difcon$ found in \mdl{zdfkpp},799 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. 800 973 % gm% + one word on non local flux with KPP scheme trakpp.F90 module... 801 974 802 % ================================================================ 803 % Double Diffusion Mixing 804 % ================================================================ 805 \section[Double diffusion mixing (\texttt{\textbf{key\_zdfddm}})] 806 {Double diffusion mixing (\protect\key{zdfddm})} 807 \label{sec:ZDF_ddm} 808 809 %-------------------------------------------namzdf_ddm------------------------------------------------- 810 % 975 %% ================================================================================================= 976 \section[Double diffusion mixing (\forcode{ln_zdfddm})]{Double diffusion mixing (\protect\np{ln_zdfddm}{ln\_zdfddm})} 977 \label{subsec:ZDF_ddm} 978 811 979 %\nlst{namzdf_ddm} 812 %-------------------------------------------------------------------------------------------------------------- 813 814 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}. 815 983 Double diffusion occurs when relatively warm, salty water overlies cooler, fresher water, or vice versa. 816 984 The former condition leads to salt fingering and the latter to diffusive convection. 817 985 Double-diffusive phenomena contribute to diapycnal mixing in extensive regions of the ocean. 818 \citet{merryfield.holloway.ea_JPO99} include a parameterisation of such phenomena in a global ocean model and show that 986 \citet{merryfield.holloway.ea_JPO99} include a parameterisation of such phenomena in a global ocean model and show that 819 987 it leads to relatively minor changes in circulation but exerts significant regional influences on 820 988 temperature and salinity. 821 This parameterisation has been introduced in \mdl{zdfddm} module and is controlled by the \key{zdfddm} CPP key. 822 823 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 824 991 \begin{align*} 825 % \label{eq: zdfddm_Kz}992 % \label{eq:ZDF_ddm_Kz} 826 993 &A^{vT} = A_o^{vT}+A_f^{vT}+A_d^{vT} \\ 827 994 &A^{vS} = A_o^{vS}+A_f^{vS}+A_d^{vS} … … 835 1002 (1981): 836 1003 \begin{align} 837 \label{eq: zdfddm_f}1004 \label{eq:ZDF_ddm_f} 838 1005 A_f^{vS} &= 839 1006 \begin{cases} … … 841 1008 0 &\text{otherwise} 842 1009 \end{cases} 843 \\ \label{eq: zdfddm_f_T}844 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 845 1012 \end{align} 846 1013 847 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>848 1014 \begin{figure}[!t] 849 \begin{center} 850 \includegraphics[width=\textwidth]{Fig_zdfddm} 851 \caption{ 852 \protect\label{fig:zdfddm} 853 From \citet{merryfield.holloway.ea_JPO99} : 854 (a) Diapycnal diffusivities $A_f^{vT}$ and $A_f^{vS}$ for temperature and salt in regions of salt fingering. 855 Heavy curves denote $A^{\ast v} = 10^{-3}~m^2.s^{-1}$ and thin curves $A^{\ast v} = 10^{-4}~m^2.s^{-1}$; 856 (b) diapycnal diffusivities $A_d^{vT}$ and $A_d^{vS}$ for temperature and salt in regions of 857 diffusive convection. 858 Heavy curves denote the Federov parameterisation and thin curves the Kelley parameterisation. 859 The latter is not implemented in \NEMO. 860 } 861 \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} 862 1029 \end{figure} 863 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 864 865 The factor 0.7 in \autoref{eq:zdfddm_f_T} reflects the measured ratio $\alpha F_T /\beta F_S \approx 0.7$ of 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 866 1032 buoyancy flux of heat to buoyancy flux of salt (\eg, \citet{mcdougall.taylor_JMR84}). 867 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}$. 868 1034 869 1035 To represent mixing of S and T by diffusive layering, the diapycnal diffusivities suggested by 870 Federov (1988) is used: 1036 Federov (1988) is used: 871 1037 \begin{align} 872 % \label{eq: zdfddm_d}1038 % \label{eq:ZDF_ddm_d} 873 1039 A_d^{vT} &= 874 1040 \begin{cases} … … 878 1044 \end{cases} 879 1045 \nonumber \\ 880 \label{eq: zdfddm_d_S}1046 \label{eq:ZDF_ddm_d_S} 881 1047 A_d^{vS} &= 882 1048 \begin{cases} … … 887 1053 \end{align} 888 1054 889 The dependencies of \autoref{eq: zdfddm_f} to \autoref{eq:zdfddm_d_S} on $R_\rho$ are illustrated in890 \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}. 891 1057 Implementing this requires computing $R_\rho$ at each grid point on every time step. 892 1058 This is done in \mdl{eosbn2} at the same time as $N^2$ is computed. 893 1059 This avoids duplication in the computation of $\alpha$ and $\beta$ (which is usually quite expensive). 894 1060 895 % ================================================================ 896 % Bottom Friction 897 % ================================================================ 898 \section[Bottom and top friction (\textit{zdfbfr.F90})] 899 {Bottom and top friction (\protect\mdl{zdfbfr})} 900 \label{sec:ZDF_bfr} 901 902 %--------------------------------------------nambfr-------------------------------------------------------- 903 % 904 %\nlst{nambfr} 905 %-------------------------------------------------------------------------------------------------------------- 906 907 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. 908 1082 The bottom friction represents the friction generated by the bathymetry. 909 1083 The top friction represents the friction generated by the ice shelf/ocean interface. 910 As the friction processes at the top and bottom are treated in similar way, 911 only the bottom friction is described in detail below. 912 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. 913 1086 914 1087 Both the surface momentum flux (wind stress) and the bottom momentum flux (bottom friction) enter the equations as 915 1088 a condition on the vertical diffusive flux. 916 1089 For the bottom boundary layer, one has: 917 \[918 % \label{eq:zdfbfr_flux}919 A^{vm} \left( \partial {\textbf U}_h / \partial z \right) = {{\cal F}}_h^{\textbf U}920 \]1090 \[ 1091 % \label{eq:ZDF_bfr_flux} 1092 A^{vm} \left( \partial {\textbf U}_h / \partial z \right) = {{\cal F}}_h^{\textbf U} 1093 \] 921 1094 where ${\cal F}_h^{\textbf U}$ is represents the downward flux of horizontal momentum outside 922 1095 the logarithmic turbulent boundary layer (thickness of the order of 1~m in the ocean). … … 926 1099 one needs a vertical diffusion coefficient $A^{vm} = 0.125$~m$^2$s$^{-1}$ 927 1100 (for a Coriolis frequency $f = 10^{-4}$~m$^2$s$^{-1}$). 928 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. 929 1102 When the vertical mixing coefficient is this small, using a flux condition is equivalent to 930 1103 entering the viscous forces (either wind stress or bottom friction) as a body force over the depth of the top or … … 932 1105 To illustrate this, consider the equation for $u$ at $k$, the last ocean level: 933 1106 \begin{equation} 934 \label{eq: zdfbfr_flux2}1107 \label{eq:ZDF_drg_flux2} 935 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}} 936 1109 \end{equation} … … 945 1118 946 1119 In the code, the bottom friction is imposed by adding the trend due to the bottom friction to 947 the general momentum trend in \mdl{dynbfr}.1120 the general momentum trend in \mdl{dynzdf}. 948 1121 For the time-split surface pressure gradient algorithm, the momentum trend due to 949 1122 the barotropic component needs to be handled separately. 950 1123 For this purpose it is convenient to compute and store coefficients which can be simply combined with 951 1124 bottom velocities and geometric values to provide the momentum trend due to bottom friction. 952 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: 953 1126 \begin{equation} 954 \label{eq: zdfbfr_bdef}1127 \label{eq:ZDF_bfr_bdef} 955 1128 \frac{\partial {\textbf U_h}}{\partial t} = 956 1129 - \frac{{\cal F}^{\textbf U}_{h}}{e_{3u}} = \frac{c_b^{\textbf U}}{e_{3u}} \;{\textbf U}_h^b 957 1130 \end{equation} 958 1131 where $\textbf{U}_h^b = (u_b\;,\;v_b)$ is the near-bottom, horizontal, ocean velocity. 959 960 % ------------------------------------------------------------------------------------------------------------- 961 % Linear Bottom Friction 962 % ------------------------------------------------------------------------------------------------------------- 963 \subsection[Linear bottom friction (\forcode{nn_botfr = [01]})] 964 {Linear bottom friction (\protect\np{nn\_botfr}\forcode{ = [01])}} 965 \label{subsec:ZDF_bfr_linear} 966 967 The linear bottom friction parameterisation (including the special case of a free-slip condition) assumes that 968 the bottom friction is proportional to the interior velocity (\ie the velocity of the last model level): 969 \[ 970 % \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} 971 1142 {\cal F}_h^\textbf{U} = \frac{A^{vm}}{e_3} \; \frac{\partial \textbf{U}_h}{\partial k} = r \; \textbf{U}_h^b 972 1143 \] 973 where $r$ is a friction coefficient expressed in ms$^{-1}$.974 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, 975 1146 and setting $r = H / \tau$, where $H$ is the ocean depth. 976 1147 Commonly accepted values of $\tau$ are of the order of 100 to 200 days \citep{weatherly_JMR84}. … … 981 1152 and assuming an ocean depth $H = 4000$~m, the resulting friction coefficient is $r = 4\;10^{-4}$~m\;s$^{-1}$. 982 1153 This is the default value used in \NEMO. It corresponds to a decay time scale of 115~days. 983 It can be changed by specifying \np{rn\_bfri1} (namelist parameter). 984 985 For the linear friction case the coefficients defined in the general expression \autoref{eq:zdfbfr_bdef} are: 986 \[ 987 % \label{eq:zdfbfr_linbfr_b} 988 \begin{split} 989 c_b^u &= - r\\ 990 c_b^v &= - r\\ 991 \end{split} 992 \] 993 When \np{nn\_botfr}\forcode{ = 1}, the value of $r$ used is \np{rn\_bfri1}. 994 Setting \np{nn\_botfr}\forcode{ = 0} is equivalent to setting $r=0$ and 995 leads to a free-slip bottom boundary condition. 996 These values are assigned in \mdl{zdfbfr}. 997 From v3.2 onwards there is support for local enhancement of these values via an externally defined 2D mask array 998 (\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. 999 1167 The mask values should vary from 0 to 1. 1000 1168 Locations with a non-zero mask value will have the friction coefficient increased by 1001 $mask\_value$*\np{rn\_bfrien}*\np{rn\_bfri1}. 1002 1003 % ------------------------------------------------------------------------------------------------------------- 1004 % Non-Linear Bottom Friction 1005 % ------------------------------------------------------------------------------------------------------------- 1006 \subsection[Non-linear bottom friction (\forcode{nn_botfr = 2})] 1007 {Non-linear bottom friction (\protect\np{nn\_botfr}\forcode{ = 2})} 1008 \label{subsec:ZDF_bfr_nonlinear} 1009 1010 The non-linear bottom friction parameterisation assumes that the bottom friction is quadratic: 1011 \[ 1012 % \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} 1013 1178 {\cal F}_h^\textbf{U} = \frac{A^{vm}}{e_3 }\frac{\partial \textbf {U}_h 1014 1179 }{\partial k}=C_D \;\sqrt {u_b ^2+v_b ^2+e_b } \;\; \textbf {U}_h^b 1015 1180 \] 1016 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, 1017 1182 internal waves breaking and other short time scale currents. 1018 1183 A typical value of the drag coefficient is $C_D = 10^{-3} $. … … 1020 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 1021 1186 $e_b =2.5\;\;10^{-3}$m$^2$\;s$^{-2}$. 1022 The CME choices have been set as default values (\np{rn\_bfri2} and \np{rn\_bfeb2} namelist parameters). 1023 1024 As for the linear case, the bottom friction is imposed in the code by adding the trend due to 1025 the bottom friction to the general momentum trend in \mdl{dynbfr}. 1026 For the non-linear friction case the terms computed in \mdl{zdfbfr} are: 1027 \[ 1028 % \label{eq:zdfbfr_nonlinbfr} 1029 \begin{split} 1030 c_b^u &= - \; C_D\;\left[ u^2 + \left(\bar{\bar{v}}^{i+1,j}\right)^2 + e_b \right]^{1/2}\\ 1031 c_b^v &= - \; C_D\;\left[ \left(\bar{\bar{u}}^{i,j+1}\right)^2 + v^2 + e_b \right]^{1/2}\\ 1032 \end{split} 1033 \] 1034 1035 The coefficients that control the strength of the non-linear bottom friction are initialised as namelist parameters: 1036 $C_D$= \np{rn\_bfri2}, and $e_b$ =\np{rn\_bfeb2}. 1037 Note for applications which treat tides explicitly a low or even zero value of \np{rn\_bfeb2} is recommended. 1038 From v3.2 onwards a local enhancement of $C_D$ is possible via an externally defined 2D mask array 1039 (\np{ln\_bfr2d}\forcode{ = .true.}). 1040 This works in the same way as for the linear bottom friction case with non-zero masked locations increased by 1041 $mask\_value$*\np{rn\_bfrien}*\np{rn\_bfri2}. 1042 1043 % ------------------------------------------------------------------------------------------------------------- 1044 % Bottom Friction Log-layer 1045 % ------------------------------------------------------------------------------------------------------------- 1046 \subsection[Log-layer bottom friction enhancement (\forcode{nn_botfr = 2}, \forcode{ln_loglayer = .true.})] 1047 {Log-layer bottom friction enhancement (\protect\np{nn\_botfr}\forcode{ = 2}, \protect\np{ln\_loglayer}\forcode{ = .true.})} 1048 \label{subsec:ZDF_bfr_loglayer} 1049 1050 In the non-linear bottom friction case, the drag coefficient, $C_D$, can be optionally enhanced using 1051 a "law of the wall" scaling. 1052 If \np{ln\_loglayer} = .true., $C_D$ is no longer constant but is related to the thickness of 1053 the last wet layer in each column by: 1054 \[ 1055 C_D = \left ( {\kappa \over {\mathrm log}\left ( 0.5e_{3t}/rn\_bfrz0 \right ) } \right )^2 1056 \] 1057 1058 \noindent where $\kappa$ is the von-Karman constant and \np{rn\_bfrz0} is a roughness length provided via 1059 the namelist. 1060 1061 For stability, the drag coefficient is bounded such that it is kept greater or equal to 1062 the base \np{rn\_bfri2} value and it is not allowed to exceed the value of an additional namelist parameter: 1063 \np{rn\_bfri2\_max}, \ie 1064 \[ 1065 rn\_bfri2 \leq C_D \leq rn\_bfri2\_max 1066 \] 1067 1068 \noindent Note also that a log-layer enhancement can also be applied to the top boundary friction if 1069 under ice-shelf cavities are in use (\np{ln\_isfcav}\forcode{ = .true.}). 1070 In this case, the relevant namelist parameters are \np{rn\_tfrz0}, \np{rn\_tfri2} and \np{rn\_tfri2\_max}. 1071 1072 % ------------------------------------------------------------------------------------------------------------- 1073 % Bottom Friction stability 1074 % ------------------------------------------------------------------------------------------------------------- 1075 \subsection{Bottom friction stability considerations} 1076 \label{subsec:ZDF_bfr_stability} 1077 1078 Some care needs to exercised over the choice of parameters to ensure that the implementation of 1079 bottom friction does not induce numerical instability. 1080 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: 1081 1248 \begin{equation} 1082 \label{eq: Eqn_bfrstab}1249 \label{eq:ZDF_Eqn_drgstab} 1083 1250 \begin{split} 1084 1251 \Delta u &= -\frac{{{\cal F}_h}^u}{e_{3u}}\;2 \rdt \\ … … 1086 1253 \end{split} 1087 1254 \end{equation} 1088 \noindent where linear bottomfriction and a leapfrog timestep have been assumed.1089 To ensure that the bottomfriction cannot reverse the direction of flow it is necessary to have:1090 \[ 1091 |\Delta u| < \;|u| 1092 \] 1093 \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: 1094 1261 \[ 1095 1262 r\frac{2\rdt}{e_{3u}} < 1 \qquad \Rightarrow \qquad r < \frac{e_{3u}}{2\rdt}\\ … … 1104 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. 1105 1272 For most applications, with physically sensible parameters these restrictions should not be of concern. 1106 But caution may be necessary if attempts are made to locally enhance the bottom friction parameters. 1107 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 1108 1275 during initialisation and at each time step. 1109 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). 1110 1277 The number of breaches of the stability criterion are reported as well as 1111 1278 the minimum and maximum values that have been set. 1112 The criterion is also checked at each time step, using the actual velocity, in \mdl{dyn bfr}.1113 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; 1114 1281 these changes are not reported. 1115 1282 1116 Limits on the bottom friction coefficient are not imposed if the user has elected to1117 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}). 1118 1285 The number of potential breaches of the explicit stability criterion are still reported for information purposes. 1119 1286 1120 % ------------------------------------------------------------------------------------------------------------- 1121 % Implicit Bottom Friction 1122 % ------------------------------------------------------------------------------------------------------------- 1123 \subsection[Implicit bottom friction (\forcode{ln_bfrimp = .true.})] 1124 {Implicit bottom friction (\protect\np{ln\_bfrimp}\forcode{ = .true.})} 1125 \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} 1126 1290 1127 1291 An optional implicit form of bottom friction has been implemented to improve model stability. 1128 We recommend this option for shelf sea and coastal ocean applications, especially for split-explicit time splitting. 1129 This option can be invoked by setting \np{ln\_bfrimp} to \forcode{.true.} in the \textit{nambfr} namelist. 1130 This option requires \np{ln\_zdfexp} to be \forcode{.false.} in the \textit{namzdf} namelist. 1131 1132 This implementation is realised in \mdl{dynzdf\_imp} and \mdl{dynspg\_ts}. In \mdl{dynzdf\_imp}, 1133 the bottom boundary condition is implemented implicitly. 1134 1135 \[ 1136 % \label{eq:dynzdf_bfr} 1137 \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{mbk} 1138 = \binom{c_{b}^{u}u^{n+1}_{mbk}}{c_{b}^{v}v^{n+1}_{mbk}} 1139 \] 1140 1141 where $mbk$ is the layer number of the bottom wet layer. 1142 Superscript $n+1$ means the velocity used in the friction formula is to be calculated, so, it is implicit. 1143 1144 If split-explicit time splitting is used, care must be taken to avoid the double counting of the bottom friction in 1145 the 2-D barotropic momentum equations. 1146 As NEMO only updates the barotropic pressure gradient and Coriolis' forcing terms in the 2-D barotropic calculation, 1147 we need to remove the bottom friction induced by these two terms which has been included in the 3-D momentum trend 1148 and update it with the latest value. 1149 On the other hand, the bottom friction contributed by the other terms 1150 (\eg the advection term, viscosity term) has been included in the 3-D momentum equations and 1151 should not be added in the 2-D barotropic mode. 1152 1153 The implementation of the implicit bottom friction in \mdl{dynspg\_ts} is done in two steps as the following: 1154 1155 \[ 1156 % \label{eq:dynspg_ts_bfr1} 1157 \frac{\textbf{U}_{med}-\textbf{U}^{m-1}}{2\Delta t}=-g\nabla\eta-f\textbf{k}\times\textbf{U}^{m}+c_{b} 1158 \left(\textbf{U}_{med}-\textbf{U}^{m-1}\right) 1159 \] 1160 \[ 1161 \frac{\textbf{U}^{m+1}-\textbf{U}_{med}}{2\Delta t}=\textbf{T}+ 1162 \left(g\nabla\eta^{'}+f\textbf{k}\times\textbf{U}^{'}\right)- 1163 2\Delta t_{bc}c_{b}\left(g\nabla\eta^{'}+f\textbf{k}\times\textbf{u}_{b}\right) 1164 \] 1165 1166 where $\textbf{T}$ is the vertical integrated 3-D momentum trend. 1167 We assume the leap-frog time-stepping is used here. 1168 $\Delta t$ is the barotropic mode time step and $\Delta t_{bc}$ is the baroclinic mode time step. 1169 $c_{b}$ is the friction coefficient. 1170 $\eta$ is the sea surface level calculated in the barotropic loops while $\eta^{'}$ is the sea surface level used in 1171 the 3-D baroclinic mode. 1172 $\textbf{u}_{b}$ is the bottom layer horizontal velocity. 1173 1174 % ------------------------------------------------------------------------------------------------------------- 1175 % Bottom Friction with split-explicit time splitting 1176 % ------------------------------------------------------------------------------------------------------------- 1177 \subsection[Bottom friction with split-explicit time splitting (\texttt{ln\_bfrimp})] 1178 {Bottom friction with split-explicit time splitting (\protect\np{ln\_bfrimp})} 1179 \label{subsec:ZDF_bfr_ts} 1180 1181 When calculating the momentum trend due to bottom friction in \mdl{dynbfr}, 1182 the bottom velocity at the before time step is used. 1183 This velocity includes both the baroclinic and barotropic components which is appropriate when 1184 using either the explicit or filtered surface pressure gradient algorithms 1185 (\key{dynspg\_exp} or \key{dynspg\_flt}). 1186 Extra attention is required, however, when using split-explicit time stepping (\key{dynspg\_ts}). 1187 In this case the free surface equation is solved with a small time step \np{rn\_rdt}/\np{nn\_baro}, 1188 while the three dimensional prognostic variables are solved with the longer time step of \np{rn\_rdt} seconds. 1189 The trend in the barotropic momentum due to bottom friction appropriate to this method is that given by 1190 the selected parameterisation (\ie linear or non-linear bottom friction) computed with 1191 the evolving velocities at each barotropic timestep. 1192 1193 In the case of non-linear bottom friction, we have elected to partially linearise the problem by 1194 keeping the coefficients fixed throughout the barotropic time-stepping to those computed in 1195 \mdl{zdfbfr} using the now timestep. 1196 This decision allows an efficient use of the $c_b^{\vect{U}}$ coefficients to: 1197 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: 1198 1322 \begin{enumerate} 1199 \item On entry to \rou{dyn\_spg\_ts}, remove the contribution of the before barotropic velocity to 1200 the bottom friction component of the vertically integrated momentum trend. 1201 Note the same stability check that is carried out on the bottom friction coefficient in \mdl{dynbfr} has to 1202 be applied here to ensure that the trend removed matches that which was added in \mdl{dynbfr}. 1203 \item At each barotropic step, compute the contribution of the current barotropic velocity to 1204 the trend due to bottom friction. 1205 Add this contribution to the vertically integrated momentum trend. 1206 This contribution is handled implicitly which eliminates the need to impose a stability criteria on 1207 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. 1208 1325 \end{enumerate} 1209 1326 1210 Note that the use of an implicit formulation within the barotropic loop for the bottom friction trend means that 1211 any limiting of the bottom friction coefficient in \mdl{dynbfr} does not adversely affect the solution when 1212 using split-explicit time splitting. 1213 This is because the major contribution to bottom friction is likely to come from the barotropic component which 1214 uses the unrestricted value of the coefficient. 1215 However, if the limiting is thought to be having a major effect 1216 (a more likely prospect in coastal and shelf seas applications) then 1217 the fully implicit form of the bottom friction should be used (see \autoref{subsec:ZDF_bfr_imp}) 1218 which can be selected by setting \np{ln\_bfrimp} $=$ \forcode{.true.}. 1219 1220 Otherwise, the implicit formulation takes the form: 1221 \[ 1222 % \label{eq:zdfbfr_implicitts} 1223 \bar{U}^{t+ \rdt} = \; \left [ \bar{U}^{t-\rdt}\; + 2 \rdt\;RHS \right ] / \left [ 1 - 2 \rdt \;c_b^{u} / H_e \right ] 1224 \] 1225 where $\bar U$ is the barotropic velocity, $H_e$ is the full depth (including sea surface height), 1226 $c_b^u$ is the bottom friction coefficient as calculated in \rou{zdf\_bfr} and 1227 $RHS$ represents all the components to the vertically integrated momentum trend except for 1228 that due to bottom friction. 1229 1230 % ================================================================ 1231 % Tidal Mixing 1232 % ================================================================ 1233 \section[Tidal mixing (\texttt{\textbf{key\_zdftmx}})] 1234 {Tidal mixing (\protect\key{zdftmx})} 1235 \label{sec:ZDF_tmx} 1236 1237 %--------------------------------------------namzdf_tmx-------------------------------------------------- 1238 % 1239 %\nlst{namzdf_tmx} 1240 %-------------------------------------------------------------------------------------------------------------- 1241 1242 1243 % ------------------------------------------------------------------------------------------------------------- 1244 % Bottom intensified tidal mixing 1245 % ------------------------------------------------------------------------------------------------------------- 1246 \subsection{Bottom intensified tidal mixing} 1247 \label{subsec:ZDF_tmx_bottom} 1248 1249 Options are defined through the \ngn{namzdf\_tmx} namelist variables. 1250 The parameterization of tidal mixing follows the general formulation for the vertical eddy diffusivity proposed by 1251 \citet{st-laurent.simmons.ea_GRL02} and first introduced in an OGCM by \citep{simmons.jayne.ea_OM04}. 1252 In this formulation an additional vertical diffusivity resulting from internal tide breaking, 1253 $A^{vT}_{tides}$ is expressed as a function of $E(x,y)$, 1254 the energy transfer from barotropic tides to baroclinic tides: 1255 \begin{equation} 1256 \label{eq:Ktides} 1257 A^{vT}_{tides} = q \,\Gamma \,\frac{ E(x,y) \, F(z) }{ \rho \, N^2 } 1258 \end{equation} 1259 where $\Gamma$ is the mixing efficiency, $N$ the Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}), 1260 $\rho$ the density, $q$ the tidal dissipation efficiency, and $F(z)$ the vertical structure function. 1261 1262 The mixing efficiency of turbulence is set by $\Gamma$ (\np{rn\_me} namelist parameter) and 1263 is usually taken to be the canonical value of $\Gamma = 0.2$ (Osborn 1980). 1264 The tidal dissipation efficiency is given by the parameter $q$ (\np{rn\_tfe} namelist parameter) 1265 represents the part of the internal wave energy flux $E(x, y)$ that is dissipated locally, 1266 with the remaining $1-q$ radiating away as low mode internal waves and 1267 contributing to the background internal wave field. 1268 A value of $q=1/3$ is typically used \citet{st-laurent.simmons.ea_GRL02}. 1269 The vertical structure function $F(z)$ models the distribution of the turbulent mixing in the vertical. 1270 It is implemented as a simple exponential decaying upward away from the bottom, 1271 with a vertical scale of $h_o$ (\np{rn\_htmx} namelist parameter, 1272 with a typical value of $500\,m$) \citep{st-laurent.nash_DSR04}, 1273 \[ 1274 % \label{eq:Fz} 1275 F(i,j,k) = \frac{ e^{ -\frac{H+z}{h_o} } }{ h_o \left( 1- e^{ -\frac{H}{h_o} } \right) } 1276 \] 1277 and is normalized so that vertical integral over the water column is unity. 1278 1279 The associated vertical viscosity is calculated from the vertical diffusivity assuming a Prandtl number of 1, 1280 \ie $A^{vm}_{tides}=A^{vT}_{tides}$. 1281 In the limit of $N \rightarrow 0$ (or becoming negative), the vertical diffusivity is capped at $300\,cm^2/s$ and 1282 impose a lower limit on $N^2$ of \np{rn\_n2min} usually set to $10^{-8} s^{-2}$. 1283 These bounds are usually rarely encountered. 1284 1285 The internal wave energy map, $E(x, y)$ in \autoref{eq:Ktides}, is derived from a barotropic model of 1286 the tides utilizing a parameterization of the conversion of barotropic tidal energy into internal waves. 1287 The essential goal of the parameterization is to represent the momentum exchange between the barotropic tides and 1288 the unrepresented internal waves induced by the tidal flow over rough topography in a stratified ocean. 1289 In the current version of \NEMO, the map is built from the output of 1290 the barotropic global ocean tide model MOG2D-G \citep{carrere.lyard_GRL03}. 1291 This model provides the dissipation associated with internal wave energy for the M2 and K1 tides component 1292 (\autoref{fig:ZDF_M2_K1_tmx}). 1293 The S2 dissipation is simply approximated as being $1/4$ of the M2 one. 1294 The internal wave energy is thus : $E(x, y) = 1.25 E_{M2} + E_{K1}$. 1295 Its global mean value is $1.1$ TW, 1296 in agreement with independent estimates \citep{egbert.ray_N00, egbert.ray_JGR01}. 1297 1298 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1299 \begin{figure}[!t] 1300 \begin{center} 1301 \includegraphics[width=\textwidth]{Fig_ZDF_M2_K1_tmx} 1302 \caption{ 1303 \protect\label{fig:ZDF_M2_K1_tmx} 1304 (a) M2 and (b) K1 internal wave drag energy from \citet{carrere.lyard_GRL03} ($W/m^2$). 1305 } 1306 \end{center} 1307 \end{figure} 1308 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 1309 1310 % ------------------------------------------------------------------------------------------------------------- 1311 % Indonesian area specific treatment 1312 % ------------------------------------------------------------------------------------------------------------- 1313 \subsection[Indonesian area specific treatment (\texttt{ln\_zdftmx\_itf})] 1314 {Indonesian area specific treatment (\protect\np{ln\_zdftmx\_itf})} 1315 \label{subsec:ZDF_tmx_itf} 1316 1317 When the Indonesian Through Flow (ITF) area is included in the model domain, 1318 a specific treatment of tidal induced mixing in this area can be used. 1319 It is activated through the namelist logical \np{ln\_tmx\_itf}, and the user must provide an input NetCDF file, 1320 \ifile{mask\_itf}, which contains a mask array defining the ITF area where the specific treatment is applied. 1321 1322 When \np{ln\_tmx\_itf}\forcode{ = .true.}, the two key parameters $q$ and $F(z)$ are adjusted following 1323 the parameterisation developed by \citet{koch-larrouy.madec.ea_GRL07}: 1324 1325 First, the Indonesian archipelago is a complex geographic region with a series of 1326 large, deep, semi-enclosed basins connected via numerous narrow straits. 1327 Once generated, internal tides remain confined within this semi-enclosed area and hardly radiate away. 1328 Therefore all the internal tides energy is consumed within this area. 1329 So it is assumed that $q = 1$, \ie all the energy generated is available for mixing. 1330 Note that for test purposed, the ITF tidal dissipation efficiency is a namelist parameter (\np{rn\_tfe\_itf}). 1331 A value of $1$ or close to is this recommended for this parameter. 1332 1333 Second, the vertical structure function, $F(z)$, is no more associated with a bottom intensification of the mixing, 1334 but with a maximum of energy available within the thermocline. 1335 \citet{koch-larrouy.madec.ea_GRL07} have suggested that the vertical distribution of 1336 the energy dissipation proportional to $N^2$ below the core of the thermocline and to $N$ above. 1337 The resulting $F(z)$ is: 1338 \[ 1339 % \label{eq:Fz_itf} 1340 F(i,j,k) \sim \left\{ 1341 \begin{aligned} 1342 \frac{q\,\Gamma E(i,j) } {\rho N \, \int N dz} \qquad \text{when $\partial_z N < 0$} \\ 1343 \frac{q\,\Gamma E(i,j) } {\rho \, \int N^2 dz} \qquad \text{when $\partial_z N > 0$} 1344 \end{aligned} 1345 \right. 1346 \] 1347 1348 Averaged over the ITF area, the resulting tidal mixing coefficient is $1.5\,cm^2/s$, 1349 which agrees with the independent estimates inferred from observations. 1350 Introduced in a regional OGCM, the parameterization improves the water mass characteristics in 1351 the different Indonesian seas, suggesting that the horizontal and vertical distributions of 1352 the mixing are adequately prescribed \citep{koch-larrouy.madec.ea_GRL07, koch-larrouy.madec.ea_OD08*a, koch-larrouy.madec.ea_OD08*b}. 1353 Note also that such a parameterisation has a significant impact on the behaviour of 1354 global coupled GCMs \citep{koch-larrouy.lengaigne.ea_CD10}. 1355 1356 % ================================================================ 1357 % Internal wave-driven mixing 1358 % ================================================================ 1359 \section[Internal wave-driven mixing (\texttt{\textbf{key\_zdftmx\_new}})] 1360 {Internal wave-driven mixing (\protect\key{zdftmx\_new})} 1361 \label{sec:ZDF_tmx_new} 1362 1363 %--------------------------------------------namzdf_tmx_new------------------------------------------ 1364 % 1365 %\nlst{namzdf_tmx_new} 1366 %-------------------------------------------------------------------------------------------------------------- 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} 1367 1338 1368 1339 The parameterization of mixing induced by breaking internal waves is a generalization of 1369 1340 the approach originally proposed by \citet{st-laurent.simmons.ea_GRL02}. 1370 1341 A three-dimensional field of internal wave energy dissipation $\epsilon(x,y,z)$ is first constructed, 1371 and the resulting diffusivity is obtained as 1372 \[ 1373 % \label{eq: Kwave}1342 and the resulting diffusivity is obtained as 1343 \[ 1344 % \label{eq:ZDF_Kwave} 1374 1345 A^{vT}_{wave} = R_f \,\frac{ \epsilon }{ \rho \, N^2 } 1375 1346 \] 1376 1347 where $R_f$ is the mixing efficiency and $\epsilon$ is a specified three dimensional distribution of 1377 1348 the energy available for mixing. 1378 If the \np{ln \_mevar} namelist parameter is set to false, the mixing efficiency is taken as constant and1349 If the \np{ln_mevar}{ln\_mevar} namelist parameter is set to \forcode{.false.}, the mixing efficiency is taken as constant and 1379 1350 equal to 1/6 \citep{osborn_JPO80}. 1380 1351 In the opposite (recommended) case, $R_f$ is instead a function of … … 1385 1356 the mixing efficiency is constant. 1386 1357 1387 In addition to the mixing efficiency, the ratio of salt to heat diffusivities can chosen to vary 1388 as a function of $Re_b$ by setting the \np{ln \_tsdiff} parameter to true, a recommended choice.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. 1389 1360 This parameterization of differential mixing, due to \cite{jackson.rehmann_JPO14}, 1390 1361 is implemented as in \cite{de-lavergne.madec.ea_JPO16}. … … 1392 1363 The three-dimensional distribution of the energy available for mixing, $\epsilon(i,j,k)$, 1393 1364 is constructed from three static maps of column-integrated internal wave energy dissipation, 1394 $E_{cri}(i,j)$, $E_{pyc}(i,j)$, and $E_{bot}(i,j)$, combined to three corresponding vertical structures 1395 (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 1396 1367 \begin{align*} 1397 1368 F_{cri}(i,j,k) &\propto e^{-h_{ab} / h_{cri} }\\ 1398 F_{pyc}(i,j,k) &\propto N^{n \_p}\\1369 F_{pyc}(i,j,k) &\propto N^{n_p}\\ 1399 1370 F_{bot}(i,j,k) &\propto N^2 \, e^{- h_{wkb} / h_{bot} } 1400 \end{align*} 1371 \end{align*} 1401 1372 In the above formula, $h_{ab}$ denotes the height above bottom, 1402 1373 $h_{wkb}$ denotes the WKB-stretched height above bottom, defined by … … 1404 1375 h_{wkb} = H \, \frac{ \int_{-H}^{z} N \, dz' } { \int_{-H}^{\eta} N \, dz' } \; , 1405 1376 \] 1406 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) 1407 1378 controls the stratification-dependence of the pycnocline-intensified dissipation. 1408 It can take values of 1 (recommended) or 2.1379 It can take values of $1$ (recommended) or $2$. 1409 1380 Finally, the vertical structures $F_{cri}$ and $F_{bot}$ require the specification of 1410 1381 the decay scales $h_{cri}(i,j)$ and $h_{bot}(i,j)$, which are defined by two additional input maps. … … 1412 1383 $h_{bot}$ is a function of the energy flux $E_{bot}$, the characteristic horizontal scale of 1413 1384 the abyssal hill topography \citep{goff_JGR10} and the latitude. 1414 1415 % ================================================================ 1416 1417 \biblio 1418 1419 \pindex 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}} 1420 1646 1421 1647 \end{document} -
NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_conservation.tex
r11151 r12149 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. … … 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. … … 41 56 \citep{Marti1992?, Levy1996?, Levy1998?}. 42 57 43 % ------------------------------------------------------------------------------------------------------------- 44 % Conservation Properties on Ocean Dynamics 45 % ------------------------------------------------------------------------------------------------------------- 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 80 \;{\mathrm {\mathbf k}}\times {\textbf {U}}_h } \right)\;dv} =0 … … 69 82 70 83 \[ 71 % \label{eq: vor_enstrophy}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}199 % \label{eq:CONS_dynldf_dyn} 191 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 … … 195 204 196 205 \[ 197 % \label{eq: dynldf_div}206 % \label{eq:CONS_dynldf_div} 198 207 \int\limits_D {\nabla _h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi } 199 208 \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} … … 202 211 203 212 \[ 204 % \label{eq: dynldf_curl}213 % \label{eq:CONS_dynldf_curl} 205 214 \int_D {{\mathrm {\mathbf U}}_h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi } 206 215 \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} … … 209 218 210 219 \[ 211 % \label{eq: dynldf_curl2}220 % \label{eq:CONS_dynldf_curl2} 212 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 … … 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 231 {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} \right]\;dv} \leqslant 0 223 232 \] 224 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}268 % \label{eq:CONS_dynzdf_vor} 261 269 \begin{aligned} 262 270 & \int_D {\frac{1}{e_3 }{\mathrm {\mathbf k}}\cdot \nabla \times \left( {\frac{1}{e_3 … … 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 … … 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/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_misc.tex
r11179 r12149 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=\textwidth]{Fig_Gibraltar} 66 \includegraphics[width=\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=\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 (\textit{closea.F90})] 105 {Closed seas (\protect\mdl{closea})} 124 125 %% ================================================================================================= 126 \section[Closed seas (\textit{closea.F90})]{Closed seas (\protect\mdl{closea})} 106 127 \label{sec:MISC_closea} 107 128 … … 117 138 to zero and put the residual flux into the ocean. 118 139 119 Prior to NEMO4 the locations of inland seas and lakes was set via120 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 121 142 the inland seas and lakes are defined using mask fields in the 122 143 domain configuration file. The options are as follows. 123 144 124 145 \begin{enumerate} 125 \item {{\bfseries No ``closea\_mask'' field is included in domain configuration146 \item {{\bfseries No ``closea\_mask'' field is included in domain configuration 126 147 file.} In this case the closea module does nothing.} 127 148 128 \item {{\bfseries A field called closea\_mask is included in the domain149 \item {{\bfseries A field called closea\_mask is included in the domain 129 150 configuration file and ln\_closea=.false. in namelist namcfg.} In this 130 151 case the inland seas defined by the closea\_mask field are filled in … … 132 153 closea\_mask that is nonzero is set to be a land point.} 133 154 134 \item {{\bfseries A field called closea\_mask is included in the domain155 \item {{\bfseries A field called closea\_mask is included in the domain 135 156 configuration file and ln\_closea=.true. in namelist namcfg.} Each 136 157 inland sea or group of inland seas is set to a positive integer value 137 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} 138 159 for an example). The net surface flux over each inland sea or group of 139 160 inland seas is set to zero each timestep and the residual flux is … … 141 162 closea\_mask is zero).} 142 163 143 \item {{\bfseries Fields called closea\_mask and closea\_mask\_rnf are164 \item {{\bfseries Fields called closea\_mask and closea\_mask\_rnf are 144 165 included in the domain configuration file and ln\_closea=.true. in 145 166 namelist namcfg.} This option works as for option 3, except that if … … 150 171 by the closea\_mask\_rnf field. Each mapping is defined by a positive 151 172 integer value for the inland sea(s) and the corresponding runoff 152 points. An example is given in Figure153 \ 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 154 175 particular inland sea then the residual is spread over the global 155 176 ocean.} 156 177 157 \item {{\bfseries Fields called closea\_mask and closea\_mask\_emp are178 \item {{\bfseries Fields called closea\_mask and closea\_mask\_emp are 158 179 included in the domain configuration file and ln\_closea=.true. in 159 180 namelist namcfg.} This option works the same as option 4 except that … … 165 186 166 187 There is a python routine to create the closea\_mask fields and append 167 them to the domain configuration file in the utils/tools/DOMAINcfg directory. 168 169 % ================================================================ 170 % Sub-Domain Functionality 171 % ================================================================ 188 them to the domain configuration file in the utils/tools/DOMAINcfg directory. 189 190 %% ================================================================================================= 172 191 \section{Sub-domain functionality} 173 192 \label{sec:MISC_zoom} 174 193 194 %% ================================================================================================= 175 195 \subsection{Simple subsetting of input files via NetCDF attributes} 176 196 177 The extended grids for use with the under-shelf ice cavities will result in redundant rows around Antarctica if 178 the ice cavities are not active. 179 A simple mechanism for subsetting input files associated with the extended domains has been implemented to 180 avoid the need to maintain different sets of input fields for use with or without active ice cavities. 181 The existing 'zoom' options are overly complex for this task and marked for deletion anyway. 182 This alternative subsetting operates for the j-direction only and works by optionally looking for and 183 using a global file attribute (named: \np{open\_ocean\_jstart}) to determine the starting j-row for input. 184 The use of this option is best explained with an example: 185 consider an ORCA1 configuration using the extended grid bathymetry and coordinate files: 186 \vspace{-10pt} 187 \ifile{eORCA1\_bathymetry\_v2} 188 \ifile{eORCA1\_coordinates} 189 \noindent These files define a horizontal domain of 362x332. 190 Assuming the first row with open ocean wet points in the non-isf bathymetry for this set is row 42 191 (\fortran indexing) then the formally correct setting for \np{open\_ocean\_jstart} is 41. 192 Using this value as the first row to be read will result in a 362x292 domain which is the same size as 193 the original ORCA1 domain. 194 Thus the extended coordinates and bathymetry files can be used with all the original input files for ORCA1 if 195 the ice cavities are not active (\np{ln\_isfcav = .false.}). 196 Full instructions for achieving this are: 197 198 \noindent Add the new attribute to any input files requiring a j-row offset, i.e: 199 \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: 200 218 \begin{cmds} 201 ncatted -a open_ocean_jstart,global,a,d,41 eORCA1_coordinates.nc 202 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 203 220 \end{cmds} 204 205 \noindent Add the logical switch to \ngn{namcfg} in the configuration namelist and set true: 206 %--------------------------------------------namcfg-------------------------------------------------------- 207 208 \nlst{namcfg} 209 %-------------------------------------------------------------------------------------------------------------- 210 211 \noindent Note the j-size of the global domain is the (extended j-size minus \np{open\_ocean\_jstart} + 1 ) and 212 this must match the size of all datasets other than bathymetry and coordinates currently. 213 However the option can be extended to any global, 2D and 3D, netcdf, input field by adding the: 214 \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 215 243 \begin{forlines} 216 244 lrowattr=ln_use_jattr 217 245 \end{forlines} 218 optional argument to the appropriate \np{iom\_get} call and the \np{open\_ocean\_jstart} attribute to 219 the corresponding input files. 220 It remains the users responsibility to set \np{jpjdta} and \np{jpjglo} values in 221 the \np{namelist\_cfg} file according to their needs. 222 223 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 224 \begin{figure}[!ht] 225 \begin{center} 226 \includegraphics[width=\textwidth]{Fig_LBC_zoom} 227 \caption{ 228 \protect\label{fig:LBC_zoom} 229 Position of a model domain compared to the data input domain when the zoom functionality is used. 230 } 231 \end{center} 232 \end{figure} 233 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 234 235 236 % ================================================================ 237 % Accuracy and Reproducibility 238 % ================================================================ 239 \section[Accuracy and reproducibility (\textit{lib\_fortran.F90})] 240 {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})} 241 257 \label{sec:MISC_fortran} 242 258 243 \subsection[Issues with intrinsinc SIGN function (\texttt{\textbf{key\_nosignedzero}})] 244 {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})} 245 261 \label{subsec:MISC_sign} 246 262 247 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. 248 264 For example, SIGN(-3.0,2.0) has the value 3.0. 249 265 The problematic case is when the second argument is zero, because, on platforms that support IEEE arithmetic, … … 257 273 and the processor is capable of distinguishing between positive and negative zero, 258 274 and B is negative real zero. 259 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. 260 276 This change may be especially sensitive for the ice model, 261 277 so we overwrite the intrinsinc function with our own function simply performing : \\ … … 267 283 some computers/compilers. 268 284 269 285 %% ================================================================================================= 270 286 \subsection{MPP reproducibility} 271 287 \label{subsec:MISC_glosum} 272 288 273 289 The numerical reproducibility of simulations on distributed memory parallel computers is a critical issue. 274 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, 275 291 and their propagation and accumulation cause uncertainty in final simulation reproducibility on 276 292 different numbers of processors. 277 293 To avoid so, based on \citet{he.ding_JS01} review of different technics, 278 294 we use a so called self-compensated summation method. 279 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. 280 296 281 297 Suppose we need to calculate $b = a_1 + a_2 + a_3$. … … 295 311 The self-compensated summation method should be used in all summation in i- and/or j-direction. 296 312 See \mdl{closea} module for an example. 297 Note also that this implementation may be sensitive to the optimization level. 298 313 Note also that this implementation may be sensitive to the optimization level. 314 315 %% ================================================================================================= 299 316 \subsection{MPP scalability} 300 317 \label{subsec:MISC_mppsca} … … 316 333 be set at all the locations actually required by each individual for the fold operation. 317 334 This alternative method should give identical results to the default \textsc{ALLGATHER} method and 318 is recommended for large values of \np{jpni} .319 The new method is activated by setting \np{ln \_nnogather} to be true (\ngn{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}). 320 337 The reproducibility of results using the two methods should be confirmed for each new, 321 338 non-reference configuration. 322 339 323 % ================================================================ 324 % Model optimisation, Control Print and Benchmark 325 % ================================================================ 340 %% ================================================================================================= 326 341 \section{Model optimisation, control print and benchmark} 327 342 \label{sec:MISC_opt} 328 %--------------------------------------------namctl------------------------------------------------------- 329 330 \nlst{namctl} 331 %-------------------------------------------------------------------------------------------------------------- 332 333 Options are defined through the \ngn{namctl} namelist variables. 334 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 %% ================================================================================================= 335 353 \subsection{Vector optimisation} 336 354 … … 338 356 This is very a very efficient way to increase the length of vector calculations and thus 339 357 to speed up the model on vector computers. 340 358 341 359 % Add here also one word on NPROMA technique that has been found useless, since compiler have made significant progress during the last decade. 342 360 343 361 % Add also one word on NEC specific optimisation (Novercheck option for example) 344 362 363 %% ================================================================================================= 345 364 \subsection{Control print} 346 365 347 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: 348 367 349 368 \begin{enumerate} 350 \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 351 370 ZDF modules. 352 371 This option is very helpful when diagnosing the origin of an undesired change in model results. } 353 372 354 \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 355 374 mono and multi processor runs.} 356 375 \end{enumerate} 357 376 358 377 However, in recent versions it has also been used to force all processors to assume the 359 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 360 379 of files such as: ocean.output, layout.dat, etc. All such files, beyond the the normal 361 380 reporting processor (narea == 1), are named with a \_XXXX extension to their name, where … … 363 382 such as run.stat (and its netCDF counterpart: run.stat.nc) and tracer.stat contain global 364 383 information and are only ever produced by the reporting master (narea == 1). For version 365 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 366 385 a new control structure which allows finer control over which files are produced. This 367 386 feature is still evolving but it does already allow the user to: select individually the … … 389 408 at a suitably long interval. For example: 390 409 391 \begin{verbatim} 410 \begin{verbatim} 392 411 sn_cfctl%ptimincr = 25 393 412 \end{verbatim} 394 413 395 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 396 415 increment also applies to the time.step file which is otherwise updated every timestep. 397 416 398 % ================================================================ 399 \biblio 400 401 \pindex 417 \subinc{\input{../../global/epilogue}} 402 418 403 419 \end{document} -
NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_model_basics.tex
r11151 r12149 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[width=\textwidth]{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, 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, 265 275 using a split-explicit method \citep{killworth.webb.ea_JPO91, zhang.endoh_JGR92} or 266 the implicit scheme \citep{dukowicz.smith_JGR94} 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 % ------------------------------------------------------------------------------------------------------------- 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. … … 293 298 A solution consists of introducing an appropriate coordinate transformation that 294 299 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. 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{eiseman.stone_SR80} 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[width=\textwidth]{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.smith.ea_JPO03} or 580 OPA (mixture of $z$-coordinate in vicinity the surface and steep topography areas and $\sigma$-coordinate elsewhere) 581 \citep{madec.delecluse.ea_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}.564 \autoref{eq:MB_s}. 594 565 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.burchard.ea_OM10}, 600 since the coordinate system is adapted in the course of the simulation. 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 advection575 the latter step implicitly embedding the vertical advection 604 576 \citep{hirt.amsden.ea_JCP74, chassignet.smith.ea_JPO03, white.adcroft.ea_JCP09}. 605 577 Here we follow the \citep{kasahara_MWR74} strategy: 606 a regridding step (an update of the vertical coordinate) followed by an eulerian step with578 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[width=\textwidth]{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 coordinate 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 746 700 (become popular as the \zstar-coordinate \citep{adcroft.campin_OM04}). 747 } 748 \end{center} 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{levier.treguier.ea_rpt07} 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$-models760 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 807 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{haney_JPO91} and \citet{beckmann.haidvogel_JPO93} 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{gerdes_JGR93*a,gerdes_JGR93*b,madec.delecluse.ea_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.delecluse.ea_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.madec.ea_OM90,madec.delecluse.ea_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 967 Observations show that 968 lateral mixing induced by mesoscale turbulence tends to be along isopycnal surfaces 1007 969 (or more precisely neutral surfaces \cite{mcdougall_JPO87}) 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. 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{gent.mcwilliams_JPO90} 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 1009 \citet{gent.mcwilliams_JPO90} parameterisation, and various slightly diffusive advection schemes. 1043 For momentum, the main ones are: Laplacian and bilaplacian operators acting along geopotential surfaces, 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{cox_OM87}. 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 … … 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 1142 a geographical coordinate system \citep{lengaigne.madec.ea_JGR03}. 1165 1143 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 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/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_model_basics_zstar.tex
r11179 r12149 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{levier.treguier.ea_rpt07} 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 (\textit{dynspg.F90})] 76 {Surface pressure gradient and sea surface heigth (\protect\mdl{dynspg})} 77 \label{sec:DYN_hpg_spg} 78 %-----------------------------------------nam_dynspg---------------------------------------------------- 79 80 %\nlst{nam_dynspg} 81 %------------------------------------------------------------------------------------------------------------ 82 Options are defined through the \ngn{nam\_dynspg} namelist variables. 83 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}). 84 89 The main distinction is between the fixed volume case (linear free surface or rigid lid) and 85 90 the variable volume case (nonlinear free surface, \key{vvl} is active). 86 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}), 87 92 the vertical scale factors $e_{3}$ are fixed in time, 88 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. 89 94 With both linear and nonlinear free surface, external gravity waves are allowed in the equations, 90 95 which imposes a very small time step when an explicit time stepping is used. 91 96 Two methods are proposed to allow a longer time step for the three-dimensional equations: 92 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?}), 93 98 and the split-explicit free surface described below. 94 99 The extra term introduced in the filtered method is calculated implicitly, 95 100 so that the update of the next velocities is done in module \mdl{dynspg\_flt} and not in \mdl{dynnxt}. 96 101 97 %-------------------------------------------------------------98 102 % Explicit 99 %------------------------------------------------------------- 100 \subsubsection[Explicit (\texttt{\textbf{key\_dynspg\_exp}})] 101 {Explicit (\protect\key{dynspg\_exp})} 102 \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} 103 106 104 107 In the explicit free surface formulation, the model time step is chosen small enough to … … 106 109 The sea surface height is given by: 107 110 \begin{equation} 108 \label{eq: dynspg_ssh}111 \label{eq:MBZ_dynspg_ssh} 109 112 \frac{\partial \eta }{\partial t}\equiv \frac{\text{EMP}}{\rho_w }+\frac{1}{e_{1T} 110 113 e_{2T} }\sum\limits_k {\left( {\delta_i \left[ {e_{2u} e_{3u} u} … … 116 119 and $\rho_w =1,000\,Kg.m^{-3}$ is the volumic mass of pure water. 117 120 The sea-surface height is evaluated using a leapfrog scheme in combination with an Asselin time filter, 118 (\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). 119 122 120 123 The surface pressure gradient, also evaluated using a leap-frog scheme, is then simply given by: 121 124 \begin{equation} 122 \label{eq: dynspg_exp}125 \label{eq:MBZ_dynspg_exp} 123 126 \left\{ 124 127 \begin{aligned} … … 127 130 \end{aligned} 128 131 \right. 129 \end{equation} 132 \end{equation} 130 133 131 134 Consistent with the linearization, a $\left. \rho \right|_{k=1} / \rho_o$ factor is omitted in 132 (\autoref{eq:dynspg_exp}). 133 134 %------------------------------------------------------------- 135 (\autoref{eq:DYN_spg_exp}). 136 135 137 % Split-explicit time-stepping 136 %------------------------------------------------------------- 137 \subsubsection[Split-explicit time-stepping (\texttt{\textbf{key\_dynspg\_ts}})] 138 {Split-explicit time-stepping (\protect\key{dynspg\_ts})} 139 \label{subsec:DYN_spg_ts} 140 %--------------------------------------------namdom---------------------------------------------------- 141 142 \nlst{namdom} 143 %-------------------------------------------------------------------------------------------------------------- 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 144 142 The split-explicit free surface formulation used in OPA follows the one proposed by \citet{Griffies2004?}. 145 143 The general idea is to solve the free surface equation with a small time step, 146 144 while the three dimensional prognostic variables are solved with a longer time step that 147 is a multiple of \np{rdtbt} in the \ngn{namdom} namelist (Figure III.3). 148 149 %> > > > > > > > > > > > > > > > > > > > > > > > > > > > 145 is a multiple of \np{rdtbt}{rdtbt} in the \nam{dom}{dom} namelist (Figure III.3). 146 150 147 \begin{figure}[!t] 151 \ begin{center}152 \includegraphics[width=\textwidth]{Fig_DYN_dynspg_ts}153 \caption{154 \protect\label{fig:DYN_dynspg_ts}155 156 157 158 159 160 161 162 163 164 165 166 167 168 A baroclinic leap-frog time step carries the surface height to $t+\Delta t$ using the convergence of169 the time averaged vertically integrated velocity taken from baroclinic time step t.170 }171 \ 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} 172 169 \end{figure} 173 %> > > > > > > > > > > > > > > > > > > > > > > > > > > >174 170 175 171 The split-explicit formulation has a damping effect on external gravity waves, 176 172 which is weaker than the filtered free surface but still significant as shown by \citet{levier.treguier.ea_rpt07} in 177 the case of an analytical barotropic Kelvin wave. 173 the case of an analytical barotropic Kelvin wave. 178 174 179 175 %from griffies book: ..... copy past ! … … 186 182 We have 187 183 \[ 188 % \label{eq: DYN_spg_ts_eta}184 % \label{eq:MBZ_dyn_spg_ts_eta} 189 185 \eta^{(b)}(\tau,t_{n+1}) - \eta^{(b)}(\tau,t_{n+1}) (\tau,t_{n-1}) 190 = 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] 191 187 \] 192 188 \begin{multline*} 193 % \label{eq: DYN_spg_ts_u}189 % \label{eq:MBZ_dyn_spg_ts_u} 194 190 \textbf{U}^{(b)}(\tau,t_{n+1}) - \textbf{U}^{(b)}(\tau,t_{n-1}) \\ 195 191 = 2\Delta t \left[ - f \textbf{k} \times \textbf{U}^{(b)}(\tau,t_{n}) … … 205 201 the freshwater flux $\text{EMP}_w(\tau)$, and total depth of the ocean $H(\tau)$ are held for 206 202 the duration of the barotropic time stepping over a single cycle. 207 This is also the time that sets the barotropic time steps via 208 \[ 209 % \label{eq: DYN_spg_ts_t}210 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 211 207 \] 212 208 with $n$ an integer. 213 The density scaled surface pressure is evaluated via 214 \[ 215 % \label{eq: DYN_spg_ts_ps}209 The density scaled surface pressure is evaluated via 210 \[ 211 % \label{eq:MBZ_dyn_spg_ts_ps} 216 212 p_s^{(b)}(\tau,t_{n}) = 217 213 \begin{cases} … … 220 216 \end{cases} 221 217 \] 222 To get started, we assume the following initial conditions 223 \[ 224 % \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} 225 221 \begin{split} 226 222 \eta^{(b)}(\tau,t_{n=0}) &= \overline{\eta^{(b)}(\tau)} \\ … … 228 224 \end{split} 229 225 \] 230 with 231 \[ 232 % \label{eq: DYN_spg_ts_etaF}226 with 227 \[ 228 % \label{eq:MBZ_dyn_spg_ts_etaF} 233 229 \overline{\eta^{(b)}(\tau)} = \frac{1}{N+1} \sum\limits_{n=0}^N \eta^{(b)}(\tau-\Delta t,t_{n}) 234 230 \] … … 236 232 Likewise, 237 233 \[ 238 % \label{eq: DYN_spg_ts_u}234 % \label{eq:MBZ_dyn_spg_ts_u} 239 235 \textbf{U}^{(b)}(\tau,t_{n=0}) = \overline{\textbf{U}^{(b)}(\tau)} \\ \\ 240 236 \textbf{U}(\tau,t_{n=1}) = \textbf{U}^{(b)}(\tau,t_{n=0}) + \Delta t \ \text{RHS}_{n=0} 241 237 \] 242 with 243 \[ 244 % \label{eq: DYN_spg_ts_u}238 with 239 \[ 240 % \label{eq:MBZ_dyn_spg_ts_u} 245 241 \overline{\textbf{U}^{(b)}(\tau)} = \frac{1}{N+1} \sum\limits_{n=0}^N\textbf{U}^{(b)}(\tau-\Delta t,t_{n}) 246 242 \] 247 243 the time averaged vertically integrated transport. 248 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. 249 245 250 246 Upon reaching $t_{n=N} = \tau + 2\Delta \tau$ , the vertically integrated velocity is time averaged to 251 produce the updated vertically integrated velocity at baroclinic time $\tau + \Delta \tau$ 252 \[ 253 % \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} 254 250 \textbf{U}(\tau+\Delta t) = \overline{\textbf{U}^{(b)}(\tau+\Delta t)} 255 251 = \frac{1}{N+1} \sum\limits_{n=0}^N\textbf{U}^{(b)}(\tau,t_{n}) 256 252 \] 257 253 The surface height on the new baroclinic time step is then determined via 258 a baroclinic leap-frog using the following form 254 a baroclinic leap-frog using the following form 259 255 \begin{equation} 260 \label{eq: DYN_spg_ts_ssh}256 \label{eq:MBZ_dyn_spg_ts_ssh} 261 257 \eta(\tau+\Delta) - \eta^{F}(\tau-\Delta) = 2\Delta t \ \left[ - \nabla \cdot \textbf{U}(\tau) + \text{EMP}_w \right] 262 258 \end{equation} … … 264 260 The use of this "big-leap-frog" scheme for the surface height ensures compatibility between 265 261 the mass/volume budgets and the tracer budgets. 266 More discussion of this point is provided in Chapter 10 (see in particular Section 10.2). 267 262 More discussion of this point is provided in Chapter 10 (see in particular Section 10.2). 263 268 264 In general, some form of time filter is needed to maintain integrity of the surface height field due to 269 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}. 270 266 We have tried various forms of such filtering, 271 267 with the following method discussed in Griffies et al. (2001) chosen due to its stability and 272 reasonably good maintenance of tracer conservation properties (see ??) 268 reasonably good maintenance of tracer conservation properties (see ??) 273 269 274 270 \begin{equation} 275 \label{eq: DYN_spg_ts_sshf}271 \label{eq:MBZ_dyn_spg_ts_sshf} 276 272 \eta^{F}(\tau-\Delta) = \overline{\eta^{(b)}(\tau)} 277 273 \end{equation} 278 Another approach tried was 279 280 \[ 281 % \label{eq: DYN_spg_ts_sshf2}274 Another approach tried was 275 276 \[ 277 % \label{eq:MBZ_dyn_spg_ts_sshf2} 282 278 \eta^{F}(\tau-\Delta) = \eta(\tau) 283 279 + (\alpha/2) \left[\overline{\eta^{(b)}}(\tau+\Delta t) … … 288 284 This isolation allows for an easy check that tracer conservation is exact when eliminating tracer and 289 285 surface height time filtering (see ?? for more complete discussion). 290 However, in the general case with a non-zero $\alpha$, the filter \autoref{eq:DYN_spg_ts_sshf} was found to 291 be more conservative, and so is recommended. 292 293 %------------------------------------------------------------- 294 % Filtered formulation 295 %------------------------------------------------------------- 296 \subsubsection[Filtered formulation (\texttt{\textbf{key\_dynspg\_flt}})] 297 {Filtered formulation (\protect\key{dynspg\_flt})} 298 \label{subsec:DYN_spg_flt} 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} 299 293 300 294 The filtered formulation follows the \citet{Roullet2000?} implementation. 301 295 The extra term introduced in the equations (see {\S}I.2.2) is solved implicitly. 302 296 The elliptic solvers available in the code are documented in \autoref{chap:MISC}. 303 The amplitude of the extra term is given by the namelist variable \np{rnu} .297 The amplitude of the extra term is given by the namelist variable \np{rnu}{rnu}. 304 298 The default value is 1, as recommended by \citet{Roullet2000?} 305 299 306 \colorbox{red}{\np{rnu}\forcode{ = 1} to be suppressed from namelist !} 307 308 %------------------------------------------------------------- 309 % Non-linear free surface formulation 310 %------------------------------------------------------------- 311 \subsection[Non-linear free surface formulation (\texttt{\textbf{key\_vvl}})] 312 {Non-linear free surface formulation (\protect\key{vvl})} 313 \label{subsec:DYN_spg_vvl} 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} 314 306 315 307 In the non-linear free surface formulation, the variations of volume are fully taken into account. 316 This option is presented in a report \citep{levier.treguier.ea_rpt07} available on the NEMOweb site.308 This option is presented in a report \citep{levier.treguier.ea_rpt07} available on the \NEMO\ web site. 317 309 The three time-stepping methods (explicit, split-explicit and filtered) are the same as in 318 \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. 319 311 In particular, this means that in filtered case, the matrix to be inverted has to be recomputed at each time-step. 320 312 321 \biblio 322 323 \pindex 313 \subinc{\input{../../global/epilogue}} 324 314 325 315 \end{document} -
NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_time_domain.tex
r11184 r12149 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 and 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 39 (\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 stepping depending on the physics with which it is associated. 56 Each term of the RHS is evaluated at a specific time stepping depending on 57 the physics with which it is associated. 43 58 44 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 The time stepping itself is performed once at each time step where implicit vertical diffusion is computed, \ie in the \mdl{trazdf} and \mdl{dynzdf} modules. 56 57 % ------------------------------------------------------------------------------------------------------------- 58 % Non-Diffusive Part---Leapfrog Scheme 59 % ------------------------------------------------------------------------------------------------------------- 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 %% ================================================================================================= 60 76 \section{Non-diffusive part --- Leapfrog scheme} 61 \label{sec: STP_leap_frog}62 63 The time stepping used for processes other than diffusion is the well-known leapfrog scheme64 \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}. 65 81 This scheme is widely used for advection processes in low-viscosity fluids. 66 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. 67 84 It may be used for momentum and tracer advection, pressure gradient, and Coriolis terms, 68 85 but not for diffusion terms. 69 86 It is an efficient method that achieves second-order accuracy with 70 87 just one right hand side evaluation per time step. 71 Moreover, it does not artificially damp linear oscillatory motion nor does it produce instability by72 amplifying the oscillations.88 Moreover, it does not artificially damp linear oscillatory motion 89 nor does it produce instability by amplifying the oscillations. 73 90 These advantages are somewhat diminished by the large phase-speed error of the leapfrog scheme, 74 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. 75 93 However, the scheme allows the coexistence of a numerical and a physical mode due to 76 94 its leading third order dispersive error. 77 95 In other words a divergence of odd and even time steps may occur. 78 To prevent it, the leapfrog scheme is often used in association with a Robert-Asselin time filter 79 (hereafter the LF-RA scheme). 80 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}, 81 100 is a kind of laplacian diffusion in time that mixes odd and even time steps: 82 101 \begin{equation} 83 \label{eq: STP_asselin}102 \label{eq:TD_asselin} 84 103 x_F^t = x^t + \gamma \, \lt[ x_F^{t - \rdt} - 2 x^t + x^{t + \rdt} \rt] 85 104 \end{equation} 86 105 where the subscript $F$ denotes filtered values and $\gamma$ is the Asselin coefficient. 87 $\gamma$ is initialized as \np{rn \_atfp} (namelist parameter).88 Its default value is \np {rn\_atfp}\forcode{ = 10.e-3} (see \autoref{sec:STP_mLF}),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}), 89 108 causing only a weak dissipation of high frequency motions (\citep{farge-coulombier_phd87}). 90 109 The addition of a time filter degrades the accuracy of the calculation from second to first order. 91 110 However, the second order truncation error is proportional to $\gamma$, which is small compared to 1. 92 111 Therefore, the LF-RA is a quasi second order accurate scheme. 93 The LF-RA scheme is preferred to other time differencing schemes such as predictor corrector or trapezoidal schemes, 94 because the user has an explicit and simple control of the magnitude of the time diffusion of the scheme. 95 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 96 116 the momentum and tracer equations, LF-RA avoids implicit numerical diffusion: 97 diffusion is set explicitly by the user through the Robert-Asselin 98 filter parameter and the viscosity and diffusion coefficients. 99 100 % ------------------------------------------------------------------------------------------------------------- 101 % Diffusive Part---Forward or Backward Scheme 102 % ------------------------------------------------------------------------------------------------------------- 117 diffusion is set explicitly by the user through the Robert-Asselin filter parameter and 118 the viscosity and diffusion coefficients. 119 120 %% ================================================================================================= 103 121 \section{Diffusive part --- Forward or backward scheme} 104 \label{sec:STP_forward_imp} 105 106 The leapfrog differencing scheme is unsuitable for the representation of diffusion and damping processes. 122 \label{sec:TD_forward_imp} 123 124 The leapfrog differencing scheme is unsuitable for 125 the representation of diffusion and damping processes. 107 126 For a tendency $D_x$, representing a diffusion term or a restoring term to a tracer climatology 108 127 (when present, see \autoref{sec:TRA_dmp}), a forward time differencing scheme is used : 109 128 \[ 110 %\label{eq: STP_euler}129 %\label{eq:TD_euler} 111 130 x^{t + \rdt} = x^{t - \rdt} + 2 \, \rdt \ D_x^{t - \rdt} 112 131 \] 113 132 114 133 This is diffusive in time and conditionally stable. 115 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}: 116 136 \begin{equation} 117 \label{eq: STP_euler_stability}137 \label{eq:TD_euler_stability} 118 138 A^h < 119 139 \begin{cases} … … 122 142 \end{cases} 123 143 \end{equation} 124 where $e$ is the smallest grid size in the two horizontal directions and $A^h$ is the mixing coefficient. 125 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. 126 147 If it is not satisfied, even mildly, then the model soon becomes wildly unstable. 127 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. 128 150 129 151 For the vertical diffusion terms, a forward time differencing scheme can be used, 130 but usually the numerical stability condition imposes a strong constraint on the time step. To overcome the stability constraint, a 131 backward (or implicit) time differencing scheme is used. This scheme is unconditionally stable but diffusive and can be written as follows: 152 but usually the numerical stability condition imposes a strong constraint on the time step. 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: 132 155 \begin{equation} 133 \label{eq: STP_imp}156 \label{eq:TD_imp} 134 157 x^{t + \rdt} = x^{t - \rdt} + 2 \, \rdt \ \text{RHS}_x^{t + \rdt} 135 158 \end{equation} 136 159 137 %%gm 138 %%gm UPDATE the next paragraphs with time varying thickness ... 139 %%gm 140 141 This scheme is rather time consuming since it requires a matrix inversion. For example, the finite difference approximation of the temperature equation is: 160 \cmtgm{UPDATE the next paragraphs with time varying thickness ...} 161 162 This scheme is rather time consuming since it requires a matrix inversion. 163 For example, the finite difference approximation of the temperature equation is: 142 164 \[ 143 % \label{eq: STP_imp_zdf}165 % \label{eq:TD_imp_zdf} 144 166 \frac{T(k)^{t + 1} - T(k)^{t - 1}}{2 \; \rdt} 145 167 \equiv … … 147 169 \] 148 170 where RHS is the right hand side of the equation except for the vertical diffusion term. 149 We rewrite \autoref{eq: STP_imp} as:171 We rewrite \autoref{eq:TD_imp} as: 150 172 \begin{equation} 151 \label{eq: STP_imp_mat}173 \label{eq:TD_imp_mat} 152 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) 153 175 \end{equation} 154 where 155 \begin{align*} 156 c(k) &= A_w^{vT} (k) \, / \, e_{3w} (k) \\ 157 d(k) &= e_{3t} (k) \, / \, (2 \rdt) + c_k + c_{k + 1} \\ 158 b(k) &= e_{3t} (k) \; \lt( T^{t - 1}(k) \, / \, (2 \rdt) + \text{RHS} \rt) 159 \end{align*} 160 161 \autoref{eq:STP_imp_mat} is a linear system of equations with an associated matrix which is tridiagonal. 162 Moreover, 163 $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, 164 187 therefore a special adaptation of the Gauss elimination procedure is used to find the solution 165 188 (see for example \citet{richtmyer.morton_bk67}). 166 189 167 % ------------------------------------------------------------------------------------------------------------- 168 % Surface Pressure gradient 169 % ------------------------------------------------------------------------------------------------------------- 190 %% ================================================================================================= 170 191 \section{Surface pressure gradient} 171 \label{sec:STP_spg_ts} 172 173 The leapfrog environment supports a centred in time computation of the surface pressure, \ie evaluated 174 at \textit{now} time step. This refers to as the explicit free surface case in the code (\np{ln\_dynspg\_exp}\forcode{ = .true.}). 175 This choice however imposes a strong constraint on the time step which should be small enough to resolve the propagation 176 of external gravity waves. As a matter of fact, one rather use in a realistic setup, a split-explicit free surface 177 (\np{ln\_dynspg\_ts}\forcode{ = .true.}) in which barotropic and baroclinic dynamical equations are solved separately with ad-hoc 178 time steps. The use of the time-splitting (in combination with non-linear free surface) imposes some constraints on the design of 179 the overall flowchart, in particular to ensure exact tracer conservation (see \autoref{fig:TimeStep_flowchart}). 180 181 Compared to the former use of the filtered free surface in \NEMO v3.6 (\citet{roullet.madec_JGR00}), the use of a split-explicit free surface is advantageous 182 on massively parallel computers. Indeed, no global computations are anymore required by the elliptic solver which saves a substantial amount of communication 183 time. Fast barotropic motions (such as tides) are also simulated with a better accuracy. 184 185 %\gmcomment{ 186 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 187 \begin{figure}[!t] 188 \begin{center} 189 \includegraphics[width=\textwidth]{Fig_TimeStepping_flowchart_v4} 190 \caption{ 191 \protect\label{fig:TimeStep_flowchart} 192 Sketch of the leapfrog time stepping sequence in \NEMO with split-explicit free surface. The latter combined 193 with non-linear free surface requires the dynamical tendency being updated prior tracers tendency to ensure 194 conservation. Note the use of time integrated fluxes issued from the barotropic loop in subsequent calculations 195 of tracer advection and in the continuity equation. Details about the time-splitting scheme can be found 196 in \autoref{subsec:DYN_spg_ts}. 197 } 198 \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} 199 225 \end{figure} 200 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>201 226 %} 202 227 203 % ------------------------------------------------------------------------------------------------------------- 204 % The Modified Leapfrog -- Asselin Filter scheme 205 % ------------------------------------------------------------------------------------------------------------- 206 \section{Modified Leapfrog -- Asselin filter scheme} 207 \label{sec:STP_mLF} 208 209 Significant changes have been introduced by \cite{leclair.madec_OM09} in the LF-RA scheme in order to 210 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. 211 235 The modifications affect both the forcing and filtering treatments in the LF-RA scheme. 212 236 213 In a classical LF-RA environment, the forcing term is centred in time,214 \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: 215 239 $x^t = x^t + 2 \rdt Q^t$ where $Q$ is the forcing applied to $x$, 216 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. 217 242 In the modified LF-RA environment, these two formulations have been replaced by: 218 243 \begin{gather} 219 \label{eq: STP_forcing}244 \label{eq:TD_forcing} 220 245 x^{t + \rdt} = x^{t - \rdt} + \rdt \lt( Q^{t - \rdt / 2} + Q^{t + \rdt / 2} \rt) \\ 221 \label{eq: STP_RA}246 \label{eq:TD_RA} 222 247 x_F^t = x^t + \gamma \, \lt( x_F^{t - \rdt} - 2 x^t + x^{t + \rdt} \rt) 223 248 - \gamma \, \rdt \, \lt( Q^{t + \rdt / 2} - Q^{t - \rdt / 2} \rt) 224 249 \end{gather} 225 The change in the forcing formulation given by \autoref{eq:STP_forcing} (see \autoref{fig:MLF_forcing}) 226 has a significant effect: 227 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}. 228 254 % forcing seen by the model.... 229 255 This property improves the LF-RA scheme in two aspects. 230 256 First, the LF-RA can now ensure the local and global conservation of tracers. 231 257 Indeed, time filtering is no longer required on the forcing part. 232 The influence of the Asselin filter on the forcing is explicitly removed by adding a new term in the filter233 (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}). 234 260 Since the filtering of the forcing was the source of non-conservation in the classical LF-RA scheme, 235 261 the modified formulation becomes conservative \citep{leclair.madec_OM09}. 236 Second, the LF-RA becomes a truly quasi 237 Indeed, \autoref{eq: STP_forcing} used in combination with a careful treatment of static instability238 (\autoref{subsec:ZDF_evd}) and of the TKE physics (\autoref{subsec:ZDF_tke_ene}) 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}) 239 265 (the two other main sources of time step divergence), 240 266 allows a reduction by two orders of magnitude of the Asselin filter parameter. … … 242 268 Note that the forcing is now provided at the middle of a time step: 243 269 $Q^{t + \rdt / 2}$ is the forcing applied over the $[t,t + \rdt]$ time interval. 244 This and the change in the time filter, \autoref{eq: STP_RA},270 This and the change in the time filter, \autoref{eq:TD_RA}, 245 271 allows for an exact evaluation of the contribution due to the forcing term between any two time steps, 246 272 even if separated by only $\rdt$ since the time filter is no longer applied to the forcing term. 247 273 248 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 249 \begin{figure}[!t] 250 \begin{center} 251 \includegraphics[width=\textwidth]{Fig_MLF_forcing} 252 \caption{ 253 \protect\label{fig:MLF_forcing} 254 Illustration of forcing integration methods. 255 (top) ''Traditional'' formulation: 256 the forcing is defined at the same time as the variable to which it is applied 257 (integer value of the time step index) and it is applied over a $2 \rdt$ period. 258 (bottom) modified formulation: 259 the forcing is defined in the middle of the time (integer and a half value of the time step index) and 260 the mean of two successive forcing values ($n - 1 / 2$, $n + 1 / 2$) is applied over a $2 \rdt$ period. 261 } 262 \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} 263 288 \end{figure} 264 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 265 266 % ------------------------------------------------------------------------------------------------------------- 267 % Start/Restart strategy 268 % ------------------------------------------------------------------------------------------------------------- 289 290 %% ================================================================================================= 269 291 \section{Start/Restart strategy} 270 \label{sec:STP_rst} 271 272 %--------------------------------------------namrun------------------------------------------- 273 \nlst{namrun} 274 %-------------------------------------------------------------------------------------------------------------- 275 276 The first time step of this three level scheme when starting from initial conditions is a forward step 277 (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): 278 302 \[ 279 % \label{eq: DOM_euler}303 % \label{eq:TD_DOM_euler} 280 304 x^1 = x^0 + \rdt \ \text{RHS}^0 281 305 \] 282 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 283 308 setting all $x^0$ (\textit{before}) and $x^1$ (\textit{now}) fields equal at the first time step and 284 using half the value of a leapfrog time step ($2 \rdt$). 309 using half the value of a leapfrog time step ($2 \rdt$). 285 310 286 311 It is also possible to restart from a previous computation, by using a restart file. … … 289 314 running the model for $2N$ time steps in one go, 290 315 or by performing two consecutive experiments of $N$ steps with a restart. 291 This requires saving two time levels and many auxiliary data in the restart files in machine precision. 316 This requires saving two time levels and many auxiliary data in 317 the restart files in machine precision. 292 318 293 319 Note that the time step $\rdt$, is also saved in the restart file. 294 When restarting, if the time step has been changed, or one of the prognostic variables at \textit{before} time step 295 is missing, an Euler time stepping scheme is imposed. A forward initial step can still be enforced by the user by setting 296 the namelist variable \np{nn\_euler}\forcode{=0}. Other options to control the time integration of the model 297 are defined through the \ngn{namrun} namelist variables. 298 %%% 299 \gmcomment{ 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{ 300 329 add here how to force the restart to contain only one time step for operational purposes 301 330 302 331 add also the idea of writing several restart for seasonal forecast : how is it done ? 303 332 304 verify that all namelist para rmeters are truly described333 verify that all namelist parameters are truly described 305 334 306 335 a word on the check of restart ..... 307 336 } 308 %%% 309 310 \gmcomment{ % add a subsection here 311 312 %------------------------------------------------------------------------------------------------------------- 313 % Time Domain 314 % ------------------------------------------------------------------------------------------------------------- 337 338 \cmtgm{ % add a subsection here 339 340 %% ================================================================================================= 315 341 \subsection{Time domain} 316 \label{subsec:STP_time} 317 %--------------------------------------------namrun------------------------------------------- 318 319 \nlst{namdom} 320 %-------------------------------------------------------------------------------------------------------------- 321 322 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. 323 345 \colorbox{yellow}{add here a few word on nit000 and nitend} 324 346 325 347 \colorbox{yellow}{Write documentation on the calendar and the key variable adatrj} 326 348 327 add a description of daymod, and the model calandar (leap-year and co) 328 329 } %% end add 330 331 332 333 %% 334 \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 335 354 336 355 Implicit time stepping in case of variable volume thickness. … … 381 400 \end{flalign*} 382 401 383 %%384 402 } 385 403 386 \biblio 387 388 \pindex 404 \subinc{\input{../../global/epilogue}} 389 405 390 406 \end{document}
Note: See TracChangeset
for help on using the changeset viewer.