Rookie HPC

About

Docs

Tools

Tests

MPI_Dims_create

Definition

MPI_Dims_create is a convenience function in the creation of cartesian topologies (MPI_Cart_create). This routine decomposes a given number of processes over a cartesian grid made of the number of dimensions specified. MPI attempts to balance the distribution by minimising the difference in the number of processes assigned to each dimension. The programmer can restrict the number of process to allocate to any dimension. If MPI is not able to find a decomposition while respecting the restrictions given, the routine returns an erroneous value. Otherwise, the decomposition found is stored in the array passed.

Copy

Feedback

int MPI_Dims_create(int process_number,
                    int dimension_number,
                    int* dimensions);

Parameters

process_number
Number of processes to decompose.
dimension_number
The number of dimensions in the cartesian grid.
dimensions
The array in which store the number of processes assigned to each dimension. The array passed must already contain values that will be used as potential restrictions. Namely, dimensions that are initialised to 0 have no restriction and allow MPI to allocate any number of processes to it. For other dimensions, MPI must find a decomposition such that these dimensions contain exactly the number of processes indicated. However, certain decompositions may become impossible due to restrictions, in which case this routine will return an erroneous code.

Returned value

MPI_SUCCESS
The routine successfully completed.

Example

Copy

Feedback

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

/**
 * @brief Illustrate how to decompose MPI processes in a cartesian grid.
 * @details This application is to be run with 60 processes. It attempts to
 * decompose these 60 MPI processes in 3 dimensions (i.e: a cube).
 **/
int main(int argc, char* argv[])
{
    MPI_Init(&argc, &argv);

    // Get total number of MPI processes
    int size;
    MPI_Comm_size(MPI_COMM_WORLD, &size);
    // Get my MPI process identifier
    int my_rank;
    MPI_Comm_rank(MPI_COMM_WORLD, &my_rank);

    if(my_rank == 0)
    {
        printf("Attempting to decompose %d processes into a cube:\n", size);

        // Give total freedom to MPI
        int dimsA[3] = {0, 0, 0};
        printf("\t- Restrictions (%d, %d, %d) give decomposition ", dimsA[0], dimsA[1], dimsA[2]);
        MPI_Dims_create(size, 3, dimsA);
        printf("(%d, %d, %d).\n", dimsA[0], dimsA[1], dimsA[2]);

        // Restrict 6 processes in the first dimension
        int dimsB[3] = {6, 0, 0};
        printf("\t- Restrictions (%d, %d, %d) give decomposition ", dimsB[0], dimsB[1], dimsB[2]);
        MPI_Dims_create(size, 3, dimsB);
        printf("(%d, %d, %d).\n", dimsB[0], dimsB[1], dimsB[2]);

        // Restrict 2 processes in the first dimension and 15 processes in the third dimension
        int dimsC[3] = {2, 0, 15};
        printf("\t- Restrictions (%d, %d, %d) give decomposition ", dimsC[0], dimsC[1], dimsC[2]);
        MPI_Dims_create(size, 3, dimsC);
        printf("(%d, %d, %d).\n", dimsC[0], dimsC[1], dimsC[2]);

        // Restrict 11 processes in the first dimension, which makes impossible to decompose 60 processes
        int dimsD[3] = {11, 0, 0};
        printf("\t- Restrictions (%d, %d, %d) give decomposition ", dimsD[0], dimsD[1], dimsD[2]);
        MPI_Dims_create(size, 3, dimsD);
        printf("(%d, %d, %d).\n", dimsD[0], dimsD[1], dimsD[2]);
    }

    MPI_Finalize();

    return EXIT_SUCCESS;
}