New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
chap_DIA.tex in NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/latex/NEMO/subfiles – NEMO

source: NEMO/branches/2019/dev_r11351_fldread_with_XIOS/doc/latex/NEMO/subfiles/chap_DIA.tex @ 13463

Last change on this file since 13463 was 13463, checked in by andmirek, 4 years ago

Ticket #2195:update to trunk 13461

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