| Home | Libraries | People | FAQ | More

## 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

1.     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.

2.     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.

3.     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

1.     int ndims() const;

   Retrive the number of dimension of the underlying toppology.

2.     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.

3.     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).

4.     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.

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

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

6.     cartesian_topology topology() const;

   Retrieve the topology of the grid.

7.     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())