P_BExchange_init.3

.TH P_BExchange 3 "10/19/2001" " " "ParLib 1.1"
.SH NAME
P_BExchange_init, P_BExchange_start, P_BEchange_end, P_BExchange_free \-  Perform nonblocking boundary exchange
.SH SYNOPSIS
.nf
\fB#include "parlib.h"\fR

\fBint P_BExchange_init(\fR int ndims, int *stride, int *blklen, int bdim, 
      int overlap[2], MPI_Datatype datatype, MPI_Comm comm, 
      int period, BExchange *bexchange \fB);\fR
\fBint P_BExchange_start(\fR void *arr, BExchange *bexchange \fB);\fR
\fBint P_BExchange_end(\fR BExchange *bexchange \fB);\fR
\fBint P_BExchange_free(\fR BExchange *bexchange \fB);\fR
.fi
.SH ARGUMENTS
.PD 0
.TP
.B arr
- address of the local part of communicated array (choice)
.PD 1
.PD 0
.TP
.B ndims
- number of dimensions of the array (positive integer)
.PD 1
.PD 0
.TP
.B stride
- dimensions of the array (array of \fIndims\fR positive integers)
.PD 1
.PD 0
.TP
.B blklen
- sizes of communicated blocks (array of \fIndims\fR positive integers)
.PD 1
.PD 0
.TP
.B bdim
- decomposed dimension of the array \fIarr\fR (integer from the range [1,\fIndims\fR])
.PD 1
.PD 0
.TP
.B overlap
- thickness of boundaries (array of 2 nonnegative integers)
.PD 1
.PD 0
.TP
.B datatype
- datatype of each array element (MPI handle)
.PD 1
.PD 0
.TP
.B comm
- communicator (MPI handle)
.PD 1
.PD 0
.TP
.B period
- logical variable specifying weather the bounfary exchange is periodic (true) or not (false)
.PD 1
.PD 0
.TP
.B bexchange
- pointer to a structure \fIBExchange\fR

.SH DESCRIPTION
The routine set exchanges interprocessor boundaries of array \fIarr\fR, whose dimension \fIbdim\fR is distributed among \fInproc\fR processors of the group defined by communicator \fIcomm\fR in nonblocking mode.

\fBP_BExchange_init ()\fR builds data types required for the exchange

\fBP_BExcahge_start ()\fR starts the exchange

\fBP_BExcahnge_end ()\fR waits for the completion of the exchange

\fBP_BExchange_free ()\fR deallocates memory allocated by the routine \fBP_BExchange_init ()\fR

We will use Matlab notations for indexes of array \fIarr\fR specifying only the index corresponding to dimension \fIbdim\fR while assuming implicitly the others to be \fI1:blklen(idim)\fR, where \fIidim\fR is the dimension number.

The exchange is performed as follows.
If the processor \fIiproc\fR is not the first processor of the group, it sends \fIarr(1:overlap(1))\fR to processor \fIiproc-1\fR.
Similarly, if it is not the last one, it sends \fIarr(blklen(bdim)-overlap(2)+1:blklen(bdim))\fR to  processor \fIiproc+1\fR.

If \fIperiod\fR is true, then the first processor also sends \fIarr(1:overlap(1))\fR to the last one and the last sends \fIarr(blklen(bdim)-overlap(2)+1:blklen(bdim))\fR to the first processor.

.SH NOTES FOR FORTRAN
All INM ParLib routines in Fortran have an additional argument
.I ierr
at the end of the argument list.
.I ierr
is an integer and has the same meaning as the return value of the routine
in C.  In Fortran, INM ParLib routines are subroutines, and are invoked 
with the
.I call
statement.

All INM ParLib objects (e.g., \fIBExchange\fR, \fITransposition\fR) are \fIINTEGER\fR arrays of size \fIHANDLE_SIZE\fR in Fortran.
The parameter \fIHANDLE_SIZE\fR is defined in 'parlibf.h' which is recommended to be included in Fortran code beforehand.

.SH COUTION
Pointer \fIarr\fR should contain the address of the local part of the array that does not include the adjacent halo regions dedicated for the boundaries which have to be received from the neighbors.

.SH ERRORS
The routine returns the following error codes:
.RS 3
.TP
.PD 0
.TP
.B 0
- No error; the routine completed successfully.
.PD 1
.PD 0
.TP
.B 1
- Nonpositive number of dimensions.
.PD 1
.PD 0
.TP
.B 2
- Dimension 
.I bdim
is out of range [1,\fIndims\fR].
.PD 1
.PD 0
.TP
.B 3
- Negative boundary thickness.
.PD 1
.PD 0
.TP
.B 4
- Nonpositive array dimension.
.PD 1
.PD 0
.TP
.B 5
- Boundary thickness exceeds the block size for dimension 
.I 
bdim

.SH SEE ALSO
\fBP_BExchange\fR(3)

.SH AUTHOR
Val N. Gloukhov, gluhoff@inm.ras.ru