[eigen] documentation: the long tutorial |

[ Thread Index | Date Index | More lists.tuxfamily.org/eigen Archives ]

*To*: eigen <eigen@xxxxxxxxxxxxxxxxxxx>*Subject*: [eigen] documentation: the long tutorial*From*: Benoit Jacob <jacob.benoit.1@xxxxxxxxx>*Date*: Thu, 17 Jun 2010 09:43:02 -0400*Dkim-signature*: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:mime-version:received:received:date:message-id :subject:from:to:content-type; bh=7FiwzKQADITxxR1ZdN/j5Jsmi8sv7jX4uH9SybDHDB4=; b=Ney1agBE1Bi9Y53v0WMwI37c6Nvb8rOwvlm488oDt0c6Nr/IhlPHawZ+wKAc0MXmAM aLb3twGwhdxTV90UGWPjeU1HiZvXNDwmfT2W9acX8Q+eO7kP1lr4vYA33xKbwwRRpcV/ Y+QMkUuiz5m5nkJWLn2UNAkZDW+X1ZsURtogA=*Domainkey-signature*: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:date:message-id:subject:from:to:content-type; b=vBnY8VKloHnAzRpeVtEQYIk+hx/rUdYifLOsQRBbPjIe1wl88oxbS5VIGXjqFOxRYM gBFpnCyZcbHfRLmZozWjqCwQ6I2Ty8Nv1l0z/r6VCWTImaHZDjVxIYQRuORlXszyC73l j+iXL/idxr0Drx+Sl8AnEkTl3jKYm0XkwgZu8=

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

**Follow-Ups**:**Re: [eigen] documentation: the long tutorial***From:*Gael Guennebaud

**Messages sorted by:**[ date | thread ]- Prev by Date:
**Re: [eigen] A modest start with the documentation** - Next by Date:
**Re: [eigen] Link error: multiple definition of ei_p*** functions** - Previous by thread:
**Re: [eigen] Eigen Blocked QR algorithm** - Next by thread:
**Re: [eigen] documentation: the long tutorial**

Mail converted by MHonArc 2.6.19+ | http://listengine.tuxfamily.org/ |