source: XIOS/trunk/doc/inputs/user/Grid.lyx @ 1533

Last change on this file since 1533 was 1084, checked in by mhnguyen, 5 years ago

Update user guide and reference guide

File size: 11.4 KB
Line 
1#LyX 2.2 created this file. For more info see http://www.lyx.org/
2\lyxformat 508
3\begin_document
4\begin_header
5\save_transient_properties true
6\origin unavailable
7\textclass book
8\use_default_options true
9\master ../../XIOS_user_guide.lyx
10\maintain_unincluded_children false
11\language english
12\language_package default
13\inputencoding auto
14\fontencoding global
15\font_roman "default" "default"
16\font_sans "default" "default"
17\font_typewriter "default" "default"
18\font_math "auto" "auto"
19\font_default_family default
20\use_non_tex_fonts false
21\font_sc false
22\font_osf false
23\font_sf_scale 100 100
24\font_tt_scale 100 100
25\graphics default
26\default_output_format default
27\output_sync 0
28\bibtex_command default
29\index_command default
30\float_placement !tph
31\paperfontsize default
32\spacing single
33\use_hyperref false
34\papersize a4paper
35\use_geometry false
36\use_package amsmath 1
37\use_package amssymb 1
38\use_package cancel 1
39\use_package esint 1
40\use_package mathdots 1
41\use_package mathtools 1
42\use_package mhchem 1
43\use_package stackrel 1
44\use_package stmaryrd 1
45\use_package undertilde 1
46\cite_engine basic
47\cite_engine_type default
48\biblio_style plain
49\use_bibtopic false
50\use_indices false
51\paperorientation portrait
52\suppress_date false
53\justification true
54\use_refstyle 1
55\index Index
56\shortcut idx
57\color #008000
58\end_index
59\secnumdepth 3
60\tocdepth 3
61\paragraph_separation indent
62\paragraph_indentation default
63\quotes_language english
64\papercolumns 1
65\papersides 1
66\paperpagestyle default
67\tracking_changes false
68\output_changes false
69\html_math_output 0
70\html_css_as_file 0
71\html_be_strict false
72\end_header
73
74\begin_body
75
76\begin_layout Chapter
77Grid
78\end_layout
79
80\begin_layout Section
81Overview
82\end_layout
83
84\begin_layout Standard
85Grid plays an important role in XIOS.
86 Same as Field, Grid is one of the basic elements in XIOS, which should
87 be well defined, not only in the configuration file but also in the FORTRAN
88 code.
89 Because, until now, XIOS has mainly served for writing NetCDF data format,
90 most of its components are inspired from NetCDF Data Model, and Grid is
91 not an exception.
92 Grid is a concept describing dimensions that contain the axes of the data
93 arrays.
94 Moreover, Grid always consists of an unlimited dimension whose length can
95 be expanded at any time.
96 Other dimensions can be described with Domain and Axis.
97 The followings describe how to make use of Grid in XIOS.
98 Details of its attributes and operations can be found in XIOS reference
99 guide.
100\end_layout
101
102\begin_layout Section
103Working with configuration file
104\end_layout
105
106\begin_layout Standard
107As mentioned above, a grid contains the axes of the data arrays, which are
108 characterized by Domain and/or Axis.
109 A domain is composed of a 2-dimension array, meanwhile an axis is, as its
110 name, an 1-dimension array.
111 
112\end_layout
113
114\begin_layout Standard
115Like other components of XIOS, a grid is defined inside its definition part
116 with the tag
117\series bold
118\color black
119grid_definition
120\series default
121\color inherit
122
123\begin_inset listings
124lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
125inline false
126status collapsed
127
128\begin_layout Plain Layout
129
130 <grid_definition>     
131\end_layout
132
133\begin_layout Plain Layout
134
135   <grid_group id="gridGroup">       
136\end_layout
137
138\begin_layout Plain Layout
139
140     <grid id="grid_A">         
141\end_layout
142
143\begin_layout Plain Layout
144
145       <domain domain_ref="domain_A" />
146\end_layout
147
148\begin_layout Plain Layout
149
150       <axis axis_ref="axis_C" />
151\end_layout
152
153\begin_layout Plain Layout
154
155     </grid>
156\end_layout
157
158\begin_layout Plain Layout
159
160         <grid id="grid_Axis">
161\end_layout
162
163\begin_layout Plain Layout
164
165           <axis axis_ref="axis_D" />
166\end_layout
167
168\begin_layout Plain Layout
169
170         </grid>
171\end_layout
172
173\begin_layout Plain Layout
174
175         <grid id="grid_All_Axis">
176\end_layout
177
178\begin_layout Plain Layout
179
180           <axis axis_ref="axis_A" />
181\end_layout
182
183\begin_layout Plain Layout
184
185       <axis axis_ref="axis_B" />
186\end_layout
187
188\begin_layout Plain Layout
189
190           <axis axis_ref="axis_C" />
191\end_layout
192
193\begin_layout Plain Layout
194
195         </grid>
196\end_layout
197
198\begin_layout Plain Layout
199
200   </grid_group>
201\end_layout
202
203\begin_layout Plain Layout
204
205 </grid_definition>
206\end_layout
207
208\end_inset
209
210
211\end_layout
212
213\begin_layout Standard
214As XIOS supports netCDF-4/HDF5, it allows user to gather several grids into
215 groups to better organize data.
216 Very often, grids are grouped, basing on the dimensions that they describe.
217 However, there is not a limit for user to group out the grids.
218 The more important thing than grid_group is grid.
219 A grid is defined with the tag
220\series bold
221\color black
222grid.
223 
224\end_layout
225
226\begin_layout Standard
227While it is not crucial for a grid group not to have an identification specified
228 by attribute id, a grid must be assigned an id to become useful.
229 Unlike grid group is a way of hierarchically organizing related grid only,
230 a grid itself is referenced by fields with its id.
231 Without the id, a grid can not be made used of by a field.
232 Id is a string of anything but there is one thing to remember: id of a
233 grid as well as id of any component in XIOS are
234\shape italic
235\color black
236unique
237\shape default
238\color inherit
239 among this kind of components.
240 If several grids use same Id, they all represent only one grid.
241\end_layout
242
243\begin_layout Standard
244A grid is defined by domain(s) and axis.
245 A domain represents two-dimension data while an axis serves as one-dimension
246 data.
247 They are defined inside the grid definition.
248 One of the convenient and effective way to reuse the definitions in XIOS
249 is to take advantage of attribute *_ref.
250 On using *_ref, the referencing component has all attributes from its reference
251d one.
252 As the example below, grid with id
253\begin_inset Quotes eld
254\end_inset
255
256grid_A
257\begin_inset Quotes erd
258\end_inset
259
260 (from now one, called grid_A), is composed of one domain whose attributes
261 derived directly from another one-domain_A, and one axis whose attributes
262 are taken from axis axis_C, which are defined previously.
263\end_layout
264
265\begin_layout Standard
266\begin_inset listings
267lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
268inline false
269status open
270
271\begin_layout Plain Layout
272
273<domain id="domain_A />
274\end_layout
275
276\begin_layout Plain Layout
277
278<axis id="axis_A" />
279\end_layout
280
281\begin_layout Plain Layout
282
283\end_layout
284
285\begin_layout Plain Layout
286
287<grid id="grid_A">          
288\end_layout
289
290\begin_layout Plain Layout
291
292   <domain domain_ref="domain_A" />
293\end_layout
294
295\begin_layout Plain Layout
296
297   <axis axis_ref="axis_C" />
298\end_layout
299
300\begin_layout Plain Layout
301
302 </grid>
303\end_layout
304
305\end_inset
306
307
308\end_layout
309
310\begin_layout Standard
311The *_ref can only used to reference to a already defined element (e.g domain,
312 axis, grid, etc).
313 If these *_ref have not been defined yet, there will be a runtime error.
314\end_layout
315
316\begin_layout Standard
317Details about domain and axis can be found in other sections but there is
318 one thing to bear in mind: A domain represents two-dimension data and it
319 also contains several special information: longitude, latitude, bound,
320 etc.
321 For the meteorological mind, domain indicates a surface with latitude and
322 longitude, whereas axis represents a vertical level.
323 
324\end_layout
325
326\begin_layout Standard
327In general cases, there is only a need of writing some multidimensional
328 data to a netCDF without any specific information, then comes the following
329 definition of grid.
330\end_layout
331
332\begin_layout Standard
333\begin_inset listings
334lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
335inline false
336status open
337
338\begin_layout Plain Layout
339
340<grid id="grid_All_Axis">
341\end_layout
342
343\begin_layout Plain Layout
344
345  <axis axis_ref="axis_A" />
346\end_layout
347
348\begin_layout Plain Layout
349
350  <axis axis_ref="axis_B" />
351\end_layout
352
353\begin_layout Plain Layout
354
355  <axis axis_ref="axis_C" />
356\end_layout
357
358\begin_layout Plain Layout
359
360</grid>
361\end_layout
362
363\end_inset
364
365
366\end_layout
367
368\begin_layout Standard
369The grid_All_Axis is similar to grid_A, but with three dimensions defined
370 by 3 axis that can be described in any way on demand of user.
371 For example, the axis_A and the axis_B can have corresponding name latitude
372 and longitude to characterize a two-dimension surface with latitude and
373 longitude.
374\end_layout
375
376\begin_layout Standard
377Very often, one dimensional data needs writing to netCDF, it can be easily
378 done with the following XML code
379\end_layout
380
381\begin_layout Standard
382\begin_inset listings
383lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
384inline false
385status open
386
387\begin_layout Plain Layout
388
389 <grid id="grid_Axis">
390\end_layout
391
392\begin_layout Plain Layout
393
394   <axis axis_ref="axis_D" />
395\end_layout
396
397\begin_layout Plain Layout
398
399 </grid>
400\end_layout
401
402\end_inset
403
404
405\end_layout
406
407\begin_layout Standard
408As it is discussed more details in the next section, but remember that even
409 the non-distributed one dimensional data can be well processed by XIOS.
410 
411\end_layout
412
413\begin_layout Standard
414As mentioned above, grid includes by default one unlimited dimension which
415 is often used as time step axis.
416 In order to write only time step to netCDF, XIOS provides a special way
417 to do: scalar grid - a grid composed of a scalar
418\end_layout
419
420\begin_layout Standard
421\begin_inset listings
422lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
423inline false
424status open
425
426\begin_layout Plain Layout
427
428<grid id="grid_TimeStep"> 
429\end_layout
430
431\begin_layout Plain Layout
432
433  <scalar id="scalar" />
434\end_layout
435
436\begin_layout Plain Layout
437
438 </grid>
439\end_layout
440
441\end_inset
442
443
444\end_layout
445
446\begin_layout Standard
447∆The order of domain and/or in grid definition decides order of data written
448 to netCDF: data on domain or axis appearing firstly in grid definition
449 will vary the most.
450 For example, on using ncdump command on netCDF which contains data written
451 on the grid_A .
452\end_layout
453
454\begin_layout Standard
455\begin_inset listings
456lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
457inline false
458status open
459
460\begin_layout Plain Layout
461
462 float field_A(time_counter, axis_A, y, x) ;
463\end_layout
464
465\begin_layout Plain Layout
466
467        field_A:online_operation = "average" ;
468\end_layout
469
470\begin_layout Plain Layout
471
472        field_A:interval_operation = "3600s" ;
473\end_layout
474
475\begin_layout Plain Layout
476
477        field_A:interval_write = "6h" ;
478\end_layout
479
480\begin_layout Plain Layout
481
482        field_A:coordinates = "time_centered axis_A nav_lat nav_lon" ;
483\end_layout
484
485\end_inset
486
487
488\end_layout
489
490\begin_layout Standard
491The data vary most quickly on dimension y, x which are two axes of domain_A.
492 These are the default name of these dimension of a domain.
493 The data on axis_C vary slower than on the domain and all the data are
494 written one time step defined by time_counter at a time.
495\end_layout
496
497\begin_layout Standard
498Although a grid can be easily configured in XML file, it also needs defining
499 in the FORTRAN via the definition of domain and axis for a model to work
500 fully and correctly.
501 All these instruction will be detailed in the next section.
502\end_layout
503
504\begin_layout Section
505Working with FORTRAN code
506\end_layout
507
508\begin_layout Standard
509Because grid is composed of domain and axis, all processing are taken grid
510 via Domain and Axis.
511 The next chapters supply the detail of these two sub components.
512 
513\end_layout
514
515\end_body
516\end_document
Note: See TracBrowser for help on using the repository browser.