--- name: "MPI_Type_create_darray" section: "3" platform: "linux" package: "openmpi" version: "5.0.11-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/MPI_Type_create_darray" --- # MPI\_Type\_create\_darray(3) *MPI\_Type\_create\_darray* — Creates a distributed array datatype; ## SYNTAX ### C Syntax ``` #include 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) ``` ### Fortran Syntax ``` 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 ``` ### Fortran 2008 Syntax ``` 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 ``` ## INPUT PARAMETERS - • **size**: Size of process group (positive integer). - • **rank**: Rank in process group (nonnegative integer). - • **ndims**: Number of array dimensions as well as process grid dimensions (positive integer). - • **array\_of\_gsizes**: Number of elements of type *oldtype* in each dimension of global array (array of positive integers). - • **array\_of\_distribs**: Distribution of array in each dimension (array of state). - • **array\_of\_dargs**: Distribution argument in each dimension (array of positive integers). - • **array\_of\_psizes**: Size of process grid in each dimension (array of positive integers). - • **order**: Array storage order flag (state). - • **oldtype**: Old data type (handle). ## OUTPUT PARAMETERS - • **newtype**: New data type (handle). - • **ierror**: Fortran only: Error status (integer). ## DESCRIPTION *MPI\_Type\_create\_darray* can be used to generate the data types corresponding to the distribution of an ndims-dimensional array of *oldtype* elements onto an *ndims*-dimensional grid of logical processes. Unused dimensions of *array\_of\_psizes* should be set to 1. For a call to *MPI\_Type\_create\_darray* to be correct, the equation ``` ndims-1 pi array_of_psizes[i] = size i=0 ``` must be satisfied. The ordering of processes in the process grid is assumed to be row-major, as in the case of virtual Cartesian process topologies in the *MPI Standard*. Each dimension of the array can be distributed in one of three ways: - • **MPI\_DISTRIBUTE\_BLOCK** - Block distribution - • **MPI\_DISTRIBUTE\_CYCLIC** - Cyclic distribution - • **MPI\_DISTRIBUTE\_NONE** - Dimension not distributed. The constant MPI\_DISTRIBUTE\_DFLT\_DARG specifies a default distribution argument. The distribution argument for a dimension that is not distributed is ignored. For any dimension *i* in which the distribution is MPI\_DISTRIBUTE\_BLOCK, it erroneous to specify *array\_of\_dargs\[i\]* *\** *array\_of\_psizes\[i\]* \< *array\_of\_gsizes\[i\]*. For example, the HPF layout ARRAY(CYCLIC(15)) corresponds to MPI\_DISTRIBUTE\_CYCLIC with a distribution argument of 15, and the HPF layout ARRAY(BLOCK) corresponds to MPI\_DISTRIBUTE\_BLOCK with a distribution argument of MPI\_DISTRIBUTE\_DFLT\_DARG. The *order* argument is used as in *MPI\_Type\_create\_subarray* to specify the storage order. Therefore, arrays described by this type constructor may be stored in Fortran (column-major) or C (row-major) order. Valid values for order are MPI\_ORDER\_FORTRAN and MPI\_ORDER\_C. This routine creates a new MPI data type with a typemap defined in terms of a function called “cyclic()” (see below). Without loss of generality, it suffices to define the typemap for the MPI\_DISTRIBUTE\_CYCLIC case where **MPI\_DISTRIBUTE\_DFLT\_DARG** is not used. MPI\_DISTRIBUTE\_BLOCK and MPI\_DISTRIBUTE\_NONE can be reduced to the MPI\_DISTRIBUTE\_CYCLIC case for dimension *i* as follows. MPI\_DISTRIBUTE\_BLOCK with *array\_of\_dargs\[i\]* equal to MPI\_DISTRIBUTE\_DFLT\_DARG is equivalent to MPI\_DISTRIBUTE\_CYCLIC with *array\_of\_dargs\[i\]* set to ``` (array_of_gsizes[i] + array_of_psizes[i] - 1)/array_of_psizes[i] ``` If *array\_of\_dargs\[i\]* is not MPI\_DISTRIBUTE\_DFLT\_DARG, then MPI\_DISTRIBUTE\_BLOCK and DISTRIBUTE\_CYCLIC are equivalent. MPI\_DISTRIBUTE\_NONE is equivalent to MPI\_DISTRIBUTE\_CYCLIC with *array\_of\_dargs\[i\]* set to *array\_of\_gsizes\[i\]*. Finally, MPI\_DISTRIBUTE\_CYCLIC with *array\_of\_dargs\[i\]* equal to MPI\_DISTRIBUTE\_DFLT\_DARG is equivalent to MPI\_DISTRIBUTE\_CYCLIC with *array\_of\_dargs\[i\]* set to 1. ## NOTES For both Fortran and C arrays, the ordering of processes in the process grid is assumed to be row-major. This is consistent with the ordering used in virtual Cartesian process topologies in MPI. To create such virtual process topologies, or to find the coordinates of a process in the process grid, etc., users may use the corresponding functions provided in MPI. ## ERRORS Almost all MPI routines return an error value; C routines as the return result of the function and Fortran routines in the last argument. Before the error value is returned, the current MPI error handler associated with the communication object (e.g., communicator, window, file) is called. If no communication object is associated with the MPI call, then the call is considered attached to MPI\_COMM\_SELF and will call the associated MPI error handler. When MPI\_COMM\_SELF is not initialized (i.e., before *MPI\_Init*/*MPI\_Init\_thread*, after *MPI\_Finalize*, or when using the Sessions Model exclusively) the error raises the initial error handler. The initial error handler can be changed by calling *MPI\_Comm\_set\_errhandler* on MPI\_COMM\_SELF when using the World model, or the mpi\_initial\_errhandler CLI argument to mpiexec or info key to *MPI\_Comm\_spawn*/*MPI\_Comm\_spawn\_multiple*. If no other appropriate error handler has been set, then the MPI\_ERRORS\_RETURN error handler is called for MPI I/O functions and the MPI\_ERRORS\_ABORT error handler is called for all other MPI functions. Open MPI includes three predefined error handlers that can be used: - • **MPI\_ERRORS\_ARE\_FATAL** Causes the program to abort all connected MPI processes. - • **MPI\_ERRORS\_ABORT** An error handler that can be invoked on a communicator, window, file, or session. When called on a communicator, it acts as if *MPI\_Abort* was called on that communicator. If called on a window or file, acts as if *MPI\_Abort* was called on a communicator containing the group of processes in the corresponding window or file. If called on a session, aborts only the local process. - • **MPI\_ERRORS\_RETURN** Returns an error code to the application. MPI applications can also implement their own error handlers by calling: - • *MPI\_Comm\_create\_errhandler* then *MPI\_Comm\_set\_errhandler* - • *MPI\_File\_create\_errhandler* then *MPI\_File\_set\_errhandler* - • *MPI\_Session\_create\_errhandler* then *MPI\_Session\_set\_errhandler* or at *MPI\_Session\_init* - • *MPI\_Win\_create\_errhandler* then *MPI\_Win\_set\_errhandler* Note that MPI does not guarantee that an MPI program can continue past an error. See the *MPI man page* for a full list of *MPI error codes*. See the Error Handling section of the MPI-3.1 standard for more information. ## COPYRIGHT 2003-2026, The Open MPI Community