source: XIOS/trunk/doc/inputs/user/Domain.lyx @ 1084

#LyX 2.2 created this file. For more info see http://www.lyx.org/
\lyxformat 508
\begin_document
\begin_header
\save_transient_properties true
\origin unavailable
\textclass book
\use_default_options true
\master ../../XIOS_user_guide.lyx
\maintain_unincluded_children false
\language english
\language_package default
\inputencoding auto
\fontencoding global
\font_roman "default" "default"
\font_sans "default" "default"
\font_typewriter "default" "default"
\font_math "auto" "auto"
\font_default_family default
\use_non_tex_fonts false
\font_sc false
\font_osf false
\font_sf_scale 100 100
\font_tt_scale 100 100
\graphics default
\default_output_format default
\output_sync 0
\bibtex_command default
\index_command default
\float_placement !tph
\paperfontsize default
\spacing single
\use_hyperref false
\papersize a4paper
\use_geometry false
\use_package amsmath 1
\use_package amssymb 1
\use_package cancel 1
\use_package esint 1
\use_package mathdots 1
\use_package mathtools 1
\use_package mhchem 1
\use_package stackrel 1
\use_package stmaryrd 1
\use_package undertilde 1
\cite_engine basic
\cite_engine_type default
\biblio_style plain
\use_bibtopic false
\use_indices false
\paperorientation portrait
\suppress_date false
\justification true
\use_refstyle 1
\index Index
\shortcut idx
\color #008000
\end_index
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\paragraph_indentation default
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\html_math_output 0
\html_css_as_file 0
\html_be_strict false
\end_header

\begin_body

\begin_layout Chapter
Domain
\end_layout

\begin_layout Standard
Domain is a two dimensional coordinates, which can be considered to be composed
 of two axis: y-axis and x-axis.
 However, different from two axis composed mechanically, a domain contains
 more typical information which play an important role in specific cases.
 Very often, in meteorological applications, domain represents a surface
 with latitude and longitude.
\end_layout

\begin_layout Section
Working with configuration file
\end_layout

\begin_layout Subsection
Basic configuration
\end_layout

\begin_layout Standard
Similar to Grid as well as other components in XIOS, a domain is defined
 inside its definition part with the tag 
\series bold
\color black
domain_definition
\series default
\color inherit
.
 
\begin_inset listings
lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
inline false
status open

\begin_layout Plain Layout

<domain_definition>
\end_layout

\begin_layout Plain Layout

  <domain id="domain_A" />
\end_layout

\begin_layout Plain Layout

  <domain domain_ref="domain_A" />
\end_layout

\begin_layout Plain Layout

</domain_definition>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The first one is to specify explicitly identification of a domain with an
 id.
 One repetition, id of any component in XIOS are 
\shape italic
\color black
unique
\shape default
\color inherit
 among this kind of components.
 Domains defined by a same Id always represent only one domain.
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
inline false
status open

\begin_layout Plain Layout

<domain_definition>
\end_layout

\begin_layout Plain Layout

  <domain id="domain_A" />  
\end_layout

\begin_layout Plain Layout

</domain_definition>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
In this way, with id, the domain can be processed, e.x modified its attributes,
 with Fortran interface; besides, it is only possible to reference to a
 domain whose id is explicitly defined.
\end_layout

\begin_layout Standard
Very often, after a domain is defined, it may be referenced many times.
 To make a reference to a domain, we use 
\shape italic
domain_ref
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
inline false
status open

\begin_layout Plain Layout

<domain_definition>
\end_layout

\begin_layout Plain Layout

  <domain domain_ref="domain_A" />
\end_layout

\begin_layout Plain Layout

</domain_definition>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
A domain defined by domain_ref will inherit all attributes of the referenced
 one, except its id attribute.
 If there is no id specified, an implicit one is assigned to this new domain.
 The domain with implicit id can only be used inside the scope where it
 is defined, it can not be referenced, nor be processed.
 It is useless to define a domain without id inside domain_definition.
 Meanwhile, the domain_ref is utilized widely outside the scope of domain_defini
tion.
\end_layout

