The two additional functions introduced in this section can be used to
implement all other topology functions. In general they will not be
called by the user directly, except when creating additional
* virtual topology* capabilities other than those provided by MPI.
The two calls are both local.

MPI_CART_MAP(comm, ndims, dims, periods, newrank) | |

IN comm | input communicator (handle) |

IN ndims | number of dimensions of Cartesian structure (integer) |

IN dims | integer array of size ndims specifying the number of processes in each coordinate direction |

IN periods | logical array of size ndims specifying the periodicity specification in each coordinate direction |

OUT newrank | reordered rank of the calling MPI process; MPI_UNDEFINED if calling MPI process does not belong to grid (integer) |

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

INTEGER, INTENT(IN) :: ndims, dims(ndims)

LOGICAL, INTENT(IN) :: periods(ndims)

INTEGER, INTENT(OUT) :: newrank

INTEGER, OPTIONAL, INTENT(OUT) :: ierror

INTEGER COMM, NDIMS, DIMS(*), NEWRANK, IERROR

LOGICAL PERIODS(*)

MPI_CART_MAP computes an ``optimal'' placement for the calling MPI process on the physical machine. A possible implementation of this function is to always return the rank of the calling MPI process, that is, not to perform any reordering.

* Advice
to implementors.*

The function MPI_CART_CREATE(comm, ndims, dims, periods, reorder, comm_cart), with reorder = true can be implemented by calling MPI_CART_MAP(comm, ndims, dims, periods, newrank), then calling MPI_COMM_SPLIT(comm, color, key, comm_cart), with color = 0 if newrank MPI_UNDEFINED, color = MPI_UNDEFINED otherwise, and key = newrank. If ndims is zero then a zero-dimensional Cartesian topology is created.

The function MPI_CART_SUB(comm, remain_dims, comm_new) can be implemented by a call to MPI_COMM_SPLIT(comm, color, key, comm_new), using a single number encoding of the lost dimensions as color and a single number encoding of the preserved dimensions as key.

All other Cartesian topology functions can be implemented locally, using
the topology information that is cached with the communicator.
(* End of advice to implementors.*)

The corresponding function for
graph structures is as follows.

MPI_GRAPH_MAP(comm, nnodes, index, edges, newrank) | |

IN comm | input communicator (handle) |

IN nnodes | number of graph nodes (integer) |

IN index | integer array specifying the graph structure (for details see the definition of MPI_GRAPH_CREATE) |

IN edges | integer array specifying the graph structure |

OUT newrank | reordered rank of the calling MPI process; MPI_UNDEFINED if the calling MPI process does not belong to graph (integer) |

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

INTEGER, INTENT(IN) :: nnodes, index(nnodes), edges(*)

INTEGER, INTENT(OUT) :: newrank

INTEGER, OPTIONAL, INTENT(OUT) :: ierror

INTEGER COMM, NNODES, INDEX(*), EDGES(*), NEWRANK, IERROR

* Advice
to implementors.*

The function MPI_GRAPH_CREATE(comm, nnodes, index, edges, reorder, comm_graph), with reorder = true can be implemented by calling MPI_GRAPH_MAP(comm, nnodes, index, edges, newrank), then calling MPI_COMM_SPLIT(comm, color, key, comm_graph), with color = 0 if newrank MPI_UNDEFINED, color = MPI_UNDEFINED otherwise, and key = newrank.

All other graph topology functions can be implemented locally, using the
topology information that is cached with the communicator.
(* End of advice to implementors.*)

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