1namespace Eigen { 2 3/** \page Eigen2ToEigen3 Porting from Eigen2 to Eigen3 4 5This page lists the most important API changes between Eigen2 and Eigen3, 6and gives tips to help porting your application from Eigen2 to Eigen3. 7 8\b Table \b of \b contents 9 - \ref CompatibilitySupport 10 - \ref Using 11 - \ref ComplexDot 12 - \ref VectorBlocks 13 - \ref Corners 14 - \ref CoefficientWiseOperations 15 - \ref PartAndExtract 16 - \ref TriangularSolveInPlace 17 - \ref Decompositions 18 - \ref LinearSolvers 19 - \ref GeometryModule 20 - \ref Transform 21 - \ref LazyVsNoalias 22 - \ref AlignMacros 23 - \ref AlignedMap 24 - \ref StdContainers 25 - \ref eiPrefix 26 27\section CompatibilitySupport Eigen2 compatibility support 28 29In order to ease the switch from Eigen2 to Eigen3, Eigen3 features \ref Eigen2SupportModes "Eigen2 support modes". 30 31The quick way to enable this is to define the \c EIGEN2_SUPPORT preprocessor token \b before including any Eigen header (typically it should be set in your project options). 32 33A more powerful, \em staged migration path is also provided, which may be useful to migrate larger projects from Eigen2 to Eigen3. This is explained in the \ref Eigen2SupportModes "Eigen 2 support modes" page. 34 35\section Using The USING_PART_OF_NAMESPACE_EIGEN macro 36 37The USING_PART_OF_NAMESPACE_EIGEN macro has been removed. In Eigen 3, just do: 38\code 39using namespace Eigen; 40\endcode 41 42\section ComplexDot Dot products over complex numbers 43 44This is the single trickiest change between Eigen 2 and Eigen 3. It only affects code using \c std::complex numbers as scalar type. 45 46Eigen 2's dot product was linear in the first variable. Eigen 3's dot product is linear in the second variable. In other words, the Eigen 2 code \code x.dot(y) \endcode is equivalent to the Eigen 3 code \code y.dot(x) \endcode In yet other words, dot products are complex-conjugated in Eigen 3 compared to Eigen 2. The switch to the new convention was commanded by common usage, especially with the notation \f$ x^Ty \f$ for dot products of column-vectors. 47 48\section VectorBlocks Vector blocks 49 50<table class="manual"> 51<tr><th>Eigen 2</th><th>Eigen 3</th></th> 52<tr><td>\code 53vector.start(length) 54vector.start<length>() 55vector.end(length) 56vector.end<length>() 57\endcode</td><td>\code 58vector.head(length) 59vector.head<length>() 60vector.tail(length) 61vector.tail<length>() 62\endcode</td></tr> 63</table> 64 65 66\section Corners Matrix Corners 67 68<table class="manual"> 69<tr><th>Eigen 2</th><th>Eigen 3</th></th> 70<tr><td>\code 71matrix.corner(TopLeft,r,c) 72matrix.corner(TopRight,r,c) 73matrix.corner(BottomLeft,r,c) 74matrix.corner(BottomRight,r,c) 75matrix.corner<r,c>(TopLeft) 76matrix.corner<r,c>(TopRight) 77matrix.corner<r,c>(BottomLeft) 78matrix.corner<r,c>(BottomRight) 79\endcode</td><td>\code 80matrix.topLeftCorner(r,c) 81matrix.topRightCorner(r,c) 82matrix.bottomLeftCorner(r,c) 83matrix.bottomRightCorner(r,c) 84matrix.topLeftCorner<r,c>() 85matrix.topRightCorner<r,c>() 86matrix.bottomLeftCorner<r,c>() 87matrix.bottomRightCorner<r,c>() 88\endcode</td> 89</tr> 90</table> 91 92Notice that Eigen3 also provides these new convenience methods: topRows(), bottomRows(), leftCols(), rightCols(). See in class DenseBase. 93 94\section CoefficientWiseOperations Coefficient wise operations 95 96In Eigen2, coefficient wise operations which have no proper mathematical definition (as a coefficient wise product) 97were achieved using the .cwise() prefix, e.g.: 98\code a.cwise() * b \endcode 99In Eigen3 this .cwise() prefix has been superseded by a new kind of matrix type called 100Array for which all operations are performed coefficient wise. You can easily view a matrix as an array and vice versa using 101the MatrixBase::array() and ArrayBase::matrix() functions respectively. Here is an example: 102\code 103Vector4f a, b, c; 104c = a.array() * b.array(); 105\endcode 106Note that the .array() function is not at all a synonym of the deprecated .cwise() prefix. 107While the .cwise() prefix changed the behavior of the following operator, the array() function performs 108a permanent conversion to the array world. Therefore, for binary operations such as the coefficient wise product, 109both sides must be converted to an \em array as in the above example. On the other hand, when you 110concatenate multiple coefficient wise operations you only have to do the conversion once, e.g.: 111\code 112Vector4f a, b, c; 113c = a.array().abs().pow(3) * b.array().abs().sin(); 114\endcode 115With Eigen2 you would have written: 116\code 117c = (a.cwise().abs().cwise().pow(3)).cwise() * (b.cwise().abs().cwise().sin()); 118\endcode 119 120\section PartAndExtract Triangular and self-adjoint matrices 121 122In 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: 123 124<table class="manual"> 125<tr><th>Eigen 2</th><th>Eigen 3</th></tr> 126<tr><td>\code 127A.part<UpperTriangular>(); 128A.part<StrictlyLowerTriangular>(); \endcode</td> 129<td>\code 130A.triangularView<Upper>() 131A.triangularView<StrictlyLower>()\endcode</td></tr> 132<tr><td>\code 133A.extract<UpperTriangular>(); 134A.extract<StrictlyLowerTriangular>();\endcode</td> 135<td>\code 136A.triangularView<Upper>() 137A.triangularView<StrictlyLower>()\endcode</td></tr> 138<tr><td>\code 139A.marked<UpperTriangular>(); 140A.marked<StrictlyLowerTriangular>();\endcode</td> 141<td>\code 142A.triangularView<Upper>() 143A.triangularView<StrictlyLower>()\endcode</td></tr> 144<tr><td colspan="2"></td></tr> 145<tr><td>\code 146A.part<SelfAdfjoint|UpperTriangular>(); 147A.extract<SelfAdfjoint|LowerTriangular>();\endcode</td> 148<td>\code 149A.selfadjointView<Upper>() 150A.selfadjointView<Lower>()\endcode</td></tr> 151<tr><td colspan="2"></td></tr> 152<tr><td>\code 153UpperTriangular 154LowerTriangular 155UnitUpperTriangular 156UnitLowerTriangular 157StrictlyUpperTriangular 158StrictlyLowerTriangular 159\endcode</td><td>\code 160Upper 161Lower 162UnitUpper 163UnitLower 164StrictlyUpper 165StrictlyLower 166\endcode</td> 167</tr> 168</table> 169 170\sa class TriangularView, class SelfAdjointView 171 172\section TriangularSolveInPlace Triangular in-place solving 173 174<table class="manual"> 175<tr><th>Eigen 2</th><th>Eigen 3</th></tr> 176<tr><td>\code A.triangularSolveInPlace<XxxTriangular>(Y);\endcode</td><td>\code A.triangularView<Xxx>().solveInPlace(Y);\endcode</td></tr> 177</table> 178 179 180\section Decompositions Matrix decompositions 181 182Some 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. 183 184<table class="manual"> 185 <tr> 186 <th>Eigen 2</th> 187 <th>Eigen 3</th> 188 <th>Notes</th> 189 </tr> 190 <tr> 191 <td>LU</td> 192 <td>FullPivLU</td> 193 <td class="alt">See also the new PartialPivLU, it's much faster</td> 194 </tr> 195 <tr> 196 <td>QR</td> 197 <td>HouseholderQR</td> 198 <td class="alt">See also the new ColPivHouseholderQR, it's more reliable</td> 199 </tr> 200 <tr> 201 <td>SVD</td> 202 <td>JacobiSVD</td> 203 <td class="alt">We currently don't have a bidiagonalizing SVD; of course this is planned.</td> 204 </tr> 205 <tr> 206 <td>EigenSolver and friends</td> 207 <td>\code #include<Eigen/Eigenvalues> \endcode </td> 208 <td class="alt">Moved to separate module</td> 209 </tr> 210</table> 211 212\section LinearSolvers Linear solvers 213 214<table class="manual"> 215<tr><th>Eigen 2</th><th>Eigen 3</th><th>Notes</th></tr> 216<tr><td>\code A.lu();\endcode</td> 217<td>\code A.fullPivLu();\endcode</td> 218<td class="alt">Now A.lu() returns a PartialPivLU</td></tr> 219<tr><td>\code A.lu().solve(B,&X);\endcode</td> 220<td>\code X = A.lu().solve(B); 221 X = A.fullPivLu().solve(B);\endcode</td> 222<td class="alt">The returned by value is fully optimized</td></tr> 223<tr><td>\code A.llt().solve(B,&X);\endcode</td> 224<td>\code X = A.llt().solve(B); 225 X = A.selfadjointView<Lower>.llt().solve(B); 226 X = A.selfadjointView<Upper>.llt().solve(B);\endcode</td> 227<td class="alt">The returned by value is fully optimized and \n 228the selfadjointView API allows you to select the \n 229triangular part to work on (default is lower part)</td></tr> 230<tr><td>\code A.llt().solveInPlace(B);\endcode</td> 231<td>\code B = A.llt().solve(B); 232 B = A.selfadjointView<Lower>.llt().solve(B); 233 B = A.selfadjointView<Upper>.llt().solve(B);\endcode</td> 234<td class="alt">In place solving</td></tr> 235<tr><td>\code A.ldlt().solve(B,&X);\endcode</td> 236<td>\code X = A.ldlt().solve(B); 237 X = A.selfadjointView<Lower>.ldlt().solve(B); 238 X = A.selfadjointView<Upper>.ldlt().solve(B);\endcode</td> 239<td class="alt">The returned by value is fully optimized and \n 240the selfadjointView API allows you to select the \n 241triangular part to work on</td></tr> 242</table> 243 244\section GeometryModule Changes in the Geometry module 245 246The Geometry module is the one that changed the most. If you rely heavily on it, it's probably a good idea to use the \ref Eigen2SupportModes "Eigen 2 support modes" to perform your migration. 247 248\section Transform The Transform class 249 250In 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. There is no default value. 251 252The Transform3f (etc) typedefs are no more. In Eigen 3, the Transform typedefs explicitly refer to the \a Projective and \a Affine modes: 253 254<table class="manual"> 255<tr><th>Eigen 2</th><th>Eigen 3</th><th>Notes</th></tr> 256<tr> 257 <td> Transform3f </td> 258 <td> Affine3f or Projective3f </td> 259 <td> Of course 3f is just an example here </td> 260</tr> 261</table> 262 263 264\section LazyVsNoalias Lazy evaluation and noalias 265 266In Eigen all operations are performed in a lazy fashion except the matrix products which are always evaluated into a temporary by default. 267In Eigen2, lazy evaluation could be enforced by tagging a product using the .lazy() function. However, in complex expressions it was not 268easy to determine where to put the lazy() function. In Eigen3, the lazy() feature has been superseded by the MatrixBase::noalias() function 269which can be used on the left hand side of an assignment when no aliasing can occur. Here is an example: 270\code 271MatrixXf a, b, c; 272... 273c.noalias() += 2 * a.transpose() * b; 274\endcode 275However, the noalias mechanism does not cover all the features of the old .lazy(). Indeed, in some extremely rare cases, 276it 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, 277just like any other expressions. To this end you can use the MatrixBase::lazyProduct() function, however we strongly discourage you to 278use it unless you are sure of what you are doing, i.e., you have rigourosly measured a speed improvement. 279 280\section AlignMacros Alignment-related macros 281 282The EIGEN_ALIGN_128 macro has been renamed to EIGEN_ALIGN16. Don't be surprised, it's just that we switched to counting in bytes ;-) 283 284The 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. 285 286\section AlignedMap Aligned Map objects 287 288A 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. 289 290New in Eigen3 is the #Aligned option. See the documentation of class Map. Use it like this: 291\code 292Map<Vector4f, Aligned> myMappedVector(some_aligned_array); 293\endcode 294There also are related convenience static methods, which actually are the preferred way as they take care of such things as constness: 295\code 296result = Vector4f::MapAligned(some_aligned_array); 297\endcode 298 299\section StdContainers STL Containers 300 301In Eigen2, #include<Eigen/StdVector> tweaked std::vector to automatically align elements. The problem was that that was quite invasive. In Eigen3, we only override standard behavior if you use Eigen::aligned_allocator<T> as your allocator type. So for example, if you use std::vector<Matrix4f>, you need to do the following change (note that aligned_allocator is under namespace Eigen): 302 303<table class="manual"> 304<tr><th>Eigen 2</th><th>Eigen 3</th></tr> 305<tr> 306 <td> \code std::vector<Matrix4f> \endcode </td> 307 <td> \code std::vector<Matrix4f, aligned_allocator<Matrix4f> > \endcode </td> 308</tr> 309</table> 310 311\section eiPrefix Internal ei_ prefix 312 313In 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. 314 315 316 317*/ 318 319} 320