blob: f5322b4a6f0f5d92fc432c543790b8e5fe71688b [file] [log] [blame]
 namespace Eigen { /** \eigenManualPage TutorialReductionsVisitorsBroadcasting Reductions, visitors and broadcasting This page explains Eigen's reductions, visitors and broadcasting and how they are used with \link MatrixBase matrices \endlink and \link ArrayBase arrays \endlink. \eigenAutoToc \section TutorialReductionsVisitorsBroadcastingReductions Reductions In Eigen, a reduction is a function taking a matrix or array, and returning a single scalar value. One of the most used reductions is \link DenseBase::sum() .sum() \endlink, returning the sum of all the coefficients inside a given matrix or array.
Example:Output:
\include tut_arithmetic_redux_basic.cpp \verbinclude tut_arithmetic_redux_basic.out
The \em trace of a matrix, as returned by the function \c trace(), is the sum of the diagonal coefficients and can equivalently be computed a.diagonal().sum(). \subsection TutorialReductionsVisitorsBroadcastingReductionsNorm Norm computations The (Euclidean a.k.a. \f$\ell^2\f$) squared norm of a vector can be obtained \link MatrixBase::squaredNorm() squaredNorm() \endlink. It is equal to the dot product of the vector by itself, and equivalently to the sum of squared absolute values of its coefficients. Eigen also provides the \link MatrixBase::norm() norm() \endlink method, which returns the square root of \link MatrixBase::squaredNorm() squaredNorm() \endlink. These operations can also operate on matrices; in that case, a n-by-p matrix is seen as a vector of size (n*p), so for example the \link MatrixBase::norm() norm() \endlink method returns the "Frobenius" or "Hilbert-Schmidt" norm. We refrain from speaking of the \f$\ell^2\f$ norm of a matrix because that can mean different things. If you want other coefficient-wise \f$\ell^p\f$ norms, use the \link MatrixBase::lpNorm lpNorm

() \endlink method. The template parameter \a p can take the special value \a Infinity if you want the \f$\ell^\infty\f$ norm, which is the maximum of the absolute values of the coefficients. The following example demonstrates these methods.

Example:Output:
\b Operator \b norm: The 1-norm and \f$\infty\f$-norm matrix operator norms can easily be computed as follows:
Example:Output:
See below for more explanations on the syntax of these expressions. \subsection TutorialReductionsVisitorsBroadcastingReductionsBool Boolean reductions The following reductions operate on boolean values: - \link DenseBase::all() all() \endlink returns \b true if all of the coefficients in a given Matrix or Array evaluate to \b true . - \link DenseBase::any() any() \endlink returns \b true if at least one of the coefficients in a given Matrix or Array evaluates to \b true . - \link DenseBase::count() count() \endlink returns the number of coefficients in a given Matrix or Array that evaluate to \b true. These are typically used in conjunction with the coefficient-wise comparison and equality operators provided by Array. For instance, array > 0 is an %Array of the same size as \c array , with \b true at those positions where the corresponding coefficient of \c array is positive. Thus, (array > 0).all() tests whether all coefficients of \c array are positive. This can be seen in the following example:
Example:Output:
\subsection TutorialReductionsVisitorsBroadcastingReductionsUserdefined User defined reductions TODO In the meantime you can have a look at the DenseBase::redux() function. \section TutorialReductionsVisitorsBroadcastingVisitors Visitors Visitors are useful when one wants to obtain the location of a coefficient inside a Matrix or Array. The simplest examples are \link MatrixBase::maxCoeff() maxCoeff(&x,&y) \endlink and \link MatrixBase::minCoeff() minCoeff(&x,&y)\endlink, which can be used to find the location of the greatest or smallest coefficient in a Matrix or Array. The arguments passed to a visitor are pointers to the variables where the row and column position are to be stored. These variables should be of type \link Eigen::Index Index \endlink, as shown below:
Example:Output:
Both functions also return the value of the minimum or maximum coefficient. \section TutorialReductionsVisitorsBroadcastingPartialReductions Partial reductions Partial reductions are reductions that can operate column- or row-wise on a Matrix or Array, applying the reduction operation on each column or row and returning a column or row vector with the corresponding values. Partial reductions are applied with \link DenseBase::colwise() colwise() \endlink or \link DenseBase::rowwise() rowwise() \endlink. A simple example is obtaining the maximum of the elements in each column in a given matrix, storing the result in a row vector:
Example:Output:
The same operation can be performed row-wise:
Example:Output: