MPI_CART_CREATE, MPI_Cart_create

Purpose

Creates a communicator containing topology information.

C synopsis

#include <mpi.h>
int MPI_Cart_create(MPI_Comm comm_old,int ndims,int *dims,
                    int *periods,int reorder,MPI_Comm *comm_cart);

C++ synopsis

#include mpi.h
MPI::Cartcomm MPI::Intracomm::Create_cart(int ndims, const int dims[],
                                          const bool periods[], bool reorder) const;

FORTRAN synopsis

include 'mpif.h' or use mpi
MPI_CART_CREATE(INTEGER COMM_OLD,INTEGER NDIMS,INTEGER DIMS(*),
                INTEGER PERIODS(*),INTEGER REORDER,INTEGER COMM_CART,INTEGER IERROR)

Parameters

comm_old
     is the input communicator (handle) (IN)

ndims
     is the number of cartesian dimensions in the grid (integer) (IN)

dims
     is an integer array of size ndims specifying the number of tasks in
     each dimension (IN)

periods
     is a logical array of size ndims specifying if the grid is periodic or
     not in each dimension (IN)

reorder
     if true, ranking may be reordered. If false, rank in comm_cart must be
     the same as in comm_old. (logical) (IN)

comm_cart
     is a communicator with new cartesian topology (handle) (OUT)

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

Description

This subroutine creates a new communicator that contains cartesian topology
information defined by ndims, dims, periods, and reorder. MPI_CART_CREATE
returns a handle for this new communicator in comm_cart. If there are more
tasks in comm than are required by the grid, some tasks are returned and
comm_cart = MPI_COMM_NULL. comm_old must be an intracommunicator.

Notes

Most or perhaps all MPI implementations before PE MPI 3.1 have ignored
reorder. If you have a program that works with reorder = false and fails
with reorder = true, examine your code for communication on comm_cart using
ranks from comm_old.

Errors

MPI not initialized

Conflicting collective operations on communicator

MPI already finalized

Invalid communicator

Invalid communicator type
     must be intracommunicator

Invalid ndims
     ndims < 0 or ndims > groupsize

Invalid dimension

Related information

     MPI_CART_SUB
     MPI_GRAPH_CREATE