source: NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_DIA.tex @ 10325

Last change on this file since 10325 was 10325, checked in by davestorkey, 2 years ago

UKMO/NEMO4_beta_mirror branch: clear SVN keywords.

File size: 95.2 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
1164\nlst{namnc4}
1165%-------------------------------------------------------------------------------------------------------------
1166
1167If \key{netcdf4} has not been defined, these namelist parameters are not read.
1168In this case, \np{ln\_nc4zip} is set false and dummy routines for
1169a few NetCDF4-specific functions are defined.
1170These functions will not be used but need to be included so that compilation is possible with
1171NetCDF3 libraries.
1172
1173When using NetCDF4 libraries, \key{netcdf4} should be defined even if the intention is to
1174create only NetCDF3-compatible files.
1175This is necessary to avoid duplication between the dummy routines and
1176the actual routines present in the library.
1177Most compilers will fail at compile time when faced with such duplication.
1178Thus when linking with NetCDF4 libraries the user must define \key{netcdf4} and
1179control the type of NetCDF file produced via the namelist parameter.
1180
1181Chunking and compression is applied only to 4D fields and there is no advantage in
1182chunking across more than one time dimension since previously written chunks would have to
1183be read back and decompressed before being added to.
1184Therefore, user control over chunk sizes is provided only for the three space dimensions.
1185The user sets an approximate number of chunks along each spatial axis.
1186The actual size of the chunks will depend on global domain size for mono-processors or,
1187more likely, the local processor domain size for distributed processing.
1188The derived values are subject to practical minimum values (to avoid wastefully small chunk sizes) and
1189cannot be greater than the domain size in any dimension.
1190The algorithm used is:
1191
1192\begin{forlines}
1193ichunksz(1) = MIN(idomain_size, MAX((idomain_size-1) / nn_nchunks_i + 1 ,16 ))
1194ichunksz(2) = MIN(jdomain_size, MAX((jdomain_size-1) / nn_nchunks_j + 1 ,16 ))
1195ichunksz(3) = MIN(kdomain_size, MAX((kdomain_size-1) / nn_nchunks_k + 1 , 1 ))
1196ichunksz(4) = 1
1197\end{forlines}
1198
1199\noindent As an example, setting:
1200
1201\begin{forlines}
1202nn_nchunks_i=4, nn_nchunks_j=4 and nn_nchunks_k=31
1203\end{forlines}
1204
1205\noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\tt 46x38x1} respectively in
1206the mono-processor case (i.e. global domain of {\small\tt 182x149x31}).
1207An illustration of the potential space savings that NetCDF4 chunking and compression provides is given in
1208table \autoref{tab:NC4} which compares the results of two short runs of
1209the ORCA2\_LIM reference configuration with a 4x2 mpi partitioning.
1210Note the variation in the compression ratio achieved which reflects chiefly the dry to
1211wet volume ratio of each processing region.
1212
1213%------------------------------------------TABLE----------------------------------------------------
1214\begin{table} \scriptsize \centering
1215   \begin{tabular}{lrrr}
1216      Filename                    & NetCDF3  & NetCDF4  & Reduction \\
1217                                  & filesize & filesize & \%        \\
1218                                  & (KB)     & (KB)     &           \\
1219      ORCA2\_restart\_0000.nc     & 16420    & 8860     & 47\%      \\
1220      ORCA2\_restart\_0001.nc     & 16064    & 11456    & 29\%      \\
1221      ORCA2\_restart\_0002.nc     & 16064    & 9744     & 40\%      \\
1222      ORCA2\_restart\_0003.nc     & 16420    & 9404     & 43\%      \\
1223      ORCA2\_restart\_0004.nc     & 16200    & 5844     & 64\%      \\
1224      ORCA2\_restart\_0005.nc     & 15848    & 8172     & 49\%      \\
1225      ORCA2\_restart\_0006.nc     & 15848    & 8012     & 50\%      \\
1226      ORCA2\_restart\_0007.nc     & 16200    & 5148     & 69\%      \\
1227      ORCA2\_2d\_grid\_T\_0000.nc & 2200     & 1504     & 32\%      \\
1228      ORCA2\_2d\_grid\_T\_0001.nc & 2200     & 1748     & 21\%      \\
1229      ORCA2\_2d\_grid\_T\_0002.nc & 2200     & 1592     & 28\%      \\
1230      ORCA2\_2d\_grid\_T\_0003.nc & 2200     & 1540     & 30\%      \\
1231      ORCA2\_2d\_grid\_T\_0004.nc & 2200     & 1204     & 46\%      \\
1232      ORCA2\_2d\_grid\_T\_0005.nc & 2200     & 1444     & 35\%      \\
1233      ORCA2\_2d\_grid\_T\_0006.nc & 2200     & 1428     & 36\%      \\
1234      ORCA2\_2d\_grid\_T\_0007.nc & 2200     & 1148     & 48\%      \\
1235      ...                         & ...      & ...      & ...       \\
1236      ORCA2\_2d\_grid\_W\_0000.nc & 4416     & 2240     & 50\%      \\
1237      ORCA2\_2d\_grid\_W\_0001.nc & 4416     & 2924     & 34\%      \\
1238      ORCA2\_2d\_grid\_W\_0002.nc & 4416     & 2512     & 44\%      \\
1239      ORCA2\_2d\_grid\_W\_0003.nc & 4416     & 2368     & 47\%      \\
1240      ORCA2\_2d\_grid\_W\_0004.nc & 4416     & 1432     & 68\%      \\
1241      ORCA2\_2d\_grid\_W\_0005.nc & 4416     & 1972     & 56\%      \\
1242      ORCA2\_2d\_grid\_W\_0006.nc & 4416     & 2028     & 55\%      \\
1243      ORCA2\_2d\_grid\_W\_0007.nc & 4416     & 1368     & 70\%      \\
1244   \end{tabular}
1245   \caption{
1246      \protect\label{tab:NC4}
1247      Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression}
1248\end{table}
1249%----------------------------------------------------------------------------------------------------
1250
1251When \key{iomput} is activated with \key{netcdf4} chunking and compression parameters for
1252fields produced via \np{iom\_put} calls are set via an equivalent and identically named namelist to
1253\textit{namnc4} in \np{xmlio\_server.def}.
1254Typically this namelist serves the mean files whilst the \ngn{ namnc4} in
1255the main namelist file continues to serve the restart files.
1256This duplication is unfortunate but appropriate since, if using io\_servers, the domain sizes of
1257the individual files produced by the io\_server processes may be different to those produced by
1258the invidual processing regions and different chunking choices may be desired.
1259 
1260% -------------------------------------------------------------------------------------------------------------
1261%       Tracer/Dynamics Trends
1262% -------------------------------------------------------------------------------------------------------------
1263\section{Tracer/Dynamics trends  (\protect\ngn{namtrd})}
1264\label{sec:DIA_trd}
1265
1266%------------------------------------------namtrd----------------------------------------------------
1267
1268\nlst{namtrd} 
1269%-------------------------------------------------------------------------------------------------------------
1270
1271Each trend of the dynamics and/or temperature and salinity time evolution equations can be send to
1272\mdl{trddyn} and/or \mdl{trdtra} modules (see TRD directory) just after their computation ($i.e.$ at
1273the end of each $dyn\cdots.F90$ and/or $tra\cdots.F90$ routines).
1274This capability is controlled by options offered in \ngn{namtrd} namelist.
1275Note that the output are done with xIOS, and therefore the \key{IOM} is required.
1276
1277What is done depends on the \ngn{namtrd} logical set to \forcode{.true.}:
1278
1279\begin{description}
1280   \item[\np{ln\_glo\_trd}]: at each \np{nn\_trd} time-step a check of the basin averaged properties of
1281                              the momentum and tracer equations is performed.
1282                              This also includes a check of $T^2$, $S^2$, $\tfrac{1}{2} (u^2+v2)$, and
1283                              potential energy time evolution equations properties;
1284   \item[\np{ln\_dyn\_trd}]: each 3D trend of the evolution of the two momentum components is output;
1285   \item[\np{ln\_dyn\_mxl}]: each 3D trend of the evolution of the two momentum components averaged over
1286                              the mixed layer is output;
1287   \item[\np{ln\_vor\_trd}]: a vertical summation of the moment tendencies is performed, then
1288                              the curl is computed to obtain the barotropic vorticity tendencies which
1289                              are output;
1290   \item[\np{ln\_KE\_trd}] : each 3D trend of the Kinetic Energy equation is output ;
1291   \item[\np{ln\_tra\_trd}]: each 3D trend of the evolution of temperature and salinity is output ;
1292   \item[\np{ln\_tra\_mxl}]: each 2D trend of the evolution of temperature and salinity averaged over
1293                              the mixed layer is output;
1294\end{description}
1295
1296Note that the mixed layer tendency diagnostic can also be used on biogeochemical models via
1297the \key{trdtrc} and \key{trdmld\_trc} CPP keys.
1298
1299\textbf{Note that} in the current version (v3.6), many changes has been introduced but not fully tested.
1300In particular, options associated with \np{ln\_dyn\_mxl}, \np{ln\_vor\_trd}, and \np{ln\_tra\_mxl} are
1301not working, and none of the options have been tested with variable volume ($i.e.$ \key{vvl} defined).
1302
1303% -------------------------------------------------------------------------------------------------------------
1304%       On-line Floats trajectories
1305% -------------------------------------------------------------------------------------------------------------
1306\section{FLO: On-Line Floats trajectories (\protect\key{floats})}
1307\label{sec:FLO}
1308%--------------------------------------------namflo-------------------------------------------------------
1309
1310\nlst{namflo} 
1311%--------------------------------------------------------------------------------------------------------------
1312
1313The on-line computation of floats advected either by the three dimensional velocity field or
1314constraint to remain at a given depth ($w = 0$ in the computation) have been introduced in
1315the system during the CLIPPER project.
1316Options are defined by \ngn{namflo} namelis variables.
1317The algorithm used is based either on the work of \cite{Blanke_Raynaud_JPO97} (default option), or
1318on a $4^th$ Runge-Hutta algorithm (\np{ln\_flork4}\forcode{ = .true.}).
1319Note that the \cite{Blanke_Raynaud_JPO97} algorithm have the advantage of providing trajectories which
1320are consistent with the numeric of the code, so that the trajectories never intercept the bathymetry.
1321
1322\subsubsection{Input data: initial coordinates}
1323
1324Initial coordinates can be given with Ariane Tools convention (IJK coordinates,
1325(\np{ln\_ariane}\forcode{ = .true.}) ) or with longitude and latitude.
1326
1327In case of Ariane convention, input filename is \np{init\_float\_ariane}.
1328Its format is: \\
1329{\scriptsize \texttt{I J K nisobfl itrash itrash}}
1330
1331\noindent with:
1332
1333 - I,J,K  : indexes of initial position
1334
1335 - nisobfl: 0 for an isobar float, 1 for a float following the w velocity 
1336
1337 - itrash : set to zero; it is a dummy variable to respect Ariane Tools convention
1338
1339\noindent Example: \\
1340\noindent {\scriptsize \texttt{
1341100.00000  90.00000  -1.50000 1.00000   0.00000   \\
1342102.00000  90.00000  -1.50000 1.00000   0.00000   \\
1343104.00000  90.00000  -1.50000 1.00000   0.00000   \\
1344106.00000  90.00000  -1.50000 1.00000   0.00000   \\
1345108.00000  90.00000  -1.50000 1.00000   0.00000}} \\
1346
1347In the other case (longitude and latitude), input filename is init\_float.
1348Its format is: \\
1349{\scriptsize \texttt{Long Lat depth nisobfl ngrpfl itrash}}
1350
1351\noindent with:
1352
1353 - Long, Lat, depth  : Longitude, latitude, depth
1354
1355 - nisobfl: 0 for an isobar float, 1 for a float following the w velocity
1356
1357 - ngrpfl : number to identify searcher group
1358
1359 - itrash :set to 1; it is a dummy variable.
1360
1361\noindent Example: \\
1362\noindent {\scriptsize \texttt{
1363 20.0 0.0 0.0 0 1 1    \\
1364-21.0 0.0 0.0 0 1 1    \\
1365-22.0 0.0 0.0 0 1 1    \\
1366-23.0 0.0 0.0 0 1 1    \\
1367-24.0 0.0 0.0 0 1 1 }} \\
1368
1369\np{jpnfl} is the total number of floats during the run.
1370When initial positions are read in a restart file (\np{ln\_rstflo}\forcode{ = .true.} ),
1371\np{jpnflnewflo} can be added in the initialization file.
1372
1373\subsubsection{Output data}
1374
1375\np{nn\_writefl} is the frequency of writing in float output file and \np{nn\_stockfl} is
1376the frequency of creation of the float restart file.
1377
1378Output data can be written in ascii files (\np{ln\_flo\_ascii}\forcode{ = .true.}).
1379In that case, output filename is trajec\_float.
1380
1381Another possiblity of writing format is Netcdf (\np{ln\_flo\_ascii}\forcode{ = .false.}).
1382There are 2 possibilities:
1383
1384 - if (\key{iomput}) is used, outputs are selected in  iodef.xml.
1385   Here it is an example of specification to put in files description section:
1386
1387\begin{xmllines}
1388<group id="1d_grid_T" name="auto" description="ocean T grid variables" >   }
1389   <file id="floats"  description="floats variables"> }
1390      <field ref="traj_lon"   name="floats_longitude"   freq_op="86400" />}
1391      <field ref="traj_lat"   name="floats_latitude"    freq_op="86400" />}
1392      <field ref="traj_dep"   name="floats_depth"       freq_op="86400" />}
1393      <field ref="traj_temp"  name="floats_temperature" freq_op="86400" />}
1394      <field ref="traj_salt"  name="floats_salinity"    freq_op="86400" />}
1395      <field ref="traj_dens"  name="floats_density"     freq_op="86400" />}
1396      <field ref="traj_group" name="floats_group"       freq_op="86400" />}
1397   </file>}
1398</group>}
1399\end{xmllines}
1400
1401 -  if (\key{iomput}) is not used, a file called \ifile{trajec\_float} will be created by IOIPSL library.
1402
1403See also \href{http://stockage.univ-brest.fr/~grima/Ariane/}{here} the web site describing
1404the off-line use of this marvellous diagnostic tool.
1405
1406% -------------------------------------------------------------------------------------------------------------
1407%       Harmonic analysis of tidal constituents
1408% -------------------------------------------------------------------------------------------------------------
1409\section{Harmonic analysis of tidal constituents (\protect\key{diaharm}) }
1410\label{sec:DIA_diag_harm}
1411
1412%------------------------------------------namdia_harm----------------------------------------------------
1413%
1414\nlst{nam_diaharm}
1415%----------------------------------------------------------------------------------------------------------
1416
1417A module is available to compute the amplitude and phase of tidal waves.
1418This on-line Harmonic analysis is actived with \key{diaharm}.
1419
1420Some parameters are available in namelist \ngn{namdia\_harm} :
1421
1422 - \np{nit000\_han} is the first time step used for harmonic analysis
1423
1424 - \np{nitend\_han} is the  last time step used for harmonic analysis
1425
1426 - \np{nstep\_han}  is the  time step frequency for harmonic analysis
1427
1428 - \np{nb\_ana}     is the number of harmonics to analyse
1429
1430 - \np{tname}       is an array with names of tidal constituents to analyse
1431
1432\np{nit000\_han} and \np{nitend\_han} must be between \np{nit000} and \np{nitend} of the simulation.
1433The restart capability is not implemented.
1434
1435The Harmonic analysis solve the following equation:
1436
1437\[h_{i} - A_{0} + \sum^{nb\_ana}_{j=1}[A_{j}cos(\nu_{j}t_{j}-\phi_{j})] = e_{i}\]
1438
1439With $A_{j}$, $\nu_{j}$, $\phi_{j}$, the amplitude, frequency and phase for each wave and
1440$e_{i}$ the error.
1441$h_{i}$ is the sea level for the time $t_{i}$ and $A_{0}$ is the mean sea level. \\
1442We can rewrite this equation:
1443
1444\[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}\]
1445
1446with $A_{j}=\sqrt{C^{2}_{j}+S^{2}_{j}}$ and $\phi_{j}=arctan(S_{j}/C_{j})$.
1447
1448We obtain in output $C_{j}$ and $S_{j}$ for each tidal wave.
1449
1450% -------------------------------------------------------------------------------------------------------------
1451%       Sections transports
1452% -------------------------------------------------------------------------------------------------------------
1453\section{Transports across sections (\protect\key{diadct}) }
1454\label{sec:DIA_diag_dct}
1455
1456%------------------------------------------namdct----------------------------------------------------
1457
1458\nlst{namdct}
1459%-------------------------------------------------------------------------------------------------------------
1460
1461A module is available to compute the transport of volume, heat and salt through sections.
1462This diagnostic is actived with \key{diadct}.
1463
1464Each section is defined by the coordinates of its 2 extremities.
1465The pathways between them are contructed using tools which can be found in
1466\texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT} 
1467and are written in a binary file
1468\texttt{section\_ijglobal.diadct\_ORCA2\_LIM} 
1469which is later read in by NEMO to compute on-line transports.
1470
1471The on-line transports module creates three output ascii files:
1472
1473- \texttt{volume\_transport} for volume transports (unit: $10^{6} m^{3} s^{-1}$)
1474
1475- \texttt{heat\_transport}   for   heat transports (unit: $10^{15} W$)
1476
1477- \texttt{salt\_transport}   for   salt transports (unit: $10^{9}Kg s^{-1}$) \\
1478
1479Namelist variables in \ngn{namdct} control how frequently the flows are summed and the time scales over
1480which they are averaged, as well as the level of output for debugging:
1481\np{nn\_dct}   : frequency of instantaneous transports computing
1482\np{nn\_dctwri}: frequency of writing ( mean of instantaneous transports )
1483\np{nn\_debug} : debugging of the section
1484
1485\subsubsection{Creating a binary file containing the pathway of each section}
1486
1487In \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT/run},
1488the file \textit{ {list\_sections.ascii\_global}} contains a list of all the sections that are to
1489be computed (this list of sections is based on MERSEA project metrics).
1490
1491Another file is available for the GYRE configuration (\texttt{ {list\_sections.ascii\_GYRE}}).
1492
1493Each section is defined by: \\
1494\noindent {\scriptsize \texttt{long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name}} \\
1495with:
1496
1497 - \texttt{long1 lat1}, coordinates of the  first extremity of the section;
1498
1499 - \texttt{long2 lat2}, coordinates of the second extremity of the section;
1500
1501 - \texttt{nclass}    the number of bounds of your classes (e.g. 3 bounds for 2 classes);
1502
1503 - \texttt{okstrpond} to compute    heat and       salt transports, \texttt{nostrpond} if no;
1504
1505 - \texttt{ice}       to compute surface and volume ice transports, \texttt{noice}     if no. \\
1506
1507\noindent The results of the computing of transports, and the directions of positive and
1508negative flow do not depend on the order of the 2 extremities in this file. \\
1509
1510\noindent If nclass $\neq$ 0,the next lines contain the class type and the nclass bounds: \\
1511{\scriptsize \texttt{
1512long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name \\
1513classtype                                                         \\
1514zbound1                                                           \\
1515zbound2                                                           \\
1516.                                                                 \\
1517.                                                                 \\
1518nclass-1                                                          \\
1519nclass}}
1520
1521\noindent where \texttt{classtype} can be:
1522
1523 - \texttt{zsal}  for          salinity classes
1524
1525 - \texttt{ztem}  for       temperature classes
1526
1527 - \texttt{zlay}  for             depth classes
1528
1529 - \texttt{zsigi} for    insitu density classes
1530
1531 - \texttt{zsigp} for potential density classes \\
1532 
1533The script \texttt{job.ksh} computes the pathway for each section and
1534creates a binary file \texttt{section\_ijglobal.diadct\_ORCA2\_LIM} which is read by NEMO. \\
1535
1536It is possible to use this tools for new configuations: \texttt{job.ksh} has to be updated with
1537the coordinates file name and path. \\
1538
1539Examples of two sections, the ACC\_Drake\_Passage with no classes, and the ATL\_Cuba\_Florida with
15404 temperature clases (5 class bounds), are shown: \\
1541\noindent {\scriptsize \texttt{
1542-68.    -54.5   -60.    -64.7  00 okstrpond noice ACC\_Drake\_Passage \\
1543-80.5    22.5   -80.5    25.5  05 nostrpond noice ATL\_Cuba\_Florida  \\
1544ztem                                                                  \\
1545-2.0                                                                  \\
1546 4.5                                                                  \\
1547 7.0                                                                  \\
154812.0                                                                  \\
154940.0}}
1550
1551\subsubsection{To read the output files}
1552
1553The output format is: \\
1554{\scriptsize \texttt{
1555date, time-step number, section number,                \\
1556section name, section slope coefficient, class number, \\
1557class name, class bound 1 , classe bound2,             \\
1558transport\_direction1, transport\_direction2,          \\
1559transport\_total}}                                     \\
1560
1561For sections with classes, the first \texttt{nclass-1} lines correspond to the transport for
1562each class and the last line corresponds to the total transport summed over all classes.
1563For sections with no classes, class number \texttt{1} corresponds to \texttt{total class} and
1564this class is called \texttt{N}, meaning \texttt{none}.
1565
1566- \texttt{transport\_direction1} is the positive part of the transport ($\geq$ 0).
1567
1568- \texttt{transport\_direction2} is the negative part of the transport ($\leq$ 0). \\
1569
1570\noindent The \texttt{section slope coefficient} gives information about the significance of
1571transports signs and direction: \\
1572
1573\begin{table} \scriptsize
1574   \begin{tabular}{|l|l|l|l|l|} \hline
1575      section slope coefficient      & section type & direction 1 & direction 2 & total transport
1576      \\ \hline
1577      0.                             & horizontal   & northward   & southward   & postive: northward
1578      \\ \hline
1579      1000.                          & vertical     & eastward    & westward    & postive: eastward
1580      \\ \hline
1581      \texttt{$\neq$ 0, $\neq$ 1000.} & diagonal     & eastward    & westward   & postive: eastward
1582      \\ \hline
1583   \end{tabular}
1584\end{table}
1585
1586% ================================================================
1587% Steric effect in sea surface height
1588% ================================================================
1589\section{Diagnosing the steric effect in sea surface height}
1590\label{sec:DIA_steric}
1591
1592
1593Changes in steric sea level are caused when changes in the density of the water column imply an
1594expansion or contraction of the column.
1595It is essentially produced through surface heating/cooling and to a lesser extent through
1596non-linear effects of the equation of state (cabbeling, thermobaricity...).
1597Non-Boussinesq models contain all ocean effects within the ocean acting on the sea level.
1598In particular, they include the steric effect.
1599In contrast, Boussinesq models, such as \NEMO, conserve volume, rather than mass,
1600and so do not properly represent expansion or contraction.
1601The steric effect is therefore not explicitely represented.
1602This approximation does not represent a serious error with respect to the flow field calculated by
1603the model \citep{Greatbatch_JGR94}, but extra attention is required when investigating sea level,
1604as steric changes are an important contribution to local changes in sea level on seasonal and
1605climatic time scales.
1606This is especially true for investigation into sea level rise due to global warming.
1607
1608Fortunately, the steric contribution to the sea level consists of a spatially uniform component that
1609can be diagnosed by considering the mass budget of the world ocean \citep{Greatbatch_JGR94}.
1610In order to better understand how global mean sea level evolves and thus how the steric sea level can
1611be diagnosed, we compare, in the following, the non-Boussinesq and Boussinesq cases.
1612
1613Let denote
1614$\mathcal{M}$ the total mass    of liquid seawater ($\mathcal{M} = \int_D \rho dv$),
1615$\mathcal{V}$ the total volume  of        seawater      ($\mathcal{V} = \int_D dv$),
1616$\mathcal{A}$ the total surface of       the ocean      ($\mathcal{A} = \int_S ds$),
1617$\bar{\rho}$ the global mean  seawater (\textit{in situ}) density
1618($\bar{\rho} = 1/\mathcal{V} \int_D \rho \,dv$), and
1619$\bar{\eta}$ the global mean sea level
1620($\bar{\eta} = 1/\mathcal{A} \int_S \eta \,ds$).
1621
1622A non-Boussinesq fluid conserves mass. It satisfies the following relations:
1623
1624\[ \begin{split}
1625      \mathcal{M} &=  \mathcal{V}  \;\bar{\rho} \\
1626      \mathcal{V} &=  \mathcal{A}  \;\bar{\eta}
1627   \end{split}  \label{eq:MV_nBq}
1628\]
1629
1630Temporal changes in total mass is obtained from the density conservation equation :
1631
1632\[ \frac{1}{e_3} \partial_t ( e_3\,\rho) + \nabla( \rho \, \textbf{U} ) 
1633   = \left. \frac{\textit{emp}}{e_3}\right|_\textit{surface}
1634 \label{eq:Co_nBq} \]
1635
1636where $\rho$ is the \textit{in situ} density, and \textit{emp} the surface mass
1637exchanges with the other media of the Earth system (atmosphere, sea-ice, land).
1638Its global averaged leads to the total mass change
1639
1640\[ \partial_t \mathcal{M} = \mathcal{A} \;\overline{\textit{emp}}
1641 \label{eq:Mass_nBq} \]
1642
1643where $\overline{\textit{emp}} = \int_S \textit{emp}\,ds$ is the net mass flux through the ocean surface.
1644Bringing \autoref{eq:Mass_nBq} and the time derivative of \autoref{eq:MV_nBq} together leads to
1645the evolution equation of the mean sea level
1646
1647\[ \partial_t \bar{\eta} = \frac{\overline{\textit{emp}}}{ \bar{\rho}}
1648                         - \frac{\mathcal{V}}{\mathcal{A}} \;\frac{\partial_t \bar{\rho} }{\bar{\rho}}
1649 \label{eq:ssh_nBq} \]
1650
1651The first term in equation \autoref{eq:ssh_nBq} alters sea level by adding or
1652subtracting mass from the ocean.
1653The second term arises from temporal changes in the global mean density; $i.e.$ from steric effects.
1654
1655In a Boussinesq fluid, $\rho$ is replaced by $\rho_o$ in all the equation except when
1656$\rho$ appears multiplied by the gravity ($i.e.$ in the hydrostatic balance of the primitive Equations).
1657In particular, the mass conservation equation, \autoref{eq:Co_nBq}, degenerates into
1658the incompressibility equation:
1659
1660\[ \frac{1}{e_3} \partial_t ( e_3 ) + \nabla( \textbf{U} )
1661   = \left. \frac{\textit{emp}}{\rho_o \,e_3}\right|_ \textit{surface}
1662 \label{eq:Co_Bq} \]
1663
1664and the global average of this equation now gives the temporal change of the total volume,
1665
1666\[ \partial_t \mathcal{V} = \mathcal{A} \;\frac{\overline{\textit{emp}}}{\rho_o}
1667 \label{eq:V_Bq} \]
1668
1669Only the volume is conserved, not mass, or, more precisely, the mass which is conserved is
1670the Boussinesq mass, $\mathcal{M}_o = \rho_o \mathcal{V}$.
1671The total volume (or equivalently the global mean sea level) is altered only by net volume fluxes across
1672the ocean surface, not by changes in mean mass of the ocean: the steric effect is missing in
1673a Boussinesq fluid.
1674
1675Nevertheless, following \citep{Greatbatch_JGR94}, the steric effect on the volume can be diagnosed by
1676considering the mass budget of the ocean.
1677The apparent changes in $\mathcal{M}$, mass of the ocean, which are not induced by
1678surface mass flux must be compensated by a spatially uniform change in the mean sea level due to
1679expansion/contraction of the ocean \citep{Greatbatch_JGR94}.
1680In others words, the Boussinesq mass, $\mathcal{M}_o$, can be related to $\mathcal{M}$,
1681the  total mass of the ocean seen by the Boussinesq model, via the steric contribution to the sea level,
1682$\eta_s$, a spatially uniform variable, as follows:
1683
1684\[ \mathcal{M}_o = \mathcal{M} + \rho_o \,\eta_s \,\mathcal{A}
1685 \label{eq:M_Bq} \]
1686
1687Any change in $\mathcal{M}$ which cannot be explained by the net mass flux through
1688the ocean surface is converted into a mean change in sea level.
1689Introducing the total density anomaly, $\mathcal{D}= \int_D d_a \,dv$, where
1690$d_a = (\rho -\rho_o ) / \rho_o$ is the density anomaly used in \NEMO (cf. \autoref{subsec:TRA_eos}) in
1691\autoref{eq:M_Bq} leads to a very simple form for the steric height:
1692
1693\[ \eta_s = - \frac{1}{\mathcal{A}} \mathcal{D}
1694 \label{eq:steric_Bq} \]
1695
1696The above formulation of the steric height of a Boussinesq ocean requires four remarks.
1697First, one can be tempted to define $\rho_o$ as the initial value of $\mathcal{M}/\mathcal{V}$,
1698$i.e.$ set $\mathcal{D}_{t=0}=0$, so that the initial steric height is zero.
1699We do not recommend that.
1700Indeed, in this case $\rho_o$ depends on the initial state of the ocean.
1701Since $\rho_o$ has a direct effect on the dynamics of the ocean (it appears in
1702the pressure gradient term of the momentum equation) it is definitively not a good idea when
1703inter-comparing experiments.
1704We better recommend to fixe once for all $\rho_o$ to $1035\;Kg\,m^{-3}$.
1705This value is a sensible choice for the reference density used in a Boussinesq ocean climate model since,
1706with the exception of only a small percentage of the ocean, density in the World Ocean varies by
1707no more than 2$\%$ from this value (\cite{Gill1982}, page 47).
1708
1709Second, we have assumed here that the total ocean surface, $\mathcal{A}$, does not change when
1710the sea level is changing as it is the case in all global ocean GCMs
1711(wetting and drying of grid point is not allowed).
1712 
1713Third, the discretisation of \autoref{eq:steric_Bq} depends on the type of
1714free surface which is considered.
1715In the non linear free surface case, $i.e.$ \key{vvl} defined, it is given by
1716
1717\[ \eta_s = - \frac{ \sum_{i,\,j,\,k} d_a\; e_{1t} e_{2t} e_{3t} }
1718                   { \sum_{i,\,j,\,k}       e_{1t} e_{2t} e_{3t} }
1719 \label{eq:discrete_steric_Bq_nfs} \]
1720
1721whereas in the linear free surface, the volume above the \textit{z=0} surface must be explicitly
1722taken into account to better approximate the total ocean mass and thus the steric sea level:
1723
1724\[ \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 }
1725                   { \sum_{i,\,j,\,k}       e_{1t}e_{2t}e_{3t} + \sum_{i,\,j}      e_{1t}e_{2t} \eta }
1726 \label{eq:discrete_steric_Bq_fs} \]
1727
1728The fourth and last remark concerns the effective sea level and the presence of sea-ice.
1729In the real ocean, sea ice (and snow above it)  depresses the liquid seawater through its mass loading.
1730This depression is a result of the mass of sea ice/snow system acting on the liquid ocean.
1731There is, however, no dynamical effect associated with these depressions in the liquid ocean sea level,
1732so that there are no associated ocean currents.
1733Hence, the dynamically relevant sea level is the effective sea level, $i.e.$ the sea level as if
1734sea ice (and snow) were converted to liquid seawater \citep{Campin_al_OM08}.
1735However, in the current version of \NEMO the sea-ice is levitating above the ocean without
1736mass exchanges between ice and ocean.
1737Therefore the model effective sea level is always given by $\eta + \eta_s$,
1738whether or not there is sea ice present.
1739
1740In AR5 outputs, the thermosteric sea level is demanded.
1741It is steric sea level due to changes in ocean density arising just from changes in temperature.
1742It is given by:
1743
1744\[ \eta_s = - \frac{1}{\mathcal{A}} \int_D d_a(T,S_o,p_o) \,dv
1745 \label{eq:thermosteric_Bq} \]
1746
1747where $S_o$ and $p_o$ are the initial salinity and pressure, respectively.
1748
1749Both steric and thermosteric sea level are computed in \mdl{diaar5} which needs
1750the \key{diaar5} defined to be called.
1751
1752% -------------------------------------------------------------------------------------------------------------
1753%       Other Diagnostics
1754% -------------------------------------------------------------------------------------------------------------
1755\section{Other diagnostics (\protect\key{diahth}, \protect\key{diaar5})}
1756\label{sec:DIA_diag_others}
1757
1758Aside from the standard model variables, other diagnostics can be computed on-line.
1759The available ready-to-add diagnostics modules can be found in directory DIA.
1760
1761\subsection{Depth of various quantities (\protect\mdl{diahth})}
1762
1763Among the available diagnostics the following ones are obtained when defining the \key{diahth} CPP key:
1764
1765- the mixed layer depth (based on a density criterion \citep{de_Boyer_Montegut_al_JGR04}) (\mdl{diahth})
1766
1767- the turbocline depth (based on a turbulent mixing coefficient criterion) (\mdl{diahth})
1768
1769- the depth of the 20\deg C isotherm (\mdl{diahth})
1770
1771- the depth of the thermocline (maximum of the vertical temperature gradient) (\mdl{diahth})
1772
1773% -----------------------------------------------------------
1774%     Poleward heat and salt transports
1775% -----------------------------------------------------------
1776
1777\subsection{Poleward heat and salt transports (\protect\mdl{diaptr})}
1778
1779%------------------------------------------namptr-----------------------------------------
1780
1781\nlst{namptr} 
1782%-----------------------------------------------------------------------------------------
1783
1784The poleward heat and salt transports, their advective and diffusive component, and
1785the meriodional stream function can be computed on-line in \mdl{diaptr} \np{ln\_diaptr} to true
1786(see the \textit{\ngn{namptr} } namelist below).
1787When \np{ln\_subbas}\forcode{ = .true.}, transports and stream function are computed for the Atlantic,
1788Indian, Pacific and Indo-Pacific Oceans (defined north of 30\deg S) as well as for the World Ocean.
1789The sub-basin decomposition requires an input file (\ifile{subbasins}) which contains
1790three 2D mask arrays, the Indo-Pacific mask been deduced from the sum of the Indian and
1791Pacific mask (\autoref{fig:mask_subasins}).
1792
1793%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
1794\begin{figure}[!t] \begin{center}
1795   \includegraphics[width=1.0\textwidth]{Fig_mask_subasins}
1796   \caption{   \protect\label{fig:mask_subasins}
1797      Decomposition of the World Ocean (here ORCA2) into sub-basin used in to compute the heat and
1798      salt transports as well as the meridional stream-function: Atlantic basin (red),
1799      Pacific basin (green), Indian basin (bleue), Indo-Pacific basin (bleue+green).
1800      Note that semi-enclosed seas (Red, Med and Baltic seas) as well as Hudson Bay are removed from
1801      the sub-basins. Note also that the Arctic Ocean has been split into Atlantic and
1802      Pacific basins along the North fold line.}
1803\end{center} \end{figure} 
1804%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
1805
1806% -----------------------------------------------------------
1807%       CMIP specific diagnostics
1808% -----------------------------------------------------------
1809\subsection{CMIP specific diagnostics (\protect\mdl{diaar5})}
1810
1811A series of diagnostics has been added in the \mdl{diaar5}.
1812They corresponds to outputs that are required for AR5 simulations (CMIP5)
1813(see also \autoref{sec:DIA_steric} for one of them).
1814Activating those outputs requires to define the \key{diaar5} CPP key.
1815
1816% -----------------------------------------------------------
1817%       25 hour mean and hourly Surface, Mid and Bed
1818% -----------------------------------------------------------
1819\subsection{25 hour mean output for tidal models}
1820
1821%------------------------------------------nam_dia25h-------------------------------------
1822
1823\nlst{nam_dia25h}
1824%-----------------------------------------------------------------------------------------
1825
1826A module is available to compute a crudely detided M2 signal by obtaining a 25 hour mean.
1827The 25 hour mean is available for daily runs by summing up the 25 hourly instantananeous hourly values from
1828midnight at the start of the day to midight at the day end.
1829This diagnostic is actived with the logical  $ln\_dia25h$
1830
1831% -----------------------------------------------------------
1832%     Top Middle and Bed hourly output
1833% -----------------------------------------------------------
1834\subsection{Top middle and bed hourly output}
1835
1836%------------------------------------------nam_diatmb-----------------------------------------------------
1837
1838\nlst{nam_diatmb}
1839%----------------------------------------------------------------------------------------------------------
1840
1841A module is available to output the surface (top), mid water and bed diagnostics of a set of
1842standard variables.
1843This can be a useful diagnostic when hourly or sub-hourly output is required in
1844high resolution tidal outputs.
1845The tidal signal is retained but the overall data usage is cut to just three vertical levels.
1846Also the bottom level is calculated for each cell.
1847This diagnostic is actived with the logical  $ln\_diatmb$
1848
1849% -----------------------------------------------------------
1850%     Courant numbers
1851% -----------------------------------------------------------
1852\subsection{Courant numbers}
1853
1854Courant numbers provide a theoretical indication of the model's numerical stability.
1855The advective Courant numbers can be calculated according to
1856
1857\[ C_u = |u|\frac{\rdt}{e_{1u}}, \quad C_v = |v|\frac{\rdt}{e_{2v}}, \quad C_w = |w|\frac{\rdt}{e_{3w}}
1858 \label{eq:CFL} \]
1859
1860in the zonal, meridional and vertical directions respectively.
1861The vertical component is included although it is not strictly valid as the vertical velocity is
1862calculated from the continuity equation rather than as a prognostic variable.
1863Physically this represents the rate at which information is propogated across a grid cell.
1864Values greater than 1 indicate that information is propagated across more than one grid cell in
1865a single time step.
1866
1867The variables can be activated by setting the \np{nn\_diacfl} namelist parameter to 1 in
1868the \ngn{namctl} namelist.
1869The diagnostics will be written out to an ascii file named cfl\_diagnostics.ascii.
1870In this file the maximum value of $C_u$, $C_v$, and $C_w$ are printed at each timestep along with
1871the coordinates of where the maximum value occurs.
1872At the end of the model run the maximum value of $C_u$, $C_v$, and $C_w$ for the whole model run is
1873printed along with the coordinates of each.
1874The maximum values from the run are also copied to the ocean.output file.
1875
1876% ================================================================
1877
1878\end{document}
Note: See TracBrowser for help on using the repository browser.