1namespace Eigen { 2 3/** \page TutorialArrayClass Tutorial page 3 - The %Array class and coefficient-wise operations 4 \ingroup Tutorial 5 6\li \b Previous: \ref TutorialMatrixArithmetic 7\li \b Next: \ref TutorialBlockOperations 8 9This tutorial aims to provide an overview and explanations on how to use 10Eigen's Array class. 11 12\b Table \b of \b contents 13 - \ref TutorialArrayClassIntro 14 - \ref TutorialArrayClassTypes 15 - \ref TutorialArrayClassAccess 16 - \ref TutorialArrayClassAddSub 17 - \ref TutorialArrayClassMult 18 - \ref TutorialArrayClassCwiseOther 19 - \ref TutorialArrayClassConvert 20 21\section TutorialArrayClassIntro What is the Array class? 22 23The Array class provides general-purpose arrays, as opposed to the Matrix class which 24is intended for linear algebra. Furthermore, the Array class provides an easy way to 25perform coefficient-wise operations, which might not have a linear algebraic meaning, 26such as adding a constant to every coefficient in the array or multiplying two arrays coefficient-wise. 27 28 29\section TutorialArrayClassTypes Array types 30Array is a class template taking the same template parameters as Matrix. 31As with Matrix, the first three template parameters are mandatory: 32\code 33Array<typename Scalar, int RowsAtCompileTime, int ColsAtCompileTime> 34\endcode 35The last three template parameters are optional. Since this is exactly the same as for Matrix, 36we won't explain it again here and just refer to \ref TutorialMatrixClass. 37 38Eigen also provides typedefs for some common cases, in a way that is similar to the Matrix typedefs 39but with some slight differences, as the word "array" is used for both 1-dimensional and 2-dimensional arrays. 40We adopt the convention that typedefs of the form ArrayNt stand for 1-dimensional arrays, where N and t are 41the size and the scalar type, as in the Matrix typedefs explained on \ref TutorialMatrixClass "this page". For 2-dimensional arrays, we 42use typedefs of the form ArrayNNt. Some examples are shown in the following table: 43 44<table class="manual"> 45 <tr> 46 <th>Type </th> 47 <th>Typedef </th> 48 </tr> 49 <tr> 50 <td> \code Array<float,Dynamic,1> \endcode </td> 51 <td> \code ArrayXf \endcode </td> 52 </tr> 53 <tr> 54 <td> \code Array<float,3,1> \endcode </td> 55 <td> \code Array3f \endcode </td> 56 </tr> 57 <tr> 58 <td> \code Array<double,Dynamic,Dynamic> \endcode </td> 59 <td> \code ArrayXXd \endcode </td> 60 </tr> 61 <tr> 62 <td> \code Array<double,3,3> \endcode </td> 63 <td> \code Array33d \endcode </td> 64 </tr> 65</table> 66 67 68\section TutorialArrayClassAccess Accessing values inside an Array 69 70The parenthesis operator is overloaded to provide write and read access to the coefficients of an array, just as with matrices. 71Furthermore, the \c << operator can be used to initialize arrays (via the comma initializer) or to print them. 72 73<table class="example"> 74<tr><th>Example:</th><th>Output:</th></tr> 75<tr><td> 76\include Tutorial_ArrayClass_accessors.cpp 77</td> 78<td> 79\verbinclude Tutorial_ArrayClass_accessors.out 80</td></tr></table> 81 82For more information about the comma initializer, see \ref TutorialAdvancedInitialization. 83 84 85\section TutorialArrayClassAddSub Addition and subtraction 86 87Adding and subtracting two arrays is the same as for matrices. 88The operation is valid if both arrays have the same size, and the addition or subtraction is done coefficient-wise. 89 90Arrays also support expressions of the form <tt>array + scalar</tt> which add a scalar to each coefficient in the array. 91This provides a functionality that is not directly available for Matrix objects. 92 93<table class="example"> 94<tr><th>Example:</th><th>Output:</th></tr> 95<tr><td> 96\include Tutorial_ArrayClass_addition.cpp 97</td> 98<td> 99\verbinclude Tutorial_ArrayClass_addition.out 100</td></tr></table> 101 102 103\section TutorialArrayClassMult Array multiplication 104 105First of all, of course you can multiply an array by a scalar, this works in the same way as matrices. Where arrays 106are fundamentally different from matrices, is when you multiply two together. Matrices interpret 107multiplication as matrix product and arrays interpret multiplication as coefficient-wise product. Thus, two 108arrays can be multiplied if and only if they have the same dimensions. 109 110<table class="example"> 111<tr><th>Example:</th><th>Output:</th></tr> 112<tr><td> 113\include Tutorial_ArrayClass_mult.cpp 114</td> 115<td> 116\verbinclude Tutorial_ArrayClass_mult.out 117</td></tr></table> 118 119 120\section TutorialArrayClassCwiseOther Other coefficient-wise operations 121 122The Array class defines other coefficient-wise operations besides the addition, subtraction and multiplication 123operators described above. For example, the \link ArrayBase::abs() .abs() \endlink method takes the absolute 124value of each coefficient, while \link ArrayBase::sqrt() .sqrt() \endlink computes the square root of the 125coefficients. If you have two arrays of the same size, you can call \link ArrayBase::min() .min() \endlink to 126construct the array whose coefficients are the minimum of the corresponding coefficients of the two given 127arrays. These operations are illustrated in the following example. 128 129<table class="example"> 130<tr><th>Example:</th><th>Output:</th></tr> 131<tr><td> 132\include Tutorial_ArrayClass_cwise_other.cpp 133</td> 134<td> 135\verbinclude Tutorial_ArrayClass_cwise_other.out 136</td></tr></table> 137 138More coefficient-wise operations can be found in the \ref QuickRefPage. 139 140 141\section TutorialArrayClassConvert Converting between array and matrix expressions 142 143When should you use objects of the Matrix class and when should you use objects of the Array class? You cannot 144apply Matrix operations on arrays, or Array operations on matrices. Thus, if you need to do linear algebraic 145operations such as matrix multiplication, then you should use matrices; if you need to do coefficient-wise 146operations, then you should use arrays. However, sometimes it is not that simple, but you need to use both 147Matrix and Array operations. In that case, you need to convert a matrix to an array or reversely. This gives 148access to all operations regardless of the choice of declaring objects as arrays or as matrices. 149 150\link MatrixBase Matrix expressions \endlink have an \link MatrixBase::array() .array() \endlink method that 151'converts' them into \link ArrayBase array expressions\endlink, so that coefficient-wise operations 152can be applied easily. Conversely, \link ArrayBase array expressions \endlink 153have a \link ArrayBase::matrix() .matrix() \endlink method. As with all Eigen expression abstractions, 154this doesn't have any runtime cost (provided that you let your compiler optimize). 155Both \link MatrixBase::array() .array() \endlink and \link ArrayBase::matrix() .matrix() \endlink 156can be used as rvalues and as lvalues. 157 158Mixing matrices and arrays in an expression is forbidden with Eigen. For instance, you cannot add a matrix and 159array directly; the operands of a \c + operator should either both be matrices or both be arrays. However, 160it is easy to convert from one to the other with \link MatrixBase::array() .array() \endlink and 161\link ArrayBase::matrix() .matrix()\endlink. The exception to this rule is the assignment operator: it is 162allowed to assign a matrix expression to an array variable, or to assign an array expression to a matrix 163variable. 164 165The following example shows how to use array operations on a Matrix object by employing the 166\link MatrixBase::array() .array() \endlink method. For example, the statement 167<tt>result = m.array() * n.array()</tt> takes two matrices \c m and \c n, converts them both to an array, uses 168* to multiply them coefficient-wise and assigns the result to the matrix variable \c result (this is legal 169because Eigen allows assigning array expressions to matrix variables). 170 171As a matter of fact, this usage case is so common that Eigen provides a \link MatrixBase::cwiseProduct() 172.cwiseProduct() \endlink method for matrices to compute the coefficient-wise product. This is also shown in 173the example program. 174 175<table class="example"> 176<tr><th>Example:</th><th>Output:</th></tr> 177<tr><td> 178\include Tutorial_ArrayClass_interop_matrix.cpp 179</td> 180<td> 181\verbinclude Tutorial_ArrayClass_interop_matrix.out 182</td></tr></table> 183 184Similarly, if \c array1 and \c array2 are arrays, then the expression <tt>array1.matrix() * array2.matrix()</tt> 185computes their matrix product. 186 187Here is a more advanced example. The expression <tt>(m.array() + 4).matrix() * m</tt> adds 4 to every 188coefficient in the matrix \c m and then computes the matrix product of the result with \c m. Similarly, the 189expression <tt>(m.array() * n.array()).matrix() * m</tt> computes the coefficient-wise product of the matrices 190\c m and \c n and then the matrix product of the result with \c m. 191 192<table class="example"> 193<tr><th>Example:</th><th>Output:</th></tr> 194<tr><td> 195\include Tutorial_ArrayClass_interop.cpp 196</td> 197<td> 198\verbinclude Tutorial_ArrayClass_interop.out 199</td></tr></table> 200 201\li \b Next: \ref TutorialBlockOperations 202 203*/ 204 205} 206