Home | History | Annotate | Download | only in doc 
      1 namespace Eigen {
      2 
      3 /** \page TopicClassHierarchy The class hierarchy
      4 
      5 This page explains the design of the core classes in Eigen's class hierarchy and how they fit together. Casual
      6 users probably need not concern themselves with these details, but it may be useful for both advanced users
      7 and Eigen developers.
      8 
      9 <b>Table of contents</b>
     10   - \ref TopicClassHierarchyPrinciples
     11   - \ref TopicClassHierarchyCoreClasses
     12   - \ref TopicClassHierarchyBaseClasses
     13   - \ref TopicClassHierarchyInheritanceDiagrams 
     14 
     15 
     16 \section TopicClassHierarchyPrinciples Principles
     17 
     18 Eigen's class hierarchy is designed so that virtual functions are avoided where their overhead would
     19 significantly impair performance. Instead, Eigen achieves polymorphism with the Curiously Recurring Template
     20 Pattern (CRTP). In this pattern, the base class (for instance, \c MatrixBase) is in fact a template class, and
     21 the derived class (for instance, \c Matrix) inherits the base class with the derived class itself as a
     22 template argument (in this case, \c Matrix inherits from \c MatrixBase&lt;Matrix&gt;). This allows Eigen to
     23 resolve the polymorphic function calls at compile time.
     24 
     25 In addition, the design avoids multiple inheritance. One reason for this is that in our experience, some
     26 compilers (like MSVC) fail to perform empty base class optimization, which is crucial for our fixed-size
     27 types.
     28 
     29 
     30 \section TopicClassHierarchyCoreClasses The core classes
     31 
     32 These are the classes that you need to know about if you want to write functions that accept or return Eigen
     33 objects.
     34 
     35   - Matrix means plain dense matrix. If \c m is a \c %Matrix, then, for instance, \c m+m is no longer a 
     36     \c %Matrix, it is a "matrix expression".
     37   - MatrixBase means dense matrix expression. This means that a \c %MatrixBase is something that can be
     38     added, matrix-multiplied, LU-decomposed, QR-decomposed... All matrix expression classes, including 
     39     \c %Matrix itself, inherit \c %MatrixBase.
     40   - Array means plain dense array. If \c x is an \c %Array, then, for instance, \c x+x is no longer an 
     41     \c %Array, it is an "array expression".
     42   - ArrayBase means dense array expression. This means that an \c %ArrayBase is something that can be
     43     added, array-multiplied, and on which you can perform all sorts of array operations... All array
     44     expression classes, including \c %Array itself, inherit \c %ArrayBase.
     45   - DenseBase means dense (matrix or array) expression. Both \c %ArrayBase and \c %MatrixBase inherit
     46     \c %DenseBase. \c %DenseBase is where all the methods go that apply to dense expressions regardless of
     47     whether they are matrix or array expressions. For example, the \link DenseBase::block() block(...) \endlink
     48     methods are in \c %DenseBase.
     49 
     50 \section TopicClassHierarchyBaseClasses Base classes
     51 
     52 These classes serve as base classes for the five core classes mentioned above. They are more internal and so
     53 less interesting for users of the Eigen library.
     54 
     55   - PlainObjectBase means dense (matrix or array) plain object, i.e. something that stores its own dense
     56     array of coefficients. This is where, for instance, the \link PlainObjectBase::resize() resize() \endlink
     57     methods go. \c %PlainObjectBase is inherited by \c %Matrix and by \c %Array. But above, we said that 
     58     \c %Matrix inherits \c %MatrixBase and \c %Array inherits \c %ArrayBase. So does that mean multiple
     59     inheritance? No, because \c %PlainObjectBase \e itself inherits \c %MatrixBase or \c %ArrayBase depending
     60     on whether we are in the matrix or array case. When we said above that \c %Matrix inherited 
     61     \c %MatrixBase, we omitted to say it does so indirectly via \c %PlainObjectBase. Same for \c %Array.
     62   - DenseCoeffsBase means something that has dense coefficient accessors. It is a base class for
     63     \c %DenseBase. The reason for \c %DenseCoeffsBase to exist is that the set of available coefficient
     64     accessors is very different depending on whether a dense expression has direct memory access or not (the
     65     \c DirectAccessBit flag). For example, if \c x is a plain matrix, then \c x has direct access, and 
     66     \c x.transpose() and \c x.block(...) also have direct access, because their coefficients can be read right
     67     off memory, but for example, \c x+x does not have direct memory access, because obtaining any of its
     68     coefficients requires a computation (an addition), it can't be just read off memory.
     69   - EigenBase means anything that can be evaluated into a plain dense matrix or array (even if that would
     70     be a bad idea). \c %EigenBase is really the absolute base class for anything that remotely looks like a
     71     matrix or array. It is a base class for \c %DenseCoeffsBase, so it sits below all our dense class
     72     hierarchy, but it is not limited to dense expressions. For example, \c %EigenBase is also inherited by
     73     diagonal matrices, sparse matrices, etc...
     74 
     75 
     76 \section TopicClassHierarchyInheritanceDiagrams Inheritance diagrams
     77 
     78 The inheritance diagram for Matrix looks as follows:
     79 
     80 <pre>
     81 EigenBase&lt;%Matrix&gt;
     82   <-- DenseCoeffsBase&lt;%Matrix&gt;    (direct access case)
     83     <-- DenseBase&lt;%Matrix&gt;
     84       <-- MatrixBase&lt;%Matrix&gt;
     85         <-- PlainObjectBase&lt;%Matrix&gt;    (matrix case)
     86           <-- Matrix
     87 </pre>
     88 
     89 The inheritance diagram for Array looks as follows:
     90 
     91 <pre>
     92 EigenBase&lt;%Array&gt;
     93   <-- DenseCoeffsBase&lt;%Array&gt;    (direct access case)
     94     <-- DenseBase&lt;%Array&gt;
     95       <-- ArrayBase&lt;%Array&gt;
     96         <-- PlainObjectBase&lt;%Array&gt;    (array case)
     97           <-- Array
     98 </pre>
     99 
    100 The inheritance diagram for some other matrix expression class, here denoted by \c SomeMatrixXpr, looks as
    101 follows:
    102 
    103 <pre>
    104 EigenBase&lt;SomeMatrixXpr&gt;
    105   <-- DenseCoeffsBase&lt;SomeMatrixXpr&gt;    (direct access or no direct access case)
    106     <-- DenseBase&lt;SomeMatrixXpr&gt;
    107       <-- MatrixBase&lt;SomeMatrixXpr&gt;
    108         <-- SomeMatrixXpr
    109 </pre>
    110 
    111 The inheritance diagram for some other array expression class, here denoted by \c SomeArrayXpr, looks as
    112 follows:
    113 
    114 <pre>
    115 EigenBase&lt;SomeArrayXpr&gt;
    116   <-- DenseCoeffsBase&lt;SomeArrayXpr&gt;    (direct access or no direct access case)
    117     <-- DenseBase&lt;SomeArrayXpr&gt;
    118       <-- ArrayBase&lt;SomeArrayXpr&gt;
    119         <-- SomeArrayXpr
    120 </pre>
    121 
    122 Finally, consider an example of something that is not a dense expression, for instance a diagonal matrix. The
    123 corresponding inheritance diagram is:
    124 
    125 <pre>
    126 EigenBase&lt;%DiagonalMatrix&gt;
    127   <-- DiagonalBase&lt;%DiagonalMatrix&gt;
    128     <-- DiagonalMatrix
    129 </pre>
    130 
    131 
    132 */
    133 }
    134