| Home | Libraries | People | FAQ | More

## Function reduce

boost::mpi::reduce — Combine the values stored by each process into a single value at the root.

## Synopsis

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

    template<typename T, typename Op>
      void reduce(const communicator & comm, const T & in_value, T & out_value,
                  Op op, int root);
    template<typename T, typename Op>
      void reduce(const communicator & comm, const T & in_value, Op op, int root);
    template<typename T, typename Op>
      void reduce(const communicator & comm, const T * in_values, int n,
                  T * out_values, Op op, int root);
    template<typename T, typename Op>
      void reduce(const communicator & comm, const T * in_values, int n, Op op,
                  int root);

## Description

`reduce` is a collective algorithm that combines the values stored by each process into a single value at the `root`. The values can be combined arbitrarily, specified via a function object. The type `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 `gather` to the `root`, followed by an `std::accumulate()` over the gathered values and using the operation `op`.

When the type `T` has an associated MPI data type, this routine invokes `MPI_Reduce` to perform the reduction. If possible, built-in MPI operations will be used; otherwise, `reduce()` will create a custom MPI_Op for the call to MPI_Reduce.

Parameters:

`comm` | The communicator over which the reduction will occur.

`in_value`

The local value to be combined with the local values of every other process. For reducing arrays, `in_values` contains a pointer to the local values. In this case, `n` is the number of values that will be reduced. Reduction occurs independently for each of the `n` values referenced by `in_values`, e.g., calling reduce on an array of `n` values is like calling `reduce` `n` separate times, one for each location in `in_values` and `out_values`.

`op`

The binary operation that combines two values of type `T` into a third value of type `T`. For types `T` that has ssociated MPI data types, `op` will either be translated into an `MPI_Op` (via `MPI_Op_create`) or, if possible, mapped directly to a built-in MPI operation. See `is_mpi_op` in the `operations.hpp` header for more details on this mapping. For any non-built-in operation, commutativity will be determined by the `is_commmutative` trait (also in `operations.hpp`): users are encouraged to mark commutative operations as such, because it gives the implementation additional lattitude to optimize the reduction operation.

`out_value` | Will receive the result of the reduction operation, but only for the `root` process. Non-root processes may omit if parameter; if they choose to supply the parameter, it will be unchanged. For reducing arrays, `out_values` contains a pointer to the storage for the output values.
`root` | The process ID number that will receive the final, combined value. This value must be the same on all processes.