mac mpi

macx64/mpi/openmpi/share/man/man3/MPI_Exscan.3

@@ -0,0 +1,131 @@
+.\" -*- nroff -*-
+.\" Copyright 2013 Los Alamos National Security, LLC. All rights reserved.
+.\" Copyright 2010 Cisco Systems, Inc.  All rights reserved.
+.\" Copyright 2006-2008 Sun Microsystems, Inc.
+.\" Copyright (c) 1996 Thinking Machines Corporation
+.\" $COPYRIGHT$
+.TH MPI_Exscan 3 "Mar 26, 2019" "4.0.1" "Open MPI"
+
+.SH NAME
+\fBMPI_Exscan, MPI_Iexscan\fP \- Computes an exclusive scan (partial reduction)
+
+.SH SYNTAX
+.ft R
+
+.SH C Syntax
+.nf
+#include <mpi.h>
+int MPI_Exscan(const void *\fIsendbuf\fP, void *\fIrecvbuf\fP, int \fIcount\fP,
+	MPI_Datatype \fIdatatype\fP, MPI_Op \fIop\fP, MPI_Comm \fIcomm\fP)
+
+int MPI_Iexscan(const void *\fIsendbuf\fP, void *\fIrecvbuf\fP, int \fIcount\fP,
+	MPI_Datatype \fIdatatype\fP, MPI_Op \fIop\fP, MPI_Comm \fIcomm\fP,
+	MPI_Request \fI*request\fP)
+
+.fi
+.SH INPUT PARAMETERS
+.ft R
+.TP 1i
+sendbuf
+Send buffer (choice).
+.TP 1i
+count
+Number of elements in input buffer (integer).
+.TP 1i
+datatype
+Data type of elements of input buffer (handle).
+.TP 1i
+op
+Operation (handle).
+.TP 1i
+comm
+Communicator (handle).
+
+.SH OUTPUT PARAMETERS
+.ft R
+.TP 1i
+recvbuf
+Receive buffer (choice).
+.TP 1i
+request
+Request (handle, non-blocking only).
+.ft R
+.TP 1i
+IERROR
+Fortran only: Error status (integer).
+
+.SH DESCRIPTION
+.ft R
+MPI_Exscan is used to perform an exclusive prefix reduction on data
+distributed across the calling processes. The operation returns, in
+the \fIrecvbuf\fP of the process with rank i, the reduction
+(calculated according to the function \fIop\fP) of the values in the
+\fIsendbuf\fPs of processes with ranks 0, ..., i-1. Compare this with
+the functionality of MPI_Scan, which calculates over the range 0, ...,
+i (inclusive). The type of operations supported, their semantics, and
+the constraints on send and receive buffers are as for MPI_Reduce.
+.sp
+The value in \fIrecvbuf\fP on process 0 is undefined and unreliable
+as \fIrecvbuf\fP is not significant for process 0. The value of
+\fIrecvbuf\fP on process 1 is always the value in \fIsendbuf\fP on
+process 0.
+.sp
+.SH USE OF IN-PLACE OPTION
+The `in place' option for intracommunicators is specified by passing MPI_IN_PLACE in the \fIsendbuf\fP argument. In this case, the input data is taken from the receive buffer, and replaced by the output data.
+.sp
+Note that MPI_IN_PLACE is a special kind of value; it has the same restrictions on its use as MPI_BOTTOM.
+.sp
+Because the in-place option converts the receive buffer into a send-and-receive buffer, a Fortran binding that includes INTENT must mark these as INOUT, not OUT.
+.sp
+
+.SH NOTES
+.ft R
+MPI does not specify which process computes which operation. In
+particular, both processes 0 and 1 may participate in the computation
+even though the results for both processes' \fIrecvbuf\fP are
+degenerate. Therefore, all processes, including 0 and 1, must provide
+the same \fIop\fP.
+.sp
+It can be argued, from a mathematical perspective, that the definition
+of MPI_Exscan is unsatisfactory because the output at process 0 is
+undefined.  The "mathematically correct" output for process 0 would be
+the unit element of the reduction operation. However, such a
+definition of an exclusive scan would not work with user-defined
+\fIop\fP functions as there is no way for MPI to "know" the unit value
+for these custom operations.
+
+.SH NOTES ON COLLECTIVE OPERATIONS
+.ft R
+The reduction functions of type MPI_Op do not return an error value.
+As a result, if the functions detect an error, all they can do is
+either call MPI_Abort or silently skip the problem. Thus, if the
+error handler is changed from MPI_ERRORS_ARE_FATAL to something else
+(e.g., MPI_ERRORS_RETURN), then no error may be indicated.
+.sp
+The reason for this is the performance problems in ensuring that
+all collective routines return the same error value.
+
+.SH ERRORS
+.ft R
+Almost all MPI routines return an error value; C routines as
+the value of the function and Fortran routines in the last argument. C++
+functions do not return errors. If the default error handler is set to
+MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism
+will be used to throw an MPI::Exception object.
+.sp
+Before the error value is returned, the current MPI error handler is
+called. By default, this error handler aborts the MPI job, except for
+I/O function errors. The error handler may be changed with
+MPI_Comm_set_errhandler; the predefined error handler MPI_ERRORS_RETURN
+may be used to cause error values to be returned. Note that MPI does not
+guarantee that an MPI program can continue past an error.
+.sp
+See the MPI man page for a full list of MPI error codes.
+
+.SH SEE ALSO
+.ft R
+.nf
+MPI_Op_create
+MPI_Reduce
+MPI_Scan
+