MPIDimscreate(3OpenMPI) MPIDimscreate(3OpenMPI)

NAME
       MMPPIIDDiimmssccrreeaattee   -  Creates  a  division  of processors in a Cartesian
       grid.


SSYYNNTTAAXX
CC SSyynnttaaxx
       #include 
       int MPIDimscreate(int nnodes, int ndims, int *dims)


FFoorrttrraann SSyynnttaaxx
       INCLUDE 'mpif.h'
       MPIDIMSCREATE(NNODES, NDIMS, DIMS, IERROR)
            INTEGER   NNODES, NDIMS, DIMS(*), IERROR


CC++++ SSyynnttaaxx
       #include 
       void Computedims(int nnodes, int ndims, int dims[])


IINNPPUUTT PPAARRAAMMEETTEERRSS
       nnodes    Number of nodes in a grid (integer).

       ndims     Number of Cartesian dimensions (integer).


IINN//OOUUTT PPAARRAAMMEETTEERR
       dims      Integer array of size ndims specifying the number of nodes in
                 each dimension.


OOUUTTPPUUTT PPAARRAAMMEETTEERR
       IERROR    Fortran only: Error status (integer).


DESCRIPTION
       For  Cartesian  topologies, the function MPIDimscreate 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 MPICOMMWORLD'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
       order. Array dims is suitable for use as input to routine MPICartcre-
       ate. MPIDimscreate is local.

       EExxaammppllee::

       dims
       before                        dims
       call      function call       on return
       ---------------------------
       (0,0)     MPIDimscreate(6, 2, dims)   (3,2)
       (0,0)     MPIDimscreate(7, 2, dims)   (7,1)
       (0,3,0)   MPIDimscreate(6, 3, dims)   (2,3,1)
       (0,3,0)   MPIDimscreate(7, 3, dims)   erroneous call
       ---------------------------


EERRRROORRSS
       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::ERRORSTHROWEXCEPTIONS, 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
       MPICommseterrhandler; the predefined error handler MPIERRORSRETURN
       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.




Open MPI 1.2                    September 2006       MPIDimscreate(3OpenMPI)