New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
Chap_DIA.tex in trunk/DOC/TexFiles/Chapters – NEMO

source: trunk/DOC/TexFiles/Chapters/Chap_DIA.tex @ 3940

Last change on this file since 3940 was 3940, checked in by smasson, 9 years ago

trunk: upgrade XIOS inteface, see #1122

File size: 65.0 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 \np{ 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). These trends are then
899used in \mdl{trdmod} (see TRD directory) every \textit{nn\_trd } time-steps.
900
901What is done depends on the CPP keys defined:
902\begin{description}
903\item[\key{trddyn}, \key{trdtra}] : a check of the basin averaged properties of the momentum
904and/or tracer equations is performed ;
905\item[\key{trdvor}] : a vertical summation of the moment tendencies is performed,
906then the curl is computed to obtain the barotropic vorticity tendencies which are output ;
907\item[\key{trdmld}] : output of the tracer tendencies averaged vertically 
908either over the mixed layer (\np{nn\_ctls}=0),
909or       over a fixed number of model levels (\np{nn\_ctls}$>$1 provides the number of level),
910or       over a spatially varying but temporally fixed number of levels (typically the base
911of the winter mixed layer) read in \ifile{ctlsurf\_idx} (\np{nn\_ctls}=1) ;
912\end{description}
913
914The units in the output file can be changed using the \np{nn\_ucf} namelist parameter.
915For example, in case of salinity tendency the units are given by PSU/s/\np{nn\_ucf}.
916Setting \np{nn\_ucf}=86400 ($i.e.$ the number of second in a day) provides the tendencies in PSU/d.
917
918When \key{trdmld} is defined, two time averaging procedure are proposed.
919Setting \np{ln\_trdmld\_instant} to \textit{true}, a simple time averaging is performed,
920so that the resulting tendency is the contribution to the change of a quantity between
921the two instantaneous values taken at the extremities of the time averaging period.
922Setting \np{ln\_trdmld\_instant} to \textit{false}, a double time averaging is performed,
923so that the resulting tendency is the contribution to the change of a quantity between
924two \textit{time mean} values. The later option requires the use of an extra file, \ifile{restart\_mld} 
925(\np{ln\_trdmld\_restart}=true), to restart a run.
926
927
928Note that the mixed layer tendency diagnostic can also be used on biogeochemical models
929via the \key{trdtrc} and \key{trdmld\_trc} CPP keys.
930
931% -------------------------------------------------------------------------------------------------------------
932%       On-line Floats trajectories
933% -------------------------------------------------------------------------------------------------------------
934\section{On-line Floats trajectories (FLO) (\key{floats})}
935\label{FLO}
936%--------------------------------------------namflo-------------------------------------------------------
937\namdisplay{namflo} 
938%--------------------------------------------------------------------------------------------------------------
939
940The on-line computation of floats advected either by the three dimensional velocity
941field or constraint to remain at a given depth ($w = 0$ in the computation) have been
942introduced in the system during the CLIPPER project. The algorithm used is based
943either on the work of \cite{Blanke_Raynaud_JPO97} (default option), or on a $4^th$
944Runge-Hutta algorithm (\np{ln\_flork4}=true). Note that the \cite{Blanke_Raynaud_JPO97} 
945algorithm have the advantage of providing trajectories which are consistent with the
946numeric of the code, so that the trajectories never intercept the bathymetry.
947
948\subsubsection{ Input data: initial coordinates }
949
950Initial coordinates can be given with Ariane Tools convention ( IJK coordinates ,(\np{ln\_ariane}=true) )
951or with longitude and latitude.
952
953
954In case of Ariane convention, input filename is \np{"init\_float\_ariane"}. Its format is:
955
956\texttt{ I J K nisobfl itrash itrash }
957
958\noindent with:
959
960 - I,J,K  : indexes of initial position
961
962 - nisobfl: 0 for an isobar float, 1 for a float following the w velocity 
963
964 - itrash : set to zero; it is a dummy variable to respect Ariane Tools convention
965
966 - itrash :set to zero; it is a dummy variable to respect Ariane Tools convention
967
968\noindent Example:\\
969\noindent \texttt{ 100.00000  90.00000  -1.50000 1.00000   0.00000}\\
970\texttt{ 102.00000  90.00000  -1.50000 1.00000   0.00000}\\
971\texttt{ 104.00000  90.00000  -1.50000 1.00000   0.00000}\\
972\texttt{ 106.00000  90.00000  -1.50000 1.00000   0.00000}\\
973\texttt{ 108.00000  90.00000  -1.50000 1.00000   0.00000}\\
974
975
976In the other case ( longitude and latitude ), input filename is \np{"init\_float"}. Its format is:
977
978\texttt{ Long Lat depth nisobfl ngrpfl itrash}
979
980\noindent with:
981
982 - Long, Lat, depth  : Longitude, latitude, depth
983
984 - nisobfl: 0 for an isobar float, 1 for a float following the w velocity
985
986 - ngrpfl : number to identify searcher group
987
988 - itrash :set to 1; it is a dummy variable.
989
990\noindent Example:
991
992\noindent\texttt{  20.0 0.0 0.0 0 1 1 }\\
993\texttt{ -21.0 0.0 0.0 0 1 1 }\\
994\texttt{ -22.0 0.0 0.0 0 1 1 }\\
995\texttt{ -23.0 0.0 0.0 0 1 1 }\\
996\texttt{ -24.0 0.0 0.0 0 1 1 }\\
997
998\np{jpnfl} is the total number of floats during the run.
999When initial positions are read in a restart file ( \np{ln\_rstflo= .TRUE.} ),  \np{jpnflnewflo}
1000can be added in the initialization file.
1001
1002\subsubsection{ Output data }
1003
1004\np{nn\_writefl} is the frequency of writing in float output file and \np{nn\_stockfl} 
1005is the frequency of creation of the float restart file.
1006
1007Output data can be written in ascii files (\np{ln\_flo\_ascii = .TRUE.} ). In that case,
1008output filename is \np{is trajec\_float}.
1009
1010Another possiblity of writing format is Netcdf (\np{ln\_flo\_ascii = .FALSE.} ). There are 2 possibilities:
1011
1012 - if (\key{iomput}) is used, outputs are selected in  \np{iodef.xml}. Here it is an example of specification
1013   to put in files description section:
1014
1015\vspace{-30pt}
1016\begin{alltt}  {{\scriptsize
1017\begin{verbatim}
1018
1019     <group id="1d\_grid\_T" name="auto" description="ocean T grid variables" >   }
1020       <file id="floats"  description="floats variables"> }\\
1021           <field ref="traj\_lon"   name="floats\_longitude"   freq\_op="86400" />}
1022           <field ref="traj\_lat"   name="floats\_latitude"    freq\_op="86400" />}
1023           <field ref="traj\_dep"   name="floats\_depth"       freq\_op="86400" />}
1024           <field ref="traj\_temp"  name="floats\_temperature" freq\_op="86400" />}
1025           <field ref="traj\_salt"  name="floats\_salinity"    freq\_op="86400" />}
1026           <field ref="traj\_dens"  name="floats\_density"     freq\_op="86400" />}
1027           <field ref="traj\_group" name="floats\_group"       freq\_op="86400" />}
1028       </file>}
1029  </group>}
1030
1031\end{verbatim}
1032}}\end{alltt}
1033
1034
1035 -  if (\key{iomput}) is not used, a file called \np{trajec\_float.nc} will be created by IOIPSL library.
1036
1037
1038
1039See also \href{http://stockage.univ-brest.fr/~grima/Ariane/}{here} the web site describing
1040the off-line use of this marvellous diagnostic tool.
1041
1042
1043% -------------------------------------------------------------------------------------------------------------
1044%       Harmonic analysis of tidal constituents
1045% -------------------------------------------------------------------------------------------------------------
1046\section{Harmonic analysis of tidal constituents (\key{diaharm}) }
1047\label{DIA_diag_harm}
1048
1049A module is available to compute the amplitude and phase for tidal waves.
1050This diagnostic is actived with \key{diaharm}.
1051
1052%------------------------------------------namdia_harm----------------------------------------------------
1053\namdisplay{namdia_harm}
1054%----------------------------------------------------------------------------------------------------------
1055
1056Concerning the on-line Harmonic analysis, some parameters are available in namelist:
1057
1058- \texttt{nit000\_han} is the first time step used for harmonic analysis
1059
1060- \texttt{nitend\_han} is the last time step used for harmonic analysis
1061
1062- \texttt{nstep\_han} is the time step frequency for harmonic analysis
1063
1064- \texttt{nb\_ana} is the number of harmonics to analyse
1065
1066- \texttt{tname} is an array with names of tidal constituents to analyse
1067
1068\texttt{nit000\_han} and \texttt{nitend\_han} must be between \texttt{nit000} and \texttt{nitend} of the simulation.
1069The restart capability is not implemented.
1070
1071The Harmonic analysis solve this equation:
1072\begin{equation}
1073h_{i} - A_{0} + \sum^{nb\_ana}_{j=1}[A_{j}cos(\nu_{j}t_{j}-\phi_{j})] = e_{i}
1074\end{equation}
1075
1076With $A_{j}$,$\nu_{j}$,$\phi_{j}$, the amplitude, frequency and phase for each wave and $e_{i}$ the error.
1077$h_{i}$ is the sea level for the time $t_{i}$ and $A_{0}$ is the mean sea level. \\
1078We can rewrite this equation:
1079\begin{equation}
1080h_{i} - A_{0} + \sum^{nb\_ana}_{j=1}[C_{j}cos(\nu_{j}t_{j})+S_{j}sin(\nu_{j}t_{j})] = e_{i}
1081\end{equation}
1082with $A_{j}=\sqrt{C^{2}_{j}+S^{2}_{j}}$ et $\phi_{j}=arctan(S_{j}/C_{j})$.
1083
1084We obtain in output $C_{j}$ and $S_{j}$ for each tidal wave.
1085
1086% -------------------------------------------------------------------------------------------------------------
1087%       Sections transports
1088% -------------------------------------------------------------------------------------------------------------
1089\section{Transports across sections (\key{diadct}) }
1090\label{DIA_diag_dct}
1091
1092A module is available to compute the transport of volume, heat and salt through sections. This diagnostic
1093is actived with \key{diadct}.
1094
1095Each section is defined by the coordinates of its 2 extremities. The pathways between them are contructed
1096using tools which can be found in  \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT} and are written in a binary file
1097 \texttt{section\_ijglobal.diadct\_ORCA2\_LIM} which is later read in by NEMO to compute on-line transports.
1098
1099The on-line transports module creates three output ascii files:
1100
1101- \texttt{volume\_transport} for volume transports (  unit: $10^{6} m^{3} s^{-1}$ )
1102
1103- \texttt{heat\_transport}   for heat transports   (  unit: $10^{15} W $ )
1104
1105- \texttt{salt\_transport}   for salt transports   (  unit: $10^{9}Kg s^{-1}$ )\\
1106
1107
1108Namelist parameters control how frequently the flows are summed and the time scales over which
1109 they are averaged, as well as the level of output for debugging:
1110
1111%------------------------------------------namdct----------------------------------------------------
1112\namdisplay{namdct}
1113%-------------------------------------------------------------------------------------------------------------
1114
1115\texttt{nn\_dct}: frequency of instantaneous transports computing
1116
1117\texttt{nn\_dctwri}: frequency of writing ( mean of instantaneous transports )
1118
1119\texttt{nn\_debug}: debugging of the section
1120
1121\subsubsection{ To create a binary file containing the pathway of each section }
1122
1123In \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT/run}, the file \texttt{ {list\_sections.ascii\_global}}
1124contains a list of all the sections that are to be computed (this list of sections is based on MERSEA project metrics).
1125
1126Another file is available for the GYRE configuration (\texttt{ {list\_sections.ascii\_GYRE}}).
1127
1128Each section is defined by:
1129
1130\noindent \texttt{ long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name }\\
1131with:
1132
1133- \texttt{long1 lat1} , coordinates of the first extremity of the section;
1134
1135- \texttt{long2 lat2} , coordinates of the second extremity of the section;
1136
1137- \texttt{nclass} the number of bounds of your classes (e.g. 3 bounds for 2 classes);
1138
1139- \texttt{okstrpond} to compute heat and salt transport, \texttt{nostrpond} if no;
1140
1141- \texttt{ice}  to compute surface and volume ice transports, \texttt{noice} if no. \\
1142
1143
1144\noindent The results of the computing of transports, and the directions of positive
1145 and negative flow do not depend on the order of the 2 extremities in this file.\\ 
1146
1147
1148\noindent If nclass =/ 0,the next lines contain the class type and the nclass bounds:
1149
1150\texttt{long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name}
1151
1152\texttt{classtype}
1153
1154\texttt{zbound1}
1155
1156\texttt{zbound2}
1157
1158\texttt{.}
1159
1160\texttt{.}
1161
1162\texttt{nclass-1}
1163
1164\texttt{nclass}
1165
1166\noindent where \texttt{classtype} can be:
1167
1168- \texttt{zsal} for salinity classes
1169
1170- \texttt{ztem} for temperature classes
1171
1172- \texttt{zlay} for depth classes
1173
1174- \texttt{zsigi} for insitu density classes
1175
1176- \texttt{zsigp} for potential density classes \\
1177
1178 
1179The script \texttt{job.ksh} computes the pathway for each section and creates a binary file
1180\texttt{section\_ijglobal.diadct\_ORCA2\_LIM} which is read by NEMO. \\
1181
1182It is possible to use this tools for new configuations: \texttt{job.ksh} has to be updated
1183with the coordinates file name and path. \\
1184
1185
1186Examples of two sections, the ACC\_Drake\_Passage with no classes, and the
1187 ATL\_Cuba\_Florida with 4 temperature clases (5 class bounds), are shown:
1188
1189\noindent \texttt{ -68.    -54.5   -60.    -64.7  00 okstrpond noice ACC\_Drake\_Passage}
1190
1191\noindent \texttt{ -80.5    22.5   -80.5    25.5  05 nostrpond noice ATL\_Cuba\_Florida}
1192
1193\noindent \texttt{ztem}
1194
1195\noindent \texttt{-2.0}
1196
1197\noindent \texttt{ 4.5}
1198
1199\noindent \texttt{ 7.0}
1200
1201\noindent \texttt{12.0}
1202
1203\noindent \texttt{40.0}
1204
1205
1206\subsubsection{ To read the output files }
1207
1208The output format is :
1209 
1210{\small\texttt{date, time-step number, section number, section name, section slope coefficient, class number,
1211class name, class bound 1 , classe bound2, transport\_direction1 ,  transport\_direction2, transport\_total}}\\
1212
1213
1214For sections with classes, the first \texttt{nclass-1} lines correspond to the transport for each class
1215and the last line corresponds to the total transport summed over all classes. For sections with no classes, class number
1216\texttt{ 1 } corresponds to \texttt{ total class } and this class is called  \texttt{N}, meaning \texttt{none}.\\
1217
1218
1219\noindent \texttt{ transport\_direction1 } is the positive part of the transport ( \texttt{ > = 0 } ).
1220
1221\noindent \texttt{ transport\_direction2 } is the negative part of the transport ( \texttt{ < = 0 } ).\\
1222
1223
1224\noindent The \texttt{section slope coefficient} gives information about the significance of transports signs and direction:\\
1225
1226
1227
1228\begin{tabular}{|c|c|c|c|p{4cm}|}
1229\hline
1230section slope coefficient & section type & direction 1 & direction 2 & total transport \\ \hline
12310.    &  horizontal & northward & southward & postive: northward  \\ \hline
12321000. &  vertical   & eastward  & westward  & postive: eastward  \\ \hline               
1233\texttt{=/0, =/ 1000.}   &  diagonal   & eastward  & westward  & postive: eastward  \\ \hline               
1234\end{tabular}
1235
1236
1237
1238% -------------------------------------------------------------------------------------------------------------
1239%       Other Diagnostics
1240% -------------------------------------------------------------------------------------------------------------
1241\section{Other Diagnostics (\key{diahth}, \key{diaar5})}
1242\label{DIA_diag_others}
1243
1244
1245Aside from the standard model variables, other diagnostics can be computed
1246on-line. The available ready-to-add diagnostics routines can be found in directory DIA.
1247Among the available diagnostics the following ones are obtained when defining
1248the \key{diahth} CPP key:
1249
1250- the mixed layer depth (based on a density criterion, \citet{de_Boyer_Montegut_al_JGR04}) (\mdl{diahth})
1251
1252- the turbocline depth (based on a turbulent mixing coefficient criterion) (\mdl{diahth})
1253
1254- the depth of the 20\deg C isotherm (\mdl{diahth})
1255
1256- the depth of the thermocline (maximum of the vertical temperature gradient) (\mdl{diahth})
1257
1258The poleward heat and salt transports, their advective and diffusive component, and
1259the meriodional stream function can be computed on-line in \mdl{diaptr} by setting
1260\np{ln\_diaptr} to true (see the \textit{namptr} namelist below). 
1261When \np{ln\_subbas}~=~true, transports and stream function are computed
1262for the Atlantic, Indian, Pacific and Indo-Pacific Oceans (defined north of 30\deg S)
1263as well as for the World Ocean. The sub-basin decomposition requires an input file
1264(\ifile{subbasins}) which contains three 2D mask arrays, the Indo-Pacific mask
1265been deduced from the sum of the Indian and Pacific mask (Fig~\ref{Fig_mask_subasins}).
1266
1267%------------------------------------------namptr----------------------------------------------------
1268\namdisplay{namptr} 
1269%-------------------------------------------------------------------------------------------------------------
1270%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
1271\begin{figure}[!t]     \begin{center}
1272\includegraphics[width=1.0\textwidth]{./TexFiles/Figures/Fig_mask_subasins.pdf}
1273\caption{   \label{Fig_mask_subasins}
1274Decomposition of the World Ocean (here ORCA2) into sub-basin used in to compute
1275the heat and salt transports as well as the meridional stream-function: Atlantic basin (red),
1276Pacific basin (green), Indian basin (bleue), Indo-Pacific basin (bleue+green).
1277Note that semi-enclosed seas (Red, Med and Baltic seas) as well as Hudson Bay
1278are removed from the sub-basins. Note also that the Arctic Ocean has been split
1279into Atlantic and Pacific basins along the North fold line.  }
1280\end{center}   \end{figure} 
1281%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
1282
1283In addition, a series of diagnostics has been added in the \mdl{diaar5}.
1284They corresponds to outputs that are required for AR5 simulations
1285(see Section \ref{DIA_steric} below for one of them).
1286Activating those outputs requires to define the \key{diaar5} CPP key.
1287\\
1288\\
1289
1290
1291
1292% ================================================================
1293% Steric effect in sea surface height
1294% ================================================================
1295\section{Diagnosing the Steric effect in sea surface height}
1296\label{DIA_steric}
1297
1298
1299Changes in steric sea level are caused when changes in the density of the water
1300column imply an expansion or contraction of the column. It is essentially produced
1301through surface heating/cooling and to a lesser extent through non-linear effects of
1302the equation of state (cabbeling, thermobaricity...).
1303Non-Boussinesq models contain all ocean effects within the ocean acting
1304on the sea level. In particular, they include the steric effect. In contrast,
1305Boussinesq models, such as \NEMO, conserve volume, rather than mass,
1306and so do not properly represent expansion or contraction. The steric effect is
1307therefore not explicitely represented.
1308This approximation does not represent a serious error with respect to the flow field
1309calculated by the model \citep{Greatbatch_JGR94}, but extra attention is required
1310when investigating sea level, as steric changes are an important
1311contribution to local changes in sea level on seasonal and climatic time scales.
1312This is especially true for investigation into sea level rise due to global warming.
1313
1314Fortunately, the steric contribution to the sea level consists of a spatially uniform
1315component that can be diagnosed by considering the mass budget of the world
1316ocean \citep{Greatbatch_JGR94}.
1317In order to better understand how global mean sea level evolves and thus how
1318the steric sea level can be diagnosed, we compare, in the following, the
1319non-Boussinesq and Boussinesq cases.
1320
1321Let denote
1322$\mathcal{M}$ the total mass of liquid seawater ($\mathcal{M}=\int_D \rho dv$),
1323$\mathcal{V}$ the total volume of seawater ($\mathcal{V}=\int_D dv$),
1324$\mathcal{A}$ the total surface of the ocean ($\mathcal{A}=\int_S ds$),
1325$\bar{\rho}$ the global mean seawater (\textit{in situ}) density ($\bar{\rho}= 1/\mathcal{V} \int_D \rho \,dv$), and
1326$\bar{\eta}$ the global mean sea level ($\bar{\eta}=1/\mathcal{A}\int_S \eta \,ds$).
1327
1328A non-Boussinesq fluid conserves mass. It satisfies the following relations:
1329\begin{equation} \label{Eq_MV_nBq} 
1330\begin{split} 
1331\mathcal{M} &\mathcal{V}  \;\bar{\rho}       \\
1332\mathcal{V} &\mathcal{A}  \;\bar{\eta} 
1333\end{split}
1334\end{equation}
1335Temporal changes in total mass is obtained from the density conservation equation :
1336\begin{equation}  \label{Eq_Co_nBq}
1337\frac{1}{e_3} \partial_t ( e_3\,\rho) + \nabla( \rho \, \textbf{U} ) = \left. \frac{\textit{emp}}{e_3}\right|_\textit{surface}
1338\end{equation}
1339where $\rho$ is the \textit{in situ} density, and \textit{emp} the surface mass
1340exchanges with the other media of the Earth system (atmosphere, sea-ice, land).
1341Its global averaged leads to the total mass change
1342\begin{equation}  \label{Eq_Mass_nBq}
1343\partial_t \mathcal{M} = \mathcal{A} \;\overline{\textit{emp}}
1344\end{equation}
1345where $\overline{\textit{emp}}=\int_S \textit{emp}\,ds$ is the net mass flux
1346through the ocean surface.
1347Bringing \eqref{Eq_Mass_nBq} and the time derivative of \eqref{Eq_MV_nBq} 
1348together leads to the evolution equation of the mean sea level
1349\begin{equation} \label{Eq_ssh_nBq}
1350  \partial_t \bar{\eta} =  \frac{\overline{\textit{emp}}}{ \bar{\rho}} 
1351               - \frac{\mathcal{V}}{\mathcal{A}}  \;\frac{\partial_t \bar{\rho} }{\bar{\rho}}
1352\end{equation}
1353The first term in equation \eqref{Eq_ssh_nBq} alters sea level by adding or
1354subtracting mass from the ocean.
1355The second term arises from temporal changes in the global mean
1356density; $i.e.$ from steric effects.
1357
1358In a Boussinesq fluid, $\rho$ is replaced by $\rho_o$ in all the equation except when $\rho$ 
1359appears multiplied by the gravity ($i.e.$ in the hydrostatic balance of the primitive Equations).
1360In particular, the mass conservation equation, \eqref{Eq_Co_nBq}, degenerates into
1361the incompressibility equation:
1362\begin{equation}  \label{Eq_Co_Bq}
1363\frac{1}{e_3} \partial_t ( e_3 ) + \nabla( \textbf{U} ) =  \left. \frac{\textit{emp}}{\rho_o \,e_3}\right|_ \textit{surface}
1364\end{equation}
1365and the global average of this equation now gives the temporal change of the total volume,
1366\begin{equation}  \label{Eq_V_Bq}
1367  \partial_t \mathcal{V} =   \mathcal{A} \;\frac{\overline{\textit{emp}}}{\rho_o} 
1368\end{equation}
1369Only the volume is conserved, not mass, or, more precisely, the mass which is conserved is the
1370Boussinesq mass, $\mathcal{M}_o = \rho_o \mathcal{V}$. The total volume (or equivalently 
1371the global mean sea level) is altered only by net volume fluxes across the ocean surface, 
1372not by changes in mean mass of the ocean: the steric effect is missing in a Boussinesq fluid.
1373 
1374Nevertheless, following \citep{Greatbatch_JGR94}, the steric effect on the volume can be
1375diagnosed by considering the mass budget of the ocean.
1376The apparent changes in $\mathcal{M}$, mass of the ocean, which are not induced by surface
1377mass flux must be compensated by a spatially uniform change in the mean sea level due to
1378expansion/contraction of the ocean \citep{Greatbatch_JGR94}. In others words, the Boussinesq
1379mass, $\mathcal{M}_o$, can be related to $\mathcal{M}$, the  total mass of the ocean seen
1380by the Boussinesq model, via the steric contribution to the sea level, $\eta_s$, a spatially
1381uniform variable, as follows:
1382\begin{equation}  \label{Eq_M_Bq}
1383   \mathcal{M}_o  =  \mathcal{M} + \rho_o \,\eta_s \,\mathcal{A} 
1384\end{equation}
1385Any change in $\mathcal{M}$ which cannot be explained by the net mass flux through
1386the ocean surface is converted into a mean change in sea level. Introducing the total density
1387anomaly, $\mathcal{D}= \int_D d_a \,dv$, where $d_a= (\rho -\rho_o ) / \rho_o$ 
1388is the density anomaly used in \NEMO (cf. \S\ref{TRA_eos}) in \eqref{Eq_M_Bq}
1389leads to a very simple form for the steric height:
1390\begin{equation}  \label{Eq_steric_Bq}
1391   \eta_s = - \frac{1}{\mathcal{A}} \mathcal{D} 
1392\end{equation}
1393
1394The above formulation of the steric height of a Boussinesq ocean requires four remarks.
1395First, one can be tempted to define $\rho_o$ as the initial value of $\mathcal{M}/\mathcal{V}$,
1396$i.e.$ set $\mathcal{D}_{t=0}=0$, so that the initial steric height is zero. We do not
1397recommend that. Indeed, in this case $\rho_o$ depends on the initial state of the ocean.
1398Since $\rho_o$ has a direct effect on the dynamics of the ocean (it appears in the pressure
1399gradient term of the momentum equation) it is definitively not a good idea when
1400inter-comparing experiments.
1401We better recommend to fixe once for all $\rho_o$ to $1035\;Kg\,m^{-3}$. This value is a
1402sensible choice for the reference density used in a Boussinesq ocean climate model since,
1403with the exception of only a small percentage of the ocean, density in the World Ocean
1404varies by no more than 2$\%$ from this value (\cite{Gill1982}, page 47).
1405
1406Second, we have assumed here that the total ocean surface, $\mathcal{A}$, does not
1407change when the sea level is changing as it is the case in all global ocean GCMs
1408(wetting and drying of grid point is not allowed).
1409 
1410Third, the discretisation of \eqref{Eq_steric_Bq} depends on the type of free surface
1411which is considered. In the non linear free surface case, $i.e.$ \key{vvl} defined, it is
1412given by
1413\begin{equation}  \label{Eq_discrete_steric_Bq}
1414   \eta_s =  - \frac{ \sum_{i,\,j,\,k} d_a\; e_{1t} e_{2t} e_{3t} }
1415                  { \sum_{i,\,j,\,k}         e_{1t} e_{2t} e_{3t} } 
1416\end{equation}
1417whereas in the linear free surface, the volume above the \textit{z=0} surface must be explicitly taken
1418into account to better approximate the total ocean mass and thus the steric sea level:
1419\begin{equation}  \label{Eq_discrete_steric_Bq}
1420   \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 }
1421                     {\sum_{i,\,j,\,k} e_{1t}e_{2t}e_{3t} + \sum_{i,\,j}           e_{1t}e_{2t} \eta } 
1422\end{equation}
1423
1424The fourth and last remark concerns the effective sea level and the presence of sea-ice.
1425In the real ocean, sea ice (and snow above it)  depresses the liquid seawater through
1426its mass loading. This depression is a result of the mass of sea ice/snow system acting
1427on the liquid ocean. There is, however, no dynamical effect associated with these depressions
1428in the liquid ocean sea level, so that there are no associated ocean currents. Hence, the
1429dynamically relevant sea level is the effective sea level, $i.e.$ the sea level as if sea ice
1430(and snow) were converted to liquid seawater \citep{Campin_al_OM08}. However,
1431in the current version of \NEMO the sea-ice is levitating above the ocean without
1432mass exchanges between ice and ocean. Therefore the model effective sea level
1433is always given by $\eta + \eta_s$, whether or not there is sea ice present.
1434
1435In AR5 outputs, the thermosteric sea level is demanded. It is steric sea level due to
1436changes in ocean density arising just from changes in temperature. It is given by:
1437\begin{equation}  \label{Eq_thermosteric_Bq}
1438   \eta_s = - \frac{1}{\mathcal{A}} \int_D d_a(T,S_o,p_o) \,dv
1439\end{equation}
1440where $S_o$ and $p_o$ are the initial salinity and pressure, respectively.
1441
1442Both steric and thermosteric sea level are computed in \mdl{diaar5} which needs
1443the \key{diaar5} defined to be called.
1444
1445% ================================================================
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
Note: See TracBrowser for help on using the repository browser.