\begin_layout Standard
Because a domain is a sub component of grid, it is possible to define a
 new domain inside a grid with the tag 
\series bold
\color black
domain.
 
\series default
\color inherit
However, it is the only region where we can define a new domain outside
 domain_definition.
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
inline false
status open

\begin_layout Plain Layout

<grid id="grid_A">          
\end_layout

\begin_layout Plain Layout

   <domain domain_ref="domain_A" />
\end_layout

\begin_layout Plain Layout

</grid>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The xml lines above can be translated as: the grid_A composed of a domain_A
 that is defined somewhere else before.
 More precisely, the grid grid_A is constituted of a 
\begin_inset Quotes eld
\end_inset

unknown id
\begin_inset Quotes erd
\end_inset

 domain which has inherited all attributes (and their values) from domain
 A (name, long name, i_index, j_index, ...
 etc).
\end_layout

\begin_layout Standard
With this approach, we only define a domain once but reuse it as many time
 as we like in different configurations.
\end_layout

\begin_layout Subsection
Advanced configuration
\end_layout

\begin_layout Standard
One of a new concept which differentiates XIOS 2.0 from its precedent is
 (spatial) transformation, which can be defined inside a domain.
 All transformations on a domain have form *_domain.
 See Chapter 
\begin_inset CommandInset ref
LatexCommand ref
reference "chap:Transformation"

\end_inset

 for more details.
\end_layout

\begin_layout Section
Working with FORTRAN code
\end_layout

\begin_layout Standard
One of the important concepts to grasp in mind in using FORTRAN interface
 is the data distribution.
 With a distributed-memory XIOS, data are broken into disjoint blocks, one
 per client process.
 In the next sections, local describes everything related to a client process,
 whereas global means global data.
 The followings describe the essential parts of domain.
 Details of its attributes and operations can be found in XIOS reference
 guide
\end_layout

\begin_layout Subsection
Domain type
\end_layout

\begin_layout Standard
Domain is a two dimensional coordinates, which can be considered to be composed
 of two axis: y-axis and x-axis.
 However, different from two axis composed mechanically, a domain contains
 more typical information which play an important role in specific cases.
 Very often, in meteorological applications, domain represents a surface
 with latitude and longitude.
 Because these properties change from one domain type to another, it is
 recommended to use domain in case of representing a surface.
\end_layout

\begin_layout Standard
In XIOS, a domain can be represented by one of three different types of
 coordinate system which also differentiate the way to represent latitude
 and longitude correspondingly.
 
\end_layout

\begin_layout Itemize
rectilinear: a simple 2-dimensional Cartesian coordinates with two perpendicular
 axes.
 Latitude represents the y-axis while longitude represents the x-axe.
\end_layout

\begin_layout Itemize
curvilinear: a 2-dimensional coordinates allows the generality of two axes
 not perpendicular to each other.
 Latitude and longitude have the size equivalent to size of local domain.
 
\end_layout

\begin_layout Itemize
unstructured: not any of two above, the latitude and longitude, as curvilinear,
 are represented with the help of boundaries.
 
\end_layout

\begin_layout Standard
Different from XIOS 1.0, in this new version, users must explicitly specify
 the type of domain which they would like to use
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
inline false
status open

\begin_layout Plain Layout

CALL xios_set_domain_attr("domain_A",type='rectilinear')
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Although there are different domain types, they share the similar patterns
 to settle local data on a client process: There are some essential attributes
 to define.
 The next sections describe their meanings and how to specify correctly
 data for a local domain.
\end_layout

\begin_layout Subsection
Local domain index
\end_layout

\begin_layout Standard
It is not uncommon that a global domain is broken into several pieces, each
 of which is distributed to one process.
 Following, we consider a simple case: a domain of rectilinear type with
 global size 9 x 9 and its data is distributed evenly among 9 client processes,
 each of which has 3x3.
\end_layout

\begin_layout Standard
\begin_inset Float figure
placement !tbph
wide false
sideways false
status open

\begin_layout Plain Layout
\begin_inset Graphics
        filename ../images/Distributed_Domain.pdf
        lyxscale 50
        scale 60

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Global domain data
\end_layout

