From 3404d5fb14099c89518f8f9c2a003ed89f9181e5 Mon Sep 17 00:00:00 2001 From: Benoit Jacob Date: Mon, 18 Oct 2010 09:09:30 -0400 Subject: improvements in pages 5 and 7 of the tutorial. --- doc/C05_TutorialAdvancedInitialization.dox | 23 +++++++++------- doc/C07_TutorialReductionsVisitorsBroadcasting.dox | 32 ++++++++++++++-------- ...uctionsVisitorsBroadcasting_reductions_norm.cpp | 22 +++++++-------- 3 files changed, 44 insertions(+), 33 deletions(-) (limited to 'doc') diff --git a/doc/C05_TutorialAdvancedInitialization.dox b/doc/C05_TutorialAdvancedInitialization.dox index db84f94a7..e3eca3eb2 100644 --- a/doc/C05_TutorialAdvancedInitialization.dox +++ b/doc/C05_TutorialAdvancedInitialization.dox @@ -67,8 +67,8 @@ Example: \include Tutorial_AdvancedInitialization_Zero.cpp Output: \verbinclude Tutorial_AdvancedInitialization_Zero.out -Similarly, the static method \link DenseBase::Constant() Constant\endlink(value) sets all coefficients to \c -value. If the size of the object needs to be specified, the additional arguments go before the \c value +Similarly, the static method \link DenseBase::Constant() Constant\endlink(value) sets all coefficients to \c value. +If the size of the object needs to be specified, the additional arguments go before the \c value argument, as in MatrixXd::Constant(rows, cols, value). The method \link DenseBase::Random() Random() \endlink fills the matrix or array with random coefficients. The identity matrix can be obtained by calling \link MatrixBase::Identity() Identity()\endlink; this method is only available for Matrix, not for Array, @@ -102,13 +102,15 @@ Output: \verbinclude Tutorial_AdvancedInitialization_ThreeWays.out A summary of all pre-defined matrix, vector and array objects can be found in the \ref QuickRefPage. -\section TutorialAdvancedInitializationTemporaryObjects Temporary matrices and arrays +\section TutorialAdvancedInitializationTemporaryObjects Usage as temporary objects -As shown above, static methods as Zero() and Constant() can be used to initialize to variables at the time of +As shown above, static methods as Zero() and Constant() can be used to initialize variables at the time of declaration or at the right-hand side of an assignment operator. You can think of these methods as returning a -matrix or array (in fact, they return a so-called \ref TopicEigenExpressionTemplates "expression object" which -evaluates to a matrix when needed). This matrix can also be used as a temporary object. The second example in -the \ref GettingStarted guide, which we reproduced here, already illustrates this. +matrix or array; in fact, they return so-called \ref TopicEigenExpressionTemplates "expression objects" which +evaluate to a matrix or array when needed, so that this syntax does not incur any overhead. + +These expressions can also be used as a temporary object. The second example in +the \ref GettingStarted guide, which we reproduce here, already illustrates this.
Example: \include QuickStart_example2_dynamic.cpp @@ -117,9 +119,10 @@ Example: \include QuickStart_example2_dynamic.cpp Output: \verbinclude QuickStart_example2_dynamic.out
-The expression m + MatrixXf::Constant(3,3,1.2) constructs the 3-by-3 matrix with all its coefficients -equal to 1.2 and adds it to \c m ; in other words, it adds 1.2 to all the coefficients of \c m . The -comma-initializer can also be used to construct temporary objects. The following example constructs a random +The expression m + MatrixXf::Constant(3,3,1.2) constructs the 3-by-3 matrix expression with all its coefficients +equal to 1.2 plus the corresponding coefficient of \a m. + +The comma-initializer, too, can also be used to construct temporary objects. The following example constructs a random matrix of size 2-by-3, and then multiplies this matrix on the left with \f$ \bigl[ \begin{smallmatrix} 0 & 1 \\ 1 & 0 \end{smallmatrix} \bigr] \f$. diff --git a/doc/C07_TutorialReductionsVisitorsBroadcasting.dox b/doc/C07_TutorialReductionsVisitorsBroadcasting.dox index 80b95a63b..130514189 100644 --- a/doc/C07_TutorialReductionsVisitorsBroadcasting.dox +++ b/doc/C07_TutorialReductionsVisitorsBroadcasting.dox @@ -22,9 +22,9 @@ This tutorial explains Eigen's reductions, visitors and broadcasting and how the \section TutorialReductionsVisitorsBroadcastingReductions Reductions -In Eigen, a reduction is a function that is applied to a certain matrix or array, returning a single -value of type scalar. One of the most used reductions is \link DenseBase::sum() .sum() \endlink, -which returns the addition of all the coefficients inside a given matrix or array. +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: \include tut_arithmetic_redux_basic.cpp @@ -33,12 +33,20 @@ Example: \include tut_arithmetic_redux_basic.cpp Output: \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 also be computed as efficiently using a.diagonal().sum(), as we will see later on. +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 reductions -Eigen also provides reductions to obtain the Euclidean norm or squared norm of a vector with \link MatrixBase::norm() norm() \endlink and \link MatrixBase::squaredNorm() squaredNorm() \endlink respectively. -These operations can also operate on matrices; in that case, they use the Frobenius norm. The following example shows these methods. +\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 \f$\ell^p\f$ norms, use the \link MatrixBase::lpNorm() lpNnorm

