eigen/doc/C03_TutorialArrayClass.dox

namespace Eigen {

/** \page TutorialArrayClass Tutorial page 3 - The Array Class
    \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 TutorialArrayClassWhatIs
    - \ref TutorialArrayClassTypes
    - \ref TutorialArrayClassAccess
  - \ref TutorialArrayClassCoeffWiseOperations
  - \ref TutorialArrayHowToUse
  - \ref TutorialArrayClassCoeffWiseOperators

\section TutorialArrayClassWhatIs What is the Array class?
The \link ArrayBase Array \endlink class provides general-purpose arrays, as opposed to the Matrix class which
is intended for doing linear algebra. Furthermore, the \link ArrayBase Array \endlink class provides an easy way to
perform coefficient-wise operations, which might not have a precise meaning in linear matrix algebra,
such as adding a constant to every coefficient in the array or multiplying two arrays coefficient-wise.


\subsection TutorialArrayClassTypes Array type and predefined types
The \link ArrayBase Array \endlink class is actually a template that works in a similar way as the \b Matrix one:

\code

//declaring an Array instance
Array<type,numRows,numCols>   a;
\endcode

Eigen provides a bunch of predefined types to make instantiation easier. These types follow the same
conventions as the ones available for the \b Matrix ones but with some slight differences,
as shown in the following table:

FIXME: explain why these differences-

<table class="tutorial_code" align="center">
<tr><td align="center">\b Type</td><td align="center">\b Typedef</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>
<tr><td>
\code Array<float,Dynamic,Dynamic> \endcode</td>
<td>
\code ArrayXXf \endcode</td></tr>
<tr><td>
\code Array<float,3,3> \endcode</td>
<td>
\code Array33f \endcode</td></tr>
</table>


\subsection TutorialArrayClassAccess Accessing values inside an Array
Write and read-access to coefficients inside \link ArrayBase Array \endlink is done in the same way as with \b Matrix. 
Here some examples are presented, just for clarification:

\include Tutorial_ArrayClass_accessing.cpp

Output:
\verbinclude Tutorial_ArrayClass_accessing.out

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








\section TutorialArrayClassCoeffWiseOperations Coefficient-wise operators



\subsection TutorialArrayClassCoeffWiseAdd Coefficient-wise addition
Adding two \link ArrayBase Array \endlink objects has the same result as adding to Matrices, performing coefficient-wise addition. This is valid as long as both arrays have the same dimensions:

\include Tutorial_ArrayClass_addition.cpp

Output:
\verbinclude Tutorial_ArrayClass_addition.out

The addition operator can also be used 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 TutorialArrayClassCoeffWiseMult Coefficient-wise multiplication

As said before, the \link ArrayBase Array \endlink class looks at operators from a coefficient-wise perspective. 
This makes an important difference with respect to \b Matrix algebraic operations, especially 
with the product operator. The following example performs coefficient-wise multiplication between two array instances:

\include Tutorial_ArrayClass_mult.cpp

Output:
\verbinclude Tutorial_ArrayClass_mult.out



\section TutorialArrayHowToUse Using arrays and matrices
It is possible to treat the data inside a \b Matrix object as an \link ArrayBase Array \endlink
and vice-versa. This allows the developer to perform a wide diversity of operators regardless 
of the actual type where the coefficients rely on.

The \b Matrix class provides a \link MatrixBase::array() .array() \endlink method that 
'converts' it into an \link ArrayBase Array \endlink type, so that coefficient-wise operations 
can be applied easily. On the other side, the \link ArrayBase Array \endlink
class provides a \link ArrayBase::matrix() .matrix() \endlink method. FIXME: note on overhead? 
Both \link MatrixBase::array() .array() \endlink and \link ArrayBase::matrix() .matrix() \endlink 
can be used as \b rvalues or \b lvalues in expressions.

<b>IMPORTANT NOTE:</b> 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. Conversely, assigning a Matrix to an 
\link ArrayBase Array \endlink or vice-versa is allowed.

\subsection TutorialArrayInteropMatrix Matrix to array example
The following example shows how to use Array operations with a Matrix object by employing 
the \link MatrixBase::array() .array() \endlink function:

<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 TutorialArrayInteropArray Array to matrix example
The following example shows how to use Matrix operations with an \link ArrayBase Array \endlink 
object by employing the \link ArrayBase::matrix() .matrix() \endlink function:

<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 TutorialArrayInteropCombination Example with combinations of .array() and .matrix()
Here there 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>


\b NOTE: there is no need to call \link ArrayBase::matrix() .matrix() \endlink to assign a 
\link ArrayBase Array \endlink type to a \b Matrix or vice-versa.

\section TutorialArrayClassCoeffWiseOperators Array coefficient-wise operators

FIXME: move to reference table? (I think it is already there)

<table class="noborder">
<tr><td>
<table class="tutorial_code" style="margin-right:10pt">
<tr><td>Coefficient wise \link ArrayBase::operator*() product \arrayworld \endlink</td>
<td>\code array3 = array1 * array2; \endcode
</td></tr>
<tr><td>
Add a scalar to all coefficients</td><td>\code
array3 = array1 + scalar;
array3 += scalar;
array3 -= scalar;
\endcode
</td></tr>
<tr><td>
Coefficient wise \link ArrayBase::operator/() division \endlink \arrayworld</td><td>\code
array3 = array1 / array2; \endcode
</td></tr>
<tr><td>
Coefficient wise \link ArrayBase::inverse() reciprocal \endlink \arrayworld</td><td>\code
array3 = array1.inverse(); \endcode
</td></tr>
<tr><td>
Coefficient wise comparisons \arrayworld \n
(support all operators)</td><td>\code
array3 = array1 < array2;
array3 = array1 <= array2;
array3 = array1 > array2;
etc.
\endcode
</td></tr></table>
</td>
<td><table class="tutorial_code">
<tr><td>
\b Trigo \arrayworld: \n
\link ArrayBase::sin sin \endlink, \link ArrayBase::cos cos \endlink</td><td>\code
array3 = array1.sin();
etc.
\endcode
</td></tr>
<tr><td>
\b Power \arrayworld: \n \link ArrayBase::pow() pow \endlink,
\link ArrayBase::square square \endlink,
\link ArrayBase::cube cube \endlink, \n
\link ArrayBase::sqrt sqrt \endlink,
\link ArrayBase::exp exp \endlink,
\link ArrayBase::log log \endlink </td><td>\code
array3 = array1.square();
array3 = array1.pow(5);
array3 = array1.log();
etc.
\endcode
</td></tr>
<tr><td>
\link ArrayBase::min min \endlink, \link ArrayBase::max max \endlink, \n
absolute value (\link ArrayBase::abs() abs \endlink, \link ArrayBase::abs2() abs2 \endlink \arrayworld)
</td><td>\code
array3 = array1.min(array2);
array3 = array1.max(array2);
array3 = array1.abs();
array3 = array1.abs2();
\endcode</td></tr>
</table>
</td></tr></table>


**/
}