Context Navigation

chap_DIA.tex @ 9596

Last change on this file since 9596 was 9414, checked in by nicolasmartin, 6 years ago
Fix multiple defined references
Property svn:keywords set to `Id`
File size: 95.3 KB

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

Note: See TracBrowser for help on using the repository browser.

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

Context Navigation

source: NEMO/trunk/doc/tex_sub/chap_DIA.tex @ 9596

Download in other formats: