MPI_CART_SHIFT, MPI_Cart_shift

Purpose

Returns shifted source and destination ranks for a task.

C synopsis

#include <mpi.h>
MPI_Cart_shift(MPI_Comm comm,int direction,int disp,
               int *rank_source,int *rank_dest);

C++ synopsis

#include mpi.h
void MPI::Cartcomm::Shift(int direction, int disp, int &rank_source,
                          int &rank_dest) const;

FORTRAN synopsis

include 'mpif.h' or use mpi
MPI_CART_SHIFT(INTEGER COMM,INTEGER DIRECTION,INTEGER DISP,
               INTEGER RANK_SOURCE,INTEGER RANK_DEST,INTEGER IERROR)

Parameters

comm
     is a communicator with cartesian topology (handle) (IN)

direction
     is the coordinate dimension of shift (integer) (IN)

disp
     is the displacement (> 0 = upward shift, < 0 = downward shift)
     (integer) (IN)

rank_source
     is the rank of the source task (integer) (OUT)

rank_dest
     is the rank of the destination task (integer) (OUT)

IERROR
     is the FORTRAN return code. It is always the last argument.

Description

This subroutine shifts the local rank along a specified coordinate
dimension to generate source and destination ranks.

rank_source is obtained by subtracting disp from the nth coordinate of the
local task, where n is equal to direction. Similarly, rank_dest is obtained
by adding disp to the nth coordinate. Coordinate dimensions (direction) are
numbered starting with 0.

If the dimension specified by direction is non-periodic, off-end shifts
result in the value MPI_PROC_NULL being returned for rank_source or
rank_dest or both.

Notes

In C and FORTRAN, the coordinate is identified by counting from 0. For
example, FORTRAN A(X,Y) or C A[x] [y] both have x as direction 0.

Errors

MPI not initialized

MPI already finalized

Invalid communicator

Invalid topology type
     must be cartesian

No topology

Related information

     MPI_CART_COORDS
     MPI_CART_CREATE
     MPI_CART_RANK