Added more detailed documentation

gtsam/linear/AcceleratedPowerMethod.h

@@ -80,7 +80,6 @@ class AcceleratedPowerMethod : public PowerMethod<Operator> {
     } else {
       beta_ = initialBeta;
     }
-    
     }
 
   // Update the ritzVector with beta and previous two ritzVector

gtsam/linear/PowerMethod.h

@@ -89,9 +89,11 @@ class PowerMethod {
   // Return the number of iterations
   size_t nrIterations() const { return nrIterations_; }
 
-  // Start the power/accelerated iteration, after updated the ritz vector,
-  // calculate the ritz error, repeat this operation until the ritz error converge
-  int compute(size_t maxIterations, double tol) {
+  // Start the power/accelerated iteration, after performing the
+  // power/accelerated power iteration, calculate the ritz error, repeat this
+  // operation until the ritz error converge. If converged return true, else
+  // false.
+  bool compute(size_t maxIterations, double tol) {
     // Starting
     bool isConverged = false;
 

gtsam/linear/tests/testAcceleratedPowerMethod.cpp

@@ -18,18 +18,16 @@
  * @brief  Check eigenvalue and eigenvector computed by accelerated power method
  */
 
+#include <CppUnitLite/TestHarness.h>
 #include <gtsam/base/Matrix.h>
 #include <gtsam/base/VectorSpace.h>
 #include <gtsam/inference/Symbol.h>
-#include <gtsam/linear/GaussianFactorGraph.h>
 #include <gtsam/linear/AcceleratedPowerMethod.h>
-
-#include <CppUnitLite/TestHarness.h>
+#include <gtsam/linear/GaussianFactorGraph.h>
 
 #include <Eigen/Core>
 #include <Eigen/Dense>
 #include <Eigen/Eigenvalues>
-
 #include <iostream>
 #include <random>
 
@@ -79,22 +77,26 @@ TEST(AcceleratedPowerMethod, useFactorGraph) {
   // Check that we get zero eigenvalue and "constant" eigenvector
   EXPECT_DOUBLES_EQUAL(0.0, solver.eigenvalues()[0].real(), 1e-9);
   auto v0 = solver.eigenvectors().col(0);
-  for (size_t j = 0; j < 3; j++)
-    EXPECT_DOUBLES_EQUAL(-0.5, v0[j].real(), 1e-9);
+  for (size_t j = 0; j < 3; j++) EXPECT_DOUBLES_EQUAL(-0.5, v0[j].real(), 1e-9);
 
   size_t maxIdx = 0;
   for (auto i = 0; i < solver.eigenvalues().rows(); ++i) {
-    if (solver.eigenvalues()(i).real() >= solver.eigenvalues()(maxIdx).real()) maxIdx = i;
+    if (solver.eigenvalues()(i).real() >= solver.eigenvalues()(maxIdx).real())
+      maxIdx = i;
   }
   // Store the max eigenvalue and its according eigenvector
   const auto ev1 = solver.eigenvalues()(maxIdx).real();
   auto ev2 = solver.eigenvectors().col(maxIdx).real();
 
-  Vector initial = Vector4::Random();
+  Vector disturb = Vector4::Random();
+  disturb.normalize();
+  Vector initial = L.first.row(0);
+  double magnitude = initial.norm();
+  initial += 0.03 * magnitude * disturb;
   AcceleratedPowerMethod<Matrix> apf(L.first, initial);
   apf.compute(50, 1e-4);
   EXPECT_DOUBLES_EQUAL(ev1, apf.eigenvalue(), 1e-8);
-  EXPECT(assert_equal(-ev2, apf.eigenvector(), 3e-5));
+  EXPECT(assert_equal(ev2, apf.eigenvector(), 3e-5));
 }
 
 /* ************************************************************************* */

gtsam/linear/tests/testPowerMethod.cpp

@@ -18,18 +18,16 @@
  * @brief  Check eigenvalue and eigenvector computed by power method
  */
 
+#include <CppUnitLite/TestHarness.h>
 #include <gtsam/base/Matrix.h>
 #include <gtsam/base/VectorSpace.h>
 #include <gtsam/inference/Symbol.h>
 #include <gtsam/linear/GaussianFactorGraph.h>
 #include <gtsam/linear/PowerMethod.h>
 
-#include <CppUnitLite/TestHarness.h>
-
 #include <Eigen/Core>
 #include <Eigen/Dense>
 #include <Eigen/Eigenvalues>
-
 #include <iostream>
 #include <random>
 
@@ -77,12 +75,12 @@ TEST(PowerMethod, useFactorGraph) {
   // Check that we get zero eigenvalue and "constant" eigenvector
   EXPECT_DOUBLES_EQUAL(0.0, solver.eigenvalues()[0].real(), 1e-9);
   auto v0 = solver.eigenvectors().col(0);
-  for (size_t j = 0; j < 3; j++)
-    EXPECT_DOUBLES_EQUAL(-0.5, v0[j].real(), 1e-9);
+  for (size_t j = 0; j < 3; j++) EXPECT_DOUBLES_EQUAL(-0.5, v0[j].real(), 1e-9);
 
   size_t maxIdx = 0;
   for (auto i = 0; i < solver.eigenvalues().rows(); ++i) {
-    if (solver.eigenvalues()(i).real() >= solver.eigenvalues()(maxIdx).real()) maxIdx = i;
+    if (solver.eigenvalues()(i).real() >= solver.eigenvalues()(maxIdx).real())
+      maxIdx = i;
   }
   // Store the max eigenvalue and its according eigenvector
   const auto ev1 = solver.eigenvalues()(maxIdx).real();

gtsam/sfm/ShonanAveraging.cpp

@@ -482,6 +482,9 @@ Sparse ShonanAveraging<d>::computeA(const Matrix &S) const {
 // Perturb the initial initialVector by adding a spherically-uniformly
 // distributed random vector with 0.03*||initialVector||_2 magnitude to
 // initialVector
+// ref : Part III. C, Rosen, D. and Carlone, L., 2017, September. Computational
+// enhancements for certifiably correct SLAM. In Proceedings of the
+// International Conference on Intelligent Robots and Systems.
 Vector perturb(const Vector &initialVector) {
   // generate a 0.03*||x_0||_2 as stated in David's paper
   int n = initialVector.rows();