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: ========================