source: NEMO/trunk/doc/latex/NEMO/subfiles/chap_DIA.tex

Last change on this file was 14530, checked in by nicolasmartin, 8 weeks ago

Revert commit 14526, can't use verbatim envs in macro

  • Property svn:keywords set to Id
File size: 99.1 KB
Line 
1\documentclass[../main/NEMO_manual]{subfiles}
2
3\begin{document}
4
5\chapter{Output and Diagnostics (IOM, DIA, TRD, FLO)}
6\label{chap:DIA}
7
8%    {\em 4.0} & {\em Mirek Andrejczuk, Massimiliano Drudi} & {\em }  \\
9%    {\em }      & {\em Dorotea Iovino, Nicolas Martin} & {\em }  \\
10%    {\em 3.6} & {\em Gurvan Madec, Sebastien Masson } & {\em }  \\
11%    {\em 3.4} & {\em Gurvan Madec, Rachid Benshila, Andrew Coward } & {\em }  \\
12%    {\em }      & {\em Christian Ethe, Sebastien Masson } & {\em }  \\
13
14\chaptertoc
15
16\paragraph{Changes record} ~\\
17
18{\footnotesize
19  \begin{tabularx}{\textwidth}{l||X|X}
20    Release & Author(s) & Modifications \\
21    \hline
22    {\em   4.0} & {\em ...} & {\em ...} \\
23    {\em   3.6} & {\em ...} & {\em ...} \\
24    {\em   3.4} & {\em ...} & {\em ...} \\
25    {\em <=3.4} & {\em ...} & {\em ...}
26  \end{tabularx}
27}
28
29\clearpage
30
31%% =================================================================================================
32\section{Model output}
33\label{sec:DIA_io_old}
34
35The model outputs are of three types: the restart file, the output listing, and the diagnostic output file(s).
36The restart file is used internally by the code when the user wants to start the model with
37initial conditions defined by a previous simulation.
38It contains all the information that is necessary in order for there to be no changes in the model results
39(even at the computer precision) between a run performed with several restarts and
40the same run performed in one step.
41It should be noted that this requires that the restart file contains two consecutive time steps for
42all the prognostic variables.
43
44The output listing and file(s) are predefined but should be checked and eventually adapted to the user's needs.
45The output listing is stored in the \textit{ocean.output} file.
46The information is printed from within the code on the logical unit \texttt{numout}.
47To locate these prints, use the UNIX command "\textit{grep -i numout}" in the source code directory.
48
49By default, diagnostic output files are written in NetCDF format.
50Since version 3.2, when defining \key{iomput}, an I/O server has been added which
51provides more flexibility in the choice of the fields to be written as well as how
52the writing work is distributed over the processors in massively parallel computing.
53A complete description of the use of this I/O server is presented in the next section.
54
55%\cmtgm{                    % start of gmcomment
56
57%% =================================================================================================
58\section{Standard model output (IOM)}
59\label{sec:DIA_iom}
60
61Since version 3.2, iomput is the \NEMO\ output interface of choice.
62It has been designed to be simple to use, flexible and efficient.
63The two main purposes of iomput are:
64
65\begin{enumerate}
66\item The complete and flexible control of the output files through external XML files adapted by
67  the user from standard templates.
68\item To achieve high performance and scalable output through the optional distribution of
69  all diagnostic output related tasks to dedicated processes.
70\end{enumerate}
71
72The first functionality allows the user to specify, without code changes or recompilation,
73aspects of the diagnostic output stream, such as:
74
75\begin{itemize}
76\item The choice of output frequencies that can be different for each file (including real months and years).
77\item The choice of file contents; includes complete flexibility over which data are written in which files
78  (the same data can be written in different files).
79\item The possibility to split output files at a chosen frequency.
80\item The possibility to extract a vertical or an horizontal subdomain.
81\item The choice of the temporal operation to perform, \eg: average, accumulate, instantaneous, min, max and once.
82\item Control over metadata via a large XML "database" of possible output fields.
83\end{itemize}
84
85In addition, iomput allows the user to add in the code the output of any new variable (scalar, 2D or 3D)
86in a very easy way.
87All details of iomput functionalities are listed in the following subsections.
88Examples of the XML files that control the outputs can be found in:
89\path{cfgs/ORCA2_ICE_PISCES/EXPREF/iodef.xml},
90\path{cfgs/SHARED/field_def_nemo-oce.xml},
91\path{cfgs/SHARED/field_def_nemo-pisces.xml},
92\path{cfgs/SHARED/field_def_nemo-ice.xml} and \path{cfgs/SHARED/domain_def_nemo.xml}. \\
93
94The second functionality targets output performance when running in parallel (\key{mpp\_mpi}).
95Iomput provides the possibility to specify N dedicated I/O processes (in addition to the \NEMO\ processes)
96to collect and write the outputs.
97With an appropriate choice of N by the user, the bottleneck associated with the writing of
98the output files can be greatly reduced.
99
100In version 3.6, the \rou{iom\_put} interface depends on
101an external code called \href{https://forge.ipsl.jussieu.fr/ioserver/browser/XIOS/branchs/xios-2.5}{XIOS-2.5}
102%(use of revision 618 or higher is required).
103This new IO server can take advantage of the parallel I/O functionality of NetCDF4 to
104create a single output file and therefore to bypass the rebuilding phase.
105Note that writing in parallel into the same NetCDF files requires that your NetCDF4 library is linked to
106an HDF5 library that has been correctly compiled (\ie\ with the configure option $--$enable-parallel).
107Note that the files created by iomput through XIOS are incompatible with NetCDF3.
108All post-processsing and visualization tools must therefore be compatible with NetCDF4 and not only NetCDF3.
109
110Even if not using the parallel I/O functionality of NetCDF4, using N dedicated I/O servers,
111where N is typically much less than the number of \NEMO\ processors, will reduce the number of output files created.
112This can greatly reduce the post-processing burden usually associated with using large numbers of \NEMO\ processors.
113Note that for smaller configurations, the rebuilding phase can be avoided,
114even without a parallel-enabled NetCDF4 library, simply by employing only one dedicated I/O server.
115
116%% =================================================================================================
117\subsection{XIOS: Reading and writing restart file}
118
119XIOS may be used to read single file restart produced by \NEMO. The variables written to
120file \forcode{numror} (OCE), \forcode{numrir} (SI3), \forcode{numrtr} (TOP), \forcode{numrsr} (SED) can be handled by XIOS.
121To activate restart reading using XIOS, set \np[=.true. ]{ln_xios_read}{ln\_xios\_read}
122in \textit{namelist\_cfg}. This setting will be ignored when multiple restart files are present, and default \NEMO
123functionality will be used for reading. There is no need to change iodef.xml file to use XIOS to read
124restart, all definitions are done within the \NEMO\ code. For high resolution configuration, however,
125there may be a need to add the following line in iodef.xml (xios context):
126
127\begin{xmllines}
128<variable id="recv_field_timeout"        type="double">1800</variable>
129\end{xmllines}
130
131This variable sets timeout for reading.
132
133If XIOS is to be used to read restart from file generated with an earlier \NEMO\ version (3.6 for instance),
134dimension \forcode{z} defined in restart file must be renamed to \forcode{nav_lev}.\\
135
136XIOS can also be used to write \NEMO\ restart. A namelist parameter \np{nn_wxios}{nn\_wxios} is used to determine the
137type of restart \NEMO\ will write. If it is set to 0, default \NEMO\ functionality will be used - each
138processor writes its own restart file; if it is set to 1 XIOS will write restart into a single file;
139for \np[=2]{nn_wxios}{nn\_wxios} the restart will be written by XIOS into multiple files, one for each XIOS server.
140Note, however, that \textbf{\NEMO\ will not read restart generated by XIOS when \np[=2]{nn_wxios}{nn\_wxios}}. The restart will
141have to be rebuild before continuing the run. This option aims to reduce number of restart files generated by \NEMO\ only,
142and may be useful when there is a need to change number of processors used to run simulation.
143
144An older versions of XIOS do not support reading functionality. It's recommended to use at least XIOS2@1451.
145
146%% =================================================================================================
147\subsection{XIOS: XML Inputs-Outputs Server}
148
149%% =================================================================================================
150\subsubsection{Attached or detached mode?}
151
152Iomput is based on \href{http://forge.ipsl.jussieu.fr/ioserver/wiki}{XIOS},
153the io\_server developed by Yann Meurdesoif from IPSL.
154The behaviour of the I/O subsystem is controlled by settings in the external XML files listed above.
155Key settings in the iodef.xml file are the tags associated with each defined file.
156
157\xmlline|<variable id="using_server" type="bool"></variable>|
158
159The \texttt{using\_server} setting determines whether or not the server will be used in
160\textit{attached mode}
161(as a library) [\texttt{> false <}] or in \textit{detached mode}
162(as an external executable on N additional, dedicated cpus) [\texttt{ > true <}].
163The \textit{attached mode} is simpler to use but much less efficient for
164massively parallel applications.
165The type of each file can be either ''multiple\_file'' or ''one\_file''.
166
167In \textit{attached mode} and if the type of file is ''multiple\_file'',
168then each \NEMO\ process will also act as an IO server and produce its own set of output files.
169Superficially, this emulates the standard behaviour in previous versions.
170However, the subdomain written out by each process does not correspond to
171the \forcode{jpi x jpj x jpk} domain actually computed by the process (although it may if \forcode{jpni=1}).
172Instead each process will have collected and written out a number of complete longitudinal strips.
173If the ''one\_file'' option is chosen then all processes will collect their longitudinal strips and
174write (in parallel) to a single output file.
175
176In \textit{detached mode} and if the type of file is ''multiple\_file'',
177then each stand-alone XIOS process will collect data for a range of complete longitudinal strips and
178write to its own set of output files.
179If the ''one\_file'' option is chosen then all XIOS processes will collect their longitudinal strips and
180write (in parallel) to a single output file.
181Note running in detached mode requires launching a Multiple Process Multiple Data (MPMD) parallel job.
182The following subsection provides a typical example but the syntax will vary in different MPP environments.
183
184%% =================================================================================================
185\subsubsection{Number of cpu used by XIOS in detached mode}
186
187The number of cores used by the XIOS is specified when launching the model.
188The number of cores dedicated to XIOS should be from \texttildelow1/10 to \texttildelow1/50 of the number of
189cores dedicated to \NEMO.
190Some manufacturers suggest using O($\sqrt{N}$) dedicated IO processors for N processors but
191this is a general recommendation and not specific to \NEMO.
192It is difficult to provide precise recommendations because the optimal choice will depend on
193the particular hardware properties of the target system
194(parallel filesystem performance, available memory, memory bandwidth etc.)
195and the volume and frequency of data to be created.
196Here is an example of 2 cpus for the io\_server and 62 cpu for nemo using mpirun:
197\cmd|mpirun -np 62 ./nemo.exe : -np 2 ./xios_server.exe|
198
199%% =================================================================================================
200\subsubsection{Control of XIOS: the context in iodef.xml}
201
202As well as the \texttt{using\_server} flag, other controls on the use of XIOS are set in
203the XIOS context in \textit{iodef.xml}.
204See the XML basics section below for more details on XML syntax and rules.
205
206\begin{table}
207  \begin{tabularx}{\textwidth}{|lXl|}
208    \hline
209    variable name                                                           &
210    description                                                             &
211    example  \\
212    \hline
213    \hline
214    buffer\_size                                                            &
215    buffer size used by XIOS to send data from \NEMO\ to XIOS.
216    Larger is more efficient.
217    Note that needed/used buffer sizes are summarized at the end of the job &
218    25000000 \\
219    \hline
220    buffer\_server\_factor\_size                                            &
221    ratio between \NEMO\ and XIOS buffer size.
222    Should be 2.                                                            &
223    2        \\
224    \hline
225    info\_level                                                             &
226    verbosity level (0 to 100)                                              &
227    0        \\
228    \hline
229    using\_server                                                           &
230    activate attached(false) or detached(true) mode                         &
231    true     \\
232    \hline
233    using\_oasis                                                            &
234    XIOS is used with OASIS(true) or not (false)                            &
235    false    \\
236    \hline
237    oasis\_codes\_id                                                        &
238    when using oasis, define the identifier of \NEMO\ in the namcouple.
239    Note that the identifier of XIOS is xios.x                              &
240    oceanx   \\
241    \hline
242  \end{tabularx}
243\end{table}
244
245%% =================================================================================================
246\subsection{Practical issues}
247
248%% =================================================================================================
249\subsubsection{Installation}
250
251As mentioned, XIOS is supported separately and must be downloaded and compiled before it can be used with \NEMO.
252See the installation guide on the \href{http://forge.ipsl.jussieu.fr/ioserver/wiki}{XIOS} wiki for help and guidance.
253\NEMO\ will need to link to the compiled XIOS library.
254The \href{https://forge.ipsl.jussieu.fr/nemo/chrome/site/doc/NEMO/guide/html/install.html#extract-and-install-xios}
255{Extract and install XIOS} guide provides an example illustration of how this can be achieved.
256
257%% =================================================================================================
258\subsubsection{Add your own outputs}
259
260It is very easy to add your own outputs with iomput.
261Many standard fields and diagnostics are already prepared (\ie, steps 1 to 3 below have been done) and
262simply need to be activated by including the required output in a file definition in iodef.xml (step 4).
263To add new output variables, all 4 of the following steps must be taken.
264
265\begin{enumerate}
266\item in \NEMO\ code, add a \forcode{CALL iom_put( 'identifier', array )} where you want to output a 2D or 3D array.
267\item If necessary, add \forcode{USE iom ! I/O manager library} to the list of used modules in
268  the upper part of your module.
269\item in the field\_def.xml file, add the definition of your variable using the same identifier you used in the f90 code
270  (see subsequent sections for a details of the XML syntax and rules).
271  For example:
272\begin{xmllines}
273<field_definition>
274   <field_group id="grid_T" grid_ref="grid_T_3D"> <!-- T grid -->
275   ...
276      <field id="identifier" long_name="blabla" ... />
277      ...
278</field_definition>
279\end{xmllines}
280Note your definition must be added to the field\_group whose reference grid is consistent with the size of
281the array passed to iomput.
282The grid\_ref attribute refers to definitions set in iodef.xml which, in turn,
283reference grids and axes either defined in the code
284(iom\_set\_domain\_attr and iom\_set\_axis\_attr in \mdl{iom}) or defined in the domain\_def.xml file.
285\eg:
286\begin{xmllines}
287<grid id="grid_T_3D" domain_ref="grid_T" axis_ref="deptht"/>
288\end{xmllines}
289Note, if your array is computed within the surface module each \np{nn_fsbc}{nn\_fsbc} time\_step,
290add the field definition within the field\_group defined with the id "SBC":
291\xmlcode{<field_group id="SBC" ...>} which has been defined with the correct frequency of operations
292(iom\_set\_field\_attr in \mdl{iom})
293\item add your field in one of the output files defined in iodef.xml
294  (again see subsequent sections for syntax and rules)
295\begin{xmllines}
296<file id="file1" .../>
297...
298   <field field_ref="identifier" />
299   ...
300</file>
301\end{xmllines}
302\end{enumerate}
303
304%% =================================================================================================
305\subsection{XML fundamentals}
306
307%% =================================================================================================
308\subsubsection{ XML basic rules}
309
310XML tags begin with the less-than character ("$<$") and end with the greater-than character ("$>$").
311You use tags to mark the start and end of elements, which are the logical units of information in an XML document.
312In addition to marking the beginning of an element, XML start tags also provide a place to specify attributes.
313An attribute specifies a single property for an element, using a name/value pair, for example:
314\xmlcode{<a b="x" c="y" d="z"> ... </a>}.
315See \href{http://www.xmlnews.org/docs/xml-basics.html}{here} for more details.
316
317%% =================================================================================================
318\subsubsection{Structure of the XML file used in \NEMO}
319
320The XML file used in XIOS is structured by 7 families of tags:
321context, axis, domain, grid, field, file and variable.
322Each tag family has hierarchy of three flavors (except for context):
323
324\begin{table}
325  \begin{tabular*}{\textwidth}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|}
326    \hline
327    flavor  & description                                                                 &
328                                                                                            example                          \\
329    \hline
330    \hline
331    root    & declaration of the root element that can contain element groups or elements &
332                                                                                            \xmlcode{<file_definition ... >} \\
333    \hline
334    group   & declaration of a group element that can contain element groups or elements  &
335                                                                                            \xmlcode{<file_group      ... >} \\
336    \hline
337    element & declaration of an element that can contain elements                         &
338                                                                                            \xmlcode{<file            ... >} \\
339    \hline
340  \end{tabular*}
341\end{table}
342
343Each element may have several attributes.
344Some attributes are mandatory, other are optional but have a default value and other are completely optional.
345Id is a special attribute used to identify an element or a group of elements.
346It must be unique for a kind of element.
347It is optional, but no reference to the corresponding element can be done if it is not defined.
348
349The XML file is split into context tags that are used to isolate IO definition from
350different codes or different parts of a code.
351No interference is possible between 2 different contexts.
352Each context has its own calendar and an associated timestep.
353In \NEMO, we used the following contexts (that can be defined in any order):
354
355\begin{table}
356  \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|}
357    \hline
358    context         &   description                                                                &
359                                                                                                     example                              \\
360    \hline
361    \hline
362    context xios    &   context containing information for XIOS                                    &
363                                                                                                     \xmlcode{<context id="xios" ... >}   \\
364    \hline
365    context nemo    &   context containing IO information for \NEMO\ (mother grid when using AGRIF)  &
366                                                                                                     \xmlcode{<context id="nemo" ... >}   \\
367    \hline
368    context 1\_nemo &   context containing IO information for \NEMO\ child grid 1 (when using AGRIF) &
369                                                                                                     \xmlcode{<context id="1_nemo" ... >} \\
370    \hline
371    context n\_nemo &   context containing IO information for \NEMO\ child grid n (when using AGRIF) &
372                                                                                                     \xmlcode{<context id="n_nemo" ... >} \\
373    \hline
374  \end{tabular}
375\end{table}
376
377\noindent The xios context contains only 1 tag:
378
379\begin{table}
380  \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|}
381    \hline
382    context tag                                      &
383                                                       description                                      &
384                                                                                                          example                              \\
385    \hline
386    \hline
387    variable\_definition                             &
388                                                       define variables needed by XIOS.
389                                                       This can be seen as a kind of namelist for XIOS. &
390                                                                                                          \xmlcode{<variable_definition ... >} \\
391    \hline
392   \end{tabular}
393\end{table}
394
395\noindent Each context tag related to \NEMO\ (mother or child grids) is divided into 5 parts
396(that can be defined in any order):
397
398\begin{table}
399  \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|}
400    \hline
401    context tag        &   description                                                               &
402                                                                                                       example                            \\
403    \hline
404    \hline
405    field\_definition  &   define all variables that can potentially be outputted                    &
406                                                                                                       \xmlcode{<field_definition ... >}  \\
407    \hline
408    file\_definition   &   define the netcdf files to be created and the variables they will contain &
409                                                                                                       \xmlcode{<file_definition ... >}   \\
410    \hline
411    axis\_definition   &   define vertical axis                                                      &
412                                                                                                       \xmlcode{<axis_definition ... >}   \\
413    \hline
414    domain\_definition &   define the horizontal grids                                               &
415                                                                                                       \xmlcode{<domain_definition ... >} \\
416    \hline
417    grid\_definition   &   define the 2D and 3D grids (association of an axis and a domain)          &
418                                                                                                       \xmlcode{<grid_definition ... >}   \\
419    \hline
420  \end{tabular}
421\end{table}
422
423%% =================================================================================================
424\subsubsection{Nesting XML files}
425
426The XML file can be split in different parts to improve its readability and facilitate its use.
427The inclusion of XML files into the main XML file can be done through the attribute src:
428\xmlline|<context src="./nemo_def.xml" />|
429
430\noindent In \NEMO, by default, the field definition is done in 3 separate files (
431\path{cfgs/SHARED/field_def_nemo-oce.xml},
432\path{cfgs/SHARED/field_def_nemo-pisces.xml} and
433\path{cfgs/SHARED/field_def_nemo-ice.xml} ) and the  domain definition is done in another file ( \path{cfgs/SHARED/domain_def_nemo.xml} )
434that
435are included in the main iodef.xml file through the following commands:
436\begin{xmllines}
437<context id="nemo" src="./context_nemo.xml"/>
438\end{xmllines}
439
440%% =================================================================================================
441\subsubsection{Use of inheritance}
442
443XML extensively uses the concept of inheritance.
444XML has a tree based structure with a parent-child oriented relation: all children inherit attributes from parent,
445but an attribute defined in a child replace the inherited attribute value.
446Note that the special attribute ''id'' is never inherited.
447\\
448\\
449example 1: Direct inheritance.
450
451\begin{xmllines}
452<field_definition operation="average" >
453   <field id="sst"                    />   <!-- averaged      sst -->
454   <field id="sss" operation="instant"/>   <!-- instantaneous sss -->
455</field_definition>
456\end{xmllines}
457
458The field ''sst'' which is part (or a child) of the field\_definition will inherit the value ''average'' of
459the attribute ''operation'' from its parent.
460Note that a child can overwrite the attribute definition inherited from its parents.
461In the example above, the field ''sss'' will for example output instantaneous values instead of average values.
462\\
463\\
464example 2: Inheritance by reference.
465
466\begin{xmllines}
467<field_definition>
468   <field id="sst" long_name="sea surface temperature" />
469   <field id="sss" long_name="sea surface salinity"    />
470</field_definition>
471<file_definition>
472   <file id="myfile" output_freq="1d" />
473      <field field_ref="sst"                            />  <!-- default def -->
474      <field field_ref="sss" long_name="my description" />  <!-- overwrite   -->
475   </file>
476</file_definition>
477\end{xmllines}
478
479Inherit (and overwrite, if needed) the attributes of a tag you are refering to.
480
481%% =================================================================================================
482\subsubsection{Use of groups}
483
484Groups can be used for 2 purposes.
485Firstly, the group can be used to define common attributes to be shared by the elements of
486the group through inheritance.
487In the following example, we define a group of field that will share a common grid ''grid\_T\_2D''.
488Note that for the field ''toce'', we overwrite the grid definition inherited from the group by ''grid\_T\_3D''.
489
490\begin{xmllines}
491<field_group id="grid_T" grid_ref="grid_T_2D">
492   <field id="toce" long_name="temperature"             unit="degC" grid_ref="grid_T_3D"/>
493   <field id="sst"  long_name="sea surface temperature" unit="degC"                     />
494   <field id="sss"  long_name="sea surface salinity"    unit="psu"                      />
495   <field id="ssh"  long_name="sea surface height"      unit="m"                        />
496   ...
497\end{xmllines}
498
499Secondly, the group can be used to replace a list of elements.
500Several examples of groups of fields are proposed at the end of the XML field files (
501\path{cfgs/SHARED/field_def_nemo-oce.xml},
502\path{cfgs/SHARED/field_def_nemo-pisces.xml} and
503\path{cfgs/SHARED/field_def_nemo-ice.xml} ) .
504For example, a short list of the usual variables related to the U grid:
505
506\begin{xmllines}
507<field_group id="groupU" >
508   <field field_ref="uoce"  />
509   <field field_ref="ssu" />
510   <field field_ref="utau"  />
511</field_group>
512\end{xmllines}
513
514that can be directly included in a file through the following syntax:
515
516\begin{xmllines}
517<file id="myfile_U" output_freq="1d" />
518   <field_group group_ref="groupU" />
519   <field field_ref="uocetr_eff"   />  <!-- add another field -->
520</file>
521\end{xmllines}
522
523%% =================================================================================================
524\subsection{Detailed functionalities}
525
526The file \path{NEMOGCM/CONFIG/ORCA2_LIM/iodef_demo.xml} provides several examples of the use of
527the new functionalities offered by the XML interface of XIOS.
528
529%% =================================================================================================
530\subsubsection{Define horizontal subdomains}
531
532Horizontal subdomains are defined through the attributs zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj of
533the tag family domain.
534It must therefore be done in the domain part of the XML file.
535For example, in \path{cfgs/SHARED/domain_def.xml}, we provide the following example of a definition of
536a 5 by 5 box with the bottom left corner at point (10,10).
537
538\begin{xmllines}
539<domain id="myzoomT" domain_ref="grid_T">
540   <zoom_domain ibegin="10" jbegin="10" ni="5" nj="5" />
541\end{xmllines}
542
543The use of this subdomain is done through the redefinition of the attribute domain\_ref of the tag family field.
544For example:
545
546\begin{xmllines}
547<file id="myfile_vzoom" output_freq="1d" >
548   <field field_ref="toce" domain_ref="myzoomT"/>
549</file>
550\end{xmllines}
551
552Moorings are seen as an extrem case corresponding to a 1 by 1 subdomain.
553The Equatorial section, the TAO, RAMA and PIRATA moorings are already registered in the code and
554can therefore be outputted without taking care of their (i,j) position in the grid.
555These predefined domains can be activated by the use of specific domain\_ref:
556''EqT'', ''EqU'' or ''EqW'' for the equatorial sections and
557the mooring position for TAO, RAMA and PIRATA followed by ''T'' (for example: ''8s137eT'', ''1.5s80.5eT'' ...)
558
559\begin{xmllines}
560<file id="myfile_vzoom" output_freq="1d" >
561   <field field_ref="toce" domain_ref="0n180wT"/>
562</file>
563\end{xmllines}
564
565Note that if the domain decomposition used in XIOS cuts the subdomain in several parts and if
566you use the ''multiple\_file'' type for your output files,
567you will endup with several files you will need to rebuild using unprovided tools (like ncpdq and ncrcat,
568\href{http://nco.sourceforge.net/nco.html#Concatenation}{see nco manual}).
569We are therefore advising to use the ''one\_file'' type in this case.
570
571%% =================================================================================================
572\subsubsection{Define vertical zooms}
573
574Vertical zooms are defined through the attributs zoom\_begin and zoom\_n of the tag family axis.
575It must therefore be done in the axis part of the XML file.
576For example, in \path{cfgs/ORCA2_ICE_PISCES/EXPREF/iodef_demo.xml}, we provide the following example:
577
578\begin{xmllines}
579<axis_definition>
580   <axis id="deptht" long_name="Vertical T levels" unit="m" positive="down" />
581   <axis id="deptht_zoom" azix_ref="deptht" >
582      <zoom_axis zoom_begin="1" zoom_n="10" />
583   </axis>
584\end{xmllines}
585
586The use of this vertical zoom is done through the redefinition of the attribute axis\_ref of the tag family field.
587For example:
588
589\begin{xmllines}
590<file id="myfile_hzoom" output_freq="1d" >
591   <field field_ref="toce" axis_ref="deptht_myzoom"/>
592</file>
593\end{xmllines}
594
595%% =================================================================================================
596\subsubsection{Control of the output file names}
597
598The output file names are defined by the attributs ''name'' and ''name\_suffix'' of the tag family file.
599For example:
600
601\begin{xmllines}
602<file_group id="1d" output_freq="1d" name="myfile_1d" >
603   <file id="myfileA" name_suffix="_AAA" > <!-- will create file "myfile_1d_AAA"  -->
604      ...
605   </file>
606   <file id="myfileB" name_suffix="_BBB" > <!-- will create file "myfile_1d_BBB" -->
607      ...
608   </file>
609</file_group>
610\end{xmllines}
611
612However it is often very convienent to define the file name with the name of the experiment,
613the output file frequency and the date of the beginning and the end of the simulation
614(which are informations stored either in the namelist or in the XML file).
615To do so, we added the following rule:
616if the id of the tag file is ''fileN'' (where N = 1 to 999 on 1 to 3 digits) or
617one of the predefined sections or moorings (see next subsection),
618the following part of the name and the name\_suffix (that can be inherited) will be automatically replaced by:
619
620\begin{table}
621  \begin{tabularx}{\textwidth}{|lX|}
622    \hline
623    \centering placeholder string &
624    automatically replaced by                          \\
625    \hline
626    \hline
627    \centering @expname@          &
628    the experiment name (from cn\_exp in the namelist) \\
629    \hline
630    \centering @freq@             &
631    output frequency (from attribute output\_freq)     \\
632    \hline
633    \centering @startdate@        &
634    starting date of the simulation (from nn\_date0 in the restart or the namelist).
635    \newline
636    \verb?yyyymmdd?          format                   \\
637    \hline
638    \centering @startdatefull@    &
639    starting date of the simulation (from nn\_date0 in the restart or the namelist).
640    \newline
641    \verb?yyyymmdd_hh:mm:ss? format                    \\
642    \hline
643    \centering @enddate@          &
644    ending date of the simulation   (from nn\_date0 and nn\_itend  in the namelist).
645    \newline
646    \verb?yyyymmdd?          format                    \\
647    \hline
648    \centering @enddatefull@      &
649    ending date of the simulation   (from nn\_date0 and nn\_itend  in the namelist).
650    \newline
651    \verb?yyyymmdd_hh:mm:ss? format                    \\
652    \hline
653  \end{tabularx}
654\end{table}
655
656\noindent For example,
657\xmlline|<file id="myfile_hzoom" name="myfile_@expname@_@startdate@_freq@freq@" output_freq="1d" >|
658
659\noindent with the namelist:
660\begin{forlines}
661cn_exp    = "ORCA2"
662nn_date0  = 19891231
663ln_rstart = .false.
664\end{forlines}
665
666\noindent will give the following file name radical: \textit{myfile\_ORCA2\_19891231\_freq1d}
667
668%% =================================================================================================
669\subsubsection{Other controls of the XML attributes from \NEMO}
670
671The values of some attributes are defined by subroutine calls within \NEMO
672(calls to iom\_set\_domain\_attr, iom\_set\_axis\_attr and iom\_set\_field\_attr in \mdl{iom}).
673Any definition given in the XML file will be overwritten.
674By convention, these attributes are defined to ''auto'' (for string) or ''0000'' (for integer) in the XML file
675(but this is not necessary).
676\\
677
678Here is the list of these attributes:
679\\
680
681\begin{table}
682  \begin{tabular}{|l|c|c|}
683    \hline
684    tag ids affected by automatic definition of some of their attributes &
685    name attribute                                                       &
686    attribute value                                                      \\
687    \hline
688    \hline
689    field\_definition                                                    &
690    freq\_op                                                             &
691    \np{rn_rdt}{rn\_rdt}                                                         \\
692    \hline
693    SBC                                                                  &
694    freq\_op                                                             &
695    \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_fsbc}{nn\_fsbc}                                  \\
696    \hline
697    ptrc\_T                                                              &
698    freq\_op                                                             &
699    \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_dttrc}{nn\_dttrc}                                 \\
700    \hline
701    diad\_T                                                              &
702    freq\_op                                                             &
703    \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_dttrc}{nn\_dttrc}                                 \\
704    \hline
705    EqT, EqU, EqW                                                        &
706    jbegin, ni,                                                          &
707    according to the grid                                                \\
708                                                                         &
709    name\_suffix                                                         &
710                                                                         \\
711    \hline
712    TAO, RAMA and PIRATA moorings                                        &
713    zoom\_ibegin, zoom\_jbegin,                                          &
714    according to the grid                                                \\
715                                                                         &
716    name\_suffix                                                         &
717                                                                         \\
718    \hline
719  \end{tabular}
720\end{table}
721
722%% =================================================================================================
723\subsubsection{Advanced use of XIOS functionalities}
724
725%% =================================================================================================
726\subsection{XML reference tables}
727\label{subsec:DIA_IOM_xmlref}
728
729\begin{enumerate}
730\item Simple computation: directly define the computation when refering to the variable in the file definition.
731
732\begin{xmllines}
733<field field_ref="sst"  name="tosK"  unit="degK" > sst + 273.15 </field>
734<field field_ref="taum" name="taum2" unit="N2/m4" long_name="square of wind stress module" > taum * taum </field>
735<field field_ref="qt"   name="stupid_check" > qt - qsr - qns </field>
736\end{xmllines}
737
738\item Simple computation: define a new variable and use it in the file definition.
739
740in field\_definition:
741
742\begin{xmllines}
743<field id="sst2" long_name="square of sea surface temperature" unit="degC2" >  sst * sst </field >
744\end{xmllines}
745
746in file\_definition:
747
748\begin{xmllines}
749<field field_ref="sst2" > sst2 </field>
750\end{xmllines}
751
752Note that in this case, the following syntaxe \xmlcode{<field field_ref="sst2" />} is not working as
753sst2 won't be evaluated.
754
755\item Change of variable precision:
756
757\begin{xmllines}
758<!-- force to keep real 8 -->
759<field field_ref="sst" name="tos_r8" prec="8" />
760<!-- integer 2  with add_offset and scale_factor attributes -->
761<field field_ref="sss" name="sos_i2" prec="2" add_offset="20." scale_factor="1.e-3" />
762\end{xmllines}
763
764Note that, then the code is crashing, writting real4 variables forces a numerical conversion from
765real8 to real4 which will create an internal error in NetCDF and will avoid the creation of the output files.
766Forcing double precision outputs with prec="8" (for example in the field\_definition) will avoid this problem.
767
768\item add user defined attributes:
769
770\begin{xmllines}
771<file_group id="1d" output_freq="1d" output_level="10" enabled=".true."> <!-- 1d files -->
772   <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" >
773      <field field_ref="sst" name="tos" >
774         <variable id="my_attribute1" type="string"  > blabla </variable>
775         <variable id="my_attribute2" type="integer" > 3      </variable>
776         <variable id="my_attribute3" type="float"   > 5.0    </variable>
777      </field>
778      <variable id="my_global_attribute" type="string" > blabla_global </variable>
779   </file>
780</file_group>
781\end{xmllines}
782
783\item use of the ``@'' function: example 1, weighted temporal average
784
785 - define a new variable in field\_definition
786
787\begin{xmllines}
788<field id="toce_e3t" long_name="temperature * e3t" unit="degC*m" grid_ref="grid_T_3D" >toce * e3t</field>
789\end{xmllines}
790
791 - use it when defining your file.
792
793\begin{xmllines}
794<file_group id="5d" output_freq="5d"  output_level="10" enabled=".true." >  <!-- 5d files -->
795   <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" >
796      <field field_ref="toce" operation="instant" freq_op="5d" > @toce_e3t / @e3t </field>
797   </file>
798</file_group>
799\end{xmllines}
800
801The freq\_op="5d" attribute is used to define the operation frequency of the ``@'' function: here 5 day.
802The temporal operation done by the ``@'' is the one defined in the field definition:
803here we use the default, average.
804So, in the above case, @toce\_e3t will do the 5-day mean of toce*e3t.
805Operation="instant" refers to the temporal operation to be performed on the field''@toce\_e3t / @e3t'':
806here the temporal average is alreday done by the ``@'' function so we just use instant to do the ratio of
807the 2 mean values.
808field\_ref="toce" means that attributes not explicitely defined, are inherited from toce field.
809Note that in this case, freq\_op must be equal to the file output\_freq.
810
811\item use of the ``@'' function: example 2, monthly SSH standard deviation
812
813 - define a new variable in field\_definition
814
815\begin{xmllines}
816<field id="ssh2" long_name="square of sea surface temperature" unit="degC2" > ssh * ssh </field >
817\end{xmllines}
818
819 - use it when defining your file.
820
821\begin{xmllines}
822<file_group id="1m" output_freq="1m"  output_level="10" enabled=".true." >  <!-- 1m files -->
823   <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" >
824      <field field_ref="ssh" name="sshstd" long_name="sea_surface_temperature_standard_deviation"
825      operation="instant" freq_op="1m" >
826         sqrt( @ssh2 - @ssh * @ssh )
827      </field>
828   </file>
829</file_group>
830\end{xmllines}
831
832The freq\_op="1m" attribute is used to define the operation frequency of the ``@'' function: here 1 month.
833The temporal operation done by the ``@'' is the one defined in the field definition:
834here we use the default, average.
835So, in the above case, @ssh2 will do the monthly mean of ssh*ssh.
836Operation="instant" refers to the temporal operation to be performed on the field ''sqrt( @ssh2 - @ssh * @ssh )'':
837here the temporal average is alreday done by the ``@'' function so we just use instant.
838field\_ref="ssh" means that attributes not explicitely defined, are inherited from ssh field.
839Note that in this case, freq\_op must be equal to the file output\_freq.
840
841\item use of the ``@'' function: example 3, monthly average of SST diurnal cycle
842
843 - define 2 new variables in field\_definition
844
845\begin{xmllines}
846<field id="sstmax" field_ref="sst" long_name="max of sea surface temperature" operation="maximum" />
847<field id="sstmin" field_ref="sst" long_name="min of sea surface temperature" operation="minimum" />
848\end{xmllines}
849
850 - use these 2 new variables when defining your file.
851
852\begin{xmllines}
853<file_group id="1m" output_freq="1m"  output_level="10" enabled=".true." >  <!-- 1m files -->
854   <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" >
855      <field field_ref="sst" name="sstdcy" long_name="amplitude of sst diurnal cycle" operation="average" freq_op="1d" >
856         @sstmax - @sstmin
857      </field>
858   </file>
859</file_group>
860\end{xmllines}
861
862\end{enumerate}
863
864The freq\_op="1d" attribute is used to define the operation frequency of the ``@'' function: here 1 day.
865The temporal operation done by the ``@'' is the one defined in the field definition:
866here maximum for sstmax and minimum for sstmin.
867So, in the above case, @sstmax will do the daily max and @sstmin the daily min.
868Operation="average" refers to the temporal operation to be performed on the field ``@sstmax - @sstmin'':
869here monthly mean (of daily max - daily min of the sst).
870field\_ref="sst" means that attributes not explicitely defined, are inherited from sst field.
871
872%% =================================================================================================
873\subsubsection{Tag list per family}
874
875\begin{table}
876  \begin{tabularx}{\textwidth}{|l|X|X|l|X|}
877    \hline
878    tag name                                                                                     &
879    description                                                                                  &
880    accepted attribute                                                                           &
881    child of                                                                                     &
882    parent of                       \\
883    \hline
884    \hline
885    simulation                                                                                   &
886    this tag is the root tag which encapsulates all the content of the XML file                  &
887    none                                                                                         &
888    none                                                                                         &
889    context                         \\
890    \hline
891    context                                                                                      &
892    encapsulates parts of the XML file dedicated to different codes or different parts of a code &
893    id (''xios'', ''nemo'' or ''n\_nemo'' for the nth AGRIF zoom), src, time\_origin             &
894    simulation                                                                                   &
895    all root tags: ... \_definition \\
896    \hline
897  \end{tabularx}
898  \caption{XIOS: context tags}
899\end{table}
900
901\begin{table}
902  \begin{tabularx}{\textwidth}{|l|X|X|X|l|}
903    \hline
904    tag name                                                                                &
905    description                                                                             &
906    accepted attribute                                                                      &
907    child of                                                                                &
908    parent of             \\
909    \hline
910    \hline
911    field\_definition                                                                       &
912    encapsulates the definition of all the fields that can potentially be outputted         &
913    axis\_ref, default\_value, domain\_ref, enabled, grid\_ref, level, operation, prec, src &
914    context                                                                                 &
915    field or field\_group \\
916    \hline
917    field\_group                                                                            &
918    encapsulates a group of fields                                                          &
919    axis\_ref, default\_value, domain\_ref, enabled, group\_ref, grid\_ref,
920    id, level, operation, prec, src                                                         &
921    field\_definition, field\_group, file                                                   &
922    field or field\_group \\
923    \hline
924    field                                                                                   &
925    define a specific field                                                                 &
926    axis\_ref, default\_value, domain\_ref, enabled, field\_ref, grid\_ref,
927    id, level, long\_name, name, operation, prec, standard\_name, unit                      &
928    field\_definition, field\_group, file                                                   &
929    none                  \\
930    \hline
931  \end{tabularx}
932  \caption{XIOS: field tags ("\texttt{field\_*}")}
933\end{table}
934
935\begin{table}
936  \begin{tabularx}{\textwidth}{|l|X|X|X|l|}
937    \hline
938    tag name                                                            &
939    description                                                         &
940    accepted attribute                                                  &
941    child of                                                            &
942    parent of           \\
943    \hline
944    \hline
945    file\_definition                                                    &
946    encapsulates the definition of all the files that will be outputted &
947    enabled, min\_digits, name, name\_suffix, output\_level,
948    split\_freq\_format, split\_freq, sync\_freq, type, src             &
949    context                                                             &
950    file or file\_group \\
951    \hline
952    file\_group                                                         &
953    encapsulates a group of files that will be outputted                &
954    enabled, description, id, min\_digits, name, name\_suffix, output\_freq, output\_level,
955    split\_freq\_format, split\_freq, sync\_freq, type, src             &
956    file\_definition, file\_group                                       &
957    file or file\_group \\
958    \hline
959    file                                                                &
960    define the contents of a file to be outputted                       &
961    enabled, description, id, min\_digits, name, name\_suffix, output\_freq, output\_level,
962    split\_freq\_format, split\_freq, sync\_freq, type, src             &
963    file\_definition, file\_group                                       &
964    field               \\
965    \hline
966  \end{tabularx}
967  \caption{XIOS: file tags ("\texttt{file\_*}")}
968\end{table}
969
970\begin{table}
971  \begin{tabularx}{\textwidth}{|l|X|X|X|X|}
972    \hline
973    tag name                                                                               &
974    description                                                                            &
975    accepted attribute                                                                     &
976    child of                                                                               &
977    parent of         \\
978    \hline
979    \hline
980    axis\_definition                                                                       &
981    define all the vertical axis potentially used by the variables                         &
982    src                                                                                    &
983    context                                                                                &
984    axis\_group, axis \\
985    \hline
986    axis\_group                                                                            &
987    encapsulates a group of vertical axis                                                  &
988    id, lon\_name, positive, src, standard\_name, unit, zoom\_begin, zoom\_end, zoom\_size &
989    axis\_definition, axis\_group                                                          &
990    axis\_group, axis \\
991    \hline
992    axis                                                                                   &
993    define a vertical axis                                                                 &
994    id, lon\_name, positive, src, standard\_name, unit, zoom\_begin, zoom\_end, zoom\_size &
995    axis\_definition, axis\_group                                                          &
996    none             \\
997    \hline
998  \end{tabularx}
999  \caption{XIOS: axis tags ("\texttt{axis\_*}")}
1000\end{table}
1001
1002\begin{table}
1003  \begin{tabularx}{\textwidth}{|l|X|X|X|X|}
1004    \hline
1005    tag name                                                            &
1006    description                                                         &
1007    accepted attribute                                                  &
1008    child of                                                            &
1009    parent of               \\
1010    \hline
1011    \hline
1012    domain\_\-definition                                                &
1013    define all the horizontal domains potentially used by the variables &
1014    src                                                                 &
1015    context                                                             &
1016    domain\_\-group, domain \\
1017    \hline
1018    domain\_group                                                       &
1019    encapsulates a group of horizontal domains                          &
1020    id, lon\_name, src, zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj  &
1021    domain\_\-definition, domain\_group                                 &
1022    domain\_\-group, domain \\
1023    \hline
1024    domain                                                              &
1025    define an horizontal domain                                         &
1026    id, lon\_name, src, zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj  &
1027    domain\_\-definition, domain\_group                                 &
1028    none                    \\
1029    \hline
1030  \end{tabularx}
1031  \caption{XIOS: domain tags ("\texttt{domain\_*)}"}
1032\end{table}
1033
1034\begin{table}
1035  \begin{tabularx}{\textwidth}{|l|X|X|X|X|}
1036    \hline
1037    tag name                                                                                     &
1038    description                                                                                  &
1039    accepted attribute                                                                           &
1040    child of                                                                                     &
1041    parent of                       \\
1042    \hline
1043    \hline
1044    grid\_definition                                                                               &
1045    define all the grid (association of a domain and/or an axis) potentially used by the variables &
1046    src                                                                                            &
1047    context                                                                                        &
1048    grid\_group, grid   \\
1049    \hline
1050    grid\_group                                                                                    &
1051    encapsulates a group of grids                                                                  &
1052    id, domain\_ref,axis\_ref                                                                      &
1053    grid\_definition, grid\_group                                                                  &
1054    grid\_group, grid   \\
1055    \hline
1056    grid                                                                                           &
1057    define a grid                                                                                  &
1058    id, domain\_ref,axis\_ref                                                                      &
1059    grid\_definition, grid\_group                                                                  &
1060    none                \\
1061    \hline
1062  \end{tabularx}
1063  \caption{XIOS: grid tags ("\texttt{grid\_*}")}
1064\end{table}
1065
1066%% =================================================================================================
1067\subsubsection{Attributes list per family}
1068
1069\begin{table}
1070  \begin{tabularx}{\textwidth}{|l|X|l|l|}
1071    \hline
1072    attribute name                           &
1073    description                              &
1074    example                                  &
1075    accepted by            \\
1076    \hline
1077    \hline
1078    axis\_ref                                &
1079    refers to the id of a vertical axis      &
1080    axis\_ref="deptht"                       &
1081    field, grid families   \\
1082    \hline
1083    domain\_ref                              &
1084    refers to the id of a domain             &
1085    domain\_ref="grid\_T"                    &
1086    field or grid families \\
1087    \hline
1088    field\_ref                               &
1089    id of the field we want to add in a file &
1090    field\_ref="toce"                        &
1091    field                  \\
1092    \hline
1093    grid\_ref                                &
1094    refers to the id of a grid               &
1095    grid\_ref="grid\_T\_2D"                  &
1096    field family           \\
1097    \hline
1098    group\_ref                               &
1099    refer to a group of variables            &
1100    group\_ref="mooring"                     &
1101    field\_group           \\
1102    \hline
1103  \end{tabularx}
1104  \caption{XIOS: reference attributes ("\texttt{*\_ref}")}
1105\end{table}
1106
1107\begin{table}
1108  \begin{tabularx}{\textwidth}{|l|X|l|l|}
1109    \hline
1110    attribute name                                     &
1111    description                                        &
1112    example                                            &
1113    accepted by   \\
1114    \hline
1115    \hline
1116    zoom\_ibegin                                       &
1117    starting point along x direction of the zoom.
1118    Automatically defined for TAO/RAMA/PIRATA moorings &
1119    zoom\_ibegin="1"                                   &
1120    domain family \\
1121    \hline
1122    zoom\_jbegin                                       &
1123    starting point along y direction of the zoom.
1124    Automatically defined for TAO/RAMA/PIRATA moorings &
1125    zoom\_jbegin="1"                                   &
1126    domain family \\
1127    \hline
1128    zoom\_ni                                           &
1129    zoom extent along x direction                      &
1130    zoom\_ni="1"                                       &
1131    domain family \\
1132    \hline
1133    zoom\_nj                                           &
1134    zoom extent along y direction                      &
1135    zoom\_nj="1"                                       &
1136    domain family \\
1137    \hline
1138  \end{tabularx}
1139  \caption{XIOS: domain attributes ("\texttt{zoom\_*}")}
1140\end{table}
1141
1142\begin{table}
1143  \begin{tabularx}{\textwidth}{|l|X|l|l|}
1144    \hline
1145    attribute name                                                                                       &
1146    description                                                                                          &
1147    example                                                                                              &
1148    accepted by                            \\
1149    \hline
1150    \hline
1151    min\_digits                                                                                          &
1152    specify the minimum of digits used in the core number in the name of the NetCDF file                 &
1153    min\_digits="4"                                                                                      &
1154    file family                            \\
1155    \hline
1156    name\_suffix                                                                                         &
1157    suffix to be inserted after the name and before the cpu number and the ''.nc'' termination of a file &
1158    name\_suffix="\_myzoom"                                                                              &
1159    file family                            \\
1160    \hline
1161    output\_level                                                                                        &
1162    output priority of variables in a file: 0 (high) to 10 (low).
1163    All variables listed in the file with a level smaller or equal to output\_level will be output.
1164    Other variables won't be output even if they are listed in the file.                                 &
1165    output\_level="10"                                                                                   &
1166    file family                            \\
1167    \hline
1168    split\_freq                                                                                          &
1169    frequency at which to temporally split output files.
1170    Units can be ts (timestep), y, mo, d, h, mi, s.
1171    Useful for long runs to prevent over-sized output files.                                             &
1172    split\_freq="1mo"                                                                                    &
1173    file family                            \\
1174    \hline
1175    split\_freq\-\_format                                                                                &
1176    date format used in the name of temporally split output files.
1177    Can be specified using the following syntaxes: \%y, \%mo, \%d, \%h \%mi and \%s                      &
1178    split\_freq\_format= "\%y\%mo\%d"                                                                    &
1179    file family                            \\
1180    \hline
1181    sync\_freq                                                                                           &
1182    NetCDF file synchronization frequency (update of the time\_counter).
1183    Units can be ts (timestep), y, mo, d, h, mi, s.                                                      &
1184    sync\_freq="10d"                                                                                     &
1185    file family                            \\
1186    \hline
1187    type (1)                                                                                             &
1188    specify if the output files are to be split spatially (multiple\_file) or not (one\_file)            &
1189    type="multiple\_file"                                                                                &
1190    file familly                           \\
1191    \hline
1192  \end{tabularx}
1193  \caption{XIOS: file attributes}
1194\end{table}
1195
1196\begin{table}
1197  \begin{tabularx}{\textwidth}{|l|X|l|l|}
1198    \hline
1199    attribute name                                                                                       &
1200    description                                                                                          &
1201    example                                                                                              &
1202    accepted by                            \\
1203    \hline
1204    \hline
1205    default\_value                                                                                       &
1206    missing\_value definition                                                                            &
1207    default\_value="1.e20"                                                                               &
1208    field family                           \\
1209    \hline
1210    level                                                                                                &
1211    output priority of a field: 0 (high) to 10 (low)                                                     &
1212    level="1"                                                                                            &
1213    field family                           \\
1214    \hline
1215    operation                                                                                            &
1216    type of temporal operation: average, accumulate, instantaneous, min, max and once                    &
1217    operation="average"                                                                                  &
1218    field family                           \\
1219    \hline
1220    output\_freq                                                                                         &
1221    operation frequency. units can be ts (timestep), y, mo, d, h, mi, s.                                 &
1222    output\_freq="1d12h"                                                                                 &
1223    field family                           \\
1224    \hline
1225    prec                                                                                                 &
1226    output precision: real 4 or real 8                                                                   &
1227    prec="4"                                                                                             &
1228    field family                           \\
1229    \hline
1230    long\_name                                                                                           &
1231    define the long\_name attribute in the NetCDF file                                                   &
1232    long\_name="Vertical T levels"                                                                       &
1233    field                                  \\
1234    \hline
1235    standard\_name                                                                                       &
1236    define the standard\_name attribute in the NetCDF file                                               &
1237    standard\_name= "Eastward\_Sea\_Ice\_Transport"                                                      &
1238    field                                  \\
1239    \hline
1240  \end{tabularx}
1241  \caption{XIOS: field attributes}
1242\end{table}
1243
1244\begin{table}
1245  \begin{tabularx}{\textwidth}{|l|X|X|X|}
1246    \hline
1247    attribute name                                                                                       &
1248    description                                                                                          &
1249    example                                                                                              &
1250    accepted by                            \\
1251    \hline
1252    \hline
1253    enabled                                                                                              &
1254    switch on/off the output of a field or a file                                                        &
1255    enabled=".true."                                                                                     &
1256    field, file families                   \\
1257    \hline
1258    description                                                                                          &
1259    just for information, not used                                                                       &
1260    description="ocean T grid variables"                                                                 &
1261    all tags                               \\
1262    \hline
1263    id                                                                                                   &
1264    allow to identify a tag                                                                              &
1265    id="nemo"                                                                                            &
1266    accepted by all tags except simulation \\
1267    \hline
1268    name                                                                                                 &
1269    name of a variable or a file. If the name of a file is undefined, its id is used as a name           &
1270    name="tos"                                                                                           &
1271    field or file families                 \\
1272    \hline
1273    positive                                                                                             &
1274    convention used for the orientation of vertival axis (positive downward in \NEMO).                   &
1275    positive="down"                                                                                      &
1276    axis family                            \\
1277    \hline
1278    src                                                                                                  &
1279    allow to include a file                                                                              &
1280    src="./field\_def.xml"                                                                               &
1281    accepted by all tags except simulation \\
1282    \hline
1283    time\_origin                                                                                         &
1284    specify the origin of the time counter                                                               &
1285    time\_origin="1900-01-01 00:00:00"                                                                   &
1286    context                                \\
1287    \hline
1288    type (2)                                                                                             &
1289    define the type of a variable tag                                                                    &
1290    type="boolean"                                                                                       &
1291    variable                               \\
1292    \hline
1293    unit                                                                                                 &
1294    unit of a variable or the vertical axis                                                              &
1295    unit="m"                                                                                             &
1296    field and axis families                \\
1297    \hline
1298  \end{tabularx}
1299  \caption{XIOS: miscellaneous attributes}
1300\end{table}
1301
1302%% =================================================================================================
1303\subsection{CF metadata standard compliance}
1304
1305Output from the XIOS IO server is compliant with
1306\href{http://cfconventions.org/Data/cf-conventions/cf-conventions-1.5/build/cf-conventions.html}{version 1.5} of
1307the CF metadata standard.
1308Therefore while a user may wish to add their own metadata to the output files (as demonstrated in example 4 of
1309section \autoref{subsec:DIA_IOM_xmlref}) the metadata should, for the most part, comply with the CF-1.5 standard.
1310
1311Some metadata that may significantly increase the file size (horizontal cell areas and vertices) are controlled by
1312the namelist parameter \np{ln_cfmeta}{ln\_cfmeta} in the \nam{run}{run} namelist.
1313This must be set to true if these metadata are to be included in the output files.
1314
1315%% =================================================================================================
1316\section[NetCDF4 support (\texttt{\textbf{key\_netcdf4}})]{NetCDF4 support (\protect\key{netcdf4})}
1317\label{sec:DIA_nc4}
1318
1319Since version 3.3, support for NetCDF4 chunking and (loss-less) compression has been included.
1320These options build on the standard NetCDF output and allow the user control over the size of the chunks via
1321namelist settings.
1322Chunking and compression can lead to significant reductions in file sizes for a small runtime overhead.
1323For a fuller discussion on chunking and other performance issues the reader is referred to
1324the NetCDF4 documentation found \href{https://www.unidata.ucar.edu/software/netcdf/docs/netcdf_perf_chunking.html}{here}.
1325
1326The new features are only available when the code has been linked with a NetCDF4 library
1327(version 4.1 onwards, recommended) which has been built with HDF5 support (version 1.8.4 onwards, recommended).
1328Datasets created with chunking and compression are not backwards compatible with NetCDF3 "classic" format but
1329most analysis codes can be relinked simply with the new libraries and will then read both NetCDF3 and NetCDF4 files.
1330\NEMO\ executables linked with NetCDF4 libraries can be made to produce NetCDF3 files by
1331setting the \np{ln_nc4zip}{ln\_nc4zip} logical to false in the \nam{nc4}{nc4} namelist:
1332
1333\begin{listing}
1334  \nlst{namnc4}
1335  \caption{\forcode{&namnc4}}
1336  \label{lst:namnc4}
1337\end{listing}
1338
1339If \key{netcdf4} has not been defined, these namelist parameters are not read.
1340In this case, \np{ln_nc4zip}{ln\_nc4zip} is set false and dummy routines for a few NetCDF4-specific functions are defined.
1341These functions will not be used but need to be included so that compilation is possible with NetCDF3 libraries.
1342
1343When using NetCDF4 libraries, \key{netcdf4} should be defined even if the intention is to
1344create only NetCDF3-compatible files.
1345This is necessary to avoid duplication between the dummy routines and the actual routines present in the library.
1346Most compilers will fail at compile time when faced with such duplication.
1347Thus when linking with NetCDF4 libraries the user must define \key{netcdf4} and
1348control the type of NetCDF file produced via the namelist parameter.
1349
1350Chunking and compression is applied only to 4D fields and
1351there is no advantage in chunking across more than one time dimension since
1352previously written chunks would have to be read back and decompressed before being added to.
1353Therefore, user control over chunk sizes is provided only for the three space dimensions.
1354The user sets an approximate number of chunks along each spatial axis.
1355The actual size of the chunks will depend on global domain size for mono-processors or, more likely,
1356the local processor domain size for distributed processing.
1357The derived values are subject to practical minimum values (to avoid wastefully small chunk sizes) and
1358cannot be greater than the domain size in any dimension.
1359The algorithm used is:
1360
1361\begin{forlines}
1362ichunksz(1) = MIN(idomain_size, MAX((idomain_size-1) / nn_nchunks_i + 1 ,16 ))
1363ichunksz(2) = MIN(jdomain_size, MAX((jdomain_size-1) / nn_nchunks_j + 1 ,16 ))
1364ichunksz(3) = MIN(kdomain_size, MAX((kdomain_size-1) / nn_nchunks_k + 1 , 1 ))
1365ichunksz(4) = 1
1366\end{forlines}
1367
1368\noindent As an example, setting:
1369
1370\begin{forlines}
1371nn_nchunks_i=4, nn_nchunks_j=4 and nn_nchunks_k=31
1372\end{forlines}
1373
1374\noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\texttt 46x38x1} respectively in
1375the mono-processor case (\ie\ global domain of {\small\texttt 182x149x31}).
1376An illustration of the potential space savings that NetCDF4 chunking and compression provides is given in
1377table \autoref{tab:DIA_NC4} which compares the results of two short runs of the ORCA2\_LIM reference configuration with
1378a 4x2 mpi partitioning.
1379Note the variation in the compression ratio achieved which reflects chiefly the dry to wet volume ratio of
1380each processing region.
1381
1382\begin{table}
1383  \centering
1384  \begin{tabular}{lrrr}
1385    Filename                    & NetCDF3 & NetCDF4  & Reduction \\
1386                                & filesize   & filesize & \%        \\
1387                                & (KB)    & (KB)     &           \\
1388    ORCA2\_restart\_0000.nc     & 16420   & 8860     & 47\%      \\
1389    ORCA2\_restart\_0001.nc     & 16064   & 11456    & 29\%      \\
1390    ORCA2\_restart\_0002.nc     & 16064      & 9744     & 40\%      \\
1391    ORCA2\_restart\_0003.nc     & 16420      & 9404     & 43\%      \\
1392    ORCA2\_restart\_0004.nc     & 16200   & 5844     & 64\%      \\
1393    ORCA2\_restart\_0005.nc     & 15848   & 8172     & 49\%      \\
1394    ORCA2\_restart\_0006.nc     & 15848   & 8012     & 50\%      \\
1395    ORCA2\_restart\_0007.nc     & 16200   & 5148     & 69\%      \\
1396    ORCA2\_2d\_grid\_T\_0000.nc & 2200       & 1504     & 32\%      \\
1397    ORCA2\_2d\_grid\_T\_0001.nc & 2200       & 1748     & 21\%      \\
1398    ORCA2\_2d\_grid\_T\_0002.nc & 2200       & 1592     & 28\%      \\
1399    ORCA2\_2d\_grid\_T\_0003.nc & 2200       & 1540     & 30\%      \\
1400    ORCA2\_2d\_grid\_T\_0004.nc & 2200       & 1204     & 46\%      \\
1401    ORCA2\_2d\_grid\_T\_0005.nc & 2200       & 1444     & 35\%      \\
1402    ORCA2\_2d\_grid\_T\_0006.nc & 2200       & 1428     & 36\%      \\
1403    ORCA2\_2d\_grid\_T\_0007.nc & 2200    & 1148     & 48\%      \\
1404    ...                         & ...     & ...      & ...       \\
1405    ORCA2\_2d\_grid\_W\_0000.nc & 4416    & 2240     & 50\%      \\
1406    ORCA2\_2d\_grid\_W\_0001.nc & 4416    & 2924     & 34\%      \\
1407    ORCA2\_2d\_grid\_W\_0002.nc & 4416    & 2512     & 44\%      \\
1408    ORCA2\_2d\_grid\_W\_0003.nc & 4416    & 2368     & 47\%      \\
1409    ORCA2\_2d\_grid\_W\_0004.nc & 4416    & 1432     & 68\%      \\
1410    ORCA2\_2d\_grid\_W\_0005.nc & 4416    & 1972     & 56\%      \\
1411    ORCA2\_2d\_grid\_W\_0006.nc & 4416    & 2028     & 55\%      \\
1412    ORCA2\_2d\_grid\_W\_0007.nc & 4416    & 1368     & 70\%      \\
1413  \end{tabular}
1414  \caption{Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression}
1415  \label{tab:DIA_NC4}
1416\end{table}
1417
1418When \key{iomput} is activated with \key{netcdf4} chunking and compression parameters for fields produced via
1419\rou{iom\_put} calls are set via an equivalent and identically named namelist to \nam{nc4}{nc4} in
1420\textit{xmlio\_server.def}.
1421Typically this namelist serves the mean files whilst the \nam{nc4}{nc4} in the main namelist file continues to
1422serve the restart files.
1423This duplication is unfortunate but appropriate since, if using io\_servers, the domain sizes of
1424the individual files produced by the io\_server processes may be different to those produced by
1425the invidual processing regions and different chunking choices may be desired.
1426
1427%% =================================================================================================
1428\section[Tracer/Dynamics trends (\forcode{&namtrd})]{Tracer/Dynamics trends (\protect\nam{trd}{trd})}
1429\label{sec:DIA_trd}
1430
1431\begin{listing}
1432  \nlst{namtrd}
1433  \caption{\forcode{&namtrd}}
1434  \label{lst:namtrd}
1435\end{listing}
1436
1437Each trend of the dynamics and/or temperature and salinity time evolution equations can be send to
1438\mdl{trddyn} and/or \mdl{trdtra} modules (see TRD directory) just after their computation
1439(\ie\ at the end of each \textit{dyn....F90} and/or \textit{tra....F90} routines).
1440This capability is controlled by options offered in \nam{trd}{trd} namelist.
1441Note that the output are done with XIOS, and therefore the \key{iomput} is required.
1442
1443What is done depends on the \nam{trd}{trd} logical set to \forcode{.true.}:
1444
1445\begin{description}
1446\item [{\np{ln_glo_trd}{ln\_glo\_trd}}]: at each \np{nn_trd}{nn\_trd} time-step a check of the basin averaged properties of
1447  the momentum and tracer equations is performed.
1448  This also includes a check of $T^2$, $S^2$, $\tfrac{1}{2} (u^2+v2)$,
1449  and potential energy time evolution equations properties;
1450\item [{\np{ln_dyn_trd}{ln\_dyn\_trd}}]: each 3D trend of the evolution of the two momentum components is output;
1451\item [{\np{ln_dyn_mxl}{ln\_dyn\_mxl}}]: each 3D trend of the evolution of the two momentum components averaged over the mixed layer is output;
1452\item [{\np{ln_vor_trd}{ln\_vor\_trd}}]: a vertical summation of the moment tendencies is performed,
1453  then the curl is computed to obtain the barotropic vorticity tendencies which are output;
1454\item [{\np{ln_KE_trd}{ln\_KE\_trd}}]  : each 3D trend of the Kinetic Energy equation is output;
1455\item [{\np{ln_tra_trd}{ln\_tra\_trd}}]: each 3D trend of the evolution of temperature and salinity is output;
1456\item [{\np{ln_tra_mxl}{ln\_tra\_mxl}}]: each 2D trend of the evolution of temperature and salinity averaged over the mixed layer is output;
1457\end{description}
1458
1459Note that the mixed layer tendency diagnostic can also be used on biogeochemical models via
1460the \key{trdtrc} and \key{trdmxl\_trc} CPP keys.
1461
1462\textbf{Note that} in the current version (v3.6), many changes has been introduced but not fully tested.
1463In particular, options associated with \np{ln_dyn_mxl}{ln\_dyn\_mxl}, \np{ln_vor_trd}{ln\_vor\_trd}, and \np{ln_tra_mxl}{ln\_tra\_mxl} are not working,
1464and none of the options have been tested with variable volume (\ie\ \np[=.true.]{ln_linssh}{ln\_linssh}).
1465
1466%% =================================================================================================
1467\section[FLO: On-Line Floats trajectories (\texttt{\textbf{key\_floats}})]{FLO: On-Line Floats trajectories (\protect\key{floats})}
1468\label{sec:DIA_FLO}
1469
1470\begin{listing}
1471  \nlst{namflo}
1472  \caption{\forcode{&namflo}}
1473  \label{lst:namflo}
1474\end{listing}
1475
1476The on-line computation of floats advected either by the three dimensional velocity field or constraint to
1477remain at a given depth ($w = 0$ in the computation) have been introduced in the system during the CLIPPER project.
1478Options are defined by \nam{flo}{flo} namelist variables.
1479The algorithm used is based either on the work of \cite{blanke.raynaud_JPO97} (default option),
1480or on a $4^th$ Runge-Hutta algorithm (\np[=.true.]{ln_flork4}{ln\_flork4}).
1481Note that the \cite{blanke.raynaud_JPO97} algorithm have the advantage of providing trajectories which
1482are consistent with the numeric of the code, so that the trajectories never intercept the bathymetry.
1483
1484%% =================================================================================================
1485\subsubsection{Input data: initial coordinates}
1486
1487Initial coordinates can be given with Ariane Tools convention
1488(IJK coordinates, (\np[=.true.]{ln_ariane}{ln\_ariane}) ) or with longitude and latitude.
1489
1490In case of Ariane convention, input filename is \textit{init\_float\_ariane}.
1491Its format is: \\
1492{ \texttt{I J K nisobfl itrash}}
1493
1494\noindent with:
1495
1496 - I,J,K  : indexes of initial position
1497
1498 - nisobfl: 0 for an isobar float, 1 for a float following the w velocity
1499
1500 - itrash : set to zero; it is a dummy variable to respect Ariane Tools convention
1501
1502\noindent Example: \\
1503\noindent
1504{
1505  \texttt{
1506    100.00000  90.00000  -1.50000 1.00000   0.00000   \\
1507    102.00000  90.00000  -1.50000 1.00000   0.00000   \\
1508    104.00000  90.00000  -1.50000 1.00000   0.00000   \\
1509    106.00000  90.00000  -1.50000 1.00000   0.00000   \\
1510    108.00000  90.00000  -1.50000 1.00000   0.00000}
1511} \\
1512
1513In the other case (longitude and latitude), input filename is init\_float.
1514Its format is: \\
1515{ \texttt{Long Lat depth nisobfl ngrpfl itrash}}
1516
1517\noindent with:
1518
1519 - Long, Lat, depth  : Longitude, latitude, depth
1520
1521 - nisobfl: 0 for an isobar float, 1 for a float following the w velocity
1522
1523 - ngrpfl : number to identify searcher group
1524
1525 - itrash :set to 1; it is a dummy variable.
1526
1527\noindent Example: \\
1528\noindent
1529{
1530  \texttt{
1531    20.0 0.0 0.0 0 1 1    \\
1532    -21.0 0.0 0.0 0 1 1    \\
1533    -22.0 0.0 0.0 0 1 1    \\
1534    -23.0 0.0 0.0 0 1 1    \\
1535    -24.0 0.0 0.0 0 1 1 }
1536} \\
1537
1538\np{jpnfl}{jpnfl} is the total number of floats during the run.
1539When initial positions are read in a restart file (\np[=.true.]{ln_rstflo}{ln\_rstflo} ),
1540\np{jpnflnewflo}{jpnflnewflo} can be added in the initialization file.
1541
1542%% =================================================================================================
1543\subsubsection{Output data}
1544
1545\np{nn_writefl}{nn\_writefl} is the frequency of writing in float output file and \np{nn_stockfl}{nn\_stockfl} is the frequency of
1546creation of the float restart file.
1547
1548Output data can be written in ascii files (\np[=.true.]{ln_flo_ascii}{ln\_flo\_ascii}).
1549In that case, output filename is trajec\_float.
1550
1551Another possiblity of writing format is Netcdf (\np[=.false.]{ln_flo_ascii}{ln\_flo\_ascii}) with
1552\key{iomput} and outputs selected in iodef.xml.
1553Here it is an example of specification to put in files description section:
1554
1555\begin{xmllines}
1556<group id="1d_grid_T" name="auto" description="ocean T grid variables" >   }
1557   <file id="floats"  description="floats variables"> }
1558      <field ref="traj_lon"   name="floats_longitude"   freq_op="86400" />}
1559      <field ref="traj_lat"   name="floats_latitude"    freq_op="86400" />}
1560      <field ref="traj_dep"   name="floats_depth"       freq_op="86400" />}
1561      <field ref="traj_temp"  name="floats_temperature" freq_op="86400" />}
1562      <field ref="traj_salt"  name="floats_salinity"    freq_op="86400" />}
1563      <field ref="traj_dens"  name="floats_density"     freq_op="86400" />}
1564      <field ref="traj_group" name="floats_group"       freq_op="86400" />}
1565   </file>}
1566</group>}
1567\end{xmllines}
1568
1569%% =================================================================================================
1570\section[Transports across sections (\texttt{\textbf{key\_diadct}})]{Transports across sections (\protect\key{diadct})}
1571\label{sec:DIA_diag_dct}
1572
1573\begin{listing}
1574  \nlst{nam_diadct}
1575  \caption{\forcode{&nam_diadct}}
1576  \label{lst:nam_diadct}
1577\end{listing}
1578
1579A module is available to compute the transport of volume, heat and salt through sections.
1580This diagnostic is actived with \key{diadct}.
1581
1582Each section is defined by the coordinates of its 2 extremities.
1583The pathways between them are contructed using tools which can be found in \texttt{tools/SECTIONS\_DIADCT}
1584and are written in a binary file \texttt{section\_ijglobal.diadct} which is later read in by
1585\NEMO\ to compute on-line transports.
1586
1587The on-line transports module creates three output ascii files:
1588
1589- \texttt{volume\_transport} for volume transports (unit: $10^{6} m^{3} s^{-1}$)
1590
1591- \texttt{heat\_transport}   for   heat transports (unit: $10^{15} W$)
1592
1593- \texttt{salt\_transport}   for   salt transports (unit: $10^{9}Kg s^{-1}$) \\
1594
1595Namelist variables in \nam{_diadct}{\_diadct} control how frequently the flows are summed and the time scales over which
1596they are averaged, as well as the level of output for debugging:
1597\np{nn_dct}{nn\_dct}   : frequency of instantaneous transports computing
1598\np{nn_dctwri}{nn\_dctwri}: frequency of writing ( mean of instantaneous transports )
1599\np{nn_debug}{nn\_debug} : debugging of the section
1600
1601%% =================================================================================================
1602\subsubsection{Creating a binary file containing the pathway of each section}
1603
1604In \texttt{tools/SECTIONS\_DIADCT/run},
1605the file \textit{ {list\_sections.ascii\_global}} contains a list of all the sections that are to be computed
1606(this list of sections is based on MERSEA project metrics).
1607
1608Another file is available for the GYRE configuration (\texttt{ {list\_sections.ascii\_GYRE}}).
1609
1610Each section is defined by: \\
1611\noindent { \texttt{long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name}} \\
1612with:
1613
1614 - \texttt{long1 lat1}, coordinates of the  first extremity of the section;
1615
1616 - \texttt{long2 lat2}, coordinates of the second extremity of the section;
1617
1618 - \texttt{nclass}    the number of bounds of your classes (\eg\ bounds for 2 classes);
1619
1620 - \texttt{okstrpond} to compute    heat and       salt transports, \texttt{nostrpond} if no;
1621
1622 - \texttt{ice}       to compute surface and volume ice transports, \texttt{noice}     if no. \\
1623
1624 \noindent The results of the computing of transports, and the directions of positive and
1625 negative flow do not depend on the order of the 2 extremities in this file. \\
1626
1627\noindent If nclass $\neq$ 0, the next lines contain the class type and the nclass bounds: \\
1628{
1629  \texttt{
1630    long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name \\
1631    classtype                                                         \\
1632    zbound1                                                           \\
1633    zbound2                                                           \\
1634    .                                                                 \\
1635    .                                                                 \\
1636    nclass-1                                                          \\
1637    nclass}
1638}
1639
1640\noindent where \texttt{classtype} can be:
1641
1642 - \texttt{zsal}  for          salinity classes
1643
1644 - \texttt{ztem}  for       temperature classes
1645
1646 - \texttt{zlay}  for             depth classes
1647
1648 - \texttt{zsigi} for    insitu density classes
1649
1650 - \texttt{zsigp} for potential density classes \\
1651
1652 The script \texttt{job.ksh} computes the pathway for each section and creates a binary file
1653 \texttt{section\_ijglobal.diadct} which is read by \NEMO. \\
1654
1655 It is possible to use this tools for new configuations: \texttt{job.ksh} has to be updated with
1656 the coordinates file name and path. \\
1657
1658 Examples of two sections, the ACC\_Drake\_Passage with no classes,
1659 and the ATL\_Cuba\_Florida with 4 temperature clases (5 class bounds), are shown: \\
1660 \noindent
1661 {
1662   \texttt{
1663     -68.    -54.5   -60.    -64.7  00 okstrpond noice ACC\_Drake\_Passage \\
1664     -80.5    22.5   -80.5    25.5  05 nostrpond noice ATL\_Cuba\_Florida  \\
1665     ztem                                                                  \\
1666     -2.0                                                                  \\
1667     4.5                                                                  \\
1668     7.0                                                                  \\
1669     12.0                                                                  \\
1670     40.0}
1671 }
1672
1673%% =================================================================================================
1674\subsubsection{To read the output files}
1675
1676The output format is: \\
1677{
1678  \texttt{
1679    date, time-step number, section number,                \\
1680    section name, section slope coefficient, class number, \\
1681    class name, class bound 1 , classe bound2,             \\
1682    transport\_direction1, transport\_direction2,          \\
1683    transport\_total}
1684}                                     \\
1685
1686For sections with classes, the first \texttt{nclass-1} lines correspond to the transport for each class and
1687the last line corresponds to the total transport summed over all classes.
1688For sections with no classes, class number \texttt{1} corresponds to \texttt{total class} and
1689this class is called \texttt{N}, meaning \texttt{none}.
1690
1691- \texttt{transport\_direction1} is the positive part of the transport ($\geq$ 0).
1692
1693- \texttt{transport\_direction2} is the negative part of the transport ($\leq$ 0). \\
1694
1695\noindent The \texttt{section slope coefficient} gives information about the significance of transports signs and
1696direction: \\
1697
1698\begin{table}
1699  \begin{tabular}{|l|l|l|l|l|}
1700    \hline
1701    section slope coefficient      & section type & direction 1 & direction 2 & total transport    \\
1702    \hline
1703    0.                             & horizontal  & northward   & southward   & postive: northward    \\
1704    \hline
1705    1000.                          & vertical     & eastward    & westward    & postive: eastward     \\
1706    \hline
1707    \texttt{$\neq$ 0, $\neq$ 1000.} & diagonal     & eastward    & westward     & postive: eastward      \\
1708    \hline
1709  \end{tabular}
1710\end{table}
1711
1712%% =================================================================================================
1713\section{Diagnosing the steric effect in sea surface height}
1714\label{sec:DIA_steric}
1715
1716Changes in steric sea level are caused when changes in the density of the water column imply an expansion or
1717contraction of the column.
1718It is essentially produced through surface heating/cooling and to a lesser extent through non-linear effects of
1719the equation of state (cabbeling, thermobaricity...).
1720Non-Boussinesq models contain all ocean effects within the ocean acting on the sea level.
1721In particular, they include the steric effect.
1722In contrast, Boussinesq models, such as \NEMO, conserve volume, rather than mass,
1723and so do not properly represent expansion or contraction.
1724The steric effect is therefore not explicitely represented.
1725This approximation does not represent a serious error with respect to the flow field calculated by the model
1726\citep{greatbatch_JGR94}, but extra attention is required when investigating sea level,
1727as steric changes are an important contribution to local changes in sea level on seasonal and climatic time scales.
1728This is especially true for investigation into sea level rise due to global warming.
1729
1730Fortunately, the steric contribution to the sea level consists of a spatially uniform component that
1731can be diagnosed by considering the mass budget of the world ocean \citep{greatbatch_JGR94}.
1732In order to better understand how global mean sea level evolves and thus how the steric sea level can be diagnosed,
1733we compare, in the following, the non-Boussinesq and Boussinesq cases.
1734
1735Let denote
1736$\mathcal{M}$ the total mass    of liquid seawater ($\mathcal{M} = \int_D \rho dv$),
1737$\mathcal{V}$ the total volume  of        seawater      ($\mathcal{V} = \int_D dv$),
1738$\mathcal{A}$ the total surface of       the ocean      ($\mathcal{A} = \int_S ds$),
1739$\bar{\rho}$ the global mean  seawater (\textit{in situ}) density
1740($\bar{\rho} = 1/\mathcal{V} \int_D \rho \,dv$), and
1741$\bar{\eta}$ the global mean sea level
1742($\bar{\eta} = 1/\mathcal{A} \int_S \eta \,ds$).
1743
1744A non-Boussinesq fluid conserves mass. It satisfies the following relations:
1745
1746\begin{equation}
1747  \begin{split}
1748    \mathcal{M} &\mathcal{V}  \;\bar{\rho} \\
1749    \mathcal{V} &\mathcal{A}  \;\bar{\eta}
1750  \end{split}
1751  \label{eq:DIA_MV_nBq}
1752\end{equation}
1753
1754Temporal changes in total mass is obtained from the density conservation equation:
1755
1756\begin{equation}
1757  \frac{1}{e_3} \partial_t ( e_3\,\rho) + \nabla( \rho \, \textbf{U} )
1758  = \left. \frac{\textit{emp}}{e_3}\right|_\textit{surface}
1759  \label{eq:DIA_Co_nBq}
1760\end{equation}
1761
1762where $\rho$ is the \textit{in situ} density, and \textit{emp} the surface mass exchanges with the other media of
1763the Earth system (atmosphere, sea-ice, land).
1764Its global averaged leads to the total mass change
1765
1766\begin{equation}
1767  \partial_t \mathcal{M} = \mathcal{A} \;\overline{\textit{emp}}
1768  \label{eq:DIA_Mass_nBq}
1769\end{equation}
1770
1771where $\overline{\textit{emp}} = \int_S \textit{emp}\,ds$ is the net mass flux through the ocean surface.
1772Bringing \autoref{eq:DIA_Mass_nBq} and the time derivative of \autoref{eq:DIA_MV_nBq} together leads to
1773the evolution equation of the mean sea level
1774
1775\begin{equation}
1776  \partial_t \bar{\eta} = \frac{\overline{\textit{emp}}}{ \bar{\rho}}
1777  - \frac{\mathcal{V}}{\mathcal{A}} \;\frac{\partial_t \bar{\rho} }{\bar{\rho}}
1778  \label{eq:DIA_ssh_nBq}
1779\end{equation}
1780
1781The first term in equation \autoref{eq:DIA_ssh_nBq} alters sea level by adding or subtracting mass from the ocean.
1782The second term arises from temporal changes in the global mean density; \ie\ from steric effects.
1783
1784In a Boussinesq fluid, $\rho$ is replaced by $\rho_o$ in all the equation except when $\rho$ appears multiplied by
1785the gravity (\ie\ in the hydrostatic balance of the primitive Equations).
1786In particular, the mass conservation equation, \autoref{eq:DIA_Co_nBq}, degenerates into the incompressibility equation:
1787
1788\[
1789  \frac{1}{e_3} \partial_t ( e_3 ) + \nabla( \textbf{U} ) = \left. \frac{\textit{emp}}{\rho_o \,e_3}\right|_ \textit{surface}
1790  % \label{eq:DIA_Co_Bq}
1791\]
1792
1793and the global average of this equation now gives the temporal change of the total volume,
1794
1795\[
1796  \partial_t \mathcal{V} = \mathcal{A} \;\frac{\overline{\textit{emp}}}{\rho_o}
1797  % \label{eq:DIA_V_Bq}
1798\]
1799
1800Only the volume is conserved, not mass, or, more precisely, the mass which is conserved is the Boussinesq mass,
1801$\mathcal{M}_o = \rho_o \mathcal{V}$.
1802The total volume (or equivalently the global mean sea level) is altered only by net volume fluxes across
1803the ocean surface, not by changes in mean mass of the ocean: the steric effect is missing in a Boussinesq fluid.
1804
1805Nevertheless, following \citep{greatbatch_JGR94}, the steric effect on the volume can be diagnosed by
1806considering the mass budget of the ocean.
1807The apparent changes in $\mathcal{M}$, mass of the ocean, which are not induced by surface mass flux
1808must be compensated by a spatially uniform change in the mean sea level due to expansion/contraction of the ocean
1809\citep{greatbatch_JGR94}.
1810In others words, the Boussinesq mass, $\mathcal{M}_o$, can be related to $\mathcal{M}$,
1811the total mass of the ocean seen by the Boussinesq model, via the steric contribution to the sea level,
1812$\eta_s$, a spatially uniform variable, as follows:
1813
1814\begin{equation}
1815  \mathcal{M}_o = \mathcal{M} + \rho_o \,\eta_s \,\mathcal{A}
1816  \label{eq:DIA_M_Bq}
1817\end{equation}
1818
1819Any change in $\mathcal{M}$ which cannot be explained by the net mass flux through the ocean surface
1820is converted into a mean change in sea level.
1821Introducing the total density anomaly, $\mathcal{D}= \int_D d_a \,dv$,
1822where $d_a = (\rho -\rho_o ) / \rho_o$ is the density anomaly used in \NEMO\ (cf. \autoref{subsec:TRA_eos})
1823in \autoref{eq:DIA_M_Bq} leads to a very simple form for the steric height:
1824
1825\begin{equation}
1826  \eta_s = - \frac{1}{\mathcal{A}} \mathcal{D}
1827  \label{eq:DIA_steric_Bq}
1828\end{equation}
1829
1830The above formulation of the steric height of a Boussinesq ocean requires four remarks.
1831First, one can be tempted to define $\rho_o$ as the initial value of $\mathcal{M}/\mathcal{V}$,
1832\ie\ set $\mathcal{D}_{t=0}=0$, so that the initial steric height is zero.
1833We do not recommend that.
1834Indeed, in this case $\rho_o$ depends on the initial state of the ocean.
1835Since $\rho_o$ has a direct effect on the dynamics of the ocean
1836(it appears in the pressure gradient term of the momentum equation)
1837it is definitively not a good idea when inter-comparing experiments.
1838We better recommend to fixe once for all $\rho_o$ to $1035\;Kg\,m^{-3}$.
1839This value is a sensible choice for the reference density used in a Boussinesq ocean climate model since,
1840with the exception of only a small percentage of the ocean, density in the World Ocean varies by no more than
18412$\%$ from this value (\cite{gill_bk82}, page 47).
1842
1843Second, we have assumed here that the total ocean surface, $\mathcal{A}$,
1844does not change when the sea level is changing as it is the case in all global ocean GCMs
1845(wetting and drying of grid point is not allowed).
1846
1847Third, the discretisation of \autoref{eq:DIA_steric_Bq} depends on the type of free surface which is considered.
1848In the non linear free surface case, \ie\ \np[=.true.]{ln_linssh}{ln\_linssh}, it is given by
1849
1850\[
1851  \eta_s = - \frac{ \sum_{i,\,j,\,k} d_a\; e_{1t} e_{2t} e_{3t} }{ \sum_{i,\,j,\,k}       e_{1t} e_{2t} e_{3t} }
1852  % \label{eq:DIA_discrete_steric_Bq_nfs}
1853\]
1854
1855whereas in the linear free surface,
1856the volume above the \textit{z=0} surface must be explicitly taken into account to
1857better approximate the total ocean mass and thus the steric sea level:
1858
1859\[
1860  \eta_s = - \frac{ \sum_{i,\,j,\,k} d_a\; e_{1t}e_{2t}e_{3t} + \sum_{i,\,j} d_a\; e_{1t}e_{2t} \eta }
1861                  { \sum_{i,\,j,\,k}       e_{1t}e_{2t}e_{3t} + \sum_{i,\,j}       e_{1t}e_{2t} \eta }
1862  % \label{eq:DIA_discrete_steric_Bq_fs}
1863\]
1864
1865The fourth and last remark concerns the effective sea level and the presence of sea-ice.
1866In the real ocean, sea ice (and snow above it)  depresses the liquid seawater through its mass loading.
1867This depression is a result of the mass of sea ice/snow system acting on the liquid ocean.
1868There is, however, no dynamical effect associated with these depressions in the liquid ocean sea level,
1869so that there are no associated ocean currents.
1870Hence, the dynamically relevant sea level is the effective sea level,
1871\ie\ the sea level as if sea ice (and snow) were converted to liquid seawater \citep{campin.marshall.ea_OM08}.
1872However, in the current version of \NEMO\ the sea-ice is levitating above the ocean without mass exchanges between
1873ice and ocean.
1874Therefore the model effective sea level is always given by $\eta + \eta_s$, whether or not there is sea ice present.
1875
1876In AR5 outputs, the thermosteric sea level is demanded.
1877It is steric sea level due to changes in ocean density arising just from changes in temperature.
1878It is given by:
1879
1880\[
1881  \eta_s = - \frac{1}{\mathcal{A}} \int_D d_a(T,S_o,p_o) \,dv
1882  % \label{eq:DIA_thermosteric_Bq}
1883\]
1884
1885where $S_o$ and $p_o$ are the initial salinity and pressure, respectively.
1886
1887Both steric and thermosteric sea level are computed in \mdl{diaar5}.
1888
1889%% =================================================================================================
1890\section{Other diagnostics}
1891\label{sec:DIA_diag_others}
1892
1893Aside from the standard model variables, other diagnostics can be computed on-line.
1894The available ready-to-add diagnostics modules can be found in directory DIA.
1895
1896%% =================================================================================================
1897\subsection[Depth of various quantities (\textit{diahth.F90})]{Depth of various quantities (\protect\mdl{diahth})}
1898
1899Among the available diagnostics the following ones are obtained when defining the \key{diahth} CPP key:
1900
1901- the mixed layer depth (based on a density criterion \citep{de-boyer-montegut.madec.ea_JGR04}) (\mdl{diahth})
1902
1903- the turbocline depth (based on a turbulent mixing coefficient criterion) (\mdl{diahth})
1904
1905- the depth of the 20\deg{C} isotherm (\mdl{diahth})
1906
1907- the depth of the thermocline (maximum of the vertical temperature gradient) (\mdl{diahth})
1908
1909\begin{figure}[!t]
1910  \centering
1911  \includegraphics[width=0.66\textwidth]{DIA_mask_subasins}
1912  \caption[Decomposition of the World Ocean to compute transports as well as
1913  the meridional stream-function]{
1914    Decomposition of the World Ocean (here ORCA2) into sub-basin used in to
1915    compute the heat and salt transports as well as the meridional stream-function:
1916    Atlantic basin (red), Pacific basin (green),
1917    Indian basin (blue), Indo-Pacific basin (blue+green).
1918    Note that semi-enclosed seas (Red, Med and Baltic seas) as well as
1919    Hudson Bay are removed from the sub-basins.
1920    Note also that the Arctic Ocean has been split into Atlantic and
1921    Pacific basins along the North fold line.
1922  }
1923  \label{fig:DIA_mask_subasins}
1924\end{figure}
1925
1926%% =================================================================================================
1927\subsection[CMIP specific diagnostics (\textit{diaar5.F90}, \textit{diaptr.F90})]{CMIP specific diagnostics (\protect\mdl{diaar5})}
1928
1929A series of diagnostics has been added in the \mdl{diaar5} and \mdl{diaptr}.
1930In \mdl{diaar5} they correspond to outputs that are required for AR5 simulations (CMIP5)
1931(see also \autoref{sec:DIA_steric} for one of them).
1932The module \mdl{diaar5} is active when one of the following outputs is required :
1933global total volume (voltot), global mean ssh (sshtot), global total mass (masstot), global mean temperature (temptot),
1934global mean ssh steric (sshsteric), global mean ssh thermosteric (sshthster), global mean salinity (saltot),
1935sea water pressure at sea floor (botpres), dynamic sea surface height (sshdyn).
1936
1937In \mdl{diaptr} when \np[=.true.]{ln_diaptr}{ln\_diaptr}
1938(see the \nam{ptr}{ptr} namelist below) can be computed on-line the poleward heat and salt transports,
1939their advective and diffusive component, and the meriodional stream function .
1940When \np[=.true.]{ln_subbas}{ln\_subbas}, transports and stream function are computed for the Atlantic, Indian,
1941Pacific and Indo-Pacific Oceans (defined north of 30\deg{S}) as well as for the World Ocean.
1942The sub-basin decomposition requires an input file (\textit{subbasins}) which contains three 2D mask arrays,
1943the Indo-Pacific mask been deduced from the sum of the Indian and Pacific mask (\autoref{fig:DIA_mask_subasins}).
1944
1945\begin{listing}
1946%  \nlst{namptr}
1947  \caption{\forcode{&namptr}}
1948  \label{lst:namptr}
1949\end{listing}
1950
1951%% =================================================================================================
1952\subsection{25 hour mean output for tidal models}
1953
1954\begin{listing}
1955  \nlst{nam_dia25h}
1956  \caption{\forcode{&nam_dia25h}}
1957  \label{lst:nam_dia25h}
1958\end{listing}
1959
1960A module is available to compute a crudely detided M2 signal by obtaining a 25 hour mean.
1961The 25 hour mean is available for daily runs by summing up the 25 hourly instantananeous hourly values from
1962midnight at the start of the day to midight at the day end.
1963This diagnostic is actived with the logical $ln\_dia25h$.
1964
1965%% =================================================================================================
1966\subsection{Courant numbers}
1967
1968Courant numbers provide a theoretical indication of the model's numerical stability.
1969The advective Courant numbers can be calculated according to
1970
1971\[
1972  C_u = |u|\frac{\rdt}{e_{1u}}, \quad C_v = |v|\frac{\rdt}{e_{2v}}, \quad C_w = |w|\frac{\rdt}{e_{3w}}
1973  % \label{eq:DIA_CFL}
1974\]
1975
1976in the zonal, meridional and vertical directions respectively.
1977The vertical component is included although it is not strictly valid as the vertical velocity is calculated from
1978the continuity equation rather than as a prognostic variable.
1979Physically this represents the rate at which information is propogated across a grid cell.
1980Values greater than 1 indicate that information is propagated across more than one grid cell in a single time step.
1981
1982The variables can be activated by setting the \np{nn_diacfl}{nn\_diacfl} namelist parameter to 1 in the \nam{ctl}{ctl} namelist.
1983The diagnostics will be written out to an ascii file named cfl\_diagnostics.ascii.
1984In this file the maximum value of $C_u$, $C_v$, and $C_w$ are printed at each timestep along with the coordinates of
1985where the maximum value occurs.
1986At the end of the model run the maximum value of $C_u$, $C_v$, and $C_w$ for the whole model run is printed along
1987with the coordinates of each.
1988The maximum values from the run are also copied to the ocean.output file.
1989
1990\subinc{\input{../../global/epilogue}}
1991
1992\end{document}
Note: See TracBrowser for help on using the repository browser.