\end_inset


\begin_inset CommandInset label
LatexCommand label
name "globalDomain"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
The region of local domain can be described by one of the following way.
\end_layout

\begin_layout Standard
Specify the the beginning and size of local domain with:
\end_layout

\begin_layout Itemize
ibegin, jbegin: global position on x-axis and y-axis where a local domain
 begin
\end_layout

\begin_layout Itemize
ni, nj: local size of domain of each process on x-axis and y-axis
\end_layout

\begin_layout Itemize
ni_glo, nj_glo: global size of x-axis and y-axis correspondingly.
 
\end_layout

\begin_layout Standard
Or tell XIOS exactly the global position of each point in the local domain,
 from left to right, top to bottom with:
\end_layout

\begin_layout Itemize
i_index, j_index: array of global position of every point in the local domain.
 It is very useful when local domains do not align with each other.
\end_layout

\begin_layout Standard
For example, with the first method, the local domain in the middle (the
 blue one) can be specified with:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
inline false
status open

\begin_layout Plain Layout

CALL xios_set_domain_attr("domain_A",ni_glo=9, nj_glo=9, ibegin=3, ni=3,
 jbegin=3, nj=3)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The second method demands only two arrays:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
inline false
status open

\begin_layout Plain Layout

CALL xios_set_domain_attr("domain_A",ni_glo=9, nj_glo=9, i_index=iIndex,
 j_index=jIndex)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
and 
\end_layout

\begin_layout Itemize
iIndex={3,4,5,3,4,5,3,4,5}, jIndex = {3,3,3,4,4,4,5,5,5}
\end_layout

\begin_layout Subsection
Local domain data
\end_layout

\begin_layout Standard
Similar to define local index, local data can be done in two ways.
\end_layout

\begin_layout Standard
Specify the beginning and size of data on the local domain:
\end_layout

\begin_layout Itemize
data_ibegin, data_jbegin: the local position of data on x-axis and y-axis
 where data begins inside the local domain
\end_layout

\begin_layout Itemize
data_ni, data_nj: size of data on each axis
\end_layout

\begin_layout Standard
Or specify data with its position in the local domain, from left to right,
 top to bottom with
\end_layout

\begin_layout Itemize
data_i_index, data_j_index: array of local position of data in the local
 domain.
\end_layout

\begin_layout Standard
Beside the attributes above, one of the essential attributes to define is
 dimensional size of data - data_dim.
 Although domain has two dimensions, data are not required to be 2-dimensional.
 In particular, for case of data_dim == 1, XIOS uses an 
\shape italic
1-dimensional block distribution
\shape default
 of data, distributed along the first dimension, the x-axis.
\end_layout

\begin_layout Standard
With the first way to define data on a local domain, we can use:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
inline false
status open

\begin_layout Plain Layout

CALL xios_set_domain_attr("domain_A",data_dim=2, data_ibegin=-1, data_ni=ni+2,
 data_jbegin=-1, data_nj=nj+2)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
In order to be processed correctly, data must be specified with the beginning
 and size of its block .
 For two-dimensional data, it can be done with data_ibegin, data_ni for
 the first dimension and data_jbegin, data_nj for the second dimension.
 In case of one-dimensional data, it is only necessary to determine data_ibegin
 and data_ni.
 Although the valid data must be inside a local domain, it is not necessary
 for data to have same size as local domain.
 In fact, data can have larger size than domain on each dimension, this
 is often the case of 
\begin_inset Quotes eld
\end_inset

ghost cell
\begin_inset Quotes erd
\end_inset

.
 The attributes data_ibegin and data_jbegin specify the offset of data from
 local domain.
 For local domain_A, the negative value indicates that data is larger than
 local domain, the valid part of data needs extracted from the real data.
 A positive value indicates data is smaller than local domain.
 The default value of data_ibegin/data_jbegin is 0, which implies that data
 fit into local domain properly.
 
\end_layout

\begin_layout Standard
\begin_inset Float figure
placement !tbph
wide false
sideways false
status open

\begin_layout Plain Layout
\begin_inset Graphics
        filename ../images/Domain.pdf
        lyxscale 50
        scale 60

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Local domain with data
\end_layout

