chap_DIA.tex

\documentclass[../main/NEMO_manual]{subfiles}

\begin{document}

\chapter{Output and Diagnostics (IOM, DIA, TRD, FLO)}
\label{chap:DIA}

%    {\em 4.0} & {\em Mirek Andrejczuk, Massimiliano Drudi} & {\em }  \\
%    {\em }      & {\em Dorotea Iovino, Nicolas Martin} & {\em }  \\
%    {\em 3.6} & {\em Gurvan Madec, Sebastien Masson } & {\em }  \\
%    {\em 3.4} & {\em Gurvan Madec, Rachid Benshila, Andrew Coward } & {\em }  \\
%    {\em }      & {\em Christian Ethe, Sebastien Masson } & {\em }  \\

\chaptertoc

\paragraph{Changes record} ~\\

{\footnotesize
  \begin{tabularx}{\textwidth}{l||X|X}
    Release & Author(s) & Modifications \\
    \hline
    {\em   4.0} & {\em ...} & {\em ...} \\
    {\em   3.6} & {\em ...} & {\em ...} \\
    {\em   3.4} & {\em ...} & {\em ...} \\
    {\em <=3.4} & {\em ...} & {\em ...}
  \end{tabularx}
}

\clearpage

%% =================================================================================================
\section{Model output}
\label{sec:DIA_io_old}

The model outputs are of three types: the output log/progress listings; 
the diagnostic output file(s); and the restart file(s)


The output listing and file(s) are predefined but should be checked and eventually adapted
to the user's needs. The output listing is stored in the \textit{ocean.output} file. The
information is printed from within the code on the logical unit \texttt{numout}. To
locate these prints, use the UNIX command "\textit{grep -i numout}" in the source code
directory. The \textit{ocean.output} file is the first place to check if something appears
to have gone wrong with the model since any detectable errors will be reported here.
Additional progress information can be requested using the options explained in
\autoref{subsec:MISC_statusinfo}.

Diagnostic output files are written in NetCDF format and the structure of legacy output files is predefined.
The legacy output files contain by default the time averaged fields, but by activating the macro \key{diainstant} 
it is possible to switch the full output to the instantaneous time value. 
When compiled with \key{xios}, \NEMO\ can employ the full capability of an I/O server (XIOS)
which provides flexibility in the choice of the fields to be written as well as how the writing tasks are distributed
over the processors in a massively parallel computing environment. A complete description
of the use of this I/O server is presented in the next section.

The restart file is used by the code when the user wants to start the model with initial
conditions defined by a previous simulation.  Restart files are NetCDF files containing
all the information that is necessary in order for there to be no changes in the model
results (even at the computer precision) between a run performed with several stops and
restarts and the same run performed in one continuous integration step.  It should be
noted that this requires that the restart file contains two consecutive time steps for all
the prognostic variables. The default behaviour of \NEMO\ is to generate a restart file
for each MPP region. These files will be read in by the same regions on restarting.
However, if a change in MPP decomposition is required, then the invidual restart files
must first be combined into a whole domain restart file. This can be done using the
\forcode{REBUILD_NEMO} tool.  Alternatively, users may experiment with the new options in
4.2 to write restarts via XIOS (see \autoref{subsec:XIOS_restarts}) with which it is possible to
write a whole domain restart file from a running model.

%% =================================================================================================
\section{Standard model output (\texttt{iom\_put})}
\label{sec:DIA_iom}

Since version 3.2, \rou{iom\_put} is the \NEMO\ output interface of choice.
It has been designed to be simple to use, flexible and efficient.
The two main purposes of \rou{iom\_put} are:

\begin{enumerate}
\item The complete and flexible control of the output files through external XML files adapted by
  the user from standard templates.
\item To achieve high performance and scalable output through the optional distribution of
  all diagnostic output related tasks to dedicated processes.
\end{enumerate}

\noindent The first functionality allows the user to specify, without code changes or recompilation,
aspects of the diagnostic output stream, such as:

\begin{itemize}
\item The choice of output frequencies that can be different for each file (including real months and years).
\item The choice of file contents; includes complete flexibility over which data are written in which files
  (the same data can be written in different files).
\item The possibility to split output files at a chosen frequency.
\item The possibility to extract a vertical or an horizontal subdomain.
\item The choice of the temporal operation to perform, \eg: average, accumulate, instantaneous, min, max and once.
\item Control over metadata via a large XML "database" of possible output fields.
\item Control over the compression and/or precision of output fields (subject to certain conditions)
\end{itemize}

\noindent In addition, \rou{iom\_put}  allows the user to add in the code the output of any new
variable (scalar, 1D, 2D or 3D) in a very easy way.  All details of \rou{iom\_put}
functionalities are listed in the following subsections.  An example of the main XML file
that control the outputs can be found in \path{cfgs/ORCA2_ICE_PISCES/EXPREF/iodef.xml}.\\

\noindent The second functionality targets output performance when running in parallel.  XIOS
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.

Since version 3.6, the \rou{iom\_put} interface depends on an external code called \XIOS, 
which is developed independently and has its own repository and support pages. Further details
are available in the \href{https://sites.nemo-ocean.io/user-guide/}{NEMO User guide}. 
Note that by default the model is interfaced with the trunk version of 
\href{https://forge.ipsl.jussieu.fr/ioserver/browser/XIOS2/trunk}{XIOS2}, but it is possible to use also 
the more recent version \href{https://forge.ipsl.jussieu.fr/ioserver/browser/XIOS3/trunk}{XIOS3} 
by adding the macro \key{xios3} in the configuration cpp file.\\

The IO server can also take advantage of the parallel I/O functionality of NetCDF4 to
create a single output file and therefore to bypass any rebuilding phase. This facility is ideal for
small to moderate size configurations but can be problematic with large models due to the large memory
requirements and the inability to use NetCDF4's compression capabilities in this "one\_file" mode.
XIOS now has the option of using two levels of I/O servers so it may be possible, in some circumstances,
to use a single I/O server at the second level to enable compression. In many cases. though, it is
often more robust to use "multiple\_file" mode (where each XIOS server writes its own file) and to
recombine these files as a post-processing step. The \forcode{REBUILD_NEMO} tool in the \forcode{tools}
directory is provided for this purpose.

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 (\ie\ with the configure option $--$enable-parallel).
Note that the files created by \rou{iom\_put} through XIOS are incompatible with NetCDF3.
All post-processsing and visualization tools must therefore be compatible with NetCDF4 and not only NetCDF3.

Even when not using the "one\_file" 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
otherwise 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.

%% =================================================================================================
\subsection{XIOS: Reading and writing restart file}
\label{subsec:XIOS_restarts}


New from version 4.2, XIOS may be used to read from a single file restart produced by \NEMO. 
This does not add a new functionality (since NEMO has long had the capability for all
processes to read their patch from a single, combined restart file) but it may be advantageous 
on systems which struggle with too many simultaneous accesses to one file.  The
variables written to file \forcode{numror} (OCE), \forcode{numrir} (SI3), \forcode{numrtr}
(TOP), \forcode{numrsr} (SED) can be handled by XIOS.  To activate restart reading using
XIOS, set \np[=.true. ]{ln_xios_read}{ln\_xios\_read} in \textit{namelist\_cfg}. This
setting will be ignored when multiple restart files are present, and default \NEMO
functionality will be used for reading. There is no need to change iodef.xml file to use
XIOS to read restart, all definitions are done within the \NEMO\ code. For high resolution
configurations, however, there may be a need to add the following line in iodef.xml (xios
context):

\begin{xmllines}
<variable id="recv_field_timeout"        type="double">1800</variable>
\end{xmllines}

\noindent This variable sets timeout for reading.

\noindent If XIOS is to be used to read restart from files generated with an earlier \NEMO\ version (3.6 for instance),
dimension \forcode{z} defined in restart file must be renamed to \forcode{nav_lev}.\\

XIOS can also be used to write \NEMO\ restarts. A namelist parameter
\np{nn_wxios}{nn\_wxios} is used to determine the type of restart \NEMO\ will write. If it
is set to 0, default \NEMO\ functionality will be used - each processor writes its own
restart file; if it is set to 1 XIOS will write restart into a single file; for
\np[=2]{nn_wxios}{nn\_wxios} the restart will be written by XIOS into multiple files, one
for each XIOS server.  Note, however, that \textbf{\NEMO\ will not read restart generated
by XIOS when \np[=2]{nn_wxios}{nn\_wxios}}. The restart will have to be rebuilt before
continuing the run. This option aims to reduce number of restart files generated by \NEMO\
only, and may be useful when there is a need to change number of processors used to run
simulation.

The use of XIOS to read and write restart files is in preparation of NEMO for exascale
computing platforms. There may not be any performance gains on current clusters but it
should reduce file system bottlenecks in any future attempts to run NEMO on hundreds of
thousands of cores.

%% =================================================================================================
\subsection{XIOS: XML Inputs-Outputs Server}

%% =================================================================================================
\subsubsection{Attached or detached mode?}

\rou{iom\_put} 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 I/O subsystem is controlled by settings in the external XML files listed above.
Key settings in the iodef.xml file are the tags associated with each defined file.

\xmlline|<variable id="using_server" type="bool"></variable>|

The \texttt{using\_server} setting determines whether or not the server will be used in
\textit{attached mode}
(as a library) [\texttt{.false.}] or in \textit{detached mode}
(as an external executable on N additional, dedicated cpus) [\texttt{.true.}].
The \textit{attached mode} is simpler to use but much less efficient for
massively parallel applications.
The type of each file can be either ''multiple\_file'' or ''one\_file''.

In \textit{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 \forcode{jpi x jpj x jpk} domain actually computed by the process (although it may if \forcode{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.

In \textit{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.

%% =================================================================================================
\subsubsection{Number of cpu used by XIOS in detached mode}

The number of cores used by the XIOS is specified when launching the model.  The number of
cores dedicated to XIOS should be from \texttildelow1/10 to \texttildelow1/50 of the
number of 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:

\begin{cmds}
  mpirun -np 62 ./nemo.exe : -np 2 ./xios_server.exe
\end{cmds}

%% =================================================================================================
\subsubsection{Control of XIOS: the context in iodef.xml}

As well as the \texttt{using\_server} flag, other controls on the use of XIOS are set in
the XIOS context in \textit{iodef.xml}.
See the XML basics section below for more details on XML syntax and rules.

\begin{table}
  \begin{tabularx}{\textwidth}{|lXl|}
    \hline
    variable name                                                           &
    description                                                             &
    example  \\
    \hline
    \hline
    info\_level                                                             &
    verbosity level (0 to 100)                                              &
    0        \\
    \hline
    using\_server                                                           &
    activate attached(false) or detached(true) mode                         &
    true     \\
    \hline
    using\_oasis                                                            &
    XIOS is used with OASIS(true) or not (false)                            &
    false    \\
    \hline
    oasis\_codes\_id                                                        &
    when using oasis, define the identifier of \NEMO\ in the namcouple.
    Note that the identifier of XIOS is xios.x                              &
    oceanx   \\
    \hline
  \end{tabularx}
\end{table}

The rest of the XML controls and definitions for XIOS-\NEMO\  interaction are contained in a series of 
XML files included via the \texttt{context\_nemo.xml} file which, is itself, included in iodef.xml. E.g.:
\begin{xmllines}
iodef.xml:           <context id="nemo" src="./context_nemo.xml"/>           <!--  NEMO                -->
context_nemo.xml:    <field_definition  src="./field_def_nemo-oce.xml"/>     <!--  NEMO ocean dynamics -->
context_nemo.xml:    <field_definition  src="./field_def_nemo-ice.xml"/>     <!--  NEMO sea-ice model  -->
context_nemo.xml:    <field_definition  src="./field_def_nemo-pisces.xml"/>  <!--  NEMO ocean biology  -->
context_nemo.xml:    <file_definition   src="./file_def_nemo-oce.xml"/>      <!--  NEMO ocean dynamics -->
context_nemo.xml:    <file_definition   src="./file_def_nemo-ice.xml"/>      <!--  NEMO sea-ice model  -->
context_nemo.xml:    <file_definition   src="./file_def_nemo-pisces.xml"/>   <!--  NEMO ocean biology  -->
context_nemo.xml:    <axis_definition   src="./axis_def_nemo.xml"/>
context_nemo.xml:    <domain_definition src="./domain_def_nemo.xml"/>
context_nemo.xml:    <grid_definition   src="./grid_def_nemo.xml"/>
\end{xmllines}
which shows the hierarchy of XML files in use by the ORCA2\_ICE\_PISCES reference configuration. This nesting
of XML files will be explained further in later sections.

%% =================================================================================================
\subsection{Practical issues}

%% =================================================================================================
\subsubsection{Installation}

As 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 \href{https://forge.ipsl.jussieu.fr/nemo/chrome/site/doc/NEMO/guide/html/install.html#extract-and-install-xios}
{Extract and install XIOS} guide provides an example illustration of how this can be achieved.

%% =================================================================================================
\subsubsection{Add your own outputs}

It is very easy to add your own outputs with iom\_put.
Many standard fields and diagnostics are already prepared (\ie, 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.

\begin{enumerate}
\item in \NEMO\ code, add a \forcode{CALL iom_put( 'identifier', array )} where you want
to output an array. In most cases, this will be in a part of the code which is executed
only once per timestep and after the array has been updated for that timestep. Note,
adding this call enables the possibility of outputing this array; whether or not and at
which frequency the values are actually written will be determined but the content of
associated XML files.
\item If necessary, add \forcode{USE iom ! I/O manager library} to the list of used
modules in the upper part of your module.
\item in the appropriate \path{cfgs/SHARED/field_def_nemo-....xml} files, add the
definition of your variable using the same identifier you used in the f90 code (see
subsequent sections for a details of the XML syntax and rules).  For example:
\begin{xmllines}
   <field_definition>
         <field_group id="grid_T" grid_ref="grid_T_3D"> <!-- T grid -->
         ...
                  <field id="identifier" long_name="blabla" ... />
                  ...
   </field_definition>
\end{xmllines}
Note your definition must be added to the field\_group whose reference grid is consistent
with the size of the array passed to \rou{iom\_put}. The grid\_ref attribute refers to
definitions set in grid\_def\_nemo.xml which, in turn, reference domains and axes either
defined in the code (iom\_set\_domain\_attr and iom\_set\_axis\_attr in \mdl{iom}) or
defined in the domain\_def\_nemo.xml and axis\_def\_nemo.xml files.  \eg:
\begin{xmllines}
  <grid id="grid_T_3D" >
    <domain domain_ref="grid_T" />
    <axis axis_ref="deptht" />
  </grid>
\end{xmllines}
Note, if your array is computed within the surface module each \np{nn_fsbc}{nn\_fsbc}
time\_step, add the field definition within the field\_group defined with the id "SBC":
\xmlcode{<field_group id="SBC" ...>} which has been defined with the correct frequency of
operations (iom\_set\_field\_attr in \mdl{iom}) \item Finally, to activate actual output,
add your field in one or more of the output files defined in file\_def\_nemo-*.xml (again
see subsequent sections for syntax and rules)
\begin{xmllines}
<file id="file1" ... />
...
   <field field_ref="identifier" />
   ...
</file>
\end{xmllines}
\end{enumerate}

%% =================================================================================================
\subsection{XML fundamentals}

%% =================================================================================================
\subsubsection{ XML basic rules}

XML tags begin with the less-than character ("$<$") and end with the greater-than character ("$>$").
You use tags to mark the start and end of elements, which are the logical units of information in an XML document.
In addition to marking the beginning of an element, XML start tags also provide a place to specify attributes.
An attribute specifies a single property for an element, using a name/value pair, for example:
\xmlcode{<a b="x" c="y" d="z"> ... </a>}.
See \href{http://www.xmlnews.org/docs/xml-basics.html}{here} for more details.

%% =================================================================================================
\subsubsection{Structure of the XML file used in \NEMO}

The 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):

\begin{table}
  \begin{tabular*}{\textwidth}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|}
    \hline
    flavor  & description                                                                 &
                                                                                            example                          \\
    \hline
    \hline
    root    & declaration of the root element that can contain element groups or elements &
                                                                                            \xmlcode{<file_definition ... >} \\
    \hline
    group   & declaration of a group element that can contain element groups or elements  &
                                                                                            \xmlcode{<file_group      ... >} \\
    \hline
    element & declaration of an element that can contain elements                         &
                                                                                            \xmlcode{<file            ... >} \\
    \hline
  \end{tabular*}
\end{table}

Each element may have several attributes.
Some attributes are mandatory, other are optional but have a default value and other 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.

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):

\begin{table}
  \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|}
    \hline
    context         &	description                                                                &
                                                                                                     example                              \\
    \hline
    \hline
    context xios    &	context containing information for XIOS                                    &
                                                                                                     \xmlcode{<context id="xios" ... >}   \\
    \hline
    context nemo    &	context containing IO information for \NEMO\ (mother grid when using AGRIF)  &
                                                                                                     \xmlcode{<context id="nemo" ... >}   \\
    \hline
    context 1\_nemo &	context containing IO information for \NEMO\ child grid 1 (when using AGRIF) &
                                                                                                     \xmlcode{<context id="1_nemo" ... >} \\
    \hline
    context n\_nemo &	context containing IO information for \NEMO\ child grid n (when using AGRIF) &
                                                                                                     \xmlcode{<context id="n_nemo" ... >} \\
    \hline
  \end{tabular}
\end{table}

\noindent The xios context contains only 1 tag:

\begin{table}
  \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|}
    \hline
    context tag                                      &
                                                       description                                      &
                                                                                                          example                              \\
    \hline
    \hline
    variable\_definition                             &
                                                       define variables needed by XIOS.
                                                       This can be seen as a kind of namelist for XIOS. &
                                                                                                          \xmlcode{<variable_definition ... >} \\
    \hline
	\end{tabular}
\end{table}

\noindent Each context tag related to \NEMO\ (mother or child grids) is divided into 5 parts
(that can be defined in any order):

\begin{table}
  \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|}
    \hline
    context tag        &	description                                                               &
                                                                                                       example                            \\
    \hline
    \hline
    field\_definition  &	define all variables that can potentially be outputted                    &
                                                                                                       \xmlcode{<field_definition ... >}  \\
    \hline
    file\_definition   &	define the netcdf files to be created and the variables they will contain &
                                                                                                       \xmlcode{<file_definition ... >}   \\
    \hline
    axis\_definition   &	define vertical axis                                                      &
                                                                                                       \xmlcode{<axis_definition ... >}   \\
    \hline
    domain\_definition &	define the horizontal grids                                               &
                                                                                                       \xmlcode{<domain_definition ... >} \\
    \hline
    grid\_definition   &	define the 2D and 3D grids (association of an axis and a domain)          &
                                                                                                       \xmlcode{<grid_definition ... >}   \\
    \hline
  \end{tabular}
\end{table}

%% =================================================================================================
\subsubsection{Nesting XML files}

The 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:
\begin{xmllines}
<context id="nemo" src="./context_nemo.xml"/>
\end{xmllines}

\noindent In \NEMO, by default, the field definition is done in 4 separate files (
\path{cfgs/SHARED/field_def_nemo-oce.xml},
\path{cfgs/SHARED/field_def_nemo-pisces.xml}, \path{cfgs/SHARED/field_def_nemo-innerttrc.xml} and
\path{cfgs/SHARED/field_def_nemo-ice.xml} ) and the grid definition is done in another 3 files (\path{cfgs/SHARED/grid_def_nemo.xml}, \path{cfgs/SHARED/axis_def_nemo.xml} and \path{cfgs/SHARED/domain_def_nemo.xml})
that
are included in each context\_nemo.xml file through the following commands:
\begin{xmllines}
<!-- Fields definition -->
    <field_definition src="./field_def_nemo-oce.xml"      />   <!--  NEMO ocean dynamics               -->
    <field_definition src="./field_def_nemo-ice.xml"      />   <!--  NEMO ocean sea ice                -->
    <field_definition src="./field_def_nemo-pisces.xml"   />   <!--  NEMO ocean biogeochemical         -->
    <field_definition src="./field_def_nemo-innerttrc.xml"/>   <!--  NEMO ocean inert passive tracer   -->

<!-- Files definition -->
    <file_definition src="./file_def_nemo-oce.xml"/>       <!--  NEMO ocean dynamics                   -->
    <file_definition src="./file_def_nemo-ice.xml"/>       <!--  NEMO ocean sea ice                    -->
    <file_definition src="./file_def_nemo-innerttrc.xml"/> <!--  NEMO ocean inert passive tracer       -->

    <axis_definition src="./axis_def_nemo.xml"/>           <!-- Axis definition -->
    <domain_definition src="./domain_def_nemo.xml"/>       <!-- Domain definition -->
    <grid_definition   src="./grid_def_nemo.xml"/>         <!-- Grids definition -->
\end{xmllines}

%% =================================================================================================
\subsubsection{Use of inheritance}

XML 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.
\\
\\
example 1: Direct inheritance.

\begin{xmllines}
<field_definition operation="average" >
     <field id="sst"                    />   <!-- averaged      sst -->
     <field id="sss" operation="instant"/>   <!-- instantaneous sss -->
</field_definition>
\end{xmllines}

\noindent The field ''sst'' which is part (or a child) of the field\_definition will inherit the value ''average'' of
the attribute ''operation'' from its parent.
Note that a child can overwrite the attribute definition inherited from its parents.
In the example above, the field ''sss'' will for example output instantaneous values instead of average values.
\\
\\
example 2: Inheritance by reference: inherit (and overwrite, if needed) the attributes of a tag you are refering to:


\begin{xmllines}
<field_definition>
   <field id="sst" long_name="sea surface temperature" />
   <field id="sss" long_name="sea surface salinity"    />
</field_definition>
<file_definition>
   <file id="myfile" output_freq="1d" />
      <field field_ref="sst"                            />  <!-- default def -->
      <field field_ref="sss" long_name="my description" />  <!-- overwrite   -->
   </file>
</file_definition>
\end{xmllines}

%% =================================================================================================
\subsubsection{Use of groups}

Groups 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''.

\begin{xmllines}
   <field_group id="grid_T" grid_ref="grid_T_2D">
   <field id="toce" long_name="temperature"             unit="degC" grid_ref="grid_T_3D"/>
   <field id="sst"  long_name="sea surface temperature" unit="degC"                     />
   <field id="sss"  long_name="sea surface salinity"    unit="psu"                      />
   <field id="ssh"  long_name="sea surface height"      unit="m"                        />
   ...
\end{xmllines}

\noindent Secondly, the group can be used to replace a list of elements.
Several examples of groups of fields are proposed at the end of the XML field files (
\path{cfgs/SHARED/field_def_nemo-oce.xml},
\path{cfgs/SHARED/field_def_nemo-pisces.xml} and
\path{cfgs/SHARED/field_def_nemo-ice.xml} ) .
For example, a short list of the usual variables related to the U grid:

\begin{xmllines}
<field_group id="groupU" >
   <field field_ref="uoce"  />
   <field field_ref="ssu" />
   <field field_ref="utau"  />
</field_group>
\end{xmllines}

\noindent that can be directly included in a file through the following syntax:

\begin{xmllines}
<file id="myfile_U" output_freq="1d" />
   <field_group group_ref="groupU" />
   <field field_ref="uocetr_eff"   />  <!-- add another field -->
</file>
\end{xmllines}

%% =================================================================================================
\subsection{Detailed functionalities}

The files \path{cfgs/ORCA2_ICE_PISCES/EXPREF/*.xml} provide several examples of the use of
the new functionalities offered by the XML interface of XIOS.

%% =================================================================================================
\subsubsection{Define horizontal subdomains}

Horizontal subdomains are defined through the attributes 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 \path{cfgs/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).

\begin{xmllines}
<domain id="myzoomT" domain_ref="grid_T">
    <zoom_domain ibegin="10" jbegin="10" ni="5" nj="5" />
\end{xmllines}

The use of this subdomain is done through the redefinition of the attribute domain\_ref of the tag family field.
For example:

\begin{xmllines}
<file id="myfile_vzoom" output_freq="1d" >
   <field field_ref="toce" domain_ref="myzoomT"/>
</file>
\end{xmllines}

\noindent Moorings are seen as an extreme case corresponding to a 1 by 1 subdomain.
The Equatorial section, the TAO, RAMA and PIRATA moorings are already 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'' ...)

\begin{xmllines}
<file id="myfile_vzoom" output_freq="1d" >
   <field field_ref="toce" domain_ref="0n180wT"/>
</file>
\end{xmllines}

\noindent Note that if the domain decomposition used in XIOS cuts the subdomain in several parts and if
you use the ''multiple\_file'' type for your output files,
you will end up 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.

%% =================================================================================================
\subsubsection{Define vertical zooms}

Vertical zooms are defined through the attributes begin and n of the zoom\_axis tag family.
It must therefore be done in the axis part of the XML file.
For example, in \path{cfgs/ORCA2_ICE_PISCES/EXPREF/axis_def_nemo.xml}, we provide the following example:

\begin{xmllines}
<axis_definition>
   <axis id="deptht" long_name="Vertical T levels" unit="m" positive="down" />
   <axis id="deptht300" azix_ref="deptht" >
     <zoom_axis begin="1" n="19" />
</axis>
\end{xmllines}

\noindent The use of this vertical zoom is done through the definition of a new grid in \texttt{grid\_def\_nemo.xml}:

\begin{xmllines}
<grid id="grid_T_zoom_300">
   <domain domain_ref="grid_T" />
   <axis axis_ref="deptht300" />
</grid>
\end{xmllines}

\noindent and subsequent application in a field definition (e.g. \texttt{field\_def\_nemo-oce.xml}):

\begin{xmllines}
<field id="toce_e3t_300"    field_ref="toce_e3t"          unit="degree_C"     
                            grid_ref="grid_T_zoom_300"    detect_missing_value="true" />
\end{xmllines}

\noindent This variable can then be added to a file\_definition for actual output.

%% =================================================================================================
\subsubsection{Control of the output file names}

The output file names are defined by the attributs ''name'' and ''name\_suffix'' of the tag family file.
For example:

\begin{xmllines}
<file_group id="1d" output_freq="1d" name="myfile_1d" >
   <file id="myfileA" name_suffix="_AAA" > <!-- will create file "myfile_1d_AAA"  -->
   ...
   </file>
   <file id="myfileB" name_suffix="_BBB" > <!-- will create file "myfile_1d_BBB" -->
   ...
   </file>
</file_group>
\end{xmllines}

However it is often very convienent to define the file name with the name of the experiment,
the output file frequency and the date of the beginning and the end of the simulation
(which are informations stored either in the namelist or in the XML file).
To do so, we added the following rule:
if the id of the tag file is ''fileN'' (where N = 1 to 999 on 1 to 3 digits) or
one of the predefined sections or moorings (see next subsection),
the following part of the name and the name\_suffix (that can be inherited) will be automatically replaced by:

\begin{table}
  \begin{tabularx}{\textwidth}{|lX|}
    \hline
    \centering placeholder string &
    automatically replaced by                          \\
    \hline
    \hline
    \centering @expname@          &
    the experiment name (from cn\_exp in the namelist) \\
    \hline
    \centering @freq@             &
    output frequency (from attribute output\_freq)     \\
    \hline
    \centering @startdate@        &
    starting date of the simulation (from nn\_date0 in the restart or the namelist).
    \newline
    \verb?yyyymmdd?          format                   \\
    \hline
    \centering @startdatefull@    &
    starting date of the simulation (from nn\_date0 in the restart or the namelist).
    \newline
    \verb?yyyymmdd_hh:mm:ss? format                    \\
    \hline
    \centering @enddate@          &
    ending date of the simulation   (from nn\_date0 and nn\_itend  in the namelist).
    \newline
    \verb?yyyymmdd?          format                    \\
    \hline
    \centering @enddatefull@      &
    ending date of the simulation   (from nn\_date0 and nn\_itend  in the namelist).
    \newline
    \verb?yyyymmdd_hh:mm:ss? format                    \\
    \hline
  \end{tabularx}
\end{table}

\noindent For example,
\begin{xmllines}
<file id="myfile_hzoom" name="myfile_@expname@_@startdate@_freq@freq@" output_freq="1d" >
\end{xmllines}

\noindent with the namelist:
\begin{forlines}
cn_exp    = "ORCA2"
nn_date0  = 19891231
ln_rstart = .false.
\end{forlines}

\noindent will give the following file name radical: \textit{myfile\_ORCA2\_19891231\_freq1d}

%% =================================================================================================
\subsubsection{Other controls of the XML attributes from \NEMO}

The values of some attributes are defined by subroutine calls within \NEMO
(calls to iom\_set\_domain\_attr, iom\_set\_axis\_attr and iom\_set\_field\_attr in \mdl{iom}).
Any definition given in the XML file will be overwritten.
By convention, these attributes are defined to ''auto'' (for string) or ''0000'' (for integer) in the XML file
(but this is not necessary).
\\

There is the list of these attributes in the previous table.
\\
\begin{table}
  \begin{tabular}{|l|c|c|}
    \hline
    tag ids affected by automatic definition &
    name attribute                                                       &
    attribute value                                                      \\
    of some of their attributes &
                                                           &
                                                          \\
    \hline
    \hline
    field\_definition                                                    &
    freq\_op                                                             &
    \np{rn_rdt}{rn\_rdt}                                                         \\
    \hline
    SBC                                                                  &
    freq\_op                                                             &
    \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_fsbc}{nn\_fsbc}                                  \\
    \hline
    ptrc\_T                                                              &
    freq\_op                                                             &
    \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_dttrc}{nn\_dttrc}                                 \\
    \hline
    diad\_T                                                              &
    freq\_op                                                             &
    \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_dttrc}{nn\_dttrc}                                 \\
    \hline
    EqT, EqU, EqW                                                        &
    jbegin, ni,                                                          &
    according to the grid                                                \\
                                                                         &
    name\_suffix                                                         &
                                                                         \\
    \hline
    TAO, RAMA and PIRATA moorings                                        &
    zoom\_ibegin, zoom\_jbegin,                                          &
    according to the grid                                                \\
                                                                         &
    name\_suffix                                                         &
                                                                         \\
    \hline
  \end{tabular}
\end{table}

%% =================================================================================================
\subsubsection{Advanced use of XIOS functionalities}

%% =================================================================================================
\subsection{XML reference tables}
\label{subsec:DIA_IOM_xmlref}

\begin{enumerate}
\item Simple computation: directly define the computation when refering to the variable in the file definition.

\begin{xmllines}
<field field_ref="sst"  name="tosK"  unit="degK" > sst + 273.15 </field>
<field field_ref="taum" name="taum2" unit="N2/m4" long_name="square of wind stress module" >   taum * taum </field>
<field field_ref="qt"   name="stupid_check" > qt - qsr - qns </field>
\end{xmllines}

\item Simple computation: define a new variable and use it in the file definition.

in field\_definition:

\begin{xmllines}
<field id="sst2" long_name="square of sea surface temperature" unit="degC2" >  sst * sst </field >
\end{xmllines}

in file\_definition:

\begin{xmllines}
<field field_ref="sst2" > sst2 </field>
\end{xmllines}

Note that in this case, the following syntaxe \xmlcode{<field field_ref="sst2" />} is not working as
sst2 won't be evaluated.

\item Change of variable precision:

\begin{xmllines}
<!-- force to keep real 8 -->
<field field_ref="sst" name="tos_r8" prec="8" />
<!-- integer 2  with add_offset and scale_factor attributes -->
<field field_ref="sss" name="sos_i2" prec="2" add_offset="20." scale_factor="1.e-3" />
\end{xmllines}

Note that, then the code is crashing, writting real4 variables forces a numerical conversion from
real8 to real4 which will create an internal error in NetCDF and will avoid the creation of the output files.
Forcing double precision outputs with prec="8" (for example in the field\_definition) will avoid this problem.

\item add user defined attributes:

\begin{xmllines}
<file_group id="1d" output_freq="1d" output_level="10" enabled=".true."> <!-- 1d files -->
   <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" >
      <field field_ref="sst" name="tos" >
         <variable id="my_attribute1" type="string"  > blabla </variable>
         <variable id="my_attribute2" type="integer" > 3      </variable>
         <variable id="my_attribute3" type="float"   > 5.0    </variable>
      </field>
      <variable id="my_global_attribute" type="string" > blabla_global </variable>
   </file>
</file_group>
\end{xmllines}

\item use of the ``@'' function: example 1, weighted temporal average

 - define a new variable in field\_definition

\begin{xmllines}
<field id="toce_e3t" long_name="temperature * e3t" unit="degC*m" grid_ref="grid_T_3D" >toce * e3t</field>
\end{xmllines}

 - use it when defining your file.

\begin{xmllines}
<file_group id="5d" output_freq="5d"  output_level="10" enabled=".true." >  <!-- 5d files -->
   <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" >
      <field field_ref="toce" operation="instant" freq_op="5d" > @toce_e3t / @e3t </field>
   </file>
</file_group>
\end{xmllines}

The freq\_op="5d" attribute is used to define the operation frequency of the ``@'' function: here 5 day.
The temporal operation done by the ``@'' is the one defined in the field definition:
here we use the default, average.
So, in the above case, @toce\_e3t will do the 5-day mean of toce*e3t.
Operation="instant" refers to the temporal operation to be performed on the field''@toce\_e3t / @e3t'':
here the temporal average is alreday done by the ``@'' function so we just use instant to do the ratio of
the 2 mean values.
field\_ref="toce" means that attributes not explicitely defined, are inherited from toce field.
Note that in this case, freq\_op must be equal to the file output\_freq.

\item use of the ``@'' function: example 2, monthly SSH standard deviation

 - define a new variable in field\_definition

\begin{xmllines}
<field id="ssh2" long_name="square of sea surface temperature" unit="degC2" > ssh * ssh </field >
\end{xmllines}

 - use it when defining your file.

\begin{xmllines}
<file_group id="1m" output_freq="1m"  output_level="10" enabled=".true." >  <!-- 1m files -->
   <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" >
      <field field_ref="ssh" name="sshstd" long_name="sea_surface_temperature_standard_deviation"
                        operation="instant" freq_op="1m" >
                        sqrt( @ssh2 - @ssh * @ssh )
      </field>
   </file>
</file_group>
\end{xmllines}

The freq\_op="1m" attribute is used to define the operation frequency of the ``@'' function: here 1 month.
The temporal operation done by the ``@'' is the one defined in the field definition:
here we use the default, average.
So, in the above case, @ssh2 will do the monthly mean of ssh*ssh.
Operation="instant" refers to the temporal operation to be performed on the field ''sqrt( @ssh2 - @ssh * @ssh )'':
here the temporal average is alreday done by the ``@'' function so we just use instant.
field\_ref="ssh" means that attributes not explicitely defined, are inherited from ssh field.
Note that in this case, freq\_op must be equal to the file output\_freq.

\item use of the ``@'' function: example 3, monthly average of SST diurnal cycle

 - define 2 new variables in field\_definition

\begin{xmllines}
   <field id="sstmax" field_ref="sst" long_name="max of sea surface temperature" operation="maximum" />
   <field id="sstmin" field_ref="sst" long_name="min of sea surface temperature" operation="minimum" />
\end{xmllines}

 - use these 2 new variables when defining your file.

\begin{xmllines}
<file_group id="1m" output_freq="1m"  output_level="10" enabled=".true." >  <!-- 1m files -->
   <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" >
      <field field_ref="sst" name="sstdcy" long_name="amplitude of sst diurnal cycle" operation="average" freq_op="1d" >
                        @sstmax - @sstmin
      </field>
   </file>
</file_group>
\end{xmllines}

\end{enumerate}

The freq\_op="1d" attribute is used to define the operation frequency of the ``@'' function: here 1 day.
The temporal operation done by the ``@'' is the one defined in the field definition:
here maximum for sstmax and minimum for sstmin.
So, in the above case, @sstmax will do the daily max and @sstmin the daily min.
Operation="average" refers to the temporal operation to be performed on the field ``@sstmax - @sstmin'':
here monthly mean (of daily max - daily min of the sst).
field\_ref="sst" means that attributes not explicitely defined, are inherited from sst field.

%% =================================================================================================
\subsubsection{Tag list per family}

\begin{table}
  \begin{tabularx}{\textwidth}{|l|X|X|l|X|}
    \hline
    tag name                                                                                     &
    description                                                                                  &
    accepted attribute                                                                           &
    child of                                                                                     &
    parent of                       \\
    \hline
    \hline
    simulation                                                                                   &
    this tag is the root tag which encapsulates all the content of the XML file                  &
    none                                                                                         &
    none                                                                                         &
    context                         \\
    \hline
    context                                                                                      &
    encapsulates parts of the XML file dedicated to different codes or different parts of a code &
    id (''xios'', ''nemo'' or ''n\_nemo'' for the nth AGRIF zoom), src, time\_origin             &
    simulation                                                                                   &
    all root tags: ... \_definition \\
    \hline
  \end{tabularx}
  \caption{XIOS: context tags}
\end{table}

\begin{table}
  \begin{tabularx}{\textwidth}{|l|X|X|X|l|}
    \hline
    tag name                                                                                &
    description                                                                             &
    accepted attribute                                                                      &
    child of                                                                                &
    parent of             \\
    \hline
    \hline
    field\_definition                                                                       &
    encapsulates the definition of all the fields that can potentially be outputted         &
    axis\_ref, default\_value, domain\_ref, enabled, grid\_ref, level, operation, prec, src &
    context                                                                                 &
    field or field\_group \\
    \hline
    field\_group                                                                            &
    encapsulates a group of fields                                                          &
    axis\_ref, default\_value, domain\_ref, enabled, group\_ref, grid\_ref,
    id, level, operation, prec, src                                                         &
    field\_definition, field\_group, file                                                   &
    field or field\_group \\