MPI Subroutine Reference

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