source: branches/2017/dev_merge_2017/DOC/texfiles/chapters/chap_DIA.tex @ 9373

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

Global reorganisation of DOC directory: files/folders renaming

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