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="degC*m" grid_ref="grid_T_3D" >toce * e3t</field> |
---|
695 | \end{xmllines} |
---|
696 | |
---|
697 | - use it when defining your file. |
---|
698 | |
---|
699 | \begin{xmllines} |
---|
700 | <file_group id="5d" output_freq="5d" output_level="10" enabled=".true." > <!-- 5d files --> |
---|
701 | <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" > |
---|
702 | <field field_ref="toce" operation="instant" freq_op="5d" > @toce_e3t / @e3t </field> |
---|
703 | </file> |
---|
704 | </file_group> |
---|
705 | \end{xmllines} |
---|
706 | |
---|
707 | The freq\_op="5d" attribute is used to define the operation frequency of the ``@'' function: here 5 day. |
---|
708 | The temporal operation done by the ``@'' is the one defined in the field definition: |
---|
709 | here we use the default, average. |
---|
710 | So, in the above case, @toce\_e3t will do the 5-day mean of toce*e3t. |
---|
711 | Operation="instant" refers to the temporal operation to be performed on the field''@toce\_e3t / @e3t'': |
---|
712 | here the temporal average is alreday done by the ``@'' function so we just use instant to do the ratio of |
---|
713 | the 2 mean values. |
---|
714 | field\_ref="toce" means that attributes not explicitely defined, are inherited from toce field. |
---|
715 | Note that in this case, freq\_op must be equal to the file output\_freq. |
---|
716 | |
---|
717 | \item use of the ``@'' function: example 2, monthly SSH standard deviation |
---|
718 | |
---|
719 | - define a new variable in field\_definition |
---|
720 | |
---|
721 | \begin{xmllines} |
---|
722 | <field id="ssh2" long_name="square of sea surface temperature" unit="degC2" > ssh * ssh </field > |
---|
723 | \end{xmllines} |
---|
724 | |
---|
725 | - use it when defining your file. |
---|
726 | |
---|
727 | \begin{xmllines} |
---|
728 | <file_group id="1m" output_freq="1m" output_level="10" enabled=".true." > <!-- 1m files --> |
---|
729 | <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" > |
---|
730 | <field field_ref="ssh" name="sshstd" long_name="sea_surface_temperature_standard_deviation" |
---|
731 | operation="instant" freq_op="1m" > |
---|
732 | sqrt( @ssh2 - @ssh * @ssh ) |
---|
733 | </field> |
---|
734 | </file> |
---|
735 | </file_group> |
---|
736 | \end{xmllines} |
---|
737 | |
---|
738 | The freq\_op="1m" attribute is used to define the operation frequency of the ``@'' function: here 1 month. |
---|
739 | The temporal operation done by the ``@'' is the one defined in the field definition: |
---|
740 | here we use the default, average. |
---|
741 | So, in the above case, @ssh2 will do the monthly mean of ssh*ssh. |
---|
742 | Operation="instant" refers to the temporal operation to be performed on |
---|
743 | the field ''sqrt( @ssh2 - @ssh * @ssh )'': |
---|
744 | here the temporal average is alreday done by the ``@'' function so we just use instant. |
---|
745 | field\_ref="ssh" means that attributes not explicitely defined, are inherited from ssh field. |
---|
746 | Note that in this case, freq\_op must be equal to the file output\_freq. |
---|
747 | |
---|
748 | \item use of the ``@'' function: example 3, monthly average of SST diurnal cycle |
---|
749 | |
---|
750 | - define 2 new variables in field\_definition |
---|
751 | |
---|
752 | \begin{xmllines} |
---|
753 | <field id="sstmax" field_ref="sst" long_name="max of sea surface temperature" operation="maximum" /> |
---|
754 | <field id="sstmin" field_ref="sst" long_name="min of sea surface temperature" operation="minimum" /> |
---|
755 | \end{xmllines} |
---|
756 | |
---|
757 | - use these 2 new variables when defining your file. |
---|
758 | |
---|
759 | \begin{xmllines} |
---|
760 | <file_group id="1m" output_freq="1m" output_level="10" enabled=".true." > <!-- 1m files --> |
---|
761 | <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" > |
---|
762 | <field field_ref="sst" name="sstdcy" long_name="amplitude of sst diurnal cycle" operation="average" freq_op="1d" > |
---|
763 | @sstmax - @sstmin |
---|
764 | </field> |
---|
765 | </file> |
---|
766 | </file_group> |
---|
767 | \end{xmllines} |
---|
768 | |
---|
769 | \end{enumerate} |
---|
770 | |
---|
771 | The freq\_op="1d" attribute is used to define the operation frequency of the ``@'' function: here 1 day. |
---|
772 | The temporal operation done by the ``@'' is the one defined in the field definition: here maximum for |
---|
773 | sstmax and minimum for sstmin. |
---|
774 | So, in the above case, @sstmax will do the daily max and @sstmin the daily min. |
---|
775 | Operation="average" refers to the temporal operation to be performed on the field ``@sstmax - @sstmin'': |
---|
776 | here monthly mean (of daily max - daily min of the sst). |
---|
777 | field\_ref="sst" means that attributes not explicitely defined, are inherited from sst field. |
---|
778 | |
---|
779 | \subsubsection{Tag list per family} |
---|
780 | |
---|
781 | \begin{table} \scriptsize |
---|
782 | \begin{tabularx}{\textwidth}{|l|X|X|l|X|} \hline |
---|
783 | tag name & |
---|
784 | description & |
---|
785 | accepted attribute & |
---|
786 | child of & |
---|
787 | parent of \\ \hline \hline |
---|
788 | simulation & |
---|
789 | this tag is the root tag which encapsulates all the content of the XML file & |
---|
790 | none & |
---|
791 | none & |
---|
792 | context \\ \hline |
---|
793 | context & |
---|
794 | encapsulates parts of the XML file dedicated to different codes or different parts of a code & |
---|
795 | id (''xios'', ''nemo'' or ''n\_nemo'' for the nth AGRIF zoom), src, time\_origin & |
---|
796 | simulation & |
---|
797 | all root tags: ... \_definition \\ \hline |
---|
798 | \end{tabularx} |
---|
799 | \caption{Context tags} |
---|
800 | \end{table} |
---|
801 | |
---|
802 | \begin{table} \scriptsize |
---|
803 | \begin{tabularx}{\textwidth}{|l|X|X|X|l|} \hline |
---|
804 | tag name & |
---|
805 | description & |
---|
806 | accepted attribute & |
---|
807 | child of & |
---|
808 | parent of \\ \hline \hline |
---|
809 | field\_definition & |
---|
810 | encapsulates the definition of all the fields that can potentially be outputted & |
---|
811 | axis\_ref, default\_value, domain\_ref, enabled, grid\_ref, level, operation, prec, src & |
---|
812 | context & |
---|
813 | field or field\_group \\ \hline |
---|
814 | field\_group & |
---|
815 | encapsulates a group of fields & |
---|
816 | axis\_ref, default\_value, domain\_ref, enabled, group\_ref, grid\_ref, |
---|
817 | id, level, operation, prec, src & |
---|
818 | field\_definition, field\_group, file & |
---|
819 | field or field\_group \\ \hline |
---|
820 | field & |
---|
821 | define a specific field & |
---|
822 | axis\_ref, default\_value, domain\_ref, enabled, field\_ref, grid\_ref, |
---|
823 | id, level, long\_name, name, operation, prec, standard\_name, unit & |
---|
824 | field\_definition, field\_group, file & |
---|
825 | none \\ \hline |
---|
826 | \end{tabularx} |
---|
827 | \caption{Field tags ("\tt{field\_*}")} |
---|
828 | \end{table} |
---|
829 | |
---|
830 | \begin{table} \scriptsize |
---|
831 | \begin{tabularx}{\textwidth}{|l|X|X|X|l|} \hline |
---|
832 | tag name & |
---|
833 | description & |
---|
834 | accepted attribute & |
---|
835 | child of & |
---|
836 | parent of \\ \hline \hline |
---|
837 | file\_definition & |
---|
838 | encapsulates the definition of all the files that will be outputted & |
---|
839 | enabled, min\_digits, name, name\_suffix, output\_level, |
---|
840 | split\_freq\_format, split\_freq, sync\_freq, type, src & |
---|
841 | context & |
---|
842 | file or file\_group \\ \hline |
---|
843 | file\_group & |
---|
844 | encapsulates a group of files that will be outputted & |
---|
845 | enabled, description, id, min\_digits, name, name\_suffix, output\_freq, output\_level, |
---|
846 | split\_freq\_format, split\_freq, sync\_freq, type, src & |
---|
847 | file\_definition, file\_group & |
---|
848 | file or file\_group \\ \hline |
---|
849 | file & |
---|
850 | define the contents of a file to be outputted & |
---|
851 | enabled, description, id, min\_digits, name, name\_suffix, output\_freq, output\_level, |
---|
852 | split\_freq\_format, split\_freq, sync\_freq, type, src & |
---|
853 | file\_definition, file\_group & |
---|
854 | field \\ \hline |
---|
855 | \end{tabularx} |
---|
856 | \caption{File tags ("\tt{file\_*}")} |
---|
857 | \end{table} |
---|
858 | |
---|
859 | \begin{table} \scriptsize |
---|
860 | \begin{tabularx}{\textwidth}{|l|X|X|X|X|} \hline |
---|
861 | tag name & |
---|
862 | description & |
---|
863 | accepted attribute & |
---|
864 | child of & |
---|
865 | parent of \\ \hline \hline |
---|
866 | axis\_definition & |
---|
867 | define all the vertical axis potentially used by the variables & |
---|
868 | src & |
---|
869 | context & |
---|
870 | axis\_group, axis \\ \hline |
---|
871 | axis\_group & |
---|
872 | encapsulates a group of vertical axis & |
---|
873 | id, lon\_name, positive, src, standard\_name, unit, zoom\_begin, zoom\_end, zoom\_size & |
---|
874 | axis\_definition, axis\_group & |
---|
875 | axis\_group, axis \\ \hline |
---|
876 | axis & |
---|
877 | define a vertical axis & |
---|
878 | id, lon\_name, positive, src, standard\_name, unit, zoom\_begin, zoom\_end, zoom\_size & |
---|
879 | axis\_definition, axis\_group & |
---|
880 | none \\ \hline |
---|
881 | \end{tabularx} |
---|
882 | \caption{Axis tags ("\tt{axis\_*}")} |
---|
883 | \end{table} |
---|
884 | |
---|
885 | \begin{table} \scriptsize |
---|
886 | \begin{tabularx}{\textwidth}{|l|X|X|X|X|} \hline |
---|
887 | tag name & |
---|
888 | description & |
---|
889 | accepted attribute & |
---|
890 | child of & |
---|
891 | parent of \\ \hline \hline |
---|
892 | domain\_\-definition & |
---|
893 | define all the horizontal domains potentially used by the variables & |
---|
894 | src & |
---|
895 | context & |
---|
896 | domain\_\-group, domain \\ \hline |
---|
897 | domain\_group & |
---|
898 | encapsulates a group of horizontal domains & |
---|
899 | id, lon\_name, src, zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj & |
---|
900 | domain\_\-definition, domain\_group & |
---|
901 | domain\_\-group, domain \\ \hline |
---|
902 | domain & |
---|
903 | define an horizontal domain & |
---|
904 | id, lon\_name, src, zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj & |
---|
905 | domain\_\-definition, domain\_group & |
---|
906 | none \\ \hline |
---|
907 | \end{tabularx} |
---|
908 | \caption{Domain tags ("\tt{domain\_*)}"} |
---|
909 | \end{table} |
---|
910 | |
---|
911 | \begin{table} \scriptsize |
---|
912 | \begin{tabularx}{\textwidth}{|l|X|X|X|X|} \hline |
---|
913 | tag name & |
---|
914 | description & |
---|
915 | accepted attribute & |
---|
916 | child of & |
---|
917 | parent of \\ \hline \hline |
---|
918 | grid\_definition & |
---|
919 | define all the grid (association of a domain and/or an axis) potentially used by the variables & |
---|
920 | src & |
---|
921 | context & |
---|
922 | grid\_group, grid \\ \hline |
---|
923 | grid\_group & |
---|
924 | encapsulates a group of grids & |
---|
925 | id, domain\_ref,axis\_ref & |
---|
926 | grid\_definition, grid\_group & |
---|
927 | grid\_group, grid \\ \hline |
---|
928 | grid & |
---|
929 | define a grid & |
---|
930 | id, domain\_ref,axis\_ref & |
---|
931 | grid\_definition, grid\_group & |
---|
932 | none \\ \hline |
---|
933 | \end{tabularx} |
---|
934 | \caption{Grid tags ("\tt{grid\_*}")} |
---|
935 | \end{table} |
---|
936 | |
---|
937 | \subsubsection{Attributes list per family} |
---|
938 | |
---|
939 | \begin{table} \scriptsize |
---|
940 | \begin{tabularx}{\textwidth}{|l|X|l|l|} \hline |
---|
941 | attribute name & |
---|
942 | description & |
---|
943 | example & |
---|
944 | accepted by \\ \hline \hline |
---|
945 | axis\_ref & |
---|
946 | refers to the id of a vertical axis & |
---|
947 | axis\_ref="deptht" & |
---|
948 | field, grid families \\ \hline |
---|
949 | domain\_ref & |
---|
950 | refers to the id of a domain & |
---|
951 | domain\_ref="grid\_T" & |
---|
952 | field or grid families \\ \hline |
---|
953 | field\_ref & |
---|
954 | id of the field we want to add in a file & |
---|
955 | field\_ref="toce" & |
---|
956 | field \\ \hline |
---|
957 | grid\_ref & |
---|
958 | refers to the id of a grid & |
---|
959 | grid\_ref="grid\_T\_2D" & |
---|
960 | field family \\ \hline |
---|
961 | group\_ref & |
---|
962 | refer to a group of variables & |
---|
963 | group\_ref="mooring" & |
---|
964 | field\_group \\ \hline |
---|
965 | \end{tabularx} |
---|
966 | \caption{Reference attributes ("\tt{*\_ref}")} |
---|
967 | \end{table} |
---|
968 | |
---|
969 | \begin{table} \scriptsize |
---|
970 | \begin{tabularx}{\textwidth}{|l|X|l|l|} \hline |
---|
971 | attribute name & |
---|
972 | description & |
---|
973 | example & |
---|
974 | accepted by \\ \hline \hline |
---|
975 | zoom\_ibegin & |
---|
976 | starting point along x direction of the zoom. |
---|
977 | Automatically defined for TAO/RAMA/PIRATA moorings & |
---|
978 | zoom\_ibegin="1" & |
---|
979 | domain family \\ \hline |
---|
980 | zoom\_jbegin & |
---|
981 | starting point along y direction of the zoom. |
---|
982 | Automatically defined for TAO/RAMA/PIRATA moorings & |
---|
983 | zoom\_jbegin="1" & |
---|
984 | domain family \\ \hline |
---|
985 | zoom\_ni & |
---|
986 | zoom extent along x direction & |
---|
987 | zoom\_ni="1" & |
---|
988 | domain family \\ \hline |
---|
989 | zoom\_nj & |
---|
990 | zoom extent along y direction & |
---|
991 | zoom\_nj="1" & |
---|
992 | domain family \\ \hline |
---|
993 | \end{tabularx} |
---|
994 | \caption{Domain attributes ("\tt{zoom\_*}")} |
---|
995 | \end{table} |
---|
996 | |
---|
997 | \begin{table} \scriptsize |
---|
998 | \begin{tabularx}{\textwidth}{|l|X|l|l|} \hline |
---|
999 | attribute name & |
---|
1000 | description & |
---|
1001 | example & |
---|
1002 | accepted by \\ \hline \hline |
---|
1003 | min\_digits & |
---|
1004 | specify the minimum of digits used in the core number in the name of the NetCDF file & |
---|
1005 | min\_digits="4" & |
---|
1006 | file family \\ \hline |
---|
1007 | name\_suffix & |
---|
1008 | suffix to be inserted after the name and before the cpu number and the ''.nc'' termination of a file & |
---|
1009 | name\_suffix="\_myzoom" & |
---|
1010 | file family \\ \hline |
---|
1011 | output\_level & |
---|
1012 | output priority of variables in a file: 0 (high) to 10 (low). |
---|
1013 | All variables listed in the file with a level smaller or equal to output\_level will be output. |
---|
1014 | Other variables won't be output even if they are listed in the file. & |
---|
1015 | output\_level="10" & |
---|
1016 | file family \\ \hline |
---|
1017 | split\_freq & |
---|
1018 | frequency at which to temporally split output files. |
---|
1019 | Units can be ts (timestep), y, mo, d, h, mi, s. |
---|
1020 | Useful for long runs to prevent over-sized output files. & |
---|
1021 | split\_freq="1mo" & |
---|
1022 | file family \\ \hline |
---|
1023 | split\_freq\-\_format & |
---|
1024 | date format used in the name of temporally split output files. |
---|
1025 | Can be specified using the following syntaxes: \%y, \%mo, \%d, \%h \%mi and \%s & |
---|
1026 | split\_freq\_format= "\%y\%mo\%d" & |
---|
1027 | file family \\ \hline |
---|
1028 | sync\_freq & |
---|
1029 | NetCDF file synchronization frequency (update of the time\_counter). |
---|
1030 | Units can be ts (timestep), y, mo, d, h, mi, s. & |
---|
1031 | sync\_freq="10d" & |
---|
1032 | file family \\ \hline |
---|
1033 | type (1) & |
---|
1034 | specify if the output files are to be split spatially (multiple\_file) or not (one\_file) & |
---|
1035 | type="multiple\_file" & |
---|
1036 | file familly \\ \hline |
---|
1037 | \end{tabularx} |
---|
1038 | \caption{File attributes} |
---|
1039 | \end{table} |
---|
1040 | |
---|
1041 | \begin{table} \scriptsize |
---|
1042 | \begin{tabularx}{\textwidth}{|l|X|l|l|} \hline |
---|
1043 | attribute name & |
---|
1044 | description & |
---|
1045 | example & |
---|
1046 | accepted by \\ \hline \hline |
---|
1047 | default\_value & |
---|
1048 | missing\_value definition & |
---|
1049 | default\_value="1.e20" & |
---|
1050 | field family \\ \hline |
---|
1051 | level & |
---|
1052 | output priority of a field: 0 (high) to 10 (low) & |
---|
1053 | level="1" & |
---|
1054 | field family \\ \hline |
---|
1055 | operation & |
---|
1056 | type of temporal operation: average, accumulate, instantaneous, min, max and once & |
---|
1057 | operation="average" & |
---|
1058 | field family \\ \hline |
---|
1059 | output\_freq & |
---|
1060 | operation frequency. units can be ts (timestep), y, mo, d, h, mi, s. & |
---|
1061 | output\_freq="1d12h" & |
---|
1062 | field family \\ \hline |
---|
1063 | prec & |
---|
1064 | output precision: real 4 or real 8 & |
---|
1065 | prec="4" & |
---|
1066 | field family \\ \hline |
---|
1067 | long\_name & |
---|
1068 | define the long\_name attribute in the NetCDF file & |
---|
1069 | long\_name="Vertical T levels" & |
---|
1070 | field \\ \hline |
---|
1071 | standard\_name & |
---|
1072 | define the standard\_name attribute in the NetCDF file & |
---|
1073 | standard\_name= "Eastward\_Sea\_Ice\_Transport" & |
---|
1074 | field \\ \hline |
---|
1075 | \end{tabularx} |
---|
1076 | \caption{Field attributes} |
---|
1077 | \end{table} |
---|
1078 | |
---|
1079 | \begin{table} \scriptsize |
---|
1080 | \begin{tabularx}{\textwidth}{|l|X|X|X|} \hline |
---|
1081 | attribute name & |
---|
1082 | description & |
---|
1083 | example & |
---|
1084 | accepted by \\ \hline \hline |
---|
1085 | enabled & |
---|
1086 | switch on/off the output of a field or a file & |
---|
1087 | enabled=".true." & |
---|
1088 | field, file families \\ \hline |
---|
1089 | description & |
---|
1090 | just for information, not used & |
---|
1091 | description="ocean T grid variables" & |
---|
1092 | all tags \\ \hline |
---|
1093 | id & |
---|
1094 | allow to identify a tag & |
---|
1095 | id="nemo" & |
---|
1096 | accepted by all tags except simulation \\ \hline |
---|
1097 | name & |
---|
1098 | name of a variable or a file. If the name of a file is undefined, its id is used as a name & |
---|
1099 | name="tos" & |
---|
1100 | field or file families \\ \hline |
---|
1101 | positive & |
---|
1102 | convention used for the orientation of vertival axis (positive downward in \NEMO). & |
---|
1103 | positive="down" & |
---|
1104 | axis family \\ \hline |
---|
1105 | src & |
---|
1106 | allow to include a file & |
---|
1107 | src="./field\_def.xml" & |
---|
1108 | accepted by all tags except simulation \\ \hline |
---|
1109 | time\_origin & |
---|
1110 | specify the origin of the time counter & |
---|
1111 | time\_origin="1900-01-01 00:00:00" & |
---|
1112 | context \\ \hline |
---|
1113 | type (2) & |
---|
1114 | define the type of a variable tag & |
---|
1115 | type="boolean" & |
---|
1116 | variable \\ \hline |
---|
1117 | unit & |
---|
1118 | unit of a variable or the vertical axis & |
---|
1119 | unit="m" & |
---|
1120 | field and axis families \\ \hline |
---|
1121 | \end{tabularx} |
---|
1122 | \caption{Miscellaneous attributes} |
---|
1123 | \end{table} |
---|
1124 | |
---|
1125 | \subsection{CF metadata standard compliance} |
---|
1126 | |
---|
1127 | Output from the XIOS-1.0 IO server is compliant with |
---|
1128 | \href{http://cfconventions.org/Data/cf-conventions/cf-conventions-1.5/build/cf-conventions.html}{version 1.5} |
---|
1129 | of the CF metadata standard. |
---|
1130 | Therefore while a user may wish to add their own metadata to the output files (as demonstrated in |
---|
1131 | example 4 of section \autoref{subsec:IOM_xmlref}) the metadata should, for the most part, comply with |
---|
1132 | the CF-1.5 standard. |
---|
1133 | |
---|
1134 | Some metadata that may significantly increase the file size (horizontal cell areas and |
---|
1135 | vertices) are controlled by the namelist parameter \np{ln\_cfmeta} in the \ngn{namrun} namelist. |
---|
1136 | This must be set to true if these metadata are to be included in the output files. |
---|
1137 | |
---|
1138 | |
---|
1139 | % ================================================================ |
---|
1140 | % NetCDF4 support |
---|
1141 | % ================================================================ |
---|
1142 | \section{NetCDF4 support (\protect\key{netcdf4})} |
---|
1143 | \label{sec:DIA_nc4} |
---|
1144 | |
---|
1145 | Since version 3.3, support for NetCDF4 chunking and (loss-less) compression has been included. |
---|
1146 | These options build on the standard NetCDF output and allow the user control over the size of |
---|
1147 | the chunks via namelist settings. |
---|
1148 | Chunking and compression can lead to significant reductions in file sizes for a small runtime overhead. |
---|
1149 | For a fuller discussion on chunking and other performance issues the reader is referred to |
---|
1150 | the NetCDF4 documentation found |
---|
1151 | \href{http://www.unidata.ucar.edu/software/netcdf/docs/netcdf.html#Chunking}{here}. |
---|
1152 | |
---|
1153 | The new features are only available when the code has been linked with a NetCDF4 library |
---|
1154 | (version 4.1 onwards, recommended) which has been built with HDF5 support |
---|
1155 | (version 1.8.4 onwards, recommended). |
---|
1156 | Datasets created with chunking and compression are not backwards compatible with |
---|
1157 | NetCDF3 "classic" format but most analysis codes can be relinked simply with the new libraries and |
---|
1158 | will then read both NetCDF3 and NetCDF4 files. |
---|
1159 | NEMO executables linked with NetCDF4 libraries can be made to produce NetCDF3 files by |
---|
1160 | setting the \np{ln\_nc4zip} logical to false in the \textit{namnc4} namelist: |
---|
1161 | |
---|
1162 | %------------------------------------------namnc4---------------------------------------------------- |
---|
1163 | \forfile{../namelists/namnc4} |
---|
1164 | %------------------------------------------------------------------------------------------------------------- |
---|
1165 | |
---|
1166 | If \key{netcdf4} has not been defined, these namelist parameters are not read. |
---|
1167 | In this case, \np{ln\_nc4zip} is set false and dummy routines for |
---|
1168 | a few NetCDF4-specific functions are defined. |
---|
1169 | These functions will not be used but need to be included so that compilation is possible with |
---|
1170 | NetCDF3 libraries. |
---|
1171 | |
---|
1172 | When using NetCDF4 libraries, \key{netcdf4} should be defined even if the intention is to |
---|
1173 | create only NetCDF3-compatible files. |
---|
1174 | This is necessary to avoid duplication between the dummy routines and |
---|
1175 | the actual routines present in the library. |
---|
1176 | Most compilers will fail at compile time when faced with such duplication. |
---|
1177 | Thus when linking with NetCDF4 libraries the user must define \key{netcdf4} and |
---|
1178 | control the type of NetCDF file produced via the namelist parameter. |
---|
1179 | |
---|
1180 | Chunking and compression is applied only to 4D fields and there is no advantage in |
---|
1181 | chunking across more than one time dimension since previously written chunks would have to |
---|
1182 | be read back and decompressed before being added to. |
---|
1183 | Therefore, user control over chunk sizes is provided only for the three space dimensions. |
---|
1184 | The user sets an approximate number of chunks along each spatial axis. |
---|
1185 | The actual size of the chunks will depend on global domain size for mono-processors or, |
---|
1186 | more likely, the local processor domain size for distributed processing. |
---|
1187 | The derived values are subject to practical minimum values (to avoid wastefully small chunk sizes) and |
---|
1188 | cannot be greater than the domain size in any dimension. |
---|
1189 | The algorithm used is: |
---|
1190 | |
---|
1191 | \begin{forlines} |
---|
1192 | ichunksz(1) = MIN(idomain_size, MAX((idomain_size-1) / nn_nchunks_i + 1 ,16 )) |
---|
1193 | ichunksz(2) = MIN(jdomain_size, MAX((jdomain_size-1) / nn_nchunks_j + 1 ,16 )) |
---|
1194 | ichunksz(3) = MIN(kdomain_size, MAX((kdomain_size-1) / nn_nchunks_k + 1 , 1 )) |
---|
1195 | ichunksz(4) = 1 |
---|
1196 | \end{forlines} |
---|
1197 | |
---|
1198 | \noindent As an example, setting: |
---|
1199 | |
---|
1200 | \begin{forlines} |
---|
1201 | nn_nchunks_i=4, nn_nchunks_j=4 and nn_nchunks_k=31 |
---|
1202 | \end{forlines} |
---|
1203 | |
---|
1204 | \noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\tt 46x38x1} respectively in |
---|
1205 | the mono-processor case (i.e. global domain of {\small\tt 182x149x31}). |
---|
1206 | An illustration of the potential space savings that NetCDF4 chunking and compression provides is given in |
---|
1207 | table \autoref{tab:NC4} which compares the results of two short runs of |
---|
1208 | the ORCA2\_LIM reference configuration with a 4x2 mpi partitioning. |
---|
1209 | Note the variation in the compression ratio achieved which reflects chiefly the dry to |
---|
1210 | wet volume ratio of each processing region. |
---|
1211 | |
---|
1212 | %------------------------------------------TABLE---------------------------------------------------- |
---|
1213 | \begin{table} \scriptsize \centering |
---|
1214 | \begin{tabular}{lrrr} |
---|
1215 | Filename & NetCDF3 & NetCDF4 & Reduction \\ |
---|
1216 | & filesize & filesize & \% \\ |
---|
1217 | & (KB) & (KB) & \\ |
---|
1218 | ORCA2\_restart\_0000.nc & 16420 & 8860 & 47\% \\ |
---|
1219 | ORCA2\_restart\_0001.nc & 16064 & 11456 & 29\% \\ |
---|
1220 | ORCA2\_restart\_0002.nc & 16064 & 9744 & 40\% \\ |
---|
1221 | ORCA2\_restart\_0003.nc & 16420 & 9404 & 43\% \\ |
---|
1222 | ORCA2\_restart\_0004.nc & 16200 & 5844 & 64\% \\ |
---|
1223 | ORCA2\_restart\_0005.nc & 15848 & 8172 & 49\% \\ |
---|
1224 | ORCA2\_restart\_0006.nc & 15848 & 8012 & 50\% \\ |
---|
1225 | ORCA2\_restart\_0007.nc & 16200 & 5148 & 69\% \\ |
---|
1226 | ORCA2\_2d\_grid\_T\_0000.nc & 2200 & 1504 & 32\% \\ |
---|
1227 | ORCA2\_2d\_grid\_T\_0001.nc & 2200 & 1748 & 21\% \\ |
---|
1228 | ORCA2\_2d\_grid\_T\_0002.nc & 2200 & 1592 & 28\% \\ |
---|
1229 | ORCA2\_2d\_grid\_T\_0003.nc & 2200 & 1540 & 30\% \\ |
---|
1230 | ORCA2\_2d\_grid\_T\_0004.nc & 2200 & 1204 & 46\% \\ |
---|
1231 | ORCA2\_2d\_grid\_T\_0005.nc & 2200 & 1444 & 35\% \\ |
---|
1232 | ORCA2\_2d\_grid\_T\_0006.nc & 2200 & 1428 & 36\% \\ |
---|
1233 | ORCA2\_2d\_grid\_T\_0007.nc & 2200 & 1148 & 48\% \\ |
---|
1234 | ... & ... & ... & ... \\ |
---|
1235 | ORCA2\_2d\_grid\_W\_0000.nc & 4416 & 2240 & 50\% \\ |
---|
1236 | ORCA2\_2d\_grid\_W\_0001.nc & 4416 & 2924 & 34\% \\ |
---|
1237 | ORCA2\_2d\_grid\_W\_0002.nc & 4416 & 2512 & 44\% \\ |
---|
1238 | ORCA2\_2d\_grid\_W\_0003.nc & 4416 & 2368 & 47\% \\ |
---|
1239 | ORCA2\_2d\_grid\_W\_0004.nc & 4416 & 1432 & 68\% \\ |
---|
1240 | ORCA2\_2d\_grid\_W\_0005.nc & 4416 & 1972 & 56\% \\ |
---|
1241 | ORCA2\_2d\_grid\_W\_0006.nc & 4416 & 2028 & 55\% \\ |
---|
1242 | ORCA2\_2d\_grid\_W\_0007.nc & 4416 & 1368 & 70\% \\ |
---|
1243 | \end{tabular} |
---|
1244 | \caption{ |
---|
1245 | \protect\label{tab:NC4} |
---|
1246 | Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression} |
---|
1247 | \end{table} |
---|
1248 | %---------------------------------------------------------------------------------------------------- |
---|
1249 | |
---|
1250 | When \key{iomput} is activated with \key{netcdf4} chunking and compression parameters for |
---|
1251 | fields produced via \np{iom\_put} calls are set via an equivalent and identically named namelist to |
---|
1252 | \textit{namnc4} in \np{xmlio\_server.def}. |
---|
1253 | Typically this namelist serves the mean files whilst the \ngn{ namnc4} in |
---|
1254 | the main namelist file continues to serve the restart files. |
---|
1255 | This duplication is unfortunate but appropriate since, if using io\_servers, the domain sizes of |
---|
1256 | the individual files produced by the io\_server processes may be different to those produced by |
---|
1257 | the invidual processing regions and different chunking choices may be desired. |
---|
1258 | |
---|
1259 | % ------------------------------------------------------------------------------------------------------------- |
---|
1260 | % Tracer/Dynamics Trends |
---|
1261 | % ------------------------------------------------------------------------------------------------------------- |
---|
1262 | \section{Tracer/Dynamics trends (\protect\ngn{namtrd})} |
---|
1263 | \label{sec:DIA_trd} |
---|
1264 | |
---|
1265 | %------------------------------------------namtrd---------------------------------------------------- |
---|
1266 | \forfile{../namelists/namtrd} |
---|
1267 | %------------------------------------------------------------------------------------------------------------- |
---|
1268 | |
---|
1269 | Each trend of the dynamics and/or temperature and salinity time evolution equations can be send to |
---|
1270 | \mdl{trddyn} and/or \mdl{trdtra} modules (see TRD directory) just after their computation ($i.e.$ at |
---|
1271 | the end of each $dyn\cdots.F90$ and/or $tra\cdots.F90$ routines). |
---|
1272 | This capability is controlled by options offered in \ngn{namtrd} namelist. |
---|
1273 | Note that the output are done with xIOS, and therefore the \key{IOM} is required. |
---|
1274 | |
---|
1275 | What is done depends on the \ngn{namtrd} logical set to \forcode{.true.}: |
---|
1276 | |
---|
1277 | \begin{description} |
---|
1278 | \item[\np{ln\_glo\_trd}]: at each \np{nn\_trd} time-step a check of the basin averaged properties of |
---|
1279 | the momentum and tracer equations is performed. |
---|
1280 | This also includes a check of $T^2$, $S^2$, $\tfrac{1}{2} (u^2+v2)$, and |
---|
1281 | potential energy time evolution equations properties; |
---|
1282 | \item[\np{ln\_dyn\_trd}]: each 3D trend of the evolution of the two momentum components is output; |
---|
1283 | \item[\np{ln\_dyn\_mxl}]: each 3D trend of the evolution of the two momentum components averaged over |
---|
1284 | the mixed layer is output; |
---|
1285 | \item[\np{ln\_vor\_trd}]: a vertical summation of the moment tendencies is performed, then |
---|
1286 | the curl is computed to obtain the barotropic vorticity tendencies which |
---|
1287 | are output; |
---|
1288 | \item[\np{ln\_KE\_trd}] : each 3D trend of the Kinetic Energy equation is output ; |
---|
1289 | \item[\np{ln\_tra\_trd}]: each 3D trend of the evolution of temperature and salinity is output ; |
---|
1290 | \item[\np{ln\_tra\_mxl}]: each 2D trend of the evolution of temperature and salinity averaged over |
---|
1291 | the mixed layer is output; |
---|
1292 | \end{description} |
---|
1293 | |
---|
1294 | Note that the mixed layer tendency diagnostic can also be used on biogeochemical models via |
---|
1295 | the \key{trdtrc} and \key{trdmld\_trc} CPP keys. |
---|
1296 | |
---|
1297 | \textbf{Note that} in the current version (v3.6), many changes has been introduced but not fully tested. |
---|
1298 | In particular, options associated with \np{ln\_dyn\_mxl}, \np{ln\_vor\_trd}, and \np{ln\_tra\_mxl} are |
---|
1299 | not working, and none of the options have been tested with variable volume ($i.e.$ \key{vvl} defined). |
---|
1300 | |
---|
1301 | % ------------------------------------------------------------------------------------------------------------- |
---|
1302 | % On-line Floats trajectories |
---|
1303 | % ------------------------------------------------------------------------------------------------------------- |
---|
1304 | \section{FLO: On-Line Floats trajectories (\protect\key{floats})} |
---|
1305 | \label{sec:FLO} |
---|
1306 | %--------------------------------------------namflo------------------------------------------------------- |
---|
1307 | \forfile{../namelists/namflo} |
---|
1308 | %-------------------------------------------------------------------------------------------------------------- |
---|
1309 | |
---|
1310 | The on-line computation of floats advected either by the three dimensional velocity field or |
---|
1311 | constraint to remain at a given depth ($w = 0$ in the computation) have been introduced in |
---|
1312 | the system during the CLIPPER project. |
---|
1313 | Options are defined by \ngn{namflo} namelis variables. |
---|
1314 | The algorithm used is based either on the work of \cite{Blanke_Raynaud_JPO97} (default option), or |
---|
1315 | on a $4^th$ Runge-Hutta algorithm (\np{ln\_flork4}\forcode{ = .true.}). |
---|
1316 | Note that the \cite{Blanke_Raynaud_JPO97} algorithm have the advantage of providing trajectories which |
---|
1317 | are consistent with the numeric of the code, so that the trajectories never intercept the bathymetry. |
---|
1318 | |
---|
1319 | \subsubsection{Input data: initial coordinates} |
---|
1320 | |
---|
1321 | Initial coordinates can be given with Ariane Tools convention (IJK coordinates, |
---|
1322 | (\np{ln\_ariane}\forcode{ = .true.}) ) or with longitude and latitude. |
---|
1323 | |
---|
1324 | In case of Ariane convention, input filename is \np{init\_float\_ariane}. |
---|
1325 | Its format is: \\ |
---|
1326 | {\scriptsize \texttt{I J K nisobfl itrash itrash}} |
---|
1327 | |
---|
1328 | \noindent with: |
---|
1329 | |
---|
1330 | - I,J,K : indexes of initial position |
---|
1331 | |
---|
1332 | - nisobfl: 0 for an isobar float, 1 for a float following the w velocity |
---|
1333 | |
---|
1334 | - itrash : set to zero; it is a dummy variable to respect Ariane Tools convention |
---|
1335 | |
---|
1336 | \noindent Example: \\ |
---|
1337 | \noindent {\scriptsize \texttt{ |
---|
1338 | 100.00000 90.00000 -1.50000 1.00000 0.00000 \\ |
---|
1339 | 102.00000 90.00000 -1.50000 1.00000 0.00000 \\ |
---|
1340 | 104.00000 90.00000 -1.50000 1.00000 0.00000 \\ |
---|
1341 | 106.00000 90.00000 -1.50000 1.00000 0.00000 \\ |
---|
1342 | 108.00000 90.00000 -1.50000 1.00000 0.00000}} \\ |
---|
1343 | |
---|
1344 | In the other case (longitude and latitude), input filename is init\_float. |
---|
1345 | Its format is: \\ |
---|
1346 | {\scriptsize \texttt{Long Lat depth nisobfl ngrpfl itrash}} |
---|
1347 | |
---|
1348 | \noindent with: |
---|
1349 | |
---|
1350 | - Long, Lat, depth : Longitude, latitude, depth |
---|
1351 | |
---|
1352 | - nisobfl: 0 for an isobar float, 1 for a float following the w velocity |
---|
1353 | |
---|
1354 | - ngrpfl : number to identify searcher group |
---|
1355 | |
---|
1356 | - itrash :set to 1; it is a dummy variable. |
---|
1357 | |
---|
1358 | \noindent Example: \\ |
---|
1359 | \noindent {\scriptsize \texttt{ |
---|
1360 | 20.0 0.0 0.0 0 1 1 \\ |
---|
1361 | -21.0 0.0 0.0 0 1 1 \\ |
---|
1362 | -22.0 0.0 0.0 0 1 1 \\ |
---|
1363 | -23.0 0.0 0.0 0 1 1 \\ |
---|
1364 | -24.0 0.0 0.0 0 1 1 }} \\ |
---|
1365 | |
---|
1366 | \np{jpnfl} is the total number of floats during the run. |
---|
1367 | When initial positions are read in a restart file (\np{ln\_rstflo}\forcode{ = .true.} ), |
---|
1368 | \np{jpnflnewflo} can be added in the initialization file. |
---|
1369 | |
---|
1370 | \subsubsection{Output data} |
---|
1371 | |
---|
1372 | \np{nn\_writefl} is the frequency of writing in float output file and \np{nn\_stockfl} is |
---|
1373 | the frequency of creation of the float restart file. |
---|
1374 | |
---|
1375 | Output data can be written in ascii files (\np{ln\_flo\_ascii}\forcode{ = .true.}). |
---|
1376 | In that case, output filename is trajec\_float. |
---|
1377 | |
---|
1378 | Another possiblity of writing format is Netcdf (\np{ln\_flo\_ascii}\forcode{ = .false.}). |
---|
1379 | There are 2 possibilities: |
---|
1380 | |
---|
1381 | - if (\key{iomput}) is used, outputs are selected in iodef.xml. |
---|
1382 | Here it is an example of specification to put in files description section: |
---|
1383 | |
---|
1384 | \begin{xmllines} |
---|
1385 | <group id="1d_grid_T" name="auto" description="ocean T grid variables" > } |
---|
1386 | <file id="floats" description="floats variables"> } |
---|
1387 | <field ref="traj_lon" name="floats_longitude" freq_op="86400" />} |
---|
1388 | <field ref="traj_lat" name="floats_latitude" freq_op="86400" />} |
---|
1389 | <field ref="traj_dep" name="floats_depth" freq_op="86400" />} |
---|
1390 | <field ref="traj_temp" name="floats_temperature" freq_op="86400" />} |
---|
1391 | <field ref="traj_salt" name="floats_salinity" freq_op="86400" />} |
---|
1392 | <field ref="traj_dens" name="floats_density" freq_op="86400" />} |
---|
1393 | <field ref="traj_group" name="floats_group" freq_op="86400" />} |
---|
1394 | </file>} |
---|
1395 | </group>} |
---|
1396 | \end{xmllines} |
---|
1397 | |
---|
1398 | - if (\key{iomput}) is not used, a file called \ifile{trajec\_float} will be created by IOIPSL library. |
---|
1399 | |
---|
1400 | See also \href{http://stockage.univ-brest.fr/~grima/Ariane/}{here} the web site describing |
---|
1401 | the off-line use of this marvellous diagnostic tool. |
---|
1402 | |
---|
1403 | % ------------------------------------------------------------------------------------------------------------- |
---|
1404 | % Harmonic analysis of tidal constituents |
---|
1405 | % ------------------------------------------------------------------------------------------------------------- |
---|
1406 | \section{Harmonic analysis of tidal constituents (\protect\key{diaharm}) } |
---|
1407 | \label{sec:DIA_diag_harm} |
---|
1408 | |
---|
1409 | %------------------------------------------namdia_harm---------------------------------------------------- |
---|
1410 | %\forfile{../namelists/namdia_harm} |
---|
1411 | %---------------------------------------------------------------------------------------------------------- |
---|
1412 | |
---|
1413 | A module is available to compute the amplitude and phase of tidal waves. |
---|
1414 | This on-line Harmonic analysis is actived with \key{diaharm}. |
---|
1415 | |
---|
1416 | Some parameters are available in namelist \ngn{namdia\_harm} : |
---|
1417 | |
---|
1418 | - \np{nit000\_han} is the first time step used for harmonic analysis |
---|
1419 | |
---|
1420 | - \np{nitend\_han} is the last time step used for harmonic analysis |
---|
1421 | |
---|
1422 | - \np{nstep\_han} is the time step frequency for harmonic analysis |
---|
1423 | |
---|
1424 | - \np{nb\_ana} is the number of harmonics to analyse |
---|
1425 | |
---|
1426 | - \np{tname} is an array with names of tidal constituents to analyse |
---|
1427 | |
---|
1428 | \np{nit000\_han} and \np{nitend\_han} must be between \np{nit000} and \np{nitend} of the simulation. |
---|
1429 | The restart capability is not implemented. |
---|
1430 | |
---|
1431 | The Harmonic analysis solve the following equation: |
---|
1432 | |
---|
1433 | \[h_{i} - A_{0} + \sum^{nb\_ana}_{j=1}[A_{j}cos(\nu_{j}t_{j}-\phi_{j})] = e_{i}\] |
---|
1434 | |
---|
1435 | With $A_{j}$, $\nu_{j}$, $\phi_{j}$, the amplitude, frequency and phase for each wave and |
---|
1436 | $e_{i}$ the error. |
---|
1437 | $h_{i}$ is the sea level for the time $t_{i}$ and $A_{0}$ is the mean sea level. \\ |
---|
1438 | We can rewrite this equation: |
---|
1439 | |
---|
1440 | \[h_{i} - A_{0} + \sum^{nb\_ana}_{j=1}[C_{j}cos(\nu_{j}t_{j})+S_{j}sin(\nu_{j}t_{j})] = e_{i}\] |
---|
1441 | |
---|
1442 | with $A_{j}=\sqrt{C^{2}_{j}+S^{2}_{j}}$ and $\phi_{j}=arctan(S_{j}/C_{j})$. |
---|
1443 | |
---|
1444 | We obtain in output $C_{j}$ and $S_{j}$ for each tidal wave. |
---|
1445 | |
---|
1446 | % ------------------------------------------------------------------------------------------------------------- |
---|
1447 | % Sections transports |
---|
1448 | % ------------------------------------------------------------------------------------------------------------- |
---|
1449 | \section{Transports across sections (\protect\key{diadct}) } |
---|
1450 | \label{sec:DIA_diag_dct} |
---|
1451 | |
---|
1452 | %------------------------------------------namdct---------------------------------------------------- |
---|
1453 | \forfile{../namelists/namdct} |
---|
1454 | %------------------------------------------------------------------------------------------------------------- |
---|
1455 | |
---|
1456 | A module is available to compute the transport of volume, heat and salt through sections. |
---|
1457 | This diagnostic is actived with \key{diadct}. |
---|
1458 | |
---|
1459 | Each section is defined by the coordinates of its 2 extremities. |
---|
1460 | The pathways between them are contructed using tools which can be found in |
---|
1461 | \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT} |
---|
1462 | and are written in a binary file |
---|
1463 | \texttt{section\_ijglobal.diadct\_ORCA2\_LIM} |
---|
1464 | which is later read in by NEMO to compute on-line transports. |
---|
1465 | |
---|
1466 | The on-line transports module creates three output ascii files: |
---|
1467 | |
---|
1468 | - \texttt{volume\_transport} for volume transports (unit: $10^{6} m^{3} s^{-1}$) |
---|
1469 | |
---|
1470 | - \texttt{heat\_transport} for heat transports (unit: $10^{15} W$) |
---|
1471 | |
---|
1472 | - \texttt{salt\_transport} for salt transports (unit: $10^{9}Kg s^{-1}$) \\ |
---|
1473 | |
---|
1474 | Namelist variables in \ngn{namdct} control how frequently the flows are summed and the time scales over |
---|
1475 | which they are averaged, as well as the level of output for debugging: |
---|
1476 | \np{nn\_dct} : frequency of instantaneous transports computing |
---|
1477 | \np{nn\_dctwri}: frequency of writing ( mean of instantaneous transports ) |
---|
1478 | \np{nn\_debug} : debugging of the section |
---|
1479 | |
---|
1480 | \subsubsection{Creating a binary file containing the pathway of each section} |
---|
1481 | |
---|
1482 | In \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT/run}, |
---|
1483 | the file \textit{ {list\_sections.ascii\_global}} contains a list of all the sections that are to |
---|
1484 | be computed (this list of sections is based on MERSEA project metrics). |
---|
1485 | |
---|
1486 | Another file is available for the GYRE configuration (\texttt{ {list\_sections.ascii\_GYRE}}). |
---|
1487 | |
---|
1488 | Each section is defined by: \\ |
---|
1489 | \noindent {\scriptsize \texttt{long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name}} \\ |
---|
1490 | with: |
---|
1491 | |
---|
1492 | - \texttt{long1 lat1}, coordinates of the first extremity of the section; |
---|
1493 | |
---|
1494 | - \texttt{long2 lat2}, coordinates of the second extremity of the section; |
---|
1495 | |
---|
1496 | - \texttt{nclass} the number of bounds of your classes (e.g. 3 bounds for 2 classes); |
---|
1497 | |
---|
1498 | - \texttt{okstrpond} to compute heat and salt transports, \texttt{nostrpond} if no; |
---|
1499 | |
---|
1500 | - \texttt{ice} to compute surface and volume ice transports, \texttt{noice} if no. \\ |
---|
1501 | |
---|
1502 | \noindent The results of the computing of transports, and the directions of positive and |
---|
1503 | negative flow do not depend on the order of the 2 extremities in this file. \\ |
---|
1504 | |
---|
1505 | \noindent If nclass $\neq$ 0,the next lines contain the class type and the nclass bounds: \\ |
---|
1506 | {\scriptsize \texttt{ |
---|
1507 | long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name \\ |
---|
1508 | classtype \\ |
---|
1509 | zbound1 \\ |
---|
1510 | zbound2 \\ |
---|
1511 | . \\ |
---|
1512 | . \\ |
---|
1513 | nclass-1 \\ |
---|
1514 | nclass}} |
---|
1515 | |
---|
1516 | \noindent where \texttt{classtype} can be: |
---|
1517 | |
---|
1518 | - \texttt{zsal} for salinity classes |
---|
1519 | |
---|
1520 | - \texttt{ztem} for temperature classes |
---|
1521 | |
---|
1522 | - \texttt{zlay} for depth classes |
---|
1523 | |
---|
1524 | - \texttt{zsigi} for insitu density classes |
---|
1525 | |
---|
1526 | - \texttt{zsigp} for potential density classes \\ |
---|
1527 | |
---|
1528 | The script \texttt{job.ksh} computes the pathway for each section and |
---|
1529 | creates a binary file \texttt{section\_ijglobal.diadct\_ORCA2\_LIM} which is read by NEMO. \\ |
---|
1530 | |
---|
1531 | It is possible to use this tools for new configuations: \texttt{job.ksh} has to be updated with |
---|
1532 | the coordinates file name and path. \\ |
---|
1533 | |
---|
1534 | Examples of two sections, the ACC\_Drake\_Passage with no classes, and the ATL\_Cuba\_Florida with |
---|
1535 | 4 temperature clases (5 class bounds), are shown: \\ |
---|
1536 | \noindent {\scriptsize \texttt{ |
---|
1537 | -68. -54.5 -60. -64.7 00 okstrpond noice ACC\_Drake\_Passage \\ |
---|
1538 | -80.5 22.5 -80.5 25.5 05 nostrpond noice ATL\_Cuba\_Florida \\ |
---|
1539 | ztem \\ |
---|
1540 | -2.0 \\ |
---|
1541 | 4.5 \\ |
---|
1542 | 7.0 \\ |
---|
1543 | 12.0 \\ |
---|
1544 | 40.0}} |
---|
1545 | |
---|
1546 | \subsubsection{To read the output files} |
---|
1547 | |
---|
1548 | The output format is: \\ |
---|
1549 | {\scriptsize \texttt{ |
---|
1550 | date, time-step number, section number, \\ |
---|
1551 | section name, section slope coefficient, class number, \\ |
---|
1552 | class name, class bound 1 , classe bound2, \\ |
---|
1553 | transport\_direction1, transport\_direction2, \\ |
---|
1554 | transport\_total}} \\ |
---|
1555 | |
---|
1556 | For sections with classes, the first \texttt{nclass-1} lines correspond to the transport for |
---|
1557 | each class and the last line corresponds to the total transport summed over all classes. |
---|
1558 | For sections with no classes, class number \texttt{1} corresponds to \texttt{total class} and |
---|
1559 | this class is called \texttt{N}, meaning \texttt{none}. |
---|
1560 | |
---|
1561 | - \texttt{transport\_direction1} is the positive part of the transport ($\geq$ 0). |
---|
1562 | |
---|
1563 | - \texttt{transport\_direction2} is the negative part of the transport ($\leq$ 0). \\ |
---|
1564 | |
---|
1565 | \noindent The \texttt{section slope coefficient} gives information about the significance of |
---|
1566 | transports signs and direction: \\ |
---|
1567 | |
---|
1568 | \begin{table} \scriptsize |
---|
1569 | \begin{tabular}{|l|l|l|l|l|} \hline |
---|
1570 | section slope coefficient & section type & direction 1 & direction 2 & total transport |
---|
1571 | \\ \hline |
---|
1572 | 0. & horizontal & northward & southward & postive: northward |
---|
1573 | \\ \hline |
---|
1574 | 1000. & vertical & eastward & westward & postive: eastward |
---|
1575 | \\ \hline |
---|
1576 | \texttt{$\neq$ 0, $\neq$ 1000.} & diagonal & eastward & westward & postive: eastward |
---|
1577 | \\ \hline |
---|
1578 | \end{tabular} |
---|
1579 | \end{table} |
---|
1580 | |
---|
1581 | % ================================================================ |
---|
1582 | % Steric effect in sea surface height |
---|
1583 | % ================================================================ |
---|
1584 | \section{Diagnosing the steric effect in sea surface height} |
---|
1585 | \label{sec:DIA_steric} |
---|
1586 | |
---|
1587 | |
---|
1588 | Changes in steric sea level are caused when changes in the density of the water column imply an |
---|
1589 | expansion or contraction of the column. |
---|
1590 | It is essentially produced through surface heating/cooling and to a lesser extent through |
---|
1591 | non-linear effects of the equation of state (cabbeling, thermobaricity...). |
---|
1592 | Non-Boussinesq models contain all ocean effects within the ocean acting on the sea level. |
---|
1593 | In particular, they include the steric effect. |
---|
1594 | In contrast, Boussinesq models, such as \NEMO, conserve volume, rather than mass, |
---|
1595 | and so do not properly represent expansion or contraction. |
---|
1596 | The steric effect is therefore not explicitely represented. |
---|
1597 | This approximation does not represent a serious error with respect to the flow field calculated by |
---|
1598 | the model \citep{Greatbatch_JGR94}, but extra attention is required when investigating sea level, |
---|
1599 | as steric changes are an important contribution to local changes in sea level on seasonal and |
---|
1600 | climatic time scales. |
---|
1601 | This is especially true for investigation into sea level rise due to global warming. |
---|
1602 | |
---|
1603 | Fortunately, the steric contribution to the sea level consists of a spatially uniform component that |
---|
1604 | can be diagnosed by considering the mass budget of the world ocean \citep{Greatbatch_JGR94}. |
---|
1605 | In order to better understand how global mean sea level evolves and thus how the steric sea level can |
---|
1606 | be diagnosed, we compare, in the following, the non-Boussinesq and Boussinesq cases. |
---|
1607 | |
---|
1608 | Let denote |
---|
1609 | $\mathcal{M}$ the total mass of liquid seawater ($\mathcal{M} = \int_D \rho dv$), |
---|
1610 | $\mathcal{V}$ the total volume of seawater ($\mathcal{V} = \int_D dv$), |
---|
1611 | $\mathcal{A}$ the total surface of the ocean ($\mathcal{A} = \int_S ds$), |
---|
1612 | $\bar{\rho}$ the global mean seawater (\textit{in situ}) density |
---|
1613 | ($\bar{\rho} = 1/\mathcal{V} \int_D \rho \,dv$), and |
---|
1614 | $\bar{\eta}$ the global mean sea level |
---|
1615 | ($\bar{\eta} = 1/\mathcal{A} \int_S \eta \,ds$). |
---|
1616 | |
---|
1617 | A non-Boussinesq fluid conserves mass. It satisfies the following relations: |
---|
1618 | |
---|
1619 | \[ \begin{split} |
---|
1620 | \mathcal{M} &= \mathcal{V} \;\bar{\rho} \\ |
---|
1621 | \mathcal{V} &= \mathcal{A} \;\bar{\eta} |
---|
1622 | \end{split} \label{eq:MV_nBq} |
---|
1623 | \] |
---|
1624 | |
---|
1625 | Temporal changes in total mass is obtained from the density conservation equation : |
---|
1626 | |
---|
1627 | \[ \frac{1}{e_3} \partial_t ( e_3\,\rho) + \nabla( \rho \, \textbf{U} ) |
---|
1628 | = \left. \frac{\textit{emp}}{e_3}\right|_\textit{surface} |
---|
1629 | \label{eq:Co_nBq} \] |
---|
1630 | |
---|
1631 | where $\rho$ is the \textit{in situ} density, and \textit{emp} the surface mass |
---|
1632 | exchanges with the other media of the Earth system (atmosphere, sea-ice, land). |
---|
1633 | Its global averaged leads to the total mass change |
---|
1634 | |
---|
1635 | \[ \partial_t \mathcal{M} = \mathcal{A} \;\overline{\textit{emp}} |
---|
1636 | \label{eq:Mass_nBq} \] |
---|
1637 | |
---|
1638 | where $\overline{\textit{emp}} = \int_S \textit{emp}\,ds$ is the net mass flux through the ocean surface. |
---|
1639 | Bringing \autoref{eq:Mass_nBq} and the time derivative of \autoref{eq:MV_nBq} together leads to |
---|
1640 | the evolution equation of the mean sea level |
---|
1641 | |
---|
1642 | \[ \partial_t \bar{\eta} = \frac{\overline{\textit{emp}}}{ \bar{\rho}} |
---|
1643 | - \frac{\mathcal{V}}{\mathcal{A}} \;\frac{\partial_t \bar{\rho} }{\bar{\rho}} |
---|
1644 | \label{eq:ssh_nBq} \] |
---|
1645 | |
---|
1646 | The first term in equation \autoref{eq:ssh_nBq} alters sea level by adding or |
---|
1647 | subtracting mass from the ocean. |
---|
1648 | The second term arises from temporal changes in the global mean density; $i.e.$ from steric effects. |
---|
1649 | |
---|
1650 | In a Boussinesq fluid, $\rho$ is replaced by $\rho_o$ in all the equation except when |
---|
1651 | $\rho$ appears multiplied by the gravity ($i.e.$ in the hydrostatic balance of the primitive Equations). |
---|
1652 | In particular, the mass conservation equation, \autoref{eq:Co_nBq}, degenerates into |
---|
1653 | the incompressibility equation: |
---|
1654 | |
---|
1655 | \[ \frac{1}{e_3} \partial_t ( e_3 ) + \nabla( \textbf{U} ) |
---|
1656 | = \left. \frac{\textit{emp}}{\rho_o \,e_3}\right|_ \textit{surface} |
---|
1657 | \label{eq:Co_Bq} \] |
---|
1658 | |
---|
1659 | and the global average of this equation now gives the temporal change of the total volume, |
---|
1660 | |
---|
1661 | \[ \partial_t \mathcal{V} = \mathcal{A} \;\frac{\overline{\textit{emp}}}{\rho_o} |
---|
1662 | \label{eq:V_Bq} \] |
---|
1663 | |
---|
1664 | Only the volume is conserved, not mass, or, more precisely, the mass which is conserved is |
---|
1665 | the Boussinesq mass, $\mathcal{M}_o = \rho_o \mathcal{V}$. |
---|
1666 | The total volume (or equivalently the global mean sea level) is altered only by net volume fluxes across |
---|
1667 | the ocean surface, not by changes in mean mass of the ocean: the steric effect is missing in |
---|
1668 | a Boussinesq fluid. |
---|
1669 | |
---|
1670 | Nevertheless, following \citep{Greatbatch_JGR94}, the steric effect on the volume can be diagnosed by |
---|
1671 | considering the mass budget of the ocean. |
---|
1672 | The apparent changes in $\mathcal{M}$, mass of the ocean, which are not induced by |
---|
1673 | surface mass flux must be compensated by a spatially uniform change in the mean sea level due to |
---|
1674 | expansion/contraction of the ocean \citep{Greatbatch_JGR94}. |
---|
1675 | In others words, the Boussinesq mass, $\mathcal{M}_o$, can be related to $\mathcal{M}$, |
---|
1676 | the total mass of the ocean seen by the Boussinesq model, via the steric contribution to the sea level, |
---|
1677 | $\eta_s$, a spatially uniform variable, as follows: |
---|
1678 | |
---|
1679 | \[ \mathcal{M}_o = \mathcal{M} + \rho_o \,\eta_s \,\mathcal{A} |
---|
1680 | \label{eq:M_Bq} \] |
---|
1681 | |
---|
1682 | Any change in $\mathcal{M}$ which cannot be explained by the net mass flux through |
---|
1683 | the ocean surface is converted into a mean change in sea level. |
---|
1684 | Introducing the total density anomaly, $\mathcal{D}= \int_D d_a \,dv$, where |
---|
1685 | $d_a = (\rho -\rho_o ) / \rho_o$ is the density anomaly used in \NEMO (cf. \autoref{subsec:TRA_eos}) in |
---|
1686 | \autoref{eq:M_Bq} leads to a very simple form for the steric height: |
---|
1687 | |
---|
1688 | \[ \eta_s = - \frac{1}{\mathcal{A}} \mathcal{D} |
---|
1689 | \label{eq:steric_Bq} \] |
---|
1690 | |
---|
1691 | The above formulation of the steric height of a Boussinesq ocean requires four remarks. |
---|
1692 | First, one can be tempted to define $\rho_o$ as the initial value of $\mathcal{M}/\mathcal{V}$, |
---|
1693 | $i.e.$ set $\mathcal{D}_{t=0}=0$, so that the initial steric height is zero. |
---|
1694 | We do not recommend that. |
---|
1695 | Indeed, in this case $\rho_o$ depends on the initial state of the ocean. |
---|
1696 | Since $\rho_o$ has a direct effect on the dynamics of the ocean (it appears in |
---|
1697 | the pressure gradient term of the momentum equation) it is definitively not a good idea when |
---|
1698 | inter-comparing experiments. |
---|
1699 | We better recommend to fixe once for all $\rho_o$ to $1035\;Kg\,m^{-3}$. |
---|
1700 | This value is a sensible choice for the reference density used in a Boussinesq ocean climate model since, |
---|
1701 | with the exception of only a small percentage of the ocean, density in the World Ocean varies by |
---|
1702 | no more than 2$\%$ from this value (\cite{Gill1982}, page 47). |
---|
1703 | |
---|
1704 | Second, we have assumed here that the total ocean surface, $\mathcal{A}$, does not change when |
---|
1705 | the sea level is changing as it is the case in all global ocean GCMs |
---|
1706 | (wetting and drying of grid point is not allowed). |
---|
1707 | |
---|
1708 | Third, the discretisation of \autoref{eq:steric_Bq} depends on the type of |
---|
1709 | free surface which is considered. |
---|
1710 | In the non linear free surface case, $i.e.$ \key{vvl} defined, it is given by |
---|
1711 | |
---|
1712 | \[ \eta_s = - \frac{ \sum_{i,\,j,\,k} d_a\; e_{1t} e_{2t} e_{3t} } |
---|
1713 | { \sum_{i,\,j,\,k} e_{1t} e_{2t} e_{3t} } |
---|
1714 | \label{eq:discrete_steric_Bq_nfs} \] |
---|
1715 | |
---|
1716 | whereas in the linear free surface, the volume above the \textit{z=0} surface must be explicitly |
---|
1717 | taken into account to better approximate the total ocean mass and thus the steric sea level: |
---|
1718 | |
---|
1719 | \[ \eta_s = - \frac{ \sum_{i,\,j,\,k} d_a\; e_{1t}e_{2t}e_{3t} + \sum_{i,\,j} d_a\; e_{1t}e_{2t} \eta } |
---|
1720 | { \sum_{i,\,j,\,k} e_{1t}e_{2t}e_{3t} + \sum_{i,\,j} e_{1t}e_{2t} \eta } |
---|
1721 | \label{eq:discrete_steric_Bq_fs} \] |
---|
1722 | |
---|
1723 | The fourth and last remark concerns the effective sea level and the presence of sea-ice. |
---|
1724 | In the real ocean, sea ice (and snow above it) depresses the liquid seawater through its mass loading. |
---|
1725 | This depression is a result of the mass of sea ice/snow system acting on the liquid ocean. |
---|
1726 | There is, however, no dynamical effect associated with these depressions in the liquid ocean sea level, |
---|
1727 | so that there are no associated ocean currents. |
---|
1728 | Hence, the dynamically relevant sea level is the effective sea level, $i.e.$ the sea level as if |
---|
1729 | sea ice (and snow) were converted to liquid seawater \citep{Campin_al_OM08}. |
---|
1730 | However, in the current version of \NEMO the sea-ice is levitating above the ocean without |
---|
1731 | mass exchanges between ice and ocean. |
---|
1732 | Therefore the model effective sea level is always given by $\eta + \eta_s$, |
---|
1733 | whether or not there is sea ice present. |
---|
1734 | |
---|
1735 | In AR5 outputs, the thermosteric sea level is demanded. |
---|
1736 | It is steric sea level due to changes in ocean density arising just from changes in temperature. |
---|
1737 | It is given by: |
---|
1738 | |
---|
1739 | \[ \eta_s = - \frac{1}{\mathcal{A}} \int_D d_a(T,S_o,p_o) \,dv |
---|
1740 | \label{eq:thermosteric_Bq} \] |
---|
1741 | |
---|
1742 | where $S_o$ and $p_o$ are the initial salinity and pressure, respectively. |
---|
1743 | |
---|
1744 | Both steric and thermosteric sea level are computed in \mdl{diaar5} which needs |
---|
1745 | the \key{diaar5} defined to be called. |
---|
1746 | |
---|
1747 | % ------------------------------------------------------------------------------------------------------------- |
---|
1748 | % Other Diagnostics |
---|
1749 | % ------------------------------------------------------------------------------------------------------------- |
---|
1750 | \section{Other diagnostics (\protect\key{diahth}, \protect\key{diaar5})} |
---|
1751 | \label{sec:DIA_diag_others} |
---|
1752 | |
---|
1753 | Aside from the standard model variables, other diagnostics can be computed on-line. |
---|
1754 | The available ready-to-add diagnostics modules can be found in directory DIA. |
---|
1755 | |
---|
1756 | \subsection{Depth of various quantities (\protect\mdl{diahth})} |
---|
1757 | |
---|
1758 | Among the available diagnostics the following ones are obtained when defining the \key{diahth} CPP key: |
---|
1759 | |
---|
1760 | - the mixed layer depth (based on a density criterion \citep{de_Boyer_Montegut_al_JGR04}) (\mdl{diahth}) |
---|
1761 | |
---|
1762 | - the turbocline depth (based on a turbulent mixing coefficient criterion) (\mdl{diahth}) |
---|
1763 | |
---|
1764 | - the depth of the 20\deg C isotherm (\mdl{diahth}) |
---|
1765 | |
---|
1766 | - the depth of the thermocline (maximum of the vertical temperature gradient) (\mdl{diahth}) |
---|
1767 | |
---|
1768 | % ----------------------------------------------------------- |
---|
1769 | % Poleward heat and salt transports |
---|
1770 | % ----------------------------------------------------------- |
---|
1771 | |
---|
1772 | \subsection{Poleward heat and salt transports (\protect\mdl{diaptr})} |
---|
1773 | |
---|
1774 | %------------------------------------------namptr----------------------------------------- |
---|
1775 | \forfile{../namelists/namptr} |
---|
1776 | %----------------------------------------------------------------------------------------- |
---|
1777 | |
---|
1778 | The poleward heat and salt transports, their advective and diffusive component, and |
---|
1779 | the meriodional stream function can be computed on-line in \mdl{diaptr} \np{ln\_diaptr} to true |
---|
1780 | (see the \textit{\ngn{namptr} } namelist below). |
---|
1781 | When \np{ln\_subbas}\forcode{ = .true.}, transports and stream function are computed for the Atlantic, |
---|
1782 | Indian, Pacific and Indo-Pacific Oceans (defined north of 30\deg S) as well as for the World Ocean. |
---|
1783 | The sub-basin decomposition requires an input file (\ifile{subbasins}) which contains |
---|
1784 | three 2D mask arrays, the Indo-Pacific mask been deduced from the sum of the Indian and |
---|
1785 | Pacific mask (\autoref{fig:mask_subasins}). |
---|
1786 | |
---|
1787 | %>>>>>>>>>>>>>>>>>>>>>>>>>>>> |
---|
1788 | \begin{figure}[!t] \begin{center} |
---|
1789 | \includegraphics[width=1.0\textwidth]{Fig_mask_subasins} |
---|
1790 | \caption{ \protect\label{fig:mask_subasins} |
---|
1791 | Decomposition of the World Ocean (here ORCA2) into sub-basin used in to compute the heat and |
---|
1792 | salt transports as well as the meridional stream-function: Atlantic basin (red), |
---|
1793 | Pacific basin (green), Indian basin (bleue), Indo-Pacific basin (bleue+green). |
---|
1794 | Note that semi-enclosed seas (Red, Med and Baltic seas) as well as Hudson Bay are removed from |
---|
1795 | the sub-basins. Note also that the Arctic Ocean has been split into Atlantic and |
---|
1796 | Pacific basins along the North fold line.} |
---|
1797 | \end{center} \end{figure} |
---|
1798 | %>>>>>>>>>>>>>>>>>>>>>>>>>>>> |
---|
1799 | |
---|
1800 | % ----------------------------------------------------------- |
---|
1801 | % CMIP specific diagnostics |
---|
1802 | % ----------------------------------------------------------- |
---|
1803 | \subsection{CMIP specific diagnostics (\protect\mdl{diaar5})} |
---|
1804 | |
---|
1805 | A series of diagnostics has been added in the \mdl{diaar5}. |
---|
1806 | They corresponds to outputs that are required for AR5 simulations (CMIP5) |
---|
1807 | (see also \autoref{sec:DIA_steric} for one of them). |
---|
1808 | Activating those outputs requires to define the \key{diaar5} CPP key. |
---|
1809 | |
---|
1810 | % ----------------------------------------------------------- |
---|
1811 | % 25 hour mean and hourly Surface, Mid and Bed |
---|
1812 | % ----------------------------------------------------------- |
---|
1813 | \subsection{25 hour mean output for tidal models} |
---|
1814 | |
---|
1815 | %------------------------------------------nam_dia25h------------------------------------- |
---|
1816 | \forfile{../namelists/nam_dia25h} |
---|
1817 | %----------------------------------------------------------------------------------------- |
---|
1818 | |
---|
1819 | A module is available to compute a crudely detided M2 signal by obtaining a 25 hour mean. |
---|
1820 | The 25 hour mean is available for daily runs by summing up the 25 hourly instantananeous hourly values from |
---|
1821 | midnight at the start of the day to midight at the day end. |
---|
1822 | This diagnostic is actived with the logical $ln\_dia25h$ |
---|
1823 | |
---|
1824 | % ----------------------------------------------------------- |
---|
1825 | % Top Middle and Bed hourly output |
---|
1826 | % ----------------------------------------------------------- |
---|
1827 | \subsection{Top middle and bed hourly output} |
---|
1828 | |
---|
1829 | %------------------------------------------nam_diatmb----------------------------------------------------- |
---|
1830 | \forfile{../namelists/nam_diatmb} |
---|
1831 | %---------------------------------------------------------------------------------------------------------- |
---|
1832 | |
---|
1833 | A module is available to output the surface (top), mid water and bed diagnostics of a set of |
---|
1834 | standard variables. |
---|
1835 | This can be a useful diagnostic when hourly or sub-hourly output is required in |
---|
1836 | high resolution tidal outputs. |
---|
1837 | The tidal signal is retained but the overall data usage is cut to just three vertical levels. |
---|
1838 | Also the bottom level is calculated for each cell. |
---|
1839 | This diagnostic is actived with the logical $ln\_diatmb$ |
---|
1840 | |
---|
1841 | % ----------------------------------------------------------- |
---|
1842 | % Courant numbers |
---|
1843 | % ----------------------------------------------------------- |
---|
1844 | \subsection{Courant numbers} |
---|
1845 | |
---|
1846 | Courant numbers provide a theoretical indication of the model's numerical stability. |
---|
1847 | The advective Courant numbers can be calculated according to |
---|
1848 | |
---|
1849 | \[ C_u = |u|\frac{\rdt}{e_{1u}}, \quad C_v = |v|\frac{\rdt}{e_{2v}}, \quad C_w = |w|\frac{\rdt}{e_{3w}} |
---|
1850 | \label{eq:CFL} \] |
---|
1851 | |
---|
1852 | in the zonal, meridional and vertical directions respectively. |
---|
1853 | The vertical component is included although it is not strictly valid as the vertical velocity is |
---|
1854 | calculated from the continuity equation rather than as a prognostic variable. |
---|
1855 | Physically this represents the rate at which information is propogated across a grid cell. |
---|
1856 | Values greater than 1 indicate that information is propagated across more than one grid cell in |
---|
1857 | a single time step. |
---|
1858 | |
---|
1859 | The variables can be activated by setting the \np{nn\_diacfl} namelist parameter to 1 in |
---|
1860 | the \ngn{namctl} namelist. |
---|
1861 | The diagnostics will be written out to an ascii file named cfl\_diagnostics.ascii. |
---|
1862 | In this file the maximum value of $C_u$, $C_v$, and $C_w$ are printed at each timestep along with |
---|
1863 | the coordinates of where the maximum value occurs. |
---|
1864 | At the end of the model run the maximum value of $C_u$, $C_v$, and $C_w$ for the whole model run is |
---|
1865 | printed along with the coordinates of each. |
---|
1866 | The maximum values from the run are also copied to the ocean.output file. |
---|
1867 | |
---|
1868 | % ================================================================ |
---|
1869 | |
---|
1870 | \end{document} |
---|