MPI_NEIGHBOR_ALLTOALLW(3)

📦

version 5.0.10 · 7 versions

💖 `MPI_NEIGHBOR_ALLTOALLW` 💖 (that's section 3 of the Open MPI manual, bestie)

MPI_Neighbor_alltoallw, MPI_Ineighbor_alltoallw, MPI_Neighbor_alltoallw_init — okay so basically: every process sends data of different types to, and receives data of different types from, literally all of its processes. Type chaos. We love her. 💅

✨ SYNTAX ✨

🌸 C Syntax

#include <mpi.h>

int MPI_Neighbor_alltoallw(const void *sendbuf, const int sendcounts[],
     const MPI_Aint sdispls[], const MPI_Datatype sendtypes[],
     void *recvbuf, const int recvcounts[], const MPI_Aint rdispls[],
     const MPI_Datatype recvtypes[], MPI_Comm comm)

int MPI_Ineighbor_alltoallw(const void *sendbuf, const int sendcounts[],
     const MPI_Aint sdispls[], const MPI_Datatype sendtypes[],
     void *recvbuf, const int recvcounts[], const MPI_Aint rdispls[],
     const MPI_Datatype recvtypes[], MPI_Comm comm, MPI_Request *request)

int MPI_Neighbor_alltoallw_init(const void *sendbuf, const int sendcounts[],
     const MPI_Aint sdispls[], const MPI_Datatype sendtypes[],
     void *recvbuf, const int recvcounts[], const MPI_Aint rdispls[],
     const MPI_Datatype recvtypes[], MPI_Comm comm, MPI_Info info, MPI_Request *request)

🦋 Fortran Syntax

USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_NEIGHBOR_ALLTOALLW(SENDBUF, SENDCOUNTS, SDISPLS, SENDTYPES,
     RECVBUF, RECVCOUNTS, RDISPLS, RECVTYPES, COMM, IERROR)

     <type>  SENDBUF(*), RECVBUF(*)
     INTEGER SENDCOUNTS(*), SENDTYPES(*)
     INTEGER RECVCOUNTS(*), RECVTYPES(*)
     INTEGER(KIND=MPI_ADDRESS_KIND) SDISPLS(*), RDISPLS(*)
     INTEGER COMM, IERROR

MPI_INEIGHBOR_ALLTOALLW(SENDBUF, SENDCOUNTS, SDISPLS, SENDTYPES,
     RECVBUF, RECVCOUNTS, RDISPLS, RECVTYPES, COMM, REQUEST, IERROR)

     <type>  SENDBUF(*), RECVBUF(*)
     INTEGER SENDCOUNTS(*), SENDTYPES(*)
     INTEGER RECVCOUNTS(*), RECVTYPES(*)
     INTEGER(KIND=MPI_ADDRESS_KIND) SDISPLS(*), RDISPLS(*)
     INTEGER COMM, REQUEST, IERROR

MPI_NEIGHBOR_ALLTOALLW_INIT(SENDBUF, SENDCOUNTS, SDISPLS, SENDTYPES,
     RECVBUF, RECVCOUNTS, RDISPLS, RECVTYPES, COMM, INFO, REQUEST, IERROR)

     <type>  SENDBUF(*), RECVBUF(*)
     INTEGER SENDCOUNTS(*), SENDTYPES(*)
     INTEGER RECVCOUNTS(*), RECVTYPES(*)
     INTEGER(KIND=MPI_ADDRESS_KIND) SDISPLS(*), RDISPLS(*)
     INTEGER COMM, INFO, REQUEST, IERROR

🫶 Fortran 2008 Syntax

USE mpi_f08
MPI_Neighbor_alltoallw(sendbuf, sendcounts, sdispls, sendtypes, recvbuf,
             recvcounts, rdispls, recvtypes, comm, ierror)

     TYPE(*), DIMENSION(..), INTENT(IN) :: sendbuf
     TYPE(*), DIMENSION(..) :: recvbuf
     INTEGER, INTENT(IN) :: sendcounts(*), recvcounts(*)
     INTEGER(KIND=MPI_ADDRESS_KIND), INTENT(IN) :: sdispls(*), rdispls(*)
     TYPE(MPI_Datatype), INTENT(IN) :: sendtypes(*), recvtypes(*)
     TYPE(MPI_Comm), INTENT(IN) :: comm
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

MPI_Ineighbor_alltoallw(sendbuf, sendcounts, sdispls, sendtypes, recvbuf,
             recvcounts, rdispls, recvtypes, comm, request, ierror)

     TYPE(*), DIMENSION(..), INTENT(IN), ASYNCHRONOUS :: sendbuf
     TYPE(*), DIMENSION(..), ASYNCHRONOUS :: recvbuf
     INTEGER, INTENT(IN), ASYNCHRONOUS :: sendcounts(*), recvcounts(*)
     INTEGER(KIND=MPI_ADDRESS_KIND), INTENT(IN), ASYNCHRONOUS ::
     sdispls(*), rdispls(*)
     TYPE(MPI_Datatype), INTENT(IN), ASYNCHRONOUS :: sendtypes(*),
     recvtypes(*)
     TYPE(MPI_Comm), INTENT(IN) :: comm
     TYPE(MPI_Request), INTENT(OUT) :: request
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

MPI_Neighbor_alltoallw_init(sendbuf, sendcounts, sdispls, sendtypes, recvbuf,
             recvcounts, rdispls, recvtypes, comm, info, request, ierror)

     TYPE(*), DIMENSION(..), INTENT(IN), ASYNCHRONOUS :: sendbuf
     TYPE(*), DIMENSION(..), ASYNCHRONOUS :: recvbuf
     INTEGER, INTENT(IN), ASYNCHRONOUS :: sendcounts(*), recvcounts(*)
     INTEGER(KIND=MPI_ADDRESS_KIND), INTENT(IN), ASYNCHRONOUS ::
     sdispls(*), rdispls(*)
     TYPE(MPI_Datatype), INTENT(IN), ASYNCHRONOUS :: sendtypes(*),
     recvtypes(*)
     TYPE(MPI_Comm), INTENT(IN) :: comm
     TYPE(MPI_Info), INTENT(IN) :: info
     TYPE(MPI_Request), INTENT(OUT) :: request
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

🎀 INPUT PARAMETERS 🎀

sendbuf — starting address of send buffer. The origin. The home base. 🏠
sendcounts — integer array, where entry i specifies the number of elements to send to neighbor i.
sdispls — integer array, where entry i specifies the displacement (in bytes, offset from sendbuf) from which to send data to neighbor i. Bytes, bestie, not elements. Do not forget. 😤
sendtypes — datatype array, where entry i specifies the datatype to use when sending data to neighbor i. Yes you get a different type per neighbor. Iconic behavior honestly. 💅
recvcounts — integer array, where entry j specifies the number of elements to receive from neighbor j.
rdispls — integer array, where entry j specifies the displacement (in bytes, offset from recvbuf) to which data from neighbor j should be written.
recvtypes — datatype array, where entry j specifies the datatype to use when receiving data from neighbor j.
comm — communicator over which data is to be exchanged.
info — Info (handle, persistent only). Only the _init one gets this. 👑

🌈 OUTPUT PARAMETERS 🌈

recvbuf — address of receive buffer. Where the goodies land. ✨
request — Request (handle, non-blocking only). For the I version and the _init version.
ierror — Fortran only: error status.

💫 DESCRIPTION 💫

Okay so MPI_Neighbor_alltoallw is a generalized collective operation where all processes send data to and receive data from all neighbors. Periodt.

She's basically MPI_Neighbor_alltoallv but with the flexibility turned all the way up, because she lets you specify the datatype of each individual data block — on top of displacement and element count. Not me giving you per-block type control, that's main character energy fr fr. 💅

You can think of the whole thing like this, where each process does 2n independent point-to-point communications (n being the number of neighbors in the topology of communicator comm). The neighbors and the buffer layout are determined by the topology of comm. The 2n because: one send + one recv per neighbor, and you got n neighbors. Math ate. 🔥

MPI_Cart_get(comm, maxdims, dims, periods, coords);
for (dim = 0, i = 0 ; dim < dims ; ++dim) {
    MPI_Cart_shift(comm, dim, 1, &r0, &r1);
    MPI_Isend(sendbuf + sdispls[i]  * extent(sendtype),
              sendcount, sendtypes[i], r0, ..., comm, ...);
    MPI_Irecv(recvbuf + rdispls[i] * extent(recvtype),
              recvcount, recvtypes[i], r0, ..., comm, ...);
    ++i;
    MPI_Isend(sendbuf + sdispls[i] * extent(sendtype),
              sendcount, sendtypes[i], r1, ..., comm, &req[i]);
    MPI_Irecv(recvbuf + rdispls[i] * extent(recvtype),
              recvcount, recvtypes[i], r1, ..., comm, ...);
    ++i;
}

MPI_Wait_all (...);

MPI_Comm_size(comm, &n);
for (i = 0, i < n; i++)
  MPI_Send(sendbuf + sdispls[i], sendcounts[i],
       sendtypes[i], i, ..., comm);
for (i = 0, i < n; i++)
  MPI_Recv(recvbuf + rdispls[i], recvcounts[i],
       recvtypes[i], i, ..., comm);

So process j sends the k-th block of its local sendbuf to neighbor k, and neighbor k places that data in the j-th block of its local recvbuf. Little block handoff. Adorable. 🎁

When a pair of processes exchanges data, each one may pass different element count and datatype arguments — as long as the sender specifies the same amount of data to send (in bytes) as the receiver expects to receive. Bytes matching is the vibe check. ✨

Also!! Note that process i may send a different amount of data to process j than it receives from process j. And a process may send entirely different amounts and types of data to different processes in the communicator. No symmetry required, she doesn't do symmetry. 💅

😭 NOTES 😭

The MPI_IN_PLACE option for sendbuf is not meaningful for this operation. Don't try it, bestie, there's nothing there for you. 💀

The specification of counts, types, and displacements should not cause any location to be written more than once. Do not double-write. That's undefined territory and we don't go there. 🙈

All arguments on all processes are significant. The comm argument, in particular, must describe the same communicator on all processes. Everybody on the same page or it's over.

The offsets of sdispls and rdispls are measured in bytes. Compare this to MPI_Neighbor_alltoallv, where those offsets are measured in units of sendtype and recvtype, respectively. Different units, different girl. Don't mix them up, iykyk. 🫶

to be continued… part 2 is coming, don't go anywhere bestie 🦋

💖 ERRORS 💖

okay bestie, real talk: almost every MPI routine hands you back an error value. For C routines it's the return result of the function, and for Fortran routines it shows up in the last argument. That's just the rule. 🌸

Before that error value even gets returned, the current MPI error handler hooked up to the communication object (think: communicator, window, file) gets called. If there's no communication object attached to the MPI call at all, then the call is treated as attached to MPI_COMM_SELF and it'll call the related MPI error handler. And when MPI_COMM_SELF isn't initialized — like before MPI_Init/MPI_Init_thread, after MPI_Finalize, or when you're using the Sessions Model exclusively — the error raises the initial error handler instead. 👑

That initial error handler is changeable! You can do it by calling MPI_Comm_set_errhandler on MPI_COMM_SELF when you're using the World model, or via the mpi_initial_errhandler CLI argument to mpiexec, or an info key to MPI_Comm_spawn/MPI_Comm_spawn_multiple. And if no other appropriate error handler has been set? Then MPI_ERRORS_RETURN gets called for MPI I/O functions, and MPI_ERRORS_ABORT gets called for all other MPI functions. no cap. 💅

✨ Open MPI ships three predefined error handlers ✨

MPI_ERRORS_ARE_FATAL — causes the program to abort all connected MPI processes. yeah. everybody. 😭
MPI_ERRORS_ABORT — an error handler you can invoke on a communicator, window, file, or session. When it's called on a communicator, it acts as if MPI_Abort was called on that communicator. If it's 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. And if it's called on a session, it aborts only the local process. 🌈
MPI_ERRORS_RETURN — returns an error code right back 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 ✨

⚠️ heads up bestie: note that MPI does not guarantee that an MPI program can continue past an error. like, it might just be over. 💀

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.

👀 See also 👀

MPI_Neighbor_alltoall
MPI_Neighbor_alltoallv
MPI_Cart_create
MPI_Graph_create
MPI_Dist_graph_create

📜 Copyright 📜

2003-2026, The Open MPI Community

aaaaand that's a wrap on this one, bestie 🫶 this page is from Sep 10, 2026 and it lives in the Open MPI man pages as MPI_NEIGHBOR_ALLTOALLW(3) — go forth and neighbor-alltoallw responsibly, ily, periodt 💅✨🎀

📦 where this page comes from

ubuntu stonking: openmpi-doc 5.0.10-6 · other
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms