diff options
author | 2011-02-10 10:55:22 -0500 | |
---|---|---|
committer | 2011-02-10 10:55:22 -0500 | |
commit | 57b22204db17bafe5a9035a5d9ad8fe323c69c6f (patch) | |
tree | 31209c5a8a6c739c797c7e311abe2ae782a66cd3 /doc | |
parent | 6a5a13e3943dbd1037582a683f554aa80913148c (diff) |
document the eigen2 support stages
Diffstat (limited to 'doc')
-rw-r--r-- | doc/A05_PortingFrom2To3.dox | 19 | ||||
-rw-r--r-- | doc/A10_Eigen2SupportModes.dox | 100 |
2 files changed, 116 insertions, 3 deletions
diff --git a/doc/A05_PortingFrom2To3.dox b/doc/A05_PortingFrom2To3.dox index 152578be8..13839a2a2 100644 --- a/doc/A05_PortingFrom2To3.dox +++ b/doc/A05_PortingFrom2To3.dox @@ -8,6 +8,7 @@ and gives tips to help porting your application from Eigen2 to Eigen3. \b Table \b of \b contents - \ref CompatibilitySupport - \ref Using + - \ref ComplexDot - \ref VectorBlocks - \ref Corners - \ref CoefficientWiseOperations @@ -15,18 +16,20 @@ and gives tips to help porting your application from Eigen2 to Eigen3. - \ref TriangularSolveInPlace - \ref Decompositions - \ref LinearSolvers + - \ref GeometryModule - \ref Transform - \ref LazyVsNoalias - \ref AlignMacros - \ref AlignedMap + - \ref eiPrefix \section CompatibilitySupport Eigen2 compatibility support -In order to ease the switch from Eigen2 to Eigen3, Eigen3 features \ref Eigen2Support "Eigen2 support modes". +In order to ease the switch from Eigen2 to Eigen3, Eigen3 features \ref Eigen2SupportModes "Eigen2 support modes". The 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). -Moreover, we also provided a \b staged \b migration \b path which may be useful to migrate larger projects from Eigen2 to Eigen3. This explained on the \ref Eigen2Support "Eigen2 support modes" page. +A more powerful, \em staged migration path is also provided, which may be useful to migrate larger projects from Eigen2 to Eigen3. This explained in the \ref Eigen2SupportModes "Eigen 2 support modes" page. \section Using The USING_PART_OF_NAMESPACE_EIGEN macro @@ -35,6 +38,12 @@ The USING_PART_OF_NAMESPACE_EIGEN macro has been removed. In Eigen 3, just do: using namespace Eigen; \endcode +\section ComplexDot Dot products over complex numbers + +This is the single trickiest change between Eigen 2 and Eigen 3. It only affects code using \c std::complex numbers as scalar type. + +Eigen 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. + \section VectorBlocks Vector blocks <table class="manual"> @@ -231,6 +240,10 @@ the selfadjointView API allows you to select the \n triangular part to work on</td></tr> </table> +\section GeometryModule Changes in the Geometry module + +The 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. + \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. @@ -277,7 +290,7 @@ New in Eigen3 is the Aligned option. See the documentation of class Map. Use it \code Map<Vector4f, Aligned> myMappedVector(some_aligned_array); \endcode -There also are related convenience static methods: +There also are related convenience static methods, which actually are the preferred way as they take care of such things as constness: \code result = Vector4f::MapAligned(some_aligned_array); \endcode diff --git a/doc/A10_Eigen2SupportModes.dox b/doc/A10_Eigen2SupportModes.dox new file mode 100644 index 000000000..c9088fac9 --- /dev/null +++ b/doc/A10_Eigen2SupportModes.dox @@ -0,0 +1,100 @@ +namespace Eigen { + +/** \page Eigen2SupportModes Eigen 2 support modes + +This page documents the Eigen2 support modes, a powerful tool to help migrating your project from Eigen 2 to Eigen 3. +Also don't miss our page on \ref Eigen2ToEigen3 "API changes" between Eigen 2 and Eigen 3. + +\b Table \b of \b contents + - \ref EIGEN2_SUPPORT_Macro + - \ref StagedMigrationPathOverview + - \ref Stage10 + - \ref Stage20 + - \ref Stage30 + - \ref Stage40 + - \ref FinallyDropAllEigen2Support + - \ref ABICompatibility + +\section EIGEN2_SUPPORT_Macro The quick way: define EIGEN2_SUPPORT + +By defining EIGEN2_SUPPORT before including any Eigen 3 header, you get back a large part of the Eigen 2 API, while keeping the Eigen 3 API and ABI unchanged. + +This defaults to the \ref Stage30 "stage 30" described below. + +The rest of this page describes an optional, more powerful \em staged migration path. + +\section StagedMigrationPathOverview Overview of the staged migration path + +The primary reason why EIGEN2_SUPPORT alone may not be enough to migrate a large project from Eigen 2 to Eigen 3 is that some of the Eigen 2 API is inherently incompatible with the Eigen 3 API. This happens when the same identifier is used in Eigen 2 and in Eigen 3 with different meanings. To help migrate projects that rely on such API, we provide a staged migration path allowing to perform the migration \em incrementally. + +It goes as follows: +\li Step 0: start with a project using Eigen 2. +\li Step 1: build your project against Eigen 3 with \ref Stage10 "Eigen 2 support stage 10". This mode enables maximum compatibility with the Eigen 2 API, with just a few exceptions. +\li Step 2: build your project against Eigen 3 with \ref Stage10 "Eigen 2 support stage 20". This mode forces you to add eigen2_ prefixes to the Eigen2 identifiers that conflict with Eigen 3 API. +\li Step 3: build your project against Eigen 3 with \ref Stage10 "Eigen 2 support stage 30". This mode enables the full Eigen 3 API. +\li Step 4: build your project against Eigen 3 with \ref Stage10 "Eigen 2 support stage 40". This mode enables the full Eigen 3 strictness on matters, such as const-correctness, where Eigen 2 was looser. +\li Step 5: build your project against Eigen 3 without any Eigen 2 support mode. + +\section Stage10 Stage 10: define EIGEN2_SUPPORT_STAGE10_FULL_EIGEN2_API + +Enable this mode by defining the EIGEN2_SUPPORT_STAGE10_FULL_EIGEN2_API preprocessor macro before including any Eigen 3 header. + +This mode maximizes support for the Eigen 2 API. As a result, it does not offer the full Eigen 3 API. Also, it doesn't offer quite 100% of the Eigen 2 API. + +The part of the Eigen 3 API that is not present in this mode, is Eigen 3's Geometry module. Indeed, this mode completely replaces it by a copy of Eigen 2's Geometry module. + +The parts of the API that are still not 100% Eigen 2 compatible in this mode are: +\li Dot products over complex numbers. Eigen 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. +\li The Sparse module. +\li Certain fine details of linear algebraic decompositions. For example, LDLT decomposition is now pivoting in Eigen 3 whereas it wasn't in Eigen 2, so code that was relying on its underlying matrix structure will break. + +\section Stage20 Stage 20: define EIGEN2_SUPPORT_STAGE20_RESOLVE_API_CONFLICTS + +Enable this mode by defining the EIGEN2_SUPPORT_STAGE10_FULL_EIGEN2_API preprocessor macro before including any Eigen 3 header. + +This mode removes the Eigen 2 API that is directly conflicting with Eigen 3 API. Instead, these bits of Eigen 2 API remain available with eigen2_ prefixes. The main examples of such API are: +\li the whole Geometry module. For example, replace \c Quaternion by \c eigen2_Quaternion, replace \c Transform3f by \c eigen2_Transform3f, etc. +\li the lu() method to obtain a LU decomposition. Replace by eigen2_lu(). + +There is also one more eigen2_-prefixed identifier that you should know about, even though its use is not checked at compile time by this mode: the dot() method. As was discussed above, over complex numbers, its meaning is different between Eigen 2 and Eigen 3. You can use eigen2_dot() to get the Eigen 2 behavior. + +\section Stage30 Stage 30: define EIGEN2_SUPPORT_STAGE30_FULL_EIGEN3_API + +Enable this mode by defining the EIGEN2_SUPPORT_STAGE30_FULL_EIGEN3_API preprocessor macro before including any Eigen 3 header. Also, this mode is what you get by default when you just define EIGEN2_SUPPORT. + +This mode gives you the full unaltered Eigen 3 API, while still keeping as much support as possible for the Eigen 2 API. + +The eigen2_-prefixed identifiers are still available, but at this stage you should now replace them by Eigen 3 identifiers. + +\section Stage40 Stage 40: define EIGEN2_SUPPORT_STAGE40_FULL_EIGEN3_STRICTNESS + +Enable this mode by defining the EIGEN2_SUPPORT_STAGE30_FULL_EIGEN3_API preprocessor macro before including any Eigen 3 header. + +This mode tightens the last bits of strictness, especially const-correctness, that had to be loosened to support what Eigen 2 allowed. For example, this code compiled in Eigen 2: +\code +const float array[4]; +x = Map<Vector4f>(array); +\endcode +That allowed to circumvent constness. This is no longer allowed in Eigen 3. If you have to map const data in Eigen 3, map it as a const-qualified type. However, rather than explictly constructing Map objects, we strongly encourage you to use the static Map methods instead, as they take care of all of this for you: +\code +const float array[4]; +x = Vector4f::Map(array); +\endcode +This lets Eigen do the right thing for you and works equally well in Eigen 2 and in Eigen 3. + +\section FinallyDropAllEigen2Support Finally drop all Eigen 2 support + +Stage 40 is the first where it's "comfortable" to stay for a little longer period, since it preserves 100% Eigen 3 compatibility. However, we still encourage you to complete your migration as quickly as possible. While we do run the Eigen 2 test suite against Eigen 3's stage 10 support mode, we can't guarantee the same level of support and quality assurance for Eigen 2 support as we do for Eigen 3 itself, especially not in the long term. + +\section ABICompatibility What about ABI compatibility? + +It goes as follows: +\li Stage 10 already is ABI compatible with Eigen 3 for the basic (Matrix, Array, SparseMatrix...) types. However, since this stage uses a copy of Eigen 2's Geometry module instead of Eigen 3's own Geometry module, the ABI in the Geometry module is not Eigen 3 compatible. +\li Stage 20 removes the Eigen 3-incompatible Eigen 2 Geometry module (it remains available with eigen2_ prefix). So at this stage, all the identifiers that exist in Eigen 3 have the Eigen 3 ABI (and API). +\li Stage 30 introduces the remaining Eigen 3 identifiers. So at this stage, you have the full Eigen 3 ABI. +\li Stage 40 is no different than Stage 30 in these matters. + + +*/ + +} |