MPI Subroutine Reference

MPI_CART_SUB, MPI_Cart_sub

Purpose

Partitions a cartesian communicator into lower-dimensional subgroups.

C synopsis

#include <mpi.h>
MPI_Cart_sub(MPI_Comm comm,int *remain_dims,MPI_Comm *newcomm);

C++ synopsis

#include mpi.h
MPI::Cartcomm MPI::Cartcomm::Sub(const bool remain_dims[]) const;

FORTRAN synopsis

include 'mpif.h' or use mpi
MPI_CART_SUB(INTEGER COMM,LOGICAL REMAIN_DIMS(*),INTEGER NEWCOMM,
	     INTEGER IERROR)

Parameters

comm

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

remain_dims

the ith entry of remain_dims specifies whether the ith dimension is kept in the subgrid or is dropped. (logical vector) (IN)

newcomm

is the communicator containing the subgrid that includes the calling task (handle) (OUT)

IERROR

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

Description

If a cartesian topology was created with MPI_CART_CREATE, you can use the function MPI_CART_SUB:

• to partition the communicator group into subgroups forming lower-dimensional cartesian subgrids
• to build a communicator with the associated subgrid cartesian topology for each of those subgroups.

This function is closely related to MPI_COMM_SPLIT.

For example, suppose MPI_CART_CREATE (..., comm) defined a 2 × 3 × 4 grid and remain_dims = (true, false, true). A call to:

MPI_CART_SUB(comm,remain_dims,comm_new),

creates three communicators. Each has eight tasks in a 2 × 4 cartesian topology. If remain_dims = (false, false, true), the call to:

MPI_CART_SUB(comm,remain_dims,comm_new),

creates six non-overlapping communicators, each with four tasks in a one-dimensional cartesian topology.

Errors

MPI not initialized

MPI already finalized

Invalid communicator

Invalid topology

must be cartesian

No topology

Related information

MPI_CART_CREATE

MPI_COMM_SPLIT