Re: [eigen] documentation: the long tutorial |

[ Thread Index | Date 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 ? 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 > > >

**Follow-Ups**:**Re: [eigen] documentation: the long tutorial***From:*Benoit Jacob

**References**:**[eigen] documentation: the long tutorial***From:*Benoit Jacob

**Messages sorted by:**[ date | thread ]- Prev by Date:
**Re: [eigen] Link error: multiple definition of ei_p*** functions** - Next by Date:
**Re: [eigen] Link error: multiple definition of ei_p*** functions** - Previous by thread:
**[eigen] documentation: the long tutorial** - Next by thread:
**Re: [eigen] documentation: the long tutorial**

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