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

Last change on this file since 983 was 669, checked in by mhnguyen, 6 years ago

Updating user document

File size: 11.3 KB
Line 
1#LyX 2.1 created this file. For more info see http://www.lyx.org/
2\lyxformat 474
3\begin_document
4\begin_header
5\textclass book
6\use_default_options true
7\master ../../XIOS_user_guide.lyx
8\maintain_unincluded_children false
9\language english
10\language_package default
11\inputencoding auto
12\fontencoding global
13\font_roman default
14\font_sans default
15\font_typewriter default
16\font_math auto
17\font_default_family default
18\use_non_tex_fonts false
19\font_sc false
20\font_osf false
21\font_sf_scale 100
22\font_tt_scale 100
23\graphics default
24\default_output_format default
25\output_sync 0
26\bibtex_command default
27\index_command default
28\float_placement !tph
29\paperfontsize default
30\spacing single
31\use_hyperref false
32\papersize a4paper
33\use_geometry false
34\use_package amsmath 1
35\use_package amssymb 1
36\use_package cancel 1
37\use_package esint 1
38\use_package mathdots 1
39\use_package mathtools 1
40\use_package mhchem 1
41\use_package stackrel 1
42\use_package stmaryrd 1
43\use_package undertilde 1
44\cite_engine basic
45\cite_engine_type default
46\biblio_style plain
47\use_bibtopic false
48\use_indices false
49\paperorientation portrait
50\suppress_date false
51\justification true
52\use_refstyle 1
53\index Index
54\shortcut idx
55\color #008000
56\end_index
57\secnumdepth 3
58\tocdepth 3
59\paragraph_separation indent
60\paragraph_indentation default
61\quotes_language english
62\papercolumns 1
63\papersides 1
64\paperpagestyle default
65\tracking_changes false
66\output_changes false
67\html_math_output 0
68\html_css_as_file 0
69\html_be_strict false
70\end_header
71
72\begin_body
73
74\begin_layout Chapter
75Grid
76\end_layout
77
78\begin_layout Section
79Overview
80\end_layout
81
82\begin_layout Standard
83Grid plays an important role in XIOS.
84 Same as Field, Grid is one of the basic elements in XIOS, which should
85 be well defined, not only in the configuration file but also in the FORTRAN
86 code.
87 Because, until now, XIOS has mainly served for writing NetCDF data format,
88 most of its components are inspired from NetCDF Data Model, and Grid is
89 not an exception.
90 Grid is a concept describing dimensions that contain the axes of the data
91 arrays.
92 Moreover, Grid always consists of an unlimited dimension whose length can
93 be expanded at any time.
94 Other dimensions can be described with Domain and Axis.
95 The followings describe how to make use of Grid in XIOS.
96 Details of its attributes and operations can be found in XIOS reference
97 guide.
98\end_layout
99
100\begin_layout Section
101Working with configuration file
102\end_layout
103
104\begin_layout Standard
105As mentioned above, a grid contains the axes of the data arrays, which are
106 characterized by Domain and/or Axis.
107 A domain is composed of a 2-dimension array, meanwhile an axis is, as its
108 name, an 1-dimension array.
109 
110\end_layout
111
112\begin_layout Standard
113Like other components of XIOS, a grid is defined inside its definition part
114 with the tag
115\series bold
116\color black
117grid_definition
118\series default
119\color inherit
120
121\begin_inset listings
122lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
123inline false
124status collapsed
125
126\begin_layout Plain Layout
127
128 <grid_definition>     
129\end_layout
130
131\begin_layout Plain Layout
132
133   <grid_group id="gridGroup">       
134\end_layout
135
136\begin_layout Plain Layout
137
138     <grid id="grid_A">         
139\end_layout
140
141\begin_layout Plain Layout
142
143       <domain domain_ref="domain_A" />
144\end_layout
145
146\begin_layout Plain Layout
147
148       <axis axis_ref="axis_C" />
149\end_layout
150
151\begin_layout Plain Layout
152
153     </grid>
154\end_layout
155
156\begin_layout Plain Layout
157
158         <grid id="grid_Axis">
159\end_layout
160
161\begin_layout Plain Layout
162
163           <axis axis_ref="axis_D" />
164\end_layout
165
166\begin_layout Plain Layout
167
168         </grid>
169\end_layout
170
171\begin_layout Plain Layout
172
173         <grid id="grid_All_Axis">
174\end_layout
175
176\begin_layout Plain Layout
177
178           <axis axis_ref="axis_A" />
179\end_layout
180
181\begin_layout Plain Layout
182
183       <axis axis_ref="axis_B" />
184\end_layout
185
186\begin_layout Plain Layout
187
188           <axis axis_ref="axis_C" />
189\end_layout
190
191\begin_layout Plain Layout
192
193         </grid>
194\end_layout
195
196\begin_layout Plain Layout
197
198   </grid_group>
199\end_layout
200
201\begin_layout Plain Layout
202
203 </grid_definition>
204\end_layout
205
206\end_inset
207
208
209\end_layout
210
211\begin_layout Standard
212As XIOS supports netCDF-4/HDF5, it allows user to gather several grids into
213 groups to better organize data.
214 Very often, grids are grouped, basing on the dimensions that they describe.
215 However, there is not a limit for user to group out the grids.
216 The more important thing than grid_group is grid.
217 A grid is defined with the tag
218\series bold
219\color black
220grid.
221 
222\end_layout
223
224\begin_layout Standard
225While it is not crucial for a grid group not to have an identification specified
226 by attribute id, a grid must be assigned an id to become useful.
227 Unlike grid group is a way of hierarchically organizing related grid only,
228 a grid itself is referenced by fields with its id.
229 Without the id, a grid can not be made used of by a field.
230 Id is a string of anything but there is one thing to remember: id of a
231 grid as well as id of any component in XIOS are
232\shape italic
233\color black
234unique
235\shape default
236\color inherit
237 among this kind of components.
238 It is not allowed to have two grids with a same id, but it is permitted
239 a grid and, for example, a domain to share a same one.
240 
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: empty grid - a grid without any domain or axis.
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 </grid>
434\end_layout
435
436\end_inset
437
438
439\end_layout
440
441\begin_layout Standard
442∆The order of domain and/or in grid definition decides order of data written
443 to netCDF: data on domain or axis appearing firstly in grid definition
444 will vary the most.
445 For example, on using ncdump command on netCDF which contains data written
446 on the grid_A .
447\end_layout
448
449\begin_layout Standard
450\begin_inset listings
451lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
452inline false
453status open
454
455\begin_layout Plain Layout
456
457 float field_A(time_counter, axis_A, y, x) ;
458\end_layout
459
460\begin_layout Plain Layout
461
462        field_A:online_operation = "average" ;
463\end_layout
464
465\begin_layout Plain Layout
466
467        field_A:interval_operation = "3600s" ;
468\end_layout
469
470\begin_layout Plain Layout
471
472        field_A:interval_write = "6h" ;
473\end_layout
474
475\begin_layout Plain Layout
476
477        field_A:coordinates = "time_centered axis_A nav_lat nav_lon" ;
478\end_layout
479
480\end_inset
481
482
483\end_layout
484
485\begin_layout Standard
486The data vary most quickly on dimension y, x which are two axes of domain_A.
487 These are the default name of these dimension of a domain.
488 The data on axis_C vary slower than on the domain and all the data are
489 written one time step defined by time_counter at a time.
490\end_layout
491
492\begin_layout Standard
493Although a grid can be easily configured in XML file, it also needs defining
494 in the FORTRAN via the definition of domain and axis for a model to work
495 fully and correctly.
496 All these instruction will be detailed in the next section.
497\end_layout
498
499\begin_layout Section
500Working with FORTRAN code
501\end_layout
502
503\begin_layout Standard
504Because grid is composed of domain and axis, all processing are taken grid
505 via Domain and Axis.
506 The next chapters supply the detail of these two sub components.
507 
508\end_layout
509
510\end_body
511\end_document
Note: See TracBrowser for help on using the repository browser.