started a page on the porting from Eigen2 to 3, updated a bit the tutorial

4 files changed, 143 insertions, 58 deletions

diff --git a/doc/A05_PortingFrom2To3.dox b/doc/A05_PortingFrom2To3.dox
new file mode 100644
index 000000000..4425cc0e0
--- /dev/null
+++ b/doc/A05_PortingFrom2To3.dox
@@ -0,0 +1,73 @@
+namespace Eigen {
+
+/** \page Eigen2ToEigen3 Porting from Eigen2 to Eigen3
+
+The goals of this page is to enumerate the API changes between Eigen2 and Eigen3,
+and to help porting an application from Eigen2 to Eigen3.
+
+\b Table \b of \b contents
+  - \ref summary
+  - \ref modules
+  - \ref core
+
+\section CompatibilitySupport Eigen2 compatibility support
+
+In order to ease th 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's header (typically it should be set in your project options).
+
+\section ChangeList List of changes
+
+<table>
+<tr><td>Eigen 2</td><td>Eigen 3</td></tr>
+<tr><td>vec.start(length)</td><td>vec.head(length)</td></tr>
+<tr><td>vec.start<length>()</td><td>vec.head<length>()</td></tr>
+<tr><td>vec.end(length)</td><td>vec.tail(length)</td></tr>
+<tr><td>vec.end<length>()</td><td>vec.tail<length>()</td></tr>
+<tr></tr>
+<tr><td>mat.cwise().XXX()</td><td>mat.array().XXX() \redstar</td></tr>
+<tr></tr>
+<tr><td>\code c = (a * b).lazy();\endcode</td><td>\code c.noalias() = a * b;\endcode</td></tr>
+</table>
+
+\redstar See \ref CoefficientWiseOperations for details.
+
+\section CoefficientWiseOperations Coefficient wise operations
+
+In Eigen2, coefficient wise operations which have no proper mathematical definiton (as a coeff wise product)
+were achied using the .cwise() prefix, e.g.:
+\code a.cwise() * b \code
+In Eigen3 this .cwise() prefix has been supersed 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 convertion to the array world. Therefore, for binary operations such as the coeff wise product,
+both sides must be converted to an \em array as in the above example. On the other hand, when you
+concatenates multiple coeff 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 LazyVsNoalias Lazy evaluation versus noalias
+
+In Eigen all operations are performed in a lazy fashion expected the matrix products which are always evaluated to 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 supersed 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
+
+*/
+
+}
diff --git a/doc/AsciiQuickReference.txt b/doc/AsciiQuickReference.txt
index 86f77a66b..74de7344b 100644
--- a/doc/AsciiQuickReference.txt
+++ b/doc/AsciiQuickReference.txt
@@ -39,10 +39,10 @@ A.setIdentity();  // Fill A with the identity.
 // Templated size versions are faster. Note that Matlab is 1-based (a size N
 // vector is x(1)...x(N)).
 // Eigen                           // Matlab
-x.start(n)                         // x(1:n)
-x.start<n>()                       // x(1:n)
-x.tail(n)                           // N = rows(x); x(N - n: N)
-x.tail<n>()                         // N = rows(x); x(N - n: N)
+x.head(n)                          // x(1:n)
+x.head<n>()                        // x(1:n)
+x.tail(n)                          // N = rows(x); x(N - n: N)
+x.tail<n>()                        // N = rows(x); x(N - n: N)
 x.segment(i, n)                    // x(i+1 : i+n)
 x.segment<n>(i)                    // x(i+1 : i+n)
 P.block(i, j, rows, cols)          // P(i+1 : i+rows, j+1 : j+cols)
@@ -81,30 +81,36 @@ a *= M;            R  = P + Q;      R  = P/s;
  // Vectorized operations on each element independently
  // (most require #include <Eigen/Array>)
 // Eigen                  // Matlab
