Creates a new communicator using a cartesian topology. : TechWeb : Boston University

This page imported from: /afs/bu.edu/cwis/webuser/web/s/c/scv/documentation/tutorials/MPI/more/MPI_Cart_create.html

MPI_Cart_create

Creates a new communicator using a cartesian topology.

<!–

Fortran syntax

Subroutine MPI_Cart_create(old_comm,ndims,dim_size,periods,reorder,new_comm,ierr)

C syntax

int MPI_Cart_create(old_comm,ndims,dim_size,periods,reorder,new_comm)

Argument	Description	Data Type	Scalar or Array	State
old_comm	Communicator from which the new communicator is created	MPI_Comm/integer	scalar	input
ndims	Number of dimensions of the cartesian topology, or grid	int/integer	scalar	input
dim_size	grid size in each dimension	int/integer	array with ndims dimensions	input
periods	periodicity in each dimension;this is used to deal with elements on the boundaries	int/integer	array with ndims dimensions	input
reorder	reorder=1 to allow MPI to determine optimal process ordering, this potentially could result in processes reordered. Otherwise, set reorder=0	int/integer	scalar	input
new_comm	the new cartesian grid communicator	MPI_Comm/integer	scalar	output
ierr	Error flag	int/integer	scalar	output

–>

Example in Fortran

      include "mpif.h"
      integer old_comm, new_comm, ndims, reorder, ierr
      integer dim_size(2), periods(2)

      old_comm = MPI_COMM_WORLD
      ndims = 2
      dim_size(1) = 3
      dim_size(2) = 2
      periods(1) = 1
      periods(2) = 0
      reorder = 1
      
      call MPI_Cart_create(old_comm,ndims,dim_size,
     &       periods,reorder,new_comm,ierr)

Shown below, in Figure a, is the resulting cartesian topology (grid)
where the index pair “i,j” indicate row “i” and column “j”. The number
in parentheses represents the rank
number associated with the cartesian grid.

Figure a. Cartesian Grid
0,0 (0)	0,1 (1)
1,0 (2)	1,1 (3)
2,0 (4)	2,1 (5)

In the same code fragment, the row index has been defined to have
periodicity (i.e., period(0)=1; period(1)=0) which essentially means that each
column of the matrix wrap around itself like a circular shift. On the other
hand, since periodicity is not set for the column index, any reference beyond
the defined cartesian coordinates results in a rank number of “-1”, or
MPI_PROC_NULL. MPI subroutines that reference myid, the current
process id, have built-in checks for MPI_PROC_NULL equivalent to

      if(myid .ne. MPI_PROC_NULL) then
        call MPI_Xxxx(..., myid, ...)
      endif

Similarly, if periodicity is defined only for the column index
(i.e., period(0)=0; period(1)=1), each row will wrap around itself. The effects
of periodic columns and periodic rows are depicted in figures b and c, respectively.

Figure b. period(0)=1;period(1)=0
&nbsp	-1,0 (4)	-1,1 (5)	&nbsp
0,-1 (-1)	0,0 (0)	0,1 (1)	0,2 (-1)
1,-1 (-1)	1,0 (2)	1,1 (3)	1,2 (-1)
2,-1 (-1)	2,0 (4)	2,1 (5)	2,2 (-1)
&nbsp	3,0 (0)	3,1 (1)	&nbsp

Figure c. period(0)=0;period(1)=1
&nbsp	-1,0 (-1)	-1,1 (-1)	&nbsp
0,-1 (1)	0, 0 (0)	0, 1 (1)	0, 2 (0)
1,-1 (3)	1, 0 (2)	1, 1 (3)	1, 2 (2)
2,-1 (5)	2, 0 (4)	2, 1 (5)	2, 2 (4)
&nbsp	3,0 (-1)	3,1 (-1)	&nbsp

Knowing the layout of the cartesian grid, more specifically, knowing the
relationship between the coordinates and their corresponding process
ranks (as shown in the tables above), is key to the opportunity to
exploit the topology for computational expediency. In the following
sections, we will discuss two subroutines that will provide us with
these informations. They are:
MPI_Cart_coords and
MPI_Cart_rank.

To see or to download the fortran code used to generate the above tables,
please
click here.

Example in C

#include "mpi.h";
MPI_Comm  old_comm, new_comm;
int ndims, reorder, ierr;
int dim_size[2], periods[2];

old_comm = MPI_COMM_WORLD;
ndims = 2;
dim_size[0] = 3;
dim_size[1] = 2;
periods[0] = 1;
periods[1] = 0;
reorder = 1;
      
ierr =  MPI_Cart_create(old_comm,ndims,dim_size,
             periods,reorder,new_comm,ierr);

In the above example, a new communicator for a two dimensional (ndims=2) cartesian grid
has been created. This grid consists of six processes and is arranged in a three by two
matrix. There is no periodicity along the second dimension (or along the y dimension
if you prefer) and is periodic along the first (or x) dimension.
Since periods(1)=1, a reference to the cartesian process (4,1) would map it to
(1,1), i.e., periodic. On the other hand, if periods(1) = 0, a reference to process (4,1) would
result in whatever MPI function called to return NULL which means no action taken.

Creates a new communicator using a cartesian topology.

MPI_Cart_create