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