-R = P.cwise() * Q;        // R = P .* Q
-R = P.cwise() / Q;        // R = P ./ Q
-R = P.cwise() + s;        // R = P + s
-R = P.cwise() - s;        // R = P - s
-R.cwise() += s;           // R = R + s
-R.cwise() -= s;           // R = R - s
-R.cwise() *= s;           // R = R * s
-R.cwise() /= s;           // R = R / s
-R.cwise() < Q;            // R < Q
-R.cwise() <= Q;           // R <= Q
-R.cwise().inverse();      // 1 ./ P
-R.cwise().sin()           // sin(P)
-R.cwise().cos()           // cos(P)
-R.cwise().pow(s)          // P .^ s
-R.cwise().square()        // P .^ 2
-R.cwise().cube()          // P .^ 3
-R.cwise().sqrt()          // sqrt(P)
-R.cwise().exp()           // exp(P)
-R.cwise().log()           // log(P)
-R.cwise().max(P)          // max(R, P)
-R.cwise().min(P)          // min(R, P)
-R.cwise().abs()           // abs(P)
-R.cwise().abs2()          // abs(P.^2)
-(R.cwise() < s).select(P,Q);  // (R < s ? P : Q)
+R = P.cwiseProduct(Q);    // R = P .* Q
+R = P.array() * s.array();// R = P .* s
+R = P.cwiseQuotient(Q);   // R = P ./ Q
+R = P.array() / Q.array();// R = P ./ Q
+R = P.array() + s.array();// R = P + s
+R = P.array() - s.array();// R = P - s
+R.array() += s;           // R = R + s
+R.array() -= s;           // R = R - s
+R.array() < Q.array();    // R < Q
+R.array() <= Q.array();   // R <= Q
+R.cwiseInverse();         // 1 ./ P
+R.array().inverse();      // 1 ./ P
+R.array().sin()           // sin(P)
+R.array().cos()           // cos(P)
+R.array().pow(s)          // P .^ s
+R.array().square()        // P .^ 2
+R.array().cube()          // P .^ 3
+R.cwiseSqrt()             // sqrt(P)
+R.array().sqrt()          // sqrt(P)
+R.array().exp()           // exp(P)
+R.array().log()           // log(P)
+R.cwiseMax(P)             // max(R, P)
+R.array().max(P.array())  // max(R, P)
+R.cwiseMin(P)             // min(R, P)
+R.array().min(P.array())  // min(R, P)
+R.cwiseAbs()              // abs(P)
+R.array().abs()           // abs(P)
+R.cwiseAbs2()             // abs(P.^2)
+R.array().abs2()          // abs(P.^2)
+(R.array() < s).select(P,Q);  // (R < s ? P : Q)
 
 // Reductions.
 int r, c;
diff --git a/doc/C01_QuickStartGuide.dox b/doc/C01_QuickStartGuide.dox
index 2240ed8b1..b342732ec 100644
--- a/doc/C01_QuickStartGuide.dox
+++ b/doc/C01_QuickStartGuide.dox
@@ -40,7 +40,7 @@ Here are some quick compilation instructions with GCC. To quickly test an exampl
 
 There is no library to link to. For good performance, add the \c -O2 compile-flag. Note however that this makes it impossible to debug inside Eigen code, as many functions get inlined. In some cases, performance can be further improved by disabling Eigen assertions: use \c -DEIGEN_NO_DEBUG or \c -DNDEBUG to disable them.
 
-On the x86 architecture, the SSE2 instruction set is not enabled by default. Use \c -msse2 to enable it, and Eigen will then automatically enable its vectorized paths. On x86-64 and AltiVec-based architectures, vectorization is enabled by default.
+On the x86 architecture, the SSE2 instruction set is not enabled by default. Use \c -msse2 to enable it, and Eigen will then automatically enable its vectorized paths. On x86-64 and AltiVec-based architectures, vectorization is enabled by default. To turn off Eigen's vectorization use \c-DEIGEN_DONT_VECTORIZE.
 
 \section TutorialCoreSimpleExampleFixedSize Simple example with fixed-size matrices and vectors
 
@@ -54,7 +54,8 @@ output:
 \include Tutorial_simple_example_fixed_size.out
 </td></tr></table>
 
