source: NEMO/trunk/doc/tex_sub/chap_DIA.tex @ 9596

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

Fix multiple defined references

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