diff --git a/docs/source/gradient_solver.rst b/docs/source/gradient_solver.rst index 81c5a560d..4e3fc7171 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 @@ Solving 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 @@ Solving #. ``it`` is the time take by the current iteration. #. ``tt`` is the total time taken by the minimizer. -.. member:: vector GradientProblemSolver::Options::callbacks +.. member:: std::vector 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 @@ Solving 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 @@ Solving 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 @@ Solving Cost of the problem (value of the objective function) after the optimization. -.. member:: vector GradientProblemSolver::Summary::iterations +.. member:: std::vector 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 fb26cb76c..261a5e978 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 a2704d86d..2e4f6f2cf 100644 --- a/docs/source/modeling_faqs.rst +++ b/docs/source/modeling_faqs.rst @@ -37,7 +37,7 @@ Modeling automatic and numeric differentiation. See :class:`CostFunctionToFunctor`. -#. When using Quaternions, consider using :class:`QuaternionParameterization`. +#. When using Quaternions, consider using :class:`QuaternionManifold`. `Quaternions `_ are a four dimensional parameterization of the space of three dimensional @@ -47,14 +47,14 @@ Modeling 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 `_ 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 @@ Modeling 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 2c3c05dba..ece6f58ab 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 @@ Where :math:`S` is a positive semi-definite matrix denoting the 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 @@ cases. entire documentation for :class:`Covariance::Options` before using :class:`Covariance`. -.. function:: bool Covariance::Compute(const vector >& covariance_blocks, Problem* problem) +.. function:: bool Covariance::Compute(const std::vector >& covariance_blocks, Problem* problem) Compute a part of the covariance matrix. @@ -378,7 +379,7 @@ Example Usage Covariance::Options options; Covariance covariance(options); - vector > covariance_blocks; + std::vector > 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 e393148b4..512834c8c 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 @@ Then, given :math:`\left[x_{1}, ... , x_{k}\right]`, virtual bool Evaluate(double const* const* parameters, double* residuals, double** jacobians) const = 0; - const vector& parameter_block_sizes(); + const std::vector& parameter_block_sizes(); int num_residuals() const; protected: - vector* mutable_parameter_block_sizes(); + std::vector* mutable_parameter_block_sizes(); void set_num_residuals(int num_residuals); }; @@ -842,7 +842,7 @@ Numeric Differentiation & Manifolds // my_cost_function produces N residuals CostFunction* my_cost_function = ... CHECK_EQ(N, my_cost_function->num_residuals()); - vector conditioners; + std::vector conditioners; // Make N 1x1 cost functions (1 parameter, 1 residual) CostFunction* f_1 = ... @@ -1190,7 +1190,7 @@ performance, so we upper bound it by zero. For more details see `corrector.cc `_ -:class:`Manifolds` +:class:`Manifold` ================== .. class:: Manifold @@ -2014,7 +2014,7 @@ be constructed as 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 parameter_blocks) +.. function:: ResidualBlockId Problem::AddResidualBlock(CostFunction* cost_function, LossFunction* loss_function, const std::vector parameter_blocks) .. function:: template ResidualBlockId Problem::AddResidualBlock(CostFunction* cost_function, LossFunction* loss_function, double* x0, Ts... xs) @@ -2055,9 +2055,9 @@ be constructed as 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 v1; + std::vector v1; v1.push_back(x1); - vector v2; + std::vector v2; v2.push_back(x2); v2.push_back(x1); @@ -2234,24 +2234,24 @@ be constructed as Is the given parameter block present in the problem or not? -.. function:: void Problem::GetParameterBlocks(vector* parameter_blocks) const +.. function:: void Problem::GetParameterBlocks(std::vector* 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* residual_blocks) const +.. function:: void Problem::GetResidualBlocks(std::vector* 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* parameter_blocks) const +.. function:: void Problem::GetParameterBlocksForResidualBlock(const ResidualBlockId residual_block, std::vector* parameter_blocks) const Get all the parameter blocks that depend on the given residual block. -.. function:: void Problem::GetResidualBlocksForParameterBlock(const double* values, vector* residual_blocks) const +.. function:: void Problem::GetResidualBlocksForParameterBlock(const double* values, std::vector* residual_blocks) const Get all the residual blocks that depend on the given parameter block. @@ -2327,7 +2327,7 @@ be constructed as :func:`Problem::EvaluateResidualBlock`). -.. function:: bool Problem::Evaluate(const Problem::EvaluateOptions& options, double* cost, vector* residuals, vector* gradient, CRSMatrix* jacobian) +.. function:: bool Problem::Evaluate(const Problem::EvaluateOptions& options, double* cost, std::vector* residuals, std::vector* 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 @@ be constructed as Options struct that is used to control :func:`Problem::Evaluate`. -.. member:: vector Problem::EvaluateOptions::parameter_blocks +.. member:: std::vector 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 @@ be constructed as should NOT point to new memory locations. Bad things will happen if you do. -.. member:: vector Problem::EvaluateOptions::residual_blocks +.. member:: std::vector 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 4b8b1715a..226e5f6de 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 @@ b. ``linear_solver_type = SPARSE_SCHUR/DENSE_SCHUR/ITERATIVE_SCHUR`` :member:`Solver::Options::update_state_every_iteration` to ``true``. + See `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 @@ b. ``linear_solver_type = SPARSE_SCHUR/DENSE_SCHUR/ITERATIVE_SCHUR`` #. ``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 @@ b. ``linear_solver_type = SPARSE_SCHUR/DENSE_SCHUR/ITERATIVE_SCHUR`` }; + See `examples/evaluation_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 ba68a7815..3268e71d7 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: ========================