MPI Subroutine Reference

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