From 2abe7d8c6e11a02fc345f6ae464b4b759b092a67 Mon Sep 17 00:00:00 2001 From: Gael Guennebaud Date: Sun, 6 Jan 2013 23:57:54 +0100 Subject: Rename the dox files: the number prefixes are not needed anymore --- doc/C00_QuickStartGuide.dox | 100 ----- doc/C01_TutorialMatrixClass.dox | 264 ----------- doc/C02_TutorialMatrixArithmetic.dox | 214 --------- doc/C03_TutorialArrayClass.dox | 192 -------- doc/C04_TutorialBlockOperations.dox | 228 ---------- doc/C05_TutorialAdvancedInitialization.dox | 162 ------- doc/C06_TutorialLinearAlgebra.dox | 255 ----------- doc/C07_TutorialReductionsVisitorsBroadcasting.dox | 257 ----------- doc/C08_TutorialGeometry.dox | 241 ---------- doc/C09_TutorialSparse.dox | 436 ------------------ doc/C10_TutorialMapClass.dox | 86 ---- doc/ClassHierarchy.dox | 129 ++++++ doc/CustomizingEigen.dox | 188 ++++++++ doc/D01_StlContainers.dox | 62 --- doc/D03_WrongStackAlignment.dox | 56 --- doc/D07_PassingByValue.dox | 40 -- doc/D09_StructHavingEigenMembers.dox | 190 -------- doc/D11_UnalignedArrayAssert.dox | 114 ----- doc/FixedSizeVectorizable.dox | 38 ++ doc/FunctionsTakingEigenTypes.dox | 183 ++++++++ doc/HiPerformance.dox | 128 ++++++ doc/I00_CustomizingEigen.dox | 188 -------- doc/I01_TopicLazyEvaluation.dox | 65 --- doc/I02_HiPerformance.dox | 128 ------ doc/I03_InsideEigenExample.dox | 495 --------------------- doc/I05_FixedSizeVectorizable.dox | 38 -- doc/I06_TopicEigenExpressionTemplates.dox | 12 - doc/I07_TopicScalarTypes.dox | 12 - doc/I08_Resizing.dox | 11 - doc/I09_Vectorization.dox | 9 - doc/I10_Assertions.dox | 108 ----- doc/I11_Aliasing.dox | 209 --------- doc/I12_ClassHierarchy.dox | 129 ------ doc/I13_FunctionsTakingEigenTypes.dox | 183 -------- doc/I14_PreprocessorDirectives.dox | 107 ----- doc/I15_StorageOrders.dox | 86 ---- doc/I16_TemplateKeyword.dox | 132 ------ doc/I17_SparseLinearSystems.dox | 107 ----- doc/InsideEigenExample.dox | 495 +++++++++++++++++++++ doc/PassingByValue.dox | 40 ++ doc/PreprocessorDirectives.dox | 107 +++++ doc/QuickStartGuide.dox | 100 +++++ doc/SparseLinearSystems.dox | 107 +++++ doc/StlContainers.dox | 62 +++ doc/StorageOrders.dox | 86 ++++ doc/StructHavingEigenMembers.dox | 190 ++++++++ doc/TemplateKeyword.dox | 132 ++++++ doc/TopicAliasing.dox | 209 +++++++++ doc/TopicAssertions.dox | 108 +++++ doc/TopicEigenExpressionTemplates.dox | 12 + doc/TopicLazyEvaluation.dox | 65 +++ doc/TopicResizing.dox | 11 + doc/TopicScalarTypes.dox | 12 + doc/TopicVectorization.dox | 9 + doc/TutorialAdvancedInitialization.dox | 162 +++++++ doc/TutorialArrayClass.dox | 192 ++++++++ doc/TutorialBlockOperations.dox | 228 ++++++++++ doc/TutorialGeometry.dox | 241 ++++++++++ doc/TutorialLinearAlgebra.dox | 255 +++++++++++ doc/TutorialMapClass.dox | 86 ++++ doc/TutorialMatrixArithmetic.dox | 214 +++++++++ doc/TutorialMatrixClass.dox | 264 +++++++++++ doc/TutorialReductionsVisitorsBroadcasting.dox | 257 +++++++++++ doc/TutorialSparse.dox | 436 ++++++++++++++++++ doc/UnalignedArrayAssert.dox | 114 +++++ doc/WrongStackAlignment.dox | 56 +++ 66 files changed, 4916 insertions(+), 4916 deletions(-) delete mode 100644 doc/C00_QuickStartGuide.dox delete mode 100644 doc/C01_TutorialMatrixClass.dox delete mode 100644 doc/C02_TutorialMatrixArithmetic.dox delete mode 100644 doc/C03_TutorialArrayClass.dox delete mode 100644 doc/C04_TutorialBlockOperations.dox delete mode 100644 doc/C05_TutorialAdvancedInitialization.dox delete mode 100644 doc/C06_TutorialLinearAlgebra.dox delete mode 100644 doc/C07_TutorialReductionsVisitorsBroadcasting.dox delete mode 100644 doc/C08_TutorialGeometry.dox delete mode 100644 doc/C09_TutorialSparse.dox delete mode 100644 doc/C10_TutorialMapClass.dox create mode 100644 doc/ClassHierarchy.dox create mode 100644 doc/CustomizingEigen.dox delete mode 100644 doc/D01_StlContainers.dox delete mode 100644 doc/D03_WrongStackAlignment.dox delete mode 100644 doc/D07_PassingByValue.dox delete mode 100644 doc/D09_StructHavingEigenMembers.dox delete mode 100644 doc/D11_UnalignedArrayAssert.dox create mode 100644 doc/FixedSizeVectorizable.dox create mode 100644 doc/FunctionsTakingEigenTypes.dox create mode 100644 doc/HiPerformance.dox delete mode 100644 doc/I00_CustomizingEigen.dox delete mode 100644 doc/I01_TopicLazyEvaluation.dox delete mode 100644 doc/I02_HiPerformance.dox delete mode 100644 doc/I03_InsideEigenExample.dox delete mode 100644 doc/I05_FixedSizeVectorizable.dox delete mode 100644 doc/I06_TopicEigenExpressionTemplates.dox delete mode 100644 doc/I07_TopicScalarTypes.dox delete mode 100644 doc/I08_Resizing.dox delete mode 100644 doc/I09_Vectorization.dox delete mode 100644 doc/I10_Assertions.dox delete mode 100644 doc/I11_Aliasing.dox delete mode 100644 doc/I12_ClassHierarchy.dox delete mode 100644 doc/I13_FunctionsTakingEigenTypes.dox delete mode 100644 doc/I14_PreprocessorDirectives.dox delete mode 100644 doc/I15_StorageOrders.dox delete mode 100644 doc/I16_TemplateKeyword.dox delete mode 100644 doc/I17_SparseLinearSystems.dox create mode 100644 doc/InsideEigenExample.dox create mode 100644 doc/PassingByValue.dox create mode 100644 doc/PreprocessorDirectives.dox create mode 100644 doc/QuickStartGuide.dox create mode 100644 doc/SparseLinearSystems.dox create mode 100644 doc/StlContainers.dox create mode 100644 doc/StorageOrders.dox create mode 100644 doc/StructHavingEigenMembers.dox create mode 100644 doc/TemplateKeyword.dox create mode 100644 doc/TopicAliasing.dox create mode 100644 doc/TopicAssertions.dox create mode 100644 doc/TopicEigenExpressionTemplates.dox create mode 100644 doc/TopicLazyEvaluation.dox create mode 100644 doc/TopicResizing.dox create mode 100644 doc/TopicScalarTypes.dox create mode 100644 doc/TopicVectorization.dox create mode 100644 doc/TutorialAdvancedInitialization.dox create mode 100644 doc/TutorialArrayClass.dox create mode 100644 doc/TutorialBlockOperations.dox create mode 100644 doc/TutorialGeometry.dox create mode 100644 doc/TutorialLinearAlgebra.dox create mode 100644 doc/TutorialMapClass.dox create mode 100644 doc/TutorialMatrixArithmetic.dox create mode 100644 doc/TutorialMatrixClass.dox create mode 100644 doc/TutorialReductionsVisitorsBroadcasting.dox create mode 100644 doc/TutorialSparse.dox create mode 100644 doc/UnalignedArrayAssert.dox create mode 100644 doc/WrongStackAlignment.dox diff --git a/doc/C00_QuickStartGuide.dox b/doc/C00_QuickStartGuide.dox deleted file mode 100644 index ea32c3b3d..000000000 --- a/doc/C00_QuickStartGuide.dox +++ /dev/null @@ -1,100 +0,0 @@ -namespace Eigen { - -/** \page GettingStarted Getting started - -\eigenAutoToc - -This is a very short guide on how to get started with Eigen. It has a dual purpose. It serves as a minimal introduction to the Eigen library for people who want to start coding as soon as possible. You can also read this page as the first part of the Tutorial, which explains the library in more detail; in this case you will continue with \ref TutorialMatrixClass. - -\section GettingStartedInstallation How to "install" Eigen? - -In order to use Eigen, you just need to download and extract Eigen's source code (see the wiki for download instructions). In fact, the header files in the \c Eigen subdirectory are the only files required to compile programs using Eigen. The header files are the same for all platforms. It is not necessary to use CMake or install anything. - - -\section GettingStartedFirstProgram A simple first program - -Here is a rather simple program to get you started. - -\include QuickStart_example.cpp - -We will explain the program after telling you how to compile it. - - -\section GettingStartedCompiling Compiling and running your first program - -There is no library to link to. The only thing that you need to keep in mind when compiling the above program is that the compiler must be able to find the Eigen header files. The directory in which you placed Eigen's source code must be in the include path. With GCC you use the -I option to achieve this, so you can compile the program with a command like this: - -\code g++ -I /path/to/eigen/ my_program.cpp -o my_program \endcode - -On Linux or Mac OS X, another option is to symlink or copy the Eigen folder into /usr/local/include/. This way, you can compile the program with: - -\code g++ my_program.cpp -o my_program \endcode - -When you run the program, it produces the following output: - -\include QuickStart_example.out - - -\section GettingStartedExplanation Explanation of the first program - -The Eigen header files define many types, but for simple applications it may be enough to use only the \c MatrixXd type. This represents a matrix of arbitrary size (hence the \c X in \c MatrixXd), in which every entry is a \c double (hence the \c d in \c MatrixXd). See the \ref QuickRef_Types "quick reference guide" for an overview of the different types you can use to represent a matrix. - -The \c Eigen/Dense header file defines all member functions for the MatrixXd type and related types (see also the \ref QuickRef_Headers "table of header files"). All classes and functions defined in this header file (and other Eigen header files) are in the \c Eigen namespace. - -The first line of the \c main function declares a variable of type \c MatrixXd and specifies that it is a matrix with 2 rows and 2 columns (the entries are not initialized). The statement m(0,0) = 3 sets the entry in the top-left corner to 3. You need to use round parentheses to refer to entries in the matrix. As usual in computer science, the index of the first index is 0, as opposed to the convention in mathematics that the first index is 1. - -The following three statements sets the other three entries. The final line outputs the matrix \c m to the standard output stream. - - -\section GettingStartedExample2 Example 2: Matrices and vectors - -Here is another example, which combines matrices with vectors. Concentrate on the left-hand program for now; we will talk about the right-hand program later. - - - - -
Size set at run time:Size set at compile time:
-\include QuickStart_example2_dynamic.cpp - -\include QuickStart_example2_fixed.cpp -
- -The output is as follows: - -\include QuickStart_example2_dynamic.out - - -\section GettingStartedExplanation2 Explanation of the second example - -The second example starts by declaring a 3-by-3 matrix \c m which is initialized using the \link DenseBase::Random(Index,Index) Random() \endlink method with random values between -1 and 1. The next line applies a linear mapping such that the values are between 10 and 110. The function call \link DenseBase::Constant(Index,Index,const Scalar&) MatrixXd::Constant\endlink(3,3,1.2) returns a 3-by-3 matrix expression having all coefficients equal to 1.2. The rest is standard arithmetics. - -The next line of the \c main function introduces a new type: \c VectorXd. This represents a (column) vector of arbitrary size. Here, the vector \c v is created to contain \c 3 coefficients which are left unitialized. The one but last line uses the so-called comma-initializer, explained in \ref TutorialAdvancedInitialization, to set all coefficients of the vector \c v to be as follows: - -\f[ -v = -\begin{bmatrix} - 1 \\ - 2 \\ - 3 -\end{bmatrix}. -\f] - -The final line of the program multiplies the matrix \c m with the vector \c v and outputs the result. - -Now look back at the second example program. We presented two versions of it. In the version in the left column, the matrix is of type \c MatrixXd which represents matrices of arbitrary size. The version in the right column is similar, except that the matrix is of type \c Matrix3d, which represents matrices of a fixed size (here 3-by-3). Because the type already encodes the size of the matrix, it is not necessary to specify the size in the constructor; compare MatrixXd m(3,3) with Matrix3d m. Similarly, we have \c VectorXd on the left (arbitrary size) versus \c Vector3d on the right (fixed size). Note that here the coefficients of vector \c v are directly set in the constructor, though the same syntax of the left example could be used too. - -The use of fixed-size matrices and vectors has two advantages. The compiler emits better (faster) code because it knows the size of the matrices and vectors. Specifying the size in the type also allows for more rigorous checking at compile-time. For instance, the compiler will complain if you try to multiply a \c Matrix4d (a 4-by-4 matrix) with a \c Vector3d (a vector of size 3). However, the use of many types increases compilation time and the size of the executable. The size of the matrix may also not be known at compile-time. A rule of thumb is to use fixed-size matrices for size 4-by-4 and smaller. - - -\section GettingStartedConclusion Where to go from here? - -It's worth taking the time to read the \ref TutorialMatrixClass "long tutorial". - -However if you think you don't need it, you can directly use the classes documentation and our \ref QuickRefPage. - -\li \b Next: \ref TutorialMatrixClass - -*/ - -} - diff --git a/doc/C01_TutorialMatrixClass.dox b/doc/C01_TutorialMatrixClass.dox deleted file mode 100644 index 057341422..000000000 --- a/doc/C01_TutorialMatrixClass.dox +++ /dev/null @@ -1,264 +0,0 @@ -namespace Eigen { - -/** \eigenManualPage TutorialMatrixClass The Matrix class - -\eigenAutoToc - -In Eigen, all matrices and vectors are objects of the Matrix template class. -Vectors are just a special case of matrices, with either 1 row or 1 column. - -\section TutorialMatrixFirst3Params The first three template parameters of Matrix - -The Matrix class takes six template parameters, but for now it's enough to -learn about the first three first parameters. The three remaining parameters have default -values, which for now we will leave untouched, and which we -\ref TutorialMatrixOptTemplParams "discuss below". - -The three mandatory template parameters of Matrix are: -\code -Matrix -\endcode -\li \c Scalar is the scalar type, i.e. the type of the coefficients. - That is, if you want a matrix of floats, choose \c float here. - See \ref TopicScalarTypes "Scalar types" for a list of all supported - scalar types and for how to extend support to new types. -\li \c RowsAtCompileTime and \c ColsAtCompileTime are the number of rows - and columns of the matrix as known at compile time (see - \ref TutorialMatrixDynamic "below" for what to do if the number is not - known at compile time). - -We offer a lot of convenience typedefs to cover the usual cases. For example, \c Matrix4f is -a 4x4 matrix of floats. Here is how it is defined by Eigen: -\code -typedef Matrix Matrix4f; -\endcode -We discuss \ref TutorialMatrixTypedefs "below" these convenience typedefs. - -\section TutorialMatrixVectors Vectors - -As mentioned above, in Eigen, vectors are just a special case of -matrices, with either 1 row or 1 column. The case where they have 1 column is the most common; -such vectors are called column-vectors, often abbreviated as just vectors. In the other case -where they have 1 row, they are called row-vectors. - -For example, the convenience typedef \c Vector3f is a (column) vector of 3 floats. It is defined as follows by Eigen: -\code -typedef Matrix Vector3f; -\endcode -We also offer convenience typedefs for row-vectors, for example: -\code -typedef Matrix RowVector2i; -\endcode - -\section TutorialMatrixDynamic The special value Dynamic - -Of course, Eigen is not limited to matrices whose dimensions are known at compile time. -The \c RowsAtCompileTime and \c ColsAtCompileTime template parameters can take the special -value \c Dynamic which indicates that the size is unknown at compile time, so must -be handled as a run-time variable. In Eigen terminology, such a size is referred to as a -\em dynamic \em size; while a size that is known at compile time is called a -\em fixed \em size. For example, the convenience typedef \c MatrixXd, meaning -a matrix of doubles with dynamic size, is defined as follows: -\code -typedef Matrix MatrixXd; -\endcode -And similarly, we define a self-explanatory typedef \c VectorXi as follows: -\code -typedef Matrix VectorXi; -\endcode -You can perfectly have e.g. a fixed number of rows with a dynamic number of columns, as in: -\code -Matrix -\endcode - -\section TutorialMatrixConstructors Constructors - -A default constructor is always available, never performs any dynamic memory allocation, and never initializes the matrix coefficients. You can do: -\code -Matrix3f a; -MatrixXf b; -\endcode -Here, -\li \c a is a 3x3 matrix, with a static float[9] array of uninitialized coefficients, -\li \c b is a dynamic-size matrix whose size is currently 0x0, and whose array of -coefficients hasn't yet been allocated at all. - -Constructors taking sizes are also available. For matrices, the number of rows is always passed first. -For vectors, just pass the vector size. They allocate the array of coefficients -with the given size, but don't initialize the coefficients themselves: -\code -MatrixXf a(10,15); -VectorXf b(30); -\endcode -Here, -\li \c a is a 10x15 dynamic-size matrix, with allocated but currently uninitialized coefficients. -\li \c b is a dynamic-size vector of size 30, with allocated but currently uninitialized coefficients. - -In order to offer a uniform API across fixed-size and dynamic-size matrices, it is legal to use these -constructors on fixed-size matrices, even if passing the sizes is useless in this case. So this is legal: -\code -Matrix3f a(3,3); -\endcode -and is a no-operation. - -Finally, we also offer some constructors to initialize the coefficients of small fixed-size vectors up to size 4: -\code -Vector2d a(5.0, 6.0); -Vector3d b(5.0, 6.0, 7.0); -Vector4d c(5.0, 6.0, 7.0, 8.0); -\endcode - -\section TutorialMatrixCoeffAccessors Coefficient accessors - -The primary coefficient accessors and mutators in Eigen are the overloaded parenthesis operators. -For matrices, the row index is always passed first. For vectors, just pass one index. -The numbering starts at 0. This example is self-explanatory: - - - - -
Example:Output:
-\include tut_matrix_coefficient_accessors.cpp - -\verbinclude tut_matrix_coefficient_accessors.out -
- -Note that the syntax m(index) -is not restricted to vectors, it is also available for general matrices, meaning index-based access -in the array of coefficients. This however depends on the matrix's storage order. All Eigen matrices default to -column-major storage order, but this can be changed to row-major, see \ref TopicStorageOrders "Storage orders". - -The operator[] is also overloaded for index-based access in vectors, but keep in mind that C++ doesn't allow operator[] to -take more than one argument. We restrict operator[] to vectors, because an awkwardness in the C++ language -would make matrix[i,j] compile to the same thing as matrix[j] ! - -\section TutorialMatrixCommaInitializer Comma-initialization - -%Matrix and vector coefficients can be conveniently set using the so-called \em comma-initializer syntax. -For now, it is enough to know this example: - - - - - - -
Example:Output:
\include Tutorial_commainit_01.cpp \verbinclude Tutorial_commainit_01.out
- - -The right-hand side can also contain matrix expressions as discussed in \ref TutorialAdvancedInitialization "this page". - -\section TutorialMatrixSizesResizing Resizing - -The current size of a matrix can be retrieved by \link EigenBase::rows() rows()\endlink, \link EigenBase::cols() cols() \endlink and \link EigenBase::size() size()\endlink. These methods return the number of rows, the number of columns and the number of coefficients, respectively. Resizing a dynamic-size matrix is done by the \link PlainObjectBase::resize(Index,Index) resize() \endlink method. - - - - - - -
Example:Output:
\include tut_matrix_resize.cpp \verbinclude tut_matrix_resize.out
- -The resize() method is a no-operation if the actual matrix size doesn't change; otherwise it is destructive: the values of the coefficients may change. -If you want a conservative variant of resize() which does not change the coefficients, use \link PlainObjectBase::conservativeResize() conservativeResize()\endlink, see \ref TopicResizing "this page" for more details. - -All these methods are still available on fixed-size matrices, for the sake of API uniformity. Of course, you can't actually -resize a fixed-size matrix. Trying to change a fixed size to an actually different value will trigger an assertion failure; -but the following code is legal: - - - - - - -
Example:Output:
\include tut_matrix_resize_fixed_size.cpp \verbinclude tut_matrix_resize_fixed_size.out
- - -\section TutorialMatrixAssignment Assignment and resizing - -Assignment is the action of copying a matrix into another, using \c operator=. Eigen resizes the matrix on the left-hand side automatically so that it matches the size of the matrix on the right-hand size. For example: - - - - - - -
Example:Output:
\include tut_matrix_assignment_resizing.cpp \verbinclude tut_matrix_assignment_resizing.out
- -Of course, if the left-hand side is of fixed size, resizing it is not allowed. - -If you do not want this automatic resizing to happen (for example for debugging purposes), you can disable it, see -\ref TopicResizing "this page". - - -\section TutorialMatrixFixedVsDynamic Fixed vs. Dynamic size - -When should one use fixed sizes (e.g. \c Matrix4f), and when should one prefer dynamic sizes (e.g. \c MatrixXf)? -The simple answer is: use fixed -sizes for very small sizes where you can, and use dynamic sizes for larger sizes or where you have to. For small sizes, -especially for sizes smaller than (roughly) 16, using fixed sizes is hugely beneficial -to performance, as it allows Eigen to avoid dynamic memory allocation and to unroll -loops. Internally, a fixed-size Eigen matrix is just a plain static array, i.e. doing -\code Matrix4f mymatrix; \endcode -really amounts to just doing -\code float mymatrix[16]; \endcode -so this really has zero runtime cost. By contrast, the array of a dynamic-size matrix -is always allocated on the heap, so doing -\code MatrixXf mymatrix(rows,columns); \endcode -amounts to doing -\code float *mymatrix = new float[rows*columns]; \endcode -and in addition to that, the MatrixXf object stores its number of rows and columns as -member variables. - -The limitation of using fixed sizes, of course, is that this is only possible -when you know the sizes at compile time. Also, for large enough sizes, say for sizes -greater than (roughly) 32, the performance benefit of using fixed sizes becomes negligible. -Worse, trying to create a very large matrix using fixed sizes could result in a stack overflow, -since Eigen will try to allocate the array as a static array, which by default goes on the stack. -Finally, depending on circumstances, Eigen can also be more aggressive trying to vectorize -(use SIMD instructions) when dynamic sizes are used, see \ref TopicVectorization "Vectorization". - -\section TutorialMatrixOptTemplParams Optional template parameters - -We mentioned at the beginning of this page that the Matrix class takes six template parameters, -but so far we only discussed the first three. The remaining three parameters are optional. Here is -the complete list of template parameters: -\code -Matrix -\endcode -\li \c Options is a bit field. Here, we discuss only one bit: \c RowMajor. It specifies that the matrices - of this type use row-major storage order; by default, the storage order is column-major. See the page on - \ref TopicStorageOrders "storage orders". For example, this type means row-major 3x3 matrices: - \code - Matrix - \endcode -\li \c MaxRowsAtCompileTime and \c MaxColsAtCompileTime are useful when you want to specify that, even though - the exact sizes of your matrices are not known at compile time, a fixed upper bound is known at - compile time. The biggest reason why you might want to do that is to avoid dynamic memory allocation. - For example the following matrix type uses a static array of 12 floats, without dynamic memory allocation: - \code - Matrix - \endcode - -\section TutorialMatrixTypedefs Convenience typedefs - -Eigen defines the following Matrix typedefs: -\li MatrixNt for Matrix. For example, MatrixXi for Matrix. -\li VectorNt for Matrix. For example, Vector2f for Matrix. -\li RowVectorNt for Matrix. For example, RowVector3d for Matrix. - -Where: -\li N can be any one of \c 2, \c 3, \c 4, or \c X (meaning \c Dynamic). -\li t can be any one of \c i (meaning int), \c f (meaning float), \c d (meaning double), - \c cf (meaning complex), or \c cd (meaning complex). The fact that typedefs are only - defined for these five types doesn't mean that they are the only supported scalar types. For example, - all standard integer types are supported, see \ref TopicScalarTypes "Scalar types". - - -*/ - -} diff --git a/doc/C02_TutorialMatrixArithmetic.dox b/doc/C02_TutorialMatrixArithmetic.dox deleted file mode 100644 index 5fc569a30..000000000 --- a/doc/C02_TutorialMatrixArithmetic.dox +++ /dev/null @@ -1,214 +0,0 @@ -namespace Eigen { - -/** \eigenManualPage TutorialMatrixArithmetic Matrix and vector arithmetic - -This page aims to provide an overview and some details on how to perform arithmetic -between matrices, vectors and scalars with Eigen. - -\eigenAutoToc - -\section TutorialArithmeticIntroduction Introduction - -Eigen offers matrix/vector arithmetic operations either through overloads of common C++ arithmetic operators such as +, -, *, -or through special methods such as dot(), cross(), etc. -For the Matrix class (matrices and vectors), operators are only overloaded to support -linear-algebraic operations. For example, \c matrix1 \c * \c matrix2 means matrix-matrix product, -and \c vector \c + \c scalar is just not allowed. If you want to perform all kinds of array operations, -not linear algebra, see the \ref TutorialArrayClass "next page". - -\section TutorialArithmeticAddSub Addition and subtraction - -The left hand side and right hand side must, of course, have the same numbers of rows and of columns. They must -also have the same \c Scalar type, as Eigen doesn't do automatic type promotion. The operators at hand here are: -\li binary operator + as in \c a+b -\li binary operator - as in \c a-b -\li unary operator - as in \c -a -\li compound operator += as in \c a+=b -\li compound operator -= as in \c a-=b - - - - -
Example:Output:
-\include tut_arithmetic_add_sub.cpp - -\verbinclude tut_arithmetic_add_sub.out -
- -\section TutorialArithmeticScalarMulDiv Scalar multiplication and division - -Multiplication and division by a scalar is very simple too. The operators at hand here are: -\li binary operator * as in \c matrix*scalar -\li binary operator * as in \c scalar*matrix -\li binary operator / as in \c matrix/scalar -\li compound operator *= as in \c matrix*=scalar -\li compound operator /= as in \c matrix/=scalar - - - - -
Example:Output:
-\include tut_arithmetic_scalar_mul_div.cpp - -\verbinclude tut_arithmetic_scalar_mul_div.out -
- - -\section TutorialArithmeticMentionXprTemplates A note about expression templates - -This is an advanced topic that we explain on \ref TopicEigenExpressionTemplates "this page", -but it is useful to just mention it now. In Eigen, arithmetic operators such as \c operator+ don't -perform any computation by themselves, they just return an "expression object" describing the computation to be -performed. The actual computation happens later, when the whole expression is evaluated, typically in \c operator=. -While this might sound heavy, any modern optimizing compiler is able to optimize away that abstraction and -the result is perfectly optimized code. For example, when you do: -\code -VectorXf a(50), b(50), c(50), d(50); -... -a = 3*b + 4*c + 5*d; -\endcode -Eigen compiles it to just one for loop, so that the arrays are traversed only once. Simplifying (e.g. ignoring -SIMD optimizations), this loop looks like this: -\code -for(int i = 0; i < 50; ++i) - a[i] = 3*b[i] + 4*c[i] + 5*d[i]; -\endcode -Thus, you should not be afraid of using relatively large arithmetic expressions with Eigen: it only gives Eigen -more opportunities for optimization. - -\section TutorialArithmeticTranspose Transposition and conjugation - -The transpose \f$ a^T \f$, conjugate \f$ \bar{a} \f$, and adjoint (i.e., conjugate transpose) \f$ a^* \f$ of a matrix or vector \f$ a \f$ are obtained by the member functions \link DenseBase::transpose() transpose()\endlink, \link MatrixBase::conjugate() conjugate()\endlink, and \link MatrixBase::adjoint() adjoint()\endlink, respectively. - - - - -
Example:Output:
-\include tut_arithmetic_transpose_conjugate.cpp - -\verbinclude tut_arithmetic_transpose_conjugate.out -
- -For real matrices, \c conjugate() is a no-operation, and so \c adjoint() is equivalent to \c transpose(). - -As for basic arithmetic operators, \c transpose() and \c adjoint() simply return a proxy object without doing the actual transposition. If you do b = a.transpose(), then the transpose is evaluated at the same time as the result is written into \c b. However, there is a complication here. If you do a = a.transpose(), then Eigen starts writing the result into \c a before the evaluation of the transpose is finished. Therefore, the instruction a = a.transpose() does not replace \c a with its transpose, as one would expect: - - - -
Example:Output:
-\include tut_arithmetic_transpose_aliasing.cpp - -\verbinclude tut_arithmetic_transpose_aliasing.out -
-This is the so-called \ref TopicAliasing "aliasing issue". In "debug mode", i.e., when \ref TopicAssertions "assertions" have not been disabled, such common pitfalls are automatically detected. - -For \em in-place transposition, as for instance in a = a.transpose(), simply use the \link DenseBase::transposeInPlace() transposeInPlace()\endlink function: - - - -
Example:Output:
-\include tut_arithmetic_transpose_inplace.cpp - -\verbinclude tut_arithmetic_transpose_inplace.out -
-There is also the \link MatrixBase::adjointInPlace() adjointInPlace()\endlink function for complex matrices. - -\section TutorialArithmeticMatrixMul Matrix-matrix and matrix-vector multiplication - -Matrix-matrix multiplication is again done with \c operator*. Since vectors are a special -case of matrices, they are implicitly handled there too, so matrix-vector product is really just a special -case of matrix-matrix product, and so is vector-vector outer product. Thus, all these cases are handled by just -two operators: -\li binary operator * as in \c a*b -\li compound operator *= as in \c a*=b (this multiplies on the right: \c a*=b is equivalent to a = a*b) - - - - -
Example:Output:
-\include tut_arithmetic_matrix_mul.cpp - -\verbinclude tut_arithmetic_matrix_mul.out -
- -Note: if you read the above paragraph on expression templates and are worried that doing \c m=m*m might cause -aliasing issues, be reassured for now: Eigen treats matrix multiplication as a special case and takes care of -introducing a temporary here, so it will compile \c m=m*m as: -\code -tmp = m*m; -m = tmp; -\endcode -If you know your matrix product can be safely evaluated into the destination matrix without aliasing issue, then you can use the \link MatrixBase::noalias() noalias()\endlink function to avoid the temporary, e.g.: -\code -c.noalias() += a * b; -\endcode -For more details on this topic, see the page on \ref TopicAliasing "aliasing". - -\b Note: for BLAS users worried about performance, expressions such as c.noalias() -= 2 * a.adjoint() * b; are fully optimized and trigger a single gemm-like function call. - -\section TutorialArithmeticDotAndCross Dot product and cross product - -For dot product and cross product, you need the \link MatrixBase::dot() dot()\endlink and \link MatrixBase::cross() cross()\endlink methods. Of course, the dot product can also be obtained as a 1x1 matrix as u.adjoint()*v. - - - -
Example:Output:
-\include tut_arithmetic_dot_cross.cpp - -\verbinclude tut_arithmetic_dot_cross.out -
- -Remember that cross product is only for vectors of size 3. Dot product is for vectors of any sizes. -When using complex numbers, Eigen's dot product is conjugate-linear in the first variable and linear in the -second variable. - -\section TutorialArithmeticRedux Basic arithmetic reduction operations -Eigen also provides some reduction operations to reduce a given matrix or vector to a single value such as the sum (computed by \link DenseBase::sum() sum()\endlink), product (\link DenseBase::prod() prod()\endlink), or the maximum (\link DenseBase::maxCoeff() maxCoeff()\endlink) and minimum (\link DenseBase::minCoeff() minCoeff()\endlink) of all its coefficients. - - - - -
Example:Output:
-\include tut_arithmetic_redux_basic.cpp - -\verbinclude tut_arithmetic_redux_basic.out -
- -The \em trace of a matrix, as returned by the function \link MatrixBase::trace() trace()\endlink, is the sum of the diagonal coefficients and can also be computed as efficiently using a.diagonal().sum(), as we will see later on. - -There also exist variants of the \c minCoeff and \c maxCoeff functions returning the coordinates of the respective coefficient via the arguments: - - - - -
Example:Output:
-\include tut_arithmetic_redux_minmax.cpp - -\verbinclude tut_arithmetic_redux_minmax.out -
- - -\section TutorialArithmeticValidity Validity of operations -Eigen checks the validity of the operations that you perform. When possible, -it checks them at compile time, producing compilation errors. These error messages can be long and ugly, -but Eigen writes the important message in UPPERCASE_LETTERS_SO_IT_STANDS_OUT. For example: -\code - Matrix3f m; - Vector4f v; - v = m*v; // Compile-time error: YOU_MIXED_MATRICES_OF_DIFFERENT_SIZES -\endcode - -Of course, in many cases, for example when checking dynamic sizes, the check cannot be performed at compile time. -Eigen then uses runtime assertions. This means that the program will abort with an error message when executing an illegal operation if it is run in "debug mode", and it will probably crash if assertions are turned off. - -\code - MatrixXf m(3,3); - VectorXf v(4); - v = m * v; // Run-time assertion failure here: "invalid matrix product" -\endcode - -For more details on this topic, see \ref TopicAssertions "this page". - -*/ - -} diff --git a/doc/C03_TutorialArrayClass.dox b/doc/C03_TutorialArrayClass.dox deleted file mode 100644 index 6432684aa..000000000 --- a/doc/C03_TutorialArrayClass.dox +++ /dev/null @@ -1,192 +0,0 @@ -namespace Eigen { - -/** \eigenManualPage TutorialArrayClass The Array class and coefficient-wise operations - -This page aims to provide an overview and explanations on how to use -Eigen's Array class. - -\eigenAutoToc - -\section TutorialArrayClassIntro What is the Array class? - -The Array class provides general-purpose arrays, as opposed to the Matrix class which -is intended for linear algebra. Furthermore, the Array class provides an easy way to -perform coefficient-wise operations, which might not have a linear algebraic meaning, -such as adding a constant to every coefficient in the array or multiplying two arrays coefficient-wise. - - -\section TutorialArrayClassTypes Array types -Array is a class template taking the same template parameters as Matrix. -As with Matrix, the first three template parameters are mandatory: -\code -Array -\endcode -The last three template parameters are optional. Since this is exactly the same as for Matrix, -we won't explain it again here and just refer to \ref TutorialMatrixClass. - -Eigen also provides typedefs for some common cases, in a way that is similar to the Matrix typedefs -but with some slight differences, as the word "array" is used for both 1-dimensional and 2-dimensional arrays. -We adopt the convention that typedefs of the form ArrayNt stand for 1-dimensional arrays, where N and t are -the size and the scalar type, as in the Matrix typedefs explained on \ref TutorialMatrixClass "this page". For 2-dimensional arrays, we -use typedefs of the form ArrayNNt. Some examples are shown in the following table: - - - - - - - - - - - - - - - - - - - - - - -
Type Typedef
\code Array \endcode \code ArrayXf \endcode
\code Array \endcode \code Array3f \endcode
\code Array \endcode \code ArrayXXd \endcode
\code Array \endcode \code Array33d \endcode
- - -\section TutorialArrayClassAccess Accessing values inside an Array - -The parenthesis operator is overloaded to provide write and read access to the coefficients of an array, just as with matrices. -Furthermore, the \c << operator can be used to initialize arrays (via the comma initializer) or to print them. - - - - -
Example:Output:
-\include Tutorial_ArrayClass_accessors.cpp - -\verbinclude Tutorial_ArrayClass_accessors.out -
- -For more information about the comma initializer, see \ref TutorialAdvancedInitialization. - - -\section TutorialArrayClassAddSub Addition and subtraction - -Adding and subtracting two arrays is the same as for matrices. -The operation is valid if both arrays have the same size, and the addition or subtraction is done coefficient-wise. - -Arrays also support expressions of the form array + scalar which add a scalar to each coefficient in the array. -This provides a functionality that is not directly available for Matrix objects. - - - - -
Example:Output:
-\include Tutorial_ArrayClass_addition.cpp - -\verbinclude Tutorial_ArrayClass_addition.out -
- - -\section TutorialArrayClassMult Array multiplication - -First of all, of course you can multiply an array by a scalar, this works in the same way as matrices. Where arrays -are fundamentally different from matrices, is when you multiply two together. Matrices interpret -multiplication as matrix product and arrays interpret multiplication as coefficient-wise product. Thus, two -arrays can be multiplied if and only if they have the same dimensions. - - - - -
Example:Output:
-\include Tutorial_ArrayClass_mult.cpp - -\verbinclude Tutorial_ArrayClass_mult.out -
- - -\section TutorialArrayClassCwiseOther Other coefficient-wise operations - -The Array class defines other coefficient-wise operations besides the addition, subtraction and multiplication -operators described above. For example, the \link ArrayBase::abs() .abs() \endlink method takes the absolute -value of each coefficient, while \link ArrayBase::sqrt() .sqrt() \endlink computes the square root of the -coefficients. If you have two arrays of the same size, you can call \link ArrayBase::min(const Eigen::ArrayBase&) const .min(.) \endlink to -construct the array whose coefficients are the minimum of the corresponding coefficients of the two given -arrays. These operations are illustrated in the following example. - - - - -
Example:Output:
-\include Tutorial_ArrayClass_cwise_other.cpp - -\verbinclude Tutorial_ArrayClass_cwise_other.out -
- -More coefficient-wise operations can be found in the \ref QuickRefPage. - - -\section TutorialArrayClassConvert Converting between array and matrix expressions - -When should you use objects of the Matrix class and when should you use objects of the Array class? You cannot -apply Matrix operations on arrays, or Array operations on matrices. Thus, if you need to do linear algebraic -operations such as matrix multiplication, then you should use matrices; if you need to do coefficient-wise -operations, then you should use arrays. However, sometimes it is not that simple, but you need to use both -Matrix and Array operations. In that case, you need to convert a matrix to an array or reversely. This gives -access to all operations regardless of the choice of declaring objects as arrays or as matrices. - -\link MatrixBase Matrix expressions \endlink have an \link MatrixBase::array() .array() \endlink method that -'converts' them into \link ArrayBase array expressions\endlink, so that coefficient-wise operations -can be applied easily. Conversely, \link ArrayBase array expressions \endlink -have a \link ArrayBase::matrix() .matrix() \endlink method. As with all Eigen expression abstractions, -this doesn't have any runtime cost (provided that you let your compiler optimize). -Both \link MatrixBase::array() .array() \endlink and \link ArrayBase::matrix() .matrix() \endlink -can be used as rvalues and as lvalues. - -Mixing matrices and arrays in an expression is forbidden with Eigen. For instance, you cannot add a matrix and -array directly; the operands of a \c + operator should either both be matrices or both be arrays. However, -it is easy to convert from one to the other with \link MatrixBase::array() .array() \endlink and -\link ArrayBase::matrix() .matrix()\endlink. The exception to this rule is the assignment operator: it is -allowed to assign a matrix expression to an array variable, or to assign an array expression to a matrix -variable. - -The following example shows how to use array operations on a Matrix object by employing the -\link MatrixBase::array() .array() \endlink method. For example, the statement -result = m.array() * n.array() takes two matrices \c m and \c n, converts them both to an array, uses -* to multiply them coefficient-wise and assigns the result to the matrix variable \c result (this is legal -because Eigen allows assigning array expressions to matrix variables). - -As a matter of fact, this usage case is so common that Eigen provides a \link MatrixBase::cwiseProduct() const -.cwiseProduct(.) \endlink method for matrices to compute the coefficient-wise product. This is also shown in -the example program. - - - - -
Example:Output:
-\include Tutorial_ArrayClass_interop_matrix.cpp - -\verbinclude Tutorial_ArrayClass_interop_matrix.out -
- -Similarly, if \c array1 and \c array2 are arrays, then the expression array1.matrix() * array2.matrix() -computes their matrix product. - -Here is a more advanced example. The expression (m.array() + 4).matrix() * m adds 4 to every -coefficient in the matrix \c m and then computes the matrix product of the result with \c m. Similarly, the -expression (m.array() * n.array()).matrix() * m computes the coefficient-wise product of the matrices -\c m and \c n and then the matrix product of the result with \c m. - - - - -
Example:Output:
-\include Tutorial_ArrayClass_interop.cpp - -\verbinclude Tutorial_ArrayClass_interop.out -
- -*/ - -} diff --git a/doc/C04_TutorialBlockOperations.dox b/doc/C04_TutorialBlockOperations.dox deleted file mode 100644 index a2d8c97cc..000000000 --- a/doc/C04_TutorialBlockOperations.dox +++ /dev/null @@ -1,228 +0,0 @@ -namespace Eigen { - -/** \eigenManualPage TutorialBlockOperations Block operations - -This page explains the essentials of block operations. -A block is a rectangular part of a matrix or array. Blocks expressions can be used both -as rvalues and as lvalues. As usual with Eigen expressions, this abstraction has zero runtime cost -provided that you let your compiler optimize. - -\eigenAutoToc - -\section TutorialBlockOperationsUsing Using block operations - -The most general block operation in Eigen is called \link DenseBase::block() .block() \endlink. -There are two versions, whose syntax is as follows: - - - - - - - - -
\b %Block \b operation -Version constructing a \n dynamic-size block expressionVersion constructing a \n fixed-size block expression
%Block of size (p,q), starting at (i,j)\code -matrix.block(i,j,p,q);\endcode \code -matrix.block(i,j);\endcode
- -As always in Eigen, indices start at 0. - -Both versions can be used on fixed-size and dynamic-size matrices and arrays. -These two expressions are semantically equivalent. -The only difference is that the fixed-size version will typically give you faster code if the block size is small, -but requires this size to be known at compile time. - -The following program uses the dynamic-size and fixed-size versions to print the values of several blocks inside a -matrix. - - - - -
Example:Output:
-\include Tutorial_BlockOperations_print_block.cpp - -\verbinclude Tutorial_BlockOperations_print_block.out -
- -In the above example the \link DenseBase::block() .block() \endlink function was employed as a \em rvalue, i.e. -it was only read from. However, blocks can also be used as \em lvalues, meaning that you can assign to a block. - -This is illustrated in the following example. This example also demonstrates blocks in arrays, which works exactly like the above-demonstrated blocks in matrices. - - - - -
Example:Output:
-\include Tutorial_BlockOperations_block_assignment.cpp - -\verbinclude Tutorial_BlockOperations_block_assignment.out -
- -While the \link DenseBase::block() .block() \endlink method can be used for any block operation, there are -other methods for special cases, providing more specialized API and/or better performance. On the topic of performance, all what -matters is that you give Eigen as much information as possible at compile time. For example, if your block is a single whole column in a matrix, -using the specialized \link DenseBase::col() .col() \endlink function described below lets Eigen know that, which can give it optimization opportunities. - -The rest of this page describes these specialized methods. - -\section TutorialBlockOperationsSyntaxColumnRows Columns and rows - -Individual columns and rows are special cases of blocks. Eigen provides methods to easily address them: -\link DenseBase::col() .col() \endlink and \link DenseBase::row() .row()\endlink. - - - - - - - - - - -
%Block operationMethod
ith row - \link DenseBase::row() * \endlink\code -matrix.row(i);\endcode
jth column - \link DenseBase::col() * \endlink\code -matrix.col(j);\endcode
- -The argument for \p col() and \p row() is the index of the column or row to be accessed. As always in Eigen, indices start at 0. - - - - -
Example:Output:
-\include Tutorial_BlockOperations_colrow.cpp - -\verbinclude Tutorial_BlockOperations_colrow.out -
- -That example also demonstrates that block expressions (here columns) can be used in arithmetic like any other expression. - - -\section TutorialBlockOperationsSyntaxCorners Corner-related operations - -Eigen also provides special methods for blocks that are flushed against one of the corners or sides of a -matrix or array. For instance, \link DenseBase::topLeftCorner() .topLeftCorner() \endlink can be used to refer -to a block in the top-left corner of a matrix. - -The different possibilities are summarized in the following table: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
%Block \b operation -Version constructing a \n dynamic-size block expressionVersion constructing a \n fixed-size block expression
Top-left p by q block \link DenseBase::topLeftCorner() * \endlink\code -matrix.topLeftCorner(p,q);\endcode \code -matrix.topLeftCorner();\endcode
Bottom-left p by q block - \link DenseBase::bottomLeftCorner() * \endlink\code -matrix.bottomLeftCorner(p,q);\endcode \code -matrix.bottomLeftCorner();\endcode
Top-right p by q block - \link DenseBase::topRightCorner() * \endlink\code -matrix.topRightCorner(p,q);\endcode \code -matrix.topRightCorner();\endcode
Bottom-right p by q block - \link DenseBase::bottomRightCorner() * \endlink\code -matrix.bottomRightCorner(p,q);\endcode \code -matrix.bottomRightCorner();\endcode
%Block containing the first q rows - \link DenseBase::topRows() * \endlink\code -matrix.topRows(q);\endcode \code -matrix.topRows();\endcode
%Block containing the last q rows - \link DenseBase::bottomRows() * \endlink\code -matrix.bottomRows(q);\endcode \code -matrix.bottomRows();\endcode
%Block containing the first p columns - \link DenseBase::leftCols() * \endlink\code -matrix.leftCols(p);\endcode \code -matrix.leftCols

();\endcode

%Block containing the last q columns - \link DenseBase::rightCols() * \endlink\code -matrix.rightCols(q);\endcode \code -matrix.rightCols();\endcode
- -Here is a simple example illustrating the use of the operations presented above: - - - - -
Example:Output:
-\include Tutorial_BlockOperations_corner.cpp - -\verbinclude Tutorial_BlockOperations_corner.out -
- - -\section TutorialBlockOperationsSyntaxVectors Block operations for vectors - -Eigen also provides a set of block operations designed specifically for the special case of vectors and one-dimensional arrays: - - - - - - - - - - - - - - - - - -
%Block operationVersion constructing a \n dynamic-size block expressionVersion constructing a \n fixed-size block expression
%Block containing the first \p n elements - \link DenseBase::head() * \endlink\code -vector.head(n);\endcode \code -vector.head();\endcode
%Block containing the last \p n elements - \link DenseBase::tail() * \endlink\code -vector.tail(n);\endcode \code -vector.tail();\endcode
%Block containing \p n elements, starting at position \p i - \link DenseBase::segment() * \endlink\code -vector.segment(i,n);\endcode \code -vector.segment(i);\endcode
- - -An example is presented below: - - - -
Example:Output:
-\include Tutorial_BlockOperations_vector.cpp - -\verbinclude Tutorial_BlockOperations_vector.out -
- -*/ - -} diff --git a/doc/C05_TutorialAdvancedInitialization.dox b/doc/C05_TutorialAdvancedInitialization.dox deleted file mode 100644 index 50374d0d0..000000000 --- a/doc/C05_TutorialAdvancedInitialization.dox +++ /dev/null @@ -1,162 +0,0 @@ -namespace Eigen { - -/** \eigenManualPage TutorialAdvancedInitialization Advanced initialization - -This page discusses several advanced methods for initializing matrices. It gives more details on the -comma-initializer, which was introduced before. It also explains how to get special matrices such as the -identity matrix and the zero matrix. - -\eigenAutoToc - -\section TutorialAdvancedInitializationCommaInitializer The comma initializer - -Eigen offers a comma initializer syntax which allows the user to easily set all the coefficients of a matrix, -vector or array. Simply list the coefficients, starting at the top-left corner and moving from left to right -and from the top to the bottom. The size of the object needs to be specified beforehand. If you list too few -or too many coefficients, Eigen will complain. - - - - -
Example:Output:
-\include Tutorial_commainit_01.cpp - -\verbinclude Tutorial_commainit_01.out -
- -Moreover, the elements of the initialization list may themselves be vectors or matrices. A common use is -to join vectors or matrices together. For example, here is how to join two row vectors together. Remember -that you have to set the size before you can use the comma initializer. - - - - -
Example:Output:
-\include Tutorial_AdvancedInitialization_Join.cpp - -\verbinclude Tutorial_AdvancedInitialization_Join.out -
- -We can use the same technique to initialize matrices with a block structure. - - - - -
Example:Output:
-\include Tutorial_AdvancedInitialization_Block.cpp - -\verbinclude Tutorial_AdvancedInitialization_Block.out -
- -The comma initializer can also be used to fill block expressions such as m.row(i). Here is a more -complicated way to get the same result as in the first example above: - - - - -
Example:Output:
-\include Tutorial_commainit_01b.cpp - -\verbinclude Tutorial_commainit_01b.out -
- - -\section TutorialAdvancedInitializationSpecialMatrices Special matrices and arrays - -The Matrix and Array classes have static methods like \link DenseBase::Zero() Zero()\endlink, which can be -used to initialize all coefficients to zero. There are three variants. The first variant takes no arguments -and can only be used for fixed-size objects. If you want to initialize a dynamic-size object to zero, you need -to specify the size. Thus, the second variant requires one argument and can be used for one-dimensional -dynamic-size objects, while the third variant requires two arguments and can be used for two-dimensional -objects. All three variants are illustrated in the following example: - - - - -
Example:Output:
-\include Tutorial_AdvancedInitialization_Zero.cpp - -\verbinclude Tutorial_AdvancedInitialization_Zero.out -
- -Similarly, the static method \link DenseBase::Constant() Constant\endlink(value) sets all coefficients to \c value. -If the size of the object needs to be specified, the additional arguments go before the \c value -argument, as in MatrixXd::Constant(rows, cols, value). The method \link DenseBase::Random() Random() -\endlink fills the matrix or array with random coefficients. The identity matrix can be obtained by calling -\link MatrixBase::Identity() Identity()\endlink; this method is only available for Matrix, not for Array, -because "identity matrix" is a linear algebra concept. The method -\link DenseBase::LinSpaced LinSpaced\endlink(size, low, high) is only available for vectors and -one-dimensional arrays; it yields a vector of the specified size whose coefficients are equally spaced between -\c low and \c high. The method \c LinSpaced() is illustrated in the following example, which prints a table -with angles in degrees, the corresponding angle in radians, and their sine and cosine. - - - - -
Example:Output:
-\include Tutorial_AdvancedInitialization_LinSpaced.cpp - -\verbinclude Tutorial_AdvancedInitialization_LinSpaced.out -
- -This example shows that objects like the ones returned by LinSpaced() can be assigned to variables (and -expressions). Eigen defines utility functions like \link DenseBase::setZero() setZero()\endlink, -\link MatrixBase::setIdentity() \endlink and \link DenseBase::setLinSpaced() \endlink to do this -conveniently. The following example contrasts three ways to construct the matrix -\f$ J = \bigl[ \begin{smallmatrix} O & I \\ I & O \end{smallmatrix} \bigr] \f$: using static methods and -assignment, using static methods and the comma-initializer, or using the setXxx() methods. - - - - -
Example:Output:
-\include Tutorial_AdvancedInitialization_ThreeWays.cpp - -\verbinclude Tutorial_AdvancedInitialization_ThreeWays.out -
- -A summary of all pre-defined matrix, vector and array objects can be found in the \ref QuickRefPage. - - -\section TutorialAdvancedInitializationTemporaryObjects Usage as temporary objects - -As shown above, static methods as Zero() and Constant() can be used to initialize variables at the time of -declaration or at the right-hand side of an assignment operator. You can think of these methods as returning a -matrix or array; in fact, they return so-called \ref TopicEigenExpressionTemplates "expression objects" which -evaluate to a matrix or array when needed, so that this syntax does not incur any overhead. - -These expressions can also be used as a temporary object. The second example in -the \ref GettingStarted guide, which we reproduce here, already illustrates this. - - - - -
Example:Output:
-\include QuickStart_example2_dynamic.cpp - -\verbinclude QuickStart_example2_dynamic.out -
- -The expression m + MatrixXf::Constant(3,3,1.2) constructs the 3-by-3 matrix expression with all its coefficients -equal to 1.2 plus the corresponding coefficient of \a m. - -The comma-initializer, too, can also be used to construct temporary objects. The following example constructs a random -matrix of size 2-by-3, and then multiplies this matrix on the left with -\f$ \bigl[ \begin{smallmatrix} 0 & 1 \\ 1 & 0 \end{smallmatrix} \bigr] \f$. - - - - -
Example:Output:
-\include Tutorial_AdvancedInitialization_CommaTemporary.cpp - -\verbinclude Tutorial_AdvancedInitialization_CommaTemporary.out -
- -The \link CommaInitializer::finished() finished() \endlink method is necessary here to get the actual matrix -object once the comma initialization of our temporary submatrix is done. - - -*/ - -} diff --git a/doc/C06_TutorialLinearAlgebra.dox b/doc/C06_TutorialLinearAlgebra.dox deleted file mode 100644 index b09f3543e..000000000 --- a/doc/C06_TutorialLinearAlgebra.dox +++ /dev/null @@ -1,255 +0,0 @@ -namespace Eigen { - -/** \eigenManualPage TutorialLinearAlgebra Linear algebra and decompositions - -This page explains how to solve linear systems, compute various decompositions such as LU, -QR, %SVD, eigendecompositions... After reading this page, don't miss our -\link TopicLinearAlgebraDecompositions catalogue \endlink of dense matrix decompositions. - -\eigenAutoToc - -\section TutorialLinAlgBasicSolve Basic linear solving - -\b The \b problem: You have a system of equations, that you have written as a single matrix equation - \f[ Ax \: = \: b \f] -Where \a A and \a b are matrices (\a b could be a vector, as a special case). You want to find a solution \a x. - -\b The \b solution: You can choose between various decompositions, depending on what your matrix \a A looks like, -and depending on whether you favor speed or accuracy. However, let's start with an example that works in all cases, -and is a good compromise: - - - - - - -
Example:Output:
\include TutorialLinAlgExSolveColPivHouseholderQR.cpp \verbinclude TutorialLinAlgExSolveColPivHouseholderQR.out
- -In this example, the colPivHouseholderQr() method returns an object of class ColPivHouseholderQR. Since here the -matrix is of type Matrix3f, this line could have been replaced by: -\code -ColPivHouseholderQR dec(A); -Vector3f x = dec.solve(b); -\endcode - -Here, ColPivHouseholderQR is a QR decomposition with column pivoting. It's a good compromise for this tutorial, as it -works for all matrices while being quite fast. Here is a table of some other decompositions that you can choose from, -depending on your matrix and the trade-off you want to make: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
DecompositionMethodRequirements on the matrixSpeedAccuracy
PartialPivLUpartialPivLu()Invertible+++
FullPivLUfullPivLu()None-+++
HouseholderQRhouseholderQr()None+++
ColPivHouseholderQRcolPivHouseholderQr()None+++
FullPivHouseholderQRfullPivHouseholderQr()None-+++
LLTllt()Positive definite++++
LDLTldlt()Positive or negative semidefinite+++++
- -All of these decompositions offer a solve() method that works as in the above example. - -For example, if your matrix is positive definite, the above table says that a very good -choice is then the LDLT decomposition. Here's an example, also demonstrating that using a general -matrix (not a vector) as right hand side is possible. - - - - - - - -
Example:Output:
\include TutorialLinAlgExSolveLDLT.cpp \verbinclude TutorialLinAlgExSolveLDLT.out
- -For a \ref TopicLinearAlgebraDecompositions "much more complete table" comparing all decompositions supported by Eigen (notice that Eigen -supports many other decompositions), see our special page on -\ref TopicLinearAlgebraDecompositions "this topic". - -\section TutorialLinAlgSolutionExists Checking if a solution really exists - -Only you know what error margin you want to allow for a solution to be considered valid. -So Eigen lets you do this computation for yourself, if you want to, as in this example: - - - - - - - -
Example:Output:
\include TutorialLinAlgExComputeSolveError.cpp \verbinclude TutorialLinAlgExComputeSolveError.out
- -\section TutorialLinAlgEigensolving Computing eigenvalues and eigenvectors - -You need an eigendecomposition here, see available such decompositions on \ref TopicLinearAlgebraDecompositions "this page". -Make sure to check if your matrix is self-adjoint, as is often the case in these problems. Here's an example using -SelfAdjointEigenSolver, it could easily be adapted to general matrices using EigenSolver or ComplexEigenSolver. - -The computation of eigenvalues and eigenvectors does not necessarily converge, but such failure to converge is -very rare. The call to info() is to check for this possibility. - - - - - - - -
Example:Output:
\include TutorialLinAlgSelfAdjointEigenSolver.cpp \verbinclude TutorialLinAlgSelfAdjointEigenSolver.out
- -\section TutorialLinAlgInverse Computing inverse and determinant - -First of all, make sure that you really want this. While inverse and determinant are fundamental mathematical concepts, -in \em numerical linear algebra they are not as popular as in pure mathematics. Inverse computations are often -advantageously replaced by solve() operations, and the determinant is often \em not a good way of checking if a matrix -is invertible. - -However, for \em very \em small matrices, the above is not true, and inverse and determinant can be very useful. - -While certain decompositions, such as PartialPivLU and FullPivLU, offer inverse() and determinant() methods, you can also -call inverse() and determinant() directly on a matrix. If your matrix is of a very small fixed size (at most 4x4) this -allows Eigen to avoid performing a LU decomposition, and instead use formulas that are more efficient on such small matrices. - -Here is an example: - - - - - - -
Example:Output:
\include TutorialLinAlgInverseDeterminant.cpp \verbinclude TutorialLinAlgInverseDeterminant.out
- -\section TutorialLinAlgLeastsquares Least squares solving - -The best way to do least squares solving is with a SVD decomposition. Eigen provides one as the JacobiSVD class, and its solve() -is doing least-squares solving. - -Here is an example: - - - - - - -
Example:Output:
\include TutorialLinAlgSVDSolve.cpp \verbinclude TutorialLinAlgSVDSolve.out
- -Another way, potentially faster but less reliable, is to use a LDLT decomposition -of the normal matrix. In any case, just read any reference text on least squares, and it will be very easy for you -to implement any linear least squares computation on top of Eigen. - -\section TutorialLinAlgSeparateComputation Separating the computation from the construction - -In the above examples, the decomposition was computed at the same time that the decomposition object was constructed. -There are however situations where you might want to separate these two things, for example if you don't know, -at the time of the construction, the matrix that you will want to decompose; or if you want to reuse an existing -decomposition object. - -What makes this possible is that: -\li all decompositions have a default constructor, -\li all decompositions have a compute(matrix) method that does the computation, and that may be called again - on an already-computed decomposition, reinitializing it. - -For example: - - - - - - - -
Example:Output:
\include TutorialLinAlgComputeTwice.cpp \verbinclude TutorialLinAlgComputeTwice.out
- -Finally, you can tell the decomposition constructor to preallocate storage for decomposing matrices of a given size, -so that when you subsequently decompose such matrices, no dynamic memory allocation is performed (of course, if you -are using fixed-size matrices, no dynamic memory allocation happens at all). This is done by just -passing the size to the decomposition constructor, as in this example: -\code -HouseholderQR qr(50,50); -MatrixXf A = MatrixXf::Random(50,50); -qr.compute(A); // no dynamic memory allocation -\endcode - -\section TutorialLinAlgRankRevealing Rank-revealing decompositions - -Certain decompositions are rank-revealing, i.e. are able to compute the rank of a matrix. These are typically -also the decompositions that behave best in the face of a non-full-rank matrix (which in the square case means a -singular matrix). On \ref TopicLinearAlgebraDecompositions "this table" you can see for all our decompositions -whether they are rank-revealing or not. - -Rank-revealing decompositions offer at least a rank() method. They can also offer convenience methods such as isInvertible(), -and some are also providing methods to compute the kernel (null-space) and image (column-space) of the matrix, as is the -case with FullPivLU: - - - - - - - -
Example:Output:
\include TutorialLinAlgRankRevealing.cpp \verbinclude TutorialLinAlgRankRevealing.out
- -Of course, any rank computation depends on the choice of an arbitrary threshold, since practically no -floating-point matrix is \em exactly rank-deficient. Eigen picks a sensible default threshold, which depends -on the decomposition but is typically the diagonal size times machine epsilon. While this is the best default we -could pick, only you know what is the right threshold for your application. You can set this by calling setThreshold() -on your decomposition object before calling rank() or any other method that needs to use such a threshold. -The decomposition itself, i.e. the compute() method, is independent of the threshold. You don't need to recompute the -decomposition after you've changed the threshold. - - - - - - - -
Example:Output:
\include TutorialLinAlgSetThreshold.cpp \verbinclude TutorialLinAlgSetThreshold.out
- -*/ - -} diff --git a/doc/C07_TutorialReductionsVisitorsBroadcasting.dox b/doc/C07_TutorialReductionsVisitorsBroadcasting.dox deleted file mode 100644 index 992cf6f34..000000000 --- a/doc/C07_TutorialReductionsVisitorsBroadcasting.dox +++ /dev/null @@ -1,257 +0,0 @@ -namespace Eigen { - -/** \eigenManualPage TutorialReductionsVisitorsBroadcasting Reductions, visitors and broadcasting - -This page explains Eigen's reductions, visitors and broadcasting and how they are used with -\link MatrixBase matrices \endlink and \link ArrayBase arrays \endlink. - -\eigenAutoToc - -\section TutorialReductionsVisitorsBroadcastingReductions Reductions -In Eigen, a reduction is a function taking a matrix or array, and returning a single -scalar value. One of the most used reductions is \link DenseBase::sum() .sum() \endlink, -returning the sum of all the coefficients inside a given matrix or array. - - - - -
Example:Output:
-\include tut_arithmetic_redux_basic.cpp - -\verbinclude tut_arithmetic_redux_basic.out -
- -The \em trace of a matrix, as returned by the function \c trace(), is the sum of the diagonal coefficients and can equivalently be computed a.diagonal().sum(). - - -\subsection TutorialReductionsVisitorsBroadcastingReductionsNorm Norm computations - -The (Euclidean a.k.a. \f$\ell^2\f$) squared norm of a vector can be obtained \link MatrixBase::squaredNorm() squaredNorm() \endlink. It is equal to the dot product of the vector by itself, and equivalently to the sum of squared absolute values of its coefficients. - -Eigen also provides the \link MatrixBase::norm() norm() \endlink method, which returns the square root of \link MatrixBase::squaredNorm() squaredNorm() \endlink. - -These operations can also operate on matrices; in that case, a n-by-p matrix is seen as a vector of size (n*p), so for example the \link MatrixBase::norm() norm() \endlink method returns the "Frobenius" or "Hilbert-Schmidt" norm. We refrain from speaking of the \f$\ell^2\f$ norm of a matrix because that can mean different things. - -If you want other \f$\ell^p\f$ norms, use the \link MatrixBase::lpNorm() lpNnorm

() \endlink method. The template parameter \a p can take the special value \a Infinity if you want the \f$\ell^\infty\f$ norm, which is the maximum of the absolute values of the coefficients. - -The following example demonstrates these methods. - - - - -
Example:Output:
-\include Tutorial_ReductionsVisitorsBroadcasting_reductions_norm.cpp - -\verbinclude Tutorial_ReductionsVisitorsBroadcasting_reductions_norm.out -
- -\subsection TutorialReductionsVisitorsBroadcastingReductionsBool Boolean reductions - -The following reductions operate on boolean values: - - \link DenseBase::all() all() \endlink returns \b true if all of the coefficients in a given Matrix or Array evaluate to \b true . - - \link DenseBase::any() any() \endlink returns \b true if at least one of the coefficients in a given Matrix or Array evaluates to \b true . - - \link DenseBase::count() count() \endlink returns the number of coefficients in a given Matrix or Array that evaluate to \b true. - -These are typically used in conjunction with the coefficient-wise comparison and equality operators provided by Array. For instance, array > 0 is an %Array of the same size as \c array , with \b true at those positions where the corresponding coefficient of \c array is positive. Thus, (array > 0).all() tests whether all coefficients of \c array are positive. This can be seen in the following example: - - - - -
Example:Output:
-\include Tutorial_ReductionsVisitorsBroadcasting_reductions_bool.cpp - -\verbinclude Tutorial_ReductionsVisitorsBroadcasting_reductions_bool.out -
- -\subsection TutorialReductionsVisitorsBroadcastingReductionsUserdefined User defined reductions - -TODO - -In the meantime you can have a look at the DenseBase::redux() function. - -\section TutorialReductionsVisitorsBroadcastingVisitors Visitors -Visitors are useful when one wants to obtain the location of a coefficient inside -a Matrix or Array. The simplest examples are -\link MatrixBase::maxCoeff() maxCoeff(&x,&y) \endlink and -\link MatrixBase::minCoeff() minCoeff(&x,&y)\endlink, which can be used to find -the location of the greatest or smallest coefficient in a Matrix or -Array. - -The arguments passed to a visitor are pointers to the variables where the -row and column position are to be stored. These variables should be of type -\link DenseBase::Index Index \endlink, as shown below: - - - - -
Example:Output:
-\include Tutorial_ReductionsVisitorsBroadcasting_visitors.cpp - -\verbinclude Tutorial_ReductionsVisitorsBroadcasting_visitors.out -
- -Note that both functions also return the value of the minimum or maximum coefficient if needed, -as if it was a typical reduction operation. - -\section TutorialReductionsVisitorsBroadcastingPartialReductions Partial reductions -Partial reductions are reductions that can operate column- or row-wise on a Matrix or -Array, applying the reduction operation on each column or row and -returning a column or row-vector with the corresponding values. Partial reductions are applied -with \link DenseBase::colwise() colwise() \endlink or \link DenseBase::rowwise() rowwise() \endlink. - -A simple example is obtaining the maximum of the elements -in each column in a given matrix, storing the result in a row-vector: - - - - -
Example:Output:
-\include Tutorial_ReductionsVisitorsBroadcasting_colwise.cpp - -\verbinclude Tutorial_ReductionsVisitorsBroadcasting_colwise.out -
- -The same operation can be performed row-wise: - - - - -
Example:Output:
-\include Tutorial_ReductionsVisitorsBroadcasting_rowwise.cpp - -\verbinclude Tutorial_ReductionsVisitorsBroadcasting_rowwise.out -
- -Note that column-wise operations return a 'row-vector' while row-wise operations -return a 'column-vector' - -\subsection TutorialReductionsVisitorsBroadcastingPartialReductionsCombined Combining partial reductions with other operations -It is also possible to use the result of a partial reduction to do further processing. -Here is another example that finds the column whose sum of elements is the maximum - within a matrix. With column-wise partial reductions this can be coded as: - - - - -
Example:Output:
-\include Tutorial_ReductionsVisitorsBroadcasting_maxnorm.cpp - -\verbinclude Tutorial_ReductionsVisitorsBroadcasting_maxnorm.out -
- -The previous example applies the \link DenseBase::sum() sum() \endlink reduction on each column -though the \link DenseBase::colwise() colwise() \endlink visitor, obtaining a new matrix whose -size is 1x4. - -Therefore, if -\f[ -\mbox{m} = \begin{bmatrix} 1 & 2 & 6 & 9 \\ - 3 & 1 & 7 & 2 \end{bmatrix} -\f] - -then - -\f[ -\mbox{m.colwise().sum()} = \begin{bmatrix} 4 & 3 & 13 & 11 \end{bmatrix} -\f] - -The \link DenseBase::maxCoeff() maxCoeff() \endlink reduction is finally applied -to obtain the column index where the maximum sum is found, -which is the column index 2 (third column) in this case. - - -\section TutorialReductionsVisitorsBroadcastingBroadcasting Broadcasting -The concept behind broadcasting is similar to partial reductions, with the difference that broadcasting -constructs an expression where a vector (column or row) is interpreted as a matrix by replicating it in -one direction. - -A simple example is to add a certain column-vector to each column in a matrix. -This can be accomplished with: - - - - -
Example:Output:
-\include Tutorial_ReductionsVisitorsBroadcasting_broadcast_simple.cpp - -\verbinclude Tutorial_ReductionsVisitorsBroadcasting_broadcast_simple.out -
- -We can interpret the instruction mat.colwise() += v in two equivalent ways. It adds the vector \c v -to every column of the matrix. Alternatively, it can be interpreted as repeating the vector \c v four times to -form a four-by-two matrix which is then added to \c mat: -\f[ -\begin{bmatrix} 1 & 2 & 6 & 9 \\ 3 & 1 & 7 & 2 \end{bmatrix} -+ \begin{bmatrix} 0 & 0 & 0 & 0 \\ 1 & 1 & 1 & 1 \end{bmatrix} -= \begin{bmatrix} 1 & 2 & 6 & 9 \\ 4 & 2 & 8 & 3 \end{bmatrix}. -\f] -The operators -=, + and - can also be used column-wise and row-wise. On arrays, we -can also use the operators *=, /=, * and / to perform coefficient-wise -multiplication and division column-wise or row-wise. These operators are not available on matrices because it -is not clear what they would do. If you want multiply column 0 of a matrix \c mat with \c v(0), column 1 with -\c v(1), and so on, then use mat = mat * v.asDiagonal(). - -It is important to point out that the vector to be added column-wise or row-wise must be of type Vector, -and cannot be a Matrix. If this is not met then you will get compile-time error. This also means that -broadcasting operations can only be applied with an object of type Vector, when operating with Matrix. -The same applies for the Array class, where the equivalent for VectorXf is ArrayXf. As always, you should -not mix arrays and matrices in the same expression. - -To perform the same operation row-wise we can do: - - - - -
Example:Output:
-\include Tutorial_ReductionsVisitorsBroadcasting_broadcast_simple_rowwise.cpp - -\verbinclude Tutorial_ReductionsVisitorsBroadcasting_broadcast_simple_rowwise.out -
- -\subsection TutorialReductionsVisitorsBroadcastingBroadcastingCombined Combining broadcasting with other operations -Broadcasting can also be combined with other operations, such as Matrix or Array operations, -reductions and partial reductions. - -Now that broadcasting, reductions and partial reductions have been introduced, we can dive into a more advanced example that finds -the nearest neighbour of a vector v within the columns of matrix m. The Euclidean distance will be used in this example, -computing the squared Euclidean distance with the partial reduction named \link MatrixBase::squaredNorm() squaredNorm() \endlink: - - - - -
Example:Output:
-\include Tutorial_ReductionsVisitorsBroadcasting_broadcast_1nn.cpp - -\verbinclude Tutorial_ReductionsVisitorsBroadcasting_broadcast_1nn.out -
- -The line that does the job is -\code - (m.colwise() - v).colwise().squaredNorm().minCoeff(&index); -\endcode - -We will go step by step to understand what is happening: - - - m.colwise() - v is a broadcasting operation, subtracting v from each column in m. The result of this operation -is a new matrix whose size is the same as matrix m: \f[ - \mbox{m.colwise() - v} = - \begin{bmatrix} - -1 & 21 & 4 & 7 \\ - 0 & 8 & 4 & -1 - \end{bmatrix} -\f] - - - (m.colwise() - v).colwise().squaredNorm() is a partial reduction, computing the squared norm column-wise. The result of -this operation is a row-vector where each coefficient is the squared Euclidean distance between each column in m and v: \f[ - \mbox{(m.colwise() - v).colwise().squaredNorm()} = - \begin{bmatrix} - 1 & 505 & 32 & 50 - \end{bmatrix} -\f] - - - Finally, minCoeff(&index) is used to obtain the index of the column in m that is closest to v in terms of Euclidean -distance. - -*/ - -} diff --git a/doc/C08_TutorialGeometry.dox b/doc/C08_TutorialGeometry.dox deleted file mode 100644 index 81aeec978..000000000 --- a/doc/C08_TutorialGeometry.dox +++ /dev/null @@ -1,241 +0,0 @@ -namespace Eigen { - -/** \eigenManualPage TutorialGeometry Space transformations - -In this page, we will introduce the many possibilities offered by the \ref Geometry_Module "geometry module" to deal with 2D and 3D rotations and projective or affine transformations. - -\eigenAutoToc - -Eigen's Geometry module provides two different kinds of geometric transformations: - - Abstract transformations, such as rotations (represented by \ref AngleAxis "angle and axis" or by a \ref Quaternion "quaternion"), \ref Translation "translations", \ref Scaling "scalings". These transformations are NOT represented as matrices, but you can nevertheless mix them with matrices and vectors in expressions, and convert them to matrices if you wish. - - Projective or affine transformation matrices: see the Transform class. These are really matrices. - -\note If you are working with OpenGL 4x4 matrices then Affine3f and Affine3d are what you want. Since Eigen defaults to column-major storage, you can directly use the Transform::data() method to pass your transformation matrix to OpenGL. - -You can construct a Transform from an abstract transformation, like this: -\code - Transform t(AngleAxis(angle,axis)); -\endcode -or like this: -\code - Transform t; - t = AngleAxis(angle,axis); -\endcode -But note that unfortunately, because of how C++ works, you can \b not do this: -\code - Transform t = AngleAxis(angle,axis); -\endcode -\b Explanation: In the C++ language, this would require Transform to have a non-explicit conversion constructor from AngleAxis, but we really don't want to allow implicit casting here. - - -\section TutorialGeoElementaryTransformations Transformation types - - - - - - - - - - -
Transformation typeTypical initialization code
-\ref Rotation2D "2D rotation" from an angle\code -Rotation2D rot2(angle_in_radian);\endcode
-3D rotation as an \ref AngleAxis "angle + axis"\code -AngleAxis aa(angle_in_radian, Vector3f(ax,ay,az));\endcode -The axis vector must be normalized.
-3D rotation as a \ref Quaternion "quaternion"\code -Quaternion q; q = AngleAxis(angle_in_radian, axis);\endcode
-N-D Scaling\code -Scaling(sx, sy) -Scaling(sx, sy, sz) -Scaling(s) -Scaling(vecN)\endcode
-N-D Translation\code -Translation(tx, ty) -Translation(tx, ty, tz) -Translation(s) -Translation(vecN)\endcode
-N-D \ref TutorialGeoTransform "Affine transformation"\code -Transform t = concatenation_of_any_transformations; -Transform t = Translation3f(p) * AngleAxisf(a,axis) * Scaling(s);\endcode
-N-D Linear transformations \n -(pure rotations, \n scaling, etc.)\code -Matrix t = concatenation_of_rotations_and_scalings; -Matrix t = Rotation2Df(a) * Scaling(s); -Matrix t = AngleAxisf(a,axis) * Scaling(s);\endcode
- -Notes on rotations\n To transform more than a single vector the preferred -representations are rotation matrices, while for other usages Quaternion is the -representation of choice as they are compact, fast and stable. Finally Rotation2D and -AngleAxis are mainly convenient types to create other rotation objects. - -Notes on Translation and Scaling\n Like AngleAxis, these classes were -designed to simplify the creation/initialization of linear (Matrix) and affine (Transform) -transformations. Nevertheless, unlike AngleAxis which is inefficient to use, these classes -might still be interesting to write generic and efficient algorithms taking as input any -kind of transformations. - -Any of the above transformation types can be converted to any other types of the same nature, -or to a more generic type. Here are some additional examples: - - -
\code -Rotation2Df r; r = Matrix2f(..); // assumes a pure rotation matrix -AngleAxisf aa; aa = Quaternionf(..); -AngleAxisf aa; aa = Matrix3f(..); // assumes a pure rotation matrix -Matrix2f m; m = Rotation2Df(..); -Matrix3f m; m = Quaternionf(..); Matrix3f m; m = Scaling(..); -Affine3f m; m = AngleAxis3f(..); Affine3f m; m = Scaling(..); -Affine3f m; m = Translation3f(..); Affine3f m; m = Matrix3f(..); -\endcode
- - -top\section TutorialGeoCommontransformationAPI Common API across transformation types - -To some extent, Eigen's \ref Geometry_Module "geometry module" allows you to write -generic algorithms working on any kind of transformation representations: - - - - - -
-Concatenation of two transformations\code -gen1 * gen2;\endcode
Apply the transformation to a vector\code -vec2 = gen1 * vec1;\endcode
Get the inverse of the transformation\code -gen2 = gen1.inverse();\endcode
Spherical interpolation \n (Rotation2D and Quaternion only)\code -rot3 = rot1.slerp(alpha,rot2);\endcode
- - - -top\section TutorialGeoTransform Affine transformations -Generic affine transformations are represented by the Transform class which internaly -is a (Dim+1)^2 matrix. In Eigen we have chosen to not distinghish between points and -vectors such that all points are actually represented by displacement vectors from the -origin ( \f$ \mathbf{p} \equiv \mathbf{p}-0 \f$ ). With that in mind, real points and -vector distinguish when the transformation is applied. - - - - - - - -
-Apply the transformation to a \b point \code -VectorNf p1, p2; -p2 = t * p1;\endcode
-Apply the transformation to a \b vector \code -VectorNf vec1, vec2; -vec2 = t.linear() * vec1;\endcode
-Apply a \em general transformation \n to a \b normal \b vector -(explanations)\code -VectorNf n1, n2; -MatrixNf normalMatrix = t.linear().inverse().transpose(); -n2 = (normalMatrix * n1).normalized();\endcode
-Apply a transformation with \em pure \em rotation \n to a \b normal \b vector -(no scaling, no shear)\code -n2 = t.linear() * n1;\endcode
-OpenGL compatibility \b 3D \code -glLoadMatrixf(t.data());\endcode
-OpenGL compatibility \b 2D \code -Affine3f aux(Affine3f::Identity()); -aux.linear().topLeftCorner<2,2>() = t.linear(); -aux.translation().start<2>() = t.translation(); -glLoadMatrixf(aux.data());\endcode
- -\b Component \b accessors - - - - - - -
-full read-write access to the internal matrix\code -t.matrix() = matN1xN1; // N1 means N+1 -matN1xN1 = t.matrix(); -\endcode
-coefficient accessors\code -t(i,j) = scalar; <=> t.matrix()(i,j) = scalar; -scalar = t(i,j); <=> scalar = t.matrix()(i,j); -\endcode
-translation part\code -t.translation() = vecN; -vecN = t.translation(); -\endcode
-linear part\code -t.linear() = matNxN; -matNxN = t.linear(); -\endcode
-extract the rotation matrix\code -matNxN = t.rotation(); -\endcode
- - -\b Transformation \b creation \n -While transformation objects can be created and updated concatenating elementary transformations, -the Transform class also features a procedural API: - - - - - - -
procedural APIequivalent natural API
Translation\code -t.translate(Vector_(tx,ty,..)); -t.pretranslate(Vector_(tx,ty,..)); -\endcode\code -t *= Translation_(tx,ty,..); -t = Translation_(tx,ty,..) * t; -\endcode
\b Rotation \n In 2D and for the procedural API, any_rotation can also \n be an angle in radian\code -t.rotate(any_rotation); -t.prerotate(any_rotation); -\endcode\code -t *= any_rotation; -t = any_rotation * t; -\endcode
Scaling\code -t.scale(Vector_(sx,sy,..)); -t.scale(s); -t.prescale(Vector_(sx,sy,..)); -t.prescale(s); -\endcode\code -t *= Scaling(sx,sy,..); -t *= Scaling(s); -t = Scaling(sx,sy,..) * t; -t = Scaling(s) * t; -\endcode
Shear transformation \n ( \b 2D \b only ! )\code -t.shear(sx,sy); -t.preshear(sx,sy); -\endcode
- -Note that in both API, any many transformations can be concatenated in a single expression as shown in the two following equivalent examples: - - - -
\code -t.pretranslate(..).rotate(..).translate(..).scale(..); -\endcode
\code -t = Translation_(..) * t * RotationType(..) * Translation_(..) * Scaling(..); -\endcode
- - - -top\section TutorialGeoEulerAngles Euler angles - - -
-Euler angles might be convenient to create rotation objects. -On the other hand, since there exist 24 different conventions, they are pretty confusing to use. This example shows how -to create a rotation matrix according to the 2-1-2 convention.\code -Matrix3f m; -m = AngleAxisf(angle1, Vector3f::UnitZ()) -* * AngleAxisf(angle2, Vector3f::UnitY()) -* * AngleAxisf(angle3, Vector3f::UnitZ()); -\endcode
- -*/ - -} diff --git a/doc/C09_TutorialSparse.dox b/doc/C09_TutorialSparse.dox deleted file mode 100644 index 9f06005fa..000000000 --- a/doc/C09_TutorialSparse.dox +++ /dev/null @@ -1,436 +0,0 @@ -namespace Eigen { - -/** \eigenManualPage TutorialSparse Sparse matrix manipulations - -\eigeneigenAutoToc - -Manipulating and solving sparse problems involves various modules which are summarized below: - - - - - - - -
ModuleHeader fileContents
\link SparseCore_Module SparseCore \endlink\code#include \endcodeSparseMatrix and SparseVector classes, matrix assembly, basic sparse linear algebra (including sparse triangular solvers)
\link SparseCholesky_Module SparseCholesky \endlink\code#include \endcodeDirect sparse LLT and LDLT Cholesky factorization to solve sparse self-adjoint positive definite problems
\link IterativeLinearSolvers_Module IterativeLinearSolvers \endlink\code#include \endcodeIterative solvers to solve large general linear square problems (including self-adjoint positive definite problems)
\link Sparse_modules Sparse \endlink\code#include \endcodeIncludes all the above modules
- -\section TutorialSparseIntro Sparse matrix representation - -In many applications (e.g., finite element methods) it is common to deal with very large matrices where only a few coefficients are different from zero. In such cases, memory consumption can be reduced and performance increased by using a specialized representation storing only the nonzero coefficients. Such a matrix is called a sparse matrix. - -\b The \b %SparseMatrix \b class - -The class SparseMatrix is the main sparse matrix representation of Eigen's sparse module; it offers high performance and low memory usage. -It implements a more versatile variant of the widely-used Compressed Column (or Row) Storage scheme. -It consists of four compact arrays: - - \c Values: stores the coefficient values of the non-zeros. - - \c InnerIndices: stores the row (resp. column) indices of the non-zeros. - - \c OuterStarts: stores for each column (resp. row) the index of the first non-zero in the previous two arrays. - - \c InnerNNZs: stores the number of non-zeros of each column (resp. row). -The word \c inner refers to an \em inner \em vector that is a column for a column-major matrix, or a row for a row-major matrix. -The word \c outer refers to the other direction. - -This storage scheme is better explained on an example. The following matrix - - - - - - -
03 00 0
220 0017
75 01 0
00 00 0
00140 8
- -and one of its possible sparse, \b column \b major representation: - - - -
Values: 227_3514__1_178
InnerIndices: 12_02 4__2_ 14
- - - -
OuterStarts:035810\em 12
InnerNNZs: 2211 2
- -Currently the elements of a given inner vector are guaranteed to be always sorted by increasing inner indices. -The \c "_" indicates available free space to quickly insert new elements. -Assuming no reallocation is needed, the insertion of a random element is therefore in O(nnz_j) where nnz_j is the number of nonzeros of the respective inner vector. -On the other hand, inserting elements with increasing inner indices in a given inner vector is much more efficient since this only requires to increase the respective \c InnerNNZs entry that is a O(1) operation. - -The case where no empty space is available is a special case, and is refered as the \em compressed mode. -It corresponds to the widely used Compressed Column (or Row) Storage schemes (CCS or CRS). -Any SparseMatrix can be turned to this form by calling the SparseMatrix::makeCompressed() function. -In this case, one can remark that the \c InnerNNZs array is redundant with \c OuterStarts because we the equality: \c InnerNNZs[j] = \c OuterStarts[j+1]-\c OuterStarts[j]. -Therefore, in practice a call to SparseMatrix::makeCompressed() frees this buffer. - -It is worth noting that most of our wrappers to external libraries requires compressed matrices as inputs. - -The results of %Eigen's operations always produces \b compressed sparse matrices. -On the other hand, the insertion of a new element into a SparseMatrix converts this later to the \b uncompressed mode. - -Here is the previous matrix represented in compressed mode: - - - -
Values: 22735141178
InnerIndices: 1202 42 14
- - -
OuterStarts:02456\em 8
- -A SparseVector is a special case of a SparseMatrix where only the \c Values and \c InnerIndices arrays are stored. -There is no notion of compressed/uncompressed mode for a SparseVector. - - -\section TutorialSparseExample First example - -Before describing each individual class, let's start with the following typical example: solving the Lapace equation \f$ \nabla u = 0 \f$ on a regular 2D grid using a finite difference scheme and Dirichlet boundary conditions. -Such problem can be mathematically expressed as a linear problem of the form \f$ Ax=b \f$ where \f$ x \f$ is the vector of \c m unknowns (in our case, the values of the pixels), \f$ b \f$ is the right hand side vector resulting from the boundary conditions, and \f$ A \f$ is an \f$ m \times m \f$ matrix containing only a few non-zero elements resulting from the discretization of the Laplacian operator. - - - -
-\include Tutorial_sparse_example.cpp - -\image html Tutorial_sparse_example.jpeg -
- -In this example, we start by defining a column-major sparse matrix type of double \c SparseMatrix, and a triplet list of the same scalar type \c Triplet. A triplet is a simple object representing a non-zero entry as the triplet: \c row index, \c column index, \c value. - -In the main function, we declare a list \c coefficients of triplets (as a std vector) and the right hand side vector \f$ b \f$ which are filled by the \a buildProblem function. -The raw and flat list of non-zero entries is then converted to a true SparseMatrix object \c A. -Note that the elements of the list do not have to be sorted, and possible duplicate entries will be summed up. - -The last step consists of effectively solving the assembled problem. -Since the resulting matrix \c A is symmetric by construction, we can perform a direct Cholesky factorization via the SimplicialLDLT class which behaves like its LDLT counterpart for dense objects. - -The resulting vector \c x contains the pixel values as a 1D array which is saved to a jpeg file shown on the right of the code above. - -Describing the \a buildProblem and \a save functions is out of the scope of this tutorial. They are given \ref TutorialSparse_example_details "here" for the curious and reproducibility purpose. - - - - -\section TutorialSparseSparseMatrix The SparseMatrix class - -\b %Matrix \b and \b vector \b properties \n - -The SparseMatrix and SparseVector classes take three template arguments: - * the scalar type (e.g., double) - * the storage order (ColMajor or RowMajor, the default is RowMajor) - * the inner index type (default is \c int). - -As for dense Matrix objects, constructors takes the size of the object. -Here are some examples: - -\code -SparseMatrix > mat(1000,2000); // declares a 1000x2000 column-major compressed sparse matrix of complex -SparseMatrix mat(1000,2000); // declares a 1000x2000 row-major compressed sparse matrix of double -SparseVector > vec(1000); // declares a column sparse vector of complex of size 1000 -SparseVector vec(1000); // declares a row sparse vector of double of size 1000 -\endcode - -In the rest of the tutorial, \c mat and \c vec represent any sparse-matrix and sparse-vector objects, respectively. - -The dimensions of a matrix can be queried using the following functions: - - - - - - - - - -
Standard \n dimensions\code -mat.rows() -mat.cols()\endcode\code -vec.size() \endcode
Sizes along the \n inner/outer dimensions\code -mat.innerSize() -mat.outerSize()\endcode
Number of non \n zero coefficients\code -mat.nonZeros() \endcode\code -vec.nonZeros() \endcode
- - -\b Iterating \b over \b the \b nonzero \b coefficients \n - -Random access to the elements of a sparse object can be done through the \c coeffRef(i,j) function. -However, this function involves a quite expensive binary search. -In most cases, one only wants to iterate over the non-zeros elements. This is achieved by a standard loop over the outer dimension, and then by iterating over the non-zeros of the current inner vector via an InnerIterator. Thus, the non-zero entries have to be visited in the same order than the storage order. -Here is an example: - - -
-\code -SparseMatrix mat(rows,cols); -for (int k=0; k::InnerIterator it(mat,k); it; ++it) - { - it.value(); - it.row(); // row index - it.col(); // col index (here it is equal to k) - it.index(); // inner index, here it is equal to it.row() - } -\endcode - -\code -SparseVector vec(size); -for (SparseVector::InnerIterator it(vec); it; ++it) -{ - it.value(); // == vec[ it.index() ] - it.index(); -} -\endcode -
-For a writable expression, the referenced value can be modified using the valueRef() function. -If the type of the sparse matrix or vector depends on a template parameter, then the \c typename keyword is -required to indicate that \c InnerIterator denotes a type; see \ref TopicTemplateKeyword for details. - - -\section TutorialSparseFilling Filling a sparse matrix - -Because of the special storage scheme of a SparseMatrix, special care has to be taken when adding new nonzero entries. -For instance, the cost of a single purely random insertion into a SparseMatrix is \c O(nnz), where \c nnz is the current number of non-zero coefficients. - -The simplest way to create a sparse matrix while guaranteeing good performance is thus to first build a list of so-called \em triplets, and then convert it to a SparseMatrix. - -Here is a typical usage example: -\code -typedef Eigen::Triplet T; -std::vector tripletList; -tripletList.reserve(estimation_of_entries); -for(...) -{ - // ... - tripletList.push_back(T(i,j,v_ij)); -} -SparseMatrixType mat(rows,cols); -mat.setFromTriplets(tripletList.begin(), tripletList.end()); -// mat is ready to go! -\endcode -The \c std::vector of triplets might contain the elements in arbitrary order, and might even contain duplicated elements that will be summed up by setFromTriplets(). -See the SparseMatrix::setFromTriplets() function and class Triplet for more details. - - -In some cases, however, slightly higher performance, and lower memory consumption can be reached by directly inserting the non-zeros into the destination matrix. -A typical scenario of this approach is illustrated bellow: -\code -1: SparseMatrix mat(rows,cols); // default is column major -2: mat.reserve(VectorXi::Constant(cols,6)); -3: for each i,j such that v_ij != 0 -4: mat.insert(i,j) = v_ij; // alternative: mat.coeffRef(i,j) += v_ij; -5: mat.makeCompressed(); // optional -\endcode - -- The key ingredient here is the line 2 where we reserve room for 6 non-zeros per column. In many cases, the number of non-zeros per column or row can easily be known in advance. If it varies significantly for each inner vector, then it is possible to specify a reserve size for each inner vector by providing a vector object with an operator[](int j) returning the reserve size of the \c j-th inner vector (e.g., via a VectorXi or std::vector). If only a rought estimate of the number of nonzeros per inner-vector can be obtained, it is highly recommended to overestimate it rather than the opposite. If this line is omitted, then the first insertion of a new element will reserve room for 2 elements per inner vector. -- The line 4 performs a sorted insertion. In this example, the ideal case is when the \c j-th column is not full and contains non-zeros whose inner-indices are smaller than \c i. In this case, this operation boils down to trivial O(1) operation. -- When calling insert(i,j) the element \c i \c ,j must not already exists, otherwise use the coeffRef(i,j) method that will allow to, e.g., accumulate values. This method first performs a binary search and finally calls insert(i,j) if the element does not already exist. It is more flexible than insert() but also more costly. -- The line 5 suppresses the remaining empty space and transforms the matrix into a compressed column storage. - - -\section TutorialSparseDirectSolvers Solving linear problems - -%Eigen currently provides a limited set of built-in solvers, as well as wrappers to external solver libraries. -They are summarized in the following table: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ClassModuleSolver kindMatrix kindFeatures related to performanceDependencies,License

Notes

SimplicialLLT \link SparseCholesky_Module SparseCholesky \endlinkDirect LLt factorizationSPDFill-in reducingbuilt-in, LGPLSimplicialLDLT is often preferable
SimplicialLDLT \link SparseCholesky_Module SparseCholesky \endlinkDirect LDLt factorizationSPDFill-in reducingbuilt-in, LGPLRecommended for very sparse and not too large problems (e.g., 2D Poisson eq.)
ConjugateGradient\link IterativeLinearSolvers_Module IterativeLinearSolvers \endlinkClassic iterative CGSPDPreconditionningbuilt-in, LGPLRecommended for large symmetric problems (e.g., 3D Poisson eq.)
BiCGSTAB\link IterativeLinearSolvers_Module IterativeLinearSolvers \endlinkIterative stabilized bi-conjugate gradientSquarePreconditionningbuilt-in, LGPLMight not always converge
PastixLLT \n PastixLDLT \n PastixLU\link PaStiXSupport_Module PaStiXSupport \endlinkDirect LLt, LDLt, LU factorizationsSPD \n SPD \n SquareFill-in reducing, Leverage fast dense algebra, MultithreadingRequires the PaStiX package, \b CeCILL-C optimized for tough problems and symmetric patterns
CholmodSupernodalLLT\link CholmodSupport_Module CholmodSupport \endlinkDirect LLt factorizationSPDFill-in reducing, Leverage fast dense algebraRequires the SuiteSparse package, \b GPL
UmfPackLU\link UmfPackSupport_Module UmfPackSupport \endlinkDirect LU factorizationSquareFill-in reducing, Leverage fast dense algebraRequires the SuiteSparse package, \b GPL
SuperLU\link SuperLUSupport_Module SuperLUSupport \endlinkDirect LU factorizationSquareFill-in reducing, Leverage fast dense algebraRequires the SuperLU library, (BSD-like)
- -Here \c SPD means symmetric positive definite. - -All these solvers follow the same general concept. -Here is a typical and general example: -\code -#include -// ... -SparseMatrix A; -// fill A -VectorXd b, x; -// fill b -// solve Ax = b -SolverClassName > solver; -solver.compute(A); -if(solver.info()!=Success) { - // decomposition failed - return; -} -x = solver.solve(b); -if(solver.info()!=Success) { - // solving failed - return; -} -// solve for another right hand side: -x1 = solver.solve(b1); -\endcode - -For \c SPD solvers, a second optional template argument allows to specify which triangular part have to be used, e.g.: - -\code -#include - -ConjugateGradient, Eigen::Upper> solver; -x = solver.compute(A).solve(b); -\endcode -In the above example, only the upper triangular part of the input matrix A is considered for solving. The opposite triangle might either be empty or contain arbitrary values. - -In the case where multiple problems with the same sparcity pattern have to be solved, then the "compute" step can be decomposed as follow: -\code -SolverClassName > solver; -solver.analyzePattern(A); // for this step the numerical values of A are not used -solver.factorize(A); -x1 = solver.solve(b1); -x2 = solver.solve(b2); -... -A = ...; // modify the values of the nonzeros of A, the nonzeros pattern must stay unchanged -solver.factorize(A); -x1 = solver.solve(b1); -x2 = solver.solve(b2); -... -\endcode -The compute() method is equivalent to calling both analyzePattern() and factorize(). - -Finally, each solver provides some specific features, such as determinant, access to the factors, controls of the iterations, and so on. -More details are availble in the documentations of the respective classes. - - -\section TutorialSparseFeatureSet Supported operators and functions - -Because of their special storage format, sparse matrices cannot offer the same level of flexbility than dense matrices. -In Eigen's sparse module we chose to expose only the subset of the dense matrix API which can be efficiently implemented. -In the following \em sm denotes a sparse matrix, \em sv a sparse vector, \em dm a dense matrix, and \em dv a dense vector. - -\subsection TutorialSparse_BasicOps Basic operations - -%Sparse expressions support most of the unary and binary coefficient wise operations: -\code -sm1.real() sm1.imag() -sm1 0.5*sm1 -sm1+sm2 sm1-sm2 sm1.cwiseProduct(sm2) -\endcode -However, a strong restriction is that the storage orders must match. For instance, in the following example: -\code -sm4 = sm1 + sm2 + sm3; -\endcode -sm1, sm2, and sm3 must all be row-major or all column major. -On the other hand, there is no restriction on the target matrix sm4. -For instance, this means that for computing \f$ A^T + A \f$, the matrix \f$ A^T \f$ must be evaluated into a temporary matrix of compatible storage order: -\code -SparseMatrix A, B; -B = SparseMatrix(A.transpose()) + A; -\endcode - -Binary coefficient wise operators can also mix sparse and dense expressions: -\code -sm2 = sm1.cwiseProduct(dm1); -dm2 = sm1 + dm1; -\endcode - - -%Sparse expressions also support transposition: -\code -sm1 = sm2.transpose(); -sm1 = sm2.adjoint(); -\endcode -However, there is no transposeInPlace() method. - - -\subsection TutorialSparse_Products Matrix products - -%Eigen supports various kind of sparse matrix products which are summarize below: - - \b sparse-dense: - \code -dv2 = sm1 * dv1; -dm2 = dm1 * sm1.adjoint(); -dm2 = 2. * sm1 * dm1; - \endcode - - \b symmetric \b sparse-dense. The product of a sparse symmetric matrix with a dense matrix (or vector) can also be optimized by specifying the symmetry with selfadjointView(): - \code -dm2 = sm1.selfadjointView<>() * dm1; // if all coefficients of A are stored -dm2 = A.selfadjointView() * dm1; // if only the upper part of A is stored -dm2 = A.selfadjointView() * dm1; // if only the lower part of A is stored - \endcode - - \b sparse-sparse. For sparse-sparse products, two different algorithms are available. The default one is conservative and preserve the explicit zeros that might appear: - \code -sm3 = sm1 * sm2; -sm3 = 4 * sm1.adjoint() * sm2; - \endcode - The second algorithm prunes on the fly the explicit zeros, or the values smaller than a given threshold. It is enabled and controlled through the prune() functions: - \code -sm3 = (sm1 * sm2).prune(); // removes numerical zeros -sm3 = (sm1 * sm2).prune(ref); // removes elements much smaller than ref -sm3 = (sm1 * sm2).prune(ref,epsilon); // removes elements smaller than ref*epsilon - \endcode - - - \b permutations. Finally, permutations can be applied to sparse matrices too: - \code -PermutationMatrix P = ...; -sm2 = P * sm1; -sm2 = sm1 * P.inverse(); -sm2 = sm1.transpose() * P; - \endcode - - -\subsection TutorialSparse_TriangularSelfadjoint Triangular and selfadjoint views - -Just as with dense matrices, the triangularView() function can be used to address a triangular part of the matrix, and perform triangular solves with a dense right hand side: -\code -dm2 = sm1.triangularView(dm1); -dv2 = sm1.transpose().triangularView(dv1); -\endcode - -The selfadjointView() function permits various operations: - - optimized sparse-dense matrix products: - \code -dm2 = sm1.selfadjointView<>() * dm1; // if all coefficients of A are stored -dm2 = A.selfadjointView() * dm1; // if only the upper part of A is stored -dm2 = A.selfadjointView() * dm1; // if only the lower part of A is stored - \endcode - - copy of triangular parts: - \code -sm2 = sm1.selfadjointView(); // makes a full selfadjoint matrix from the upper triangular part -sm2.selfadjointView() = sm1.selfadjointView(); // copies the upper triangular part to the lower triangular part - \endcode - - application of symmetric permutations: - \code -PermutationMatrix P = ...; -sm2 = A.selfadjointView().twistedBy(P); // compute P S P' from the upper triangular part of A, and make it a full matrix -sm2.selfadjointView() = A.selfadjointView().twistedBy(P); // compute P S P' from the lower triangular part of A, and then only compute the lower part - \endcode - -\subsection TutorialSparse_Submat Sub-matrices - -%Sparse matrices does not support yet the addressing of arbitrary sub matrices. Currently, one can only reference a set of contiguous \em inner vectors, i.e., a set of contiguous rows for a row-major matrix, or a set of contiguous columns for a column major matrix: -\code - sm1.innerVector(j); // returns an expression of the j-th column (resp. row) of the matrix if sm1 is col-major (resp. row-major) - sm1.innerVectors(j, nb); // returns an expression of the nb columns (resp. row) starting from the j-th column (resp. row) - // of the matrix if sm1 is col-major (resp. row-major) - sm1.middleRows(j, nb); // for row major matrices only, get a range of nb rows - sm1.middleCols(j, nb); // for column major matrices only, get a range of nb columns -\endcode - -*/ - -} diff --git a/doc/C10_TutorialMapClass.dox b/doc/C10_TutorialMapClass.dox deleted file mode 100644 index a5c20f1bf..000000000 --- a/doc/C10_TutorialMapClass.dox +++ /dev/null @@ -1,86 +0,0 @@ -namespace Eigen { - -/** \eigenManualPage TutorialMapClass Interfacing with raw buffers: the Map class - -This page explains how to work with "raw" C/C++ arrays. -This can be useful in a variety of contexts, particularly when "importing" vectors and matrices from other libraries into Eigen. - -\eigenAutoToc - -\section TutorialMapIntroduction Introduction - -Occasionally you may have a pre-defined array of numbers that you want to use within Eigen as a vector or matrix. While one option is to make a copy of the data, most commonly you probably want to re-use this memory as an Eigen type. Fortunately, this is very easy with the Map class. - -\section TutorialMapTypes Map types and declaring Map variables - -A Map object has a type defined by its Eigen equivalent: -\code -Map > -\endcode -Note that, in this default case, a Map requires just a single template parameter. - -To construct a Map variable, you need two other pieces of information: a pointer to the region of memory defining the array of coefficients, and the desired shape of the matrix or vector. For example, to define a matrix of \c float with sizes determined at compile time, you might do the following: -\code -Map mf(pf,rows,columns); -\endcode -where \c pf is a \c float \c * pointing to the array of memory. A fixed-size read-only vector of integers might be declared as -\code -Map mi(pi); -\endcode -where \c pi is an \c int \c *. In this case the size does not have to be passed to the constructor, because it is already specified by the Matrix/Array type. - -Note that Map does not have a default constructor; you \em must pass a pointer to intialize the object. However, you can work around this requirement (see \ref TutorialMapPlacementNew). - -Map is flexible enough to accomodate a variety of different data representations. There are two other (optional) template parameters: -\code -Map -\endcode -\li \c MapOptions specifies whether the pointer is \c #Aligned, or \c #Unaligned. The default is \c #Unaligned. -\li \c StrideType allows you to specify a custom layout for the memory array, using the Stride class. One example would be to specify that the data array is organized in row-major format: - - - - - -
Example:Output:
\include Tutorial_Map_rowmajor.cpp \verbinclude Tutorial_Map_rowmajor.out
-However, Stride is even more flexible than this; for details, see the documentation for the Map and Stride classes. - -\section TutorialMapUsing Using Map variables - -You can use a Map object just like any other Eigen type: - - - - - -
Example:Output:
\include Tutorial_Map_using.cpp \verbinclude Tutorial_Map_using.out
- -However, when writing functions taking Eigen types, it is important to realize that a Map type is \em not identical to its Dense equivalent. See \ref TopicFunctionTakingEigenTypesMultiarguments for details. - -\section TutorialMapPlacementNew Changing the mapped array - -It is possible to change the array of a Map object after declaration, using the C++ "placement new" syntax: - - - - - -
Example:Output:
\include Map_placement_new.cpp \verbinclude Map_placement_new.out
-Despite appearances, this does not invoke the memory allocator, because the syntax specifies the location for storing the result. - -This syntax makes it possible to declare a Map object without first knowing the mapped array's location in memory: -\code -Map A(NULL); // don't try to use this matrix yet! -VectorXf b(n_matrices); -for (int i = 0; i < n_matrices; i++) -{ - new (&A) Map(get_matrix_pointer(i)); - b(i) = A.trace(); -} -\endcode - -*/ - -} diff --git a/doc/ClassHierarchy.dox b/doc/ClassHierarchy.dox new file mode 100644 index 000000000..468e60a76 --- /dev/null +++ b/doc/ClassHierarchy.dox @@ -0,0 +1,129 @@ +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: + +

+EigenBase<%Matrix>
+  <-- DenseCoeffsBase<%Matrix>    (direct access case)
+    <-- DenseBase<%Matrix>
+      <-- MatrixBase<%Matrix>
+        <-- PlainObjectBase<%Matrix>    (matrix case)
+          <-- Matrix
+
+ +The inheritance diagram for Array looks as follows: + +
+EigenBase<%Array>
+  <-- DenseCoeffsBase<%Array>    (direct access case)
+    <-- DenseBase<%Array>
+      <-- ArrayBase<%Array>
+        <-- PlainObjectBase<%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/CustomizingEigen.dox b/doc/CustomizingEigen.dox new file mode 100644 index 000000000..e42eaa812 --- /dev/null +++ b/doc/CustomizingEigen.dox @@ -0,0 +1,188 @@ +namespace Eigen { + +/** \page TopicCustomizingEigen Customizing/Extending Eigen + +Eigen can be extended in several ways, for instance, by defining global methods, \ref ExtendingMatrixBase "by adding custom methods to MatrixBase", adding support to \ref CustomScalarType "custom types" etc. + +\eigenAutoToc + +\section ExtendingMatrixBase Extending MatrixBase (and other classes) + +In this section we will see how to add custom methods to MatrixBase. Since all expressions and matrix types inherit MatrixBase, adding a method to MatrixBase make it immediately available to all expressions ! A typical use case is, for instance, to make Eigen compatible with another API. + +You certainly know that in C++ it is not possible to add methods to an existing class. So how that's possible ? Here the trick is to include in the declaration of MatrixBase a file defined by the preprocessor token \c EIGEN_MATRIXBASE_PLUGIN: +\code +class MatrixBase { + // ... + #ifdef EIGEN_MATRIXBASE_PLUGIN + #include EIGEN_MATRIXBASE_PLUGIN + #endif +}; +\endcode +Therefore to extend MatrixBase with your own methods you just have to create a file with your method declaration and define EIGEN_MATRIXBASE_PLUGIN before you include any Eigen's header file. + +You can extend many of the other classes used in Eigen by defining similarly named preprocessor symbols. For instance, define \c EIGEN_ARRAYBASE_PLUGIN if you want to extend the ArrayBase class. A full list of classes that can be extended in this way and the corresponding preprocessor symbols can be found on our page \ref TopicPreprocessorDirectives. + +Here is an example of an extension file for adding methods to MatrixBase: \n +\b MatrixBaseAddons.h +\code +inline Scalar at(uint i, uint j) const { return this->operator()(i,j); } +inline Scalar& at(uint i, uint j) { return this->operator()(i,j); } +inline Scalar at(uint i) const { return this->operator[](i); } +inline Scalar& at(uint i) { return this->operator[](i); } + +inline RealScalar squaredLength() const { return squaredNorm(); } +inline RealScalar length() const { return norm(); } +inline RealScalar invLength(void) const { return fast_inv_sqrt(squaredNorm()); } + +template +inline Scalar squaredDistanceTo(const MatrixBase& other) const +{ return (derived() - other.derived()).squaredNorm(); } + +template +inline RealScalar distanceTo(const MatrixBase& other) const +{ return internal::sqrt(derived().squaredDistanceTo(other)); } + +inline void scaleTo(RealScalar l) { RealScalar vl = norm(); if (vl>1e-9) derived() *= (l/vl); } + +inline Transpose transposed() {return this->transpose();} +inline const Transpose transposed() const {return this->transpose();} + +inline uint minComponentId(void) const { int i; this->minCoeff(&i); return i; } +inline uint maxComponentId(void) const { int i; this->maxCoeff(&i); return i; } + +template +void makeFloor(const MatrixBase& other) { derived() = derived().cwiseMin(other.derived()); } +template +void makeCeil(const MatrixBase& other) { derived() = derived().cwiseMax(other.derived()); } + +const CwiseUnaryOp, Derived> +operator+(const Scalar& scalar) const +{ return CwiseUnaryOp, Derived>(derived(), internal::scalar_add_op(scalar)); } + +friend const CwiseUnaryOp, Derived> +operator+(const Scalar& scalar, const MatrixBase& mat) +{ return CwiseUnaryOp, Derived>(mat.derived(), internal::scalar_add_op(scalar)); } +\endcode + +Then one can the following declaration in the config.h or whatever prerequisites header file of his project: +\code +#define EIGEN_MATRIXBASE_PLUGIN "MatrixBaseAddons.h" +\endcode + +\section InheritingFromMatrix Inheriting from Matrix + +Before inheriting from Matrix, be really, i mean REALLY sure that using +EIGEN_MATRIX_PLUGIN is not what you really want (see previous section). +If you just need to add few members to Matrix, this is the way to go. + +An example of when you actually need to inherit Matrix, is when you have +several layers of heritage such as MyVerySpecificVector1,MyVerySpecificVector1 -> MyVector1 -> Matrix and. +MyVerySpecificVector3,MyVerySpecificVector4 -> MyVector2 -> Matrix. + +In order for your object to work within the %Eigen framework, you need to +define a few members in your inherited class. + +Here is a minimalistic example:\n +\code +class MyVectorType : public Eigen::VectorXd +{ +public: + MyVectorType(void):Eigen::VectorXd() {} + + typedef Eigen::VectorXd Base; + + // This constructor allows you to construct MyVectorType from Eigen expressions + template + MyVectorType(const Eigen::MatrixBase& other) + : Eigen::Vector3d(other) + { } + + // This method allows you to assign Eigen expressions to MyVectorType + template + MyVectorType & operator= (const Eigen::MatrixBase & other) + { + this->Base::operator=(other); + return *this; + } +}; +\endcode + +This is the kind of error you can get if you don't provide those methods +\code +error: no match for ‘operator=’ in ‘delta = +(((Eigen::MatrixBase, 10000, 1, 2, 10000, +1> >*)(& delta)) + 8u)->Eigen::MatrixBase::cwise [with Derived = +Eigen::Matrix, 10000, 1, 2, 10000, +1>]().Eigen::Cwise::operator* [with OtherDerived = +Eigen::Matrix, 10000, 1, 2, 10000, 1>, ExpressionType = +Eigen::Matrix, 10000, 1, 2, 10000, 1>](((const +Eigen::MatrixBase, 10000, 1, 2, 10000, 1> +>&)(((const Eigen::MatrixBase, 10000, 1, +>2, 10000, 1> >*)((const spectral1d*)where)) + 8u)))’ +\endcode + +\anchor user_defined_scalars \section CustomScalarType Using custom scalar types + +By default, Eigen currently supports standard floating-point types (\c float, \c double, \c std::complex, \c std::complex, \c long \c double), as well as all integrale types (e.g., \c int, \c unsigned \c int, \c short, etc.), and \c bool. +On x86-64 systems, \c long \c double permits to locally enforces the use of x87 registers with extended accuracy (in comparison to SSE). + +In order to add support for a custom type \c T you need: +-# make sure the common operator (+,-,*,/,etc.) are supported by the type \c T +-# add a specialization of struct Eigen::NumTraits (see \ref NumTraits) +-# define the math functions that makes sense for your type. This includes standard ones like sqrt, pow, sin, tan, conj, real, imag, etc, as well as abs2 which is Eigen specific. + (see the file Eigen/src/Core/MathFunctions.h) + +The math function should be defined in the same namespace than \c T, or in the \c std namespace though that second appraoch is not recommended. + +Here is a concrete example adding support for the Adolc's \c adouble type. Adolc is an automatic differentiation library. The type \c adouble is basically a real value tracking the values of any number of partial derivatives. + +\code +#ifndef ADOLCSUPPORT_H +#define ADOLCSUPPORT_H + +#define ADOLC_TAPELESS +#include +#include + +namespace Eigen { + +template<> struct NumTraits + : NumTraits // permits to get the epsilon, dummy_precision, lowest, highest functions +{ + typedef adtl::adouble Real; + typedef adtl::adouble NonInteger; + typedef adtl::adouble Nested; + + enum { + IsComplex = 0, + IsInteger = 0, + IsSigned = 1, + RequireInitialization = 1, + ReadCost = 1, + AddCost = 3, + MulCost = 3 + }; +}; + +} + +namespace adtl { + +inline const adouble& conj(const adouble& x) { return x; } +inline const adouble& real(const adouble& x) { return x; } +inline adouble imag(const adouble&) { return 0.; } +inline adouble abs(const adouble& x) { return fabs(x); } +inline adouble abs2(const adouble& x) { return x*x; } + +} + +#endif // ADOLCSUPPORT_H +\endcode + + +\sa \ref TopicPreprocessorDirectives + +*/ + +} diff --git a/doc/D01_StlContainers.dox b/doc/D01_StlContainers.dox deleted file mode 100644 index d8d0d529c..000000000 --- a/doc/D01_StlContainers.dox +++ /dev/null @@ -1,62 +0,0 @@ -namespace Eigen { - -/** \eigenManualPage TopicStlContainers Using STL Containers with Eigen - -\eigenAutoToc - -\section summary Executive summary - -Using STL containers on \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types", or classes having members of such types, requires taking the following two steps: - -\li A 16-byte-aligned allocator must be used. Eigen does provide one ready for use: aligned_allocator. -\li If you want to use the std::vector container, you need to \#include . - -These issues arise only with \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types" and \ref TopicStructHavingEigenMembers "structures having such Eigen objects as member". For other Eigen types, such as Vector3f or MatrixXd, no special care is needed when using STL containers. - -\section allocator Using an aligned allocator - -STL containers take an optional template parameter, the allocator type. When using STL containers on \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types", you need tell the container to use an allocator that will always allocate memory at 16-byte-aligned locations. Fortunately, Eigen does provide such an allocator: Eigen::aligned_allocator. - -For example, instead of -\code -std::map -\endcode -you need to use -\code -std::map, - Eigen::aligned_allocator > > -\endcode -Note that the third parameter "std::less" is just the default value, but we have to include it because we want to specify the fourth parameter, which is the allocator type. - -\section vector The case of std::vector - -The situation with std::vector was even worse (explanation below) so we had to specialize it for the Eigen::aligned_allocator type. In practice you \b must use the Eigen::aligned_allocator (not another aligned allocator), \b and \#include . - -Here is an example: -\code -#include -/* ... */ -std::vector > -\endcode - -\subsection vector_spec An alternative - specializing std::vector for Eigen types - -As an alternative to the recommended approach described above, you have the option to specialize std::vector for Eigen types requiring alignment. -The advantage is that you won't need to declare std::vector all over with Eigen::allocator. One drawback on the other hand side is that -the specialization needs to be defined before all code pieces in which e.g. std::vector is used. Otherwise, without knowing the specialization -the compiler will compile that particular instance with the default std::allocator and you program is most likely to crash. - -Here is an example: -\code -#include -/* ... */ -EIGEN_DEFINE_STL_VECTOR_SPECIALIZATION(Matrix2d) -std::vector -\endcode - -\b Explanation: The resize() method of std::vector takes a value_type argument (defaulting to value_type()). So with std::vector, some Eigen::Vector4f objects will be passed by value, which discards any alignment modifiers, so a Eigen::Vector4f can be created at an unaligned location. In order to avoid that, the only solution we saw was to specialize std::vector to make it work on a slight modification of, here, Eigen::Vector4f, that is able to deal properly with this situation. - - -*/ - -} diff --git a/doc/D03_WrongStackAlignment.dox b/doc/D03_WrongStackAlignment.dox deleted file mode 100644 index 17d5513a7..000000000 --- a/doc/D03_WrongStackAlignment.dox +++ /dev/null @@ -1,56 +0,0 @@ -namespace Eigen { - -/** \eigenManualPage TopicWrongStackAlignment Compiler making a wrong assumption on stack alignment - -

It appears that this was a GCC bug that has been fixed in GCC 4.5. -If you hit this issue, please upgrade to GCC 4.5 and report to us, so we can update this page.

- -This is an issue that, so far, we met only with GCC on Windows: for instance, MinGW and TDM-GCC. - -By default, in a function like this, - -\code -void foo() -{ - Eigen::Quaternionf q; - //... -} -\endcode - -GCC assumes that the stack is already 16-byte-aligned so that the object \a q will be created at a 16-byte-aligned location. For this reason, it doesn't take any special care to explicitly align the object \a q, as Eigen requires. - -The problem is that, in some particular cases, this assumption can be wrong on Windows, where the stack is only guaranteed to have 4-byte alignment. Indeed, even though GCC takes care of aligning the stack in the main function and does its best to keep it aligned, when a function is called from another thread or from a binary compiled with another compiler, the stack alignment can be corrupted. This results in the object 'q' being created at an unaligned location, making your program crash with the \ref TopicUnalignedArrayAssert "assertion on unaligned arrays". So far we found the three following solutions. - - -\section sec_sol1 Local solution - -A local solution is to mark such a function with this attribute: -\code -__attribute__((force_align_arg_pointer)) void foo() -{ - Eigen::Quaternionf q; - //... -} -\endcode -Read this GCC documentation to understand what this does. Of course this should only be done on GCC on Windows, so for portability you'll have to encapsulate this in a macro which you leave empty on other platforms. The advantage of this solution is that you can finely select which function might have a corrupted stack alignment. Of course on the downside this has to be done for every such function, so you may prefer one of the following two global solutions. - - -\section sec_sol2 Global solutions - -A global solution is to edit your project so that when compiling with GCC on Windows, you pass this option to GCC: -\code --mincoming-stack-boundary=2 -\endcode -Explanation: this tells GCC that the stack is only required to be aligned to 2^2=4 bytes, so that GCC now knows that it really must take extra care to honor the 16 byte alignment of \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types" when needed. - -Another global solution is to pass this option to gcc: -\code --mstackrealign -\endcode -which has the same effect than adding the \c force_align_arg_pointer attribute to all functions. - -These global solutions are easy to use, but note that they may slowdown your program because they lead to extra prologue/epilogue instructions for every function. - -*/ - -} diff --git a/doc/D07_PassingByValue.dox b/doc/D07_PassingByValue.dox deleted file mode 100644 index bf4d0ef4b..000000000 --- a/doc/D07_PassingByValue.dox +++ /dev/null @@ -1,40 +0,0 @@ -namespace Eigen { - -/** \eigenManualPage TopicPassingByValue Passing Eigen objects by value to functions - -Passing objects by value is almost always a very bad idea in C++, as this means useless copies, and one should pass them by reference instead. - -With Eigen, this is even more important: passing \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen objects" by value is not only inefficient, it can be illegal or make your program crash! And the reason is that these Eigen objects have alignment modifiers that aren't respected when they are passed by value. - -So for example, a function like this, where v is passed by value: - -\code -void my_function(Eigen::Vector2d v); -\endcode - -needs to be rewritten as follows, passing v by reference: - -\code -void my_function(const Eigen::Vector2d& v); -\endcode - -Likewise if you have a class having a Eigen object as member: - -\code -struct Foo -{ - Eigen::Vector2d v; -}; -void my_function(Foo v); -\endcode - -This function also needs to be rewritten like this: -\code -void my_function(const Foo& v); -\endcode - -Note that on the other hand, there is no problem with functions that return objects by value. - -*/ - -} diff --git a/doc/D09_StructHavingEigenMembers.dox b/doc/D09_StructHavingEigenMembers.dox deleted file mode 100644 index 74a8d5217..000000000 --- a/doc/D09_StructHavingEigenMembers.dox +++ /dev/null @@ -1,190 +0,0 @@ -namespace Eigen { - -/** \eigenManualPage TopicStructHavingEigenMembers Structures Having Eigen Members - -\eigenAutoToc - -\section summary Executive Summary - -If you define a structure having members of \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types", you must overload its "operator new" so that it generates 16-bytes-aligned pointers. Fortunately, Eigen provides you with a macro EIGEN_MAKE_ALIGNED_OPERATOR_NEW that does that for you. - -\section what What kind of code needs to be changed? - -The kind of code that needs to be changed is this: - -\code -class Foo -{ - ... - Eigen::Vector2d v; - ... -}; - -... - -Foo *foo = new Foo; -\endcode - -In other words: you have a class that has as a member a \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen object", and then you dynamically create an object of that class. - -\section how How should such code be modified? - -Very easy, you just need to put a EIGEN_MAKE_ALIGNED_OPERATOR_NEW macro in a public part of your class, like this: - -\code -class Foo -{ - ... - Eigen::Vector2d v; - ... -public: - EIGEN_MAKE_ALIGNED_OPERATOR_NEW -}; - -... - -Foo *foo = new Foo; -\endcode - -This macro makes "new Foo" always return an aligned pointer. - -If this approach is too intrusive, see also the \ref othersolutions. - -\section why Why is this needed? - -OK let's say that your code looks like this: - -\code -class Foo -{ - ... - Eigen::Vector2d v; - ... -}; - -... - -Foo *foo = new Foo; -\endcode - -A Eigen::Vector2d consists of 2 doubles, which is 128 bits. Which is exactly the size of a SSE packet, which makes it possible to use SSE for all sorts of operations on this vector. But SSE instructions (at least the ones that Eigen uses, which are the fast ones) require 128-bit alignment. Otherwise you get a segmentation fault. - -For this reason, Eigen takes care by itself to require 128-bit alignment for Eigen::Vector2d, by doing two things: -\li Eigen requires 128-bit alignment for the Eigen::Vector2d's array (of 2 doubles). With GCC, this is done with a __attribute__ ((aligned(16))). -\li Eigen overloads the "operator new" of Eigen::Vector2d so it will always return 128-bit aligned pointers. - -Thus, normally, you don't have to worry about anything, Eigen handles alignment for you... - -... except in one case. When you have a class Foo like above, and you dynamically allocate a new Foo as above, then, since Foo doesn't have aligned "operator new", the returned pointer foo is not necessarily 128-bit aligned. - -The alignment attribute of the member v is then relative to the start of the class, foo. If the foo pointer wasn't aligned, then foo->v won't be aligned either! - -The solution is to let class Foo have an aligned "operator new", as we showed in the previous section. - -\section movetotop Should I then put all the members of Eigen types at the beginning of my class? - -That's not required. Since Eigen takes care of declaring 128-bit alignment, all members that need it are automatically 128-bit aligned relatively to the class. So code like this works fine: - -\code -class Foo -{ - double x; - Eigen::Vector2d v; -public: - EIGEN_MAKE_ALIGNED_OPERATOR_NEW -}; -\endcode - -\section dynamicsize What about dynamic-size matrices and vectors? - -Dynamic-size matrices and vectors, such as Eigen::VectorXd, allocate dynamically their own array of coefficients, so they take care of requiring absolute alignment automatically. So they don't cause this issue. The issue discussed here is only with \ref TopicFixedSizeVectorizable "fixed-size vectorizable matrices and vectors". - -\section bugineigen So is this a bug in Eigen? - -No, it's not our bug. It's more like an inherent problem of the C++98 language specification, and seems to be taken care of in the upcoming language revision: see this document. - -\section conditional What if I want to do this conditionnally (depending on template parameters) ? - -For this situation, we offer the macro EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF(NeedsToAlign). It will generate aligned operators like EIGEN_MAKE_ALIGNED_OPERATOR_NEW if NeedsToAlign is true. It will generate operators with the default alignment if NeedsToAlign is false. - -Example: - -\code -template class Foo -{ - typedef Eigen::Matrix Vector; - enum { NeedsToAlign = (sizeof(Vector)%16)==0 }; - ... - Vector v; - ... -public: - EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF(NeedsToAlign) -}; - -... - -Foo<4> *foo4 = new Foo<4>; // foo4 is guaranteed to be 128bit-aligned -Foo<3> *foo3 = new Foo<3>; // foo3 has only the system default alignment guarantee -\endcode - - -\section othersolutions Other solutions - -In case putting the EIGEN_MAKE_ALIGNED_OPERATOR_NEW macro everywhere is too intrusive, there exists at least two other solutions. - -\subsection othersolutions1 Disabling alignment - -The first is to disable alignment requirement for the fixed size members: -\code -class Foo -{ - ... - Eigen::Matrix v; - ... -}; -\endcode -This has for effect to disable vectorization when using \c v. -If a function of Foo uses it several times, then it still possible to re-enable vectorization by copying it into an aligned temporary vector: -\code -void Foo::bar() -{ - Eigen::Vector2d av(v); - // use av instead of v - ... - // if av changed, then do: - v = av; -} -\endcode - -\subsection othersolutions2 Private structure - -The second consist in storing the fixed-size objects into a private struct which will be dynamically allocated at the construction time of the main object: - -\code -struct Foo_d -{ - EIGEN_MAKE_ALIGNED_OPERATOR_NEW - Vector2d v; - ... -}; - - -struct Foo { - Foo() { init_d(); } - ~Foo() { delete d; } - void bar() - { - // use d->v instead of v - ... - } -private: - void init_d() { d = new Foo_d; } - Foo_d* d; -}; -\endcode - -The clear advantage here is that the class Foo remains unchanged regarding alignment issues. The drawback is that a heap allocation will be required whatsoever. - -*/ - -} diff --git a/doc/D11_UnalignedArrayAssert.dox b/doc/D11_UnalignedArrayAssert.dox deleted file mode 100644 index 8c97d7874..000000000 --- a/doc/D11_UnalignedArrayAssert.dox +++ /dev/null @@ -1,114 +0,0 @@ -namespace Eigen { - -/** \eigenManualPage TopicUnalignedArrayAssert Explanation of the assertion on unaligned arrays - -Hello! You are seeing this webpage because your program terminated on an assertion failure like this one: -
-my_program: path/to/eigen/Eigen/src/Core/DenseStorage.h:44:
-Eigen::internal::matrix_array::internal::matrix_array()
-[with T = double, int Size = 2, int MatrixOptions = 2, bool Align = true]:
-Assertion `(reinterpret_cast(array) & 0xf) == 0 && "this assertion
-is explained here: http://eigen.tuxfamily.org/dox/UnalignedArrayAssert.html
-**** READ THIS WEB PAGE !!! ****"' failed.
-
- -There are 4 known causes for this issue. Please read on to understand them and learn how to fix them. - -\eigenAutoToc - -\section where Where in my own code is the cause of the problem? - -First of all, you need to find out where in your own code this assertion was triggered from. At first glance, the error message doesn't look helpful, as it refers to a file inside Eigen! However, since your program crashed, if you can reproduce the crash, you can get a backtrace using any debugger. For example, if you're using GCC, you can use the GDB debugger as follows: -\code -$ gdb ./my_program # Start GDB on your program -> run # Start running your program -... # Now reproduce the crash! -> bt # Obtain the backtrace -\endcode -Now that you know precisely where in your own code the problem is happening, read on to understand what you need to change. - -\section c1 Cause 1: Structures having Eigen objects as members - -If you have code like this, - -\code -class Foo -{ - //... - Eigen::Vector2d v; - //... -}; -//... -Foo *foo = new Foo; -\endcode - -then you need to read this separate page: \ref TopicStructHavingEigenMembers "Structures Having Eigen Members". - -Note that here, Eigen::Vector2d is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types". - -\section c2 Cause 2: STL Containers - -If you use STL Containers such as std::vector, std::map, ..., with Eigen objects, or with classes containing Eigen objects, like this, - -\code -std::vector my_vector; -struct my_class { ... Eigen::Matrix2f m; ... }; -std::map my_map; -\endcode - -then you need to read this separate page: \ref TopicStlContainers "Using STL Containers with Eigen". - -Note that here, Eigen::Matrix2f is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types" and \ref TopicStructHavingEigenMembers "structures having such Eigen objects as member". - -\section c3 Cause 3: Passing Eigen objects by value - -If some function in your code is getting an Eigen object passed by value, like this, - -\code -void func(Eigen::Vector4d v); -\endcode - -then you need to read this separate page: \ref TopicPassingByValue "Passing Eigen objects by value to functions". - -Note that here, Eigen::Vector4d is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types". - -\section c4 Cause 4: Compiler making a wrong assumption on stack alignment (for instance GCC on Windows) - -This is a must-read for people using GCC on Windows (like MinGW or TDM-GCC). If you have this assertion failure in an innocent function declaring a local variable like this: - -\code -void foo() -{ - Eigen::Quaternionf q; - //... -} -\endcode - -then you need to read this separate page: \ref TopicWrongStackAlignment "Compiler making a wrong assumption on stack alignment". - -Note that here, Eigen::Quaternionf is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types". - -\section explanation General explanation of this assertion - -\ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen objects" must absolutely be created at 16-byte-aligned locations, otherwise SIMD instructions adressing them will crash. - -Eigen normally takes care of these alignment issues for you, by setting an alignment attribute on them and by overloading their "operator new". - -However there are a few corner cases where these alignment settings get overridden: they are the possible causes for this assertion. - -\section getrid I don't care about vectorization, how do I get rid of that stuff? - -Two possibilities: -
    -
  • Define EIGEN_DONT_ALIGN_STATICALLY. That disables all 128-bit static alignment code, while keeping 128-bit heap alignment. This has the effect of - disabling vectorization for fixed-size objects (like Matrix4d) while keeping vectorization of dynamic-size objects - (like MatrixXd). But do note that this breaks ABI compatibility with the default behavior of 128-bit static alignment.
    • -
  • Or define both EIGEN_DONT_VECTORIZE and EIGEN_DISABLE_UNALIGNED_ARRAY_ASSERT. This keeps the - 128-bit alignment code and thus preserves ABI compatibility, but completely disables vectorization.
    • -
- -For more information, see this FAQ. - -*/ - -} diff --git a/doc/FixedSizeVectorizable.dox b/doc/FixedSizeVectorizable.dox new file mode 100644 index 000000000..8ae135173 --- /dev/null +++ b/doc/FixedSizeVectorizable.dox @@ -0,0 +1,38 @@ +namespace Eigen { + +/** \eigenManualPage TopicFixedSizeVectorizable Fixed-size vectorizable Eigen objects + +The goal of this page is to explain what we mean by "fixed-size vectorizable". + +\section summary Executive Summary + +An Eigen object is called "fixed-size vectorizable" if it has fixed size and that size is a multiple of 16 bytes. + +Examples include: +\li Eigen::Vector2d +\li Eigen::Vector4d +\li Eigen::Vector4f +\li Eigen::Matrix2d +\li Eigen::Matrix2f +\li Eigen::Matrix4d +\li Eigen::Matrix4f +\li Eigen::Affine3d +\li Eigen::Affine3f +\li Eigen::Quaterniond +\li Eigen::Quaternionf + +\section explanation Explanation + +First, "fixed-size" should be clear: an Eigen object has fixed size if its number of rows and its number of columns are fixed at compile-time. So for example Matrix3f has fixed size, but MatrixXf doesn't (the opposite of fixed-size is dynamic-size). + +The array of coefficients of a fixed-size Eigen object is a plain "static array", it is not dynamically allocated. For example, the data behind a Matrix4f is just a "float array[16]". + +Fixed-size objects are typically very small, which means that we want to handle them with zero runtime overhead -- both in terms of memory usage and of speed. + +Now, vectorization (both SSE and AltiVec) works with 128-bit packets. Moreover, for performance reasons, these packets need to be have 128-bit alignment. + +So it turns out that the only way that fixed-size Eigen objects can be vectorized, is if their size is a multiple of 128 bits, or 16 bytes. Eigen will then request 16-byte alignment for these objects, and henceforth rely on these objects being aligned so no runtime check for alignment is performed. + +*/ + +} diff --git a/doc/FunctionsTakingEigenTypes.dox b/doc/FunctionsTakingEigenTypes.dox new file mode 100644 index 000000000..ad315edf0 --- /dev/null +++ b/doc/FunctionsTakingEigenTypes.dox @@ -0,0 +1,183 @@ +namespace Eigen { + +/** \page TopicFunctionTakingEigenTypes Writing Functions Taking Eigen Types as Parameters + +Eigen's use of expression templates results in potentially every expression being of a different type. If you pass such an expression to a function taking a parameter of type Matrix, your expression will implicitly be evaluated into a temporary Matrix, which will then be passed to the function. This means that you lose the benefit of expression templates. Concretely, this has two drawbacks: + \li The evaluation into a temporary may be useless and inefficient; + \li This only allows the function to read from the expression, not to write to it. + +Fortunately, all this myriad of expression types have in common that they all inherit a few common, templated base classes. By letting your function take templated parameters of these base types, you can let them play nicely with Eigen's expression templates. + +\eigenAutoToc + +\section TopicFirstExamples Some First Examples + +This section will provide simple examples for different types of objects Eigen is offering. Before starting with the actual examples, we need to recapitulate which base objects we can work with (see also \ref TopicClassHierarchy). + + \li MatrixBase: The common base class for all dense matrix expressions (as opposed to array expressions, as opposed to sparse and special matrix classes). Use it in functions that are meant to work only on dense matrices. + \li ArrayBase: The common base class for all dense array expressions (as opposed to matrix expressions, etc). Use it in functions that are meant to work only on arrays. + \li DenseBase: The common base class for all dense matrix expression, that is, the base class for both \c MatrixBase and \c ArrayBase. It can be used in functions that are meant to work on both matrices and arrays. + \li EigenBase: The base class unifying all types of objects that can be evaluated into dense matrices or arrays, for example special matrix classes such as diagonal matrices, permutation matrices, etc. It can be used in functions that are meant to work on any such general type. + + %EigenBase Example

+Prints the dimensions of the most generic object present in Eigen. It coulde be any matrix expressions, any dense or sparse matrix and any array. + + + +
Example:Output:
+\include function_taking_eigenbase.cpp + +\verbinclude function_taking_eigenbase.out +
+ %DenseBase Example

+Prints a sub-block of the dense expression. Accepts any dense matrix or array expression, but no sparse objects and no special matrix classes such as DiagonalMatrix. +\code +template +void print_block(const DenseBase& b, int x, int y, int r, int c) +{ + std::cout << "block: " << b.block(x,y,r,c) << std::endl; +} +\endcode + %ArrayBase Example

+Prints the maximum coefficient of the array or array-expression. +\code +template +void print_max_coeff(const ArrayBase &a) +{ + std::cout << "max: " << a.maxCoeff() << std::endl; +} +\endcode + %MatrixBase Example

+Prints the inverse condition number of the given matrix or matrix-expression. +\code +template +void print_inv_cond(const MatrixBase& a) +{ + const typename JacobiSVD::SingularValuesType& + sing_vals = a.jacobiSvd().singularValues(); + std::cout << "inv cond: " << sing_vals(sing_vals.size()-1) / sing_vals(0) << std::endl; +} +\endcode + Multiple templated arguments example

+Calculate the Euclidean distance between two points. +\code +template +typename DerivedA::Scalar squaredist(const MatrixBase& p1,const MatrixBase& p2) +{ + return (p1-p2).squaredNorm(); +} +\endcode +Notice that we used two template parameters, one per argument. This permits the function to handle inputs of different types, e.g., +\code +squaredist(v1,2*v2) +\endcode +where the first argument \c v1 is a vector and the second argument \c 2*v2 is an expression. +

+ +These examples are just intended to give the reader a first impression of how functions can be written which take a plain and constant Matrix or Array argument. They are also intended to give the reader an idea about the most common base classes being the optimal candidates for functions. In the next section we will look in more detail at an example and the different ways it can be implemented, while discussing each implementation's problems and advantages. For the discussion below, Matrix and Array as well as MatrixBase and ArrayBase can be exchanged and all arguments still hold. + +\section TopicPlainFunctionsWorking In which cases do functions taking plain Matrix or Array arguments work? + +Let's assume one wants to write a function computing the covariance matrix of two input matrices where each row is an observation. The implementation of this function might look like this +\code +MatrixXf cov(const MatrixXf& x, const MatrixXf& y) +{ + const float num_observations = static_cast(x.rows()); + const RowVectorXf x_mean = x.colwise().sum() / num_observations; + const RowVectorXf y_mean = y.colwise().sum() / num_observations; + return (x.rowwise() - x_mean).transpose() * (y.rowwise() - y_mean) / num_observations; +} +\endcode +and contrary to what one might think at first, this implementation is fine unless you require a genric implementation that works with double matrices too and unless you do not care about temporary objects. Why is that the case? Where are temporaries involved? How can code as given below compile? +\code +MatrixXf x,y,z; +MatrixXf C = cov(x,y+z); +\endcode +In this special case, the example is fine and will be working because both parameters are declared as \e const references. The compiler creates a temporary and evaluates the expression x+z into this temporary. Once the function is processed, the temporary is released and the result is assigned to C. + +\b Note: Functions taking \e const references to Matrix (or Array) can process expressions at the cost of temporaries. + +\section TopicPlainFunctionsFailing In which cases do functions taking a plain Matrix or Array argument fail? + +Here, we consider a slightly modified version of the function given above. This time, we do not want to return the result but pass an additional non-const paramter which allows us to store the result. A first naive implementation might look as follows. +\code +// Note: This code is flawed! +void cov(const MatrixXf& x, const MatrixXf& y, MatrixXf& C) +{ + const float num_observations = static_cast(x.rows()); + const RowVectorXf x_mean = x.colwise().sum() / num_observations; + const RowVectorXf y_mean = y.colwise().sum() / num_observations; + C = (x.rowwise() - x_mean).transpose() * (y.rowwise() - y_mean) / num_observations; +} +\endcode +When trying to execute the following code +\code +MatrixXf C = MatrixXf::Zero(3,6); +cov(x,y, C.block(0,0,3,3)); +\endcode +the compiler will fail, because it is not possible to convert the expression returned by \c MatrixXf::block() into a non-const \c MatrixXf&. This is the case because the compiler wants to protect you from writing your result to a temporary object. In this special case this protection is not intended -- we want to write to a temporary object. So how can we overcome this problem? + +The solution which is preferred at the moment is based on a little \em hack. One needs to pass a const reference to the matrix and internally the constness needs to be cast away. The correct implementation for C98 compliant compilers would be +\code +template +void cov(const MatrixBase& x, const MatrixBase& y, MatrixBase const & C) +{ + typedef typename Derived::Scalar Scalar; + typedef typename internal::plain_row_type::type RowVectorType; + + const Scalar num_observations = static_cast(x.rows()); + + const RowVectorType x_mean = x.colwise().sum() / num_observations; + const RowVectorType y_mean = y.colwise().sum() / num_observations; + + const_cast< MatrixBase& >(C) = + (x.rowwise() - x_mean).transpose() * (y.rowwise() - y_mean) / num_observations; +} +\endcode +The implementation above does now not only work with temporary expressions but it also allows to use the function with matrices of arbitrary floating point scalar types. + +\b Note: The const cast hack will only work with templated functions. It will not work with the MatrixXf implementation because it is not possible to cast a Block expression to a Matrix reference! + + + +\section TopicResizingInGenericImplementations How to resize matrices in generic implementations? + +One might think we are done now, right? This is not completely true because in order for our covariance function to be generically applicable, we want the follwing code to work +\code +MatrixXf x = MatrixXf::Random(100,3); +MatrixXf y = MatrixXf::Random(100,3); +MatrixXf C; +cov(x, y, C); +\endcode +This is not the case anymore, when we are using an implementation taking MatrixBase as a parameter. In general, Eigen supports automatic resizing but it is not possible to do so on expressions. Why should resizing of a matrix Block be allowed? It is a reference to a sub-matrix and we definitely don't want to resize that. So how can we incorporate resizing if we cannot resize on MatrixBase? The solution is to resize the derived object as in this implementation. +\code +template +void cov(const MatrixBase& x, const MatrixBase& y, MatrixBase const & C_) +{ + typedef typename Derived::Scalar Scalar; + typedef typename internal::plain_row_type::type RowVectorType; + + const Scalar num_observations = static_cast(x.rows()); + + const RowVectorType x_mean = x.colwise().sum() / num_observations; + const RowVectorType y_mean = y.colwise().sum() / num_observations; + + MatrixBase& C = const_cast< MatrixBase& >(C_); + + C.derived().resize(x.cols(),x.cols()); // resize the derived object + C = (x.rowwise() - x_mean).transpose() * (y.rowwise() - y_mean) / num_observations; +} +\endcode +This implementation is now working for parameters being expressions and for parameters being matrices and having the wrong size. Resizing the expressions does not do any harm in this case unless they actually require resizing. That means, passing an expression with the wrong dimensions will result in a run-time error (in debug mode only) while passing expressions of the correct size will just work fine. + +\b Note: In the above discussion the terms Matrix and Array and MatrixBase and ArrayBase can be exchanged and all arguments still hold. + +\section TopicSummary Summary + + - To summarize, the implementation of functions taking non-writable (const referenced) objects is not a big issue and does not lead to problematic situations in terms of compiling and running your program. However, a naive implementation is likely to introduce unnecessary temporary objects in your code. In order to avoid evaluating parameters into temporaries, pass them as (const) references to MatrixBase or ArrayBase (so templatize your function). + + - Functions taking writable (non-const) parameters must take const references and cast away constness within the function body. + + - Functions that take as parameters MatrixBase (or ArrayBase) objects, and potentially need to resize them (in the case where they are resizable), must call resize() on the derived class, as returned by derived(). +*/ +} diff --git a/doc/HiPerformance.dox b/doc/HiPerformance.dox new file mode 100644 index 000000000..ab6cdfd44 --- /dev/null +++ b/doc/HiPerformance.dox @@ -0,0 +1,128 @@ + +namespace Eigen { + +/** \page TopicWritingEfficientProductExpression Writing efficient matrix product expressions + +In general achieving good performance with Eigen does no require any special effort: +simply write your expressions in the most high level way. This is especially true +for small fixed size matrices. For large matrices, however, it might be useful to +take some care when writing your expressions in order to minimize useless evaluations +and optimize the performance. +In this page we will give a brief overview of the Eigen's internal mechanism to simplify +and evaluate complex product expressions, and discuss the current limitations. +In particular we will focus on expressions matching level 2 and 3 BLAS routines, i.e, +all kind of matrix products and triangular solvers. + +Indeed, in Eigen we have implemented a set of highly optimized routines which are very similar +to BLAS's ones. Unlike BLAS, those routines are made available to user via a high level and +natural API. Each of these routines can compute in a single evaluation a wide variety of expressions. +Given an expression, the challenge is then to map it to a minimal set of routines. +As explained latter, this mechanism has some limitations, and knowing them will allow +you to write faster code by making your expressions more Eigen friendly. + +\section GEMM General Matrix-Matrix product (GEMM) + +Let's start with the most common primitive: the matrix product of general dense matrices. +In the BLAS world this corresponds to the GEMM routine. Our equivalent primitive can +perform the following operation: +\f$ C.noalias() += \alpha op1(A) op2(B) \f$ +where A, B, and C are column and/or row major matrices (or sub-matrices), +alpha is a scalar value, and op1, op2 can be transpose, adjoint, conjugate, or the identity. +When Eigen detects a matrix product, it analyzes both sides of the product to extract a +unique scalar factor alpha, and for each side, its effective storage order, shape, and conjugation states. +More precisely each side is simplified by iteratively removing trivial expressions such as scalar multiple, +negation and conjugation. Transpose and Block expressions are not evaluated and they only modify the storage order +and shape. All other expressions are immediately evaluated. +For instance, the following expression: +\code m1.noalias() -= s4 * (s1 * m2.adjoint() * (-(s3*m3).conjugate()*s2)) \endcode +is automatically simplified to: +\code m1.noalias() += (s1*s2*conj(s3)*s4) * m2.adjoint() * m3.conjugate() \endcode +which exactly matches our GEMM routine. + +\subsection GEMM_Limitations Limitations +Unfortunately, this simplification mechanism is not perfect yet and not all expressions which could be +handled by a single GEMM-like call are correctly detected. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Not optimal expressionEvaluated asOptimal version (single evaluation)Comments
\code +m1 += m2 * m3; \endcode\code +temp = m2 * m3; +m1 += temp; \endcode\code +m1.noalias() += m2 * m3; \endcodeUse .noalias() to tell Eigen the result and right-hand-sides do not alias. + Otherwise the product m2 * m3 is evaluated into a temporary.
\code +m1.noalias() += s1 * (m2 * m3); \endcodeThis is a special feature of Eigen. Here the product between a scalar + and a matrix product does not evaluate the matrix product but instead it + returns a matrix product expression tracking the scalar scaling factor.
+ Without this optimization, the matrix product would be evaluated into a + temporary as in the next example.
\code +m1.noalias() += (m2 * m3).adjoint(); \endcode\code +temp = m2 * m3; +m1 += temp.adjoint(); \endcode\code +m1.noalias() += m3.adjoint() +* * m2.adjoint(); \endcodeThis is because the product expression has the EvalBeforeNesting bit which + enforces the evaluation of the product by the Tranpose expression.
\code +m1 = m1 + m2 * m3; \endcode\code +temp = m2 * m3; +m1 = m1 + temp; \endcode\code m1.noalias() += m2 * m3; \endcodeHere there is no way to detect at compile time that the two m1 are the same, + and so the matrix product will be immediately evaluated.
\code +m1.noalias() = m4 + m2 * m3; \endcode\code +temp = m2 * m3; +m1 = m4 + temp; \endcode\code +m1 = m4; +m1.noalias() += m2 * m3; \endcodeFirst of all, here the .noalias() in the first expression is useless because + m2*m3 will be evaluated anyway. However, note how this expression can be rewritten + so that no temporary is required. (tip: for very small fixed size matrix + it is slighlty better to rewrite it like this: m1.noalias() = m2 * m3; m1 += m4;
\code +m1.noalias() += (s1*m2).block(..) * m3; \endcode\code +temp = (s1*m2).block(..); +m1 += temp * m3; \endcode\code +m1.noalias() += s1 * m2.block(..) * m3; \endcodeThis is because our expression analyzer is currently not able to extract trivial + expressions nested in a Block expression. Therefore the nested scalar + multiple cannot be properly extracted.
+ +Of course all these remarks hold for all other kind of products involving triangular or selfadjoint matrices. + +*/ + +} diff --git a/doc/I00_CustomizingEigen.dox b/doc/I00_CustomizingEigen.dox deleted file mode 100644 index e42eaa812..000000000 --- a/doc/I00_CustomizingEigen.dox +++ /dev/null @@ -1,188 +0,0 @@ -namespace Eigen { - -/** \page TopicCustomizingEigen Customizing/Extending Eigen - -Eigen can be extended in several ways, for instance, by defining global methods, \ref ExtendingMatrixBase "by adding custom methods to MatrixBase", adding support to \ref CustomScalarType "custom types" etc. - -\eigenAutoToc - -\section ExtendingMatrixBase Extending MatrixBase (and other classes) - -In this section we will see how to add custom methods to MatrixBase. Since all expressions and matrix types inherit MatrixBase, adding a method to MatrixBase make it immediately available to all expressions ! A typical use case is, for instance, to make Eigen compatible with another API. - -You certainly know that in C++ it is not possible to add methods to an existing class. So how that's possible ? Here the trick is to include in the declaration of MatrixBase a file defined by the preprocessor token \c EIGEN_MATRIXBASE_PLUGIN: -\code -class MatrixBase { - // ... - #ifdef EIGEN_MATRIXBASE_PLUGIN - #include EIGEN_MATRIXBASE_PLUGIN - #endif -}; -\endcode -Therefore to extend MatrixBase with your own methods you just have to create a file with your method declaration and define EIGEN_MATRIXBASE_PLUGIN before you include any Eigen's header file. - -You can extend many of the other classes used in Eigen by defining similarly named preprocessor symbols. For instance, define \c EIGEN_ARRAYBASE_PLUGIN if you want to extend the ArrayBase class. A full list of classes that can be extended in this way and the corresponding preprocessor symbols can be found on our page \ref TopicPreprocessorDirectives. - -Here is an example of an extension file for adding methods to MatrixBase: \n -\b MatrixBaseAddons.h -\code -inline Scalar at(uint i, uint j) const { return this->operator()(i,j); } -inline Scalar& at(uint i, uint j) { return this->operator()(i,j); } -inline Scalar at(uint i) const { return this->operator[](i); } -inline Scalar& at(uint i) { return this->operator[](i); } - -inline RealScalar squaredLength() const { return squaredNorm(); } -inline RealScalar length() const { return norm(); } -inline RealScalar invLength(void) const { return fast_inv_sqrt(squaredNorm()); } - -template -inline Scalar squaredDistanceTo(const MatrixBase& other) const -{ return (derived() - other.derived()).squaredNorm(); } - -template -inline RealScalar distanceTo(const MatrixBase& other) const -{ return internal::sqrt(derived().squaredDistanceTo(other)); } - -inline void scaleTo(RealScalar l) { RealScalar vl = norm(); if (vl>1e-9) derived() *= (l/vl); } - -inline Transpose transposed() {return this->transpose();} -inline const Transpose transposed() const {return this->transpose();} - -inline uint minComponentId(void) const { int i; this->minCoeff(&i); return i; } -inline uint maxComponentId(void) const { int i; this->maxCoeff(&i); return i; } - -template -void makeFloor(const MatrixBase& other) { derived() = derived().cwiseMin(other.derived()); } -template -void makeCeil(const MatrixBase& other) { derived() = derived().cwiseMax(other.derived()); } - -const CwiseUnaryOp, Derived> -operator+(const Scalar& scalar) const -{ return CwiseUnaryOp, Derived>(derived(), internal::scalar_add_op(scalar)); } - -friend const CwiseUnaryOp, Derived> -operator+(const Scalar& scalar, const MatrixBase& mat) -{ return CwiseUnaryOp, Derived>(mat.derived(), internal::scalar_add_op(scalar)); } -\endcode - -Then one can the following declaration in the config.h or whatever prerequisites header file of his project: -\code -#define EIGEN_MATRIXBASE_PLUGIN "MatrixBaseAddons.h" -\endcode - -\section InheritingFromMatrix Inheriting from Matrix - -Before inheriting from Matrix, be really, i mean REALLY sure that using -EIGEN_MATRIX_PLUGIN is not what you really want (see previous section). -If you just need to add few members to Matrix, this is the way to go. - -An example of when you actually need to inherit Matrix, is when you have -several layers of heritage such as MyVerySpecificVector1,MyVerySpecificVector1 -> MyVector1 -> Matrix and. -MyVerySpecificVector3,MyVerySpecificVector4 -> MyVector2 -> Matrix. - -In order for your object to work within the %Eigen framework, you need to -define a few members in your inherited class. - -Here is a minimalistic example:\n -\code -class MyVectorType : public Eigen::VectorXd -{ -public: - MyVectorType(void):Eigen::VectorXd() {} - - typedef Eigen::VectorXd Base; - - // This constructor allows you to construct MyVectorType from Eigen expressions - template - MyVectorType(const Eigen::MatrixBase& other) - : Eigen::Vector3d(other) - { } - - // This method allows you to assign Eigen expressions to MyVectorType - template - MyVectorType & operator= (const Eigen::MatrixBase & other) - { - this->Base::operator=(other); - return *this; - } -}; -\endcode - -This is the kind of error you can get if you don't provide those methods -\code -error: no match for ‘operator=’ in ‘delta = -(((Eigen::MatrixBase, 10000, 1, 2, 10000, -1> >*)(& delta)) + 8u)->Eigen::MatrixBase::cwise [with Derived = -Eigen::Matrix, 10000, 1, 2, 10000, -1>]().Eigen::Cwise::operator* [with OtherDerived = -Eigen::Matrix, 10000, 1, 2, 10000, 1>, ExpressionType = -Eigen::Matrix, 10000, 1, 2, 10000, 1>](((const -Eigen::MatrixBase, 10000, 1, 2, 10000, 1> ->&)(((const Eigen::MatrixBase, 10000, 1, ->2, 10000, 1> >*)((const spectral1d*)where)) + 8u)))’ -\endcode - -\anchor user_defined_scalars \section CustomScalarType Using custom scalar types - -By default, Eigen currently supports standard floating-point types (\c float, \c double, \c std::complex, \c std::complex, \c long \c double), as well as all integrale types (e.g., \c int, \c unsigned \c int, \c short, etc.), and \c bool. -On x86-64 systems, \c long \c double permits to locally enforces the use of x87 registers with extended accuracy (in comparison to SSE). - -In order to add support for a custom type \c T you need: --# make sure the common operator (+,-,*,/,etc.) are supported by the type \c T --# add a specialization of struct Eigen::NumTraits (see \ref NumTraits) --# define the math functions that makes sense for your type. This includes standard ones like sqrt, pow, sin, tan, conj, real, imag, etc, as well as abs2 which is Eigen specific. - (see the file Eigen/src/Core/MathFunctions.h) - -The math function should be defined in the same namespace than \c T, or in the \c std namespace though that second appraoch is not recommended. - -Here is a concrete example adding support for the Adolc's \c adouble type. Adolc is an automatic differentiation library. The type \c adouble is basically a real value tracking the values of any number of partial derivatives. - -\code -#ifndef ADOLCSUPPORT_H -#define ADOLCSUPPORT_H - -#define ADOLC_TAPELESS -#include -#include - -namespace Eigen { - -template<> struct NumTraits - : NumTraits // permits to get the epsilon, dummy_precision, lowest, highest functions -{ - typedef adtl::adouble Real; - typedef adtl::adouble NonInteger; - typedef adtl::adouble Nested; - - enum { - IsComplex = 0, - IsInteger = 0, - IsSigned = 1, - RequireInitialization = 1, - ReadCost = 1, - AddCost = 3, - MulCost = 3 - }; -}; - -} - -namespace adtl { - -inline const adouble& conj(const adouble& x) { return x; } -inline const adouble& real(const adouble& x) { return x; } -inline adouble imag(const adouble&) { return 0.; } -inline adouble abs(const adouble& x) { return fabs(x); } -inline adouble abs2(const adouble& x) { return x*x; } - -} - -#endif // ADOLCSUPPORT_H -\endcode - - -\sa \ref TopicPreprocessorDirectives - -*/ - -} diff --git a/doc/I01_TopicLazyEvaluation.dox b/doc/I01_TopicLazyEvaluation.dox deleted file mode 100644 index 393bc41d8..000000000 --- a/doc/I01_TopicLazyEvaluation.dox +++ /dev/null @@ -1,65 +0,0 @@ -namespace Eigen { - -/** \page TopicLazyEvaluation Lazy Evaluation and Aliasing - -Executive summary: Eigen has intelligent compile-time mechanisms to enable lazy evaluation and removing temporaries where appropriate. -It will handle aliasing automatically in most cases, for example with matrix products. The automatic behavior can be overridden -manually by using the MatrixBase::eval() and MatrixBase::noalias() methods. - -When you write a line of code involving a complex expression such as - -\code mat1 = mat2 + mat3 * (mat4 + mat5); \endcode - -Eigen determines automatically, for each sub-expression, whether to evaluate it into a temporary variable. Indeed, in certain cases it is better to evaluate immediately a sub-expression into a temporary variable, while in other cases it is better to avoid that. - -A traditional math library without expression templates always evaluates all sub-expressions into temporaries. So with this code, - -\code vec1 = vec2 + vec3; \endcode - -a traditional library would evaluate \c vec2 + vec3 into a temporary \c vec4 and then copy \c vec4 into \c vec1. This is of course inefficient: the arrays are traversed twice, so there are a lot of useless load/store operations. - -Expression-templates-based libraries can avoid evaluating sub-expressions into temporaries, which in many cases results in large speed improvements. This is called lazy evaluation as an expression is getting evaluated as late as possible, instead of immediately. However, most other expression-templates-based libraries always choose lazy evaluation. There are two problems with that: first, lazy evaluation is not always a good choice for performance; second, lazy evaluation can be very dangerous, for example with matrix products: doing matrix = matrix*matrix gives a wrong result if the matrix product is lazy-evaluated, because of the way matrix product works. - -For these reasons, Eigen has intelligent compile-time mechanisms to determine automatically when to use lazy evaluation, and when on the contrary it should evaluate immediately into a temporary variable. - -So in the basic example, - -\code matrix1 = matrix2 + matrix3; \endcode - -Eigen chooses lazy evaluation. Thus the arrays are traversed only once, producing optimized code. If you really want to force immediate evaluation, use \link MatrixBase::eval() eval()\endlink: - -\code matrix1 = (matrix2 + matrix3).eval(); \endcode - -Here is now a more involved example: - -\code matrix1 = -matrix2 + matrix3 + 5 * matrix4; \endcode - -Eigen chooses lazy evaluation at every stage in that example, which is clearly the correct choice. In fact, lazy evaluation is the "default choice" and Eigen will choose it except in a few circumstances. - -The first circumstance in which Eigen chooses immediate evaluation, is when it sees an assignment a = b; and the expression \c b has the evaluate-before-assigning \link flags flag\endlink. The most important example of such an expression is the \link GeneralProduct matrix product expression\endlink. For example, when you do - -\code matrix = matrix * matrix; \endcode - -Eigen first evaluates matrix * matrix into a temporary matrix, and then copies it into the original \c matrix. This guarantees a correct result as we saw above that lazy evaluation gives wrong results with matrix products. It also doesn't cost much, as the cost of the matrix product itself is much higher. - -What if you know that the result does no alias the operand of the product and want to force lazy evaluation? Then use \link MatrixBase::noalias() .noalias()\endlink instead. Here is an example: - -\code matrix1.noalias() = matrix2 * matrix2; \endcode - -Here, since we know that matrix2 is not the same matrix as matrix1, we know that lazy evaluation is not dangerous, so we may force lazy evaluation. Concretely, the effect of noalias() here is to bypass the evaluate-before-assigning \link flags flag\endlink. - -The second circumstance in which Eigen chooses immediate evaluation, is when it sees a nested expression such as a + b where \c b is already an expression having the evaluate-before-nesting \link flags flag\endlink. Again, the most important example of such an expression is the \link GeneralProduct matrix product expression\endlink. For example, when you do - -\code matrix1 = matrix2 + matrix3 * matrix4; \endcode - -the product matrix3 * matrix4 gets evaluated immediately into a temporary matrix. Indeed, experiments showed that it is often beneficial for performance to evaluate immediately matrix products when they are nested into bigger expressions. - -The third circumstance in which Eigen chooses immediate evaluation, is when its cost model shows that the total cost of an operation is reduced if a sub-expression gets evaluated into a temporary. Indeed, in certain cases, an intermediate result is sufficiently costly to compute and is reused sufficiently many times, that is worth "caching". Here is an example: - -\code matrix1 = matrix2 * (matrix3 + matrix4); \endcode - -Here, provided the matrices have at least 2 rows and 2 columns, each coefficienct of the expression matrix3 + matrix4 is going to be used several times in the matrix product. Instead of computing the sum everytime, it is much better to compute it once and store it in a temporary variable. Eigen understands this and evaluates matrix3 + matrix4 into a temporary variable before evaluating the product. - -*/ - -} diff --git a/doc/I02_HiPerformance.dox b/doc/I02_HiPerformance.dox deleted file mode 100644 index ab6cdfd44..000000000 --- a/doc/I02_HiPerformance.dox +++ /dev/null @@ -1,128 +0,0 @@ - -namespace Eigen { - -/** \page TopicWritingEfficientProductExpression Writing efficient matrix product expressions - -In general achieving good performance with Eigen does no require any special effort: -simply write your expressions in the most high level way. This is especially true -for small fixed size matrices. For large matrices, however, it might be useful to -take some care when writing your expressions in order to minimize useless evaluations -and optimize the performance. -In this page we will give a brief overview of the Eigen's internal mechanism to simplify -and evaluate complex product expressions, and discuss the current limitations. -In particular we will focus on expressions matching level 2 and 3 BLAS routines, i.e, -all kind of matrix products and triangular solvers. - -Indeed, in Eigen we have implemented a set of highly optimized routines which are very similar -to BLAS's ones. Unlike BLAS, those routines are made available to user via a high level and -natural API. Each of these routines can compute in a single evaluation a wide variety of expressions. -Given an expression, the challenge is then to map it to a minimal set of routines. -As explained latter, this mechanism has some limitations, and knowing them will allow -you to write faster code by making your expressions more Eigen friendly. - -\section GEMM General Matrix-Matrix product (GEMM) - -Let's start with the most common primitive: the matrix product of general dense matrices. -In the BLAS world this corresponds to the GEMM routine. Our equivalent primitive can -perform the following operation: -\f$ C.noalias() += \alpha op1(A) op2(B) \f$ -where A, B, and C are column and/or row major matrices (or sub-matrices), -alpha is a scalar value, and op1, op2 can be transpose, adjoint, conjugate, or the identity. -When Eigen detects a matrix product, it analyzes both sides of the product to extract a -unique scalar factor alpha, and for each side, its effective storage order, shape, and conjugation states. -More precisely each side is simplified by iteratively removing trivial expressions such as scalar multiple, -negation and conjugation. Transpose and Block expressions are not evaluated and they only modify the storage order -and shape. All other expressions are immediately evaluated. -For instance, the following expression: -\code m1.noalias() -= s4 * (s1 * m2.adjoint() * (-(s3*m3).conjugate()*s2)) \endcode -is automatically simplified to: -\code m1.noalias() += (s1*s2*conj(s3)*s4) * m2.adjoint() * m3.conjugate() \endcode -which exactly matches our GEMM routine. - -\subsection GEMM_Limitations Limitations -Unfortunately, this simplification mechanism is not perfect yet and not all expressions which could be -handled by a single GEMM-like call are correctly detected. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Not optimal expressionEvaluated asOptimal version (single evaluation)Comments
\code -m1 += m2 * m3; \endcode\code -temp = m2 * m3; -m1 += temp; \endcode\code -m1.noalias() += m2 * m3; \endcodeUse .noalias() to tell Eigen the result and right-hand-sides do not alias. - Otherwise the product m2 * m3 is evaluated into a temporary.
\code -m1.noalias() += s1 * (m2 * m3); \endcodeThis is a special feature of Eigen. Here the product between a scalar - and a matrix product does not evaluate the matrix product but instead it - returns a matrix product expression tracking the scalar scaling factor.
- Without this optimization, the matrix product would be evaluated into a - temporary as in the next example.
\code -m1.noalias() += (m2 * m3).adjoint(); \endcode\code -temp = m2 * m3; -m1 += temp.adjoint(); \endcode\code -m1.noalias() += m3.adjoint() -* * m2.adjoint(); \endcodeThis is because the product expression has the EvalBeforeNesting bit which - enforces the evaluation of the product by the Tranpose expression.
\code -m1 = m1 + m2 * m3; \endcode\code -temp = m2 * m3; -m1 = m1 + temp; \endcode\code m1.noalias() += m2 * m3; \endcodeHere there is no way to detect at compile time that the two m1 are the same, - and so the matrix product will be immediately evaluated.
\code -m1.noalias() = m4 + m2 * m3; \endcode\code -temp = m2 * m3; -m1 = m4 + temp; \endcode\code -m1 = m4; -m1.noalias() += m2 * m3; \endcodeFirst of all, here the .noalias() in the first expression is useless because - m2*m3 will be evaluated anyway. However, note how this expression can be rewritten - so that no temporary is required. (tip: for very small fixed size matrix - it is slighlty better to rewrite it like this: m1.noalias() = m2 * m3; m1 += m4;
\code -m1.noalias() += (s1*m2).block(..) * m3; \endcode\code -temp = (s1*m2).block(..); -m1 += temp * m3; \endcode\code -m1.noalias() += s1 * m2.block(..) * m3; \endcodeThis is because our expression analyzer is currently not able to extract trivial - expressions nested in a Block expression. Therefore the nested scalar - multiple cannot be properly extracted.
- -Of course all these remarks hold for all other kind of products involving triangular or selfadjoint matrices. - -*/ - -} diff --git a/doc/I03_InsideEigenExample.dox b/doc/I03_InsideEigenExample.dox deleted file mode 100644 index ed053c69d..000000000 --- a/doc/I03_InsideEigenExample.dox +++ /dev/null @@ -1,495 +0,0 @@ -namespace Eigen { - -/** \page TopicInsideEigenExample What happens inside Eigen, on a simple example - -\eigenAutoToc - -
- - -Consider the following example program: - -\code -#include - -int main() -{ - int size = 50; - // VectorXf is a vector of floats, with dynamic size. - Eigen::VectorXf u(size), v(size), w(size); - u = v + w; -} -\endcode - -The goal of this page is to understand how Eigen compiles it, assuming that SSE2 vectorization is enabled (GCC option -msse2). - -\section WhyInteresting Why it's interesting - -Maybe you think, that the above example program is so simple, that compiling it shouldn't involve anything interesting. So before starting, let us explain what is nontrivial in compiling it correctly -- that is, producing optimized code -- so that the complexity of Eigen, that we'll explain here, is really useful. - -Look at the line of code -\code - u = v + w; // (*) -\endcode - -The first important thing about compiling it, is that the arrays should be traversed only once, like -\code - for(int i = 0; i < size; i++) u[i] = v[i] + w[i]; -\endcode -The problem is that if we make a naive C++ library where the VectorXf class has an operator+ returning a VectorXf, then the line of code (*) will amount to: -\code - VectorXf tmp = v + w; - VectorXf u = tmp; -\endcode -Obviously, the introduction of the temporary \a tmp here is useless. It has a very bad effect on performance, first because the creation of \a tmp requires a dynamic memory allocation in this context, and second as there are now two for loops: -\code - for(int i = 0; i < size; i++) tmp[i] = v[i] + w[i]; - for(int i = 0; i < size; i++) u[i] = tmp[i]; -\endcode -Traversing the arrays twice instead of once is terrible for performance, as it means that we do many redundant memory accesses. - -The second important thing about compiling the above program, is to make correct use of SSE2 instructions. Notice that Eigen also supports AltiVec and that all the discussion that we make here applies also to AltiVec. - -SSE2, like AltiVec, is a set of instructions allowing to perform computations on packets of 128 bits at once. Since a float is 32 bits, this means that SSE2 instructions can handle 4 floats at once. This means that, if correctly used, they can make our computation go up to 4x faster. - -However, in the above program, we have chosen size=50, so our vectors consist of 50 float's, and 50 is not a multiple of 4. This means that we cannot hope to do all of that computation using SSE2 instructions. The second best thing, to which we should aim, is to handle the 48 first coefficients with SSE2 instructions, since 48 is the biggest multiple of 4 below 50, and then handle separately, without SSE2, the 49th and 50th coefficients. Something like this: - -\code - for(int i = 0; i < 4*(size/4); i+=4) u.packet(i) = v.packet(i) + w.packet(i); - for(int i = 4*(size/4); i < size; i++) u[i] = v[i] + w[i]; -\endcode - -So let us look line by line at our example program, and let's follow Eigen as it compiles it. - -\section ConstructingVectors Constructing vectors - -Let's analyze the first line: - -\code - Eigen::VectorXf u(size), v(size), w(size); -\endcode - -First of all, VectorXf is the following typedef: -\code - typedef Matrix VectorXf; -\endcode - -The class template Matrix is declared in src/Core/util/ForwardDeclarations.h with 6 template parameters, but the last 3 are automatically determined by the first 3. So you don't need to worry about them for now. Here, Matrix\ means a matrix of floats, with a dynamic number of rows and 1 column. - -The Matrix class inherits a base class, MatrixBase. Don't worry about it, for now it suffices to say that MatrixBase is what unifies matrices/vectors and all the expressions types -- more on that below. - -When we do -\code - Eigen::VectorXf u(size); -\endcode -the constructor that is called is Matrix::Matrix(int), in src/Core/Matrix.h. Besides some assertions, all it does is to construct the \a m_storage member, which is of type DenseStorage\. - -You may wonder, isn't it overengineering to have the storage in a separate class? The reason is that the Matrix class template covers all kinds of matrices and vector: both fixed-size and dynamic-size. The storage method is not the same in these two cases. For fixed-size, the matrix coefficients are stored as a plain member array. For dynamic-size, the coefficients will be stored as a pointer to a dynamically-allocated array. Because of this, we need to abstract storage away from the Matrix class. That's DenseStorage. - -Let's look at this constructor, in src/Core/DenseStorage.h. You can see that there are many partial template specializations of DenseStorages here, treating separately the cases where dimensions are Dynamic or fixed at compile-time. The partial specialization that we are looking at is: -\code -template class DenseStorage -\endcode - -Here, the constructor called is DenseStorage::DenseStorage(int size, int rows, int columns) -with size=50, rows=50, columns=1. - -Here is this constructor: -\code -inline DenseStorage(int size, int rows, int) : m_data(internal::aligned_new(size)), m_rows(rows) {} -\endcode - -Here, the \a m_data member is the actual array of coefficients of the matrix. As you see, it is dynamically allocated. Rather than calling new[] or malloc(), as you can see, we have our own internal::aligned_new defined in src/Core/util/Memory.h. What it does is that if vectorization is enabled, then it uses a platform-specific call to allocate a 128-bit-aligned array, as that is very useful for vectorization with both SSE2 and AltiVec. If vectorization is disabled, it amounts to the standard new[]. - -As you can see, the constructor also sets the \a m_rows member to \a size. Notice that there is no \a m_columns member: indeed, in this partial specialization of DenseStorage, we know the number of columns at compile-time, since the _Cols template parameter is different from Dynamic. Namely, in our case, _Cols is 1, which is to say that our vector is just a matrix with 1 column. Hence, there is no need to store the number of columns as a runtime variable. - -When you call VectorXf::data() to get the pointer to the array of coefficients, it returns DenseStorage::data() which returns the \a m_data member. - -When you call VectorXf::size() to get the size of the vector, this is actually a method in the base class MatrixBase. It determines that the vector is a column-vector, since ColsAtCompileTime==1 (this comes from the template parameters in the typedef VectorXf). It deduces that the size is the number of rows, so it returns VectorXf::rows(), which returns DenseStorage::rows(), which returns the \a m_rows member, which was set to \a size by the constructor. - -\section ConstructionOfSumXpr Construction of the sum expression - -Now that our vectors are constructed, let's move on to the next line: - -\code -u = v + w; -\endcode - -The executive summary is that operator+ returns a "sum of vectors" expression, but doesn't actually perform the computation. It is the operator=, whose call occurs thereafter, that does the computation. - -Let us now see what Eigen does when it sees this: - -\code -v + w -\endcode - -Here, v and w are of type VectorXf, which is a typedef for a specialization of Matrix (as we explained above), which is a subclass of MatrixBase. So what is being called is - -\code -MatrixBase::operator+(const MatrixBase&) -\endcode - -The return type of this operator is -\code -CwiseBinaryOp, VectorXf, VectorXf> -\endcode -The CwiseBinaryOp class is our first encounter with an expression template. As we said, the operator+ doesn't by itself perform any computation, it just returns an abstract "sum of vectors" expression. Since there are also "difference of vectors" and "coefficient-wise product of vectors" expressions, we unify them all as "coefficient-wise binary operations", which we abbreviate as "CwiseBinaryOp". "Coefficient-wise" means that the operations is performed coefficient by coefficient. "binary" means that there are two operands -- we are adding two vectors with one another. - -Now you might ask, what if we did something like - -\code -v + w + u; -\endcode - -The first v + w would return a CwiseBinaryOp as above, so in order for this to compile, we'd need to define an operator+ also in the class CwiseBinaryOp... at this point it starts looking like a nightmare: are we going to have to define all operators in each of the expression classes (as you guessed, CwiseBinaryOp is only one of many) ? This looks like a dead end! - -The solution is that CwiseBinaryOp itself, as well as Matrix and all the other expression types, is a subclass of MatrixBase. So it is enough to define once and for all the operators in class MatrixBase. - -Since MatrixBase is the common base class of different subclasses, the aspects that depend on the subclass must be abstracted from MatrixBase. This is called polymorphism. - -The classical approach to polymorphism in C++ is by means of virtual functions. This is dynamic polymorphism. Here we don't want dynamic polymorphism because the whole design of Eigen is based around the assumption that all the complexity, all the abstraction, gets resolved at compile-time. This is crucial: if the abstraction can't get resolved at compile-time, Eigen's compile-time optimization mechanisms become useless, not to mention that if that abstraction has to be resolved at runtime it'll incur an overhead by itself. - -Here, what we want is to have a single class MatrixBase as the base of many subclasses, in such a way that each MatrixBase object (be it a matrix, or vector, or any kind of expression) knows at compile-time (as opposed to run-time) of which particular subclass it is an object (i.e. whether it is a matrix, or an expression, and what kind of expression). - -The solution is the Curiously Recurring Template Pattern. Let's do the break now. Hopefully you can read this wikipedia page during the break if needed, but it won't be allowed during the exam. - -In short, MatrixBase takes a template parameter \a Derived. Whenever we define a subclass Subclass, we actually make Subclass inherit MatrixBase\. The point is that different subclasses inherit different MatrixBase types. Thanks to this, whenever we have an object of a subclass, and we call on it some MatrixBase method, we still remember even from inside the MatrixBase method which particular subclass we're talking about. - -This means that we can put almost all the methods and operators in the base class MatrixBase, and have only the bare minimum in the subclasses. If you look at the subclasses in Eigen, like for instance the CwiseBinaryOp class, they have very few methods. There are coeff() and sometimes coeffRef() methods for access to the coefficients, there are rows() and cols() methods returning the number of rows and columns, but there isn't much more than that. All the meat is in MatrixBase, so it only needs to be coded once for all kinds of expressions, matrices, and vectors. - -So let's end this digression and come back to the piece of code from our example program that we were currently analyzing, - -\code -v + w -\endcode - -Now that MatrixBase is a good friend, let's write fully the prototype of the operator+ that gets called here (this code is from src/Core/MatrixBase.h): - -\code -template -class MatrixBase -{ - // ... - - template - const CwiseBinaryOp::Scalar>, Derived, OtherDerived> - operator+(const MatrixBase &other) const; - - // ... -}; -\endcode - -Here of course, \a Derived and \a OtherDerived are VectorXf. - -As we said, CwiseBinaryOp is also used for other operations such as substration, so it takes another template parameter determining the operation that will be applied to coefficients. This template parameter is a functor, that is, a class in which we have an operator() so it behaves like a function. Here, the functor used is internal::scalar_sum_op. It is defined in src/Core/Functors.h. - -Let us now explain the internal::traits here. The internal::scalar_sum_op class takes one template parameter: the type of the numbers to handle. Here of course we want to pass the scalar type (a.k.a. numeric type) of VectorXf, which is \c float. How do we determine which is the scalar type of \a Derived ? Throughout Eigen, all matrix and expression types define a typedef \a Scalar which gives its scalar type. For example, VectorXf::Scalar is a typedef for \c float. So here, if life was easy, we could find the numeric type of \a Derived as just -\code -typename Derived::Scalar -\endcode -Unfortunately, we can't do that here, as the compiler would complain that the type Derived hasn't yet been defined. So we use a workaround: in src/Core/util/ForwardDeclarations.h, we declared (not defined!) all our subclasses, like Matrix, and we also declared the following class template: -\code -template struct internal::traits; -\endcode -In src/Core/Matrix.h, right \em before the definition of class Matrix, we define a partial specialization of internal::traits for T=Matrix\. In this specialization of internal::traits, we define the Scalar typedef. So when we actually define Matrix, it is legal to refer to "typename internal::traits\::Scalar". - -Anyway, we have declared our operator+. In our case, where \a Derived and \a OtherDerived are VectorXf, the above declaration amounts to: -\code -class MatrixBase -{ - // ... - - const CwiseBinaryOp, VectorXf, VectorXf> - operator+(const MatrixBase &other) const; - - // ... -}; -\endcode - -Let's now jump to src/Core/CwiseBinaryOp.h to see how it is defined. As you can see there, all it does is to return a CwiseBinaryOp object, and this object is just storing references to the left-hand-side and right-hand-side expressions -- here, these are the vectors \a v and \a w. Well, the CwiseBinaryOp object is also storing an instance of the (empty) functor class, but you shouldn't worry about it as that is a minor implementation detail. - -Thus, the operator+ hasn't performed any actual computation. To summarize, the operation \a v + \a w just returned an object of type CwiseBinaryOp which did nothing else than just storing references to \a v and \a w. - -\section Assignment The assignment - -At this point, the expression \a v + \a w has finished evaluating, so, in the process of compiling the line of code -\code -u = v + w; -\endcode -we now enter the operator=. - -What operator= is being called here? The vector u is an object of class VectorXf, i.e. Matrix. In src/Core/Matrix.h, inside the definition of class Matrix, we see this: -\code - template - inline Matrix& operator=(const MatrixBase& other) - { - eigen_assert(m_storage.data()!=0 && "you cannot use operator= with a non initialized matrix (instead use set()"); - return Base::operator=(other.derived()); - } -\endcode -Here, Base is a typedef for MatrixBase\. So, what is being called is the operator= of MatrixBase. Let's see its prototype in src/Core/MatrixBase.h: -\code - template - Derived& operator=(const MatrixBase& other); -\endcode -Here, \a Derived is VectorXf (since u is a VectorXf) and \a OtherDerived is CwiseBinaryOp. More specifically, as explained in the previous section, \a OtherDerived is: -\code -CwiseBinaryOp, VectorXf, VectorXf> -\endcode -So the full prototype of the operator= being called is: -\code -VectorXf& MatrixBase::operator=(const MatrixBase, VectorXf, VectorXf> > & other); -\endcode -This operator= literally reads "copying a sum of two VectorXf's into another VectorXf". - -Let's now look at the implementation of this operator=. It resides in the file src/Core/Assign.h. - -What we can see there is: -\code -template -template -inline Derived& MatrixBase - ::operator=(const MatrixBase& other) -{ - return internal::assign_selector::run(derived(), other.derived()); -} -\endcode - -OK so our next task is to understand internal::assign_selector :) - -Here is its declaration (all that is still in the same file src/Core/Assign.h) -\code -template -struct internal::assign_selector; -\endcode - -So internal::assign_selector takes 4 template parameters, but the 2 last ones are automatically determined by the 2 first ones. - -EvalBeforeAssigning is here to enforce the EvalBeforeAssigningBit. As explained here, certain expressions have this flag which makes them automatically evaluate into temporaries before assigning them to another expression. This is the case of the Product expression, in order to avoid strange aliasing effects when doing "m = m * m;" However, of course here our CwiseBinaryOp expression doesn't have the EvalBeforeAssigningBit: we said since the beginning that we didn't want a temporary to be introduced here. So if you go to src/Core/CwiseBinaryOp.h, you'll see that the Flags in internal::traits\ don't include the EvalBeforeAssigningBit. The Flags member of CwiseBinaryOp is then imported from the internal::traits by the EIGEN_GENERIC_PUBLIC_INTERFACE macro. Anyway, here the template parameter EvalBeforeAssigning has the value \c false. - -NeedToTranspose is here for the case where the user wants to copy a row-vector into a column-vector. We allow this as a special exception to the general rule that in assignments we require the dimesions to match. Anyway, here both the left-hand and right-hand sides are column vectors, in the sense that ColsAtCompileTime is equal to 1. So NeedToTranspose is \c false too. - -So, here we are in the partial specialization: -\code -internal::assign_selector -\endcode - -Here's how it is defined: -\code -template -struct internal::assign_selector { - static Derived& run(Derived& dst, const OtherDerived& other) { return dst.lazyAssign(other.derived()); } -}; -\endcode - -OK so now our next job is to understand how lazyAssign works :) - -\code -template -template -inline Derived& MatrixBase - ::lazyAssign(const MatrixBase& other) -{ - EIGEN_STATIC_ASSERT_SAME_MATRIX_SIZE(Derived,OtherDerived) - eigen_assert(rows() == other.rows() && cols() == other.cols()); - internal::assign_impl::run(derived(),other.derived()); - return derived(); -} -\endcode - -What do we see here? Some assertions, and then the only interesting line is: -\code - internal::assign_impl::run(derived(),other.derived()); -\endcode - -OK so now we want to know what is inside internal::assign_impl. - -Here is its declaration: -\code -template::Vectorization, - int Unrolling = internal::assign_traits::Unrolling> -struct internal::assign_impl; -\endcode -Again, internal::assign_selector takes 4 template parameters, but the 2 last ones are automatically determined by the 2 first ones. - -These two parameters \a Vectorization and \a Unrolling are determined by a helper class internal::assign_traits. Its job is to determine which vectorization strategy to use (that is \a Vectorization) and which unrolling strategy to use (that is \a Unrolling). - -We'll not enter into the details of how these strategies are chosen (this is in the implementation of internal::assign_traits at the top of the same file). Let's just say that here \a Vectorization has the value \a LinearVectorization, and \a Unrolling has the value \a NoUnrolling (the latter is obvious since our vectors have dynamic size so there's no way to unroll the loop at compile-time). - -So the partial specialization of internal::assign_impl that we're looking at is: -\code -internal::assign_impl -\endcode - -Here is how it's defined: -\code -template -struct internal::assign_impl -{ - static void run(Derived1 &dst, const Derived2 &src) - { - const int size = dst.size(); - const int packetSize = internal::packet_traits::size; - const int alignedStart = internal::assign_traits::DstIsAligned ? 0 - : internal::first_aligned(&dst.coeffRef(0), size); - const int alignedEnd = alignedStart + ((size-alignedStart)/packetSize)*packetSize; - - for(int index = 0; index < alignedStart; index++) - dst.copyCoeff(index, src); - - for(int index = alignedStart; index < alignedEnd; index += packetSize) - { - dst.template copyPacket::SrcAlignment>(index, src); - } - - for(int index = alignedEnd; index < size; index++) - dst.copyCoeff(index, src); - } -}; -\endcode - -Here's how it works. \a LinearVectorization means that the left-hand and right-hand side expression can be accessed linearly i.e. you can refer to their coefficients by one integer \a index, as opposed to having to refer to its coefficients by two integers \a row, \a column. - -As we said at the beginning, vectorization works with blocks of 4 floats. Here, \a PacketSize is 4. - -There are two potential problems that we need to deal with: -\li first, vectorization works much better if the packets are 128-bit-aligned. This is especially important for write access. So when writing to the coefficients of \a dst, we want to group these coefficients by packets of 4 such that each of these packets is 128-bit-aligned. In general, this requires to skip a few coefficients at the beginning of \a dst. This is the purpose of \a alignedStart. We then copy these first few coefficients one by one, not by packets. However, in our case, the \a dst expression is a VectorXf and remember that in the construction of the vectors we allocated aligned arrays. Thanks to \a DstIsAligned, Eigen remembers that without having to do any runtime check, so \a alignedStart is zero and this part is avoided altogether. -\li second, the number of coefficients to copy is not in general a multiple of \a packetSize. Here, there are 50 coefficients to copy and \a packetSize is 4. So we'll have to copy the last 2 coefficients one by one, not by packets. Here, \a alignedEnd is 48. - -Now come the actual loops. - -First, the vectorized part: the 48 first coefficients out of 50 will be copied by packets of 4: -\code - for(int index = alignedStart; index < alignedEnd; index += packetSize) - { - dst.template copyPacket::SrcAlignment>(index, src); - } -\endcode - -What is copyPacket? It is defined in src/Core/Coeffs.h: -\code -template -template -inline void MatrixBase::copyPacket(int index, const MatrixBase& other) -{ - eigen_internal_assert(index >= 0 && index < size()); - derived().template writePacket(index, - other.derived().template packet(index)); -} -\endcode - -OK, what are writePacket() and packet() here? - -First, writePacket() here is a method on the left-hand side VectorXf. So we go to src/Core/Matrix.h to look at its definition: -\code -template -inline void writePacket(int index, const PacketScalar& x) -{ - internal::pstoret(m_storage.data() + index, x); -} -\endcode -Here, \a StoreMode is \a #Aligned, indicating that we are doing a 128-bit-aligned write access, \a PacketScalar is a type representing a "SSE packet of 4 floats" and internal::pstoret is a function writing such a packet in memory. Their definitions are architecture-specific, we find them in src/Core/arch/SSE/PacketMath.h: - -The line in src/Core/arch/SSE/PacketMath.h that determines the PacketScalar type (via a typedef in Matrix.h) is: -\code -template<> struct internal::packet_traits { typedef __m128 type; enum {size=4}; }; -\endcode -Here, __m128 is a SSE-specific type. Notice that the enum \a size here is what was used to define \a packetSize above. - -And here is the implementation of internal::pstoret: -\code -template<> inline void internal::pstore(float* to, const __m128& from) { _mm_store_ps(to, from); } -\endcode -Here, __mm_store_ps is a SSE-specific intrinsic function, representing a single SSE instruction. The difference between internal::pstore and internal::pstoret is that internal::pstoret is a dispatcher handling both the aligned and unaligned cases, you find its definition in src/Core/GenericPacketMath.h: -\code -template -inline void internal::pstoret(Scalar* to, const Packet& from) -{ - if(LoadMode == Aligned) - internal::pstore(to, from); - else - internal::pstoreu(to, from); -} -\endcode - -OK, that explains how writePacket() works. Now let's look into the packet() call. Remember that we are analyzing this line of code inside copyPacket(): -\code -derived().template writePacket(index, - other.derived().template packet(index)); -\endcode - -Here, \a other is our sum expression \a v + \a w. The .derived() is just casting from MatrixBase to the subclass which here is CwiseBinaryOp. So let's go to src/Core/CwiseBinaryOp.h: -\code -class CwiseBinaryOp -{ - // ... - template - inline PacketScalar packet(int index) const - { - return m_functor.packetOp(m_lhs.template packet(index), m_rhs.template packet(index)); - } -}; -\endcode -Here, \a m_lhs is the vector \a v, and \a m_rhs is the vector \a w. So the packet() function here is Matrix::packet(). The template parameter \a LoadMode is \a #Aligned. So we're looking at -\code -class Matrix -{ - // ... - template - inline PacketScalar packet(int index) const - { - return internal::ploadt(m_storage.data() + index); - } -}; -\endcode -We let you look up the definition of internal::ploadt in GenericPacketMath.h and the internal::pload in src/Core/arch/SSE/PacketMath.h. It is very similar to the above for internal::pstore. - -Let's go back to CwiseBinaryOp::packet(). Once the packets from the vectors \a v and \a w have been returned, what does this function do? It calls m_functor.packetOp() on them. What is m_functor? Here we must remember what particular template specialization of CwiseBinaryOp we're dealing with: -\code -CwiseBinaryOp, VectorXf, VectorXf> -\endcode -So m_functor is an object of the empty class internal::scalar_sum_op. As we mentioned above, don't worry about why we constructed an object of this empty class at all -- it's an implementation detail, the point is that some other functors need to store member data. - -Anyway, internal::scalar_sum_op is defined in src/Core/Functors.h: -\code -template struct internal::scalar_sum_op EIGEN_EMPTY_STRUCT { - inline const Scalar operator() (const Scalar& a, const Scalar& b) const { return a + b; } - template - inline const PacketScalar packetOp(const PacketScalar& a, const PacketScalar& b) const - { return internal::padd(a,b); } -}; -\endcode -As you can see, all what packetOp() does is to call internal::padd on the two packets. Here is the definition of internal::padd from src/Core/arch/SSE/PacketMath.h: -\code -template<> inline __m128 internal::padd(const __m128& a, const __m128& b) { return _mm_add_ps(a,b); } -\endcode -Here, _mm_add_ps is a SSE-specific intrinsic function, representing a single SSE instruction. - -To summarize, the loop -\code - for(int index = alignedStart; index < alignedEnd; index += packetSize) - { - dst.template copyPacket::SrcAlignment>(index, src); - } -\endcode -has been compiled to the following code: for \a index going from 0 to the 11 ( = 48/4 - 1), read the i-th packet (of 4 floats) from the vector v and the i-th packet from the vector w using two __mm_load_ps SSE instructions, then add them together using a __mm_add_ps instruction, then store the result using a __mm_store_ps instruction. - -There remains the second loop handling the last few (here, the last 2) coefficients: -\code - for(int index = alignedEnd; index < size; index++) - dst.copyCoeff(index, src); -\endcode -However, it works just like the one we just explained, it is just simpler because there is no SSE vectorization involved here. copyPacket() becomes copyCoeff(), packet() becomes coeff(), writePacket() becomes coeffRef(). If you followed us this far, you can probably understand this part by yourself. - -We see that all the C++ abstraction of Eigen goes away during compilation and that we indeed are precisely controlling which assembly instructions we emit. Such is the beauty of C++! Since we have such precise control over the emitted assembly instructions, but such complex logic to choose the right instructions, we can say that Eigen really behaves like an optimizing compiler. If you prefer, you could say that Eigen behaves like a script for the compiler. In a sense, C++ template metaprogramming is scripting the compiler -- and it's been shown that this scripting language is Turing-complete. See Wikipedia. - -*/ - -} diff --git a/doc/I05_FixedSizeVectorizable.dox b/doc/I05_FixedSizeVectorizable.dox deleted file mode 100644 index 8ae135173..000000000 --- a/doc/I05_FixedSizeVectorizable.dox +++ /dev/null @@ -1,38 +0,0 @@ -namespace Eigen { - -/** \eigenManualPage TopicFixedSizeVectorizable Fixed-size vectorizable Eigen objects - -The goal of this page is to explain what we mean by "fixed-size vectorizable". - -\section summary Executive Summary - -An Eigen object is called "fixed-size vectorizable" if it has fixed size and that size is a multiple of 16 bytes. - -Examples include: -\li Eigen::Vector2d -\li Eigen::Vector4d -\li Eigen::Vector4f -\li Eigen::Matrix2d -\li Eigen::Matrix2f -\li Eigen::Matrix4d -\li Eigen::Matrix4f -\li Eigen::Affine3d -\li Eigen::Affine3f -\li Eigen::Quaterniond -\li Eigen::Quaternionf - -\section explanation Explanation - -First, "fixed-size" should be clear: an Eigen object has fixed size if its number of rows and its number of columns are fixed at compile-time. So for example Matrix3f has fixed size, but MatrixXf doesn't (the opposite of fixed-size is dynamic-size). - -The array of coefficients of a fixed-size Eigen object is a plain "static array", it is not dynamically allocated. For example, the data behind a Matrix4f is just a "float array[16]". - -Fixed-size objects are typically very small, which means that we want to handle them with zero runtime overhead -- both in terms of memory usage and of speed. - -Now, vectorization (both SSE and AltiVec) works with 128-bit packets. Moreover, for performance reasons, these packets need to be have 128-bit alignment. - -So it turns out that the only way that fixed-size Eigen objects can be vectorized, is if their size is a multiple of 128 bits, or 16 bytes. Eigen will then request 16-byte alignment for these objects, and henceforth rely on these objects being aligned so no runtime check for alignment is performed. - -*/ - -} diff --git a/doc/I06_TopicEigenExpressionTemplates.dox b/doc/I06_TopicEigenExpressionTemplates.dox deleted file mode 100644 index b31fd47f9..000000000 --- a/doc/I06_TopicEigenExpressionTemplates.dox +++ /dev/null @@ -1,12 +0,0 @@ -namespace Eigen { - -/** \page TopicEigenExpressionTemplates Expression templates in Eigen - - -TODO: write this dox page! - -Is linked from the tutorial on arithmetic ops. - -*/ - -} diff --git a/doc/I07_TopicScalarTypes.dox b/doc/I07_TopicScalarTypes.dox deleted file mode 100644 index 2ff03c198..000000000 --- a/doc/I07_TopicScalarTypes.dox +++ /dev/null @@ -1,12 +0,0 @@ -namespace Eigen { - -/** \page TopicScalarTypes Scalar types - - -TODO: write this dox page! - -Is linked from the tutorial on the Matrix class. - -*/ - -} diff --git a/doc/I08_Resizing.dox b/doc/I08_Resizing.dox deleted file mode 100644 index c323e17ad..000000000 --- a/doc/I08_Resizing.dox +++ /dev/null @@ -1,11 +0,0 @@ -namespace Eigen { - -/** \page TopicResizing Resizing - - -TODO: write this dox page! - -Is linked from the tutorial on the Matrix class. - -*/ -} diff --git a/doc/I09_Vectorization.dox b/doc/I09_Vectorization.dox deleted file mode 100644 index 274d0451b..000000000 --- a/doc/I09_Vectorization.dox +++ /dev/null @@ -1,9 +0,0 @@ -namespace Eigen { - -/** \page TopicVectorization Vectorization - - -TODO: write this dox page! - -*/ -} diff --git a/doc/I10_Assertions.dox b/doc/I10_Assertions.dox deleted file mode 100644 index 4ead40174..000000000 --- a/doc/I10_Assertions.dox +++ /dev/null @@ -1,108 +0,0 @@ -namespace Eigen { - -/** \page TopicAssertions Assertions - -\eigenAutoToc - -\section PlainAssert Assertions - -The macro eigen_assert is defined to be \c eigen_plain_assert by default. We use eigen_plain_assert instead of \c assert to work around a known bug for GCC <= 4.3. Basically, eigen_plain_assert \a is \c assert. - -\subsection RedefineAssert Redefining assertions - -Both eigen_assert and eigen_plain_assert are defined in Macros.h. Defining eigen_assert indirectly gives you a chance to change its behavior. You can redefine this macro if you want to do something else such as throwing an exception, and fall back to its default behavior with eigen_plain_assert. The code below tells Eigen to throw an std::runtime_error: - -\code -#include -#undef eigen_assert -#define eigen_assert(x) \ - if (!x) { throw (std::runtime_error("Put your message here")); } -\endcode - -\subsection DisableAssert Disabling assertions - -Assertions cost run time and can be turned off. You can suppress eigen_assert by defining \c EIGEN_NO_DEBUG \b before including Eigen headers. \c EIGEN_NO_DEBUG is undefined by default unless \c NDEBUG is defined. - -\section StaticAssert Static assertions - -Static assertions are not standardized until C++11. However, in the Eigen library, there are many conditions can and should be detectedat compile time. For instance, we use static assertions to prevent the code below from compiling. - -\code -Matrix3d() + Matrix4d(); // adding matrices of different sizes -Matrix4cd() * Vector3cd(); // invalid product known at compile time -\endcode - -Static assertions are defined in StaticAssert.h. If there is native static_assert, we use it. Otherwise, we have implemented an assertion macro that can show a limited range of messages. - -One can easily come up with static assertions without messages, such as: - -\code -#define STATIC_ASSERT(x) \ - switch(0) { case 0: case x:; } -\endcode - -However, the example above obviously cannot tell why the assertion failed. Therefore, we define a \c struct in namespace Eigen::internal to handle available messages. - -\code -template -struct static_assertion {}; - -template<> -struct static_assertion -{ - enum { - YOU_TRIED_CALLING_A_VECTOR_METHOD_ON_A_MATRIX, - YOU_MIXED_VECTORS_OF_DIFFERENT_SIZES, - // see StaticAssert.h for all enums. - }; -}; -\endcode - -And then, we define EIGEN_STATIC_ASSERT(CONDITION,MSG) to access Eigen::internal::static_assertion::MSG. If the condition evaluates into \c false, your compiler displays a lot of messages explaining there is no MSG in static_assert. Nevertheless, this is \a not in what we are interested. As you can see, all members of static_assert are ALL_CAPS_AND_THEY_ARE_SHOUTING. - -\warning -When using this macro, MSG should be a member of static_assertion, or the static assertion \b always fails. -Currently, it can only be used in function scope. - -\subsection DerivedStaticAssert Derived static assertions - -There are other macros derived from EIGEN_STATIC_ASSERT to enhance readability. Their names are self-explanatory. - -- \b EIGEN_STATIC_ASSERT_FIXED_SIZE(TYPE) - passes if \a TYPE is fixed size. -- \b EIGEN_STATIC_ASSERT_DYNAMIC_SIZE(TYPE) - passes if \a TYPE is dynamic size. -- \b EIGEN_STATIC_ASSERT_LVALUE(Derived) - failes if \a Derived is read-only. -- \b EIGEN_STATIC_ASSERT_ARRAYXPR(Derived) - passes if \a Derived is an array expression. -- EIGEN_STATIC_ASSERT_SAME_XPR_KIND(Derived1, Derived2) - failes if the two expressions are an array one and a matrix one. - -Because Eigen handles both fixed-size and dynamic-size expressions, some conditions cannot be clearly determined at compile time. We classify them into strict assertions and permissive assertions. - -\subsubsection StrictAssertions Strict assertions - -These assertions fail if the condition may not be met. For example, MatrixXd may not be a vector, so it fails EIGEN_STATIC_ASSERT_VECTOR_ONLY. - -- \b EIGEN_STATIC_ASSERT_VECTOR_ONLY(TYPE) - passes if \a TYPE must be a vector type. -- EIGEN_STATIC_ASSERT_VECTOR_SPECIFIC_SIZE(TYPE, SIZE) - passes if \a TYPE must be a vector of the given size. -- EIGEN_STATIC_ASSERT_MATRIX_SPECIFIC_SIZE(TYPE, ROWS, COLS) - passes if \a TYPE must be a matrix with given rows and columns. - -\subsubsection PermissiveAssertions Permissive assertions - -These assertions fail if the condition \b cannot be met. For example, MatrixXd and Matrix4d may have the same size, so they pass EIGEN_STATIC_ASSERT_SAME_MATRIX_SIZE. - -- \b EIGEN_STATIC_ASSERT_SAME_VECTOR_SIZE(TYPE0,TYPE1) - fails if the two vector expression types must have different sizes. -- \b EIGEN_STATIC_ASSERT_SAME_MATRIX_SIZE(TYPE0,TYPE1) - fails if the two matrix expression types must have different sizes. -- \b EIGEN_STATIC_ASSERT_SIZE_1x1(TYPE) - fails if \a TYPE cannot be an 1x1 expression. - -See StaticAssert.h for details such as what messages they throw. - -\subsection DisableStaticAssert Disabling static assertions - -If \c EIGEN_NO_STATIC_ASSERT is defined, static assertions turn into eigen_assert's, working like: - -\code -#define EIGEN_STATIC_ASSERT(CONDITION,MSG) eigen_assert((CONDITION) && #MSG); -\endcode - -This saves compile time but consumes more run time. \c EIGEN_NO_STATIC_ASSERT is undefined by default. - -*/ -} diff --git a/doc/I11_Aliasing.dox b/doc/I11_Aliasing.dox deleted file mode 100644 index bd1d329ce..000000000 --- a/doc/I11_Aliasing.dox +++ /dev/null @@ -1,209 +0,0 @@ -namespace Eigen { - -/** \eigenManualPage TopicAliasing Aliasing - -In Eigen, aliasing refers to assignment statement in which the same matrix (or array or vector) appears on the -left and on the right of the assignment operators. Statements like mat = 2 * mat; or mat = -mat.transpose(); exhibit aliasing. The aliasing in the first example is harmless, but the aliasing in the -second example leads to unexpected results. This page explains what aliasing is, when it is harmful, and what -to do about it. - -\eigenAutoToc - - -\section TopicAliasingExamples Examples - -Here is a simple example exhibiting aliasing: - - - - -
ExampleOutput
-\include TopicAliasing_block.cpp - -\verbinclude TopicAliasing_block.out -
- -The output is not what one would expect. The problem is the assignment -\code -mat.bottomRightCorner(2,2) = mat.topLeftCorner(2,2); -\endcode -This assignment exhibits aliasing: the coefficient \c mat(1,1) appears both in the block -mat.bottomRightCorner(2,2) on the left-hand side of the assignment and the block -mat.topLeftCorner(2,2) on the right-hand side. After the assignment, the (2,2) entry in the bottom -right corner should have the value of \c mat(1,1) before the assignment, which is 5. However, the output shows -that \c mat(2,2) is actually 1. The problem is that Eigen uses lazy evaluation (see -\ref TopicEigenExpressionTemplates) for mat.topLeftCorner(2,2). The result is similar to -\code -mat(1,1) = mat(0,0); -mat(1,2) = mat(0,1); -mat(2,1) = mat(1,0); -mat(2,2) = mat(1,1); -\endcode -Thus, \c mat(2,2) is assigned the \e new value of \c mat(1,1) instead of the old value. The next section -explains how to solve this problem by calling \link DenseBase::eval() eval()\endlink. - -Note that if \c mat were a bigger, then the blocks would not overlap, and there would be no aliasing -problem. This means that in general aliasing cannot be detected at compile time. However, Eigen does detect -some instances of aliasing, albeit at run time. The following example exhibiting aliasing was mentioned in -\ref TutorialMatrixArithmetic : - - - - -
ExampleOutput
-\include tut_arithmetic_transpose_aliasing.cpp - -\verbinclude tut_arithmetic_transpose_aliasing.out -
- -Again, the output shows the aliasing issue. However, by default Eigen uses a run-time assertion to detect this -and exits with a message like - -\verbatim -void Eigen::DenseBase::checkTransposeAliasing(const OtherDerived&) const -[with OtherDerived = Eigen::Transpose >, Derived = Eigen::Matrix]: -Assertion `(!internal::check_transpose_aliasing_selector::IsTransposed,OtherDerived>::run(internal::extract_data(derived()), other)) -&& "aliasing detected during tranposition, use transposeInPlace() or evaluate the rhs into a temporary using .eval()"' failed. -\endverbatim - -The user can turn Eigen's run-time assertions like the one to detect this aliasing problem off by defining the -EIGEN_NO_DEBUG macro, and the above program was compiled with this macro turned off in order to illustrate the -aliasing problem. See \ref TopicAssertions for more information about Eigen's run-time assertions. - - -\section TopicAliasingSolution Resolving aliasing issues - -If you understand the cause of the aliasing issue, then it is obvious what must happen to solve it: Eigen has -to evaluate the right-hand side fully into a temporary matrix/array and then assign it to the left-hand -side. The function \link DenseBase::eval() eval() \endlink does precisely that. - -For example, here is the corrected version of the first example above: - - - - -
ExampleOutput
-\include TopicAliasing_block_correct.cpp - -\verbinclude TopicAliasing_block_correct.out -
- -Now, \c mat(2,2) equals 5 after the assignment, as it should be. - -The same solution also works for the second example, with the transpose: simply replace the line -a = a.transpose(); with a = a.transpose().eval();. However, in this common case there is a -better solution. Eigen provides the special-purpose function -\link DenseBase::transposeInPlace() transposeInPlace() \endlink which replaces a matrix by its transpose. -This is shown below: - - - - -
ExampleOutput
-\include tut_arithmetic_transpose_inplace.cpp - -\verbinclude tut_arithmetic_transpose_inplace.out -
- -If an xxxInPlace() function is available, then it is best to use it, because it indicates more clearly what you -are doing. This may also allow Eigen to optimize more aggressively. These are some of the xxxInPlace() -functions provided: - - - - - - - - - -
Original functionIn-place function
MatrixBase::adjoint() MatrixBase::adjointInPlace()
DenseBase::reverse() DenseBase::reverseInPlace()
LDLT::solve() LDLT::solveInPlace()
LLT::solve() LLT::solveInPlace()
TriangularView::solve() TriangularView::solveInPlace()
DenseBase::transpose() DenseBase::transposeInPlace()
- - -\section TopicAliasingCwise Aliasing and component-wise operations - -As explained above, it may be dangerous if the same matrix or array occurs on both the left-hand side and the -right-hand side of an assignment operator, and it is then often necessary to evaluate the right-hand side -explicitly. However, applying component-wise operations (such as matrix addition, scalar multiplication and -array multiplication) is safe. - -The following example has only component-wise operations. Thus, there is no need for .eval() even though -the same matrix appears on both sides of the assignments. - - - - -
ExampleOutput
-\include TopicAliasing_cwise.cpp - -\verbinclude TopicAliasing_cwise.out -
- -In general, an assignment is safe if the (i,j) entry of the expression on the right-hand side depends only on -the (i,j) entry of the matrix or array on the left-hand side and not on any other entries. In that case it is -not necessary to evaluate the right-hand side explicitly. - - -\section TopicAliasingMatrixMult Aliasing and matrix multiplication - -Matrix multiplication is the only operation in Eigen that assumes aliasing by default. Thus, if \c matA is a -matrix, then the statement matA = matA * matA; is safe. All other operations in Eigen assume that -there are no aliasing problems, either because the result is assigned to a different matrix or because it is a -component-wise operation. - - - - -
ExampleOutput
-\include TopicAliasing_mult1.cpp - -\verbinclude TopicAliasing_mult1.out -
- -However, this comes at a price. When executing the expression matA = matA * matA, Eigen evaluates the -product in a temporary matrix which is assigned to \c matA after the computation. This is fine. But Eigen does -the same when the product is assigned to a different matrix (e.g., matB = matA * matA). In that case, -it is more efficient to evaluate the product directly into \c matB instead of evaluating it first into a -temporary matrix and copying that matrix to \c matB. - -The user can indicate with the \link MatrixBase::noalias() noalias()\endlink function that there is no -aliasing, as follows: matB.noalias() = matA * matA. This allows Eigen to evaluate the matrix product -matA * matA directly into \c matB. - - - - -
ExampleOutput
-\include TopicAliasing_mult2.cpp - -\verbinclude TopicAliasing_mult2.out -
- -Of course, you should not use \c noalias() when there is in fact aliasing taking place. If you do, then you -may get wrong results: - - - - -
ExampleOutput
-\include TopicAliasing_mult3.cpp - -\verbinclude TopicAliasing_mult3.out -
- - -\section TopicAliasingSummary Summary - -Aliasing occurs when the same matrix or array coefficients appear both on the left- and the right-hand side of -an assignment operator. - - Aliasing is harmless with coefficient-wise computations; this includes scalar multiplication and matrix or - array addition. - - When you multiply two matrices, Eigen assumes that aliasing occurs. If you know that there is no aliasing, - then you can use \link MatrixBase::noalias() noalias()\endlink. - - In all other situations, Eigen assumes that there is no aliasing issue and thus gives the wrong result if - aliasing does in fact occur. To prevent this, you have to use \link DenseBase::eval() eval() \endlink or - one of the xxxInPlace() functions. - -*/ -} diff --git a/doc/I12_ClassHierarchy.dox b/doc/I12_ClassHierarchy.dox deleted file mode 100644 index 468e60a76..000000000 --- a/doc/I12_ClassHierarchy.dox +++ /dev/null @@ -1,129 +0,0 @@ -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: - -
-EigenBase<%Matrix>
-  <-- DenseCoeffsBase<%Matrix>    (direct access case)
-    <-- DenseBase<%Matrix>
-      <-- MatrixBase<%Matrix>
-        <-- PlainObjectBase<%Matrix>    (matrix case)
-          <-- Matrix
-
- -The inheritance diagram for Array looks as follows: - -
-EigenBase<%Array>
-  <-- DenseCoeffsBase<%Array>    (direct access case)
-    <-- DenseBase<%Array>
-      <-- ArrayBase<%Array>
-        <-- PlainObjectBase<%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/I13_FunctionsTakingEigenTypes.dox b/doc/I13_FunctionsTakingEigenTypes.dox deleted file mode 100644 index ad315edf0..000000000 --- a/doc/I13_FunctionsTakingEigenTypes.dox +++ /dev/null @@ -1,183 +0,0 @@ -namespace Eigen { - -/** \page TopicFunctionTakingEigenTypes Writing Functions Taking Eigen Types as Parameters - -Eigen's use of expression templates results in potentially every expression being of a different type. If you pass such an expression to a function taking a parameter of type Matrix, your expression will implicitly be evaluated into a temporary Matrix, which will then be passed to the function. This means that you lose the benefit of expression templates. Concretely, this has two drawbacks: - \li The evaluation into a temporary may be useless and inefficient; - \li This only allows the function to read from the expression, not to write to it. - -Fortunately, all this myriad of expression types have in common that they all inherit a few common, templated base classes. By letting your function take templated parameters of these base types, you can let them play nicely with Eigen's expression templates. - -\eigenAutoToc - -\section TopicFirstExamples Some First Examples - -This section will provide simple examples for different types of objects Eigen is offering. Before starting with the actual examples, we need to recapitulate which base objects we can work with (see also \ref TopicClassHierarchy). - - \li MatrixBase: The common base class for all dense matrix expressions (as opposed to array expressions, as opposed to sparse and special matrix classes). Use it in functions that are meant to work only on dense matrices. - \li ArrayBase: The common base class for all dense array expressions (as opposed to matrix expressions, etc). Use it in functions that are meant to work only on arrays. - \li DenseBase: The common base class for all dense matrix expression, that is, the base class for both \c MatrixBase and \c ArrayBase. It can be used in functions that are meant to work on both matrices and arrays. - \li EigenBase: The base class unifying all types of objects that can be evaluated into dense matrices or arrays, for example special matrix classes such as diagonal matrices, permutation matrices, etc. It can be used in functions that are meant to work on any such general type. - - %EigenBase Example

-Prints the dimensions of the most generic object present in Eigen. It coulde be any matrix expressions, any dense or sparse matrix and any array. - - - -
Example:Output:
-\include function_taking_eigenbase.cpp - -\verbinclude function_taking_eigenbase.out -
- %DenseBase Example

-Prints a sub-block of the dense expression. Accepts any dense matrix or array expression, but no sparse objects and no special matrix classes such as DiagonalMatrix. -\code -template -void print_block(const DenseBase& b, int x, int y, int r, int c) -{ - std::cout << "block: " << b.block(x,y,r,c) << std::endl; -} -\endcode - %ArrayBase Example

-Prints the maximum coefficient of the array or array-expression. -\code -template -void print_max_coeff(const ArrayBase &a) -{ - std::cout << "max: " << a.maxCoeff() << std::endl; -} -\endcode - %MatrixBase Example

-Prints the inverse condition number of the given matrix or matrix-expression. -\code -template -void print_inv_cond(const MatrixBase& a) -{ - const typename JacobiSVD::SingularValuesType& - sing_vals = a.jacobiSvd().singularValues(); - std::cout << "inv cond: " << sing_vals(sing_vals.size()-1) / sing_vals(0) << std::endl; -} -\endcode - Multiple templated arguments example

-Calculate the Euclidean distance between two points. -\code -template -typename DerivedA::Scalar squaredist(const MatrixBase& p1,const MatrixBase& p2) -{ - return (p1-p2).squaredNorm(); -} -\endcode -Notice that we used two template parameters, one per argument. This permits the function to handle inputs of different types, e.g., -\code -squaredist(v1,2*v2) -\endcode -where the first argument \c v1 is a vector and the second argument \c 2*v2 is an expression. -

- -These examples are just intended to give the reader a first impression of how functions can be written which take a plain and constant Matrix or Array argument. They are also intended to give the reader an idea about the most common base classes being the optimal candidates for functions. In the next section we will look in more detail at an example and the different ways it can be implemented, while discussing each implementation's problems and advantages. For the discussion below, Matrix and Array as well as MatrixBase and ArrayBase can be exchanged and all arguments still hold. - -\section TopicPlainFunctionsWorking In which cases do functions taking plain Matrix or Array arguments work? - -Let's assume one wants to write a function computing the covariance matrix of two input matrices where each row is an observation. The implementation of this function might look like this -\code -MatrixXf cov(const MatrixXf& x, const MatrixXf& y) -{ - const float num_observations = static_cast(x.rows()); - const RowVectorXf x_mean = x.colwise().sum() / num_observations; - const RowVectorXf y_mean = y.colwise().sum() / num_observations; - return (x.rowwise() - x_mean).transpose() * (y.rowwise() - y_mean) / num_observations; -} -\endcode -and contrary to what one might think at first, this implementation is fine unless you require a genric implementation that works with double matrices too and unless you do not care about temporary objects. Why is that the case? Where are temporaries involved? How can code as given below compile? -\code -MatrixXf x,y,z; -MatrixXf C = cov(x,y+z); -\endcode -In this special case, the example is fine and will be working because both parameters are declared as \e const references. The compiler creates a temporary and evaluates the expression x+z into this temporary. Once the function is processed, the temporary is released and the result is assigned to C. - -\b Note: Functions taking \e const references to Matrix (or Array) can process expressions at the cost of temporaries. - -\section TopicPlainFunctionsFailing In which cases do functions taking a plain Matrix or Array argument fail? - -Here, we consider a slightly modified version of the function given above. This time, we do not want to return the result but pass an additional non-const paramter which allows us to store the result. A first naive implementation might look as follows. -\code -// Note: This code is flawed! -void cov(const MatrixXf& x, const MatrixXf& y, MatrixXf& C) -{ - const float num_observations = static_cast(x.rows()); - const RowVectorXf x_mean = x.colwise().sum() / num_observations; - const RowVectorXf y_mean = y.colwise().sum() / num_observations; - C = (x.rowwise() - x_mean).transpose() * (y.rowwise() - y_mean) / num_observations; -} -\endcode -When trying to execute the following code -\code -MatrixXf C = MatrixXf::Zero(3,6); -cov(x,y, C.block(0,0,3,3)); -\endcode -the compiler will fail, because it is not possible to convert the expression returned by \c MatrixXf::block() into a non-const \c MatrixXf&. This is the case because the compiler wants to protect you from writing your result to a temporary object. In this special case this protection is not intended -- we want to write to a temporary object. So how can we overcome this problem? - -The solution which is preferred at the moment is based on a little \em hack. One needs to pass a const reference to the matrix and internally the constness needs to be cast away. The correct implementation for C98 compliant compilers would be -\code -template -void cov(const MatrixBase& x, const MatrixBase& y, MatrixBase const & C) -{ - typedef typename Derived::Scalar Scalar; - typedef typename internal::plain_row_type::type RowVectorType; - - const Scalar num_observations = static_cast(x.rows()); - - const RowVectorType x_mean = x.colwise().sum() / num_observations; - const RowVectorType y_mean = y.colwise().sum() / num_observations; - - const_cast< MatrixBase& >(C) = - (x.rowwise() - x_mean).transpose() * (y.rowwise() - y_mean) / num_observations; -} -\endcode -The implementation above does now not only work with temporary expressions but it also allows to use the function with matrices of arbitrary floating point scalar types. - -\b Note: The const cast hack will only work with templated functions. It will not work with the MatrixXf implementation because it is not possible to cast a Block expression to a Matrix reference! - - - -\section TopicResizingInGenericImplementations How to resize matrices in generic implementations? - -One might think we are done now, right? This is not completely true because in order for our covariance function to be generically applicable, we want the follwing code to work -\code -MatrixXf x = MatrixXf::Random(100,3); -MatrixXf y = MatrixXf::Random(100,3); -MatrixXf C; -cov(x, y, C); -\endcode -This is not the case anymore, when we are using an implementation taking MatrixBase as a parameter. In general, Eigen supports automatic resizing but it is not possible to do so on expressions. Why should resizing of a matrix Block be allowed? It is a reference to a sub-matrix and we definitely don't want to resize that. So how can we incorporate resizing if we cannot resize on MatrixBase? The solution is to resize the derived object as in this implementation. -\code -template -void cov(const MatrixBase& x, const MatrixBase& y, MatrixBase const & C_) -{ - typedef typename Derived::Scalar Scalar; - typedef typename internal::plain_row_type::type RowVectorType; - - const Scalar num_observations = static_cast(x.rows()); - - const RowVectorType x_mean = x.colwise().sum() / num_observations; - const RowVectorType y_mean = y.colwise().sum() / num_observations; - - MatrixBase& C = const_cast< MatrixBase& >(C_); - - C.derived().resize(x.cols(),x.cols()); // resize the derived object - C = (x.rowwise() - x_mean).transpose() * (y.rowwise() - y_mean) / num_observations; -} -\endcode -This implementation is now working for parameters being expressions and for parameters being matrices and having the wrong size. Resizing the expressions does not do any harm in this case unless they actually require resizing. That means, passing an expression with the wrong dimensions will result in a run-time error (in debug mode only) while passing expressions of the correct size will just work fine. - -\b Note: In the above discussion the terms Matrix and Array and MatrixBase and ArrayBase can be exchanged and all arguments still hold. - -\section TopicSummary Summary - - - To summarize, the implementation of functions taking non-writable (const referenced) objects is not a big issue and does not lead to problematic situations in terms of compiling and running your program. However, a naive implementation is likely to introduce unnecessary temporary objects in your code. In order to avoid evaluating parameters into temporaries, pass them as (const) references to MatrixBase or ArrayBase (so templatize your function). - - - Functions taking writable (non-const) parameters must take const references and cast away constness within the function body. - - - Functions that take as parameters MatrixBase (or ArrayBase) objects, and potentially need to resize them (in the case where they are resizable), must call resize() on the derived class, as returned by derived(). -*/ -} diff --git a/doc/I14_PreprocessorDirectives.dox b/doc/I14_PreprocessorDirectives.dox deleted file mode 100644 index 0c4c47464..000000000 --- a/doc/I14_PreprocessorDirectives.dox +++ /dev/null @@ -1,107 +0,0 @@ -namespace Eigen { - -/** \page TopicPreprocessorDirectives Preprocessor directives - -You can control some aspects of %Eigen by defining the preprocessor tokens using \c \#define. These macros -should be defined before any %Eigen headers are included. Often they are best set in the project options. - -This page lists the preprocesor tokens recognised by %Eigen. - -\eigenAutoToc - - -\section TopicPreprocessorDirectivesMajor Macros with major effects - -These macros have a major effect and typically break the API (Application Programming Interface) and/or the -ABI (Application Binary Interface). This can be rather dangerous: if parts of your program are compiled with -one option, and other parts (or libraries that you use) are compiled with another option, your program may -fail to link or exhibit subtle bugs. Nevertheless, these options can be useful for people who know what they -are doing. - - - \b EIGEN2_SUPPORT - if defined, enables the Eigen2 compatibility mode. This is meant to ease the transition - of Eigen2 to Eigen3 (see \ref Eigen2ToEigen3). Not defined by default. - - \b EIGEN2_SUPPORT_STAGEnn_xxx (for various values of nn and xxx) - staged migration path from Eigen2 to - Eigen3; see \ref Eigen2SupportModes. - - \b EIGEN_DEFAULT_DENSE_INDEX_TYPE - the type for column and row indices in matrices, vectors and array - (DenseBase::Index). Set to \c std::ptrdiff_t by default. - - \b EIGEN_DEFAULT_IO_FORMAT - the IOFormat to use when printing a matrix if no %IOFormat is specified. - Defaults to the %IOFormat constructed by the default constructor IOFormat::IOFormat(). - - \b EIGEN_INITIALIZE_MATRICES_BY_ZERO - if defined, all entries of newly constructed matrices and arrays are - initializes to zero, as are new entries in matrices and arrays after resizing. Not defined by default. - - \b EIGEN_NO_AUTOMATIC_RESIZING - if defined, the matrices (or arrays) on both sides of an assignment - a = b have to be of the same size; otherwise, %Eigen automatically resizes \c a so that it is of - the correct size. Not defined by default. - - -\section TopicPreprocessorDirectivesAssertions Assertions - -The %Eigen library contains many assertions to guard against programming errors, both at compile time and at -run time. However, these assertions do cost time and can thus be turned off. - - - \b EIGEN_NO_DEBUG - disables %Eigen's assertions if defined. Not defined by default, unless the - \c NDEBUG macro is defined (this is a standard C++ macro which disables all asserts). - - \b EIGEN_NO_STATIC_ASSERT - if defined, compile-time static assertions are replaced by runtime assertions; - this saves compilation time. Not defined by default. - - \b eigen_assert - macro with one argument that is used inside %Eigen for assertions. By default, it is - basically defined to be \c assert, which aborts the program if the assertion is violated. Redefine this - macro if you want to do something else, like throwing an exception. - - \b EIGEN_MPL2_ONLY - disable non MPL2 compatible features, or in other words disable the features which - are still under the LGPL. - - -\section TopicPreprocessorDirectivesPerformance Alignment, vectorization and performance tweaking - - - \b EIGEN_DONT_ALIGN - disables alignment completely. %Eigen will not try to align its objects and does not - expect that any objects passed to it are aligned. This will turn off vectorization. Not defined by default. - - \b EIGEN_DONT_ALIGN_STATICALLY - disables alignment of arrays on the stack. Not defined by default, unless - \c EIGEN_DONT_ALIGN is defined. - - \b EIGEN_DONT_VECTORIZE - disables explicit vectorization when defined. Not defined by default, unless - alignment is disabled by %Eigen's platform test or the user defining \c EIGEN_DONT_ALIGN. - - \b EIGEN_FAST_MATH - enables some optimizations which might affect the accuracy of the result. The only - optimization this currently includes is single precision sin() and cos() in the present of SSE - vectorization. Defined by default. - - \b EIGEN_UNROLLING_LIMIT - defines the size of a loop to enable meta unrolling. Set it to zero to disable - unrolling. The size of a loop here is expressed in %Eigen's own notion of "number of FLOPS", it does not - correspond to the number of iterations or the number of instructions. The default is value 100. - - -\section TopicPreprocessorDirectivesPlugins Plugins - -It is possible to add new methods to many fundamental classes in %Eigen by writing a plugin. As explained in -the section \ref ExtendingMatrixBase, the plugin is specified by defining a \c EIGEN_xxx_PLUGIN macro. The -following macros are supported; none of them are defined by default. - - - \b EIGEN_ARRAY_PLUGIN - filename of plugin for extending the Array class. - - \b EIGEN_ARRAYBASE_PLUGIN - filename of plugin for extending the ArrayBase class. - - \b EIGEN_CWISE_PLUGIN - filename of plugin for extending the Cwise class. - - \b EIGEN_DENSEBASE_PLUGIN - filename of plugin for extending the DenseBase class. - - \b EIGEN_DYNAMICSPARSEMATRIX_PLUGIN - filename of plugin for extending the DynamicSparseMatrix class. - - \b EIGEN_MATRIX_PLUGIN - filename of plugin for extending the Matrix class. - - \b EIGEN_MATRIXBASE_PLUGIN - filename of plugin for extending the MatrixBase class. - - \b EIGEN_PLAINOBJECTBASE_PLUGIN - filename of plugin for extending the PlainObjectBase class. - - \b EIGEN_QUATERNIONBASE_PLUGIN - filename of plugin for extending the QuaternionBase class. - - \b EIGEN_SPARSEMATRIX_PLUGIN - filename of plugin for extending the SparseMatrix class. - - \b EIGEN_SPARSEMATRIXBASE_PLUGIN - filename of plugin for extending the SparseMatrixBase class. - - \b EIGEN_SPARSEVECTOR_PLUGIN - filename of plugin for extending the SparseVector class. - - \b EIGEN_TRANSFORM_PLUGIN - filename of plugin for extending the Transform class. - - \b EIGEN_FUNCTORS_PLUGIN - filename of plugin for adding new functors and specializations of functor_traits. - - -\section TopicPreprocessorDirectivesDevelopers Macros for Eigen developers - -These macros are mainly meant for people developing %Eigen and for testing purposes. Even though, they might be useful for power users and the curious for debugging and testing purpose, they \b should \b not \b be \b used by real-word code. - - - \b EIGEN_DEFAULT_TO_ROW_MAJOR - when defined, the default storage order for matrices becomes row-major - instead of column-major. Not defined by default. - - \b EIGEN_INTERNAL_DEBUGGING - if defined, enables assertions in %Eigen's internal routines. This is useful - for debugging %Eigen itself. Not defined by default. - - \b EIGEN_NO_MALLOC - if defined, any request from inside the %Eigen to allocate memory from the heap - results in an assertion failure. This is useful to check that some routine does not allocate memory - dynamically. Not defined by default. - - \b EIGEN_RUNTIME_NO_MALLOC - if defined, a new switch is introduced which can be turned on and off by - calling set_is_malloc_allowed(bool). If malloc is not allowed and %Eigen tries to allocate memory - dynamically anyway, an assertion failure results. Not defined by default. - -*/ - -} diff --git a/doc/I15_StorageOrders.dox b/doc/I15_StorageOrders.dox deleted file mode 100644 index 61645313e..000000000 --- a/doc/I15_StorageOrders.dox +++ /dev/null @@ -1,86 +0,0 @@ -namespace Eigen { - -/** \eigenManualPage TopicStorageOrders Storage orders - -There are two different storage orders for matrices and two-dimensional arrays: column-major and row-major. -This page explains these storage orders and how to specify which one should be used. - -\eigenAutoToc - - -\section TopicStorageOrdersIntro Column-major and row-major storage - -The entries of a matrix form a two-dimensional grid. However, when the matrix is stored in memory, the entries -have to somehow be laid out linearly. There are two main ways to do this, by row and by column. - -We say that a matrix is stored in \b row-major order if it is stored row by row. The entire first row is -stored first, followed by the entire second row, and so on. Consider for example the matrix - -\f[ -A = \begin{bmatrix} -8 & 2 & 2 & 9 \\ -9 & 1 & 4 & 4 \\ -3 & 5 & 4 & 5 -\end{bmatrix}. -\f] - -If this matrix is stored in row-major order, then the entries are laid out in memory as follows: - -\code 8 2 2 9 9 1 4 4 3 5 4 5 \endcode - -On the other hand, a matrix is stored in \b column-major order if it is stored column by column, starting with -the entire first column, followed by the entire second column, and so on. If the above matrix is stored in -column-major order, it is laid out as follows: - -\code 8 9 3 2 1 5 2 4 4 9 4 5 \endcode - -This example is illustrated by the following Eigen code. It uses the PlainObjectBase::data() function, which -returns a pointer to the memory location of the first entry of the matrix. - - - - -
ExampleOutput
-\include TopicStorageOrders_example.cpp - -\verbinclude TopicStorageOrders_example.out -
- - -\section TopicStorageOrdersInEigen Storage orders in Eigen - -The storage order of a matrix or a two-dimensional array can be set by specifying the \c Options template -parameter for Matrix or Array. As \ref TutorialMatrixClass explains, the %Matrix class template has six -template parameters, of which three are compulsory (\c Scalar, \c RowsAtCompileTime and \c ColsAtCompileTime) -and three are optional (\c Options, \c MaxRowsAtCompileTime and \c MaxColsAtCompileTime). If the \c Options -parameter is set to \c RowMajor, then the matrix or array is stored in row-major order; if it is set to -\c ColMajor, then it is stored in column-major order. This mechanism is used in the above Eigen program to -specify the storage order. - -If the storage order is not specified, then Eigen defaults to storing the entry in column-major. This is also -the case if one of the convenience typedefs (\c Matrix3f, \c ArrayXXd, etc.) is used. - -Matrices and arrays using one storage order can be assigned to matrices and arrays using the other storage -order, as happens in the above program when \c Arowmajor is initialized using \c Acolmajor. Eigen will reorder -the entries automatically. More generally, row-major and column-major matrices can be mixed in an expression -as we want. - - -\section TopicStorageOrdersWhich Which storage order to choose? - -So, which storage order should you use in your program? There is no simple answer to this question; it depends -on your application. Here are some points to keep in mind: - - - Your users may expect you to use a specific storage order. Alternatively, you may use other libraries than - Eigen, and these other libraries may expect a certain storage order. In these cases it may be easiest and - fastest to use this storage order in your whole program. - - Algorithms that traverse a matrix row by row will go faster when the matrix is stored in row-major order - because of better data locality. Similarly, column-by-column traversal is faster for column-major - matrices. It may be worthwhile to experiment a bit to find out what is faster for your particular - application. - - The default in Eigen is column-major. Naturally, most of the development and testing of the Eigen library - is thus done with column-major matrices. This means that, even though we aim to support column-major and - row-major storage orders transparently, the Eigen library may well work best with column-major matrices. - -*/ -} diff --git a/doc/I16_TemplateKeyword.dox b/doc/I16_TemplateKeyword.dox deleted file mode 100644 index f4e4f237e..000000000 --- a/doc/I16_TemplateKeyword.dox +++ /dev/null @@ -1,132 +0,0 @@ -namespace Eigen { - -/** \page TopicTemplateKeyword The template and typename keywords in C++ - -There are two uses for the \c template and \c typename keywords in C++. One of them is fairly well known -amongst programmers: to define templates. The other use is more obscure: to specify that an expression refers -to a template function or a type. This regularly trips up programmers that use the %Eigen library, often -leading to error messages from the compiler that are difficult to understand. - -\eigenAutoToc - - -\section TopicTemplateKeywordToDefineTemplates Using the template and typename keywords to define templates - -The \c template and \c typename keywords are routinely used to define templates. This is not the topic of this -page as we assume that the reader is aware of this (otherwise consult a C++ book). The following example -should illustrate this use of the \c template keyword. - -\code -template -bool isPositive(T x) -{ - return x > 0; -} -\endcode - -We could just as well have written template <class T>; the keywords \c typename and \c class have the -same meaning in this context. - - -\section TopicTemplateKeywordExample An example showing the second use of the template keyword - -Let us illustrate the second use of the \c template keyword with an example. Suppose we want to write a -function which copies all entries in the upper triangular part of a matrix into another matrix, while keeping -the lower triangular part unchanged. A straightforward implementation would be as follows: - - - - -
Example:Output:
-\include TemplateKeyword_simple.cpp - -\verbinclude TemplateKeyword_simple.out -
- -That works fine, but it is not very flexible. First, it only works with dynamic-size matrices of -single-precision floats; the function \c copyUpperTriangularPart() does not accept static-size matrices or -matrices with double-precision numbers. Second, if you use an expression such as -mat.topLeftCorner(3,3) as the parameter \c src, then this is copied into a temporary variable of type -MatrixXf; this copy can be avoided. - -As explained in \ref TopicFunctionTakingEigenTypes, both issues can be resolved by making -\c copyUpperTriangularPart() accept any object of type MatrixBase. This leads to the following code: - - - - -
Example:Output:
-\include TemplateKeyword_flexible.cpp - -\verbinclude TemplateKeyword_flexible.out -
- -The one line in the body of the function \c copyUpperTriangularPart() shows the second, more obscure use of -the \c template keyword in C++. Even though it may look strange, the \c template keywords are necessary -according to the standard. Without it, the compiler may reject the code with an error message like "no match -for operator<". - - -\section TopicTemplateKeywordExplanation Explanation - -The reason that the \c template keyword is necessary in the last example has to do with the rules for how -templates are supposed to be compiled in C++. The compiler has to check the code for correct syntax at the -point where the template is defined, without knowing the actual value of the template arguments (\c Derived1 -and \c Derived2 in the example). That means that the compiler cannot know that dst.triangularPart is -a member template and that the following < symbol is part of the delimiter for the template -parameter. Another possibility would be that dst.triangularPart is a member variable with the < -symbol refering to the operator<() function. In fact, the compiler should choose the second -possibility, according to the standard. If dst.triangularPart is a member template (as in our case), -the programmer should specify this explicitly with the \c template keyword and write dst.template -triangularPart. - -The precise rules are rather complicated, but ignoring some subtleties we can summarize them as follows: -- A dependent name is name that depends (directly or indirectly) on a template parameter. In the - example, \c dst is a dependent name because it is of type MatrixBase<Derived1> which depends - on the template parameter \c Derived1. -- If the code contains either one of the contructions xxx.yyy or xxx->yyy and \c xxx is a - dependent name and \c yyy refers to a member template, then the \c template keyword must be used before - \c yyy, leading to xxx.template yyy or xxx->template yyy. -- If the code contains the contruction xxx::yyy and \c xxx is a dependent name and \c yyy refers to a - member typedef, then the \c typename keyword must be used before the whole construction, leading to - typename xxx::yyy. - -As an example where the \c typename keyword is required, consider the following code in \ref TutorialSparse -for iterating over the non-zero entries of a sparse matrix type: - -\code -SparseMatrixType mat(rows,cols); -for (int k=0; k -void iterateOverSparseMatrix(const SparseMatrix& mat; -{ - for (int k=0; k::InnerIterator it(mat,k); it; ++it) - { - /* ... */ - } -} -\endcode - - -\section TopicTemplateKeywordResources Resources for further reading - -For more information and a fuller explanation of this topic, the reader may consult the following sources: -- The book "C++ Template Metaprogramming" by David Abrahams and Aleksey Gurtovoy contains a very good - explanation in Appendix B ("The typename and template Keywords") which formed the basis for this page. -- http://pages.cs.wisc.edu/~driscoll/typename.html -- http://www.parashift.com/c++-faq-lite/templates.html#faq-35.18 -- http://www.comeaucomputing.com/techtalk/templates/#templateprefix -- http://www.comeaucomputing.com/techtalk/templates/#typename - -*/ -} diff --git a/doc/I17_SparseLinearSystems.dox b/doc/I17_SparseLinearSystems.dox deleted file mode 100644 index e447c40ce..000000000 --- a/doc/I17_SparseLinearSystems.dox +++ /dev/null @@ -1,107 +0,0 @@ -namespace Eigen { -/** \eigenManualPage TopicSparseSystems Solving Sparse Linear Systems -In Eigen, there are several methods available to solve linear systems when the coefficient matrix is sparse. Because of the special representation of this class of matrices, special care should be taken in order to get a good performance. See \ref TutorialSparse for a detailed introduction about sparse matrices in Eigen. In this page, we briefly present the main steps that are common to all the linear solvers in Eigen together with the main concepts behind them. Depending on the properties of the matrix, the desired accuracy, the end-user is able to tune these steps in order to improve the performance of its code. However, an impatient user does not need to know deeply what's hiding behind these steps: the last section presents a benchmark routine that can be easily used to get an insight on the performance of all the available solvers. - -\eigenAutoToc - - As summarized in \ref TutorialSparseDirectSolvers, there are many built-in solvers in Eigen as well as interface to external solvers libraries. All these solvers follow the same calling sequence. The basic steps are as follows : -\code -#include -// ... -SparseMatrix A; -// fill A -VectorXd b, x; -// fill b -// solve Ax = b -SolverClassName > solver; -solver.compute(A); -if(solver.info()!=Succeeded) { - // decomposition failed - return; -} -x = solver.solve(b); -if(solver.info()!=Succeeded) { - // solving failed - return; -} -\endcode - -\section TheSparseCompute The Compute Step -In the compute() function, the matrix is generally factorized: LLT for self-adjoint matrices, LDLT for general hermitian matrices and LU for non hermitian matrices. These are the results of using direct solvers. For this class of solvers precisely, the compute step is further subdivided into analyzePattern() and factorize(). - -The goal of analyzePattern() is to reorder the nonzero elements of the matrix, such that the factorization step creates less fill-in. This step exploits only the structure of the matrix. Hence, the results of this step can be used for other linear systems where the matrix has the same structure. Note however that sometimes, some external solvers (like SuperLU) require that the values of the matrix are set in this step, for instance to equilibrate the rows and columns of the matrix. In this situation, the results of this step can note be used with other matrices. - -Eigen provides a limited set of methods to reorder the matrix in this step, either built-in (COLAMD, AMD) or external (METIS). These methods are set in template parameter list of the solver : -\code -DirectSolverClassName, OrderingMethod > solver; -\endcode - -See the \link OrderingMethods_Module OrderingMethods module \endlink for the list of available methods and the associated options. - -In factorize(), the factors of the coefficient matrix are computed. This step should be called each time the values of the matrix change. However, the structural pattern of the matrix should not change between multiple calls. - -For iterative solvers, the compute step is used to eventually setup a preconditioner. Remember that, basically, the goal of the preconditioner is to speedup the convergence of an iterative method by solving a modified linear system where the coefficient matrix has more clustered eigenvalues. For real problems, an iterative solver should always be used with a preconditioner. In Eigen, a preconditioner is selected by simply adding it as a template parameter to the iterative solver object. -\code -IterativeSolverClassName, PreconditionerName > solver; -\endcode -The member function preconditioner() returns a read-write reference to the preconditioner - to directly interact with it. - -For instance, with the ILUT preconditioner, the incomplete factors L and U are computed in this step. -See \link Sparse_modules the Sparse module \endlink for the list of available preconditioners in Eigen. -\section TheSparseSolve The Solve step -The solve() function computes the solution of the linear systems with one or many right hand sides. -\code -X = solver.solve(B); -\endcode -Here, B can be a vector or a matrix where the columns form the different right hand sides. The solve() function can be called several times as well, for instance When all the right hand sides are not available at once. -\code -x1 = solver.solve(b1); -// Get the second right hand side b2 -x2 = solver.solve(b2); -// ... -\endcode -For direct methods, the solution are computed at the machine precision. Sometimes, the solution need not be too accurate. In this case, the iterative methods are more suitable and the desired accuracy can be set before the solve step using setTolerance(). For all the available functions, please, refer to the documentation of the \link IterativeLinearSolvers_Module Iterative solvers module \endlink. - -\section BenchmarkRoutine -Most of the time, all you need is to know how much time it will take to qolve your system, and hopefully, what is the most suitable solver. In Eigen, we provide a benchmark routine that can be used for this purpose. It is very easy to use. First, it should be activated at the configuration step with the flag TEST_REAL_CASES. Then, in bench/spbench, you can compile the routine by typing \b make \e spbenchsolver. You can then run it with --help option to get the list of all available options. Basically, the matrices to test should be in MatrixMarket Coordinate format, and the routine returns the statistics from all available solvers in Eigen. - -The following table gives an example of XHTML statistics from several Eigen built-in and external solvers. - - -
Matrix N NNZ UMFPACK SUPERLU PASTIX LU BiCGSTAB BiCGSTAB+ILUT GMRES+ILUT LDLT CHOLMOD LDLT PASTIX LDLT LLT CHOLMOD SP LLT CHOLMOD LLT PASTIX LLT CG
vector_graphics 12855 72069 Compute Time 0.02545490.02156770.07018270.0001533880.01401070.01537090.01016010.009305020.0649689 -
Solve Time 0.003378350.0009518260.004843730.03748860.00464450.008477540.0005418130.0002936960.00485376 -
Total Time 0.02883330.02251950.07502650.0376420.01865520.02384840.01070190.009598710.0698227 -
Error(Iter) 1.299e-16 2.04207e-16 4.83393e-15 3.94856e-11 (80) 1.03861e-12 (3) 5.81088e-14 (6) 1.97578e-16 1.83927e-16 4.24115e-15 -
poisson_SPD 19788 308232 Compute Time 0.4250261.823780.6173670.0004789211.340011.334710.7964190.8575730.4730070.8148260.1847190.8615550.4705590.000458188 -
Solve Time 0.02800530.01944020.02687470.2494370.05484440.09269910.008502040.00531710.02589320.008746030.005781550.005303610.02489420.239093 -
Total Time 0.4530311.843220.6442410.2499161.394861.427410.8049210.8628910.49890.8235720.1905010.8668590.4954530.239551 -
Error(Iter) 4.67146e-16 1.068e-15 1.3397e-15 6.29233e-11 (201) 3.68527e-11 (6) 3.3168e-15 (16) 1.86376e-15 1.31518e-16 1.42593e-15 3.45361e-15 3.14575e-16 2.21723e-15 7.21058e-16 9.06435e-12 (261) -
sherman2 1080 23094 Compute Time 0.006317540.0150520.0247514 -0.02144250.0217988 -
Solve Time 0.0004784240.0003379980.0010291 -0.002431520.00246152 -
Total Time 0.006795970.015390.0257805 -0.0238740.0242603 -
Error(Iter) 1.83099e-15 8.19351e-15 2.625e-14 1.3678e+69 (1080) 4.1911e-12 (7) 5.0299e-13 (12) -
bcsstk01_SPD 48 400 Compute Time 0.0001690790.000107890.0005725381.425e-069.1612e-058.3985e-055.6489e-057.0913e-050.0004682515.7389e-058.0212e-055.8394e-050.0004630171.333e-06 -
Solve Time 1.2288e-051.1124e-050.0002863878.5896e-051.6381e-051.6984e-053.095e-064.115e-060.0003254383.504e-067.369e-063.454e-060.0002940956.0516e-05 -
Total Time 0.0001813670.0001190140.0008589258.7321e-050.0001079930.0001009695.9584e-057.5028e-050.0007936896.0893e-058.7581e-056.1848e-050.0007571126.1849e-05 -
Error(Iter) 1.03474e-16 2.23046e-16 2.01273e-16 4.87455e-07 (48) 1.03553e-16 (2) 3.55965e-16 (2) 2.48189e-16 1.88808e-16 1.97976e-16 2.37248e-16 1.82701e-16 2.71474e-16 2.11322e-16 3.547e-09 (48) -
sherman1 1000 3750 Compute Time 0.002288050.002092310.005282689.846e-060.001635220.001621550.0007892590.0008044950.00438269 -
Solve Time 0.0002137889.7983e-050.0009388310.006298350.0003617640.000787944.3989e-052.5331e-050.000917166 -
Total Time 0.002501840.002190290.006221510.00630820.001996980.002409490.0008332480.0008298260.00529986 -
Error(Iter) 1.16839e-16 2.25968e-16 2.59116e-16 3.76779e-11 (248) 4.13343e-11 (4) 2.22347e-14 (10) 2.05861e-16 1.83555e-16 1.02917e-15 -
young1c 841 4089 Compute Time 0.002358430.002172280.005680751.2735e-050.002648660.00258236 -
Solve Time 0.0003295990.0001686340.000801180.05347380.001871930.00450211 -
Total Time 0.002688030.002340910.006481930.05348650.004520590.00708447 -
Error(Iter) 1.27029e-16 2.81321e-16 5.0492e-15 8.0507e-11 (706) 3.00447e-12 (8) 1.46532e-12 (16) -
mhd1280b 1280 22778 Compute Time 0.002348980.002070790.005709182.5976e-050.003025630.002980360.001445250.0009199220.00426444 -
Solve Time 0.001033920.0002119110.001050.01104320.0006282870.003920890.0001383036.2446e-050.00097564 -
Total Time 0.00338290.00228270.006759180.01106920.003653920.006901240.001583550.0009823680.00524008 -
Error(Iter) 1.32953e-16 3.08646e-16 6.734e-16 8.83132e-11 (40) 1.51153e-16 (1) 6.08556e-16 (8) 1.89264e-16 1.97477e-16 6.68126e-09 -
crashbasis 160000 1750416 Compute Time 3.20195.789215.75730.003835153.10063.09921 -
Solve Time 0.2619150.1062250.4021411.490890.248880.443673 -
Total Time 3.463815.8954216.15941.494733.349483.54288 -
Error(Iter) 1.76348e-16 4.58395e-16 1.67982e-14 8.64144e-11 (61) 8.5996e-12 (2) 6.04042e-14 (5) - -
-*/ -} diff --git a/doc/InsideEigenExample.dox b/doc/InsideEigenExample.dox new file mode 100644 index 000000000..ed053c69d --- /dev/null +++ b/doc/InsideEigenExample.dox @@ -0,0 +1,495 @@ +namespace Eigen { + +/** \page TopicInsideEigenExample What happens inside Eigen, on a simple example + +\eigenAutoToc + +
+ + +Consider the following example program: + +\code +#include + +int main() +{ + int size = 50; + // VectorXf is a vector of floats, with dynamic size. + Eigen::VectorXf u(size), v(size), w(size); + u = v + w; +} +\endcode + +The goal of this page is to understand how Eigen compiles it, assuming that SSE2 vectorization is enabled (GCC option -msse2). + +\section WhyInteresting Why it's interesting + +Maybe you think, that the above example program is so simple, that compiling it shouldn't involve anything interesting. So before starting, let us explain what is nontrivial in compiling it correctly -- that is, producing optimized code -- so that the complexity of Eigen, that we'll explain here, is really useful. + +Look at the line of code +\code + u = v + w; // (*) +\endcode + +The first important thing about compiling it, is that the arrays should be traversed only once, like +\code + for(int i = 0; i < size; i++) u[i] = v[i] + w[i]; +\endcode +The problem is that if we make a naive C++ library where the VectorXf class has an operator+ returning a VectorXf, then the line of code (*) will amount to: +\code + VectorXf tmp = v + w; + VectorXf u = tmp; +\endcode +Obviously, the introduction of the temporary \a tmp here is useless. It has a very bad effect on performance, first because the creation of \a tmp requires a dynamic memory allocation in this context, and second as there are now two for loops: +\code + for(int i = 0; i < size; i++) tmp[i] = v[i] + w[i]; + for(int i = 0; i < size; i++) u[i] = tmp[i]; +\endcode +Traversing the arrays twice instead of once is terrible for performance, as it means that we do many redundant memory accesses. + +The second important thing about compiling the above program, is to make correct use of SSE2 instructions. Notice that Eigen also supports AltiVec and that all the discussion that we make here applies also to AltiVec. + +SSE2, like AltiVec, is a set of instructions allowing to perform computations on packets of 128 bits at once. Since a float is 32 bits, this means that SSE2 instructions can handle 4 floats at once. This means that, if correctly used, they can make our computation go up to 4x faster. + +However, in the above program, we have chosen size=50, so our vectors consist of 50 float's, and 50 is not a multiple of 4. This means that we cannot hope to do all of that computation using SSE2 instructions. The second best thing, to which we should aim, is to handle the 48 first coefficients with SSE2 instructions, since 48 is the biggest multiple of 4 below 50, and then handle separately, without SSE2, the 49th and 50th coefficients. Something like this: + +\code + for(int i = 0; i < 4*(size/4); i+=4) u.packet(i) = v.packet(i) + w.packet(i); + for(int i = 4*(size/4); i < size; i++) u[i] = v[i] + w[i]; +\endcode + +So let us look line by line at our example program, and let's follow Eigen as it compiles it. + +\section ConstructingVectors Constructing vectors + +Let's analyze the first line: + +\code + Eigen::VectorXf u(size), v(size), w(size); +\endcode + +First of all, VectorXf is the following typedef: +\code + typedef Matrix VectorXf; +\endcode + +The class template Matrix is declared in src/Core/util/ForwardDeclarations.h with 6 template parameters, but the last 3 are automatically determined by the first 3. So you don't need to worry about them for now. Here, Matrix\ means a matrix of floats, with a dynamic number of rows and 1 column. + +The Matrix class inherits a base class, MatrixBase. Don't worry about it, for now it suffices to say that MatrixBase is what unifies matrices/vectors and all the expressions types -- more on that below. + +When we do +\code + Eigen::VectorXf u(size); +\endcode +the constructor that is called is Matrix::Matrix(int), in src/Core/Matrix.h. Besides some assertions, all it does is to construct the \a m_storage member, which is of type DenseStorage\. + +You may wonder, isn't it overengineering to have the storage in a separate class? The reason is that the Matrix class template covers all kinds of matrices and vector: both fixed-size and dynamic-size. The storage method is not the same in these two cases. For fixed-size, the matrix coefficients are stored as a plain member array. For dynamic-size, the coefficients will be stored as a pointer to a dynamically-allocated array. Because of this, we need to abstract storage away from the Matrix class. That's DenseStorage. + +Let's look at this constructor, in src/Core/DenseStorage.h. You can see that there are many partial template specializations of DenseStorages here, treating separately the cases where dimensions are Dynamic or fixed at compile-time. The partial specialization that we are looking at is: +\code +template class DenseStorage +\endcode + +Here, the constructor called is DenseStorage::DenseStorage(int size, int rows, int columns) +with size=50, rows=50, columns=1. + +Here is this constructor: +\code +inline DenseStorage(int size, int rows, int) : m_data(internal::aligned_new(size)), m_rows(rows) {} +\endcode + +Here, the \a m_data member is the actual array of coefficients of the matrix. As you see, it is dynamically allocated. Rather than calling new[] or malloc(), as you can see, we have our own internal::aligned_new defined in src/Core/util/Memory.h. What it does is that if vectorization is enabled, then it uses a platform-specific call to allocate a 128-bit-aligned array, as that is very useful for vectorization with both SSE2 and AltiVec. If vectorization is disabled, it amounts to the standard new[]. + +As you can see, the constructor also sets the \a m_rows member to \a size. Notice that there is no \a m_columns member: indeed, in this partial specialization of DenseStorage, we know the number of columns at compile-time, since the _Cols template parameter is different from Dynamic. Namely, in our case, _Cols is 1, which is to say that our vector is just a matrix with 1 column. Hence, there is no need to store the number of columns as a runtime variable. + +When you call VectorXf::data() to get the pointer to the array of coefficients, it returns DenseStorage::data() which returns the \a m_data member. + +When you call VectorXf::size() to get the size of the vector, this is actually a method in the base class MatrixBase. It determines that the vector is a column-vector, since ColsAtCompileTime==1 (this comes from the template parameters in the typedef VectorXf). It deduces that the size is the number of rows, so it returns VectorXf::rows(), which returns DenseStorage::rows(), which returns the \a m_rows member, which was set to \a size by the constructor. + +\section ConstructionOfSumXpr Construction of the sum expression + +Now that our vectors are constructed, let's move on to the next line: + +\code +u = v + w; +\endcode + +The executive summary is that operator+ returns a "sum of vectors" expression, but doesn't actually perform the computation. It is the operator=, whose call occurs thereafter, that does the computation. + +Let us now see what Eigen does when it sees this: + +\code +v + w +\endcode + +Here, v and w are of type VectorXf, which is a typedef for a specialization of Matrix (as we explained above), which is a subclass of MatrixBase. So what is being called is + +\code +MatrixBase::operator+(const MatrixBase&) +\endcode + +The return type of this operator is +\code +CwiseBinaryOp, VectorXf, VectorXf> +\endcode +The CwiseBinaryOp class is our first encounter with an expression template. As we said, the operator+ doesn't by itself perform any computation, it just returns an abstract "sum of vectors" expression. Since there are also "difference of vectors" and "coefficient-wise product of vectors" expressions, we unify them all as "coefficient-wise binary operations", which we abbreviate as "CwiseBinaryOp". "Coefficient-wise" means that the operations is performed coefficient by coefficient. "binary" means that there are two operands -- we are adding two vectors with one another. + +Now you might ask, what if we did something like + +\code +v + w + u; +\endcode + +The first v + w would return a CwiseBinaryOp as above, so in order for this to compile, we'd need to define an operator+ also in the class CwiseBinaryOp... at this point it starts looking like a nightmare: are we going to have to define all operators in each of the expression classes (as you guessed, CwiseBinaryOp is only one of many) ? This looks like a dead end! + +The solution is that CwiseBinaryOp itself, as well as Matrix and all the other expression types, is a subclass of MatrixBase. So it is enough to define once and for all the operators in class MatrixBase. + +Since MatrixBase is the common base class of different subclasses, the aspects that depend on the subclass must be abstracted from MatrixBase. This is called polymorphism. + +The classical approach to polymorphism in C++ is by means of virtual functions. This is dynamic polymorphism. Here we don't want dynamic polymorphism because the whole design of Eigen is based around the assumption that all the complexity, all the abstraction, gets resolved at compile-time. This is crucial: if the abstraction can't get resolved at compile-time, Eigen's compile-time optimization mechanisms become useless, not to mention that if that abstraction has to be resolved at runtime it'll incur an overhead by itself. + +Here, what we want is to have a single class MatrixBase as the base of many subclasses, in such a way that each MatrixBase object (be it a matrix, or vector, or any kind of expression) knows at compile-time (as opposed to run-time) of which particular subclass it is an object (i.e. whether it is a matrix, or an expression, and what kind of expression). + +The solution is the Curiously Recurring Template Pattern. Let's do the break now. Hopefully you can read this wikipedia page during the break if needed, but it won't be allowed during the exam. + +In short, MatrixBase takes a template parameter \a Derived. Whenever we define a subclass Subclass, we actually make Subclass inherit MatrixBase\. The point is that different subclasses inherit different MatrixBase types. Thanks to this, whenever we have an object of a subclass, and we call on it some MatrixBase method, we still remember even from inside the MatrixBase method which particular subclass we're talking about. + +This means that we can put almost all the methods and operators in the base class MatrixBase, and have only the bare minimum in the subclasses. If you look at the subclasses in Eigen, like for instance the CwiseBinaryOp class, they have very few methods. There are coeff() and sometimes coeffRef() methods for access to the coefficients, there are rows() and cols() methods returning the number of rows and columns, but there isn't much more than that. All the meat is in MatrixBase, so it only needs to be coded once for all kinds of expressions, matrices, and vectors. + +So let's end this digression and come back to the piece of code from our example program that we were currently analyzing, + +\code +v + w +\endcode + +Now that MatrixBase is a good friend, let's write fully the prototype of the operator+ that gets called here (this code is from src/Core/MatrixBase.h): + +\code +template +class MatrixBase +{ + // ... + + template + const CwiseBinaryOp::Scalar>, Derived, OtherDerived> + operator+(const MatrixBase &other) const; + + // ... +}; +\endcode + +Here of course, \a Derived and \a OtherDerived are VectorXf. + +As we said, CwiseBinaryOp is also used for other operations such as substration, so it takes another template parameter determining the operation that will be applied to coefficients. This template parameter is a functor, that is, a class in which we have an operator() so it behaves like a function. Here, the functor used is internal::scalar_sum_op. It is defined in src/Core/Functors.h. + +Let us now explain the internal::traits here. The internal::scalar_sum_op class takes one template parameter: the type of the numbers to handle. Here of course we want to pass the scalar type (a.k.a. numeric type) of VectorXf, which is \c float. How do we determine which is the scalar type of \a Derived ? Throughout Eigen, all matrix and expression types define a typedef \a Scalar which gives its scalar type. For example, VectorXf::Scalar is a typedef for \c float. So here, if life was easy, we could find the numeric type of \a Derived as just +\code +typename Derived::Scalar +\endcode +Unfortunately, we can't do that here, as the compiler would complain that the type Derived hasn't yet been defined. So we use a workaround: in src/Core/util/ForwardDeclarations.h, we declared (not defined!) all our subclasses, like Matrix, and we also declared the following class template: +\code +template struct internal::traits; +\endcode +In src/Core/Matrix.h, right \em before the definition of class Matrix, we define a partial specialization of internal::traits for T=Matrix\. In this specialization of internal::traits, we define the Scalar typedef. So when we actually define Matrix, it is legal to refer to "typename internal::traits\::Scalar". + +Anyway, we have declared our operator+. In our case, where \a Derived and \a OtherDerived are VectorXf, the above declaration amounts to: +\code +class MatrixBase +{ + // ... + + const CwiseBinaryOp, VectorXf, VectorXf> + operator+(const MatrixBase &other) const; + + // ... +}; +\endcode + +Let's now jump to src/Core/CwiseBinaryOp.h to see how it is defined. As you can see there, all it does is to return a CwiseBinaryOp object, and this object is just storing references to the left-hand-side and right-hand-side expressions -- here, these are the vectors \a v and \a w. Well, the CwiseBinaryOp object is also storing an instance of the (empty) functor class, but you shouldn't worry about it as that is a minor implementation detail. + +Thus, the operator+ hasn't performed any actual computation. To summarize, the operation \a v + \a w just returned an object of type CwiseBinaryOp which did nothing else than just storing references to \a v and \a w. + +\section Assignment The assignment + +At this point, the expression \a v + \a w has finished evaluating, so, in the process of compiling the line of code +\code +u = v + w; +\endcode +we now enter the operator=. + +What operator= is being called here? The vector u is an object of class VectorXf, i.e. Matrix. In src/Core/Matrix.h, inside the definition of class Matrix, we see this: +\code + template + inline Matrix& operator=(const MatrixBase& other) + { + eigen_assert(m_storage.data()!=0 && "you cannot use operator= with a non initialized matrix (instead use set()"); + return Base::operator=(other.derived()); + } +\endcode +Here, Base is a typedef for MatrixBase\. So, what is being called is the operator= of MatrixBase. Let's see its prototype in src/Core/MatrixBase.h: +\code + template + Derived& operator=(const MatrixBase& other); +\endcode +Here, \a Derived is VectorXf (since u is a VectorXf) and \a OtherDerived is CwiseBinaryOp. More specifically, as explained in the previous section, \a OtherDerived is: +\code +CwiseBinaryOp, VectorXf, VectorXf> +\endcode +So the full prototype of the operator= being called is: +\code +VectorXf& MatrixBase::operator=(const MatrixBase, VectorXf, VectorXf> > & other); +\endcode +This operator= literally reads "copying a sum of two VectorXf's into another VectorXf". + +Let's now look at the implementation of this operator=. It resides in the file src/Core/Assign.h. + +What we can see there is: +\code +template +template +inline Derived& MatrixBase + ::operator=(const MatrixBase& other) +{ + return internal::assign_selector::run(derived(), other.derived()); +} +\endcode + +OK so our next task is to understand internal::assign_selector :) + +Here is its declaration (all that is still in the same file src/Core/Assign.h) +\code +template +struct internal::assign_selector; +\endcode + +So internal::assign_selector takes 4 template parameters, but the 2 last ones are automatically determined by the 2 first ones. + +EvalBeforeAssigning is here to enforce the EvalBeforeAssigningBit. As explained here, certain expressions have this flag which makes them automatically evaluate into temporaries before assigning them to another expression. This is the case of the Product expression, in order to avoid strange aliasing effects when doing "m = m * m;" However, of course here our CwiseBinaryOp expression doesn't have the EvalBeforeAssigningBit: we said since the beginning that we didn't want a temporary to be introduced here. So if you go to src/Core/CwiseBinaryOp.h, you'll see that the Flags in internal::traits\ don't include the EvalBeforeAssigningBit. The Flags member of CwiseBinaryOp is then imported from the internal::traits by the EIGEN_GENERIC_PUBLIC_INTERFACE macro. Anyway, here the template parameter EvalBeforeAssigning has the value \c false. + +NeedToTranspose is here for the case where the user wants to copy a row-vector into a column-vector. We allow this as a special exception to the general rule that in assignments we require the dimesions to match. Anyway, here both the left-hand and right-hand sides are column vectors, in the sense that ColsAtCompileTime is equal to 1. So NeedToTranspose is \c false too. + +So, here we are in the partial specialization: +\code +internal::assign_selector +\endcode + +Here's how it is defined: +\code +template +struct internal::assign_selector { + static Derived& run(Derived& dst, const OtherDerived& other) { return dst.lazyAssign(other.derived()); } +}; +\endcode + +OK so now our next job is to understand how lazyAssign works :) + +\code +template +template +inline Derived& MatrixBase + ::lazyAssign(const MatrixBase& other) +{ + EIGEN_STATIC_ASSERT_SAME_MATRIX_SIZE(Derived,OtherDerived) + eigen_assert(rows() == other.rows() && cols() == other.cols()); + internal::assign_impl::run(derived(),other.derived()); + return derived(); +} +\endcode + +What do we see here? Some assertions, and then the only interesting line is: +\code + internal::assign_impl::run(derived(),other.derived()); +\endcode + +OK so now we want to know what is inside internal::assign_impl. + +Here is its declaration: +\code +template::Vectorization, + int Unrolling = internal::assign_traits::Unrolling> +struct internal::assign_impl; +\endcode +Again, internal::assign_selector takes 4 template parameters, but the 2 last ones are automatically determined by the 2 first ones. + +These two parameters \a Vectorization and \a Unrolling are determined by a helper class internal::assign_traits. Its job is to determine which vectorization strategy to use (that is \a Vectorization) and which unrolling strategy to use (that is \a Unrolling). + +We'll not enter into the details of how these strategies are chosen (this is in the implementation of internal::assign_traits at the top of the same file). Let's just say that here \a Vectorization has the value \a LinearVectorization, and \a Unrolling has the value \a NoUnrolling (the latter is obvious since our vectors have dynamic size so there's no way to unroll the loop at compile-time). + +So the partial specialization of internal::assign_impl that we're looking at is: +\code +internal::assign_impl +\endcode + +Here is how it's defined: +\code +template +struct internal::assign_impl +{ + static void run(Derived1 &dst, const Derived2 &src) + { + const int size = dst.size(); + const int packetSize = internal::packet_traits::size; + const int alignedStart = internal::assign_traits::DstIsAligned ? 0 + : internal::first_aligned(&dst.coeffRef(0), size); + const int alignedEnd = alignedStart + ((size-alignedStart)/packetSize)*packetSize; + + for(int index = 0; index < alignedStart; index++) + dst.copyCoeff(index, src); + + for(int index = alignedStart; index < alignedEnd; index += packetSize) + { + dst.template copyPacket::SrcAlignment>(index, src); + } + + for(int index = alignedEnd; index < size; index++) + dst.copyCoeff(index, src); + } +}; +\endcode + +Here's how it works. \a LinearVectorization means that the left-hand and right-hand side expression can be accessed linearly i.e. you can refer to their coefficients by one integer \a index, as opposed to having to refer to its coefficients by two integers \a row, \a column. + +As we said at the beginning, vectorization works with blocks of 4 floats. Here, \a PacketSize is 4. + +There are two potential problems that we need to deal with: +\li first, vectorization works much better if the packets are 128-bit-aligned. This is especially important for write access. So when writing to the coefficients of \a dst, we want to group these coefficients by packets of 4 such that each of these packets is 128-bit-aligned. In general, this requires to skip a few coefficients at the beginning of \a dst. This is the purpose of \a alignedStart. We then copy these first few coefficients one by one, not by packets. However, in our case, the \a dst expression is a VectorXf and remember that in the construction of the vectors we allocated aligned arrays. Thanks to \a DstIsAligned, Eigen remembers that without having to do any runtime check, so \a alignedStart is zero and this part is avoided altogether. +\li second, the number of coefficients to copy is not in general a multiple of \a packetSize. Here, there are 50 coefficients to copy and \a packetSize is 4. So we'll have to copy the last 2 coefficients one by one, not by packets. Here, \a alignedEnd is 48. + +Now come the actual loops. + +First, the vectorized part: the 48 first coefficients out of 50 will be copied by packets of 4: +\code + for(int index = alignedStart; index < alignedEnd; index += packetSize) + { + dst.template copyPacket::SrcAlignment>(index, src); + } +\endcode + +What is copyPacket? It is defined in src/Core/Coeffs.h: +\code +template +template +inline void MatrixBase::copyPacket(int index, const MatrixBase& other) +{ + eigen_internal_assert(index >= 0 && index < size()); + derived().template writePacket(index, + other.derived().template packet(index)); +} +\endcode + +OK, what are writePacket() and packet() here? + +First, writePacket() here is a method on the left-hand side VectorXf. So we go to src/Core/Matrix.h to look at its definition: +\code +template +inline void writePacket(int index, const PacketScalar& x) +{ + internal::pstoret(m_storage.data() + index, x); +} +\endcode +Here, \a StoreMode is \a #Aligned, indicating that we are doing a 128-bit-aligned write access, \a PacketScalar is a type representing a "SSE packet of 4 floats" and internal::pstoret is a function writing such a packet in memory. Their definitions are architecture-specific, we find them in src/Core/arch/SSE/PacketMath.h: + +The line in src/Core/arch/SSE/PacketMath.h that determines the PacketScalar type (via a typedef in Matrix.h) is: +\code +template<> struct internal::packet_traits { typedef __m128 type; enum {size=4}; }; +\endcode +Here, __m128 is a SSE-specific type. Notice that the enum \a size here is what was used to define \a packetSize above. + +And here is the implementation of internal::pstoret: +\code +template<> inline void internal::pstore(float* to, const __m128& from) { _mm_store_ps(to, from); } +\endcode +Here, __mm_store_ps is a SSE-specific intrinsic function, representing a single SSE instruction. The difference between internal::pstore and internal::pstoret is that internal::pstoret is a dispatcher handling both the aligned and unaligned cases, you find its definition in src/Core/GenericPacketMath.h: +\code +template +inline void internal::pstoret(Scalar* to, const Packet& from) +{ + if(LoadMode == Aligned) + internal::pstore(to, from); + else + internal::pstoreu(to, from); +} +\endcode + +OK, that explains how writePacket() works. Now let's look into the packet() call. Remember that we are analyzing this line of code inside copyPacket(): +\code +derived().template writePacket(index, + other.derived().template packet(index)); +\endcode + +Here, \a other is our sum expression \a v + \a w. The .derived() is just casting from MatrixBase to the subclass which here is CwiseBinaryOp. So let's go to src/Core/CwiseBinaryOp.h: +\code +class CwiseBinaryOp +{ + // ... + template + inline PacketScalar packet(int index) const + { + return m_functor.packetOp(m_lhs.template packet(index), m_rhs.template packet(index)); + } +}; +\endcode +Here, \a m_lhs is the vector \a v, and \a m_rhs is the vector \a w. So the packet() function here is Matrix::packet(). The template parameter \a LoadMode is \a #Aligned. So we're looking at +\code +class Matrix +{ + // ... + template + inline PacketScalar packet(int index) const + { + return internal::ploadt(m_storage.data() + index); + } +}; +\endcode +We let you look up the definition of internal::ploadt in GenericPacketMath.h and the internal::pload in src/Core/arch/SSE/PacketMath.h. It is very similar to the above for internal::pstore. + +Let's go back to CwiseBinaryOp::packet(). Once the packets from the vectors \a v and \a w have been returned, what does this function do? It calls m_functor.packetOp() on them. What is m_functor? Here we must remember what particular template specialization of CwiseBinaryOp we're dealing with: +\code +CwiseBinaryOp, VectorXf, VectorXf> +\endcode +So m_functor is an object of the empty class internal::scalar_sum_op. As we mentioned above, don't worry about why we constructed an object of this empty class at all -- it's an implementation detail, the point is that some other functors need to store member data. + +Anyway, internal::scalar_sum_op is defined in src/Core/Functors.h: +\code +template struct internal::scalar_sum_op EIGEN_EMPTY_STRUCT { + inline const Scalar operator() (const Scalar& a, const Scalar& b) const { return a + b; } + template + inline const PacketScalar packetOp(const PacketScalar& a, const PacketScalar& b) const + { return internal::padd(a,b); } +}; +\endcode +As you can see, all what packetOp() does is to call internal::padd on the two packets. Here is the definition of internal::padd from src/Core/arch/SSE/PacketMath.h: +\code +template<> inline __m128 internal::padd(const __m128& a, const __m128& b) { return _mm_add_ps(a,b); } +\endcode +Here, _mm_add_ps is a SSE-specific intrinsic function, representing a single SSE instruction. + +To summarize, the loop +\code + for(int index = alignedStart; index < alignedEnd; index += packetSize) + { + dst.template copyPacket::SrcAlignment>(index, src); + } +\endcode +has been compiled to the following code: for \a index going from 0 to the 11 ( = 48/4 - 1), read the i-th packet (of 4 floats) from the vector v and the i-th packet from the vector w using two __mm_load_ps SSE instructions, then add them together using a __mm_add_ps instruction, then store the result using a __mm_store_ps instruction. + +There remains the second loop handling the last few (here, the last 2) coefficients: +\code + for(int index = alignedEnd; index < size; index++) + dst.copyCoeff(index, src); +\endcode +However, it works just like the one we just explained, it is just simpler because there is no SSE vectorization involved here. copyPacket() becomes copyCoeff(), packet() becomes coeff(), writePacket() becomes coeffRef(). If you followed us this far, you can probably understand this part by yourself. + +We see that all the C++ abstraction of Eigen goes away during compilation and that we indeed are precisely controlling which assembly instructions we emit. Such is the beauty of C++! Since we have such precise control over the emitted assembly instructions, but such complex logic to choose the right instructions, we can say that Eigen really behaves like an optimizing compiler. If you prefer, you could say that Eigen behaves like a script for the compiler. In a sense, C++ template metaprogramming is scripting the compiler -- and it's been shown that this scripting language is Turing-complete. See Wikipedia. + +*/ + +} diff --git a/doc/PassingByValue.dox b/doc/PassingByValue.dox new file mode 100644 index 000000000..bf4d0ef4b --- /dev/null +++ b/doc/PassingByValue.dox @@ -0,0 +1,40 @@ +namespace Eigen { + +/** \eigenManualPage TopicPassingByValue Passing Eigen objects by value to functions + +Passing objects by value is almost always a very bad idea in C++, as this means useless copies, and one should pass them by reference instead. + +With Eigen, this is even more important: passing \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen objects" by value is not only inefficient, it can be illegal or make your program crash! And the reason is that these Eigen objects have alignment modifiers that aren't respected when they are passed by value. + +So for example, a function like this, where v is passed by value: + +\code +void my_function(Eigen::Vector2d v); +\endcode + +needs to be rewritten as follows, passing v by reference: + +\code +void my_function(const Eigen::Vector2d& v); +\endcode + +Likewise if you have a class having a Eigen object as member: + +\code +struct Foo +{ + Eigen::Vector2d v; +}; +void my_function(Foo v); +\endcode + +This function also needs to be rewritten like this: +\code +void my_function(const Foo& v); +\endcode + +Note that on the other hand, there is no problem with functions that return objects by value. + +*/ + +} diff --git a/doc/PreprocessorDirectives.dox b/doc/PreprocessorDirectives.dox new file mode 100644 index 000000000..0c4c47464 --- /dev/null +++ b/doc/PreprocessorDirectives.dox @@ -0,0 +1,107 @@ +namespace Eigen { + +/** \page TopicPreprocessorDirectives Preprocessor directives + +You can control some aspects of %Eigen by defining the preprocessor tokens using \c \#define. These macros +should be defined before any %Eigen headers are included. Often they are best set in the project options. + +This page lists the preprocesor tokens recognised by %Eigen. + +\eigenAutoToc + + +\section TopicPreprocessorDirectivesMajor Macros with major effects + +These macros have a major effect and typically break the API (Application Programming Interface) and/or the +ABI (Application Binary Interface). This can be rather dangerous: if parts of your program are compiled with +one option, and other parts (or libraries that you use) are compiled with another option, your program may +fail to link or exhibit subtle bugs. Nevertheless, these options can be useful for people who know what they +are doing. + + - \b EIGEN2_SUPPORT - if defined, enables the Eigen2 compatibility mode. This is meant to ease the transition + of Eigen2 to Eigen3 (see \ref Eigen2ToEigen3). Not defined by default. + - \b EIGEN2_SUPPORT_STAGEnn_xxx (for various values of nn and xxx) - staged migration path from Eigen2 to + Eigen3; see \ref Eigen2SupportModes. + - \b EIGEN_DEFAULT_DENSE_INDEX_TYPE - the type for column and row indices in matrices, vectors and array + (DenseBase::Index). Set to \c std::ptrdiff_t by default. + - \b EIGEN_DEFAULT_IO_FORMAT - the IOFormat to use when printing a matrix if no %IOFormat is specified. + Defaults to the %IOFormat constructed by the default constructor IOFormat::IOFormat(). + - \b EIGEN_INITIALIZE_MATRICES_BY_ZERO - if defined, all entries of newly constructed matrices and arrays are + initializes to zero, as are new entries in matrices and arrays after resizing. Not defined by default. + - \b EIGEN_NO_AUTOMATIC_RESIZING - if defined, the matrices (or arrays) on both sides of an assignment + a = b have to be of the same size; otherwise, %Eigen automatically resizes \c a so that it is of + the correct size. Not defined by default. + + +\section TopicPreprocessorDirectivesAssertions Assertions + +The %Eigen library contains many assertions to guard against programming errors, both at compile time and at +run time. However, these assertions do cost time and can thus be turned off. + + - \b EIGEN_NO_DEBUG - disables %Eigen's assertions if defined. Not defined by default, unless the + \c NDEBUG macro is defined (this is a standard C++ macro which disables all asserts). + - \b EIGEN_NO_STATIC_ASSERT - if defined, compile-time static assertions are replaced by runtime assertions; + this saves compilation time. Not defined by default. + - \b eigen_assert - macro with one argument that is used inside %Eigen for assertions. By default, it is + basically defined to be \c assert, which aborts the program if the assertion is violated. Redefine this + macro if you want to do something else, like throwing an exception. + - \b EIGEN_MPL2_ONLY - disable non MPL2 compatible features, or in other words disable the features which + are still under the LGPL. + + +\section TopicPreprocessorDirectivesPerformance Alignment, vectorization and performance tweaking + + - \b EIGEN_DONT_ALIGN - disables alignment completely. %Eigen will not try to align its objects and does not + expect that any objects passed to it are aligned. This will turn off vectorization. Not defined by default. + - \b EIGEN_DONT_ALIGN_STATICALLY - disables alignment of arrays on the stack. Not defined by default, unless + \c EIGEN_DONT_ALIGN is defined. + - \b EIGEN_DONT_VECTORIZE - disables explicit vectorization when defined. Not defined by default, unless + alignment is disabled by %Eigen's platform test or the user defining \c EIGEN_DONT_ALIGN. + - \b EIGEN_FAST_MATH - enables some optimizations which might affect the accuracy of the result. The only + optimization this currently includes is single precision sin() and cos() in the present of SSE + vectorization. Defined by default. + - \b EIGEN_UNROLLING_LIMIT - defines the size of a loop to enable meta unrolling. Set it to zero to disable + unrolling. The size of a loop here is expressed in %Eigen's own notion of "number of FLOPS", it does not + correspond to the number of iterations or the number of instructions. The default is value 100. + + +\section TopicPreprocessorDirectivesPlugins Plugins + +It is possible to add new methods to many fundamental classes in %Eigen by writing a plugin. As explained in +the section \ref ExtendingMatrixBase, the plugin is specified by defining a \c EIGEN_xxx_PLUGIN macro. The +following macros are supported; none of them are defined by default. + + - \b EIGEN_ARRAY_PLUGIN - filename of plugin for extending the Array class. + - \b EIGEN_ARRAYBASE_PLUGIN - filename of plugin for extending the ArrayBase class. + - \b EIGEN_CWISE_PLUGIN - filename of plugin for extending the Cwise class. + - \b EIGEN_DENSEBASE_PLUGIN - filename of plugin for extending the DenseBase class. + - \b EIGEN_DYNAMICSPARSEMATRIX_PLUGIN - filename of plugin for extending the DynamicSparseMatrix class. + - \b EIGEN_MATRIX_PLUGIN - filename of plugin for extending the Matrix class. + - \b EIGEN_MATRIXBASE_PLUGIN - filename of plugin for extending the MatrixBase class. + - \b EIGEN_PLAINOBJECTBASE_PLUGIN - filename of plugin for extending the PlainObjectBase class. + - \b EIGEN_QUATERNIONBASE_PLUGIN - filename of plugin for extending the QuaternionBase class. + - \b EIGEN_SPARSEMATRIX_PLUGIN - filename of plugin for extending the SparseMatrix class. + - \b EIGEN_SPARSEMATRIXBASE_PLUGIN - filename of plugin for extending the SparseMatrixBase class. + - \b EIGEN_SPARSEVECTOR_PLUGIN - filename of plugin for extending the SparseVector class. + - \b EIGEN_TRANSFORM_PLUGIN - filename of plugin for extending the Transform class. + - \b EIGEN_FUNCTORS_PLUGIN - filename of plugin for adding new functors and specializations of functor_traits. + + +\section TopicPreprocessorDirectivesDevelopers Macros for Eigen developers + +These macros are mainly meant for people developing %Eigen and for testing purposes. Even though, they might be useful for power users and the curious for debugging and testing purpose, they \b should \b not \b be \b used by real-word code. + + - \b EIGEN_DEFAULT_TO_ROW_MAJOR - when defined, the default storage order for matrices becomes row-major + instead of column-major. Not defined by default. + - \b EIGEN_INTERNAL_DEBUGGING - if defined, enables assertions in %Eigen's internal routines. This is useful + for debugging %Eigen itself. Not defined by default. + - \b EIGEN_NO_MALLOC - if defined, any request from inside the %Eigen to allocate memory from the heap + results in an assertion failure. This is useful to check that some routine does not allocate memory + dynamically. Not defined by default. + - \b EIGEN_RUNTIME_NO_MALLOC - if defined, a new switch is introduced which can be turned on and off by + calling set_is_malloc_allowed(bool). If malloc is not allowed and %Eigen tries to allocate memory + dynamically anyway, an assertion failure results. Not defined by default. + +*/ + +} diff --git a/doc/QuickStartGuide.dox b/doc/QuickStartGuide.dox new file mode 100644 index 000000000..ea32c3b3d --- /dev/null +++ b/doc/QuickStartGuide.dox @@ -0,0 +1,100 @@ +namespace Eigen { + +/** \page GettingStarted Getting started + +\eigenAutoToc + +This is a very short guide on how to get started with Eigen. It has a dual purpose. It serves as a minimal introduction to the Eigen library for people who want to start coding as soon as possible. You can also read this page as the first part of the Tutorial, which explains the library in more detail; in this case you will continue with \ref TutorialMatrixClass. + +\section GettingStartedInstallation How to "install" Eigen? + +In order to use Eigen, you just need to download and extract Eigen's source code (see the wiki for download instructions). In fact, the header files in the \c Eigen subdirectory are the only files required to compile programs using Eigen. The header files are the same for all platforms. It is not necessary to use CMake or install anything. + + +\section GettingStartedFirstProgram A simple first program + +Here is a rather simple program to get you started. + +\include QuickStart_example.cpp + +We will explain the program after telling you how to compile it. + + +\section GettingStartedCompiling Compiling and running your first program + +There is no library to link to. The only thing that you need to keep in mind when compiling the above program is that the compiler must be able to find the Eigen header files. The directory in which you placed Eigen's source code must be in the include path. With GCC you use the -I option to achieve this, so you can compile the program with a command like this: + +\code g++ -I /path/to/eigen/ my_program.cpp -o my_program \endcode + +On Linux or Mac OS X, another option is to symlink or copy the Eigen folder into /usr/local/include/. This way, you can compile the program with: + +\code g++ my_program.cpp -o my_program \endcode + +When you run the program, it produces the following output: + +\include QuickStart_example.out + + +\section GettingStartedExplanation Explanation of the first program + +The Eigen header files define many types, but for simple applications it may be enough to use only the \c MatrixXd type. This represents a matrix of arbitrary size (hence the \c X in \c MatrixXd), in which every entry is a \c double (hence the \c d in \c MatrixXd). See the \ref QuickRef_Types "quick reference guide" for an overview of the different types you can use to represent a matrix. + +The \c Eigen/Dense header file defines all member functions for the MatrixXd type and related types (see also the \ref QuickRef_Headers "table of header files"). All classes and functions defined in this header file (and other Eigen header files) are in the \c Eigen namespace. + +The first line of the \c main function declares a variable of type \c MatrixXd and specifies that it is a matrix with 2 rows and 2 columns (the entries are not initialized). The statement m(0,0) = 3 sets the entry in the top-left corner to 3. You need to use round parentheses to refer to entries in the matrix. As usual in computer science, the index of the first index is 0, as opposed to the convention in mathematics that the first index is 1. + +The following three statements sets the other three entries. The final line outputs the matrix \c m to the standard output stream. + + +\section GettingStartedExample2 Example 2: Matrices and vectors + +Here is another example, which combines matrices with vectors. Concentrate on the left-hand program for now; we will talk about the right-hand program later. + + + + +
Size set at run time:Size set at compile time:
+\include QuickStart_example2_dynamic.cpp + +\include QuickStart_example2_fixed.cpp +
+ +The output is as follows: + +\include QuickStart_example2_dynamic.out + + +\section GettingStartedExplanation2 Explanation of the second example + +The second example starts by declaring a 3-by-3 matrix \c m which is initialized using the \link DenseBase::Random(Index,Index) Random() \endlink method with random values between -1 and 1. The next line applies a linear mapping such that the values are between 10 and 110. The function call \link DenseBase::Constant(Index,Index,const Scalar&) MatrixXd::Constant\endlink(3,3,1.2) returns a 3-by-3 matrix expression having all coefficients equal to 1.2. The rest is standard arithmetics. + +The next line of the \c main function introduces a new type: \c VectorXd. This represents a (column) vector of arbitrary size. Here, the vector \c v is created to contain \c 3 coefficients which are left unitialized. The one but last line uses the so-called comma-initializer, explained in \ref TutorialAdvancedInitialization, to set all coefficients of the vector \c v to be as follows: + +\f[ +v = +\begin{bmatrix} + 1 \\ + 2 \\ + 3 +\end{bmatrix}. +\f] + +The final line of the program multiplies the matrix \c m with the vector \c v and outputs the result. + +Now look back at the second example program. We presented two versions of it. In the version in the left column, the matrix is of type \c MatrixXd which represents matrices of arbitrary size. The version in the right column is similar, except that the matrix is of type \c Matrix3d, which represents matrices of a fixed size (here 3-by-3). Because the type already encodes the size of the matrix, it is not necessary to specify the size in the constructor; compare MatrixXd m(3,3) with Matrix3d m. Similarly, we have \c VectorXd on the left (arbitrary size) versus \c Vector3d on the right (fixed size). Note that here the coefficients of vector \c v are directly set in the constructor, though the same syntax of the left example could be used too. + +The use of fixed-size matrices and vectors has two advantages. The compiler emits better (faster) code because it knows the size of the matrices and vectors. Specifying the size in the type also allows for more rigorous checking at compile-time. For instance, the compiler will complain if you try to multiply a \c Matrix4d (a 4-by-4 matrix) with a \c Vector3d (a vector of size 3). However, the use of many types increases compilation time and the size of the executable. The size of the matrix may also not be known at compile-time. A rule of thumb is to use fixed-size matrices for size 4-by-4 and smaller. + + +\section GettingStartedConclusion Where to go from here? + +It's worth taking the time to read the \ref TutorialMatrixClass "long tutorial". + +However if you think you don't need it, you can directly use the classes documentation and our \ref QuickRefPage. + +\li \b Next: \ref TutorialMatrixClass + +*/ + +} + diff --git a/doc/SparseLinearSystems.dox b/doc/SparseLinearSystems.dox new file mode 100644 index 000000000..e447c40ce --- /dev/null +++ b/doc/SparseLinearSystems.dox @@ -0,0 +1,107 @@ +namespace Eigen { +/** \eigenManualPage TopicSparseSystems Solving Sparse Linear Systems +In Eigen, there are several methods available to solve linear systems when the coefficient matrix is sparse. Because of the special representation of this class of matrices, special care should be taken in order to get a good performance. See \ref TutorialSparse for a detailed introduction about sparse matrices in Eigen. In this page, we briefly present the main steps that are common to all the linear solvers in Eigen together with the main concepts behind them. Depending on the properties of the matrix, the desired accuracy, the end-user is able to tune these steps in order to improve the performance of its code. However, an impatient user does not need to know deeply what's hiding behind these steps: the last section presents a benchmark routine that can be easily used to get an insight on the performance of all the available solvers. + +\eigenAutoToc + + As summarized in \ref TutorialSparseDirectSolvers, there are many built-in solvers in Eigen as well as interface to external solvers libraries. All these solvers follow the same calling sequence. The basic steps are as follows : +\code +#include +// ... +SparseMatrix A; +// fill A +VectorXd b, x; +// fill b +// solve Ax = b +SolverClassName > solver; +solver.compute(A); +if(solver.info()!=Succeeded) { + // decomposition failed + return; +} +x = solver.solve(b); +if(solver.info()!=Succeeded) { + // solving failed + return; +} +\endcode + +\section TheSparseCompute The Compute Step +In the compute() function, the matrix is generally factorized: LLT for self-adjoint matrices, LDLT for general hermitian matrices and LU for non hermitian matrices. These are the results of using direct solvers. For this class of solvers precisely, the compute step is further subdivided into analyzePattern() and factorize(). + +The goal of analyzePattern() is to reorder the nonzero elements of the matrix, such that the factorization step creates less fill-in. This step exploits only the structure of the matrix. Hence, the results of this step can be used for other linear systems where the matrix has the same structure. Note however that sometimes, some external solvers (like SuperLU) require that the values of the matrix are set in this step, for instance to equilibrate the rows and columns of the matrix. In this situation, the results of this step can note be used with other matrices. + +Eigen provides a limited set of methods to reorder the matrix in this step, either built-in (COLAMD, AMD) or external (METIS). These methods are set in template parameter list of the solver : +\code +DirectSolverClassName, OrderingMethod > solver; +\endcode + +See the \link OrderingMethods_Module OrderingMethods module \endlink for the list of available methods and the associated options. + +In factorize(), the factors of the coefficient matrix are computed. This step should be called each time the values of the matrix change. However, the structural pattern of the matrix should not change between multiple calls. + +For iterative solvers, the compute step is used to eventually setup a preconditioner. Remember that, basically, the goal of the preconditioner is to speedup the convergence of an iterative method by solving a modified linear system where the coefficient matrix has more clustered eigenvalues. For real problems, an iterative solver should always be used with a preconditioner. In Eigen, a preconditioner is selected by simply adding it as a template parameter to the iterative solver object. +\code +IterativeSolverClassName, PreconditionerName > solver; +\endcode +The member function preconditioner() returns a read-write reference to the preconditioner + to directly interact with it. + +For instance, with the ILUT preconditioner, the incomplete factors L and U are computed in this step. +See \link Sparse_modules the Sparse module \endlink for the list of available preconditioners in Eigen. +\section TheSparseSolve The Solve step +The solve() function computes the solution of the linear systems with one or many right hand sides. +\code +X = solver.solve(B); +\endcode +Here, B can be a vector or a matrix where the columns form the different right hand sides. The solve() function can be called several times as well, for instance When all the right hand sides are not available at once. +\code +x1 = solver.solve(b1); +// Get the second right hand side b2 +x2 = solver.solve(b2); +// ... +\endcode +For direct methods, the solution are computed at the machine precision. Sometimes, the solution need not be too accurate. In this case, the iterative methods are more suitable and the desired accuracy can be set before the solve step using setTolerance(). For all the available functions, please, refer to the documentation of the \link IterativeLinearSolvers_Module Iterative solvers module \endlink. + +\section BenchmarkRoutine +Most of the time, all you need is to know how much time it will take to qolve your system, and hopefully, what is the most suitable solver. In Eigen, we provide a benchmark routine that can be used for this purpose. It is very easy to use. First, it should be activated at the configuration step with the flag TEST_REAL_CASES. Then, in bench/spbench, you can compile the routine by typing \b make \e spbenchsolver. You can then run it with --help option to get the list of all available options. Basically, the matrices to test should be in MatrixMarket Coordinate format, and the routine returns the statistics from all available solvers in Eigen. + +The following table gives an example of XHTML statistics from several Eigen built-in and external solvers. + + +
Matrix N NNZ UMFPACK SUPERLU PASTIX LU BiCGSTAB BiCGSTAB+ILUT GMRES+ILUT LDLT CHOLMOD LDLT PASTIX LDLT LLT CHOLMOD SP LLT CHOLMOD LLT PASTIX LLT CG
vector_graphics 12855 72069 Compute Time 0.02545490.02156770.07018270.0001533880.01401070.01537090.01016010.009305020.0649689 +
Solve Time 0.003378350.0009518260.004843730.03748860.00464450.008477540.0005418130.0002936960.00485376 +
Total Time 0.02883330.02251950.07502650.0376420.01865520.02384840.01070190.009598710.0698227 +
Error(Iter) 1.299e-16 2.04207e-16 4.83393e-15 3.94856e-11 (80) 1.03861e-12 (3) 5.81088e-14 (6) 1.97578e-16 1.83927e-16 4.24115e-15 +
poisson_SPD 19788 308232 Compute Time 0.4250261.823780.6173670.0004789211.340011.334710.7964190.8575730.4730070.8148260.1847190.8615550.4705590.000458188 +
Solve Time 0.02800530.01944020.02687470.2494370.05484440.09269910.008502040.00531710.02589320.008746030.005781550.005303610.02489420.239093 +
Total Time 0.4530311.843220.6442410.2499161.394861.427410.8049210.8628910.49890.8235720.1905010.8668590.4954530.239551 +
Error(Iter) 4.67146e-16 1.068e-15 1.3397e-15 6.29233e-11 (201) 3.68527e-11 (6) 3.3168e-15 (16) 1.86376e-15 1.31518e-16 1.42593e-15 3.45361e-15 3.14575e-16 2.21723e-15 7.21058e-16 9.06435e-12 (261) +
sherman2 1080 23094 Compute Time 0.006317540.0150520.0247514 -0.02144250.0217988 +
Solve Time 0.0004784240.0003379980.0010291 -0.002431520.00246152 +
Total Time 0.006795970.015390.0257805 -0.0238740.0242603 +
Error(Iter) 1.83099e-15 8.19351e-15 2.625e-14 1.3678e+69 (1080) 4.1911e-12 (7) 5.0299e-13 (12) +
bcsstk01_SPD 48 400 Compute Time 0.0001690790.000107890.0005725381.425e-069.1612e-058.3985e-055.6489e-057.0913e-050.0004682515.7389e-058.0212e-055.8394e-050.0004630171.333e-06 +
Solve Time 1.2288e-051.1124e-050.0002863878.5896e-051.6381e-051.6984e-053.095e-064.115e-060.0003254383.504e-067.369e-063.454e-060.0002940956.0516e-05 +
Total Time 0.0001813670.0001190140.0008589258.7321e-050.0001079930.0001009695.9584e-057.5028e-050.0007936896.0893e-058.7581e-056.1848e-050.0007571126.1849e-05 +
Error(Iter) 1.03474e-16 2.23046e-16 2.01273e-16 4.87455e-07 (48) 1.03553e-16 (2) 3.55965e-16 (2) 2.48189e-16 1.88808e-16 1.97976e-16 2.37248e-16 1.82701e-16 2.71474e-16 2.11322e-16 3.547e-09 (48) +
sherman1 1000 3750 Compute Time 0.002288050.002092310.005282689.846e-060.001635220.001621550.0007892590.0008044950.00438269 +
Solve Time 0.0002137889.7983e-050.0009388310.006298350.0003617640.000787944.3989e-052.5331e-050.000917166 +
Total Time 0.002501840.002190290.006221510.00630820.001996980.002409490.0008332480.0008298260.00529986 +
Error(Iter) 1.16839e-16 2.25968e-16 2.59116e-16 3.76779e-11 (248) 4.13343e-11 (4) 2.22347e-14 (10) 2.05861e-16 1.83555e-16 1.02917e-15 +
young1c 841 4089 Compute Time 0.002358430.002172280.005680751.2735e-050.002648660.00258236 +
Solve Time 0.0003295990.0001686340.000801180.05347380.001871930.00450211 +
Total Time 0.002688030.002340910.006481930.05348650.004520590.00708447 +
Error(Iter) 1.27029e-16 2.81321e-16 5.0492e-15 8.0507e-11 (706) 3.00447e-12 (8) 1.46532e-12 (16) +
mhd1280b 1280 22778 Compute Time 0.002348980.002070790.005709182.5976e-050.003025630.002980360.001445250.0009199220.00426444 +
Solve Time 0.001033920.0002119110.001050.01104320.0006282870.003920890.0001383036.2446e-050.00097564 +
Total Time 0.00338290.00228270.006759180.01106920.003653920.006901240.001583550.0009823680.00524008 +
Error(Iter) 1.32953e-16 3.08646e-16 6.734e-16 8.83132e-11 (40) 1.51153e-16 (1) 6.08556e-16 (8) 1.89264e-16 1.97477e-16 6.68126e-09 +
crashbasis 160000 1750416 Compute Time 3.20195.789215.75730.003835153.10063.09921 +
Solve Time 0.2619150.1062250.4021411.490890.248880.443673 +
Total Time 3.463815.8954216.15941.494733.349483.54288 +
Error(Iter) 1.76348e-16 4.58395e-16 1.67982e-14 8.64144e-11 (61) 8.5996e-12 (2) 6.04042e-14 (5) + +
+*/ +} diff --git a/doc/StlContainers.dox b/doc/StlContainers.dox new file mode 100644 index 000000000..d8d0d529c --- /dev/null +++ b/doc/StlContainers.dox @@ -0,0 +1,62 @@ +namespace Eigen { + +/** \eigenManualPage TopicStlContainers Using STL Containers with Eigen + +\eigenAutoToc + +\section summary Executive summary + +Using STL containers on \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types", or classes having members of such types, requires taking the following two steps: + +\li A 16-byte-aligned allocator must be used. Eigen does provide one ready for use: aligned_allocator. +\li If you want to use the std::vector container, you need to \#include . + +These issues arise only with \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types" and \ref TopicStructHavingEigenMembers "structures having such Eigen objects as member". For other Eigen types, such as Vector3f or MatrixXd, no special care is needed when using STL containers. + +\section allocator Using an aligned allocator + +STL containers take an optional template parameter, the allocator type. When using STL containers on \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types", you need tell the container to use an allocator that will always allocate memory at 16-byte-aligned locations. Fortunately, Eigen does provide such an allocator: Eigen::aligned_allocator. + +For example, instead of +\code +std::map +\endcode +you need to use +\code +std::map, + Eigen::aligned_allocator > > +\endcode +Note that the third parameter "std::less" is just the default value, but we have to include it because we want to specify the fourth parameter, which is the allocator type. + +\section vector The case of std::vector + +The situation with std::vector was even worse (explanation below) so we had to specialize it for the Eigen::aligned_allocator type. In practice you \b must use the Eigen::aligned_allocator (not another aligned allocator), \b and \#include . + +Here is an example: +\code +#include +/* ... */ +std::vector > +\endcode + +\subsection vector_spec An alternative - specializing std::vector for Eigen types + +As an alternative to the recommended approach described above, you have the option to specialize std::vector for Eigen types requiring alignment. +The advantage is that you won't need to declare std::vector all over with Eigen::allocator. One drawback on the other hand side is that +the specialization needs to be defined before all code pieces in which e.g. std::vector is used. Otherwise, without knowing the specialization +the compiler will compile that particular instance with the default std::allocator and you program is most likely to crash. + +Here is an example: +\code +#include +/* ... */ +EIGEN_DEFINE_STL_VECTOR_SPECIALIZATION(Matrix2d) +std::vector +\endcode + +\b Explanation: The resize() method of std::vector takes a value_type argument (defaulting to value_type()). So with std::vector, some Eigen::Vector4f objects will be passed by value, which discards any alignment modifiers, so a Eigen::Vector4f can be created at an unaligned location. In order to avoid that, the only solution we saw was to specialize std::vector to make it work on a slight modification of, here, Eigen::Vector4f, that is able to deal properly with this situation. + + +*/ + +} diff --git a/doc/StorageOrders.dox b/doc/StorageOrders.dox new file mode 100644 index 000000000..61645313e --- /dev/null +++ b/doc/StorageOrders.dox @@ -0,0 +1,86 @@ +namespace Eigen { + +/** \eigenManualPage TopicStorageOrders Storage orders + +There are two different storage orders for matrices and two-dimensional arrays: column-major and row-major. +This page explains these storage orders and how to specify which one should be used. + +\eigenAutoToc + + +\section TopicStorageOrdersIntro Column-major and row-major storage + +The entries of a matrix form a two-dimensional grid. However, when the matrix is stored in memory, the entries +have to somehow be laid out linearly. There are two main ways to do this, by row and by column. + +We say that a matrix is stored in \b row-major order if it is stored row by row. The entire first row is +stored first, followed by the entire second row, and so on. Consider for example the matrix + +\f[ +A = \begin{bmatrix} +8 & 2 & 2 & 9 \\ +9 & 1 & 4 & 4 \\ +3 & 5 & 4 & 5 +\end{bmatrix}. +\f] + +If this matrix is stored in row-major order, then the entries are laid out in memory as follows: + +\code 8 2 2 9 9 1 4 4 3 5 4 5 \endcode + +On the other hand, a matrix is stored in \b column-major order if it is stored column by column, starting with +the entire first column, followed by the entire second column, and so on. If the above matrix is stored in +column-major order, it is laid out as follows: + +\code 8 9 3 2 1 5 2 4 4 9 4 5 \endcode + +This example is illustrated by the following Eigen code. It uses the PlainObjectBase::data() function, which +returns a pointer to the memory location of the first entry of the matrix. + + + + +
ExampleOutput
+\include TopicStorageOrders_example.cpp + +\verbinclude TopicStorageOrders_example.out +
+ + +\section TopicStorageOrdersInEigen Storage orders in Eigen + +The storage order of a matrix or a two-dimensional array can be set by specifying the \c Options template +parameter for Matrix or Array. As \ref TutorialMatrixClass explains, the %Matrix class template has six +template parameters, of which three are compulsory (\c Scalar, \c RowsAtCompileTime and \c ColsAtCompileTime) +and three are optional (\c Options, \c MaxRowsAtCompileTime and \c MaxColsAtCompileTime). If the \c Options +parameter is set to \c RowMajor, then the matrix or array is stored in row-major order; if it is set to +\c ColMajor, then it is stored in column-major order. This mechanism is used in the above Eigen program to +specify the storage order. + +If the storage order is not specified, then Eigen defaults to storing the entry in column-major. This is also +the case if one of the convenience typedefs (\c Matrix3f, \c ArrayXXd, etc.) is used. + +Matrices and arrays using one storage order can be assigned to matrices and arrays using the other storage +order, as happens in the above program when \c Arowmajor is initialized using \c Acolmajor. Eigen will reorder +the entries automatically. More generally, row-major and column-major matrices can be mixed in an expression +as we want. + + +\section TopicStorageOrdersWhich Which storage order to choose? + +So, which storage order should you use in your program? There is no simple answer to this question; it depends +on your application. Here are some points to keep in mind: + + - Your users may expect you to use a specific storage order. Alternatively, you may use other libraries than + Eigen, and these other libraries may expect a certain storage order. In these cases it may be easiest and + fastest to use this storage order in your whole program. + - Algorithms that traverse a matrix row by row will go faster when the matrix is stored in row-major order + because of better data locality. Similarly, column-by-column traversal is faster for column-major + matrices. It may be worthwhile to experiment a bit to find out what is faster for your particular + application. + - The default in Eigen is column-major. Naturally, most of the development and testing of the Eigen library + is thus done with column-major matrices. This means that, even though we aim to support column-major and + row-major storage orders transparently, the Eigen library may well work best with column-major matrices. + +*/ +} diff --git a/doc/StructHavingEigenMembers.dox b/doc/StructHavingEigenMembers.dox new file mode 100644 index 000000000..74a8d5217 --- /dev/null +++ b/doc/StructHavingEigenMembers.dox @@ -0,0 +1,190 @@ +namespace Eigen { + +/** \eigenManualPage TopicStructHavingEigenMembers Structures Having Eigen Members + +\eigenAutoToc + +\section summary Executive Summary + +If you define a structure having members of \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types", you must overload its "operator new" so that it generates 16-bytes-aligned pointers. Fortunately, Eigen provides you with a macro EIGEN_MAKE_ALIGNED_OPERATOR_NEW that does that for you. + +\section what What kind of code needs to be changed? + +The kind of code that needs to be changed is this: + +\code +class Foo +{ + ... + Eigen::Vector2d v; + ... +}; + +... + +Foo *foo = new Foo; +\endcode + +In other words: you have a class that has as a member a \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen object", and then you dynamically create an object of that class. + +\section how How should such code be modified? + +Very easy, you just need to put a EIGEN_MAKE_ALIGNED_OPERATOR_NEW macro in a public part of your class, like this: + +\code +class Foo +{ + ... + Eigen::Vector2d v; + ... +public: + EIGEN_MAKE_ALIGNED_OPERATOR_NEW +}; + +... + +Foo *foo = new Foo; +\endcode + +This macro makes "new Foo" always return an aligned pointer. + +If this approach is too intrusive, see also the \ref othersolutions. + +\section why Why is this needed? + +OK let's say that your code looks like this: + +\code +class Foo +{ + ... + Eigen::Vector2d v; + ... +}; + +... + +Foo *foo = new Foo; +\endcode + +A Eigen::Vector2d consists of 2 doubles, which is 128 bits. Which is exactly the size of a SSE packet, which makes it possible to use SSE for all sorts of operations on this vector. But SSE instructions (at least the ones that Eigen uses, which are the fast ones) require 128-bit alignment. Otherwise you get a segmentation fault. + +For this reason, Eigen takes care by itself to require 128-bit alignment for Eigen::Vector2d, by doing two things: +\li Eigen requires 128-bit alignment for the Eigen::Vector2d's array (of 2 doubles). With GCC, this is done with a __attribute__ ((aligned(16))). +\li Eigen overloads the "operator new" of Eigen::Vector2d so it will always return 128-bit aligned pointers. + +Thus, normally, you don't have to worry about anything, Eigen handles alignment for you... + +... except in one case. When you have a class Foo like above, and you dynamically allocate a new Foo as above, then, since Foo doesn't have aligned "operator new", the returned pointer foo is not necessarily 128-bit aligned. + +The alignment attribute of the member v is then relative to the start of the class, foo. If the foo pointer wasn't aligned, then foo->v won't be aligned either! + +The solution is to let class Foo have an aligned "operator new", as we showed in the previous section. + +\section movetotop Should I then put all the members of Eigen types at the beginning of my class? + +That's not required. Since Eigen takes care of declaring 128-bit alignment, all members that need it are automatically 128-bit aligned relatively to the class. So code like this works fine: + +\code +class Foo +{ + double x; + Eigen::Vector2d v; +public: + EIGEN_MAKE_ALIGNED_OPERATOR_NEW +}; +\endcode + +\section dynamicsize What about dynamic-size matrices and vectors? + +Dynamic-size matrices and vectors, such as Eigen::VectorXd, allocate dynamically their own array of coefficients, so they take care of requiring absolute alignment automatically. So they don't cause this issue. The issue discussed here is only with \ref TopicFixedSizeVectorizable "fixed-size vectorizable matrices and vectors". + +\section bugineigen So is this a bug in Eigen? + +No, it's not our bug. It's more like an inherent problem of the C++98 language specification, and seems to be taken care of in the upcoming language revision: see this document. + +\section conditional What if I want to do this conditionnally (depending on template parameters) ? + +For this situation, we offer the macro EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF(NeedsToAlign). It will generate aligned operators like EIGEN_MAKE_ALIGNED_OPERATOR_NEW if NeedsToAlign is true. It will generate operators with the default alignment if NeedsToAlign is false. + +Example: + +\code +template class Foo +{ + typedef Eigen::Matrix Vector; + enum { NeedsToAlign = (sizeof(Vector)%16)==0 }; + ... + Vector v; + ... +public: + EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF(NeedsToAlign) +}; + +... + +Foo<4> *foo4 = new Foo<4>; // foo4 is guaranteed to be 128bit-aligned +Foo<3> *foo3 = new Foo<3>; // foo3 has only the system default alignment guarantee +\endcode + + +\section othersolutions Other solutions + +In case putting the EIGEN_MAKE_ALIGNED_OPERATOR_NEW macro everywhere is too intrusive, there exists at least two other solutions. + +\subsection othersolutions1 Disabling alignment + +The first is to disable alignment requirement for the fixed size members: +\code +class Foo +{ + ... + Eigen::Matrix v; + ... +}; +\endcode +This has for effect to disable vectorization when using \c v. +If a function of Foo uses it several times, then it still possible to re-enable vectorization by copying it into an aligned temporary vector: +\code +void Foo::bar() +{ + Eigen::Vector2d av(v); + // use av instead of v + ... + // if av changed, then do: + v = av; +} +\endcode + +\subsection othersolutions2 Private structure + +The second consist in storing the fixed-size objects into a private struct which will be dynamically allocated at the construction time of the main object: + +\code +struct Foo_d +{ + EIGEN_MAKE_ALIGNED_OPERATOR_NEW + Vector2d v; + ... +}; + + +struct Foo { + Foo() { init_d(); } + ~Foo() { delete d; } + void bar() + { + // use d->v instead of v + ... + } +private: + void init_d() { d = new Foo_d; } + Foo_d* d; +}; +\endcode + +The clear advantage here is that the class Foo remains unchanged regarding alignment issues. The drawback is that a heap allocation will be required whatsoever. + +*/ + +} diff --git a/doc/TemplateKeyword.dox b/doc/TemplateKeyword.dox new file mode 100644 index 000000000..f4e4f237e --- /dev/null +++ b/doc/TemplateKeyword.dox @@ -0,0 +1,132 @@ +namespace Eigen { + +/** \page TopicTemplateKeyword The template and typename keywords in C++ + +There are two uses for the \c template and \c typename keywords in C++. One of them is fairly well known +amongst programmers: to define templates. The other use is more obscure: to specify that an expression refers +to a template function or a type. This regularly trips up programmers that use the %Eigen library, often +leading to error messages from the compiler that are difficult to understand. + +\eigenAutoToc + + +\section TopicTemplateKeywordToDefineTemplates Using the template and typename keywords to define templates + +The \c template and \c typename keywords are routinely used to define templates. This is not the topic of this +page as we assume that the reader is aware of this (otherwise consult a C++ book). The following example +should illustrate this use of the \c template keyword. + +\code +template +bool isPositive(T x) +{ + return x > 0; +} +\endcode + +We could just as well have written template <class T>; the keywords \c typename and \c class have the +same meaning in this context. + + +\section TopicTemplateKeywordExample An example showing the second use of the template keyword + +Let us illustrate the second use of the \c template keyword with an example. Suppose we want to write a +function which copies all entries in the upper triangular part of a matrix into another matrix, while keeping +the lower triangular part unchanged. A straightforward implementation would be as follows: + + + + +
Example:Output:
+\include TemplateKeyword_simple.cpp + +\verbinclude TemplateKeyword_simple.out +
+ +That works fine, but it is not very flexible. First, it only works with dynamic-size matrices of +single-precision floats; the function \c copyUpperTriangularPart() does not accept static-size matrices or +matrices with double-precision numbers. Second, if you use an expression such as +mat.topLeftCorner(3,3) as the parameter \c src, then this is copied into a temporary variable of type +MatrixXf; this copy can be avoided. + +As explained in \ref TopicFunctionTakingEigenTypes, both issues can be resolved by making +\c copyUpperTriangularPart() accept any object of type MatrixBase. This leads to the following code: + + + + +
Example:Output:
+\include TemplateKeyword_flexible.cpp + +\verbinclude TemplateKeyword_flexible.out +
+ +The one line in the body of the function \c copyUpperTriangularPart() shows the second, more obscure use of +the \c template keyword in C++. Even though it may look strange, the \c template keywords are necessary +according to the standard. Without it, the compiler may reject the code with an error message like "no match +for operator<". + + +\section TopicTemplateKeywordExplanation Explanation + +The reason that the \c template keyword is necessary in the last example has to do with the rules for how +templates are supposed to be compiled in C++. The compiler has to check the code for correct syntax at the +point where the template is defined, without knowing the actual value of the template arguments (\c Derived1 +and \c Derived2 in the example). That means that the compiler cannot know that dst.triangularPart is +a member template and that the following < symbol is part of the delimiter for the template +parameter. Another possibility would be that dst.triangularPart is a member variable with the < +symbol refering to the operator<() function. In fact, the compiler should choose the second +possibility, according to the standard. If dst.triangularPart is a member template (as in our case), +the programmer should specify this explicitly with the \c template keyword and write dst.template +triangularPart. + +The precise rules are rather complicated, but ignoring some subtleties we can summarize them as follows: +- A dependent name is name that depends (directly or indirectly) on a template parameter. In the + example, \c dst is a dependent name because it is of type MatrixBase<Derived1> which depends + on the template parameter \c Derived1. +- If the code contains either one of the contructions xxx.yyy or xxx->yyy and \c xxx is a + dependent name and \c yyy refers to a member template, then the \c template keyword must be used before + \c yyy, leading to xxx.template yyy or xxx->template yyy. +- If the code contains the contruction xxx::yyy and \c xxx is a dependent name and \c yyy refers to a + member typedef, then the \c typename keyword must be used before the whole construction, leading to + typename xxx::yyy. + +As an example where the \c typename keyword is required, consider the following code in \ref TutorialSparse +for iterating over the non-zero entries of a sparse matrix type: + +\code +SparseMatrixType mat(rows,cols); +for (int k=0; k +void iterateOverSparseMatrix(const SparseMatrix& mat; +{ + for (int k=0; k::InnerIterator it(mat,k); it; ++it) + { + /* ... */ + } +} +\endcode + + +\section TopicTemplateKeywordResources Resources for further reading + +For more information and a fuller explanation of this topic, the reader may consult the following sources: +- The book "C++ Template Metaprogramming" by David Abrahams and Aleksey Gurtovoy contains a very good + explanation in Appendix B ("The typename and template Keywords") which formed the basis for this page. +- http://pages.cs.wisc.edu/~driscoll/typename.html +- http://www.parashift.com/c++-faq-lite/templates.html#faq-35.18 +- http://www.comeaucomputing.com/techtalk/templates/#templateprefix +- http://www.comeaucomputing.com/techtalk/templates/#typename + +*/ +} diff --git a/doc/TopicAliasing.dox b/doc/TopicAliasing.dox new file mode 100644 index 000000000..bd1d329ce --- /dev/null +++ b/doc/TopicAliasing.dox @@ -0,0 +1,209 @@ +namespace Eigen { + +/** \eigenManualPage TopicAliasing Aliasing + +In Eigen, aliasing refers to assignment statement in which the same matrix (or array or vector) appears on the +left and on the right of the assignment operators. Statements like mat = 2 * mat; or mat = +mat.transpose(); exhibit aliasing. The aliasing in the first example is harmless, but the aliasing in the +second example leads to unexpected results. This page explains what aliasing is, when it is harmful, and what +to do about it. + +\eigenAutoToc + + +\section TopicAliasingExamples Examples + +Here is a simple example exhibiting aliasing: + + + + +
ExampleOutput
+\include TopicAliasing_block.cpp + +\verbinclude TopicAliasing_block.out +
+ +The output is not what one would expect. The problem is the assignment +\code +mat.bottomRightCorner(2,2) = mat.topLeftCorner(2,2); +\endcode +This assignment exhibits aliasing: the coefficient \c mat(1,1) appears both in the block +mat.bottomRightCorner(2,2) on the left-hand side of the assignment and the block +mat.topLeftCorner(2,2) on the right-hand side. After the assignment, the (2,2) entry in the bottom +right corner should have the value of \c mat(1,1) before the assignment, which is 5. However, the output shows +that \c mat(2,2) is actually 1. The problem is that Eigen uses lazy evaluation (see +\ref TopicEigenExpressionTemplates) for mat.topLeftCorner(2,2). The result is similar to +\code +mat(1,1) = mat(0,0); +mat(1,2) = mat(0,1); +mat(2,1) = mat(1,0); +mat(2,2) = mat(1,1); +\endcode +Thus, \c mat(2,2) is assigned the \e new value of \c mat(1,1) instead of the old value. The next section +explains how to solve this problem by calling \link DenseBase::eval() eval()\endlink. + +Note that if \c mat were a bigger, then the blocks would not overlap, and there would be no aliasing +problem. This means that in general aliasing cannot be detected at compile time. However, Eigen does detect +some instances of aliasing, albeit at run time. The following example exhibiting aliasing was mentioned in +\ref TutorialMatrixArithmetic : + + + + +
ExampleOutput
+\include tut_arithmetic_transpose_aliasing.cpp + +\verbinclude tut_arithmetic_transpose_aliasing.out +
+ +Again, the output shows the aliasing issue. However, by default Eigen uses a run-time assertion to detect this +and exits with a message like + +\verbatim +void Eigen::DenseBase::checkTransposeAliasing(const OtherDerived&) const +[with OtherDerived = Eigen::Transpose >, Derived = Eigen::Matrix]: +Assertion `(!internal::check_transpose_aliasing_selector::IsTransposed,OtherDerived>::run(internal::extract_data(derived()), other)) +&& "aliasing detected during tranposition, use transposeInPlace() or evaluate the rhs into a temporary using .eval()"' failed. +\endverbatim + +The user can turn Eigen's run-time assertions like the one to detect this aliasing problem off by defining the +EIGEN_NO_DEBUG macro, and the above program was compiled with this macro turned off in order to illustrate the +aliasing problem. See \ref TopicAssertions for more information about Eigen's run-time assertions. + + +\section TopicAliasingSolution Resolving aliasing issues + +If you understand the cause of the aliasing issue, then it is obvious what must happen to solve it: Eigen has +to evaluate the right-hand side fully into a temporary matrix/array and then assign it to the left-hand +side. The function \link DenseBase::eval() eval() \endlink does precisely that. + +For example, here is the corrected version of the first example above: + + + + +
ExampleOutput
+\include TopicAliasing_block_correct.cpp + +\verbinclude TopicAliasing_block_correct.out +
+ +Now, \c mat(2,2) equals 5 after the assignment, as it should be. + +The same solution also works for the second example, with the transpose: simply replace the line +a = a.transpose(); with a = a.transpose().eval();. However, in this common case there is a +better solution. Eigen provides the special-purpose function +\link DenseBase::transposeInPlace() transposeInPlace() \endlink which replaces a matrix by its transpose. +This is shown below: + + + + +
ExampleOutput
+\include tut_arithmetic_transpose_inplace.cpp + +\verbinclude tut_arithmetic_transpose_inplace.out +
+ +If an xxxInPlace() function is available, then it is best to use it, because it indicates more clearly what you +are doing. This may also allow Eigen to optimize more aggressively. These are some of the xxxInPlace() +functions provided: + + + + + + + + + +
Original functionIn-place function
MatrixBase::adjoint() MatrixBase::adjointInPlace()
DenseBase::reverse() DenseBase::reverseInPlace()
LDLT::solve() LDLT::solveInPlace()
LLT::solve() LLT::solveInPlace()
TriangularView::solve() TriangularView::solveInPlace()
DenseBase::transpose() DenseBase::transposeInPlace()
+ + +\section TopicAliasingCwise Aliasing and component-wise operations + +As explained above, it may be dangerous if the same matrix or array occurs on both the left-hand side and the +right-hand side of an assignment operator, and it is then often necessary to evaluate the right-hand side +explicitly. However, applying component-wise operations (such as matrix addition, scalar multiplication and +array multiplication) is safe. + +The following example has only component-wise operations. Thus, there is no need for .eval() even though +the same matrix appears on both sides of the assignments. + + + + +
ExampleOutput
+\include TopicAliasing_cwise.cpp + +\verbinclude TopicAliasing_cwise.out +
+ +In general, an assignment is safe if the (i,j) entry of the expression on the right-hand side depends only on +the (i,j) entry of the matrix or array on the left-hand side and not on any other entries. In that case it is +not necessary to evaluate the right-hand side explicitly. + + +\section TopicAliasingMatrixMult Aliasing and matrix multiplication + +Matrix multiplication is the only operation in Eigen that assumes aliasing by default. Thus, if \c matA is a +matrix, then the statement matA = matA * matA; is safe. All other operations in Eigen assume that +there are no aliasing problems, either because the result is assigned to a different matrix or because it is a +component-wise operation. + + + + +
ExampleOutput
+\include TopicAliasing_mult1.cpp + +\verbinclude TopicAliasing_mult1.out +
+ +However, this comes at a price. When executing the expression matA = matA * matA, Eigen evaluates the +product in a temporary matrix which is assigned to \c matA after the computation. This is fine. But Eigen does +the same when the product is assigned to a different matrix (e.g., matB = matA * matA). In that case, +it is more efficient to evaluate the product directly into \c matB instead of evaluating it first into a +temporary matrix and copying that matrix to \c matB. + +The user can indicate with the \link MatrixBase::noalias() noalias()\endlink function that there is no +aliasing, as follows: matB.noalias() = matA * matA. This allows Eigen to evaluate the matrix product +matA * matA directly into \c matB. + + + + +
ExampleOutput
+\include TopicAliasing_mult2.cpp + +\verbinclude TopicAliasing_mult2.out +
+ +Of course, you should not use \c noalias() when there is in fact aliasing taking place. If you do, then you +may get wrong results: + + + + +
ExampleOutput
+\include TopicAliasing_mult3.cpp + +\verbinclude TopicAliasing_mult3.out +
+ + +\section TopicAliasingSummary Summary + +Aliasing occurs when the same matrix or array coefficients appear both on the left- and the right-hand side of +an assignment operator. + - Aliasing is harmless with coefficient-wise computations; this includes scalar multiplication and matrix or + array addition. + - When you multiply two matrices, Eigen assumes that aliasing occurs. If you know that there is no aliasing, + then you can use \link MatrixBase::noalias() noalias()\endlink. + - In all other situations, Eigen assumes that there is no aliasing issue and thus gives the wrong result if + aliasing does in fact occur. To prevent this, you have to use \link DenseBase::eval() eval() \endlink or + one of the xxxInPlace() functions. + +*/ +} diff --git a/doc/TopicAssertions.dox b/doc/TopicAssertions.dox new file mode 100644 index 000000000..4ead40174 --- /dev/null +++ b/doc/TopicAssertions.dox @@ -0,0 +1,108 @@ +namespace Eigen { + +/** \page TopicAssertions Assertions + +\eigenAutoToc + +\section PlainAssert Assertions + +The macro eigen_assert is defined to be \c eigen_plain_assert by default. We use eigen_plain_assert instead of \c assert to work around a known bug for GCC <= 4.3. Basically, eigen_plain_assert \a is \c assert. + +\subsection RedefineAssert Redefining assertions + +Both eigen_assert and eigen_plain_assert are defined in Macros.h. Defining eigen_assert indirectly gives you a chance to change its behavior. You can redefine this macro if you want to do something else such as throwing an exception, and fall back to its default behavior with eigen_plain_assert. The code below tells Eigen to throw an std::runtime_error: + +\code +#include +#undef eigen_assert +#define eigen_assert(x) \ + if (!x) { throw (std::runtime_error("Put your message here")); } +\endcode + +\subsection DisableAssert Disabling assertions + +Assertions cost run time and can be turned off. You can suppress eigen_assert by defining \c EIGEN_NO_DEBUG \b before including Eigen headers. \c EIGEN_NO_DEBUG is undefined by default unless \c NDEBUG is defined. + +\section StaticAssert Static assertions + +Static assertions are not standardized until C++11. However, in the Eigen library, there are many conditions can and should be detectedat compile time. For instance, we use static assertions to prevent the code below from compiling. + +\code +Matrix3d() + Matrix4d(); // adding matrices of different sizes +Matrix4cd() * Vector3cd(); // invalid product known at compile time +\endcode + +Static assertions are defined in StaticAssert.h. If there is native static_assert, we use it. Otherwise, we have implemented an assertion macro that can show a limited range of messages. + +One can easily come up with static assertions without messages, such as: + +\code +#define STATIC_ASSERT(x) \ + switch(0) { case 0: case x:; } +\endcode + +However, the example above obviously cannot tell why the assertion failed. Therefore, we define a \c struct in namespace Eigen::internal to handle available messages. + +\code +template +struct static_assertion {}; + +template<> +struct static_assertion +{ + enum { + YOU_TRIED_CALLING_A_VECTOR_METHOD_ON_A_MATRIX, + YOU_MIXED_VECTORS_OF_DIFFERENT_SIZES, + // see StaticAssert.h for all enums. + }; +}; +\endcode + +And then, we define EIGEN_STATIC_ASSERT(CONDITION,MSG) to access Eigen::internal::static_assertion::MSG. If the condition evaluates into \c false, your compiler displays a lot of messages explaining there is no MSG in static_assert. Nevertheless, this is \a not in what we are interested. As you can see, all members of static_assert are ALL_CAPS_AND_THEY_ARE_SHOUTING. + +\warning +When using this macro, MSG should be a member of static_assertion, or the static assertion \b always fails. +Currently, it can only be used in function scope. + +\subsection DerivedStaticAssert Derived static assertions + +There are other macros derived from EIGEN_STATIC_ASSERT to enhance readability. Their names are self-explanatory. + +- \b EIGEN_STATIC_ASSERT_FIXED_SIZE(TYPE) - passes if \a TYPE is fixed size. +- \b EIGEN_STATIC_ASSERT_DYNAMIC_SIZE(TYPE) - passes if \a TYPE is dynamic size. +- \b EIGEN_STATIC_ASSERT_LVALUE(Derived) - failes if \a Derived is read-only. +- \b EIGEN_STATIC_ASSERT_ARRAYXPR(Derived) - passes if \a Derived is an array expression. +- EIGEN_STATIC_ASSERT_SAME_XPR_KIND(Derived1, Derived2) - failes if the two expressions are an array one and a matrix one. + +Because Eigen handles both fixed-size and dynamic-size expressions, some conditions cannot be clearly determined at compile time. We classify them into strict assertions and permissive assertions. + +\subsubsection StrictAssertions Strict assertions + +These assertions fail if the condition may not be met. For example, MatrixXd may not be a vector, so it fails EIGEN_STATIC_ASSERT_VECTOR_ONLY. + +- \b EIGEN_STATIC_ASSERT_VECTOR_ONLY(TYPE) - passes if \a TYPE must be a vector type. +- EIGEN_STATIC_ASSERT_VECTOR_SPECIFIC_SIZE(TYPE, SIZE) - passes if \a TYPE must be a vector of the given size. +- EIGEN_STATIC_ASSERT_MATRIX_SPECIFIC_SIZE(TYPE, ROWS, COLS) - passes if \a TYPE must be a matrix with given rows and columns. + +\subsubsection PermissiveAssertions Permissive assertions + +These assertions fail if the condition \b cannot be met. For example, MatrixXd and Matrix4d may have the same size, so they pass EIGEN_STATIC_ASSERT_SAME_MATRIX_SIZE. + +- \b EIGEN_STATIC_ASSERT_SAME_VECTOR_SIZE(TYPE0,TYPE1) - fails if the two vector expression types must have different sizes. +- \b EIGEN_STATIC_ASSERT_SAME_MATRIX_SIZE(TYPE0,TYPE1) - fails if the two matrix expression types must have different sizes. +- \b EIGEN_STATIC_ASSERT_SIZE_1x1(TYPE) - fails if \a TYPE cannot be an 1x1 expression. + +See StaticAssert.h for details such as what messages they throw. + +\subsection DisableStaticAssert Disabling static assertions + +If \c EIGEN_NO_STATIC_ASSERT is defined, static assertions turn into eigen_assert's, working like: + +\code +#define EIGEN_STATIC_ASSERT(CONDITION,MSG) eigen_assert((CONDITION) && #MSG); +\endcode + +This saves compile time but consumes more run time. \c EIGEN_NO_STATIC_ASSERT is undefined by default. + +*/ +} diff --git a/doc/TopicEigenExpressionTemplates.dox b/doc/TopicEigenExpressionTemplates.dox new file mode 100644 index 000000000..b31fd47f9 --- /dev/null +++ b/doc/TopicEigenExpressionTemplates.dox @@ -0,0 +1,12 @@ +namespace Eigen { + +/** \page TopicEigenExpressionTemplates Expression templates in Eigen + + +TODO: write this dox page! + +Is linked from the tutorial on arithmetic ops. + +*/ + +} diff --git a/doc/TopicLazyEvaluation.dox b/doc/TopicLazyEvaluation.dox new file mode 100644 index 000000000..393bc41d8 --- /dev/null +++ b/doc/TopicLazyEvaluation.dox @@ -0,0 +1,65 @@ +namespace Eigen { + +/** \page TopicLazyEvaluation Lazy Evaluation and Aliasing + +Executive summary: Eigen has intelligent compile-time mechanisms to enable lazy evaluation and removing temporaries where appropriate. +It will handle aliasing automatically in most cases, for example with matrix products. The automatic behavior can be overridden +manually by using the MatrixBase::eval() and MatrixBase::noalias() methods. + +When you write a line of code involving a complex expression such as + +\code mat1 = mat2 + mat3 * (mat4 + mat5); \endcode + +Eigen determines automatically, for each sub-expression, whether to evaluate it into a temporary variable. Indeed, in certain cases it is better to evaluate immediately a sub-expression into a temporary variable, while in other cases it is better to avoid that. + +A traditional math library without expression templates always evaluates all sub-expressions into temporaries. So with this code, + +\code vec1 = vec2 + vec3; \endcode + +a traditional library would evaluate \c vec2 + vec3 into a temporary \c vec4 and then copy \c vec4 into \c vec1. This is of course inefficient: the arrays are traversed twice, so there are a lot of useless load/store operations. + +Expression-templates-based libraries can avoid evaluating sub-expressions into temporaries, which in many cases results in large speed improvements. This is called lazy evaluation as an expression is getting evaluated as late as possible, instead of immediately. However, most other expression-templates-based libraries always choose lazy evaluation. There are two problems with that: first, lazy evaluation is not always a good choice for performance; second, lazy evaluation can be very dangerous, for example with matrix products: doing matrix = matrix*matrix gives a wrong result if the matrix product is lazy-evaluated, because of the way matrix product works. + +For these reasons, Eigen has intelligent compile-time mechanisms to determine automatically when to use lazy evaluation, and when on the contrary it should evaluate immediately into a temporary variable. + +So in the basic example, + +\code matrix1 = matrix2 + matrix3; \endcode + +Eigen chooses lazy evaluation. Thus the arrays are traversed only once, producing optimized code. If you really want to force immediate evaluation, use \link MatrixBase::eval() eval()\endlink: + +\code matrix1 = (matrix2 + matrix3).eval(); \endcode + +Here is now a more involved example: + +\code matrix1 = -matrix2 + matrix3 + 5 * matrix4; \endcode + +Eigen chooses lazy evaluation at every stage in that example, which is clearly the correct choice. In fact, lazy evaluation is the "default choice" and Eigen will choose it except in a few circumstances. + +The first circumstance in which Eigen chooses immediate evaluation, is when it sees an assignment a = b; and the expression \c b has the evaluate-before-assigning \link flags flag\endlink. The most important example of such an expression is the \link GeneralProduct matrix product expression\endlink. For example, when you do + +\code matrix = matrix * matrix; \endcode + +Eigen first evaluates matrix * matrix into a temporary matrix, and then copies it into the original \c matrix. This guarantees a correct result as we saw above that lazy evaluation gives wrong results with matrix products. It also doesn't cost much, as the cost of the matrix product itself is much higher. + +What if you know that the result does no alias the operand of the product and want to force lazy evaluation? Then use \link MatrixBase::noalias() .noalias()\endlink instead. Here is an example: + +\code matrix1.noalias() = matrix2 * matrix2; \endcode + +Here, since we know that matrix2 is not the same matrix as matrix1, we know that lazy evaluation is not dangerous, so we may force lazy evaluation. Concretely, the effect of noalias() here is to bypass the evaluate-before-assigning \link flags flag\endlink. + +The second circumstance in which Eigen chooses immediate evaluation, is when it sees a nested expression such as a + b where \c b is already an expression having the evaluate-before-nesting \link flags flag\endlink. Again, the most important example of such an expression is the \link GeneralProduct matrix product expression\endlink. For example, when you do + +\code matrix1 = matrix2 + matrix3 * matrix4; \endcode + +the product matrix3 * matrix4 gets evaluated immediately into a temporary matrix. Indeed, experiments showed that it is often beneficial for performance to evaluate immediately matrix products when they are nested into bigger expressions. + +The third circumstance in which Eigen chooses immediate evaluation, is when its cost model shows that the total cost of an operation is reduced if a sub-expression gets evaluated into a temporary. Indeed, in certain cases, an intermediate result is sufficiently costly to compute and is reused sufficiently many times, that is worth "caching". Here is an example: + +\code matrix1 = matrix2 * (matrix3 + matrix4); \endcode + +Here, provided the matrices have at least 2 rows and 2 columns, each coefficienct of the expression matrix3 + matrix4 is going to be used several times in the matrix product. Instead of computing the sum everytime, it is much better to compute it once and store it in a temporary variable. Eigen understands this and evaluates matrix3 + matrix4 into a temporary variable before evaluating the product. + +*/ + +} diff --git a/doc/TopicResizing.dox b/doc/TopicResizing.dox new file mode 100644 index 000000000..c323e17ad --- /dev/null +++ b/doc/TopicResizing.dox @@ -0,0 +1,11 @@ +namespace Eigen { + +/** \page TopicResizing Resizing + + +TODO: write this dox page! + +Is linked from the tutorial on the Matrix class. + +*/ +} diff --git a/doc/TopicScalarTypes.dox b/doc/TopicScalarTypes.dox new file mode 100644 index 000000000..2ff03c198 --- /dev/null +++ b/doc/TopicScalarTypes.dox @@ -0,0 +1,12 @@ +namespace Eigen { + +/** \page TopicScalarTypes Scalar types + + +TODO: write this dox page! + +Is linked from the tutorial on the Matrix class. + +*/ + +} diff --git a/doc/TopicVectorization.dox b/doc/TopicVectorization.dox new file mode 100644 index 000000000..274d0451b --- /dev/null +++ b/doc/TopicVectorization.dox @@ -0,0 +1,9 @@ +namespace Eigen { + +/** \page TopicVectorization Vectorization + + +TODO: write this dox page! + +*/ +} diff --git a/doc/TutorialAdvancedInitialization.dox b/doc/TutorialAdvancedInitialization.dox new file mode 100644 index 000000000..50374d0d0 --- /dev/null +++ b/doc/TutorialAdvancedInitialization.dox @@ -0,0 +1,162 @@ +namespace Eigen { + +/** \eigenManualPage TutorialAdvancedInitialization Advanced initialization + +This page discusses several advanced methods for initializing matrices. It gives more details on the +comma-initializer, which was introduced before. It also explains how to get special matrices such as the +identity matrix and the zero matrix. + +\eigenAutoToc + +\section TutorialAdvancedInitializationCommaInitializer The comma initializer + +Eigen offers a comma initializer syntax which allows the user to easily set all the coefficients of a matrix, +vector or array. Simply list the coefficients, starting at the top-left corner and moving from left to right +and from the top to the bottom. The size of the object needs to be specified beforehand. If you list too few +or too many coefficients, Eigen will complain. + + + + +
Example:Output:
+\include Tutorial_commainit_01.cpp + +\verbinclude Tutorial_commainit_01.out +
+ +Moreover, the elements of the initialization list may themselves be vectors or matrices. A common use is +to join vectors or matrices together. For example, here is how to join two row vectors together. Remember +that you have to set the size before you can use the comma initializer. + + + + +
Example:Output:
+\include Tutorial_AdvancedInitialization_Join.cpp + +\verbinclude Tutorial_AdvancedInitialization_Join.out +
+ +We can use the same technique to initialize matrices with a block structure. + + + + +
Example:Output:
+\include Tutorial_AdvancedInitialization_Block.cpp + +\verbinclude Tutorial_AdvancedInitialization_Block.out +
+ +The comma initializer can also be used to fill block expressions such as m.row(i). Here is a more +complicated way to get the same result as in the first example above: + + + + +
Example:Output:
+\include Tutorial_commainit_01b.cpp + +\verbinclude Tutorial_commainit_01b.out +
+ + +\section TutorialAdvancedInitializationSpecialMatrices Special matrices and arrays + +The Matrix and Array classes have static methods like \link DenseBase::Zero() Zero()\endlink, which can be +used to initialize all coefficients to zero. There are three variants. The first variant takes no arguments +and can only be used for fixed-size objects. If you want to initialize a dynamic-size object to zero, you need +to specify the size. Thus, the second variant requires one argument and can be used for one-dimensional +dynamic-size objects, while the third variant requires two arguments and can be used for two-dimensional +objects. All three variants are illustrated in the following example: + + + + +
Example:Output:
+\include Tutorial_AdvancedInitialization_Zero.cpp + +\verbinclude Tutorial_AdvancedInitialization_Zero.out +
+ +Similarly, the static method \link DenseBase::Constant() Constant\endlink(value) sets all coefficients to \c value. +If the size of the object needs to be specified, the additional arguments go before the \c value +argument, as in MatrixXd::Constant(rows, cols, value). The method \link DenseBase::Random() Random() +\endlink fills the matrix or array with random coefficients. The identity matrix can be obtained by calling +\link MatrixBase::Identity() Identity()\endlink; this method is only available for Matrix, not for Array, +because "identity matrix" is a linear algebra concept. The method +\link DenseBase::LinSpaced LinSpaced\endlink(size, low, high) is only available for vectors and +one-dimensional arrays; it yields a vector of the specified size whose coefficients are equally spaced between +\c low and \c high. The method \c LinSpaced() is illustrated in the following example, which prints a table +with angles in degrees, the corresponding angle in radians, and their sine and cosine. + + + + +
Example:Output:
+\include Tutorial_AdvancedInitialization_LinSpaced.cpp + +\verbinclude Tutorial_AdvancedInitialization_LinSpaced.out +
+ +This example shows that objects like the ones returned by LinSpaced() can be assigned to variables (and +expressions). Eigen defines utility functions like \link DenseBase::setZero() setZero()\endlink, +\link MatrixBase::setIdentity() \endlink and \link DenseBase::setLinSpaced() \endlink to do this +conveniently. The following example contrasts three ways to construct the matrix +\f$ J = \bigl[ \begin{smallmatrix} O & I \\ I & O \end{smallmatrix} \bigr] \f$: using static methods and +assignment, using static methods and the comma-initializer, or using the setXxx() methods. + + + + +
Example:Output:
+\include Tutorial_AdvancedInitialization_ThreeWays.cpp + +\verbinclude Tutorial_AdvancedInitialization_ThreeWays.out +
+ +A summary of all pre-defined matrix, vector and array objects can be found in the \ref QuickRefPage. + + +\section TutorialAdvancedInitializationTemporaryObjects Usage as temporary objects + +As shown above, static methods as Zero() and Constant() can be used to initialize variables at the time of +declaration or at the right-hand side of an assignment operator. You can think of these methods as returning a +matrix or array; in fact, they return so-called \ref TopicEigenExpressionTemplates "expression objects" which +evaluate to a matrix or array when needed, so that this syntax does not incur any overhead. + +These expressions can also be used as a temporary object. The second example in +the \ref GettingStarted guide, which we reproduce here, already illustrates this. + + + + +
Example:Output:
+\include QuickStart_example2_dynamic.cpp + +\verbinclude QuickStart_example2_dynamic.out +
+ +The expression m + MatrixXf::Constant(3,3,1.2) constructs the 3-by-3 matrix expression with all its coefficients +equal to 1.2 plus the corresponding coefficient of \a m. + +The comma-initializer, too, can also be used to construct temporary objects. The following example constructs a random +matrix of size 2-by-3, and then multiplies this matrix on the left with +\f$ \bigl[ \begin{smallmatrix} 0 & 1 \\ 1 & 0 \end{smallmatrix} \bigr] \f$. + + + + +
Example:Output:
+\include Tutorial_AdvancedInitialization_CommaTemporary.cpp + +\verbinclude Tutorial_AdvancedInitialization_CommaTemporary.out +
+ +The \link CommaInitializer::finished() finished() \endlink method is necessary here to get the actual matrix +object once the comma initialization of our temporary submatrix is done. + + +*/ + +} diff --git a/doc/TutorialArrayClass.dox b/doc/TutorialArrayClass.dox new file mode 100644 index 000000000..6432684aa --- /dev/null +++ b/doc/TutorialArrayClass.dox @@ -0,0 +1,192 @@ +namespace Eigen { + +/** \eigenManualPage TutorialArrayClass The Array class and coefficient-wise operations + +This page aims to provide an overview and explanations on how to use +Eigen's Array class. + +\eigenAutoToc + +\section TutorialArrayClassIntro What is the Array class? + +The Array class provides general-purpose arrays, as opposed to the Matrix class which +is intended for linear algebra. Furthermore, the Array class provides an easy way to +perform coefficient-wise operations, which might not have a linear algebraic meaning, +such as adding a constant to every coefficient in the array or multiplying two arrays coefficient-wise. + + +\section TutorialArrayClassTypes Array types +Array is a class template taking the same template parameters as Matrix. +As with Matrix, the first three template parameters are mandatory: +\code +Array +\endcode +The last three template parameters are optional. Since this is exactly the same as for Matrix, +we won't explain it again here and just refer to \ref TutorialMatrixClass. + +Eigen also provides typedefs for some common cases, in a way that is similar to the Matrix typedefs +but with some slight differences, as the word "array" is used for both 1-dimensional and 2-dimensional arrays. +We adopt the convention that typedefs of the form ArrayNt stand for 1-dimensional arrays, where N and t are +the size and the scalar type, as in the Matrix typedefs explained on \ref TutorialMatrixClass "this page". For 2-dimensional arrays, we +use typedefs of the form ArrayNNt. Some examples are shown in the following table: + + + + + + + + + + + + + + + + + + + + + + +
Type Typedef
\code Array \endcode \code ArrayXf \endcode
\code Array \endcode \code Array3f \endcode
\code Array \endcode \code ArrayXXd \endcode
\code Array \endcode \code Array33d \endcode
+ + +\section TutorialArrayClassAccess Accessing values inside an Array + +The parenthesis operator is overloaded to provide write and read access to the coefficients of an array, just as with matrices. +Furthermore, the \c << operator can be used to initialize arrays (via the comma initializer) or to print them. + + + + +
Example:Output:
+\include Tutorial_ArrayClass_accessors.cpp + +\verbinclude Tutorial_ArrayClass_accessors.out +
+ +For more information about the comma initializer, see \ref TutorialAdvancedInitialization. + + +\section TutorialArrayClassAddSub Addition and subtraction + +Adding and subtracting two arrays is the same as for matrices. +The operation is valid if both arrays have the same size, and the addition or subtraction is done coefficient-wise. + +Arrays also support expressions of the form array + scalar which add a scalar to each coefficient in the array. +This provides a functionality that is not directly available for Matrix objects. + + + + +
Example:Output:
+\include Tutorial_ArrayClass_addition.cpp + +\verbinclude Tutorial_ArrayClass_addition.out +
+ + +\section TutorialArrayClassMult Array multiplication + +First of all, of course you can multiply an array by a scalar, this works in the same way as matrices. Where arrays +are fundamentally different from matrices, is when you multiply two together. Matrices interpret +multiplication as matrix product and arrays interpret multiplication as coefficient-wise product. Thus, two +arrays can be multiplied if and only if they have the same dimensions. + + + + +
Example:Output:
+\include Tutorial_ArrayClass_mult.cpp + +\verbinclude Tutorial_ArrayClass_mult.out +
+ + +\section TutorialArrayClassCwiseOther Other coefficient-wise operations + +The Array class defines other coefficient-wise operations besides the addition, subtraction and multiplication +operators described above. For example, the \link ArrayBase::abs() .abs() \endlink method takes the absolute +value of each coefficient, while \link ArrayBase::sqrt() .sqrt() \endlink computes the square root of the +coefficients. If you have two arrays of the same size, you can call \link ArrayBase::min(const Eigen::ArrayBase&) const .min(.) \endlink to +construct the array whose coefficients are the minimum of the corresponding coefficients of the two given +arrays. These operations are illustrated in the following example. + + + + +
Example:Output:
+\include Tutorial_ArrayClass_cwise_other.cpp + +\verbinclude Tutorial_ArrayClass_cwise_other.out +
+ +More coefficient-wise operations can be found in the \ref QuickRefPage. + + +\section TutorialArrayClassConvert Converting between array and matrix expressions + +When should you use objects of the Matrix class and when should you use objects of the Array class? You cannot +apply Matrix operations on arrays, or Array operations on matrices. Thus, if you need to do linear algebraic +operations such as matrix multiplication, then you should use matrices; if you need to do coefficient-wise +operations, then you should use arrays. However, sometimes it is not that simple, but you need to use both +Matrix and Array operations. In that case, you need to convert a matrix to an array or reversely. This gives +access to all operations regardless of the choice of declaring objects as arrays or as matrices. + +\link MatrixBase Matrix expressions \endlink have an \link MatrixBase::array() .array() \endlink method that +'converts' them into \link ArrayBase array expressions\endlink, so that coefficient-wise operations +can be applied easily. Conversely, \link ArrayBase array expressions \endlink +have a \link ArrayBase::matrix() .matrix() \endlink method. As with all Eigen expression abstractions, +this doesn't have any runtime cost (provided that you let your compiler optimize). +Both \link MatrixBase::array() .array() \endlink and \link ArrayBase::matrix() .matrix() \endlink +can be used as rvalues and as lvalues. + +Mixing matrices and arrays in an expression is forbidden with Eigen. For instance, you cannot add a matrix and +array directly; the operands of a \c + operator should either both be matrices or both be arrays. However, +it is easy to convert from one to the other with \link MatrixBase::array() .array() \endlink and +\link ArrayBase::matrix() .matrix()\endlink. The exception to this rule is the assignment operator: it is +allowed to assign a matrix expression to an array variable, or to assign an array expression to a matrix +variable. + +The following example shows how to use array operations on a Matrix object by employing the +\link MatrixBase::array() .array() \endlink method. For example, the statement +result = m.array() * n.array() takes two matrices \c m and \c n, converts them both to an array, uses +* to multiply them coefficient-wise and assigns the result to the matrix variable \c result (this is legal +because Eigen allows assigning array expressions to matrix variables). + +As a matter of fact, this usage case is so common that Eigen provides a \link MatrixBase::cwiseProduct() const +.cwiseProduct(.) \endlink method for matrices to compute the coefficient-wise product. This is also shown in +the example program. + + + + +
Example:Output:
+\include Tutorial_ArrayClass_interop_matrix.cpp + +\verbinclude Tutorial_ArrayClass_interop_matrix.out +
+ +Similarly, if \c array1 and \c array2 are arrays, then the expression array1.matrix() * array2.matrix() +computes their matrix product. + +Here is a more advanced example. The expression (m.array() + 4).matrix() * m adds 4 to every +coefficient in the matrix \c m and then computes the matrix product of the result with \c m. Similarly, the +expression (m.array() * n.array()).matrix() * m computes the coefficient-wise product of the matrices +\c m and \c n and then the matrix product of the result with \c m. + + + + +
Example:Output:
+\include Tutorial_ArrayClass_interop.cpp + +\verbinclude Tutorial_ArrayClass_interop.out +
+ +*/ + +} diff --git a/doc/TutorialBlockOperations.dox b/doc/TutorialBlockOperations.dox new file mode 100644 index 000000000..a2d8c97cc --- /dev/null +++ b/doc/TutorialBlockOperations.dox @@ -0,0 +1,228 @@ +namespace Eigen { + +/** \eigenManualPage TutorialBlockOperations Block operations + +This page explains the essentials of block operations. +A block is a rectangular part of a matrix or array. Blocks expressions can be used both +as rvalues and as lvalues. As usual with Eigen expressions, this abstraction has zero runtime cost +provided that you let your compiler optimize. + +\eigenAutoToc + +\section TutorialBlockOperationsUsing Using block operations + +The most general block operation in Eigen is called \link DenseBase::block() .block() \endlink. +There are two versions, whose syntax is as follows: + + + + + + + + +
\b %Block \b operation +Version constructing a \n dynamic-size block expressionVersion constructing a \n fixed-size block expression
%Block of size (p,q), starting at (i,j)\code +matrix.block(i,j,p,q);\endcode \code +matrix.block(i,j);\endcode
+ +As always in Eigen, indices start at 0. + +Both versions can be used on fixed-size and dynamic-size matrices and arrays. +These two expressions are semantically equivalent. +The only difference is that the fixed-size version will typically give you faster code if the block size is small, +but requires this size to be known at compile time. + +The following program uses the dynamic-size and fixed-size versions to print the values of several blocks inside a +matrix. + + + + +
Example:Output:
+\include Tutorial_BlockOperations_print_block.cpp + +\verbinclude Tutorial_BlockOperations_print_block.out +
+ +In the above example the \link DenseBase::block() .block() \endlink function was employed as a \em rvalue, i.e. +it was only read from. However, blocks can also be used as \em lvalues, meaning that you can assign to a block. + +This is illustrated in the following example. This example also demonstrates blocks in arrays, which works exactly like the above-demonstrated blocks in matrices. + + + + +
Example:Output:
+\include Tutorial_BlockOperations_block_assignment.cpp + +\verbinclude Tutorial_BlockOperations_block_assignment.out +
+ +While the \link DenseBase::block() .block() \endlink method can be used for any block operation, there are +other methods for special cases, providing more specialized API and/or better performance. On the topic of performance, all what +matters is that you give Eigen as much information as possible at compile time. For example, if your block is a single whole column in a matrix, +using the specialized \link DenseBase::col() .col() \endlink function described below lets Eigen know that, which can give it optimization opportunities. + +The rest of this page describes these specialized methods. + +\section TutorialBlockOperationsSyntaxColumnRows Columns and rows + +Individual columns and rows are special cases of blocks. Eigen provides methods to easily address them: +\link DenseBase::col() .col() \endlink and \link DenseBase::row() .row()\endlink. + + + + + + + + + + +
%Block operationMethod
ith row + \link DenseBase::row() * \endlink\code +matrix.row(i);\endcode
jth column + \link DenseBase::col() * \endlink\code +matrix.col(j);\endcode
+ +The argument for \p col() and \p row() is the index of the column or row to be accessed. As always in Eigen, indices start at 0. + + + + +
Example:Output:
+\include Tutorial_BlockOperations_colrow.cpp + +\verbinclude Tutorial_BlockOperations_colrow.out +
+ +That example also demonstrates that block expressions (here columns) can be used in arithmetic like any other expression. + + +\section TutorialBlockOperationsSyntaxCorners Corner-related operations + +Eigen also provides special methods for blocks that are flushed against one of the corners or sides of a +matrix or array. For instance, \link DenseBase::topLeftCorner() .topLeftCorner() \endlink can be used to refer +to a block in the top-left corner of a matrix. + +The different possibilities are summarized in the following table: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
%Block \b operation +Version constructing a \n dynamic-size block expressionVersion constructing a \n fixed-size block expression
Top-left p by q block \link DenseBase::topLeftCorner() * \endlink\code +matrix.topLeftCorner(p,q);\endcode \code +matrix.topLeftCorner();\endcode
Bottom-left p by q block + \link DenseBase::bottomLeftCorner() * \endlink\code +matrix.bottomLeftCorner(p,q);\endcode \code +matrix.bottomLeftCorner();\endcode
Top-right p by q block + \link DenseBase::topRightCorner() * \endlink\code +matrix.topRightCorner(p,q);\endcode \code +matrix.topRightCorner();\endcode
Bottom-right p by q block + \link DenseBase::bottomRightCorner() * \endlink\code +matrix.bottomRightCorner(p,q);\endcode \code +matrix.bottomRightCorner();\endcode
%Block containing the first q rows + \link DenseBase::topRows() * \endlink\code +matrix.topRows(q);\endcode \code +matrix.topRows();\endcode
%Block containing the last q rows + \link DenseBase::bottomRows() * \endlink\code +matrix.bottomRows(q);\endcode \code +matrix.bottomRows();\endcode
%Block containing the first p columns + \link DenseBase::leftCols() * \endlink\code +matrix.leftCols(p);\endcode \code +matrix.leftCols

();\endcode

%Block containing the last q columns + \link DenseBase::rightCols() * \endlink\code +matrix.rightCols(q);\endcode \code +matrix.rightCols();\endcode
+ +Here is a simple example illustrating the use of the operations presented above: + + + + +
Example:Output:
+\include Tutorial_BlockOperations_corner.cpp + +\verbinclude Tutorial_BlockOperations_corner.out +
+ + +\section TutorialBlockOperationsSyntaxVectors Block operations for vectors + +Eigen also provides a set of block operations designed specifically for the special case of vectors and one-dimensional arrays: + + + + + + + + + + + + + + + + + +
%Block operationVersion constructing a \n dynamic-size block expressionVersion constructing a \n fixed-size block expression
%Block containing the first \p n elements + \link DenseBase::head() * \endlink\code +vector.head(n);\endcode \code +vector.head();\endcode
%Block containing the last \p n elements + \link DenseBase::tail() * \endlink\code +vector.tail(n);\endcode \code +vector.tail();\endcode
%Block containing \p n elements, starting at position \p i + \link DenseBase::segment() * \endlink\code +vector.segment(i,n);\endcode \code +vector.segment(i);\endcode
+ + +An example is presented below: + + + +
Example:Output:
+\include Tutorial_BlockOperations_vector.cpp + +\verbinclude Tutorial_BlockOperations_vector.out +
+ +*/ + +} diff --git a/doc/TutorialGeometry.dox b/doc/TutorialGeometry.dox new file mode 100644 index 000000000..81aeec978 --- /dev/null +++ b/doc/TutorialGeometry.dox @@ -0,0 +1,241 @@ +namespace Eigen { + +/** \eigenManualPage TutorialGeometry Space transformations + +In this page, we will introduce the many possibilities offered by the \ref Geometry_Module "geometry module" to deal with 2D and 3D rotations and projective or affine transformations. + +\eigenAutoToc + +Eigen's Geometry module provides two different kinds of geometric transformations: + - Abstract transformations, such as rotations (represented by \ref AngleAxis "angle and axis" or by a \ref Quaternion "quaternion"), \ref Translation "translations", \ref Scaling "scalings". These transformations are NOT represented as matrices, but you can nevertheless mix them with matrices and vectors in expressions, and convert them to matrices if you wish. + - Projective or affine transformation matrices: see the Transform class. These are really matrices. + +\note If you are working with OpenGL 4x4 matrices then Affine3f and Affine3d are what you want. Since Eigen defaults to column-major storage, you can directly use the Transform::data() method to pass your transformation matrix to OpenGL. + +You can construct a Transform from an abstract transformation, like this: +\code + Transform t(AngleAxis(angle,axis)); +\endcode +or like this: +\code + Transform t; + t = AngleAxis(angle,axis); +\endcode +But note that unfortunately, because of how C++ works, you can \b not do this: +\code + Transform t = AngleAxis(angle,axis); +\endcode +\b Explanation: In the C++ language, this would require Transform to have a non-explicit conversion constructor from AngleAxis, but we really don't want to allow implicit casting here. + + +\section TutorialGeoElementaryTransformations Transformation types + + + + + + + + + + +
Transformation typeTypical initialization code
+\ref Rotation2D "2D rotation" from an angle\code +Rotation2D rot2(angle_in_radian);\endcode
+3D rotation as an \ref AngleAxis "angle + axis"\code +AngleAxis aa(angle_in_radian, Vector3f(ax,ay,az));\endcode +The axis vector must be normalized.
+3D rotation as a \ref Quaternion "quaternion"\code +Quaternion q; q = AngleAxis(angle_in_radian, axis);\endcode
+N-D Scaling\code +Scaling(sx, sy) +Scaling(sx, sy, sz) +Scaling(s) +Scaling(vecN)\endcode
+N-D Translation\code +Translation(tx, ty) +Translation(tx, ty, tz) +Translation(s) +Translation(vecN)\endcode
+N-D \ref TutorialGeoTransform "Affine transformation"\code +Transform t = concatenation_of_any_transformations; +Transform t = Translation3f(p) * AngleAxisf(a,axis) * Scaling(s);\endcode
+N-D Linear transformations \n +(pure rotations, \n scaling, etc.)\code +Matrix t = concatenation_of_rotations_and_scalings; +Matrix t = Rotation2Df(a) * Scaling(s); +Matrix t = AngleAxisf(a,axis) * Scaling(s);\endcode
+ +Notes on rotations\n To transform more than a single vector the preferred +representations are rotation matrices, while for other usages Quaternion is the +representation of choice as they are compact, fast and stable. Finally Rotation2D and +AngleAxis are mainly convenient types to create other rotation objects. + +Notes on Translation and Scaling\n Like AngleAxis, these classes were +designed to simplify the creation/initialization of linear (Matrix) and affine (Transform) +transformations. Nevertheless, unlike AngleAxis which is inefficient to use, these classes +might still be interesting to write generic and efficient algorithms taking as input any +kind of transformations. + +Any of the above transformation types can be converted to any other types of the same nature, +or to a more generic type. Here are some additional examples: + + +
\code +Rotation2Df r; r = Matrix2f(..); // assumes a pure rotation matrix +AngleAxisf aa; aa = Quaternionf(..); +AngleAxisf aa; aa = Matrix3f(..); // assumes a pure rotation matrix +Matrix2f m; m = Rotation2Df(..); +Matrix3f m; m = Quaternionf(..); Matrix3f m; m = Scaling(..); +Affine3f m; m = AngleAxis3f(..); Affine3f m; m = Scaling(..); +Affine3f m; m = Translation3f(..); Affine3f m; m = Matrix3f(..); +\endcode
+ + +top\section TutorialGeoCommontransformationAPI Common API across transformation types + +To some extent, Eigen's \ref Geometry_Module "geometry module" allows you to write +generic algorithms working on any kind of transformation representations: + + + + + +
+Concatenation of two transformations\code +gen1 * gen2;\endcode
Apply the transformation to a vector\code +vec2 = gen1 * vec1;\endcode
Get the inverse of the transformation\code +gen2 = gen1.inverse();\endcode
Spherical interpolation \n (Rotation2D and Quaternion only)\code +rot3 = rot1.slerp(alpha,rot2);\endcode
+ + + +top\section TutorialGeoTransform Affine transformations +Generic affine transformations are represented by the Transform class which internaly +is a (Dim+1)^2 matrix. In Eigen we have chosen to not distinghish between points and +vectors such that all points are actually represented by displacement vectors from the +origin ( \f$ \mathbf{p} \equiv \mathbf{p}-0 \f$ ). With that in mind, real points and +vector distinguish when the transformation is applied. + + + + + + + +
+Apply the transformation to a \b point \code +VectorNf p1, p2; +p2 = t * p1;\endcode
+Apply the transformation to a \b vector \code +VectorNf vec1, vec2; +vec2 = t.linear() * vec1;\endcode
+Apply a \em general transformation \n to a \b normal \b vector +(explanations)\code +VectorNf n1, n2; +MatrixNf normalMatrix = t.linear().inverse().transpose(); +n2 = (normalMatrix * n1).normalized();\endcode
+Apply a transformation with \em pure \em rotation \n to a \b normal \b vector +(no scaling, no shear)\code +n2 = t.linear() * n1;\endcode
+OpenGL compatibility \b 3D \code +glLoadMatrixf(t.data());\endcode
+OpenGL compatibility \b 2D \code +Affine3f aux(Affine3f::Identity()); +aux.linear().topLeftCorner<2,2>() = t.linear(); +aux.translation().start<2>() = t.translation(); +glLoadMatrixf(aux.data());\endcode
+ +\b Component \b accessors + + + + + + +
+full read-write access to the internal matrix\code +t.matrix() = matN1xN1; // N1 means N+1 +matN1xN1 = t.matrix(); +\endcode
+coefficient accessors\code +t(i,j) = scalar; <=> t.matrix()(i,j) = scalar; +scalar = t(i,j); <=> scalar = t.matrix()(i,j); +\endcode
+translation part\code +t.translation() = vecN; +vecN = t.translation(); +\endcode
+linear part\code +t.linear() = matNxN; +matNxN = t.linear(); +\endcode
+extract the rotation matrix\code +matNxN = t.rotation(); +\endcode
+ + +\b Transformation \b creation \n +While transformation objects can be created and updated concatenating elementary transformations, +the Transform class also features a procedural API: + + + + + + +
procedural APIequivalent natural API
Translation\code +t.translate(Vector_(tx,ty,..)); +t.pretranslate(Vector_(tx,ty,..)); +\endcode\code +t *= Translation_(tx,ty,..); +t = Translation_(tx,ty,..) * t; +\endcode
\b Rotation \n In 2D and for the procedural API, any_rotation can also \n be an angle in radian\code +t.rotate(any_rotation); +t.prerotate(any_rotation); +\endcode\code +t *= any_rotation; +t = any_rotation * t; +\endcode
Scaling\code +t.scale(Vector_(sx,sy,..)); +t.scale(s); +t.prescale(Vector_(sx,sy,..)); +t.prescale(s); +\endcode\code +t *= Scaling(sx,sy,..); +t *= Scaling(s); +t = Scaling(sx,sy,..) * t; +t = Scaling(s) * t; +\endcode
Shear transformation \n ( \b 2D \b only ! )\code +t.shear(sx,sy); +t.preshear(sx,sy); +\endcode
+ +Note that in both API, any many transformations can be concatenated in a single expression as shown in the two following equivalent examples: + + + +
\code +t.pretranslate(..).rotate(..).translate(..).scale(..); +\endcode
\code +t = Translation_(..) * t * RotationType(..) * Translation_(..) * Scaling(..); +\endcode
+ + + +top\section TutorialGeoEulerAngles Euler angles + + +
+Euler angles might be convenient to create rotation objects. +On the other hand, since there exist 24 different conventions, they are pretty confusing to use. This example shows how +to create a rotation matrix according to the 2-1-2 convention.\code +Matrix3f m; +m = AngleAxisf(angle1, Vector3f::UnitZ()) +* * AngleAxisf(angle2, Vector3f::UnitY()) +* * AngleAxisf(angle3, Vector3f::UnitZ()); +\endcode
+ +*/ + +} diff --git a/doc/TutorialLinearAlgebra.dox b/doc/TutorialLinearAlgebra.dox new file mode 100644 index 000000000..b09f3543e --- /dev/null +++ b/doc/TutorialLinearAlgebra.dox @@ -0,0 +1,255 @@ +namespace Eigen { + +/** \eigenManualPage TutorialLinearAlgebra Linear algebra and decompositions + +This page explains how to solve linear systems, compute various decompositions such as LU, +QR, %SVD, eigendecompositions... After reading this page, don't miss our +\link TopicLinearAlgebraDecompositions catalogue \endlink of dense matrix decompositions. + +\eigenAutoToc + +\section TutorialLinAlgBasicSolve Basic linear solving + +\b The \b problem: You have a system of equations, that you have written as a single matrix equation + \f[ Ax \: = \: b \f] +Where \a A and \a b are matrices (\a b could be a vector, as a special case). You want to find a solution \a x. + +\b The \b solution: You can choose between various decompositions, depending on what your matrix \a A looks like, +and depending on whether you favor speed or accuracy. However, let's start with an example that works in all cases, +and is a good compromise: + + + + + + +
Example:Output:
\include TutorialLinAlgExSolveColPivHouseholderQR.cpp \verbinclude TutorialLinAlgExSolveColPivHouseholderQR.out
+ +In this example, the colPivHouseholderQr() method returns an object of class ColPivHouseholderQR. Since here the +matrix is of type Matrix3f, this line could have been replaced by: +\code +ColPivHouseholderQR dec(A); +Vector3f x = dec.solve(b); +\endcode + +Here, ColPivHouseholderQR is a QR decomposition with column pivoting. It's a good compromise for this tutorial, as it +works for all matrices while being quite fast. Here is a table of some other decompositions that you can choose from, +depending on your matrix and the trade-off you want to make: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DecompositionMethodRequirements on the matrixSpeedAccuracy
PartialPivLUpartialPivLu()Invertible+++
FullPivLUfullPivLu()None-+++
HouseholderQRhouseholderQr()None+++
ColPivHouseholderQRcolPivHouseholderQr()None+++
FullPivHouseholderQRfullPivHouseholderQr()None-+++
LLTllt()Positive definite++++
LDLTldlt()Positive or negative semidefinite+++++
+ +All of these decompositions offer a solve() method that works as in the above example. + +For example, if your matrix is positive definite, the above table says that a very good +choice is then the LDLT decomposition. Here's an example, also demonstrating that using a general +matrix (not a vector) as right hand side is possible. + + + + + + + +
Example:Output:
\include TutorialLinAlgExSolveLDLT.cpp \verbinclude TutorialLinAlgExSolveLDLT.out
+ +For a \ref TopicLinearAlgebraDecompositions "much more complete table" comparing all decompositions supported by Eigen (notice that Eigen +supports many other decompositions), see our special page on +\ref TopicLinearAlgebraDecompositions "this topic". + +\section TutorialLinAlgSolutionExists Checking if a solution really exists + +Only you know what error margin you want to allow for a solution to be considered valid. +So Eigen lets you do this computation for yourself, if you want to, as in this example: + + + + + + + +
Example:Output:
\include TutorialLinAlgExComputeSolveError.cpp \verbinclude TutorialLinAlgExComputeSolveError.out
+ +\section TutorialLinAlgEigensolving Computing eigenvalues and eigenvectors + +You need an eigendecomposition here, see available such decompositions on \ref TopicLinearAlgebraDecompositions "this page". +Make sure to check if your matrix is self-adjoint, as is often the case in these problems. Here's an example using +SelfAdjointEigenSolver, it could easily be adapted to general matrices using EigenSolver or ComplexEigenSolver. + +The computation of eigenvalues and eigenvectors does not necessarily converge, but such failure to converge is +very rare. The call to info() is to check for this possibility. + + + + + + + +
Example:Output:
\include TutorialLinAlgSelfAdjointEigenSolver.cpp \verbinclude TutorialLinAlgSelfAdjointEigenSolver.out
+ +\section TutorialLinAlgInverse Computing inverse and determinant + +First of all, make sure that you really want this. While inverse and determinant are fundamental mathematical concepts, +in \em numerical linear algebra they are not as popular as in pure mathematics. Inverse computations are often +advantageously replaced by solve() operations, and the determinant is often \em not a good way of checking if a matrix +is invertible. + +However, for \em very \em small matrices, the above is not true, and inverse and determinant can be very useful. + +While certain decompositions, such as PartialPivLU and FullPivLU, offer inverse() and determinant() methods, you can also +call inverse() and determinant() directly on a matrix. If your matrix is of a very small fixed size (at most 4x4) this +allows Eigen to avoid performing a LU decomposition, and instead use formulas that are more efficient on such small matrices. + +Here is an example: + + + + + + +
Example:Output:
\include TutorialLinAlgInverseDeterminant.cpp \verbinclude TutorialLinAlgInverseDeterminant.out
+ +\section TutorialLinAlgLeastsquares Least squares solving + +The best way to do least squares solving is with a SVD decomposition. Eigen provides one as the JacobiSVD class, and its solve() +is doing least-squares solving. + +Here is an example: + + + + + + +
Example:Output:
\include TutorialLinAlgSVDSolve.cpp \verbinclude TutorialLinAlgSVDSolve.out
+ +Another way, potentially faster but less reliable, is to use a LDLT decomposition +of the normal matrix. In any case, just read any reference text on least squares, and it will be very easy for you +to implement any linear least squares computation on top of Eigen. + +\section TutorialLinAlgSeparateComputation Separating the computation from the construction + +In the above examples, the decomposition was computed at the same time that the decomposition object was constructed. +There are however situations where you might want to separate these two things, for example if you don't know, +at the time of the construction, the matrix that you will want to decompose; or if you want to reuse an existing +decomposition object. + +What makes this possible is that: +\li all decompositions have a default constructor, +\li all decompositions have a compute(matrix) method that does the computation, and that may be called again + on an already-computed decomposition, reinitializing it. + +For example: + + + + + + + +
Example:Output:
\include TutorialLinAlgComputeTwice.cpp \verbinclude TutorialLinAlgComputeTwice.out
+ +Finally, you can tell the decomposition constructor to preallocate storage for decomposing matrices of a given size, +so that when you subsequently decompose such matrices, no dynamic memory allocation is performed (of course, if you +are using fixed-size matrices, no dynamic memory allocation happens at all). This is done by just +passing the size to the decomposition constructor, as in this example: +\code +HouseholderQR qr(50,50); +MatrixXf A = MatrixXf::Random(50,50); +qr.compute(A); // no dynamic memory allocation +\endcode + +\section TutorialLinAlgRankRevealing Rank-revealing decompositions + +Certain decompositions are rank-revealing, i.e. are able to compute the rank of a matrix. These are typically +also the decompositions that behave best in the face of a non-full-rank matrix (which in the square case means a +singular matrix). On \ref TopicLinearAlgebraDecompositions "this table" you can see for all our decompositions +whether they are rank-revealing or not. + +Rank-revealing decompositions offer at least a rank() method. They can also offer convenience methods such as isInvertible(), +and some are also providing methods to compute the kernel (null-space) and image (column-space) of the matrix, as is the +case with FullPivLU: + + + + + + + +
Example:Output:
\include TutorialLinAlgRankRevealing.cpp \verbinclude TutorialLinAlgRankRevealing.out
+ +Of course, any rank computation depends on the choice of an arbitrary threshold, since practically no +floating-point matrix is \em exactly rank-deficient. Eigen picks a sensible default threshold, which depends +on the decomposition but is typically the diagonal size times machine epsilon. While this is the best default we +could pick, only you know what is the right threshold for your application. You can set this by calling setThreshold() +on your decomposition object before calling rank() or any other method that needs to use such a threshold. +The decomposition itself, i.e. the compute() method, is independent of the threshold. You don't need to recompute the +decomposition after you've changed the threshold. + + + + + + + +
Example:Output:
\include TutorialLinAlgSetThreshold.cpp \verbinclude TutorialLinAlgSetThreshold.out
+ +*/ + +} diff --git a/doc/TutorialMapClass.dox b/doc/TutorialMapClass.dox new file mode 100644 index 000000000..a5c20f1bf --- /dev/null +++ b/doc/TutorialMapClass.dox @@ -0,0 +1,86 @@ +namespace Eigen { + +/** \eigenManualPage TutorialMapClass Interfacing with raw buffers: the Map class + +This page explains how to work with "raw" C/C++ arrays. +This can be useful in a variety of contexts, particularly when "importing" vectors and matrices from other libraries into Eigen. + +\eigenAutoToc + +\section TutorialMapIntroduction Introduction + +Occasionally you may have a pre-defined array of numbers that you want to use within Eigen as a vector or matrix. While one option is to make a copy of the data, most commonly you probably want to re-use this memory as an Eigen type. Fortunately, this is very easy with the Map class. + +\section TutorialMapTypes Map types and declaring Map variables + +A Map object has a type defined by its Eigen equivalent: +\code +Map > +\endcode +Note that, in this default case, a Map requires just a single template parameter. + +To construct a Map variable, you need two other pieces of information: a pointer to the region of memory defining the array of coefficients, and the desired shape of the matrix or vector. For example, to define a matrix of \c float with sizes determined at compile time, you might do the following: +\code +Map mf(pf,rows,columns); +\endcode +where \c pf is a \c float \c * pointing to the array of memory. A fixed-size read-only vector of integers might be declared as +\code +Map mi(pi); +\endcode +where \c pi is an \c int \c *. In this case the size does not have to be passed to the constructor, because it is already specified by the Matrix/Array type. + +Note that Map does not have a default constructor; you \em must pass a pointer to intialize the object. However, you can work around this requirement (see \ref TutorialMapPlacementNew). + +Map is flexible enough to accomodate a variety of different data representations. There are two other (optional) template parameters: +\code +Map +\endcode +\li \c MapOptions specifies whether the pointer is \c #Aligned, or \c #Unaligned. The default is \c #Unaligned. +\li \c StrideType allows you to specify a custom layout for the memory array, using the Stride class. One example would be to specify that the data array is organized in row-major format: + + + + + +
Example:Output:
\include Tutorial_Map_rowmajor.cpp \verbinclude Tutorial_Map_rowmajor.out
+However, Stride is even more flexible than this; for details, see the documentation for the Map and Stride classes. + +\section TutorialMapUsing Using Map variables + +You can use a Map object just like any other Eigen type: + + + + + +
Example:Output:
\include Tutorial_Map_using.cpp \verbinclude Tutorial_Map_using.out
+ +However, when writing functions taking Eigen types, it is important to realize that a Map type is \em not identical to its Dense equivalent. See \ref TopicFunctionTakingEigenTypesMultiarguments for details. + +\section TutorialMapPlacementNew Changing the mapped array + +It is possible to change the array of a Map object after declaration, using the C++ "placement new" syntax: + + + + + +
Example:Output:
\include Map_placement_new.cpp \verbinclude Map_placement_new.out
+Despite appearances, this does not invoke the memory allocator, because the syntax specifies the location for storing the result. + +This syntax makes it possible to declare a Map object without first knowing the mapped array's location in memory: +\code +Map A(NULL); // don't try to use this matrix yet! +VectorXf b(n_matrices); +for (int i = 0; i < n_matrices; i++) +{ + new (&A) Map(get_matrix_pointer(i)); + b(i) = A.trace(); +} +\endcode + +*/ + +} diff --git a/doc/TutorialMatrixArithmetic.dox b/doc/TutorialMatrixArithmetic.dox new file mode 100644 index 000000000..5fc569a30 --- /dev/null +++ b/doc/TutorialMatrixArithmetic.dox @@ -0,0 +1,214 @@ +namespace Eigen { + +/** \eigenManualPage TutorialMatrixArithmetic Matrix and vector arithmetic + +This page aims to provide an overview and some details on how to perform arithmetic +between matrices, vectors and scalars with Eigen. + +\eigenAutoToc + +\section TutorialArithmeticIntroduction Introduction + +Eigen offers matrix/vector arithmetic operations either through overloads of common C++ arithmetic operators such as +, -, *, +or through special methods such as dot(), cross(), etc. +For the Matrix class (matrices and vectors), operators are only overloaded to support +linear-algebraic operations. For example, \c matrix1 \c * \c matrix2 means matrix-matrix product, +and \c vector \c + \c scalar is just not allowed. If you want to perform all kinds of array operations, +not linear algebra, see the \ref TutorialArrayClass "next page". + +\section TutorialArithmeticAddSub Addition and subtraction + +The left hand side and right hand side must, of course, have the same numbers of rows and of columns. They must +also have the same \c Scalar type, as Eigen doesn't do automatic type promotion. The operators at hand here are: +\li binary operator + as in \c a+b +\li binary operator - as in \c a-b +\li unary operator - as in \c -a +\li compound operator += as in \c a+=b +\li compound operator -= as in \c a-=b + + + + +
Example:Output:
+\include tut_arithmetic_add_sub.cpp + +\verbinclude tut_arithmetic_add_sub.out +
+ +\section TutorialArithmeticScalarMulDiv Scalar multiplication and division + +Multiplication and division by a scalar is very simple too. The operators at hand here are: +\li binary operator * as in \c matrix*scalar +\li binary operator * as in \c scalar*matrix +\li binary operator / as in \c matrix/scalar +\li compound operator *= as in \c matrix*=scalar +\li compound operator /= as in \c matrix/=scalar + + + + +
Example:Output:
+\include tut_arithmetic_scalar_mul_div.cpp + +\verbinclude tut_arithmetic_scalar_mul_div.out +
+ + +\section TutorialArithmeticMentionXprTemplates A note about expression templates + +This is an advanced topic that we explain on \ref TopicEigenExpressionTemplates "this page", +but it is useful to just mention it now. In Eigen, arithmetic operators such as \c operator+ don't +perform any computation by themselves, they just return an "expression object" describing the computation to be +performed. The actual computation happens later, when the whole expression is evaluated, typically in \c operator=. +While this might sound heavy, any modern optimizing compiler is able to optimize away that abstraction and +the result is perfectly optimized code. For example, when you do: +\code +VectorXf a(50), b(50), c(50), d(50); +... +a = 3*b + 4*c + 5*d; +\endcode +Eigen compiles it to just one for loop, so that the arrays are traversed only once. Simplifying (e.g. ignoring +SIMD optimizations), this loop looks like this: +\code +for(int i = 0; i < 50; ++i) + a[i] = 3*b[i] + 4*c[i] + 5*d[i]; +\endcode +Thus, you should not be afraid of using relatively large arithmetic expressions with Eigen: it only gives Eigen +more opportunities for optimization. + +\section TutorialArithmeticTranspose Transposition and conjugation + +The transpose \f$ a^T \f$, conjugate \f$ \bar{a} \f$, and adjoint (i.e., conjugate transpose) \f$ a^* \f$ of a matrix or vector \f$ a \f$ are obtained by the member functions \link DenseBase::transpose() transpose()\endlink, \link MatrixBase::conjugate() conjugate()\endlink, and \link MatrixBase::adjoint() adjoint()\endlink, respectively. + + + + +
Example:Output:
+\include tut_arithmetic_transpose_conjugate.cpp + +\verbinclude tut_arithmetic_transpose_conjugate.out +
+ +For real matrices, \c conjugate() is a no-operation, and so \c adjoint() is equivalent to \c transpose(). + +As for basic arithmetic operators, \c transpose() and \c adjoint() simply return a proxy object without doing the actual transposition. If you do b = a.transpose(), then the transpose is evaluated at the same time as the result is written into \c b. However, there is a complication here. If you do a = a.transpose(), then Eigen starts writing the result into \c a before the evaluation of the transpose is finished. Therefore, the instruction a = a.transpose() does not replace \c a with its transpose, as one would expect: + + + +
Example:Output:
+\include tut_arithmetic_transpose_aliasing.cpp + +\verbinclude tut_arithmetic_transpose_aliasing.out +
+This is the so-called \ref TopicAliasing "aliasing issue". In "debug mode", i.e., when \ref TopicAssertions "assertions" have not been disabled, such common pitfalls are automatically detected. + +For \em in-place transposition, as for instance in a = a.transpose(), simply use the \link DenseBase::transposeInPlace() transposeInPlace()\endlink function: + + + +
Example:Output:
+\include tut_arithmetic_transpose_inplace.cpp + +\verbinclude tut_arithmetic_transpose_inplace.out +
+There is also the \link MatrixBase::adjointInPlace() adjointInPlace()\endlink function for complex matrices. + +\section TutorialArithmeticMatrixMul Matrix-matrix and matrix-vector multiplication + +Matrix-matrix multiplication is again done with \c operator*. Since vectors are a special +case of matrices, they are implicitly handled there too, so matrix-vector product is really just a special +case of matrix-matrix product, and so is vector-vector outer product. Thus, all these cases are handled by just +two operators: +\li binary operator * as in \c a*b +\li compound operator *= as in \c a*=b (this multiplies on the right: \c a*=b is equivalent to a = a*b) + + + + +
Example:Output:
+\include tut_arithmetic_matrix_mul.cpp + +\verbinclude tut_arithmetic_matrix_mul.out +
+ +Note: if you read the above paragraph on expression templates and are worried that doing \c m=m*m might cause +aliasing issues, be reassured for now: Eigen treats matrix multiplication as a special case and takes care of +introducing a temporary here, so it will compile \c m=m*m as: +\code +tmp = m*m; +m = tmp; +\endcode +If you know your matrix product can be safely evaluated into the destination matrix without aliasing issue, then you can use the \link MatrixBase::noalias() noalias()\endlink function to avoid the temporary, e.g.: +\code +c.noalias() += a * b; +\endcode +For more details on this topic, see the page on \ref TopicAliasing "aliasing". + +\b Note: for BLAS users worried about performance, expressions such as c.noalias() -= 2 * a.adjoint() * b; are fully optimized and trigger a single gemm-like function call. + +\section TutorialArithmeticDotAndCross Dot product and cross product + +For dot product and cross product, you need the \link MatrixBase::dot() dot()\endlink and \link MatrixBase::cross() cross()\endlink methods. Of course, the dot product can also be obtained as a 1x1 matrix as u.adjoint()*v. + + + +
Example:Output:
+\include tut_arithmetic_dot_cross.cpp + +\verbinclude tut_arithmetic_dot_cross.out +
+ +Remember that cross product is only for vectors of size 3. Dot product is for vectors of any sizes. +When using complex numbers, Eigen's dot product is conjugate-linear in the first variable and linear in the +second variable. + +\section TutorialArithmeticRedux Basic arithmetic reduction operations +Eigen also provides some reduction operations to reduce a given matrix or vector to a single value such as the sum (computed by \link DenseBase::sum() sum()\endlink), product (\link DenseBase::prod() prod()\endlink), or the maximum (\link DenseBase::maxCoeff() maxCoeff()\endlink) and minimum (\link DenseBase::minCoeff() minCoeff()\endlink) of all its coefficients. + + + + +
Example:Output:
+\include tut_arithmetic_redux_basic.cpp + +\verbinclude tut_arithmetic_redux_basic.out +
+ +The \em trace of a matrix, as returned by the function \link MatrixBase::trace() trace()\endlink, is the sum of the diagonal coefficients and can also be computed as efficiently using a.diagonal().sum(), as we will see later on. + +There also exist variants of the \c minCoeff and \c maxCoeff functions returning the coordinates of the respective coefficient via the arguments: + + + + +
Example:Output:
+\include tut_arithmetic_redux_minmax.cpp + +\verbinclude tut_arithmetic_redux_minmax.out +
+ + +\section TutorialArithmeticValidity Validity of operations +Eigen checks the validity of the operations that you perform. When possible, +it checks them at compile time, producing compilation errors. These error messages can be long and ugly, +but Eigen writes the important message in UPPERCASE_LETTERS_SO_IT_STANDS_OUT. For example: +\code + Matrix3f m; + Vector4f v; + v = m*v; // Compile-time error: YOU_MIXED_MATRICES_OF_DIFFERENT_SIZES +\endcode + +Of course, in many cases, for example when checking dynamic sizes, the check cannot be performed at compile time. +Eigen then uses runtime assertions. This means that the program will abort with an error message when executing an illegal operation if it is run in "debug mode", and it will probably crash if assertions are turned off. + +\code + MatrixXf m(3,3); + VectorXf v(4); + v = m * v; // Run-time assertion failure here: "invalid matrix product" +\endcode + +For more details on this topic, see \ref TopicAssertions "this page". + +*/ + +} diff --git a/doc/TutorialMatrixClass.dox b/doc/TutorialMatrixClass.dox new file mode 100644 index 000000000..057341422 --- /dev/null +++ b/doc/TutorialMatrixClass.dox @@ -0,0 +1,264 @@ +namespace Eigen { + +/** \eigenManualPage TutorialMatrixClass The Matrix class + +\eigenAutoToc + +In Eigen, all matrices and vectors are objects of the Matrix template class. +Vectors are just a special case of matrices, with either 1 row or 1 column. + +\section TutorialMatrixFirst3Params The first three template parameters of Matrix + +The Matrix class takes six template parameters, but for now it's enough to +learn about the first three first parameters. The three remaining parameters have default +values, which for now we will leave untouched, and which we +\ref TutorialMatrixOptTemplParams "discuss below". + +The three mandatory template parameters of Matrix are: +\code +Matrix +\endcode +\li \c Scalar is the scalar type, i.e. the type of the coefficients. + That is, if you want a matrix of floats, choose \c float here. + See \ref TopicScalarTypes "Scalar types" for a list of all supported + scalar types and for how to extend support to new types. +\li \c RowsAtCompileTime and \c ColsAtCompileTime are the number of rows + and columns of the matrix as known at compile time (see + \ref TutorialMatrixDynamic "below" for what to do if the number is not + known at compile time). + +We offer a lot of convenience typedefs to cover the usual cases. For example, \c Matrix4f is +a 4x4 matrix of floats. Here is how it is defined by Eigen: +\code +typedef Matrix Matrix4f; +\endcode +We discuss \ref TutorialMatrixTypedefs "below" these convenience typedefs. + +\section TutorialMatrixVectors Vectors + +As mentioned above, in Eigen, vectors are just a special case of +matrices, with either 1 row or 1 column. The case where they have 1 column is the most common; +such vectors are called column-vectors, often abbreviated as just vectors. In the other case +where they have 1 row, they are called row-vectors. + +For example, the convenience typedef \c Vector3f is a (column) vector of 3 floats. It is defined as follows by Eigen: +\code +typedef Matrix Vector3f; +\endcode +We also offer convenience typedefs for row-vectors, for example: +\code +typedef Matrix RowVector2i; +\endcode + +\section TutorialMatrixDynamic The special value Dynamic + +Of course, Eigen is not limited to matrices whose dimensions are known at compile time. +The \c RowsAtCompileTime and \c ColsAtCompileTime template parameters can take the special +value \c Dynamic which indicates that the size is unknown at compile time, so must +be handled as a run-time variable. In Eigen terminology, such a size is referred to as a +\em dynamic \em size; while a size that is known at compile time is called a +\em fixed \em size. For example, the convenience typedef \c MatrixXd, meaning +a matrix of doubles with dynamic size, is defined as follows: +\code +typedef Matrix MatrixXd; +\endcode +And similarly, we define a self-explanatory typedef \c VectorXi as follows: +\code +typedef Matrix VectorXi; +\endcode +You can perfectly have e.g. a fixed number of rows with a dynamic number of columns, as in: +\code +Matrix +\endcode + +\section TutorialMatrixConstructors Constructors + +A default constructor is always available, never performs any dynamic memory allocation, and never initializes the matrix coefficients. You can do: +\code +Matrix3f a; +MatrixXf b; +\endcode +Here, +\li \c a is a 3x3 matrix, with a static float[9] array of uninitialized coefficients, +\li \c b is a dynamic-size matrix whose size is currently 0x0, and whose array of +coefficients hasn't yet been allocated at all. + +Constructors taking sizes are also available. For matrices, the number of rows is always passed first. +For vectors, just pass the vector size. They allocate the array of coefficients +with the given size, but don't initialize the coefficients themselves: +\code +MatrixXf a(10,15); +VectorXf b(30); +\endcode +Here, +\li \c a is a 10x15 dynamic-size matrix, with allocated but currently uninitialized coefficients. +\li \c b is a dynamic-size vector of size 30, with allocated but currently uninitialized coefficients. + +In order to offer a uniform API across fixed-size and dynamic-size matrices, it is legal to use these +constructors on fixed-size matrices, even if passing the sizes is useless in this case. So this is legal: +\code +Matrix3f a(3,3); +\endcode +and is a no-operation. + +Finally, we also offer some constructors to initialize the coefficients of small fixed-size vectors up to size 4: +\code +Vector2d a(5.0, 6.0); +Vector3d b(5.0, 6.0, 7.0); +Vector4d c(5.0, 6.0, 7.0, 8.0); +\endcode + +\section TutorialMatrixCoeffAccessors Coefficient accessors + +The primary coefficient accessors and mutators in Eigen are the overloaded parenthesis operators. +For matrices, the row index is always passed first. For vectors, just pass one index. +The numbering starts at 0. This example is self-explanatory: + + + + +
Example:Output:
+\include tut_matrix_coefficient_accessors.cpp + +\verbinclude tut_matrix_coefficient_accessors.out +
+ +Note that the syntax m(index) +is not restricted to vectors, it is also available for general matrices, meaning index-based access +in the array of coefficients. This however depends on the matrix's storage order. All Eigen matrices default to +column-major storage order, but this can be changed to row-major, see \ref TopicStorageOrders "Storage orders". + +The operator[] is also overloaded for index-based access in vectors, but keep in mind that C++ doesn't allow operator[] to +take more than one argument. We restrict operator[] to vectors, because an awkwardness in the C++ language +would make matrix[i,j] compile to the same thing as matrix[j] ! + +\section TutorialMatrixCommaInitializer Comma-initialization + +%Matrix and vector coefficients can be conveniently set using the so-called \em comma-initializer syntax. +For now, it is enough to know this example: + + + + + + +
Example:Output:
\include Tutorial_commainit_01.cpp \verbinclude Tutorial_commainit_01.out
+ + +The right-hand side can also contain matrix expressions as discussed in \ref TutorialAdvancedInitialization "this page". + +\section TutorialMatrixSizesResizing Resizing + +The current size of a matrix can be retrieved by \link EigenBase::rows() rows()\endlink, \link EigenBase::cols() cols() \endlink and \link EigenBase::size() size()\endlink. These methods return the number of rows, the number of columns and the number of coefficients, respectively. Resizing a dynamic-size matrix is done by the \link PlainObjectBase::resize(Index,Index) resize() \endlink method. + + + + + + +
Example:Output:
\include tut_matrix_resize.cpp \verbinclude tut_matrix_resize.out
+ +The resize() method is a no-operation if the actual matrix size doesn't change; otherwise it is destructive: the values of the coefficients may change. +If you want a conservative variant of resize() which does not change the coefficients, use \link PlainObjectBase::conservativeResize() conservativeResize()\endlink, see \ref TopicResizing "this page" for more details. + +All these methods are still available on fixed-size matrices, for the sake of API uniformity. Of course, you can't actually +resize a fixed-size matrix. Trying to change a fixed size to an actually different value will trigger an assertion failure; +but the following code is legal: + + + + + + +
Example:Output:
\include tut_matrix_resize_fixed_size.cpp \verbinclude tut_matrix_resize_fixed_size.out
+ + +\section TutorialMatrixAssignment Assignment and resizing + +Assignment is the action of copying a matrix into another, using \c operator=. Eigen resizes the matrix on the left-hand side automatically so that it matches the size of the matrix on the right-hand size. For example: + + + + + + +
Example:Output:
\include tut_matrix_assignment_resizing.cpp \verbinclude tut_matrix_assignment_resizing.out
+ +Of course, if the left-hand side is of fixed size, resizing it is not allowed. + +If you do not want this automatic resizing to happen (for example for debugging purposes), you can disable it, see +\ref TopicResizing "this page". + + +\section TutorialMatrixFixedVsDynamic Fixed vs. Dynamic size + +When should one use fixed sizes (e.g. \c Matrix4f), and when should one prefer dynamic sizes (e.g. \c MatrixXf)? +The simple answer is: use fixed +sizes for very small sizes where you can, and use dynamic sizes for larger sizes or where you have to. For small sizes, +especially for sizes smaller than (roughly) 16, using fixed sizes is hugely beneficial +to performance, as it allows Eigen to avoid dynamic memory allocation and to unroll +loops. Internally, a fixed-size Eigen matrix is just a plain static array, i.e. doing +\code Matrix4f mymatrix; \endcode +really amounts to just doing +\code float mymatrix[16]; \endcode +so this really has zero runtime cost. By contrast, the array of a dynamic-size matrix +is always allocated on the heap, so doing +\code MatrixXf mymatrix(rows,columns); \endcode +amounts to doing +\code float *mymatrix = new float[rows*columns]; \endcode +and in addition to that, the MatrixXf object stores its number of rows and columns as +member variables. + +The limitation of using fixed sizes, of course, is that this is only possible +when you know the sizes at compile time. Also, for large enough sizes, say for sizes +greater than (roughly) 32, the performance benefit of using fixed sizes becomes negligible. +Worse, trying to create a very large matrix using fixed sizes could result in a stack overflow, +since Eigen will try to allocate the array as a static array, which by default goes on the stack. +Finally, depending on circumstances, Eigen can also be more aggressive trying to vectorize +(use SIMD instructions) when dynamic sizes are used, see \ref TopicVectorization "Vectorization". + +\section TutorialMatrixOptTemplParams Optional template parameters + +We mentioned at the beginning of this page that the Matrix class takes six template parameters, +but so far we only discussed the first three. The remaining three parameters are optional. Here is +the complete list of template parameters: +\code +Matrix +\endcode +\li \c Options is a bit field. Here, we discuss only one bit: \c RowMajor. It specifies that the matrices + of this type use row-major storage order; by default, the storage order is column-major. See the page on + \ref TopicStorageOrders "storage orders". For example, this type means row-major 3x3 matrices: + \code + Matrix + \endcode +\li \c MaxRowsAtCompileTime and \c MaxColsAtCompileTime are useful when you want to specify that, even though + the exact sizes of your matrices are not known at compile time, a fixed upper bound is known at + compile time. The biggest reason why you might want to do that is to avoid dynamic memory allocation. + For example the following matrix type uses a static array of 12 floats, without dynamic memory allocation: + \code + Matrix + \endcode + +\section TutorialMatrixTypedefs Convenience typedefs + +Eigen defines the following Matrix typedefs: +\li MatrixNt for Matrix. For example, MatrixXi for Matrix. +\li VectorNt for Matrix. For example, Vector2f for Matrix. +\li RowVectorNt for Matrix. For example, RowVector3d for Matrix. + +Where: +\li N can be any one of \c 2, \c 3, \c 4, or \c X (meaning \c Dynamic). +\li t can be any one of \c i (meaning int), \c f (meaning float), \c d (meaning double), + \c cf (meaning complex), or \c cd (meaning complex). The fact that typedefs are only + defined for these five types doesn't mean that they are the only supported scalar types. For example, + all standard integer types are supported, see \ref TopicScalarTypes "Scalar types". + + +*/ + +} diff --git a/doc/TutorialReductionsVisitorsBroadcasting.dox b/doc/TutorialReductionsVisitorsBroadcasting.dox new file mode 100644 index 000000000..992cf6f34 --- /dev/null +++ b/doc/TutorialReductionsVisitorsBroadcasting.dox @@ -0,0 +1,257 @@ +namespace Eigen { + +/** \eigenManualPage TutorialReductionsVisitorsBroadcasting Reductions, visitors and broadcasting + +This page explains Eigen's reductions, visitors and broadcasting and how they are used with +\link MatrixBase matrices \endlink and \link ArrayBase arrays \endlink. + +\eigenAutoToc + +\section TutorialReductionsVisitorsBroadcastingReductions Reductions +In Eigen, a reduction is a function taking a matrix or array, and returning a single +scalar value. One of the most used reductions is \link DenseBase::sum() .sum() \endlink, +returning the sum of all the coefficients inside a given matrix or array. + + + + +
Example:Output:
+\include tut_arithmetic_redux_basic.cpp + +\verbinclude tut_arithmetic_redux_basic.out +
+ +The \em trace of a matrix, as returned by the function \c trace(), is the sum of the diagonal coefficients and can equivalently be computed a.diagonal().sum(). + + +\subsection TutorialReductionsVisitorsBroadcastingReductionsNorm Norm computations + +The (Euclidean a.k.a. \f$\ell^2\f$) squared norm of a vector can be obtained \link MatrixBase::squaredNorm() squaredNorm() \endlink. It is equal to the dot product of the vector by itself, and equivalently to the sum of squared absolute values of its coefficients. + +Eigen also provides the \link MatrixBase::norm() norm() \endlink method, which returns the square root of \link MatrixBase::squaredNorm() squaredNorm() \endlink. + +These operations can also operate on matrices; in that case, a n-by-p matrix is seen as a vector of size (n*p), so for example the \link MatrixBase::norm() norm() \endlink method returns the "Frobenius" or "Hilbert-Schmidt" norm. We refrain from speaking of the \f$\ell^2\f$ norm of a matrix because that can mean different things. + +If you want other \f$\ell^p\f$ norms, use the \link MatrixBase::lpNorm() lpNnorm

() \endlink method. The template parameter \a p can take the special value \a Infinity if you want the \f$\ell^\infty\f$ norm, which is the maximum of the absolute values of the coefficients. + +The following example demonstrates these methods. + + + + +
Example:Output:
+\include Tutorial_ReductionsVisitorsBroadcasting_reductions_norm.cpp + +\verbinclude Tutorial_ReductionsVisitorsBroadcasting_reductions_norm.out +
+ +\subsection TutorialReductionsVisitorsBroadcastingReductionsBool Boolean reductions + +The following reductions operate on boolean values: + - \link DenseBase::all() all() \endlink returns \b true if all of the coefficients in a given Matrix or Array evaluate to \b true . + - \link DenseBase::any() any() \endlink returns \b true if at least one of the coefficients in a given Matrix or Array evaluates to \b true . + - \link DenseBase::count() count() \endlink returns the number of coefficients in a given Matrix or Array that evaluate to \b true. + +These are typically used in conjunction with the coefficient-wise comparison and equality operators provided by Array. For instance, array > 0 is an %Array of the same size as \c array , with \b true at those positions where the corresponding coefficient of \c array is positive. Thus, (array > 0).all() tests whether all coefficients of \c array are positive. This can be seen in the following example: + + + + +
Example:Output:
+\include Tutorial_ReductionsVisitorsBroadcasting_reductions_bool.cpp + +\verbinclude Tutorial_ReductionsVisitorsBroadcasting_reductions_bool.out +
+ +\subsection TutorialReductionsVisitorsBroadcastingReductionsUserdefined User defined reductions + +TODO + +In the meantime you can have a look at the DenseBase::redux() function. + +\section TutorialReductionsVisitorsBroadcastingVisitors Visitors +Visitors are useful when one wants to obtain the location of a coefficient inside +a Matrix or Array. The simplest examples are +\link MatrixBase::maxCoeff() maxCoeff(&x,&y) \endlink and +\link MatrixBase::minCoeff() minCoeff(&x,&y)\endlink, which can be used to find +the location of the greatest or smallest coefficient in a Matrix or +Array. + +The arguments passed to a visitor are pointers to the variables where the +row and column position are to be stored. These variables should be of type +\link DenseBase::Index Index \endlink, as shown below: + + + + +
Example:Output:
+\include Tutorial_ReductionsVisitorsBroadcasting_visitors.cpp + +\verbinclude Tutorial_ReductionsVisitorsBroadcasting_visitors.out +
+ +Note that both functions also return the value of the minimum or maximum coefficient if needed, +as if it was a typical reduction operation. + +\section TutorialReductionsVisitorsBroadcastingPartialReductions Partial reductions +Partial reductions are reductions that can operate column- or row-wise on a Matrix or +Array, applying the reduction operation on each column or row and +returning a column or row-vector with the corresponding values. Partial reductions are applied +with \link DenseBase::colwise() colwise() \endlink or \link DenseBase::rowwise() rowwise() \endlink. + +A simple example is obtaining the maximum of the elements +in each column in a given matrix, storing the result in a row-vector: + + + + +
Example:Output:
+\include Tutorial_ReductionsVisitorsBroadcasting_colwise.cpp + +\verbinclude Tutorial_ReductionsVisitorsBroadcasting_colwise.out +
+ +The same operation can be performed row-wise: + + + + +
Example:Output:
+\include Tutorial_ReductionsVisitorsBroadcasting_rowwise.cpp + +\verbinclude Tutorial_ReductionsVisitorsBroadcasting_rowwise.out +
+ +Note that column-wise operations return a 'row-vector' while row-wise operations +return a 'column-vector' + +\subsection TutorialReductionsVisitorsBroadcastingPartialReductionsCombined Combining partial reductions with other operations +It is also possible to use the result of a partial reduction to do further processing. +Here is another example that finds the column whose sum of elements is the maximum + within a matrix. With column-wise partial reductions this can be coded as: + + + + +
Example:Output:
+\include Tutorial_ReductionsVisitorsBroadcasting_maxnorm.cpp + +\verbinclude Tutorial_ReductionsVisitorsBroadcasting_maxnorm.out +
+ +The previous example applies the \link DenseBase::sum() sum() \endlink reduction on each column +though the \link DenseBase::colwise() colwise() \endlink visitor, obtaining a new matrix whose +size is 1x4. + +Therefore, if +\f[ +\mbox{m} = \begin{bmatrix} 1 & 2 & 6 & 9 \\ + 3 & 1 & 7 & 2 \end{bmatrix} +\f] + +then + +\f[ +\mbox{m.colwise().sum()} = \begin{bmatrix} 4 & 3 & 13 & 11 \end{bmatrix} +\f] + +The \link DenseBase::maxCoeff() maxCoeff() \endlink reduction is finally applied +to obtain the column index where the maximum sum is found, +which is the column index 2 (third column) in this case. + + +\section TutorialReductionsVisitorsBroadcastingBroadcasting Broadcasting +The concept behind broadcasting is similar to partial reductions, with the difference that broadcasting +constructs an expression where a vector (column or row) is interpreted as a matrix by replicating it in +one direction. + +A simple example is to add a certain column-vector to each column in a matrix. +This can be accomplished with: + + + + +
Example:Output:
+\include Tutorial_ReductionsVisitorsBroadcasting_broadcast_simple.cpp + +\verbinclude Tutorial_ReductionsVisitorsBroadcasting_broadcast_simple.out +
+ +We can interpret the instruction mat.colwise() += v in two equivalent ways. It adds the vector \c v +to every column of the matrix. Alternatively, it can be interpreted as repeating the vector \c v four times to +form a four-by-two matrix which is then added to \c mat: +\f[ +\begin{bmatrix} 1 & 2 & 6 & 9 \\ 3 & 1 & 7 & 2 \end{bmatrix} ++ \begin{bmatrix} 0 & 0 & 0 & 0 \\ 1 & 1 & 1 & 1 \end{bmatrix} += \begin{bmatrix} 1 & 2 & 6 & 9 \\ 4 & 2 & 8 & 3 \end{bmatrix}. +\f] +The operators -=, + and - can also be used column-wise and row-wise. On arrays, we +can also use the operators *=, /=, * and / to perform coefficient-wise +multiplication and division column-wise or row-wise. These operators are not available on matrices because it +is not clear what they would do. If you want multiply column 0 of a matrix \c mat with \c v(0), column 1 with +\c v(1), and so on, then use mat = mat * v.asDiagonal(). + +It is important to point out that the vector to be added column-wise or row-wise must be of type Vector, +and cannot be a Matrix. If this is not met then you will get compile-time error. This also means that +broadcasting operations can only be applied with an object of type Vector, when operating with Matrix. +The same applies for the Array class, where the equivalent for VectorXf is ArrayXf. As always, you should +not mix arrays and matrices in the same expression. + +To perform the same operation row-wise we can do: + + + + +
Example:Output:
+\include Tutorial_ReductionsVisitorsBroadcasting_broadcast_simple_rowwise.cpp + +\verbinclude Tutorial_ReductionsVisitorsBroadcasting_broadcast_simple_rowwise.out +
+ +\subsection TutorialReductionsVisitorsBroadcastingBroadcastingCombined Combining broadcasting with other operations +Broadcasting can also be combined with other operations, such as Matrix or Array operations, +reductions and partial reductions. + +Now that broadcasting, reductions and partial reductions have been introduced, we can dive into a more advanced example that finds +the nearest neighbour of a vector v within the columns of matrix m. The Euclidean distance will be used in this example, +computing the squared Euclidean distance with the partial reduction named \link MatrixBase::squaredNorm() squaredNorm() \endlink: + + + + +
Example:Output:
+\include Tutorial_ReductionsVisitorsBroadcasting_broadcast_1nn.cpp + +\verbinclude Tutorial_ReductionsVisitorsBroadcasting_broadcast_1nn.out +
+ +The line that does the job is +\code + (m.colwise() - v).colwise().squaredNorm().minCoeff(&index); +\endcode + +We will go step by step to understand what is happening: + + - m.colwise() - v is a broadcasting operation, subtracting v from each column in m. The result of this operation +is a new matrix whose size is the same as matrix m: \f[ + \mbox{m.colwise() - v} = + \begin{bmatrix} + -1 & 21 & 4 & 7 \\ + 0 & 8 & 4 & -1 + \end{bmatrix} +\f] + + - (m.colwise() - v).colwise().squaredNorm() is a partial reduction, computing the squared norm column-wise. The result of +this operation is a row-vector where each coefficient is the squared Euclidean distance between each column in m and v: \f[ + \mbox{(m.colwise() - v).colwise().squaredNorm()} = + \begin{bmatrix} + 1 & 505 & 32 & 50 + \end{bmatrix} +\f] + + - Finally, minCoeff(&index) is used to obtain the index of the column in m that is closest to v in terms of Euclidean +distance. + +*/ + +} diff --git a/doc/TutorialSparse.dox b/doc/TutorialSparse.dox new file mode 100644 index 000000000..9f06005fa --- /dev/null +++ b/doc/TutorialSparse.dox @@ -0,0 +1,436 @@ +namespace Eigen { + +/** \eigenManualPage TutorialSparse Sparse matrix manipulations + +\eigeneigenAutoToc + +Manipulating and solving sparse problems involves various modules which are summarized below: + + + + + + + +
ModuleHeader fileContents
\link SparseCore_Module SparseCore \endlink\code#include \endcodeSparseMatrix and SparseVector classes, matrix assembly, basic sparse linear algebra (including sparse triangular solvers)
\link SparseCholesky_Module SparseCholesky \endlink\code#include \endcodeDirect sparse LLT and LDLT Cholesky factorization to solve sparse self-adjoint positive definite problems
\link IterativeLinearSolvers_Module IterativeLinearSolvers \endlink\code#include \endcodeIterative solvers to solve large general linear square problems (including self-adjoint positive definite problems)
\link Sparse_modules Sparse \endlink\code#include \endcodeIncludes all the above modules
+ +\section TutorialSparseIntro Sparse matrix representation + +In many applications (e.g., finite element methods) it is common to deal with very large matrices where only a few coefficients are different from zero. In such cases, memory consumption can be reduced and performance increased by using a specialized representation storing only the nonzero coefficients. Such a matrix is called a sparse matrix. + +\b The \b %SparseMatrix \b class + +The class SparseMatrix is the main sparse matrix representation of Eigen's sparse module; it offers high performance and low memory usage. +It implements a more versatile variant of the widely-used Compressed Column (or Row) Storage scheme. +It consists of four compact arrays: + - \c Values: stores the coefficient values of the non-zeros. + - \c InnerIndices: stores the row (resp. column) indices of the non-zeros. + - \c OuterStarts: stores for each column (resp. row) the index of the first non-zero in the previous two arrays. + - \c InnerNNZs: stores the number of non-zeros of each column (resp. row). +The word \c inner refers to an \em inner \em vector that is a column for a column-major matrix, or a row for a row-major matrix. +The word \c outer refers to the other direction. + +This storage scheme is better explained on an example. The following matrix + + + + + + +
03 00 0
220 0017
75 01 0
00 00 0
00140 8
+ +and one of its possible sparse, \b column \b major representation: + + + +
Values: 227_3514__1_178
InnerIndices: 12_02 4__2_ 14
+ + + +
OuterStarts:035810\em 12
InnerNNZs: 2211 2
+ +Currently the elements of a given inner vector are guaranteed to be always sorted by increasing inner indices. +The \c "_" indicates available free space to quickly insert new elements. +Assuming no reallocation is needed, the insertion of a random element is therefore in O(nnz_j) where nnz_j is the number of nonzeros of the respective inner vector. +On the other hand, inserting elements with increasing inner indices in a given inner vector is much more efficient since this only requires to increase the respective \c InnerNNZs entry that is a O(1) operation. + +The case where no empty space is available is a special case, and is refered as the \em compressed mode. +It corresponds to the widely used Compressed Column (or Row) Storage schemes (CCS or CRS). +Any SparseMatrix can be turned to this form by calling the SparseMatrix::makeCompressed() function. +In this case, one can remark that the \c InnerNNZs array is redundant with \c OuterStarts because we the equality: \c InnerNNZs[j] = \c OuterStarts[j+1]-\c OuterStarts[j]. +Therefore, in practice a call to SparseMatrix::makeCompressed() frees this buffer. + +It is worth noting that most of our wrappers to external libraries requires compressed matrices as inputs. + +The results of %Eigen's operations always produces \b compressed sparse matrices. +On the other hand, the insertion of a new element into a SparseMatrix converts this later to the \b uncompressed mode. + +Here is the previous matrix represented in compressed mode: + + + +
Values: 22735141178
InnerIndices: 1202 42 14
+ + +
OuterStarts:02456\em 8
+ +A SparseVector is a special case of a SparseMatrix where only the \c Values and \c InnerIndices arrays are stored. +There is no notion of compressed/uncompressed mode for a SparseVector. + + +\section TutorialSparseExample First example + +Before describing each individual class, let's start with the following typical example: solving the Lapace equation \f$ \nabla u = 0 \f$ on a regular 2D grid using a finite difference scheme and Dirichlet boundary conditions. +Such problem can be mathematically expressed as a linear problem of the form \f$ Ax=b \f$ where \f$ x \f$ is the vector of \c m unknowns (in our case, the values of the pixels), \f$ b \f$ is the right hand side vector resulting from the boundary conditions, and \f$ A \f$ is an \f$ m \times m \f$ matrix containing only a few non-zero elements resulting from the discretization of the Laplacian operator. + + + +
+\include Tutorial_sparse_example.cpp + +\image html Tutorial_sparse_example.jpeg +
+ +In this example, we start by defining a column-major sparse matrix type of double \c SparseMatrix, and a triplet list of the same scalar type \c Triplet. A triplet is a simple object representing a non-zero entry as the triplet: \c row index, \c column index, \c value. + +In the main function, we declare a list \c coefficients of triplets (as a std vector) and the right hand side vector \f$ b \f$ which are filled by the \a buildProblem function. +The raw and flat list of non-zero entries is then converted to a true SparseMatrix object \c A. +Note that the elements of the list do not have to be sorted, and possible duplicate entries will be summed up. + +The last step consists of effectively solving the assembled problem. +Since the resulting matrix \c A is symmetric by construction, we can perform a direct Cholesky factorization via the SimplicialLDLT class which behaves like its LDLT counterpart for dense objects. + +The resulting vector \c x contains the pixel values as a 1D array which is saved to a jpeg file shown on the right of the code above. + +Describing the \a buildProblem and \a save functions is out of the scope of this tutorial. They are given \ref TutorialSparse_example_details "here" for the curious and reproducibility purpose. + + + + +\section TutorialSparseSparseMatrix The SparseMatrix class + +\b %Matrix \b and \b vector \b properties \n + +The SparseMatrix and SparseVector classes take three template arguments: + * the scalar type (e.g., double) + * the storage order (ColMajor or RowMajor, the default is RowMajor) + * the inner index type (default is \c int). + +As for dense Matrix objects, constructors takes the size of the object. +Here are some examples: + +\code +SparseMatrix > mat(1000,2000); // declares a 1000x2000 column-major compressed sparse matrix of complex +SparseMatrix mat(1000,2000); // declares a 1000x2000 row-major compressed sparse matrix of double +SparseVector > vec(1000); // declares a column sparse vector of complex of size 1000 +SparseVector vec(1000); // declares a row sparse vector of double of size 1000 +\endcode + +In the rest of the tutorial, \c mat and \c vec represent any sparse-matrix and sparse-vector objects, respectively. + +The dimensions of a matrix can be queried using the following functions: + + + + + + + + + +
Standard \n dimensions\code +mat.rows() +mat.cols()\endcode\code +vec.size() \endcode
Sizes along the \n inner/outer dimensions\code +mat.innerSize() +mat.outerSize()\endcode
Number of non \n zero coefficients\code +mat.nonZeros() \endcode\code +vec.nonZeros() \endcode
+ + +\b Iterating \b over \b the \b nonzero \b coefficients \n + +Random access to the elements of a sparse object can be done through the \c coeffRef(i,j) function. +However, this function involves a quite expensive binary search. +In most cases, one only wants to iterate over the non-zeros elements. This is achieved by a standard loop over the outer dimension, and then by iterating over the non-zeros of the current inner vector via an InnerIterator. Thus, the non-zero entries have to be visited in the same order than the storage order. +Here is an example: + + +
+\code +SparseMatrix mat(rows,cols); +for (int k=0; k::InnerIterator it(mat,k); it; ++it) + { + it.value(); + it.row(); // row index + it.col(); // col index (here it is equal to k) + it.index(); // inner index, here it is equal to it.row() + } +\endcode + +\code +SparseVector vec(size); +for (SparseVector::InnerIterator it(vec); it; ++it) +{ + it.value(); // == vec[ it.index() ] + it.index(); +} +\endcode +
+For a writable expression, the referenced value can be modified using the valueRef() function. +If the type of the sparse matrix or vector depends on a template parameter, then the \c typename keyword is +required to indicate that \c InnerIterator denotes a type; see \ref TopicTemplateKeyword for details. + + +\section TutorialSparseFilling Filling a sparse matrix + +Because of the special storage scheme of a SparseMatrix, special care has to be taken when adding new nonzero entries. +For instance, the cost of a single purely random insertion into a SparseMatrix is \c O(nnz), where \c nnz is the current number of non-zero coefficients. + +The simplest way to create a sparse matrix while guaranteeing good performance is thus to first build a list of so-called \em triplets, and then convert it to a SparseMatrix. + +Here is a typical usage example: +\code +typedef Eigen::Triplet T; +std::vector tripletList; +tripletList.reserve(estimation_of_entries); +for(...) +{ + // ... + tripletList.push_back(T(i,j,v_ij)); +} +SparseMatrixType mat(rows,cols); +mat.setFromTriplets(tripletList.begin(), tripletList.end()); +// mat is ready to go! +\endcode +The \c std::vector of triplets might contain the elements in arbitrary order, and might even contain duplicated elements that will be summed up by setFromTriplets(). +See the SparseMatrix::setFromTriplets() function and class Triplet for more details. + + +In some cases, however, slightly higher performance, and lower memory consumption can be reached by directly inserting the non-zeros into the destination matrix. +A typical scenario of this approach is illustrated bellow: +\code +1: SparseMatrix mat(rows,cols); // default is column major +2: mat.reserve(VectorXi::Constant(cols,6)); +3: for each i,j such that v_ij != 0 +4: mat.insert(i,j) = v_ij; // alternative: mat.coeffRef(i,j) += v_ij; +5: mat.makeCompressed(); // optional +\endcode + +- The key ingredient here is the line 2 where we reserve room for 6 non-zeros per column. In many cases, the number of non-zeros per column or row can easily be known in advance. If it varies significantly for each inner vector, then it is possible to specify a reserve size for each inner vector by providing a vector object with an operator[](int j) returning the reserve size of the \c j-th inner vector (e.g., via a VectorXi or std::vector). If only a rought estimate of the number of nonzeros per inner-vector can be obtained, it is highly recommended to overestimate it rather than the opposite. If this line is omitted, then the first insertion of a new element will reserve room for 2 elements per inner vector. +- The line 4 performs a sorted insertion. In this example, the ideal case is when the \c j-th column is not full and contains non-zeros whose inner-indices are smaller than \c i. In this case, this operation boils down to trivial O(1) operation. +- When calling insert(i,j) the element \c i \c ,j must not already exists, otherwise use the coeffRef(i,j) method that will allow to, e.g., accumulate values. This method first performs a binary search and finally calls insert(i,j) if the element does not already exist. It is more flexible than insert() but also more costly. +- The line 5 suppresses the remaining empty space and transforms the matrix into a compressed column storage. + + +\section TutorialSparseDirectSolvers Solving linear problems + +%Eigen currently provides a limited set of built-in solvers, as well as wrappers to external solver libraries. +They are summarized in the following table: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ClassModuleSolver kindMatrix kindFeatures related to performanceDependencies,License

Notes

SimplicialLLT \link SparseCholesky_Module SparseCholesky \endlinkDirect LLt factorizationSPDFill-in reducingbuilt-in, LGPLSimplicialLDLT is often preferable
SimplicialLDLT \link SparseCholesky_Module SparseCholesky \endlinkDirect LDLt factorizationSPDFill-in reducingbuilt-in, LGPLRecommended for very sparse and not too large problems (e.g., 2D Poisson eq.)
ConjugateGradient\link IterativeLinearSolvers_Module IterativeLinearSolvers \endlinkClassic iterative CGSPDPreconditionningbuilt-in, LGPLRecommended for large symmetric problems (e.g., 3D Poisson eq.)
BiCGSTAB\link IterativeLinearSolvers_Module IterativeLinearSolvers \endlinkIterative stabilized bi-conjugate gradientSquarePreconditionningbuilt-in, LGPLMight not always converge
PastixLLT \n PastixLDLT \n PastixLU\link PaStiXSupport_Module PaStiXSupport \endlinkDirect LLt, LDLt, LU factorizationsSPD \n SPD \n SquareFill-in reducing, Leverage fast dense algebra, MultithreadingRequires the PaStiX package, \b CeCILL-C optimized for tough problems and symmetric patterns
CholmodSupernodalLLT\link CholmodSupport_Module CholmodSupport \endlinkDirect LLt factorizationSPDFill-in reducing, Leverage fast dense algebraRequires the SuiteSparse package, \b GPL
UmfPackLU\link UmfPackSupport_Module UmfPackSupport \endlinkDirect LU factorizationSquareFill-in reducing, Leverage fast dense algebraRequires the SuiteSparse package, \b GPL
SuperLU\link SuperLUSupport_Module SuperLUSupport \endlinkDirect LU factorizationSquareFill-in reducing, Leverage fast dense algebraRequires the SuperLU library, (BSD-like)
+ +Here \c SPD means symmetric positive definite. + +All these solvers follow the same general concept. +Here is a typical and general example: +\code +#include +// ... +SparseMatrix A; +// fill A +VectorXd b, x; +// fill b +// solve Ax = b +SolverClassName > solver; +solver.compute(A); +if(solver.info()!=Success) { + // decomposition failed + return; +} +x = solver.solve(b); +if(solver.info()!=Success) { + // solving failed + return; +} +// solve for another right hand side: +x1 = solver.solve(b1); +\endcode + +For \c SPD solvers, a second optional template argument allows to specify which triangular part have to be used, e.g.: + +\code +#include + +ConjugateGradient, Eigen::Upper> solver; +x = solver.compute(A).solve(b); +\endcode +In the above example, only the upper triangular part of the input matrix A is considered for solving. The opposite triangle might either be empty or contain arbitrary values. + +In the case where multiple problems with the same sparcity pattern have to be solved, then the "compute" step can be decomposed as follow: +\code +SolverClassName > solver; +solver.analyzePattern(A); // for this step the numerical values of A are not used +solver.factorize(A); +x1 = solver.solve(b1); +x2 = solver.solve(b2); +... +A = ...; // modify the values of the nonzeros of A, the nonzeros pattern must stay unchanged +solver.factorize(A); +x1 = solver.solve(b1); +x2 = solver.solve(b2); +... +\endcode +The compute() method is equivalent to calling both analyzePattern() and factorize(). + +Finally, each solver provides some specific features, such as determinant, access to the factors, controls of the iterations, and so on. +More details are availble in the documentations of the respective classes. + + +\section TutorialSparseFeatureSet Supported operators and functions + +Because of their special storage format, sparse matrices cannot offer the same level of flexbility than dense matrices. +In Eigen's sparse module we chose to expose only the subset of the dense matrix API which can be efficiently implemented. +In the following \em sm denotes a sparse matrix, \em sv a sparse vector, \em dm a dense matrix, and \em dv a dense vector. + +\subsection TutorialSparse_BasicOps Basic operations + +%Sparse expressions support most of the unary and binary coefficient wise operations: +\code +sm1.real() sm1.imag() -sm1 0.5*sm1 +sm1+sm2 sm1-sm2 sm1.cwiseProduct(sm2) +\endcode +However, a strong restriction is that the storage orders must match. For instance, in the following example: +\code +sm4 = sm1 + sm2 + sm3; +\endcode +sm1, sm2, and sm3 must all be row-major or all column major. +On the other hand, there is no restriction on the target matrix sm4. +For instance, this means that for computing \f$ A^T + A \f$, the matrix \f$ A^T \f$ must be evaluated into a temporary matrix of compatible storage order: +\code +SparseMatrix A, B; +B = SparseMatrix(A.transpose()) + A; +\endcode + +Binary coefficient wise operators can also mix sparse and dense expressions: +\code +sm2 = sm1.cwiseProduct(dm1); +dm2 = sm1 + dm1; +\endcode + + +%Sparse expressions also support transposition: +\code +sm1 = sm2.transpose(); +sm1 = sm2.adjoint(); +\endcode +However, there is no transposeInPlace() method. + + +\subsection TutorialSparse_Products Matrix products + +%Eigen supports various kind of sparse matrix products which are summarize below: + - \b sparse-dense: + \code +dv2 = sm1 * dv1; +dm2 = dm1 * sm1.adjoint(); +dm2 = 2. * sm1 * dm1; + \endcode + - \b symmetric \b sparse-dense. The product of a sparse symmetric matrix with a dense matrix (or vector) can also be optimized by specifying the symmetry with selfadjointView(): + \code +dm2 = sm1.selfadjointView<>() * dm1; // if all coefficients of A are stored +dm2 = A.selfadjointView() * dm1; // if only the upper part of A is stored +dm2 = A.selfadjointView() * dm1; // if only the lower part of A is stored + \endcode + - \b sparse-sparse. For sparse-sparse products, two different algorithms are available. The default one is conservative and preserve the explicit zeros that might appear: + \code +sm3 = sm1 * sm2; +sm3 = 4 * sm1.adjoint() * sm2; + \endcode + The second algorithm prunes on the fly the explicit zeros, or the values smaller than a given threshold. It is enabled and controlled through the prune() functions: + \code +sm3 = (sm1 * sm2).prune(); // removes numerical zeros +sm3 = (sm1 * sm2).prune(ref); // removes elements much smaller than ref +sm3 = (sm1 * sm2).prune(ref,epsilon); // removes elements smaller than ref*epsilon + \endcode + + - \b permutations. Finally, permutations can be applied to sparse matrices too: + \code +PermutationMatrix P = ...; +sm2 = P * sm1; +sm2 = sm1 * P.inverse(); +sm2 = sm1.transpose() * P; + \endcode + + +\subsection TutorialSparse_TriangularSelfadjoint Triangular and selfadjoint views + +Just as with dense matrices, the triangularView() function can be used to address a triangular part of the matrix, and perform triangular solves with a dense right hand side: +\code +dm2 = sm1.triangularView(dm1); +dv2 = sm1.transpose().triangularView(dv1); +\endcode + +The selfadjointView() function permits various operations: + - optimized sparse-dense matrix products: + \code +dm2 = sm1.selfadjointView<>() * dm1; // if all coefficients of A are stored +dm2 = A.selfadjointView() * dm1; // if only the upper part of A is stored +dm2 = A.selfadjointView() * dm1; // if only the lower part of A is stored + \endcode + - copy of triangular parts: + \code +sm2 = sm1.selfadjointView(); // makes a full selfadjoint matrix from the upper triangular part +sm2.selfadjointView() = sm1.selfadjointView(); // copies the upper triangular part to the lower triangular part + \endcode + - application of symmetric permutations: + \code +PermutationMatrix P = ...; +sm2 = A.selfadjointView().twistedBy(P); // compute P S P' from the upper triangular part of A, and make it a full matrix +sm2.selfadjointView() = A.selfadjointView().twistedBy(P); // compute P S P' from the lower triangular part of A, and then only compute the lower part + \endcode + +\subsection TutorialSparse_Submat Sub-matrices + +%Sparse matrices does not support yet the addressing of arbitrary sub matrices. Currently, one can only reference a set of contiguous \em inner vectors, i.e., a set of contiguous rows for a row-major matrix, or a set of contiguous columns for a column major matrix: +\code + sm1.innerVector(j); // returns an expression of the j-th column (resp. row) of the matrix if sm1 is col-major (resp. row-major) + sm1.innerVectors(j, nb); // returns an expression of the nb columns (resp. row) starting from the j-th column (resp. row) + // of the matrix if sm1 is col-major (resp. row-major) + sm1.middleRows(j, nb); // for row major matrices only, get a range of nb rows + sm1.middleCols(j, nb); // for column major matrices only, get a range of nb columns +\endcode + +*/ + +} diff --git a/doc/UnalignedArrayAssert.dox b/doc/UnalignedArrayAssert.dox new file mode 100644 index 000000000..8c97d7874 --- /dev/null +++ b/doc/UnalignedArrayAssert.dox @@ -0,0 +1,114 @@ +namespace Eigen { + +/** \eigenManualPage TopicUnalignedArrayAssert Explanation of the assertion on unaligned arrays + +Hello! You are seeing this webpage because your program terminated on an assertion failure like this one: +

+my_program: path/to/eigen/Eigen/src/Core/DenseStorage.h:44:
+Eigen::internal::matrix_array::internal::matrix_array()
+[with T = double, int Size = 2, int MatrixOptions = 2, bool Align = true]:
+Assertion `(reinterpret_cast(array) & 0xf) == 0 && "this assertion
+is explained here: http://eigen.tuxfamily.org/dox/UnalignedArrayAssert.html
+**** READ THIS WEB PAGE !!! ****"' failed.
+
+ +There are 4 known causes for this issue. Please read on to understand them and learn how to fix them. + +\eigenAutoToc + +\section where Where in my own code is the cause of the problem? + +First of all, you need to find out where in your own code this assertion was triggered from. At first glance, the error message doesn't look helpful, as it refers to a file inside Eigen! However, since your program crashed, if you can reproduce the crash, you can get a backtrace using any debugger. For example, if you're using GCC, you can use the GDB debugger as follows: +\code +$ gdb ./my_program # Start GDB on your program +> run # Start running your program +... # Now reproduce the crash! +> bt # Obtain the backtrace +\endcode +Now that you know precisely where in your own code the problem is happening, read on to understand what you need to change. + +\section c1 Cause 1: Structures having Eigen objects as members + +If you have code like this, + +\code +class Foo +{ + //... + Eigen::Vector2d v; + //... +}; +//... +Foo *foo = new Foo; +\endcode + +then you need to read this separate page: \ref TopicStructHavingEigenMembers "Structures Having Eigen Members". + +Note that here, Eigen::Vector2d is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types". + +\section c2 Cause 2: STL Containers + +If you use STL Containers such as std::vector, std::map, ..., with Eigen objects, or with classes containing Eigen objects, like this, + +\code +std::vector my_vector; +struct my_class { ... Eigen::Matrix2f m; ... }; +std::map my_map; +\endcode + +then you need to read this separate page: \ref TopicStlContainers "Using STL Containers with Eigen". + +Note that here, Eigen::Matrix2f is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types" and \ref TopicStructHavingEigenMembers "structures having such Eigen objects as member". + +\section c3 Cause 3: Passing Eigen objects by value + +If some function in your code is getting an Eigen object passed by value, like this, + +\code +void func(Eigen::Vector4d v); +\endcode + +then you need to read this separate page: \ref TopicPassingByValue "Passing Eigen objects by value to functions". + +Note that here, Eigen::Vector4d is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types". + +\section c4 Cause 4: Compiler making a wrong assumption on stack alignment (for instance GCC on Windows) + +This is a must-read for people using GCC on Windows (like MinGW or TDM-GCC). If you have this assertion failure in an innocent function declaring a local variable like this: + +\code +void foo() +{ + Eigen::Quaternionf q; + //... +} +\endcode + +then you need to read this separate page: \ref TopicWrongStackAlignment "Compiler making a wrong assumption on stack alignment". + +Note that here, Eigen::Quaternionf is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types". + +\section explanation General explanation of this assertion + +\ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen objects" must absolutely be created at 16-byte-aligned locations, otherwise SIMD instructions adressing them will crash. + +Eigen normally takes care of these alignment issues for you, by setting an alignment attribute on them and by overloading their "operator new". + +However there are a few corner cases where these alignment settings get overridden: they are the possible causes for this assertion. + +\section getrid I don't care about vectorization, how do I get rid of that stuff? + +Two possibilities: +
    +
  • Define EIGEN_DONT_ALIGN_STATICALLY. That disables all 128-bit static alignment code, while keeping 128-bit heap alignment. This has the effect of + disabling vectorization for fixed-size objects (like Matrix4d) while keeping vectorization of dynamic-size objects + (like MatrixXd). But do note that this breaks ABI compatibility with the default behavior of 128-bit static alignment.
    • +
  • Or define both EIGEN_DONT_VECTORIZE and EIGEN_DISABLE_UNALIGNED_ARRAY_ASSERT. This keeps the + 128-bit alignment code and thus preserves ABI compatibility, but completely disables vectorization.
    • +
+ +For more information, see this FAQ. + +*/ + +} diff --git a/doc/WrongStackAlignment.dox b/doc/WrongStackAlignment.dox new file mode 100644 index 000000000..17d5513a7 --- /dev/null +++ b/doc/WrongStackAlignment.dox @@ -0,0 +1,56 @@ +namespace Eigen { + +/** \eigenManualPage TopicWrongStackAlignment Compiler making a wrong assumption on stack alignment + +

It appears that this was a GCC bug that has been fixed in GCC 4.5. +If you hit this issue, please upgrade to GCC 4.5 and report to us, so we can update this page.

+ +This is an issue that, so far, we met only with GCC on Windows: for instance, MinGW and TDM-GCC. + +By default, in a function like this, + +\code +void foo() +{ + Eigen::Quaternionf q; + //... +} +\endcode + +GCC assumes that the stack is already 16-byte-aligned so that the object \a q will be created at a 16-byte-aligned location. For this reason, it doesn't take any special care to explicitly align the object \a q, as Eigen requires. + +The problem is that, in some particular cases, this assumption can be wrong on Windows, where the stack is only guaranteed to have 4-byte alignment. Indeed, even though GCC takes care of aligning the stack in the main function and does its best to keep it aligned, when a function is called from another thread or from a binary compiled with another compiler, the stack alignment can be corrupted. This results in the object 'q' being created at an unaligned location, making your program crash with the \ref TopicUnalignedArrayAssert "assertion on unaligned arrays". So far we found the three following solutions. + + +\section sec_sol1 Local solution + +A local solution is to mark such a function with this attribute: +\code +__attribute__((force_align_arg_pointer)) void foo() +{ + Eigen::Quaternionf q; + //... +} +\endcode +Read this GCC documentation to understand what this does. Of course this should only be done on GCC on Windows, so for portability you'll have to encapsulate this in a macro which you leave empty on other platforms. The advantage of this solution is that you can finely select which function might have a corrupted stack alignment. Of course on the downside this has to be done for every such function, so you may prefer one of the following two global solutions. + + +\section sec_sol2 Global solutions + +A global solution is to edit your project so that when compiling with GCC on Windows, you pass this option to GCC: +\code +-mincoming-stack-boundary=2 +\endcode +Explanation: this tells GCC that the stack is only required to be aligned to 2^2=4 bytes, so that GCC now knows that it really must take extra care to honor the 16 byte alignment of \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types" when needed. + +Another global solution is to pass this option to gcc: +\code +-mstackrealign +\endcode +which has the same effect than adding the \c force_align_arg_pointer attribute to all functions. + +These global solutions are easy to use, but note that they may slowdown your program because they lead to extra prologue/epilogue instructions for every function. + +*/ + +} -- cgit v1.2.3