Re: [eigen] documentation: the long tutorial

[Gael Guennebaud <gael.guennebaud@xxxxxxxxx>]

wow, this is a pretty good start. I have only a few minor remarks:

- I'd put the basic reduction operations into section 2, and of course
keep colwise/rowwise for the end of the tutorial.
- sections 7 and 8 could probably fit into a single one.
- I'd put cross references to the related sections of the related
references pages at the end of each tutorial section.
- I'm not sure where to put triangularView/selfadjointView. Perhaps in
section 4 with the blocks ? or in dedicated section ?

gael

On Thu, Jun 17, 2010 at 3:43 PM, Benoit Jacob <jacob.benoit.1@xxxxxxxxx> wrote:
> 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
>
>
>