-<a href="#" class="top">top</a>\section TutorialCoreSimpleExampleDynamicSize Simple example with dynamic-size matrices and vectors
+<a href="#" class="top">top</a>
+\section TutorialCoreSimpleExampleDynamicSize Simple example with dynamic-size matrices and vectors
 
 By dynamic-size, we mean that the numbers of rows and columns are not fixed at compile-time. In this case, they are stored as runtime variables and the arrays are dynamically allocated.
 
@@ -74,11 +75,14 @@ output:
 This slows compilation down but at least you don't have to worry anymore about including the correct files! There also is the Eigen/Dense header including all dense functionality i.e. leaving out the Sparse module.
 
 
-<a href="#" class="top">top</a>\section TutorialCoreMatrixTypes Matrix and vector types
+<a href="#" class="top">top</a>
+\section TutorialCoreMatrixTypes Array, matrix and vector types
 
-In Eigen, all kinds of dense matrices and vectors are represented by the template class Matrix. In most cases, you can simply use one of the \ref matrixtypedefs "convenience typedefs".
+Eigen provides two kinds of dense objects: mathematical matrices and vectors which are both represented by the template class Matrix, and 1D and 2D arrays represented by the template class Array. While the former (Matrix) is specialized for the representation of mathematical objects, the latter (Array) represents a collection of scalar values arranged in a 1D or 2D fashion. In particular, all operations performed on arrays are coefficient wise. Conversion between the two worlds can be done using the MatrixBase::array() and ArrayBase::matrix() functions respectively without any overhead. See \ref TutorialCoreArithmeticOperators for further details.
 
-The template class Matrix takes a number of template parameters, but for now it is enough to understand the 3 first ones (and the others can then be left unspecified):
+In most cases, you can simply use one of the \ref matrixtypedefs "convenience typedefs".
+
+The template class Matrix, just like the class Array) take a number of template parameters, but for now it is enough to understand the 3 first ones (and the others can then be left unspecified):
 
 \code Matrix<Scalar, RowsAtCompileTime, ColsAtCompileTime> \endcode
 
@@ -368,24 +372,24 @@ most common coefficient-wise operators.
 <tr><td>
 Add a scalar to all coefficients \redstar</td><td>\code
 mat3 = mat1.cwise() + scalar;
-mat3.cwise() += scalar;
-mat3.cwise() -= scalar;
+mat3.array() += scalar;
+mat3.array() -= scalar;
 \endcode
 </td></tr>
 <tr><td>
 Coefficient wise \link Cwise::operator/() division \endlink \redstar</td><td>\code
-mat3 = mat1.cwise() / mat2; \endcode
+mat3 = mat1.array() / mat2.array(); \endcode
 </td></tr>
 <tr><td>
 Coefficient wise \link Cwise::inverse() reciprocal \endlink \redstar</td><td>\code
-mat3 = mat1.cwise().inverse(); \endcode
+mat3 = mat1.array().inverse(); \endcode
 </td></tr>
 <tr><td>
 Coefficient wise comparisons \redstar \n
 (support all operators)</td><td>\code
-mat3 = mat1.cwise() < mat2;
-mat3 = mat1.cwise() <= mat2;
-mat3 = mat1.cwise() > mat2;
+mat3 = mat1.array() < mat2.array();
+mat3 = mat1.array() <= mat2.array();
+mat3 = mat1.array() > mat2.array();
 etc.
 \endcode
 </td></tr></table>
@@ -394,20 +398,20 @@ etc.
 <tr><td>
 \b Trigo \redstar: \n
 \link Cwise::sin sin \endlink, \link Cwise::cos cos \endlink</td><td>\code
-mat3 = mat1.cwise().sin();
+mat3 = mat1.array().sin();
 etc.
 \endcode
 </td></tr>
 <tr><td>
 \b Power \redstar: \n \link Cwise::pow() pow \endlink,
-\link Cwise::square square \endlink,
-\link Cwise::cube cube \endlink, \n
-\link Cwise::sqrt sqrt \endlink,
-\link Cwise::exp exp \endlink,
-\link Cwise::log log \endlink </td><td>\code
-mat3 = mat1.cwise().square();
-mat3 = mat1.cwise().pow(5);
-mat3 = mat1.cwise().log();
+\link ArrayBase::square square \endlink,
+\link ArrayBase::cube cube \endlink, \n
+\link ArrayBase::sqrt sqrt \endlink,
+\link ArrayBase::exp exp \endlink,
+\link ArrayBase::log log \endlink </td><td>\code
+mat3 = mat1.array().square();
+mat3 = mat1.array().pow(5);
+mat3 = mat1.array().log();
 etc.
 \endcode
 </td></tr>
