MPI Subroutine Reference

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