From 508b51cb627ade859491030ab3817b05e9a81f17 Mon Sep 17 00:00:00 2001 From: Jitse Niesen Date: Mon, 2 Aug 2010 11:36:44 +0100 Subject: Add page giving an overview of the class hierarchy. This is mostly copied from the wiki, which in turn copies Benoit's email at http://listengine.tuxfamily.org/lists.tuxfamily.org/eigen/2010/06/msg00576.html I used ASCII art for the inheritance diagrams for now, but I don't mind moving to GraphViz/dot as discussed earlier. --- doc/I12_ClassHierarchy.dox | 133 +++++++++++++++++++++++++++++++++++++++++++++ doc/Overview.dox | 1 + 2 files changed, 134 insertions(+) create mode 100644 doc/I12_ClassHierarchy.dox (limited to 'doc') diff --git a/doc/I12_ClassHierarchy.dox b/doc/I12_ClassHierarchy.dox new file mode 100644 index 000000000..a725e3245 --- /dev/null +++ b/doc/I12_ClassHierarchy.dox @@ -0,0 +1,133 @@ +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. + +Table of contents + - \ref TopicClassHierarchyPrinciples + - \ref TopicClassHierarchyCoreClasses + - \ref TopicClassHierarchyBaseClasses + - \ref TopicClassHierarchyInheritanceDiagrams + + +\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. + + - DenseStorageBase 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 DenseStoreBase::resize() resize() \endlink + methods go. \c %DenseStorageBase 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 %DenseStorageBase \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 %DenseStorageBase. 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: + +
+EigenBase<%Matrix>
+  <-- DenseCoeffsBase<%Matrix>    (direct access case)
+    <-- DenseBase<%Matrix>
+      <-- MatrixBase<%Matrix>
+        <-- DenseStorageBase<%Matrix>    (matrix case)
+          <-- Matrix
+
+ +The inheritance diagram for Array looks as follows: + +
+EigenBase<%Array>
+  <-- DenseCoeffsBase<%Array>    (direct access case)
+    <-- DenseBase<%Array>
+      <-- ArrayBase<%Array>
+        <-- DenseStorageBase<%Array>    (array case)
+          <-- Array
+
+ +The inheritance diagram for some other matrix expression class, here denoted by \c SomeMatrixXpr, looks as +follows: + +
+EigenBase<SomeMatrixXpr>
+  <-- DenseCoeffsBase<SomeMatrixXpr>    (direct access or no direct access case)
+    <-- DenseBase<SomeMatrixXpr>
+      <-- MatrixBase<SomeMatrixXpr>
+        <-- SomeMatrixXpr
+
+ +The inheritance diagram for some other array expression class, here denoted by \c SomeArrayXpr, looks as +follows: + +
+EigenBase<SomeArrayXpr>
+  <-- DenseCoeffsBase<SomeArrayXpr>    (direct access or no direct access case)
+    <-- DenseBase<SomeArrayXpr>
+      <-- ArrayBase<SomeArrayXpr>
+        <-- SomeArrayXpr
+
+ +Finally, consider an example of something that is not a dense expression, for instance a diagonal matrix. The +corresponding inheritance diagram is: + +
+EigenBase<%DiagonalMatrix>
+  <-- DiagonalBase<%DiagonalMatrix>
+    <-- DiagonalMatrix
+
+ + +*/ +} diff --git a/doc/Overview.dox b/doc/Overview.dox index 9071c0f15..bb24ef3a9 100644 --- a/doc/Overview.dox +++ b/doc/Overview.dox @@ -35,6 +35,7 @@ For a first contact with Eigen, the best place is to have a look at the \ref Get - \ref TopicCustomizingEigen - \ref TopicInsideEigenExample - \ref TopicWritingEfficientProductExpression + - \ref TopicClassHierarchy - Topics related to alignment issues - \ref TopicUnalignedArrayAssert - \ref TopicFixedSizeVectorizable -- cgit v1.2.3