MPI_Dims_create(3) Open MPI MPI_Dims_create(3)
NAME
MPI_Dims_create - Creates a division of processors in a Cartesian
grid.
SYNTAX
C Syntax
#include <mpi.h>
int MPI_Dims_create(int nnodes, int ndims, int dims[])
Fortran Syntax
USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_DIMS_CREATE(NNODES, NDIMS, DIMS, IERROR)
INTEGER NNODES, NDIMS, DIMS(*), IERROR
Fortran 2008 Syntax
USE mpi_f08
MPI_Dims_create(nnodes, ndims, dims, ierror)
INTEGER, INTENT(IN) :: nnodes, ndims
INTEGER, INTENT(INOUT) :: dims(ndims)
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
C++ Syntax
#include <mpi.h>
void Compute_dims(int nnodes, int ndims, int dims[])
INPUT PARAMETERS
nnodes Number of nodes in a grid (integer).
ndims Number of Cartesian dimensions (integer).
IN/OUT PARAMETER
dims Integer array of size ndims specifying the number of nodes in
each dimension.
OUTPUT PARAMETER
IERROR Fortran only: Error status (integer).
DESCRIPTION
For Cartesian topologies, the function MPI_Dims_create helps the user
select a balanced distribution of processes per coordinate direction,
depending on the number of processes in the group to be balanced and
optional constraints that can be specified by the user. One use is to
partition all the processes (the size of MPI_COMM_WORLD's group) into
an n-dimensional topology.
The entries in the array dims are set to describe a Cartesian grid with
ndims dimensions and a total of nnodes nodes. The dimensions are set to
be as close to each other as possible, using an appropriate divisibil-
ity algorithm. The caller may further constrain the operation of this
routine by specifying elements of array dims. If dims[i] is set to a
positive number, the routine will not modify the number of nodes in di-
mension i; only those entries where dims[i] = 0 are modified by the
call.
Negative input values of dims[i] are erroneous. An error will occur if
nnodes is not a multiple of ((pi) over (i, dims[i] != 0)) dims[i].
For dims[i] set by the call, dims[i] will be ordered in nonincreasing
order. Array dims is suitable for use as input to routine MPI_Cart_cre-
ate. MPI_Dims_create is local.
Example:
dims
before dims
call function call on return
-----------------------------------------------------
(0,0) MPI_Dims_create(6, 2, dims) (3,2)
(0,0) MPI_Dims_create(7, 2, dims) (7,1)
(0,3,0) MPI_Dims_create(6, 3, dims) (2,3,1)
(0,3,0) MPI_Dims_create(7, 3, dims) erroneous call
------------------------------------------------------
ERRORS
Almost all MPI routines return an error value; C routines as the value
of the function and Fortran routines in the last argument. C++ func-
tions do not return errors. If the default error handler is set to
MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism
will be used to throw an MPI::Exception object.
Before the error value is returned, the current MPI error handler is
called. By default, this error handler aborts the MPI job, except for
I/O function errors. The error handler may be changed with
MPI_Comm_set_errhandler; the predefined error handler MPI_ERRORS_RETURN
may be used to cause error values to be returned. Note that MPI does
not guarantee that an MPI program can continue past an error.
4.1.2 Nov 24, 2021 MPI_Dims_create(3)
Generated by dwww version 1.14 on Fri Jan 24 09:42:59 CET 2025.