123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129 |
- namespace Eigen {
- /** \page TopicClassHierarchy The class hierarchy
- This page explains the design of the core classes in Eigen's class hierarchy and how they fit together. Casual
- users probably need not concern themselves with these details, but it may be useful for both advanced users
- and Eigen developers.
- \eigenAutoToc
- \section TopicClassHierarchyPrinciples Principles
- Eigen's class hierarchy is designed so that virtual functions are avoided where their overhead would
- significantly impair performance. Instead, Eigen achieves polymorphism with the Curiously Recurring Template
- Pattern (CRTP). In this pattern, the base class (for instance, \c MatrixBase) is in fact a template class, and
- the derived class (for instance, \c Matrix) inherits the base class with the derived class itself as a
- template argument (in this case, \c Matrix inherits from \c MatrixBase<Matrix>). This allows Eigen to
- resolve the polymorphic function calls at compile time.
- In addition, the design avoids multiple inheritance. One reason for this is that in our experience, some
- compilers (like MSVC) fail to perform empty base class optimization, which is crucial for our fixed-size
- types.
- \section TopicClassHierarchyCoreClasses The core classes
- These are the classes that you need to know about if you want to write functions that accept or return Eigen
- objects.
- - Matrix means plain dense matrix. If \c m is a \c %Matrix, then, for instance, \c m+m is no longer a
- \c %Matrix, it is a "matrix expression".
- - MatrixBase means dense matrix expression. This means that a \c %MatrixBase is something that can be
- added, matrix-multiplied, LU-decomposed, QR-decomposed... All matrix expression classes, including
- \c %Matrix itself, inherit \c %MatrixBase.
- - Array means plain dense array. If \c x is an \c %Array, then, for instance, \c x+x is no longer an
- \c %Array, it is an "array expression".
- - ArrayBase means dense array expression. This means that an \c %ArrayBase is something that can be
- added, array-multiplied, and on which you can perform all sorts of array operations... All array
- expression classes, including \c %Array itself, inherit \c %ArrayBase.
- - DenseBase means dense (matrix or array) expression. Both \c %ArrayBase and \c %MatrixBase inherit
- \c %DenseBase. \c %DenseBase is where all the methods go that apply to dense expressions regardless of
- whether they are matrix or array expressions. For example, the \link DenseBase::block() block(...) \endlink
- methods are in \c %DenseBase.
- \section TopicClassHierarchyBaseClasses Base classes
- These classes serve as base classes for the five core classes mentioned above. They are more internal and so
- less interesting for users of the Eigen library.
- - PlainObjectBase means dense (matrix or array) plain object, i.e. something that stores its own dense
- array of coefficients. This is where, for instance, the \link PlainObjectBase::resize() resize() \endlink
- methods go. \c %PlainObjectBase is inherited by \c %Matrix and by \c %Array. But above, we said that
- \c %Matrix inherits \c %MatrixBase and \c %Array inherits \c %ArrayBase. So does that mean multiple
- inheritance? No, because \c %PlainObjectBase \e itself inherits \c %MatrixBase or \c %ArrayBase depending
- on whether we are in the matrix or array case. When we said above that \c %Matrix inherited
- \c %MatrixBase, we omitted to say it does so indirectly via \c %PlainObjectBase. Same for \c %Array.
- - DenseCoeffsBase means something that has dense coefficient accessors. It is a base class for
- \c %DenseBase. The reason for \c %DenseCoeffsBase to exist is that the set of available coefficient
- accessors is very different depending on whether a dense expression has direct memory access or not (the
- \c DirectAccessBit flag). For example, if \c x is a plain matrix, then \c x has direct access, and
- \c x.transpose() and \c x.block(...) also have direct access, because their coefficients can be read right
- off memory, but for example, \c x+x does not have direct memory access, because obtaining any of its
- coefficients requires a computation (an addition), it can't be just read off memory.
- - EigenBase means anything that can be evaluated into a plain dense matrix or array (even if that would
- be a bad idea). \c %EigenBase is really the absolute base class for anything that remotely looks like a
- matrix or array. It is a base class for \c %DenseCoeffsBase, so it sits below all our dense class
- hierarchy, but it is not limited to dense expressions. For example, \c %EigenBase is also inherited by
- diagonal matrices, sparse matrices, etc...
- \section TopicClassHierarchyInheritanceDiagrams Inheritance diagrams
- The inheritance diagram for Matrix looks as follows:
- <pre>
- EigenBase<%Matrix>
- <-- DenseCoeffsBase<%Matrix> (direct access case)
- <-- DenseBase<%Matrix>
- <-- MatrixBase<%Matrix>
- <-- PlainObjectBase<%Matrix> (matrix case)
- <-- Matrix
- </pre>
- The inheritance diagram for Array looks as follows:
- <pre>
- EigenBase<%Array>
- <-- DenseCoeffsBase<%Array> (direct access case)
- <-- DenseBase<%Array>
- <-- ArrayBase<%Array>
- <-- PlainObjectBase<%Array> (array case)
- <-- Array
- </pre>
- The inheritance diagram for some other matrix expression class, here denoted by \c SomeMatrixXpr, looks as
- follows:
- <pre>
- EigenBase<SomeMatrixXpr>
- <-- DenseCoeffsBase<SomeMatrixXpr> (direct access or no direct access case)
- <-- DenseBase<SomeMatrixXpr>
- <-- MatrixBase<SomeMatrixXpr>
- <-- SomeMatrixXpr
- </pre>
- The inheritance diagram for some other array expression class, here denoted by \c SomeArrayXpr, looks as
- follows:
- <pre>
- EigenBase<SomeArrayXpr>
- <-- DenseCoeffsBase<SomeArrayXpr> (direct access or no direct access case)
- <-- DenseBase<SomeArrayXpr>
- <-- ArrayBase<SomeArrayXpr>
- <-- SomeArrayXpr
- </pre>
- Finally, consider an example of something that is not a dense expression, for instance a diagonal matrix. The
- corresponding inheritance diagram is:
- <pre>
- EigenBase<%DiagonalMatrix>
- <-- DiagonalBase<%DiagonalMatrix>
- <-- DiagonalMatrix
- </pre>
- */
- }
|