MPI_Comm_split(3)

NAME
     MPI_Comm_split - Creates new communicators based on colors and keys

SYNOPSIS
     C:

          #include <mpi.h>

          int MPI_Comm_split ( comm, color, key, comm_out )
          MPI_Comm  comm;
          int       color, key;
          MPI_Comm *comm_out;


     C++:

          #include <mpi.h>

          Intracomm Intracomm::Split(
          int               color,
          int               key) const


     Fortran:

          INCLUDE "mpif.h" (or USE MPI)

          INTEGER comm, color, key, newcomm, ierror

          CALL MPI_COMM_SPLIT(comm, color, key, newcomm,
          ierror)


STANDARDS
     This release implements the MPI 1.2 standard, as documented by the MPI
     Forum in the spring 1997 release of MPI:  A Message Passing Interface
     Standard.

DESCRIPTION
     The MPI_Comm_split routine creates new communicators based on colors and
     keys.  This routine accepts the following parameters:

     comm      Specifies the communicator. (handle)

     color     Specifies the control of subset assignment. color must be
               nonnegative or MPI_UNDEFINED. (nonnegative integer)

     key       Specifies the control of rank assignment. (integer)

     comm_out  Returns a new communicator. (handle)
     ierror    Specifies the return code value for successful completion,
               which is in MPI_SUCCESS.  MPI_SUCCESS is defined in the mpif.h
               file.

NOTES
     The algorithm that is used for creating new communicators based on colors
     and keys is as follows:

     1.   A table of colors and keys is built (has a next field also).

     2.   The MPI_Allreduce(3) routine is used to merge the tables of all
          processes.

     3.   Two contexts are allocated for all of the communicators to be
          created.  These same two contexts can be used for all created
          communicators because the communicators will not overlap.

     4.   If the local process has a color of MPI_UNDEFINED, it can return a
          null communicator.

     5.   The table entries that match the local process color are sorted by
          key and rank.

     6.   A group is created from the sorted list and a communicator is
          created with this group and the previously allocated contexts.

     Note:  This algorithm contains inefficiencies that can be removed.

SEE ALSO
     MPI_Allreduce(3)