New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
Changeset 13463 for NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/latex/NEMO/subfiles/chap_misc.tex – NEMO

Ignore:
Timestamp:
2020-09-14T17:40:34+02:00 (4 years ago)
Author:
andmirek
Message:

Ticket #2195:update to trunk 13461

Location:
NEMO/branches/2019/dev_r11351_fldread_with_XIOS
Files:
6 edited

Legend:

Unmodified
Added
Removed

  • NEMO/branches/2019/dev_r11351_fldread_with_XIOS

    • Property svn:externals

      •  

        old new  
        33^/utils/build/mk@HEAD         mk 
        44^/utils/tools@HEAD            tools 
        5 ^/vendors/AGRIF/dev@HEAD      ext/AGRIF 
         5^/vendors/AGRIF/dev_r12970_AGRIF_CMEMS      ext/AGRIF 
        66^/vendors/FCM@HEAD            ext/FCM 
        77^/vendors/IOIPSL@HEAD         ext/IOIPSL 
         8 
         9# SETTE 
         10^/utils/CI/sette@13382        sette 

  • NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc

    • Property svn:externals set to
      ^/utils/badges badges
      ^/utils/logos logos

  • NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/latex

    • Property svn:ignore deleted

  • NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/latex/NEMO

    • Property svn:externals set to
      ^/utils/figures/NEMO figures

  • NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/latex/NEMO/subfiles

    • Property svn:ignore

      •  

        old new  
        1 *.aux 
        2 *.bbl 
        3 *.blg 
        4 *.dvi 
        5 *.fdb* 
        6 *.fls 
        7 *.idx 
         1*.ind 
        82*.ilg 
        9 *.ind 
        10 *.log 
        11 *.maf 
        12 *.mtc* 
        13 *.out 
        14 *.pdf 
        15 *.toc 
        16 _minted-* 

  • NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/latex/NEMO/subfiles/chap_misc.tex

    r11339 r13463  
    22 
    33\begin{document} 
    4 % ================================================================ 
    5 % Chapter --- Miscellaneous Topics 
    6 % ================================================================ 
     4 
    75\chapter{Miscellaneous Topics} 
    86\label{chap:MISC} 
    97 
    10 \minitoc 
    11  
    12 \newpage 
    13  
    14 % ================================================================ 
    15 % Representation of Unresolved Straits 
    16 % ================================================================ 
     8\thispagestyle{plain} 
     9 
     10\chaptertoc 
     11 
     12\paragraph{Changes record} ~\\ 
     13 
     14{\footnotesize 
     15  \begin{tabularx}{\textwidth}{l||X|X} 
     16    Release & Author(s) & Modifications \\ 
     17    \hline 
     18    {\em   4.0} & {\em ...} & {\em ...} \\ 
     19    {\em   3.6} & {\em ...} & {\em ...} \\ 
     20    {\em   3.4} & {\em ...} & {\em ...} \\ 
     21    {\em <=3.4} & {\em ...} & {\em ...} 
     22  \end{tabularx} 
     23} 
     24 
     25\clearpage 
     26 
     27%% ================================================================================================= 
    1728\section{Representation of unresolved straits} 
    1829\label{sec:MISC_strait} 
    … …  
    2738balance the net evaporation occurring over the Mediterranean region. 
    2839This problem occurs even in eddy permitting simulations. 
    29 For example, in ORCA 1/4\deg several straits of the Indonesian archipelago (Ombai, Lombok...) 
     40For example, in ORCA 1/4\deg\ several straits of the Indonesian archipelago (Ombai, Lombok...) 
    3041are much narrow than even a single ocean grid-point. 
    3142 
    32 We describe briefly here the two methods that can be used in \NEMO to handle such 
     43We describe briefly here the two methods that can be used in \NEMO\ to handle such 
    3344improperly resolved straits. The methods consist of opening the strait while ensuring 
    3445that the mass exchanges through the strait are not too large by either artificially 
    … …  
    3647lateral friction. 
    3748 
    38 % ------------------------------------------------------------------------------------------------------------- 
    39 %       Hand made geometry changes 
    40 % ------------------------------------------------------------------------------------------------------------- 
     49%% ================================================================================================= 
    4150\subsection{Hand made geometry changes} 
    4251\label{subsec:MISC_strait_hand} 
    … …  
    4655(\autoref{fig:MISC_strait_hand}).  This technique is sometime called "partially open face" 
    4756or "partially closed cells".  The key issue here is only to reduce the faces of $T$-cell 
    48 (\ie change the value of the horizontal scale factors at $u$- or $v$-point) but not the 
     57(\ie\ change the value of the horizontal scale factors at $u$- or $v$-point) but not the 
    4958volume of the $T$-cell.  Indeed, reducing the volume of strait $T$-cell can easily produce 
    5059a numerical instability at that grid point which would require a reduction of the model 
    … …  
    5362\begin{itemize} 
    5463 
    55 \item Add \texttt{e1e2u} and \texttt{e1e2v} arrays to the \np{cn\_domcfg} file. These 2D 
     64\item Add \texttt{e1e2u} and \texttt{e1e2v} arrays to the \np{cn_domcfg}{cn\_domcfg} file. These 2D 
    5665arrays should contain the products of the unaltered values of: $\texttt{e1u}*\texttt{e2u}$ 
    5766and $\texttt{e1u}*\texttt{e2v}$ respectively. That is the original surface areas of $u$- 
    5867and $v$- cells respectively.  These areas are usually defined by the corresponding product 
    59 within the \NEMO code but the presence of \texttt{e1e2u} and \texttt{e1e2v} in the 
    60 \np{cn\_domcfg} file will suppress this calculation and use the supplied fields instead. 
     68within the \NEMO\ code but the presence of \texttt{e1e2u} and \texttt{e1e2v} in the 
     69\np{cn_domcfg}{cn\_domcfg} file will suppress this calculation and use the supplied fields instead. 
    6170If the model domain is provided by user-supplied code in \mdl{usrdef\_hgr}, then this 
    6271routine should also return \texttt{e1e2u} and \texttt{e1e2v} and set the integer return 
    … …  
    6473will suppress the calculation of the areas. 
    6574 
    66 \item Change values of \texttt{e2u} or \texttt{e1v} (either in the \np{cn\_domcfg} file or 
     75\item Change values of \texttt{e2u} or \texttt{e1v} (either in the \np{cn_domcfg}{cn\_domcfg} file or 
    6776via code in  \mdl{usrdef\_hgr}), whereever a Strait reduction is required. The choice of 
    6877whether to alter \texttt{e2u} or \texttt{e1v} depends. respectively,  on whether the 
    69 Strait in question is North-South orientated (\eg Gibraltar) or East-West orientated (\eg 
     78Strait in question is North-South orientated (\eg\ Gibraltar) or East-West orientated (\eg 
    7079Lombok). 
    7180 
    7281\end{itemize} 
    73  
    7482 
    7583The second method is to increase the viscous boundary layer thickness by a local increase 
    … …  
    8492\texttt{fmask} for any other configuration. 
    8593 
    86 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    8794\begin{figure}[!tbp] 
    88   \begin{center} 
    89     \includegraphics[width=\textwidth]{Fig_Gibraltar} 
    90     \includegraphics[width=\textwidth]{Fig_Gibraltar2} 
    91     \caption{ 
    92       \protect\label{fig:MISC_strait_hand} 
    93       Example of the Gibraltar strait defined in a $1^{\circ} \times 1^{\circ}$ mesh. 
    94       \textit{Top}: using partially open cells. 
    95       The meridional scale factor at $v$-point is reduced on both sides of the strait to account for 
    96       the real width of the strait (about 20 km). 
    97       Note that the scale factors of the strait $T$-point remains unchanged. 
    98       \textit{Bottom}: using viscous boundary layers. 
    99       The four fmask parameters along the strait coastlines are set to a value larger than 4, 
    100       \ie "strong" no-slip case (see \autoref{fig:LBC_shlat}) creating a large viscous boundary layer that 
    101       allows a reduced transport through the strait. 
    102     } 
    103   \end{center} 
     95  \centering 
     96  \includegraphics[width=0.66\textwidth]{MISC_Gibraltar} 
     97  \includegraphics[width=0.66\textwidth]{MISC_Gibraltar2} 
     98  \caption[Two methods to defined the Gibraltar strait]{ 
     99    Example of the Gibraltar strait defined in a 1\deg\ $\times$ 1\deg\ mesh. 
     100    \textit{Top}: using partially open cells. 
     101    The meridional scale factor at $v$-point is reduced on both sides of the strait to 
     102    account for the real width of the strait (about 20 km). 
     103    Note that the scale factors of the strait $T$-point remains unchanged. 
     104    \textit{Bottom}: using viscous boundary layers. 
     105    The four fmask parameters along the strait coastlines are set to a value larger than 4, 
     106    \ie\ "strong" no-slip case (see \autoref{fig:LBC_shlat}) creating a large viscous boundary layer 
     107    that allows a reduced transport through the strait.} 
     108  \label{fig:MISC_strait_hand} 
    104109\end{figure} 
    105 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    106  
    107 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     110 
    108111\begin{figure}[!tbp] 
    109   \begin{center} 
    110     \includegraphics[width=\textwidth]{Fig_closea_mask_example} 
    111     \caption{ 
    112       \protect\label{fig:closea_mask_example} 
    113       Example of mask fields for the closea module. \textit{Left}: a 
    114       closea\_mask field; \textit{Right}: a closea\_mask\_rnf 
    115       field. In this example, if ln\_closea is set to .true., the mean 
    116       freshwater flux over each of the American Great Lakes will be 
    117       set to zero, and the total residual for all the lakes, if 
    118       negative, will be put into the St Laurence Seaway in the area 
    119       shown.  
    120     } 
    121   \end{center} 
     112  \centering 
     113  \includegraphics[width=0.66\textwidth]{MISC_closea_mask_example} 
     114  \caption[Mask fields for the \protect\mdl{closea} module]{ 
     115    Example of mask fields for the \protect\mdl{closea} module. 
     116    \textit{Left}: a closea\_mask field; 
     117    \textit{Right}: a closea\_mask\_rnf field. 
     118    In this example, if \protect\np{ln_closea}{ln\_closea} is set to \forcode{.true.}, 
     119    the mean freshwater flux over each of the American Great Lakes will be set to zero, 
     120    and the total residual for all the lakes, if negative, will be put into 
     121    the St Laurence Seaway in the area shown.} 
     122  \label{fig:MISC_closea_mask_example} 
    122123\end{figure} 
    123 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    124  
    125 % ================================================================ 
    126 % Closed seas 
    127 % ================================================================ 
    128 \section[Closed seas (\textit{closea.F90})] 
    129 {Closed seas (\protect\mdl{closea})} 
     124 
     125%% ================================================================================================= 
     126\section[Closed seas (\textit{closea.F90})]{Closed seas (\protect\mdl{closea})} 
    130127\label{sec:MISC_closea} 
    131128 
    … …  
    141138to zero and put the residual flux into the ocean. 
    142139 
    143 Prior to NEMO 4 the locations of inland seas and lakes was set via 
    144 hardcoded indices for various ORCA configurations. From NEMO 4 onwards 
     140Prior to \NEMO\ 4 the locations of inland seas and lakes was set via 
     141hardcoded indices for various ORCA configurations. From \NEMO\ 4 onwards 
    145142the inland seas and lakes are defined using mask fields in the 
    146143domain configuration file. The options are as follows. 
    147144 
    148145\begin{enumerate} 
    149 \item{{\bfseries No ``closea\_mask'' field is included in domain configuration 
     146\item {{\bfseries No ``closea\_mask'' field is included in domain configuration 
    150147  file.} In this case the closea module does nothing.} 
    151148 
    152 \item{{\bfseries A field called closea\_mask is included in the domain 
     149\item {{\bfseries A field called closea\_mask is included in the domain 
    153150configuration file and ln\_closea=.false. in namelist namcfg.} In this 
    154151case the inland seas defined by the closea\_mask field are filled in 
    … …  
    156153closea\_mask that is nonzero is set to be a land point.} 
    157154 
    158 \item{{\bfseries A field called closea\_mask is included in the domain 
     155\item {{\bfseries A field called closea\_mask is included in the domain 
    159156configuration file and ln\_closea=.true. in namelist namcfg.} Each 
    160157inland sea or group of inland seas is set to a positive integer value 
    161 in the closea\_mask field (see Figure \ref{fig:closea_mask_example} 
     158in the closea\_mask field (see \autoref{fig:MISC_closea_mask_example} 
    162159for an example). The net surface flux over each inland sea or group of 
    163160inland seas is set to zero each timestep and the residual flux is 
    … …  
    165162closea\_mask is zero).} 
    166163 
    167 \item{{\bfseries Fields called closea\_mask and closea\_mask\_rnf are 
     164\item {{\bfseries Fields called closea\_mask and closea\_mask\_rnf are 
    168165included in the domain configuration file and ln\_closea=.true. in 
    169166namelist namcfg.} This option works as for option 3, except that if 
    … …  
    174171by the closea\_mask\_rnf field. Each mapping is defined by a positive 
    175172integer value for the inland sea(s) and the corresponding runoff 
    176 points. An example is given in Figure 
    177 \ref{fig:closea_mask_example}. If no mapping is provided for a 
     173points. An example is given in 
     174\autoref{fig:MISC_closea_mask_example}. If no mapping is provided for a 
    178175particular inland sea then the residual is spread over the global 
    179176ocean.} 
    180177 
    181 \item{{\bfseries Fields called closea\_mask and closea\_mask\_emp are 
     178\item {{\bfseries Fields called closea\_mask and closea\_mask\_emp are 
    182179included in the domain configuration file and ln\_closea=.true. in 
    183180namelist namcfg.} This option works the same as option 4 except that 
    … …  
    189186 
    190187There is a python routine to create the closea\_mask fields and append 
    191 them to the domain configuration file in the utils/tools/DOMAINcfg directory.  
    192  
    193 % ================================================================ 
    194 % Sub-Domain Functionality  
    195 % ================================================================ 
     188them to the domain configuration file in the utils/tools/DOMAINcfg directory. 
     189 
     190%% ================================================================================================= 
    196191\section{Sub-domain functionality} 
    197192\label{sec:MISC_zoom} 
    198193 
     194%% ================================================================================================= 
    199195\subsection{Simple subsetting of input files via NetCDF attributes} 
    200196 
    … …  
    204200maintain different sets of input fields for use with or without active ice cavities.  This 
    205201subsetting operates for the j-direction only and works by optionally looking for and using 
    206 a global file attribute (named: \np{open\_ocean\_jstart}) to determine the starting j-row 
    207 for input.  The use of this option is best explained with an example:  
     202a global file attribute (named: \np{open_ocean_jstart}{open\_ocean\_jstart}) to determine the starting j-row 
     203for input.  The use of this option is best explained with an example: 
    208204\medskip 
    209205 
    … …  
    211207configuration using the extended grid domain configuration file: \ifile{eORCA1\_domcfg.nc} 
    212208This file define a horizontal domain of 362x332.  The first row with 
    213 open ocean wet points in the non-isf bathymetry for this set is row 42 (\fortran indexing) 
    214 then the formally correct setting for \np{open\_ocean\_jstart} is 41.  Using this value as 
     209open ocean wet points in the non-isf bathymetry for this set is row 42 (\fortran\ indexing) 
     210then the formally correct setting for \np{open_ocean_jstart}{open\_ocean\_jstart} is 41.  Using this value as 
    215211the first row to be read will result in a 362x292 domain which is the same size as the 
    216212original ORCA1 domain.  Thus the extended domain configuration file can be used with all 
    … …  
    219215 
    220216\begin{itemize} 
    221 \item  Add the new attribute to any input files requiring a j-row offset, i.e: 
    222 \begin{cmds}  
    223 ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_domcfg.nc  
     217\item Add the new attribute to any input files requiring a j-row offset, i.e: 
     218\begin{cmds} 
     219ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_domcfg.nc 
    224220\end{cmds} 
    225221 
    226 \item Add the logical switch \np{ln\_use\_jattr} to \ngn{namcfg} in the configuration 
    227 namelist (if it is not already there) and set \np{.true.} 
     222\item Add the logical switch \np{ln_use_jattr}{ln\_use\_jattr} to \nam{cfg}{cfg} in the configuration 
     223namelist (if it is not already there) and set \forcode{.true.} 
    228224\end{itemize} 
    229225 
    230226\noindent Note that with this option, the j-size of the global domain is (extended 
    231 j-size minus \np{open\_ocean\_jstart} + 1 ) and this must match the \texttt{jpjglo} value 
     227j-size minus \np{open_ocean_jstart}{open\_ocean\_jstart} + 1 ) and this must match the \texttt{jpjglo} value 
    232228for the configuration. This means an alternative version of \ifile{eORCA1\_domcfg.nc} must 
    233 be created for when \np{ln\_use\_jattr} is active. The \texttt{ncap2} tool provides a 
     229be created for when \np{ln_use_jattr}{ln\_use\_jattr} is active. The \texttt{ncap2} tool provides a 
    234230convenient way of achieving this: 
    235231 
    … …  
    238234\end{cmds} 
    239235 
    240 The domain configuration file is unique in this respect since it also contains the value 
    241 of \texttt{jpjglo} that is read and used by the model. Any other global, 2D and 3D, 
    242 netcdf, input field can be prepared for use in a reduced domain by adding the 
    243 \texttt{open\_ocean\_jstart} attribute to the file's  global attributes. In particular 
    244 this is true for any field that is read by \NEMO using the following optional argument to 
    245 the appropriate call to \np{iom\_get}. 
     236The domain configuration file is unique in this respect since it also contains the value of \jp{jpjglo} 
     237that is read and used by the model. 
     238Any other global, 2D and 3D, netcdf, input field can be prepared for use in a reduced domain by adding the 
     239\texttt{open\_ocean\_jstart} attribute to the file's global attributes. 
     240In particular this is true for any field that is read by \NEMO\ using the following optional argument to 
     241the appropriate call to \np{iom_get}{iom\_get}. 
     242 
    246243\begin{forlines} 
    247244lrowattr=ln_use_jattr 
    … …  
    256253conditions. Experimenting with this remains an exercise for the user. 
    257254 
    258 % ================================================================ 
    259 % Accuracy and Reproducibility 
    260 % ================================================================ 
    261 \section[Accuracy and reproducibility (\textit{lib\_fortran.F90})] 
    262 {Accuracy and reproducibility (\protect\mdl{lib\_fortran})} 
     255%% ================================================================================================= 
     256\section[Accuracy and reproducibility (\textit{lib\_fortran.F90})]{Accuracy and reproducibility (\protect\mdl{lib\_fortran})} 
    263257\label{sec:MISC_fortran} 
    264258 
    265 \subsection[Issues with intrinsinc SIGN function (\texttt{\textbf{key\_nosignedzero}})] 
    266 {Issues with intrinsinc SIGN function (\protect\key{nosignedzero})} 
     259%% ================================================================================================= 
     260\subsection[Issues with intrinsinc SIGN function (\texttt{\textbf{key\_nosignedzero}})]{Issues with intrinsinc SIGN function (\protect\key{nosignedzero})} 
    267261\label{subsec:MISC_sign} 
    268262 
    269 The SIGN(A, B) is the \fortran intrinsic function delivers the magnitude of A with the sign of B. 
     263The SIGN(A, B) is the \fortran\ intrinsic function delivers the magnitude of A with the sign of B. 
    270264For example, SIGN(-3.0,2.0) has the value 3.0. 
    271265The problematic case is when the second argument is zero, because, on platforms that support IEEE arithmetic, 
    … …  
    279273and the processor is capable of distinguishing between positive and negative zero, 
    280274and B is negative real zero. 
    281 Then SIGN delivers a negative result where, under \fninety rules, it used to return a positive result. 
     275Then SIGN delivers a negative result where, under \fninety\ rules, it used to return a positive result. 
    282276This change may be especially sensitive for the ice model, 
    283277so we overwrite the intrinsinc function with our own function simply performing :   \\ 
    … …  
    289283some computers/compilers. 
    290284 
    291  
     285%% ================================================================================================= 
    292286\subsection{MPP reproducibility} 
    293287\label{subsec:MISC_glosum} 
    294288 
    295289The numerical reproducibility of simulations on distributed memory parallel computers is a critical issue. 
    296 In particular, within NEMO global summation of distributed arrays is most susceptible to rounding errors, 
     290In particular, within \NEMO\ global summation of distributed arrays is most susceptible to rounding errors, 
    297291and their propagation and accumulation cause uncertainty in final simulation reproducibility on 
    298292different numbers of processors. 
    299293To avoid so, based on \citet{he.ding_JS01} review of different technics, 
    300294we use a so called self-compensated summation method. 
    301 The idea is to estimate the roundoff error, store it in a buffer, and then add it back in the next addition.  
     295The idea is to estimate the roundoff error, store it in a buffer, and then add it back in the next addition. 
    302296 
    303297Suppose we need to calculate $b = a_1 + a_2 + a_3$. 
    … …  
    317311The self-compensated summation method should be used in all summation in i- and/or j-direction. 
    318312See \mdl{closea} module for an example. 
    319 Note also that this implementation may be sensitive to the optimization level.  
    320  
     313Note also that this implementation may be sensitive to the optimization level. 
     314 
     315%% ================================================================================================= 
    321316\subsection{MPP scalability} 
    322317\label{subsec:MISC_mppsca} 
    … …  
    338333be set at all the locations actually required by each individual for the fold operation. 
    339334This alternative method should give identical results to the default \textsc{ALLGATHER} method and 
    340 is recommended for large values of \np{jpni}. 
    341 The new method is activated by setting \np{ln\_nnogather} to be true (\ngn{nammpp}). 
     335is recommended for large values of \np{jpni}{jpni}. 
     336The new method is activated by setting \np{ln_nnogather}{ln\_nnogather} to be true (\nam{mpp}{mpp}). 
    342337The reproducibility of results using the two methods should be confirmed for each new, 
    343338non-reference configuration. 
    344339 
    345 % ================================================================ 
    346 % Model optimisation, Control Print and Benchmark 
    347 % ================================================================ 
     340%% ================================================================================================= 
    348341\section{Model optimisation, control print and benchmark} 
    349342\label{sec:MISC_opt} 
    350 %--------------------------------------------namctl------------------------------------------------------- 
    351  
    352 \nlst{namctl}  
    353 %-------------------------------------------------------------------------------------------------------------- 
    354  
    355 Options are defined through the  \ngn{namctl} namelist variables. 
    356  
     343 
     344\begin{listing} 
     345  \nlst{namctl} 
     346  \caption{\forcode{&namctl}} 
     347  \label{lst:namctl} 
     348\end{listing} 
     349 
     350Options are defined through the  \nam{ctl}{ctl} namelist variables. 
     351 
     352%% ================================================================================================= 
    357353\subsection{Vector optimisation} 
    358354 
    … …  
    360356This is very a very efficient way to increase the length of vector calculations and thus 
    361357to speed up the model on vector computers. 
    362   
     358 
    363359% Add here also one word on NPROMA technique that has been found useless, since compiler have made significant progress during the last decade. 
    364   
     360 
    365361% Add also one word on NEC specific optimisation (Novercheck option for example) 
    366   
    367 \subsection{Control print} 
    368  
    369 The \np{ln\_ctl} switch was originally used as a debugging option in two modes: 
    370  
    371 \begin{enumerate} 
    372 \item{\np{ln\_ctl}: compute and print the trends averaged over the interior domain in all TRA, DYN, LDF and 
    373 ZDF modules. 
    374 This option is very helpful when diagnosing the origin of an undesired change in model results. } 
    375  
    376 \item{also \np{ln\_ctl} but using the nictl and njctl namelist parameters to check the source of differences between 
    377 mono and multi processor runs.} 
     362 
     363%% ================================================================================================= 
     364\subsection{Status and debugging information output} 
     365 
     366 
     367NEMO can produce a range of text information output either: in the main output 
     368file (ocean.output) written by the normal reporting processor (narea == 1) or various 
     369specialist output files (e.g. layout.dat, run.stat, tracer.stat etc.). Some, for example 
     370run.stat and tracer.stat, contain globally collected values for which a single file is 
     371sufficient. Others, however, contain information that could, potentially, be different 
     372for each processing region. For computational efficiency, the default volume of text 
     373information produced is reduced to just a few files from the narea=1 processor. 
     374 
     375When more information is required for monitoring or debugging purposes, the various 
     376forms of output can be selected via the \np{sn\_cfctl} structure. As well as simple 
     377on-off switches this structure also allows selection of a range of processors for 
     378individual reporting (where appropriate) and a time-increment option to restrict 
     379globally collected values to specified time-step increments. 
     380 
     381Most options within the structure are influenced by the top-level switches shown here 
     382with their default settings: 
     383 
     384\begin{verbatim} 
     385   sn_cfctl%l_allon  = .FALSE.    ! IF T activate all options. If F deactivate all unless l_config is T 
     386     sn_cfctl%l_config = .TRUE.     ! IF .true. then control which reports are written with the following 
     387\end{verbatim} 
     388 
     389The first switch is a convenience option which can be used to switch on and off all 
     390sub-options. However, if it is false then switching off all sub-options is only done 
     391if \texttt{sn_cfctl%l\_config} is also false. Specifically, the logic is: 
     392 
     393\begin{verbatim} 
     394  IF ( sn_cfctl%l_allon ) THEN 
     395    set all suboptions .TRUE. 
     396    and set procmin, procmax and procincr so that all regions are selected ([0,10000000,1], respectively) 
     397  ELSEIF ( sn_cfctl%l_config ) THEN 
     398    honour individual settings of the suboptions from the namelist 
     399  ELSE 
     400    set all suboptions .FALSE. 
     401  ENDIF 
     402\end{verbatim} 
     403 
     404Details of the suboptions follow but first an explanation of the stand-alone option: 
     405\texttt{sn_cfctl%l_glochk}.  This option modifies the action of the early warning checks 
     406carried out in \textt{stpctl.F90}. These checks detect probable numerical instabilites 
     407by searching for excessive sea surface heights or velocities and salinity values 
     408outside a sensible physical range. If breaches are detected then the default behaviour 
     409is to locate and report the local indices of the grid-point in breach. These indices 
     410are included in the error message that precedes the model shutdown. When true, 
     411\texttt{sn_cfctl%l_glochk} modifies this action by performing a global location of 
     412the various minimum and maximum values and the global indices are reported. This has 
     413some value in locating the most severe error in cases where the first detected error 
     414may not be the worst culprit. 
     415 
     416\subsubsection{Control print suboptions} 
     417 
     418The options that can be individually selected fall into three categories: 
     419 
     420\begin{enumerate} \item{Time step progress information} This category includes 
     421\texttt{run.stat} and \texttt{tracer.stat} files which record certain physical and 
     422passive tracer metrics (respectively). Typical contents of \texttt{run.stat} include 
     423global maximums of ssh, velocity; and global minimums and maximums of temperature 
     424and salinity.  A netCDF version of \texttt{run.stat} (\texttt{run.stat.nc}) is also 
     425produced with the same time-series data and this can easily be expanded to include 
     426extra monitoring information.  \texttt{tracer.stat} contains the volume-weighted 
     427average tracer value for each passive tracer. Collecting these metrics involves 
     428global communications and will impact on model efficiency so both these options are 
     429disabled by default by setting the respective options, \texttt{sn\_cfctl%runstat} and 
     430\texttt{sn\_cfctl%trcstat} to false. A compromise can be made by activating either or 
     431both of these options and setting the \texttt{sn\_cfctl%timincr} entry to an integer 
     432value greater than one. This increment determines the time-step frequency at which 
     433the global metrics are collected and reported.  This increment also applies to the 
     434time.step file which is otherwise updated every timestep. 
     435\item{One-time configuration information/progress logs} 
     436 
     437Some run-time configuration information and limited progress information is always 
     438produced by the first ocean process. This includes the \texttt{ocean.output} file 
     439which reports on all the namelist options read by the model and remains open to catch 
     440any warning or error messages generated during execution. A \texttt{layout.dat} 
     441file is also produced which details the MPI-decomposition used by the model. The 
     442suboptions: \texttt{sn\_cfctl%oceout} and \texttt{sn\_cfctl%layout} can be used 
     443to activate the creation of these files by all ocean processes.  For example, 
     444when \texttt{sn\_cfctl%oceout} is true all processors produce their own version of 
     445\texttt{ocean.output}.  All files, beyond the the normal reporting processor (narea == 1), are 
     446named with a \_XXXX extension to their name, where XXXX is a 4-digit area number (with 
     447leading zeros, if required). This is useful as a debugging aid since all processes can 
     448report their local conditions. Note though that these files are buffered on most UNIX 
     449systems so bug-hunting efforts using this facility should also utilise the \fortran: 
     450 
     451\begin{verbatim}  
     452   CALL FLUSH(numout) 
     453\end{verbatim} 
     454 
     455statement after any additional write statements to ensure that file contents reflect 
     456the last model state. Associated with the \texttt{sn\_cfctl%oceout} option is the 
     457additional \texttt{sn\_cfctl%oasout} suboption. This does not activate its own output 
     458file but rather activates the writing of addition information regarding the OASIS 
     459configuration when coupling via oasis and the sbccpl routine. This information is 
     460written to any active \texttt{ocean.output} files. 
     461\item{Control sums of trends for debugging} 
     462 
     463NEMO includes an option for debugging reproducibility differences between 
     464a MPP and mono-processor runs.  This is somewhat dated and clearly only 
     465useful for this purpose when dealing with configurations that can be run 
     466on a single processor. The full details can be found in this report: \href{ 
     467http://forge.ipsl.jussieu.fr/nemo/attachment/wiki/Documentation/prtctl_NEMO_doc_v2.pdf}{The 
     468control print option in NEMO} The switches to activate production of the control sums 
     469of trends for either the physics or passive tracers are the \texttt{sn\_cfctl%prtctl} 
     470and \texttt{sn\_cfctl%prttrc} suboptions, respectively. Although, perhaps, of limited use for its 
     471original intention, the ability to produce these control sums of trends in specific 
     472areas provides another tool for diagnosing model behaviour.  If only the output from a 
     473select few regions is required then additional options are available to activate options 
     474for only a simple subset of processing regions. These are: \texttt{sn\_cfctl%procmin}, 
     475\texttt{sn\_cfctl%procmax} and \texttt{sn\_cfctl%procincr} which can be used to specify 
     476the minimum and maximum active areas and the increment. The default values are set 
     477such that all regions will be active. Note this subsetting can also be used to limit 
     478which additional \texttt{ocean.output} and \texttt{layout.dat} files are produced if 
     479those suboptions are active. 
     480 
    378481\end{enumerate} 
    379482 
    380 However, in recent versions it has also been used to force all processors to assume the 
    381 reporting role. Thus when \np{ln\_ctl} is true all processors produce their own versions 
    382 of files such as: ocean.output, layout.dat, etc.  All such files, beyond the the normal 
    383 reporting processor (narea == 1), are named with a \_XXXX extension to their name, where 
    384 XXXX is a 4-digit area number (with leading zeros, if required). Other reporting files 
    385 such as run.stat (and its netCDF counterpart: run.stat.nc) and tracer.stat contain global 
    386 information and are only ever produced by the reporting master (narea == 1). For version 
    387 4.0 a start has been made to return \np{ln\_ctl} to its original function by introducing 
    388 a new control structure which allows finer control over which files are produced. This 
    389 feature is still evolving but it does already allow the user to: select individually the 
    390 production of run.stat and tracer.stat files and to toggle the production of other files 
    391 on processors other than the reporting master. These other reporters can be a simple 
    392 subset of processors as defined by a minimum, maximum and incremental processor number. 
    393  
    394 Note, that production of the run.stat and tracer.stat files require global communications. 
    395 For run.stat, these are global min and max operations to find metrics such as the gloabl 
    396 maximum velocity. For tracer.stat these are global sums of tracer fields. To improve model 
    397 performance these operations are disabled by default and, where necessary, any use of the 
    398 global values have been replaced with local calculations. For example, checks on the CFL 
    399 criterion are now done on the local domain and only reported if a breach is detected. 
    400  
    401 Experienced users may wish to still monitor this information as a check on model progress. 
    402 If so, the best compromise will be to activate the files with: 
    403  
    404 \begin{verbatim} 
    405      sn_cfctl%l_config = .TRUE. 
    406        sn_cfctl%l_runstat = .TRUE. 
    407        sn_cfctl%l_trcstat = .TRUE. 
    408 \end{verbatim} 
    409  
    410 and to use the new time increment setting to ensure the values are collected and reported 
    411 at a suitably long interval. For example: 
    412  
    413 \begin{verbatim}      
    414        sn_cfctl%ptimincr  = 25 
    415 \end{verbatim} 
    416  
    417 will carry out the global communications and write the information every 25 timesteps. This  
    418 increment also applies to the time.step file which is otherwise updated every timestep. 
    419  
    420 % ================================================================ 
    421 \biblio 
    422  
    423 \pindex 
     483 
     484   sn_cfctl%l_glochk = .FALSE.    ! Range sanity checks are local (F) or global (T). Set T for debugging only 
     485   sn_cfctl%l_allon  = .FALSE.    ! IF T activate all options. If F deactivate all unless l_config is T 
     486     sn_cfctl%l_config = .TRUE.     ! IF .true. then control which reports are written with the following 
     487       sn_cfctl%l_runstat = .FALSE. ! switches and which areas produce reports with the proc integer settings. 
     488       sn_cfctl%l_trcstat = .FALSE. ! The default settings for the proc integers should ensure 
     489       sn_cfctl%l_oceout  = .FALSE. ! that  all areas report. 
     490       sn_cfctl%l_layout  = .FALSE. ! 
     491       sn_cfctl%l_prtctl  = .FALSE. ! 
     492       sn_cfctl%l_prttrc  = .FALSE. ! 
     493       sn_cfctl%l_oasout  = .FALSE. ! 
     494       sn_cfctl%procmin   = 0       ! Minimum area number for reporting [default:0] 
     495       sn_cfctl%procmax   = 1000000 ! Maximum area number for reporting [default:1000000] 
     496       sn_cfctl%procincr  = 1       ! Increment for optional subsetting of areas [default:1] 
     497       sn_cfctl%ptimincr  = 1       ! Timestep increment for writing time step progress info 
     498 
     499 
     500 
     501\subinc{\input{../../global/epilogue}} 
    424502 
    425503\end{document} 
Note: See TracChangeset for help on using the changeset viewer.