[136] | 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 | \eigenAutoToc
|
---|
| 10 |
|
---|
| 11 |
|
---|
| 12 | \section TopicClassHierarchyPrinciples Principles
|
---|
| 13 |
|
---|
| 14 | Eigen's class hierarchy is designed so that virtual functions are avoided where their overhead would
|
---|
| 15 | significantly impair performance. Instead, Eigen achieves polymorphism with the Curiously Recurring Template
|
---|
| 16 | Pattern (CRTP). In this pattern, the base class (for instance, \c MatrixBase) is in fact a template class, and
|
---|
| 17 | the derived class (for instance, \c Matrix) inherits the base class with the derived class itself as a
|
---|
| 18 | template argument (in this case, \c Matrix inherits from \c MatrixBase<Matrix>). This allows Eigen to
|
---|
| 19 | resolve the polymorphic function calls at compile time.
|
---|
| 20 |
|
---|
| 21 | In addition, the design avoids multiple inheritance. One reason for this is that in our experience, some
|
---|
| 22 | compilers (like MSVC) fail to perform empty base class optimization, which is crucial for our fixed-size
|
---|
| 23 | types.
|
---|
| 24 |
|
---|
| 25 |
|
---|
| 26 | \section TopicClassHierarchyCoreClasses The core classes
|
---|
| 27 |
|
---|
| 28 | These are the classes that you need to know about if you want to write functions that accept or return Eigen
|
---|
| 29 | objects.
|
---|
| 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 |
|
---|
| 48 | These classes serve as base classes for the five core classes mentioned above. They are more internal and so
|
---|
| 49 | less 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 |
|
---|
| 74 | The inheritance diagram for Matrix looks as follows:
|
---|
| 75 |
|
---|
| 76 | <pre>
|
---|
| 77 | EigenBase<%Matrix>
|
---|
| 78 | <-- DenseCoeffsBase<%Matrix> (direct access case)
|
---|
| 79 | <-- DenseBase<%Matrix>
|
---|
| 80 | <-- MatrixBase<%Matrix>
|
---|
| 81 | <-- PlainObjectBase<%Matrix> (matrix case)
|
---|
| 82 | <-- Matrix
|
---|
| 83 | </pre>
|
---|
| 84 |
|
---|
| 85 | The inheritance diagram for Array looks as follows:
|
---|
| 86 |
|
---|
| 87 | <pre>
|
---|
| 88 | EigenBase<%Array>
|
---|
| 89 | <-- DenseCoeffsBase<%Array> (direct access case)
|
---|
| 90 | <-- DenseBase<%Array>
|
---|
| 91 | <-- ArrayBase<%Array>
|
---|
| 92 | <-- PlainObjectBase<%Array> (array case)
|
---|
| 93 | <-- Array
|
---|
| 94 | </pre>
|
---|
| 95 |
|
---|
| 96 | The inheritance diagram for some other matrix expression class, here denoted by \c SomeMatrixXpr, looks as
|
---|
| 97 | follows:
|
---|
| 98 |
|
---|
| 99 | <pre>
|
---|
| 100 | EigenBase<SomeMatrixXpr>
|
---|
| 101 | <-- DenseCoeffsBase<SomeMatrixXpr> (direct access or no direct access case)
|
---|
| 102 | <-- DenseBase<SomeMatrixXpr>
|
---|
| 103 | <-- MatrixBase<SomeMatrixXpr>
|
---|
| 104 | <-- SomeMatrixXpr
|
---|
| 105 | </pre>
|
---|
| 106 |
|
---|
| 107 | The inheritance diagram for some other array expression class, here denoted by \c SomeArrayXpr, looks as
|
---|
| 108 | follows:
|
---|
| 109 |
|
---|
| 110 | <pre>
|
---|
| 111 | EigenBase<SomeArrayXpr>
|
---|
| 112 | <-- DenseCoeffsBase<SomeArrayXpr> (direct access or no direct access case)
|
---|
| 113 | <-- DenseBase<SomeArrayXpr>
|
---|
| 114 | <-- ArrayBase<SomeArrayXpr>
|
---|
| 115 | <-- SomeArrayXpr
|
---|
| 116 | </pre>
|
---|
| 117 |
|
---|
| 118 | Finally, consider an example of something that is not a dense expression, for instance a diagonal matrix. The
|
---|
| 119 | corresponding inheritance diagram is:
|
---|
| 120 |
|
---|
| 121 | <pre>
|
---|
| 122 | EigenBase<%DiagonalMatrix>
|
---|
| 123 | <-- DiagonalBase<%DiagonalMatrix>
|
---|
| 124 | <-- DiagonalMatrix
|
---|
| 125 | </pre>
|
---|
| 126 |
|
---|
| 127 |
|
---|
| 128 | */
|
---|
| 129 | }
|
---|