MPI_DIST_GRAPH_NEIGHBORS(3)

💖 MPI_Dist_graph_neighbors(3) — the Open MPI girlies' guide 💖

okay bestie, you know how a distributed graph topology is like a whole group chat where everyone has their own little circle of who they talk to? yeah. this is the function that tells you who's in your circle. no cap. it's MPI_Dist_graph_neighbors, it lives in the Open MPI manual (section 3, the library calls section, periodt), and it returns the neighbors of the calling process in a distributed graph topology. that's the vibe. 👑

---

✨ SYNTAX ✨

bestie there are three versions and you gotta pick your fighter 💅

C Syntax

#include <mpi.h>

int MPI_Dist_graph_neighbors(MPI_Comm comm, int maxindegree, int sources[], int sourceweights[],
                             int maxoutdegree, int destinations[], int destweights[])

Fortran Syntax

USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_DIST_GRAPH_NEIGHBORS(COMM, MAXINDEGREE, SOURCES, SOURCEWEIGHTS,
        MAXOUTDEGREE, DESTINATIONS, DESTWEIGHTS, IERROR)
        INTEGER COMM, MAXINDEGREE, SOURCES(*), SOURCEWEIGHTS(*), MAXOUTDEGREE,
                DESTINATIONS(*), DESTWEIGHTS(*), IERROR

Fortran 2008 Syntax

USE mpi_f08
MPI_Dist_Graph_neighbors(comm, maxindegree, sources, sourceweights,
             maxoutdegree, destinations, destweights, ierror)
     TYPE(MPI_Comm), INTENT(IN) :: comm
     INTEGER, INTENT(IN) :: maxindegree, maxoutdegree
     INTEGER, INTENT(OUT) :: sources(maxindegree), destinations(maxoutdegree)
     INTEGER :: sourceweights(*), destweights(*)
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

---

🌸 INPUT PARAMETERS 🌸

stuff you gotta hand over, no takebacks:

• comm — the communicator that's got the distributed graph topology on it (a handle). 🫶
• maxindegree — how big your sources and sourceweights arrays are (a non-negative integer, so like, zero is valid bestie).
• maxoutdegree — how big your destinations and destweights arrays are (also a non-negative integer 🎀).

---

🦋 OUTPUT PARAMETERS 🦋

stuff it hands back to you, and it's giving main character energy:

• sources — the processes that have you as a destination, i.e. the ones pointing at you (array of non-negative integers). 💜
• sourceweights — the weights on the edges coming into you, an icon (array of non-negative integers).
• destinations — the processes you point at, you're their source, you're the origin story (array of non-negative integers). ✨
• destweights — the weights on the edges going out of you (array of non-negative integers).
• ierror — Fortran only: the error status (integer). classic Fortran, putting everything in the last argument 😭

---

💅 DESCRIPTION 💅

okay so MPI_Dist_graph_neighbors literally returns the source and destination ranks in a distributed graph topology for the calling process. it's your personal contact list.

this call will return up to maxindegree source ranks in the sources array and up to maxoutdegree destination ranks in the destinations array. so if you sized your arrays too small, you only get up to that many, bestie — mind your buffers. 🙈

if weights were specified back when the communicator was created, then the associated weights come back to you in the sourceweights and destweights arrays. cute right?

and here's the lore drop: if the communicator was created with MPI_Dist_graph_create_adjacent <#mpi-dist-graph-create-adjacent>, then the order of the values in sources and destinations is identical to the input that was used by the process with the same rank in comm_old in the creation call. so the ordering is preserved exactly like it went in. obsessed with the consistency honestly. 👑

---

😭 ERRORS 😭

almost all MPI routines return an error value, bestie — in C it's the return result of the function, and in Fortran it's in the last argument. fr fr.

before that error value even gets returned, the current MPI error handler associated with the communication object (like, e.g., communicator, window, file) gets 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>. and 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. that's just how it goes. 🌈

Open MPI includes three predefined error handlers that can be used:

• MPI_ERRORS_ARE_FATAL — causes the program to abort all connected MPI processes. yeah. all of them. dramatic but effective. 💀
• 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, it 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, it aborts only the local process. so it scales the drama to the object. ✨
• MPI_ERRORS_RETURN — returns an error code to the application. the chill one. the "we'll handle it ourselves" one. 🫶

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. like, no promises bestie.

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. that's the homework, iykyk.

See also:

• MPI_Dist_graph_neighbors_count <#mpi-dist-graph-neighbors-count> — go check the count before you check the neighbors, it's the prequel. 🎀

---

🌟 Copyright 🌟

2003-2026, The Open MPI Community — the whole squad. 👑

---

and that's the tea, bestie: this page came from the Open MPI manual, it's the MPI_Dist_graph_neighbors(3) page, and it was dated Sep 10, 2026. slay, go call your neighbors, don't forget to size your arrays 💖✨🦋🌸💅