blob: f6f351091a472deeaf606eeae2d8d48ece8e0eef [file] [log] [blame]
 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:
\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
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
*/ }