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

#LyX 2.1 created this file. For more info see http://www.lyx.org/
\lyxformat 474
\begin_document
\begin_header
\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
\font_sans default
\font_typewriter default
\font_math auto
\font_default_family default
\use_non_tex_fonts false
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 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.
 It is not allowed to have two domains with a same id, but it is permitted
 a domain and a grid, for example, to share a same one.
\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 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 rare to define a domain without id inside domain_definition.
 However, the domain_ref is utilized widely outside the scope of domain_definiti
on.
\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
Moreover 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 differenciates XIOS 2.0 from its precedent is
 transformation.
 In a simple case, zoom feature is now considered to be a transformation.
 It can be more complicated for other geometric transformation such as inversion
 or interpolation.
 All transformation are taken place on grid level.
 It means that it is neccessary to define a grid source and a grid destination
 as well as a transformation or list of transformation which we'd like to
 have.
 In order to transform a grid to one another, we need to specify a transformatio
n on its sub-component: domain or axis.
\end_layout

\begin_layout Standard
Because transformation on a domain is different from one on an axis, we
 differenciate two categories of transformation: transformation_domain and
 transformation_axis.
\end_layout

\begin_layout Standard
Till now, XIOS supports the following transformation on domain:
\end_layout

\begin_layout Itemize
zoom_domain: Like zoom functionality in XIOS 1.0, the destination grid is
 the zoomed region of the source grid.
\end_layout

\begin_layout Itemize
interpolation_domain: Implement interpolation from a domain to one another,
 for now XIOS can only do interpolation by reading calculated weight values
 from a file.
 The calculation on the fly will be implemented soon.
\end_layout

\begin_layout Standard
It is not difficult to define a transformation: Include type of transformation
 inside domain definition, as the following
\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 id="domain_A_zoom" domain_ref="domain_A"> 
\end_layout

\begin_layout Plain Layout

   <zoom_domain zoom_ibegin="1" zoom_ni="3" zoom_jbegin="0" zoom_nj="2"/>
\end_layout

\begin_layout Plain Layout

  </domain>
\end_layout

\begin_layout Plain Layout

</domain_definition>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The concrete example above says many things: a domain named domain_A_zoom
 is transformed from domain name domain_A with a zoom activity.
 The detailed attributes of zoom_domain can be found in reference document,
 but simply it contains the begining and size of zoomed region.
\end_layout

\begin_layout Standard
One remark is the transformed domain SHOULD have an id, in this case, it's
 domain_A_zoom.
 As mentioned before, a no-id domain or any no-id component of XIOS can
 only be used inside its definition scope.
 It exists but is useless.
 So care about that.
\end_layout

\begin_layout Standard
To make use of transformation, the grid must contain domains which reference
 to transformed ones.
 
\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

\begin_layout Plain Layout

<grid id="grid_A_zoom">          
\end_layout

\begin_layout Plain Layout

   <domain domain_ref="domain_A_zoom" />
\end_layout

\begin_layout Plain Layout

 </grid>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
On defining this way, we tell XIOS to establish a connection between two
 grids by a transformation (zoom) with: grid source - grid_A, grid destination
 - grid_A_zoom.
\end_layout

\begin_layout Standard
As mentioned in Grid Chapter, in order to use transformed grid, just reference
 to it in field_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

<field_definition level="1" enabled=".TRUE." default_value="9.96921e+36">
\end_layout

\begin_layout Plain Layout

  <field id="field_A"  operation="average" freq_op="3600s" grid_ref="grid_A"
 />
\end_layout

\begin_layout Plain Layout

  <field id="field_A_zoom"  operation="average" freq_op="3600s" grid_ref="grid_A
_zoom" />
\end_layout

\begin_layout Plain Layout

 </field_definition>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Although xml is helpful to define several configurations, it can not be
 used to customize attributes of domain.
 So it's the turn of Fortran interface.
\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 whole 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-axe 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 whole domain.
 
\end_layout

\begin_layout Itemize
unstructured: not any of two above, the latitutude and longitude, as curvilinear
, are reprensented 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
Althoug 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
ni_glo, nj_glo: global size of x-axis and y-axis correspondingly.
 
\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 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",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 begining 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
\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 begining
 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 domain, it is not neccessary for
 data to have same size as 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, whereas 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 secon 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 continously, 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 auxilliary attributes which make data meaningful, especially
 for meteorological one.
 The next section disscuses these attributes.
\end_layout

\begin_layout Subsection
Longitude and latitude
\end_layout

\begin_layout Standard
Different from the previous version, in XIOS 2.0, lonngitude 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 have longitude and latitude 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
 rectinlinear, 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 curlinear 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 runtime error.
\end_layout

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

\end_body
\end_document