MPI_INEIGHBOR_ALLTOALLV(3)

📦

version 5.0.10 · 4 versions

💖 MPI_INEIGHBOR_ALLTOALLV — the Open MPI manual page (section 3) 💖

okay bestie, gather round, because this one is a banger. Welcome to the Open MPI MPI_INEIGHBOR_ALLTOALLV page — aka the one where all processes send different amounts of data to, and receive different amounts of data from, all neighbors. yes you read that right. different amounts. every neighbor. no cap. 🦋

and it's not just one function, it's a whole squad: MPI_Neighbor_alltoallv, MPI_Ineighbor_alltoallv, and MPI_Neighbor_alltoallv_init. three icons, one vibe. let's get into it ✨

✨ SYNTAX ✨

🌸 C Syntax

#include <mpi.h>

int MPI_Neighbor_alltoallv(const void *sendbuf, const int sendcounts[],
     const int sdispls[], MPI_Datatype sendtype,
     void *recvbuf, const int recvcounts[],
     const int rdispls[], MPI_Datatype recvtype, MPI_Comm comm)

int MPI_Ineighbor_alltoallv(const void *sendbuf, const int sendcounts[],
     const int sdispls[], MPI_Datatype sendtype,
     void *recvbuf, const int recvcounts[],
     const int rdispls[], MPI_Datatype recvtype, MPI_Comm comm,
     MPI_Request *request)

int MPI_Neighbor_alltoallv_init(const void *sendbuf, const int sendcounts[],
     const int sdispls[], MPI_Datatype sendtype,
     void *recvbuf, const int recvcounts[],
     const int rdispls[], MPI_Datatype recvtype, MPI_Comm comm,
     MPI_Info info, MPI_Request *request)

🎀 Fortran Syntax

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

     <type>  SENDBUF(*), RECVBUF(*)
     INTEGER SENDCOUNTS(*), SDISPLS(*), SENDTYPE
     INTEGER RECVCOUNTS(*), RDISPLS(*), RECVTYPE
     INTEGER COMM, IERROR

MPI_INEIGHBOR_ALLTOALLV(SENDBUF, SENDCOUNTS, SDISPLS, SENDTYPE,
     RECVBUF, RECVCOUNTS, RDISPLS, RECVTYPE, COMM, REQUEST, IERROR)

     <type>  SENDBUF(*), RECVBUF(*)
     INTEGER SENDCOUNTS(*), SDISPLS(*), SENDTYPE
     INTEGER RECVCOUNTS(*), RDISPLS(*), RECVTYPE
     INTEGER COMM, REQUEST, IERROR

MPI_NEIGHBOR_ALLTOALLV_INIT(SENDBUF, SENDCOUNTS, SDISPLS, SENDTYPE,
     RECVBUF, RECVCOUNTS, RDISPLS, RECVTYPE, COMM, INFO, REQUEST, IERROR)

     <type>  SENDBUF(*), RECVBUF(*)
     INTEGER SENDCOUNTS(*), SDISPLS(*), SENDTYPE
     INTEGER RECVCOUNTS(*), RDISPLS(*), RECVTYPE
     INTEGER COMM, INFO, REQUEST, IERROR

🦋 Fortran 2008 Syntax

USE mpi_f08
MPI_Neighbor_alltoallv(sendbuf, sendcounts, sdispls, sendtype, recvbuf,
             recvcounts, rdispls, recvtype, comm, ierror)

     TYPE(*), DIMENSION(..), INTENT(IN) :: sendbuf
     TYPE(*), DIMENSION(..) :: recvbuf
     INTEGER, INTENT(IN) :: sendcounts(*), sdispls(*), recvcounts(*),
     rdispls(*)
     TYPE(MPI_Datatype), INTENT(IN) :: sendtype, recvtype
     TYPE(MPI_Comm), INTENT(IN) :: comm
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

MPI_Ineighbor_alltoallv(sendbuf, sendcounts, sdispls, sendtype, recvbuf,
             recvcounts, rdispls, recvtype, comm, request, ierror)

     TYPE(*), DIMENSION(..), INTENT(IN), ASYNCHRONOUS :: sendbuf
     TYPE(*), DIMENSION(..), ASYNCHRONOUS :: recvbuf
     INTEGER, INTENT(IN), ASYNCHRONOUS :: sendcounts(*), sdispls(*),
     recvcounts(*), rdispls(*)
     TYPE(MPI_Datatype), INTENT(IN) :: sendtype, recvtype
     TYPE(MPI_Comm), INTENT(IN) :: comm
     TYPE(MPI_Request), INTENT(OUT) :: request
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

