namespace Eigen { /** \page Eigen2ToEigen3 Porting from Eigen2 to Eigen3 This page lists the most important API changes between Eigen2 and Eigen3, and gives tips to help porting your application from Eigen2 to Eigen3. \b Table \b of \b contents - \ref CompatibilitySupport - \ref Using - \ref VectorBlocks - \ref Corners - \ref CoefficientWiseOperations - \ref PartAndExtract - \ref TriangularSolveInPlace - \ref Decompositions - \ref LinearSolvers - \ref Transform - \ref LazyVsNoalias - \ref AlignMacros - \ref AlignedMap \section CompatibilitySupport Eigen2 compatibility support In order to ease the switch from Eigen2 to Eigen3, Eigen3 features a compatibility mode which can be enabled by defining the EIGEN2_SUPPORT preprocessor token \b before including any Eigen header (typically it should be set in your project options). \section Using The USING_PART_OF_NAMESPACE_EIGEN macro The USING_PART_OF_NAMESPACE_EIGEN macro has been removed. In Eigen 3, just do: \code using namespace Eigen; \endcode \section VectorBlocks Vector blocks
Eigen 2Eigen 3
\code vector.start(length) vector.start() vector.end(length) vector.end() \endcode\code vector.head(length) vector.head() vector.tail(length) vector.tail() \endcode
\section Corners Matrix Corners
Eigen 2Eigen 3
\code matrix.corner(TopLeft,r,c) matrix.corner(TopRight,r,c) matrix.corner(BottomLeft,r,c) matrix.corner(BottomRight,r,c) matrix.corner(TopLeft) matrix.corner(TopRight) matrix.corner(BottomLeft) matrix.corner(BottomRight) \endcode\code matrix.topLeftCorner(r,c) matrix.topRightCorner(r,c) matrix.bottomLeftCorner(r,c) matrix.bottomRightCorner(r,c) matrix.topLeftCorner() matrix.topRightCorner() matrix.bottomLeftCorner() matrix.bottomRightCorner() \endcode
Notice that Eigen3 also provides these new convenience methods: topRows(), bottomRows(), leftCols(), rightCols(). See in class DenseBase. \section CoefficientWiseOperations Coefficient wise operations In Eigen2, coefficient wise operations which have no proper mathematical definition (as a coefficient wise product) were achieved using the .cwise() prefix, e.g.: \code a.cwise() * b \endcode In Eigen3 this .cwise() prefix has been superseded by a new kind of matrix type called Array for which all operations are performed coefficient wise. You can easily view a matrix as an array and vice versa using the MatrixBase::array() and ArrayBase::matrix() functions respectively. Here is an example: \code Vector4f a, b, c; c = a.array() * b.array(); \endcode Note that the .array() function is not at all a synonym of the deprecated .cwise() prefix. While the .cwise() prefix changed the behavior of the following operator, the array() function performs a permanent conversion to the array world. Therefore, for binary operations such as the coefficient wise product, both sides must be converted to an \em array as in the above example. On the other hand, when you concatenate multiple coefficient wise operations you only have to do the conversion once, e.g.: \code Vector4f a, b, c; c = a.array().abs().pow(3) * b.array().abs().sin(); \endcode With Eigen2 you would have written: \code c = (a.cwise().abs().cwise().pow(3)).cwise() * (b.cwise().abs().cwise().sin()); \endcode \section PartAndExtract Triangular and self-adjoint matrices In Eigen 2 you had to play with the part, extract, and marked functions to deal with triangular and selfadjoint matrices. In Eigen 3, all these functions have been removed in favor of the concept of \em views:
Eigen 2Eigen 3
\code A.part(); A.part(); \endcode \code A.triangularView() A.triangularView()\endcode
\code A.extract(); A.extract();\endcode \code A.triangularView() A.triangularView()\endcode
\code A.marked(); A.marked();\endcode \code A.triangularView() A.triangularView()\endcode
\code A.part(); A.extract();\endcode \code A.selfadjointView() A.selfadjointView()\endcode
\code UpperTriangular LowerTriangular UnitUpperTriangular UnitLowerTriangular StrictlyUpperTriangular StrictlyLowerTriangular \endcode\code Upper Lower UnitUpper UnitLower StrictlyUpper StrictlyLower \endcode
\sa class TriangularView, class SelfAdjointView \section TriangularSolveInPlace Triangular in-place solving
Eigen 2Eigen 3
\code A.triangularSolveInPlace(Y);\endcode\code A.triangularView().solveInPlace(Y);\endcode
\section Decompositions Matrix decompositions Some of Eigen 2's matrix decompositions have been renamed in Eigen 3, while some others have been removed and are replaced by other decompositions in Eigen 3.
Eigen 2 Eigen 3 Notes
LU FullPivLU See also the new PartialPivLU, it's much faster
QR HouseholderQR See also the new ColPivHouseholderQR, it's more reliable
SVD JacobiSVD We currently don't have a bidiagonalizing SVD; of course this is planned.
EigenSolver and friends \code #include \endcode Moved to separate module
\section LinearSolvers Linear solvers
Eigen 2Eigen 3Notes
\code A.lu();\endcode \code A.fullPivLu();\endcode Now A.lu() returns a PartialPivLU
\code A.lu().solve(B,&X);\endcode \code X = A.lu().solve(B); X = A.fullPivLu().solve(B);\endcode The returned by value is fully optimized
\code A.llt().solve(B,&X);\endcode \code X = A.llt().solve(B); X = A.selfadjointView.llt().solve(B); X = A.selfadjointView.llt().solve(B);\endcode The returned by value is fully optimized and \n the selfadjointView API allows you to select the \n triangular part to work on (default is lower part)
\code A.llt().solveInPlace(B);\endcode \code B = A.llt().solve(B); B = A.selfadjointView.llt().solve(B); B = A.selfadjointView.llt().solve(B);\endcode In place solving
\code A.ldlt().solve(B,&X);\endcode \code X = A.ldlt().solve(B); X = A.selfadjointView.ldlt().solve(B); X = A.selfadjointView.ldlt().solve(B);\endcode The returned by value is fully optimized and \n the selfadjointView API allows you to select the \n triangular part to work on
\section Transform The Transform class In Eigen 2, the Transform class didn't really know whether it was a projective or affine transformation. In Eigen 3, it takes a new \a Mode template parameter, which indicates whether it's \a Projective or \a Affine transform. The default is \a Projective. The Transform3f (etc) typedefs are no more. In Eigen 3, the Transform typedefs explicitly refer to the \a Projective and \a Affine modes:
Eigen 2Eigen 3Notes
Transform3f Affine3f or Projective3f Of course 3f is just an example here
\section LazyVsNoalias Lazy evaluation and noalias In Eigen all operations are performed in a lazy fashion except the matrix products which are always evaluated into a temporary by default. In Eigen2, lazy evaluation could be enforced by tagging a product using the .lazy() function. However, in complex expressions it was not easy to determine where to put the lazy() function. In Eigen3, the lazy() feature has been superseded by the MatrixBase::noalias() function which can be used on the left hand side of an assignment when no aliasing can occur. Here is an example: \code MatrixXf a, b, c; ... c.noalias() += 2 * a.transpose() * b; \endcode However, the noalias mechanism does not cover all the features of the old .lazy(). Indeed, in some extremely rare cases, it might be useful to explicit request for a lay product, i.e., for a product which will be evaluated one coefficient at once, on request, just like any other expressions. To this end you can use the MatrixBase::lazyProduct() function, however we strongly discourage you to use it unless you are sure of what you are doing, i.e., you have rigourosly measured a speed improvement. \section AlignMacros Alignment-related macros The EIGEN_ALIGN_128 macro has been renamed to EIGEN_ALIGN16. Don't be surprised, it's just that we switched to counting in bytes ;-) The EIGEN_DONT_ALIGN option still exists in Eigen 3, but it has a new cousin: EIGEN_DONT_ALIGN_STATICALLY. It allows to get rid of all static alignment issues while keeping alignment of dynamic-size heap-allocated arrays, thus keeping vectorization for dynamic-size objects. \section AlignedMap Aligned Map objects A common issue with Eigen 2 was that when mapping an array with Map, there was no way to tell Eigen that your array was aligned. There was a ForceAligned option but it didn't mean that; it was just confusing and has been removed. New in Eigen3 is the Aligned option. See the documentation of class Map. Use it like this: \code Map myMappedVector(some_aligned_array); \endcode There also are related convenience static methods: \code result = Vector4f::MapAligned(some_aligned_array); \endcode \section eiPrefix Internal ei_ prefix In Eigen2, global internal functions and structures were prefixed by \c ei_. In Eigen3, they all have been moved into the more explicit \c internal namespace. So, e.g., \c ei_sqrt(x) now becomes \c internal::sqrt(x). Of course it is not recommended to rely on Eigen's internal features. */ }