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

Last change on this file since 10354 was 10354, checked in by nicolasmartin, 2 years ago

Vast edition of LaTeX subfiles to improve the readability by cutting sentences in a more suitable way
Every sentence begins in a new line and if necessary is splitted around 110 characters lenght for side-by-side visualisation,
this setting may not be adequate for everyone but something has to be set.
The punctuation was the primer trigger for the cutting process, otherwise subordinators and coordinators, in order to mostly keep a meaning for each line

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