17.2.382. MPI_Type_create_darray
MPI_Type_create_darray — 创建一个分布式数组数据类型；
17.2.382.1. 语法
17.2.382.1.1. C语法
#include <mpi.h>
int MPI_Type_create_darray(int size, int rank, int ndims,
const int array_of_gsizes[], const int array_of_distribs[],
const int array_of_dargs[], const int array_of_psizes[],
int order, MPI_Datatype oldtype, MPI_Datatype *newtype)
17.2.382.1.2. Fortran语法
USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_TYPE_CREATE_DARRAY(SIZE, RANK, NDIMS, ARRAY_OF_GSIZES,
ARRAY_OF_DISTRIBS, ARRAY_OF_DARGS, ARRAY_OF_PSIZES, ORDER,
OLDTYPE, NEWTYPE, IERROR)
INTEGER SIZE, RANK, NDIMS, ARRAY_OF_GSIZES(*), ARRAY_OF_DISTRIBS(*),
ARRAY_OF_DARGS(*), ARRAY_OF_PSIZES(*), ORDER, OLDTYPE,
NEWTYPE, IERROR
17.2.382.1.3. Fortran 2008 语法
USE mpi_f08
MPI_Type_create_darray(size, rank, ndims, array_of_gsizes,
array_of_distribs, array_of_dargs, array_of_psizes, order,
oldtype, newtype, ierror)
INTEGER, INTENT(IN) :: size, rank, ndims, array_of_gsizes(ndims),
array_of_distribs(ndims), array_of_dargs(ndims),
array_of_psizes(ndims), order
TYPE(MPI_Datatype), INTENT(IN) :: oldtype
TYPE(MPI_Datatype), INTENT(OUT) :: newtype
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
17.2.382.2. 输入参数
size: 进程组的大小（正整数）。rank: 进程组中的排名（非负整数）。ndims: 数组维数以及进程网格维数（正整数）。array_of_gsizes: 全局数组每个维度中oldtype类型的元素数量（正整数数组）。array_of_distribs: 数组在每个维度上的分布（状态数组）。array_of_dargs: 每个维度中的分布参数（正整数数组）。array_of_psizes: 进程网格在每个维度上的大小（正整数数组）。order: 数组存储顺序标志（状态）。oldtype: 旧数据类型（句柄）。
17.2.382.3. 输出参数
newtype: 新数据类型（句柄）。ierror: 仅限Fortran：错误状态（整数）。
17.2.382.4. 描述
MPI_Type_create_darray 可用于生成与将oldtype元素的ndims维数组分布到逻辑进程的ndims维网格上相对应的数据类型。array_of_psizes中未使用的维度应设置为1。要使MPI_Type_create_darray调用正确，需满足以下等式
ndims-1
pi array_of_psizes[i] = size
i=0
必须满足。进程网格中的进程顺序假定为行优先，类似于MPI标准中虚拟笛卡尔进程拓扑的情况。
数组的每个维度可以通过以下三种方式之一进行分布：
MPI_DISTRIBUTE_BLOCK- 块分布MPI_DISTRIBUTE_CYCLIC- 循环分布MPI_DISTRIBUTE_NONE- 该维度未进行分布式处理。
常量MPI_DISTRIBUTE_DFLT_DARG用于指定默认的分布参数。对于未进行分布的维度，其分布参数将被忽略。在任何维度i中，若分布方式为MPI_DISTRIBUTE_BLOCK，则指定array_of_dargs[i]*array_of_psizes[i] < array_of_gsizes[i]将导致错误。
例如，HPF布局ARRAY(CYCLIC(15))对应MPI_DISTRIBUTE_CYCLIC且分布参数为15，而HPF布局ARRAY(BLOCK)则对应MPI_DISTRIBUTE_BLOCK且分布参数为MPI_DISTRIBUTE_DFLT_DARG。
order参数与MPI_Type_create_subarray中的用法相同，用于指定存储顺序。因此，通过此类型构造器描述的数组可以按Fortran（列优先）或C（行优先）顺序存储。order的有效值为MPI_ORDER_FORTRAN和MPI_ORDER_C。
该例程创建一个新的MPI数据类型，其类型映射通过名为"cyclic()"的函数定义（见下文）。
不失一般性，只需为未使用MPI_DISTRIBUTE_DFLT_DARG的MPI_DISTRIBUTE_CYCLIC情况定义类型映射即可。
对于维度i，MPI_DISTRIBUTE_BLOCK和MPI_DISTRIBUTE_NONE可以简化为MPI_DISTRIBUTE_CYCLIC的情况，具体如下。
当array_of_dargs[i]等于MPI_DISTRIBUTE_DFLT_DARG时，MPI_DISTRIBUTE_BLOCK等同于将array_of_dargs[i]设置为MPI_DISTRIBUTE_CYCLIC的情况
(array_of_gsizes[i] + array_of_psizes[i] - 1)/array_of_psizes[i]
如果array_of_dargs[i]不是MPI_DISTRIBUTE_DFLT_DARG，那么MPI_DISTRIBUTE_BLOCK和DISTRIBUTE_CYCLIC是等效的。
MPI_DISTRIBUTE_NONE 等同于将 array_of_dargs[i] 设置为 array_of_gsizes[i] 的 MPI_DISTRIBUTE_CYCLIC。
最后，当array_of_dargs[i]等于MPI_DISTRIBUTE_DFLT_DARG时，MPI_DISTRIBUTE_CYCLIC等同于将array_of_dargs[i]设置为1的MPI_DISTRIBUTE_CYCLIC。
17.2.382.5. 注意事项
对于Fortran和C语言数组，进程网格中的进程顺序默认为行优先排列。这与MPI中虚拟笛卡尔进程拓扑所使用的排序方式一致。要创建此类虚拟进程拓扑，或查找进程在网格中的坐标等，用户可以使用MPI提供的相应函数。
17.2.382.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标准中的错误处理部分。