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 W 3 W 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 W 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