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

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

source: NEMO/branches/2019/dev_r10503_XIOS_RW_doc/doc/latex/NEMO/subfiles/chap_DIA.tex @ 10506

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

ticket #2204 updates

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