[97] | 1 | .\"Copyright 2006-2008 Sun Microsystems, Inc. |
---|
| 2 | .\"Copyright (c) 1996 Thinking Machines |
---|
| 3 | .TH MPI_Cart_shift 3 "Dec 08, 2009" "1.4" "Open MPI" |
---|
| 4 | .SH NAME |
---|
| 5 | \fBMPI_Cart_shift \fP \- Returns the shifted source and destination ranks, given a shift direction and amount. |
---|
| 6 | |
---|
| 7 | .SH SYNTAX |
---|
| 8 | .ft R |
---|
| 9 | .SH C Syntax |
---|
| 10 | .nf |
---|
| 11 | #include <mpi.h> |
---|
| 12 | int MPI_Cart_shift(MPI_Comm \fIcomm\fP, int\fI direction\fP, int\fI disp\fP, |
---|
| 13 | int\fI *rank_source\fP, int\fI *rank_dest\fP) |
---|
| 14 | |
---|
| 15 | .SH Fortran Syntax |
---|
| 16 | .nf |
---|
| 17 | INCLUDE 'mpif.h' |
---|
| 18 | MPI_CART_SHIFT(\fICOMM, DIRECTION, DISP, RANK_SOURCE, |
---|
| 19 | RANK_DEST, IERROR\fP) |
---|
| 20 | INTEGER \fICOMM, DIRECTION, DISP, RANK_SOURCE\fP |
---|
| 21 | INTEGER \fIRANK_DEST, IERROR\fP |
---|
| 22 | |
---|
| 23 | .SH C++ Syntax |
---|
| 24 | .nf |
---|
| 25 | #include <mpi.h> |
---|
| 26 | void Cartcomm::Shift(int \fIdirection\fP, int \fIdisp\fP, int& \fIrank_source\fP, |
---|
| 27 | int& \fIrank_dest\fP) const |
---|
| 28 | |
---|
| 29 | .SH INPUT PARAMETERS |
---|
| 30 | .ft R |
---|
| 31 | .TP 1i |
---|
| 32 | comm |
---|
| 33 | Communicator with Cartesian structure (handle). |
---|
| 34 | .TP 1i |
---|
| 35 | direction |
---|
| 36 | Coordinate dimension of shift (integer). |
---|
| 37 | .TP 1i |
---|
| 38 | disp |
---|
| 39 | Displacement ( > 0: upward shift, < 0: downward shift) (integer). |
---|
| 40 | |
---|
| 41 | .SH OUTPUT PARAMETERS |
---|
| 42 | .ft R |
---|
| 43 | .TP 1i |
---|
| 44 | rank_source |
---|
| 45 | Rank of source process (integer). |
---|
| 46 | .TP 1i |
---|
| 47 | rank_dest |
---|
| 48 | Rank of destination process (integer). |
---|
| 49 | .ft R |
---|
| 50 | .TP 1i |
---|
| 51 | IERROR |
---|
| 52 | Fortran only: Error status (integer). |
---|
| 53 | |
---|
| 54 | .SH DESCRIPTION |
---|
| 55 | .ft R |
---|
| 56 | If the process topology is a Cartesian structure, an MPI_Sendrecv operation is likely to be used along a coordinate direction to perform a shift of data. As input, MPI_Sendrecv takes the rank of a source process for the receive, and the rank of a destination process for the send. If the function MPI_Cart_shift is called for a Cartesian process group, it provides the calling process with the above identifiers, which then can be passed to MPI_Sendrecv. The user specifies the coordinate direction and the size of the step (positive or negative). The function is local. |
---|
| 57 | .sp |
---|
| 58 | The direction argument indicates the dimension of the shift, i.e., the coordinate whose value is modified by the shift. The coordinates are numbered from 0 to ndims-1, where ndims is the number of dimensions. |
---|
| 59 | .sp |
---|
| 60 | \fBNote:\fP The direction argument is in the range [0, n-1] for an n-dimensional Cartesian mesh. |
---|
| 61 | .sp |
---|
| 62 | Depending on the periodicity of the Cartesian group in the specified coordinate direction, MPI_Cart_shift provides the identifiers for a circular or an end-off shift. In the case of an end-off shift, the value MPI_PROC_NULL may be returned in rank_source or rank_dest, indicating that the source or the destination for the shift is out of range. |
---|
| 63 | .sp |
---|
| 64 | \fBExample:\fP The communicator, comm, has a two-dimensional, periodic, Cartesian topology associated with it. A two-dimensional array of REALs is stored one element per process, in variable A. One wishes to skew this array, by shifting column i (vertically, i.e., along the column) by i steps. |
---|
| 65 | .sp |
---|
| 66 | .nf |
---|
| 67 | \&.... |
---|
| 68 | C find process rank |
---|
| 69 | CALL MPI_COMM_RANK(comm, rank, ierr)) |
---|
| 70 | C find Cartesian coordinates |
---|
| 71 | CALL MPI_CART_COORDS(comm, rank, maxdims, coords, |
---|
| 72 | ierr) |
---|
| 73 | C compute shift source and destination |
---|
| 74 | CALL MPI_CART_SHIFT(comm, 0, coords(2), source, |
---|
| 75 | dest, ierr) |
---|
| 76 | C skew array |
---|
| 77 | CALL MPI_SENDRECV_REPLACE(A, 1, MPI_REAL, dest, 0, |
---|
| 78 | source, 0, comm, status, |
---|
| 79 | ierr) |
---|
| 80 | .fi |
---|
| 81 | |
---|
| 82 | .SH NOTE |
---|
| 83 | In Fortran, the dimension indicated by DIRECTION = i has DIMS(i+1) nodes, where DIMS is the array that was used to create the grid. In C, the dimension indicated by direction = i is the dimension specified by dims[i]. |
---|
| 84 | |
---|
| 85 | .SH ERRORS |
---|
| 86 | Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument. C++ functions do not return errors. If the default error handler is set to MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism will be used to throw an MPI:Exception object. |
---|
| 87 | .sp |
---|
| 88 | Before the error value is returned, the current MPI error handler is |
---|
| 89 | called. By default, this error handler aborts the MPI job, except for I/O function errors. The error handler may be changed with MPI_Comm_set_errhandler; the predefined error handler MPI_ERRORS_RETURN may be used to cause error values to be returned. Note that MPI does not guarantee that an MPI program can continue past an error. |
---|
| 90 | |
---|