1namespace Eigen {
2
3/** \eigenManualPage TutorialArrayClass The Array class and coefficient-wise operations
4
5This page aims to provide an overview and explanations on how to use
6Eigen's Array class.
7
8\eigenAutoToc
9  
10\section TutorialArrayClassIntro What is the Array class?
11
12The Array class provides general-purpose arrays, as opposed to the Matrix class which
13is intended for linear algebra. Furthermore, the Array class provides an easy way to
14perform coefficient-wise operations, which might not have a linear algebraic meaning,
15such as adding a constant to every coefficient in the array or multiplying two arrays coefficient-wise.
16
17
18\section TutorialArrayClassTypes Array types
19Array is a class template taking the same template parameters as Matrix.
20As with Matrix, the first three template parameters are mandatory:
21\code
22Array<typename Scalar, int RowsAtCompileTime, int ColsAtCompileTime>
23\endcode
24The last three template parameters are optional. Since this is exactly the same as for Matrix,
25we won't explain it again here and just refer to \ref TutorialMatrixClass.
26
27Eigen also provides typedefs for some common cases, in a way that is similar to the Matrix typedefs
28but with some slight differences, as the word "array" is used for both 1-dimensional and 2-dimensional arrays.
29We adopt the convention that typedefs of the form ArrayNt stand for 1-dimensional arrays, where N and t are
30the size and the scalar type, as in the Matrix typedefs explained on \ref TutorialMatrixClass "this page". For 2-dimensional arrays, we
31use 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
59The parenthesis operator is overloaded to provide write and read access to the coefficients of an array, just as with matrices.
60Furthermore, 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
71For more information about the comma initializer, see \ref TutorialAdvancedInitialization.
72
73
74\section TutorialArrayClassAddSub Addition and subtraction
75
76Adding and subtracting two arrays is the same as for matrices.
77The operation is valid if both arrays have the same size, and the addition or subtraction is done coefficient-wise.
78
79Arrays also support expressions of the form <tt>array + scalar</tt> which add a scalar to each coefficient in the array.
80This 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
94First of all, of course you can multiply an array by a scalar, this works in the same way as matrices. Where arrays
95are fundamentally different from matrices, is when you multiply two together. Matrices interpret
96multiplication as matrix product and arrays interpret multiplication as coefficient-wise product. Thus, two 
97arrays 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
111The Array class defines other coefficient-wise operations besides the addition, subtraction and multiplication
112operators described above. For example, the \link ArrayBase::abs() .abs() \endlink method takes the absolute
113value of each coefficient, while \link ArrayBase::sqrt() .sqrt() \endlink computes the square root of the
114coefficients. If you have two arrays of the same size, you can call \link ArrayBase::min(const Eigen::ArrayBase<OtherDerived>&) const .min(.) \endlink to
115construct the array whose coefficients are the minimum of the corresponding coefficients of the two given
116arrays. 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
127More coefficient-wise operations can be found in the \ref QuickRefPage.
128
129
130\section TutorialArrayClassConvert Converting between array and matrix expressions
131
132When should you use objects of the Matrix class and when should you use objects of the Array class? You cannot
133apply Matrix operations on arrays, or Array operations on matrices. Thus, if you need to do linear algebraic
134operations such as matrix multiplication, then you should use matrices; if you need to do coefficient-wise
135operations, then you should use arrays. However, sometimes it is not that simple, but you need to use both
136Matrix and Array operations. In that case, you need to convert a matrix to an array or reversely. This gives
137access 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
141can be applied easily. Conversely, \link ArrayBase array expressions \endlink
142have a \link ArrayBase::matrix() .matrix() \endlink method. As with all Eigen expression abstractions,
143this doesn't have any runtime cost (provided that you let your compiler optimize).
144Both \link MatrixBase::array() .array() \endlink and \link ArrayBase::matrix() .matrix() \endlink 
145can be used as rvalues and as lvalues.
146
147Mixing matrices and arrays in an expression is forbidden with Eigen. For instance, you cannot add a matrix and
148array directly; the operands of a \c + operator should either both be matrices or both be arrays. However,
149it 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
151allowed to assign a matrix expression to an array variable, or to assign an array expression to a matrix
152variable.
153
154The 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
158because Eigen allows assigning array expressions to matrix variables). 
159
160As 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
162the 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
173Similarly, if \c array1 and \c array2 are arrays, then the expression <tt>array1.matrix() * array2.matrix()</tt>
174computes their matrix product.
175
176Here is a more advanced example. The expression <tt>(m.array() + 4).matrix() * m</tt> adds 4 to every
177coefficient in the matrix \c m and then computes the matrix product of the result with \c m. Similarly, the
178expression <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}
193