@@ -415,10 +419,10 @@ etc.
 \link Cwise::min min \endlink, \link Cwise::max max \endlink, \n
 absolute value (\link Cwise::abs() abs \endlink, \link Cwise::abs2() abs2 \endlink)
 </td><td>\code
-mat3 = mat1.cwise().min(mat2);
-mat3 = mat1.cwise().max(mat2);
-mat3 = mat1.cwise().abs();
-mat3 = mat1.cwise().abs2();
+mat3 = mat1.cwiseMin(mat2);
+mat3 = mat1.cwiseMax(mat2);
+mat3 = mat1.cwiseAbs();
+mat3 = mat1.cwiseAbs2();
 \endcode</td></tr>
 </table>
 </td></tr></table>
@@ -492,7 +496,7 @@ Read-write access to sub-vectors:
 <td>Optimized versions when the size \n is known at compile time</td></tr>
 <td></td>
 
-<tr><td>\code vec1.start(n)\endcode</td><td>\code vec1.start<n>()\endcode</td><td>the first \c n coeffs </td></tr>
+<tr><td>\code vec1.head(n)\endcode</td><td>\code vec1.head<n>()\endcode</td><td>the first \c n coeffs </td></tr>
 <tr><td>\code vec1.tail(n)\endcode</td><td>\code vec1.tail<n>()\endcode</td><td>the last \c n coeffs </td></tr>
 <tr><td>\code vec1.segment(pos,n)\endcode</td><td>\code vec1.segment<n>(pos)\endcode</td>
     <td>the \c size coeffs in \n the range [\c pos : \c pos + \c n [</td></tr>
diff --git a/doc/Overview.dox b/doc/Overview.dox
index 78bf5f9dd..10463900e 100644
--- a/doc/Overview.dox
+++ b/doc/Overview.dox
@@ -9,15 +9,17 @@ o /** \mainpage Eigen
   | \ref TutorialSparse "Sparse matrix"
 </div>
 
-This is the API documentation for Eigen.
+This is the API documentation for Eigen3.
+
+You come from Eigen2? Here is a \ref Eigen2ToEigen3 guide for porting your application from Eigen2 to Eigen3.
 
 For a first contact with Eigen, the best place is to have a look at the \ref TutorialCore "tutorial". For an even shorter overview, we have an <a href="AsciiQuickReference.txt">ASCII quick reference</a> with Matlab translations.
 
-Most of the API is available as methods in MatrixBase, so this is a good starting point for browsing. Also have a look at Matrix, as a few methods and the matrix constructors are there. Other notable classes for the Eigen API are Cwise, which contains the methods for doing certain coefficient-wise operations, and Part.
+Most of the API is available as methods in DenseBase and MatrixBase, so this is a good starting point for browsing. Also have a look at Matrix, as a few methods and the matrix constructors are there. Other notable classes for the Eigen API are ArrayBase, which contains the methods for doing certain coefficient-wise operations, and TriangularView.
 
-In fact, except for advanced use, the only class that you'll have to explicitly name in your program, i.e. of which you'll explicitly contruct objects, is Matrix. For instance, vectors are handled as a special case of Matrix with one column. Typedefs are provided, e.g. Vector2f is a typedef for Matrix<float, 2, 1>.
+In fact, except for advanced use, the only classes that you'll have to explicitly name in your program, i.e. of which you'll explicitly contruct objects, is Matrix and Array. For instance, vectors are handled as a special case of Matrix with one column. Typedefs are provided, e.g. Vector2f is a typedef for Matrix<float, 2, 1>.
 
-Most of the other classes are just return types for MatrixBase methods.
+Most of the other classes are just return types for DenseBase and MatrixBase methods.
 
 Want more? Checkout the \ref Unsupported_modules "unsupported modules" <a href="unsupported/index.html">documentation</a>.