Topology
C | FORTRAN-legacy | FORTRAN-2008
MPI_Cart_create
Definition
MPI_Cart_create creates a communicator from the cartesian topology information passed.
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.
Returned value
The error code returned from the coordinates creation.
- MPI_SUCCESS
- The routine successfully completed.
Example
#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;
}