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