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 NEMO/branches/2018/dev_r10164_HPC09_ESIWACE_PREP_MERGE/doc/latex/NEMO/subfiles – NEMO

Context Navigation

source: NEMO/branches/2018/dev_r10164_HPC09_ESIWACE_PREP_MERGE/doc/latex/NEMO/subfiles/chap_DIA.tex @ 10368

Last change on this file since 10368 was 10368, checked in by smasson, 5 years ago
dev_r10164_HPC09_ESIWACE_PREP_MERGE: merge with trunk@10365, see #2133
Property svn:keywords set to `Id`
File size: 95.0 KB

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

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

Download in other formats: