source: XIOS/trunk/doc/inputs/user/Domain.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: 19.7 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
77Domain
78\end_layout
79
80\begin_layout Standard
81Domain is a two dimensional coordinates, which can be considered to be composed
82 of two axis: y-axis and x-axis.
83 However, different from two axis composed mechanically, a domain contains
84 more typical information which play an important role in specific cases.
85 Very often, in meteorological applications, domain represents a surface
86 with latitude and longitude.
87\end_layout
88
89\begin_layout Section
90Working with configuration file
91\end_layout
92
93\begin_layout Subsection
94Basic configuration
95\end_layout
96
97\begin_layout Standard
98Similar to Grid as well as other components in XIOS, a domain is defined
99 inside its definition part with the tag
100\series bold
101\color black
102domain_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<domain_definition>
115\end_layout
116
117\begin_layout Plain Layout
118
119  <domain id="domain_A" />
120\end_layout
121
122\begin_layout Plain Layout
123
124  <domain domain_ref="domain_A" />
125\end_layout
126
127\begin_layout Plain Layout
128
129</domain_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 a domain with an
139 id.
140 One repetition, id of any component in XIOS are
141\shape italic
142\color black
143unique
144\shape default
145\color inherit
146 among this kind of components.
147 Domains defined by a same Id always represent only one domain.
148\end_layout
149
150\begin_layout Standard
151\begin_inset listings
152lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
153inline false
154status open
155
156\begin_layout Plain Layout
157
158<domain_definition>
159\end_layout
160
161\begin_layout Plain Layout
162
163  <domain id="domain_A" /> 
164\end_layout
165
166\begin_layout Plain Layout
167
168</domain_definition>
169\end_layout
170
171\end_inset
172
173
174\end_layout
175
176\begin_layout Standard
177In this way, with id, the domain can be processed, e.x modified its attributes,
178 with Fortran interface; besides, it is only possible to reference to a
179 domain whose id is explicitly defined.
180\end_layout
181
182\begin_layout Standard
183Very often, after a domain is defined, it may be referenced many times.
184 To make a reference to a domain, we use
185\shape italic
186domain_ref
187\end_layout
188
189\begin_layout Standard
190\begin_inset listings
191lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
192inline false
193status open
194
195\begin_layout Plain Layout
196
197<domain_definition>
198\end_layout
199
200\begin_layout Plain Layout
201
202  <domain domain_ref="domain_A" />
203\end_layout
204
205\begin_layout Plain Layout
206
207</domain_definition>
208\end_layout
209
210\end_inset
211
212
213\end_layout
214
215\begin_layout Standard
216A domain defined by domain_ref will inherit all attributes of the referenced
217 one, except its id attribute.
218 If there is no id specified, an implicit one is assigned to this new domain.
219 The domain with implicit id can only be used inside the scope where it
220 is defined, it can not be referenced, nor be processed.
221 It is useless to define a domain without id inside domain_definition.
222 Meanwhile, the domain_ref is utilized widely outside the scope of domain_defini
223tion.
224\end_layout
225
226\begin_layout Standard
227Because a domain is a sub component of grid, it is possible to define a
228 new domain inside a grid with the tag
229\series bold
230\color black
231domain.
232 
233\series default
234\color inherit
235However, it is the only region where we can define a new domain outside
236 domain_definition.
237\end_layout
238
239\begin_layout Standard
240\begin_inset listings
241lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
242inline false
243status open
244
245\begin_layout Plain Layout
246
247<grid id="grid_A">          
248\end_layout
249
250\begin_layout Plain Layout
251
252   <domain domain_ref="domain_A" />
253\end_layout
254
255\begin_layout Plain Layout
256
257</grid>
258\end_layout
259
260\end_inset
261
262
263\end_layout
264
265\begin_layout Standard
266The xml lines above can be translated as: the grid_A composed of a domain_A
267 that is defined somewhere else before.
268 More precisely, the grid grid_A is constituted of a
269\begin_inset Quotes eld
270\end_inset
271
272unknown id
273\begin_inset Quotes erd
274\end_inset
275
276 domain which has inherited all attributes (and their values) from domain
277 A (name, long name, i_index, j_index, ...
278 etc).
279\end_layout
280
281\begin_layout Standard
282With this approach, we only define a domain once but reuse it as many time
283 as we like in different configurations.
284\end_layout
285
286\begin_layout Subsection
287Advanced configuration
288\end_layout
289
290\begin_layout Standard
291One of a new concept which differentiates XIOS 2.0 from its precedent is
292 (spatial) transformation, which can be defined inside a domain.
293 All transformations on a domain have form *_domain.
294 See Chapter
295\begin_inset CommandInset ref
296LatexCommand ref
297reference "chap:Transformation"
298
299\end_inset
300
301 for more details.
302\end_layout
303
304\begin_layout Section
305Working with FORTRAN code
306\end_layout
307
308\begin_layout Standard
309One of the important concepts to grasp in mind in using FORTRAN interface
310 is the data distribution.
311 With a distributed-memory XIOS, data are broken into disjoint blocks, one
312 per client process.
313 In the next sections, local describes everything related to a client process,
314 whereas global means global data.
315 The followings describe the essential parts of domain.
316 Details of its attributes and operations can be found in XIOS reference
317 guide
318\end_layout
319
320\begin_layout Subsection
321Domain type
322\end_layout
323
324\begin_layout Standard
325Domain is a two dimensional coordinates, which can be considered to be composed
326 of two axis: y-axis and x-axis.
327 However, different from two axis composed mechanically, a domain contains
328 more typical information which play an important role in specific cases.
329 Very often, in meteorological applications, domain represents a surface
330 with latitude and longitude.
331 Because these properties change from one domain type to another, it is
332 recommended to use domain in case of representing a surface.
333\end_layout
334
335\begin_layout Standard
336In XIOS, a domain can be represented by one of three different types of
337 coordinate system which also differentiate the way to represent latitude
338 and longitude correspondingly.
339 
340\end_layout
341
342\begin_layout Itemize
343rectilinear: a simple 2-dimensional Cartesian coordinates with two perpendicular
344 axes.
345 Latitude represents the y-axis while longitude represents the x-axe.
346\end_layout
347
348\begin_layout Itemize
349curvilinear: a 2-dimensional coordinates allows the generality of two axes
350 not perpendicular to each other.
351 Latitude and longitude have the size equivalent to size of local domain.
352 
353\end_layout
354
355\begin_layout Itemize
356unstructured: not any of two above, the latitude and longitude, as curvilinear,
357 are represented with the help of boundaries.
358 
359\end_layout
360
361\begin_layout Standard
362Different from XIOS 1.0, in this new version, users must explicitly specify
363 the type of domain which they would like to use
364\end_layout
365
366\begin_layout Standard
367\begin_inset listings
368lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
369inline false
370status open
371
372\begin_layout Plain Layout
373
374CALL xios_set_domain_attr("domain_A",type='rectilinear')
375\end_layout
376
377\end_inset
378
379
380\end_layout
381
382\begin_layout Standard
383Although there are different domain types, they share the similar patterns
384 to settle local data on a client process: There are some essential attributes
385 to define.
386 The next sections describe their meanings and how to specify correctly
387 data for a local domain.
388\end_layout
389
390\begin_layout Subsection
391Local domain index
392\end_layout
393
394\begin_layout Standard
395It is not uncommon that a global domain is broken into several pieces, each
396 of which is distributed to one process.
397 Following, we consider a simple case: a domain of rectilinear type with
398 global size 9 x 9 and its data is distributed evenly among 9 client processes,
399 each of which has 3x3.
400\end_layout
401
402\begin_layout Standard
403\begin_inset Float figure
404placement !tbph
405wide false
406sideways false
407status open
408
409\begin_layout Plain Layout
410\begin_inset Graphics
411        filename ../images/Distributed_Domain.pdf
412        lyxscale 50
413        scale 60
414
415\end_inset
416
417
418\end_layout
419
420\begin_layout Plain Layout
421\begin_inset Caption Standard
422
423\begin_layout Plain Layout
424Global domain data
425\end_layout
426
427\end_inset
428
429
430\begin_inset CommandInset label
431LatexCommand label
432name "globalDomain"
433
434\end_inset
435
436
437\end_layout
438
439\end_inset
440
441
442\end_layout
443
444\begin_layout Standard
445The region of local domain can be described by one of the following way.
446\end_layout
447
448\begin_layout Standard
449Specify the the beginning and size of local domain with:
450\end_layout
451
452\begin_layout Itemize
453ibegin, jbegin: global position on x-axis and y-axis where a local domain
454 begin
455\end_layout
456
457\begin_layout Itemize
458ni, nj: local size of domain of each process on x-axis and y-axis
459\end_layout
460
461\begin_layout Itemize
462ni_glo, nj_glo: global size of x-axis and y-axis correspondingly.
463 
464\end_layout
465
466\begin_layout Standard
467Or tell XIOS exactly the global position of each point in the local domain,
468 from left to right, top to bottom with:
469\end_layout
470
471\begin_layout Itemize
472i_index, j_index: array of global position of every point in the local domain.
473 It is very useful when local domains do not align with each other.
474\end_layout
475
476\begin_layout Standard
477For example, with the first method, the local domain in the middle (the
478 blue one) can be specified with:
479\end_layout
480
481\begin_layout Standard
482\begin_inset listings
483lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
484inline false
485status open
486
487\begin_layout Plain Layout
488
489CALL xios_set_domain_attr("domain_A",ni_glo=9, nj_glo=9, ibegin=3, ni=3,
490 jbegin=3, nj=3)
491\end_layout
492
493\end_inset
494
495
496\end_layout
497
498\begin_layout Standard
499The second method demands only two arrays:
500\end_layout
501
502\begin_layout Standard
503\begin_inset listings
504lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
505inline false
506status open
507
508\begin_layout Plain Layout
509
510CALL xios_set_domain_attr("domain_A",ni_glo=9, nj_glo=9, i_index=iIndex,
511 j_index=jIndex)
512\end_layout
513
514\end_inset
515
516
517\end_layout
518
519\begin_layout Standard
520and
521\end_layout
522
523\begin_layout Itemize
524iIndex={3,4,5,3,4,5,3,4,5}, jIndex = {3,3,3,4,4,4,5,5,5}
525\end_layout
526
527\begin_layout Subsection
528Local domain data
529\end_layout
530
531\begin_layout Standard
532Similar to define local index, local data can be done in two ways.
533\end_layout
534
535\begin_layout Standard
536Specify the beginning and size of data on the local domain:
537\end_layout
538
539\begin_layout Itemize
540data_ibegin, data_jbegin: the local position of data on x-axis and y-axis
541 where data begins inside the local domain
542\end_layout
543
544\begin_layout Itemize
545data_ni, data_nj: size of data on each axis
546\end_layout
547
548\begin_layout Standard
549Or specify data with its position in the local domain, from left to right,
550 top to bottom with
551\end_layout
552
553\begin_layout Itemize
554data_i_index, data_j_index: array of local position of data in the local
555 domain.
556\end_layout
557
558\begin_layout Standard
559Beside the attributes above, one of the essential attributes to define is
560 dimensional size of data - data_dim.
561 Although domain has two dimensions, data are not required to be 2-dimensional.
562 In particular, for case of data_dim == 1, XIOS uses an
563\shape italic
5641-dimensional block distribution
565\shape default
566 of data, distributed along the first dimension, the x-axis.
567\end_layout
568
569\begin_layout Standard
570With the first way to define data on a local domain, we can use:
571\end_layout
572
573\begin_layout Standard
574\begin_inset listings
575lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
576inline false
577status open
578
579\begin_layout Plain Layout
580
581CALL xios_set_domain_attr("domain_A",data_dim=2, data_ibegin=-1, data_ni=ni+2,
582 data_jbegin=-1, data_nj=nj+2)
583\end_layout
584
585\end_inset
586
587
588\end_layout
589
590\begin_layout Standard
591In order to be processed correctly, data must be specified with the beginning
592 and size of its block .
593 For two-dimensional data, it can be done with data_ibegin, data_ni for
594 the first dimension and data_jbegin, data_nj for the second dimension.
595 In case of one-dimensional data, it is only necessary to determine data_ibegin
596 and data_ni.
597 Although the valid data must be inside a local domain, it is not necessary
598 for data to have same size as local domain.
599 In fact, data can have larger size than domain on each dimension, this
600 is often the case of
601\begin_inset Quotes eld
602\end_inset
603
604ghost cell
605\begin_inset Quotes erd
606\end_inset
607
608.
609 The attributes data_ibegin and data_jbegin specify the offset of data from
610 local domain.
611 For local domain_A, the negative value indicates that data is larger than
612 local domain, the valid part of data needs extracted from the real data.
613 A positive value indicates data is smaller than local domain.
614 The default value of data_ibegin/data_jbegin is 0, which implies that data
615 fit into local domain properly.
616 
617\end_layout
618
619\begin_layout Standard
620\begin_inset Float figure
621placement !tbph
622wide false
623sideways false
624status open
625
626\begin_layout Plain Layout
627\begin_inset Graphics
628        filename ../images/Domain.pdf
629        lyxscale 50
630        scale 60
631
632\end_inset
633
634
635\end_layout
636
637\begin_layout Plain Layout
638\begin_inset Caption Standard
639
640\begin_layout Plain Layout
641Local domain with data
642\end_layout
643
644\end_inset
645
646
647\begin_inset CommandInset label
648LatexCommand label
649name "localDomain"
650
651\end_inset
652
653
654\end_layout
655
656\end_inset
657
658
659\end_layout
660
661\begin_layout Standard
662On Figure
663\begin_inset CommandInset ref
664LatexCommand ref
665reference "localDomain"
666
667\end_inset
668
669, local domain occupies the center of the global domain, where real data
670 fill up a larger region.
671 Only data inside the local domain, represented by blue cells, are valid.
672 
673\end_layout
674
675\begin_layout Standard
676With the second way, data can be represented with:
677\end_layout
678
679\begin_layout Standard
680\begin_inset listings
681lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
682inline false
683status open
684
685\begin_layout Plain Layout
686
687CALL xios_set_domain_attr("domain_A",data_dim=2, data_i_index=dataI, data_j_inde
688x=dataJ)
689\end_layout
690
691\end_inset
692
693
694\end_layout
695
696\begin_layout Standard
697with
698\end_layout
699
700\begin_layout Itemize
701dataJ = {-1,-1,-1,-1,-1,0,0,0,0,0,1,1,1,1,1,2,2,2,3,3,3,3,3}
702\end_layout
703
704\begin_layout Itemize
705dataI = {-1,0,1,2,3,-1,0,1,2,3,-1,0,1,2,3,-1,0,1,2,3,-1,0,1,2,3}
706\end_layout
707
708\begin_layout Standard
709As mentioned, data on a domain are two-dimensional but in some cases, there
710 is a need to write data continuously, there comes one-dimensional data.
711 With the precedent example, we can define one dimensional data with:
712\end_layout
713
714\begin_layout Standard
715\begin_inset listings
716lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
717inline false
718status open
719
720\begin_layout Plain Layout
721
722CALL xios_set_domain_attr("domain_A",data_dim=1, data_i_index=dataI)
723\end_layout
724
725\end_inset
726
727
728\end_layout
729
730\begin_layout Standard
731and
732\end_layout
733
734\begin_layout Itemize
735dataI = {-6,-5,-4,-3,-2,-1,0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18}
736\end_layout
737
738\begin_layout Standard
739Above are the mandatory attributes to define local domain.
740 There are some auxiliary attributes which make data meaningful, especially
741 for meteorological one.
742 The next section discuses these attributes.
743\end_layout
744
745\begin_layout Subsection
746Longitude and latitude
747\end_layout
748
749\begin_layout Standard
750Different from the previous version, in XIOS 2.0, longitude and latitude
751 are optional.
752 Moreover, to be coherent to the data_dim concept, there are more ways to
753 input longitude and latitude values.
754\end_layout
755
756\begin_layout Standard
757Like data, longitude and latitude values can be one or two dimension.
758 The first ones are represented with lonvalue_1d, latvalue_1d; the second
759 ones are specified with lonvalue_2d and latvalue_2d.
760\end_layout
761
762\begin_layout Standard
763With the same domain_A, we can set longitude and latitude values by calling:
764\end_layout
765
766\begin_layout Standard
767\begin_inset listings
768lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
769inline false
770status open
771
772\begin_layout Plain Layout
773
774CALL xios_set_domain_attr("domain_A",lonvalue_1d=lon1D, latvalue_1d=lat1D)
775\end_layout
776
777\end_inset
778
779
780\end_layout
781
782\begin_layout Standard
783with
784\end_layout
785
786\begin_layout Itemize
787lon1D = {30, 40, 50, 30, 40, 50, 30, 40, 50}
788\end_layout
789
790\begin_layout Itemize
791lat1D = {30, 30, 30, 40, 40, 40, 50, 50, 50}
792\end_layout
793
794\begin_layout Standard
795Or by using two-dimension longitude and latitude
796\end_layout
797
798\begin_layout Standard
799\begin_inset listings
800lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
801inline false
802status open
803
804\begin_layout Plain Layout
805
806CALL xios_set_domain_attr("domain_A",lonvalue_2d=lon2D, latvalue_1d=lat2D)
807\end_layout
808
809\end_inset
810
811
812\end_layout
813
814\begin_layout Standard
815with
816\end_layout
817
818\begin_layout Itemize
819lon2D = {
820\begin_inset Formula $\begin{array}{ccc}
82130 & 40 & 50\\
82230 & 40 & 50\\
82330 & 40 & 50
824\end{array}$
825\end_inset
826
827}
828\end_layout
829
830\begin_layout Itemize
831lat1D = {
832\begin_inset Formula $\begin{array}{ccc}
83330 & 30 & 30\\
83440 & 40 & 40\\
83550 & 50 & 50
836\end{array}$
837\end_inset
838
839}
840\end_layout
841
842\begin_layout Standard
843For unstructured mesh, a cell can have different number of vertices than
844 rectilinear, in this case, longitude and latitude value of the vertex of
845 cell are specified with bounds_lon_1d and bounds_lat_1d.
846\end_layout
847
848\begin_layout Standard
849For curvilinear mesh, bounds_lon_2d and bounds_lat_2d provide a convenient
850 way to define longitude and latitude value for the vertex of the cell.
851 However, it is possible to use bounds_lon_1d and bounds_lat_1d to describe
852 these values.
853\end_layout
854
855\begin_layout Standard
856One thing to remind, only *_1d or *_2d attributes are used, if *_1d and
857 *_2d of a same attribute are provides, there will be run-time error.
858\end_layout
859
860\begin_layout Standard
861All attributes of domain can be found in Reference Guide.
862\end_layout
863
864\end_body
865\end_document
Note: See TracBrowser for help on using the repository browser.