introduce the 3 stages of eigen2 support, writing to the mailing list about that in Eigen2 to Eigen3 Migration Path thread

Eigen/Array

@@ -1,10 +1,11 @@
 #ifndef EIGEN_ARRAY_MODULE_H
 #define EIGEN_ARRAY_MODULE_H
 
+// include Core first to handle Eigen2 support macros
+#include "Core"
+
 #ifndef EIGEN2_SUPPORT
   #error The Eigen/Array header does no longer exist in Eigen3. All that functionality has moved to Eigen/Core.
 #endif
 
-#include "Core"
-
 #endif // EIGEN_ARRAY_MODULE_H

Eigen/Core

@@ -221,6 +221,28 @@ inline static const char *SimdInstructionSetsInUse(void) {
 #endif
 }
 
+#define STAGE1_FULL_EIGEN2_API       1
+#define STAGE2_RESOLVE_API_CONFLICTS 2
+#define STAGE3_FULL_EIGEN3_API       3
+#define STAGE9_NO_EIGEN2_SUPPORT     9
+
+#ifdef EIGEN2_SUPPORT_STAGE1_FULL_EIGEN2_API
+  #define EIGEN2_SUPPORT
+  #define EIGEN2_SUPPORT_STAGE STAGE1_FULL_EIGEN2_API
+#elif defined EIGEN2_SUPPORT_STAGE2_RESOLVE_API_CONFLICTS
+  #define EIGEN2_SUPPORT
+  #define EIGEN2_SUPPORT_STAGE STAGE2_RESOLVE_API_CONFLICTS
+#elif defined EIGEN2_SUPPORT_STAGE3_FULL_EIGEN3_API
+  #define EIGEN2_SUPPORT
+  #define EIGEN2_SUPPORT_STAGE STAGE3_FULL_EIGEN3_API
+#elif defined EIGEN2_SUPPORT
+  // default to stage 3, that's what it's always meant
+  #define EIGEN2_SUPPORT_STAGE3_FULL_EIGEN3_API
+  #define EIGEN2_SUPPORT_STAGE STAGE3_FULL_EIGEN3_API
+#else
+  #define EIGEN2_SUPPORT_STAGE STAGE9_NO_EIGEN2_SUPPORT
+#endif
+
 #ifdef EIGEN2_SUPPORT
 #undef minor
 #endif

Eigen/src/Core/Dot.h

@@ -81,9 +81,43 @@ MatrixBase<Derived>::dot(const MatrixBase<OtherDerived>& other) const
 
   eigen_assert(size() == other.size());
 
+#if EIGEN2_SUPPORT_STAGE >= STAGE3_FULL_EIGEN3_API
   return internal::dot_nocheck<Derived,OtherDerived>::run(*this, other);
+#else
+  return internal::dot_nocheck<OtherDerived,Derived>::run(other,*this);
+#endif
 }
 
