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