Open MPI logo

MPI_Dims_create(3) man page (version 1.3.4)

  |   Home   |   Support   |   FAQ   |  

« Return to documentation listing



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

       INCLUDE 'mpif.h'
       MPI_DIMS_CREATE(NNODES, NDIMS, DIMS, IERROR)
            INTEGER   NNODES, NDIMS, DIMS(*), 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
       dimension 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
       -----------------------------------------------------
       (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.

1.3.4                            Nov 11, 2009               MPI_Dims_create(3)

« Return to documentation listing