Re: [eigen] documentation: the long tutorial

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

2010/6/17 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.

OK, good idea.

> - sections 7 and 8 could probably fit into a single one.

OK

> - I'd put cross references to the related sections of the related
> references pages at the end of each tutorial section.

Sure. Or even inline, at every occasion.

> - I'm not sure where to put triangularView/selfadjointView. Perhaps in
> section 4 with the blocks ? or in dedicated section ?

Ah yes, forgot about them. I'd say dedicated section, since it's
really different (not real expression...)

Also, I forgot about something important. At the beginning of my email
I said that an important goal was to make people more autonomous, able
to make sense of doxygen-generated class documentation. In order to
help people in that direction, I think we should finish with 2 pages:

11. Eigen's class hierarchy

Without having some notions about it, users just can't make good use
of doxygen class documentation.

12. Eigen's various header files

We mention here the headers such as Eigen/Core (so far we talked only
about Eigen/Dense and perhaps Sparse).

Then we mention the existence of unsupported modules, the special
headers such as StlSupport,...

Finally we say for each of the main classes in our class hierarchy,
the corresponding header file. This can help a lot demystifying Eigen
to users and help them look for answers themselves at the right place
in the code.

Benoit

>
> 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
>>
>>
>>
>
>
>