Context Navigation

chap_DIA.tex @ 10146

Last change on this file since 10146 was 10146, checked in by nicolasmartin, 6 years ago

Reorganisation for future addition of .rst files from users wiki extraction

Create root directories latex and rst for tidy up
Move namelists folder to the root with the aim to gather later all namelist groups here (OCE, ICE & TOP) Also building scripts have been modified so that figures is now expected to be present at the root
Create bin directory with namelist utilities (check and update)
Under rst, add 4 dummy files that would gather the whole documentation existing currently in users wiki
- model_interfacing.rst
- reference_configurations.rst
- setup_configuration.rst
- test_cases.rst

Property svn:keywords set to Id

File size: 95.2 KB

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

Download in other formats: