Newer
Older
\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}
Andrew Coward
committed
The model outputs are of three types: the restart file; the output log/progress listings;
and the diagnostic output file(s).
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.
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. 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.
%% =================================================================================================
\section{Standard model output (\textt{iom\_put})}
Andrew Coward
committed
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.
Andrew Coward
committed
\item Control over the compression and/or precision of output fields (subject to certain conditions)
\noindent In addition, \rou{iom\_put} allows the user to add in the code the output of any new
Andrew Coward
committed
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
Andrew Coward
committed
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.
In version 4.2, the \rou{iom\_put} interface depends on
Andrew Coward
committed
an external code called \href{https://forge.ipsl.jussieu.fr/ioserver/browser/XIOS/trunk}{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
version 4.2. requires the trunk version of XIOS; this is a change from earlier versions which
recommended the tagged XIOS2.5 release.
Andrew Coward
committed
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.
Andrew Coward
committed
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}
Andrew Coward
committed
\label{subsec:XIOS_restarts}
New from 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}.\\
Andrew Coward
committed
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?}
Andrew Coward
committed
\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}
Andrew Coward
committed
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}
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
%% =================================================================================================
\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
Andrew Coward
committed
XML files included via the \file{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}
Andrew Coward
committed
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}
Andrew Coward
committed
\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:
Andrew Coward
committed
<field_definition>
<field_group id="grid_T" grid_ref="grid_T_3D"> <!-- T grid -->
...
<field id="identifier" long_name="blabla" ... />
...
</field_definition>
Andrew Coward
committed
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:
<grid id="grid_T_3D" >
<domain domain_ref="grid_T" />
<axis axis_ref="deptht" />
</grid>
Andrew Coward
committed
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)
Andrew Coward
committed
<file id="file1" ... />
Andrew Coward
committed
<field field_ref="identifier" />
...
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
</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-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})
are included in each context\_nemo.xml file through the following commands:
<!-- 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" >
Andrew Coward
committed
<field id="sst" /> <!-- averaged sst -->
<field id="sss" operation="instant"/> <!-- instantaneous sss -->
\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:
Andrew Coward
committed
<field id="sst" long_name="sea surface temperature" />
<field id="sss" long_name="sea surface salinity" />
Andrew Coward
committed
<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}
Andrew Coward
committed
<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" />
...
\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" >
Andrew Coward
committed
<field field_ref="uoce" />
<field field_ref="ssu" />
<field field_ref="utau" />
\noindent that can be directly included in a file through the following syntax:
\begin{xmllines}
<file id="myfile_U" output_freq="1d" />
Andrew Coward
committed
<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}
Andrew Coward
committed
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">
Andrew Coward
committed
<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" >
Andrew Coward
committed
<field field_ref="toce" domain_ref="myzoomT"/>
\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" >
Andrew Coward
committed
<field field_ref="toce" domain_ref="0n180wT"/>
\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,
Andrew Coward
committed
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}
Andrew Coward
committed
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.
Andrew Coward
committed
For example, in \path{cfgs/ORCA2_ICE_PISCES/EXPREF/axis_def_nemo.xml}, we provide the following example:
Andrew Coward
committed
<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>
\noindent The use of this vertical zoom is done through the definition of a new grid in \file{grid_def_nemo.xml}:
Andrew Coward
committed
<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. \file{field_def_nemo-oce.xml}):
Andrew Coward
committed
\begin{xmllines}
<field id="toce_e3t_300" field_ref="toce_e3t" unit="degree_C"
grid_ref="grid_T_zoom_300" detect_missing_value="true" />
\noindent This variable can then be added to a file_definition for actual output.
Andrew Coward
committed
%% =================================================================================================
\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" >
Andrew Coward
committed
<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>
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
</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,
\xmlline|<file id="myfile_hzoom" name="myfile_@expname@_@startdate@_freq@freq@" output_freq="1d" >|
\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.
Andrew Coward
committed
\begin{tabularx}{\textwidth}{|X|X|X|}
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
\hline
tag ids affected by automatic definition of some of their attributes &
name attribute &
attribute value \\
\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
Andrew Coward
committed
\end{tabularx}
\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>
Andrew Coward
committed
<field field_ref="taum" name="taum2" unit="N2/m4" long_name="square of wind stress module" > taum * taum </field>
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
<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 -->
Andrew Coward
committed
<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 -->
Andrew Coward
committed
<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 -->
Andrew Coward
committed
<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}
Andrew Coward
committed
<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 -->
Andrew Coward
committed
<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>
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
</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 \\
\hline
field &
define a specific field &
axis\_ref, default\_value, domain\_ref, enabled, field\_ref, grid\_ref,
id, level, long\_name, name, operation, prec, standard\_name, unit &
field\_definition, field\_group, file &