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

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
Changeset 4193 for branches/2013/dev_r3867_MERCATOR1_DYN/DOC/TexFiles – NEMO

Ignore:
Timestamp:
2013-11-14T12:04:31+01:00 (11 years ago)
Author:
cbricaud
Message:

Merge branch with revision 4119

File:
1 edited

Legend:

Unmodified
Added
Removed

  • branches/2013/dev_r3867_MERCATOR1_DYN/DOC/TexFiles/Chapters/Chap_DIA.tex

    r3764 r4193  
    11% ================================================================ 
    2 % Chapter Ñ I/O & Diagnostics 
     2% Chapter I/O & Diagnostics 
    33% ================================================================ 
    44\chapter{Ouput and Diagnostics (IOM, DIA, TRD, FLO)} 
    … …  
    1616 
    1717The model outputs are of three types: the restart file, the output listing,  
    18 and the output file(s). The restart file is used internally by the code when  
     18and the diagnostic output file(s). The restart file is used internally by the code when  
    1919the user wants to start the model with initial conditions defined by a  
    2020previous simulation. It contains all the information that is necessary in  
    … …  
    2525that it is saved in the same binary format as the one used by the computer  
    2626that is to read it (in particular, 32 bits binary IEEE format must not be used for  
    27 this file). The output listing and file(s) are predefined but should be checked  
     27this file).  
     28 
     29The output listing and file(s) are predefined but should be checked  
    2830and eventually adapted to the user's needs. The output listing is stored in  
    2931the $ocean.output$ file. The information is printed from within the code on the  
    … …  
    3133"\textit{grep -i numout}" in the source code directory. 
    3234 
    33 In the standard configuration, the user will find the model results in  
    34 NetCDF files containing mean values (or instantaneous values if  
    35 \key{diainstant} is defined) for every time-step where output is demanded. 
    36 These outputs are defined in the \mdl{diawri} module.  
    37 When defining \key{dimgout}, the output are written in DIMG format, 
    38 an IEEE output format. 
    39  
    40 Since version 3.2, an I/O server has been added which provides more 
    41 flexibility in the choice of the fields to be output as well as how the  
    42 writing work is distributed over the processors in massively parallel 
    43 computing. It is presented in next section.  
    44  
     35By default, diagnostic output files are written in NetCDF format but an IEEE binary output format, called DIMG, can be choosen by defining \key{dimgout}.  
     36 
     37Since version 3.2, when defining \key{iomput}, an I/O server has been added which provides more flexibility in the choice of the fields to be written as well as how the writing work is distributed over the processors in massively parallel computing. The complete description of the use of this I/O server is presented in the next section.  
     38 
     39By default, if neither \key{iomput} nor \key{dimgout} are defined, NEMO produces NetCDF with the old IOIPSL library which has been kept for compatibility and its easy installation. However, the IOIPSL library is quite inefficient on parallel machines and, since version 3.2, many diagnostic options have been added presuming the use of \key{iomput}. The usefulness of the default IOIPSL-based option is expected to reduce with each new release. If \key{iomput} is not defined, output files and content are defined in the \mdl{diawri} module and contain mean (or instantaneous if \key{diainstant} is defined) values over a regular period of nn\_write time-steps (namelist parameter).  
    4540 
    4641%\gmcomment{                    % start of gmcomment 
    … …  
    5348 
    5449 
    55 Since version 3.2, iom\_put is the NEMO output interface. It was designed to be simple to use,  
    56 flexible and efficient. Two main functionalities are covered by iom\_put:  
    57 (1) the control of the output files through an external xml file defined by the user ;  
    58 (2) the distribution (or not) of all task related to output files on dedicated processors. 
    59 The first functionality allows the user to specify, without touching anything into the code,  
    60 the way he want to output data: \\ 
    61 - choice of output frequencies that can be different for each file (including real months and years) \\ 
    62 - choice of file contents: decide which data will be written in which file (the same data can be  
    63 outputted in different files)  \\ 
    64 - possibility to extract a subdomain (for example all TAO-PIRATA-RAMA moorings are already defined)  \\ 
    65 - choice of the temporal operation to perform: mean, instantaneous, min, max  \\ 
    66 - extremely large choice of data available   \\ 
    67 - redefine variables name and long\_name  \\ 
    68 In addition, iom\_put allows the user to output any variable (scalar, 2D or 3D) in the code  
    69 in a very easy way. All details of iom\_put functionalities are listed in the following subsections. 
    70 An example of the iodef.xml file that control the outputs can be found here:  
    71 NEMOGCM/CONFIG/ORCA2\_LIM/EXP00/iodef.xml 
    72  
    73 The second functionality targets outputs performances when running on a very large number of processes.  
    74 The idea is to dedicate N specific processes to write the outputs, where N is defined by the user.  
    75 In the current version, this functionality is technically working however, its performance are usually poor  
    76 (for known reasons). Users can therefore test this functionality but they must be aware that expected  
    77 performance improvement will not be achieved before the release 3.4. 
    78 An example of xmlio\_server.def NEMOGCM/CONFIG/ORCA2\_LIM/EXP00/xmlio\_server.def 
    79   
    80  
    81 \subsection{Basic knowledge} 
    82  
     50Since version 3.2, iomput is the NEMO output interface of choice. It has been designed to be simple to use, flexible and efficient. The two main purposes of iomput are:  
     51\begin{enumerate} 
     52\item The complete and flexible control of the output files through external XML files adapted by the user from standard templates.  
     53\item To achieve high performance and scalable output through the optional distribution of all diagnostic output related tasks to dedicated processes.  
     54\end{enumerate} 
     55The first functionality allows the user to specify, without code changes or recompilation, aspects of the diagnostic output stream, such as: 
     56\begin{itemize} 
     57\item The choice of output frequencies that can be different for each file (including real months and years). 
     58\item The choice of file contents; includes complete flexibility over which data are written in which files (the same data can be written in different files).  
     59\item The possibility to split output files at a choosen frequency. 
     60\item The possibility to extract a vertical or an horizontal subdomain. 
     61\item The choice of the temporal operation to perform, e.g.: average, accumulate, instantaneous, min, max and once. 
     62\item Control over metadata via a large XML "database" of possible output fields. 
     63\end{itemize} 
     64In addition, iomput allows the user to add the output of any new variable (scalar, 2D or 3D) in the code in a very easy way. All details of iomput functionalities are listed in the following subsections. Examples of the XML files that control the outputs can be found in: 
     65\begin{alltt} 
     66\begin{verbatim} 
     67  NEMOGCM/CONFIG/ORCA2_LIM/EXP00/iodef.xml 
     68  NEMOGCM/CONFIG/SHARED/field_def.xml 
     69  and 
     70  NEMOGCM/CONFIG/SHARED/domain_def.xml. 
     71\end{verbatim} 
     72\end{alltt} 
     73 
     74The second functionality targets output performance when running in parallel (\key{mpp\_mpi}). Iomput provides the possibility to specify N dedicated I/O processes (in addition to the NEMO processes) to collect and write the outputs. With an appropriate choice of N by the user, the bottleneck associated with the writing of the output files can be greatly reduced.  
     75 
     76Since version 3.5, the iom\_put interface depends on an external code called \href{http://forge.ipsl.jussieu.fr/ioserver}{XIOS}. This new IO server can take advantage of the parallel I/O functionality of NetCDF4 to create a single output file and therefore to bypass the rebuilding phase. Note that writing in parallel into the same NetCDF files requires that your NetCDF4 library is linked to an HDF5 library that has been correctly compiled (i.e. with the configure option $--$enable-parallel). Note that the files created by iomput through XIOS are incompatible with NetCDF3. All post-processsing and visualization tools must therefore be compatible with NetCDF4 and not only NetCDF3. 
     77 
     78Even if not using the parallel I/O functionality of NetCDF4, using N dedicated I/O servers, where N is typically much less than the number of NEMO processors, will reduce the number of output files created. This can greatly reduce the post-processing burden usually associated with using large numbers of NEMO processors. Note that for smaller configurations, the rebuilding phase can be avoided, even without a parallel-enabled NetCDF4 library, simply by employing only one dedicated I/O server. 
     79 
     80\subsection{XIOS: the IO\_SERVER} 
     81 
     82\subsubsection{Attached or detached mode?} 
     83 
     84Iomput is based on \href{http://forge.ipsl.jussieu.fr/ioserver/wiki}{XIOS}, the io\_server developed by Yann Meurdesoif from IPSL. The behaviour of the io subsystem is controlled by settings in the external XML files listed above. Key settings in the iodef.xml file are {\tt using\_server} and the {\tt type} tag associated with each defined file. The {\tt using\_server} setting determines whether or not the server will be used in ''attached mode'' (as a library) [{\tt false}] or in ''detached mode'' (as an external executable on N additional, dedicated cpus) [{\tt true}]. The ''attached mode'' is simpler to use but much less efficient for massively parallel applications. The type of each file can be either ''multiple\_file'' or ''one\_file''. 
     85 
     86In attached mode and if the type of file is ''multiple\_file'', then each NEMO process will also act as an IO server and produce its own set of output files. Superficially, this emulates the standard behaviour in previous versions, However, the subdomain written out by each process does not correspond to the {\tt jpi x jpj x jpk} domain actually computed by the process (although it may if {\tt jpni=1}). Instead each process will have collected and written out a number of complete longitudinal strips. If the ''one\_file'' option is chosen then all processes will collect their longitudinal strips and write (in parallel) to a single output file.  
     87 
     88In detached mode and if the type of file is ''multiple\_file'', then each stand-alone XIOS process will collect data for a range of complete longitudinal strips and write to its own set of output files. If the ''one\_file'' option is chosen then all XIOS processes will collect their longitudinal strips and write (in parallel) to a single output file. Note running in detached mode requires launching a Multiple Process Multiple Data (MPMD) parallel job. The following subsection provides a typical example but the syntax will vary in different MPP environments. 
     89 
     90\subsubsection{Number of cpu used by XIOS in detached mode} 
     91 
     92The number of cores used by the XIOS is specified when launching the model. The number of cores dedicated to XIOS should be from ~1/10 to ~1/50 of the number or cores dedicated to NEMO. Some manufacturers suggest using O($\sqrt{N}$) dedicated IO processors for N processors but this is a general recommendation and not specific to NEMO. It is difficult to provide precise recommendations because the optimal choice will depend on the particular hardware properties of the target system (parallel filesystem performance, available memory, memory bandwidth etc.) and the volume and frequency of data to be created. Here is an example of 2 cpus for the io\_server and 62 cpu for nemo using mpirun: 
     93 
     94\texttt{ mpirun -np 62 ./nemo.exe : -np 2 ./xios\_server.exe } 
     95 
     96\subsubsection{Control of XIOS: the XIOS context in iodef.xml} 
     97 
     98As well as the {\tt using\_server} flag, other controls on the use of XIOS are set in the XIOS context in iodef.xml. See the XML basics section below for more details on XML syntax and rules. 
     99 
     100\begin{tabular}{|p{4cm}|p{6.0cm}|p{2.0cm}|} 
     101   \hline 
     102   variable name &  
     103   description &  
     104   example \\  
     105   \hline    
     106   \hline 
     107   buffer\_size &  
     108   buffer size used by XIOS to send data from NEMO to XIOS. Larger is more efficient. Note that needed/used buffer sizes are summarized at the end of the job &  
     109   25000000 \\  
     110   \hline    
     111   buffer\_server\_factor\_size &  
     112   ratio between NEMO and XIOS buffer size. Should be 2. &  
     113   2 \\  
     114   \hline 
     115   info\_level &  
     116   verbosity level (0 to 100) &  
     117   0 \\  
     118   \hline 
     119   using\_server &  
     120   activate attached(false) or detached(true) mode &  
     121   true \\  
     122   \hline 
     123   using\_oasis &  
     124   XIOS is used with OASIS(true) or not (false) &  
     125   false \\  
     126   \hline 
     127   oasis\_codes\_id &  
     128   when using oasis, define the identifier of NEMO in the namcouple. Note that the identifier of XIOS is xios.x &  
     129   oceanx \\  
     130   \hline    
     131\end{tabular} 
     132 
     133 
     134\subsection{Practical issues} 
     135 
     136\subsubsection{Installation} 
     137 
     138As mentioned, XIOS is supported separately and must be downloaded and compiled before it can be used with NEMO. See the installation guide on the \href{http://forge.ipsl.jussieu.fr/ioserver/wiki}{XIOS} wiki for help and guidance. NEMO will need to link to the compiled XIOS library. The  
     139\href{http://www.nemo-ocean.eu/Using-NEMO/User-Guides/Basics/XIOS-IO-server-installation-and-use}{XIOS with NEMO} guide provides an example illustration of how this can be achieved. 
     140 
     141\subsubsection{Add your own outputs} 
     142 
     143It is very easy to add your own outputs with iomput. Many standard fields and diagnostics are already prepared (i.e., steps 1 to 3 below have been done) and simply need to be activated by including the required output in a file definition in iodef.xml (step 4). To add new output variables, all 4 of the following steps must be taken. 
     144\begin{description} 
     145\item[1.] in NEMO code, add a \\ 
     146\texttt{      CALL iom\_put( 'identifier', array ) } \\ 
     147where you want to output a 2D or 3D array. 
     148 
     149\item[2.] If necessary, add \\ 
     150\texttt{   USE iom\ \ \ \ \ \ \ \ \ \ \ \ ! I/O manager library }  \\ 
     151to the list of used modules in the upper part of your module.  
     152 
     153\item[3.] in the field\_def.xml file, add the definition of your variable using the same identifier you used in the f90 code (see subsequent sections for a details of the XML syntax and rules). For example: 
     154\vspace{-20pt} 
     155\begin{alltt}  {{\scriptsize 
     156\begin{verbatim} 
     157   <field_definition> 
     158      <!-- T grid --> 
     159 
     160     <field_group id="grid_T" grid_ref="grid_T_3D"> 
     161      ... 
     162      <field id="identifier" long_name="blabla" ... />    
     163      ... 
     164   </field_definition>  
     165\end{verbatim} 
     166}}\end{alltt}  
     167Note your definition must be added to the field\_group whose reference grid is consistent with the size of the array passed to iomput. The grid\_ref attribute refers to definitions set in iodef.xml which, in turn, reference grids and axes either defined in the code (iom\_set\_domain\_attr and iom\_set\_axis\_attr in iom.F90) or defined in the domain\_def.xml file. E.g.: 
     168\vspace{-20pt} 
     169\begin{alltt}  {{\scriptsize 
     170\begin{verbatim} 
     171     <grid id="grid_T_3D" domain_ref="grid_T" axis_ref="deptht"/> 
     172\end{verbatim} 
     173}}\end{alltt}  
     174Note, if your array is computed within the surface module each nn\_fsbc time\_step,  
     175add the field definition within the field\_group defined with the id ''SBC'': $<$field\_group id=''SBC''...$>$ which has been defined with the correct frequency of operations (iom\_set\_field\_attr in iom.F90) 
     176 
     177\item[4.] add your field in one of the output files defined in iodef.xml (again see subsequent sections for syntax and rules)   \\ 
     178\vspace{-20pt} 
     179\begin{alltt}  {{\scriptsize 
     180\begin{verbatim} 
     181   <file id="file1" .../>    
     182      ... 
     183      <field field_ref="identifier" />    
     184      ... 
     185   </file>    
     186\end{verbatim} 
     187}}\end{alltt}  
     188 
     189\end{description} 
     190\subsection{XML fundamentals} 
    83191 
    84192\subsubsection{ XML basic rules} 
    … …  
    93201\subsubsection{Structure of the xml file used in NEMO} 
    94202 
    95 The xml file is split into 3 parts: 
    96 \begin{description} 
    97 \item[field definition]: define all variables that can be output \\ 
    98 all lines in between the following two tags\\ 
    99 \verb?   <field\_definition ...> ?  \\ 
    100 \verb?   </field\_definition ...> ?  
    101 \item[file definition]: define the netcdf files to be created and the variables they will contain \\ 
    102 all lines in between the following two tags \\ 
    103 \verb?   <field\_definition> ?  \\ 
    104 \verb?   </field\_definition> ? 
    105 \item[axis and grid definitions]: define the horizontal and vertical grids \\ 
    106 all lines in between the following two set of two tags\\ 
    107 \verb?   <axis\_definition ...> ?  \\ 
    108 \verb?   </axis\_definition ...> ? 
    109 and \\ 
    110 \verb?   <grid\_definition ...> ?  \\ 
    111 \verb?   </grid\_definition ...> ? 
    112 \end{description} 
    113  
    114 \subsubsection{Inheritance and group } 
    115  
    116  Xml extensively uses the concept of inheritance. \\ 
     203The XML file used in XIOS is structured by 7 families of tags: context, axis, domain, grid, field, file and variable. Each tag family has hierarchy of three flavors (except for context): 
    117204\\ 
    118 example 1: \\ 
    119 \vspace{-30pt} 
     205\begin{tabular}{|p{3.0cm}|p{4.5cm}|p{4.5cm}|} 
     206   \hline 
     207   flavor & 
     208   description & 
     209   example \\ 
     210   \hline 
     211   \hline 
     212   root & 
     213   declaration of the root element that can contain element groups or elements & 
     214   {\scriptsize \verb? < file_definition ... >?} \\ 
     215   \hline 
     216   group & 
     217   declaration of a group element that can contain element groups or elements & 
     218   {\scriptsize \verb? < file_group ... >?} \\ 
     219   \hline 
     220   element & 
     221   declaration of an element that can contain elements & 
     222   {\scriptsize \verb? < file ... >?} \\ 
     223   \hline 
     224\end{tabular} 
     225\\ 
     226 
     227Each element may have several attributes. Some attributes are mandatory, other are optional but have a default value and other are are completely optional. Id is a special attribute used to identify an element or a group of elements. It must be unique for a kind of element. It is optional, but no reference to the corresponding element can be done if it is not defined. 
     228 
     229The XML file is split into context tags that are used to isolate IO definition from different codes or different parts of a code. No interference is possible between 2 different contexts. Each context has its own calendar and an associated timestep. In NEMO, we used the following contexts (that can be defined in any order):\\ 
     230\\ 
     231\begin{tabular}{|p{3.0cm}|p{4.5cm}|p{4.5cm}|} 
     232   \hline 
     233   context & 
     234   description & 
     235   example \\ 
     236   \hline 
     237   \hline 
     238   context xios & 
     239   context containing information for XIOS & 
     240   {\scriptsize \verb? <context id="xios" ...  ?} \\ 
     241   \hline 
     242   context nemo & 
     243   context containing IO information for NEMO (mother grid when using AGRIF) & 
     244   {\scriptsize \verb? <context id="nemo" ... ?} \\ 
     245   \hline 
     246   context 1\_nemo & 
     247   context containing IO information for NEMO child grid 1 (when using AGRIF) & 
     248   {\scriptsize \verb? <context id="1_nemo" ...  ?} \\ 
     249   \hline 
     250   context n\_nemo & 
     251   context containing IO information for NEMO child grid n (when using AGRIF) & 
     252   {\scriptsize \verb? <context id="n_nemo" ...  ?} \\ 
     253   \hline 
     254\end{tabular} 
     255\\ 
     256 
     257\noindent The xios context contains only 1 tag: 
     258\\ 
     259\begin{tabular}{|p{3.0cm}|p{4.5cm}|p{4.5cm}|} 
     260   \hline 
     261   context tag & 
     262   description & 
     263   example \\ 
     264   \hline 
     265   \hline 
     266   variable\_definition & 
     267   define variables needed by XIOS. This can be seen as a kind of namelist for XIOS. & 
     268   {\scriptsize \verb? <variable_definition ... ?} \\ 
     269   \hline 
     270\end{tabular} 
     271\\ 
     272 
     273\noindent Each context tag related to NEMO (mother or child grids) is divided into 5 parts (that can be defined in any order):\\ 
     274\\ 
     275\begin{tabular}{|p{3.0cm}|p{4.5cm}|p{4.5cm}|} 
     276   \hline 
     277   context tag & 
     278   description & 
     279   example \\ 
     280   \hline 
     281   \hline 
     282   field\_definition & 
     283   define all variables that can potentially be outputted & 
     284   {\scriptsize \verb? <field_definition ... ?} \\ 
     285   \hline 
     286   file\_definition & 
     287   define the netcdf files to be created and the variables they will contain & 
     288   {\scriptsize \verb? <file_definition ... ?} \\ 
     289   \hline 
     290   axis\_definition & 
     291   define vertical axis & 
     292   {\scriptsize \verb? <axis_definition ... ?} \\ 
     293   \hline 
     294   domain\_definition & 
     295   define the horizontal grids & 
     296   {\scriptsize \verb? <domain_definition ... ?} \\ 
     297   \hline 
     298   grid\_definition & 
     299   define the 2D and 3D grids (association of an axis and a domain) & 
     300   {\scriptsize \verb? <grid_definition ... ?} \\ 
     301   \hline 
     302\end{tabular} 
     303\\ 
     304 
     305\subsubsection{Nesting XML files} 
     306 
     307The XML file can be split in different parts to improve its readability and facilitate its use. The inclusion of XML files into the main XML file can be done through the attribute src: \\ 
     308{\scriptsize \verb? <context src="./nemo_def.xml" /> ?}\\ 
     309  
     310\noindent In NEMO, by default, the field and domain definition is done in 2 separate files: 
     311{\scriptsize \tt 
     312\begin{verbatim} 
     313NEMOGCM/CONFIG/SHARED/field_def.xml 
     314and 
     315NEMOGCM/CONFIG/SHARED/domain_def.xml  
     316\end{verbatim} 
     317} 
     318\noindent that are included in the main iodef.xml file through the following commands: \\ 
     319{\scriptsize \verb? <field_definition src="./field_def.xml" /> ? \\ 
     320\verb? <domain_definition src="./domain_def.xml" /> ? } 
     321 
     322 
     323\subsubsection{Use of inheritance} 
     324 
     325XML extensively uses the concept of inheritance. XML has a tree based structure with a parent-child oriented relation: all children inherit attributes from parent, but an attribute defined in a child replace the inherited attribute value. Note that the special attribute ''id'' is never inherited.  \\ 
     326\\ 
     327example 1: Direct inheritance. 
     328\vspace{-20pt} 
    120329\begin{alltt}  {{\scriptsize     
    121330\begin{verbatim} 
    122    <field_definition operation="ave(X)" > 
    123       <field id="sst"                    />   <!-- averaged      sst -->  
    124       <field id="sss" operation="inst(X)"/>   <!-- instantaneous sss -->  
     331   <field_definition operation="average" > 
     332     <field id="sst"                    />   <!-- averaged      sst -->  
     333     <field id="sss" operation="instant"/>   <!-- instantaneous sss -->  
    125334   </field_definition>  
    126335\end{verbatim} 
    127336}}\end{alltt}  
    128337 
    129 The field ''sst'' which is part (or a child) of the field\_definition will inherit the value ''ave(X)''  
    130 of the attribute ''operation'' from its parent ''field definition''. Note that a child can overwrite  
     338The field ''sst'' which is part (or a child) of the field\_definition will inherit the value ''average''  
     339of the attribute ''operation'' from its parent. Note that a child can overwrite  
    131340the attribute definition inherited from its parents. In the example above, the field ''sss'' will  
    132 therefore output instantaneous values instead of average values. 
    133  
    134 example 2: Use (or overwrite) attributes value of a field when listing the variables included in a file 
     341for example output instantaneous values instead of average values. \\ 
     342\\ 
     343example 2: Inheritance by reference. 
    135344\vspace{-20pt} 
    136345\begin{alltt}  {{\scriptsize 
    137346\begin{verbatim} 
    138347   <field_definition> 
    139       <field id="sst" description="sea surface temperature" />    
    140       <field id="sss" description="sea surface salinity"    />   
     348     <field id="sst" long_name="sea surface temperature" />    
     349     <field id="sss" long_name="sea surface salinity"    />   
    141350   </field_definition>       
    142351 
    143352   <file_definition> 
    144       <file id="file_1" />    
    145             <field ref="sst"                              />  <!-- default def --> 
    146             <field ref="sss" description="my description" />  <!-- overwrite   --> 
    147       </file>    
     353     <file id="myfile" output_freq="1d" />    
     354       <field field_ref="sst"                            />  <!-- default def --> 
     355       <field field_ref="sss" long_name="my description" />  <!-- overwrite   --> 
     356     </file>    
    148357   </file_definition>  
    149358\end{verbatim} 
    150359}}\end{alltt}  
    151  
    152 With the help of the inheritance, the concept of group allow to define a set of attributes  
    153 for several fields or files.  
    154  
    155 example 3, group of fields: define a group ''T\_grid\_variables'' identified with the name  
    156 ''grid\_T''. By default variables of this group have no vertical axis but, following inheritance  
    157 rules, ''axis\_ref'' can be redefined for the field ''toce'' that is a 3D variable. 
    158 \vspace{-30pt} 
     360Inherit (and overwrite, if needed) the attributes of a tag you are refering to. 
     361 
     362\subsubsection{Use of Groups} 
     363 
     364Groups can be used for 2 purposes. Firstly, the group can be used to define common attributes to be shared by the elements of the group through inheritance. In the following example, we define a group of field that will share a common grid ''grid\_T\_2D''. Note that for the field ''toce'', we overwrite the grid definition inherited from the group by ''grid\_T\_3D''. 
     365\vspace{-20pt} 
    159366\begin{alltt}  {{\scriptsize 
    160367\begin{verbatim} 
    161    <field_definition> 
    162       <group id="grid_T" axis_ref="none" grid_ref="T_grid_variables"> 
    163             <field id="sst"/>   
    164             <field id="sss"/>   
    165             <field id="toce" axis_ref="deptht"/>  <!-- overwrite axis def --> 
    166       </group> 
    167    </field_definition>  
     368   <field_group id="grid_T" grid_ref="grid_T_2D"> 
     369    <field id="toce" long_name="temperature"             unit="degC" grid_ref="grid_T_3D"/> 
     370    <field id="sst"  long_name="sea surface temperature" unit="degC"                     /> 
     371    <field id="sss"  long_name="sea surface salinity"    unit="psu"                      /> 
     372    <field id="ssh"  long_name="sea surface height"      unit="m"                        /> 
     373         ... 
    168374\end{verbatim} 
    169375}}\end{alltt}  
    170376 
    171 example 4, group of files: define a group of file with the attribute output\_freq equal to 432000 (5 days) 
    172 \vspace{-30pt} 
     377Secondly, the group can be used to replace a list of elements. Several examples of groups of fields are proposed at the end of the file {\tt CONFIG/SHARED/field\_def.xml}. For example, a short list of the usual variables related to the U grid: 
     378\vspace{-20pt} 
    173379\begin{alltt}  {{\scriptsize 
    174380\begin{verbatim} 
    175    <file_definition> 
    176       <group id="5d" output_freq="432000">    <!-- 5d files --> 
    177          <file id="5d_grid_T" name="auto">   <!-- T grid file --> 
     381   <field_group id="groupU" > 
     382    <field field_ref="uoce"  /> 
     383    <field field_ref="suoce" /> 
     384    <field field_ref="utau"  /> 
     385   </field_group> 
     386\end{verbatim} 
     387}}\end{alltt}  
     388that can be directly included in a file through the following syntax: 
     389\vspace{-20pt} 
     390\begin{alltt}  {{\scriptsize 
     391\begin{verbatim} 
     392   <file id="myfile_U" output_freq="1d" />    
     393    <field_group group_ref="groupU"/>   
     394    <field field_ref="uocetr_eff"  />  <!-- add another field --> 
     395   </file>    
     396\end{verbatim} 
     397}}\end{alltt}  
     398 
     399\subsection{Detailed functionalities } 
     400 
     401The file {\tt NEMOGCM/CONFIG/ORCA2\_LIM/iodef\_demo.xml} provides several examples of the use of the new functionalities offered by the XML interface of XIOS.  
     402 
     403\subsubsection{Define horizontal subdomains} 
     404Horizontal subdomains are defined through the attributs zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj of the tag family domain. It must therefore be done in the domain part of the XML file. For example, in {\tt CONFIG/SHARED/domain\_def.xml}, we provide the following example of a definition of a 5 by 5 box with the bottom left corner at point (10,10). 
     405\vspace{-20pt} 
     406\begin{alltt}  {{\scriptsize 
     407\begin{verbatim} 
     408   <domain_group id="grid_T"> 
     409    <domain id="myzoom" zoom_ibegin="10" zoom_jbegin="10" zoom_ni="5" zoom_nj="5" /> 
     410\end{verbatim} 
     411}}\end{alltt}  
     412The use of this subdomain is done through the redefinition of the attribute domain\_ref of the tag family field. For example: 
     413\vspace{-20pt} 
     414\begin{alltt}  {{\scriptsize 
     415\begin{verbatim} 
     416   <file id="myfile_vzoom" output_freq="1d" > 
     417      <field field_ref="toce" domain_ref="myzoom"/> 
     418   </file> 
     419\end{verbatim} 
     420}}\end{alltt}  
     421Moorings are seen as an extrem case corresponding to a 1 by 1 subdomain. The Equatorial section, the TAO, RAMA and PIRATA moorings are alredy registered in the code and can therefore be outputted without taking care of their (i,j) position in the grid. These predefined domains can be activated by the use of specific domain\_ref: ''EqT'', ''EqU'' or ''EqW'' for the equatorial sections and the mooring position for TAO, RAMA and PIRATA followed by ''T'' (for example: ''8s137eT'', ''1.5s80.5eT'' ...) 
     422\vspace{-20pt} 
     423\begin{alltt}  {{\scriptsize 
     424\begin{verbatim} 
     425   <file id="myfile_vzoom" output_freq="1d" > 
     426      <field field_ref="toce" domain_ref="0n180wT"/> 
     427   </file> 
     428\end{verbatim} 
     429}}\end{alltt}  
     430Note 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. 
     431 
     432\subsubsection{Define vertical zooms} 
     433Vertical 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: 
     434\vspace{-20pt} 
     435\begin{alltt}  {{\scriptsize 
     436\begin{verbatim} 
     437   <axis_group id="deptht" long_name="Vertical T levels" unit="m" positive="down" > 
     438      <axis id="deptht" /> 
     439      <axis id="deptht_myzoom" zoom_begin="1" zoom_end="10" /> 
     440\end{verbatim} 
     441}}\end{alltt}  
     442The use of this vertical zoom is done through the redefinition of the attribute axis\_ref of the tag family field. For example: 
     443\vspace{-20pt} 
     444\begin{alltt}  {{\scriptsize 
     445\begin{verbatim} 
     446   <file id="myfile_hzoom" output_freq="1d" > 
     447      <field field_ref="toce" axis_ref="deptht_myzoom"/> 
     448   </file> 
     449\end{verbatim} 
     450}}\end{alltt}  
     451 
     452\subsubsection{Control of the output file names} 
     453 
     454The output file names are defined by the attributs ''name'' and ''name\_suffix'' of the tag family file. for example: 
     455\vspace{-20pt} 
     456\begin{alltt}  {{\scriptsize 
     457\begin{verbatim} 
     458   <file_group id="1d" output_freq="1d" name="myfile_1d" >  
     459      <file id="myfileA" name_suffix="_AAA" > <!-- will create file "myfile_1d_AAA"  --> 
    178460         ... 
    179          </file> 
    180          <file id="5d_grid_U" name="auto">   <!-- U grid file --> 
     461      </file> 
     462      <file id="myfileB" name_suffix="_BBB" > <!-- will create file "myfile_1d_BBB" --> 
    181463         ... 
    182          </file> 
    183       </group> 
    184    </file_definition>  
     464      </file> 
     465   </file_group> 
    185466\end{verbatim} 
    186467}}\end{alltt}  
    187  
    188 \subsubsection{Control of the xml attributes from NEMO} 
    189  
    190 The values of some attributes are automatically defined by NEMO (and any definition  
    191 given in the xml file is overwritten). By convention, these attributes are defined to ''auto''  
    192 (for string) or ''0000'' (for integer) in the xml file (but this is not necessary).  
    193  
    194 Here is the list of these attributes: \\ 
     468However 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 99) 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:\\ 
     469\\ 
     470\begin{tabular}{|p{4cm}|p{8cm}|} 
     471   \hline 
     472   \centering placeholder string & automatically  replaced by \\ 
     473   \hline 
     474   \hline 
     475   \centering @expname@ & 
     476   the experiment name (from cn\_exp in the namelist) \\ 
     477   \hline 
     478   \centering @freq@ & 
     479   output frequency (from attribute output\_freq) \\ 
     480   \hline 
     481   \centering @startdate@  & 
     482   starting date of the simulation (from nn\_date0 in the restart or the namelist). \verb?yyyymmdd? format \\ 
     483   \hline 
     484   \centering @startdatefull@  &  
     485   starting date of the simulation (from nn\_date0 in the restart or the namelist). \verb?yyyymmdd_hh:mm:ss? format \\ 
     486   \hline 
     487   \centering @enddate@  & 
     488   ending date of the simulation (from nn\_date0 and nn\_itend in the namelist). \verb?yyyymmdd? format \\ 
     489   \hline 
     490   \centering @enddatefull@  &  
     491   ending date of the simulation (from nn\_date0 and nn\_itend in the namelist). \verb?yyyymmdd_hh:mm:ss? format \\ 
     492   \hline 
     493\end{tabular}\\ 
     494\\ 
     495 
     496\noindent For example,  
     497{{\scriptsize 
     498\begin{verbatim} 
     499   <file id="myfile_hzoom" name="myfile_@expname@_@startdate@_freq@freq@" output_freq="1d" > 
     500\end{verbatim} 
     501}} 
     502\noindent with the namelist: 
     503{{\scriptsize 
     504\begin{verbatim} 
     505   cn_exp      =  "ORCA2" 
     506   nn_date0    =  19891231 
     507   ln_rstart   = .false. 
     508\end{verbatim} 
     509}} 
     510\noindent will give the following file name radical: 
     511{{\scriptsize 
     512\begin{verbatim} 
     513   myfile_ORCA2_19891231_freq1d  
     514\end{verbatim} 
     515}} 
     516 
     517\subsubsection{Other controls of the xml attributes from NEMO} 
     518 
     519The 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 iom.F90). 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).  
     520 
     521Here is the list of these attributes:\\ 
    195522\\ 
    196523\begin{tabular}{|l|c|c|c|} 
    … …  
    202529    \multicolumn{2}{|c|}{field\_definition} & freq\_op & \np{rn\_rdt} \\ 
    203530   \hline 
    204     \multicolumn{2}{|c|}{SBC}                  & freq\_op & \np{rn\_rdt} $\times$ \np{nn\_fsbc} \\ 
    205    \hline 
    206     1h, 2h, 3h, 4h, 6h, 12h & \_grid\_T, \_grid\_U,  &  name & filename defined by   \\ 
    207     1d, 3d, 5d                     & \_grid\_V, \_grid\_W, &            & a call to rou{dia\_nam}  \\ 
    208     1m, 2m, 3m, 4m, 6m    & \_icemod, \_ptrc\_T,  &            & following NEMO \\ 
    209     1y, 2y, 5y, 10y               &  \_diad\_T, \_scalar   &            & nomenclature \\ 
     531    \multicolumn{2}{|c|}{SBC}               & freq\_op & \np{rn\_rdt} $\times$ \np{nn\_fsbc}  \\ 
     532   \hline 
     533    \multicolumn{2}{|c|}{ptrc\_T}           & freq\_op & \np{rn\_rdt} $\times$ \np{nn\_dttrc} \\ 
     534   \hline 
     535    \multicolumn{2}{|c|}{diad\_T}           & freq\_op & \np{rn\_rdt} $\times$ \np{nn\_dttrc} \\ 
    210536   \hline 
    211537    \multicolumn{2}{|c|}{EqT, EqU, EqW} & jbegin, ni,      & according to the grid    \\ 
    212538    \multicolumn{2}{|c|}{                         } & name\_suffix &                                      \\ 
    213539   \hline 
    214     \multicolumn{2}{|c|}{TAO, RAMA and PIRATA moorings} & ibegin, jbegin,      & according to the grid    \\ 
     540   \multicolumn{2}{|c|}{TAO, RAMA and PIRATA moorings} & zoom\_ibegin, zoom\_jbegin, & according to the grid    \\ 
    215541    \multicolumn{2}{|c|}{                                                       } & name\_suffix &                                      \\ 
    216542   \hline 
    … …  
    218544 
    219545 
    220 \subsection{ Detailed functionalities } 
     546\subsection{XML reference tables} 
    221547 
    222548\subsubsection{Tag list} 
    223549 
    224 \begin{description} 
    225  
    226 \item[context]: define the model using the xml file. Id is the only attribute accepted.  
    227 Its value must be ''nemo'' or ''n\_nemo'' for the nth AGRIF zoom. Child of simulation tag. 
    228  
    229 \item[field]: define the field to be output. Accepted attributes are axis\_ref, description, enable,  
    230 freq\_op, grid\_ref, id (if child of field\_definition), level, operation, name, ref (if child of file),  
    231 unit, zoom\_ref. Child of field\_definition, file or group of fields tag. 
    232  
    233 \item[field\_definition]: definition of the part of the xml file corresponding to the field definition.  
    234 Accept the same attributes as field tag. Child of context tag. 
    235  
    236 \item[group]: define a group of file or field. Accept the same attributes as file or field. 
    237  
    238 \item[file]: define the output file's characteristics. Accepted attributes are description, enable,  
    239 output\_freq, output\_level, id, name, name\_suffix. Child of file\_definition or group of files tag. 
    240  
    241 \item[file\_definition]: definition of the part of the xml file corresponding to the file definition.  
    242 Accept the same attributes as file tag. Child of context tag. 
    243  
    244 \item[axis]: definition of the vertical axis. Accepted attributes are description, id, positive, size, unit.  
    245 Child of axis\_definition tag. 
    246  
    247 \item[axis\_definition]: definition of the part of the xml file corresponding to the vertical axis definition.  
    248 Accept the same attributes as axis tag. Child of context tag 
    249  
    250 \item[grid]: definition of the horizontal grid. Accepted attributes are description and id.  
    251 Child of axis\_definition tag. 
    252  
    253 \item[grid\_definition]: definition of the part of the xml file corresponding to the horizontal grid definition.  
    254 Accept the same attributes as grid tag. Child of context tag 
    255  
    256 \item[zoom]: definition of a subdomain of an horizontal grid. Accepted attributes are description, id,  
    257 i/jbegin, ni/j. Child of grid tag. 
    258  
    259 \end{description} 
     550\begin{longtable}{|p{2.2cm}|p{2.5cm}|p{3.5cm}|p{2.2cm}|p{1.6cm}|} 
     551   \hline 
     552   tag name &  
     553   description &  
     554   accepted attribute &  
     555   child of & 
     556   parent of \endhead 
     557   \hline    
     558   simulation &  
     559   this tag is the root tag which encapsulates all the content of the xml file & 
     560   none & 
     561   none & 
     562   context \\ 
     563   \hline    
     564   context & 
     565   encapsulates parts of the xml file dedicated to different codes or different parts of a code & 
     566   id (''xios'', ''nemo'' or ''n\_nemo'' for the nth AGRIF zoom), src, time\_origin & 
     567   simulation & 
     568   all root tags: ... \_definition \\ 
     569   \hline    
     570   \hline    
     571   field\_definition & 
     572   encapsulates the definition of all the fields that can potentially be outputted & 
     573   axis\_ref, default\_value, domain\_ref, enabled, grid\_ref, level, operation, prec, src & 
     574   context & 
     575   field or field\_group \\ 
     576   \hline    
     577   field\_group & 
     578   encapsulates a group of fields & 
     579   axis\_ref, default\_value, domain\_ref, enabled, group\_ref, grid\_ref, id, level, operation, prec, src & 
     580   field\_definition, field\_group, file & 
     581   field or field\_group \\ 
     582   \hline    
     583   field & 
     584   define a specific field & 
     585   axis\_ref, default\_value, domain\_ref, enabled, field\_ref, grid\_ref, id, level, long\_name, name, operation, prec, standard\_name, unit & 
     586   field\_definition, field\_group, file & 
     587   none \\ 
     588   \hline    
     589   \hline    
     590   file\_definition &  
     591   encapsulates the definition of all the files that will be outputted & 
     592   enabled, min\_digits, name, name\_suffix, output\_level, split\_freq\_format, split\_freq, sync\_freq, type, src & 
     593   context &  
     594   file or file\_group \\ 
     595   \hline    
     596   file\_group &  
     597   encapsulates a group of files that will be outputted & 
     598   enabled, description, id, min\_digits, name, name\_suffix, output\_freq, output\_level, split\_freq\_format, split\_freq, sync\_freq, type, src & 
     599   file\_definition, file\_group &  
     600   file or file\_group \\ 
     601   \hline    
     602   file &  
     603   define the contents of a file to be outputted & 
     604   enabled, description, id, min\_digits, name, name\_suffix, output\_freq, output\_level, split\_freq\_format, split\_freq, sync\_freq, type, src & 
     605   file\_definition, file\_group &  
     606   field \\ 
     607   \hline    
     608   axis\_definition &  
     609   define all the vertical axis potentially used by the variables & 
     610   src & 
     611   context &   
     612   axis\_group, axis \\ 
     613   \hline    
     614   axis\_group &  
     615   encapsulates a group of vertical axis & 
     616   id, lon\_name, positive, src, standard\_name, unit, zoom\_begin, zoom\_end, zoom\_size & 
     617   axis\_definition, axis\_group &  
     618   axis\_group, axis \\ 
     619   \hline    
     620   axis &  
     621   define a vertical axis & 
     622   id, lon\_name, positive, src, standard\_name, unit, zoom\_begin, zoom\_end, zoom\_size & 
     623   axis\_definition, axis\_group  &  
     624   none \\ 
     625   \hline    
     626   \hline    
     627   domain\_\-definition &  
     628   define all the horizontal domains potentially used by the variables & 
     629   src & 
     630   context &  
     631   domain\_\-group, domain \\ 
     632   \hline    
     633   domain\_group &  
     634   encapsulates a group of horizontal domains & 
     635   id, lon\_name, src, zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj & 
     636   domain\_\-definition, domain\_group &  
     637   domain\_\-group, domain \\ 
     638   \hline    
     639   domain &  
     640   define an horizontal domain & 
     641   id, lon\_name, src, zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj & 
     642   domain\_\-definition, domain\_group &  
     643   none \\ 
     644   \hline    
     645   \hline    
     646   grid\_definition &  
     647   define all the grid (association of a domain and/or an axis) potentially used by the variables & 
     648   src & 
     649   context &  
     650   grid\_group, grid \\ 
     651   \hline    
     652   grid\_group &  
     653   encapsulates a group of grids & 
     654   id, domain\_ref, axis\_ref & 
     655   grid\_definition, grid\_group &  
     656   grid\_group, grid \\ 
     657   \hline    
     658   grid &  
     659   define a grid & 
     660   id, domain\_ref, axis\_ref & 
     661   grid\_definition, grid\_group &  
     662   none \\ 
     663   \hline    
     664\end{longtable} 
    260665 
    261666 
    262667\subsubsection{Attributes list} 
    263668 
    264 Applied to a tag or a group of tags. 
    265  
    266 % table to be added ? 
    267 Another table, perhaps? 
    268  
    269 %%%% 
    270  
    271 Attribute 
    272 Applied to? 
    273 Definition 
    274 Comment 
    275 axis\_ref 
    276 field 
    277 String defining the vertical axis of the variable. It refers to the id of the vertical axis defined in the axis tag. 
    278 Use ''non'' if the variable has no vertical axis 
    279  
    280 %%%%%% 
    281  
    282 \begin{description} 
    283  
    284 \item[axis\_ref]: field attribute. String defining the vertical axis of the variable.  
    285 It refers to the id of the vertical axis defined in the axis tag.  
    286 Use ''none'' if the variable has no vertical axis 
    287  
    288 \item[description]: this attribute can be applied to all tags but it is used only with the field tag.  
    289 In this case, the value of description will be used to define, in the output netcdf file,  
    290 the attributes long\_name and standard\_name of the variable. 
    291  
    292 \item[enabled]: field and file attribute. Logical to switch on/off the output of a field or a file.  
    293  
    294 \item[freq\_op]: field attribute (automatically defined, see part 1.4 (''control of the xml attributes'')).  
    295 An integer defining the frequency in seconds at which NEMO is calling iom\_put for this variable.  
    296 It corresponds to the model time step (rn\_rdt in the namelist) except for the variables computed  
    297 at the frequency of the surface boundary condition (rn\_rdt ? nn\_fsbc in the namelist).    
    298  
    299 \item[grid\_ref]: field attribute. String defining the horizontal grid of the variable.  
    300 It refers to the id of the grid tag. 
    301  
    302 \item[ibegin]: zoom attribute. Integer defining the zoom starting point along x direction.  
    303 Automatically defined for TAO/RAMA/PIRATA moorings (see part 1.4).   
    304  
    305 \item[id]: exists for all tag. This is a string defining the name to a specific tag that will be used  
    306 later to refer to this tag. Tags of the same category must have different ids. 
    307  
    308 \item[jbegin]: zoom attribute. Integer defining the zoom starting point along y direction.  
    309 Automatically defined for TAO/RAMA/PIRATA moorings and equatorial section (see part 1.4).  
    310  
    311 \item[level]: field attribute. Integer from 0 to 10 defining the output priority of a field.  
    312 See output\_level attribute definition 
    313  
    314 \item[operation]: field attribute. String defining the type of temporal operation to perform on a variable.  
    315 Possible choices are ''ave(X)'' for temporal mean, ''inst(X)'' for instantaneous, ''t\_min(X)'' for temporal min  
    316 and ''t\_max(X)'' for temporal max. 
    317  
    318 \item[output\_freq]: file attribute. Integer defining the operation frequency in seconds.  
    319 For example 86400 for daily mean. 
    320  
    321 \item[output\_level]: file attribute. Integer from 0 to 10 defining the output priority of variables in a file:  
    322 all variables listed in the file with a level smaller or equal to output\_level will be output.  
    323 Other variables won't be output even if they are listed in the file.   
    324  
    325 \item[positive]: axis attribute (always .FALSE.). Logical defining the vertical axis convention used  
    326 in \NEMO (positive downward). Define the attribute positive of the variable in the netcdf output file. 
    327  
    328 \item[prec]: field attribute. Integer defining the output precision.  
    329 Not implemented, we always output real4 arrays.  
    330  
    331 \item[name]: field or file attribute. String defining the name of a variable or a file.  
    332 If the name of a file is undefined, its id is used as a name. 2 files must have different names.  
    333 Files with specific ids will have their name automatically defined (see part 1.4).  
    334 Note that is name will be automatically completed by the cpu number (if needed) and ''.nc'' 
    335  
    336 \item[name\_suffix]: file attribute. String defining a suffix to be inserted after the name  
    337 and before the cpu number and the ''.nc'' termination. Files with specific ids have an  
    338 automatic definition of their suffix (see part 1.4). 
    339  
    340 \item[ni]: zoom attribute. Integer defining the zoom extent along x direction.  
    341 Automatically defined for equatorial sections (see part 1.4).   
    342  
    343 \item[nj]: zoom attribute. Integer defining the zoom extent along x direction.  
    344  
    345 \item[ref]: field attribute. String referring to the id of the field we want to add in a file. 
    346  
    347 \item[size]: axis attribute. use unknown... 
    348  
    349 \item[unit]: field attribute. String defining the unit of a variable and the associated  
    350 attribute in the netcdf output file. 
    351  
    352 \item[zoom\_ref]: field attribute. String defining the subdomain of data on which  
    353 the file should be written (to ouput data only in a limited area).  
    354 It refers to the id of a zoom defined in the zoom tag. 
    355 \end{description} 
    356  
    357  
    358 \subsection{IO\_SERVER} 
    359  
    360 \subsubsection{Attached or detached mode?} 
    361  
    362 Iom\_put is based on the io\_server developed by Yann Meurdesoif from IPSL  
    363 (see \href{http://forge.ipsl.jussieu.fr/ioserver/browser}{here} for the source code or  
    364 see its copy in NEMOGCM/EXTERNAL directory).  
    365 This server can be used in ''attached mode'' (as a library) or in ''detached mode''  
    366 (as an external executable on n cpus). In attached mode, each cpu of NEMO will output  
    367 its own subdomain. In detached mode, the io\_server will gather data from NEMO  
    368 and output them split over n files with n the number of cpu dedicated to the io\_server. 
    369  
    370 \subsubsection{Control the io\_server: the namelist file xmlio\_server.def} 
    371  
    372 % 
    373 %Again, a small table might be more readable? 
    374 %Name 
    375 %Type 
    376 %Description 
    377 %Comment 
    378 %Using_server 
    379 %Logical  
    380 %Switch to use the server in attached or detached mode 
    381 %(.TRUE. corresponding to detached mode). 
    382  
    383 The control of the use of the io\_server is done through the namelist file of the io\_server  
    384 called xmlio\_server.def. 
    385  
    386 \textbf{using\_server}: logical, switch to use the server in attached or detached mode  
    387 (.TRUE. corresponding to detached mode). 
    388  
    389 \textbf{using\_oasis}: logical, set to .TRUE. if NEMO is used in coupled mode. 
    390  
    391 \textbf{client\_id} = ''oceanx'' : character, used only in coupled mode.  
    392 Specify the id used in OASIS to refer to NEMO. The same id must be used to refer to NEMO  
    393 in the \$NBMODEL part of OASIS namcouple in the call of prim\_init\_comp\_proto in cpl\_oasis3f90 
    394  
    395 \textbf{server\_id} = ''ionemo'' : character, used only in coupled mode.  
    396 Specify the id used in OASIS to refer to the IO\_SERVER when used in detached mode.  
    397 Use the same id to refer to the io\_server in the \$NBMODEL part of OASIS namcouple. 
    398  
    399 \textbf{global\_mpi\_buffer\_size}: integer; define the size in Mb of the MPI buffer used by the io\_server. 
    400  
    401 \subsubsection{Number of cpu used by the io\_server in detached mode} 
    402  
    403 The number of cpu used by the io\_server is specified only when launching the model. 
    404 Here is an example of 2 cpus for the io\_server and 6 cpu for opa using mpirun: 
    405  
    406 \texttt{ -p 2 -e ./ioserver} 
    407  
    408 \texttt{ -p 6 -e ./opa } 
    409  
    410  
    411 \subsection{Practical issues} 
    412  
    413 \subsubsection{Add your own outputs} 
    414  
    415 It is very easy to add you own outputs with iom\_put. 4 points must be followed. 
    416 \begin{description} 
    417 \item[1-] in NEMO code, add a \\ 
    418 \texttt{      CALL iom\_put( 'identifier', array ) } \\ 
    419 where you want to output a 2D or 3D array. 
    420  
    421 \item[2-] don't forget to add \\ 
    422 \texttt{   USE iom            ! I/O manager library }  \\ 
    423 in the list of used modules in the upper part of your module.  
    424  
    425 \item[3-] in the file\_definition part of the xml file, add the definition of your variable using the same identifier you used in the f90 code. 
    426 \vspace{-20pt} 
    427 \begin{alltt}  {{\scriptsize 
    428 \begin{verbatim} 
    429    <field_definition> 
    430       ... 
    431       <field id="identifier" description="blabla" />    
    432       ... 
    433    </field_definition>  
    434 \end{verbatim} 
    435 }}\end{alltt}  
    436 attributes axis\_ref and grid\_ref must be consistent with the size of the array to pass to iom\_put. 
    437 if your array is computed within the surface module each nn\_fsbc time\_step,  
    438 add the field definition within the group defined with the id ''SBC'': $<$group id=''SBC''...$>$ 
    439  
    440 \item[4-] add your field in one of the output files   \\ 
    441 \vspace{-20pt} 
    442 \begin{alltt}  {{\scriptsize 
    443 \begin{verbatim} 
    444    <file id="file_1" .../>    
    445       ... 
    446       <field ref="identifier" />    
    447       ... 
    448    </file>    
    449 \end{verbatim} 
    450 }}\end{alltt}  
    451  
    452 \end{description} 
    453  
    454 \subsubsection{Several time axes in the output file} 
    455  
    456 If your output file contains variables with different operations (see operation definition),  
    457 IOIPSL will create one specific time axis for each operation. Note that inst(X) will have  
    458 a time axis corresponding to the end each output period whereas all other operators  
    459 will have a time axis centred in the middle of the output periods. 
    460  
    461 \subsubsection{Error/bug messages from IOIPSL} 
    462  
    463 If you get the following error in the standard output file: 
    464 \vspace{-20pt} 
    465 \begin{alltt}  {{\scriptsize 
    466 \begin{verbatim} 
    467 FATAL ERROR FROM ROUTINE flio_dom_set 
    468  --> too many domains simultaneously defined  
    469  --> please unset useless domains  
    470  --> by calling flio_dom_unset  
    471 \end{verbatim} 
    472 }}\end{alltt}  
    473  
    474 You must increase the value of dom\_max\_nb in fliocom.f90 (multiply it by 10 for example).  
    475  
    476 If you mix, in the same file, variables with different freq\_op (see definition above),  
    477 like for example variables from the surface module with other variables,  
    478 IOIPSL will print in the standard output file warning messages saying there may be a bug.  
    479 \vspace{-20pt} 
    480 \begin{alltt}  {{\scriptsize 
    481 \begin{verbatim} 
    482 WARNING FROM ROUTINE histvar_seq    
    483  --> There were 10 errors in the learned sequence of variables   
    484  --> for file   4  
    485  --> This looks like a bug, please report it. 
    486 \end{verbatim} 
    487 }}\end{alltt}  
    488  
    489 Don't worry, there is no bug, everything is properly working! 
    490  
    491  %    }      %end  \gmcomment 
     669\begin{longtable}{|p{2.2cm}|p{4cm}|p{3.8cm}|p{2cm}|} 
     670   \hline 
     671   attribute name &  
     672   description &  
     673   example &  
     674   accepted by \endhead 
     675   \hline    
     676   axis\_ref &  
     677   refers to the id of a vertical axis &  
     678   axis\_ref="deptht" &  
     679   field, grid families \\  
     680   \hline    
     681   enabled &  
     682   switch on/off the output of a field or a file &  
     683   enabled=".TRUE." &  
     684   field, file families \\  
     685   \hline    
     686   default\_value &  
     687   missing\_value definition &  
     688   default\_value="1.e20" &  
     689   field family \\  
     690   \hline    
     691   description &  
     692   just for information, not used &  
     693   description="ocean T grid variables" &  
     694   all tags \\  
     695   \hline    
     696   domain\_ref &  
     697   refers to the id of a domain &  
     698   domain\_ref="grid\_T" &  
     699   field or grid families \\  
     700   \hline    
     701   field\_ref &  
     702   id of the field we want to add in a file &  
     703   field\_ref="toce" &  
     704   field \\  
     705   \hline    
     706   grid\_ref &  
     707   refers to the id of a grid &  
     708   grid\_ref="grid\_T\_2D" &  
     709   field family \\  
     710   \hline    
     711   group\_ref &  
     712   refer to a group of variables &  
     713   group\_ref="mooring" &  
     714   field\_group \\  
     715   \hline    
     716   id &  
     717   allow to identify a tag &  
     718   id="nemo" & 
     719   accepted by all tags except simulation \\  
     720   \hline    
     721   level &  
     722   output priority of a field: 0 (high) to 10 (low)&  
     723   level="1" &  
     724   field family \\  
     725   \hline    
     726   long\_name &  
     727   define the long\_name attribute in the NetCDF file &  
     728   long\_name="Vertical T levels" &  
     729   field \\  
     730   \hline    
     731   min\_digits &  
     732   specify the minimum of digits used in the core number in the name of the NetCDF file &  
     733   min\_digits="4" &  
     734   file family \\  
     735   \hline    
     736   name &  
     737   name of a variable or a file. If the name of a file is undefined, its id is used as a name &  
     738   name="tos" &  
     739   field or file families \\  
     740   \hline    
     741   name\_suffix &  
     742   suffix to be inserted after the name and before the cpu number and the ''.nc'' termination of a file &  
     743   name\_suffix="\_myzoom" &  
     744   file family \\  
     745   \hline    
     746   attribute name &  
     747   description &  
     748   example &  
     749   accepted by \\  
     750   \hline    
     751   \hline    
     752   operation &  
     753   type of temporal operation: average, accumulate, instantaneous, min, max and once &  
     754   operation="average" &  
     755   field family \\  
     756   \hline    
     757   output\_freq &  
     758   operation frequency. units can be ts (timestep), y, mo, d, h, mi, s. &  
     759   output\_freq="1d12h" &  
     760   field family \\  
     761   \hline    
     762   output\_level &  
     763   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. &   
     764   output\_level="10"&  
     765   file family \\  
     766   \hline    
     767   positive &  
     768   convention used for the orientation of vertival axis (positive downward in \NEMO). &  
     769   positive="down" &  
     770   axis family \\  
     771   \hline    
     772   prec &  
     773   output precision: real 4 or real 8 &  
     774   prec="4" &  
     775   field family \\  
     776   \hline    
     777   split\_freq &  
     778   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.&  
     779   split\_freq="1mo" &  
     780   file family \\  
     781   \hline    
     782   split\_freq\-\_format &  
     783   date format used in the name of temporally split output files. Can be specified  
     784   using the following syntaxes: \%y, \%mo, \%d, \%h \%mi and \%s &  
     785   split\_freq\_format= "\%y\%mo\%d" &  
     786   file family \\  
     787   \hline    
     788   src &  
     789   allow to include a file &  
     790   src="./field\_def.xml" &  
     791   accepted by all tags except simulation \\  
     792   \hline    
     793   standard\_name &  
     794   define the standard\_name attribute in the NetCDF file &  
     795   standard\_name= "Eastward\_Sea\_Ice\_Transport" &  
     796   field \\  
     797   \hline    
     798   sync\_freq &  
     799   NetCDF file synchronization frequency (update of the time\_counter). units can be ts (timestep), y, mo, d, h, mi, s. &  
     800   sync\_freq="10d" &  
     801   file family \\  
     802   \hline    
     803   attribute name &  
     804   description &  
     805   example &  
     806   accepted by \\  
     807   \hline    
     808   \hline    
     809   time\_origin &  
     810   specify the origin of the time counter &  
     811   time\_origin="1900-01-01 00:00:00"&  
     812   context \\  
     813   \hline    
     814   type (1)&  
     815   specify if the output files are to be split spatially (multiple\_file) or not (one\_file) &  
     816   type="multiple\_file" &  
     817   file familly \\  
     818   \hline    
     819   type (2)&  
     820   define the type of a variable tag &  
     821   type="boolean" &  
     822   variable \\  
     823   \hline    
     824   unit &  
     825   unit of a variable or the vertical axis &  
     826   unit="m" &  
     827   field and axis families \\  
     828   \hline    
     829   zoom\_ibegin &  
     830   starting point along x direction of the zoom. Automatically defined for TAO/RAMA/PIRATA moorings &  
     831   zoom\_ibegin="1" &  
     832   domain family \\  
     833   \hline    
     834   zoom\_jbegin &  
     835   starting point along y direction of the zoom. Automatically defined for TAO/RAMA/PIRATA moorings &  
     836   zoom\_jbegin="1" &  
     837   domain family \\  
     838   \hline    
     839   zoom\_ni &  
     840   zoom extent along x direction &  
     841   zoom\_ni="1" &  
     842   domain family \\  
     843   \hline    
     844   zoom\_nj &  
     845   zoom extent along y direction &  
     846   zoom\_nj="1" &  
     847   domain family \\  
     848   \hline    
     849\end{longtable} 
     850 
    492851 
    493852 
    … …  
    544903domain size in any dimension. The algorithm used is: 
    545904 
     905\vspace{-20pt} 
    546906\begin{alltt}  {{\scriptsize  
    547907\begin{verbatim} 
Note: See TracChangeset for help on using the changeset viewer.