YetAnotherCoupler  1.2.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
YetAnotherCoupler Documentation
yak_small.jpg

Autors

Moritz Hanke, Rene Redler

Copyright

Copyright 2013 by DKRZ and MPI-M.

License

YAC is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

YAC is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy (COPYING) of the GNU General Public License along with YAC. If not, see http://www.gnu.org/licenses/gpl.txt.

Code Availability

Tagged versions of the software are available upon request. Please contact

Moritz Hanke ( hanke at dkrz.de ) or Rene Redler ( rene.redler at mpimet.mpg.de )

and provide your name, institution and a few lines describing your intention with yac.

Rationale

"A complete rewrite of legacy science software, with a specific focus on clarity, can prove useful. It uncovers bugs, provide a definitive statement of the underlying algorithm, lets scientists easily pose and answer new research questions, makes it easier to develop new visualizations and other interfaces, and makes the code considerably more accessible to interested third parties and the public."

[N. Barnes and D. Jones, 2011: Clear Climate Code: Rewriting Legacy Science Software for Clarity. IEEE Software, Nov/Dec 2011, 36 - 42.]

The YAC development started as a pilot study to investigate the coupling between unstructured meshes. Rather than implementing all required functionality directly into an existing coupler like OASIS4 we decided to ground our effort on a light weight software infrastructure. In order not to repeat the problems we encounter with OASIS4 we stick to the following:

The information about the connectivity has to be provided by the user in all cases.
Grid points and elements of the halo have to be provided by the user.
Information about the process on which the halo points are located have to be provided by the user.
Only unstructured and fully regular grids are supported directly.
Internally, grid information and exchange fields are handled as double.
Fortran reals are converted to double precision before delivering it to the C world.

Software Design

The coupling and associated tasks can be grouped into four different phases, the initialisation and definition phase; the neighbourhood search and calculation of interpolation weights; the data exchange; and the finalisation of the coupling.

In the initialisation phase the grids and coupling fields are defined by the user via the user interfaces. The initialisation and definition phase is terminated with a single command which at the same time invokes the neighbourhood search and calculation of weights. The data exchange consists of pairs of calls to send and receive routines while the end of the coupling is announced with a single finalising call. On this abstract level we closely follow the OASIS4 paradigm with the side effect of keeping the YAC Fortran user interface very similar to OASIS4.

In order to overcome some problems we encountered with the OASIS4 user interface and the software design we took the freedom to deviate where needed from the OASIS4 specification. At the same time we use this development to get practical experience with the git version control system, inline documentation like Doxygen, and autoconf for the configuration management.

YAC is programmed in C, user interfaces to Fortran (prefix yac_f) and C (prefix yac_c) are available. The Fortran interface is provided using the ISO-C standard.

C User Interface in interface.h
yac_cinit
yac_cdef_comp
yac_cdef_datetime
yac_cget_localcomm
yac_cdef_subdomain
yac_cconnect_subdomains
yac_cdef_points_reg2d
yac_cdef_points_unstruct
yac_cdef_elements_reg2d
yac_cdef_elements_unstruct
yac_cdef_mask
yac_cdef_index_location
yac_cdef_field
yac_csearch
yac_cput
yac_cget
yac_cfinalize
yac_cget_nbr_fields
yac_cget_field_ids
yac_cget_field_id_from_name
yac_cget_field_name_from_id
yac_cget_role_of_field_by_id
yac_cget_role_of_field_by_name
yac_cget_coupling_timestep_id
yac_cget_coupling_timestep_name
yac_cget_model_timestep_id
yac_cget_model_timestep_name
yac_cget_pair_rootcomm
yac_redirstdout
yac_abort_message
Fortran User Interface in yac_finterface.f90 and mo_yac_finterface.f90
yac_finit
yac_fdef_comp
yac_fdef_datetime
yac_fget_localcomm
yac_fdef_subdomain
yac_fconnect_subdomains
yac_fdef_points (*)
yac_fdef_elements (*)
yac_fdef_mask (*)
yac_fdef_index_location
yac_fget_field_ids
yac_fsearch
yac_fput (*)
yac_fget (*)
yac_ffinalize
yac_fget_field_ids
yac_fget_nbr_fields
yac_fget_field_id_from_name
yac_fget_field_name_from_id
yac_fget_role_of_field (*)
yac_fget_model_timestep (*)
yac_fget_coupling_timestep (*)
yac_cget_pair_rootcomm
yac_redirstdout
yac_abort_message

Functions marked with (*) are overloaded with respect to the data type. See mo_yac_finterface.f90 for details.

The user interface is detailed in the Doxygen documentation which is not repeated here. Rather we provide a brief explanation of the vocabulary that we use in the code which may also help to understand to basic concept behind YAC and how to implement the user interface in the application code.

The GUI come with its own documentation available in the local distribution or repository under gui/doc/index.html.

Glossary

grid
an abstract entity under which all relevant information of one subdomain is collected.
domain
the complete compute domain on a process
subdomain
a domain may consist of a number of subdomains. Each subdomain is described with a call to def_subdomain, follwowed by def_elements and def_points.
points
geographical positions where physical quantities are located
elements
or cells, can be considered as the control volume around a point.