source: XIOS/trunk/doc/inputs/user/Axis.lyx @ 669

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

Updating user document

File size: 14.4 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
75Axis
76\end_layout
77
78\begin_layout Standard
79Like Domain, Axis is a sub-component of Grid but is one dimension.
80 In meteorological applications, axis represents a vertical line with different
81 levels.
82\end_layout
83
84\begin_layout Section
85Working with configuration file
86\end_layout
87
88\begin_layout Standard
89The way to define an axis with configuration file is similar to define a
90 domain.
91\end_layout
92
93\begin_layout Subsection
94Basic configuration
95\end_layout
96
97\begin_layout Standard
98Similar to domain, an axis is defined inside its definition part with the
99 tag
100\series bold
101\color black
102axis_definition
103\series default
104\color inherit
105.
106 
107\begin_inset listings
108lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
109inline false
110status open
111
112\begin_layout Plain Layout
113
114<axis_definition>
115\end_layout
116
117\begin_layout Plain Layout
118
119  <axis id="axis_A" />
120\end_layout
121
122\begin_layout Plain Layout
123
124  <axis axis_ref="axis_A" />
125\end_layout
126
127\begin_layout Plain Layout
128
129</axis_definition>
130\end_layout
131
132\end_inset
133
134
135\end_layout
136
137\begin_layout Standard
138The first one is to specify explicitly identification of an axis with an
139 id.
140 
141\end_layout
142
143\begin_layout Standard
144\begin_inset listings
145lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
146inline false
147status open
148
149\begin_layout Plain Layout
150
151<axis_definition>
152\end_layout
153
154\begin_layout Plain Layout
155
156  <axis id="axis_A" /> 
157\end_layout
158
159\begin_layout Plain Layout
160
161</axis_definition>
162\end_layout
163
164\end_inset
165
166
167\end_layout
168
169\begin_layout Standard
170In this way, with id, the axis can be processed, e.x modified its attributes,
171 with Fortran interface; besides, it is only possible to reference to a
172 axis whose id is explicitly defined.
173\end_layout
174
175\begin_layout Standard
176To make a reference to an axis, we use axis_ref
177\end_layout
178
179\begin_layout Standard
180\begin_inset listings
181lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
182inline false
183status open
184
185\begin_layout Plain Layout
186
187<axis_definition>
188\end_layout
189
190\begin_layout Plain Layout
191
192  <axis axis_ref="axis_A" />
193\end_layout
194
195\begin_layout Plain Layout
196
197</axis_definition>
198\end_layout
199
200\end_inset
201
202
203\end_layout
204
205\begin_layout Standard
206An axis defined by axis_ref will inherit all attributes of the referenced
207 one, except its id attribute.
208 If there is no id specified, an implicit one is assigned to this new axis.
209 The axis with implicit id can only be used inside the scope where it is
210 defined, it can not be referenced, nor be processed.
211 It is rare to define an axis without id inside axis_definition.
212 
213\end_layout
214
215\begin_layout Standard
216To define a new axis inside a grid, we use the tag
217\series bold
218\color black
219axis.
220\end_layout
221
222\begin_layout Standard
223\begin_inset listings
224lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
225inline false
226status open
227
228\begin_layout Plain Layout
229
230<grid id="grid_A">          
231\end_layout
232
233\begin_layout Plain Layout
234
235   <axis axis_ref="axis_A" />
236\end_layout
237
238\begin_layout Plain Layout
239
240</grid>
241\end_layout
242
243\end_inset
244
245
246\end_layout
247
248\begin_layout Standard
249The xml lines above can be translated as: the grid_A composed of an axis_A
250 that is defined somewhere else before.
251 More precisely, the grid grid_A is constituted of a
252\begin_inset Quotes eld
253\end_inset
254
255unknown id
256\begin_inset Quotes erd
257\end_inset
258
259 axis which has inherited all attributes (and their values) from axis A
260 (name, long name, i_index, j_index, ...
261 etc).
262\end_layout
263
264\begin_layout Subsection
265Advanced configuration
266\end_layout
267
268\begin_layout Standard
269Like domain, there are several transformation which can be defined with
270 configuration file.
271 All transformations on an axis have form *_axis.
272 
273\end_layout
274
275\begin_layout Standard
276Till now, XIOS supports the following transformation on axis:
277\end_layout
278
279\begin_layout Itemize
280zoom_axis: Like zoom functionality in XIOS 1.0, the destination grid is the
281 zoomed region of the source grid.
282\end_layout
283
284\begin_layout Itemize
285interpolation_axis: Implement interpolation from an axis to one another.
286 For now, only polynominal interpolation is available.
287\end_layout
288
289\begin_layout Standard
290It is not difficult to define a transformation: Include type of transformation
291 inside axis definition, as the following
292\end_layout
293
294\begin_layout Standard
295\begin_inset listings
296lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
297inline false
298status open
299
300\begin_layout Plain Layout
301
302<axis_definition>
303\end_layout
304
305\begin_layout Plain Layout
306
307  <axis id="axis_A" />
308\end_layout
309
310\begin_layout Plain Layout
311
312  <axis id="axis_A_zoom" axis_ref="axis_A">
313\end_layout
314
315\begin_layout Plain Layout
316
317   <zoom_axis zoom_begin="1" zoom_size="3"/>
318\end_layout
319
320\begin_layout Plain Layout
321
322  </axis>
323\end_layout
324
325\begin_layout Plain Layout
326
327</axis_definition>
328\end_layout
329
330\end_inset
331
332
333\end_layout
334
335\begin_layout Standard
336The concrete example above says many things: the axis named axis_A_zoom
337 is transformed from axis name axis_A with a zoom activity.
338 The detailed attributes of zoom_axis can be found in reference document,
339 but simply it contains the begining and size of zoomed region.
340\end_layout
341
342\begin_layout Standard
343One remark is the transformed axis SHOULD have an id, in this case, it's
344 axis_A_zoom.
345 As mentioned before, a no-id axis or any no-id component of XIOS can only
346 be used inside its definition scope.
347\end_layout
348
349\begin_layout Standard
350To make use of transformation, the grid must contain axis which references
351 to transformed ones.
352 
353\end_layout
354
355\begin_layout Standard
356\begin_inset listings
357lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
358inline false
359status open
360
361\begin_layout Plain Layout
362
363<grid id="grid_A">          
364\end_layout
365
366\begin_layout Plain Layout
367
368  <axis axis_ref="axis_A" />
369\end_layout
370
371\begin_layout Plain Layout
372
373</grid>
374\end_layout
375
376\begin_layout Plain Layout
377
378<grid id="grid_A_zoom">          
379\end_layout
380
381\begin_layout Plain Layout
382
383  <axis axis_ref="axis_A_zoom" />
384\end_layout
385
386\begin_layout Plain Layout
387
388</grid>
389\end_layout
390
391\end_inset
392
393
394\end_layout
395
396\begin_layout Standard
397On defining this way, we tell XIOS to establish a connection between two
398 grids by a transformation (zoom) with: grid source - grid_A, grid destination
399 - grid_A_zoom.
400\end_layout
401
402\begin_layout Standard
403As mentioned in Grid Chapter, in order to use transformed grid, just reference
404 to it in field_definition
405\end_layout
406
407\begin_layout Standard
408\begin_inset listings
409lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
410inline false
411status open
412
413\begin_layout Plain Layout
414
415<field_definition level="1" enabled=".TRUE." default_value="9.96921e+36">
416\end_layout
417
418\begin_layout Plain Layout
419
420  <field id="field_A"  operation="average" freq_op="3600s" grid_ref="grid_A"
421 />
422\end_layout
423
424\begin_layout Plain Layout
425
426  <field id="field_A_zoom"  operation="average" freq_op="3600s" grid_ref="grid_A
427_zoom" />
428\end_layout
429
430\begin_layout Plain Layout
431
432 </field_definition>
433\end_layout
434
435\end_inset
436
437
438\end_layout
439
440\begin_layout Standard
441Although xml is helpful to define several configurations, it can not be
442 used to customize attributes of axis.
443 So it's the turn of Fortran interface.
444\end_layout
445
446\begin_layout Section
447Working with FORTRAN code
448\end_layout
449
450\begin_layout Standard
451Although axis is not as complexe as domain, there are some mandatory attributes
452 to define.
453 Different from precedent version, XIOS 2.0 supports distribution of data
454 on a axis.
455 The followings describe the essential parts of axis.
456 Details of its attributes and operations can be found in XIOS reference
457 guide.
458\end_layout
459
460\begin_layout Subsection
461Local axis index
462\end_layout
463
464\begin_layout Standard
465Axis is often used with domain, which is broken into several distributed
466 pieces, to make a 3 dimension grid.
467 However, there are cases in which data on axis are distributed among processes.
468 Following we consider a simple case: a axis with global size 9 and its
469 data are distributed evenly among 3 client processes, each of which has
470 size 3.
471\end_layout
472
473\begin_layout Standard
474\begin_inset Float figure
475placement !tbph
476wide false
477sideways false
478status open
479
480\begin_layout Plain Layout
481\begin_inset Graphics
482        filename ../images/Distributed_Axis.pdf
483        lyxscale 50
484        scale 60
485
486\end_inset
487
488
489\end_layout
490
491\begin_layout Plain Layout
492\begin_inset Caption Standard
493
494\begin_layout Plain Layout
495Global axis data
496\end_layout
497
498\end_inset
499
500
501\begin_inset CommandInset label
502LatexCommand label
503name "globalAxis"
504
505\end_inset
506
507
508\end_layout
509
510\end_inset
511
512
513\end_layout
514
515\begin_layout Standard
516The local axis can be described by the following way.
517\end_layout
518
519\begin_layout Standard
520Specify the the beginning and size of local axis with:
521\end_layout
522
523\begin_layout Itemize
524n_glo: global size of axis.
525 
526\end_layout
527
528\begin_layout Itemize
529begin: global position where a local axis begin
530\end_layout
531
532\begin_layout Itemize
533n: local size of axis on each process
534\end_layout
535
536\begin_layout Standard
537For example, the local axis in the middle (the yellow one) can be specified
538 with:
539\end_layout
540
541\begin_layout Standard
542\begin_inset listings
543lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
544inline false
545status open
546
547\begin_layout Plain Layout
548
549CALL xios_set_axis_attr("axis_A",n_glo=9, begin=3, n=3)
550\end_layout
551
552\end_inset
553
554
555\end_layout
556
557\begin_layout Subsection
558Local axis data
559\end_layout
560
561\begin_layout Standard
562Simpler than local domain data, data on axis is always on-dimension.
563 Like local domain data, local axis data represent the data offset from
564 local axis, and it can be defined in two ways.
565\end_layout
566
567\begin_layout Standard
568Specify the begining and size of data on the local axis:
569\end_layout
570
571\begin_layout Itemize
572data_begin: the local position of data on axis where data begins
573\end_layout
574
575\begin_layout Itemize
576data_n: size of data on each local axis
577\end_layout
578
579\begin_layout Standard
580Or specify data with its position in the local axis:
581\end_layout
582
583\begin_layout Itemize
584data_index: array of local position of data in the local axis.
585\end_layout
586
587\begin_layout Standard
588Although the valid data must be inside a local axis, it is not neccessary
589 for data to have same size.
590 In fact, data can have larger size than local axis.
591\end_layout
592
593\begin_layout Standard
594\begin_inset listings
595lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
596inline false
597status open
598
599\begin_layout Plain Layout
600
601CALL xios_set_axis_attr("axis_A", data_begin=-1, data_n=n+2)
602\end_layout
603
604\end_inset
605
606
607\end_layout
608
609\begin_layout Standard
610For local axis_A, the negative value of data_begin indicates that data is
611 larger than local axis, the valid part of data needs extracted from the
612 real data.
613 If data_begin has a positive value, that means data size is smaller than
614 local axis.
615 The default value of data_begin is 0, which implies that local data fit
616 into local axis properly.
617 
618\end_layout
619
620\begin_layout Standard
621Loal data can be defined with:
622\end_layout
623
624\begin_layout Standard
625\begin_inset listings
626lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
627inline false
628status open
629
630\begin_layout Plain Layout
631
632CALL xios_set_axis_attr("axis_A",data_index=data)
633\end_layout
634
635\end_inset
636
637
638\end_layout
639
640\begin_layout Standard
641with
642\end_layout
643
644\begin_layout Itemize
645data = {-1,0,1,2,3}
646\end_layout
647
648\begin_layout Subsection
649Value
650\end_layout
651
652\begin_layout Standard
653Value of axis plays a same role as longitude and latitude of domain.
654 As local data, it can be distributed among processes.
655\end_layout
656
657\begin_layout Standard
658\begin_inset listings
659lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
660inline false
661status open
662
663\begin_layout Plain Layout
664
665CALL xios_set_axis_attr("axis_A", value=valueAxis)
666\end_layout
667
668\end_inset
669
670
671\end_layout
672
673\begin_layout Standard
674with
675\end_layout
676
677\begin_layout Itemize
678valueAxis = {30, 40, 50}
679\end_layout
680
681\begin_layout Standard
682Because there is a need of direction of an axis, then comes the attribute
683 positive
684\end_layout
685
686\begin_layout Standard
687\begin_inset listings
688lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
689inline false
690status open
691
692\begin_layout Plain Layout
693
694CALL xios_set_axis_attr("axis_A", positive='up')
695\end_layout
696
697\end_inset
698
699
700\end_layout
701
702\begin_layout Standard
703All attributes of axis can be found in Reference Guide.
704\end_layout
705
706\begin_layout Standard
707
708\end_layout
709
710\end_body
711\end_document
Note: See TracBrowser for help on using the repository browser.