source: branches/2013/dev_LOCEAN_2013/DOC/TexFiles/Chapters/Chap_DIA.tex @ 4148

Last change on this file since 4148 was 4148, checked in by cetlod, 8 years ago

merge in trunk changes between r3853 and r3940 and commit the changes, see ticket #1169

File size: 65.1 KB
Line 
1% ================================================================
2% Chapter � I/O & Diagnostics
3% ================================================================
4\chapter{Ouput and Diagnostics (IOM, DIA, TRD, FLO)}
5\label{DIA}
6\minitoc
7
8\newpage
9$\ $\newline    % force a new ligne
10
11% ================================================================
12%       Old Model Output
13% ================================================================
14\section{Old Model Output (default or \key{dimgout})}
15\label{DIA_io_old}
16
17The model outputs are of three types: the restart file, the output listing,
18and the output file(s). The restart file is used internally by the code when
19the user wants to start the model with initial conditions defined by a
20previous simulation. It contains all the information that is necessary in
21order for there to be no changes in the model results (even at the computer
22precision) between a run performed with several restarts and the same run
23performed in one step. It should be noted that this requires that the restart file
24contain two consecutive time steps for all the prognostic variables, and
25that it is saved in the same binary format as the one used by the computer
26that is to read it (in particular, 32 bits binary IEEE format must not be used for
27this file). The output listing and file(s) are predefined but should be checked
28and eventually adapted to the user's needs. The output listing is stored in
29the $ocean.output$ file. The information is printed from within the code on the
30logical unit $numout$. To locate these prints, use the UNIX command
31"\textit{grep -i numout}" in the source code directory.
32
33By default, outpout files are written in NetCDF format but an IEEE output format, called DIMG, can be choosen when defining \key{dimgout}. Since version 3.2, when defining \key{iomput}, an I/O server has been added which provides more flexibility in the choice of the fields to be outputted as well as how the writing work is distributed over the processors in massively parallel computing. The complete description of the use of this I/O server is presented in next section. If neither \key{iomput} nor \key{dimgout} are defined, NEMO is producing NetCDF with the old IOIPSL library which has been kept for compatibility and its easy installation, but it is quite inefficient on parrallel machines. If \key{iomput} is not defined, output files are defined in the \mdl{diawri} module and containing mean (or instantaneous if \key{diainstant} is defined) values over a period of nn\_write time-step (namelist parameter).
34
35%\gmcomment{                    % start of gmcomment
36
37% ================================================================
38% Diagnostics
39% ================================================================
40\section{Standard model Output (IOM)}
41\label{DIA_iom}
42
43
44Since version 3.2, iomput is the NEMO output interface. It was designed to be simple to use, flexible and efficient. The two main purposes of iomput are: \\
45(1) the complete and flexible control of the output files through an external xml file defined by the user \\
46(2) to achieve high performance outputs through the distribution (or not) of all tasks related to output files on dedicated processes. \\
47The first functionality allows the user to specify, without touching anything into the code, the way he want to output data: \\
48- choice of output frequencies that can be different for each file (including real months and years) \\
49- choice of file contents: decide which data will be written in which file (the same data can be outputted in different files)  \\
50- possibility to split output files at a choosen frequency \\
51- possibility to extract a vertical or an horizontal subdomain  \\
52- choice of the temporal operation to perform: average, accumulate, instantaneous, min, max and once  \\
53- extremely large choice of data available   \\
54- redefine variables name and long\_name  \\
55In addition, iomput allows the user to output any variable (scalar, 2D or 3D) in the code in a very easy way. All details of iomput functionalities are listed in the following subsections. Example of the iodef.xml files that control the outputs can be found here: NEMOGCM/CONFIG/ORCA2\_LIM/EXP00/iodef*.xml
56
57The second functionality targets outputs performances when running on a very large number of processes. First, iomput provides the possibility to dedicate N specific processes (in addition to NEMO processes) to write the outputs, where N is big enough (and defined by the user) to suppress the bottle neck associated with the the writing of the output files. Since version 3.5, this interface depends on an external code called \href{http://forge.ipsl.jussieu.fr/ioserver}{XIOS}. This new IO server takes advantage of the new functionalitiy of NetCDF4 that allows the user to write files in parallel and therefore to bypass the rebuilding phase. Note that writting in parallel into the same NetCDF files requires that your NetCDF4 library is linked to an HDF5 library that has been correctly compiled (i.e. with the configure option $--$enable-parallel). Note that the files created by iomput trough xios are incompatible with NetCDF3. All post-processsing and visualization tools must therefore be compatible with NetCDF4 and not only NetCDF3.
58
59\subsection{Basic knowledge}
60
61
62\subsubsection{ XML basic rules}
63
64XML tags begin with the less-than character ("$<$") and end with the greater-than character (''$>$'').
65You use tags to mark the start and end of elements, which are the logical units of information
66in an XML document. In addition to marking the beginning of an element, XML start tags also
67provide a place to specify attributes. An attribute specifies a single property for an element,
68using a name/value pair, for example: $<$a b="x" c="y" b="z"$>$ ... $<$/a$>$.
69See \href{http://www.xmlnews.org/docs/xml-basics.html}{here} for more details.
70
71\subsubsection{Structure of the xml file used in NEMO}
72
73The XML file used in XIOS is structured by 7 families of tags: context, axis, domain, grid, field, file and variable. Each tag family has hierarchy of three flavors (except for context):
74\begin{description}
75\item[root]: declaration of the root element that can contain element groups or elements, for example : $<$file\_definition ...$/>$ \\
76\item[group]: declaration of a group element that can contain element groups or elements, for example : $<$file\_group ...$/>$ \\
77\item[element]: declaration of an element that can contain elements, for example : $<$file ...$/>$  \\
78\end{description}
79
80Each element may have several attributes. Some attributes are mandatory, other are optional but have a default value and other are are completely optional. Id is a special attribute used to identify an element or a group of elements. It must be unique for a kind of element. It is optional, but no reference to the corresponding element can be done if it is not defined.
81
82The XML file is split into context tags that are used to isolate IO definition from different codes or different parts of a code. No interference is possible between 2 different contexts. Each context has its own calendar and an associated timestep. In NEMO, we used the following contexts (that can be defined in any order):
83\begin{description}
84\item[contex xios]: context containing informations for XIOS \\
85\verb?   <context id="xios" ... ?
86\item[context nemo]: contex containing IO informations for NEMO (mother grid when using AGRIF) \\
87\verb?   <context id="nemo" ... ?
88\item[context 1\_nemo]: contex containing IO informations for NEMO child grid 1 (when using AGRIF) \\
89\verb?   <context id="1_nemo" ... ? 
90\item[context n\_nemo]: contex containing IO informations for NEMO child grid n (when using AGRIF) \\
91\verb?   <context id="n_nemo" ... ?
92\end{description}
93
94Each context tag related to NEMO (mother or child grids) is divided into 5 parts (that can be defined in any order):
95\begin{description}
96\item[field definition]: define all variables that can potentially be outputted \\
97\verb?   <field_definition ... ?
98\item[file definition]: define the netcdf files to be created and the variables they will contain \\
99\verb?   <file_definition ... ?
100\item[axis definitions]: define vertical axis \\
101\verb?   <axis_definition ... ?
102\item[domain definitions]: define the horizontal grids \\
103\verb?   <domain_definition ... ?
104\item[grid definitions]: define the 2D and 3D grids (association of an axis and a domain) \\
105\verb?   <grid_definition ... ?
106\end{description}
107
108the xios context contains only 1 tag:
109\begin{description}
110\item[variable definition]: define variables needed by xios. This can be seen as a kind of namelist for xios. \\
111\verb?   <variable_definition ... ?
112\end{description}
113
114The XML file can be split in different parts to improve its readability and facilitate its use. The inclusing of XML files into the main XML file can be done through the attribute src: \\
115\verb?   <context src="./nemo_def.xml" /> ?
116In NEMO, by default, the field and domain définition is done in 2 séparate files: \\
117NEMOGCM/CONFIG/SHARED/field\_def.xml and \\
118NEMOGCM/CONFIG/SHARED/domain\_def.xml that are included in the main iodef.xml file through the following commands: \\
119\verb?   <field_definition src="./field_def.xml" /> ? \\
120\verb?   <domain_definition src="./domain_def.xml" /> ?
121
122
123\subsubsection{Use of inheritance}
124
125XML extensively uses the concept of inheritance. XML has a based tree structure with a parent-child oriented relation: all children inherit attributes from parent, but an attribute defined in a child replace the inherited attribute value. Note that the special attribute ''id'' is never inherited.  \\
126\\
127example 1: Direct inheritance. \\
128\begin{alltt}  {{\scriptsize   
129\begin{verbatim}
130   <field_definition operation="average" >
131      <field id="sst"                    />   <!-- averaged      sst -->
132      <field id="sss" operation="instant"/>   <!-- instantaneous sss -->
133   </field_definition>
134\end{verbatim}
135}}\end{alltt} 
136
137The field ''sst'' which is part (or a child) of the field\_definition will inherit the value ''average''
138of the attribute ''operation'' from its parent. Note that a child can overwrite
139the attribute definition inherited from its parents. In the example above, the field ''sss'' will
140for example output instantaneous values instead of average values. \\
141\\
142example 2: Inheritance by reference. \\
143\begin{alltt}  {{\scriptsize
144\begin{verbatim}
145   <field_definition>
146      <field id="sst" long_name="sea surface temperature" />   
147      <field id="sss" long_name="sea surface salinity"    /> 
148   </field_definition>     
149
150   <file_definition>
151      <file id="myfile" output_freq="1d" />   
152            <field field_ref="sst"                            />  <!-- default def -->
153            <field field_ref="sss" long_name="my description" />  <!-- overwrite   -->
154      </file>   
155   </file_definition>
156\end{verbatim}
157}}\end{alltt} 
158Inherite (and overwrite, if needed) the attributes of a tag you are refering to.
159
160\subsubsection{Use of Group}
161
162Groups can be used fort 2 purposes. \\
163
164First, the group can be used to define common attributes to be shared by the elements of the group through the inheritance. In the following example, we define a group of field that will share a common grid ''grid\_T\_2D''. Note that for the field ''toce'', we overwrite the grid definition inherited from the group by ''grid\_T\_3D''.
165\begin{alltt}  {{\scriptsize
166\begin{verbatim}
167   <field_group id="grid_T" grid_ref="grid_T_2D">
168      <field id="toce" long_name="temperature"             unit="degC" grid_ref="grid_T_3D"/>
169      <field id="sst"  long_name="sea surface temperature" unit="degC"                     />
170      <field id="sss"  long_name="sea surface salinity"    unit="psu"                      />
171      <field id="ssh"  long_name="sea surface height"      unit="m"                        />
172         ...
173\end{verbatim}
174}}\end{alltt} 
175
176Second, the group can be used to replace a list of elements. Several examples of groups of fields are proposed at the end of the file \\
177NEMOGCM/CONFIG/SHARED/field\_def.xml. For example, a short list of usual variables related to the U grid:
178\begin{alltt}  {{\scriptsize
179\begin{verbatim}
180   <field_group id="groupU" >
181      <field field_ref="uoce"  />
182      <field field_ref="suoce" />
183      <field field_ref="utau"  />
184   </field_group>
185\end{verbatim}
186}}\end{alltt} 
187that can be directly include in a file through the following syntaxe:
188\begin{alltt}  {{\scriptsize
189\begin{verbatim}
190   <file id="myfile_U" output_freq="1d" />   
191      <field_group group_ref="groupU"/> 
192      <field field_ref="uocetr_eff"  />  <!-- add another field -->
193   </file>   
194\end{verbatim}
195}}\end{alltt} 
196
197\subsection{Detailed functionalities }
198
199The file NEMOGCM/CONFIG/ORCA2\_LIM/iodef\_demo.xml provides several examples of the use of the new functionalities offered by the XML interface of XIOS.
200
201\subsubsection{Define horizontal subdomains}
202Horizontal subdomains are defined through the attributs zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj of the tag family domain. It must therefore be done in the domain part of the XML file. For example, in NEMOGCM/CONFIG/SHARED/domain\_def.xml, we provide the following example of a definition of a 5 by 5 box with the bottom left corner at point (10,10).
203\begin{alltt}  {{\scriptsize
204\begin{verbatim}
205   <domain_group id="grid_T">
206      <domain id="myzoom" zoom_ibegin="10" zoom_jbegin="10" zoom_ni="5" zoom_nj="5" />
207\end{verbatim}
208}}\end{alltt} 
209The use of this subdomain is done through the redefinition of the attribute domain\_ref of the tag family field. For example:
210\begin{alltt}  {{\scriptsize
211\begin{verbatim}
212   <file id="myfile_vzoom" output_freq="1d" >
213      <field field_ref="toce" domain_ref="myzoom"/>
214   </file>
215\end{verbatim}
216}}\end{alltt} 
217Moorings are seen as an extrem case corresponding to a 1 by 1 subdomain. The Equatorial section, the TAO, RAMA and PIRATA moorings are alredy registered in the code and can therefore be outputted without taking care of their (i,j) position in the grid. These predefined domains can be activated by the use of specific domain\_ref: ''EqT'', ''EqU'' or ''EqW'' for the equatorial sections and the mooring position for TAO, RAMA and PIRATA followed by ''T'' (for example: ''8s137eT'', ''1.5s80.5eT'' ...)
218\begin{alltt}  {{\scriptsize
219\begin{verbatim}
220   <file id="myfile_vzoom" output_freq="1d" >
221      <field field_ref="toce" domain_ref="0n180wT"/>
222   </file>
223\end{verbatim}
224}}\end{alltt} 
225Note 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.
226
227\subsubsection{Define vertical zooms}
228Vertical 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:
229\begin{alltt}  {{\scriptsize
230\begin{verbatim}
231   <axis_group id="deptht" long_name="Vertical T levels" unit="m" positive="down" >
232      <axis id="deptht" />
233      <axis id="deptht_myzoom" zoom_begin="1" zoom_end="10" />
234\end{verbatim}
235}}\end{alltt} 
236The use of this vertical zoom is done through the redefinition of the attribute axis\_ref of the tag family field. For example:
237\begin{alltt}  {{\scriptsize
238\begin{verbatim}
239   <file id="myfile_hzoom" output_freq="1d" >
240      <field field_ref="toce" axis_ref="deptht_myzoom"/>
241   </file>
242\end{verbatim}
243}}\end{alltt} 
244
245\subsubsection{Control of the output file names}
246
247The output file names are defined by the attributs ''name'' and ''name\_suffix'' of the tag family file. for example:
248\begin{alltt}  {{\scriptsize
249\begin{verbatim}
250   <file_group id="1d" output_freq="1d" name="myfile_1d" >
251      <file id="myfileA" name_suffix="_AAA" > <!-- will create file "myfile_1d_AAA"  -->
252         ...
253      </file>
254      <file id="myfileB" name_suffix="_BBB" > <!-- will create file "myfile_1d_BBB" -->
255         ...
256      </file>
257   </file_group>
258\end{verbatim}
259}}\end{alltt} 
260However it is also often very convienent to define the file name with the name of the experience, 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 99) or one of the predefined section or mooring (see next subsection), the following part of the name and the name\_suffix (that can be inherited) will be automatically replaced by: \\
261\\
262\begin{tabular}{|p{4cm}|p{8cm}|}
263   \hline
264   \centering part of the name automatically to be replaced &
265   by \\
266   \hline
267   \hline
268   \centering @expname@ &
269   the experience name (from cn\_exp in the namelist) \\
270   \hline
271   \centering @freq@ &
272   output frequency (from attribute output\_freq) \\
273   \hline
274   \centering @startdate@  &
275   starting date of the simulation (from nn\_date0 in the restart or the namelist). \verb?yyyymmdd? format \\
276   \hline
277   \centering @startdatefull@  & 
278   starting date of the simulation (from nn\_date0 in the restart or the namelist). \verb?yyyymmdd_hh:mm:ss? format \\
279   \hline
280   \centering @enddate@  &
281   ending date of the simulation (from nn\_date0 and nn\_itend in the namelist). \verb?yyyymmdd? format \\
282   \hline
283   \centering @enddatefull@  & 
284   ending date of the simulation (from nn\_date0 and nn\_itend in the namelist). \verb?yyyymmdd_hh:mm:ss? format \\
285   \hline
286\end{tabular}
287\\
288
289For example,
290
291\begin{alltt}  {{\scriptsize
292\begin{verbatim}
293   <file id="myfile_hzoom" name="myfile_@expname@_@startdate@_freq@freq@" output_freq="1d" >
294\end{verbatim}
295}}\end{alltt} 
296
297With, in the namelist:
298
299\begin{alltt}  {{\scriptsize
300\begin{verbatim}
301   cn_exp      =  "ORCA2"
302   nn_date0    =  19891231
303   ln_rstart   = .false.
304\end{verbatim}
305}}\end{alltt} 
306
307will give the following file name radical:
308
309\begin{alltt}  {{\scriptsize
310\begin{verbatim}
311   myfile_ORCA2_19891231_freq1d
312\end{verbatim}
313}}\end{alltt} 
314
315
316\subsubsection{Other controls of the xml attributes from NEMO}
317
318The values of some attributes are automatically defined by NEMO (and any definition given in the xml file is overwritten). By convention, these attributes are defined to ''auto'' (for string) or ''0000'' (for integer) in the xml file (but this is not necessary).
319
320Here is the list of these attributes: \\
321\\
322\begin{tabular}{|l|c|c|c|}
323   \hline
324 \multicolumn{2}{|c|}{tag ids affected by automatic           }  & name      & attribute value \\
325  \multicolumn{2}{|c|}{definition of some of their attributes }  & attribute  &        \\
326   \hline
327   \hline
328    \multicolumn{2}{|c|}{field\_definition} & freq\_op & \np{rn\_rdt} \\
329   \hline
330    \multicolumn{2}{|c|}{SBC}               & freq\_op & \np{rn\_rdt} $\times$ \np{nn\_fsbc}  \\
331   \hline
332    \multicolumn{2}{|c|}{ptrc\_T}           & freq\_op & \np{rn\_rdt} $\times$ \np{nn\_dttrc} \\
333   \hline
334    \multicolumn{2}{|c|}{diad\_T}           & freq\_op & \np{rn\_rdt} $\times$ \np{nn\_dttrc} \\
335   \hline
336    \multicolumn{2}{|c|}{EqT, EqU, EqW} & jbegin, ni,      & according to the grid    \\
337    \multicolumn{2}{|c|}{                         } & name\_suffix &                                      \\
338   \hline
339   \multicolumn{2}{|c|}{TAO, RAMA and PIRATA moorings} & zoom\_ibegin, zoom\_jbegin, & according to the grid    \\
340    \multicolumn{2}{|c|}{                                                       } & name\_suffix &                                      \\
341   \hline
342\end{tabular}
343
344
345\subsubsection{Tag list}
346
347
348\begin{tabular}{|p{2cm}|p{2.5cm}|p{3.5cm}|p{2cm}|p{2cm}|}
349   \hline
350   tag name & 
351   description & 
352   accepted attribute & 
353   child of &
354   parent of \\
355   \hline   
356   \hline   
357   simulation & 
358   this tag is the root tag which encapsulates all the content of the xml file &
359   none &
360   none &
361   context \\
362   \hline   
363   context &
364   encapsulates parts of the xml file dédicated to different codes or different parts of a code &
365   id (''xios'', ''nemo'' or ''n\_nemo'' for the nth AGRIF zoom), src, time\_origin &
366   simulation &
367   all root tags: ...\_definition \\
368   \hline   
369   \hline   
370   field\_definition &
371   encapsulates the definition of all the fields that can potentially be outputted &
372   axis\_ref, default\_value, domain\_ref, enabled, grid\_ref, level, operation, prec, src &
373   context &
374   field or field\_group \\
375   \hline   
376   field\_group &
377   encapsulates a group of fields &
378   axis\_ref, default\_value, domain\_ref, enabled, group\_ref, grid\_ref, id, level, operation, prec, src &
379   field\_definition, field\_group, file &
380   field or field\_group \\
381   \hline   
382   field &
383   define a specific field &
384   axis\_ref, default\_value, domain\_ref, enabled, field\_ref, grid\_ref, id, level, long\_name, name, operation, prec, standard\_name, unit &
385   field\_definition, field\_group, file &
386   none \\
387   \hline   
388   \hline   
389   file\_definition & 
390   encapsulates the definition of all the files that will be outputted &
391   enabled, min\_digits, name, name\_suffix, output\_level, split\_format, split\_freq, sync\_freq, type, src &
392   context & 
393   file or file\_group \\
394   \hline   
395   file\_group & 
396   encapsulates a group of files that will be outputted &
397   enabled, description, id, min\_digits, name, name\_suffix, output\_freq, output\_level, split\_format, split\_freq, sync\_freq, type, src &
398   file\_definition, file\_group & 
399   file or file\_group \\
400   \hline   
401   file & 
402   defile the contentof a file to be outputted &
403   enabled, description, id, min\_digits, name, name\_suffix, output\_freq, output\_level, split\_format, split\_freq, sync\_freq, type, src &
404   file\_definition, file\_group & 
405   field \\
406   \hline   
407\end{tabular}
408\begin{tabular}{|p{2cm}|p{2.5cm}|p{3.5cm}|p{2cm}|p{2cm}|}
409   \hline
410   tag name & 
411   description & 
412   accepted attribute & 
413   child of &
414   parent of \\
415   \hline   
416   \hline   
417   axis\_definition & 
418   define all the vertical axis potentially used by the variables &
419   src &
420   context & 
421   axis\_group, axis \\
422   \hline   
423   axis\_group & 
424   encapsulates a group of vertical axis &
425   id, lon\_name, positive, src, standard\_name, unit, zoom\_begin, zoom\_end, zoom\_size &
426   axis\_definition, axis\_group & 
427   axis\_group, axis \\
428   \hline   
429   axis & 
430   define a vertical axis &
431   id, lon\_name, positive, src, standard\_name, unit, zoom\_begin, zoom\_end, zoom\_size &
432   axis\_definition, axis\_group  & 
433   none \\
434   \hline   
435   \hline   
436   domain\_definition & 
437   define all the horizontal domains potentially used by the variables &
438   src &
439   context & 
440   domain\_group, domain \\
441   \hline   
442   domain\_group & 
443   encapsulates a group of horizontal domains &
444   id, lon\_name, src, zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj &
445   domain\_definition, domain\_group & 
446   domain\_group, domain \\
447   \hline   
448   domain & 
449   define an horizontal domain &
450   id, lon\_name, src, zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj &
451   domain\_definition, domain\_group & 
452   none \\
453   \hline   
454   \hline   
455   grid\_definition & 
456   define all the grid (association of a domain and/or an axis) potentially used by the variables &
457   src &
458   context & 
459   grid\_group, grid \\
460   \hline   
461   grid\_group & 
462   encapsulates a group of grids &
463   id, domain\_ref, axis\_ref &
464   grid\_definition, grid\_group & 
465   grid\_group, grid \\
466   \hline   
467   grid & 
468   define a grid &
469   id, domain\_ref, axis\_ref &
470   grid\_definition, grid\_group & 
471   none \\
472   \hline   
473\end{tabular}
474
475
476\subsubsection{Attributes list}
477
478\begin{tabular}{|p{2cm}|p{4cm}|p{4cm}|p{2cm}|}
479   \hline
480   attribute name & 
481   description & 
482   example & 
483   accepted by \\ 
484   \hline   
485   \hline   
486   axis\_ref & 
487   refers to the id of a vertical axis & 
488   axis\_ref="deptht" & 
489   field, grid families \\ 
490   \hline   
491   enabled & 
492   switch on/off the output of a field or a file & 
493   enabled=".TRUE." & 
494   field, file families \\ 
495   \hline   
496   default\_value & 
497   missing\_value definition & 
498   default\_value="1.e20" & 
499   field family \\ 
500   \hline   
501   description & 
502   just for information, not used & 
503   description="ocean T grid variables" & 
504   all tags \\ 
505   \hline   
506   domain\_ref & 
507   refers to the id of a domain & 
508   domain\_ref="grid\_T" & 
509   field or grid families \\ 
510   \hline   
511   field\_ref= & 
512   id of the field we want to add in a file & 
513   field\_ref="toce" & 
514   field \\ 
515   \hline   
516   grid\_ref & 
517   refers to the id of a grid & 
518   grid\_ref="grid\_T\_2D" & 
519   field family \\ 
520   \hline   
521   group\_ref & 
522   refer to a group of variables & 
523   group\_ref="mooring" & 
524   field\_group \\ 
525   \hline   
526   id & 
527   allow to identify a tag & 
528   id="nemo" &
529   accepted by all tags except simulation \\ 
530   \hline   
531   level & 
532   output priority of a field: 0 (high) to 10 (low)& 
533   level="1" & 
534   field family \\ 
535   \hline   
536   long\_name & 
537   define the long\_name attribute in the NetCDF file & 
538   long\_name="Vertical T levels" & 
539   field \\ 
540   \hline   
541   min\_digits & 
542   specify the minimum of digits used in the core number in the name of the NetCDF file & 
543   min\_digits="4" & 
544   file family \\ 
545   \hline   
546   name & 
547   name of a variable or a file. If the name of a file is undefined, its id is used as a name & 
548   name="tos" & 
549   field or file families \\ 
550   \hline   
551   name\_suffix & 
552   suffix to be inserted after the name and before the cpu number and the ''.nc'' termination of a file & 
553   name\_suffix="\_myzoom" & 
554   file family \\ 
555   \hline   
556\end{tabular}
557\begin{tabular}{|p{2cm}|p{4cm}|p{4cm}|p{2cm}|}
558   \hline
559   attribute name & 
560   description & 
561   example & 
562   accepted by \\ 
563   \hline   
564   \hline   
565   operation & 
566   type of temporal operation: average, accumulate, instantaneous, min, max and once & 
567   operation="average" & 
568   field family \\ 
569   \hline   
570   output\_freq & 
571   operation frequency. units can be ts (timestep), y, mo, d, h, mi, s. & 
572   output\_freq="1d12h" & 
573   field family \\ 
574   \hline   
575   output\_level & 
576   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. & 
577   output\_level="10"& 
578   file family \\ 
579   \hline   
580   positive & 
581   convention used for the orientation of vertival axis (positive downward in \NEMO). & 
582   positive="down" & 
583   axis family \\ 
584   \hline   
585   prec & 
586   output precision: real 4 or real 8 & 
587   prec="4" & 
588   field family \\ 
589   \hline   
590   split\_format & 
591   date format used in the name of splitted output files. can be spécified using the following syntaxe: \%y, \%mo, \%d, \%h \%mi and \%s & 
592   split\_format="\%yy\%mom\%dd" & 
593   file family \\ 
594   \hline   
595   split\_freq & 
596   split output files frequency. units can be ts (timestep), y, mo, d, h, mi, s. & 
597   split\_freq="1mo" & 
598   file family \\ 
599   \hline   
600   src & 
601   allow to include a file & 
602   src="./field\_def.xml" & 
603   accepted by all tags except simulation \\ 
604   \hline   
605   standard\_name & 
606   define the standard\_name attribute in the NetCDF file & 
607   standard\_name="Eastward\_Sea\_Ice\_Transport" & 
608   field \\ 
609   \hline   
610   sync\_freq & 
611   NetCDF file synchronization frequency (update of the time\_counter). units can be ts (timestep), y, mo, d, h, mi, s. & 
612   sync\_freq="10d" & 
613   file family \\ 
614   \hline   
615\end{tabular}
616\begin{tabular}{|p{2cm}|p{4cm}|p{4cm}|p{2cm}|}
617   \hline
618   attribute name & 
619   description & 
620   example & 
621   accepted by \\ 
622   \hline   
623   \hline   
624   time\_origin & 
625   specify the origin of the time counter & 
626   time\_origin="1900-01-01 00:00:00"& 
627   context \\ 
628   \hline   
629   type (1)& 
630   specify if the output files must be splitted (multiple\_file) or not (one\_file) & 
631   type="multiple\_file" & 
632   file familly \\ 
633   \hline   
634   type (2)& 
635   define the type of a variable tag & 
636   type="boolean" & 
637   variable \\ 
638   \hline   
639   unit & 
640   unit of a variable or the vertical axis & 
641   unit="m" & 
642   field and axis families \\ 
643   \hline   
644   zoom\_ibegin & 
645   starting point along x direction of the zoom. Automatically defined for TAO/RAMA/PIRATA moorings & 
646   zoom\_ibegin="1" & 
647   domain family \\ 
648   \hline   
649   zoom\_jbegin & 
650   starting point along y direction of the zoom. Automatically defined for TAO/RAMA/PIRATA moorings & 
651   zoom\_jbegin="1" & 
652   domain family \\ 
653   \hline   
654   zoom\_ni & 
655   zoom extent along x direction & 
656   zoom\_ni="1" & 
657   domain family \\ 
658   \hline   
659   zoom\_nj & 
660   zoom extent along y direction & 
661   zoom\_nj="1" & 
662   domain family \\ 
663   \hline   
664\end{tabular}
665
666\subsection{XIOS: the IO\_SERVER}
667
668\subsubsection{Attached or detached mode?}
669
670Iomput is based on \href{http://forge.ipsl.jussieu.fr/ioserver/wiki}{XIOS}, the io\_server developed by Yann Meurdesoif from IPSL. This server can be used in ''attached mode'' (as a library) or in ''detached mode'' (as an external executable on n cpus). The ''attached mode'' is simpler to use but much less efficient. If the type of file is ''multiple\_file'', then in attached(detached) mode, each NEMO(XIOS) process will output its own subdomain: if NEMO(XIOS) is runnning on N cores, the ouput files will be splitted into N files. If the type of file is ''one\_file'', the output files will be directly recombined into one unique file either in ''detached mode'' or ''attached mode''. 
671
672\subsubsection{Control of xios: the xios context in iodef.xml}
673
674The control of the use of xios is done through the xios context in iodef.xml.
675
676\begin{tabular}{|p{3cm}|p{6.5cm}|p{2.5cm}|}
677   \hline
678   variable name & 
679   description & 
680   example \\ 
681   \hline   
682   \hline
683   buffer\_size & 
684   buffer size used by XIOS to send data from NEMO to XIOS. Larger is more efficient. Note that needed/used buffer sizes are summarized at the end of the job & 
685   25000000 \\ 
686   \hline   
687   buffer\_server\_factor\_size & 
688   ratio between NEMO and XIOS buffer size. Should be 2. & 
689   2 \\ 
690   \hline
691   info\_level & 
692   verbosity level (0 to 100) & 
693   0 \\ 
694   \hline
695   using\_server & 
696   activate attached(false) or detached(true) mode & 
697   true \\ 
698   \hline
699   using\_oasis & 
700   xios is used with OASIS(true) or not (false) & 
701   false \\ 
702   \hline
703   oasis\_codes\_id & 
704   when using oasis, define the identifier of NEMO in the namcouple. Not that the identifier of XIOS is xios.x & 
705   oceanx \\ 
706   \hline   
707\end{tabular}
708
709\subsubsection{Number of cpu used by XIOS in detached mode}
710
711The number of cores used by the xios is specified only when launching the model. The number or cores dedicated to XIOS should be from ~1/10 to ~1/50 of the number or cores dedicated to NEMO (according of the amount of data to be created). Here is an example of 2 cpus for the io\_server and 62 cpu for opa using mpirun:
712
713\texttt{ mpirun -np 2 ./nemo.exe : -np 62 ./xios\_server.exe }
714
715\subsection{Practical issues}
716
717\subsubsection{Add your own outputs}
718
719It is very easy to add you own outputs with iomput. 4 points must be followed.
720\begin{description}
721\item[1-] in NEMO code, add a \\
722\texttt{      CALL iom\_put( 'identifier', array ) } \\
723where you want to output a 2D or 3D array.
724
725\item[2-] don't forget to add \\
726\texttt{   USE iom            ! I/O manager library }  \\
727in the list of used modules in the upper part of your module.
728
729\item[3-] in the file\_definition part of the xml file, add the definition of your variable using the same identifier you used in the f90 code.
730\vspace{-20pt}
731\begin{alltt}  {{\scriptsize
732\begin{verbatim}
733   <field_definition>
734      ...
735      <field id="identifier" long_name="blabla" ... />   
736      ...
737   </field_definition>
738\end{verbatim}
739}}\end{alltt} 
740attributes axis\_ref and grid\_ref must be consistent with the size of the array to pass to iomput.
741if your array is computed within the surface module each nn\_fsbc time\_step,
742add the field definition within the group defined with the id ''SBC'': $<$group id=''SBC''...$>$
743
744\item[4-] add your field in one of the output files   \\
745\vspace{-20pt}
746\begin{alltt}  {{\scriptsize
747\begin{verbatim}
748   <file id="file1" .../>   
749      ...
750      <field ref="identifier" />   
751      ...
752   </file>   
753\end{verbatim}
754}}\end{alltt} 
755
756\end{description}
757
758
759% ================================================================
760%       NetCDF4 support
761% ================================================================
762\section{NetCDF4 Support (\key{netcdf4})}
763\label{DIA_iom}
764
765Since version 3.3, support for NetCDF4 chunking and (loss-less) compression has
766been included.  These options build on the standard NetCDF output and allow
767the user control over the size of the chunks via namelist settings. Chunking
768and compression can lead to significant reductions in file sizes for a small
769runtime overhead. For a fuller discussion on chunking and other performance
770issues the reader is referred to the NetCDF4 documentation found
771\href{http://www.unidata.ucar.edu/software/netcdf/docs/netcdf.html#Chunking}{here}.
772
773The new features are only available when the code has been linked with a
774NetCDF4 library (version 4.1 onwards, recommended) which has been built
775with HDF5 support (version 1.8.4 onwards, recommended). Datasets created
776with chunking and compression are not backwards compatible with NetCDF3
777"classic" format but most analysis codes can be relinked simply with the
778new libraries and will then read both NetCDF3 and NetCDF4 files. NEMO
779executables linked with NetCDF4 libraries can be made to produce NetCDF3
780files by setting the \np{ln\_nc4zip} logical to false in the \textit{namnc4} 
781namelist:
782
783%------------------------------------------namnc4----------------------------------------------------
784\namdisplay{namnc4}
785%-------------------------------------------------------------------------------------------------------------
786
787If \key{netcdf4} has not been defined, these namelist parameters are not read.
788In this case, \np{ln\_nc4zip} is set false and dummy routines for a few
789NetCDF4-specific functions are defined. These functions will not be used but
790need to be included so that compilation is possible with NetCDF3 libraries.
791
792When using NetCDF4 libraries, \key{netcdf4} should be defined even if the
793intention is to create only NetCDF3-compatible files. This is necessary to
794avoid duplication between the dummy routines and the actual routines present
795in the library. Most compilers will fail at compile time when faced with
796such duplication. Thus when linking with NetCDF4 libraries the user must
797define \key{netcdf4} and control the type of NetCDF file produced via the
798namelist parameter.
799
800Chunking and compression is applied only to 4D fields and there is no
801advantage in chunking across more than one time dimension since previously
802written chunks would have to be read back and decompressed before being
803added to. Therefore, user control over chunk sizes is provided only for the
804three space dimensions. The user sets an approximate number of chunks along
805each spatial axis. The actual size of the chunks will depend on global domain
806size for mono-processors or, more likely, the local processor domain size for
807distributed processing. The derived values are subject to practical minimum
808values (to avoid wastefully small chunk sizes) and cannot be greater than the
809domain size in any dimension. The algorithm used is:
810
811\begin{alltt}  {{\scriptsize 
812\begin{verbatim}
813     ichunksz(1) = MIN( idomain_size,MAX( (idomain_size-1)/nn_nchunks_i + 1 ,16 ) )
814     ichunksz(2) = MIN( jdomain_size,MAX( (jdomain_size-1)/nn_nchunks_j + 1 ,16 ) )
815     ichunksz(3) = MIN( kdomain_size,MAX( (kdomain_size-1)/nn_nchunks_k + 1 , 1 ) )
816     ichunksz(4) = 1
817\end{verbatim}
818}}\end{alltt} 
819
820\noindent As an example, setting:
821\vspace{-20pt}
822\begin{alltt}  {{\scriptsize
823\begin{verbatim}
824     nn_nchunks_i=4, nn_nchunks_j=4 and nn_nchunks_k=31
825\end{verbatim}
826}}\end{alltt} \vspace{-10pt}
827
828\noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\tt 46x38x1}
829respectively in the mono-processor case (i.e. global domain of {\small\tt 182x149x31}).
830An illustration of the potential space savings that NetCDF4 chunking and compression
831provides is given in table \ref{Tab_NC4} which compares the results of two short
832runs of the ORCA2\_LIM reference configuration with a 4x2 mpi partitioning. Note
833the variation in the compression ratio achieved which reflects chiefly the dry to wet
834volume ratio of each processing region.
835
836%------------------------------------------TABLE----------------------------------------------------
837\begin{table}  \begin{tabular}{lrrr}
838Filename & NetCDF3 & NetCDF4 & Reduction\\
839         &filesize & filesize & \% \\
840         &(KB)     & (KB)     & \\
841ORCA2\_restart\_0000.nc & 16420 & 8860 & 47\%\\
842ORCA2\_restart\_0001.nc & 16064 & 11456 & 29\%\\
843ORCA2\_restart\_0002.nc & 16064 & 9744 & 40\%\\
844ORCA2\_restart\_0003.nc & 16420 & 9404 & 43\%\\
845ORCA2\_restart\_0004.nc & 16200 & 5844 & 64\%\\
846ORCA2\_restart\_0005.nc & 15848 & 8172 & 49\%\\
847ORCA2\_restart\_0006.nc & 15848 & 8012 & 50\%\\
848ORCA2\_restart\_0007.nc & 16200 & 5148 & 69\%\\
849ORCA2\_2d\_grid\_T\_0000.nc & 2200 & 1504 & 32\%\\
850ORCA2\_2d\_grid\_T\_0001.nc & 2200 & 1748 & 21\%\\
851ORCA2\_2d\_grid\_T\_0002.nc & 2200 & 1592 & 28\%\\
852ORCA2\_2d\_grid\_T\_0003.nc & 2200 & 1540 & 30\%\\
853ORCA2\_2d\_grid\_T\_0004.nc & 2200 & 1204 & 46\%\\
854ORCA2\_2d\_grid\_T\_0005.nc & 2200 & 1444 & 35\%\\
855ORCA2\_2d\_grid\_T\_0006.nc & 2200 & 1428 & 36\%\\
856ORCA2\_2d\_grid\_T\_0007.nc & 2200 & 1148 & 48\%\\
857             ...            &  ... &  ... & ..  \\
858ORCA2\_2d\_grid\_W\_0000.nc & 4416 & 2240 & 50\%\\
859ORCA2\_2d\_grid\_W\_0001.nc & 4416 & 2924 & 34\%\\
860ORCA2\_2d\_grid\_W\_0002.nc & 4416 & 2512 & 44\%\\
861ORCA2\_2d\_grid\_W\_0003.nc & 4416 & 2368 & 47\%\\
862ORCA2\_2d\_grid\_W\_0004.nc & 4416 & 1432 & 68\%\\
863ORCA2\_2d\_grid\_W\_0005.nc & 4416 & 1972 & 56\%\\
864ORCA2\_2d\_grid\_W\_0006.nc & 4416 & 2028 & 55\%\\
865ORCA2\_2d\_grid\_W\_0007.nc & 4416 & 1368 & 70\%\\
866\end{tabular}
867\caption{   \label{Tab_NC4} 
868Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression}
869\end{table}
870%----------------------------------------------------------------------------------------------------
871
872When \key{iomput} is activated with \key{netcdf4} chunking and
873compression parameters for fields produced via \np{iom\_put} calls are
874set via an equivalent and identically named namelist to \textit{namnc4} 
875in \np{xmlio\_server.def}. Typically this namelist serves the mean files
876whilst the \ngn{ namnc4} in the main namelist file continues to serve the
877restart files. This duplication is unfortunate but appropriate since, if
878using io\_servers, the domain sizes of the individual files produced by the
879io\_server processes may be different to those produced by the invidual
880processing regions and different chunking choices may be desired.
881 
882
883% -------------------------------------------------------------------------------------------------------------
884%       Tracer/Dynamics Trends
885% -------------------------------------------------------------------------------------------------------------
886\section[Tracer/Dynamics Trends (TRD)]
887                  {Tracer/Dynamics Trends  (\key{trdtra}, \key{trddyn},    \\ 
888                                                             \key{trddvor}, \key{trdmld})}
889\label{DIA_trd}
890
891%------------------------------------------namtrd----------------------------------------------------
892\namdisplay{namtrd} 
893%-------------------------------------------------------------------------------------------------------------
894
895When \key{trddyn} and/or \key{trddyn} CPP variables are defined, each
896trend of the dynamics and/or temperature and salinity time evolution equations
897is stored in three-dimensional arrays just after their computation ($i.e.$ at the end
898of each $dyn\cdots.F90$ and/or $tra\cdots.F90$ routines). Options are defined by
899\ngn{namtrd} namelist variables. These trends are then
900used in \mdl{trdmod} (see TRD directory) every \textit{nn\_trd } time-steps.
901
902What is done depends on the CPP keys defined:
903\begin{description}
904\item[\key{trddyn}, \key{trdtra}] : a check of the basin averaged properties of the momentum
905and/or tracer equations is performed ;
906\item[\key{trdvor}] : a vertical summation of the moment tendencies is performed,
907then the curl is computed to obtain the barotropic vorticity tendencies which are output ;
908\item[\key{trdmld}] : output of the tracer tendencies averaged vertically 
909either over the mixed layer (\np{nn\_ctls}=0),
910or       over a fixed number of model levels (\np{nn\_ctls}$>$1 provides the number of level),
911or       over a spatially varying but temporally fixed number of levels (typically the base
912of the winter mixed layer) read in \ifile{ctlsurf\_idx} (\np{nn\_ctls}=1) ;
913\end{description}
914
915The units in the output file can be changed using the \np{nn\_ucf} namelist parameter.
916For example, in case of salinity tendency the units are given by PSU/s/\np{nn\_ucf}.
917Setting \np{nn\_ucf}=86400 ($i.e.$ the number of second in a day) provides the tendencies in PSU/d.
918
919When \key{trdmld} is defined, two time averaging procedure are proposed.
920Setting \np{ln\_trdmld\_instant} to \textit{true}, a simple time averaging is performed,
921so that the resulting tendency is the contribution to the change of a quantity between
922the two instantaneous values taken at the extremities of the time averaging period.
923Setting \np{ln\_trdmld\_instant} to \textit{false}, a double time averaging is performed,
924so that the resulting tendency is the contribution to the change of a quantity between
925two \textit{time mean} values. The later option requires the use of an extra file, \ifile{restart\_mld} 
926(\np{ln\_trdmld\_restart}=true), to restart a run.
927
928
929Note that the mixed layer tendency diagnostic can also be used on biogeochemical models
930via the \key{trdtrc} and \key{trdmld\_trc} CPP keys.
931
932% -------------------------------------------------------------------------------------------------------------
933%       On-line Floats trajectories
934% -------------------------------------------------------------------------------------------------------------
935\section{On-line Floats trajectories (FLO) (\key{floats})}
936\label{FLO}
937%--------------------------------------------namflo-------------------------------------------------------
938\namdisplay{namflo} 
939%--------------------------------------------------------------------------------------------------------------
940
941The on-line computation of floats advected either by the three dimensional velocity
942field or constraint to remain at a given depth ($w = 0$ in the computation) have been
943introduced in the system during the CLIPPER project. Options are defined by \ngn{namflo}
944namelis variables. The algorithm used is based
945either on the work of \cite{Blanke_Raynaud_JPO97} (default option), or on a $4^th$
946Runge-Hutta algorithm (\np{ln\_flork4}=true). Note that the \cite{Blanke_Raynaud_JPO97} 
947algorithm have the advantage of providing trajectories which are consistent with the
948numeric of the code, so that the trajectories never intercept the bathymetry.
949
950\subsubsection{ Input data: initial coordinates }
951
952Initial coordinates can be given with Ariane Tools convention ( IJK coordinates ,(\np{ln\_ariane}=true) )
953or with longitude and latitude.
954
955
956In case of Ariane convention, input filename is \np{init\_float\_ariane}. Its format is:
957
958\texttt{ I J K nisobfl itrash itrash }
959
960\noindent with:
961
962 - I,J,K  : indexes of initial position
963
964 - nisobfl: 0 for an isobar float, 1 for a float following the w velocity 
965
966 - itrash : set to zero; it is a dummy variable to respect Ariane Tools convention
967
968 - itrash :set to zero; it is a dummy variable to respect Ariane Tools convention
969
970\noindent Example:\\
971\noindent \texttt{ 100.00000  90.00000  -1.50000 1.00000   0.00000}\\
972\texttt{ 102.00000  90.00000  -1.50000 1.00000   0.00000}\\
973\texttt{ 104.00000  90.00000  -1.50000 1.00000   0.00000}\\
974\texttt{ 106.00000  90.00000  -1.50000 1.00000   0.00000}\\
975\texttt{ 108.00000  90.00000  -1.50000 1.00000   0.00000}\\
976
977
978In the other case ( longitude and latitude ), input filename is init\_float. Its format is:
979
980\texttt{ Long Lat depth nisobfl ngrpfl itrash}
981
982\noindent with:
983
984 - Long, Lat, depth  : Longitude, latitude, depth
985
986 - nisobfl: 0 for an isobar float, 1 for a float following the w velocity
987
988 - ngrpfl : number to identify searcher group
989
990 - itrash :set to 1; it is a dummy variable.
991
992\noindent Example:
993
994\noindent\texttt{  20.0 0.0 0.0 0 1 1 }\\
995\texttt{ -21.0 0.0 0.0 0 1 1 }\\
996\texttt{ -22.0 0.0 0.0 0 1 1 }\\
997\texttt{ -23.0 0.0 0.0 0 1 1 }\\
998\texttt{ -24.0 0.0 0.0 0 1 1 }\\
999
1000\np{jpnfl} is the total number of floats during the run.
1001When initial positions are read in a restart file ( \np{ln\_rstflo}= .TRUE. ),  \np{jpnflnewflo}
1002can be added in the initialization file.
1003
1004\subsubsection{ Output data }
1005
1006\np{nn\_writefl} is the frequency of writing in float output file and \np{nn\_stockfl} 
1007is the frequency of creation of the float restart file.
1008
1009Output data can be written in ascii files (\np{ln\_flo\_ascii} = .TRUE. ). In that case,
1010output filename is trajec\_float.
1011
1012Another possiblity of writing format is Netcdf (\np{ln\_flo\_ascii} = .FALSE. ). There are 2 possibilities:
1013
1014 - if (\key{iomput}) is used, outputs are selected in  iodef.xml. Here it is an example of specification
1015   to put in files description section:
1016
1017\vspace{-30pt}
1018\begin{alltt}  {{\scriptsize
1019\begin{verbatim}
1020
1021     <group id="1d\_grid\_T" name="auto" description="ocean T grid variables" >   }
1022       <file id="floats"  description="floats variables"> }\\
1023           <field ref="traj\_lon"   name="floats\_longitude"   freq\_op="86400" />}
1024           <field ref="traj\_lat"   name="floats\_latitude"    freq\_op="86400" />}
1025           <field ref="traj\_dep"   name="floats\_depth"       freq\_op="86400" />}
1026           <field ref="traj\_temp"  name="floats\_temperature" freq\_op="86400" />}
1027           <field ref="traj\_salt"  name="floats\_salinity"    freq\_op="86400" />}
1028           <field ref="traj\_dens"  name="floats\_density"     freq\_op="86400" />}
1029           <field ref="traj\_group" name="floats\_group"       freq\_op="86400" />}
1030       </file>}
1031  </group>}
1032
1033\end{verbatim}
1034}}\end{alltt}
1035
1036
1037 -  if (\key{iomput}) is not used, a file called trajec\_float.nc will be created by IOIPSL library.
1038
1039
1040
1041See also \href{http://stockage.univ-brest.fr/~grima/Ariane/}{here} the web site describing
1042the off-line use of this marvellous diagnostic tool.
1043
1044
1045% -------------------------------------------------------------------------------------------------------------
1046%       Harmonic analysis of tidal constituents
1047% -------------------------------------------------------------------------------------------------------------
1048\section{Harmonic analysis of tidal constituents (\key{diaharm}) }
1049\label{DIA_diag_harm}
1050
1051A module is available to compute the amplitude and phase for tidal waves.
1052This diagnostic is actived with \key{diaharm}.
1053
1054%------------------------------------------namdia_harm----------------------------------------------------
1055\namdisplay{namdia_harm}
1056%----------------------------------------------------------------------------------------------------------
1057
1058Concerning the on-line Harmonic analysis, some parameters are available in namelist
1059\ngn{namdia\_harm} :
1060
1061- \texttt{nit000\_han} is the first time step used for harmonic analysis
1062
1063- \texttt{nitend\_han} is the last time step used for harmonic analysis
1064
1065- \texttt{nstep\_han} is the time step frequency for harmonic analysis
1066
1067- \texttt{nb\_ana} is the number of harmonics to analyse
1068
1069- \texttt{tname} is an array with names of tidal constituents to analyse
1070
1071\texttt{nit000\_han} and \texttt{nitend\_han} must be between \texttt{nit000} and \texttt{nitend} of the simulation.
1072The restart capability is not implemented.
1073
1074The Harmonic analysis solve this equation:
1075\begin{equation}
1076h_{i} - A_{0} + \sum^{nb\_ana}_{j=1}[A_{j}cos(\nu_{j}t_{j}-\phi_{j})] = e_{i}
1077\end{equation}
1078
1079With $A_{j}$,$\nu_{j}$,$\phi_{j}$, the amplitude, frequency and phase for each wave and $e_{i}$ the error.
1080$h_{i}$ is the sea level for the time $t_{i}$ and $A_{0}$ is the mean sea level. \\
1081We can rewrite this equation:
1082\begin{equation}
1083h_{i} - A_{0} + \sum^{nb\_ana}_{j=1}[C_{j}cos(\nu_{j}t_{j})+S_{j}sin(\nu_{j}t_{j})] = e_{i}
1084\end{equation}
1085with $A_{j}=\sqrt{C^{2}_{j}+S^{2}_{j}}$ et $\phi_{j}=arctan(S_{j}/C_{j})$.
1086
1087We obtain in output $C_{j}$ and $S_{j}$ for each tidal wave.
1088
1089% -------------------------------------------------------------------------------------------------------------
1090%       Sections transports
1091% -------------------------------------------------------------------------------------------------------------
1092\section{Transports across sections (\key{diadct}) }
1093\label{DIA_diag_dct}
1094
1095A module is available to compute the transport of volume, heat and salt through sections. This diagnostic
1096is actived with \key{diadct}.
1097
1098Each section is defined by the coordinates of its 2 extremities. The pathways between them are contructed
1099using tools which can be found in  \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT} and are written in a binary file
1100 \texttt{section\_ijglobal.diadct\_ORCA2\_LIM} which is later read in by NEMO to compute on-line transports.
1101
1102The on-line transports module creates three output ascii files:
1103
1104- \texttt{volume\_transport} for volume transports (  unit: $10^{6} m^{3} s^{-1}$ )
1105
1106- \texttt{heat\_transport}   for heat transports   (  unit: $10^{15} W $ )
1107
1108- \texttt{salt\_transport}   for salt transports   (  unit: $10^{9}Kg s^{-1}$ )\\
1109
1110
1111Namelist variables in \ngn{namdct} control how frequently the flows are summed
1112and the time scales over which they are averaged, as well as the level of output for debugging:
1113
1114%------------------------------------------namdct----------------------------------------------------
1115\namdisplay{namdct}
1116%-------------------------------------------------------------------------------------------------------------
1117
1118\texttt{nn\_dct}: frequency of instantaneous transports computing
1119
1120\texttt{nn\_dctwri}: frequency of writing ( mean of instantaneous transports )
1121
1122\texttt{nn\_debug}: debugging of the section
1123
1124\subsubsection{ To create a binary file containing the pathway of each section }
1125
1126In \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT/run}, the file \texttt{ {list\_sections.ascii\_global}}
1127contains a list of all the sections that are to be computed (this list of sections is based on MERSEA project metrics).
1128
1129Another file is available for the GYRE configuration (\texttt{ {list\_sections.ascii\_GYRE}}).
1130
1131Each section is defined by:
1132
1133\noindent \texttt{ long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name }\\
1134with:
1135
1136- \texttt{long1 lat1} , coordinates of the first extremity of the section;
1137
1138- \texttt{long2 lat2} , coordinates of the second extremity of the section;
1139
1140- \texttt{nclass} the number of bounds of your classes (e.g. 3 bounds for 2 classes);
1141
1142- \texttt{okstrpond} to compute heat and salt transport, \texttt{nostrpond} if no;
1143
1144- \texttt{ice}  to compute surface and volume ice transports, \texttt{noice} if no. \\
1145
1146
1147\noindent The results of the computing of transports, and the directions of positive
1148 and negative flow do not depend on the order of the 2 extremities in this file.\\ 
1149
1150
1151\noindent If nclass =/ 0,the next lines contain the class type and the nclass bounds:
1152
1153\texttt{long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name}
1154
1155\texttt{classtype}
1156
1157\texttt{zbound1}
1158
1159\texttt{zbound2}
1160
1161\texttt{.}
1162
1163\texttt{.}
1164
1165\texttt{nclass-1}
1166
1167\texttt{nclass}
1168
1169\noindent where \texttt{classtype} can be:
1170
1171- \texttt{zsal} for salinity classes
1172
1173- \texttt{ztem} for temperature classes
1174
1175- \texttt{zlay} for depth classes
1176
1177- \texttt{zsigi} for insitu density classes
1178
1179- \texttt{zsigp} for potential density classes \\
1180
1181 
1182The script \texttt{job.ksh} computes the pathway for each section and creates a binary file
1183\texttt{section\_ijglobal.diadct\_ORCA2\_LIM} which is read by NEMO. \\
1184
1185It is possible to use this tools for new configuations: \texttt{job.ksh} has to be updated
1186with the coordinates file name and path. \\
1187
1188
1189Examples of two sections, the ACC\_Drake\_Passage with no classes, and the
1190 ATL\_Cuba\_Florida with 4 temperature clases (5 class bounds), are shown:
1191
1192\noindent \texttt{ -68.    -54.5   -60.    -64.7  00 okstrpond noice ACC\_Drake\_Passage}
1193
1194\noindent \texttt{ -80.5    22.5   -80.5    25.5  05 nostrpond noice ATL\_Cuba\_Florida}
1195
1196\noindent \texttt{ztem}
1197
1198\noindent \texttt{-2.0}
1199
1200\noindent \texttt{ 4.5}
1201
1202\noindent \texttt{ 7.0}
1203
1204\noindent \texttt{12.0}
1205
1206\noindent \texttt{40.0}
1207
1208
1209\subsubsection{ To read the output files }
1210
1211The output format is :
1212 
1213{\small\texttt{date, time-step number, section number, section name, section slope coefficient, class number,
1214class name, class bound 1 , classe bound2, transport\_direction1 ,  transport\_direction2, transport\_total}}\\
1215
1216
1217For sections with classes, the first \texttt{nclass-1} lines correspond to the transport for each class
1218and the last line corresponds to the total transport summed over all classes. For sections with no classes, class number
1219\texttt{ 1 } corresponds to \texttt{ total class } and this class is called  \texttt{N}, meaning \texttt{none}.\\
1220
1221
1222\noindent \texttt{ transport\_direction1 } is the positive part of the transport ( \texttt{ > = 0 } ).
1223
1224\noindent \texttt{ transport\_direction2 } is the negative part of the transport ( \texttt{ < = 0 } ).\\
1225
1226
1227\noindent The \texttt{section slope coefficient} gives information about the significance of transports signs and direction:\\
1228
1229
1230
1231\begin{tabular}{|c|c|c|c|p{4cm}|}
1232\hline
1233section slope coefficient & section type & direction 1 & direction 2 & total transport \\ \hline
12340.    &  horizontal & northward & southward & postive: northward  \\ \hline
12351000. &  vertical   & eastward  & westward  & postive: eastward  \\ \hline               
1236\texttt{=/0, =/ 1000.}   &  diagonal   & eastward  & westward  & postive: eastward  \\ \hline               
1237\end{tabular}
1238
1239
1240
1241% -------------------------------------------------------------------------------------------------------------
1242%       Other Diagnostics
1243% -------------------------------------------------------------------------------------------------------------
1244\section{Other Diagnostics (\key{diahth}, \key{diaar5})}
1245\label{DIA_diag_others}
1246
1247
1248Aside from the standard model variables, other diagnostics can be computed
1249on-line. The available ready-to-add diagnostics routines can be found in directory DIA.
1250Among the available diagnostics the following ones are obtained when defining
1251the \key{diahth} CPP key:
1252
1253- the mixed layer depth (based on a density criterion, \citet{de_Boyer_Montegut_al_JGR04}) (\mdl{diahth})
1254
1255- the turbocline depth (based on a turbulent mixing coefficient criterion) (\mdl{diahth})
1256
1257- the depth of the 20\deg C isotherm (\mdl{diahth})
1258
1259- the depth of the thermocline (maximum of the vertical temperature gradient) (\mdl{diahth})
1260
1261The poleward heat and salt transports, their advective and diffusive component, and
1262the meriodional stream function can be computed on-line in \mdl{diaptr} 
1263\np{ln\_diaptr} to true (see the \textit{\ngn{namptr} } namelist below). 
1264When \np{ln\_subbas}~=~true, transports and stream function are computed
1265for the Atlantic, Indian, Pacific and Indo-Pacific Oceans (defined north of 30\deg S)
1266as well as for the World Ocean. The sub-basin decomposition requires an input file
1267(\ifile{subbasins}) which contains three 2D mask arrays, the Indo-Pacific mask
1268been deduced from the sum of the Indian and Pacific mask (Fig~\ref{Fig_mask_subasins}).
1269
1270%------------------------------------------namptr----------------------------------------------------
1271\namdisplay{namptr} 
1272%-------------------------------------------------------------------------------------------------------------
1273%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
1274\begin{figure}[!t]     \begin{center}
1275\includegraphics[width=1.0\textwidth]{./TexFiles/Figures/Fig_mask_subasins.pdf}
1276\caption{   \label{Fig_mask_subasins}
1277Decomposition of the World Ocean (here ORCA2) into sub-basin used in to compute
1278the heat and salt transports as well as the meridional stream-function: Atlantic basin (red),
1279Pacific basin (green), Indian basin (bleue), Indo-Pacific basin (bleue+green).
1280Note that semi-enclosed seas (Red, Med and Baltic seas) as well as Hudson Bay
1281are removed from the sub-basins. Note also that the Arctic Ocean has been split
1282into Atlantic and Pacific basins along the North fold line.  }
1283\end{center}   \end{figure} 
1284%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
1285
1286In addition, a series of diagnostics has been added in the \mdl{diaar5}.
1287They corresponds to outputs that are required for AR5 simulations
1288(see Section \ref{DIA_steric} below for one of them).
1289Activating those outputs requires to define the \key{diaar5} CPP key.
1290\\
1291\\
1292
1293
1294
1295% ================================================================
1296% Steric effect in sea surface height
1297% ================================================================
1298\section{Diagnosing the Steric effect in sea surface height}
1299\label{DIA_steric}
1300
1301
1302Changes in steric sea level are caused when changes in the density of the water
1303column imply an expansion or contraction of the column. It is essentially produced
1304through surface heating/cooling and to a lesser extent through non-linear effects of
1305the equation of state (cabbeling, thermobaricity...).
1306Non-Boussinesq models contain all ocean effects within the ocean acting
1307on the sea level. In particular, they include the steric effect. In contrast,
1308Boussinesq models, such as \NEMO, conserve volume, rather than mass,
1309and so do not properly represent expansion or contraction. The steric effect is
1310therefore not explicitely represented.
1311This approximation does not represent a serious error with respect to the flow field
1312calculated by the model \citep{Greatbatch_JGR94}, but extra attention is required
1313when investigating sea level, as steric changes are an important
1314contribution to local changes in sea level on seasonal and climatic time scales.
1315This is especially true for investigation into sea level rise due to global warming.
1316
1317Fortunately, the steric contribution to the sea level consists of a spatially uniform
1318component that can be diagnosed by considering the mass budget of the world
1319ocean \citep{Greatbatch_JGR94}.
1320In order to better understand how global mean sea level evolves and thus how
1321the steric sea level can be diagnosed, we compare, in the following, the
1322non-Boussinesq and Boussinesq cases.
1323
1324Let denote
1325$\mathcal{M}$ the total mass of liquid seawater ($\mathcal{M}=\int_D \rho dv$),
1326$\mathcal{V}$ the total volume of seawater ($\mathcal{V}=\int_D dv$),
1327$\mathcal{A}$ the total surface of the ocean ($\mathcal{A}=\int_S ds$),
1328$\bar{\rho}$ the global mean seawater (\textit{in situ}) density ($\bar{\rho}= 1/\mathcal{V} \int_D \rho \,dv$), and
1329$\bar{\eta}$ the global mean sea level ($\bar{\eta}=1/\mathcal{A}\int_S \eta \,ds$).
1330
1331A non-Boussinesq fluid conserves mass. It satisfies the following relations:
1332\begin{equation} \label{Eq_MV_nBq} 
1333\begin{split} 
1334\mathcal{M} &\mathcal{V}  \;\bar{\rho}       \\
1335\mathcal{V} &\mathcal{A}  \;\bar{\eta} 
1336\end{split}
1337\end{equation}
1338Temporal changes in total mass is obtained from the density conservation equation :
1339\begin{equation}  \label{Eq_Co_nBq}
1340\frac{1}{e_3} \partial_t ( e_3\,\rho) + \nabla( \rho \, \textbf{U} ) = \left. \frac{\textit{emp}}{e_3}\right|_\textit{surface}
1341\end{equation}
1342where $\rho$ is the \textit{in situ} density, and \textit{emp} the surface mass
1343exchanges with the other media of the Earth system (atmosphere, sea-ice, land).
1344Its global averaged leads to the total mass change
1345\begin{equation}  \label{Eq_Mass_nBq}
1346\partial_t \mathcal{M} = \mathcal{A} \;\overline{\textit{emp}}
1347\end{equation}
1348where $\overline{\textit{emp}}=\int_S \textit{emp}\,ds$ is the net mass flux
1349through the ocean surface.
1350Bringing \eqref{Eq_Mass_nBq} and the time derivative of \eqref{Eq_MV_nBq} 
1351together leads to the evolution equation of the mean sea level
1352\begin{equation} \label{Eq_ssh_nBq}
1353  \partial_t \bar{\eta} =  \frac{\overline{\textit{emp}}}{ \bar{\rho}} 
1354               - \frac{\mathcal{V}}{\mathcal{A}}  \;\frac{\partial_t \bar{\rho} }{\bar{\rho}}
1355\end{equation}
1356The first term in equation \eqref{Eq_ssh_nBq} alters sea level by adding or
1357subtracting mass from the ocean.
1358The second term arises from temporal changes in the global mean
1359density; $i.e.$ from steric effects.
1360
1361In a Boussinesq fluid, $\rho$ is replaced by $\rho_o$ in all the equation except when $\rho$ 
1362appears multiplied by the gravity ($i.e.$ in the hydrostatic balance of the primitive Equations).
1363In particular, the mass conservation equation, \eqref{Eq_Co_nBq}, degenerates into
1364the incompressibility equation:
1365\begin{equation}  \label{Eq_Co_Bq}
1366\frac{1}{e_3} \partial_t ( e_3 ) + \nabla( \textbf{U} ) =  \left. \frac{\textit{emp}}{\rho_o \,e_3}\right|_ \textit{surface}
1367\end{equation}
1368and the global average of this equation now gives the temporal change of the total volume,
1369\begin{equation}  \label{Eq_V_Bq}
1370  \partial_t \mathcal{V} =   \mathcal{A} \;\frac{\overline{\textit{emp}}}{\rho_o} 
1371\end{equation}
1372Only the volume is conserved, not mass, or, more precisely, the mass which is conserved is the
1373Boussinesq mass, $\mathcal{M}_o = \rho_o \mathcal{V}$. The total volume (or equivalently 
1374the global mean sea level) is altered only by net volume fluxes across the ocean surface, 
1375not by changes in mean mass of the ocean: the steric effect is missing in a Boussinesq fluid.
1376 
1377Nevertheless, following \citep{Greatbatch_JGR94}, the steric effect on the volume can be
1378diagnosed by considering the mass budget of the ocean.
1379The apparent changes in $\mathcal{M}$, mass of the ocean, which are not induced by surface
1380mass flux must be compensated by a spatially uniform change in the mean sea level due to
1381expansion/contraction of the ocean \citep{Greatbatch_JGR94}. In others words, the Boussinesq
1382mass, $\mathcal{M}_o$, can be related to $\mathcal{M}$, the  total mass of the ocean seen
1383by the Boussinesq model, via the steric contribution to the sea level, $\eta_s$, a spatially
1384uniform variable, as follows:
1385\begin{equation}  \label{Eq_M_Bq}
1386   \mathcal{M}_o  =  \mathcal{M} + \rho_o \,\eta_s \,\mathcal{A} 
1387\end{equation}
1388Any change in $\mathcal{M}$ which cannot be explained by the net mass flux through
1389the ocean surface is converted into a mean change in sea level. Introducing the total density
1390anomaly, $\mathcal{D}= \int_D d_a \,dv$, where $d_a= (\rho -\rho_o ) / \rho_o$ 
1391is the density anomaly used in \NEMO (cf. \S\ref{TRA_eos}) in \eqref{Eq_M_Bq}
1392leads to a very simple form for the steric height:
1393\begin{equation}  \label{Eq_steric_Bq}
1394   \eta_s = - \frac{1}{\mathcal{A}} \mathcal{D} 
1395\end{equation}
1396
1397The above formulation of the steric height of a Boussinesq ocean requires four remarks.
1398First, one can be tempted to define $\rho_o$ as the initial value of $\mathcal{M}/\mathcal{V}$,
1399$i.e.$ set $\mathcal{D}_{t=0}=0$, so that the initial steric height is zero. We do not
1400recommend that. Indeed, in this case $\rho_o$ depends on the initial state of the ocean.
1401Since $\rho_o$ has a direct effect on the dynamics of the ocean (it appears in the pressure
1402gradient term of the momentum equation) it is definitively not a good idea when
1403inter-comparing experiments.
1404We better recommend to fixe once for all $\rho_o$ to $1035\;Kg\,m^{-3}$. This value is a
1405sensible choice for the reference density used in a Boussinesq ocean climate model since,
1406with the exception of only a small percentage of the ocean, density in the World Ocean
1407varies by no more than 2$\%$ from this value (\cite{Gill1982}, page 47).
1408
1409Second, we have assumed here that the total ocean surface, $\mathcal{A}$, does not
1410change when the sea level is changing as it is the case in all global ocean GCMs
1411(wetting and drying of grid point is not allowed).
1412 
1413Third, the discretisation of \eqref{Eq_steric_Bq} depends on the type of free surface
1414which is considered. In the non linear free surface case, $i.e.$ \key{vvl} defined, it is
1415given by
1416\begin{equation}  \label{Eq_discrete_steric_Bq}
1417   \eta_s =  - \frac{ \sum_{i,\,j,\,k} d_a\; e_{1t} e_{2t} e_{3t} }
1418                  { \sum_{i,\,j,\,k}         e_{1t} e_{2t} e_{3t} } 
1419\end{equation}
1420whereas in the linear free surface, the volume above the \textit{z=0} surface must be explicitly taken
1421into account to better approximate the total ocean mass and thus the steric sea level:
1422\begin{equation}  \label{Eq_discrete_steric_Bq}
1423   \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 }
1424                     {\sum_{i,\,j,\,k} e_{1t}e_{2t}e_{3t} + \sum_{i,\,j}           e_{1t}e_{2t} \eta } 
1425\end{equation}
1426
1427The fourth and last remark concerns the effective sea level and the presence of sea-ice.
1428In the real ocean, sea ice (and snow above it)  depresses the liquid seawater through
1429its mass loading. This depression is a result of the mass of sea ice/snow system acting
1430on the liquid ocean. There is, however, no dynamical effect associated with these depressions
1431in the liquid ocean sea level, so that there are no associated ocean currents. Hence, the
1432dynamically relevant sea level is the effective sea level, $i.e.$ the sea level as if sea ice
1433(and snow) were converted to liquid seawater \citep{Campin_al_OM08}. However,
1434in the current version of \NEMO the sea-ice is levitating above the ocean without
1435mass exchanges between ice and ocean. Therefore the model effective sea level
1436is always given by $\eta + \eta_s$, whether or not there is sea ice present.
1437
1438In AR5 outputs, the thermosteric sea level is demanded. It is steric sea level due to
1439changes in ocean density arising just from changes in temperature. It is given by:
1440\begin{equation}  \label{Eq_thermosteric_Bq}
1441   \eta_s = - \frac{1}{\mathcal{A}} \int_D d_a(T,S_o,p_o) \,dv
1442\end{equation}
1443where $S_o$ and $p_o$ are the initial salinity and pressure, respectively.
1444
1445Both steric and thermosteric sea level are computed in \mdl{diaar5} which needs
1446the \key{diaar5} defined to be called.
1447
1448% ================================================================
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
Note: See TracBrowser for help on using the repository browser.