#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
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\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
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\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
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\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
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\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