MPI_Neighbor_alltoallv_init(sendbuf, sendcounts, sdispls, sendtype, recvbuf,
             recvcounts, rdispls, recvtype, comm, info, request, ierror)

     TYPE(*), DIMENSION(..), INTENT(IN), ASYNCHRONOUS :: sendbuf
     TYPE(*), DIMENSION(..), ASYNCHRONOUS :: recvbuf
     INTEGER, INTENT(IN), ASYNCHRONOUS :: sendcounts(*), sdispls(*),
     recvcounts(*), rdispls(*)
     TYPE(MPI_Datatype), INTENT(IN) :: sendtype, recvtype
     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 🫶

here's the tea, one arg at a time:

sendbuf — starting address of send buffer. that's it, that's the address, bestie. 📬
sendcounts — integer array, where entry i specifies the number of elements to send to neighbor i. yes, it's a whole array, because every neighbor gets its own custom amount. main character treatment for everyone. 👑
sdispls — integer array, where entry i specifies the displacement (offset from sendbuf, in units of sendtype) from which to send data to neighbor i. lowkey this is the "where in the buffer do I even start" map. 🗺️
sendtype — datatype of send buffer elements. (and remember: sdispls is measured in units of this. 👀)
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 (offset from recvbuf, in units of recvtype) to which data from neighbor j should be written. that's the little parking spot in recvbuf for each neighbor's goodies. 🅿️
recvtype — datatype of receive buffer elements.
comm — communicator over which data is to be exchanged. the group chat, basically. 🗣️
info — Info (handle, persistent only). yes, just the persistent one. 💅

🎀 OUTPUT PARAMETERS 🎀

recvbuf — address of receive buffer. the other side of the story. 📭
request — Request (handle, non-blocking only). for the non-blocking girly who can't be waiting around. ⏳
ierror — Fortran only: Error status. ✨

🌈 DESCRIPTION 🌈

MPI_Neighbor_alltoallv is a generalized collective operation in which all processes send data to and receive data from all neighbors. it's got extra flexibility compared to MPI_Neighbor_alltoall, because it lets you specify the data to send and receive vector-style — that's a displacement plus an element count. so you're not just saying "hey, everybody swap the same amount," you're saying "hey, you get this much from here, and you get that much from there." bespoke. tailored. iconic. 🧚

the way this operation actually works, think of it like this: each process performs 2n independent point-to-point communications, where n is the number of neighbors in the topology of communicator comm. the neighbors and the buffer layout are all determined by the topology of comm. and the pseudo-code vibe goes a little something like:

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, sendtype, r0, ..., comm, ...);
    MPI_Irecv(recvbuf + rdispls[i] * extent(recvtype),
              recvcount, recvtype, r0, ..., comm, ...);
    ++i;
    MPI_Isend(sendbuf + sdispls[i] * extent(sendtype),
              sendcount, sendtype, r1, ..., comm, &req[i]);
    MPI_Irecv(recvbuf + rdispls[i] * extent(recvtype),
              recvcount, recvtype, r1, ..., comm, ...);
    ++i;
}

so process j sends the k-th block of its local sendbuf to neighbor k, and that neighbor drops the data into the j-th block of its local recvbuf. 🔁

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. that matching-bytes thing is non-negotiable, okay? it's the vibe check of this whole operation. 😤

also note: 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 of data to different processes in the communicator. fully unequal, fully valid, fully slay. 💅

🌸 NEIGHBOR ORDERING 🌸

okay this part is important, because "neighbor i" means different things depending on how your topology got made:

for a distributed graph topology, created with MPI_Dist_graph_create, the sequence of neighbors in the send and receive buffers at each process is defined as the sequence returned by MPI_Dist_graph_neighbors for destinations and sources, respectively.

for a general graph topology, created with MPI_Graph_create, the order of neighbors in the send and receive buffers is defined as the sequence of neighbors as returned by MPI_Graph_neighbors. and ngl, general graph topologies should generally be replaced by the distributed graph topologies. that's the original's own words, not mine. 🙈

