From 44861dcbfeee041223c4aac1ee075e92fa4daa01 Mon Sep 17 00:00:00 2001 From: Stanislaw Halik Date: Sun, 18 Sep 2016 12:42:15 +0200 Subject: update --- eigen/doc/TutorialArrayClass.dox | 192 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 eigen/doc/TutorialArrayClass.dox (limited to 'eigen/doc/TutorialArrayClass.dox') diff --git a/eigen/doc/TutorialArrayClass.dox b/eigen/doc/TutorialArrayClass.dox new file mode 100644 index 0000000..6432684 --- /dev/null +++ b/eigen/doc/TutorialArrayClass.dox @@ -0,0 +1,192 @@ +namespace Eigen { + +/** \eigenManualPage TutorialArrayClass The Array class and coefficient-wise operations + +This page aims to provide an overview and explanations on how to use +Eigen's Array class. + +\eigenAutoToc + +\section TutorialArrayClassIntro What is the Array class? + +The Array class provides general-purpose arrays, as opposed to the Matrix class which +is intended for linear algebra. Furthermore, the Array class provides an easy way to +perform coefficient-wise operations, which might not have a linear algebraic meaning, +such as adding a constant to every coefficient in the array or multiplying two arrays coefficient-wise. + + +\section TutorialArrayClassTypes Array types +Array is a class template taking the same template parameters as Matrix. +As with Matrix, the first three template parameters are mandatory: +\code +Array +\endcode +The last three template parameters are optional. Since this is exactly the same as for Matrix, +we won't explain it again here and just refer to \ref TutorialMatrixClass. + +Eigen also provides typedefs for some common cases, in a way that is similar to the Matrix typedefs +but with some slight differences, as the word "array" is used for both 1-dimensional and 2-dimensional arrays. +We adopt the convention that typedefs of the form ArrayNt stand for 1-dimensional arrays, where N and t are +the size and the scalar type, as in the Matrix typedefs explained on \ref TutorialMatrixClass "this page". For 2-dimensional arrays, we +use typedefs of the form ArrayNNt. Some examples are shown in the following table: + + + + + + + + + + + + + + + + + + + + + + +
Type Typedef
\code Array \endcode \code ArrayXf \endcode
\code Array \endcode \code Array3f \endcode
\code Array \endcode \code ArrayXXd \endcode
\code Array \endcode \code Array33d \endcode
+ + +\section TutorialArrayClassAccess Accessing values inside an Array + +The parenthesis operator is overloaded to provide write and read access to the coefficients of an array, just as with matrices. +Furthermore, the \c << operator can be used to initialize arrays (via the comma initializer) or to print them. + + + + +
Example:Output:
+\include Tutorial_ArrayClass_accessors.cpp + +\verbinclude Tutorial_ArrayClass_accessors.out +
+ +For more information about the comma initializer, see \ref TutorialAdvancedInitialization. + + +\section TutorialArrayClassAddSub Addition and subtraction + +Adding and subtracting two arrays is the same as for matrices. +The operation is valid if both arrays have the same size, and the addition or subtraction is done coefficient-wise. + +Arrays also support expressions of the form array + scalar which add a scalar to each coefficient in the array. +This provides a functionality that is not directly available for Matrix objects. + + + + +
Example:Output:
+\include Tutorial_ArrayClass_addition.cpp + +\verbinclude Tutorial_ArrayClass_addition.out +
+ + +\section TutorialArrayClassMult Array multiplication + +First of all, of course you can multiply an array by a scalar, this works in the same way as matrices. Where arrays +are fundamentally different from matrices, is when you multiply two together. Matrices interpret +multiplication as matrix product and arrays interpret multiplication as coefficient-wise product. Thus, two +arrays can be multiplied if and only if they have the same dimensions. + + + + +
Example:Output:
+\include Tutorial_ArrayClass_mult.cpp + +\verbinclude Tutorial_ArrayClass_mult.out +
+ + +\section TutorialArrayClassCwiseOther Other coefficient-wise operations + +The Array class defines other coefficient-wise operations besides the addition, subtraction and multiplication +operators described above. For example, the \link ArrayBase::abs() .abs() \endlink method takes the absolute +value of each coefficient, while \link ArrayBase::sqrt() .sqrt() \endlink computes the square root of the +coefficients. If you have two arrays of the same size, you can call \link ArrayBase::min(const Eigen::ArrayBase&) const .min(.) \endlink to +construct the array whose coefficients are the minimum of the corresponding coefficients of the two given +arrays. These operations are illustrated in the following example. + + + + +
Example:Output:
+\include Tutorial_ArrayClass_cwise_other.cpp + +\verbinclude Tutorial_ArrayClass_cwise_other.out +
+ +More coefficient-wise operations can be found in the \ref QuickRefPage. + + +\section TutorialArrayClassConvert Converting between array and matrix expressions + +When should you use objects of the Matrix class and when should you use objects of the Array class? You cannot +apply Matrix operations on arrays, or Array operations on matrices. Thus, if you need to do linear algebraic +operations such as matrix multiplication, then you should use matrices; if you need to do coefficient-wise +operations, then you should use arrays. However, sometimes it is not that simple, but you need to use both +Matrix and Array operations. In that case, you need to convert a matrix to an array or reversely. This gives +access to all operations regardless of the choice of declaring objects as arrays or as matrices. + +\link MatrixBase Matrix expressions \endlink have an \link MatrixBase::array() .array() \endlink method that +'converts' them into \link ArrayBase array expressions\endlink, so that coefficient-wise operations +can be applied easily. Conversely, \link ArrayBase array expressions \endlink +have a \link ArrayBase::matrix() .matrix() \endlink method. As with all Eigen expression abstractions, +this doesn't have any runtime cost (provided that you let your compiler optimize). +Both \link MatrixBase::array() .array() \endlink and \link ArrayBase::matrix() .matrix() \endlink +can be used as rvalues and as lvalues. + +Mixing matrices and arrays in an expression is forbidden with Eigen. For instance, you cannot add a matrix and +array directly; the operands of a \c + operator should either both be matrices or both be arrays. However, +it is easy to convert from one to the other with \link MatrixBase::array() .array() \endlink and +\link ArrayBase::matrix() .matrix()\endlink. The exception to this rule is the assignment operator: it is +allowed to assign a matrix expression to an array variable, or to assign an array expression to a matrix +variable. + +The following example shows how to use array operations on a Matrix object by employing the +\link MatrixBase::array() .array() \endlink method. For example, the statement +result = m.array() * n.array() takes two matrices \c m and \c n, converts them both to an array, uses +* to multiply them coefficient-wise and assigns the result to the matrix variable \c result (this is legal +because Eigen allows assigning array expressions to matrix variables). + +As a matter of fact, this usage case is so common that Eigen provides a \link MatrixBase::cwiseProduct() const +.cwiseProduct(.) \endlink method for matrices to compute the coefficient-wise product. This is also shown in +the example program. + + + + +
Example:Output:
+\include Tutorial_ArrayClass_interop_matrix.cpp + +\verbinclude Tutorial_ArrayClass_interop_matrix.out +
+ +Similarly, if \c array1 and \c array2 are arrays, then the expression array1.matrix() * array2.matrix() +computes their matrix product. + +Here is a more advanced example. The expression (m.array() + 4).matrix() * m adds 4 to every +coefficient in the matrix \c m and then computes the matrix product of the result with \c m. Similarly, the +expression (m.array() * n.array()).matrix() * m computes the coefficient-wise product of the matrices +\c m and \c n and then the matrix product of the result with \c m. + + + + +
Example:Output:
+\include Tutorial_ArrayClass_interop.cpp + +\verbinclude Tutorial_ArrayClass_interop.out +
+ +*/ + +} -- cgit v1.2.3