MPI_COMM_SPLIT, MPI_Comm_split

Purpose

Splits a communicator into multiple communicators based on color and key.

C synopsis

#include <mpi.h>
int MPI_Comm_split(MPI_Comm comm_in, int color, int key, MPI_Comm *comm_out);

C++ synopsis

#include mpi.h
MPI::Intercomm MPI::Intercomm::Split(int color, int key) const;

#include mpi.h
MPI::Intracomm MPI::Intracomm::Split(int color, int key) const;

FORTRAN synopsis

include 'mpif.h' or use mpi
MPI_COMM_SPLIT(INTEGER COMM_IN, INTEGER COLOR, INTEGER KEY,
    INTEGER COMM_OUT, INTEGER IERROR)

Parameters

comm_in
     is the original communicator (handle) (IN)

color
     is an integer specifying control of subset assignment (IN)

key
     is an integer specifying control of rank assignment (IN)

comm_out
     is the new communicator (handle) (OUT)

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

Description

MPI_COMM_SPLIT is a collective operation that partitions the group
associated with comm_in into disjoint subgroups, one for each value of
color. Each subgroup contains all tasks of the same color. Within each
subgroup, the tasks are ranked in the order defined by the value of the
argument key. Ties are broken according to their rank in the old group. A
new communicator is created for each subgroup and returned in comm_out. If
a task supplies the color value MPI_UNDEFINED, comm_out returns
MPI_COMM_NULL. Even though this is a collective operation, each task is
allowed to provide different values for color and key.

The value of color must be greater than or equal to 0.

Notes

The result of MPI_COMM_SPLIT on an intercommunicator is that those tasks on
one side of the intercommunicator with the same color as those tasks on the
other side of the intercommunicator combine to create a new
intercommunicator. The key argument describes the relative rank of tasks on
each side of the intercommunicator. For those colors that are specified
only on one side of the intercommunicator, MPI_COMM_NULL is returned.
MPI_COMM_NULL is also returned to those tasks that specify MPI_UNDEFINED as
the color.

Errors

Fatal errors:

Conflicting collective operations on communicator

Invalid color
     color < 0

Invalid communicator

MPI not initialized

MPI already finalized

Related information

     MPI_CART_SUB