for a Cartesian topology, created with MPI_Cart_create, the sequence of neighbors in the send and receive buffers at each process is defined by order of the dimensions — first the neighbor in the negative direction and then in the positive direction with displacement 1. the numbers of sources and destinations in the communication routines are 2*ndims with ndims defined in MPI_Cart_create. 📐

and if a neighbor does not exist — like, you're at the border of a Cartesian topology in the case of a non-periodic virtual grid dimension (i.e., periods[…]==false) — then this neighbor is defined to be MPI_PROC_NULL. ghost neighbor. doesn't exist, still has a seat at the table. 👻

if a neighbor in any of the functions is MPI_PROC_NULL, then the neighborhood collective communication behaves like a point-to-point communication with MPI_PROC_NULL in this direction. meaning: the buffer is still part of the sequence of neighbors, but it is neither communicated nor updated. so it's sitting there, present in the list, doing absolutely nothing. respect honestly. 💀

💜 NOTES 💜

the MPI_IN_PLACE option for sendbuf is not meaningful for this operation. don't try it. not this one. 🚫
the specification of counts and displacements should not cause any location to be written more than once. like. don't double-write a spot. that's the rule. ⚠️

fr fr, be careful with your counts and displacements here — writing the same memory location twice is a whole mess and the spec is telling you not to.

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, always. 📖
the offsets of sdispls and rdispls are measured in units of sendtype and recvtype, respectively. compare this to MPI_Neighbor_alltoallw, where these offsets are measured in bytes. yes, different function, different unit. that's the trap. iykyk. 🪤

and that's where part 1 lands, bestie — part 2 is pulling up right behind this, so don't go anywhere 💖

💀 ERRORS 💀

okay bestie, listen up, because this part is the "what happens when things go wrong" part and it applies to almost every MPI routine, not just this one 🫶

In C, the error value comes back as the return result of the function.
In Fortran, it shows up in the last argument.

Before that error value even gets returned, the current MPI error handler attached to the communication object (think: communicator, window, file) gets called. That's just how it works, no cap.

And if there's no communication object associated with the MPI call? Then the call is treated as if it's attached to MPI_COMM_SELF, and it'll call the error handler associated with that instead. 🌸

okay so here's the plot twist: when MPI_COMM_SELF is not initialized — meaning 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. 😭

And guess what, you can actually change that initial error handler:

on MPI_COMM_SELF by calling MPI_Comm_set_errhandler, but only when you're using the World model
or with the mpi_initial_errhandler CLI argument to mpiexec
or with the info key to MPI_Comm_spawn / MPI_Comm_spawn_multiple

And if literally no other appropriate error handler has been set? Then:

the MPI_ERRORS_RETURN error handler gets called for MPI I/O functions
the MPI_ERRORS_ABORT error handler gets called for all other MPI functions

✨ the three predefined error handlers Open MPI ships with ✨

Open MPI includes three predefined error handlers you can use, and they are iconic in their own way:

MPI_ERRORS_ARE_FATAL — causes the program to abort all connected MPI processes. 💀 no survivors, fr fr.
MPI_ERRORS_ABORT — an error handler that can be invoked on a communicator, window, file, or session. Here's the tea on each:
- 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. simple, clean, respectful ✨

🎀 making your own error handler (main character energy) 🎀

MPI applications can also implement their own error handlers, and honestly? slay. You do it 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

⚠️ but bestie, keep this in mind: MPI does not guarantee that an MPI program can continue past an error. like. at all. so don't be out here assuming you can just keep vibing after one. 🙈

That's a whole mood, I know.

if you want the full list of MPI error codes, go look at the MPI man page 👑. And for even more depth, check out the Error Handling section of the MPI-3.1 standard. iykyk 📚

Also see, bestie (these are the related reads you're gonna wanna peek at):

MPI_Neighbor_alltoall
MPI_Neighbor_alltoallw
MPI_Cart_create
MPI_Graph_create
MPI_Dist_graph_create

👑 Copyright 👑

2003-2026, The Open MPI Community

and that's the whole page, bestie 💖 this was the Open MPI rendition of MPI_INEIGHBOR_ALLTOALLV(3) — source/version: Open MPI, dated Sep 10, 2026 🎀 go forth and neighbor-alltoallv responsibly, mwah 🫶✨🦋

📦 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