Documentation for Eigen3

From Eigen
Jump to: navigation, search

Here is an outline for the documentation for Eigen3. The basics are from Benoit's email and replies.

The documentation for Eigen3 consists of the following parts:

  • A super quick 5-minute "getting started" tutorial, similar to the beginning of our existing tutorial.
  • A long, detailed 1-hour tutorial, of perhaps 4-8 pages, taking the time to explain some basic concepts, with lots of links to the other pages:
    • Simple example with fixed-size matrix, to get started. How to "install" Eigen, how to compile the example.
    • Accessing the entries of a matrix.
    • Initializing the matrix. Special matrices (refer to "cheat sheet"), comma initializer.
    • Dynamic-size matrices. Simple example. How to specify the size (constructor, assignment, resize).
    • Matrix operations; some examples with rest in "cheat sheet"
    • Vectors, and where they differ from matrices.
    • The three template parameters of the Matrix templates, and the standard typedefs.
    • Arrays, and where they differ from matrices/vectors.
    • Output.
    • Matrix blocks.
    • The Map class. Interfacing with other libraries / code.
    • How to handle matrices of special shape (diagonal, triangular, symmetric, band).
    • Organization of header files / modules. Summary of modules provided.
    • Summary of special topic pages.
  • A set of topical "cheat sheets", basically like most of current tutorial, just updated, and freed from the requirement of being actually a tutorial - this just has to be a reference, since the tutorial role is taken over by other pages. Also see ASCII quick reference.
    • List cheat sheets here
  • Doxygen pages on specific topics, like http://eigen.tuxfamily.org/dox/TopicLazyEvaluation.html . These may overlap a bit, the goal is to make info easy to find.
    • What member data is inside of a Matrix/Array? What's the memory layout? Is it heap allocated? People want to know how to interact with other libs, and want to know if Eigen incurs any memory overhead (esp. in the fixed-size case). Knowing that a Matrix is just a dumb array of coeffs, will also help people understand stuff.
    • Storage orders. What's the default? How to use row-major? How to set it as the default? When evaluating m.transpose(), what storage order is used? What about the special case of Vectors, can a row-vector be column-major storage order (hint: no it can't, vectors MUST have the "right" storage order or you get a compilation error).
    • Memory allocation, even if that will overlap with many other pages, because many people will be looking for info about that. What causes heap allocation? Mention aligned malloc too. That page should perhaps be mostly just links to other pages. See Talk:FAQ for a start.
    • Sizes at compile time. The constant Dynamic. The Max-sizes. The link between the Max-sizes and memory allocation: the fact that Matrix4f().block(...).eval() doesn't cause a heap allocation. Block(...) is the perfect example for the Max-sizes.
    • Alignment, aligned malloc, alignment qualifiers, the issues that that can cause (link to the unaligned assert's pages)
    • Expression templates, lazy evaluation etc.
    • Aliasing, eval(), noalias().
    • Writing one's own expression classes; inheriting from Matrix and other Eigen classes.
    • The overall design and class hierarchy, the role of MatrixBase and other base classes, the standard typedefs such as PlainMatrixType and Scalar...
    • Writing functions that take matrices as arguments and/or return them. What prototype to use? Matrix or MatrixBase? (perhaps combine with point above)
    • Compile-time switches (preprocessor symbols like EIGEN_NO_DEBUG etc)
    • Compiler support/options and Vectorization : also see coverage in the FAQ
    • Thread safety
    • Usage with OpenGL
    • The existing "special topics" pages need to be updated and/or replaced.
  • The API pages generated by doxygen.

This wiki is used to supplement the documentation. Information available here can be converted to the doxygen docs if necessary / required.