\end_inset


\begin_inset CommandInset label
LatexCommand label
name "localDomain"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
On Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "localDomain"

\end_inset

, local domain occupies the center of the global domain, where real data
 fill up a larger region.
 Only data inside the local domain, represented by blue cells, are valid.
  
\end_layout

\begin_layout Standard
With the second way, data can be represented with:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
inline false
status open

\begin_layout Plain Layout

CALL xios_set_domain_attr("domain_A",data_dim=2, data_i_index=dataI, data_j_inde
x=dataJ)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
with
\end_layout

\begin_layout Itemize
dataJ = {-1,-1,-1,-1,-1,0,0,0,0,0,1,1,1,1,1,2,2,2,3,3,3,3,3}
\end_layout

\begin_layout Itemize
dataI = {-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}
\end_layout

\begin_layout Standard
As mentioned, data on a domain are two-dimensional but in some cases, there
 is a need to write data continuously, there comes one-dimensional data.
 With the precedent example, we can define one dimensional data with:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
inline false
status open

\begin_layout Plain Layout

CALL xios_set_domain_attr("domain_A",data_dim=1, data_i_index=dataI)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
and 
\end_layout

\begin_layout Itemize
dataI = {-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}
\end_layout

\begin_layout Standard
Above are the mandatory attributes to define local domain.
 There are some auxiliary attributes which make data meaningful, especially
 for meteorological one.
 The next section discuses these attributes.
\end_layout

\begin_layout Subsection
Longitude and latitude
\end_layout

\begin_layout Standard
Different from the previous version, in XIOS 2.0, longitude and latitude
 are optional.
 Moreover, to be coherent to the data_dim concept, there are more ways to
 input longitude and latitude values.
\end_layout

\begin_layout Standard
Like data, longitude and latitude values can be one or two dimension.
 The first ones are represented with lonvalue_1d, latvalue_1d; the second
 ones are specified with lonvalue_2d and latvalue_2d.
\end_layout

\begin_layout Standard
With the same domain_A, we can set longitude and latitude values by calling:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
inline false
status open

\begin_layout Plain Layout

CALL xios_set_domain_attr("domain_A",lonvalue_1d=lon1D, latvalue_1d=lat1D)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
with
\end_layout

\begin_layout Itemize
lon1D = {30, 40, 50, 30, 40, 50, 30, 40, 50}
\end_layout

\begin_layout Itemize
lat1D = {30, 30, 30, 40, 40, 40, 50, 50, 50}
\end_layout

\begin_layout Standard
Or by using two-dimension longitude and latitude
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
inline false
status open

\begin_layout Plain Layout

CALL xios_set_domain_attr("domain_A",lonvalue_2d=lon2D, latvalue_1d=lat2D)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
with 
\end_layout

\begin_layout Itemize
lon2D = {
\begin_inset Formula $\begin{array}{ccc}
30 & 40 & 50\\
30 & 40 & 50\\
30 & 40 & 50
\end{array}$
\end_inset

}
\end_layout

\begin_layout Itemize
lat1D = { 
\begin_inset Formula $\begin{array}{ccc}
30 & 30 & 30\\
40 & 40 & 40\\
50 & 50 & 50
\end{array}$
\end_inset

}
\end_layout

\begin_layout Standard
For unstructured mesh, a cell can have different number of vertices than
 rectilinear, in this case, longitude and latitude value of the vertex of
 cell are specified with bounds_lon_1d and bounds_lat_1d.
\end_layout

\begin_layout Standard
For curvilinear mesh, bounds_lon_2d and bounds_lat_2d provide a convenient
 way to define longitude and latitude value for the vertex of the cell.
 However, it is possible to use bounds_lon_1d and bounds_lat_1d to describe
 these values.
\end_layout

\begin_layout Standard
One thing to remind, only *_1d or *_2d attributes are used, if *_1d and
 *_2d of a same attribute are provides, there will be run-time error.
\end_layout

\begin_layout Standard
All attributes of domain can be found in Reference Guide.
\end_layout

\end_body
\end_document