// Copyright Alain Miniussi 2014.
|
// Distributed under the Boost Software License, Version 1.0.
|
// (See accompanying file LICENSE_1_0.txt or copy at
|
// http://www.boost.org/LICENSE_1_0.txt)
|
|
// Authors: Alain Miniussi
|
|
/** @file cartesian_communicator.hpp
|
*
|
* This header defines facilities to support MPI communicators with
|
* cartesian topologies.
|
* If known at compiled time, the dimension of the implied grid
|
* can be statically enforced, through the templatized communicator
|
* class. Otherwise, a non template, dynamic, base class is provided.
|
*
|
*/
|
#ifndef BOOST_MPI_CARTESIAN_COMMUNICATOR_HPP
|
#define BOOST_MPI_CARTESIAN_COMMUNICATOR_HPP
|
|
#include <boost/mpi/communicator.hpp>
|
|
#include <vector>
|
#include <utility>
|
#include <iostream>
|
#include <utility>
|
#if !defined(BOOST_NO_CXX11_HDR_INITIALIZER_LIST)
|
#include <initializer_list>
|
#endif // BOOST_NO_CXX11_HDR_INITIALIZER_LIST
|
|
// Headers required to implement cartesian topologies
|
#include <boost/shared_array.hpp>
|
#include <boost/assert.hpp>
|
#include <boost/foreach.hpp>
|
|
namespace boost { namespace mpi {
|
|
/**
|
* @brief Specify the size and periodicity of the grid in a single dimension.
|
*
|
* POD lightweight object.
|
*/
|
struct cartesian_dimension {
|
/** The size of the grid n this dimension. */
|
int size;
|
/** Is the grid periodic in this dimension. */
|
bool periodic;
|
|
cartesian_dimension(int sz = 0, bool p = false) : size(sz), periodic(p) {}
|
|
private:
|
friend class boost::serialization::access;
|
template<class Archive>
|
void serialize(Archive & ar, const unsigned int version)
|
{
|
ar & size & periodic;
|
}
|
|
};
|
|
template <>
|
struct is_mpi_datatype<cartesian_dimension> : mpl::true_ { };
|
|
/**
|
* @brief Test if the dimensions values are identical.
|
*/
|
inline
|
bool
|
operator==(cartesian_dimension const& d1, cartesian_dimension const& d2) {
|
return &d1 == &d2 || (d1.size == d2.size && d1.periodic == d2.periodic);
|
}
|
|
/**
|
* @brief Test if the dimension values are different.
|
*/
|
inline
|
bool
|
operator!=(cartesian_dimension const& d1, cartesian_dimension const& d2) {
|
return !(d1 == d2);
|
}
|
|
/**
|
* @brief Pretty printing of a cartesian dimension (size, periodic)
|
*/
|
std::ostream& operator<<(std::ostream& out, cartesian_dimension const& d);
|
|
/**
|
* @brief Describe the topology of a cartesian grid.
|
*
|
* Behave mostly like a sequence of @c cartesian_dimension with the notable
|
* exception that its size is fixed.
|
* This is a lightweight object, so that any constructor that could be considered
|
* missing could be replaced with a function (move constructor provided when supported).
|
*/
|
class BOOST_MPI_DECL cartesian_topology
|
: private std::vector<cartesian_dimension> {
|
friend class cartesian_communicator;
|
typedef std::vector<cartesian_dimension> super;
|
public:
|
/**
|
* Retrieve a specific dimension.
|
*/
|
using super::operator[];
|
/**
|
* @brief Topology dimentionality.
|
*/
|
using super::size;
|
using super::begin;
|
using super::end;
|
using super::swap;
|
|
#if !defined(BOOST_NO_CXX11_DELETED_FUNCTIONS)
|
cartesian_topology() = delete;
|
#endif
|
#if !defined(BOOST_NO_CXX11_DEFAULTED_FUNCTIONS)
|
cartesian_topology(cartesian_topology const&) = default;
|
cartesian_topology& operator=(cartesian_topology const&) = default;
|
// There is apparently no macro for checking the support of move constructor.
|
// Assume that defaulted function is close enough.
|
#if !defined(BOOST_NO_CXX11_DEFAULTED_MOVES)
|
cartesian_topology(cartesian_topology&& other) : super(other) {}
|
cartesian_topology& operator=(cartesian_topology&& other) {
|
stl().swap(other.stl());
|
return *this;
|
}
|
#endif
|
~cartesian_topology() = default;
|
#endif
|
/**
|
* @brief Create a N dimension space.
|
* Each dimension is initialized as non periodic of size 0.
|
*/
|
cartesian_topology(int ndim)
|
: super(ndim) {}
|
|
/**
|
* @brief Use the provided dimensions specification as initial values.
|
*/
|
cartesian_topology(std::vector<cartesian_dimension> const& dims)
|
: super(dims) {}
|
|
/**
|
* @brief Use dimensions specification provided in the sequence container as initial values.
|
* #param dims must be a sequence container.
|
*/
|
template<class InitArr>
|
explicit cartesian_topology(InitArr dims)
|
: super(0) {
|
BOOST_FOREACH(cartesian_dimension const& d, dims) {
|
push_back(d);
|
}
|
}
|
#if !defined(BOOST_NO_CXX11_HDR_INITIALIZER_LIST)
|
/**
|
* @brief Use dimensions specification provided in the initialization list as initial values.
|
* #param dims can be of the form { dim_1, false}, .... {dim_n, true}
|
*/
|
explicit cartesian_topology(std::initializer_list<cartesian_dimension> dims)
|
: super(dims) {}
|
#endif
|
/**
|
* @brief Use dimensions specification provided in the array.
|
* #param dims can be of the form { dim_1, false}, .... {dim_n, true}
|
*/
|
template<int NDIM>
|
explicit cartesian_topology(cartesian_dimension (&dims)[NDIM])
|
: super(dims, dims+NDIM) {}
|
|
/**
|
* @brief Use dimensions specification provided in the input ranges
|
* The ranges do not need to be the same size. If the sizes are different,
|
* the missing values will be complete with zeros of the dim and assumed non periodic.
|
* @param dim_rg the dimensions, values must convert to integers.
|
* @param period_rg the periodicities, values must convert to booleans.
|
* #param dims can be of the form { dim_1, false}, .... {dim_n, true}
|
*/
|
template<class DimRg, class PerRg>
|
cartesian_topology(DimRg const& dim_rg, PerRg const& period_rg)
|
: super(0) {
|
BOOST_FOREACH(int d, dim_rg) {
|
super::push_back(cartesian_dimension(d));
|
}
|
super::iterator it = begin();
|
BOOST_FOREACH(bool p, period_rg) {
|
if (it < end()) {
|
it->periodic = p;
|
} else {
|
push_back(cartesian_dimension(0,p));
|
}
|
++it;
|
}
|
}
|
|
|
/**
|
* @brief Iterator based initializer.
|
* Will use the first n iterated values.
|
* Both iterators can be single pass.
|
* @param dit dimension iterator, value must convert to integer type.
|
* @param pit periodicity iterator, value must convert to booleans..
|
*/
|
template<class DimIter, class PerIter>
|
cartesian_topology(DimIter dit, PerIter pit, int n)
|
: super(n) {
|
for(int i = 0; i < n; ++i) {
|
(*this)[i] = cartesian_dimension(*dit++, *pit++);
|
}
|
}
|
|
/**
|
* Export as an stl sequence.
|
*/
|
std::vector<cartesian_dimension>& stl() { return *this; }
|
/**
|
* Export as an stl sequence.
|
*/
|
std::vector<cartesian_dimension> const& stl() const{ return *this; }
|
/**
|
* Split the topology in two sequences of sizes and periodicities.
|
*/
|
void split(std::vector<int>& dims, std::vector<bool>& periodics) const;
|
};
|
|
inline
|
bool
|
operator==(cartesian_topology const& t1, cartesian_topology const& t2) {
|
return t1.stl() == t2.stl();
|
}
|
|
inline
|
bool
|
operator!=(cartesian_topology const& t1, cartesian_topology const& t2) {
|
return t1.stl() != t2.stl();
|
}
|
|
/**
|
* @brief Pretty printing of a cartesian topology
|
*/
|
std::ostream& operator<<(std::ostream& out, cartesian_topology const& t);
|
|
/**
|
* @brief An MPI communicator with a cartesian topology.
|
*
|
* A @c 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.
|
*/
|
class BOOST_MPI_DECL cartesian_communicator : public communicator
|
{
|
friend class communicator;
|
|
/**
|
* INTERNAL ONLY
|
*
|
* Construct a cartesian communicator given a shared pointer to the
|
* underlying MPI_Comm (which must have a cartesian topology).
|
* This operation is used for "casting" from a communicator to
|
* a cartesian communicator.
|
*/
|
explicit cartesian_communicator(const shared_ptr<MPI_Comm>& comm_ptr)
|
: communicator()
|
{
|
this->comm_ptr = comm_ptr;
|
BOOST_ASSERT(has_cartesian_topology());
|
}
|
|
public:
|
/**
|
* Build a new Boost.MPI cartesian communicator based on the MPI
|
* communicator @p comm with cartesian topology.
|
*
|
* @p comm may be any valid MPI communicator. If @p comm is
|
* MPI_COMM_NULL, an empty communicator (that cannot be used for
|
* communication) is created and the @p kind parameter is
|
* ignored. Otherwise, the @p kind parameter determines how the
|
* Boost.MPI communicator will be related to @p comm:
|
*
|
* - If @p kind is @c comm_duplicate, duplicate @c 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 @p kind is @c comm_take_ownership, take ownership of @c
|
* comm. It will be freed automatically when all of the Boost.MPI
|
* communicators go out of scope.
|
*
|
* - If @p kind is @c comm_attach, this Boost.MPI communicator
|
* will reference the existing MPI communicator @p comm but will
|
* not free @p 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 MPI_Comm& comm, comm_create_kind kind)
|
: communicator(comm, kind)
|
{
|
BOOST_ASSERT(has_cartesian_topology());
|
}
|
|
/**
|
* 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.
|
*
|
* @param comm The communicator that the new, cartesian communicator
|
* will be based on.
|
*
|
* @param 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.
|
*
|
* @param 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 communicator& comm,
|
const cartesian_topology& dims,
|
bool reorder = false);
|
|
/**
|
* Create a new cartesian communicator whose topology is a subset of
|
* an existing cartesian cimmunicator.
|
* @param comm the original communicator.
|
* @param keep and array containiing the dimension to keep from the existing
|
* communicator.
|
*/
|
cartesian_communicator(const cartesian_communicator& comm,
|
const std::vector<int>& keep );
|
|
using communicator::rank;
|
|
/**
|
* Retrive the number of dimension of the underlying toppology.
|
*/
|
int ndims() const;
|
|
/**
|
* Return the rank of the process at the given coordinates.
|
* @param coords the coordinates. the size must match the communicator's topology.
|
*/
|
int rank(const std::vector<int>& coords) const;
|
/**
|
* Return the rank of the source and target destination process through a shift.
|
* @param dim the dimension in which the shift takes place. 0 <= dim <= ndim().
|
* @param disp the shift displacement, can be positive (upward) or negative (downward).
|
*/
|
std::pair<int, int> shifted_ranks(int dim, int disp) const;
|
/**
|
* Provides the coordinates of the process with the given rank.
|
* @param rk the ranks in this communicator.
|
* @returns the coordinates.
|
*/
|
std::vector<int> coordinates(int rk) const;
|
/**
|
* Retrieve the topology and coordinates of this process in the grid.
|
*
|
*/
|
void topology( cartesian_topology& dims, std::vector<int>& coords ) const;
|
/**
|
* Retrieve the topology of the grid.
|
*
|
*/
|
cartesian_topology topology() const;
|
};
|
|
/**
|
* Given en number of processes, and a partially filled sequence
|
* of dimension, try to complete the dimension sequence.
|
* @param nb_proc the numer of mpi processes.fill a sequence of dimension.
|
* @param dims a sequence of positive or null dimensions. Non zero dimension
|
* will be left untouched.
|
*/
|
std::vector<int>& cartesian_dimensions(int nb_proc, std::vector<int>& dims);
|
|
} } // end namespace boost::mpi
|
|
#endif // BOOST_MPI_CARTESIAN_COMMUNICATOR_HPP
|