+#if EIGEN2_SUPPORT_STAGE <= STAGE3_FULL_EIGEN3_API
+/** \returns the dot product of *this with other, with the Eigen2 convention that the dot product is linear in the first variable
+  * (conjugating the second variable). Of course this only makes a difference in the complex case.
+  *
+  * This method is only available in EIGEN2_SUPPORT mode. With EIGEN2_SUPPORT_STAGE1_FULL_EIGEN2_API and
+  * EIGEN2_SUPPORT_STAGE2_RESOLVE_API_CONFLICTS, the dot() method itself uses it. With EIGEN2_SUPPORT_STAGE3_FULL_EIGEN3_API,
+  * the dot() method no longer uses it, but it's still available.
+  *
+  * \only_for_vectors
+  *
+  * \sa dot()
+  */
+template<typename Derived>
+template<typename OtherDerived>
+typename internal::traits<Derived>::Scalar
+MatrixBase<Derived>::eigen2_dot(const MatrixBase<OtherDerived>& other) const
+{
+  EIGEN_STATIC_ASSERT_VECTOR_ONLY(Derived)
+  EIGEN_STATIC_ASSERT_VECTOR_ONLY(OtherDerived)
+  EIGEN_STATIC_ASSERT_SAME_VECTOR_SIZE(Derived,OtherDerived)
+  EIGEN_STATIC_ASSERT((internal::is_same<Scalar, typename OtherDerived::Scalar>::value),
+    YOU_MIXED_DIFFERENT_NUMERIC_TYPES__YOU_NEED_TO_USE_THE_CAST_METHOD_OF_MATRIXBASE_TO_CAST_NUMERIC_TYPES_EXPLICITLY)
+
+  eigen_assert(size() == other.size());
+
+  return internal::dot_nocheck<OtherDerived,Derived>::run(other,*this);
+}
+#endif
+
+
 //---------- implementation of L2 norm and related functions ----------
 
 /** \returns the squared \em l2 norm of *this, i.e., for vectors, the dot product of *this with itself.

Eigen/src/Core/Functors.h

@@ -87,22 +87,15 @@ struct functor_traits<scalar_product_op<LhsScalar,RhsScalar> > {
 template<typename Scalar> struct scalar_conj_product_op {
 
   enum {
-    Conj = NumTraits<Scalar>::IsComplex,
-    #ifdef EIGEN2_SUPPORT // in Eigen2, dot product is linear in the first variable
-      LhsConj = false,
-      RhsConj = Conj
-    #else // in Eigen3, dot product is linear in the second variable
-      LhsConj = Conj,
-      RhsConj = false
-    #endif
+    Conj = NumTraits<Scalar>::IsComplex
   };
   
   EIGEN_EMPTY_STRUCT_CTOR(scalar_conj_product_op)
   EIGEN_STRONG_INLINE const Scalar operator() (const Scalar& a, const Scalar& b) const
-  { return conj_helper<Scalar,Scalar,LhsConj,RhsConj>().pmul(a,b); }
+  { return conj_helper<Scalar,Scalar,Conj,false>().pmul(a,b); }
   template<typename Packet>
   EIGEN_STRONG_INLINE const Packet packetOp(const Packet& a, const Packet& b) const
-  { return conj_helper<Packet,Packet,LhsConj,RhsConj>().pmul(a,b); }
+  { return conj_helper<Packet,Packet,Conj,false>().pmul(a,b); }
 };
 template<typename Scalar>
 struct functor_traits<scalar_conj_product_op<Scalar> > {

Eigen/src/Core/MatrixBase.h

@@ -201,7 +201,19 @@ template<typename Derived> class MatrixBase
     operator*(const DiagonalBase<DiagonalDerived> &diagonal) const;
 
     template<typename OtherDerived>
+    #if EIGEN2_SUPPORT_STAGE == STAGE2_RESOLVE_API_CONFLICTS
+    EIGEN_DEPRECATED
+    #endif
     Scalar dot(const MatrixBase<OtherDerived>& other) const;
+    
+    #if EIGEN2_SUPPORT_STAGE <= STAGE3_FULL_EIGEN3_API
+      template<typename OtherDerived>
+      #if EIGEN2_SUPPORT_STAGE >= STAGE3_FULL_EIGEN3_API
+      EIGEN_DEPRECATED
+      #endif
+      Scalar eigen2_dot(const MatrixBase<OtherDerived>& other) const;
+    #endif
+    
     RealScalar squaredNorm() const;
     RealScalar norm() const;
     RealScalar stableNorm() const;

test/eigen2/CMakeLists.txt

@@ -2,7 +2,7 @@ add_custom_target(buildtests_eigen2)
 add_custom_target(check_eigen2 COMMAND "ctest")
 add_dependencies(check_eigen2 buildtests_eigen2)
 
-add_definitions("-DEIGEN2_SUPPORT")
+add_definitions("-DEIGEN2_SUPPORT_STAGE1_FULL_EIGEN2_API")
 
 # Macro to add a test
 #