Yet Another eXchange Tool  0.9.2.1
The concept of yaxt

Introduction

Concept

The usage of yaxt can be divided into several steps:

  • define global indices
  • describe local data using global indices (=> index list)
  • use yaxt to generate a transition from one index list to another (=> xmap)
  • describe local data layout (offsets and mpi datatype)
  • use yaxt to combine xmap and data layout (=> redist)
  • optionally aggregate multiple redists
  • use yaxt to execute collective data exchange(s)
  • clean up

global indices

Global indices are used in yaxt as abstraction of global data points, i.e., they are integer numbers that allow to identify any data point. The concrete values of these indices have no meaning for yaxt and can be choosen freely as long as the values are used consistently when describing different sequences of data points.

index list

An index list (Xt_idxlist) is a sequence of global indices describing local data points. E.g., data points calculated locally ("owned by this process") or data points that are calculated on a different process but are required locally (e.g., halo points). The order of indices must be consistent with the order of offsets used to describe the local data layout. Yaxt offers a variety of methods to generate index lists (see How to generate an index list).

xmap

Using two index lists - one representing source data points and one representing target data points - given on all processes within a mpi communicator, yaxt can calculate an abstract communication pattern ("a pattern for indices") if such a pattern exists, i.e., if for each given local target index there exists an equal source index, local or remote. Yaxt stores this pattern in an exchange map (Xt_xmap). It is an user error if such a pattern does not exist. There are multiple algorithms available to generate exchange maps (see Algorithms to generate exchange maps). It is not unusual that the same index list is used to construct different xmaps where the role of souce and target data points changes, e.g., for global transpositions.

redistribution object

An abstract communication pattern (xmap) together with data layout information (offsets and MPI datatype of local data points) can be used to create a redistribution object (Xt_redist). It contains all the information required to execute a collective communication that establishes the target state (e.g., updated halo points). It is possible to merge multiple redistribution objects into a single one (see How to merge multiple redistributions).

data exchange

The exchange can be executed by a blocking call to xt_redist_s_exchange or xt_redist_s_exchange1 (only possible for non-merged redistributions).

Clean up

If a yaxt object is not needed anymore then it can be deleted by the respective delete calls (e.g. xt_idxlist_delete).