Deprecate LocalParameterizations

Add [[deprecate]] notices to everything LocalParameterization
related.

Make sure that Ceres can be compiled without triggering
deprecation warnings.

Update the documentation:

a. Add deprecation notices.
b. Document interaction between LocalParameterization and Manifold
   coexisting in the Problem.
c. Add documentation for Manifold(s)

Change-Id: Ie4ad48963c83fded86e533c8c60561af402fbaff

docs/source/conf.py

@@ -41,16 +41,16 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Ceres Solver'
-copyright = u'2020 Google Inc'
+copyright = u'2022 Google Inc'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '2.0'
+version = '2.1'
 # The full version, including alpha/beta/rc tags.
-release = '2.0.0'
+release = '2.1.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/features.rst

@@ -1,3 +1,7 @@
+.. default-domain:: cpp
+
+.. cpp:namespace:: ceres
+
 ====
 Why?
 ====

docs/source/gradient_solver.rst

@@ -1,6 +1,8 @@
+.. default-domain:: cpp
+
 .. highlight:: c++
 
-.. default-domain:: cpp
+.. cpp:namespace:: ceres
 
 .. _chapter-gradient_problem_solver:
 
@@ -46,6 +48,12 @@ Modeling
 :class:`GradientProblem`
 ------------------------
 
+.. NOTE::
+
+   The :class:`LocalParameterization` interface and associated classes
+   are deprecated. They will be removed in the version 2.2.0. Please use
+   :class:`Manifold` based constructor instead.
+
 .. class:: GradientProblem
 
 .. code-block:: c++
@@ -55,8 +63,11 @@ Modeling
     explicit GradientProblem(FirstOrderFunction* function);
     GradientProblem(FirstOrderFunction* function,
                     LocalParameterization* parameterization);
+    GradientProblem(FirstOrderFunction* function,
+                    Manifold* manifold);
     int NumParameters() const;
-    int NumLocalParameters() const;
+    int NumLocalParameters() const { return NumTangentParameters(); }
+    int NumTangentParameters() const;
     bool Evaluate(const double* parameters, double* cost, double* gradient) const;
     bool Plus(const double* x, const double* delta, double* x_plus_delta) const;
   };
@@ -70,19 +81,21 @@ form of the objective function.
 
 Structurally :class:`GradientProblem` is a composition of a
 :class:`FirstOrderFunction` and optionally a
-:class:`LocalParameterization`.
+:class:`LocalParameterization` or a :class:`Manifold`.
 
 The :class:`FirstOrderFunction` is responsible for evaluating the cost
 and gradient of the objective function.
 
-The :class:`LocalParameterization` is responsible for going back and
-forth between the ambient space and the local tangent space. When a
-:class:`LocalParameterization` is not provided, then the tangent space
-is assumed to coincide with the ambient Euclidean space that the
-gradient vector lives in.
+The :class:`LocalParameterization`/:class:`Manifold` is responsible
+for going back and forth between the ambient space and the local
+tangent space. When a :class:`LocalParameterization` or a
+:class:`Manifold` is not provided, then the tangent space is assumed
+to coincide with the ambient Euclidean space that the gradient vector
+lives in.
 
 The constructor takes ownership of the :class:`FirstOrderFunction` and
-:class:`LocalParamterization` objects passed to it.
+:class:`LocalParameterization` or :class:`Manifold` objects passed to
+it.
 
 
 .. function:: void Solve(const GradientProblemSolver::Options& options, const GradientProblem& problem, double* parameters, GradientProblemSolver::Summary* summary)
@@ -342,8 +355,8 @@ Solving
 
    where :math:`\|\cdot\|_\infty` refers to the max norm, :math:`\Pi`
    is projection onto the bounds constraints and :math:`\boxplus` is
-   Plus operation for the overall local parameterization associated
-   with the parameter vector.
+   Plus operation for the manifold associated with the parameter
+   vector.
 
 .. member:: double GradientProblemSolver::Options::parameter_tolerance
 
@@ -490,7 +503,19 @@ Solving
 
    Dimension of the tangent space of the problem. This is different
    from :member:`GradientProblemSolver::Summary::num_parameters` if a
-   :class:`LocalParameterization` object is used.
+   :class:`LocalParameterization`/:class:`Manifold` object is used.
+
+   .. NOTE::
+
+      ``num_local_parameters`` is deprecated and will be removed in
+      Ceres Solver version 2.2.0. Please use ``num_tangent_parameters``
+      instead.
+
+.. member:: int GradientProblemSolver::Summary::num_tangent_parameters
+
+   Dimension of the tangent space of the problem. This is different
+   from :member:`GradientProblemSolver::Summary::num_parameters` if a
+   :class:`LocalParameterization`/:class:`Manifold` object is used.
 
 .. member:: LineSearchDirectionType GradientProblemSolver::Summary::line_search_direction_type
 

docs/source/gradient_tutorial.rst

@@ -160,7 +160,7 @@ follows [#f2]_.
                                                       kNumParameters>(
           new Rosenbrock);
     }
