2010-06-26 08:16:12 +08:00
namespace Eigen {
Big changes in Eigen documentation:
- Organize the documentation into "chapters".
- Each chapter include many documentation pages, reference pages organized as modules, and a quick reference page.
- The "Chapters" tree is created using the defgroup/ingroup mechanism, even for the documentation pages (i.e., .dox files for which I added an \eigenManualPage macro that we can switch between \page or \defgroup ).
- Add a "General topics" entry for all pages that do not fit well in the previous "chapters".
- The highlevel struture is managed by a new eigendoxy_layout.xml file.
- remove the "index" and quite useless pages (namespace list, class hierarchy, member list, file list, etc.)
- add the javascript search-engine.
- add the "treeview" panel.
- remove \tableofcontents (replace them by a custom \eigenAutoToc macro to be able to easily re-enable if needed).
- add javascript to automatically generate a TOC from the h1/h2 tags of the current page, and put the TOC in the left side panel.
- overload various javascript function generated by doxygen to:
- remove the root of the treeview
- remove links to section/subsection from the treeview
- automatically expand the "Chapters" section
- automatically expand the current section
- adjust the height of the treeview to take into account the TOC
- always use the default .css file, eigendoxy.css now only includes our modifications
- use Doxyfile to specify our logo
- remove cross references to unsupported modules (temporarily)
2013-01-05 23:37:11 +08:00
/** \eigenManualPage TutorialArrayClass The Array class and coefficient-wise operations
2010-06-26 08:16:12 +08:00
2013-01-07 06:48:59 +08:00
This page aims to provide an overview and explanations on how to use
2010-07-13 05:45:57 +08:00
Eigen's Array class.
2010-06-26 08:16:12 +08:00
Big changes in Eigen documentation:
- Organize the documentation into "chapters".
- Each chapter include many documentation pages, reference pages organized as modules, and a quick reference page.
- The "Chapters" tree is created using the defgroup/ingroup mechanism, even for the documentation pages (i.e., .dox files for which I added an \eigenManualPage macro that we can switch between \page or \defgroup ).
- Add a "General topics" entry for all pages that do not fit well in the previous "chapters".
- The highlevel struture is managed by a new eigendoxy_layout.xml file.
- remove the "index" and quite useless pages (namespace list, class hierarchy, member list, file list, etc.)
- add the javascript search-engine.
- add the "treeview" panel.
- remove \tableofcontents (replace them by a custom \eigenAutoToc macro to be able to easily re-enable if needed).
- add javascript to automatically generate a TOC from the h1/h2 tags of the current page, and put the TOC in the left side panel.
- overload various javascript function generated by doxygen to:
- remove the root of the treeview
- remove links to section/subsection from the treeview
- automatically expand the "Chapters" section
- automatically expand the current section
- adjust the height of the treeview to take into account the TOC
- always use the default .css file, eigendoxy.css now only includes our modifications
- use Doxyfile to specify our logo
- remove cross references to unsupported modules (temporarily)
2013-01-05 23:37:11 +08:00
\eigenAutoToc
2012-12-29 01:58:07 +08:00
2010-07-02 08:29:13 +08:00
\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,
2010-06-29 01:42:09 +08:00
such as adding a constant to every coefficient in the array or multiplying two arrays coefficient-wise.
2010-06-26 08:16:12 +08:00
2010-07-02 08:29:13 +08:00
\section TutorialArrayClassTypes Array types
Array is a class template taking the same template parameters as Matrix.
2010-07-13 05:45:57 +08:00
As with Matrix, the first three template parameters are mandatory:
2010-06-26 08:16:12 +08:00
\code
2010-07-02 08:29:13 +08:00
Array<typename Scalar, int RowsAtCompileTime, int ColsAtCompileTime>
2010-06-26 08:16:12 +08:00
\endcode
2010-07-13 05:45:57 +08:00
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.
2010-06-26 08:16:12 +08:00
2010-07-02 08:29:13 +08:00
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.
2011-03-21 18:45:57 +08:00
We adopt the convention that typedefs of the form ArrayNt stand for 1-dimensional arrays, where N and t are
2010-07-13 05:45:57 +08:00
the size and the scalar type, as in the Matrix typedefs explained on \ref TutorialMatrixClass "this page". For 2-dimensional arrays, we
2010-07-02 08:29:13 +08:00
use typedefs of the form ArrayNNt. Some examples are shown in the following table:
2010-06-26 08:16:12 +08:00
2010-10-19 17:40:49 +08:00
<table class="manual">
2010-07-02 08:29:13 +08:00
<tr>
2010-10-19 17:40:49 +08:00
<th>Type </th>
<th>Typedef </th>
2010-07-02 08:29:13 +08:00
</tr>
<tr>
<td> \code Array<float,Dynamic,1> \endcode </td>
<td> \code ArrayXf \endcode </td>
</tr>
<tr>
<td> \code Array<float,3,1> \endcode </td>
<td> \code Array3f \endcode </td>
</tr>
<tr>
<td> \code Array<double,Dynamic,Dynamic> \endcode </td>
<td> \code ArrayXXd \endcode </td>
</tr>
<tr>
<td> \code Array<double,3,3> \endcode </td>
<td> \code Array33d \endcode </td>
</tr>
</table>
2010-06-26 08:16:12 +08:00
2010-06-29 01:42:09 +08:00
2010-07-02 08:29:13 +08:00
\section TutorialArrayClassAccess Accessing values inside an Array
2010-06-29 01:42:09 +08:00
2010-07-13 05:45:57 +08:00
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.
2010-06-29 01:42:09 +08:00
2010-10-19 17:40:49 +08:00
<table class="example">
<tr><th>Example:</th><th>Output:</th></tr>
<tr><td>
\include Tutorial_ArrayClass_accessors.cpp
2010-07-13 05:45:57 +08:00
</td>
<td>
2010-10-19 17:40:49 +08:00
\verbinclude Tutorial_ArrayClass_accessors.out
2010-07-13 05:45:57 +08:00
</td></tr></table>
2010-06-29 01:42:09 +08:00
2010-07-13 05:45:57 +08:00
For more information about the comma initializer, see \ref TutorialAdvancedInitialization.
2010-06-29 01:42:09 +08:00
2010-07-13 05:45:57 +08:00
\section TutorialArrayClassAddSub Addition and subtraction
2010-06-29 01:42:09 +08:00
2010-07-13 05:45:57 +08:00
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.
2010-06-29 01:42:09 +08:00
2010-07-13 05:45:57 +08:00
Arrays also support expressions of the form <tt>array + scalar</tt> which add a scalar to each coefficient in the array.
This provides a functionality that is not directly available for Matrix objects.
2010-06-29 01:42:09 +08:00
2010-10-19 17:40:49 +08:00
<table class="example">
<tr><th>Example:</th><th>Output:</th></tr>
<tr><td>
\include Tutorial_ArrayClass_addition.cpp
2010-07-13 05:45:57 +08:00
</td>
<td>
2010-10-19 17:40:49 +08:00
\verbinclude Tutorial_ArrayClass_addition.out
2010-07-13 05:45:57 +08:00
</td></tr></table>
2010-06-29 01:42:09 +08:00
2010-07-13 05:45:57 +08:00
\section TutorialArrayClassMult Array multiplication
2010-06-29 01:42:09 +08:00
2010-07-02 08:29:13 +08:00
First of all, of course you can multiply an array by a scalar, this works in the same way as matrices. Where arrays
2010-07-13 05:45:57 +08:00
are fundamentally different from matrices, is when you multiply two together. Matrices interpret
2011-03-21 18:45:57 +08:00
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.
2010-06-29 01:42:09 +08:00
2010-10-19 17:40:49 +08:00
<table class="example">
<tr><th>Example:</th><th>Output:</th></tr>
<tr><td>
\include Tutorial_ArrayClass_mult.cpp
2010-07-13 05:45:57 +08:00
</td>
<td>
2010-10-19 17:40:49 +08:00
\verbinclude Tutorial_ArrayClass_mult.out
2010-07-13 05:45:57 +08:00
</td></tr></table>
2010-06-29 01:42:09 +08:00
2010-07-13 05:45:57 +08:00
\section TutorialArrayClassCwiseOther Other coefficient-wise operations
2011-03-21 18:45:57 +08:00
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
2010-07-13 05:45:57 +08:00
value of each coefficient, while \link ArrayBase::sqrt() .sqrt() \endlink computes the square root of the
2012-12-24 20:33:22 +08:00
coefficients. If you have two arrays of the same size, you can call \link ArrayBase::min(const Eigen::ArrayBase<OtherDerived>&) const .min(.) \endlink to
2010-07-13 05:45:57 +08:00
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.
2010-10-19 17:40:49 +08:00
<table class="example">
<tr><th>Example:</th><th>Output:</th></tr>
<tr><td>
\include Tutorial_ArrayClass_cwise_other.cpp
2010-07-13 05:45:57 +08:00
</td>
<td>
2010-10-19 17:40:49 +08:00
\verbinclude Tutorial_ArrayClass_cwise_other.out
2010-07-13 05:45:57 +08:00
</td></tr></table>
More coefficient-wise operations can be found in the \ref QuickRefPage.
2010-06-26 08:16:12 +08:00
2010-07-02 08:29:13 +08:00
\section TutorialArrayClassConvert Converting between array and matrix expressions
2010-07-13 05:45:57 +08:00
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.
2010-07-02 08:29:13 +08:00
2010-07-13 05:45:57 +08:00
\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
2010-07-02 08:29:13 +08:00
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).
2010-06-29 01:42:09 +08:00
Both \link MatrixBase::array() .array() \endlink and \link ArrayBase::matrix() .matrix() \endlink
2010-07-02 08:52:40 +08:00
can be used as rvalues and as lvalues.
2010-06-29 01:42:09 +08:00
2011-06-20 03:39:19 +08:00
Mixing matrices and arrays in an expression is forbidden with Eigen. For instance, you cannot add a matrix and
2010-07-13 05:45:57 +08:00
array directly; the operands of a \c + operator should either both be matrices or both be arrays. However,
2010-06-29 01:42:09 +08:00
it is easy to convert from one to the other with \link MatrixBase::array() .array() \endlink and
2010-07-13 05:45:57 +08:00
\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.
2010-06-29 01:42:09 +08:00
2010-07-13 05:45:57 +08:00
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
<tt>result = m.array() * n.array()</tt> 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).
2010-07-02 08:29:13 +08:00
2012-12-24 20:33:22 +08:00
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
2010-07-13 05:45:57 +08:00
the example program.
2010-06-29 01:42:09 +08:00
2010-10-19 17:40:49 +08:00
<table class="example">
<tr><th>Example:</th><th>Output:</th></tr>
<tr><td>
2010-06-29 01:42:09 +08:00
\include Tutorial_ArrayClass_interop_matrix.cpp
</td>
<td>
\verbinclude Tutorial_ArrayClass_interop_matrix.out
</td></tr></table>
2010-06-26 08:16:12 +08:00
2010-07-13 05:45:57 +08:00
Similarly, if \c array1 and \c array2 are arrays, then the expression <tt>array1.matrix() * array2.matrix()</tt>
computes their matrix product.
2010-06-26 08:16:12 +08:00
2010-07-13 05:45:57 +08:00
Here is a more advanced example. The expression <tt>(m.array() + 4).matrix() * m</tt> 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 <tt>(m.array() * n.array()).matrix() * m</tt> computes the coefficient-wise product of the matrices
\c m and \c n and then the matrix product of the result with \c m.
2010-06-29 01:42:09 +08:00
2010-10-19 17:40:49 +08:00
<table class="example">
<tr><th>Example:</th><th>Output:</th></tr>
<tr><td>
2010-06-29 01:42:09 +08:00
\include Tutorial_ArrayClass_interop.cpp
</td>
<td>
\verbinclude Tutorial_ArrayClass_interop.out
</td></tr></table>
2010-07-02 08:29:13 +08:00
*/
2010-06-26 08:16:12 +08:00
}
