Class cartesian_communicator

boost::mpi::cartesian_communicator — An MPI communicator with a cartesian topology.

Synopsis

// In header: <boost/mpi/cartesian_communicator.hpp>


class cartesian_communicator : public boost::mpi::communicator {
public:
  // construct/copy/destruct
  cartesian_communicator(const MPI_Comm &, comm_create_kind);
  cartesian_communicator(const communicator &, const cartesian_topology &, 
                         bool = false);
  cartesian_communicator(const cartesian_communicator &, 
                         const std::vector< int > &);

  // public member functions
  int ndims() const;
  int rank(const std::vector< int > &) const;
  std::pair< int, int > shifted_ranks(int, int) const;
  std::vector< int > coordinates(int) const;
  void topology(cartesian_topology &, std::vector< int > &) const;
  cartesian_topology topology() const;
  int rank();
};

Description

A cartesian_communicator is a communicator whose topology is expressed as a grid. Cartesian communicators have the same functionality as (intra)communicators, but also allow one to query the relationships among processes and the properties of the grid.

`cartesian_communicator` public construct/copy/destruct

```
cartesian_communicator(const MPI_Comm & comm, comm_create_kind kind);
```
Build a new Boost.MPI cartesian communicator based on the MPI communicator comm with cartesian topology.

comm may be any valid MPI communicator. If comm is MPI_COMM_NULL, an empty communicator (that cannot be used for communication) is created and the kind parameter is ignored. Otherwise, the kind parameter determines how the Boost.MPI communicator will be related to comm:
- If kind is comm_duplicate, duplicate comm to create a new communicator. This new communicator will be freed when the Boost.MPI communicator (and all copies of it) is destroyed. This option is only permitted if the underlying MPI implementation supports MPI 2.0; duplication of intercommunicators is not available in MPI 1.x.
- If kind is comm_take_ownership, take ownership of comm. It will be freed automatically when all of the Boost.MPI communicators go out of scope.
- If kind is comm_attach, this Boost.MPI communicator will reference the existing MPI communicator comm but will not free comm when the Boost.MPI communicator goes out of scope. This option should only be used when the communicator is managed by the user.

cartesian_communicator(const communicator & comm, 
                       const cartesian_topology & dims, bool reorder = false);

Create a new communicator whose topology is described by the given cartesian. The indices of the vertices in the cartesian will be assumed to be the ranks of the processes within the communicator. There may be fewer vertices in the cartesian than there are processes in the communicator; in this case, the resulting communicator will be a NULL communicator.

Parameters:

`comm`	The communicator that the new, cartesian communicator will be based on.
`dims`	the cartesian dimension of the new communicator. The size indicate the number of dimension. Some dimensions be set to zero, in which case the corresponding dimension value is left to the system.
`reorder`	Whether MPI is permitted to re-order the process ranks within the returned communicator, to better optimize communication. If false, the ranks of each process in the returned process will match precisely the rank of that process within the original communicator.

```
cartesian_communicator(const cartesian_communicator & comm, 
                       const std::vector< int > & keep);
```
Create a new cartesian communicator whose topology is a subset of an existing cartesian cimmunicator.

Parameters:

comm

the original communicator.

keep

and array containiing the dimension to keep from the existing communicator.

`cartesian_communicator` public member functions

```
int ndims() const;
```
Retrive the number of dimension of the underlying toppology.
```
int rank(const std::vector< int > & coords) const;
```
Return the rank of the process at the given coordinates.

Parameters:

coords

the coordinates. the size must match the communicator's topology.
```
std::pair< int, int > shifted_ranks(int dim, int disp) const;
```
Return the rank of the source and target destination process through a shift.

Parameters:

dim

the dimension in which the shift takes place. 0 <= dim <= ndim().

disp

the shift displacement, can be positive (upward) or negative (downward).
```
std::vector< int > coordinates(int rk) const;
```
Provides the coordinates of the process with the given rank.

Parameters:

rk

the ranks in this communicator.

Returns:

the coordinates.

void topology(cartesian_topology & dims, std::vector< int > & coords) const;

Retrieve the topology and coordinates of this process in the grid.

```
cartesian_topology topology() const;
```
Retrieve the topology of the grid.
```
int rank();
```
Determine the rank of the executing process in a communicator.
This routine is equivalent to MPI_Comm_rank.

Returns:

The rank of the process in the communicator, which will be a value in [0, size())