[eigen] documentation: the long tutorial

[Benoit Jacob <jacob.benoit.1@xxxxxxxxx>]

Hi,

Now that Jitse has written a great 5-minute tutorial, the next thing
that we need the most is the 1-hour tutorial. It should target people
who already read the 5-minute tutorial, and are ready to spend some
time learning. It should bring them to the point where they can be
autonomous and ready to use our reference tables and the
doxygen-generated class/method documentation. So 1 hour is not too
much actually.

Let me make an attempt at an outline, so we can discuss first the
shape it should take and then distribute the work among ourselves.

I imagine it as a series of doxygen pages, numbered 1 to N, intended
to be read sequentially. It can start with boring stuff right away,
since the 5-minute tutorial is already playing the role of luring
users into believing that Eigen is sexy.

Here's my shot in the dark:

First part: basic usage of Eigen

1. The Matrix class: matrices and vectors
  - First section: matrices. Introduce the 3 first template parameters
of Matrix<Scalar, Rows, Cols...>. Explain what Matrix3f is a typedef
for. Explain then MatrixXf and the special value Dynamic. Give an
example similar to the 2nd example of the 5 min tutorial, where a
fixed-size and a dyn-size version are shown side by side. To be a
little different, this could show Identity() for example. This should
also demonstrate the .rows() and .cols() methods as they are how you
get dynamic sizes.
  - Second section: vectors. Say they're just matrices with 1 row or
col at compile time. Since the definition of vector involves the
notion of size at compile time, you can't introduce them before that
notion has been introduced, that's why I defer them to second section.
Say what Vector3f, VectorXf are typedefs for.

2. Arithmetic with matrices and vectors.
  - Show various examples to comfort the reader in the idea that Eigen
does overload arithmetic operators so that doing arithmetic is very
intuitive.
  - Then focus on products, since that's the area where libraries
differ the most. Say that in Eigen, * means matrix product or
multiplication by a scalar. Then show .dot() and .cross(). Not a
problem since we're doing #include<Eigen/Dense> in all examples.
Finish by saying "if you want coeff-wise product, see next page"

3. The Array class and coefficient-wise operations
 - In the same vein as page 1, introduce the Array class. Explain the
only difference is in the kind of operation that it supports: while
Matrix is for doing linear algebra, Array is for general tables of
numbers. Focus on the example of operator*
 - Introduce .matrix() and .array().
 - Finish by mentioning quickly that Array supports a lot more
advanced operations on arrays, give just one example (perhaps applying
a math function, array.exp()).

4. Block operations
 - introduce various functions such as .block(), .row(),
..bottomLeftCorner(), etc...
 - say they work on both matrices and arrays
 - say they have zero cost (perhaps mention the word 'expression
templates' but only as a mystery word at that point).

5. Dense linear algebra
 - only for matrices, not arrays
 - mention various decompositions, give examples of .solve() especially.
 - mention which decompositions are
    - only for invertible matrices (PartialPivLU, LLT...)
    - support non-invertible matrices, but are not able to detect
invertibility (non rank revealing): LDLT, HouseholderQR...
    - rank-revealing decompositions: FullPivLU, ColPivHouseholderQR...
 - mention which decompositions are only for selfadjoint matrices
 - mention which decompositions are able to compute spectral data
(eigenvalues / singular values)

6. Geometry
 - only for matrices, not arrays
 - only fixed-size, not dynamic
 - Transform, Quaternion...

7. Reductions, visitors, and broadcasting
 - for all kinds of matrices/arrays
 - sum() etc...
 - mention partial reductions with .colwise()...
 - mention broadcasting e.g. m.colwise() += vector;

8. Advanced Array manipulation
 - here goes all what's only for arrays and we didn't mention yet.

9. Sparse matrices and vectors?
10. Sparse solvers?
these depend on Gael's opinion of course...

Where from here? In a final page, provide a list of links to other
documentation resources, especially the "special topics pages" that I
mentioned in my documentation plan. Some most pressing questions that
users will have at that point are
 - vectorization?
 - direct memory access, storage orders?
 - how to write a function taking any Eigen matrix or expression as argument?
 - lazy evaluation?
 etc, etc.

All of these are best handled as "special topics" pages rather than in
the tutorial format.

This is just a suggestion to start the discussion, we need to discuss
the outline and then we can start sharing the work of actually writing
these pages...

Benoit