Collectives

Topology

C | Fortran-2008 | Fortran-90

MPI_Comm_split

Definition

MPI_Comm_split partitions the group of MPI processes associated with the communicator passed into disjoint subgroups. The split is determined by the colour value passed: MPI processes providing the same colour value will be put in the same subgroup. Within each subgroup, the rank of the MPI processes put in each subgroup are ordered according to the value of the key passed. When multiple MPI processes of a subgroup have provided the same key value, their rank in that subgroup will be determined according to their rank in the old group. A new communicator is created for each subgroup and returned. A process may supply the colour value MPI_UNDEFINED, in which case the new communicator returned is MPI_COMM_NULL. This is a collective call, therefore all MPI processes in the communicator must call the routine, however each process is permitted to provide different values for colour and key.

Copy

Feedback

int MPI_Comm_split(MPI_Comm old_communicator,
                   int colour,
                   int key,
                   MPI_Comm* new_communicator);

Parameters

old_communicator

The communicator in which the calling MPI process belongs and is the one to split.

colour

The value determining in which group the calling MPI process will be; MPI processes providing the same colour value will be put in the same subgroup. If MPI_UNDEFINED is passed as the colour value, the subgroup in which the calling MPI process will be placed is MPI_COMM_NULL.

key

The value determining the rank that the calling MPI process will be assigned in the subgroup in which it will be placed. For each subgroup, MPI processes will be assigned ranks in the order of their key value, with ties being broken according to their rank in the old communicator.

new_communicator

The communicator created, made of the group containing all MPI processes having provided the same colour value. If MPI_UNDEFINED was provided as the colour value, MPI_COMM_NULL is returned.

Return value

The error code returned from the communicator split.

Example

Copy

Feedback

#include <stdio.h>
#include <stdlib.h>
#include <mpi.h>

/**
 * @brief Illustrates
 * @details MPI processes split into two groups depending on whether their rank
 * is even.
 *
 * +----------------+---+---+---+---+
 * | MPI processes  | 0 | 1 | 2 | 3 |
 * +----------------+---+---+---+---+
 * | MPI_COMM_WORLD | X | X | X | X |
 * | Subgroup A     | X |   | X |   |
 * | Subgroup B     |   | X |   | X |
 * +----------------+---+---+---+---+
 *
 * In subcommunicator A, MPI processes are assigned ranks in the same order as
 * their rank in the global communicator.
 * In subcommunicator B, MPI processes are assigned ranks in the opposite order
 * as their rank in the global communicator.
 **/
int main(int argc, char* argv[])
{
    MPI_Init(&argc, &argv);

    // Check that 4 MPI processes are used
    int comm_size;
    MPI_Comm_size(MPI_COMM_WORLD, &comm_size);
    if(comm_size != 4)
    {
        printf("This application is meant to be run with 4 MPI processes, not %d.\n", comm_size);
        MPI_Abort(MPI_COMM_WORLD, EXIT_FAILURE);
    }

    // Get my rank in the global communicator
    int my_rank;
    MPI_Comm_rank(MPI_COMM_WORLD, &my_rank);

    // Determine the colour and key based on whether my rank is even.
    char subcommunicator;
    int colour;
    int key;
    if(my_rank % 2 == 0)
    {
        subcommunicator = 'A';
        colour = 0;
        key = my_rank;
    }
    else
    {
        subcommunicator = 'B';
        colour = 1;
        key = comm_size - my_rank;
    }

    // Split de global communicator
    MPI_Comm new_comm;
    MPI_Comm_split(MPI_COMM_WORLD, colour, key, &new_comm);

    // Get my rank in the new communicator
    int my_new_comm_rank;
    MPI_Comm_rank(new_comm, &my_new_comm_rank);

    // Print my new rank and new communicator
    printf("[MPI process %d] I am now MPI process %d in subcommunicator %c.\n", my_rank, my_new_comm_rank, subcommunicator);

    MPI_Finalize();

    return EXIT_SUCCESS;
}