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

Last change on this file since 11577 was 11577, checked in by nicolasmartin, 13 months ago

New LaTeX commands \nam and \np to mention namelist content
(Partial commit to serve as a backup before other large edits)
In order to benefit of the syntax highlighting and to have a simpler syntax for
citing namelist block (\nam) and parameter (\np) with an optional variable assignment (\forcode{…}),
at this time the only viable solution I found is to require a double marker for
what it looks like the same item:

  1. Marker with the real name: 'tra_adv' block or 'ln_flx' parameter
  2. Marker with underscore character escaping: 'tra\_adv' block or 'ln\_flx' parameter

Despite many searches and attempts, I did not find a workaround to edit on-the-fly one or
the other marker.
In fact, the problem is on one side that the LaTeX index interprets '_' as a switch for lowering like
in math mode while on the other hand the backslash is considered for Pygments as a typo in Fortran
(red box).

For instance, \nam and \np have as of now the aforementioned 2 mandatory arguments in
the previous order (between braces) + an optional argument for \np when the parameter is defined
(between brackets at the first position):

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