eigen/doc/C03_TutorialArrayClass.dox

namespace Eigen {

/** \page TutorialArrayClass Tutorial page 3 - The %Array class and coefficient-wise operations
    \ingroup Tutorial

\li \b Previous: \ref TutorialMatrixArithmetic
\li \b Next: \ref TutorialBlockOperations

This tutorial aims to provide an overview and explanations on how to use
Eigen's \link ArrayBase Array \endlink class

\b Table \b of \b contents
  - \ref TutorialArrayClassIntro
  - \ref TutorialArrayClassTypes
  - \ref TutorialArrayClassAccess
  - \ref TutorialArrayClassAddSub
  - \ref TutorialArrayClassMult
  - \ref TutorialArrayClassConvert

\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 3 template parameters are mandatory:
\code
Array<typename Scalar, int RowsAtCompileTime, int ColsAtCompileTime>
\endcode
And the last 3 template parameters are optional. Since this is exactly the same as for Matrix,
we won't reexplain it and just refer to \ref TutorialMatrixClass "this page".

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 that convention that typedefs of the form ArrayNt stand for 1-dimensional arrays, where N and t are
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:

<table class="tutorial_code" align="center">

  <tr>
    <td align="center">\b Type </td>
    <td align="center">\b Typedef </td>
  </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>


\section TutorialArrayClassAccess Accessing values inside an Array
Write and read access to coefficients of an array expression is done in the same way as with matrix expressions.
For example:

\include Tutorial_ArrayClass_accessors.cpp
Output:
\verbinclude Tutorial_ArrayClass_accessors.out

For more information about the comma initializer, refer to \ref TutorialAdvancedInitialization "this page".


\section TutorialArrayClassAddSub Addition and substraction


Adding and substracting two arrays has the same result as for Matrices.
This is valid as long as both arrays have the same sizes:

\include Tutorial_ArrayClass_addition.cpp
Output:
\verbinclude Tutorial_ArrayClass_addition.out

It is also allowed to add a scalar to each coefficient in an Array,
providing a functionality that was not available for Matrix objects:

\include Tutorial_ArrayClass_addition_scalar.cpp
Output:
\verbinclude Tutorial_ArrayClass_addition_scalar.out


\subsection 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 arrays together. While Matrices interprete
multiplication as matrix product, arrays interprete multiplication as coefficient-wise product. For example:

\include Tutorial_ArrayClass_mult.cpp
Output:
\verbinclude Tutorial_ArrayClass_mult.out



\section TutorialArrayClassConvert Converting between array and matrix expressions

It is possible to wrap a matrix expression as an array expression and conversely. This gives access to all operations
regardless of the choice of declaring objects as arrays or as matrices.

\link MatrixBase Matrix expressions \endlink have a \link MatrixBase::array() .array() \endlink method that
'converts' them into \link ArrayBase array expressions \endlink, so that coefficient-wise operations
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).

Both \link MatrixBase::array() .array() \endlink and \link ArrayBase::matrix() .matrix() \endlink 
can be used as rvalues and as lvalues.

Mixing matrices and arrays in an expression is forbidden with Eigen. However,
it is easy to convert from one to the other with \link MatrixBase::array() .array() \endlink and 
\link ArrayBase::matrix() .matrix() \endlink.

On the other hand, assigning a matrix expression to an array expression is allowed.

\subsection TutorialArrayClassInteropMatrix Matrix to array example
The following example shows how to use array operations on a Matrix object by employing
the \link MatrixBase::array() .array() \endlink method:

<table class="tutorial_code"><tr><td>
\include Tutorial_ArrayClass_interop_matrix.cpp
</td>
<td>
Output:
\verbinclude Tutorial_ArrayClass_interop_matrix.out
</td></tr></table>


\subsection TutorialArrayClassInteropArray Array to matrix example
The following example shows how to use matrix operations with an Array
object by employing the \link ArrayBase::matrix() .matrix() \endlink method:

<table class="tutorial_code"><tr><td>
\include Tutorial_ArrayClass_interop_array.cpp
</td>
<td>
Output:
\verbinclude Tutorial_ArrayClass_interop_array.out
</td></tr></table>

\subsection TutorialArrayClassInteropCombination Example with combinations of .array() and .matrix()
Here is a more advanced example:

<table class="tutorial_code"><tr><td>
\include Tutorial_ArrayClass_interop.cpp
</td>
<td>
Output:
\verbinclude Tutorial_ArrayClass_interop.out
</td></tr></table>

\li \b Next: \ref TutorialBlockOperations

*/

}