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 @ 11597

Last change on this file since 11597 was 11597, checked in by nicolasmartin, 3 years ago

Continuation of coding rules application
Recovery of some sections deleted by the previous commit

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