# Changeset 11692 for NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc

Ignore:
Timestamp:
2019-10-12T16:08:18+02:00 (19 months ago)
Message:

Update branch to integrate the development starting from the current v4.01 ready trunk

Location:
NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc
Files:
29 deleted
72 edited
41 copied

Unmodified
Removed
• ## NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc

• Property svn:externals set to
^/utils/logos logos
• ## NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex

• Property svn:ignore deleted
• ## NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/.svnignore

 r11187 *.ilg *.ind *.lof *.log *.lot *.lo* *.maf *.mtc* *.pdf *.toc *.xdv _minted-*
• ## NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO

• Property svn:externals set to
^/utils/figures/NEMO figures
• ## NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO/build

• Property svn:ignore
•  old *.pdf *.toc *.xdv _minted-*
• ## NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO/main/appendices.tex

 r11330 \subfile{../subfiles/annex_A}             %% Generalised vertical coordinate \subfile{../subfiles/annex_B}             %% Diffusive operator \subfile{../subfiles/annex_C}             %% Discrete invariants of the eqs. \subfile{../subfiles/annex_iso}            %% Isoneutral diffusion using triads \subfile{../subfiles/annex_DOMAINcfg}     %% Brief notes on DOMAINcfg \subfile{../subfiles/apdx_s_coord}      %% A. Generalised vertical coordinate \subfile{../subfiles/apdx_diff_opers}   %% B. Diffusive operators \subfile{../subfiles/apdx_invariants}   %% C. Discrete invariants of the eqs. \subfile{../subfiles/apdx_triads}       %% D. Isoneutral diffusion using triads \subfile{../subfiles/apdx_DOMAINcfg}    %% E. Brief notes on DOMAINcfg %% Not included %\subfile{../subfiles/chap_DIU} %\subfile{../subfiles/chap_conservation} %\subfile{../subfiles/annex_E}            %% Notes on some on going staff %\subfile{../subfiles/apdx_algos}   %% Notes on some on going staff
• ## NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO/main/bibliography.bib

 r11336 } @article{         kraus.turner_tellus67, author = {Kraus, E.B. and Turner, J.}, journal = {Tellus}, pages = {98--106}, title = {A one dimensional model of the seasonal thermocline {II}. {T}he general theory and its consequences}, volume = {19}, year = {1967} } @article{        large.ea_RG97, author        = "Large, W. G. and McWilliams, J. C. and Doney, S. C.", doi           = "10.1029/94RG01872", journal       = "Reviews of Geophysics", number        = {4}, pages         = {363--403}, publisher     = {AGU}, title         = "Oceanic vertical mixing: {A} review and a model with a nonlocal boundary layer parameterization", year          = "1994" } @techreport{      large.yeager_rpt04, title         = "Diurnal to decadal global forcing for ocean and sea-ice } @article{mcwilliams.ea_JFM97, author = {McWilliams, James C. and Sullivan, Peter P. and Moeng, Chin-Hoh}, doi = {10.1017/S0022112096004375}, journal = {Journal of Fluid Mechanics}, pages = {1--30}, title = {Langmuir turbulence in the ocean}, volume = {334}, year = {1997}, } @article{         mellor.blumberg_JPO04, title         = "Wave Breaking and Ocean Surface Layer Thermal Response",
• ## NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO/main/chapters.tex

 r11170 \subfile{../subfiles/introduction}        %% Introduction \subfile{../subfiles/chap_model_basics} \subfile{../subfiles/chap_time_domain}    %% Time discretisation (time stepping strategy) \subfile{../subfiles/chap_DOM}            %% Space discretisation \subfile{../subfiles/chap_TRA}            %% Tracer advection/diffusion equation \subfile{../subfiles/chap_DYN}            %% Dynamics : momentum equation \subfile{../subfiles/chap_SBC}            %% Surface Boundary Conditions \subfile{../subfiles/chap_LBC}            %% Lateral Boundary Conditions \subfile{../subfiles/chap_LDF}            %% Lateral diffusion \subfile{../subfiles/chap_ZDF}            %% Vertical diffusion \subfile{../subfiles/chap_DIA}            %% Outputs and Diagnostics \subfile{../subfiles/chap_OBS}            %% Observation operator \subfile{../subfiles/chap_ASM}            %% Assimilation increments \subfile{../subfiles/chap_STO}            %% Stochastic param. \subfile{../subfiles/chap_misc}           %% Miscellaneous topics \subfile{../subfiles/chap_CONFIG}         %% Predefined configurations \subfile{../subfiles/chap_model_basics}   %% 1. \subfile{../subfiles/chap_time_domain}    %% 2.  Time discretisation (time stepping strategy) \subfile{../subfiles/chap_DOM}            %% 3.  Space discretisation \subfile{../subfiles/chap_TRA}            %% 4.  Tracer advection/diffusion equation \subfile{../subfiles/chap_DYN}            %% 5.  Dynamics : momentum equation \subfile{../subfiles/chap_SBC}            %% 6.  Surface Boundary Conditions \subfile{../subfiles/chap_LBC}            %% 7.  Lateral Boundary Conditions \subfile{../subfiles/chap_LDF}            %% 8.  Lateral diffusion \subfile{../subfiles/chap_ZDF}            %% 9.  Vertical diffusion \subfile{../subfiles/chap_DIA}            %% 10. Outputs and Diagnostics \subfile{../subfiles/chap_OBS}            %% 11. Observation operator \subfile{../subfiles/chap_ASM}            %% 12. Assimilation increments \subfile{../subfiles/chap_STO}            %% 13. Stochastic param. \subfile{../subfiles/chap_misc}           %% 14. Miscellaneous topics \subfile{../subfiles/chap_cfgs}           %% 15. Predefined configurations %% Not included %\subfile{../subfiles/chap_model_basics_zstar} %\subfile{../subfiles/chap_DIU} %\subfile{../subfiles/chap_conservation}
• ## NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO/subfiles

• Property svn:ignore
•  old *.aux *.bbl *.blg *.dvi *.fdb* *.fls *.idx *.ind *.ilg *.ind *.log *.maf *.mtc* *.out *.pdf *.toc _minted-*
• ## NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO/subfiles/chap_ASM.tex

 r11435 \begin{document} % ================================================================ % Chapter Assimilation increments (ASM) % ================================================================ \chapter{Apply Assimilation Increments (ASM)} \label{chap:ASM} %    {\em 4.0} & {\em D. J. Lea} & {\em \NEMO\ 4.0 updates}  \\ %    {\em 3.4} & {\em D. J. Lea, M. Martin, K. Mogensen, A. Weaver} & {\em Initial version}  \\ \thispagestyle{plain} \chaptertoc \vfill \begin{figure}[b] \subsubsection*{Changes record} \begin{tabular}{l||l|m{0.65\linewidth}} Release   & Author        & Modifications \\ {\em 4.0} & {\em D. J. Lea} & {\em \NEMO\ 4.0 updates}  \\ {\em 3.4} & {\em D. J. Lea, M. Martin, K. Mogensen, A. Weaver} & {\em Initial version}  \\ \end{tabular} \end{figure} \paragraph{Changes record} ~\\ \newpage {\footnotesize \begin{tabularx}{\textwidth}{l||X|X} Release & Author(s) & Modifications \\ \hline {\em   4.0} & {\em ...} & {\em ...} \\ {\em   3.6} & {\em ...} & {\em ...} \\ {\em   3.4} & {\em ...} & {\em ...} \\ {\em <=3.4} & {\em ...} & {\em ...} \end{tabularx} } \clearpage The ASM code adds the functionality to apply increments to the model variables: temperature, salinity, These are read into the model from a NetCDF file which may be produced by separate data assimilation code. The code can also output model background fields which are used as an input to data assimilation code. This is all controlled by the namelist \nam{\_asminc}. This is all controlled by the namelist \nam{_asminc}{\_asminc}. There is a brief description of all the namelist options provided. To build the ASM code \key{asminc} must be set. %=============================================================== %% ================================================================================================= \section{Direct initialization} \label{sec:ASM_DI} Direct initialization (DI) refers to the instantaneous correction of the model background state using the analysis increment. DI is used when \np{ln\_asmdin} is set to true. DI is used when \np{ln_asmdin}{ln\_asmdin} is set to true. %% ================================================================================================= \section{Incremental analysis updates} \label{sec:ASM_IAU} This technique is referred to as Incremental Analysis Updates (IAU) \citep{bloom.takacs.ea_MWR96}. IAU is a common technique used with 3D assimilation methods such as 3D-Var or OI. IAU is used when \np{ln\_asmiau} is set to true. IAU is used when \np{ln_asmiau}{ln\_asmiau} is set to true. With IAU, the model state trajectory ${\mathbf x}$ in the assimilation window ($t_{0} \leq t_{i} \leq t_{N}$) additional tendency terms to the prognostic equations: \begin{align*} % \label{eq:wa_traj_iau} % \label{eq:ASM_wa_traj_iau} {\mathbf x}^{a}(t_{i}) = M(t_{i}, t_{0})[{\mathbf x}^{b}(t_{0})] \; + \; F_{i} \delta \tilde{\mathbf x}^{a} \end{align*} Typically the increments are spread evenly over the full window. In addition, two different weighting functions have been implemented. The first function (namelist option \np{niaufn} = 0) employs constant weights, The first function (namelist option \np{niaufn}{niaufn}=0) employs constant weights, \begin{align} \label{eq:F1_i} \label{eq:ASM_F1_i} F^{(1)}_{i} =\left\{ \end{align} where $M = m-n$. The second function (namelist option \np{niaufn} = 1) employs peaked hat-like weights in order to give maximum weight in the centre of the sub-window, 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, with the weighting reduced linearly to a small value at the window end-points: \begin{align} \label{eq:F2_i} \label{eq:ASM_F2_i} F^{(2)}_{i} =\left\{ \end{align} where $\alpha^{-1} = \sum_{i=1}^{M/2} 2i$ and $M$ is assumed to be even. The weights described by \autoref{eq:F2_i} provide a smoother transition of the analysis trajectory from one assimilation cycle to the next than that described by \autoref{eq:F1_i}. The weights described by \autoref{eq:ASM_F2_i} provide a smoother transition of the analysis trajectory from one assimilation cycle to the next than that described by \autoref{eq:ASM_F1_i}. %========================================================================== % Divergence damping description %%% %% ================================================================================================= \section{Divergence damping initialisation} \label{sec:ASM_div_dmp} \label{eq:asm_dmp} \label{eq:ASM_dmp} \left\{ \begin{aligned} $% \label{eq:asm_div} % \label{eq:ASM_div} \chi^{n-1}_I = \frac{1}{e_{1t}\,e_{2t}\,e_{3t} } \left( {\delta_i \left[ {e_{2u}\,e_{3u}\,u^{n-1}_I} \right]$ By the application of \autoref{eq:asm_dmp} the divergence is filtered in each iteration, By the application of \autoref{eq:ASM_dmp} the divergence is filtered in each iteration, and the vorticity is left unchanged. In the presence of coastal boundaries with zero velocity increments perpendicular to the coast \citep{talagrand_JAS72, dobricic.pinardi.ea_OS07}. Diffusion coefficients are defined as $A_D = \alpha e_{1t} e_{2t}$, where $\alpha = 0.2$. The divergence damping is activated by assigning to \np{nn\_divdmp} in the \nam{\_asminc} namelist The divergence damping is activated by assigning to \np{nn_divdmp}{nn\_divdmp} in the \nam{_asminc}{\_asminc} namelist a value greater than zero. 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. %========================================================================== %% ================================================================================================= \section{Implementation details} \label{sec:ASM_details} Here we show an example \nam{\_asminc} namelist and the header of an example assimilation increments file on Here we show an example \nam{_asminc}{\_asminc} namelist and the header of an example assimilation increments file on the ORCA2 grid. %------------------------------------------nam_asminc----------------------------------------------------- % \nlst{nam_asminc} %------------------------------------------------------------------------------------------------------------- \begin{listing} \nlst{nam_asminc} \caption{\forcode{&nam_asminc}} \label{lst:nam_asminc} \end{listing} The header of an assimilation increments file produced using the NetCDF tool \end{clines} \biblio \pindex \onlyinsubfile{\input{../../global/epilogue}} \end{document}
• ## NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO/subfiles/chap_DIA.tex

 r11435 \begin{document} % ================================================================ % Chapter I/O & Diagnostics % ================================================================ \chapter{Output and Diagnostics (IOM, DIA, TRD, FLO)} \label{chap:DIA} %    {\em 4.0} & {\em Mirek Andrejczuk, Massimiliano Drudi} & {\em }  \\ %    {\em }      & {\em Dorotea Iovino, Nicolas Martin} & {\em }  \\ %    {\em 3.6} & {\em Gurvan Madec, Sebastien Masson } & {\em }  \\ %    {\em 3.4} & {\em Gurvan Madec, Rachid Benshila, Andrew Coward } & {\em }  \\ %    {\em }      & {\em Christian Ethe, Sebastien Masson } & {\em }  \\ \thispagestyle{plain} \chaptertoc \vfill \begin{figure}[b] \subsubsection*{Changes record} \begin{tabular}{l||l|m{0.65\linewidth}} Release   & Author        & Modifications \\ {\em 4.0} & {\em Mirek Andrejczuk, Massimiliano Drudi} & {\em }  \\ {\em }      & {\em Dorotea Iovino, Nicolas Martin} & {\em }  \\ {\em 3.6} & {\em Gurvan Madec, Sebastien Masson } & {\em }  \\ {\em 3.4} & {\em Gurvan Madec, Rachid Benshila, Andrew Coward } & {\em }  \\ {\em }      & {\em Christian Ethe, Sebastien Masson } & {\em }  \\ \end{tabular} \end{figure} \newpage % ================================================================ %       Old Model Output % ================================================================ \paragraph{Changes record} ~\\ {\footnotesize \begin{tabularx}{\textwidth}{l||X|X} Release & Author(s) & Modifications \\ \hline {\em   4.0} & {\em ...} & {\em ...} \\ {\em   3.6} & {\em ...} & {\em ...} \\ {\em   3.4} & {\em ...} & {\em ...} \\ {\em <=3.4} & {\em ...} & {\em ...} \end{tabularx} } \clearpage %% ================================================================================================= \section{Model output} \label{sec:DIA_io_old} %\gmcomment{                    % start of gmcomment % ================================================================ % Diagnostics % ================================================================ %% ================================================================================================= \section{Standard model output (IOM)} \label{sec:DIA_iom} \begin{enumerate} \item The complete and flexible control of the output files through external XML files adapted by \item The complete and flexible control of the output files through external XML files adapted by the user from standard templates. \item To achieve high performance and scalable output through the optional distribution of \item To achieve high performance and scalable output through the optional distribution of all diagnostic output related tasks to dedicated processes. \end{enumerate} \begin{itemize} \item The choice of output frequencies that can be different for each file (including real months and years). \item The choice of file contents; includes complete flexibility over which data are written in which files \item The choice of output frequencies that can be different for each file (including real months and years). \item The choice of file contents; includes complete flexibility over which data are written in which files (the same data can be written in different files). \item The possibility to split output files at a chosen frequency. \item The possibility to extract a vertical or an horizontal subdomain. \item The choice of the temporal operation to perform, \eg: average, accumulate, instantaneous, min, max and once. \item Control over metadata via a large XML "database" of possible output fields. \item The possibility to split output files at a chosen frequency. \item The possibility to extract a vertical or an horizontal subdomain. \item The choice of the temporal operation to perform, \eg: average, accumulate, instantaneous, min, max and once. \item Control over metadata via a large XML "database" of possible output fields. \end{itemize} even without a parallel-enabled NetCDF4 library, simply by employing only one dedicated I/O server. %% ================================================================================================= \subsection{XIOS: Reading and writing restart file} XIOS may be used to read single file restart produced by \NEMO. Currently only the variables written to file \forcode{numror} can be handled by XIOS. To activate restart reading using XIOS, set \np{ln\_xios\_read}\forcode{ = .true. } file \forcode{numror} can be handled by XIOS. To activate restart reading using XIOS, set \np[=.true. ]{ln_xios_read}{ln\_xios\_read} in \textit{namelist\_cfg}. This setting will be ignored when multiple restart files are present, and default \NEMO functionality will be used for reading. There is no need to change iodef.xml file to use XIOS to read dimension \forcode{z} defined in restart file must be renamed to \forcode{nav_lev}.\\ XIOS can also be used to write \NEMO\ restart. A namelist parameter \np{nn\_wxios} is used to determine the XIOS can also be used to write \NEMO\ restart. A namelist parameter \np{nn_wxios}{nn\_wxios} is used to determine the type of restart \NEMO\ will write. If it is set to 0, default \NEMO\ functionality will be used - each processor writes its own restart file; if it is set to 1 XIOS will write restart into a single file; for \np{nn\_wxios}\forcode{ = 2} the restart will be written by XIOS into multiple files, one for each XIOS server. Note, however, that \textbf{\NEMO\ will not read restart generated by XIOS when \np{nn\_wxios}\forcode{ = 2}}. The restart will for \np[=2]{nn_wxios}{nn\_wxios} the restart will be written by XIOS into multiple files, one for each XIOS server. Note, however, that \textbf{\NEMO\ will not read restart generated by XIOS when \np[=2]{nn_wxios}{nn\_wxios}}. The restart will have to be rebuild before continuing the run. This option aims to reduce number of restart files generated by \NEMO\ only, and may be useful when there is a need to change number of processors used to run simulation. If an additional variable must be written to a restart file, the following steps are needed: \begin{description} \item[step 1:] add variable name to a list of restart variables (in subroutine \rou{iom\_set\_rst\_vars,} \mdl{iom}) and \begin{enumerate} \item Add variable name to a list of restart variables (in subroutine \rou{iom\_set\_rst\_vars,} \mdl{iom}) and define correct grid for the variable (\forcode{grid_N_3D} - 3D variable, \forcode{grid_N} - 2D variable, \forcode{grid_vector} - 1D variable, \forcode{grid_scalar} - scalar), \item[step 2:] add variable to the list of fields written by restart.  This can be done either in subroutine \item Add variable to the list of fields written by restart.  This can be done either in subroutine \rou{iom\_set\_rstw\_core} (\mdl{iom}) or by calling  \rou{iom\_set\_rstw\_active} (\mdl{iom}) with the name of a variable as an argument. This convention follows approach for writing restart using iom, where variables are written either by \rou{rst\_write} or by calling \rou{iom\_rstput} from individual routines. \end{description} \end{enumerate} An older versions of XIOS do not support reading functionality. It's recommended to use at least XIOS2@1451. %% ================================================================================================= \subsection{XIOS: XML Inputs-Outputs Server} %% ================================================================================================= \subsubsection{Attached or detached mode?} \xmlline|| The {\ttfamily using\_server} setting determines whether or not the server will be used in \textit{attached mode} (as a library) [{\ttfamily> false <}] or in \textit{detached mode} (as an external executable on N additional, dedicated cpus) [{\ttfamily > true <}]. The \textit{attached mode} is simpler to use but much less efficient for massively parallel applications. The \texttt{using\_server} setting determines whether or not the server will be used in \textit{attached mode} (as a library) [\texttt{> false <}] or in \textit{detached mode} (as an external executable on N additional, dedicated cpus) [\texttt{ > true <}]. The \textit{attached mode} is simpler to use but much less efficient for massively parallel applications. The type of each file can be either ''multiple\_file'' or ''one\_file''. The following subsection provides a typical example but the syntax will vary in different MPP environments. %% ================================================================================================= \subsubsection{Number of cpu used by XIOS in detached mode} \cmd|mpirun -np 62 ./nemo.exe : -np 2 ./xios_server.exe| %% ================================================================================================= \subsubsection{Control of XIOS: the context in iodef.xml} \begin{table} \scriptsize \begin{tabularx}{\textwidth}{|lXl|} \hline \end{table} %% ================================================================================================= \subsection{Practical issues} %% ================================================================================================= \subsubsection{Installation} {Extract and install XIOS} guide provides an example illustration of how this can be achieved. %% ================================================================================================= \subsubsection{Add your own outputs} \begin{enumerate} \item[1.] in \NEMO\ code, add a \forcode{CALL iom_put( 'identifier', array )} where you want to output a 2D or 3D array. \item[2.] If necessary, add \forcode{USE iom ! I/O manager library} to the list of used modules in \item in \NEMO\ code, add a \forcode{CALL iom_put( 'identifier', array )} where you want to output a 2D or 3D array. \item If necessary, add \forcode{USE iom ! I/O manager library} to the list of used modules in the upper part of your module. \item[3.] in the field\_def.xml file, add the definition of your variable using the same identifier you used in the f90 code \item in the field\_def.xml file, add the definition of your variable using the same identifier you used in the f90 code (see subsequent sections for a details of the XML syntax and rules). For example: \begin{xmllines} \end{xmllines} Note your definition must be added to the field\_group whose reference grid is consistent with the size of the array passed to iomput. (iom\_set\_domain\_attr and iom\_set\_axis\_attr in \mdl{iom}) or defined in the domain\_def.xml file. \eg: \begin{xmllines} \end{xmllines} Note, if your array is computed within the surface module each \np{nn\_fsbc} time\_step, Note, if your array is computed within the surface module each \np{nn_fsbc}{nn\_fsbc} time\_step, add the field definition within the field\_group defined with the id "SBC": \xmlcode{} which has been defined with the correct frequency of operations (iom\_set\_field\_attr in \mdl{iom}) \item[4.] add your field in one of the output files defined in iodef.xml \item add your field in one of the output files defined in iodef.xml (again see subsequent sections for syntax and rules) \begin{xmllines} \end{xmllines} \end{enumerate} %% ================================================================================================= \subsection{XML fundamentals} %% ================================================================================================= \subsubsection{ XML basic rules} See \href{http://www.xmlnews.org/docs/xml-basics.html}{here} for more details. %% ================================================================================================= \subsubsection{Structure of the XML file used in \NEMO} \begin{table} \scriptsize \begin{tabular*}{\textwidth}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} \hline \begin{table} \scriptsize \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} \hline \begin{table} \scriptsize \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} \hline \begin{table} \scriptsize \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} \hline \end{table} %% ================================================================================================= \subsubsection{Nesting XML files} \end{xmllines} %% ================================================================================================= \subsubsection{Use of inheritance} Inherit (and overwrite, if needed) the attributes of a tag you are refering to. %% ================================================================================================= \subsubsection{Use of groups} \end{xmllines} %% ================================================================================================= \subsection{Detailed functionalities} the new functionalities offered by the XML interface of XIOS. %% ================================================================================================= \subsubsection{Define horizontal subdomains} We are therefore advising to use the ''one\_file'' type in this case. %% ================================================================================================= \subsubsection{Define vertical zooms} \end{xmllines} %% ================================================================================================= \subsubsection{Control of the output file names} \begin{table} \scriptsize \begin{tabularx}{\textwidth}{|lX|} \hline \noindent will give the following file name radical: \ifile{myfile\_ORCA2\_19891231\_freq1d} %% ================================================================================================= \subsubsection{Other controls of the XML attributes from \NEMO} \begin{table} \scriptsize \begin{tabularx}{\textwidth}{|X|c|c|c|} \begin{tabular}{|l|c|c|} \hline tag ids affected by automatic definition of some of their attributes & name attribute                                                       & attribute value                      \\ attribute value                                                      \\ \hline \hline field\_definition                                                    & freq\_op                                                             & \np{rn\_rdt}                         \\ \np{rn_rdt}{rn\_rdt}                                                         \\ \hline SBC                                                                  & freq\_op                                                             & \np{rn\_rdt} $\times$ \np{nn\_fsbc}  \\ \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_fsbc}{nn\_fsbc}                                  \\ \hline ptrc\_T                                                              & freq\_op                                                             & \np{rn\_rdt} $\times$ \np{nn\_dttrc} \\ \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_dttrc}{nn\_dttrc}                                \\ \hline diad\_T                                                              & freq\_op                                                             & \np{rn\_rdt} $\times$ \np{nn\_dttrc} \\ \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_dttrc}{nn\_dttrc}                                \\ \hline EqT, EqU, EqW                                                        & jbegin, ni,                                                          & according to the grid                \\ & according to the grid                                                \\ & name\_suffix                                                         & \\ \\ \hline TAO, RAMA and PIRATA moorings                                        & zoom\_ibegin, zoom\_jbegin,                                          & according to the grid                \\ & according to the grid                                                \\ & name\_suffix                                                         & \\ \hline \end{tabularx} \\ \hline \end{tabular} \end{table} %% ================================================================================================= \subsubsection{Advanced use of XIOS functionalities} %% ================================================================================================= \subsection{XML reference tables} \label{subsec:IOM_xmlref} \label{subsec:DIA_IOM_xmlref} \begin{enumerate} \item Simple computation: directly define the computation when refering to the variable in the file definition. \item Simple computation: directly define the computation when refering to the variable in the file definition. \begin{xmllines} \end{xmllines} \item Simple computation: define a new variable and use it in the file definition. \item Simple computation: define a new variable and use it in the file definition. in field\_definition: sst2 won't be evaluated. \item Change of variable precision: \item Change of variable precision: \begin{xmllines} Forcing double precision outputs with prec="8" (for example in the field\_definition) will avoid this problem. \item add user defined attributes: \item add user defined attributes: \begin{xmllines} \end{xmllines} \item use of the @'' function: example 1, weighted temporal average \item use of the @'' function: example 1, weighted temporal average - define a new variable in field\_definition Note that in this case, freq\_op must be equal to the file output\_freq. \item use of the @'' function: example 2, monthly SSH standard deviation \item use of the @'' function: example 2, monthly SSH standard deviation - define a new variable in field\_definition Note that in this case, freq\_op must be equal to the file output\_freq. \item use of the @'' function: example 3, monthly average of SST diurnal cycle \item use of the @'' function: example 3, monthly average of SST diurnal cycle - define 2 new variables in field\_definition field\_ref="sst" means that attributes not explicitely defined, are inherited from sst field. %% ================================================================================================= \subsubsection{Tag list per family} \begin{table} \scriptsize \begin{tabularx}{\textwidth}{|l|X|X|l|X|} \hline \hline \end{tabularx} \caption{Context tags} \caption{XIOS: context tags} \end{table} \begin{table} \scriptsize \begin{tabularx}{\textwidth}{|l|X|X|X|l|} \hline \hline \end{tabularx} \caption{Field tags ("\ttfamily{field\_*}")} \caption{XIOS: field tags ("\texttt{field\_*}")} \end{table} \begin{table} \scriptsize \begin{tabularx}{\textwidth}{|l|X|X|X|l|} \hline \hline \end{tabularx} \caption{File tags ("\ttfamily{file\_*}")} \caption{XIOS: file tags ("\texttt{file\_*}")} \end{table} \begin{table} \scriptsize \begin{tabularx}{\textwidth}{|l|X|X|X|X|} \hline \hline \end{tabularx} \caption{Axis tags ("\ttfamily{axis\_*}")} \caption{XIOS: axis tags ("\texttt{axis\_*}")} \end{table} \begin{table} \scriptsize \begin{tabularx}{\textwidth}{|l|X|X|X|X|} \hline \hline \end{tabularx} \caption{Domain tags ("\ttfamily{domain\_*)}"} \caption{XIOS: domain tags ("\texttt{domain\_*)}"} \end{table} \begin{table} \scriptsize \begin{tabularx}{\textwidth}{|l|X|X|X|X|} \hline \hline \end{tabularx} \caption{Grid tags ("\ttfamily{grid\_*}")} \caption{XIOS: grid tags ("\texttt{grid\_*}")} \end{table} %% ================================================================================================= \subsubsection{Attributes list per family} \begin{table} \scriptsize \begin{tabularx}{\textwidth}{|l|X|l|l|} \hline \hline \end{tabularx} \caption{Reference attributes ("\ttfamily{*\_ref}")} \caption{XIOS: reference attributes ("\texttt{*\_ref}")} \end{table} \begin{table} \scriptsize \begin{tabularx}{\textwidth}{|l|X|l|l|} \hline \hline \end{tabularx} \caption{Domain attributes ("\ttfamily{zoom\_*}")} \caption{XIOS: domain attributes ("\texttt{zoom\_*}")} \end{table} \begin{table} \scriptsize \begin{tabularx}{\textwidth}{|l|X|l|l|} \hline \hline \end{tabularx} \caption{File attributes} \caption{XIOS: file attributes} \end{table} \begin{table} \scriptsize \begin{tabularx}{\textwidth}{|l|X|l|l|} \hline \hline \end{tabularx} \caption{Field attributes} \caption{XIOS: field attributes} \end{table} \begin{table} \scriptsize \begin{tabularx}{\textwidth}{|l|X|X|X|} \hline \hline \end{tabularx} \caption{Miscellaneous attributes} \caption{XIOS: miscellaneous attributes} \end{table} %% ================================================================================================= \subsection{CF metadata standard compliance} the CF metadata standard. Therefore while a user may wish to add their own metadata to the output files (as demonstrated in example 4 of section \autoref{subsec:IOM_xmlref}) the metadata should, for the most part, comply with the CF-1.5 standard. section \autoref{subsec:DIA_IOM_xmlref}) the metadata should, for the most part, comply with the CF-1.5 standard. Some metadata that may significantly increase the file size (horizontal cell areas and vertices) are controlled by the namelist parameter \np{ln\_cfmeta} in the \nam{run} namelist. the namelist parameter \np{ln_cfmeta}{ln\_cfmeta} in the \nam{run}{run} namelist. This must be set to true if these metadata are to be included in the output files. % ================================================================ %       NetCDF4 support % ================================================================ \section[NetCDF4 support (\texttt{\textbf{key\_netcdf4}})] {NetCDF4 support (\protect\key{netcdf4})} %% ================================================================================================= \section[NetCDF4 support (\texttt{\textbf{key\_netcdf4}})]{NetCDF4 support (\protect\key{netcdf4})} \label{sec:DIA_nc4} most analysis codes can be relinked simply with the new libraries and will then read both NetCDF3 and NetCDF4 files. \NEMO\ executables linked with NetCDF4 libraries can be made to produce NetCDF3 files by setting the \np{ln\_nc4zip} logical to false in the \nam{nc4} namelist: %------------------------------------------namnc4---------------------------------------------------- \nlst{namnc4} %------------------------------------------------------------------------------------------------------------- setting the \np{ln_nc4zip}{ln\_nc4zip} logical to false in the \nam{nc4}{nc4} namelist: \begin{listing} \nlst{namnc4} \caption{\forcode{&namnc4}} \label{lst:namnc4} \end{listing} If \key{netcdf4} has not been defined, these namelist parameters are not read. In this case, \np{ln\_nc4zip} is set false and dummy routines for a few NetCDF4-specific functions are defined. In this case, \np{ln_nc4zip}{ln\_nc4zip} is set false and dummy routines for a few NetCDF4-specific functions are defined. These functions will not be used but need to be included so that compilation is possible with NetCDF3 libraries. \end{forlines} \noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\ttfamily 46x38x1} respectively in the mono-processor case (\ie\ global domain of {\small\ttfamily 182x149x31}). \noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\texttt 46x38x1} respectively in the mono-processor case (\ie\ global domain of {\small\texttt 182x149x31}). An illustration of the potential space savings that NetCDF4 chunking and compression provides is given in table \autoref{tab:NC4} which compares the results of two short runs of the ORCA2\_LIM reference configuration with table \autoref{tab:DIA_NC4} which compares the results of two short runs of the ORCA2\_LIM reference configuration with a 4x2 mpi partitioning. Note the variation in the compression ratio achieved which reflects chiefly the dry to wet volume ratio of each processing region. %------------------------------------------TABLE---------------------------------------------------- \begin{table} \scriptsize \centering \begin{tabular}{lrrr} ORCA2\_2d\_grid\_W\_0007.nc & 4416    & 1368     & 70\%      \\ \end{tabular} \caption{ \protect\label{tab:NC4} Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression } \caption{Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression} \label{tab:DIA_NC4} \end{table} %---------------------------------------------------------------------------------------------------- When \key{iomput} is activated with \key{netcdf4} chunking and compression parameters for fields produced via \rou{iom\_put} calls are set via an equivalent and identically named namelist to \nam{nc4} in \rou{iom\_put} calls are set via an equivalent and identically named namelist to \nam{nc4}{nc4} in \textit{xmlio\_server.def}. Typically this namelist serves the mean files whilst the \nam{nc4} in the main namelist file continues to Typically this namelist serves the mean files whilst the \nam{nc4}{nc4} in the main namelist file continues to serve the restart files. This duplication is unfortunate but appropriate since, if using io\_servers, the domain sizes of the invidual processing regions and different chunking choices may be desired. % ------------------------------------------------------------------------------------------------------------- %       Tracer/Dynamics Trends % ------------------------------------------------------------------------------------------------------------- \section[Tracer/Dynamics trends (\texttt{namtrd})] {Tracer/Dynamics trends (\protect\nam{trd})} %% ================================================================================================= \section[Tracer/Dynamics trends (\forcode{&namtrd})]{Tracer/Dynamics trends (\protect\nam{trd}{trd})} \label{sec:DIA_trd} %------------------------------------------namtrd---------------------------------------------------- \nlst{namtrd} %------------------------------------------------------------------------------------------------------------- \begin{listing} \nlst{namtrd} \caption{\forcode{&namtrd}} \label{lst:namtrd} \end{listing} Each trend of the dynamics and/or temperature and salinity time evolution equations can be send to \mdl{trddyn} and/or \mdl{trdtra} modules (see TRD directory) just after their computation (\ie\ at the end of each \textit{dyn....F90} and/or \textit{tra....F90} routines). This capability is controlled by options offered in \nam{trd} namelist. This capability is controlled by options offered in \nam{trd}{trd} namelist. Note that the output are done with XIOS, and therefore the \key{iomput} is required. What is done depends on the \nam{trd} logical set to \forcode{.true.}: What is done depends on the \nam{trd}{trd} logical set to \forcode{.true.}: \begin{description} \item[\np{ln\_glo\_trd}]: at each \np{nn\_trd} time-step a check of the basin averaged properties of \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 the momentum and tracer equations is performed. This also includes a check of $T^2$, $S^2$, $\tfrac{1}{2} (u^2+v2)$, and potential energy time evolution equations properties; \item[\np{ln\_dyn\_trd}]: each 3D trend of the evolution of the two momentum components is output; \item[\np{ln\_dyn\_mxl}]: each 3D trend of the evolution of the two momentum components averaged over the mixed layer is output; \item[\np{ln\_vor\_trd}]: a vertical summation of the moment tendencies is performed, \item [{\np{ln_dyn_trd}{ln\_dyn\_trd}}]: each 3D trend of the evolution of the two momentum components is output; \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; \item [{\np{ln_vor_trd}{ln\_vor\_trd}}]: a vertical summation of the moment tendencies is performed, then the curl is computed to obtain the barotropic vorticity tendencies which are output; \item[\np{ln\_KE\_trd}] : each 3D trend of the Kinetic Energy equation is output; \item[\np{ln\_tra\_trd}]: each 3D trend of the evolution of temperature and salinity is output; \item[\np{ln\_tra\_mxl}]: each 2D trend of the evolution of temperature and salinity averaged over the mixed layer is output; \item [{\np{ln_KE_trd}{ln\_KE\_trd}}]  : each 3D trend of the Kinetic Energy equation is output; \item [{\np{ln_tra_trd}{ln\_tra\_trd}}]: each 3D trend of the evolution of temperature and salinity is output; \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; \end{description} \textbf{Note that} in the current version (v3.6), many changes has been introduced but not fully tested. In particular, options associated with \np{ln\_dyn\_mxl}, \np{ln\_vor\_trd}, and \np{ln\_tra\_mxl} are not working, and none of the options have been tested with variable volume (\ie\ \np{ln\_linssh}\forcode{ = .true.}). % ------------------------------------------------------------------------------------------------------------- %       On-line Floats trajectories % ------------------------------------------------------------------------------------------------------------- \section[FLO: On-Line Floats trajectories (\texttt{\textbf{key\_floats}})] {FLO: On-Line Floats trajectories (\protect\key{floats})} \label{sec:FLO} %--------------------------------------------namflo------------------------------------------------------- \nlst{namflo} %-------------------------------------------------------------------------------------------------------------- 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, and none of the options have been tested with variable volume (\ie\ \np[=.true.]{ln_linssh}{ln\_linssh}). %% ================================================================================================= \section[FLO: On-Line Floats trajectories (\texttt{\textbf{key\_floats}})]{FLO: On-Line Floats trajectories (\protect\key{floats})} \label{sec:DIA_FLO} \begin{listing} \nlst{namflo} \caption{\forcode{&namflo}} \label{lst:namflo} \end{listing} The on-line computation of floats advected either by the three dimensional velocity field or constraint to remain at a given depth ($w = 0$ in the computation) have been introduced in the system during the CLIPPER project. Options are defined by \nam{flo} namelist variables. Options are defined by \nam{flo}{flo} namelist variables. The algorithm used is based either on the work of \cite{blanke.raynaud_JPO97} (default option), or on a $4^th$ Runge-Hutta algorithm (\np{ln\_flork4}\forcode{ = .true.}). or on a $4^th$ Runge-Hutta algorithm (\np[=.true.]{ln_flork4}{ln\_flork4}). Note that the \cite{blanke.raynaud_JPO97} algorithm have the advantage of providing trajectories which are consistent with the numeric of the code, so that the trajectories never intercept the bathymetry. %% ================================================================================================= \subsubsection{Input data: initial coordinates} Initial coordinates can be given with Ariane Tools convention (IJK coordinates, (\np{ln\_ariane}\forcode{ = .true.}) ) or with longitude and latitude. (IJK coordinates, (\np[=.true.]{ln_ariane}{ln\_ariane}) ) or with longitude and latitude. In case of Ariane convention, input filename is \textit{init\_float\_ariane}. Its format is: \\ {\scriptsize \texttt{I J K nisobfl itrash}} { \texttt{I J K nisobfl itrash}} \noindent with: \noindent Example: \\ \noindent {\scriptsize { \texttt{ 100.00000  90.00000  -1.50000 1.00000   0.00000   \\ In the other case (longitude and latitude), input filename is init\_float. Its format is: \\ {\scriptsize \texttt{Long Lat depth nisobfl ngrpfl itrash}} { \texttt{Long Lat depth nisobfl ngrpfl itrash}} \noindent with: \noindent Example: \\ \noindent {\scriptsize { \texttt{ 20.0 0.0 0.0 0 1 1    \\ } \\ \np{jpnfl} is the total number of floats during the run. When initial positions are read in a restart file (\np{ln\_rstflo}\forcode{ = .true.} ), \np{jpnflnewflo} can be added in the initialization file. \np{jpnfl}{jpnfl} is the total number of floats during the run. When initial positions are read in a restart file (\np[=.true.]{ln_rstflo}{ln\_rstflo} ), \np{jpnflnewflo}{jpnflnewflo} can be added in the initialization file. %% ================================================================================================= \subsubsection{Output data} \np{nn\_writefl} is the frequency of writing in float output file and \np{nn\_stockfl} is the frequency of \np{nn_writefl}{nn\_writefl} is the frequency of writing in float output file and \np{nn_stockfl}{nn\_stockfl} is the frequency of creation of the float restart file. Output data can be written in ascii files (\np{ln\_flo\_ascii}\forcode{ = .true.}). Output data can be written in ascii files (\np[=.true.]{ln_flo_ascii}{ln\_flo\_ascii}). In that case, output filename is trajec\_float. Another possiblity of writing format is Netcdf (\np{ln\_flo\_ascii}\forcode{ = .false.}) with Another possiblity of writing format is Netcdf (\np[=.false.]{ln_flo_ascii}{ln\_flo\_ascii}) with \key{iomput} and outputs selected in iodef.xml. Here it is an example of specification to put in files description section: \end{xmllines} % ------------------------------------------------------------------------------------------------------------- %       Harmonic analysis of tidal constituents % ------------------------------------------------------------------------------------------------------------- \section[Harmonic analysis of tidal constituents (\texttt{\textbf{key\_diaharm}})] {Harmonic analysis of tidal constituents (\protect\key{diaharm})} %% ================================================================================================= \section[Harmonic analysis of tidal constituents (\texttt{\textbf{key\_diaharm}})]{Harmonic analysis of tidal constituents (\protect\key{diaharm})} \label{sec:DIA_diag_harm} %------------------------------------------nam_diaharm---------------------------------------------------- % \nlst{nam_diaharm} %---------------------------------------------------------------------------------------------------------- \begin{listing} \nlst{nam_diaharm} \caption{\forcode{&nam_diaharm}} \label{lst:nam_diaharm} \end{listing} A module is available to compute the amplitude and phase of tidal waves. This on-line Harmonic analysis is actived with \key{diaharm}. Some parameters are available in namelist \nam{\_diaharm}: - \np{nit000\_han} is the first time step used for harmonic analysis - \np{nitend\_han} is the  last time step used for harmonic analysis - \np{nstep\_han}  is the  time step frequency for harmonic analysis % - \np{nb\_ana}     is the number of harmonics to analyse - \np{tname}       is an array with names of tidal constituents to analyse \np{nit000\_han} and \np{nitend\_han} must be between \np{nit000} and \np{nitend} of the simulation. Some parameters are available in namelist \nam{_diaharm}{\_diaharm}: - \np{nit000_han}{nit000\_han} is the first time step used for harmonic analysis - \np{nitend_han}{nitend\_han} is the  last time step used for harmonic analysis - \np{nstep_han}{nstep\_han}  is the  time step frequency for harmonic analysis % - \np{nb_ana}{nb\_ana}     is the number of harmonics to analyse - \np{tname}{tname}       is an array with names of tidal constituents to analyse \np{nit000_han}{nit000\_han} and \np{nitend_han}{nitend\_han} must be between \np{nit000}{nit000} and \np{nitend}{nitend} of the simulation. The restart capability is not implemented. We obtain in output $C_{j}$ and $S_{j}$ for each tidal wave. % ------------------------------------------------------------------------------------------------------------- %       Sections transports % ------------------------------------------------------------------------------------------------------------- \section[Transports across sections (\texttt{\textbf{key\_diadct}})] {Transports across sections (\protect\key{diadct})} %% ================================================================================================= \section[Transports across sections (\texttt{\textbf{key\_diadct}})]{Transports across sections (\protect\key{diadct})} \label{sec:DIA_diag_dct} %------------------------------------------namdct---------------------------------------------------- \nlst{namdct} %------------------------------------------------------------------------------------------------------------- \begin{listing} \nlst{nam_diadct} \caption{\forcode{&nam_diadct}} \label{lst:nam_diadct} \end{listing} A module is available to compute the transport of volume, heat and salt through sections. - \texttt{salt\_transport}   for   salt transports (unit: $10^{9}Kg s^{-1}$) \\ Namelist variables in \nam{dct} control how frequently the flows are summed and the time scales over which Namelist variables in \nam{_diadct}{\_diadct} control how frequently the flows are summed and the time scales over which they are averaged, as well as the level of output for debugging: \np{nn\_dct}   : frequency of instantaneous transports computing \np{nn\_dctwri}: frequency of writing ( mean of instantaneous transports ) \np{nn\_debug} : debugging of the section \np{nn_dct}{nn\_dct}   : frequency of instantaneous transports computing \np{nn_dctwri}{nn\_dctwri}: frequency of writing ( mean of instantaneous transports ) \np{nn_debug}{nn\_debug} : debugging of the section %% ================================================================================================= \subsubsection{Creating a binary file containing the pathway of each section} Each section is defined by: \\ \noindent {\scriptsize \texttt{long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name}} \\ \noindent { \texttt{long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name}} \\ with: \noindent If nclass $\neq$ 0, the next lines contain the class type and the nclass bounds: \\ {\scriptsize { \texttt{ long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name \\ and the ATL\_Cuba\_Florida with 4 temperature clases (5 class bounds), are shown: \\ \noindent {\scriptsize { \texttt{ -68.    -54.5   -60.    -64.7  00 okstrpond noice ACC\_Drake\_Passage \\ } %% ================================================================================================= \subsubsection{To read the output files} The output format is: \\ {\scriptsize { \texttt{ date, time-step number, section number,                \\ \begin{table} \scriptsize \begin{tabular}{|l|l|l|l|l|} \hline \end{table} % ================================================================ % Steric effect in sea surface height % ================================================================ %% ================================================================================================= \section{Diagnosing the steric effect in sea surface height} \label{sec:DIA_steric} Changes in steric sea level are caused when changes in the density of the water column imply an expansion or \mathcal{V} &=  \mathcal{A}  \;\bar{\eta} \end{split} \label{eq:MV_nBq} \label{eq:DIA_MV_nBq} \frac{1}{e_3} \partial_t ( e_3\,\rho) + \nabla( \rho \, \textbf{U} ) = \left. \frac{\textit{emp}}{e_3}\right|_\textit{surface} \label{eq:Co_nBq} \label{eq:DIA_Co_nBq} \partial_t \mathcal{M} = \mathcal{A} \;\overline{\textit{emp}} \label{eq:Mass_nBq} \label{eq:DIA_Mass_nBq} where $\overline{\textit{emp}} = \int_S \textit{emp}\,ds$ is the net mass flux through the ocean surface. Bringing \autoref{eq:Mass_nBq} and the time derivative of \autoref{eq:MV_nBq} together leads to Bringing \autoref{eq:DIA_Mass_nBq} and the time derivative of \autoref{eq:DIA_MV_nBq} together leads to the evolution equation of the mean sea level \partial_t \bar{\eta} = \frac{\overline{\textit{emp}}}{ \bar{\rho}} - \frac{\mathcal{V}}{\mathcal{A}} \;\frac{\partial_t \bar{\rho} }{\bar{\rho}} \label{eq:ssh_nBq} \label{eq:DIA_ssh_nBq} The first term in equation \autoref{eq:ssh_nBq} alters sea level by adding or subtracting mass from the ocean. The first term in equation \autoref{eq:DIA_ssh_nBq} alters sea level by adding or subtracting mass from the ocean. The second term arises from temporal changes in the global mean density; \ie\ from steric effects. In a Boussinesq fluid, $\rho$ is replaced by $\rho_o$ in all the equation except when $\rho$ appears multiplied by the gravity (\ie\ in the hydrostatic balance of the primitive Equations). In particular, the mass conservation equation, \autoref{eq:Co_nBq}, degenerates into the incompressibility equation: In particular, the mass conservation equation, \autoref{eq:DIA_Co_nBq}, degenerates into the incompressibility equation: $\frac{1}{e_3} \partial_t ( e_3 ) + \nabla( \textbf{U} ) = \left. \frac{\textit{emp}}{\rho_o \,e_3}\right|_ \textit{surface} % \label{eq:Co_Bq} % \label{eq:DIA_Co_Bq}$ $\partial_t \mathcal{V} = \mathcal{A} \;\frac{\overline{\textit{emp}}}{\rho_o} % \label{eq:V_Bq} % \label{eq:DIA_V_Bq}$ \mathcal{M}_o = \mathcal{M} + \rho_o \,\eta_s \,\mathcal{A} \label{eq:M_Bq} \label{eq:DIA_M_Bq} Introducing the total density anomaly, $\mathcal{D}= \int_D d_a \,dv$, where $d_a = (\rho -\rho_o ) / \rho_o$ is the density anomaly used in \NEMO\ (cf. \autoref{subsec:TRA_eos}) in \autoref{eq:M_Bq} leads to a very simple form for the steric height: in \autoref{eq:DIA_M_Bq} leads to a very simple form for the steric height: \eta_s = - \frac{1}{\mathcal{A}} \mathcal{D} \label{eq:steric_Bq} \label{eq:DIA_steric_Bq} (wetting and drying of grid point is not allowed). Third, the discretisation of \autoref{eq:steric_Bq} depends on the type of free surface which is considered. In the non linear free surface case, \ie\ \np{ln\_linssh}\forcode{ = .true.}, it is given by Third, the discretisation of \autoref{eq:DIA_steric_Bq} depends on the type of free surface which is considered. In the non linear free surface case, \ie\ \np[=.true.]{ln_linssh}{ln\_linssh}, it is given by $\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} } % \label{eq:discrete_steric_Bq_nfs} % \label{eq:DIA_discrete_steric_Bq_nfs}$ \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 } { \sum_{i,\,j,\,k}       e_{1t}e_{2t}e_{3t} + \sum_{i,\,j}       e_{1t}e_{2t} \eta } % \label{eq:discrete_steric_Bq_fs} % \label{eq:DIA_discrete_steric_Bq_fs} \] $\eta_s = - \frac{1}{\mathcal{A}} \int_D d_a(T,S_o,p_o) \,dv % \label{eq:thermosteric_Bq} % \label{eq:DIA_thermosteric_Bq}$ Both steric and thermosteric sea level are computed in \mdl{diaar5}. % ------------------------------------------------------------------------------------------------------------- %       Other Diagnostics % ------------------------------------------------------------------------------------------------------------- \section[Other diagnostics] {Other diagnostics} %% ================================================================================================= \section{Other diagnostics} \label{sec:DIA_diag_others} The available ready-to-add diagnostics modules can be found in directory DIA. \subsection[Depth of various quantities (\textit{diahth.F90})] {Depth of various quantities (\protect\mdl{diahth})} %% ================================================================================================= \subsection[Depth of various quantities (\textit{diahth.F90})]{Depth of various quantities (\protect\mdl{diahth})} Among the available diagnostics the following ones are obtained when defining the \key{diahth} CPP key: - the depth of the thermocline (maximum of the vertical temperature gradient) (\mdl{diahth}) %>>>>>>>>>>>>>>>>>>>>>>>>>>>> \begin{figure}[!t] \begin{center} \includegraphics[width=\textwidth]{Fig_mask_subasins} \caption{ \protect\label{fig:mask_subasins} Decomposition of the World Ocean (here ORCA2) into sub-basin used in to compute the heat and salt transports as well as the meridional stream-function: Atlantic basin (red), Pacific basin (green), Indian basin (bleue), Indo-Pacific basin (bleue+green). Note that semi-enclosed seas (Red, Med and Baltic seas) as well as Hudson Bay are removed from the sub-basins. Note also that the Arctic Ocean has been split into Atlantic and Pacific basins along the North fold line. } \end{center} \centering \includegraphics[width=0.66\textwidth]{DIA_mask_subasins} \caption[Decomposition of the World Ocean to compute transports as well as the meridional stream-function]{ Decomposition of the World Ocean (here ORCA2) into sub-basin used in to compute the heat and salt transports as well as the meridional stream-function: Atlantic basin (red), Pacific basin (green), Indian basin (blue), Indo-Pacific basin (blue+green). Note that semi-enclosed seas (Red, Med and Baltic seas) as well as Hudson Bay are removed from the sub-basins. Note also that the Arctic Ocean has been split into Atlantic and Pacific basins along the North fold line. } \label{fig:DIA_mask_subasins} \end{figure} %>>>>>>>>>>>>>>>>>>>>>>>>>>>> % ----------------------------------------------------------- %       CMIP specific diagnostics % ----------------------------------------------------------- \subsection[CMIP specific diagnostics (\textit{diaar5.F90}, \textit{diaptr.F90})] {CMIP specific diagnostics (\protect\mdl{diaar5})} %% ================================================================================================= \subsection[CMIP specific diagnostics (\textit{diaar5.F90}, \textit{diaptr.F90})]{CMIP specific diagnostics (\protect\mdl{diaar5})} A series of diagnostics has been added in the \mdl{diaar5} and \mdl{diaptr}. sea water pressure at sea floor (botpres), dynamic sea surface height (sshdyn). In \mdl{diaptr} when \np{ln\_diaptr}\forcode{ = .true.} (see the \nam{ptr} namelist below) can be computed on-line the poleward heat and salt transports, In \mdl{diaptr} when \np[=.true.]{ln_diaptr}{ln\_diaptr} (see the \nam{ptr}{ptr} namelist below) can be computed on-line the poleward heat and salt transports, their advective and diffusive component, and the meriodional stream function . When \np{ln\_subbas}\forcode{ = .true.}, transports and stream function are computed for the Atlantic, Indian, When \np[=.true.]{ln_subbas}{ln\_subbas}, transports and stream function are computed for the Atlantic, Indian, Pacific and Indo-Pacific Oceans (defined north of 30\deg{S}) as well as for the World Ocean. The sub-basin decomposition requires an input file (\ifile{subbasins}) which contains three 2D mask arrays, the Indo-Pacific mask been deduced from the sum of the Indian and Pacific mask (\autoref{fig:mask_subasins}). %------------------------------------------namptr----------------------------------------- \nlst{namptr} %----------------------------------------------------------------------------------------- % ----------------------------------------------------------- %       25 hour mean and hourly Surface, Mid and Bed % ----------------------------------------------------------- the Indo-Pacific mask been deduced from the sum of the Indian and Pacific mask (\autoref{fig:DIA_mask_subasins}). \begin{listing} \nlst{namptr} \caption{\forcode{&namptr}} \label{lst:namptr} \end{listing} %% ================================================================================================= \subsection{25 hour mean output for tidal models} %------------------------------------------nam_dia25h------------------------------------- \nlst{nam_dia25h} %----------------------------------------------------------------------------------------- \begin{listing} \nlst{nam_dia25h} \caption{\forcode{&nam_dia25h}} \label{lst:nam_dia25h} \end{listing} A module is available to compute a crudely detided M2 signal by obtaining a 25 hour mean. This diagnostic is actived with the logical $ln\_dia25h$. % ----------------------------------------------------------- %     Top Middle and Bed hourly output % ----------------------------------------------------------- %% ================================================================================================= \subsection{Top middle and bed hourly output} %------------------------------------------nam_diatmb----------------------------------------------------- \nlst{nam_diatmb} %---------------------------------------------------------------------------------------------------------- \begin{listing} \nlst{nam_diatmb} \caption{\forcode{&nam_diatmb}} \label{lst:nam_diatmb} \end{listing} A module is available to output the surface (top), mid water and bed diagnostics of a set of standard variables. This diagnostic is actived with the logical $ln\_diatmb$. % ----------------------------------------------------------- %     Courant numbers % ----------------------------------------------------------- %% ================================================================================================= \subsection{Courant numbers} $C_u = |u|\frac{\rdt}{e_{1u}}, \quad C_v = |v|\frac{\rdt}{e_{2v}}, \quad C_w = |w|\frac{\rdt}{e_{3w}} % \label{eq:CFL} % \label{eq:DIA_CFL}$ Values greater than 1 indicate that information is propagated across more than one grid cell in a single time step. The variables can be activated by setting the \np{nn\_diacfl} namelist parameter to 1 in the \nam{ctl} namelist. The variables can be activated by setting the \np{nn_diacfl}{nn\_diacfl} namelist parameter to 1 in the \nam{ctl}{ctl} namelist. The diagnostics will be written out to an ascii file named cfl\_diagnostics.ascii. In this file the maximum value of $C_u$, $C_v$, and $C_w$ are printed at each timestep along with the coordinates of The maximum values from the run are also copied to the ocean.output file. % ================================================================ \biblio \pindex \onlyinsubfile{\input{../../global/epilogue}} \end{document}
• ## NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO/subfiles/chap_DIU.tex

 r11435 \begin{document} % ================================================================ % Diurnal SST models (DIU) % Edited by James While % ================================================================ \chapter{Diurnal SST Models (DIU)} \label{chap:DIU} \thispagestyle{plain} \chaptertoc \paragraph{Changes record} ~\\ \newpage $\$\newline % force a new line {\footnotesize \begin{tabularx}{\textwidth}{l||X|X} Release & Author(s) & Modifications \\ \hline {\em   4.0} & {\em ...} & {\em ...} \\ {\em   3.6} & {\em ...} & {\em ...} \\ {\em   3.4} & {\em ...} & {\em ...} \\ {\em <=3.4} & {\em ...} & {\em ...} \end{tabularx} } \clearpage Code to produce an estimate of the diurnal warming and cooling of the sea surface skin The skin temperature can be split into three parts: \begin{itemize} \item A foundation SST which is free from diurnal warming. \item A warm layer, typically ~3\,m thick, \item A foundation SST which is free from diurnal warming. \item A warm layer, typically ~3\,m thick, where heating from solar radiation can cause a warm stably stratified layer during the daytime \item A cool skin, a thin layer, approximately ~1\, mm thick, \item A cool skin, a thin layer, approximately ~1\, mm thick, where long wave cooling is dominant and cools the immediate ocean surface. \end{itemize} both must be added to a foundation SST to obtain the true skin temperature. Both the cool skin and warm layer models are controlled through the namelist \nam{diu}: Both the cool skin and warm layer models are controlled through the namelist \nam{diu}{diu}: \nlst{namdiu} \begin{listing} \nlst{namdiu} \caption{\forcode{&namdiu}} \label{lst:namdiu} \end{listing} This namelist contains only two variables: \begin{description} \item[\np{ln\_diurnal}] A logical switch for turning on/off both the cool skin and warm layer. \item[\np{ln\_diurnal\_only}] A logical switch which if \forcode{.true.} will run the diurnal model without the other dynamical parts of \NEMO. \np{ln\_diurnal\_only} must be \forcode{.false.} if \np{ln\_diurnal} is \forcode{.false.}. \item [{\np{ln_diurnal}{ln\_diurnal}}] A logical switch for turning on/off both the cool skin and warm layer. \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. \np{ln_diurnal_only}{ln\_diurnal\_only} must be \forcode{.false.} if \np{ln_diurnal}{ln\_diurnal} is \forcode{.false.}. \end{description} The cool skin model, which is determined purely by the instantaneous fluxes, has no initialisation variable. %=============================================================== %% ================================================================================================= \section{Warm layer model} \label{sec:warm_layer_sec} %=============================================================== \label{sec:DIU_warm_layer_sec} The warm layer is calculated using the model of \citet{takaya.bidlot.ea_JGR10} (TAKAYA10 model hereafter). \frac{\partial{\Delta T_{\mathrm{wl}}}}{\partial{t}}&=&\frac{Q(\nu+1)}{D_T\rho_w c_p \nu}-\frac{(\nu+1)ku^*_{w}f(L_a)\Delta T}{D_T\Phi\!\left(\frac{D_T}{L}\right)} \mbox{,} \label{eq:ecmwf1} \\ L&=&\frac{\rho_w c_p u^{*^3}_{w}}{\kappa g \alpha_w Q }\mbox{,}\label{eq:ecmwf2} \label{eq:DIU_ecmwf1} \\ L&=&\frac{\rho_w c_p u^{*^3}_{w}}{\kappa g \alpha_w Q }\mbox{,}\label{eq:DIU_ecmwf2} \end{align} 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. In equation (\autoref{eq:ecmwf1}) $\alpha_w=2\times10^{-4}$ is the thermal expansion coefficient of water, In equation (\autoref{eq:DIU_ecmwf1}) $\alpha_w=2\times10^{-4}$ is the thermal expansion coefficient of water, $\kappa=0.4$ is von K\'{a}rm\'{a}n's constant, $c_p$ is the heat capacity at constant pressure of sea water, $\rho_w$ is the water density, and $L$ is the Monin-Obukhov length. the relationship $u^*_{w} = u_{10}\sqrt{\frac{C_d\rho_a}{\rho_w}}$, where $C_d$ is the drag coefficient, and $\rho_a$ is the density of air. The symbol $Q$ in equation (\autoref{eq:ecmwf1}) is the instantaneous total thermal energy flux into The symbol $Q$ in equation (\autoref{eq:DIU_ecmwf1}) is the instantaneous total thermal energy flux into the diurnal layer, \ie $Q = Q_{\mathrm{sol}} + Q_{\mathrm{lw}} + Q_{\mathrm{h}}\mbox{,} % \label{eq:e_flux_eqn} % \label{eq:DIU_e_flux_eqn}$ where $Q_{\mathrm{h}}$ is the sensible and latent heat flux, $Q_{\mathrm{lw}}$ is the long wave flux, and $Q_{\mathrm{sol}}$ is the solar flux absorbed within the diurnal warm layer. For $Q_{\mathrm{sol}}$ the 9 term representation of \citet{gentemann.minnett.ea_JGR09} is used. In equation \autoref{eq:ecmwf1} the function $f(L_a)=\max(1,L_a^{\frac{2}{3}})$, In equation \autoref{eq:DIU_ecmwf1} the function $f(L_a)=\max(1,L_a^{\frac{2}{3}})$, where $L_a=0.3$\footnote{ This is a global average value, more accurately $L_a$ could be computed as $L_a=(u^*_{w}/u_s)^{\frac{1}{2}}$, 4\zeta^2}{1+3\zeta+0.25\zeta^2} &(\zeta \ge 0) \\ (1 - 16\zeta)^{-\frac{1}{2}} & (\zeta < 0) \mbox{,} \end{array} \right. \label{eq:stab_func_eqn} \end{array} \right. \label{eq:DIU_stab_func_eqn} where $\zeta=\frac{D_T}{L}$.  It is clear that the first derivative of (\autoref{eq:stab_func_eqn}), and thus of (\autoref{eq:ecmwf1}), is discontinuous at $\zeta=0$ (\ie\ $Q\rightarrow0$ in equation (\autoref{eq:ecmwf2})). where $\zeta=\frac{D_T}{L}$.  It is clear that the first derivative of (\autoref{eq:DIU_stab_func_eqn}), and thus of (\autoref{eq:DIU_ecmwf1}), is discontinuous at $\zeta=0$ (\ie\ $Q\rightarrow0$ in equation (\autoref{eq:DIU_ecmwf2})). The two terms on the right hand side of (\autoref{eq:ecmwf1}) represent different processes. The two terms on the right hand side of (\autoref{eq:DIU_ecmwf1}) represent different processes. The first term is simply the diabatic heating or cooling of the diurnal warm layer due to thermal energy fluxes into and out of the layer. In practice the second term acts as a relaxation on the temperature. %=============================================================== %% ================================================================================================= \section{Cool skin model} \label{sec:cool_skin_sec} %=============================================================== \label{sec:DIU_cool_skin_sec} 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}$. 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 $% \label{eq:sunders_eqn} % \label{eq:DIU_sunders_eqn} \Delta T_{\mathrm{cs}}=\frac{Q_{\mathrm{ns}}\delta}{k_t} \mbox{,}$ $\delta$ is the thickness of the skin layer and is given by \label{eq:sunders_thick_eqn} \label{eq:DIU_sunders_thick_eqn} \delta=\frac{\lambda \mu}{u^*_{w}} \mbox{,} \citet{saunders_JAS67} suggested varied between 5 and 10. The value of $\lambda$ used in equation (\autoref{eq:sunders_thick_eqn}) is that of \citet{artale.iudicone.ea_JGR02}, The value of $\lambda$ used in equation (\autoref{eq:DIU_sunders_thick_eqn}) is that of \citet{artale.iudicone.ea_JGR02}, which is shown in \citet{tu.tsuang_GRL05} to outperform a number of other parametrisations at both low and high wind speeds. Specifically, $% \label{eq:artale_lambda_eqn} % \label{eq:DIU_artale_lambda_eqn} \lambda = \frac{ 8.64\times10^4 u^*_{w} k_t }{ \rho c_p h \mu \gamma }\mbox{,}$ $\gamma$ is a dimensionless function of wind speed $u$: $% \label{eq:artale_gamma_eqn} % \label{eq:DIU_artale_gamma_eqn} \gamma = \begin{cases}$ \biblio \pindex \onlyinsubfile{\input{../../global/epilogue}} \end{document}
• ## NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO/subfiles/chap_DOM.tex

 r11435 \begin{document} % ================================================================ % Chapter 2 ——— Space and Time Domain (DOM) % ================================================================ \chapter{Space Domain (DOM)} \label{chap:DOM} %\chaptertoc % Missing things: %  - istate: description of the initial state   ==> this has to be put elsewhere.. %                  perhaps in MISC ?  By the way the initialisation of T S and dynamics %                  should be put outside of DOM routine (better with TRC staff and off-line %                  tracers) %  -geo2ocean:  how to switch from geographic to mesh coordinate %     - domclo:  closed sea and lakes.... management of closea sea area : specific to global configuration, both forced and coupled \vfill \begin{table}[b] \footnotesize \caption*{Changes record} \begin{tabularx}{\textwidth}{l||X|X} Release & Author(s) & Modifications                                                          \\ \hline {\em 4.0} & {\em Simon M\"{u}ller \& Andrew Coward} & {\em Compatibility changes Major simplification has moved many of the options to external domain configuration tools. (see \autoref{apdx:DOMAINcfg}) }                                                                                            \\ {\em 3.x} & {\em Rachid Benshila, Gurvan Madec \& S\'{e}bastien Masson} & {\em First version}                                                                          \\ % Missing things % -    istate: description of the initial state   ==> this has to be put elsewhere.. %              perhaps in MISC ?  By the way the initialisation of T S and dynamics %              should be put outside of DOM routine (better with TRC staff and off-line %              tracers) % - geo2ocean: how to switch from geographic to mesh coordinate % -    domclo: closed sea and lakes.... %              management of closea sea area: specific to global cfg, both forced and coupled \thispagestyle{plain} \chaptertoc \paragraph{Changes record} ~\\ {\footnotesize \begin{tabularx}{0.8\textwidth}{l||X|X} Release                                                                                 & Author(s)                                                                               & Modifications                                                                           \\ \hline {\em 4.0                                                                              } & {\em Simon M\"{u}ller \& Andrew Coward \newline \newline Simona Flavoni and Tim Graham                                                       } & {\em Compatibility changes: many options moved to external domain configuration tools (see \autoref{apdx:DOMCFG}). \newline Updates                                                                             } \\ {\em 3.6                                                                              } & {\em Rachid Benshila, Christian \'{E}th\'{e}, Pierre Mathiot and Gurvan Madec         } & {\em Updates                                                                          } \\ {\em $\leq$ 3.4                                                                       } & {\em Gurvan Madec and S\'{e}bastien Masson                                            } & {\em First version                                                                    } \end{tabularx} \end{table} \newpage Having defined the continuous equations in \autoref{chap:PE} and chosen a time discretisation \autoref{chap:STP}, } \clearpage Having defined the continuous equations in \autoref{chap:MB} and chosen a time discretisation \autoref{chap:TD}, we need to choose a grid for spatial discretisation and related numerical algorithms. In the present chapter, we provide a general description of the staggered grid used in \NEMO, and other relevant information about the DOM (DOMain) source code modules. % ================================================================ % Fundamentals of the Discretisation % ================================================================ %% ================================================================================================= \section{Fundamentals of the discretisation} \label{sec:DOM_basics} % ------------------------------------------------------------------------------------------------------------- %        Arrangement of Variables % ------------------------------------------------------------------------------------------------------------- %% ================================================================================================= \subsection{Arrangement of variables} \label{subsec:DOM_cell} %>>>>>>>>>>>>>>>>>>>>>>>>>>>> \begin{figure}[!tb] \begin{center} \includegraphics[width=\textwidth]{Fig_cell} \caption{ \protect\label{fig:cell} Arrangement of variables. $t$ indicates scalar points where temperature, salinity, density, pressure and horizontal divergence are defined. $(u,v,w)$ indicates vector points, and $f$ indicates vorticity points where both relative and planetary vorticities are defined. } \end{center} \begin{figure} \centering \includegraphics[width=0.33\textwidth]{DOM_cell} \caption[Arrangement of variables in the unit cell of space domain]{ Arrangement of variables in the unit cell of space domain. $t$ indicates scalar points where temperature, salinity, density, pressure and horizontal divergence are defined. $(u,v,w)$ indicates vector points, and $f$ indicates vorticity points where both relative and planetary vorticities are defined.} \label{fig:DOM_cell} \end{figure} %>>>>>>>>>>>>>>>>>>>>>>>>>>>> The numerical techniques used to solve the Primitive Equations in this model are based on the traditional, centred second-order finite difference approximation. The numerical techniques used to solve the Primitive Equations in this model are based on the traditional, centred second-order finite difference approximation. Special attention has been given to the homogeneity of the solution in the three spatial directions. The arrangement of variables is the same in all directions. It consists of cells centred on scalar points ($t$, $S$, $p$, $\rho$) with vector points $(u, v, w)$ defined in the centre of each face of the cells (\autoref{fig:cell}). This is the generalisation to three dimensions of the well-known C'' grid in Arakawa's classification \citep{mesinger.arakawa_bk76}. The relative and planetary vorticity, $\zeta$ and $f$, are defined in the centre of each vertical edge and the barotropic stream function $\psi$ is defined at horizontal points overlying the $\zeta$ and $f$-points. The ocean mesh (\ie\ the position of all the scalar and vector points) is defined by the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. The grid-points are located at integer or integer and a half value of $(i,j,k)$ as indicated on \autoref{tab:cell}. In all the following, subscripts $u$, $v$, $w$, $f$, $uw$, $vw$ or $fw$ indicate the position of the grid-point where the scale factors are defined. Each scale factor is defined as the local analytical value provided by \autoref{eq:scale_factors}. It consists of cells centred on scalar points ($t$, $S$, $p$, $\rho$) with vector points $(u, v, w)$ defined in the centre of each face of the cells (\autoref{fig:DOM_cell}). This is the generalisation to three dimensions of the well-known C'' grid in Arakawa's classification \citep{mesinger.arakawa_bk76}. The relative and planetary vorticity, $\zeta$ and $f$, are defined in the centre of each vertical edge and the barotropic stream function $\psi$ is defined at horizontal points overlying the $\zeta$ and $f$-points. The ocean mesh (\ie\ the position of all the scalar and vector points) is defined by the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. The grid-points are located at integer or integer and a half value of $(i,j,k)$ as indicated on \autoref{tab:DOM_cell}. In all the following, subscripts $u$, $v$, $w$, $f$, $uw$, $vw$ or $fw$ indicate the position of the grid-point where the scale factors are defined. Each scale factor is defined as the local analytical value provided by \autoref{eq:MB_scale_factors}. As a result, the mesh on which partial derivatives $\pd[]{\lambda}$, $\pd[]{\varphi}$ and $\pd[]{z}$ are evaluated is a uniform mesh with a grid size of unity. Discrete partial derivatives are formulated by the traditional, centred second order finite difference approximation while the scale factors are chosen equal to their local analytical value. Discrete partial derivatives are formulated by the traditional, centred second order finite difference approximation while the scale factors are chosen equal to their local analytical value. An important point here is that the partial derivative of the scale factors must be evaluated by centred finite difference approximation, not from their analytical expression. This preserves the symmetry of the discrete set of equations and therefore satisfies many of the continuous properties (see \autoref{apdx:C}). This preserves the symmetry of the discrete set of equations and therefore satisfies many of the continuous properties (see \autoref{apdx:INVARIANTS}). A similar, related remark can be made about the domain size: when needed, an area, volume, or the total ocean depth must be evaluated as the product or sum of the relevant scale factors (see \autoref{eq:DOM_bar} in the next section). %>>>>>>>>>>>>>>>>>>>>>>>>>>>> \begin{table}[!tb] \begin{center} \begin{tabular}{|p{46pt}|p{56pt}|p{56pt}|p{56pt}|} \hline t  & $i$ & $j$ & $k$ \\ \hline u  & $i + 1/2$ & $j$ & $k$ \\ \hline v  & $i$ & $j + 1/2$ & $k$ \\ \hline w  & $i$ & $j$ & $k + 1/2$ \\ \hline f  & $i + 1/2$ & $j + 1/2$ & $k$ \\ \hline uw & $i + 1/2$ & $j$ & $k + 1/2$ \\ \hline vw & $i$ & $j + 1/2$ & $k + 1/2$ \\ \hline fw & $i + 1/2$ & $j + 1/2$ & $k + 1/2$ \\ \hline \end{tabular} \caption{ \protect\label{tab:cell} Location of grid-points as a function of integer or integer and a half value of the column, line or level. This indexing is only used for the writing of the semi -discrete equations. In the code, the indexing uses integer values only and is positive downwards in the vertical with $k=1$ at the surface. (see \autoref{subsec:DOM_Num_Index}) } \end{center} when needed, an area, volume, or the total ocean depth must be evaluated as the product or sum of the relevant scale factors (see \autoref{eq:DOM_bar} in the next section). \begin{table} \centering \begin{tabular}{|l|l|l|l|} \hline t   & $i$ & $j$ & $k$ \\ \hline u   & $i + 1/2$ & $j$ & $k$ \\ \hline v   & $i$ & $j + 1/2$ & $k$ \\ \hline w   & $i$ & $j$ & $k + 1/2$ \\ \hline f   & $i + 1/2$ & $j + 1/2$ & $k$ \\ \hline uw  & $i + 1/2$ & $j$ & $k + 1/2$ \\ \hline vw  & $i$ & $j + 1/2$ & $k + 1/2$ \\ \hline fw  & $i + 1/2$ & $j + 1/2$ & $k + 1/2$ \\ \hline \end{tabular} \caption[Location of grid-points]{ Location of grid-points as a function of integer or integer and a half value of the column, line or level. This indexing is only used for the writing of the semi-discrete equations. In the code, the indexing uses integer values only and is positive downwards in the vertical with $k=1$ at the surface. (see \autoref{subsec:DOM_Num_Index})} \label{tab:DOM_cell} \end{table} %>>>>>>>>>>>>>>>>>>>>>>>>>>>> Note that the definition of the scale factors firstly, there is no ambiguity in the scale factors appearing in the discrete equations, since they are first introduced in the continuous equations; secondly, analytical transformations encourage good practice by the definition of smoothly varying grids (rather than allowing the user to set arbitrary jumps in thickness between adjacent layers) \citep{treguier.dukowicz.ea_JGR96}. An example of the effect of such a choice is shown in \autoref{fig:zgr_e3}. %>>>>>>>>>>>>>>>>>>>>>>>>>>>> \begin{figure}[!t] \begin{center} \includegraphics[width=\textwidth]{Fig_zgr_e3} \caption{ \protect\label{fig:zgr_e3} Comparison of (a) traditional definitions of grid-point position and grid-size in the vertical, and (b) analytically derived grid-point position and scale factors. For both grids here, the same $w$-point depth has been chosen but in (a) the $t$-points are set half way between $w$-points while in (b) they are defined from an analytical function: $z(k) = 5 \, (k - 1/2)^3 - 45 \, (k - 1/2)^2 + 140 \, (k - 1/2) - 150$. Note the resulting difference between the value of the grid-size $\Delta_k$ and those of the scale factor $e_k$. } \end{center} secondly, analytical transformations encourage good practice by the definition of smoothly varying grids (rather than allowing the user to set arbitrary jumps in thickness between adjacent layers) \citep{treguier.dukowicz.ea_JGR96}. An example of the effect of such a choice is shown in \autoref{fig:DOM_zgr_e3}. \begin{figure} \centering \includegraphics[width=0.5\textwidth]{DOM_zgr_e3} \caption[Comparison of grid-point position, vertical grid-size and scale factors]{ Comparison of (a) traditional definitions of grid-point position and grid-size in the vertical, and (b) analytically derived grid-point position and scale factors. For both grids here, the same $w$-point depth has been chosen but in (a) the $t$-points are set half way between $w$-points while in (b) they are defined from an analytical function: $z(k) = 5 \, (k - 1/2)^3 - 45 \, (k - 1/2)^2 + 140 \, (k - 1/2) - 150$. Note the resulting difference between the value of the grid-size $\Delta_k$ and those of the scale factor $e_k$.} \label{fig:DOM_zgr_e3} \end{figure} %>>>>>>>>>>>>>>>>>>>>>>>>>>>> % ------------------------------------------------------------------------------------------------------------- %        Vector Invariant Formulation % ------------------------------------------------------------------------------------------------------------- %% ================================================================================================= \subsection{Discrete operators} \label{subsec:DOM_operators} Given the values of a variable $q$ at adjacent points, the differencing and averaging operators at the midpoint between them are: Given the values of a variable $q$ at adjacent points, the differencing and averaging operators at the midpoint between them are: \begin{alignat*}{2} % \label{eq:di_mi} % \label{eq:DOM_di_mi} \delta_i [q]      &= &       &q (i + 1/2) - q (i - 1/2) \\ \overline q^{\, i} &= &\big\{ &q (i + 1/2) + q (i - 1/2) \big\} / 2 Similar operators are defined with respect to $i + 1/2$, $j$, $j + 1/2$, $k$, and $k + 1/2$. Following \autoref{eq:PE_grad} and \autoref{eq:PE_lap}, the gradient of a variable $q$ defined at a $t$-point has its three components defined at $u$-, $v$- and $w$-points while its Laplacian is defined at the $t$-point. Following \autoref{eq:MB_grad} and \autoref{eq:MB_lap}, the gradient of a variable $q$ defined at a $t$-point has its three components defined at $u$-, $v$- and $w$-points while its Laplacian is defined at the $t$-point. These operators have the following discrete forms in the curvilinear $s$-coordinates system: $\begin{gather*} % \label{eq:DOM_grad} \nabla q \equiv \frac{1}{e_{1u}} \delta_{i + 1/2} [q] \; \, \vect i + \frac{1}{e_{2v}} \delta_{j + 1/2} [q] \; \, \vect j + \frac{1}{e_{3w}} \delta_{k + 1/2} [q] \; \, \vect k$ \begin{multline*} + \frac{1}{e_{3w}} \delta_{k + 1/2} [q] \; \, \vect k \\ % \label{eq:DOM_lap} \Delta q \equiv   \frac{1}{e_{1t} \, e_{2t} \, e_{3t}} \; \lt[   \delta_i \lt( \frac{e_{2u} \, e_{3u}}{e_{1u}} \; \delta_{i + 1/2} [q] \rt) + \delta_j \lt( \frac{e_{1v} \, e_{3v}}{e_{2v}} \; \delta_{j + 1/2} [q] \rt) \; \rt] \\ + \delta_j \lt( \frac{e_{1v} \, e_{3v}}{e_{2v}} \; \delta_{j + 1/2} [q] \rt) \; \rt] + \frac{1}{e_{3t}} \delta_k \lt[ \frac{1              }{e_{3w}} \; \delta_{k + 1/2} [q] \rt] \end{multline*} Following \autoref{eq:PE_curl} and \autoref{eq:PE_div}, a vector $\vect A = (a_1,a_2,a_3)$ defined at vector points $(u,v,w)$ has its three curl components defined at $vw$-, $uw$, and $f$-points, and \end{gather*} Following \autoref{eq:MB_curl} and \autoref{eq:MB_div}, a vector $\vect A = (a_1,a_2,a_3)$ defined at vector points $(u,v,w)$ has its three curl components defined at $vw$-, $uw$, and $f$-points, and its divergence defined at $t$-points: \begin{multline} \begin{multline*} % \label{eq:DOM_curl} \nabla \times \vect A \equiv   \frac{1}{e_{2v} \, e_{3vw}} \Big[   \delta_{i + 1/2} (e_{2v} \, a_2) - \delta_{j + 1/2} (e_{1u} \, a_1) \Big] \vect k \end{multline} \begin{equation} \end{multline*} $% \label{eq:DOM_div} \nabla \cdot \vect A \equiv \frac{1}{e_{1t} \, e_{2t} \, e_{3t}} \Big[ \delta_i (e_{2u} \, e_{3u} \, a_1) + \delta_j (e_{1v} \, e_{3v} \, a_2) \Big] + \frac{1}{e_{3t}} \delta_k (a_3) \end{equation} The vertical average over the whole water column is denoted by an overbar and is for a masked field q (\ie\ a quantity that is equal to zero inside solid areas):$ The vertical average over the whole water column is denoted by an overbar and is for a masked field $q$ (\ie\ a quantity that is equal to zero inside solid areas): \label{eq:DOM_bar} where $H_q$  is the ocean depth, which is the masked sum of the vertical scale factors at $q$ points, $k^b$ and $k^o$ are the bottom and surface $k$-indices, and the symbol $\sum \limits_k$ refers to a summation over all grid points of the same type in the direction indicated by the subscript (here $k$). $k^b$ and $k^o$ are the bottom and surface $k$-indices, and the symbol $\sum \limits_k$ refers to a summation over all grid points of the same type in the direction indicated by the subscript (here $k$). In continuous form, the following properties are satisfied: \end{gather} It is straightforward to demonstrate that these properties are verified locally in discrete form as soon as the scalar $q$ is taken at $t$-points and the vector $\vect A$ has its components defined at It is straightforward to demonstrate that these properties are verified locally in discrete form as soon as the scalar $q$ is taken at $t$-points and the vector $\vect A$ has its components defined at vector points $(u,v,w)$. Let $a$ and $b$ be two fields defined on the mesh, with a value of zero inside continental areas. It can be shown that the differencing operators ($\delta_i$, $\delta_j$ and $\delta_k$) are skew-symmetric linear operators, and further that the averaging operators $\overline{\cdots}^{\, i}$, $\overline{\cdots}^{\, j}$ and $\overline{\cdots}^{\, k}$) are symmetric linear operators, \ie \begin{alignat}{4} It can be shown that the differencing operators ($\delta_i$, $\delta_j$ and $\delta_k$) are skew-symmetric linear operators, and further that the averaging operators ($\overline{\cdots}^{\, i}$, $\overline{\cdots}^{\, j}$ and $\overline{\cdots}^{\, k}$) are symmetric linear operators, \ie \begin{alignat}{5} \label{eq:DOM_di_adj} &\sum \limits_i a_i \; \delta_i [b]      &\equiv &- &&\sum \limits_i \delta      _{   i + 1/2} [a] &b_{i + 1/2} \\ \end{alignat} In other words, the adjoint of the differencing and averaging operators are $\delta_i^* = \delta_{i + 1/2}$ and In other words, the adjoint of the differencing and averaging operators are $\delta_i^* = \delta_{i + 1/2}$ and $(\overline{\cdots}^{\, i})^* = \overline{\cdots}^{\, i + 1/2}$, respectively. These two properties will be used extensively in the \autoref{apdx:C} to These two properties will be used extensively in the \autoref{apdx:INVARIANTS} to demonstrate integral conservative properties of the discrete formulation chosen. % ------------------------------------------------------------------------------------------------------------- %        Numerical Indexing % ------------------------------------------------------------------------------------------------------------- %% ================================================================================================= \subsection{Numerical indexing} \label{subsec:DOM_Num_Index} %>>>>>>>>>>>>>>>>>>>>>>>>>>>> \begin{figure}[!tb] \begin{center} \includegraphics[width=\textwidth]{Fig_index_hor} \caption{ \protect\label{fig:index_hor} Horizontal integer indexing used in the \fortran code. The dashed area indicates the cell in which variables contained in arrays have the same $i$- and $j$-indices } \end{center} \begin{figure} \centering \includegraphics[width=0.33\textwidth]{DOM_index_hor} \caption[Horizontal integer indexing]{ Horizontal integer indexing used in the \fortran\ code. The dashed area indicates the cell in which variables contained in arrays have the same $i$- and $j$-indices} \label{fig:DOM_index_hor} \end{figure} %>>>>>>>>>>>>>>>>>>>>>>>>>>>> The array representation used in the \fortran code requires an integer indexing. However, the analytical definition of the mesh (see \autoref{subsec:DOM_cell}) is associated with the use of integer values for $t$-points only while all the other points involve integer and a half values. The array representation used in the \fortran\ code requires an integer indexing. However, the analytical definition of the mesh (see \autoref{subsec:DOM_cell}) is associated with the use of integer values for $t$-points only while all the other points involve integer and a half values. Therefore, a specific integer indexing has been defined for points other than $t$-points (\ie\ velocity and vorticity grid-points). Furthermore, the direction of the vertical indexing has been reversed and the surface level set at $k = 1$. % ----------------------------------- %        Horizontal Indexing % ----------------------------------- Furthermore, the direction of the vertical indexing has been reversed and the surface level set at $k = 1$. %% ================================================================================================= \subsubsection{Horizontal indexing} \label{subsec:DOM_Num_Index_hor} The indexing in the horizontal plane has been chosen as shown in \autoref{fig:index_hor}. The indexing in the horizontal plane has been chosen as shown in \autoref{fig:DOM_index_hor}. For an increasing $i$ index ($j$ index), the $t$-point and the eastward $u$-point (northward $v$-point) have the same index (see the dashed area in \autoref{fig:index_hor}). (see the dashed area in \autoref{fig:DOM_index_hor}). A $t$-point and its nearest north-east $f$-point have the same $i$-and $j$-indices. % ----------------------------------- %        Vertical indexing % ----------------------------------- %% ================================================================================================= \subsubsection{Vertical indexing} \label{subsec:DOM_Num_Index_vertical} In the vertical, the chosen indexing requires special attention since the direction of the $k$-axis in the \fortran code is the reverse of that used in the semi -discrete equations and given in \autoref{subsec:DOM_cell}. The sea surface corresponds to the $w$-level $k = 1$, which is the same index as the $t$-level just below (\autoref{fig:index_vert}). In the vertical, the chosen indexing requires special attention since the direction of the $k$-axis in the \fortran\ code is the reverse of that used in the semi-discrete equations and given in \autoref{subsec:DOM_cell}. The sea surface corresponds to the $w$-level $k = 1$, which is the same index as the $t$-level just below (\autoref{fig:DOM_index_vert}). The last $w$-level ($k = jpk$) either corresponds to or is below the ocean floor while the last $t$-level is always outside the ocean domain (\autoref{fig:index_vert}). the last $t$-level is always outside the ocean domain (\autoref{fig:DOM_index_vert}). Note that a $w$-point and the directly underlaying $t$-point have a common $k$ index (\ie\ $t$-points and their nearest $w$-point neighbour in negative index direction), in contrast to the indexing on the horizontal plane where the $t$-point has the same index as the nearest velocity points in the positive direction of the respective horizontal axis index (compare the dashed area in \autoref{fig:index_hor} and \autoref{fig:index_vert}). in contrast to the indexing on the horizontal plane where the $t$-point has the same index as the nearest velocity points in the positive direction of the respective horizontal axis index (compare the dashed area in \autoref{fig:DOM_index_hor} and \autoref{fig:DOM_index_vert}). Since the scale factors are chosen to be strictly positive, a \textit{minus sign} is included in the \fortran implementations of a \textit{minus sign} is included in the \fortran\ implementations of \textit{all the vertical derivatives} of the discrete equations given in this manual in order to accommodate the opposing vertical index directions in implementation and documentation. %>>>>>>>>>>>>>>>>>>>>>>>>>>>> \begin{figure}[!pt] \begin{center} \includegraphics[width=\textwidth]{Fig_index_vert} \caption{ \protect\label{fig:index_vert} Vertical integer indexing used in the \fortran code. Note that the $k$-axis is oriented downward. The dashed area indicates the cell in which variables contained in arrays have a common $k$-index. } \end{center} \begin{figure} \centering \includegraphics[width=0.33\textwidth]{DOM_index_vert} \caption[Vertical integer indexing]{ Vertical integer indexing used in the \fortran\ code. Note that the $k$-axis is oriented downward. The dashed area indicates the cell in which variables contained in arrays have a common $k$-index.} \label{fig:DOM_index_vert} \end{figure} %>>>>>>>>>>>>>>>>>>>>>>>>>>>> % ------------------------------------------------------------------------------------------------------------- %        Domain configuration % ------------------------------------------------------------------------------------------------------------- %% ================================================================================================= \section{Spatial domain configuration} \label{subsec:DOM_config} \nlst{namcfg} Two typical methods are available to specify the spatial domain configuration; they can be selected using parameter \np{ln\_read\_cfg} parameter in namelist \nam{cfg}. If \np{ln\_read\_cfg} is set to \forcode{.true.}, the domain-specific parameters and fields are read from a netCDF input file, whose name (without its .nc suffix) can be specified as the value of the \np{cn\_domcfg} parameter in namelist \nam{cfg}. If \np{ln\_read\_cfg} is set to \forcode{.false.}, they can be selected using parameter \np{ln_read_cfg}{ln\_read\_cfg} parameter in namelist \nam{cfg}{cfg}. If \np{ln_read_cfg}{ln\_read\_cfg} is set to \forcode{.true.}, the domain-specific parameters and fields are read from a NetCDF input file, whose name (without its .nc suffix) can be specified as the value of the \np{cn_domcfg}{cn\_domcfg} parameter in namelist \nam{cfg}{cfg}. If \np{ln_read_cfg}{ln\_read\_cfg} is set to \forcode{.false.}, the domain-specific parameters and fields can be provided (\eg\ analytically computed) by subroutines \mdl{usrdef\_hgr} and \mdl{usrdef\_zgr}. These subroutines can be supplied in the \path{MY_SRC} directory of the configuration, and default versions that configure the spatial domain for the GYRE reference configuration are present in the \path{./src/OCE/USR} directory. and default versions that configure the spatial domain for the GYRE reference configuration are present in the \path{./src/OCE/USR} directory. In version 4.0 there are no longer any options for reading complex bathymetries and to run similar models with and without partial bottom boxes and/or sigma-coordinates, supporting such choices leads to overly complex code. Worse still is the difficulty of ensuring the model configurations intended to be identical are indeed so when the model domain itself can be altered by runtime selections. The code previously used to perform vertical discretisation has been incorporated into an external tool (\path{./tools/DOMAINcfg}) which is briefly described in \autoref{apdx:DOMAINcfg}. The next subsections summarise the parameter and fields related to the configuration of the whole model domain. These represent the minimum information that must be provided either via the \np{cn\_domcfg} file or set by code inserted into user-supplied versions of the \texttt{usrdef\_*} subroutines. Worse still is the difficulty of ensuring the model configurations intended to be identical are indeed so when the model domain itself can be altered by runtime selections. The code previously used to perform vertical discretisation has been incorporated into an external tool (\path{./tools/DOMAINcfg}) which is briefly described in \autoref{apdx:DOMCFG}. The next subsections summarise the parameter and fields related to the configuration of the whole model domain. These represent the minimum information that must be provided either via the \np{cn_domcfg}{cn\_domcfg} file or set by code inserted into user-supplied versions of the \texttt{usrdef\_*} subroutines. The requirements are presented in three sections: the domain size (\autoref{subsec:DOM_size}), the horizontal mesh (\autoref{subsec:DOM_hgr}), and the vertical grid (\autoref{subsec:DOM_zgr}). % ----------------------------------- %        Domain Size % ----------------------------------- %% ================================================================================================= \subsection{Domain size} \label{subsec:DOM_size} The total size of the computational domain is set by the parameters \jp{jpiglo}, \jp{jpjglo} and \jp{jpkglo} for the $i$, $j$ and $k$ directions, respectively. Note, that the variables \texttt{jpi} and \texttt{jpj} refer to the size of each processor subdomain when the code is run in parallel using domain decomposition (\key{mpp\_mpi} defined, see \autoref{sec:LBC_mpp}). The name of the configuration is set through parameter \np{cn\_cfg}, and the nominal resolution through parameter \np{nn\_cfg} The total size of the computational domain is set by the parameters \jp{jpiglo}, \jp{jpjglo} and \jp{jpkglo} for the $i$, $j$ and $k$ directions, respectively. Note, that the variables \texttt{jpi} and \texttt{jpj} refer to the size of each processor subdomain when the code is run in parallel using domain decomposition (\key{mpp\_mpi} defined, see \autoref{sec:LBC_mpp}). The name of the configuration is set through parameter \np{cn_cfg}{cn\_cfg}, and the nominal resolution through parameter \np{nn_cfg}{nn\_cfg} (unless in the input file both of variables \texttt{ORCA} and \texttt{ORCA\_index} are present, in which case \np{cn\_cfg} and \np{nn\_cfg} are set from these values accordingly). in which case \np{cn_cfg}{cn\_cfg} and \np{nn_cfg}{nn\_cfg} are set from these values accordingly). The global lateral boundary condition type is selected from 8 options using parameter \jp{jperio}. See \autoref{sec:LBC_jperio} for details on the available options and the corresponding values for \jp{jperio}. % ================================================================ % Domain: Horizontal Grid (mesh) % ================================================================ \subsection{Horizontal grid mesh (\protect\mdl{domhgr})} See \autoref{sec:LBC_jperio} for details on the available options and the corresponding values for \jp{jperio}. %% ================================================================================================= \subsection[Horizontal grid mesh (\textit{domhgr.F90}]{Horizontal grid mesh (\protect\mdl{domhgr})} \label{subsec:DOM_hgr} % ================================================================ % Domain: List of hgr-related fields needed % ================================================================ %% ================================================================================================= \subsubsection{Required fields} \label{sec:DOM_hgr_fields} The explicit specification of a range of mesh-related fields are required for the definition of a configuration. The explicit specification of a range of mesh-related fields are required for the definition of a configuration. These include: \begin{clines} int    jpiglo, jpjglo, jpkglo            /* global domain sizes                                          */ int    jperio                            /* lateral global domain b.c.                                   */ double glamt, glamu, glamv, glamf        /* geographic longitude (t,u,v and f points respectively)      */ double gphit, gphiu, gphiv, gphif        /* geographic latitude                                          */ double e1t, e1u, e1v, e1f                /* horizontal scale factors                                     */ double e2t, e2u, e2v, e2f                /* horizontal scale factors                                     */ int    jpiglo, jpjglo, jpkglo     /* global domain sizes                                    */ int    jperio                     /* lateral global domain b.c.                             */ double glamt, glamu, glamv, glamf /* geographic longitude (t,u,v and f points respectively) */ double gphit, gphiu, gphiv, gphif /* geographic latitude                                    */ double e1t, e1u, e1v, e1f         /* horizontal scale factors                               */ double e2t, e2u, e2v, e2f         /* horizontal scale factors                               */ \end{clines} The values of the geographic longitude and latitude arrays at indices $i,j$ correspond to the analytical expressions of the longitude $\lambda$ and latitude $\varphi$ as a function of $(i,j)$, evaluated at the values as specified in \autoref{tab:cell} for the respective grid-point position. evaluated at the values as specified in \autoref{tab:DOM_cell} for the respective grid-point position. The calculation of the values of the horizontal scale factor arrays in general additionally involves partial derivatives of $\lambda$ and $\varphi$ with respect to $i$ and $j$, evaluated for the same arguments as $\lambda$ and $\varphi$. %% ================================================================================================= \subsubsection{Optional fields} \begin{clines} /* Optional:                                                    */ int    ORCA, ORCA_index                  /* configuration name, configuration resolution                 */ double e1e2u, e1e2v                      /* U and V surfaces (if grid size reduction in some straits)    */ double ff_f, ff_t                        /* Coriolis parameter (if not on the sphere)                    */ /* Optional:                                                 */ int    ORCA, ORCA_index /* configuration name, configuration resolution              */ double e1e2u, e1e2v     /* U and V surfaces (if grid size reduction in some straits) */ double ff_f, ff_t       /* Coriolis parameter (if not on the sphere)                 */ \end{clines} This is particularly useful for locations such as Gibraltar or Indonesian Throughflow pinch-points (see \autoref{sec:MISC_strait} for illustrated examples). The key is to reduce the faces of $T$-cell (\ie\ change the value of the horizontal scale factors at $u$- or $v$-point) but The key is to reduce the faces of $T$-cell (\ie\ change the value of the horizontal scale factors at $u$- or $v$-point) but not the volume of the cells. Doing otherwise can lead to numerical instability issues. In normal operation the surface areas are computed from $e1u * e2u$ and $e1v * e2v$ but in cases where a gridsize reduction is required, the unaltered surface areas at $u$ and $v$ grid points (\texttt{e1e2u} and \texttt{e1e2v}, respectively) must be read or pre-computed in \mdl{usrdef\_hgr}. If these arrays are present in the \np{cn\_domcfg} file they are read and the internal computation is suppressed. Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{e1e2u} and \texttt{e1e2v} should set the surface-area computation flag: the unaltered surface areas at $u$ and $v$ grid points (\texttt{e1e2u} and \texttt{e1e2v}, respectively) must be read or pre-computed in \mdl{usrdef\_hgr}. If these arrays are present in the \np{cn_domcfg}{cn\_domcfg} file they are read and the internal computation is suppressed. Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{e1e2u} and \texttt{e1e2v} should set the surface-area computation flag: \texttt{ie1e2u\_v} to a non-zero value to suppress their re-computation. \smallskip Similar logic applies to the other optional fields: \texttt{ff\_f} and \texttt{ff\_t} which can be used to provide the Coriolis parameter at F- and T-points respectively if the mesh is not on a sphere. If present these fields will be read and used and the normal calculation ($2 * \Omega * \sin(\varphi)$) suppressed. Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{ff\_f} and \texttt{ff\_t} should set the Coriolis computation flag: \texttt{ff\_f} and \texttt{ff\_t} which can be used to provide the Coriolis parameter at F- and T-points respectively if the mesh is not on a sphere. If present these fields will be read and used and the normal calculation ($2 * \Omega * \sin(\varphi)$) suppressed. Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{ff\_f} and \texttt{ff\_t} should set the Coriolis computation flag: \texttt{iff} to a non-zero value to suppress their re-computation. Note that longitudes, latitudes, and scale factors at $w$ points are exactly equal to those of $t$ points, thus no specific arrays are defined at $w$ points. % ================================================================ % Domain: Vertical Grid (domzgr) % ================================================================ \subsection[Vertical grid (\textit{domzgr.F90})] {Vertical grid (\protect\mdl{domzgr})} Note that longitudes, latitudes, and scale factors at $w$ points are exactly equal to those of $t$ points, thus no specific arrays are defined at $w$ points. %% ================================================================================================= \subsection[Vertical grid (\textit{domzgr.F90})]{Vertical grid (\protect\mdl{domzgr})} \label{subsec:DOM_zgr} %-----------------------------------------namdom------------------------------------------- \nlst{namdom} %------------------------------------------------------------------------------------------------------------- \begin{listing} \nlst{namdom} \caption{\forcode{&namdom}} \label{lst:namdom} \end{listing} In the vertical, the model mesh is determined by four things: \begin{enumerate} \item the bathymetry given in meters; \item the number of levels of the model (\jp{jpk}); \item the analytical transformation $z(i,j,k)$ and the vertical scale factors (derivatives of the transformation); and \item the masking system, \ie\ the number of wet model levels at each $(i,j)$ location of the horizontal grid. \item the bathymetry given in meters; \item the number of levels of the model (\jp{jpk}); \item the analytical transformation $z(i,j,k)$ and the vertical scale factors (derivatives of the transformation); and \item the masking system, \ie\ the number of wet model levels at each $(i,j)$ location of the horizontal grid. \end{enumerate} %>>>>>>>>>>>>>>>>>>>>>>>>>>>> \begin{figure}[!tb] \begin{center} \includegraphics[width=\textwidth]{Fig_z_zps_s_sps} \caption{ \protect\label{fig:z_zps_s_sps} The ocean bottom as seen by the model: (a) $z$-coordinate with full step, (b) $z$-coordinate with partial step, (c) $s$-coordinate: terrain following representation, (d) hybrid $s-z$ coordinate, (e) hybrid $s-z$ coordinate with partial step, and (f) same as (e) but in the non-linear free surface (\protect\np{ln\_linssh}\forcode{ = .false.}). Note that the non-linear free surface can be used with any of the 5 coordinates (a) to (e). } \end{center} \begin{figure} \centering \includegraphics[width=0.5\textwidth]{DOM_z_zps_s_sps} \caption[Ocean bottom regarding coordinate systems ($z$, $s$ and hybrid $s-z$)]{ The ocean bottom as seen by the model: \begin{enumerate*}[label=(\textit{\alph*})] \item $z$-coordinate with full step, \item $z$-coordinate with partial step, \item $s$-coordinate: terrain following representation, \item hybrid $s-z$ coordinate, \item hybrid $s-z$ coordinate with partial step, and \item same as (e) but in the non-linear free surface (\protect\np[=.false.]{ln_linssh}{ln\_linssh}). \end{enumerate*} Note that the non-linear free surface can be used with any of the 5 coordinates (a) to (e).} \label{fig:DOM_z_zps_s_sps} \end{figure} %>>>>>>>>>>>>>>>>>>>>>>>>>>>> The choice of a vertical coordinate is made when setting up the configuration; it is not intended to be an option which can be changed in the middle of an experiment. The one exception to this statement being the choice of linear or non-linear free surface. In v4.0 the linear free surface option is implemented as a special case of the non-linear free surface. In v4.0 the linear free surface option is implemented as a special case of the non-linear free surface. This is computationally wasteful since it uses the structures for time-varying 3D metrics for fields that (in the linear free surface case) are fixed. However, the linear free-surface is rarely used and implementing it this way means a single configuration file can support both options. By default a non-linear free surface is used (\np{ln\_linssh} set to \forcode{ = .false.} in \nam{dom}): the coordinate follow the time-variation of the free surface so that the transformation is time dependent: $z(i,j,k,t)$ (\eg\ \autoref{fig:z_zps_s_sps}f). When a linear free surface is assumed (\np{ln\_linssh} set to \forcode{ = .true.} in \nam{dom}), the vertical coordinates are fixed in time, but the seawater can move up and down across the $z_0$ surface However, the linear free-surface is rarely used and implementing it this way means a single configuration file can support both options. By default a non-linear free surface is used (\np{ln_linssh}{ln\_linssh} set to \forcode{=.false.} in \nam{dom}{dom}): the coordinate follow the time-variation of the free surface so that the transformation is time dependent: $z(i,j,k,t)$ (\eg\ \autoref{fig:DOM_z_zps_s_sps}f). When a linear free surface is assumed (\np{ln_linssh}{ln\_linssh} set to \forcode{=.true.} in \nam{dom}{dom}), the vertical coordinates are fixed in time, but the seawater can move up and down across the $z_0$ surface (in other words, the top of the ocean in not a rigid lid). Note that settings: \np{ln\_zco}, \np{ln\_zps}, \np{ln\_sco} and \np{ln\_isfcav} mentioned in the following sections appear to be namelist options but they are no longer truly namelist options for \NEMO. \np{ln_zco}{ln\_zco}, \np{ln_zps}{ln\_zps}, \np{ln_sco}{ln\_sco} and \np{ln_isfcav}{ln\_isfcav} mentioned in the following sections appear to be namelist options but they are no longer truly namelist options for \NEMO. Their value is written to and read from the domain configuration file and they should be treated as fixed parameters for a particular configuration. They are namelist options for the \texttt{DOMAINcfg} tool that can be used to build the configuration file and serve both to provide a record of the choices made whilst building the configuration and to trigger appropriate code blocks within \NEMO. These values should not be altered in the \np{cn\_domcfg} file. They are namelist options for the \texttt{DOMAINcfg} tool that can be used to build the configuration file and serve both to provide a record of the choices made whilst building the configuration and to trigger appropriate code blocks within \NEMO. These values should not be altered in the \np{cn_domcfg}{cn\_domcfg} file. \medskip The decision on these choices must be made when the \np{cn\_domcfg} file is constructed. Three main choices are offered (\autoref{fig:z_zps_s_sps}a-c): The decision on these choices must be made when the \np{cn_domcfg}{cn\_domcfg} file is constructed. Three main choices are offered (\autoref{fig:DOM_z_zps_s_sps}a-c): \begin{itemize} \item $z$-coordinate with full step bathymetry (\np{ln\_zco}\forcode{ = .true.}), \item $z$-coordinate with partial step ($zps$) bathymetry (\np{ln\_zps}\forcode{ = .true.}), \item Generalized, $s$-coordinate (\np{ln\_sco}\forcode{ = .true.}). \item $z$-coordinate with full step bathymetry (\np[=.true.]{ln_zco}{ln\_zco}), \item $z$-coordinate with partial step ($zps$) bathymetry (\np[=.true.]{ln_zps}{ln\_zps}), \item Generalized, $s$-coordinate (\np[=.true.]{ln_sco}{ln\_sco}). \end{itemize} Additionally, hybrid combinations of the three main coordinates are available: $s-z$ or $s-zps$ coordinate (\autoref{fig:z_zps_s_sps}d and \autoref{fig:z_zps_s_sps}e). $s-z$ or $s-zps$ coordinate (\autoref{fig:DOM_z_zps_s_sps}d and \autoref{fig:DOM_z_zps_s_sps}e). A further choice related to vertical coordinate concerns the presence (or not) of ocean cavities beneath ice shelves within the model domain. A setting of \np{ln\_isfcav} as \forcode{.true.} indicates that the domain contains ocean cavities, A setting of \np{ln_isfcav}{ln\_isfcav} as \forcode{.true.} indicates that the domain contains ocean cavities, otherwise the top, wet layer of the ocean will always be at the ocean surface. This option is currently only available for $z$- or $zps$-coordinates. In the latter case, partial steps are also applied at the ocean/ice shelf interface. Within the model, the arrays describing the grid point depths and vertical scale factors are three set of three dimensional arrays $(i,j,k)$ defined at \textit{before}, \textit{now} and \textit{after} time step. Within the model, the arrays describing the grid point depths and vertical scale factors are three set of three dimensional arrays $(i,j,k)$ defined at \textit{before}, \textit{now} and \textit{after} time step. The time at which they are defined is indicated by a suffix: $\_b$, $\_n$, or $\_a$, respectively. They are updated at each model time step. The initial fixed reference coordinate system is held in variable names with a $\_0$ suffix. When the linear free surface option is used (\np{ln\_linssh}\forcode{ = .true.}), When the linear free surface option is used (\np[=.true.]{ln_linssh}{ln\_linssh}), \textit{before}, \textit{now} and \textit{after} arrays are initially set to their reference counterpart and remain fixed. %% ================================================================================================= \subsubsection{Required fields} \label{sec:DOM_zgr_fields} \end{clines} This set of vertical metrics is sufficient to describe the initial depth and thickness of every gridcell in the model regardless of the choice of vertical coordinate. This set of vertical metrics is sufficient to describe the initial depth and thickness of every gridcell in the model regardless of the choice of vertical coordinate. With constant z-levels, e3 metrics will be uniform across each horizontal level. In the partial step case each e3 at the \jp{bottom\_level} may vary from its horizontal neighbours. And, in s-coordinates, variations can occur throughout the water column. With the non-linear free-surface, all the coordinates behave more like the s-coordinate in that variations occur throughout the water column with displacements related to the sea surface height. With the non-linear free-surface, all the coordinates behave more like the s-coordinate in that variations occur throughout the water column with displacements related to the sea surface height. These variations are typically much smaller than those arising from bottom fitted coordinates. The values for vertical metrics supplied in the domain configuration file can be considered as those arising from a flat sea surface with zero elevation. The \jp{bottom\_level} and \jp{top\_level} 2D arrays define the \jp{bottom\_level} and top wet levels in each grid column. The \jp{bottom\_level} and \jp{top\_level} 2D arrays define the \jp{bottom\_level} and top wet levels in each grid column. Without ice cavities, \jp{top\_level} is essentially a land mask (0 on land; 1 everywhere else). With ice cavities, \jp{top\_level} determines the first wet point below the overlying ice shelf. % ------------------------------------------------------------------------------------------------------------- %        level bathymetry and mask % ------------------------------------------------------------------------------------------------------------- %% ================================================================================================= \subsubsection{Level bathymetry and mask} \label{subsec:DOM_msk} From \jp{top\_level} and \jp{bottom\_level} fields, the mask fields are defined as follows: \begin{alignat*}{2} tmask(i,j,k) &= &  & \begin{cases} 0 &\text{if $k < top\_level(i,j)$} \\ 1 &\text{if $bottom\_level(i,j) \leq k \leq top\_level(i,j)$} \\ 0 &\text{if $k > bottom\_level(i,j)$} \end{cases} \\ umask(i,j,k) &= &  &tmask(i,j,k) * tmask(i + 1,j,    k) \\ vmask(i,j,k) &= &  &tmask(i,j,k) * tmask(i    ,j + 1,k) \\ fmask(i,j,k) &= &  &tmask(i,j,k) * tmask(i + 1,j,    k) \\ &  &* &tmask(i,j,k) * tmask(i + 1,j,    k) \\ wmask(i,j,k) &= &  &tmask(i,j,k) * tmask(i    ,j,k - 1) \\ \text{with~} wmask(i,j,1) &= & &tmask(i,j,1) \end{alignat*} \begin{align*} tmask(i,j,k) &= \begin{cases} 0 &\text{if $k < top\_level(i,j)$} \\ 1 &\text{if $bottom\_level(i,j) \leq k \leq top\_level(i,j)$} \\ 0 &\text{if $k > bottom\_level(i,j)$} \end{cases} \\ umask(i,j,k) &= tmask(i,j,k) * tmask(i + 1,j,    k) \\ vmask(i,j,k) &= tmask(i,j,k) * tmask(i    ,j + 1,k) \\ fmask(i,j,k) &= tmask(i,j,k) * tmask(i + 1,j,    k) * tmask(i,j,k) * tmask(i + 1,j,    k) \\ wmask(i,j,k) &= tmask(i,j,k) * tmask(i    ,j,k - 1) \\ \text{with~} wmask(i,j,1) &= tmask(i,j,1) \end{align*} Note that, without ice shelves cavities, masks at $t-$ and $w-$points are identical with the numerical indexing used (\autoref{subsec:DOM_Num_Index}). Nevertheless, $wmask$ are required with ocean cavities to deal with the top boundary (ice shelf/ocean interface) masks at $t-$ and $w-$points are identical with the numerical indexing used (\autoref{subsec:DOM_Num_Index}). Nevertheless, $wmask$ are required with ocean cavities to deal with the top boundary (ice shelf/ocean interface) exactly in the same way as for the bottom boundary. %% (see \autoref{fig:LBC_jperio}). %------------------------------------------------------------------------------------------------- %        Closed seas %------------------------------------------------------------------------------------------------- \subsection{Closed seas} \label{subsec:DOM_closea} When a global ocean is coupled to an atmospheric model it is better to represent all large water bodies (\eg\ Great Lakes, Caspian sea \dots) even if the model resolution does not allow their communication with the rest of the ocean. %% ================================================================================================= \subsection{Closed seas} \label{subsec:DOM_closea} When a global ocean is coupled to an atmospheric model it is better to represent all large water bodies (\eg\ Great Lakes, Caspian sea, \dots) even if the model resolution does not allow their communication with the rest of the ocean. This is unnecessary when the ocean is forced by fixed atmospheric conditions, so these seas can be removed from the ocean domain. The user has the option to set the bathymetry in closed seas to zero (see \autoref{sec:MISC_closea}) and to optionally decide on the fate of any freshwater imbalance over the area. The options are explained in \autoref{sec:MISC_closea} but it should be noted here that a successful use of these options requires appropriate mask fields to be present in the domain configuration file. The user has the option to set the bathymetry in closed seas to zero (see \autoref{sec:MISC_closea}) and to optionally decide on the fate of any freshwater imbalance over the area. The options are explained in \autoref{sec:MISC_closea} but it should be noted here that a successful use of these options requires appropriate mask fields to be present in the domain configuration file. Among the possibilities are: \begin{clines} int    closea_mask          /* non-zero values in closed sea areas for optional masking                  */ int    closea_mask_rnf      /* non-zero values in closed sea areas with runoff locations (precip only)  */ int    closea_mask_emp      /* non-zero values in closed sea areas with runoff locations (total emp)     */ int closea_mask     /* non-zero values in closed sea areas for optional masking                */ int closea_mask_rnf /* non-zero values in closed sea areas with runoff locations (precip only) */ int closea_mask_emp /* non-zero values in closed sea areas with runoff locations (total emp)   */ \end{clines} % ------------------------------------------------------------------------------------------------------------- %        Grid files % ------------------------------------------------------------------------------------------------------------- %% ================================================================================================= \subsection{Output grid files} \label{subsec:DOM_meshmask} \nlst{namcfg} Most of the arrays relating to a particular ocean model configuration discussed in this chapter (grid-point position, scale factors) can be saved in a file if namelist parameter \np{ln\_write\_cfg} (namelist \nam{cfg}) is set to \forcode{.true.}; the output filename is set through parameter \np{cn\_domcfg\_out}. (grid-point position, scale factors) can be saved in a file if namelist parameter \np{ln_write_cfg}{ln\_write\_cfg} (namelist \nam{cfg}{cfg}) is set to \forcode{.true.}; the output filename is set through parameter \np{cn_domcfg_out}{cn\_domcfg\_out}. This is only really useful if the fields are computed in subroutines \mdl{usrdef\_hgr} or \mdl{usrdef\_zgr} and checking or confirmation is required. \nlst{namdom} Alternatively, all the arrays relating to a particular ocean model configuration (grid-point position, scale factors, depths and masks) can be saved in a file called \texttt{mesh\_mask} if namelist parameter \np{ln\_meshmask} (namelist \nam{dom}) is set to \forcode{.true.}. (grid-point position, scale factors, depths and masks) can be saved in a file called \texttt{mesh\_mask} if namelist parameter \np{ln_meshmask}{ln\_meshmask} (namelist \nam{dom}{dom}) is set to \forcode{.true.}. This file contains additional fields that can be useful for post-processing applications. % ================================================================ % Domain: Initial State (dtatsd & istate) % ================================================================ \section[Initial state (\textit{istate.F90} and \textit{dtatsd.F90})] {Initial state (\protect\mdl{istate} and \protect\mdl{dtatsd})} \label{sec:DTA_tsd} %-----------------------------------------namtsd------------------------------------------- \nlst{namtsd} %------------------------------------------------------------------------------------------ Basic initial state options are defined in \nam{tsd}. %% ================================================================================================= \section[Initial state (\textit{istate.F90} and \textit{dtatsd.F90})]{Initial state (\protect\mdl{istate} and \protect\mdl{dtatsd})} \label{sec:DOM_DTA_tsd} \begin{listing} \nlst{namtsd} \caption{\forcode{&namtsd}} \label{lst:namtsd} \end{listing} Basic initial state options are defined in \nam{tsd}{tsd}. By default, the ocean starts from rest (the velocity field is set to zero) and the initialization of temperature and salinity fields is controlled through the \np{ln\_tsd\_init} namelist parameter. the initialization of temperature and salinity fields is controlled through the \np{ln_tsd_init}{ln\_tsd\_init} namelist parameter. \begin{description} \item[\np{ln\_tsd\_init}\forcode{= .true.}] Use T and S input files that can be given on the model grid itself or on their native input data grids. In the latter case, the data will be interpolated on-the-fly both in the horizontal and the vertical to the model grid \item [{\np[=.true.]{ln_tsd_init}{ln\_tsd\_init}}] Use T and S input files that can be given on the model grid itself or on their native input data grids. In the latter case, the data will be interpolated on-the-fly both in the horizontal and the vertical to the model grid (see \autoref{subsec:SBC_iof}). The information relating to the input files are specified in the \np{sn\_tem} and \np{sn\_sal} structures. The information relating to the input files are specified in the \np{sn_tem}{sn\_tem} and \np{sn_sal}{sn\_sal} structures. The computation is done in the \mdl{dtatsd} module. \item[\np{ln\_tsd\_init}\forcode{= .false.}] Initial values for T and S are set via a user supplied \rou{usr\_def\_istate} routine contained in \mdl{userdef\_istate}. \item [{\np[=.false.]{ln_tsd_init}{ln\_tsd\_init}}] Initial values for T and S are set via a user supplied \rou{usr\_def\_istate} routine contained in \mdl{userdef\_istate}. The default version sets horizontally uniform T and profiles as used in the GYRE configuration (see \autoref{sec:CFG_gyre}). (see \autoref{sec:CFGS_gyre}). \end{description} \biblio \pindex \onlyinsubfile{\input{../../global/epilogue}} \end{document}