Various cleanups to the documentation
Fixes https://github.com/ceres-solver/ceres-solver/issues/208
Change-Id: I62c575b646260f801c95188910910ecf441fa9ac
diff --git a/docs/source/gradient_solver.rst b/docs/source/gradient_solver.rst
index 81c5a56..4e3fc71 100644
--- a/docs/source/gradient_solver.rst
+++ b/docs/source/gradient_solver.rst
@@ -1,7 +1,7 @@
-.. default-domain:: cpp
-
.. highlight:: c++
+.. default-domain:: cpp
+
.. cpp:namespace:: ceres
.. _chapter-gradient_problem_solver:
@@ -103,7 +103,7 @@
behavior of the solver. We list the various settings and their
default values below.
-.. function:: bool GradientProblemSolver::Options::IsValid(string* error) const
+.. function:: bool GradientProblemSolver::Options::IsValid(std::string* error) const
Validate the values in the options struct and returns true on
success. If there is a problem, the method returns false with
@@ -388,14 +388,14 @@
#. ``it`` is the time take by the current iteration.
#. ``tt`` is the total time taken by the minimizer.
-.. member:: vector<IterationCallback> GradientProblemSolver::Options::callbacks
+.. member:: std::vector<IterationCallback> GradientProblemSolver::Options::callbacks
Callbacks that are executed at the end of each iteration of the
:class:`Minimizer`. They are executed in the order that they are
specified in this vector. By default, parameter blocks are updated
only at the end of the optimization, i.e., when the
:class:`Minimizer` terminates. This behavior is controlled by
- :member:`GradientProblemSolver::Options::update_state_every_variable`. If
+ :member:`GradientProblemSolver::Options::update_state_every_iteration`. If
the user wishes to have access to the update parameter blocks when
his/her callbacks are executed, then set
:member:`GradientProblemSolver::Options::update_state_every_iteration`
@@ -420,12 +420,12 @@
Summary of the various stages of the solver after termination.
-.. function:: string GradientProblemSolver::Summary::BriefReport() const
+.. function:: std::string GradientProblemSolver::Summary::BriefReport() const
A brief one line description of the state of the solver after
termination.
-.. function:: string GradientProblemSolver::Summary::FullReport() const
+.. function:: std::string GradientProblemSolver::Summary::FullReport() const
A full multiline description of the state of the solver after
termination.
@@ -444,7 +444,7 @@
The cause of the minimizer terminating.
-.. member:: string GradientProblemSolver::Summary::message
+.. member:: std::string GradientProblemSolver::Summary::message
Reason why the solver terminated.
@@ -458,7 +458,7 @@
Cost of the problem (value of the objective function) after the
optimization.
-.. member:: vector<IterationSummary> GradientProblemSolver::Summary::iterations
+.. member:: std::vector<IterationSummary> GradientProblemSolver::Summary::iterations
:class:`IterationSummary` for each minimizer iteration in order.
diff --git a/docs/source/gradient_tutorial.rst b/docs/source/gradient_tutorial.rst
index fb26cb7..261a5e9 100644
--- a/docs/source/gradient_tutorial.rst
+++ b/docs/source/gradient_tutorial.rst
@@ -2,6 +2,8 @@
.. default-domain:: cpp
+.. cpp:namespace:: ceres
+
.. _chapter-gradient_tutorial:
==================================
diff --git a/docs/source/modeling_faqs.rst b/docs/source/modeling_faqs.rst
index a2704d8..2e4f6f2 100644
--- a/docs/source/modeling_faqs.rst
+++ b/docs/source/modeling_faqs.rst
@@ -37,7 +37,7 @@
automatic and numeric differentiation. See
:class:`CostFunctionToFunctor`.
-#. When using Quaternions, consider using :class:`QuaternionParameterization`.
+#. When using Quaternions, consider using :class:`QuaternionManifold`.
`Quaternions <https://en.wikipedia.org/wiki/Quaternion>`_ are a
four dimensional parameterization of the space of three dimensional
@@ -47,14 +47,14 @@
associate a local parameterization with parameter blocks
representing a Quaternion. Assuming that the order of entries in
your parameter block is :math:`w,x,y,z`, you can use
- :class:`QuaternionParameterization`.
+ :class:`QuaternionManifold`.
.. NOTE::
If you are using `Eigen's Quaternion
<http://eigen.tuxfamily.org/dox/classEigen_1_1Quaternion.html>`_
object, whose layout is :math:`x,y,z,w`, then you should use
- :class:`EigenQuaternionParameterization`.
+ :class:`EigenQuaternionManifold`.
#. How do I solve problems with general linear & non-linear
@@ -81,8 +81,9 @@
and lower bounds constraints on the parameter blocks.
The trick described above for dealing with inequality
- constraints will **not** work for equality constraints.
+ constraints will **not** work.. default-domain:: cpp |
+ for equality constraints.
#. How do I set one or more components of a parameter block constant?
- Using :class:`SubsetParameterization`.
+ Using :class:`SubsetManifold`.
diff --git a/docs/source/nnls_covariance.rst b/docs/source/nnls_covariance.rst
index 2c3c05d..ece6f58 100644
--- a/docs/source/nnls_covariance.rst
+++ b/docs/source/nnls_covariance.rst
@@ -1,3 +1,4 @@
+.. highlight:: c++
.. default-domain:: cpp
@@ -49,7 +50,7 @@
covariance of :math:`y`, then the maximum likelihood problem to be
solved is
-.. math:: x^* = \arg \min_x f'(x) S^{-1} f(x)
+o.. math:: x^* = \arg \min_x f'(x) S^{-1} f(x)
and the corresponding covariance estimate of :math:`x^*` is given by
@@ -302,7 +303,7 @@
entire documentation for :class:`Covariance::Options` before using
:class:`Covariance`.
-.. function:: bool Covariance::Compute(const vector<pair<const double*, const double*> >& covariance_blocks, Problem* problem)
+.. function:: bool Covariance::Compute(const std::vector<std::pair<const double*, const double*> >& covariance_blocks, Problem* problem)
Compute a part of the covariance matrix.
@@ -378,7 +379,7 @@
Covariance::Options options;
Covariance covariance(options);
- vector<pair<const double*, const double*> > covariance_blocks;
+ std::vector<std::pair<const double*, const double*> > covariance_blocks;
covariance_blocks.push_back(make_pair(x, x));
covariance_blocks.push_back(make_pair(y, y));
covariance_blocks.push_back(make_pair(x, y));
diff --git a/docs/source/nnls_modeling.rst b/docs/source/nnls_modeling.rst
index e393148..512834c 100644
--- a/docs/source/nnls_modeling.rst
+++ b/docs/source/nnls_modeling.rst
@@ -1,7 +1,7 @@
-.. default-domain:: cpp
-
.. highlight:: c++
+.. default-domain:: cpp
+
.. cpp:namespace:: ceres
.. _`chapter-nnls_modeling`:
@@ -83,11 +83,11 @@
virtual bool Evaluate(double const* const* parameters,
double* residuals,
double** jacobians) const = 0;
- const vector<int32>& parameter_block_sizes();
+ const std::vector<int32>& parameter_block_sizes();
int num_residuals() const;
protected:
- vector<int32>* mutable_parameter_block_sizes();
+ std::vector<int32>* mutable_parameter_block_sizes();
void set_num_residuals(int num_residuals);
};
@@ -842,7 +842,7 @@
// my_cost_function produces N residuals
CostFunction* my_cost_function = ...
CHECK_EQ(N, my_cost_function->num_residuals());
- vector<CostFunction*> conditioners;
+ std::vector<CostFunction*> conditioners;
// Make N 1x1 cost functions (1 parameter, 1 residual)
CostFunction* f_1 = ...
@@ -1190,7 +1190,7 @@
`corrector.cc <https://github.com/ceres-solver/ceres-solver/blob/master/internal/ceres/corrector.cc#L51>`_
-:class:`Manifolds`
+:class:`Manifold`
==================
.. class:: Manifold
@@ -2014,7 +2014,7 @@
on a :class:`Problem` with a non-null evaluation callback is an
error.
-.. function:: ResidualBlockId Problem::AddResidualBlock(CostFunction* cost_function, LossFunction* loss_function, const vector<double*> parameter_blocks)
+.. function:: ResidualBlockId Problem::AddResidualBlock(CostFunction* cost_function, LossFunction* loss_function, const std::vector<double*> parameter_blocks)
.. function:: template <typename Ts...> ResidualBlockId Problem::AddResidualBlock(CostFunction* cost_function, LossFunction* loss_function, double* x0, Ts... xs)
@@ -2055,9 +2055,9 @@
double x1[] = {1.0, 2.0, 3.0};
double x2[] = {1.0, 2.0, 5.0, 6.0};
double x3[] = {3.0, 6.0, 2.0, 5.0, 1.0};
- vector<double*> v1;
+ std::vector<double*> v1;
v1.push_back(x1);
- vector<double*> v2;
+ std::vector<double*> v2;
v2.push_back(x2);
v2.push_back(x1);
@@ -2234,24 +2234,24 @@
Is the given parameter block present in the problem or not?
-.. function:: void Problem::GetParameterBlocks(vector<double*>* parameter_blocks) const
+.. function:: void Problem::GetParameterBlocks(std::vector<double*>* parameter_blocks) const
Fills the passed ``parameter_blocks`` vector with pointers to the
parameter blocks currently in the problem. After this call,
``parameter_block.size() == NumParameterBlocks``.
-.. function:: void Problem::GetResidualBlocks(vector<ResidualBlockId>* residual_blocks) const
+.. function:: void Problem::GetResidualBlocks(std::vector<ResidualBlockId>* residual_blocks) const
Fills the passed `residual_blocks` vector with pointers to the
residual blocks currently in the problem. After this call,
`residual_blocks.size() == NumResidualBlocks`.
-.. function:: void Problem::GetParameterBlocksForResidualBlock(const ResidualBlockId residual_block, vector<double*>* parameter_blocks) const
+.. function:: void Problem::GetParameterBlocksForResidualBlock(const ResidualBlockId residual_block, std::vector<double*>* parameter_blocks) const
Get all the parameter blocks that depend on the given residual
block.
-.. function:: void Problem::GetResidualBlocksForParameterBlock(const double* values, vector<ResidualBlockId>* residual_blocks) const
+.. function:: void Problem::GetResidualBlocksForParameterBlock(const double* values, std::vector<ResidualBlockId>* residual_blocks) const
Get all the residual blocks that depend on the given parameter
block.
@@ -2327,7 +2327,7 @@
:func:`Problem::EvaluateResidualBlock`).
-.. function:: bool Problem::Evaluate(const Problem::EvaluateOptions& options, double* cost, vector<double>* residuals, vector<double>* gradient, CRSMatrix* jacobian)
+.. function:: bool Problem::Evaluate(const Problem::EvaluateOptions& options, double* cost, std::vector<double>* residuals, std::vector<double>* gradient, CRSMatrix* jacobian)
Evaluate a :class:`Problem`. Any of the output pointers can be
``nullptr``. Which residual blocks and parameter blocks are used is
@@ -2383,7 +2383,7 @@
Options struct that is used to control :func:`Problem::Evaluate`.
-.. member:: vector<double*> Problem::EvaluateOptions::parameter_blocks
+.. member:: std::vector<double*> Problem::EvaluateOptions::parameter_blocks
The set of parameter blocks for which evaluation should be
performed. This vector determines the order in which parameter
@@ -2399,7 +2399,7 @@
should NOT point to new memory locations. Bad things will happen if
you do.
-.. member:: vector<ResidualBlockId> Problem::EvaluateOptions::residual_blocks
+.. member:: std::vector<ResidualBlockId> Problem::EvaluateOptions::residual_blocks
The set of residual blocks for which evaluation should be
performed. This vector determines the order in which the residuals
diff --git a/docs/source/nnls_solving.rst b/docs/source/nnls_solving.rst
index 4b8b171..226e5f6 100644
--- a/docs/source/nnls_solving.rst
+++ b/docs/source/nnls_solving.rst
@@ -1,7 +1,7 @@
-.. default-domain:: cpp
-
.. highlight:: c++
+.. default-domain:: cpp
+
.. cpp:namespace:: ceres
.. _chapter-nnls_solving:
@@ -2091,6 +2091,13 @@
:member:`Solver::Options::update_state_every_iteration` to
``true``.
+ See `examples/iteration_callback_example.cc
+ <https://ceres-solver.googlesource.com/ceres-solver/+/master/examples/iteration_callback_example.cc>`_
+ for an example of an :class:`IterationCallback` that uses
+ :member:`Solver::Options::update_state_every_iteration` to log
+ changes to the parameter blocks over the course of the
+ optimization.
+
The solver does NOT take ownership of these pointers.
:class:`ParameterBlockOrdering`
@@ -2307,6 +2314,10 @@
#. ``SOLVER_CONTINUE`` indicates that the solver should continue
optimizing.
+ The return values can be used to implement custom termination
+ criterion that supercede the iteration/time/tolerance based
+ termination implemented by Ceres.
+
For example, the following :class:`IterationCallback` is used
internally by Ceres to log the progress of the optimization.
@@ -2346,6 +2357,12 @@
};
+ See `examples/evaluation_callback_example.cc
+ <https://ceres-solver.googlesource.com/ceres-solver/+/master/examples/iteration_callback_example.cc>`_
+ for another example that uses
+ :member:`Solver::Options::update_state_every_iteration` to log
+ changes to the parameter blocks over the course of the optimization.
+
:class:`CRSMatrix`
==================
diff --git a/docs/source/nnls_tutorial.rst b/docs/source/nnls_tutorial.rst
index ba68a78..3268e71 100644
--- a/docs/source/nnls_tutorial.rst
+++ b/docs/source/nnls_tutorial.rst
@@ -2,6 +2,8 @@
.. default-domain:: cpp
+.. cpp:namespace:: ceres
+
.. _chapter-nnls_tutorial:
========================
