doc updates/improvements

doc/C00_QuickStartGuide.dox

@@ -83,8 +83,9 @@ The use of fixed-size matrices and vectors has two advantages. The compiler emit
 
 \section GettingStartedConclusion Where to go from here?
 
-You could directly use our \ref QuickRefPage and class documentation, or if you do not yet feel ready for that, you could
+It's worth taking the time to read the  \ref TutorialMatrixClass "long tutorial".
-read the longer \ref TutorialMatrixClass "Tutorial" in which the Eigen library is explained in more detail.
+
+However if you think you don't need it, you can directly use the classes documentation and our \ref QuickRefPage.
 
 \li \b Next: \ref TutorialMatrixClass
 

doc/C01_TutorialMatrixClass.dox

@@ -92,7 +92,7 @@ Matrix<float, 3, Dynamic>
 
 \section TutorialMatrixConstructors Constructors
 
-A default constructor is always available, and always has zero runtime cost. You can do:
+A default constructor is always available, never performs any dynamic memory allocation, and never initializes the matrix coefficients. You can do:
 \code
 Matrix3f a;
 MatrixXf b;

doc/C06_TutorialLinearAlgebra.dox

@@ -180,9 +180,18 @@ Here is an example:
 
 \section TutorialLinAlgLeastsquares Least squares solving
 
-Eigen doesn't currently provide built-in linear least squares solving functions, but you can easily compute that yourself
+The best way to do least squares solving is with a SVD decomposition. Eigen provides one as the JacobiSVD class, and its solve()
-from Eigen's decompositions. The most reliable way is to use a SVD (or better yet, JacobiSVD), and in the future
+is doing least-squares solving.
-these classes will offer methods for least squares solving. Another, potentially faster way, is to use a LLT decomposition
+
+Here is an example:
+<table class="tutorial_code">
+<tr>
+  <td>\include TutorialLinAlgSVDSolve.cpp </td>
+  <td>output: \verbinclude TutorialLinAlgSVDSolve.out </td>
+</tr>
+</table>
+
+Another way, potentially faster but less reliable, is to use a LDLT decomposition
 of the normal matrix. In any case, just read any reference text on least squares, and it will be very easy for you
 to implement any linear least squares computation on top of Eigen.
 

doc/QuickReference.dox

@@ -27,11 +27,11 @@ The Eigen library is divided in a Core module and several additional modules. Ea
 <tr><td>\link LU_Module LU \endlink</td><td>\code#include <Eigen/LU>\endcode</td><td>Inverse, determinant, LU decompositions with solver (FullPivLU, PartialPivLU)</td></tr>
 <tr><td>\link Cholesky_Module Cholesky \endlink</td><td>\code#include <Eigen/Cholesky>\endcode</td><td>LLT and LDLT Cholesky factorization with solver</td></tr>
 <tr><td>\link Householder_Module Householder \endlink</td><td>\code#include <Eigen/Householder>\endcode</td><td>Householder transformations; this module is used by several linear algebra modules</td></tr>
-<tr><td>\link SVD_Module SVD \endlink</td><td>\code#include <Eigen/SVD>\endcode</td><td>%SVD decomposition with solver (SVD, JacobiSVD)</td></tr>
+<tr><td>\link SVD_Module SVD \endlink</td><td>\code#include <Eigen/SVD>\endcode</td><td>SVD decomposition with least-squares solver (JacobiSVD)</td></tr>
 <tr><td>\link QR_Module QR \endlink</td><td>\code#include <Eigen/QR>\endcode</td><td>QR decomposition with solver (HouseholderQR, ColPivHouseholderQR, FullPivHouseholderQR)</td></tr>
 <tr><td>\link Eigenvalues_Module Eigenvalues \endlink</td><td>\code#include <Eigen/Eigenvalues>\endcode</td><td>Eigenvalue, eigenvector decompositions (EigenSolver, SelfAdjointEigenSolver, ComplexEigenSolver)</td></tr>
 <tr><td>\link Sparse_Module Sparse \endlink</td><td>\code#include <Eigen/Sparse>\endcode</td><td>%Sparse matrix storage and related basic linear algebra (SparseMatrix, DynamicSparseMatrix, SparseVector)</td></tr>
-<tr><td></td><td>\code#include <Eigen/Dense>\endcode</td><td>Includes Core, Geometry, LU, Cholesky, %SVD, QR, and Eigenvalues header files</td></tr>
+<tr><td></td><td>\code#include <Eigen/Dense>\endcode</td><td>Includes Core, Geometry, LU, Cholesky, SVD, QR, and Eigenvalues header files</td></tr>
 <tr><td></td><td>\code#include <Eigen/Eigen>\endcode</td><td>Includes %Dense and %Sparse header files (the whole Eigen library)</td></tr>
 </table>
 

doc/TopicLinearAlgebraDecompositions.dox

@@ -112,27 +112,15 @@ namespace Eigen {
     <tr><td colspan="9">\n Singular values and eigenvalues decompositions</td></tr>
 
     <tr>
-        <td>SVD</td>
+        <td>JacobiSVD (two-sided)</td>
-        <td>-</td>
-        <td>Average</td>
-        <td>Good</td>
-        <td>Yes</td>
-        <td>Singular values/vectors, least squares</td>
-        <td>Yes</td>
-        <td>Average</td>
-        <td>-</td>
-    </tr>
-
-    <tr>
-        <td>JacobiSVD</td>
         <td>-</td>
         <td>Slow (but fast for small matrices)</td>
-        <td>Proven</td>
+        <td>Excellent-Proven<sup><a href="#note3">3</a></sup></td>
         <td>Yes</td>
         <td>Singular values/vectors, least squares</td>
-        <td>-</td>
+        <td>Yes (and does least squares)</td>
         <td>Excellent</td>
-        <td>-</td>
+        <td>R-SVD</td>
     </tr>
 
     <tr>
@@ -251,6 +239,7 @@ namespace Eigen {
 <ul>
 <li><a name="note1">\b 1: </a>There exist two variants of the LDLT algorithm. Eigen's one produces a pure diagonal D matrix, and therefore it cannot handle indefinite matrices, unlike Lapack's one which produces a block diagonal D matrix.</li>
 <li><a name="note2">\b 2: </a>Eigenvalues, SVD and Schur decompositions rely on iterative algorithms. Their convergence speed depends on how well the eigenvalues are separated.</li>
+<li><a name="note3">\b 3: </a>Our JacobiSVD is two-sided, making for proven and optimal precision for square matrices. For non-square matrices, we have to use a QR preconditioner first. The default choice, ColPivHouseholderQR, is already very reliable, but if you want it to be proven, use FullPivHouseholderQR instead.
 </ul>
 
 \section TopicLinAlgTerminology Terminology

doc/examples/TutorialLinAlgSVDSolve.cpp

@@ -0,0 +1,15 @@
+#include <iostream>
+#include <Eigen/Dense>
+
+using namespace std;
+using namespace Eigen;
+
+int main()
+{
+   MatrixXf A = MatrixXf::Random(3, 2);
+   cout << "Here is the matrix A:\n" << A << endl;
+   VectorXf b = VectorXf::Random(3);
+   cout << "Here is the right hand side b:\n" << b << endl;
+   JacobiSVD<MatrixXf> svd(A, ComputeThinU | ComputeThinV);
+   cout << "The least-squares solution is:\n" << svd.solve(b) << endl;
+}