Topology

C | Fortran-2008 | Fortran-90

MPI_Cart_create

Definition

MPI_Cart_create creates a communicator from the cartesian topology information passed.

Copy

Feedback

int MPI_Cart_create(MPI_Comm old_communicator,
                    int dimension_number,
                    const int* dimensions,
                    const int* periods,
                    int reorder,
                    MPI_Comm new_communicator);

Parameters

old_communicator

Communicator containing the processes to use in the creation of the new communicator.

dimension_number

The number of dimensions in the cartesian grid.

dimensions

The array containing the number of processes to assign to each dimension.

periods

The array containing the periodicity for each dimension. It indicates, for each dimension, if it is periodic (true) or non-periodic (false).

reorder

Indicates if processes must preserve their rank from the old communiator to the new. If reorder is true, MPI has the flexibility to decide what ranks assign to the processes in the new communicator, for example so that the cartesian topology maps well onto the physical machine.

new_communicator

Contains the new communicator created. Certain processes may obtain MPI_COMM_NULL in the event that the cartesian grid passed needs fewer processes than that contained in the old communicator.

Return value

The error code returned from the coordinates creation.

Example

Copy

Feedback

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

/**
 * @brief Illustrates how to create a communicator representing a 2D torus
 * topology.
 **/
int main(int argc, char* argv[])
{
    MPI_Init(&argc, &argv);

    // Size of the default communicator
    int size;
    MPI_Comm_size(MPI_COMM_WORLD, &size);

    // Ask MPI to decompose our processes in a 2D cartesian grid for us
    int dims[2] = {0, 0};
    MPI_Dims_create(size, 2, dims);

    // Make both dimensions periodic
    int periods[2] = {true, true};

    // Let MPI assign arbitrary ranks if it deems it necessary
    int reorder = true;

    // Create a communicator given the 2D torus topology.
    MPI_Comm new_communicator;
    MPI_Cart_create(MPI_COMM_WORLD, 2, dims, periods, reorder, &new_communicator);

    // My rank in the new communicator
    int my_rank;
    MPI_Comm_rank(new_communicator, &my_rank);

    // Get my coordinates in the new communicator
    int my_coords[2];
    MPI_Cart_coords(new_communicator, my_rank, 2, my_coords);

    // Print my location in the 2D torus.
    printf("[MPI process %d] I am located at (%d, %d).\n", my_rank, my_coords[0],my_coords[1]);

    MPI_Finalize();

    return EXIT_SUCCESS;
}