MPI_DIMS_CREATE(3)

📦
version 5.0.10 · 7 versions
, in ubuntu stonking

🎀 NAME 🎀

MPI_Dims_create — bestie, this one literally creates a division of processors in a Cartesian grid 💖 (it's from the Open MPI manual, page MPI_DIMS_CREATE(3), iykyk)

✨ 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 — the number of nodes in a grid, and yes she's an integer 👑
  • ndims — how many Cartesian dimensions we're working with (integer, periodt)

🫶 IN/OUT PARAMETER 🫶

  • dims — an integer array of size ndims that says how many nodes live in each dimension. She goes in, she gets modified, she's a whole main character 🦋

💌 OUTPUT PARAMETER 💌

  • ierror — Fortran only bb, this is the error status (integer)

🧚 DESCRIPTION 🧚

Okay so for Cartesian topologies, MPI_Dims_create is literally the friend who helps you pick a balanced distribution of processes per coordinate direction 🫶 It looks at how many processes are in the group that needs balancing, plus any optional constraints you wanna specify. One classic use: partitioning all the processes (aka the size of MPI_COMM_WORLD's group) into an n-dimensional topology. Slay.

The entries in the array dims get set so they describe a Cartesian grid with ndims dimensions and a total of nnodes nodes. The dimensions get set to be as close to each other as possible, using an appropriate divisibility algorithm — balanced queen energy ⚖️✨

You can constrain it further by setting elements of the array dims yourself before the call:

  • if dims[i] is a positive number, the routine will not touch the number of nodes in dimension i
  • only the entries where dims[i] = 0 get modified by the call
Negative input values of dims[i] are erroneous, no cap. And an error will occur if nnodes is not a multiple of ((pi) over (i, dims[i] != 0)) dims[i].

For the dims[i] that the call does set, dims[i] will be ordered in nonincreasing order 🔥 Also, array dims is suitable for use as input to routine MPI_Cart_create. And MPI_Dims_create is local — she keeps to herself 💅

Example, because a visual never hurts:

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, bestie: C routines hand it back as the return result of the function, and Fortran routines put it in the last argument 📬

Before that error value comes back, the current MPI error handler associated with the communication object (e.g., communicator, window, file) gets called. If there's no communication object associated with the MPI call, then the call counts as attached to MPI_COMM_SELF and it'll 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. And that initial error handler can be changed by calling MPI_Comm_set_errhandler on MPI_COMM_SELF when you're using the World model, or the mpi_initial_errhandler CLI argument to mpiexec, or the 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 you can use:

  • 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, it 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, it 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. Like, she said what she said 🙈

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 📚

2003-2026, The Open MPI Community

k that's the whole page bestie, you ate 💅 this was the MPI_DIMS_CREATE(3) page from Open MPI, dated Sep 10, 2026 — go forth and balance your grid, you iconic thing 💖✨🦋

📦 where this page comes from