Context Navigation

← Previous Revision
Next Revision →
Blame
Revision Log

chap_DIA.tex

Last change on this file was 14530, checked in by nicolasmartin, 3 years ago
Revert commit 14526, can't use verbatim envs in macro
Property svn:keywords set to `Id`
File size: 99.1 KB

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

Download in other formats: