source: XIOS/dev/XIOS_DEV_CMIP6/doc/inputs/user/Axis.lyx @ 1482

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

Updating User guide and reference doc

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 Itemize
290inverse_axis: Inverse an axis
291\end_layout
292
293\begin_layout Standard
294It is not difficult to define a transformation: Include type of transformation
295 inside axis definition, as the following
296\end_layout
297
298\begin_layout Standard
299\begin_inset listings
300lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
301inline false
302status open
303
304\begin_layout Plain Layout
305
306<axis_definition>
307\end_layout
308
309\begin_layout Plain Layout
310
311  <axis id="axis_A" />
312\end_layout
313
314\begin_layout Plain Layout
315
316  <axis id="axis_A_zoom" axis_ref="axis_A">
317\end_layout
318
319\begin_layout Plain Layout
320
321   <zoom_axis zoom_begin="1" zoom_n="3"/>
322\end_layout
323
324\begin_layout Plain Layout
325
326  </axis>
327\end_layout
328
329\begin_layout Plain Layout
330
331</axis_definition>
332\end_layout
333
334\end_inset
335
336
337\end_layout
338
339\begin_layout Standard
340The concrete example is translated as: the axis named axis_A_zoom is transformed
341 from axis name axis_A with a zoom activity.
342 The detailed attributes of zoom_axis can be found in reference document,
343 but simply it contains the begining and size of zoomed region.
344\end_layout
345
346\begin_layout Standard
347One remark is the transformed axis SHOULD have an id, in this case, it's
348 axis_A_zoom.
349 As mentioned before, a no-id axis or any no-id component of XIOS can only
350 be used inside its definition scope.
351\end_layout
352
353\begin_layout Standard
354To make use of transformation, the grid must contain axis which references
355 to transformed ones.
356 
357\end_layout
358
359\begin_layout Standard
360\begin_inset listings
361lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
362inline false
363status open
364
365\begin_layout Plain Layout
366
367<grid id="grid_A">          
368\end_layout
369
370\begin_layout Plain Layout
371
372  <axis axis_ref="axis_A" />
373\end_layout
374
375\begin_layout Plain Layout
376
377</grid>
378\end_layout
379
380\begin_layout Plain Layout
381
382<grid id="grid_A_zoom">          
383\end_layout
384
385\begin_layout Plain Layout
386
387  <axis axis_ref="axis_A_zoom" />
388\end_layout
389
390\begin_layout Plain Layout
391
392</grid>
393\end_layout
394
395\end_inset
396
397
398\end_layout
399
400\begin_layout Standard
401On defining this way, we tell XIOS to establish a connection between two
402 grids by a transformation (zoom) with: grid source - grid_A, grid destination
403 - grid_A_zoom.
404\end_layout
405
406\begin_layout Standard
407As mentioned in Grid Chapter, in order to use transformed grid, just reference
408 to it in field_definition
409\end_layout
410
411\begin_layout Standard
412\begin_inset listings
413lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
414inline false
415status open
416
417\begin_layout Plain Layout
418
419<field_definition level="1" enabled=".TRUE." default_value="9.96921e+36">
420\end_layout
421
422\begin_layout Plain Layout
423
424  <field id="field_A"  operation="average" freq_op="3600s" grid_ref="grid_A"
425 />
426\end_layout
427
428\begin_layout Plain Layout
429
430  <field id="field_A_zoom"  operation="average" freq_op="3600s" grid_ref="grid_A
431_zoom" />
432\end_layout
433
434\begin_layout Plain Layout
435
436 </field_definition>
437\end_layout
438
439\end_inset
440
441
442\end_layout
443
444\begin_layout Standard
445Although xml is helpful to define several configurations, it can not be
446 used to customize attributes of axis.
447 So it's the turn of Fortran interface.
448\end_layout
449
450\begin_layout Section
451Working with FORTRAN code
452\end_layout
453
454\begin_layout Standard
455Although axis is not as complexe as domain, there are some mandatory attributes
456 to define.
457 Different from precedent version, XIOS 2.0 supports distribution of data
458 on a axis.
459 The followings describe the essential parts of axis.
460 Details of its attributes and operations can be found in XIOS reference
461 guide.
462\end_layout
463
464\begin_layout Subsection
465Local axis index
466\end_layout
467
468\begin_layout Standard
469Axis is often used with domain, which is broken into several distributed
470 pieces, to make a 3 dimension grid.
471 However, there are cases in which data on axis are distributed among processes.
472 Following we consider a simple case: a axis with global size 9 and its
473 data are distributed evenly among 3 client processes, each of which has
474 size 3.
475\end_layout
476
477\begin_layout Standard
478\begin_inset Float figure
479placement !tbph
480wide false
481sideways false
482status open
483
484\begin_layout Plain Layout
485\begin_inset Graphics
486        filename ../images/Distributed_Axis.pdf
487        lyxscale 50
488        scale 60
489
490\end_inset
491
492
493\end_layout
494
495\begin_layout Plain Layout
496\begin_inset Caption Standard
497
498\begin_layout Plain Layout
499Global axis data
500\end_layout
501
502\end_inset
503
504
505\begin_inset CommandInset label
506LatexCommand label
507name "globalAxis"
508
509\end_inset
510
511
512\end_layout
513
514\end_inset
515
516
517\end_layout
518
519\begin_layout Standard
520The local axis can be described by the following way.
521\end_layout
522
523\begin_layout Standard
524Specify the the beginning and size of local axis with:
525\end_layout
526
527\begin_layout Itemize
528n_glo: global size of axis.
529 
530\end_layout
531
532\begin_layout Itemize
533begin: global position where a local axis begin
534\end_layout
535
536\begin_layout Itemize
537n: local size of axis on each process
538\end_layout
539
540\begin_layout Standard
541For example, the local axis in the middle (the yellow one) can be specified
542 with:
543\end_layout
544
545\begin_layout Standard
546\begin_inset listings
547lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
548inline false
549status open
550
551\begin_layout Plain Layout
552
553CALL xios_set_axis_attr("axis_A",n_glo=9, begin=3, n=3)
554\end_layout
555
556\end_inset
557
558
559\end_layout
560
561\begin_layout Subsection
562Local axis data
563\end_layout
564
565\begin_layout Standard
566Simpler than local domain data, data on axis is always on-dimension.
567 Like local domain data, local axis data represent the data offset from
568 local axis, and it can be defined in two ways.
569\end_layout
570
571\begin_layout Standard
572Specify the begining and size of data on the local axis:
573\end_layout
574
575\begin_layout Itemize
576data_begin: the local position of data on axis where data begins
577\end_layout
578
579\begin_layout Itemize
580data_n: size of data on each local axis
581\end_layout
582
583\begin_layout Standard
584Or specify data with its position in the local axis:
585\end_layout
586
587\begin_layout Itemize
588data_index: array of local position of data in the local axis.
589\end_layout
590
591\begin_layout Standard
592Although the valid data must be inside a local axis, it is not neccessary
593 for data to have same size.
594 In fact, data can have larger size than local axis.
595\end_layout
596
597\begin_layout Standard
598\begin_inset listings
599lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
600inline false
601status open
602
603\begin_layout Plain Layout
604
605CALL xios_set_axis_attr("axis_A", data_begin=-1, data_n=n+2)
606\end_layout
607
608\end_inset
609
610
611\end_layout
612
613\begin_layout Standard
614For local axis_A, the negative value of data_begin indicates that data is
615 larger than local axis, the valid part of data needs extracted from the
616 real data.
617 If data_begin has a positive value, that means data size is smaller than
618 local axis.
619 The default value of data_begin is 0, which implies that local data fit
620 into local axis properly.
621 
622\end_layout
623
624\begin_layout Standard
625Loal data can be defined with:
626\end_layout
627
628\begin_layout Standard
629\begin_inset listings
630lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
631inline false
632status open
633
634\begin_layout Plain Layout
635
636CALL xios_set_axis_attr("axis_A",data_index=data)
637\end_layout
638
639\end_inset
640
641
642\end_layout
643
644\begin_layout Standard
645with
646\end_layout
647
648\begin_layout Itemize
649data = {-1,0,1,2,3}
650\end_layout
651
652\begin_layout Subsection
653Value
654\end_layout
655
656\begin_layout Standard
657Value of axis plays a same role as longitude and latitude of domain.
658 As local data, it can be distributed among processes.
659\end_layout
660
661\begin_layout Standard
662\begin_inset listings
663lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
664inline false
665status open
666
667\begin_layout Plain Layout
668
669CALL xios_set_axis_attr("axis_A", value=valueAxis)
670\end_layout
671
672\end_inset
673
674
675\end_layout
676
677\begin_layout Standard
678with
679\end_layout
680
681\begin_layout Itemize
682valueAxis = {30, 40, 50}
683\end_layout
684
685\begin_layout Standard
686Because there is a need of direction of an axis, then comes the attribute
687 positive
688\end_layout
689
690\begin_layout Standard
691\begin_inset listings
692lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
693inline false
694status open
695
696\begin_layout Plain Layout
697
698CALL xios_set_axis_attr("axis_A", positive='up')
699\end_layout
700
701\end_inset
702
703
704\end_layout
705
706\begin_layout Standard
707All attributes of axis can be found in Reference Guide.
708\end_layout
709
710\begin_layout Standard
711
712\end_layout
713
714\end_body
715\end_document
Note: See TracBrowser for help on using the repository browser.