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

MPI_Cart_create

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.