Topologies can be added to an intra-communicator, but not inter-communicators, as an optional attribute to provide a convenient process naming mechanism for communication between the processes in the group/communicator. This topology can map processes to physical hardware within the runtime system (this mapping is machine-independant).
If a hardware topology is known, it can be used in the virtual topology to optimize performance by assigning processes to physical hardware to increase speed in communications. If a hardware topology is not known, a virtual topology will still provide a convenient process naming structure for use by the runtime system and increase the readablity of the program.
MPI provides us with two types of topologies: topologies based on a cartesian grid, and topologies based on graphs. Under the topology based upon a graph the nodes stand for processes and the edges connect processes that communicate with each other. Many applications use a grid based topology that creates a ring, two or more dimensional grids, or tori. Grid structures are defined by a number of dimensions and number of processes in each coordinate direction. The easiest of the two topologies is the grid structure. Grid structures are mapped using a row-major numbering system. Below is an example of a 2 x 2 grid.
| 0 [0,0] |
1 [0,1] |
| 2 [1,0] |
3 [1,1] |
int MPI_Cart_create ( MPI_Comm comm_old, int ndims, int *dims, int *periods, int reorder, MPI_Comm *comm_cart )
| Parameter | Meaning of Parameter |
| comm_old | input communicator (handle) |
| ndims | number of dimensions of cartesian grid (integer) |
| dims | integer array of size ndims specifying the number of processes in each dimension |
| periods | logical array of size ndims specifying whether the grid is periodic (true) or not (false) in each dimension |
| reorder | ranking may be reordered (true) or not (false) (logical) |
| comm_cart | communicator with new cartesian topology (handle) |
MPI_Cart_create makes a new communicator to which topology information has been attached. Periodic
means that if the neighbor of a ranking process is out of range, it will wrap to the beginning if true
or will be MPI_PROC_NULL if false.
int MPI_Dims_create( int nnodes, int ndims, int *dims)
| Parameter | Meaning of Parameter |
| nnodes | number of nodes in a grid (integer) |
| ndims | number of cartesian dimensions (integer) |
| dims | integer array of size ndims specifying the number of nodes in each dimension |
MPI_Dims_create creates a division of processors in a cartesian grid.
int MPI_Graph_create ( MPI_Comm comm_old, int nnodes, int *index, int *edges, int reorder, MPI_Comm *comm_graph )
| Parameter | Meaning of Parameter |
| comm_old | input communicator without topology (handle) |
| nnodes | number of nodes in graph (integer) |
| index | array of integers describing node degrees |
| edges | array of integers describing graph edges |
| reorder | ranking may be reordered (true) or not (false) (logical) |
| comm_graph | communicator with graph topology added (handle) |
MPI_Graph_create makes a new communicator to which topology information has been attached.
int MPI_Topo_test ( MPI_Comm comm, int *top_type )
| Parameter | Meaning of Parameter |
| comm | communicator (handle) |
| top_type | topology type of communicator comm (choice) |
MPI_Topo_test determines the type of topology (if any) associated with a communicator. On
success, top_type will be either MPI_CART, MPI_GRAPH,
or MPI_UNDEFINED.
int MPI_Graphdims_get ( MPI_Comm comm, int *nnodes, int *nedges )
| Parameter | Meaning of Parameter |
| comm | communicator for group with graph structure (handle) |
| nnodes | number of nodes in graph (integer) |
| nedges | number of edges in graph (integer) |
MPI_Graphdims_get retrieves graph topology information associated with a communicator.
int MPI_Graph_get ( MPI_Comm comm, int maxindex, int maxedges, int *index, int *edges )
| Parameter | Meaning of Parameter |
| comm | communicator with graph structure (handle) |
| maxindex | length of vector index in the calling program (integer) |
| maxedges | length of vector edges in the calling program (integer) |
| index | array of integers containing the graph structure (for details see the definition of MPI_GRAPH_CREATE ) |
| edges | array of integers containing the graph structure |
MPI_Graph_get retrieves graph topology information associated with a communicator.
int MPI_Cartdim_get ( MPI_Comm comm, int *ndims )
| Parameter | Meaning of Parameter |
| comm | communicator with cartesian structure (handle) |
| ndims | number of dimensions of the cartesian structure (integer) |
MPI_Cartdim_get retrieves Cartesian topology information associated with a communicator.
int MPI_Cart_get ( MPI_Comm comm, int maxdims, int *dims, int *periods, int *coords )
| Parameter | Meaning of Parameter |
| comm | communicator with cartesian structure (handle) |
| maxdims | length of vectors dims , periods , and coords in the calling program (integer) |
| dims | number of processes for each cartesian dimension (array of integer) |
| periods | periodicity (true/false) for each cartesian dimension (array of logical) |
| coords | coordinates of calling process in cartesian structure (array of integer) |
MPI_Cart_get retrieves Cartesian topology information associated with a communicator.
int MPI_Cart_rank ( MPI_Comm comm, int *coords, int *rank )
| Parameter | Meaning of Parameter |
| comm | communicator with cartesian structure (handle) |
| coords | integer array (of size ndims ) specifying the cartesian coordinates of a process |
| rank | rank of specified process (integer) |
MPI_Cart_rank determines process rank in communicator given Cartesian location.
int MPI_Cart_coords ( MPI_Comm comm, int rank, int maxdims, int *coords )
| Parameter | Meaning of Parameter |
| comm | communicator with cartesian structure (handle) |
| rank | rank of a process within group of comm (integer) |
| maxdims | length of vector coords in the calling program (integer) |
| coords | integer array (of size ndims ) containing the Cartesian coordinates of specified pro- cess (integer) |
MPI_Cart_coords determines process coords in cartesian topology given rank in group.
int MPI_Graph_neighbors_count ( MPI_Comm comm, int rank, int *nneighbors )
| Parameter | Meaning of Parameter |
| comm | communicator with graph topology (handle) |
| rank | rank of process in group of comm (integer) |
| nneighbors | number of neighbors of specified process (integer) |
MPI_Graph_neighbors_count returns the number of neighbors of a node associated with a graph topology.
int MPI_Graph_neighbors ( MPI_Comm comm, int rank, int maxneighbors, int *neighbors )
| Parameter | Meaning of Parameter |
| comm | communicator with graph topology (handle) |
| rank | rank of process in group of comm (integer) |
| maxneighbors | size of array neighbors (integer) |
| neighbors | ranks of processes that are neighbors to specified process (array of integer) |
MPI_Graph_neighbors returns the neighbors of a node associated with a graph topology.
int MPI_Cart_shift ( MPI_Comm comm, int direction, int displ, int *source, int *dest )
| Parameter | Meaning of Parameter |
| comm | communicator with cartesian structure (handle) |
| direction | coordinate dimension of shift (integer) |
| displ | displacement (> 0: upwards shift, < 0: downwards shift) (integer) |
| source | rank of source process (integer) |
| dest | rank of destination process (integer) |
MPI_Cart_shift returns the shifted source and destination ranks, given a shift direction and amount. This is useful when wanting to use a MPI_SENDRECV operation on a neighbor destination and source, causing a shift in data.
int MPI_Cart_sub ( MPI_Comm comm, int *remain_dims, MPI_Comm *comm_new )
| Parameter | Meaning of Parameter |
| comm | communicator with cartesian structure (handle) |
| remain_dims | the i th entry of remain_dims specifies whether the i th dimension is kept in the sub- grid (true) or is dropped (false) (logical vector) |
| comm_new | communicator containing the subgrid that includes the calling process (handle) |
MPI_Cart_sub partitions a communicator into subgroups which form lower-dimensional cartesian subgrids.
int MPI_Cart_map ( MPI_Comm comm_old, int ndims, int *dims, int *periods, int *newrank)
| Parameter | Meaning of Parameter |
| comm_old | input communicator (handle) |
| ndims | number of dimensions of Cartesian structure (integer) |
| dims | integer array of size ndims specifying the number of processes in each coordinate direction |
| periods | logical array of size ndims specifying the periodicity specification in each coordinate direction |
| newrank | reordered rank of the calling process; MPI_UNDEFINED if calling process does not belong to grid (integer) |
MPI_Cart_map maps process to Cartesian topology information.
int MPI_Graph_map ( MPI_Comm comm_old, int nnodes, int *index, int *edges, int *newrank )
| Parameter | Meaning of Parameter |
| comm_old | input communicator (handle) |
| nnodes | number of graph nodes (integer) |
| index | integer array specifying the graph structure, see MPI_GRAPH_CREATE |
| edges | integer array specifying the graph structure |
| newrank | reordered rank of the calling process; MPI_UNDEFINED if the calling process does not belong to graph (integer) |
MPI_Graph_map maps process to graph topology information.