() \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: \include Tutorial_ReductionsVisitorsBroadcasting_reductions_norm.cpp @@ -48,12 +56,12 @@ Output: \verbinclude Tutorial_ReductionsVisitorsBroadcasting_reductions_norm.out
-\subsection TutorialReductionsVisitorsBroadcastingReductionsBool Boolean-like reductions +\subsection TutorialReductionsVisitorsBroadcastingReductionsBool Boolean reductions -Another interesting type of reductions are the ones that deal with \b true and \b false values: - - \link DenseBase::all() all() \endlink returns \b true if all of the coefficients in a given Matrix or Array are \b true . - - \link DenseBase::any() any() \endlink returns \b true if at least one of the coefficients in a given Matrix or Array is \b true . - - \link DenseBase::count() count() \endlink returns the number of \b true coefficients in a given Matrix or Array. +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: diff --git a/doc/examples/Tutorial_ReductionsVisitorsBroadcasting_reductions_norm.cpp b/doc/examples/Tutorial_ReductionsVisitorsBroadcasting_reductions_norm.cpp index f3364d7fc..740439fb3 100644 --- a/doc/examples/Tutorial_ReductionsVisitorsBroadcasting_reductions_norm.cpp +++ b/doc/examples/Tutorial_ReductionsVisitorsBroadcasting_reductions_norm.cpp @@ -9,20 +9,20 @@ int main() VectorXf v(2); MatrixXf m(2,2), n(2,2); - v << 5, - 10; + v << -1, + 2; - m << 2,2, - 3,4; + m << 1,-2, + -3,4; - n << 1, 2, - 32,12; - + cout << "v.squaredNorm() = " << v.squaredNorm() << endl; cout << "v.norm() = " << v.norm() << endl; - cout << "m.norm() = " << m.norm() << endl; - cout << "n.norm() = " << n.norm() << endl; + cout << "v.lpNorm<1>() = " << v.lpNorm<1>() << endl; + cout << "v.lpNorm() = " << v.lpNorm() << endl; + cout << endl; - cout << "v.squaredNorm() = " << v.squaredNorm() << endl; cout << "m.squaredNorm() = " << m.squaredNorm() << endl; - cout << "n.squaredNorm() = " << n.squaredNorm() << endl; + cout << "m.norm() = " << m.norm() << endl; + cout << "m.lpNorm<1>() = " << m.lpNorm<1>() << endl; + cout << "m.lpNorm() = " << m.lpNorm() << endl; } -- cgit v1.2.3