boost/mpi/collectives.hpp
// Copyright (C) 2005-2006 Douglas Gregor <doug.gregor -at- gmail.com>. // Use, modification and distribution is subject to 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) // Message Passing Interface 1.1 -- Section 4. MPI Collectives /** @file collectives.hpp * * This header contains MPI collective operations, which implement * various parallel algorithms that require the coordination of all * processes within a communicator. The header @c collectives_fwd.hpp * provides forward declarations for each of these operations. To * include only specific collective algorithms, use the headers @c * boost/mpi/collectives/algorithm_name.hpp. */ #ifndef BOOST_MPI_COLLECTIVES_HPP #define BOOST_MPI_COLLECTIVES_HPP #include <boost/mpi/communicator.hpp> #include <vector> namespace boost { namespace mpi { /** * @brief Gather the values stored at every process into vectors of * values from each process. * * @c all_gather is a collective algorithm that collects the values * stored at each process into a vector of values indexed by the * process number they came from. The type @c T of the values may be * any type that is serializable or has an associated MPI data type. * * When the type @c T has an associated MPI data type, this routine * invokes @c MPI_Allgather to gather the values. * * @param comm The communicator over which the all-gather will * occur. * * @param in_value The value to be transmitted by each process. To * gather an array of values, @c in_values points to the @c n local * values to be transmitted. * * @param out_values A vector or pointer to storage that will be * populated with the values from each process, indexed by the * process ID number. If it is a vector, the vector will be resized * accordingly. */ template<typename T> void all_gather(const communicator& comm, const T& in_value, std::vector<T>& out_values); /** * \overload */ template<typename T> void all_gather(const communicator& comm, const T& in_value, T* out_values); /** * \overload */ template<typename T> void all_gather(const communicator& comm, const T* in_values, int n, std::vector<T>& out_values); /** * \overload */ template<typename T> void all_gather(const communicator& comm, const T* in_values, int n, T* out_values); /** * @brief Combine the values stored by each process into a single * value available to all processes. * * @c all_reduce is a collective algorithm that combines the values * stored by each process into a single value available to all * processes. The values are combined in a user-defined way, * specified via a function object. The type @c T of the values may * be any type that is serializable or has an associated MPI data * type. One can think of this operation as a @c all_gather, followed * by an @c std::accumulate() over the gather values and using the * operation @c op. * * When the type @c T has an associated MPI data type, this routine * invokes @c MPI_Allreduce to perform the reduction. If possible, * built-in MPI operations will be used; otherwise, @c all_reduce() * will create a custom MPI_Op for the call to MPI_Allreduce. * * @param comm The communicator over which the reduction will * occur. * * @param in_value The local value to be combined with the local * values of every other process. For reducing arrays, @c in_values * is a pointer to the local values to be reduced and @c n is the * number of values to reduce. See @c reduce for more information. * * @param out_value Will receive the result of the reduction * operation. If this parameter is omitted, the outgoing value will * instead be returned. * * @param op The binary operation that combines two values of type * @c T and returns a third value of type @c T. For types @c T that has * ssociated MPI data types, @c op will either be translated into * an @c MPI_Op (via @c MPI_Op_create) or, if possible, mapped * directly to a built-in MPI operation. See @c is_mpi_op in the @c * operations.hpp header for more details on this mapping. For any * non-built-in operation, commutativity will be determined by the * @c is_commmutative trait (also in @c operations.hpp): users are * encouraged to mark commutative operations as such, because it * gives the implementation additional lattitude to optimize the * reduction operation. * * @returns If no @p out_value parameter is supplied, returns the * result of the reduction operation. */ template<typename T, typename Op> void all_reduce(const communicator& comm, const T& in_value, T& out_value, Op op); /** * \overload */ template<typename T, typename Op> T all_reduce(const communicator& comm, const T& in_value, Op op); /** * \overload */ template<typename T, typename Op> void all_reduce(const communicator& comm, const T* in_values, int n, T* out_values, Op op); /** * @brief Send data from every process to every other process. * * @c all_to_all is a collective algorithm that transmits @c p values * from every process to every other process. On process i, jth value * of the @p in_values vector is sent to process j and placed in the * ith position of the @p out_values vector in process @p j. The type * @c T of the values may be any type that is serializable or has an * associated MPI data type. If @c n is provided, then arrays of @p n * values will be transferred from one process to another. * * When the type @c T has an associated MPI data type, this routine * invokes @c MPI_Alltoall to scatter the values. * * @param comm The communicator over which the all-to-all * communication will occur. * * @param in_values A vector or pointer to storage that contains * the values to send to each process, indexed by the process ID * number. * * @param out_values A vector or pointer to storage that will be * updated to contain the values received from other processes. The * jth value in @p out_values will come from the procss with rank j. */ template<typename T> void all_to_all(const communicator& comm, const std::vector<T>& in_values, std::vector<T>& out_values); /** * \overload */ template<typename T> void all_to_all(const communicator& comm, const T* in_values, T* out_values); /** * \overload */ template<typename T> void all_to_all(const communicator& comm, const std::vector<T>& in_values, int n, std::vector<T>& out_values); /** * \overload */ template<typename T> void all_to_all(const communicator& comm, const T* in_values, int n, T* out_values); /** * @brief Broadcast a value from a root process to all other * processes. * * @c broadcast is a collective algorithm that transfers a value from * an arbitrary @p root process to every other process that is part of * the given communicator. The @c broadcast algorithm can transmit any * Serializable value, values that have associated MPI data types, * packed archives, skeletons, and the content of skeletons; see the * @c send primitive for communicators for a complete list. The type * @c T shall be the same for all processes that are a part of the * communicator @p comm, unless packed archives are being transferred: * with packed archives, the root sends a @c packed_oarchive or @c * packed_skeleton_oarchive whereas the other processes receive a * @c packed_iarchive or @c packed_skeleton_iarchve, respectively. * * When the type @c T has an associated MPI data type, this routine * invokes @c MPI_Bcast to perform the broadcast. * * @param comm The communicator over which the broadcast will * occur. * * @param value The value (or values, if @p n is provided) to be * transmitted (if the rank of @p comm is equal to @p root) or * received (if the rank of @p comm is not equal to @p root). When * the @p value is a @c skeleton_proxy, only the skeleton of the * object will be broadcast. In this case, the @p root will build a * skeleton from the object help in the proxy and all of the * non-roots will reshape the objects held in their proxies based on * the skeleton sent from the root. * * @param n When supplied, the number of values that the pointer @p * values points to, for broadcasting an array of values. The value * of @p n must be the same for all processes in @p comm. * * @param root The rank/process ID of the process that will be * transmitting the value. */ template<typename T> void broadcast(const communicator& comm, T& value, int root); /** * \overload */ template<typename T> void broadcast(const communicator& comm, T* values, int n, int root); /** * \overload */ template<typename T> void broadcast(const communicator& comm, skeleton_proxy<T>& value, int root); /** * \overload */ template<typename T> void broadcast(const communicator& comm, const skeleton_proxy<T>& value, int root); /** * @brief Gather the values stored at every process into a vector at * the root process. * * @c gather is a collective algorithm that collects the values * stored at each process into a vector of values at the @p root * process. This vector is indexed by the process number that the * value came from. The type @c T of the values may be any type that * is serializable or has an associated MPI data type. * * When the type @c T has an associated MPI data type, this routine * invokes @c MPI_Gather to gather the values. * * @param comm The communicator over which the gather will occur. * * @param in_value The value to be transmitted by each process. For * gathering arrays of values, @c in_values points to storage for * @c n*comm.size() values. * * @param out_values A vector or pointer to storage that will be * populated with the values from each process, indexed by the * process ID number. If it is a vector, it will be resized * accordingly. For non-root processes, this parameter may be * omitted. If it is still provided, however, it will be unchanged. * * @param root The process ID number that will collect the * values. This value must be the same on all processes. */ template<typename T> void gather(const communicator& comm, const T& in_value, std::vector<T>& out_values, int root); /** * \overload */ template<typename T> void gather(const communicator& comm, const T& in_value, T* out_values, int root); /** * \overload */ template<typename T> void gather(const communicator& comm, const T& in_value, int root); /** * \overload */ template<typename T> void gather(const communicator& comm, const T* in_values, int n, std::vector<T>& out_values, int root); /** * \overload */ template<typename T> void gather(const communicator& comm, const T* in_values, int n, T* out_values, int root); /** * \overload */ template<typename T> void gather(const communicator& comm, const T* in_values, int n, int root); /** * @brief Scatter the values stored at the root to all processes * within the communicator. * * @c scatter is a collective algorithm that scatters the values * stored in the @p root process (inside a vector) to all of the * processes in the communicator. The vector @p out_values (only * significant at the @p root) is indexed by the process number to * which the corresponding value will be sent. The type @c T of the * values may be any type that is serializable or has an associated * MPI data type. * * When the type @c T has an associated MPI data type, this routine * invokes @c MPI_Scatter to scatter the values. * * @param comm The communicator over which the gather will occur. * * @param in_values A vector or pointer to storage that will contain * the values to send to each process, indexed by the process rank. * For non-root processes, this parameter may be omitted. If it is * still provided, however, it will be unchanged. * * @param out_value The value received by each process. When * scattering an array of values, @p out_values points to the @p n * values that will be received by each process. * * @param root The process ID number that will scatter the * values. This value must be the same on all processes. */ template<typename T> void scatter(const communicator& comm, const std::vector<T>& in_values, T& out_value, int root); /** * \overload */ template<typename T> void scatter(const communicator& comm, const T* in_values, T& out_value, int root); /** * \overload */ template<typename T> void scatter(const communicator& comm, T& out_value, int root); /** * \overload */ template<typename T> void scatter(const communicator& comm, const std::vector<T>& in_values, T* out_values, int n, int root); /** * \overload */ template<typename T> void scatter(const communicator& comm, const T* in_values, T* out_values, int n, int root); /** * \overload */ template<typename T> void scatter(const communicator& comm, T* out_values, int n, int root); /** * @brief Combine the values stored by each process into a single * value at the root. * * @c reduce is a collective algorithm that combines the values * stored by each process into a single value at the @c root. The * values can be combined arbitrarily, specified via a function * object. The type @c T of the values may be any type that is * serializable or has an associated MPI data type. One can think of * this operation as a @c gather to the @p root, followed by an @c * std::accumulate() over the gathered values and using the operation * @c op. * * When the type @c T has an associated MPI data type, this routine * invokes @c MPI_Reduce to perform the reduction. If possible, * built-in MPI operations will be used; otherwise, @c reduce() will * create a custom MPI_Op for the call to MPI_Reduce. * * @param comm The communicator over which the reduction will * occur. * * @param in_value The local value to be combined with the local * values of every other process. For reducing arrays, @c in_values * contains a pointer to the local values. In this case, @c n is * the number of values that will be reduced. Reduction occurs * independently for each of the @p n values referenced by @p * in_values, e.g., calling reduce on an array of @p n values is * like calling @c reduce @p n separate times, one for each * location in @p in_values and @p out_values. * * @param out_value Will receive the result of the reduction * operation, but only for the @p root process. Non-root processes * may omit if parameter; if they choose to supply the parameter, * it will be unchanged. For reducing arrays, @c out_values * contains a pointer to the storage for the output values. * * @param op The binary operation that combines two values of type * @c T into a third value of type @c T. For types @c T that has * ssociated MPI data types, @c op will either be translated into * an @c MPI_Op (via @c MPI_Op_create) or, if possible, mapped * directly to a built-in MPI operation. See @c is_mpi_op in the @c * operations.hpp header for more details on this mapping. For any * non-built-in operation, commutativity will be determined by the * @c is_commmutative trait (also in @c operations.hpp): users are * encouraged to mark commutative operations as such, because it * gives the implementation additional lattitude to optimize the * reduction operation. * * @param root The process ID number that will receive the final, * combined value. This value must be the same on all processes. */ template<typename T, typename Op> void reduce(const communicator& comm, const T& in_value, T& out_value, Op op, int root); /** * \overload */ template<typename T, typename Op> void reduce(const communicator& comm, const T& in_value, Op op, int root); /** * \overload */ template<typename T, typename Op> void reduce(const communicator& comm, const T* in_values, int n, T* out_values, Op op, int root); /** * \overload */ template<typename T, typename Op> void reduce(const communicator& comm, const T* in_values, int n, Op op, int root); /** * @brief Compute a prefix reduction of values from all processes in * the communicator. * * @c scan is a collective algorithm that combines the values stored * by each process with the values of all processes with a smaller * rank. The values can be arbitrarily combined, specified via a * function object @p op. The type @c T of the values may be any type * that is serializable or has an associated MPI data type. One can * think of this operation as a @c gather to some process, followed * by an @c std::prefix_sum() over the gathered values using the * operation @c op. The ith process returns the ith value emitted by * @c std::prefix_sum(). * * When the type @c T has an associated MPI data type, this routine * invokes @c MPI_Scan to perform the reduction. If possible, * built-in MPI operations will be used; otherwise, @c scan() will * create a custom @c MPI_Op for the call to MPI_Scan. * * @param comm The communicator over which the prefix reduction * will occur. * * @param in_value The local value to be combined with the local * values of other processes. For the array variant, the @c * in_values parameter points to the @c n local values that will be * combined. * * @param out_value If provided, the ith process will receive the * value @c op(in_value[0], op(in_value[1], op(..., in_value[i]) * ... )). For the array variant, @c out_values contains a pointer * to storage for the @c n output values. The prefix reduction * occurs independently for each of the @p n values referenced by * @p in_values, e.g., calling scan on an array of @p n values is * like calling @c scan @p n separate times, one for each location * in @p in_values and @p out_values. * * @param op The binary operation that combines two values of type * @c T into a third value of type @c T. For types @c T that has * ssociated MPI data types, @c op will either be translated into * an @c MPI_Op (via @c MPI_Op_create) or, if possible, mapped * directly to a built-in MPI operation. See @c is_mpi_op in the @c * operations.hpp header for more details on this mapping. For any * non-built-in operation, commutativity will be determined by the * @c is_commmutative trait (also in @c operations.hpp). * * @returns If no @p out_value parameter is provided, returns the * result of prefix reduction. */ template<typename T, typename Op> void scan(const communicator& comm, const T& in_value, T& out_value, Op op); /** * \overload */ template<typename T, typename Op> T scan(const communicator& comm, const T& in_value, Op op); /** * \overload */ template<typename T, typename Op> void scan(const communicator& comm, const T* in_values, int n, T* out_values, Op op); } } // end namespace boost::mpi #endif // BOOST_MPI_COLLECTIVES_HPP #ifndef BOOST_MPI_COLLECTIVES_FORWARD_ONLY // Include implementations of each of the collectives # include <boost/mpi/collectives/all_gather.hpp> # include <boost/mpi/collectives/all_reduce.hpp> # include <boost/mpi/collectives/all_to_all.hpp> # include <boost/mpi/collectives/broadcast.hpp> # include <boost/mpi/collectives/gather.hpp> # include <boost/mpi/collectives/scatter.hpp> # include <boost/mpi/collectives/reduce.hpp> # include <boost/mpi/collectives/scan.hpp> #endif