-};
+  };
 
 And finally, if you would rather compute the derivatives by hand (say
 because the size of the parameter vector is too large to be

docs/source/nnls_solving.rst

@@ -1,6 +1,7 @@
-
 .. default-domain:: cpp
 
+.. highlight:: c++
+
 .. cpp:namespace:: ceres
 
 .. _chapter-nnls_solving:
@@ -1239,8 +1240,8 @@ elimination group [LiSaad]_.
 
    where :math:`\|\cdot\|_\infty` refers to the max norm, :math:`\Pi`
    is projection onto the bounds constraints and :math:`\boxplus` is
-   Plus operation for the overall local parameterization associated
-   with the parameter vector.
+   Plus operation for the overall manifold associated with the
+   parameter vector.
 
 .. member:: double Solver::Options::parameter_tolerance
 
@@ -2212,7 +2213,7 @@ The three arrays will be:
    Dimension of the tangent space of the problem (or the number of
    columns in the Jacobian for the problem). This is different from
    :member:`Solver::Summary::num_parameters` if a parameter block is
-   associated with a :class:`LocalParameterization`.
+   associated with a :class:`Manifold`.
 
 .. member:: int Solver::Summary::num_residual_blocks
 
@@ -2238,7 +2239,7 @@ The three arrays will be:
    number of columns in the Jacobian for the reduced problem). This is
    different from :member:`Solver::Summary::num_parameters_reduced` if
    a parameter block in the reduced problem is associated with a
-   :class:`LocalParameterization`.
+   :class:`Manifold`.
 
 .. member:: int Solver::Summary::num_residual_blocks_reduced
 

docs/source/nnls_tutorial.rst

@@ -728,7 +728,7 @@ simplest of them ``DENSE_SCHUR``.
 
 For a more sophisticated bundle adjustment example which demonstrates
 the use of Ceres' more advanced features including its various linear
-solvers, robust loss functions and local parameterizations see
+solvers, robust loss functions and manifolds see
 `examples/bundle_adjuster.cc
 <https://ceres-solver.googlesource.com/ceres-solver/+/master/examples/bundle_adjuster.cc>`_
 
@@ -886,10 +886,12 @@ directory contains a number of other examples:
    i.e. :math:`\Sigma_{ab}^{-\frac{1}{2}} r_{ab}` where :math:`\Sigma_{ab}` is
    the covariance.
 
-   Lastly, we use a local parameterization to normalize the orientation in the
-   range which is normalized between :math:`[-\pi,\pi)`.  Specially, we define
-   the :member:`AngleLocalParameterization::operator()` function to be:
-   :math:`\mathrm{Normalize}(\psi + \delta \psi)`.
+   Lastly, we use a manifold to normalize the orientation in the range
+   :math:`[-\pi,\pi)`.  Specially, we define the
+   :member:`AngleManifold::Plus()` function to be:
+   :math:`\mathrm{Normalize}(\psi + \Delta)` and
+   ::member::`AngleManifold::Minus()` function to be
+   :math:`\mathrm{Normalize}(y) - \mathrm{Normalize}(x)`.
 
    This package includes an executable :member:`pose_graph_2d` that will read a
    problem definition file. This executable can work with any 2D problem
@@ -980,17 +982,18 @@ directory contains a number of other examples:
    i.e. :math:`\Sigma_{ab}^{-\frac{1}{2}} r_{ab}` where :math:`\Sigma_{ab}` is
    the covariance.
 
-   Given that we are using a quaternion to represent the orientation, we need to
-   use a local parameterization (:class:`EigenQuaternionParameterization`) to
+   Given that we are using a quaternion to represent the orientation,
+   we need to use a manifold (:class:`EigenQuaternionManifold`) to
    only apply updates orthogonal to the 4-vector defining the
-   quaternion. Eigen's quaternion uses a different internal memory layout for
-   the elements of the quaternion than what is commonly used. Specifically,
-   Eigen stores the elements in memory as :math:`[x, y, z, w]` where the real
-   part is last whereas it is typically stored first. Note, when creating an
-   Eigen quaternion through the constructor the elements are accepted in
-   :math:`w`, :math:`x`, :math:`y`, :math:`z` order. Since Ceres operates on
-   parameter blocks which are raw double pointers this difference is important
-   and requires a different parameterization.
+   quaternion. Eigen's quaternion uses a different internal memory
+   layout for the elements of the quaternion than what is commonly
+   used. Specifically, Eigen stores the elements in memory as
+   :math:`[x, y, z, w]` where the real part is last whereas it is
+   typically stored first. Note, when creating an Eigen quaternion
+   through the constructor the elements are accepted in :math:`w`,
+   :math:`x`, :math:`y`, :math:`z` order. Since Ceres operates on
+   parameter blocks which are raw double pointers this difference is
+   important and requires a different parameterization.
 
    This package includes an executable :member:`pose_graph_3d` that will read a
    problem definition file. This executable can work with any 3D problem