MPI_COMM_GROUP(3)

📦
version 5.0.10 · 7 versions
, in ubuntu stonking

💖 MPI_COMM_GROUP(3) — Open MPI 💖

okay bestie, gather round, because today we're getting the group out of a communicator and it's honestly iconic. this is a page from the Open MPI manual set, and no cap, it's short but it matters. 🎀

✨ NAME ✨

MPI_Comm_group — hands you back the group that's associated with a communicator. that's it. that's the whole job. 💅

✨ SYNTAX ✨

🌸 C Syntax 🌸

#include <mpi.h>

int MPI_Comm_group(MPI_Comm comm, MPI_Group *group)

🌸 Fortran Syntax 🌸

USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_COMM_GROUP(COMM, GROUP, IERROR)
     INTEGER COMM, GROUP, IERROR

🌸 Fortran 2008 Syntax 🌸

USE mpi_f08
MPI_Comm_group(comm, group, ierror)
     TYPE(MPI_Comm), INTENT(IN) :: comm
     TYPE(MPI_Group), INTENT(OUT) :: group
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

like, look at that mpi_f08 version being all typed and elegant. main character energy fr. 👑

💖 INPUT PARAMETER 💖

  • comm — the communicator. that's the thing you're pulling a group out of, bestie.

🦋 OUTPUT PARAMETERS 🦋

  • group — the group that lives inside that communicator (it's a handle, so hold it gently).
  • ierror — Fortran-only babes: this is your error status, and it's an integer.

🌈 DESCRIPTION 🌈

so here's the tea 🍵: if the communicator you handed over is an intercommunicator — aka the kind that lets two separate groups of processes talk to each other — then this function gives you back the local group. only the local one. local. 🫶

and if what you actually wanted was the other side? the remote group? then you go call MPI_Comm_remote_group instead. different function, different vibe, don't mix them up. 💀

🔥 ERRORS 🔥

okay so basically almost every MPI routine returns an error value. in C it comes back as the return result of the function, and in Fortran it lands in the last argument. no surprises there. ✨

and before that error value ever gets returned? the current MPI error handler attached to the communication object gets called — and by "communication object" we mean stuff like a communicator, window, or file. and if there's no communication object associated with the MPI call at all, then the call counts as attached to MPI_COMM_SELF and it calls the error handler associated with that.

now here's the part where you gotta pay attention, bestie, because it's giving edge case:

when MPI_COMM_SELF isn't initialized — meaning before MPI_Init/MPI_Init_thread, after MPI_Finalize, or when you're running the Sessions Model exclusively — the error raises the initial error handler. 😭

and you can change that initial error handler! you do it by calling MPI_Comm_set_errhandler on MPI_COMM_SELF when you're using the World model, or by using the mpi_initial_errhandler CLI argument to mpiexec, or the info key to MPI_Comm_spawn/MPI_Comm_spawn_multiple.

and if no other appropriate error handler has been set? then:

  • the MPI_ERRORS_RETURN error handler gets called for MPI I/O functions, and
  • the MPI_ERRORS_ABORT error handler gets called for all other MPI functions.

🌟 the three predefined error handlers Open MPI ships with 🌟

  • MPI_ERRORS_ARE_FATAL — causes the program to abort all connected MPI processes. dramatic? yes. effective? also yes. 💀
  • MPI_ERRORS_ABORT — an error handler that can be invoked 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 to the application. polite. respectful. we love her. 🫶

💜 and you can absolutely write your own 💜

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

DIY queen behavior honestly. 👑

⚠️ real talk, no cap: note that MPI does not guarantee that an MPI program can continue past an error. like, do not assume you can just keep going. that's not a thing. 😭

for the full list of MPI error codes, go check the MPI man page. and for even more detail, see the Error Handling section of the MPI-3.1 standard. iykyk. 📚

2003-2026, The Open MPI Community

and that's the whole page, bestie!! 🎀💖 slay, you now know exactly how to get a group out of a communicator, and you know it was written up on Sep 10, 2026 in the Open MPI manual, page MPI_COMM_GROUP(3). go forth and group responsibly. ✨🦋🌸

📦 where this page comes from