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.
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.
|
|
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.