LocalParameterization -> Manifold #1

Manifolds are now part of the public API and co-exist
with LocalParameterizations.

1. Add Manifolds to the Problem API.
   a. AddParameterBlock(double*, int, Manifold*)
   b. SetParameterization(double*, Manifold*)
   b. GetManifold(const double*)
   c. HasManifold(const double*)

2. Internally Ceres now only uses Manifolds. When the user uses
   a LocalParameterization, it is wrapped in a ManifoldAdapter.

3. To preserve the API semantics while keeping the internals clean
   we need a new map in ProblemImpl which stores the association
   between parameter blocks and local parameterizations. This
   is temporary, it will go away once this transition is complete.

4. There are NO algorithmic changes, as in we are not using
   any of the expanded interface of the Manifold objects yet.
   That will come later.

5. All tests that use LocalParameterization have been duplicated
   to use Manifolds, and when this transition is complete the
   LocalParameterization based tests will be deleted.

6. Public documentation for the API has been updated. Deprecation
   notices to the documentation as well as C++ annotations will come
   later.

7. Similar changes have been made to GradientProblem.

Change-Id: I8e03c8ced6e141876ef3eca5740c113afa788f0c

include/ceres/gradient_problem.h

@@ -36,6 +36,7 @@
 #include "ceres/first_order_function.h"
 #include "ceres/internal/port.h"
 #include "ceres/local_parameterization.h"
+#include "ceres/manifold.h"
 
 namespace ceres {
 
@@ -43,23 +44,22 @@ class FirstOrderFunction;
 
 // Instances of GradientProblem represent general non-linear
 // optimization problems that must be solved using just the value of
-// the objective function and its gradient. Unlike the Problem class,
-// which can only be used to model non-linear least squares problems,
-// instances of GradientProblem not restricted in the form of the
-// objective function.
+// the objective function and its gradient.
+
+// Unlike the Problem class, which can only be used to model non-linear least
+// squares problems, instances of GradientProblem are not restricted in the form
+// of the objective function.
 //
-// Structurally GradientProblem is a composition of a
-// FirstOrderFunction and optionally a LocalParameterization.
+// Structurally GradientProblem is a composition of a FirstOrderFunction and
+// optionally a Manifold.
 //
-// The FirstOrderFunction is responsible for evaluating the cost and
-// gradient of the objective function.
+// The FirstOrderFunction is responsible for evaluating the cost and gradient of
+// the objective function.
 //
-// The LocalParameterization is responsible for going back and forth
-// between the ambient space and the local tangent space. (See
-// local_parameterization.h for more details). When a
-// LocalParameterization is not provided, then the tangent space is
-// assumed to coincide with the ambient Euclidean space that the
-// gradient vector lives in.
+// The Manifold is responsible for going back and forth between the ambient
+// space and the local tangent space. (See manifold.h for more details). When a
+// Manifold is not provided, then the tangent space is assumed to coincide with
+// the ambient Euclidean space that the gradient vector lives in.
 //
 // Example usage:
 //
@@ -89,17 +89,43 @@ class FirstOrderFunction;
 // };
 //
 // ceres::GradientProblem problem(new Rosenbrock());
+//
+// NOTE: We are currently in the process of transitioning from
+// LocalParameterization to Manifolds in the Ceres API. During this period,
+// GradientProblem will support using both Manifold and LocalParameterization
+// objects interchangably. For methods in the API affected by this change, see
+// their documentation below.
 class CERES_EXPORT GradientProblem {
  public:
   // Takes ownership of the function.
   explicit GradientProblem(FirstOrderFunction* function);
 
   // Takes ownership of the function and the parameterization.
+  //
+  // NOTE: This constructor is deprecated and will be removed in the next public
+  // release of Ceres Solver. Please move to using the Manifold based
+  // constructor.
   GradientProblem(FirstOrderFunction* function,
                   LocalParameterization* parameterization);
 
+  // Takes ownership of the function and the manifold.
+  GradientProblem(FirstOrderFunction* function, Manifold* manifold);
+
   int NumParameters() const;
-  int NumLocalParameters() const;
+
+  // Dimension of the manifold (and its tangent space).
+  //
+  // During the transition from LocalParameterization to Manifold, this method
+  // reports the LocalSize of the LocalParameterization or the TangentSize of
+  // the Manifold object associated with this problem.
+  int NumTangentParameters() const;
+
+  // Dimension of the manifold (and its tangent space).
+  //
+  // NOTE: This method is deprecated and will be removed in the next public
+  // release of Ceres Solver. Please move to using NumTangentParameters()
+  // instead.
+  int NumLocalParameters() const { return NumTangentParameters(); }
 
   // This call is not thread safe.
   bool Evaluate(const double* parameters, double* cost, double* gradient) const;
@@ -107,9 +133,33 @@ class CERES_EXPORT GradientProblem {
 
   const FirstOrderFunction* function() const { return function_.get(); }
   FirstOrderFunction* mutable_function() { return function_.get(); }
+
+  // NOTE: During the transition from LocalParameterization to Manifold we need
+  // to support both The LocalParameterization and Manifold based constructors.
+  //
+  // When the user uses the LocalParameterization, internally the solver will
+  // wrap it in a ManifoldAdapter object and return it when manifold or
+  // mutable_manifold are called.
+  //
+  // As a result this method will return a non-nullptr result if a Manifold or a
+  // LocalParameterization was used when constructing the GradientProblem.
+  const Manifold* manifold() const { return manifold_.get(); }
+  Manifold* mutable_manifold() { return manifold_.get(); }
+
+  // If the problem is constructed without a LocalParameterization or with a
+  // Manifold this method will return a nullptr.
+  //
+  // NOTE: This method is deprecated and will be removed in the next public
+  // release of Ceres Solver.
   const LocalParameterization* parameterization() const {
     return parameterization_.get();
   }
+
+  // If the problem is constructed without a LocalParameterization or with a
+  // Manifold this method will return a nullptr.
+  //
+  // NOTE: This method is deprecated and will be removed in the next public
+  // release of Ceres Solver.
   LocalParameterization* mutable_parameterization() {
     return parameterization_.get();
   }
@@ -117,6 +167,7 @@ class CERES_EXPORT GradientProblem {
  private:
   std::unique_ptr<FirstOrderFunction> function_;
   std::unique_ptr<LocalParameterization> parameterization_;
+  std::unique_ptr<Manifold> manifold_;
   std::unique_ptr<double[]> scratch_;
 };