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