|Re: [eigen] documentation: the long tutorial|
[ Thread Index |
| More lists.tuxfamily.org/eigen Archives
- To: eigen@xxxxxxxxxxxxxxxxxxx
- Subject: Re: [eigen] documentation: the long tutorial
- From: Gael Guennebaud <gael.guennebaud@xxxxxxxxx>
- Date: Thu, 17 Jun 2010 21:52:06 +0200
- Dkim-signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:received:mime-version:received:in-reply-to :references:from:date:message-id:subject:to:content-type :content-transfer-encoding; bh=gYZw5jQ0Jfe94KP0Fu//tnQ9nYYOw6b6M+1XmZrVeXQ=; b=Pb16ZxwHWAtQ2GRGyMD1l4WTagtqDVK9wqNMz95Y2c5TUZaHGkiov2QhixfuSvwOPK mQaP4EVJoF01XWxm+HXCcGDw1KKs0zosevEBOSaDGaNOTfGa+G0lf1mbT94COb3Vh0Vf qlI65tdNthvsNuiefAiWHNckBdg0AGgAy6N7g=
- Domainkey-signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :content-type:content-transfer-encoding; b=AYH3iWD9w05AxgrIBXxmYyr5xF2lXpztatBuhGDDxiKaOdN6KTohLRsOJ0/Og0SQkU Tqv5A36gu16+m36PJrpuFcuQi07n84Ynuu4SwRHhw62sgRpBoUlqvfsMMYm9jxkMjFRe vwSLAxjsuygrBfo6kG1cVgCxiR6CMRmM2lZyI=
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 ?
On Thu, Jun 17, 2010 at 3:43 PM, Benoit Jacob <jacob.benoit.1@xxxxxxxxx> wrote:
> 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
> - 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...