MPI_COMM_CREATE, MPI_Comm_create

Purpose

Creates a new communicator with a given group.

C synopsis

#include <mpi.h>
int MPI_Comm_create(MPI_Comm comm_in, MPI_Group group, MPI_Comm *comm_out);

C++ synopsis

#include mpi.h
MPI::Intercomm MPI::Intercomm::Create(const MPI::Group& group) const;

#include mpi.h
MPI::Intracomm MPI::Intracomm::Create(const MPI::Group& group) const;

FORTRAN synopsis

include 'mpif.h' or use mpi
MPI_COMM_CREATE(INTEGER COMM_IN, INTEGER GROUP, INTEGER COMM_OUT,
      INTEGER IERROR)

Parameters

comm_in
     is the original communicator (handle) (IN)

group
     is a group of tasks that will be in the new communicator (handle) (IN)

comm_out
     is the new communicator (handle) (OUT)

IERROR
     is the FORTRAN return code. It is always the last argument.

Description

MPI_COMM_CREATE is a collective operation that is invoked by all tasks in
the group associated with comm_in. This subroutine creates a new
communicator comm_out with the communication group defined by group and a
new context. Cached information is not propagated from comm_in to comm_out.

For tasks that are not in group, MPI_COMM_NULL is returned. The call is
erroneous if group is not a subset of the group associated with comm_in.
The call is executed by all tasks in comm_in even if they do not belong to
the new group.

If comm_in is an intercommunicator, the output communicator is also an
intercommunicator where the local group consists only of those tasks
contained in group. The group argument should only contain those tasks in
the local group of the input intercommunicator that are to be a part of
comm_out. If either group does not specify at least one task in the local
group of the intercommunicator, or if the calling task is not included in
the group, MPI_COMM_NULL is returned.

Notes

MPI_COMM_CREATE provides a way to subset a group of tasks for the purpose
of separate MIMD computation with separate communication space. You can use
comm_out in subsequent calls to MPI_COMM_CREATE or other communicator
constructors to further subdivide a computation into parallel
sub-computations.

Errors

Fatal errors:

Conflicting collective operations on communicator

Invalid communicator

Invalid group
     group is not a subset of the group associated with comm_in

MPI not initialized

MPI already finalized

Related information

     MPI_COMM_DUP
     MPI_COMM_SPLIT