## 9.5.7. Partitioning of Cartesian Structures

**Up: ** Topology Constructors
**Next: ** Low-Level Topology Functions
**Previous: ** Cartesian Shift Coordinates

MPI_CART_SUB(comm, remain_dims, newcomm) |

IN comm | communicator with associated Cartesian topology (handle) |

IN remain_dims | the i-th entry of remain_dims specifies whether the i-th dimension is kept in the subgrid ( true) or is dropped ( false) (array of logicals) |

OUT newcomm | new communicator with associated Cartesian topology containing the subgrid that includes the calling MPI process (handle) |

** C binding**

` int MPI_Cart_sub(MPI_Comm comm, const int remain_dims[], MPI_Comm *newcomm) `

** Fortran 2008 binding**

` MPI_Cart_sub(comm, remain_dims, newcomm, ierror) `

TYPE(MPI_Comm), INTENT(IN) :: comm

LOGICAL, INTENT(IN) :: remain_dims(*)

TYPE(MPI_Comm), INTENT(OUT) :: newcomm

INTEGER, OPTIONAL, INTENT(OUT) :: ierror

** Fortran binding**

` MPI_CART_SUB(COMM, REMAIN_DIMS, NEWCOMM, IERROR) `

INTEGER COMM, NEWCOMM, IERROR

LOGICAL REMAIN_DIMS(*)

MPI_CART_SUB can be used to partition the
group associated with a communicator that has an associated Cartesian topology
into subgroups that form lower-dimensional Cartesian
subgrids, and to create for each subgroup a communicator with the associated
subgrid Cartesian topology.
The topologies of the new communicators describe the subgrids.
The number of dimensions of the subgrids is the number of remaining dimensions, i.e., the number of true values in remain_dims.
The numbers of MPI processes in each coordinate direction of the subgrids are the remaining numbers of MPI processes in each coordinate direction of the grid associated with the original communicator, i.e., the values of the original grid dimensions for which the corresponding entry in remain_dims is true.
The periodicity for the remaining dimensions in the new communicator is preserved from the original communicator.
If all entries in remain_dims are false or comm is already associated
with a zero-dimensional Cartesian topology then newcomm is associated
with a zero-dimensional Cartesian topology.
(This function is closely related to
MPI_COMM_SPLIT.)

** Example**
Creation of nonoverlapping Cartesian subcommunicators with MPI_CART_SUB.

Assume that MPI_Cart_create(*...*, comm) has defined a
*(2 × 3 × 4)* grid. Let remain_dims = (true, false, true).
Then a call to

will create three communicators each with eight MPI processes
in a *2 × 4* Cartesian
topology. If remain_dims = (false, false, true) then the call to

will create six nonoverlapping
communicators, each with four MPI processes,
in a one-dimensional Cartesian topology.

**Up: ** Topology Constructors
**Next: ** Low-Level Topology Functions
**Previous: ** Cartesian Shift Coordinates

Return to MPI-4.1 Standard Index

Return to MPI Forum Home Page

(Unofficial) MPI-4.1 of November 2, 2023

HTML Generated on November 19, 2023