17.2.84. MPI_Dist_graph_create
MPI_Dist_graph_create — 创建一个附加了拓扑信息的新通信器。
17.2.84.1. 语法
17.2.84.1.1. C语法
#include <mpi.h>
int MPI_Dist_graph_create(MPI_Comm comm_old, int n, const int sources[],
const int degrees[], const int destinations[], const int weights[],
MPI_Info info, int reorder, MPI_Comm *comm_dist_graph)
17.2.84.1.2. Fortran 语法
USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_DIST_GRAPH_CREATE(COMM_OLD, N, SOURCES, DEGREES, DESTINATIONS, WEIGHTS,
INFO, REORDER, COMM_DIST_GRAPH, IERROR)
INTEGER COMM_OLD, N, SOURCES(*), DEGRES(*), WEIGHTS(*), INFO
INTEGER COMM_DIST_GRAPH, IERROR
LOGICAL REORDER
17.2.84.1.3. Fortran 2008 语法
USE mpi_f08
MPI_Dist_Graph_create(comm_old, n, sources, degrees, destinations, weights,
info, reorder, comm_dist_graph, ierror)
TYPE(MPI_Comm), INTENT(IN) :: comm_old
INTEGER, INTENT(IN) :: n, sources(n), degrees(n), destinations(*)
INTEGER, INTENT(IN) :: weights(*)
TYPE(MPI_Info), INTENT(IN) :: info
LOGICAL, INTENT(IN) :: reorder
TYPE(MPI_Comm), INTENT(OUT) :: comm_dist_graph
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
17.2.84.2. 输入参数
comm_old: 输入无拓扑结构的通信器（句柄）。n: 该进程指定边数的源节点数量（非负整数）。sources: 包含该进程指定边的n个源节点的数组（非负整数数组）。degrees: 数组，指定源节点数组中每个源节点的目标节点数量（非负整数数组）。destinations: 源节点数组中各源节点的目标节点（非负整数数组）。weights: 源节点到目标节点边的权重（非负整数数组）。info: 关于权重优化和解释的提示（handle）。reorder: 排名可以重新排序（true）或保持不变（false）（逻辑值）。
17.2.84.3. 输出参数
comm_dist_graph: 添加了分布式图拓扑的通信器（句柄）。ierror: 仅限Fortran：错误状态（整数）。
17.2.84.4. 描述
MPI_Dist_graph_create 创建一个具有分布式图拓扑的新通信器 comm_dist_graph，并返回该新通信器的句柄。comm_dist_graph 中的进程数量与 comm_old 中的进程数量相同。具体来说，每个进程调用此构造函数时需提供一组有向（源节点，目标节点）通信边，如下所述。 每个进程在 sources 数组中传递 n 个源节点。对于每个源节点，degrees 数组中指定了非负数的目标节点数量。目标节点存储在 destinations 数组对应的连续段中。更准确地说，如果源节点数组中的第 i 个节点是 s，则指定了 degrees[i] 条边 (s,d)，其中第 j 条边的目标节点 d 存储在 destinations[degrees[0]+…+degrees[i-1]+j] 中。该边的权重存储在 weights[degrees[0]+…+degrees[i-1]+j] 中。 sources 和 destinations 数组可能多次包含相同的节点，且节点作为目标或源列出的顺序无关紧要。类似地，不同进程可以指定具有相同源节点和目标节点的边。源节点和目标节点必须是 comm_old 的进程秩。不同进程可以指定不同数量的源节点和目标节点，以及不同的源到目标边。这允许通信图的完全分布式规范。 允许存在孤立进程（即没有出边或入边的进程，也就是在图规范中不作为源节点或目标节点出现的进程）。调用 MPI_Dist_graph_create 是集体操作。
如果 reorder = false，所有进程在 comm_dist_graph 中将保持与 comm_old 中相同的排名。如果 reorder = true，则 MPI 库可以自由地将进程（来自 comm_old）重新映射，以优化通信图中边的通信效率。每条边关联的权重是向 MPI 库提供的提示，表示该边上通信的量或强度，可用于计算
17.2.84.5. 权重
权重被指定为非负整数，可用于影响进程重映射策略和其他MPI内部优化。例如，后续沿特定边的通信调用的近似计数参数可用作边的权重。边的多重性同样可以表示进程对之间更密集的通信。然而，边权重的确切含义并未由MPI标准规定，而是留给具体实现决定。应用程序可为权重数组提供特殊值MPI_UNWEIGHTED，表示所有边具有相同（实际上无）权重。若仅为comm_old的部分而非全部进程提供MPI_UNWEIGHTED，则会产生错误。如果图是加权的但n = 0，则可传递MPI_WEIGHTS_EMPTY或任意数组给weights。请注意MPI_UNWEIGHTED和MPI_WEIGHTS_EMPTY并非特殊的权重值，而是整个数组参数的特殊值。在Fortran中，MPI_UNWEIGHTED和MPI_WEIGHTS_EMPTY是类似MPI_BOTTOM的对象（不可用于初始化或赋值）。参见MPI-3第2.5.4节。
17.2.84.6. 错误
几乎所有MPI例程都会返回一个错误值；C语言例程通过函数返回值返回，Fortran例程则通过最后一个参数返回。
在返回错误值之前，会调用与通信对象（如通信器、窗口、文件）关联的当前MPI错误处理程序。如果MPI调用未关联任何通信对象，则该调用被视为附加到MPI_COMM_SELF，并将调用关联的MPI错误处理程序。当MPI_COMM_SELF未初始化时（即在MPI_Init/MPI_Init_thread之前、MPI_Finalize之后，或仅使用会话模型时），错误会触发初始错误处理程序。初始错误处理程序可通过在使用世界模型时调用MPI_Comm_set_errhandler来修改MPI_COMM_SELF，或通过mpiexec的mpi_initial_errhandler命令行参数，或MPI_Comm_spawn/MPI_Comm_spawn_multiple的info键来设置。如果未设置其他适当的错误处理程序，则MPI I/O函数将调用MPI_ERRORS_RETURN错误处理程序，而其他所有MPI函数将调用MPI_ERRORS_ABORT错误处理程序。
Open MPI 包含三个可使用的预定义错误处理器：
MPI_ERRORS_ARE_FATAL导致程序中止所有连接的MPI进程。MPI_ERRORS_ABORT一个可在通信器、窗口、文件或会话上调用的错误处理程序。当在通信器上调用时，其行为类似于在该通信器上调用MPI_Abort。如果在窗口或文件上调用，则行为类似于在包含对应窗口或文件中进程组的通信器上调用MPI_Abort。如果在会话上调用，则仅中止本地进程。MPI_ERRORS_RETURN向应用程序返回一个错误代码。
MPI应用程序也可以通过调用以下方式实现自己的错误处理程序：
请注意，MPI不保证MPI程序在出现错误后能够继续运行。
有关更多信息，请参阅MPI-3.1标准中的错误处理部分。