Changeset 3976


Ignore:
Timestamp:
2013-07-16T11:28:29+02:00 (7 years ago)
Author:
acc
Message:

Refinement of XIOS documentation (#1122). More still to come soonso pdf file is not yet updated. Meanwhile, see ticket wiki page for a PDF of the modified chapter.

Location:
trunk/DOC
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/DOC/NEMO_book.tex

    r3294 r3976  
    2323\usepackage[margin=10pt,font={small},labelsep=colon,labelfont={bf}]{caption} % Gives small font for captions 
    2424\usepackage{enumitem}                          % allows non-bold description items 
     25\usepackage{longtable}                         % allows multipage tables 
    2526%\usepackage{colortbl}                           % gives coloured panels behind table columns 
    2627 
  • trunk/DOC/TexFiles/Chapters/Chap_DIA.tex

    r3940 r3976  
    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 By default, outpout files are written in NetCDF format but an IEEE output format, called DIMG, can be choosen when defining \key{dimgout}. Since 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 outputted 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 next section. If neither \key{iomput} nor \key{dimgout} are defined, NEMO is producing NetCDF with the old IOIPSL library which has been kept for compatibility and its easy installation, but it is quite inefficient on parrallel machines. If \key{iomput} is not defined, output files are defined in the \mdl{diawri} module and containing mean (or instantaneous if \key{diainstant} is defined) values over a period of nn\_write time-step (namelist parameter).  
     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).  
    3440 
    3541%\gmcomment{                    % start of gmcomment 
     
    4248 
    4349 
    44 Since version 3.2, iomput is the NEMO output interface. It was designed to be simple to use, flexible and efficient. The two main purposes of iomput are: \\ 
    45 (1) the complete and flexible control of the output files through an external xml file defined by the user \\ 
    46 (2) to achieve high performance outputs through the distribution (or not) of all tasks related to output files on dedicated processes. \\ 
    47 The first functionality allows the user to specify, without touching anything into the code, the way he want to output data: \\ 
    48 - choice of output frequencies that can be different for each file (including real months and years) \\ 
    49 - choice of file contents: decide which data will be written in which file (the same data can be outputted in different files)  \\ 
    50 - possibility to split output files at a choosen frequency \\ 
    51 - possibility to extract a vertical or an horizontal subdomain  \\ 
    52 - choice of the temporal operation to perform: average, accumulate, instantaneous, min, max and once  \\ 
    53 - extremely large choice of data available   \\ 
    54 - redefine variables name and long\_name  \\ 
    55 In addition, iomput allows the user to output any variable (scalar, 2D or 3D) in the code in a very easy way. All details of iomput functionalities are listed in the following subsections. Example of the iodef.xml files that control the outputs can be found here: NEMOGCM/CONFIG/ORCA2\_LIM/EXP00/iodef*.xml 
    56  
    57 The second functionality targets outputs performances when running on a very large number of processes. First, iomput provides the possibility to dedicate N specific processes (in addition to NEMO processes) to write the outputs, where N is big enough (and defined by the user) to suppress the bottle neck associated with the the writing of the output files. Since version 3.5, this interface depends on an external code called \href{http://forge.ipsl.jussieu.fr/ioserver}{XIOS}. This new IO server takes advantage of the new functionalitiy of NetCDF4 that allows the user to write files in parallel and therefore to bypass the rebuilding phase. Note that writting 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 trough xios are incompatible with NetCDF3. All post-processsing and visualization tools must therefore be compatible with NetCDF4 and not only NetCDF3. 
    58  
    59 \subsection{Basic knowledge} 
    60  
     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} 
    61191 
    62192\subsubsection{ XML basic rules} 
     
    72202 
    73203The 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): 
    74 \begin{description} 
    75 \item[root]: declaration of the root element that can contain element groups or elements, for example : $<$file\_definition ...$/>$ \\ 
    76 \item[group]: declaration of a group element that can contain element groups or elements, for example : $<$file\_group ...$/>$ \\ 
    77 \item[element]: declaration of an element that can contain elements, for example : $<$file ...$/>$  \\ 
    78 \end{description} 
     204\\ 
     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\\ 
    79226 
    80227Each 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. 
    81228 
    82 The 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): 
    83 \begin{description} 
    84 \item[contex xios]: context containing informations for XIOS \\ 
    85 \verb?   <context id="xios" ... ?  
    86 \item[context nemo]: contex containing IO informations for NEMO (mother grid when using AGRIF) \\ 
    87 \verb?   <context id="nemo" ... ?  
    88 \item[context 1\_nemo]: contex containing IO informations for NEMO child grid 1 (when using AGRIF) \\ 
    89 \verb?   <context id="1_nemo" ... ?   
    90 \item[context n\_nemo]: contex containing IO informations for NEMO child grid n (when using AGRIF) \\ 
    91 \verb?   <context id="n_nemo" ... ? 
    92 \end{description} 
    93  
    94 Each context tag related to NEMO (mother or child grids) is divided into 5 parts (that can be defined in any order): 
    95 \begin{description} 
    96 \item[field definition]: define all variables that can potentially be outputted \\ 
    97 \verb?   <field_definition ... ? 
    98 \item[file definition]: define the netcdf files to be created and the variables they will contain \\ 
    99 \verb?   <file_definition ... ?  
    100 \item[axis definitions]: define vertical axis \\ 
    101 \verb?   <axis_definition ... ? 
    102 \item[domain definitions]: define the horizontal grids \\ 
    103 \verb?   <domain_definition ... ? 
    104 \item[grid definitions]: define the 2D and 3D grids (association of an axis and a domain) \\ 
    105 \verb?   <grid_definition ... ?  
    106 \end{description} 
    107  
    108 the xios context contains only 1 tag: 
    109 \begin{description} 
    110 \item[variable definition]: define variables needed by xios. This can be seen as a kind of namelist for xios. \\ 
    111 \verb?   <variable_definition ... ?  
    112 \end{description} 
    113  
    114 The XML file can be split in different parts to improve its readability and facilitate its use. The inclusing of XML files into the main XML file can be done through the attribute src: \\ 
    115 \verb?   <context src="./nemo_def.xml" /> ?  
    116 In NEMO, by default, the field and domain définition is done in 2 séparate files: \\ 
    117 NEMOGCM/CONFIG/SHARED/field\_def.xml and \\ 
    118 NEMOGCM/CONFIG/SHARED/domain\_def.xml that are included in the main iodef.xml file through the following commands: \\ 
    119 \verb?   <field_definition src="./field_def.xml" /> ? \\ 
    120 \verb?   <domain_definition src="./domain_def.xml" /> ?  
     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" /> ? } 
    121321 
    122322 
    123323\subsubsection{Use of inheritance} 
    124324 
    125 XML extensively uses the concept of inheritance. XML has a based tree 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.  \\ 
     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.  \\ 
    126326\\ 
    127 example 1: Direct inheritance. \\ 
     327example 1: Direct inheritance. 
     328\vspace{-20pt} 
    128329\begin{alltt}  {{\scriptsize     
    129330\begin{verbatim} 
    130331   <field_definition operation="average" > 
    131       <field id="sst"                    />   <!-- averaged      sst -->  
    132       <field id="sss" operation="instant"/>   <!-- instantaneous sss -->  
     332     <field id="sst"                    />   <!-- averaged      sst -->  
     333     <field id="sss" operation="instant"/>   <!-- instantaneous sss -->  
    133334   </field_definition>  
    134335\end{verbatim} 
     
    140341for example output instantaneous values instead of average values. \\ 
    141342\\ 
    142 example 2: Inheritance by reference. \\ 
     343example 2: Inheritance by reference. 
     344\vspace{-20pt} 
    143345\begin{alltt}  {{\scriptsize 
    144346\begin{verbatim} 
    145347   <field_definition> 
    146       <field id="sst" long_name="sea surface temperature" />    
    147       <field id="sss" long_name="sea surface salinity"    />   
     348     <field id="sst" long_name="sea surface temperature" />    
     349     <field id="sss" long_name="sea surface salinity"    />   
    148350   </field_definition>       
    149351 
    150352   <file_definition> 
    151       <file id="myfile" output_freq="1d" />    
    152             <field field_ref="sst"                            />  <!-- default def --> 
    153             <field field_ref="sss" long_name="my description" />  <!-- overwrite   --> 
    154       </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>    
    155357   </file_definition>  
    156358\end{verbatim} 
    157359}}\end{alltt}  
    158 Inherite (and overwrite, if needed) the attributes of a tag you are refering to. 
    159  
    160 \subsubsection{Use of Group} 
    161  
    162 Groups can be used fort 2 purposes. \\ 
    163  
    164 First, the group can be used to define common attributes to be shared by the elements of the group through the 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''. 
     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 the 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} 
    165366\begin{alltt}  {{\scriptsize 
    166367\begin{verbatim} 
    167368   <field_group id="grid_T" grid_ref="grid_T_2D"> 
    168       <field id="toce" long_name="temperature"             unit="degC" grid_ref="grid_T_3D"/> 
    169       <field id="sst"  long_name="sea surface temperature" unit="degC"                     /> 
    170       <field id="sss"  long_name="sea surface salinity"    unit="psu"                      /> 
    171       <field id="ssh"  long_name="sea surface height"      unit="m"                        /> 
     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"                        /> 
    172373         ... 
    173374\end{verbatim} 
    174375}}\end{alltt}  
    175376 
    176 Second, 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 \\ 
    177 NEMOGCM/CONFIG/SHARED/field\_def.xml. For example, a short list of usual variables related to the U grid: 
     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} 
    178379\begin{alltt}  {{\scriptsize 
    179380\begin{verbatim} 
    180381   <field_group id="groupU" > 
    181       <field field_ref="uoce"  /> 
    182       <field field_ref="suoce" /> 
    183       <field field_ref="utau"  /> 
     382    <field field_ref="uoce"  /> 
     383    <field field_ref="suoce" /> 
     384    <field field_ref="utau"  /> 
    184385   </field_group> 
    185386\end{verbatim} 
    186387}}\end{alltt}  
    187 that can be directly include in a file through the following syntaxe: 
     388that can be directly include in a file through the following syntax: 
     389\vspace{-20pt} 
    188390\begin{alltt}  {{\scriptsize 
    189391\begin{verbatim} 
    190392   <file id="myfile_U" output_freq="1d" />    
    191       <field_group group_ref="groupU"/>   
    192       <field field_ref="uocetr_eff"  />  <!-- add another field --> 
     393    <field_group group_ref="groupU"/>   
     394    <field field_ref="uocetr_eff"  />  <!-- add another field --> 
    193395   </file>    
    194396\end{verbatim} 
     
    197399\subsection{Detailed functionalities } 
    198400 
    199 The file NEMOGCM/CONFIG/ORCA2\_LIM/iodef\_demo.xml provides several examples of the use of the new functionalities offered by the XML interface of XIOS.  
     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.  
    200402 
    201403\subsubsection{Define horizontal subdomains} 
    202 Horizontal 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 NEMOGCM/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). 
     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} 
    203406\begin{alltt}  {{\scriptsize 
    204407\begin{verbatim} 
    205408   <domain_group id="grid_T"> 
    206       <domain id="myzoom" zoom_ibegin="10" zoom_jbegin="10" zoom_ni="5" zoom_nj="5" /> 
     409    <domain id="myzoom" zoom_ibegin="10" zoom_jbegin="10" zoom_ni="5" zoom_nj="5" /> 
    207410\end{verbatim} 
    208411}}\end{alltt}  
    209412The use of this subdomain is done through the redefinition of the attribute domain\_ref of the tag family field. For example: 
     413\vspace{-20pt} 
    210414\begin{alltt}  {{\scriptsize 
    211415\begin{verbatim} 
     
    216420}}\end{alltt}  
    217421Moorings 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} 
    218423\begin{alltt}  {{\scriptsize 
    219424\begin{verbatim} 
     
    227432\subsubsection{Define vertical zooms} 
    228433Vertical 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} 
    229435\begin{alltt}  {{\scriptsize 
    230436\begin{verbatim} 
     
    235441}}\end{alltt}  
    236442The 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} 
    237444\begin{alltt}  {{\scriptsize 
    238445\begin{verbatim} 
     
    246453 
    247454The output file names are defined by the attributs ''name'' and ''name\_suffix'' of the tag family file. for example: 
     455\vspace{-20pt} 
    248456\begin{alltt}  {{\scriptsize 
    249457\begin{verbatim} 
     
    258466\end{verbatim} 
    259467}}\end{alltt}  
    260 However it is also often very convienent to define the file name with the name of the experience, 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 section or mooring (see next subsection), the following part of the name and the name\_suffix (that can be inherited) will be automatically replaced by: \\ 
     468However it is often very convienent to define the file name with the name of the experience, 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 section or mooring (see next subsection), the following part of the name and the name\_suffix (that can be inherited) will be automatically replaced by:\\ 
    261469\\ 
    262470\begin{tabular}{|p{4cm}|p{8cm}|} 
    263471   \hline 
    264    \centering part of the name automatically to be replaced & 
    265    by \\ 
     472   \centering placeholder string & automatically  replaced by \\ 
    266473   \hline 
    267474   \hline 
     
    284491   ending date of the simulation (from nn\_date0 and nn\_itend in the namelist). \verb?yyyymmdd_hh:mm:ss? format \\ 
    285492   \hline 
    286 \end{tabular} 
     493\end{tabular}\\ 
    287494\\ 
    288495 
    289 For example,  
    290  
    291 \begin{alltt}  {{\scriptsize 
     496\noindent For example,  
     497{{\scriptsize 
    292498\begin{verbatim} 
    293499   <file id="myfile_hzoom" name="myfile_@expname@_@startdate@_freq@freq@" output_freq="1d" > 
    294500\end{verbatim} 
    295 }}\end{alltt}  
    296  
    297 With, in the namelist: 
    298  
    299 \begin{alltt}  {{\scriptsize 
     501}} 
     502\noindent with the namelist: 
     503{{\scriptsize 
    300504\begin{verbatim} 
    301505   cn_exp      =  "ORCA2" 
     
    303507   ln_rstart   = .false. 
    304508\end{verbatim} 
    305 }}\end{alltt}  
    306  
    307 will give the following file name radical: 
    308  
    309 \begin{alltt}  {{\scriptsize 
     509}} 
     510\noindent will give the following file name radical: 
     511{{\scriptsize 
    310512\begin{verbatim} 
    311513   myfile_ORCA2_19891231_freq1d  
    312514\end{verbatim} 
    313 }}\end{alltt}  
    314  
     515}} 
    315516 
    316517\subsubsection{Other controls of the xml attributes from NEMO} 
    317518 
    318 The values of some attributes are automatically defined by NEMO (and any definition given in the xml file is overwritten). By convention, these attributes are defined to ''auto'' (for string) or ''0000'' (for integer) in the xml file (but this is not necessary).  
    319  
    320 Here is the list of these attributes: \\ 
     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:\\ 
    321522\\ 
    322523\begin{tabular}{|l|c|c|c|} 
     
    343544 
    344545 
     546\subsection{XML reference tables} 
     547 
    345548\subsubsection{Tag list} 
    346549 
    347  
    348 \begin{tabular}{|p{2cm}|p{2.5cm}|p{3.5cm}|p{2cm}|p{2cm}|} 
     550\begin{longtable}{|p{2.2cm}|p{2.5cm}|p{3.5cm}|p{2.2cm}|p{1.6cm}|} 
    349551   \hline 
    350552   tag name &  
     
    352554   accepted attribute &  
    353555   child of & 
    354    parent of \\ 
    355    \hline    
     556   parent of \endhead 
    356557   \hline    
    357558   simulation &  
     
    362563   \hline    
    363564   context & 
    364    encapsulates parts of the xml file dédicated to different codes or different parts of a code & 
     565   encapsulates parts of the xml file dedicated to different codes or different parts of a code & 
    365566   id (''xios'', ''nemo'' or ''n\_nemo'' for the nth AGRIF zoom), src, time\_origin & 
    366567   simulation & 
    367    all root tags: ...\_definition \\ 
     568   all root tags: ... \_definition \\ 
    368569   \hline    
    369570   \hline    
     
    400601   \hline    
    401602   file &  
    402    defile the contentof a file to be outputted & 
     603   define the contents of a file to be outputted & 
    403604   enabled, description, id, min\_digits, name, name\_suffix, output\_freq, output\_level, split\_format, split\_freq, sync\_freq, type, src & 
    404605   file\_definition, file\_group &  
    405606   field \\ 
    406    \hline    
    407 \end{tabular} 
    408 \begin{tabular}{|p{2cm}|p{2.5cm}|p{3.5cm}|p{2cm}|p{2cm}|} 
    409    \hline 
    410    tag name &  
    411    description &  
    412    accepted attribute &  
    413    child of & 
    414    parent of \\ 
    415    \hline    
    416607   \hline    
    417608   axis\_definition &  
     
    434625   \hline    
    435626   \hline    
    436    domain\_definition &  
     627   domain\_\-definition &  
    437628   define all the horizontal domains potentially used by the variables & 
    438629   src & 
    439630   context &  
    440    domain\_group, domain \\ 
     631   domain\_\-group, domain \\ 
    441632   \hline    
    442633   domain\_group &  
    443634   encapsulates a group of horizontal domains & 
    444635   id, lon\_name, src, zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj & 
    445    domain\_definition, domain\_group &  
    446    domain\_group, domain \\ 
     636   domain\_\-definition, domain\_group &  
     637   domain\_\-group, domain \\ 
    447638   \hline    
    448639   domain &  
    449640   define an horizontal domain & 
    450641   id, lon\_name, src, zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj & 
    451    domain\_definition, domain\_group &  
     642   domain\_\-definition, domain\_group &  
    452643   none \\ 
    453644   \hline    
     
    471662   none \\ 
    472663   \hline    
    473 \end{tabular} 
     664\end{longtable} 
    474665 
    475666 
    476667\subsubsection{Attributes list} 
    477668 
    478 \begin{tabular}{|p{2cm}|p{4cm}|p{4cm}|p{2cm}|} 
    479    \hline 
     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    
    480746   attribute name &  
    481747   description &  
     
    484750   \hline    
    485751   \hline    
    486    axis\_ref &  
    487    refers to the id of a vertical axis &  
    488    axis\_ref="deptht" &  
    489    field, grid families \\  
    490    \hline    
    491    enabled &  
    492    switch on/off the output of a field or a file &  
    493    enabled=".TRUE." &  
    494    field, file families \\  
    495    \hline    
    496    default\_value &  
    497    missing\_value definition &  
    498    default\_value="1.e20" &  
     752   operation &  
     753   type of temporal operation: average, accumulate, instantaneous, min, max and once &  
     754   operation="average" &  
    499755   field family \\  
    500756   \hline    
    501    description &  
    502    just for information, not used &  
    503    description="ocean T grid variables" &  
    504    all tags \\  
    505    \hline    
    506    domain\_ref &  
    507    refers to the id of a domain &  
    508    domain\_ref="grid\_T" &  
    509    field or grid families \\  
    510    \hline    
    511    field\_ref= &  
    512    id of the field we want to add in a file &  
    513    field\_ref="toce" &  
     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\_format &  
     778   date format used in the name of splitted output files. can be spécified using the following syntaxe: \%y, \%mo, \%d, \%h \%mi and \%s &  
     779   split\_format= "\%yy\%mom\%dd" &  
     780   file family \\  
     781   \hline    
     782   split\_freq &  
     783   split output files frequency. units can be ts (timestep), y, mo, d, h, mi, s. &  
     784   split\_freq="1mo" &  
     785   file family \\  
     786   \hline    
     787   src &  
     788   allow to include a file &  
     789   src="./field\_def.xml" &  
     790   accepted by all tags except simulation \\  
     791   \hline    
     792   standard\_name &  
     793   define the standard\_name attribute in the NetCDF file &  
     794   standard\_name= "Eastward\_Sea\_Ice\_Transport" &  
    514795   field \\  
    515796   \hline    
    516    grid\_ref &  
    517    refers to the id of a grid &  
    518    grid\_ref="grid\_T\_2D" &  
    519    field family \\  
    520    \hline    
    521    group\_ref &  
    522    refer to a group of variables &  
    523    group\_ref="mooring" &  
    524    field\_group \\  
    525    \hline    
    526    id &  
    527    allow to identify a tag &  
    528    id="nemo" & 
    529    accepted by all tags except simulation \\  
    530    \hline    
    531    level &  
    532    output priority of a field: 0 (high) to 10 (low)&  
    533    level="1" &  
    534    field family \\  
    535    \hline    
    536    long\_name &  
    537    define the long\_name attribute in the NetCDF file &  
    538    long\_name="Vertical T levels" &  
    539    field \\  
    540    \hline    
    541    min\_digits &  
    542    specify the minimum of digits used in the core number in the name of the NetCDF file &  
    543    min\_digits="4" &  
     797   sync\_freq &  
     798   NetCDF file synchronization frequency (update of the time\_counter). units can be ts (timestep), y, mo, d, h, mi, s. &  
     799   sync\_freq="10d" &  
    544800   file family \\  
    545801   \hline    
    546    name &  
    547    name of a variable or a file. If the name of a file is undefined, its id is used as a name &  
    548    name="tos" &  
    549    field or file families \\  
    550    \hline    
    551    name\_suffix &  
    552    suffix to be inserted after the name and before the cpu number and the ''.nc'' termination of a file &  
    553    name\_suffix="\_myzoom" &  
    554    file family \\  
    555    \hline    
    556 \end{tabular} 
    557 \begin{tabular}{|p{2cm}|p{4cm}|p{4cm}|p{2cm}|} 
    558    \hline 
    559802   attribute name &  
    560803   description &  
     
    563806   \hline    
    564807   \hline    
    565    operation &  
    566    type of temporal operation: average, accumulate, instantaneous, min, max and once &  
    567    operation="average" &  
    568    field family \\  
    569    \hline    
    570    output\_freq &  
    571    operation frequency. units can be ts (timestep), y, mo, d, h, mi, s. &  
    572    output\_freq="1d12h" &  
    573    field family \\  
    574    \hline    
    575    output\_level &  
    576    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. &   
    577    output\_level="10"&  
    578    file family \\  
    579    \hline    
    580    positive &  
    581    convention used for the orientation of vertival axis (positive downward in \NEMO). &  
    582    positive="down" &  
    583    axis family \\  
    584    \hline    
    585    prec &  
    586    output precision: real 4 or real 8 &  
    587    prec="4" &  
    588    field family \\  
    589    \hline    
    590    split\_format &  
    591    date format used in the name of splitted output files. can be spécified using the following syntaxe: \%y, \%mo, \%d, \%h \%mi and \%s &  
    592    split\_format="\%yy\%mom\%dd" &  
    593    file family \\  
    594    \hline    
    595    split\_freq &  
    596    split output files frequency. units can be ts (timestep), y, mo, d, h, mi, s. &  
    597    split\_freq="1mo" &  
    598    file family \\  
    599    \hline    
    600    src &  
    601    allow to include a file &  
    602    src="./field\_def.xml" &  
    603    accepted by all tags except simulation \\  
    604    \hline    
    605    standard\_name &  
    606    define the standard\_name attribute in the NetCDF file &  
    607    standard\_name="Eastward\_Sea\_Ice\_Transport" &  
    608    field \\  
    609    \hline    
    610    sync\_freq &  
    611    NetCDF file synchronization frequency (update of the time\_counter). units can be ts (timestep), y, mo, d, h, mi, s. &  
    612    sync\_freq="10d" &  
    613    file family \\  
    614    \hline    
    615 \end{tabular} 
    616 \begin{tabular}{|p{2cm}|p{4cm}|p{4cm}|p{2cm}|} 
    617    \hline 
    618    attribute name &  
    619    description &  
    620    example &  
    621    accepted by \\  
    622    \hline    
    623    \hline    
    624808   time\_origin &  
    625809   specify the origin of the time counter &  
     
    628812   \hline    
    629813   type (1)&  
    630    specify if the output files must be splitted (multiple\_file) or not (one\_file) &  
     814   specify if the output files must be split (multiple\_file) or not (one\_file) &  
    631815   type="multiple\_file" &  
    632816   file familly \\  
     
    662846   domain family \\  
    663847   \hline    
    664 \end{tabular} 
    665  
    666 \subsection{XIOS: the IO\_SERVER} 
    667  
    668 \subsubsection{Attached or detached mode?} 
    669  
    670 Iomput is based on \href{http://forge.ipsl.jussieu.fr/ioserver/wiki}{XIOS}, the io\_server developed by Yann Meurdesoif from IPSL. This server can be used in ''attached mode'' (as a library) or in ''detached mode'' (as an external executable on n cpus). The ''attached mode'' is simpler to use but much less efficient. If the type of file is ''multiple\_file'', then in attached(detached) mode, each NEMO(XIOS) process will output its own subdomain: if NEMO(XIOS) is runnning on N cores, the ouput files will be splitted into N files. If the type of file is ''one\_file'', the output files will be directly recombined into one unique file either in ''detached mode'' or ''attached mode''.   
    671  
    672 \subsubsection{Control of xios: the xios context in iodef.xml} 
    673  
    674 The control of the use of xios is done through the xios context in iodef.xml. 
    675  
    676 \begin{tabular}{|p{3cm}|p{6.5cm}|p{2.5cm}|} 
    677    \hline 
    678    variable name &  
    679    description &  
    680    example \\  
    681    \hline    
    682    \hline 
    683    buffer\_size &  
    684    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 &  
    685    25000000 \\  
    686    \hline    
    687    buffer\_server\_factor\_size &  
    688    ratio between NEMO and XIOS buffer size. Should be 2. &  
    689    2 \\  
    690    \hline 
    691    info\_level &  
    692    verbosity level (0 to 100) &  
    693    0 \\  
    694    \hline 
    695    using\_server &  
    696    activate attached(false) or detached(true) mode &  
    697    true \\  
    698    \hline 
    699    using\_oasis &  
    700    xios is used with OASIS(true) or not (false) &  
    701    false \\  
    702    \hline 
    703    oasis\_codes\_id &  
    704    when using oasis, define the identifier of NEMO in the namcouple. Not that the identifier of XIOS is xios.x &  
    705    oceanx \\  
    706    \hline    
    707 \end{tabular} 
    708  
    709 \subsubsection{Number of cpu used by XIOS in detached mode} 
    710  
    711 The number of cores used by the xios is specified only when launching the model. The number or cores dedicated to XIOS should be from ~1/10 to ~1/50 of the number or cores dedicated to NEMO (according of the amount of data to be created). Here is an example of 2 cpus for the io\_server and 62 cpu for opa using mpirun: 
    712  
    713 \texttt{ mpirun -np 2 ./nemo.exe : -np 62 ./xios\_server.exe } 
    714  
    715 \subsection{Practical issues} 
    716  
    717 \subsubsection{Add your own outputs} 
    718  
    719 It is very easy to add you own outputs with iomput. 4 points must be followed. 
    720 \begin{description} 
    721 \item[1-] in NEMO code, add a \\ 
    722 \texttt{      CALL iom\_put( 'identifier', array ) } \\ 
    723 where you want to output a 2D or 3D array. 
    724  
    725 \item[2-] don't forget to add \\ 
    726 \texttt{   USE iom            ! I/O manager library }  \\ 
    727 in the list of used modules in the upper part of your module.  
    728  
    729 \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. 
    730 \vspace{-20pt} 
    731 \begin{alltt}  {{\scriptsize 
    732 \begin{verbatim} 
    733    <field_definition> 
    734       ... 
    735       <field id="identifier" long_name="blabla" ... />    
    736       ... 
    737    </field_definition>  
    738 \end{verbatim} 
    739 }}\end{alltt}  
    740 attributes axis\_ref and grid\_ref must be consistent with the size of the array to pass to iomput. 
    741 if your array is computed within the surface module each nn\_fsbc time\_step,  
    742 add the field definition within the group defined with the id ''SBC'': $<$group id=''SBC''...$>$ 
    743  
    744 \item[4-] add your field in one of the output files   \\ 
    745 \vspace{-20pt} 
    746 \begin{alltt}  {{\scriptsize 
    747 \begin{verbatim} 
    748    <file id="file1" .../>    
    749       ... 
    750       <field ref="identifier" />    
    751       ... 
    752    </file>    
    753 \end{verbatim} 
    754 }}\end{alltt}  
    755  
    756 \end{description} 
     848\end{longtable} 
     849 
    757850 
    758851 
     
    809902domain size in any dimension. The algorithm used is: 
    810903 
     904\vspace{-20pt} 
    811905\begin{alltt}  {{\scriptsize  
    812906\begin{verbatim} 
Note: See TracChangeset for help on using the changeset viewer.