MPI_DIMS_CREATE(3)				     Open MPI					MPI_DIMS_CREATE(3)

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

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
       divisibility  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 MPI_Cart_create <#mpi-cart-create>. 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 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>/MPI_Init_thread  <#mpi-init-thread>,
       after  MPI_Finalize  <#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	<#
       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>/MPI_Comm_spawn_multiple	<#
       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 <#mpi-abort> was called on that communicator. If called
	 on a window or file, acts as if MPI_Abort <#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	 <#mpi-comm-create-errhandler>	   then	    MPI_Comm_set_errhandler	<#
	 mpi-comm-set-errhandler>

       • MPI_File_create_errhandler	<#mpi-file-create-errhandler>	  then	   MPI_File_set_errhandler	<#
	 mpi-file-set-errhandler>

       • MPI_Session_create_errhandler	 <#mpi-session-create-errhandler>   then   MPI_Session_set_errhandler	<#
	 mpi-session-set-errhandler> or at MPI_Session_init <#mpi-session-init>

       • MPI_Win_create_errhandler	<#mpi-win-create-errhandler>	  then	    MPI_Win_set_errhandler	<#
	 mpi-win-set-errhandler>

       Note that MPI does not guarantee that an MPI program can continue past an error.

       See the MPI man page <#open-mpi> for a full list of MPI error codes <#open-mpi-errors>.

       See the Error Handling section of the MPI-3.1 standard for more information.

Copyright
       2003-2026, The Open MPI Community

						   Mar 05, 2026					MPI_DIMS_CREATE(3)
