#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 \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. 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 \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 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 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 \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 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 or calculate the weights on the fly. \end_layout \begin_layout Itemize generate_rectilinear_domain: auto generating, distributing a rectilinear domain then filling all mandatory attributes. \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 \end_layout \begin_layout Plain Layout \end_layout \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 concrete example above tells many things: a domain named domain_A_zoom is transformed from domain name domain_A with a zoom activity. The domain_A_zoom is the zoomed region of domain_A. 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 \end_layout \begin_layout Plain Layout \end_layout \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 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 \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 Although xml is helpful to define several configurations, it is not convenient 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 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-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 local 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",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 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 local domain, it is not neccessary 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 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 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 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 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 runtime error. \end_layout \begin_layout Standard All attributes of domain can be found in Reference Guide. \end_layout \end_body \end_document