MPI_GROUP_RANGE_INCL(3)

💖 NAME 💖

MPI_Group_range_incl — bestie, this one builds you a whole new group out of ranges of ranks from a group you already have. it's giving "cherry-pick, but the deluxe range edition" 🍒✨

this is the page for MPI_GROUP_RANGE_INCL(3) from the Open MPI manual, and yes we're going to get through all of it together 🫶

---

🌈 SYNTAX 🌈

🎀 C Syntax

#include <mpi.h>

int MPI_Group_range_incl(MPI_Group group, int n, int ranges[][3],
     MPI_Group *newgroup)

🎀 Fortran Syntax

USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_GROUP_RANGE_INCL(GROUP, N, RANGES, NEWGROUP, IERROR)
     INTEGER GROUP, N, RANGES(3,*), NEWGROUP, IERROR

🎀 Fortran 2008 Syntax

USE mpi_f08
MPI_Group_range_incl(group, n, ranges, newgroup, ierror)
     TYPE(MPI_Group), INTENT(IN) :: group
     INTEGER, INTENT(IN) :: n, ranges(3,n)
     TYPE(MPI_Group), INTENT(OUT) :: newgroup
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

---

🌸 INPUT PARAMETERS 🌸

the stuff you hand over 💌

• group — the Group (handle). your starting group, the one we're slicing up ✂️
• n — the number of triplets sitting in the ranges array (integer). like, how many ranges did you bring 💅
• ranges — a one-dimensional array of integer triplets, of the form (first rank, last rank, stride), showing which ranks in group (aka which processes) get to be in newgroup. trio girlies only 👑 (that's an integer-trio thing, iykyk)

---

🦋 OUTPUT PARAMETERS 🦋

the stuff you get back, no cap 🎁

• newgroup — the new group derived from all that, in the order defined by ranges (handle). order matters bestie, it's literally defined by ranges 📋
• ierror — Fortran only: error status (integer). classic Fortran, always gotta sneak the error into the last argument 😭

---

✨ DESCRIPTION ✨

okay so if ranges is made of these triplets

(first1, last1, stride1), ..., (firstn, lastn, striden)

then newgroup is the sequence of processes in group with these ranks:

                                                         last(1)-first(1)
          first(1), first(1) + stride(1),..., first(1) + ---------------- stride(1),...
                                                             stride(1)

                                                         last(n)-first(n)
          first(n), first(n) + stride(n),..., first(n) + ---------------- stride(n).
                                                             stride(n)

🚨 every computed rank has to be a valid rank in group, and all the computed ranks have to be distinct — otherwise your program is erroneous. not "oopsie", like, erroneous erroneous. 💀

and yes, plot twist: we may have first(i) > last(i) 📉 — it's giving backwards, and that's allowed. stride(i) may be negative too. but stride(i) cannot be zero. zero stride is NOT the vibe, do not do it 🙈

the functionality of this routine is specified to be equivalent to expanding the array of ranges into an array of the included ranks, then passing that resulting array of ranks (plus the other arguments) to MPI_Group_incl. so like, same energy, different delivery 🚚

and flip it around: a call to MPI_Group_incl is equivalent to a call to MPI_Group_range_incl where each rank i in ranks gets replaced by the triplet (i,i,1) in the ranges argument. iconic symmetry, honestly 👑

---

⚠️ NOTE ⚠️

heads up bestie 📢 — this implementation does not currently check to see that the list of ranges to include are valid ranks in the group. so it's not gonna catch that for you. you gotta know. fr fr 🫠

---

😭 ERRORS 😭

Almost all MPI routines return an error value; C routines as the return result of the function and Fortran routines in the last argument.

Before the error value is returned, the current MPI error handler associated with the communication object (e.g., communicator, window, file) is 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_thread, after 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 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_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 that can be used:

• MPI_ERRORS_ARE_FATAL — Causes the program to abort all connected MPI processes. 💀 rip
• 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, 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, aborts only the local process.
• MPI_ERRORS_RETURN — Returns an error code to the application. 🫶 the polite one

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.

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_Group_incl
• MPI_Group_free

---

👑 Copyright 👑

2003-2026, The Open MPI Community

---

and that's the whole page bestie!! 💜 this was MPI_GROUP_RANGE_INCL(3) from Open MPI, and it left us on Sep 10, 2026 — mwah, go forth and range-include responsibly, periodt 💅✨🦋