Changeset 9413


Ignore:
Timestamp:
2018-03-21T14:43:08+01:00 (2 years ago)
Author:
nicolasmartin
Message:

Complete review of 'Output and Diagnostic chapter',

  • Reduction of all lines to ~100 characters max for easier side-by-side diff
  • Use of \xmlcode{…}, \xmlline|…| and {xmllines} env. to include XML code
  • Split long tables for XML tags and attributes to smaller ones (per type family)
  • For readability, alignement of table cells content and replacement of simple equation env. by shortand syntax \[…\]
  • Several formatting modifications
File:
1 edited

Legend:

Unmodified
Added
Removed
  • branches/2017/dev_merge_2017/DOC/tex_sub/chap_DIA.tex

    r9407 r9413  
    1717\label{sec:DIA_io_old} 
    1818 
    19 The model outputs are of three types: the restart file, the output listing,  
    20 and the diagnostic output file(s). The restart file is used internally by the code when  
    21 the user wants to start the model with initial conditions defined by a  
    22 previous simulation. It contains all the information that is necessary in  
    23 order for there to be no changes in the model results (even at the computer  
    24 precision) between a run performed with several restarts and the same run  
    25 performed in one step. It should be noted that this requires that the restart file  
    26 contain two consecutive time steps for all the prognostic variables, and  
    27 that it is saved in the same binary format as the one used by the computer  
    28 that is to read it (in particular, 32 bits binary IEEE format must not be used for  
    29 this file).  
    30  
    31 The output listing and file(s) are predefined but should be checked  
    32 and eventually adapted to the user's needs. The output listing is stored in  
    33 the $ocean.output$ file. The information is printed from within the code on the  
    34 logical unit $numout$. To locate these prints, use the UNIX command  
    35 "\textit{grep -i numout}" in the source code directory. 
    36  
    37 By default, diagnostic output files are written in NetCDF format.  
    38 Since version 3.2, when defining \key{iomput}, an I/O server has been added  
    39 which provides more flexibility in the choice of the fields to be written  
    40 as well as how the writing work is distributed over the processors in massively parallel computing.  
     19The model outputs are of three types: the restart file, the output listing, and  
     20the diagnostic output file(s). 
     21The restart file is used internally by the code when the user wants to start the model with  
     22initial conditions defined by a previous simulation. 
     23It contains all the information that is necessary in order for there to be no changes in  
     24the model results (even at the computer precision) between a run performed with several restarts and  
     25the same run performed in one step. 
     26It should be noted that this requires that the restart file contains two consecutive time steps for  
     27all the prognostic variables, and that it is saved in the same binary format as the one used by  
     28the computer that is to read it (in particular, 32 bits binary IEEE format must not be used for this file). 
     29 
     30The output listing and file(s) are predefined but should be checked and eventually adapted to  
     31the user's needs. 
     32The output listing is stored in the $ocean.output$ file. 
     33The information is printed from within the code on the logical unit $numout$. 
     34To locate these prints, use the UNIX command "\textit{grep -i numout}" in the source code directory. 
     35 
     36By default, diagnostic output files are written in NetCDF format. 
     37Since version 3.2, when defining \key{iomput}, an I/O server has been added which  
     38provides more flexibility in the choice of the fields to be written as well as  
     39how the writing work is distributed over the processors in massively parallel computing.  
    4140A complete description of the use of this I/O server is presented in the next section.  
    4241 
    43 By default, \key{iomput} is not defined, NEMO produces NetCDF with the old IOIPSL library  
    44 which has been kept for compatibility and its easy installation.  
     42By default, \key{iomput} is not defined, NEMO produces NetCDF with the old IOIPSL library which  
     43has been kept for compatibility and its easy installation. 
    4544However, the IOIPSL library is quite inefficient on parallel machines and, since version 3.2,  
    4645many diagnostic options have been added presuming the use of \key{iomput}.  
    4746The usefulness of the default IOIPSL-based option is expected to reduce with each new release.  
    48 If \key{iomput} is not defined, output files and content are defined in the \mdl{diawri} module  
    49 and contain mean (or instantaneous if \key{diainstant} is defined) values over a regular period  
    50 of nn\_write time-steps (namelist parameter).  
     47If \key{iomput} is not defined, output files and content are defined in the \mdl{diawri} module and  
     48contain mean (or instantaneous if \key{diainstant} is defined) values over a regular period of  
     49nn\_write time-steps (namelist parameter).  
    5150 
    5251%\gmcomment{                    % start of gmcomment 
     
    5857\label{sec:DIA_iom} 
    5958 
    60  
    6159Since version 3.2, iomput is the NEMO output interface of choice.  
    6260It has been designed to be simple to use, flexible and efficient.  
    6361The two main purposes of iomput are:  
     62 
    6463\begin{enumerate} 
    65 \item The complete and flexible control of the output files through external XML files  
    66 adapted by the user from standard templates.  
    67 \item To achieve high performance and scalable output through the optional distribution  
    68 of all diagnostic output related tasks to dedicated processes.  
     64   \item The complete and flexible control of the output files through external XML files adapted by  
     65         the user from standard templates. 
     66   \item To achieve high performance and scalable output through the optional distribution of  
     67         all diagnostic output related tasks to dedicated processes. 
    6968\end{enumerate} 
     69 
    7070The first functionality allows the user to specify, without code changes or recompilation,  
    7171aspects of the diagnostic output stream, such as: 
     72 
    7273\begin{itemize} 
    73 \item The choice of output frequencies that can be different for each file (including real months and years). 
    74 \item The choice of file contents; includes complete flexibility over which data are written in which files  
    75 (the same data can be written in different files).  
    76 \item The possibility to split output files at a chosen frequency. 
    77 \item The possibility to extract a vertical or an horizontal subdomain. 
    78 \item The choice of the temporal operation to perform, e.g.: average, accumulate, instantaneous, min, max and once. 
    79 \item Control over metadata via a large XML "database" of possible output fields. 
     74   \item The choice of output frequencies that can be different for each file  
     75         (including real months and years). 
     76   \item The choice of file contents; includes complete flexibility over which data are written in  
     77         which files (the same data can be written in different files). 
     78   \item The possibility to split output files at a chosen frequency. 
     79   \item The possibility to extract a vertical or an horizontal subdomain. 
     80   \item The choice of the temporal operation to perform,  
     81         e.g.: average, accumulate, instantaneous, min, max and once. 
     82   \item Control over metadata via a large XML "database" of possible output fields. 
    8083\end{itemize} 
    81 In addition, iomput allows the user to add in the code the output of any new variable (scalar, 2D or 3D)  
    82 in a very easy way. All details of iomput functionalities are listed in the following subsections.  
    83 Examples of the XML files that control the outputs can be found in: 
    84 \path{NEMOGCM/CONFIG/ORCA2_LIM/EXP00/iodef.xml}, \path{NEMOGCM/CONFIG/SHARED/field_def.xml} and 
    85 \path{NEMOGCM/CONFIG/SHARED/domain_def.xml}. 
    86  
    87 The second functionality targets output performance when running in parallel (\key{mpp\_mpi}).  
    88 Iomput provides the possibility to specify N dedicated I/O processes (in addition to the NEMO processes)  
    89 to collect and write the outputs. With an appropriate choice of N by the user,  
    90 the bottleneck associated with the writing of the output files can be greatly reduced.  
     84 
     85In addition, iomput allows the user to add in the code the output of any new variable (scalar, 2D or  
     863D) in a very easy way. 
     87All details of iomput functionalities are listed in the following subsections. 
     88Examples of the XML files that control the outputs can be found in:  
     89\path{NEMOGCM/CONFIG/ORCA2_LIM/EXP00/iodef.xml}, \path{NEMOGCM/CONFIG/SHARED/field_def.xml} and  
     90\path{NEMOGCM/CONFIG/SHARED/domain_def.xml}. \\ 
     91 
     92The second functionality targets output performance when running in parallel (\key{mpp\_mpi}). 
     93Iomput provides the possibility to specify N dedicated I/O processes (in addition to  
     94the NEMO processes) to collect and write the outputs. 
     95With an appropriate choice of N by the user, the bottleneck associated with the writing of  
     96the output files can be greatly reduced. 
    9197 
    9298In version 3.6, the iom\_put interface depends on an external code called  
    9399\href{https://forge.ipsl.jussieu.fr/ioserver/browser/XIOS/branchs/xios-1.0}{XIOS-1.0}  
    94 (use of revision 618 or higher is required). This new IO server can take advantage of  
    95 the parallel I/O functionality of NetCDF4 to create a single output file and therefore  
    96 to bypass the rebuilding phase. Note that writing in parallel into the same NetCDF files  
    97 requires that your NetCDF4 library is linked to an HDF5 library that has been correctly compiled  
    98 ($i.e.$ with the configure option $--$enable-parallel).  
    99 Note that the files created by iomput through XIOS are incompatible with NetCDF3.  
    100 All post-processsing and visualization tools must therefore be compatible with NetCDF4 and not only NetCDF3. 
     100(use of revision 618 or higher is required). 
     101This new IO server can take advantage of the parallel I/O functionality of NetCDF4 to  
     102create a single output file and therefore to bypass the rebuilding phase. 
     103Note that writing in parallel into the same NetCDF files requires that  
     104your NetCDF4 library is linked to an HDF5 library that has been correctly compiled ($i.e.$ with  
     105the configure option $--$enable-parallel). 
     106Note that the files created by iomput through XIOS are incompatible with NetCDF3. 
     107All post-processsing and visualization tools must therefore be compatible with  
     108NetCDF4 and not only NetCDF3. 
    101109 
    102110Even if not using the parallel I/O functionality of NetCDF4, using N dedicated I/O servers,  
    103 where N is typically much less than the number of NEMO processors, will reduce the number of output files created.  
    104 This can greatly reduce the post-processing burden usually associated with using large numbers of NEMO processors.  
    105 Note that for smaller configurations, the rebuilding phase can be avoided,  
    106 even without a parallel-enabled NetCDF4 library, simply by employing only one dedicated I/O server. 
     111where N is typically much less than the number of NEMO processors,  
     112will reduce the number of output files created. 
     113This can greatly reduce the post-processing burden usually associated with using  
     114large numbers of NEMO processors. 
     115Note that for smaller configurations, the rebuilding phase can be avoided, even without  
     116a parallel-enabled NetCDF4 library, simply by employing only one dedicated I/O server. 
    107117 
    108118\subsection{XIOS: XML Inputs-Outputs Server} 
     
    111121 
    112122Iomput is based on \href{http://forge.ipsl.jussieu.fr/ioserver/wiki}{XIOS},  
    113 the io\_server developed by Yann Meurdesoif from IPSL.  
    114 The behaviour of the I/O subsystem is controlled by settings in the external XML files listed above.  
    115 Key settings in the iodef.xml file are {\tt using\_server} and the {\tt type} tag associated with each defined file.  
    116 The {\tt using\_server} setting determines whether or not the server will be used in \textit{attached mode} (as a library)  
    117 [{\tt false}] or in \textit{detached mode} (as an external executable on N additional, dedicated cpus) [{\tt true}].  
    118 The \textit{attached mode} is simpler to use but much less efficient for massively parallel applications.  
     123the io\_server developed by Yann Meurdesoif from IPSL. 
     124The behaviour of the I/O subsystem is controlled by settings in the external XML files listed above. 
     125Key settings in the iodef.xml file are the tags associated with each defined file. 
     126 
     127\xmlline|<variable id="using_server" type="bool"></variable>| 
     128 
     129The {\tt using\_server} setting determines whether or not the server will be used in  
     130\textit{attached mode} (as a library) [{\tt> false <}] or in \textit{detached mode} (as  
     131an external executable on N additional, dedicated cpus) [{\tt > true <}]. 
     132The \textit{attached mode} is simpler to use but much less efficient for massively parallel applications. 
    119133The type of each file can be either ''multiple\_file'' or ''one\_file''. 
    120134 
    121135In \textit{attached mode} and if the type of file is ''multiple\_file'',  
    122 then each NEMO process will also act as an IO server and produce its own set of output files.  
    123 Superficially, this emulates the standard behaviour in previous versions.  
    124 However, the subdomain written out by each process does not correspond to the {\tt jpi x jpj x jpk}  
    125 domain actually computed by the process (although it may if {\tt jpni=1}).  
    126 Instead each process will have collected and written out a number of complete longitudinal strips.  
    127 If the ''one\_file'' option is chosen then all processes will collect their longitudinal strips  
    128 and write (in parallel) to a single output file.  
    129  
    130 In \textit{detached mode} and if the type of file is ''multiple\_file'',  
    131 then each stand-alone XIOS process will collect data for a range of complete longitudinal strips  
    132 and write to its own set of output files. If the ''one\_file'' option is chosen then  
    133 all XIOS processes will collect their longitudinal strips and write (in parallel) to a single output file.  
    134 Note running in detached mode requires launching a Multiple Process Multiple Data (MPMD) parallel job.  
    135 The following subsection provides a typical example but the syntax will vary in different MPP environments. 
     136then each NEMO process will also act as an IO server and produce its own set of output files. 
     137Superficially, this emulates the standard behaviour in previous versions. 
     138However, the subdomain written out by each process does not correspond to  
     139the \forcode{jpi x jpj x jpk} domain actually computed by the process (although it may if \forcode{jpni=1}). 
     140Instead each process will have collected and written out a number of complete longitudinal strips. 
     141If the ''one\_file'' option is chosen then all processes will collect their longitudinal strips and  
     142write (in parallel) to a single output file. 
     143 
     144In \textit{detached mode} and if the type of file is ''multiple\_file'', then  
     145each stand-alone XIOS process will collect data for a range of complete longitudinal strips and  
     146write to its own set of output files. 
     147If the ''one\_file'' option is chosen then all XIOS processes will collect their longitudinal strips and  
     148write (in parallel) to a single output file.  
     149Note running in detached mode requires launching a Multiple Process Multiple Data (MPMD) parallel job. 
     150The following subsection provides a typical example but the syntax will vary in  
     151different MPP environments. 
    136152 
    137153\subsubsection{Number of cpu used by XIOS in detached mode} 
    138154 
    139 The number of cores used by the XIOS is specified when launching the model.  
    140 The number of cores dedicated to XIOS should be from ~1/10 to ~1/50 of the number or cores dedicated to NEMO.  
    141 Some manufacturers suggest using O($\sqrt{N}$) dedicated IO processors for N processors  
    142 but this is a general recommendation and not specific to NEMO.  
     155The number of cores used by the XIOS is specified when launching the model. 
     156The number of cores dedicated to XIOS should be from \texttildelow1/10 to \texttildelow1/50 of the number of  
     157cores dedicated to NEMO. 
     158Some manufacturers suggest using O($\sqrt{N}$) dedicated IO processors for N processors but  
     159this is a general recommendation and not specific to NEMO. 
    143160It is difficult to provide precise recommendations because the optimal choice will depend on  
    144 the particular hardware properties of the target system (parallel filesystem performance, available memory,  
    145 memory bandwidth etc.) and the volume and frequency of data to be created.  
     161the particular hardware properties of the target system  
     162(parallel filesystem performance, available memory, memory bandwidth etc.) and  
     163the volume and frequency of data to be created. 
    146164Here is an example of 2 cpus for the io\_server and 62 cpu for nemo using mpirun: 
    147  
    148 \texttt{ mpirun -np 62 ./nemo.exe : -np 2 ./xios\_server.exe } 
     165\cmd|mpirun -np 62 ./nemo.exe : -np 2 ./xios_server.exe| 
    149166 
    150167\subsubsection{Control of XIOS: the context in iodef.xml} 
    151168 
    152 As well as the {\tt using\_server} flag, other controls on the use of XIOS are set in the XIOS context in iodef.xml.  
     169As well as the {\tt using\_server} flag, other controls on the use of XIOS are set in  
     170the XIOS context in iodef.xml. 
    153171See the XML basics section below for more details on XML syntax and rules. 
    154172 
    155 \begin{tabular}{|p{4cm}|p{6.0cm}|p{2.0cm}|} 
    156    \hline 
    157    variable name &  
    158    description &  
    159    example \\  
    160    \hline    
    161    \hline 
    162    buffer\_size &  
    163    buffer size used by XIOS to send data from NEMO to XIOS. Larger is more efficient.  
    164    Note that needed/used buffer sizes are summarized at the end of the job &  
    165    25000000 \\  
    166    \hline    
    167    buffer\_server\_factor\_size &  
    168    ratio between NEMO and XIOS buffer size. Should be 2. &  
    169    2 \\  
    170    \hline 
    171    info\_level &  
    172    verbosity level (0 to 100) &  
    173    0 \\  
    174    \hline 
    175    using\_server &  
    176    activate attached(false) or detached(true) mode &  
    177    true \\  
    178    \hline 
    179    using\_oasis &  
    180    XIOS is used with OASIS(true) or not (false) &  
    181    false \\  
    182    \hline 
    183    oasis\_codes\_id &  
    184    when using oasis, define the identifier of NEMO in the namcouple. Note that the identifier of XIOS is xios.x &  
    185    oceanx \\  
    186    \hline    
    187 \end{tabular} 
    188  
     173\begin{table} \scriptsize 
     174   \begin{tabularx}{\textwidth}{|lXl|} \hline 
     175      variable name                                                           & 
     176      description                                                             & 
     177      example  \\ \hline   \hline 
     178      buffer\_size                                                            & 
     179      buffer size used by XIOS to send data from NEMO to XIOS.  
     180      Larger is more efficient.  
     181      Note that needed/used buffer sizes are summarized at the end of the job & 
     182      25000000 \\ \hline 
     183      buffer\_server\_factor\_size                                            & 
     184      ratio between NEMO and XIOS buffer size. 
     185      Should be 2.                                                            & 
     186      2        \\ \hline 
     187      info\_level                                                             & 
     188      verbosity level (0 to 100)                                              & 
     189      0        \\ \hline 
     190      using\_server                                                           & 
     191      activate attached(false) or detached(true) mode                         & 
     192      true     \\ \hline 
     193      using\_oasis                                                            & 
     194      XIOS is used with OASIS(true) or not (false)                            & 
     195      false    \\ \hline 
     196      oasis\_codes\_id                                                        & 
     197      when using oasis, define the identifier of NEMO in the namcouple.  
     198      Note that the identifier of XIOS is xios.x                              & 
     199      oceanx   \\ \hline 
     200   \end{tabularx} 
     201\end{table} 
    189202 
    190203\subsection{Practical issues} 
     
    192205\subsubsection{Installation} 
    193206 
    194 As mentioned, XIOS is supported separately and must be downloaded and compiled before it can be used with NEMO.  
    195 See the installation guide on the \href{http://forge.ipsl.jussieu.fr/ioserver/wiki}{XIOS} wiki for help and guidance.  
    196 NEMO will need to link to the compiled XIOS library.  
    197 The \href{https://forge.ipsl.jussieu.fr/nemo/wiki/Users/ModelInterfacing/InputsOutputs#Inputs-OutputsusingXIOS}{XIOS with NEMO}  
     207As mentioned, XIOS is supported separately and must be downloaded and compiled before  
     208it can be used with NEMO. 
     209See the installation guide on the \href{http://forge.ipsl.jussieu.fr/ioserver/wiki}{XIOS} wiki for  
     210help and guidance. 
     211NEMO will need to link to the compiled XIOS library. 
     212The  
     213\href{https://forge.ipsl.jussieu.fr/nemo/wiki/Users/ModelInterfacing/InputsOutputs#Inputs-OutputsusingXIOS} 
     214{XIOS with NEMO} 
    198215guide provides an example illustration of how this can be achieved. 
    199216 
    200217\subsubsection{Add your own outputs} 
    201218 
    202 It is very easy to add your own outputs with iomput.  
    203 Many standard fields and diagnostics are already prepared ($i.e.$, steps 1 to 3 below have been done)  
    204 and simply need to be activated by including the required output in a file definition in iodef.xml (step 4).  
     219It is very easy to add your own outputs with iomput. 
     220Many standard fields and diagnostics are already prepared ($i.e.$, steps 1 to 3 below have been done) and  
     221simply need to be activated by including the required output in a file definition in iodef.xml (step 4). 
    205222To add new output variables, all 4 of the following steps must be taken. 
    206 \begin{description} 
    207 \item[1.] in NEMO code, add a \\ 
    208 \texttt{      CALL iom\_put( 'identifier', array ) } \\ 
    209 where you want to output a 2D or 3D array. 
    210  
    211 \item[2.] If necessary, add \\ 
    212 \texttt{   USE iom\ \ \ \ \ \ \ \ \ \ \ \ ! I/O manager library }  \\ 
    213 to the list of used modules in the upper part of your module.  
    214  
    215 \item[3.] in the field\_def.xml file, add the definition of your variable using the same identifier  
    216 you used in the f90 code (see subsequent sections for a details of the XML syntax and rules).  
     223 
     224\begin{enumerate} 
     225   \item[1.] in NEMO code, add a \forcode{CALL iom\_put( 'identifier', array )} where you want to  
     226               output a 2D or 3D array. 
     227   \item[2.] If necessary, add \forcode{USE iom ! I/O manager library} to the list of used modules in  
     228               the upper part of your module. 
     229   \item[3.] in the field\_def.xml file, add the definition of your variable using  
     230               the same identifier you used in the f90 code (see subsequent sections for  
     231               a details of the XML syntax and rules). 
    217232For example: 
    218 \begin{xmllines} 
    219    <field_definition> 
    220       <!-- T grid --> 
    221  
    222      <field_group id="grid_T" grid_ref="grid_T_3D"> 
    223       ... 
    224       <field id="identifier" long_name="blabla" ... />    
    225       ... 
    226    </field_definition>  
    227 \end{xmllines} 
    228 Note your definition must be added to the field\_group whose reference grid is consistent  
    229 with the size of the array passed to iomput.  
    230 The grid\_ref attribute refers to definitions set in iodef.xml which, in turn, reference grids  
    231 and axes either defined in the code (iom\_set\_domain\_attr and iom\_set\_axis\_attr in \mdl{iom})  
    232 or defined in the domain\_def.xml file. $e.g.$: 
    233 \begin{xmllines} 
    234      <grid id="grid_T_3D" domain_ref="grid_T" axis_ref="deptht"/> 
    235 \end{xmllines} 
     233 
     234\begin{xmllines} 
     235<field_definition> 
     236   <field_group id="grid_T" grid_ref="grid_T_3D"> <!-- T grid --> 
     237   ... 
     238      <field id="identifier" long_name="blabla" ... />    
     239      ... 
     240</field_definition>  
     241\end{xmllines} 
     242 
     243Note your definition must be added to the field\_group whose reference grid is consistent with  
     244the size of the array passed to iomput. 
     245The grid\_ref attribute refers to definitions set in iodef.xml which, in turn, reference grids and  
     246axes either defined in the code (iom\_set\_domain\_attr and iom\_set\_axis\_attr in \mdl{iom}) or  
     247defined in the domain\_def.xml file. 
     248$e.g.$: 
     249 
     250\begin{xmllines} 
     251<grid id="grid_T_3D" domain_ref="grid_T" axis_ref="deptht"/> 
     252\end{xmllines} 
     253 
    236254Note, if your array is computed within the surface module each \np{nn\_fsbc} time\_step,  
    237 add the field definition within the field\_group defined with the id ''SBC'': $<$field\_group id=''SBC''...$>$  
    238 which has been defined with the correct frequency of operations (iom\_set\_field\_attr in \mdl{iom}) 
    239  
    240 \item[4.] add your field in one of the output files defined in iodef.xml (again see subsequent sections for syntax and rules) 
    241 \begin{xmllines} 
    242    <file id="file1" .../>    
    243       ... 
    244       <field field_ref="identifier" />    
    245       ... 
    246    </file>    
    247 \end{xmllines} 
    248  
    249 \end{description} 
     255add the field definition within the field\_group defined with the id "SBC": 
     256\xmlcode{<field_group id="SBC" ...>} which has been defined with the correct frequency of  
     257operations (iom\_set\_field\_attr in \mdl{iom}) 
     258   \item[4.] add your field in one of the output files defined in iodef.xml  
     259(again see subsequent sections for syntax and rules) 
     260 
     261\begin{xmllines} 
     262<file id="file1" .../>    
     263... 
     264   <field field_ref="identifier" />    
     265   ... 
     266</file>    
     267\end{xmllines} 
     268 
     269\end{enumerate} 
    250270 
    251271\subsection{XML fundamentals} 
     
    253273\subsubsection{ XML basic rules} 
    254274 
    255 XML tags begin with the less-than character ("$<$") and end with the greater-than character (''$>$'').  
    256 You use tags to mark the start and end of elements, which are the logical units of information  
    257 in an XML document. In addition to marking the beginning of an element, XML start tags also  
    258 provide a place to specify attributes. An attribute specifies a single property for an element,  
    259 using a name/value pair, for example: $<$a b="x" c="y" b="z"$>$ ... $<$/a$>$. 
     275XML tags begin with the less-than character ("$<$") and end with the greater-than character ("$>$"). 
     276You use tags to mark the start and end of elements, which are the logical units of information in  
     277an XML document. 
     278In addition to marking the beginning of an element, XML start tags also provide a place to  
     279specify attributes. 
     280An attribute specifies a single property for an element, using a name/value pair, for example:  
     281\xmlcode{<a b="x" c="y" d="z"> ... </a>}. 
    260282See \href{http://www.xmlnews.org/docs/xml-basics.html}{here} for more details. 
    261283 
    262284\subsubsection{Structure of the XML file used in NEMO} 
    263285 
    264 The XML file used in XIOS is structured by 7 families of tags: context, axis, domain, grid, field, file and variable.  
     286The XML file used in XIOS is structured by 7 families of tags:  
     287context, axis, domain, grid, field, file and variable. 
    265288Each tag family has hierarchy of three flavors (except for context): 
    266 \\ 
    267 \begin{tabular}{|p{3.0cm}|p{4.5cm}|p{4.5cm}|} 
    268    \hline 
    269    flavor & 
    270    description & 
    271    example \\ 
    272    \hline 
    273    \hline 
    274    root & 
    275    declaration of the root element that can contain element groups or elements & 
    276    {\scriptsize \verb? < file_definition ... >?} \\ 
    277    \hline 
    278    group & 
    279    declaration of a group element that can contain element groups or elements & 
    280    {\scriptsize \verb? < file_group ... >?} \\ 
    281    \hline 
    282    element & 
    283    declaration of an element that can contain elements & 
    284    {\scriptsize \verb? < file ... >?} \\ 
    285    \hline 
    286 \end{tabular} 
    287 \\ 
    288  
    289 Each element may have several attributes.  
    290 Some attributes are mandatory, other are optional but have a default value and other are are completely optional.  
    291 Id is a special attribute used to identify an element or a group of elements.  
    292 It must be unique for a kind of element.  
     289 
     290\begin{table} \scriptsize 
     291   \begin{tabular*}{\textwidth}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} \hline 
     292      flavor  & description                                                                 & 
     293      example                          \\ \hline \hline 
     294      root    & declaration of the root element that can contain element groups or elements & 
     295      \xmlcode{<file_definition ... >} \\ \hline 
     296      group   & declaration of a group element that can contain element groups or elements  & 
     297      \xmlcode{<file_group      ... >} \\ \hline 
     298      element & declaration of an element that can contain elements                         & 
     299      \xmlcode{<file            ... >} \\ \hline 
     300   \end{tabular*} 
     301\end{table} 
     302 
     303Each element may have several attributes. 
     304Some attributes are mandatory, other are optional but have a default value and  
     305other are completely optional. 
     306Id is a special attribute used to identify an element or a group of elements. 
     307It must be unique for a kind of element. 
    293308It is optional, but no reference to the corresponding element can be done if it is not defined. 
    294309 
    295 The XML file is split into context tags that are used to isolate IO definition from different codes  
    296 or different parts of a code. No interference is possible between 2 different contexts.  
    297 Each context has its own calendar and an associated timestep.  
    298 In \NEMO, we used the following contexts (that can be defined in any order):\\ 
    299 \\ 
    300 \begin{tabular}{|p{3.0cm}|p{4.5cm}|p{4.5cm}|} 
    301    \hline 
    302    context & 
    303    description & 
    304    example \\ 
    305    \hline 
    306    \hline 
    307    context xios & 
    308    context containing information for XIOS & 
    309    {\scriptsize \verb? <context id="xios" ...  ?} \\ 
    310    \hline 
    311    context nemo & 
    312    context containing IO information for NEMO (mother grid when using AGRIF) & 
    313    {\scriptsize \verb? <context id="nemo" ... ?} \\ 
    314    \hline 
    315    context 1\_nemo & 
    316    context containing IO information for NEMO child grid 1 (when using AGRIF) & 
    317    {\scriptsize \verb? <context id="1_nemo" ...  ?} \\ 
    318    \hline 
    319    context n\_nemo & 
    320    context containing IO information for NEMO child grid n (when using AGRIF) & 
    321    {\scriptsize \verb? <context id="n_nemo" ...  ?} \\ 
    322    \hline 
    323 \end{tabular} 
    324 \\ 
     310The XML file is split into context tags that are used to isolate IO definition from different codes or  
     311different parts of a code. 
     312No interference is possible between 2 different contexts. 
     313Each context has its own calendar and an associated timestep. 
     314In \NEMO, we used the following contexts (that can be defined in any order): 
     315 
     316\begin{table} \scriptsize 
     317   \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} \hline 
     318      context         & description                                                                &  
     319      example                              \\   \hline \hline 
     320      context xios    & context containing information for XIOS                                    &  
     321      \xmlcode{<context id="xios" ... >}   \\   \hline 
     322      context nemo    & context containing IO information for NEMO (mother grid when using AGRIF)  &  
     323      \xmlcode{<context id="nemo" ... >}   \\   \hline 
     324      context 1\_nemo & context containing IO information for NEMO child grid 1 (when using AGRIF) &  
     325      \xmlcode{<context id="1_nemo" ... >} \\   \hline 
     326      context n\_nemo & context containing IO information for NEMO child grid n (when using AGRIF) &  
     327      \xmlcode{<context id="n_nemo" ... >} \\   \hline 
     328   \end{tabular} 
     329\end{table} 
    325330 
    326331\noindent The xios context contains only 1 tag: 
    327 \\ 
    328 \begin{tabular}{|p{3.0cm}|p{4.5cm}|p{4.5cm}|} 
    329    \hline 
    330    context tag & 
    331    description & 
    332    example \\ 
    333    \hline 
    334    \hline 
    335    variable\_definition & 
    336    define variables needed by XIOS. This can be seen as a kind of namelist for XIOS. & 
    337    {\scriptsize \verb? <variable_definition ... ?} \\ 
    338    \hline 
    339 \end{tabular} 
    340 \\ 
     332 
     333\begin{table} \scriptsize 
     334   \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} \hline 
     335      context tag                                      &  
     336      description                                      &  
     337      example                              \\ \hline  \hline 
     338      variable\_definition                             &  
     339      define variables needed by XIOS.  
     340      This can be seen as a kind of namelist for XIOS. &  
     341      \xmlcode{<variable_definition ... >} \\ \hline 
     342   \end{tabular} 
     343\end{table} 
    341344 
    342345\noindent Each context tag related to NEMO (mother or child grids) is divided into 5 parts  
    343 (that can be defined in any order):\\ 
    344 \\ 
    345 \begin{tabular}{|p{3.0cm}|p{4.5cm}|p{4.5cm}|} 
    346    \hline 
    347    context tag & 
    348    description & 
    349    example \\ 
    350    \hline 
    351    \hline 
    352    field\_definition & 
    353    define all variables that can potentially be outputted & 
    354    {\scriptsize \verb? <field_definition ... ?} \\ 
    355    \hline 
    356    file\_definition & 
    357    define the netcdf files to be created and the variables they will contain & 
    358    {\scriptsize \verb? <file_definition ... ?} \\ 
    359    \hline 
    360    axis\_definition & 
    361    define vertical axis & 
    362    {\scriptsize \verb? <axis_definition ... ?} \\ 
    363    \hline 
    364    domain\_definition & 
    365    define the horizontal grids & 
    366    {\scriptsize \verb? <domain_definition ... ?} \\ 
    367    \hline 
    368    grid\_definition & 
    369    define the 2D and 3D grids (association of an axis and a domain) & 
    370    {\scriptsize \verb? <grid_definition ... ?} \\ 
    371    \hline 
    372 \end{tabular} 
    373 \\ 
     346(that can be defined in any order): 
     347 
     348\begin{table} \scriptsize 
     349   \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} \hline 
     350      context tag        & description                                                               &  
     351      example                            \\ \hline \hline 
     352      field\_definition  & define all variables that can potentially be outputted                    &  
     353      \xmlcode{<field_definition ... >}  \\ \hline 
     354      file\_definition   & define the netcdf files to be created and the variables they will contain &  
     355      \xmlcode{<file_definition ... >}   \\ \hline 
     356      axis\_definition   & define vertical axis                                                      &  
     357      \xmlcode{<axis_definition ... >}   \\ \hline 
     358      domain\_definition & define the horizontal grids                                               &  
     359      \xmlcode{<domain_definition ... >} \\ \hline 
     360      grid\_definition   & define the 2D and 3D grids (association of an axis and a domain)          &  
     361      \xmlcode{<grid_definition ... >}   \\ \hline 
     362   \end{tabular} 
     363\end{table} 
    374364 
    375365\subsubsection{Nesting XML files} 
    376366 
    377 The XML file can be split in different parts to improve its readability and facilitate its use.  
    378 The inclusion of XML files into the main XML file can be done through the attribute src: \\ 
    379 {\scriptsize \verb? <context src="./nemo_def.xml" /> ?}\\ 
     367The XML file can be split in different parts to improve its readability and facilitate its use. 
     368The inclusion of XML files into the main XML file can be done through the attribute src: 
     369\xmlline|<context src="./nemo_def.xml" />| 
    380370  
    381371\noindent In NEMO, by default, the field and domain definition is done in 2 separate files: 
    382 \path{NEMOGCM/CONFIG/SHARED/field_def.xml} and \path{NEMOGCM/CONFIG/SHARED/domain_def.xml} 
    383  
    384 \noindent that are included in the main iodef.xml file through the following commands: \\ 
    385 {\scriptsize \verb? <field_definition src="./field_def.xml" /> ? \\ 
    386 \verb? <domain_definition src="./domain_def.xml" /> ? } 
    387  
     372\path{NEMOGCM/CONFIG/SHARED/field_def.xml} and \path{NEMOGCM/CONFIG/SHARED/domain_def.xml}  
     373that are included in the main iodef.xml file through the following commands: 
     374\begin{xmllines} 
     375<field_definition src="./field_def.xml" /> 
     376<domain_definition src="./domain_def.xml" /> 
     377\end{xmllines} 
    388378 
    389379\subsubsection{Use of inheritance} 
    390380 
    391 XML extensively uses the concept of inheritance.  
     381XML extensively uses the concept of inheritance. 
    392382XML has a tree based structure with a parent-child oriented relation:  
    393 all children inherit attributes from parent, but an attribute defined in a child replace the inherited attribute value.  
    394 Note that the special attribute ''id'' is never inherited.  \\ 
    395 \\ 
     383all children inherit attributes from parent, but an attribute defined in a child replace  
     384the inherited attribute value.  
     385Note that the special attribute ''id'' is never inherited. \\ \\ 
    396386example 1: Direct inheritance. 
    397 \begin{xmllines} 
    398    <field_definition operation="average" > 
    399      <field id="sst"                    />   <!-- averaged      sst -->  
    400      <field id="sss" operation="instant"/>   <!-- instantaneous sss -->  
    401    </field_definition>  
    402 \end{xmllines} 
     387 
     388\begin{xmllines} 
     389<field_definition operation="average" > 
     390   <field id="sst"                    />   <!-- averaged      sst -->  
     391   <field id="sss" operation="instant"/>   <!-- instantaneous sss -->  
     392</field_definition>  
     393\end{xmllines} 
     394 
    403395The field ''sst'' which is part (or a child) of the field\_definition will inherit the value ''average''  
    404 of the attribute ''operation'' from its parent. Note that a child can overwrite  
    405 the attribute definition inherited from its parents. In the example above, the field ''sss'' will  
    406 for example output instantaneous values instead of average values. \\ 
    407 \\ 
     396of the attribute ''operation'' from its parent. 
     397Note that a child can overwrite the attribute definition inherited from its parents. 
     398In the example above, the field ''sss'' will for example output instantaneous values instead of  
     399average values. \\ \\ 
    408400example 2: Inheritance by reference. 
    409 \begin{xmllines} 
    410    <field_definition> 
    411      <field id="sst" long_name="sea surface temperature" />    
    412      <field id="sss" long_name="sea surface salinity"    />   
    413    </field_definition>       
    414  
    415    <file_definition> 
    416      <file id="myfile" output_freq="1d" />    
    417        <field field_ref="sst"                            />  <!-- default def --> 
    418        <field field_ref="sss" long_name="my description" />  <!-- overwrite   --> 
    419      </file>    
    420    </file_definition>  
    421 \end{xmllines} 
     401 
     402\begin{xmllines} 
     403<field_definition> 
     404   <field id="sst" long_name="sea surface temperature" /> 
     405   <field id="sss" long_name="sea surface salinity"    /> 
     406</field_definition> 
     407<file_definition> 
     408   <file id="myfile" output_freq="1d" />    
     409      <field field_ref="sst"                            />  <!-- default def --> 
     410      <field field_ref="sss" long_name="my description" />  <!-- overwrite   --> 
     411   </file> 
     412</file_definition>  
     413\end{xmllines} 
     414 
    422415Inherit (and overwrite, if needed) the attributes of a tag you are refering to. 
    423416 
    424417\subsubsection{Use of groups} 
    425418 
    426 Groups can be used for 2 purposes.  
    427 Firstly, the group can be used to define common attributes to be shared by the elements of the group through inheritance.  
    428 In the following example, we define a group of field that will share a common grid ''grid\_T\_2D''.  
    429 Note that for the field ''toce'', we overwrite the grid definition inherited from the group by ''grid\_T\_3D''. 
    430 \begin{xmllines} 
    431    <field_group id="grid_T" grid_ref="grid_T_2D"> 
    432     <field id="toce" long_name="temperature"             unit="degC" grid_ref="grid_T_3D"/> 
    433     <field id="sst"  long_name="sea surface temperature" unit="degC"                     /> 
    434     <field id="sss"  long_name="sea surface salinity"    unit="psu"                      /> 
    435     <field id="ssh"  long_name="sea surface height"      unit="m"                        /> 
    436          ... 
    437 \end{xmllines} 
    438  
    439 Secondly, the group can be used to replace a list of elements.  
    440 Several examples of groups of fields are proposed at the end of the file {\tt CONFIG/SHARED/field\_def.xml}.  
     419Groups can be used for 2 purposes. 
     420Firstly, the group can be used to define common attributes to be shared by the elements of  
     421the group through inheritance. 
     422In the following example, we define a group of field that will share a common grid ''grid\_T\_2D''. 
     423Note that for the field ''toce'', we overwrite the grid definition inherited from the group by  
     424''grid\_T\_3D''. 
     425 
     426\begin{xmllines} 
     427<field_group id="grid_T" grid_ref="grid_T_2D"> 
     428   <field id="toce" long_name="temperature"             unit="degC" grid_ref="grid_T_3D"/> 
     429   <field id="sst"  long_name="sea surface temperature" unit="degC"                     /> 
     430   <field id="sss"  long_name="sea surface salinity"    unit="psu"                      /> 
     431   <field id="ssh"  long_name="sea surface height"      unit="m"                        /> 
     432   ... 
     433\end{xmllines} 
     434 
     435Secondly, the group can be used to replace a list of elements. 
     436Several examples of groups of fields are proposed at the end of the file \path{CONFIG/SHARED/field_def.xml}. 
    441437For example, a short list of the usual variables related to the U grid: 
    442 \begin{xmllines} 
    443    <field_group id="groupU" > 
    444     <field field_ref="uoce"  /> 
    445     <field field_ref="suoce" /> 
    446     <field field_ref="utau"  /> 
    447    </field_group> 
    448 \end{xmllines} 
     438 
     439\begin{xmllines} 
     440<field_group id="groupU" > 
     441   <field field_ref="uoce"  /> 
     442   <field field_ref="suoce" /> 
     443   <field field_ref="utau"  /> 
     444</field_group> 
     445\end{xmllines} 
     446 
    449447that can be directly included in a file through the following syntax: 
    450 \begin{xmllines} 
    451    <file id="myfile_U" output_freq="1d" />    
    452     <field_group group_ref="groupU"/>   
    453     <field field_ref="uocetr_eff"  />  <!-- add another field --> 
    454    </file>    
    455 \end{xmllines} 
    456  
    457 \subsection{Detailed functionalities } 
    458  
    459 The file {\tt NEMOGCM/CONFIG/ORCA2\_LIM/iodef\_demo.xml} provides several examples of the use  
    460 of the new functionalities offered by the XML interface of XIOS.  
     448 
     449\begin{xmllines} 
     450<file id="myfile_U" output_freq="1d" /> 
     451   <field_group group_ref="groupU" /> 
     452   <field field_ref="uocetr_eff"   />  <!-- add another field --> 
     453</file>    
     454\end{xmllines} 
     455 
     456\subsection{Detailed functionalities} 
     457 
     458The file \path{NEMOGCM/CONFIG/ORCA2_LIM/iodef_demo.xml} provides several examples of the use of  
     459the new functionalities offered by the XML interface of XIOS. 
    461460 
    462461\subsubsection{Define horizontal subdomains} 
    463 Horizontal subdomains are defined through the attributs zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj of the tag family domain.  
     462 
     463Horizontal subdomains are defined through the attributs zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj of  
     464the tag family domain. 
    464465It must therefore be done in the domain part of the XML file.  
    465 For example, in {\tt CONFIG/SHARED/domain\_def.xml}, we provide the following example of a definition  
    466 of a 5 by 5 box with the bottom left corner at point (10,10). 
    467 \begin{xmllines} 
    468    <domain_group id="grid_T"> 
    469     <domain id="myzoom" zoom_ibegin="10" zoom_jbegin="10" zoom_ni="5" zoom_nj="5" /> 
    470 \end{xmllines} 
    471 The use of this subdomain is done through the redefinition of the attribute domain\_ref of the tag family field. For example: 
    472 \begin{xmllines} 
    473    <file id="myfile_vzoom" output_freq="1d" > 
    474       <field field_ref="toce" domain_ref="myzoom"/> 
    475    </file> 
    476 \end{xmllines} 
     466For example, in \path{CONFIG/SHARED/domain_def.xml}, we provide the following example of a definition of  
     467a 5 by 5 box with the bottom left corner at point (10,10). 
     468 
     469\begin{xmllines} 
     470<domain_group id="grid_T"> 
     471   <domain id="myzoom" zoom_ibegin="10" zoom_jbegin="10" zoom_ni="5" zoom_nj="5" /> 
     472\end{xmllines} 
     473 
     474The use of this subdomain is done through the redefinition of the attribute domain\_ref of  
     475the tag family field. 
     476For example: 
     477 
     478\begin{xmllines} 
     479<file id="myfile_vzoom" output_freq="1d" > 
     480   <field field_ref="toce" domain_ref="myzoom"/> 
     481</file> 
     482\end{xmllines} 
     483 
    477484Moorings are seen as an extrem case corresponding to a 1 by 1 subdomain.  
    478 The Equatorial section, the TAO, RAMA and PIRATA moorings are alredy registered in the code  
    479 and can therefore be outputted without taking care of their (i,j) position in the grid.  
    480 These predefined domains can be activated by the use of specific domain\_ref: ''EqT'', ''EqU'' or ''EqW''  
    481 for the equatorial sections and the mooring position for TAO, RAMA and PIRATA followed  
    482 by ''T'' (for example: ''8s137eT'', ''1.5s80.5eT'' ...) 
    483 \begin{xmllines} 
    484    <file id="myfile_vzoom" output_freq="1d" > 
    485       <field field_ref="toce" domain_ref="0n180wT"/> 
    486    </file> 
    487 \end{xmllines} 
    488 Note that if the domain decomposition used in XIOS cuts the subdomain in several parts and if you use the ''multiple\_file'' type for your output files, you will endup with several files you will need to rebuild using unprovided tools (like ncpdq and ncrcat, \href{http://nco.sourceforge.net/nco.html#Concatenation}{see nco manual}). We are therefore advising to use the ''one\_file'' type in this case. 
     485The Equatorial section, the TAO, RAMA and PIRATA moorings are alredy registered in the code and  
     486can therefore be outputted without taking care of their (i,j) position in the grid. 
     487These predefined domains can be activated by the use of specific domain\_ref: 
     488''EqT'', ''EqU'' or ''EqW'' for the equatorial sections and the mooring position for  
     489TAO, RAMA and PIRATA followed by ''T'' (for example: ''8s137eT'', ''1.5s80.5eT'' ...) 
     490 
     491\begin{xmllines} 
     492<file id="myfile_vzoom" output_freq="1d" > 
     493   <field field_ref="toce" domain_ref="0n180wT"/> 
     494</file> 
     495\end{xmllines} 
     496 
     497Note that if the domain decomposition used in XIOS cuts the subdomain in several parts and if  
     498you use the ''multiple\_file'' type for your output files,  
     499you will endup with several files you will need to rebuild using unprovided tools (like ncpdq and ncrcat,  
     500\href{http://nco.sourceforge.net/nco.html#Concatenation}{see nco manual}). 
     501We are therefore advising to use the ''one\_file'' type in this case. 
    489502 
    490503\subsubsection{Define vertical zooms} 
    491 Vertical zooms are defined through the attributs zoom\_begin and zoom\_end of the tag family axis. It must therefore be done in the axis part of the XML file. For example, in NEMOGCM/CONFIG/ORCA2\_LIM/iodef\_demo.xml, we provide the following example: 
    492 \begin{xmllines} 
    493    <axis_group id="deptht" long_name="Vertical T levels" unit="m" positive="down" > 
    494       <axis id="deptht" /> 
    495       <axis id="deptht_myzoom" zoom_begin="1" zoom_end="10" /> 
    496 \end{xmllines} 
    497 The use of this vertical zoom is done through the redefinition of the attribute axis\_ref of the tag family field. For example: 
    498 \begin{xmllines} 
    499    <file id="myfile_hzoom" output_freq="1d" > 
    500       <field field_ref="toce" axis_ref="deptht_myzoom"/> 
    501    </file> 
     504 
     505Vertical zooms are defined through the attributs zoom\_begin and zoom\_end of the tag family axis.  
     506It must therefore be done in the axis part of the XML file.  
     507For example, in \path{NEMOGCM/CONFIG/ORCA2_LIM/iodef_demo.xml}, we provide the following example: 
     508 
     509\begin{xmllines} 
     510<axis_group id="deptht" long_name="Vertical T levels" unit="m" positive="down" > 
     511   <axis id="deptht" /> 
     512   <axis id="deptht_myzoom" zoom_begin="1" zoom_end="10" /> 
     513\end{xmllines} 
     514 
     515The use of this vertical zoom is done through the redefinition of the attribute axis\_ref of  
     516the tag family field. 
     517For example: 
     518 
     519\begin{xmllines} 
     520<file id="myfile_hzoom" output_freq="1d" > 
     521   <field field_ref="toce" axis_ref="deptht_myzoom"/> 
     522</file> 
    502523\end{xmllines} 
    503524 
    504525\subsubsection{Control of the output file names} 
    505526 
    506 The output file names are defined by the attributs ''name'' and ''name\_suffix'' of the tag family file. for example: 
    507 \begin{xmllines} 
    508    <file_group id="1d" output_freq="1d" name="myfile_1d" >  
    509       <file id="myfileA" name_suffix="_AAA" > <!-- will create file "myfile_1d_AAA"  --> 
    510          ... 
    511       </file> 
    512       <file id="myfileB" name_suffix="_BBB" > <!-- will create file "myfile_1d_BBB" --> 
    513          ... 
    514       </file> 
    515    </file_group> 
    516 \end{xmllines} 
    517 However it is often very convienent to define the file name with the name of the experiment, the output file frequency and the date of the beginning and the end of the simulation (which are informations stored either in the namelist or in the XML file). To do so, we added the following rule: if the id of the tag file is ''fileN''(where N = 1 to 999 on 1 to 3 digits) or one of the predefined sections or moorings (see next subsection), the following part of the name and the name\_suffix (that can be inherited) will be automatically replaced by:\\ 
    518 \\ 
    519 \begin{tabular}{|p{4cm}|p{8cm}|} 
    520    \hline 
    521    \centering placeholder string & automatically  replaced by \\ 
    522    \hline 
    523    \hline 
    524    \centering @expname@ & 
    525    the experiment name (from cn\_exp in the namelist) \\ 
    526    \hline 
    527    \centering @freq@ & 
    528    output frequency (from attribute output\_freq) \\ 
    529    \hline 
    530    \centering @startdate@  & 
    531    starting date of the simulation (from nn\_date0 in the restart or the namelist). \verb?yyyymmdd? format \\ 
    532    \hline 
    533    \centering @startdatefull@  &  
    534    starting date of the simulation (from nn\_date0 in the restart or the namelist). \verb?yyyymmdd_hh:mm:ss? format \\ 
    535    \hline 
    536    \centering @enddate@  & 
    537    ending date of the simulation (from nn\_date0 and nn\_itend in the namelist). \verb?yyyymmdd? format \\ 
    538    \hline 
    539    \centering @enddatefull@  &  
    540    ending date of the simulation (from nn\_date0 and nn\_itend in the namelist). \verb?yyyymmdd_hh:mm:ss? format \\ 
    541    \hline 
    542 \end{tabular}\\ 
    543 \\ 
     527The output file names are defined by the attributs ''name'' and ''name\_suffix'' of the tag family file. 
     528For example: 
     529 
     530\begin{xmllines} 
     531<file_group id="1d" output_freq="1d" name="myfile_1d" >  
     532   <file id="myfileA" name_suffix="_AAA" > <!-- will create file "myfile_1d_AAA"  --> 
     533      ... 
     534   </file> 
     535   <file id="myfileB" name_suffix="_BBB" > <!-- will create file "myfile_1d_BBB" --> 
     536      ... 
     537   </file> 
     538</file_group> 
     539\end{xmllines} 
     540 
     541However it is often very convienent to define the file name with the name of the experiment,  
     542the output file frequency and the date of the beginning and the end of the simulation  
     543(which are informations stored either in the namelist or in the XML file). 
     544To do so, we added the following rule: if the id of the tag file is ''fileN'' (where N = 1 to 999 on  
     5451 to 3 digits) or one of the predefined sections or moorings (see next subsection),  
     546the following part of the name and the name\_suffix (that can be inherited) will be automatically  
     547replaced by: 
     548 
     549\begin{table} \scriptsize 
     550   \begin{tabularx}{\textwidth}{|lX|} \hline 
     551      \centering placeholder string & 
     552      automatically replaced by                          \\ \hline \hline 
     553      \centering @expname@          & 
     554      the experiment name (from cn\_exp in the namelist) \\ \hline 
     555      \centering @freq@             & 
     556      output frequency (from attribute output\_freq)     \\ \hline 
     557      \centering @startdate@        & 
     558      starting date of the simulation (from nn\_date0 in the restart or the namelist). \newline 
     559      \verb?yyyymmdd?          format                   \\ \hline 
     560      \centering @startdatefull@    & 
     561      starting date of the simulation (from nn\_date0 in the restart or the namelist). \newline 
     562      \verb?yyyymmdd_hh:mm:ss? format                    \\ \hline 
     563      \centering @enddate@          & 
     564      ending date of the simulation   (from nn\_date0 and nn\_itend  in the namelist). \newline 
     565      \verb?yyyymmdd?          format                    \\ \hline 
     566      \centering @enddatefull@      & 
     567      ending date of the simulation   (from nn\_date0 and nn\_itend  in the namelist). \newline 
     568      \verb?yyyymmdd_hh:mm:ss? format                    \\ \hline 
     569   \end{tabularx} 
     570\end{table} 
    544571 
    545572\noindent For example,  
    546 {{\scriptsize 
    547 \begin{verbatim} 
    548    <file id="myfile_hzoom" name="myfile_@expname@_@startdate@_freq@freq@" output_freq="1d" > 
    549 \end{verbatim} 
    550 }} 
     573\xmlline|<file id="myfile_hzoom" name="myfile_@expname@_@startdate@_freq@freq@" output_freq="1d" >| 
     574 
    551575\noindent with the namelist: 
    552 {{\scriptsize 
    553 \begin{verbatim} 
    554    cn_exp      =  "ORCA2" 
    555    nn_date0    =  19891231 
    556    ln_rstart   = .false. 
    557 \end{verbatim} 
    558 }} 
     576\begin{forlines} 
     577cn_exp    = "ORCA2" 
     578nn_date0  = 19891231 
     579ln_rstart = .false. 
     580\end{forlines} 
     581 
    559582\noindent will give the following file name radical: 
    560 {{\scriptsize 
    561 \begin{verbatim} 
    562    myfile_ORCA2_19891231_freq1d  
    563 \end{verbatim} 
    564 }} 
     583\ifile{myfile\_ORCA2\_19891231\_freq1d} 
    565584 
    566585\subsubsection{Other controls of the XML attributes from NEMO} 
    567586 
    568 The values of some attributes are defined by subroutine calls within NEMO (calls to iom\_set\_domain\_attr, iom\_set\_axis\_attr and iom\_set\_field\_attr in \mdl{iom}). Any definition given in the xml file will be overwritten. By convention, these attributes are defined to ''auto'' (for string) or ''0000'' (for integer) in the xml file (but this is not necessary).  
    569  
    570 Here is the list of these attributes:\\ 
    571 \\ 
    572 \begin{tabular}{|l|c|c|c|} 
    573    \hline 
    574  \multicolumn{2}{|c|}{tag ids affected by automatic           }  & name      & attribute value \\ 
    575   \multicolumn{2}{|c|}{definition of some of their attributes }  & attribute  &        \\ 
    576    \hline 
    577    \hline 
    578     \multicolumn{2}{|c|}{field\_definition} & freq\_op & \np{rn\_rdt} \\ 
    579    \hline 
    580     \multicolumn{2}{|c|}{SBC}               & freq\_op & \np{rn\_rdt} $\times$ \np{nn\_fsbc}  \\ 
    581    \hline 
    582     \multicolumn{2}{|c|}{ptrc\_T}           & freq\_op & \np{rn\_rdt} $\times$ \np{nn\_dttrc} \\ 
    583    \hline 
    584     \multicolumn{2}{|c|}{diad\_T}           & freq\_op & \np{rn\_rdt} $\times$ \np{nn\_dttrc} \\ 
    585    \hline 
    586     \multicolumn{2}{|c|}{EqT, EqU, EqW} & jbegin, ni,      & according to the grid    \\ 
    587     \multicolumn{2}{|c|}{                         } & name\_suffix &                                      \\ 
    588    \hline 
    589    \multicolumn{2}{|c|}{TAO, RAMA and PIRATA moorings} & zoom\_ibegin, zoom\_jbegin, & according to the grid    \\ 
    590     \multicolumn{2}{|c|}{                                                       } & name\_suffix &                                      \\ 
    591    \hline 
    592 \end{tabular} 
     587The values of some attributes are defined by subroutine calls within NEMO  
     588(calls to iom\_set\_domain\_attr, iom\_set\_axis\_attr and iom\_set\_field\_attr in \mdl{iom}).  
     589Any definition given in the XML file will be overwritten.  
     590By convention, these attributes are defined to ''auto'' (for string) or ''0000'' (for integer) in  
     591the XML file (but this is not necessary). \\ 
     592 
     593Here is the list of these attributes: \\ 
     594 
     595\begin{table} \scriptsize 
     596\begin{tabularx}{\textwidth}{|X|c|c|c|}   \hline 
     597   tag ids affected by automatic definition of some of their attributes &  
     598   name attribute                                                       &  
     599   attribute value                      \\ \hline \hline 
     600   field\_definition                                                    &  
     601   freq\_op                                                             &  
     602   \np{rn\_rdt}                         \\ \hline 
     603   SBC                                                                  &  
     604   freq\_op                                                             &  
     605   \np{rn\_rdt} $\times$ \np{nn\_fsbc}  \\ \hline 
     606   ptrc\_T                                                              &  
     607   freq\_op                                                             &  
     608   \np{rn\_rdt} $\times$ \np{nn\_dttrc} \\ \hline 
     609   diad\_T                                                              &  
     610   freq\_op                                                             &  
     611   \np{rn\_rdt} $\times$ \np{nn\_dttrc} \\ \hline 
     612   EqT, EqU, EqW                                                        &  
     613   jbegin, ni,                                                          &  
     614   according to the grid                \\ 
     615                                                                        &  
     616   name\_suffix                                                         &  
     617                                        \\ \hline 
     618   TAO, RAMA and PIRATA moorings                                        &  
     619   zoom\_ibegin, zoom\_jbegin,                                          &  
     620   according to the grid                \\ 
     621                                                                        &  
     622   name\_suffix                                                         &  
     623                                        \\ \hline 
     624\end{tabularx} 
     625\end{table} 
    593626 
    594627\subsubsection{Advanced use of XIOS functionalities} 
     
    597630\label{subsec:IOM_xmlref} 
    598631 
    599 (1) Simple computation: directly define the computation when refering to the variable in the file definition. 
    600  
    601 \begin{xmllines} 
    602  <field field_ref="sst"  name="tosK"  unit="degK" > sst + 273.15 </field> 
    603  <field field_ref="taum" name="taum2" unit="N2/m4" long_name="square of wind stress module" > taum * taum </field> 
    604  <field field_ref="qt"   name="stupid_check" > qt - qsr - qns </field> 
    605 \end{xmllines} 
    606  
    607 (2) Simple computation: define a new variable and use it in the file definition. 
     632\begin{enumerate} 
     633\item Simple computation: directly define the computation when refering to the variable in  
     634the file definition. 
     635 
     636\begin{xmllines} 
     637<field field_ref="sst"  name="tosK"  unit="degK" > sst + 273.15 </field> 
     638<field field_ref="taum" name="taum2" unit="N2/m4" long_name="square of wind stress module" > taum * taum </field> 
     639<field field_ref="qt"   name="stupid_check" > qt - qsr - qns </field> 
     640\end{xmllines} 
     641 
     642\item Simple computation: define a new variable and use it in the file definition. 
    608643 
    609644in field\_definition: 
    610 \begin{xmllines} 
    611  <field id="sst2" long_name="square of sea surface temperature" unit="degC2" >  sst * sst </field > 
    612 \end{xmllines} 
     645 
     646\begin{xmllines} 
     647<field id="sst2" long_name="square of sea surface temperature" unit="degC2" >  sst * sst </field > 
     648\end{xmllines} 
     649 
    613650in file\_definition: 
    614 \begin{xmllines} 
    615  <field field_ref="sst2" > sst2 </field> 
    616 \end{xmllines} 
    617 Note that in this case, the following syntaxe $<$field field\_ref="sst2" /$>$ is not working as sst2 won't be evaluated. 
    618  
    619 (3) Change of variable precision: 
    620  
    621 \begin{xmllines} 
    622      <!-- force to keep real 8 --> 
    623  <field field_ref="sst" name="tos_r8" prec="8" /> 
    624       <!-- integer 2  with add_offset and scale_factor attributes --> 
    625  <field field_ref="sss" name="sos_i2" prec="2" add_offset="20." scale_factor="1.e-3" /> 
    626 \end{xmllines} 
    627 Note that, then the code is crashing, writting real4 variables forces a numerical convection from real8 to real4 which will create an internal error in NetCDF and will avoid the creation of the output files. Forcing double precision outputs with prec="8" (for example in the field\_definition) will avoid this problem. 
    628  
    629 (4) add user defined attributes: 
    630  
    631 \begin{xmllines} 
    632       <file_group id="1d" output_freq="1d" output_level="10" enabled=".true."> <!-- 1d files -->  
     651 
     652\begin{xmllines} 
     653<field field_ref="sst2" > sst2 </field> 
     654\end{xmllines} 
     655 
     656Note that in this case, the following syntaxe \xmlcode{<field field_ref="sst2" />} is not working as  
     657sst2 won't be evaluated. 
     658 
     659\item Change of variable precision: 
     660 
     661\begin{xmllines} 
     662<!-- force to keep real 8 --> 
     663<field field_ref="sst" name="tos_r8" prec="8" /> 
     664<!-- integer 2  with add_offset and scale_factor attributes --> 
     665<field field_ref="sss" name="sos_i2" prec="2" add_offset="20." scale_factor="1.e-3" /> 
     666\end{xmllines} 
     667 
     668Note that, then the code is crashing, writting real4 variables forces a numerical convection from  
     669real8 to real4 which will create an internal error in NetCDF and will avoid the creation of  
     670the output files. 
     671Forcing double precision outputs with prec="8" (for example in the field\_definition) will  
     672avoid this problem. 
     673 
     674\item add user defined attributes: 
     675 
     676\begin{xmllines} 
     677<file_group id="1d" output_freq="1d" output_level="10" enabled=".true."> <!-- 1d files -->  
    633678   <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" > 
    634      <field field_ref="sst" name="tos" > 
    635        <variable id="my_attribute1" type="string"  > blabla </variable> 
    636        <variable id="my_attribute2" type="integer" > 3      </variable> 
    637        <variable id="my_attribute3" type="float"   > 5.0    </variable> 
    638      </field> 
    639      <variable id="my_global_attribute" type="string" > blabla_global </variable> 
    640        </file> 
    641      </file_group>  
    642 \end{xmllines} 
    643  
    644 (5) use of the ``@'' function: example 1, weighted temporal average 
     679      <field field_ref="sst" name="tos" > 
     680         <variable id="my_attribute1" type="string"  > blabla </variable> 
     681         <variable id="my_attribute2" type="integer" > 3      </variable> 
     682         <variable id="my_attribute3" type="float"   > 5.0    </variable> 
     683      </field> 
     684      <variable id="my_global_attribute" type="string" > blabla_global </variable> 
     685   </file> 
     686</file_group>  
     687\end{xmllines} 
     688 
     689\item use of the ``@'' function: example 1, weighted temporal average 
    645690 
    646691 - define a new variable in field\_definition 
    647 \begin{xmllines} 
    648  <field id="toce_e3t" long_name="temperature * e3t" unit="degC*m" grid_ref="grid_T_3D" > toce * e3t </field > 
    649 \end{xmllines} 
    650  - use it when defining your file.   
     692 
     693\begin{xmllines} 
     694<field id="toce_e3t" long_name="temperature * e3t" unit="degC*m" grid_ref="grid_T_3D" >toce * e3t</field> 
     695\end{xmllines} 
     696 
     697 - use it when defining your file. 
     698 
    651699\begin{xmllines} 
    652700<file_group id="5d" output_freq="5d"  output_level="10" enabled=".true." >  <!-- 5d files -->   
    653  <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" > 
    654   <field field_ref="toce" operation="instant" freq_op="5d" > @toce_e3t / @e3t </field> 
    655  </file> 
     701   <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" > 
     702      <field field_ref="toce" operation="instant" freq_op="5d" > @toce_e3t / @e3t </field> 
     703   </file> 
    656704</file_group>  
    657705\end{xmllines} 
    658 The freq\_op="5d" attribute is used to define the operation frequency of the ``@'' function: here 5 day. The temporal operation done by the ``@'' is the one defined in the field definition: here we use the default, average. So, in the above case, @toce\_e3t will do the 5-day mean of toce*e3t. Operation="instant" refers to the temporal operation to be performed on the field''@toce\_e3t / @e3t'': here the temporal average is alreday done by the ``@'' function so we just use instant to do the ratio of the 2 mean values. field\_ref="toce" means that attributes not explicitely defined, are inherited from toce field. Note that in this case, freq\_op must be equal to the file output\_freq. 
    659  
    660 (6) use of the ``@'' function: example 2, monthly SSH standard deviation 
     706 
     707The freq\_op="5d" attribute is used to define the operation frequency of the ``@'' function: here 5 day. 
     708The temporal operation done by the ``@'' is the one defined in the field definition:  
     709here we use the default, average. 
     710So, in the above case, @toce\_e3t will do the 5-day mean of toce*e3t. 
     711Operation="instant" refers to the temporal operation to be performed on the field''@toce\_e3t / @e3t'':  
     712here the temporal average is alreday done by the ``@'' function so we just use instant to do the ratio of  
     713the 2 mean values. 
     714field\_ref="toce" means that attributes not explicitely defined, are inherited from toce field. 
     715Note that in this case, freq\_op must be equal to the file output\_freq. 
     716 
     717\item use of the ``@'' function: example 2, monthly SSH standard deviation 
    661718 
    662719 - define a new variable in field\_definition 
    663 \begin{xmllines} 
    664  <field id="ssh2" long_name="square of sea surface temperature" unit="degC2" >  ssh * ssh </field > 
    665 \end{xmllines} 
    666  - use it when defining your file.   
     720 
     721\begin{xmllines} 
     722<field id="ssh2" long_name="square of sea surface temperature" unit="degC2" > ssh * ssh </field > 
     723\end{xmllines} 
     724 
     725 - use it when defining your file. 
     726 
    667727\begin{xmllines} 
    668728<file_group id="1m" output_freq="1m"  output_level="10" enabled=".true." >  <!-- 1m files -->   
    669  <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" > 
    670   <field field_ref="ssh" name="sshstd" long_name="sea_surface_temperature_standard_deviation" operation="instant" freq_op="1m" > sqrt( @ssh2 - @ssh * @ssh ) </field> 
    671  </file> 
     729   <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" > 
     730      <field field_ref="ssh" name="sshstd" long_name="sea_surface_temperature_standard_deviation"  
     731      operation="instant" freq_op="1m" > 
     732         sqrt( @ssh2 - @ssh * @ssh ) 
     733      </field> 
     734   </file> 
    672735</file_group>  
    673736\end{xmllines} 
    674 The freq\_op="1m" attribute is used to define the operation frequency of the ``@'' function: here 1 month. The temporal operation done by the ``@'' is the one defined in the field definition: here we use the default, average. So, in the above case, @ssh2 will do the monthly mean of ssh*ssh. Operation="instant" refers to the temporal operation to be performed on the field ''sqrt( @ssh2 - @ssh * @ssh )'': here the temporal average is alreday done by the ``@'' function so we just use instant. field\_ref="ssh" means that attributes not explicitely defined, are inherited from ssh field. Note that in this case, freq\_op must be equal to the file output\_freq. 
    675  
    676 (7) use of the ``@'' function: example 3, monthly average of SST diurnal cycle 
     737 
     738The freq\_op="1m" attribute is used to define the operation frequency of the ``@'' function: here 1 month. 
     739The temporal operation done by the ``@'' is the one defined in the field definition:  
     740here we use the default, average. 
     741So, in the above case, @ssh2 will do the monthly mean of ssh*ssh. 
     742Operation="instant" refers to the temporal operation to be performed on  
     743the field ''sqrt( @ssh2 - @ssh * @ssh )'':  
     744here the temporal average is alreday done by the ``@'' function so we just use instant. 
     745field\_ref="ssh" means that attributes not explicitely defined, are inherited from ssh field. 
     746Note that in this case, freq\_op must be equal to the file output\_freq. 
     747 
     748\item use of the ``@'' function: example 3, monthly average of SST diurnal cycle 
    677749 
    678750 - define 2 new variables in field\_definition 
    679 \begin{xmllines} 
    680  <field id="sstmax" field_ref="sst" long_name="max of sea surface temperature" operation="maximum" /> 
    681  <field id="sstmin" field_ref="sst" long_name="min of sea surface temperature" operation="minimum" /> 
    682 \end{xmllines} 
    683  - use these 2 new variables when defining your file.   
     751 
     752\begin{xmllines} 
     753<field id="sstmax" field_ref="sst" long_name="max of sea surface temperature" operation="maximum" /> 
     754<field id="sstmin" field_ref="sst" long_name="min of sea surface temperature" operation="minimum" /> 
     755\end{xmllines} 
     756 
     757 - use these 2 new variables when defining your file. 
     758 
    684759\begin{xmllines} 
    685760<file_group id="1m" output_freq="1m"  output_level="10" enabled=".true." >  <!-- 1m files -->   
    686  <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" > 
    687   <field field_ref="sst" name="sstdcy" long_name="amplitude of sst diurnal cycle" operation="average" freq_op="1d" > @sstmax - @sstmin </field> 
    688  </file> 
     761   <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" > 
     762      <field field_ref="sst" name="sstdcy" long_name="amplitude of sst diurnal cycle" operation="average" freq_op="1d" > 
     763         @sstmax - @sstmin 
     764      </field> 
     765   </file> 
    689766</file_group>  
    690767\end{xmllines} 
    691 The freq\_op="1d" attribute is used to define the operation frequency of the ``@'' function: here 1 day. The temporal operation done by the ``@'' is the one defined in the field definition: here maximum for sstmax and minimum for sstmin. So, in the above case, @sstmax will do the daily max and @sstmin the daily min. Operation="average" refers to the temporal operation to be performed on the field ``@sstmax - @sstmin'': here monthly mean (of daily max - daily min of the sst). field\_ref="sst" means that attributes not explicitely defined, are inherited from sst field. 
    692  
    693  
    694  
    695 \subsubsection{Tag list} 
    696  
    697 \begin{longtable}{|p{2.2cm}|p{2.5cm}|p{3.5cm}|p{2.2cm}|p{1.6cm}|} 
    698    \hline 
    699    tag name &  
    700    description &  
    701    accepted attribute &  
    702    child of & 
    703    parent of \endhead 
    704    \hline    
    705    simulation &  
    706    this tag is the root tag which encapsulates all the content of the xml file & 
    707    none & 
    708    none & 
    709    context \\ 
    710    \hline    
    711    context & 
    712    encapsulates parts of the xml file dedicated to different codes or different parts of a code & 
    713    id (''xios'', ''nemo'' or ''n\_nemo'' for the nth AGRIF zoom), src, time\_origin & 
    714    simulation & 
    715    all root tags: ... \_definition \\ 
    716    \hline    
    717    \hline    
    718    field\_definition & 
    719    encapsulates the definition of all the fields that can potentially be outputted & 
    720    axis\_ref, default\_value, domain\_ref, enabled, grid\_ref, level, operation, prec, src & 
    721    context & 
    722    field or field\_group \\ 
    723    \hline    
    724    field\_group & 
    725    encapsulates a group of fields & 
    726    axis\_ref, default\_value, domain\_ref, enabled, group\_ref, grid\_ref, id, level, operation, prec, src & 
    727    field\_definition, field\_group, file & 
    728    field or field\_group \\ 
    729    \hline    
    730    field & 
    731    define a specific field & 
    732    axis\_ref, default\_value, domain\_ref, enabled, field\_ref, grid\_ref, id, level, long\_name, name, operation, prec, standard\_name, unit & 
    733    field\_definition, field\_group, file & 
    734    none \\ 
    735    \hline    
    736    \hline    
    737    file\_definition &  
    738    encapsulates the definition of all the files that will be outputted & 
    739    enabled, min\_digits, name, name\_suffix, output\_level, split\_freq\_format, split\_freq, sync\_freq, type, src & 
    740    context &  
    741    file or file\_group \\ 
    742    \hline    
    743    file\_group &  
    744    encapsulates a group of files that will be outputted & 
    745    enabled, description, id, min\_digits, name, name\_suffix, output\_freq, output\_level, split\_freq\_format, split\_freq, sync\_freq, type, src & 
    746    file\_definition, file\_group &  
    747    file or file\_group \\ 
    748    \hline    
    749    file &  
    750    define the contents of a file to be outputted & 
    751    enabled, description, id, min\_digits, name, name\_suffix, output\_freq, output\_level, split\_freq\_format, split\_freq, sync\_freq, type, src & 
    752    file\_definition, file\_group &  
    753    field \\ 
    754    \hline    
    755    axis\_definition &  
    756    define all the vertical axis potentially used by the variables & 
    757    src & 
    758    context &   
    759    axis\_group, axis \\ 
    760    \hline    
    761    axis\_group &  
    762    encapsulates a group of vertical axis & 
    763    id, lon\_name, positive, src, standard\_name, unit, zoom\_begin, zoom\_end, zoom\_size & 
    764    axis\_definition, axis\_group &  
    765    axis\_group, axis \\ 
    766    \hline    
    767    axis &  
    768    define a vertical axis & 
    769    id, lon\_name, positive, src, standard\_name, unit, zoom\_begin, zoom\_end, zoom\_size & 
    770    axis\_definition, axis\_group  &  
    771    none \\ 
    772    \hline    
    773    \hline    
    774    domain\_\-definition &  
    775    define all the horizontal domains potentially used by the variables & 
    776    src & 
    777    context &  
    778    domain\_\-group, domain \\ 
    779    \hline    
    780    domain\_group &  
    781    encapsulates a group of horizontal domains & 
    782    id, lon\_name, src, zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj & 
    783    domain\_\-definition, domain\_group &  
    784    domain\_\-group, domain \\ 
    785    \hline    
    786    domain &  
    787    define an horizontal domain & 
    788    id, lon\_name, src, zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj & 
    789    domain\_\-definition, domain\_group &  
    790    none \\ 
    791    \hline    
    792    \hline    
    793    grid\_definition &  
    794    define all the grid (association of a domain and/or an axis) potentially used by the variables & 
    795    src & 
    796    context &  
    797    grid\_group, grid \\ 
    798    \hline    
    799    grid\_group &  
    800    encapsulates a group of grids & 
    801    id, domain\_ref, axis\_ref & 
    802    grid\_definition, grid\_group &  
    803    grid\_group, grid \\ 
    804    \hline    
    805    grid &  
    806    define a grid & 
    807    id, domain\_ref, axis\_ref & 
    808    grid\_definition, grid\_group &  
    809    none \\ 
    810    \hline    
    811 \end{longtable} 
    812  
    813  
    814 \subsubsection{Attributes list} 
    815  
    816 \begin{longtable}{|p{2.2cm}|p{4cm}|p{3.8cm}|p{2cm}|} 
    817    \hline 
    818    attribute name &  
    819    description &  
    820    example &  
    821    accepted by \endhead 
    822    \hline    
    823    axis\_ref &  
    824    refers to the id of a vertical axis &  
    825    axis\_ref="deptht" &  
    826    field, grid families \\  
    827    \hline    
    828    enabled &  
    829    switch on/off the output of a field or a file &  
    830    enabled=".true." &  
    831    field, file families \\  
    832    \hline    
    833    default\_value &  
    834    missing\_value definition &  
    835    default\_value="1.e20" &  
    836    field family \\  
    837    \hline    
    838    description &  
    839    just for information, not used &  
    840    description="ocean T grid variables" &  
    841    all tags \\  
    842    \hline    
    843    domain\_ref &  
    844    refers to the id of a domain &  
    845    domain\_ref="grid\_T" &  
    846    field or grid families \\  
    847    \hline    
    848    field\_ref &  
    849    id of the field we want to add in a file &  
    850    field\_ref="toce" &  
    851    field \\  
    852    \hline    
    853    grid\_ref &  
    854    refers to the id of a grid &  
    855    grid\_ref="grid\_T\_2D" &  
    856    field family \\  
    857    \hline    
    858    group\_ref &  
    859    refer to a group of variables &  
    860    group\_ref="mooring" &  
    861    field\_group \\  
    862    \hline    
    863    id &  
    864    allow to identify a tag &  
    865    id="nemo" & 
    866    accepted by all tags except simulation \\  
    867    \hline    
    868    level &  
    869    output priority of a field: 0 (high) to 10 (low)&  
    870    level="1" &  
    871    field family \\  
    872    \hline    
    873    long\_name &  
    874    define the long\_name attribute in the NetCDF file &  
    875    long\_name="Vertical T levels" &  
    876    field \\  
    877    \hline    
    878    min\_digits &  
    879    specify the minimum of digits used in the core number in the name of the NetCDF file &  
    880    min\_digits="4" &  
    881    file family \\  
    882    \hline    
    883    name &  
    884    name of a variable or a file. If the name of a file is undefined, its id is used as a name &  
    885    name="tos" &  
    886    field or file families \\  
    887    \hline    
    888    name\_suffix &  
    889    suffix to be inserted after the name and before the cpu number and the ''.nc'' termination of a file &  
    890    name\_suffix="\_myzoom" &  
    891    file family \\  
    892    \hline    
    893    attribute name &  
    894    description &  
    895    example &  
    896    accepted by \\  
    897    \hline    
    898    \hline    
    899    operation &  
    900    type of temporal operation: average, accumulate, instantaneous, min, max and once &  
    901    operation="average" &  
    902    field family \\  
    903    \hline    
    904    output\_freq &  
    905    operation frequency. units can be ts (timestep), y, mo, d, h, mi, s. &  
    906    output\_freq="1d12h" &  
    907    field family \\  
    908    \hline    
    909    output\_level &  
    910    output priority of variables in a file: 0 (high) to 10 (low). All variables listed in the file with a level smaller or equal to output\_level will be output. Other variables won't be output even if they are listed in the file. &   
    911    output\_level="10"&  
    912    file family \\  
    913    \hline    
    914    positive &  
    915    convention used for the orientation of vertival axis (positive downward in \NEMO). &  
    916    positive="down" &  
    917    axis family \\  
    918    \hline    
    919    prec &  
    920    output precision: real 4 or real 8 &  
    921    prec="4" &  
    922    field family \\  
    923    \hline    
    924    split\_freq &  
    925    frequency at which to temporally split output files. Units can be ts (timestep), y, mo, d, h, mi, s. Useful for long runs to prevent over-sized output files.&  
    926    split\_freq="1mo" &  
    927    file family \\  
    928    \hline    
    929    split\_freq\-\_format &  
    930    date format used in the name of temporally split output files. Can be specified  
    931    using the following syntaxes: \%y, \%mo, \%d, \%h \%mi and \%s &  
    932    split\_freq\_format= "\%y\%mo\%d" &  
    933    file family \\  
    934    \hline    
    935    src &  
    936    allow to include a file &  
    937    src="./field\_def.xml" &  
    938    accepted by all tags except simulation \\  
    939    \hline    
    940    standard\_name &  
    941    define the standard\_name attribute in the NetCDF file &  
    942    standard\_name= "Eastward\_Sea\_Ice\_Transport" &  
    943    field \\  
    944    \hline    
    945    sync\_freq &  
    946    NetCDF file synchronization frequency (update of the time\_counter). units can be ts (timestep), y, mo, d, h, mi, s. &  
    947    sync\_freq="10d" &  
    948    file family \\  
    949    \hline    
    950    attribute name &  
    951    description &  
    952    example &  
    953    accepted by \\  
    954    \hline    
    955    \hline    
    956    time\_origin &  
    957    specify the origin of the time counter &  
    958    time\_origin="1900-01-01 00:00:00"&  
    959    context \\  
    960    \hline    
    961    type (1)&  
    962    specify if the output files are to be split spatially (multiple\_file) or not (one\_file) &  
    963    type="multiple\_file" &  
    964    file familly \\  
    965    \hline    
    966    type (2)&  
    967    define the type of a variable tag &  
    968    type="boolean" &  
    969    variable \\  
    970    \hline    
    971    unit &  
    972    unit of a variable or the vertical axis &  
    973    unit="m" &  
    974    field and axis families \\  
    975    \hline    
    976    zoom\_ibegin &  
    977    starting point along x direction of the zoom. Automatically defined for TAO/RAMA/PIRATA moorings &  
    978    zoom\_ibegin="1" &  
    979    domain family \\  
    980    \hline    
    981    zoom\_jbegin &  
    982    starting point along y direction of the zoom. Automatically defined for TAO/RAMA/PIRATA moorings &  
    983    zoom\_jbegin="1" &  
    984    domain family \\  
    985    \hline    
    986    zoom\_ni &  
    987    zoom extent along x direction &  
    988    zoom\_ni="1" &  
    989    domain family \\  
    990    \hline    
    991    zoom\_nj &  
    992    zoom extent along y direction &  
    993    zoom\_nj="1" &  
    994    domain family \\  
    995    \hline    
    996 \end{longtable} 
     768 
     769\end{enumerate} 
     770 
     771The freq\_op="1d" attribute is used to define the operation frequency of the ``@'' function: here 1 day. 
     772The temporal operation done by the ``@'' is the one defined in the field definition: here maximum for  
     773sstmax and minimum for sstmin. 
     774So, in the above case, @sstmax will do the daily max and @sstmin the daily min. 
     775Operation="average" refers to the temporal operation to be performed on the field ``@sstmax - @sstmin'':  
     776here monthly mean (of daily max - daily min of the sst). 
     777field\_ref="sst" means that attributes not explicitely defined, are inherited from sst field. 
     778 
     779\subsubsection{Tag list per family} 
     780 
     781\begin{table} \scriptsize 
     782   \begin{tabularx}{\textwidth}{|l|X|X|l|X|} \hline 
     783   tag name                                                                                     & 
     784   description                                                                                  & 
     785   accepted attribute                                                                           & 
     786   child of                                                                                     & 
     787   parent of                       \\ \hline \hline 
     788   simulation                                                                                   & 
     789   this tag is the root tag which encapsulates all the content of the XML file                  & 
     790   none                                                                                         & 
     791   none                                                                                         & 
     792   context                         \\ \hline 
     793   context                                                                                      & 
     794   encapsulates parts of the XML file dedicated to different codes or different parts of a code & 
     795   id (''xios'', ''nemo'' or ''n\_nemo'' for the nth AGRIF zoom), src, time\_origin             & 
     796   simulation                                                                                   & 
     797   all root tags: ... \_definition \\ \hline 
     798   \end{tabularx} 
     799   \caption{Context tags} 
     800\end{table} 
     801 
     802\begin{table} \scriptsize 
     803   \begin{tabularx}{\textwidth}{|l|X|X|X|l|} \hline 
     804   tag name                                                                                &  
     805   description                                                                             &  
     806   accepted attribute                                                                      &  
     807   child of                                                                                &  
     808   parent of             \\ \hline \hline 
     809   field\_definition                                                                       &  
     810   encapsulates the definition of all the fields that can potentially be outputted         &  
     811   axis\_ref, default\_value, domain\_ref, enabled, grid\_ref, level, operation, prec, src &  
     812   context                                                                                 &  
     813   field or field\_group \\ \hline 
     814   field\_group                                                                            &  
     815   encapsulates a group of fields                                                          &  
     816   axis\_ref, default\_value, domain\_ref, enabled, group\_ref, grid\_ref, 
     817   id, level, operation, prec, src                                                         &  
     818   field\_definition, field\_group, file                                                   &  
     819   field or field\_group \\ \hline 
     820   field                                                                                   &  
     821   define a specific field                                                                 &  
     822   axis\_ref, default\_value, domain\_ref, enabled, field\_ref, grid\_ref, 
     823   id, level, long\_name, name, operation, prec, standard\_name, unit                      &  
     824   field\_definition, field\_group, file                                                   &  
     825   none                  \\ \hline 
     826   \end{tabularx} 
     827   \caption{Field tags ("\tt{field\_*}")} 
     828\end{table} 
     829 
     830\begin{table} \scriptsize 
     831   \begin{tabularx}{\textwidth}{|l|X|X|X|l|} \hline 
     832   tag name                                                            &  
     833   description                                                         &  
     834   accepted attribute                                                  &  
     835   child of                                                            &  
     836   parent of           \\ \hline \hline 
     837   file\_definition                                                    &  
     838   encapsulates the definition of all the files that will be outputted &  
     839   enabled, min\_digits, name, name\_suffix, output\_level, 
     840   split\_freq\_format, split\_freq, sync\_freq, type, src             &  
     841   context                                                             &  
     842   file or file\_group \\ \hline 
     843   file\_group                                                         &  
     844   encapsulates a group of files that will be outputted                &  
     845   enabled, description, id, min\_digits, name, name\_suffix, output\_freq, output\_level, 
     846   split\_freq\_format, split\_freq, sync\_freq, type, src             &  
     847   file\_definition, file\_group                                       &  
     848   file or file\_group \\ \hline 
     849   file                                                                &  
     850   define the contents of a file to be outputted                       &  
     851   enabled, description, id, min\_digits, name, name\_suffix, output\_freq, output\_level, 
     852   split\_freq\_format, split\_freq, sync\_freq, type, src             &  
     853   file\_definition, file\_group                                       &  
     854   field               \\ \hline 
     855   \end{tabularx} 
     856   \caption{File tags ("\tt{file\_*}")} 
     857\end{table} 
     858 
     859\begin{table} \scriptsize 
     860   \begin{tabularx}{\textwidth}{|l|X|X|X|X|} \hline 
     861   tag name                                                                               &  
     862   description                                                                            &  
     863   accepted attribute                                                                     &  
     864   child of                                                                               &  
     865   parent of         \\ \hline \hline 
     866   axis\_definition                                                                       &  
     867   define all the vertical axis potentially used by the variables                         &  
     868   src                                                                                    &  
     869   context                                                                                &  
     870   axis\_group, axis \\ \hline 
     871   axis\_group                                                                            &  
     872   encapsulates a group of vertical axis                                                  &  
     873   id, lon\_name, positive, src, standard\_name, unit, zoom\_begin, zoom\_end, zoom\_size &  
     874   axis\_definition, axis\_group                                                          &  
     875   axis\_group, axis \\ \hline 
     876   axis                                                                                   &  
     877   define a vertical axis                                                                 &  
     878   id, lon\_name, positive, src, standard\_name, unit, zoom\_begin, zoom\_end, zoom\_size &  
     879   axis\_definition, axis\_group                                                          &  
     880   none              \\ \hline 
     881   \end{tabularx} 
     882   \caption{Axis tags ("\tt{axis\_*}")} 
     883\end{table} 
     884 
     885\begin{table} \scriptsize 
     886   \begin{tabularx}{\textwidth}{|l|X|X|X|X|} \hline 
     887   tag name                                                            &  
     888   description                                                         &  
     889   accepted attribute                                                  &  
     890   child of                                                            &  
     891   parent of               \\ \hline \hline 
     892   domain\_\-definition                                                &  
     893   define all the horizontal domains potentially used by the variables &  
     894   src                                                                 &  
     895   context                                                             &  
     896   domain\_\-group, domain \\ \hline 
     897   domain\_group                                                       &  
     898   encapsulates a group of horizontal domains                          &  
     899   id, lon\_name, src, zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj  &  
     900   domain\_\-definition, domain\_group                                 &  
     901   domain\_\-group, domain \\ \hline 
     902   domain                                                              &  
     903   define an horizontal domain                                         &  
     904   id, lon\_name, src, zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj  &  
     905   domain\_\-definition, domain\_group                                 &  
     906   none                    \\ \hline 
     907   \end{tabularx} 
     908   \caption{Domain tags ("\tt{domain\_*)}"} 
     909\end{table} 
     910 
     911\begin{table} \scriptsize 
     912   \begin{tabularx}{\textwidth}{|l|X|X|X|X|} \hline 
     913   tag name                                                                                     & 
     914   description                                                                                  & 
     915   accepted attribute                                                                           & 
     916   child of                                                                                     & 
     917   parent of                       \\ \hline \hline 
     918   grid\_definition                                                                               & 
     919   define all the grid (association of a domain and/or an axis) potentially used by the variables & 
     920   src                                                                                            & 
     921   context                                                                                        & 
     922   grid\_group, grid \\ \hline 
     923   grid\_group                                                                                    & 
     924   encapsulates a group of grids                                                                  & 
     925   id, domain\_ref,axis\_ref                                                                      & 
     926   grid\_definition, grid\_group                                                                  & 
     927   grid\_group, grid \\ \hline 
     928   grid                                                                                           & 
     929   define a grid                                                                                  & 
     930   id, domain\_ref,axis\_ref                                                                      & 
     931   grid\_definition, grid\_group                                                                  & 
     932   none              \\ \hline 
     933   \end{tabularx} 
     934   \caption{Grid tags ("\tt{grid\_*}")} 
     935\end{table} 
     936 
     937\subsubsection{Attributes list per family} 
     938 
     939\begin{table} \scriptsize 
     940   \begin{tabularx}{\textwidth}{|l|X|l|l|} \hline 
     941      attribute name                           &  
     942      description                              &  
     943      example                                  &  
     944      accepted by            \\ \hline \hline 
     945      axis\_ref                                &  
     946      refers to the id of a vertical axis      &  
     947      axis\_ref="deptht"                       &  
     948      field, grid families   \\  \hline 
     949      domain\_ref                              &  
     950      refers to the id of a domain             &  
     951      domain\_ref="grid\_T"                    &  
     952      field or grid families \\ \hline 
     953      field\_ref                               &  
     954      id of the field we want to add in a file &  
     955      field\_ref="toce"                        &  
     956      field                  \\ \hline 
     957      grid\_ref                                &  
     958      refers to the id of a grid               &  
     959      grid\_ref="grid\_T\_2D"                  &  
     960      field family           \\ \hline 
     961      group\_ref                               &  
     962      refer to a group of variables            &  
     963      group\_ref="mooring"                     &  
     964      field\_group           \\ \hline 
     965   \end{tabularx} 
     966   \caption{Reference attributes ("\tt{*\_ref}")} 
     967\end{table} 
     968 
     969\begin{table} \scriptsize 
     970   \begin{tabularx}{\textwidth}{|l|X|l|l|} \hline 
     971      attribute name                                     &  
     972      description                                        &  
     973      example                                            &  
     974      accepted by   \\ \hline \hline 
     975      zoom\_ibegin                                       &  
     976      starting point along x direction of the zoom. 
     977      Automatically defined for TAO/RAMA/PIRATA moorings &  
     978      zoom\_ibegin="1"                                   &  
     979      domain family \\ \hline 
     980      zoom\_jbegin                                       &  
     981      starting point along y direction of the zoom. 
     982      Automatically defined for TAO/RAMA/PIRATA moorings &  
     983      zoom\_jbegin="1"                                   &  
     984      domain family \\ \hline 
     985      zoom\_ni                                           &  
     986      zoom extent along x direction                      &  
     987      zoom\_ni="1"                                       &  
     988      domain family \\ \hline 
     989      zoom\_nj                                           &  
     990      zoom extent along y direction                      &  
     991      zoom\_nj="1"                                       &  
     992      domain family \\ \hline 
     993   \end{tabularx} 
     994   \caption{Domain attributes ("\tt{zoom\_*}")} 
     995\end{table} 
     996 
     997\begin{table} \scriptsize 
     998   \begin{tabularx}{\textwidth}{|l|X|l|l|} \hline 
     999      attribute name                                                                                       & 
     1000      description                                                                                          & 
     1001      example                                                                                              & 
     1002      accepted by                            \\ \hline \hline 
     1003      min\_digits                                                                                          & 
     1004      specify the minimum of digits used in the core number in the name of the NetCDF file                 & 
     1005      min\_digits="4"                                                                                      & 
     1006      file family                            \\ \hline 
     1007      name\_suffix                                                                                         & 
     1008      suffix to be inserted after the name and before the cpu number and the ''.nc'' termination of a file & 
     1009      name\_suffix="\_myzoom"                                                                              & 
     1010      file family                            \\ \hline 
     1011      output\_level                                                                                        & 
     1012      output priority of variables in a file: 0 (high) to 10 (low). 
     1013      All variables listed in the file with a level smaller or equal to output\_level will be output. 
     1014      Other variables won't be output even if they are listed in the file.                                 & 
     1015      output\_level="10"                                                                                   & 
     1016      file family                            \\ \hline 
     1017      split\_freq                                                                                          & 
     1018      frequency at which to temporally split output files. 
     1019      Units can be ts (timestep), y, mo, d, h, mi, s. 
     1020      Useful for long runs to prevent over-sized output files.                                             & 
     1021      split\_freq="1mo"                                                                                    & 
     1022      file family                            \\ \hline 
     1023      split\_freq\-\_format                                                                                & 
     1024      date format used in the name of temporally split output files. 
     1025      Can be specified using the following syntaxes: \%y, \%mo, \%d, \%h \%mi and \%s                      & 
     1026      split\_freq\_format= "\%y\%mo\%d"                                                                    & 
     1027      file family                            \\ \hline 
     1028      sync\_freq                                                                                           & 
     1029      NetCDF file synchronization frequency (update of the time\_counter). 
     1030      Units can be ts (timestep), y, mo, d, h, mi, s.                                                      & 
     1031      sync\_freq="10d"                                                                                     & 
     1032      file family                            \\ \hline 
     1033      type (1)                                                                                             & 
     1034      specify if the output files are to be split spatially (multiple\_file) or not (one\_file)            & 
     1035      type="multiple\_file"                                                                                & 
     1036      file familly                           \\ \hline 
     1037   \end{tabularx} 
     1038   \caption{File attributes} 
     1039\end{table} 
     1040 
     1041\begin{table} \scriptsize 
     1042   \begin{tabularx}{\textwidth}{|l|X|l|l|} \hline 
     1043      attribute name                                                                                       & 
     1044      description                                                                                          & 
     1045      example                                                                                              & 
     1046      accepted by                            \\ \hline \hline 
     1047      default\_value                                                                                       & 
     1048      missing\_value definition                                                                            & 
     1049      default\_value="1.e20"                                                                               & 
     1050      field family                           \\ \hline 
     1051      level                                                                                                & 
     1052      output priority of a field: 0 (high) to 10 (low)                                                     & 
     1053      level="1"                                                                                            & 
     1054      field family                           \\ \hline 
     1055      operation                                                                                            & 
     1056      type of temporal operation: average, accumulate, instantaneous, min, max and once                    & 
     1057      operation="average"                                                                                  & 
     1058      field family                           \\ \hline 
     1059      output\_freq                                                                                         & 
     1060      operation frequency. units can be ts (timestep), y, mo, d, h, mi, s.                                 & 
     1061      output\_freq="1d12h"                                                                                 & 
     1062      field family                           \\ \hline 
     1063      prec                                                                                                 & 
     1064      output precision: real 4 or real 8                                                                   & 
     1065      prec="4"                                                                                             & 
     1066      field family                           \\ \hline 
     1067      long\_name                                                                                           & 
     1068      define the long\_name attribute in the NetCDF file                                                   & 
     1069      long\_name="Vertical T levels"                                                                       & 
     1070      field                                  \\ \hline 
     1071      standard\_name                                                                                       & 
     1072      define the standard\_name attribute in the NetCDF file                                               & 
     1073      standard\_name= "Eastward\_Sea\_Ice\_Transport"                                                      & 
     1074      field                                  \\ \hline 
     1075   \end{tabularx} 
     1076   \caption{Field attributes} 
     1077\end{table} 
     1078 
     1079\begin{table} \scriptsize 
     1080   \begin{tabularx}{\textwidth}{|l|X|X|X|} \hline 
     1081      attribute name                                                                                       & 
     1082      description                                                                                          & 
     1083      example                                                                                              & 
     1084      accepted by                            \\ \hline \hline 
     1085      enabled                                                                                              & 
     1086      switch on/off the output of a field or a file                                                        & 
     1087      enabled=".true."                                                                                     & 
     1088      field, file families                   \\ \hline 
     1089      description                                                                                          & 
     1090      just for information, not used                                                                       & 
     1091      description="ocean T grid variables"                                                                 & 
     1092      all tags                               \\ \hline 
     1093      id                                                                                                   & 
     1094      allow to identify a tag                                                                              & 
     1095      id="nemo"                                                                                            & 
     1096      accepted by all tags except simulation \\ \hline 
     1097      name                                                                                                 & 
     1098      name of a variable or a file. If the name of a file is undefined, its id is used as a name           & 
     1099      name="tos"                                                                                           & 
     1100      field or file families                 \\ \hline 
     1101      positive                                                                                             & 
     1102      convention used for the orientation of vertival axis (positive downward in \NEMO).                   & 
     1103      positive="down"                                                                                      & 
     1104      axis family                            \\ \hline 
     1105      src                                                                                                  & 
     1106      allow to include a file                                                                              & 
     1107      src="./field\_def.xml"                                                                               & 
     1108      accepted by all tags except simulation \\ \hline 
     1109      time\_origin                                                                                         & 
     1110      specify the origin of the time counter                                                               & 
     1111      time\_origin="1900-01-01 00:00:00"                                                                   & 
     1112      context                                \\ \hline 
     1113      type (2)                                                                                             & 
     1114      define the type of a variable tag                                                                    & 
     1115      type="boolean"                                                                                       & 
     1116      variable                               \\ \hline 
     1117      unit                                                                                                 & 
     1118      unit of a variable or the vertical axis                                                              & 
     1119      unit="m"                                                                                             & 
     1120      field and axis families                \\ \hline 
     1121   \end{tabularx} 
     1122   \caption{Miscellaneous attributes} 
     1123\end{table} 
    9971124 
    9981125\subsection{CF metadata standard compliance} 
    9991126 
    1000 Output from the XIOS-1.0 IO server is compliant with \href{http://cfconventions.org/Data/cf-conventions/cf-conventions-1.5/build/cf-conventions.html}{version 1.5} of 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. 
    1001  
    1002 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 \ngn{namrun} namelist. This must be set to true if these metadata are to be included in the output files. 
     1127Output from the XIOS-1.0 IO server is compliant with  
     1128\href{http://cfconventions.org/Data/cf-conventions/cf-conventions-1.5/build/cf-conventions.html}{version 1.5}  
     1129of the CF metadata standard.  
     1130Therefore while a user may wish to add their own metadata to the output files (as demonstrated in  
     1131example 4 of section \autoref{subsec:IOM_xmlref}) the metadata should, for the most part, comply with  
     1132the CF-1.5 standard. 
     1133 
     1134Some metadata that may significantly increase the file size (horizontal cell areas and  
     1135vertices) are controlled by the namelist parameter \np{ln\_cfmeta} in the \ngn{namrun} namelist. 
     1136This must be set to true if these metadata are to be included in the output files. 
    10031137 
    10041138 
     
    10071141% ================================================================ 
    10081142\section{NetCDF4 support (\protect\key{netcdf4})} 
    1009 \label{sec:DIA_iom} 
    1010  
    1011 Since version 3.3, support for NetCDF4 chunking and (loss-less) compression has 
    1012 been included.  These options build on the standard NetCDF output and allow 
    1013 the user control over the size of the chunks via namelist settings. Chunking 
    1014 and compression can lead to significant reductions in file sizes for a small 
    1015 runtime overhead. For a fuller discussion on chunking and other performance 
    1016 issues the reader is referred to the NetCDF4 documentation found  
     1143\label{sec:DIA_nc4} 
     1144 
     1145Since version 3.3, support for NetCDF4 chunking and (loss-less) compression has been included. 
     1146These options build on the standard NetCDF output and allow the user control over the size of  
     1147the chunks via namelist settings. 
     1148Chunking and compression can lead to significant reductions in file sizes for a small runtime overhead. 
     1149For a fuller discussion on chunking and other performance issues the reader is referred to  
     1150the NetCDF4 documentation found  
    10171151\href{http://www.unidata.ucar.edu/software/netcdf/docs/netcdf.html#Chunking}{here}. 
    10181152 
    1019 The new features are only available when the code has been linked with a 
    1020 NetCDF4 library (version 4.1 onwards, recommended) which has been built 
    1021 with HDF5 support (version 1.8.4 onwards, recommended). Datasets created 
    1022 with chunking and compression are not backwards compatible with NetCDF3 
    1023 "classic" format but most analysis codes can be relinked simply with the 
    1024 new libraries and will then read both NetCDF3 and NetCDF4 files. NEMO 
    1025 executables linked with NetCDF4 libraries can be made to produce NetCDF3 
    1026 files by setting the \np{ln\_nc4zip} logical to false in the \textit{namnc4}  
    1027 namelist: 
     1153The new features are only available when the code has been linked with a NetCDF4 library  
     1154(version 4.1 onwards, recommended) which has been built with HDF5 support  
     1155(version 1.8.4 onwards, recommended). 
     1156Datasets created with chunking and compression are not backwards compatible with  
     1157NetCDF3 "classic" format but most analysis codes can be relinked simply with the new libraries and  
     1158will then read both NetCDF3 and NetCDF4 files. 
     1159NEMO executables linked with NetCDF4 libraries can be made to produce NetCDF3 files by  
     1160setting the \np{ln\_nc4zip} logical to false in the \textit{namnc4} namelist: 
    10281161 
    10291162%------------------------------------------namnc4---------------------------------------------------- 
     
    10311164%------------------------------------------------------------------------------------------------------------- 
    10321165 
    1033 If \key{netcdf4} has not been defined, these namelist parameters are not read.  
    1034 In this case, \np{ln\_nc4zip} is set false and dummy routines for a few 
    1035 NetCDF4-specific functions are defined. These functions will not be used but 
    1036 need to be included so that compilation is possible with NetCDF3 libraries. 
    1037  
    1038 When using NetCDF4 libraries, \key{netcdf4} should be defined even if the 
    1039 intention is to create only NetCDF3-compatible files. This is necessary to 
    1040 avoid duplication between the dummy routines and the actual routines present 
    1041 in the library. Most compilers will fail at compile time when faced with 
    1042 such duplication. Thus when linking with NetCDF4 libraries the user must 
    1043 define \key{netcdf4} and control the type of NetCDF file produced via the 
    1044 namelist parameter. 
    1045  
    1046 Chunking and compression is applied only to 4D fields and there is no 
    1047 advantage in chunking across more than one time dimension since previously 
    1048 written chunks would have to be read back and decompressed before being 
    1049 added to. Therefore, user control over chunk sizes is provided only for the 
    1050 three space dimensions. The user sets an approximate number of chunks along 
    1051 each spatial axis. The actual size of the chunks will depend on global domain 
    1052 size for mono-processors or, more likely, the local processor domain size for 
    1053 distributed processing. The derived values are subject to practical minimum 
    1054 values (to avoid wastefully small chunk sizes) and cannot be greater than the 
    1055 domain size in any dimension. The algorithm used is: 
     1166If \key{netcdf4} has not been defined, these namelist parameters are not read. 
     1167In this case, \np{ln\_nc4zip} is set false and dummy routines for  
     1168a few NetCDF4-specific functions are defined. 
     1169These functions will not be used but need to be included so that compilation is possible with  
     1170NetCDF3 libraries. 
     1171 
     1172When using NetCDF4 libraries, \key{netcdf4} should be defined even if the intention is to  
     1173create only NetCDF3-compatible files. 
     1174This is necessary to avoid duplication between the dummy routines and  
     1175the actual routines present in the library. 
     1176Most compilers will fail at compile time when faced with such duplication. 
     1177Thus when linking with NetCDF4 libraries the user must define \key{netcdf4} and  
     1178control the type of NetCDF file produced via the namelist parameter. 
     1179 
     1180Chunking and compression is applied only to 4D fields and there is no advantage in  
     1181chunking across more than one time dimension since previously written chunks would have to  
     1182be read back and decompressed before being added to. 
     1183Therefore, user control over chunk sizes is provided only for the three space dimensions. 
     1184The user sets an approximate number of chunks along each spatial axis. 
     1185The actual size of the chunks will depend on global domain size for mono-processors or,  
     1186more likely, the local processor domain size for distributed processing. 
     1187The derived values are subject to practical minimum values (to avoid wastefully small chunk sizes) and  
     1188cannot be greater than the domain size in any dimension. 
     1189The algorithm used is: 
    10561190 
    10571191\begin{forlines} 
    1058      ichunksz(1) = MIN( idomain_size,MAX( (idomain_size-1)/nn_nchunks_i + 1 ,16 ) ) 
    1059      ichunksz(2) = MIN( jdomain_size,MAX( (jdomain_size-1)/nn_nchunks_j + 1 ,16 ) ) 
    1060      ichunksz(3) = MIN( kdomain_size,MAX( (kdomain_size-1)/nn_nchunks_k + 1 , 1 ) ) 
    1061      ichunksz(4) = 1 
     1192ichunksz(1) = MIN(idomain_size, MAX((idomain_size-1) / nn_nchunks_i + 1 ,16 )) 
     1193ichunksz(2) = MIN(jdomain_size, MAX((jdomain_size-1) / nn_nchunks_j + 1 ,16 )) 
     1194ichunksz(3) = MIN(kdomain_size, MAX((kdomain_size-1) / nn_nchunks_k + 1 , 1 )) 
     1195ichunksz(4) = 1 
    10621196\end{forlines} 
    10631197 
    10641198\noindent As an example, setting: 
     1199 
    10651200\begin{forlines} 
    1066      nn_nchunks_i=4, nn_nchunks_j=4 and nn_nchunks_k=31 
     1201nn_nchunks_i=4, nn_nchunks_j=4 and nn_nchunks_k=31 
    10671202\end{forlines} 
    10681203 
    1069 \noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\tt 46x38x1} 
    1070 respectively in the mono-processor case (i.e. global domain of {\small\tt 182x149x31}). 
    1071 An illustration of the potential space savings that NetCDF4 chunking and compression 
    1072 provides is given in table \autoref{tab:NC4} which compares the results of two short 
    1073 runs of the ORCA2\_LIM reference configuration with a 4x2 mpi partitioning. Note 
    1074 the variation in the compression ratio achieved which reflects chiefly the dry to wet  
    1075 volume ratio of each processing region. 
     1204\noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\tt 46x38x1} respectively in  
     1205the mono-processor case (i.e. global domain of {\small\tt 182x149x31}). 
     1206An illustration of the potential space savings that NetCDF4 chunking and compression provides is given in  
     1207table \autoref{tab:NC4} which compares the results of two short runs of  
     1208the ORCA2\_LIM reference configuration with a 4x2 mpi partitioning. 
     1209Note the variation in the compression ratio achieved which reflects chiefly the dry to  
     1210wet volume ratio of each processing region. 
    10761211 
    10771212%------------------------------------------TABLE---------------------------------------------------- 
    1078 \begin{table}  \begin{tabular}{lrrr} 
    1079 Filename & NetCDF3 & NetCDF4 & Reduction\\ 
    1080          &filesize & filesize & \% \\ 
    1081          &(KB)     & (KB)     & \\ 
    1082 ORCA2\_restart\_0000.nc & 16420 & 8860 & 47\%\\ 
    1083 ORCA2\_restart\_0001.nc & 16064 & 11456 & 29\%\\ 
    1084 ORCA2\_restart\_0002.nc & 16064 & 9744 & 40\%\\ 
    1085 ORCA2\_restart\_0003.nc & 16420 & 9404 & 43\%\\ 
    1086 ORCA2\_restart\_0004.nc & 16200 & 5844 & 64\%\\ 
    1087 ORCA2\_restart\_0005.nc & 15848 & 8172 & 49\%\\ 
    1088 ORCA2\_restart\_0006.nc & 15848 & 8012 & 50\%\\ 
    1089 ORCA2\_restart\_0007.nc & 16200 & 5148 & 69\%\\ 
    1090 ORCA2\_2d\_grid\_T\_0000.nc & 2200 & 1504 & 32\%\\ 
    1091 ORCA2\_2d\_grid\_T\_0001.nc & 2200 & 1748 & 21\%\\ 
    1092 ORCA2\_2d\_grid\_T\_0002.nc & 2200 & 1592 & 28\%\\ 
    1093 ORCA2\_2d\_grid\_T\_0003.nc & 2200 & 1540 & 30\%\\ 
    1094 ORCA2\_2d\_grid\_T\_0004.nc & 2200 & 1204 & 46\%\\ 
    1095 ORCA2\_2d\_grid\_T\_0005.nc & 2200 & 1444 & 35\%\\ 
    1096 ORCA2\_2d\_grid\_T\_0006.nc & 2200 & 1428 & 36\%\\ 
    1097 ORCA2\_2d\_grid\_T\_0007.nc & 2200 & 1148 & 48\%\\ 
    1098      ...         & ...  &  ... & ...  \\ 
    1099 ORCA2\_2d\_grid\_W\_0000.nc & 4416 & 2240 & 50\%\\ 
    1100 ORCA2\_2d\_grid\_W\_0001.nc & 4416 & 2924 & 34\%\\ 
    1101 ORCA2\_2d\_grid\_W\_0002.nc & 4416 & 2512 & 44\%\\ 
    1102 ORCA2\_2d\_grid\_W\_0003.nc & 4416 & 2368 & 47\%\\ 
    1103 ORCA2\_2d\_grid\_W\_0004.nc & 4416 & 1432 & 68\%\\ 
    1104 ORCA2\_2d\_grid\_W\_0005.nc & 4416 & 1972 & 56\%\\ 
    1105 ORCA2\_2d\_grid\_W\_0006.nc & 4416 & 2028 & 55\%\\ 
    1106 ORCA2\_2d\_grid\_W\_0007.nc & 4416 & 1368 & 70\%\\ 
    1107 \end{tabular} 
    1108 \caption{   \protect\label{tab:NC4}  
    1109 Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression} 
     1213\begin{table} \scriptsize \centering 
     1214   \begin{tabular}{lrrr} 
     1215      Filename                    & NetCDF3  & NetCDF4  & Reduction \\ 
     1216                                  & filesize & filesize & \%        \\ 
     1217                                  & (KB)     & (KB)     &           \\ 
     1218      ORCA2\_restart\_0000.nc     & 16420    & 8860     & 47\%      \\ 
     1219      ORCA2\_restart\_0001.nc     & 16064    & 11456    & 29\%      \\ 
     1220      ORCA2\_restart\_0002.nc     & 16064    & 9744     & 40\%      \\ 
     1221      ORCA2\_restart\_0003.nc     & 16420    & 9404     & 43\%      \\ 
     1222      ORCA2\_restart\_0004.nc     & 16200    & 5844     & 64\%      \\ 
     1223      ORCA2\_restart\_0005.nc     & 15848    & 8172     & 49\%      \\ 
     1224      ORCA2\_restart\_0006.nc     & 15848    & 8012     & 50\%      \\ 
     1225      ORCA2\_restart\_0007.nc     & 16200    & 5148     & 69\%      \\ 
     1226      ORCA2\_2d\_grid\_T\_0000.nc & 2200     & 1504     & 32\%      \\ 
     1227      ORCA2\_2d\_grid\_T\_0001.nc & 2200     & 1748     & 21\%      \\ 
     1228      ORCA2\_2d\_grid\_T\_0002.nc & 2200     & 1592     & 28\%      \\ 
     1229      ORCA2\_2d\_grid\_T\_0003.nc & 2200     & 1540     & 30\%      \\ 
     1230      ORCA2\_2d\_grid\_T\_0004.nc & 2200     & 1204     & 46\%      \\ 
     1231      ORCA2\_2d\_grid\_T\_0005.nc & 2200     & 1444     & 35\%      \\ 
     1232      ORCA2\_2d\_grid\_T\_0006.nc & 2200     & 1428     & 36\%      \\ 
     1233      ORCA2\_2d\_grid\_T\_0007.nc & 2200     & 1148     & 48\%      \\ 
     1234      ...                         & ...      & ...      & ...       \\ 
     1235      ORCA2\_2d\_grid\_W\_0000.nc & 4416     & 2240     & 50\%      \\ 
     1236      ORCA2\_2d\_grid\_W\_0001.nc & 4416     & 2924     & 34\%      \\ 
     1237      ORCA2\_2d\_grid\_W\_0002.nc & 4416     & 2512     & 44\%      \\ 
     1238      ORCA2\_2d\_grid\_W\_0003.nc & 4416     & 2368     & 47\%      \\ 
     1239      ORCA2\_2d\_grid\_W\_0004.nc & 4416     & 1432     & 68\%      \\ 
     1240      ORCA2\_2d\_grid\_W\_0005.nc & 4416     & 1972     & 56\%      \\ 
     1241      ORCA2\_2d\_grid\_W\_0006.nc & 4416     & 2028     & 55\%      \\ 
     1242      ORCA2\_2d\_grid\_W\_0007.nc & 4416     & 1368     & 70\%      \\ 
     1243   \end{tabular} 
     1244   \caption{ 
     1245      \protect\label{tab:NC4} 
     1246      Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression} 
    11101247\end{table} 
    11111248%---------------------------------------------------------------------------------------------------- 
    11121249 
    1113 When \key{iomput} is activated with \key{netcdf4} chunking and 
    1114 compression parameters for fields produced via \np{iom\_put} calls are 
    1115 set via an equivalent and identically named namelist to \textit{namnc4}  
    1116 in \np{xmlio\_server.def}. Typically this namelist serves the mean files 
    1117 whilst the \ngn{ namnc4} in the main namelist file continues to serve the 
    1118 restart files. This duplication is unfortunate but appropriate since, if 
    1119 using io\_servers, the domain sizes of the individual files produced by the 
    1120 io\_server processes may be different to those produced by the invidual 
    1121 processing regions and different chunking choices may be desired. 
     1250When \key{iomput} is activated with \key{netcdf4} chunking and compression parameters for  
     1251fields produced via \np{iom\_put} calls are set via an equivalent and identically named namelist to  
     1252\textit{namnc4} in \np{xmlio\_server.def}. 
     1253Typically this namelist serves the mean files whilst the \ngn{ namnc4} in  
     1254the main namelist file continues to serve the restart files. 
     1255This duplication is unfortunate but appropriate since, if using io\_servers, the domain sizes of  
     1256the individual files produced by the io\_server processes may be different to those produced by  
     1257the invidual processing regions and different chunking choices may be desired. 
    11221258  
    1123  
    11241259% ------------------------------------------------------------------------------------------------------------- 
    11251260%       Tracer/Dynamics Trends 
     
    11321267%------------------------------------------------------------------------------------------------------------- 
    11331268 
    1134 Each trend of the dynamics and/or temperature and salinity time evolution equations  
    1135 can be send to \mdl{trddyn} and/or \mdl{trdtra} modules (see TRD directory) just after their computation  
    1136 ($i.e.$ at the end of each $dyn\cdots.F90$ and/or $tra\cdots.F90$ routines).  
    1137 This capability is controlled by options offered in \ngn{namtrd} namelist.  
     1269Each trend of the dynamics and/or temperature and salinity time evolution equations can be send to  
     1270\mdl{trddyn} and/or \mdl{trdtra} modules (see TRD directory) just after their computation ($i.e.$ at  
     1271the end of each $dyn\cdots.F90$ and/or $tra\cdots.F90$ routines). 
     1272This capability is controlled by options offered in \ngn{namtrd} namelist. 
    11381273Note that the output are done with xIOS, and therefore the \key{IOM} is required. 
    11391274 
    11401275What is done depends on the \ngn{namtrd} logical set to \forcode{.true.}: 
     1276 
    11411277\begin{description} 
    1142 \item[\np{ln\_glo\_trd}] : at each \np{nn\_trd} time-step a check of the basin averaged properties  
    1143 of the momentum and tracer equations is performed. This also includes a check of $T^2$, $S^2$,  
    1144 $\tfrac{1}{2} (u^2+v2)$, and potential energy time evolution equations properties ;  
    1145 \item[\np{ln\_dyn\_trd}] : each 3D trend of the evolution of the two momentum components is output ;  
    1146 \item[\np{ln\_dyn\_mxl}] : each 3D trend of the evolution of the two momentum components averaged  
    1147                            over the mixed layer is output  ;  
    1148 \item[\np{ln\_vor\_trd}] : a vertical summation of the moment tendencies is performed,  
    1149                            then the curl is computed to obtain the barotropic vorticity tendencies which are output ; 
    1150 \item[\np{ln\_KE\_trd}]  : each 3D trend of the Kinetic Energy equation is output ; 
    1151 \item[\np{ln\_tra\_trd}] : each 3D trend of the evolution of temperature and salinity is output ; 
    1152 \item[\np{ln\_tra\_mxl}] : each 2D trend of the evolution of temperature and salinity averaged  
    1153                            over the mixed layer is output ; 
     1278   \item[\np{ln\_glo\_trd}]: at each \np{nn\_trd} time-step a check of the basin averaged properties of  
     1279                              the momentum and tracer equations is performed. 
     1280                              This also includes a check of $T^2$, $S^2$, $\tfrac{1}{2} (u^2+v2)$, and  
     1281                              potential energy time evolution equations properties; 
     1282   \item[\np{ln\_dyn\_trd}]: each 3D trend of the evolution of the two momentum components is output; 
     1283   \item[\np{ln\_dyn\_mxl}]: each 3D trend of the evolution of the two momentum components averaged over  
     1284                              the mixed layer is output; 
     1285   \item[\np{ln\_vor\_trd}]: a vertical summation of the moment tendencies is performed, then  
     1286                              the curl is computed to obtain the barotropic vorticity tendencies which  
     1287                              are output; 
     1288   \item[\np{ln\_KE\_trd}] : each 3D trend of the Kinetic Energy equation is output ; 
     1289   \item[\np{ln\_tra\_trd}]: each 3D trend of the evolution of temperature and salinity is output ; 
     1290   \item[\np{ln\_tra\_mxl}]: each 2D trend of the evolution of temperature and salinity averaged over  
     1291                              the mixed layer is output; 
    11541292\end{description} 
    11551293 
    1156 Note that the mixed layer tendency diagnostic can also be used on biogeochemical models  
    1157 via the \key{trdtrc} and \key{trdmld\_trc} CPP keys. 
    1158  
    1159 \textbf{Note that} in the current version (v3.6), many changes has been introduced but not fully tested.  
    1160 In particular, options associated with \np{ln\_dyn\_mxl}, \np{ln\_vor\_trd}, and \np{ln\_tra\_mxl}  
    1161 are not working, and none of the option have been tested with variable volume ($i.e.$ \key{vvl} defined). 
    1162  
     1294Note that the mixed layer tendency diagnostic can also be used on biogeochemical models via  
     1295the \key{trdtrc} and \key{trdmld\_trc} CPP keys. 
     1296 
     1297\textbf{Note that} in the current version (v3.6), many changes has been introduced but not fully tested. 
     1298In particular, options associated with \np{ln\_dyn\_mxl}, \np{ln\_vor\_trd}, and \np{ln\_tra\_mxl} are  
     1299not working, and none of the options have been tested with variable volume ($i.e.$ \key{vvl} defined). 
    11631300 
    11641301% ------------------------------------------------------------------------------------------------------------- 
     
    11711308%-------------------------------------------------------------------------------------------------------------- 
    11721309 
    1173 The on-line computation of floats advected either by the three dimensional velocity  
    1174 field or constraint to remain at a given depth ($w = 0$ in the computation) have been  
    1175 introduced in the system during the CLIPPER project. Options are defined by \ngn{namflo} 
    1176 namelis variables. The algorithm used is based  
    1177 either on the work of \cite{Blanke_Raynaud_JPO97} (default option), or on a $4^th$ 
    1178 Runge-Hutta algorithm (\np{ln\_flork4}\forcode{ = .true.}). Note that the \cite{Blanke_Raynaud_JPO97}  
    1179 algorithm have the advantage of providing trajectories which are consistent with the  
    1180 numeric of the code, so that the trajectories never intercept the bathymetry.  
    1181  
    1182 \subsubsection{ Input data: initial coordinates } 
    1183  
    1184 Initial coordinates can be given with Ariane Tools convention ( IJK coordinates ,(\np{ln\_ariane}\forcode{ = .true.}) ) 
    1185 or with longitude and latitude. 
    1186  
    1187  
    1188 In case of Ariane convention, input filename is \np{init\_float\_ariane}. Its format is: 
    1189  
    1190 \texttt{ I J K nisobfl itrash itrash } 
    1191  
    1192 \noindent with:  
     1310The on-line computation of floats advected either by the three dimensional velocity field or  
     1311constraint to remain at a given depth ($w = 0$ in the computation) have been introduced in  
     1312the system during the CLIPPER project. 
     1313Options are defined by \ngn{namflo} namelis variables. 
     1314The algorithm used is based either on the work of \cite{Blanke_Raynaud_JPO97} (default option), or  
     1315on a $4^th$ Runge-Hutta algorithm (\np{ln\_flork4}\forcode{ = .true.}). 
     1316Note that the \cite{Blanke_Raynaud_JPO97} algorithm have the advantage of providing trajectories which  
     1317are consistent with the numeric of the code, so that the trajectories never intercept the bathymetry. 
     1318 
     1319\subsubsection{Input data: initial coordinates} 
     1320 
     1321Initial coordinates can be given with Ariane Tools convention (IJK coordinates, 
     1322(\np{ln\_ariane}\forcode{ = .true.}) ) or with longitude and latitude. 
     1323 
     1324In case of Ariane convention, input filename is \np{init\_float\_ariane}. 
     1325Its format is: \\ 
     1326{\scriptsize \texttt{I J K nisobfl itrash itrash}} 
     1327 
     1328\noindent with: 
    11931329 
    11941330 - I,J,K  : indexes of initial position 
     
    11981334 - itrash : set to zero; it is a dummy variable to respect Ariane Tools convention 
    11991335 
    1200  - itrash :set to zero; it is a dummy variable to respect Ariane Tools convention 
    1201  
    1202 \noindent Example:\\ 
    1203 \noindent \texttt{ 100.00000  90.00000  -1.50000 1.00000   0.00000}\\ 
    1204 \texttt{ 102.00000  90.00000  -1.50000 1.00000   0.00000}\\ 
    1205 \texttt{ 104.00000  90.00000  -1.50000 1.00000   0.00000}\\ 
    1206 \texttt{ 106.00000  90.00000  -1.50000 1.00000   0.00000}\\ 
    1207 \texttt{ 108.00000  90.00000  -1.50000 1.00000   0.00000}\\ 
    1208  
    1209  
    1210 In the other case ( longitude and latitude ), input filename is init\_float. Its format is: 
    1211  
    1212 \texttt{ Long Lat depth nisobfl ngrpfl itrash} 
     1336\noindent Example: \\ 
     1337\noindent {\scriptsize \texttt{ 
     1338100.00000  90.00000  -1.50000 1.00000   0.00000   \\ 
     1339102.00000  90.00000  -1.50000 1.00000   0.00000   \\ 
     1340104.00000  90.00000  -1.50000 1.00000   0.00000   \\ 
     1341106.00000  90.00000  -1.50000 1.00000   0.00000   \\ 
     1342108.00000  90.00000  -1.50000 1.00000   0.00000}} \\ 
     1343 
     1344In the other case (longitude and latitude), input filename is init\_float. 
     1345Its format is: \\ 
     1346{\scriptsize \texttt{Long Lat depth nisobfl ngrpfl itrash}} 
    12131347 
    12141348\noindent with: 
     
    12221356 - itrash :set to 1; it is a dummy variable. 
    12231357 
    1224 \noindent Example: 
    1225  
    1226 \noindent\texttt{  20.0 0.0 0.0 0 1 1 }\\ 
    1227 \texttt{ -21.0 0.0 0.0 0 1 1 }\\ 
    1228 \texttt{ -22.0 0.0 0.0 0 1 1 }\\ 
    1229 \texttt{ -23.0 0.0 0.0 0 1 1 }\\ 
    1230 \texttt{ -24.0 0.0 0.0 0 1 1 }\\ 
     1358\noindent Example: \\ 
     1359\noindent {\scriptsize \texttt{ 
     1360 20.0 0.0 0.0 0 1 1    \\ 
     1361-21.0 0.0 0.0 0 1 1    \\ 
     1362-22.0 0.0 0.0 0 1 1    \\ 
     1363-23.0 0.0 0.0 0 1 1    \\ 
     1364-24.0 0.0 0.0 0 1 1 }} \\ 
    12311365 
    12321366\np{jpnfl} is the total number of floats during the run. 
    1233 When initial positions are read in a restart file (\np{ln\_rstflo}\forcode{ = .true.} ),  \np{jpnflnewflo} 
    1234 can be added in the initialization file.  
     1367When initial positions are read in a restart file (\np{ln\_rstflo}\forcode{ = .true.} ),  
     1368\np{jpnflnewflo} can be added in the initialization file. 
    12351369 
    12361370\subsubsection{Output data} 
    12371371 
    1238 \np{nn\_writefl} is the frequency of writing in float output file and \np{nn\_stockfl}  
    1239 is the frequency of creation of the float restart file. 
    1240  
    1241 Output data can be written in ascii files (\np{ln\_flo\_ascii}\forcode{ = .true.}). In that case,  
    1242 output filename is trajec\_float. 
    1243  
    1244 Another possiblity of writing format is Netcdf (\np{ln\_flo\_ascii}\forcode{ = .false.}). There are 2 possibilities: 
    1245  
    1246  - if (\key{iomput}) is used, outputs are selected in  iodef.xml. Here it is an example of specification  
    1247    to put in files description section: 
    1248  
    1249 \begin{xmllines} 
    1250      <group id="1d_grid_T" name="auto" description="ocean T grid variables" >   } 
    1251        <file id="floats"  description="floats variables"> }\\ 
    1252            <field ref="traj_lon"   name="floats_longitude"   freq_op="86400" />} 
    1253            <field ref="traj_lat"   name="floats_latitude"    freq_op="86400" />} 
    1254            <field ref="traj_dep"   name="floats_depth"       freq_op="86400" />} 
    1255            <field ref="traj_temp"  name="floats_temperature" freq_op="86400" />} 
    1256            <field ref="traj_salt"  name="floats_salinity"    freq_op="86400" />} 
    1257            <field ref="traj_dens"  name="floats_density"     freq_op="86400" />} 
    1258            <field ref="traj_group" name="floats_group"       freq_op="86400" />} 
    1259        </file>} 
    1260   </group>} 
    1261 \end{xmllines} 
    1262  
     1372\np{nn\_writefl} is the frequency of writing in float output file and \np{nn\_stockfl} is  
     1373the frequency of creation of the float restart file. 
     1374 
     1375Output data can be written in ascii files (\np{ln\_flo\_ascii}\forcode{ = .true.}). 
     1376In that case, output filename is trajec\_float. 
     1377 
     1378Another possiblity of writing format is Netcdf (\np{ln\_flo\_ascii}\forcode{ = .false.}). 
     1379There are 2 possibilities: 
     1380 
     1381 - if (\key{iomput}) is used, outputs are selected in  iodef.xml. 
     1382   Here it is an example of specification to put in files description section: 
     1383 
     1384\begin{xmllines} 
     1385<group id="1d_grid_T" name="auto" description="ocean T grid variables" >   } 
     1386   <file id="floats"  description="floats variables"> } 
     1387      <field ref="traj_lon"   name="floats_longitude"   freq_op="86400" />} 
     1388      <field ref="traj_lat"   name="floats_latitude"    freq_op="86400" />} 
     1389      <field ref="traj_dep"   name="floats_depth"      freq_op="86400" />} 
     1390      <field ref="traj_temp"  name="floats_temperature" freq_op="86400" />} 
     1391      <field ref="traj_salt"  name="floats_salinity"    freq_op="86400" />} 
     1392      <field ref="traj_dens"  name="floats_density"     freq_op="86400" />} 
     1393      <field ref="traj_group" name="floats_group"       freq_op="86400" />} 
     1394   </file>} 
     1395</group>} 
     1396\end{xmllines} 
    12631397 
    12641398 -  if (\key{iomput}) is not used, a file called \ifile{trajec\_float} will be created by IOIPSL library. 
    1265  
    1266  
    12671399 
    12681400See also \href{http://stockage.univ-brest.fr/~grima/Ariane/}{here} the web site describing  
    12691401the off-line use of this marvellous diagnostic tool. 
    1270  
    12711402 
    12721403% ------------------------------------------------------------------------------------------------------------- 
     
    12801411%---------------------------------------------------------------------------------------------------------- 
    12811412 
    1282 A module is available to compute the amplitude and phase of tidal waves.  
     1413A module is available to compute the amplitude and phase of tidal waves. 
    12831414This on-line Harmonic analysis is actived with \key{diaharm}. 
     1415 
    12841416Some parameters are available in namelist \ngn{namdia\_harm} : 
    12851417 
    1286 - \np{nit000\_han} is the first time step used for harmonic analysis 
    1287  
    1288 - \np{nitend\_han} is the last time step used for harmonic analysis 
    1289  
    1290 - \np{nstep\_han} is the time step frequency for harmonic analysis 
    1291  
    1292 - \np{nb\_ana} is the number of harmonics to analyse 
    1293  
    1294 - \np{tname} is an array with names of tidal constituents to analyse 
     1418 - \np{nit000\_han} is the first time step used for harmonic analysis 
     1419 
     1420 - \np{nitend\_han} is the last time step used for harmonic analysis 
     1421 
     1422 - \np{nstep\_han}  is the time step frequency for harmonic analysis 
     1423 
     1424 - \np{nb\_ana}    is the number of harmonics to analyse 
     1425 
     1426 - \np{tname}      is an array with names of tidal constituents to analyse 
    12951427 
    12961428\np{nit000\_han} and \np{nitend\_han} must be between \np{nit000} and \np{nitend} of the simulation. 
     
    12981430 
    12991431The Harmonic analysis solve the following equation: 
    1300 \begin{equation} 
    1301 h_{i} - A_{0} + \sum^{nb\_ana}_{j=1}[A_{j}cos(\nu_{j}t_{j}-\phi_{j})] = e_{i} 
    1302 \end{equation} 
    1303  
    1304 With $A_{j}$,$\nu_{j}$,$\phi_{j}$, the amplitude, frequency and phase for each wave and $e_{i}$ the error. 
     1432 
     1433\[h_{i} - A_{0} + \sum^{nb\_ana}_{j=1}[A_{j}cos(\nu_{j}t_{j}-\phi_{j})] = e_{i}\] 
     1434 
     1435With $A_{j}$, $\nu_{j}$, $\phi_{j}$, the amplitude, frequency and phase for each wave and  
     1436$e_{i}$ the error. 
    13051437$h_{i}$ is the sea level for the time $t_{i}$ and $A_{0}$ is the mean sea level. \\ 
    13061438We can rewrite this equation: 
    1307 \begin{equation} 
    1308 h_{i} - A_{0} + \sum^{nb\_ana}_{j=1}[C_{j}cos(\nu_{j}t_{j})+S_{j}sin(\nu_{j}t_{j})] = e_{i} 
    1309 \end{equation} 
    1310 with $A_{j}=\sqrt{C^{2}_{j}+S^{2}_{j}}$ et $\phi_{j}=arctan(S_{j}/C_{j})$. 
     1439 
     1440\[h_{i} - A_{0} + \sum^{nb\_ana}_{j=1}[C_{j}cos(\nu_{j}t_{j})+S_{j}sin(\nu_{j}t_{j})] = e_{i}\] 
     1441 
     1442with $A_{j}=\sqrt{C^{2}_{j}+S^{2}_{j}}$ and $\phi_{j}=arctan(S_{j}/C_{j})$. 
    13111443 
    13121444We obtain in output $C_{j}$ and $S_{j}$ for each tidal wave. 
     
    13251457This diagnostic is actived with \key{diadct}. 
    13261458 
    1327 Each section is defined by the coordinates of its 2 extremities. The pathways between them are contructed 
    1328 using tools which can be found in  \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT} and are written in a binary file 
    1329  \texttt{section\_ijglobal.diadct\_ORCA2\_LIM} which is later read in by NEMO to compute on-line transports. 
    1330  
    1331 The on-line transports module creates three output ascii files:  
    1332  
    1333 - \texttt{volume\_transport} for volume transports (  unit: $10^{6} m^{3} s^{-1}$ ) 
    1334  
    1335 - \texttt{heat\_transport}   for heat transports   (  unit: $10^{15} W $ ) 
    1336  
    1337 - \texttt{salt\_transport}   for salt transports   (  unit: $10^{9}Kg s^{-1}$ )\\ 
    1338  
    1339  
    1340 Namelist variables in \ngn{namdct} control how frequently the flows are summed  
    1341 and the time scales over which they are averaged, as well as the level of output for debugging: 
    1342  
    1343 \np{nn\_dct}: frequency of instantaneous transports computing 
    1344  
     1459Each section is defined by the coordinates of its 2 extremities. 
     1460The pathways between them are contructed using tools which can be found in  
     1461\texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT}  
     1462and are written in a binary file  
     1463\texttt{section\_ijglobal.diadct\_ORCA2\_LIM}  
     1464which is later read in by NEMO to compute on-line transports. 
     1465 
     1466The on-line transports module creates three output ascii files: 
     1467 
     1468- \texttt{volume\_transport} for volume transports (unit: $10^{6} m^{3} s^{-1}$) 
     1469 
     1470- \texttt{heat\_transport}   for   heat transports (unit: $10^{15} W$) 
     1471 
     1472- \texttt{salt\_transport}   for   salt transports (unit: $10^{9}Kg s^{-1}$) \\ 
     1473 
     1474Namelist variables in \ngn{namdct} control how frequently the flows are summed and the time scales over  
     1475which they are averaged, as well as the level of output for debugging: 
     1476\np{nn\_dct}   : frequency of instantaneous transports computing 
    13451477\np{nn\_dctwri}: frequency of writing ( mean of instantaneous transports ) 
    1346  
    1347 \np{nn\_debug}: debugging of the section 
     1478\np{nn\_debug} : debugging of the section 
    13481479 
    13491480\subsubsection{Creating a binary file containing the pathway of each section} 
    13501481 
    1351 In \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT/run}, the file \textit{ {list\_sections.ascii\_global}} 
    1352 contains a list of all the sections that are to be computed (this list of sections is based on MERSEA project metrics). 
    1353  
    1354 Another file is available for the GYRE configuration (\texttt{ {list\_sections.ascii\_GYRE}}).  
    1355  
    1356 Each section is defined by: 
    1357  
    1358 \noindent \texttt{ long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name }\\ 
     1482In \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT/run},  
     1483the file \textit{ {list\_sections.ascii\_global}} contains a list of all the sections that are to  
     1484be computed (this list of sections is based on MERSEA project metrics). 
     1485 
     1486Another file is available for the GYRE configuration (\texttt{ {list\_sections.ascii\_GYRE}}). 
     1487 
     1488Each section is defined by: \\ 
     1489\noindent {\scriptsize \texttt{long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name}} \\ 
    13591490with: 
    13601491 
    1361 - \texttt{long1 lat1} , coordinates of the first extremity of the section; 
    1362  
    1363 - \texttt{long2 lat2} , coordinates of the second extremity of the section; 
    1364  
    1365 - \texttt{nclass} the number of bounds of your classes (e.g. 3 bounds for 2 classes); 
    1366  
    1367 - \texttt{okstrpond} to compute heat and salt transport, \texttt{nostrpond} if no; 
    1368  
    1369 - \texttt{ice}  to compute surface and volume ice transports, \texttt{noice} if no. \\ 
    1370  
    1371  
    1372 \noindent The results of the computing of transports, and the directions of positive 
    1373  and negative flow do not depend on the order of the 2 extremities in this file.\\  
    1374  
    1375  
    1376 \noindent If nclass =/ 0,the next lines contain the class type and the nclass bounds: 
    1377  
    1378 \texttt{long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name} 
    1379  
    1380 \texttt{classtype} 
    1381  
    1382 \texttt{zbound1} 
    1383  
    1384 \texttt{zbound2} 
    1385  
    1386 \texttt{.} 
    1387  
    1388 \texttt{.} 
    1389  
    1390 \texttt{nclass-1} 
    1391  
    1392 \texttt{nclass} 
     1492 - \texttt{long1 lat1}, coordinates of the  first extremity of the section; 
     1493 
     1494 - \texttt{long2 lat2}, coordinates of the second extremity of the section; 
     1495 
     1496 - \texttt{nclass}    the number of bounds of your classes (e.g. 3 bounds for 2 classes); 
     1497 
     1498 - \texttt{okstrpond} to compute    heat and       salt transports, \texttt{nostrpond} if no; 
     1499 
     1500 - \texttt{ice}       to compute surface and volume ice transports, \texttt{noice}     if no. \\ 
     1501 
     1502\noindent The results of the computing of transports, and the directions of positive and  
     1503negative flow do not depend on the order of the 2 extremities in this file. \\ 
     1504 
     1505\noindent If nclass $\neq$ 0,the next lines contain the class type and the nclass bounds: \\ 
     1506{\scriptsize \texttt{ 
     1507long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name \\ 
     1508classtype                                                         \\ 
     1509zbound1                                                           \\ 
     1510zbound2                                                           \\ 
     1511.                                                                 \\ 
     1512.                                                                 \\ 
     1513nclass-1                                                          \\ 
     1514nclass}} 
    13931515 
    13941516\noindent where \texttt{classtype} can be: 
    13951517 
    1396 - \texttt{zsal} for salinity classes 
    1397  
    1398 - \texttt{ztem} for temperature classes 
    1399  
    1400 - \texttt{zlay} for depth classes 
    1401  
    1402 - \texttt{zsigi} for insitu density classes 
    1403  
    1404 - \texttt{zsigp} for potential density classes \\ 
    1405  
     1518 - \texttt{zsal}  for          salinity classes 
     1519 
     1520 - \texttt{ztem}  for       temperature classes 
     1521 
     1522 - \texttt{zlay}  for             depth classes 
     1523 
     1524 - \texttt{zsigi} for    insitu density classes 
     1525 
     1526 - \texttt{zsigp} for potential density classes \\ 
    14061527   
    1407 The script \texttt{job.ksh} computes the pathway for each section and creates a binary file  
    1408 \texttt{section\_ijglobal.diadct\_ORCA2\_LIM} which is read by NEMO. \\ 
    1409  
    1410 It is possible to use this tools for new configuations: \texttt{job.ksh} has to be updated  
    1411 with the coordinates file name and path. \\ 
    1412  
    1413  
    1414 Examples of two sections, the ACC\_Drake\_Passage with no classes, and the 
    1415  ATL\_Cuba\_Florida with 4 temperature clases (5 class bounds), are shown: 
    1416  
    1417 \noindent \texttt{ -68.    -54.5   -60.    -64.7  00 okstrpond noice ACC\_Drake\_Passage} 
    1418  
    1419 \noindent \texttt{ -80.5    22.5   -80.5    25.5  05 nostrpond noice ATL\_Cuba\_Florida} 
    1420  
    1421 \noindent \texttt{ztem} 
    1422  
    1423 \noindent \texttt{-2.0} 
    1424  
    1425 \noindent \texttt{ 4.5} 
    1426  
    1427 \noindent \texttt{ 7.0} 
    1428  
    1429 \noindent \texttt{12.0} 
    1430  
    1431 \noindent \texttt{40.0} 
    1432  
     1528The script \texttt{job.ksh} computes the pathway for each section and  
     1529creates a binary file \texttt{section\_ijglobal.diadct\_ORCA2\_LIM} which is read by NEMO. \\ 
     1530 
     1531It is possible to use this tools for new configuations: \texttt{job.ksh} has to be updated with  
     1532the coordinates file name and path. \\ 
     1533 
     1534Examples of two sections, the ACC\_Drake\_Passage with no classes, and the ATL\_Cuba\_Florida with  
     15354 temperature clases (5 class bounds), are shown: \\ 
     1536\noindent {\scriptsize \texttt{ 
     1537-68.    -54.5   -60.    -64.7  00 okstrpond noice ACC\_Drake\_Passage \\ 
     1538-80.5    22.5   -80.5    25.5  05 nostrpond noice ATL\_Cuba\_Florida  \\ 
     1539ztem                                                                  \\ 
     1540-2.0                                                                  \\ 
     1541 4.5                                                                  \\ 
     1542 7.0                                                                  \\ 
     154312.0                                                                  \\ 
     154440.0}} 
    14331545 
    14341546\subsubsection{To read the output files} 
    14351547 
    1436 The output format is : 
    1437   
    1438 {\small\texttt{date, time-step number, section number, section name, section slope coefficient, class number,  
    1439 class name, class bound 1 , classe bound2, transport\_direction1 ,  transport\_direction2, transport\_total}}\\ 
    1440  
    1441  
    1442 For sections with classes, the first \texttt{nclass-1} lines correspond to the transport for each class  
    1443 and the last line corresponds to the total transport summed over all classes. For sections with no classes, class number 
    1444 \texttt{ 1 } corresponds to \texttt{ total class } and this class is called  \texttt{N}, meaning \texttt{none}.\\ 
    1445  
    1446  
    1447 \noindent \texttt{ transport\_direction1 } is the positive part of the transport ( \texttt{ > = 0 } ). 
    1448  
    1449 \noindent \texttt{ transport\_direction2 } is the negative part of the transport ( \texttt{ < = 0 } ).\\ 
    1450  
    1451  
    1452 \noindent The \texttt{section slope coefficient} gives information about the significance of transports signs and direction:\\ 
    1453  
    1454  
    1455  
    1456 \begin{tabular}{|c|c|c|c|p{4cm}|} 
    1457 \hline 
    1458 section slope coefficient & section type & direction 1 & direction 2 & total transport \\ \hline 
    1459 0.    &  horizontal & northward & southward & postive: northward  \\ \hline 
    1460 1000. &  vertical   & eastward  & westward  & postive: eastward  \\ \hline                 
    1461 \texttt{=/0, =/ 1000.}   &  diagonal   & eastward  & westward  & postive: eastward  \\ \hline                 
    1462 \end{tabular} 
    1463  
     1548The output format is: \\ 
     1549{\scriptsize \texttt{ 
     1550date, time-step number, section number,                \\ 
     1551section name, section slope coefficient, class number, \\ 
     1552class name, class bound 1 , classe bound2,             \\ 
     1553transport\_direction1, transport\_direction2,          \\ 
     1554transport\_total}}                                     \\ 
     1555 
     1556For sections with classes, the first \texttt{nclass-1} lines correspond to the transport for  
     1557each class and the last line corresponds to the total transport summed over all classes. 
     1558For sections with no classes, class number \texttt{1} corresponds to \texttt{total class} and  
     1559this class is called \texttt{N}, meaning \texttt{none}. 
     1560 
     1561- \texttt{transport\_direction1} is the positive part of the transport ($\geq$ 0). 
     1562 
     1563- \texttt{transport\_direction2} is the negative part of the transport ($\leq$ 0). \\ 
     1564 
     1565\noindent The \texttt{section slope coefficient} gives information about the significance of  
     1566transports signs and direction: \\ 
     1567 
     1568\begin{table} \scriptsize 
     1569   \begin{tabular}{|l|l|l|l|l|} \hline 
     1570      section slope coefficient      & section type & direction 1 & direction 2 & total transport 
     1571      \\ \hline 
     1572      0.                             & horizontal   & northward   & southward   & postive: northward 
     1573      \\ \hline 
     1574      1000.                          & vertical     & eastward    & westward    & postive: eastward 
     1575      \\ \hline 
     1576      \texttt{$\neq$ 0, $\neq$ 1000.} & diagonal     & eastward    & westward   & postive: eastward 
     1577      \\ \hline 
     1578   \end{tabular} 
     1579\end{table} 
    14641580 
    14651581% ================================================================ 
     
    14701586 
    14711587 
    1472 Changes in steric sea level are caused when changes in the density of the water  
    1473 column imply an expansion or contraction of the column. It is essentially produced  
    1474 through surface heating/cooling and to a lesser extent through non-linear effects of  
    1475 the equation of state (cabbeling, thermobaricity...). 
    1476 Non-Boussinesq models contain all ocean effects within the ocean acting  
    1477 on the sea level. In particular, they include the steric effect. In contrast,  
    1478 Boussinesq models, such as \NEMO, conserve volume, rather than mass,  
    1479 and so do not properly represent expansion or contraction. The steric effect is  
    1480 therefore not explicitely represented. 
    1481 This approximation does not represent a serious error with respect to the flow field  
    1482 calculated by the model \citep{Greatbatch_JGR94}, but extra attention is required 
    1483 when investigating sea level, as steric changes are an important  
    1484 contribution to local changes in sea level on seasonal and climatic time scales. 
     1588Changes in steric sea level are caused when changes in the density of the water column imply an  
     1589expansion or contraction of the column. 
     1590It is essentially produced through surface heating/cooling and to a lesser extent through  
     1591non-linear effects of the equation of state (cabbeling, thermobaricity...). 
     1592Non-Boussinesq models contain all ocean effects within the ocean acting on the sea level. 
     1593In particular, they include the steric effect. 
     1594In contrast, Boussinesq models, such as \NEMO, conserve volume, rather than mass,  
     1595and so do not properly represent expansion or contraction. 
     1596The steric effect is therefore not explicitely represented. 
     1597This approximation does not represent a serious error with respect to the flow field calculated by  
     1598the model \citep{Greatbatch_JGR94}, but extra attention is required when investigating sea level,  
     1599as steric changes are an important contribution to local changes in sea level on seasonal and  
     1600climatic time scales. 
    14851601This is especially true for investigation into sea level rise due to global warming.  
    14861602 
    1487 Fortunately, the steric contribution to the sea level consists of a spatially uniform  
    1488 component that can be diagnosed by considering the mass budget of the world  
    1489 ocean \citep{Greatbatch_JGR94}.  
    1490 In order to better understand how global mean sea level evolves and thus how 
    1491 the steric sea level can be diagnosed, we compare, in the following, the  
    1492 non-Boussinesq and Boussinesq cases. 
    1493  
    1494 Let denote  
    1495 $\mathcal{M}$ the total mass of liquid seawater ($\mathcal{M}=\int_D \rho dv$),  
    1496 $\mathcal{V}$ the total volume of seawater ($\mathcal{V}=\int_D dv$),  
    1497 $\mathcal{A}$ the total surface of the ocean ($\mathcal{A}=\int_S ds$),  
    1498 $\bar{\rho}$ the global mean seawater (\textit{in situ}) density ($\bar{\rho}= 1/\mathcal{V} \int_D \rho \,dv$), and 
    1499 $\bar{\eta}$ the global mean sea level ($\bar{\eta}=1/\mathcal{A}\int_S \eta \,ds$). 
     1603Fortunately, the steric contribution to the sea level consists of a spatially uniform component that  
     1604can be diagnosed by considering the mass budget of the world ocean \citep{Greatbatch_JGR94}. 
     1605In order to better understand how global mean sea level evolves and thus how the steric sea level can  
     1606be diagnosed, we compare, in the following, the non-Boussinesq and Boussinesq cases. 
     1607 
     1608Let denote 
     1609$\mathcal{M}$ the total mass    of liquid seawater ($\mathcal{M} = \int_D \rho dv$),  
     1610$\mathcal{V}$ the total volume  of        seawater      ($\mathcal{V} = \int_D dv$),  
     1611$\mathcal{A}$ the total surface of       the ocean      ($\mathcal{A} = \int_S ds$),  
     1612$\bar{\rho}$ the global mean  seawater (\textit{in situ}) density  
     1613($\bar{\rho} = 1/\mathcal{V} \int_D \rho \,dv$), and 
     1614$\bar{\eta}$ the global mean sea level  
     1615($\bar{\eta} = 1/\mathcal{A} \int_S \eta \,ds$). 
    15001616 
    15011617A non-Boussinesq fluid conserves mass. It satisfies the following relations: 
    1502 \begin{equation} \label{eq:MV_nBq}  
    1503 \begin{split}  
    1504 \mathcal{M} &=  \mathcal{V}  \;\bar{\rho}       \\ 
    1505 \mathcal{V} &=  \mathcal{A}  \;\bar{\eta}  
    1506 \end{split} 
     1618 
     1619\begin{equation} \label{eq:MV_nBq} 
     1620   \begin{split} 
     1621      \mathcal{M} &=  \mathcal{V}  \;\bar{\rho} \\ 
     1622      \mathcal{V} &=  \mathcal{A}  \;\bar{\eta} 
     1623   \end{split} 
    15071624\end{equation} 
     1625 
    15081626Temporal changes in total mass is obtained from the density conservation equation : 
    1509 \begin{equation}  \label{eq:Co_nBq} 
    1510 \frac{1}{e_3} \partial_t ( e_3\,\rho) + \nabla( \rho \, \textbf{U} ) = \left. \frac{\textit{emp}}{e_3}\right|_\textit{surface} 
    1511 \end{equation} 
     1627 
     1628\[ \frac{1}{e_3} \partial_t ( e_3\,\rho) + \nabla( \rho \, \textbf{U} )  
     1629   = \left. \frac{\textit{emp}}{e_3}\right|_\textit{surface} 
     1630 \label{eq:Co_nBq} \] 
     1631 
    15121632where $\rho$ is the \textit{in situ} density, and \textit{emp} the surface mass  
    15131633exchanges with the other media of the Earth system (atmosphere, sea-ice, land).  
    15141634Its global averaged leads to the total mass change  
    1515 \begin{equation}  \label{eq:Mass_nBq} 
    1516 \partial_t \mathcal{M} = \mathcal{A} \;\overline{\textit{emp}} 
    1517 \end{equation} 
    1518 where $\overline{\textit{emp}}=\int_S \textit{emp}\,ds$ is the net mass flux  
    1519 through the ocean surface. 
    1520 Bringing \autoref{eq:Mass_nBq} and the time derivative of \autoref{eq:MV_nBq}  
    1521 together leads to the evolution equation of the mean sea level 
    1522 \begin{equation} \label{eq:ssh_nBq} 
    1523   \partial_t \bar{\eta} =  \frac{\overline{\textit{emp}}}{ \bar{\rho}}  
    1524                - \frac{\mathcal{V}}{\mathcal{A}}  \;\frac{\partial_t \bar{\rho} }{\bar{\rho}} 
    1525 \end{equation} 
     1635 
     1636\[ \partial_t \mathcal{M} = \mathcal{A} \;\overline{\textit{emp}} 
     1637 \label{eq:Mass_nBq} \] 
     1638 
     1639where $\overline{\textit{emp}} = \int_S \textit{emp}\,ds$ is the net mass flux through the ocean surface. 
     1640Bringing \autoref{eq:Mass_nBq} and the time derivative of \autoref{eq:MV_nBq} together leads to  
     1641the evolution equation of the mean sea level 
     1642 
     1643\[ \partial_t \bar{\eta} = \frac{\overline{\textit{emp}}}{ \bar{\rho}}  
     1644                         - \frac{\mathcal{V}}{\mathcal{A}} \;\frac{\partial_t \bar{\rho} }{\bar{\rho}} 
     1645 \label{eq:ssh_nBq} \] 
     1646 
    15261647The first term in equation \autoref{eq:ssh_nBq} alters sea level by adding or  
    15271648subtracting mass from the ocean.  
    1528 The second term arises from temporal changes in the global mean  
    1529 density; $i.e.$ from steric effects.  
    1530  
    1531 In a Boussinesq fluid, $\rho$ is replaced by $\rho_o$ in all the equation except when $\rho$  
    1532 appears multiplied by the gravity ($i.e.$ in the hydrostatic balance of the primitive Equations).  
     1649The second term arises from temporal changes in the global mean density; $i.e.$ from steric effects.  
     1650 
     1651In a Boussinesq fluid, $\rho$ is replaced by $\rho_o$ in all the equation except when  
     1652$\rho$ appears multiplied by the gravity ($i.e.$ in the hydrostatic balance of the primitive Equations). 
    15331653In particular, the mass conservation equation, \autoref{eq:Co_nBq}, degenerates into  
    15341654the incompressibility equation: 
    1535 \begin{equation}  \label{eq:Co_Bq} 
    1536 \frac{1}{e_3} \partial_t ( e_3 ) + \nabla( \textbf{U} ) =  \left. \frac{\textit{emp}}{\rho_o \,e_3}\right|_ \textit{surface} 
    1537 \end{equation} 
     1655 
     1656\[ \frac{1}{e_3} \partial_t ( e_3 ) + \nabla( \textbf{U} ) 
     1657   = \left. \frac{\textit{emp}}{\rho_o \,e_3}\right|_ \textit{surface} 
     1658 \label{eq:Co_Bq} \] 
     1659 
    15381660and the global average of this equation now gives the temporal change of the total volume, 
    1539 \begin{equation}  \label{eq:V_Bq} 
    1540   \partial_t \mathcal{V} =   \mathcal{A} \;\frac{\overline{\textit{emp}}}{\rho_o}  
    1541 \end{equation} 
    1542 Only the volume is conserved, not mass, or, more precisely, the mass which is conserved is the  
    1543 Boussinesq mass, $\mathcal{M}_o = \rho_o \mathcal{V}$. The total volume (or equivalently   
    1544 the global mean sea level) is altered only by net volume fluxes across the ocean surface,   
    1545 not by changes in mean mass of the ocean: the steric effect is missing in a Boussinesq fluid. 
    1546   
    1547 Nevertheless, following \citep{Greatbatch_JGR94}, the steric effect on the volume can be  
    1548 diagnosed by considering the mass budget of the ocean.  
    1549 The apparent changes in $\mathcal{M}$, mass of the ocean, which are not induced by surface  
    1550 mass flux must be compensated by a spatially uniform change in the mean sea level due to  
    1551 expansion/contraction of the ocean \citep{Greatbatch_JGR94}. In others words, the Boussinesq  
    1552 mass, $\mathcal{M}_o$, can be related to $\mathcal{M}$, the  total mass of the ocean seen  
    1553 by the Boussinesq model, via the steric contribution to the sea level, $\eta_s$, a spatially  
    1554 uniform variable, as follows: 
    1555 \begin{equation}  \label{eq:M_Bq} 
    1556    \mathcal{M}_o  =  \mathcal{M} + \rho_o \,\eta_s \,\mathcal{A}  
    1557 \end{equation} 
     1661 
     1662\[ \partial_t \mathcal{V} = \mathcal{A} \;\frac{\overline{\textit{emp}}}{\rho_o} 
     1663 \label{eq:V_Bq} \] 
     1664 
     1665Only the volume is conserved, not mass, or, more precisely, the mass which is conserved is  
     1666the Boussinesq mass, $\mathcal{M}_o = \rho_o \mathcal{V}$. 
     1667The total volume (or equivalently the global mean sea level) is altered only by net volume fluxes across  
     1668the ocean surface, not by changes in mean mass of the ocean: the steric effect is missing in  
     1669a Boussinesq fluid. 
     1670 
     1671Nevertheless, following \citep{Greatbatch_JGR94}, the steric effect on the volume can be diagnosed by  
     1672considering the mass budget of the ocean.  
     1673The apparent changes in $\mathcal{M}$, mass of the ocean, which are not induced by  
     1674surface mass flux must be compensated by a spatially uniform change in the mean sea level due to  
     1675expansion/contraction of the ocean \citep{Greatbatch_JGR94}. 
     1676In others words, the Boussinesq mass, $\mathcal{M}_o$, can be related to $\mathcal{M}$,  
     1677the  total mass of the ocean seen by the Boussinesq model, via the steric contribution to the sea level,  
     1678$\eta_s$, a spatially uniform variable, as follows: 
     1679 
     1680\[ \mathcal{M}_o = \mathcal{M} + \rho_o \,\eta_s \,\mathcal{A} 
     1681 \label{eq:M_Bq} \] 
     1682 
    15581683Any change in $\mathcal{M}$ which cannot be explained by the net mass flux through  
    1559 the ocean surface is converted into a mean change in sea level. Introducing the total density  
    1560 anomaly, $\mathcal{D}= \int_D d_a \,dv$, where $d_a= (\rho -\rho_o ) / \rho_o$  
    1561 is the density anomaly used in \NEMO (cf. \autoref{subsec:TRA_eos}) in \autoref{eq:M_Bq} 
    1562 leads to a very simple form for the steric height: 
    1563 \begin{equation}  \label{eq:steric_Bq} 
    1564    \eta_s = - \frac{1}{\mathcal{A}} \mathcal{D}  
    1565 \end{equation} 
     1684the ocean surface is converted into a mean change in sea level. 
     1685Introducing the total density anomaly, $\mathcal{D}= \int_D d_a \,dv$, where  
     1686$d_a = (\rho -\rho_o ) / \rho_o$ is the density anomaly used in \NEMO (cf. \autoref{subsec:TRA_eos}) in  
     1687\autoref{eq:M_Bq} leads to a very simple form for the steric height: 
     1688 
     1689\[ \eta_s = - \frac{1}{\mathcal{A}} \mathcal{D} 
     1690 \label{eq:steric_Bq} \] 
    15661691 
    15671692The above formulation of the steric height of a Boussinesq ocean requires four remarks. 
    15681693First, one can be tempted to define $\rho_o$ as the initial value of $\mathcal{M}/\mathcal{V}$, 
    1569 $i.e.$ set $\mathcal{D}_{t=0}=0$, so that the initial steric height is zero. We do not 
    1570 recommend that. Indeed, in this case $\rho_o$ depends on the initial state of the ocean.  
    1571 Since $\rho_o$ has a direct effect on the dynamics of the ocean (it appears in the pressure  
    1572 gradient term of the momentum equation) it is definitively not a good idea when  
    1573 inter-comparing experiments.  
    1574 We better recommend to fixe once for all $\rho_o$ to $1035\;Kg\,m^{-3}$. This value is a  
    1575 sensible choice for the reference density used in a Boussinesq ocean climate model since,  
    1576 with the exception of only a small percentage of the ocean, density in the World Ocean  
    1577 varies by no more than 2$\%$ from this value (\cite{Gill1982}, page 47). 
    1578  
    1579 Second, we have assumed here that the total ocean surface, $\mathcal{A}$, does not 
    1580 change when the sea level is changing as it is the case in all global ocean GCMs  
    1581 (wetting and drying of grid point is not allowed).  
     1694$i.e.$ set $\mathcal{D}_{t=0}=0$, so that the initial steric height is zero. 
     1695We do not recommend that. 
     1696Indeed, in this case $\rho_o$ depends on the initial state of the ocean. 
     1697Since $\rho_o$ has a direct effect on the dynamics of the ocean (it appears in  
     1698the pressure gradient term of the momentum equation) it is definitively not a good idea when  
     1699inter-comparing experiments. 
     1700We better recommend to fixe once for all $\rho_o$ to $1035\;Kg\,m^{-3}$. 
     1701This value is a sensible choice for the reference density used in a Boussinesq ocean climate model since,  
     1702with the exception of only a small percentage of the ocean, density in the World Ocean varies by  
     1703no more than 2$\%$ from this value (\cite{Gill1982}, page 47). 
     1704 
     1705Second, we have assumed here that the total ocean surface, $\mathcal{A}$, does not change when  
     1706the sea level is changing as it is the case in all global ocean GCMs  
     1707(wetting and drying of grid point is not allowed). 
    15821708   
    1583 Third, the discretisation of \autoref{eq:steric_Bq} depends on the type of free surface 
    1584 which is considered. In the non linear free surface case, $i.e.$ \key{vvl} defined, it is 
    1585 given by 
    1586 \begin{equation}  \label{eq:discrete_steric_Bq} 
    1587    \eta_s =  - \frac{ \sum_{i,\,j,\,k} d_a\; e_{1t} e_{2t} e_{3t} } 
    1588                   { \sum_{i,\,j,\,k}         e_{1t} e_{2t} e_{3t} }  
    1589 \end{equation} 
    1590 whereas in the linear free surface, the volume above the \textit{z=0} surface must be explicitly taken  
    1591 into account to better approximate the total ocean mass and thus the steric sea level: 
    1592 \begin{equation}  \label{eq:discrete_steric_Bq} 
    1593    \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 } 
    1594                      {\sum_{i,\,j,\,k} e_{1t}e_{2t}e_{3t} + \sum_{i,\,j}           e_{1t}e_{2t} \eta }  
    1595 \end{equation} 
     1709Third, the discretisation of \autoref{eq:steric_Bq} depends on the type of  
     1710free surface which is considered. 
     1711In the non linear free surface case, $i.e.$ \key{vvl} defined, it is given by 
     1712 
     1713\[ \eta_s = - \frac{ \sum_{i,\,j,\,k} d_a\; e_{1t} e_{2t} e_{3t} } 
     1714                   { \sum_{i,\,j,\,k}       e_{1t} e_{2t} e_{3t} } 
     1715 \label{eq:discrete_steric_Bq_nfs} \] 
     1716 
     1717whereas in the linear free surface, the volume above the \textit{z=0} surface must be explicitly  
     1718taken into account to better approximate the total ocean mass and thus the steric sea level: 
     1719 
     1720\[ \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 } 
     1721                   { \sum_{i,\,j,\,k}       e_{1t}e_{2t}e_{3t} + \sum_{i,\,j}      e_{1t}e_{2t} \eta } 
     1722 \label{eq:discrete_steric_Bq_fs} \] 
    15961723 
    15971724The fourth and last remark concerns the effective sea level and the presence of sea-ice. 
    1598 In the real ocean, sea ice (and snow above it)  depresses the liquid seawater through  
    1599 its mass loading. This depression is a result of the mass of sea ice/snow system acting  
    1600 on the liquid ocean. There is, however, no dynamical effect associated with these depressions  
    1601 in the liquid ocean sea level, so that there are no associated ocean currents. Hence, the  
    1602 dynamically relevant sea level is the effective sea level, $i.e.$ the sea level as if sea ice  
    1603 (and snow) were converted to liquid seawater \citep{Campin_al_OM08}. However, 
    1604 in the current version of \NEMO the sea-ice is levitating above the ocean without  
    1605 mass exchanges between ice and ocean. Therefore the model effective sea level 
    1606 is always given by $\eta + \eta_s$, whether or not there is sea ice present. 
    1607  
    1608 In AR5 outputs, the thermosteric sea level is demanded. It is steric sea level due to  
    1609 changes in ocean density arising just from changes in temperature. It is given by: 
    1610 \begin{equation}  \label{eq:thermosteric_Bq} 
    1611    \eta_s = - \frac{1}{\mathcal{A}} \int_D d_a(T,S_o,p_o) \,dv 
    1612 \end{equation} 
     1725In the real ocean, sea ice (and snow above it)  depresses the liquid seawater through its mass loading. 
     1726This depression is a result of the mass of sea ice/snow system acting on the liquid ocean. 
     1727There is, however, no dynamical effect associated with these depressions in the liquid ocean sea level,  
     1728so that there are no associated ocean currents. 
     1729Hence, the dynamically relevant sea level is the effective sea level, $i.e.$ the sea level as if  
     1730sea ice (and snow) were converted to liquid seawater \citep{Campin_al_OM08}. 
     1731However, in the current version of \NEMO the sea-ice is levitating above the ocean without  
     1732mass exchanges between ice and ocean. 
     1733Therefore the model effective sea level is always given by $\eta + \eta_s$,  
     1734whether or not there is sea ice present. 
     1735 
     1736In AR5 outputs, the thermosteric sea level is demanded. 
     1737It is steric sea level due to changes in ocean density arising just from changes in temperature. 
     1738It is given by: 
     1739 
     1740\[ \eta_s = - \frac{1}{\mathcal{A}} \int_D d_a(T,S_o,p_o) \,dv 
     1741 \label{eq:thermosteric_Bq} \] 
     1742 
    16131743where $S_o$ and $p_o$ are the initial salinity and pressure, respectively. 
    16141744 
    16151745Both steric and thermosteric sea level are computed in \mdl{diaar5} which needs 
    16161746the \key{diaar5} defined to be called. 
    1617  
    1618  
    16191747 
    16201748% ------------------------------------------------------------------------------------------------------------- 
     
    16241752\label{sec:DIA_diag_others} 
    16251753 
    1626  
    1627 Aside from the standard model variables, other diagnostics can be computed on-line.  
    1628 The available ready-to-add diagnostics modules can be found in directory DIA.  
     1754Aside from the standard model variables, other diagnostics can be computed on-line. 
     1755The available ready-to-add diagnostics modules can be found in directory DIA. 
    16291756 
    16301757\subsection{Depth of various quantities (\protect\mdl{diahth})} 
    16311758 
    1632 Among the available diagnostics the following ones are obtained when defining  
    1633 the \key{diahth} CPP key:  
     1759Among the available diagnostics the following ones are obtained when defining the \key{diahth} CPP key:  
    16341760 
    16351761- the mixed layer depth (based on a density criterion \citep{de_Boyer_Montegut_al_JGR04}) (\mdl{diahth}) 
     
    16521778 
    16531779The poleward heat and salt transports, their advective and diffusive component, and  
    1654 the meriodional stream function can be computed on-line in \mdl{diaptr}  
    1655 \np{ln\_diaptr} to true (see the \textit{\ngn{namptr} } namelist below).   
    1656 When \np{ln\_subbas}\forcode{ = .true.}, transports and stream function are computed  
    1657 for the Atlantic, Indian, Pacific and Indo-Pacific Oceans (defined north of 30\deg S)  
    1658 as well as for the World Ocean. The sub-basin decomposition requires an input file  
    1659 (\ifile{subbasins}) which contains three 2D mask arrays, the Indo-Pacific mask  
    1660 been deduced from the sum of the Indian and Pacific mask (\autoref{fig:mask_subasins}).  
     1780the meriodional stream function can be computed on-line in \mdl{diaptr} \np{ln\_diaptr} to true  
     1781(see the \textit{\ngn{namptr} } namelist below). 
     1782When \np{ln\_subbas}\forcode{ = .true.}, transports and stream function are computed for the Atlantic,  
     1783Indian, Pacific and Indo-Pacific Oceans (defined north of 30\deg S) as well as for the World Ocean. 
     1784The sub-basin decomposition requires an input file (\ifile{subbasins}) which contains  
     1785three 2D mask arrays, the Indo-Pacific mask been deduced from the sum of the Indian and  
     1786Pacific mask (\autoref{fig:mask_subasins}). 
    16611787 
    16621788%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    1663 \begin{figure}[!t]     \begin{center} 
    1664 \includegraphics[width=1.0\textwidth]{Fig_mask_subasins} 
    1665 \caption{   \protect\label{fig:mask_subasins} 
    1666 Decomposition of the World Ocean (here ORCA2) into sub-basin used in to compute 
    1667 the heat and salt transports as well as the meridional stream-function: Atlantic basin (red),  
    1668 Pacific basin (green), Indian basin (bleue), Indo-Pacific basin (bleue+green).  
    1669 Note that semi-enclosed seas (Red, Med and Baltic seas) as well as Hudson Bay  
    1670 are removed from the sub-basins. Note also that the Arctic Ocean has been split  
    1671 into Atlantic and Pacific basins along the North fold line.  } 
    1672 \end{center}   \end{figure}   
     1789\begin{figure}[!t] \begin{center} 
     1790   \includegraphics[width=1.0\textwidth]{Fig_mask_subasins} 
     1791   \caption{   \protect\label{fig:mask_subasins} 
     1792      Decomposition of the World Ocean (here ORCA2) into sub-basin used in to compute the heat and  
     1793      salt transports as well as the meridional stream-function: Atlantic basin (red),  
     1794      Pacific basin (green), Indian basin (bleue), Indo-Pacific basin (bleue+green). 
     1795      Note that semi-enclosed seas (Red, Med and Baltic seas) as well as Hudson Bay are removed from  
     1796      the sub-basins. Note also that the Arctic Ocean has been split into Atlantic and  
     1797      Pacific basins along the North fold line.} 
     1798\end{center} \end{figure}   
    16731799%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    1674  
    16751800 
    16761801% ----------------------------------------------------------- 
     
    16791804\subsection{CMIP specific diagnostics (\protect\mdl{diaar5})} 
    16801805 
    1681 A series of diagnostics has been added in the \mdl{diaar5}.  
     1806A series of diagnostics has been added in the \mdl{diaar5}. 
    16821807They corresponds to outputs that are required for AR5 simulations (CMIP5) 
    1683 (see also  \autoref{sec:DIA_steric} for one of them).  
     1808(see also \autoref{sec:DIA_steric} for one of them). 
    16841809Activating those outputs requires to define the \key{diaar5} CPP key. 
    1685  
    16861810 
    16871811% ----------------------------------------------------------- 
     
    16991823This diagnostic is actived with the logical  $ln\_dia25h$ 
    17001824 
    1701  
    17021825% ----------------------------------------------------------- 
    17031826%     Top Middle and Bed hourly output 
     
    17091832%---------------------------------------------------------------------------------------------------------- 
    17101833 
    1711 A module is available to output the surface (top), mid water and bed diagnostics of a set of standard variables.  
    1712 This can be a useful diagnostic when hourly or sub-hourly output is required in high resolution tidal outputs. 
    1713 The tidal signal is retained but the overall data usage is cut to just three vertical levels. Also the bottom level  
    1714 is calculated for each cell. 
     1834A module is available to output the surface (top), mid water and bed diagnostics of a set of  
     1835standard variables. 
     1836This can be a useful diagnostic when hourly or sub-hourly output is required in  
     1837high resolution tidal outputs. 
     1838The tidal signal is retained but the overall data usage is cut to just three vertical levels. 
     1839Also the bottom level is calculated for each cell. 
    17151840This diagnostic is actived with the logical  $ln\_diatmb$ 
    1716  
    1717  
    17181841 
    17191842% ----------------------------------------------------------- 
     
    17211844% ----------------------------------------------------------- 
    17221845\subsection{Courant numbers} 
    1723 Courant numbers provide a theoretical indication of the model's numerical stability. The advective Courant numbers can be calculated according to 
    1724 \begin{equation} 
    1725 \label{eq:CFL} 
    1726 C_u = |u|\frac{\rdt}{e_{1u}}, \quad C_v = |v|\frac{\rdt}{e_{2v}}, \quad C_w = |w|\frac{\rdt}{e_{3w}} 
    1727 \end{equation} 
    1728 in the zonal, meridional and vertical directions respectively. The vertical component is included although it is not strictly valid as the vertical velocity is calculated from the continuity equation rather than as a prognostic variable. Physically this represents the rate at which information is propogated across a grid cell. Values greater than 1 indicate that information is propagated across more than one grid cell in a single time step. 
    1729  
    1730 The variables can be activated by setting the \np{nn\_diacfl} namelist parameter to 1 in the \ngn{namctl} 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 where the maximum value occurs. At the end of the model run the maximum value of $C_u$, $C_v$, and $C_w$ for the whole model run is printed along with the coordinates of each. The maximum values from the run are also copied to the ocean.output file.  
    1731  
     1846 
     1847Courant numbers provide a theoretical indication of the model's numerical stability. 
     1848The advective Courant numbers can be calculated according to 
     1849 
     1850\[ C_u = |u|\frac{\rdt}{e_{1u}}, \quad C_v = |v|\frac{\rdt}{e_{2v}}, \quad C_w = |w|\frac{\rdt}{e_{3w}} 
     1851 \label{eq:CFL} \] 
     1852 
     1853in the zonal, meridional and vertical directions respectively. 
     1854The vertical component is included although it is not strictly valid as the vertical velocity is  
     1855calculated from the continuity equation rather than as a prognostic variable. 
     1856Physically this represents the rate at which information is propogated across a grid cell. 
     1857Values greater than 1 indicate that information is propagated across more than one grid cell in  
     1858a single time step. 
     1859 
     1860The variables can be activated by setting the \np{nn\_diacfl} namelist parameter to 1 in  
     1861the \ngn{namctl} namelist. 
     1862The diagnostics will be written out to an ascii file named cfl\_diagnostics.ascii. 
     1863In this file the maximum value of $C_u$, $C_v$, and $C_w$ are printed at each timestep along with  
     1864the coordinates of where the maximum value occurs. 
     1865At the end of the model run the maximum value of $C_u$, $C_v$, and $C_w$ for the whole model run is  
     1866printed along with the coordinates of each. 
     1867The maximum values from the run are also copied to the ocean.output file.  
    17321868 
    17331869% ================================================================ 
    17341870 
    1735  
    1736  
    1737  
    1738  
    1739  
    1740  
    1741  
    1742  
    1743  
    1744  
    1745  
    17461871\end{document} 
Note: See TracChangeset for help on using the changeset viewer.