17.2.39. MPI_Cart_shift

MPI_Cart_shift — 根据指定的移动方向和距离，返回移动后的源和目标进程排名。

17.2.39.1. 语法

17.2.39.1.1. C语言语法

#include <mpi.h>

int MPI_Cart_shift(MPI_Comm comm, int direction, int disp,
    int *rank_source, int *rank_dest)

17.2.39.1.2. Fortran语法

USE MPI
! or the older form: INCLUDE 'mpif.h'

MPI_CART_SHIFT(COMM, DIRECTION, DISP, RANK_SOURCE,
        RANK_DEST, IERROR)
    INTEGER COMM, DIRECTION, DISP, RANK_SOURCE
    INTEGER RANK_DEST, IERROR

17.2.39.1.3. Fortran 2008 语法

USE mpi_f08

MPI_Cart_shift(comm, direction, disp, rank_source, rank_dest, ierror)
    TYPE(MPI_Comm), INTENT(IN) :: comm
    INTEGER, INTENT(IN) :: direction, disp
    INTEGER, INTENT(OUT) :: rank_source, rank_dest
    INTEGER, OPTIONAL, INTENT(OUT) :: ierror

17.2.39.2. 输入参数

comm : 具有笛卡尔结构的通信器（句柄）。
direction : 位移的坐标维度（整数）。
disp位移量（> 0：向上移动，< 0：向下移动）
(整数类型)。

17.2.39.3. 输出参数

rank_source : 源进程的排名（整数）。
rank_dest : 目标进程的排名（整数）。
ierror : 仅限Fortran：错误状态（整数）。

17.2.39.4. 描述

如果进程拓扑结构是笛卡尔结构，可能会沿着坐标direction方向使用MPI_Sendrecv操作来执行数据移位。作为输入，MPI_Sendrecv需要接收操作的源进程秩和发送操作的目标进程秩。如果为笛卡尔进程组调用函数MPI_Cart_shift，它会为调用进程提供上述标识符，这些标识符随后可以传递给MPI_Sendrecv。用户需指定坐标direction和步长大小（正或负）。该函数是本地操作。

direction参数表示偏移的维度，即其值会被偏移修改的坐标轴。坐标轴的编号从0到ndims-1，其中ndims是维度的数量。

注意：对于n维笛卡尔网格，direction参数的取值范围是[0, n-1]。

根据笛卡尔群在指定坐标direction方向上的周期性，MPI_Cart_shift会提供循环移位或末端移位的标识符。在末端移位的情况下，可能会在rank_source或rank_dest中返回MPI_PROC_NULL值，表示移位操作的源或目标已超出范围。

示例：通信器comm关联着一个二维周期性笛卡尔拓扑结构。一个二维实数数组的每个元素分别存储在各进程的变量A中。现需要对该数组进行斜移操作——将第i列（垂直方向，即沿列方向）移动i步。

! find process rank
    CALL MPI_COMM_RANK(comm, rank, ierr)
! find Cartesian coordinates
    CALL MPI_CART_COORDS(comm, rank, maxdims, coords, ierr)
! compute shift source and destination
    CALL MPI_CART_SHIFT(comm, 0, coords(2), source, dest, ierr)
! skew array
    CALL MPI_SENDRECV_REPLACE(A, 1, MPI_REAL, dest, 0, source, 0, comm, status,
                              ierr)

17.2.39.5. 注意

在Fortran中，由DIRECTION = i指定的维度具有DIMS(i+1)个节点，其中DIMS是用于创建网格的数组。在C语言中，由direction = i指定的维度是由dims[i]定义的维度。

17.2.39.6. 错误

几乎所有MPI例程都会返回一个错误值；C语言例程通过函数返回值返回，Fortran例程则通过最后一个参数返回。

在返回错误值之前，会调用与通信对象（如通信器、窗口、文件）关联的当前MPI错误处理程序。如果MPI调用未关联任何通信对象，则该调用被视为附加到MPI_COMM_SELF，并将调用关联的MPI错误处理程序。当MPI_COMM_SELF未初始化时（即在MPI_Init/MPI_Init_thread之前、MPI_Finalize之后，或仅使用会话模型时），错误会触发初始错误处理程序。初始错误处理程序可通过在使用世界模型时调用MPI_Comm_set_errhandler来修改MPI_COMM_SELF，或通过mpiexec的mpi_initial_errhandler命令行参数，或MPI_Comm_spawn/MPI_Comm_spawn_multiple的info键来设置。如果未设置其他适当的错误处理程序，则MPI I/O函数将调用MPI_ERRORS_RETURN错误处理程序，而其他所有MPI函数将调用MPI_ERRORS_ABORT错误处理程序。

Open MPI 包含三个可使用的预定义错误处理器：

MPI_ERRORS_ARE_FATAL 导致程序中止所有连接的MPI进程。
MPI_ERRORS_ABORT 一个可在通信器、窗口、文件或会话上调用的错误处理程序。当在通信器上调用时，其行为类似于在该通信器上调用MPI_Abort。如果在窗口或文件上调用，则行为类似于在包含对应窗口或文件中进程组的通信器上调用MPI_Abort。如果在会话上调用，则仅中止本地进程。
MPI_ERRORS_RETURN 向应用程序返回一个错误代码。

MPI应用程序也可以通过调用以下方式实现自己的错误处理程序：

请注意，MPI不保证MPI程序在出现错误后能够继续运行。

查看MPI手册页获取完整的MPI错误代码列表。

有关更多信息，请参阅MPI-3.1标准中的错误处理部分。