MPI_Comm_split function
Partitions the group that is associated with the specified communicator into a specified number of disjoint subgroups.
Syntax
int MPIAPI MPI_Comm_split(
MPI_Comm comm,
int color,
int key,
_Out_ MPI_Comm *newcomm
);
Parameters
comm
The communicator to split.color
The new communicator that the calling process is to be assigned to. The value of color must be non-negative.If a process specifies the color value MPI_UNDEFINED, the function returns MPI_COMM_NULL in the newcomm parameter to the calling process.
key
The relative rank of the calling process in the group of the new communicator. For details on using the key and color parameters, see Remarks.newcomm [out]
On return, contains a handle to a new communicator.
Return value
Returns MPI_SUCCESS on success. Otherwise, the return value is an error code.
In Fortran, the return value is stored in the IERROR parameter.
Fortran
MPI_COMM_SPLIT(COMM,COLOR,KEY,NEWCOMM,IERROR)
INTEGER COMM, COLOR, KEY, NEWCOMM, IERROR
Remarks
This is a collective function, but each process can specify different values for the color and key parameters.
This is an extremely powerful mechanism for dividing a single communicating group of processes into an arbitrary number of subgroups. The number of subgroups is determined by the number of colors that are specified over all the processes. The resulting communicators do not overlap. Subdividing a communicator in this way is useful for defining a hierarchy of computations, such as for multigrid or linear algebra.
Each subgroup contains all the processes that specified the same value for the color parameter. Within each subgroup, the processes are ranked in the order that is defined by the value of the key parameter, with ties broken according to their rank in the old group.
With an intracommunicator communicator, a call to MPI_COMM_CREATE(comm, group, new-comm) is equivalent to a call to MPI_COMM_SPLIT(comm, color, key, newcomm), where processes that are group members specify the number of the group, based on a unique numbering of all disjoint groups, for the color parameter and their rank in the group for the key parameter. All processes that are not members of the group specify MPI_UNDEFINED for the color parameter.
For any one color, the key values do not have to be unique. The MPI_Comm_split function sorts processes in order according to the value of the key parameter, and it sorts ties by their relative rank in the source group. If the same value is specified for all the key parameters, then all the processes in a given color have the same relative rank order that they had in their parent group.
For intracommunicators, the MPI_Comm_split and MPI_Comm_create functions provide similar capability to split a communicating group into disjoint subgroups.
The MPI_Comm_split function is used when some processes do not have complete information of the other members in their group, but all processes have the color of the group to which they belong. In this case, the MPI implementation discovers the other group members via communication.
The MPI_Comm_create function is used when all processes have complete information of the members of their group. In this case, the MPI implementation can avoid the extra communication that is required to discover group membership.
Communicators created by MPI_Comm_split cannot overlap. You can call the MPI_Comm_split function multiple times to overcome this limitation. You can create multiple overlapping communication structures in this way. Creative use of the color and key parameters in such splitting operations is encouraged.
The result of the MPI_Comm_split function on an intercommunicator is that those processes on the left with the same color as those processes on the right combine to create a new intercommunicator. The key parameter defines the relative rank of processes on each side of the intercommunicator. A new communicator with a handle of MPI_COMM_NULL is returned to those processes that specify MPI_UNDEFINED as their color, or specify a color that is only specified on one side of the intercommunicator.
Requirements
Product |
HPC Pack 2012 MS-MPI Redistributable Package, HPC Pack 2008 R2 MS-MPI Redistributable Package, HPC Pack 2008 MS-MPI Redistributable Package or HPC Pack 2008 Client Utilities |
Header |
Mpi.h; Mpif.h |
Library |
Msmpi.lib |
DLL |
Msmpi.dll |