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/trunk/doc/latex/NEMO/subfiles – NEMO

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

Last change on this file since 11561 was 11561, checked in by nicolasmartin, 4 years ago

Apply two thirds ratio on figures width as default

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