MPI Subroutine Reference

MPI_ACCUMULATE, MPI_Accumulate

Purpose

Accumulates, according to the specified reduction operation, the contents of the origin buffer to the specified target buffer.

C synopsis

#include <mpi.h>
int MPI_Accumulate (void *origin_addr, int origin_count,
                    MPI_Datatype origin_datatype, int target_rank,
                    MPI_Aint target_disp, int target_count,
                    MPI_Datatype target_datatype, MPI_Op op,
                    MPI_Win win);

C++ synopsis

#include mpi.h
void MPI::Win::Accumulate(const void* origin_addr, int origin_count, 
			  const MPI::Datatype& origin_datatype,
			  int target_rank, MPI::Aint target_disp, 
			  int target_count, const MPI::Datatype& target_datatype, 
			  const MPI::Op& op) const;

FORTRAN synopsis

include 'mpif.h' or use mpi
MPI_ACCUMULATE (CHOICE ORIGIN_ADDR, INTEGER ORIGIN_COUNT,
                INTEGER ORIGIN_DATATYPE, INTEGER TARGET_RANK,
                INTEGER TARGET_DISP, INTEGER TARGET_COUNT,
                INTEGER TARGET_DATATYPE, INTEGER OP,
                INTEGER WIN, INTEGER IERROR)

Parameters

origin_addr

is the initial address of the origin buffer (choice) (IN)

origin_count

is the number of entries in origin buffer (nonnegative integer) (IN)

origin_datatype

is the datatype of each entry in the origin buffer (handle) (IN)

target_rank

is the rank of the target (nonnegative integer) (IN)

target_disp

is the displacement from the start of the window to the target buffer (nonnegative integer) (IN)

target_count

is the number of entries in the target buffer (nonnegative integer) (IN)

target_datatype

is the datatype of each entry in the target buffer (handle) (IN)

op

is the reduction operation (handle) (IN)

win

is the window object used for communication (handle) (IN)

IERROR

is the FORTRAN return code. It is always the last argument.

Description

This subroutine accumulates the contents of the origin buffer (as defined by origin_addr, origin_count, and origin_datatype) to the buffer specified by arguments target_count and target_datatype, at offset target_disp, in the target window specified by target_rank and win, using the operation op. MPI_ACCUMULATE is similar to MPI_PUT, except that data is combined into (rather than overwritten in) the target area.

Any of the predefined operations for MPI_REDUCE can be used. User-defined functions cannot be used. For example, if op is MPI_SUM, each element of the origin buffer is added to the corresponding element in the target, replacing the former value in the target.

Each datatype argument must be a predefined datatype or a derived datatype, where all basic components are of the same predefined datatype. Both datatype arguments must be constructed from the same predefined datatype. The operation op applies to elements of that predefined type. target_datatype must not specify overlapping entries, and the target buffer must fit in the target window.

A new predefined operation, MPI_REPLACE, corresponds to the associative function f(a,b) = b. That is, the current value in the target memory is replaced by the value supplied by the origin.

Notes

MPI_ACCUMULATE does not require that data move from origin to target until some synchronization occurs. PE MPI may try to combine multiple puts to a target within an epoch into a single data transfer. The user must not modify the source buffer or make any assumption about the contents of the destination buffer until after a synchronization operation has closed the epoch.

On some systems, there may be reasons to use special memory for one-sided communication buffers. MPI_ALLOC_MEM may be the preferred way to allocate buffers on these systems. With PE MPI, there is no advantage to using MPI_ALLOC_MEM, but you can use it to improve the portability of your MPI code.

Errors

Invalid origin count (count)

Invalid origin datatype (handle)

Invalid target rank (rank)

Invalid target displacement (value)

Invalid target count (count)

Invalid target datatype (handle)

Invalid window handle (handle)

Target outside access group

Origin buffer too small (size)

Target buffer ends outside target window

Target buffer starts outside target window

RMA communication call outside access epoch

RMA communication call in progress

RMA synchronization call in progress

Origin datatype inappropriate for accumulate

Target datatype inappropriate for accumulate

Incompatible origin and target datatypes

Invalid reduction operation (op)

Related information

MPI_GET

MPI_PUT