Squashed 'third_party/ceres/' changes from e51e9b46f..399cda773
399cda773 Update build documentation to reflect detection of Eigen via config mode
bb127272f Fix typos.
a0ec5c32a Update version history for 2.0.0RC2
3f6d27367 Unify symbol visibility configuration for all compilers
29c2912ee Unbreak the bazel build some more
bf47e1a36 Fix the Bazel build.
600e8c529 fix minor typos
bdcdcc78a update docs for changed cmake usage
3f69e5b36 Corrections from William Rucklidge
8bfdb02fb Rewrite uses of VLOG_IF and LOG_IF.
d1b35ffc1 Corrections from William Rucklidge
f34e80e91 Add dividers between licenses.
65c397dae Fix formatting
f63b1fea9 Add the MIT license text corresponding to the libmv derived files.
542613c13 minor formatting fix for trust_region_minimizer.cc
6d9e9843d Remove inclusion of ceres/eigen.h
eafeca5dc Fix a logging bug in TrustRegionMinimizer.
1fd0be916 Fix default initialisation of IterationCallback::cost
137bbe845 add info about clang-format to contributing docs
d3f66d77f fix formatting generated files (best effort)
a9c7361c8 minor formatting fix (wrongly updated in earlier commit)
7b8f675bf fix formatting for (non-generated) internal source files
921368ce3 Fix a number of typos in covariance.h
7b6b2491c fix formatting for examples
82275d8a4 some fixes for Linux and macOS install docs
9d762d74f fix formatting for public header files
c76478c48 gitignore *.pyc
4e69a475c Fix potential for mismatched release/debug TBB libraries
8e1d8e32a A number of small changes.
368a738e5 AutoDiffCostFunction: optional ownership
8cbd721c1 Add erf and erfc to jet.h, including tests in jet_test.cc
31366cff2 Benchmarks for dynamic autodiff.
29fb08aea Use CMAKE_PREFIX_PATH to pass Homebrew install location
242c703b5 Minor fixes to the documentation
79bbf9510 Add changelog for 2.0.0
41d05f13d Fix lint errors in evaluation_callback_test.cc
4b67903c1 Remove unused variables from problem_test.cc
10449fc36 Add Apache license to the LICENSE file for FixedArray
8c3ecec6d Fix some minor errors in IterationCallback docs
7d3ffcb42 Remove forced CONFIG from find_package(Eigen3)
a029fc0f9 Use latest FindTBB.cmake from VTK project
aa1abbc57 Replace use of GFLAGS_LIBRARIES with export gflags target
db2af1be8 Add Problem::EvaluateResidualBlockAssumingParametersUnchanged
ab4ed32cd Replace NULL with nullptr in the documentation.
ee280e27a Allow SubsetParameterization to accept an empty vector of constant parameters.
4b8c731d8 Fix a bug in DynamicAutoDiffCostFunction
5cb5b35a9 Fixed incorrect argument name in RotationMatrixToQuaternion()
e39d9ed1d Add a missing term and remove a superfluous word
27cab77b6 Reformulate some sentences
8ac6655ce Fix documentation formatting issues
7ef83e075 Update minimum required C++ version for Ceres to C++14
1d75e7568 Improve documentation for LocalParameterization
763398ca4 Update the section on Preconditioners
a614f788a Call EvaluationCallback before evaluating the fixed cost.
70308f7bb Simplify documentation generation.
e886d7e65 Reduce the number of minimizer iterations in evaluation_callback_test.cc
9483e6f2f Simplify DynamicCompressedRowJacobianWriter::Write
323cc55bb Update the version in package.xml to 2.0.0.
303b078b5 Fix few typos and alter a NULL to nullptr.
cca93fed6 Bypass Ceres' FindGlog.cmake in CeresConfig.cmake if possible
77fc1d0fc Use build_depend for private dependencies in Catkin package.xml
a09682f00 Fix MSVC version check to support use of clang-cl front-end
b70687fcc Add namespace qualified Ceres::ceres CMake target
99efa54bd Replace type aliases deprecated/removed in C++17/C++20 from FixedArray
adb973e4a NULL -> nullptr
27b717951 Respect FIND_QUIETLY flag in cmake config file
646959ef1 Do not export class template LineParameterization
1f128d070 Change the type of parameter index/offset to match their getter/setter
072c8f070 Initialize integer variables with integer instead of double
8c36bcc81 Use inline & -inlinehint-threshold in auto-diff benchmarks
57cf20aa5 static const -> static constexpr where we can.
40b27482a Add std::numeric_limit specialization for Jets
e751d6e4f Remove AutodiffCodegen
e9eb76f8e Remove AutodiffCodegen CMake integration
9435e08a7 More clang-tidy and wjr@ comment fixes
d93fac4b7 Remove AutodiffCodegen Tests
2281c6ed2 Fixes for comments from William Rucklidge
d797a87a4 Use Ridders' method in GradientChecker.
41675682d Fix a MSVC type deduction bug in ComputeHouseholderVector
947ec0c1f Remove AutodiffCodegen autodiff benchmarks
27183d661 Allow LocalParameterizations to have zero local size.
7ac7d79dc Remove HelloWorldCodegen example
8c8738bf8 Add photometric and relative-pose residuals to autodiff benchmarks
9f7fb66d6 Add a constant cost function to the autodiff benchmarks
ab0d373e4 Fix a comment in autodiff.h
27bb99714 Change SVD algorithm in covariance computation.
84fdac38e Add const to GetCovarianceMatrix*
6bde61d6b Add line local parameterization.
2c1c0932e Update documentation in autodiff.h
8904fa488 Inline Jet initialization in Autodiff
18a464d4e Remove an errant CR from local_parameterization.cc
5c85f2179 Use ArraySelector in Autodiff
80477ff07 Add class ArraySelector
e7a30359e Pass kNumResiduals to Autodiff
f339d71dd Refactor the automatic differentiation benchmarks.
d37b4cb15 Fix some include headers in codegen/test_utils.cc/h
550766e6d Add Autodiff Brdf Benchmark
8da9876e7 Add more autodiff benchmarks
6da364713 Fix Tukey loss function
cf4185c4e Add Codegen BA Benchmark
75dd30fae Simplify GenerateCodeForFunctor
9049688c6 Default Initialize ExpressionRef to Zero
bf1aff2f0 Fix 3+ nested Jet constructor
92d6541c7 Move Codegen files into codegen/ directory
8e962f37d Add Autodiff Codegen Tests
13c7a22ce Codegen Optimizer API
90799e29e Fix install and unnecessary string copy
032d5844c AutoDiff Code Generation - CMake Integration
d82de91b8 Add ExpressionGraph::Erase(ExpressionId)
c8e35e19f Add namespaces to generated functions and constants
75e575cae Fix use of incomplete type in defaulted Problem methods
8def19616 Remove ExpressionRef Move Constructor
f26f95410 Fix windows MSVC build.
fdf9cfd32 Add functions to find the matching ELSE, ENDIF expressions
678c05b28 Fix invert PSD matrix.
a384a7e96 Remove not used using declaration
a60136b7a Add COMMENT ExpressionType
f212c9295 Let Problem::SetParameterization be called more than once.
a3696835b use CMake function to create CeresConfigVersion
67fcff918 Make Problem movable.
19728e72d Add documentation for Problem::IsParameterBlockConstant
ba6e5fb4a Make the custom uninstall target optional
8547cbd55 Make EventLogger more efficient.
edb8322bd Update the minimum required version of Eigen to 3.3.
aa6ef417f Specify Eigen3_DIR in iOS and Android Travis CI builds
4655f2549 Use find_package() instead of find_dependency() in CeresConfig.cmake
a548766d1 Use glfags target
33dd469a5 Use Eigen3::Eigen target
47e784bb4 NULL-jacobians are handled correctly in generated autodiff code
edd54b83e Update Jet.h and rotation.h to use the new IF/ELSE macros
848c1f90c Update return type in code generator and add tests for logical functions
5010421bb Add the expression return type as a member to Expression
f4dc670ee Improve testing of the codegen system
572ec4a5a Rework Expression creation and insertion
c7337154e Disable the code generation module by default
7fa0f3db4 Explicitly state PUBLIC/PRIVATE when linking
4362a2169 Run clang-format on the public headers. Also update copyright year.
c56702aac Fix installation of codegen headers
0d03e74dc Fix the include in the autodiff codegen example
d16026440 Autodiff Codegen Part 4: Public API
d1703db45 Moved AutoDiffCodeGen macros to a separate (public) header
5ce6c063d Fix ExpressionRef copy constructor and add a move constructor
a90b5a12c Pass ExpressionRef by const reference instead of by value
ea057678c Remove MakeFunctionCall() and add test for Ternary
1084c5460 Quote all configure-expanded paths
3d756b07c Test Expressions with 'insert' instead of a macro
486d81812 Add ExpressionGraph::InsertExpression
3831a1dd3 Expression and ExpressionGraph comparison
9bb1dcb84 Remove definition of ExpressionRef::ExpressionRef(double&);
5be2e4883 Autodiff Codegen Part 3: CodeGenerator
6cd633043 Remove unused ExpressionTypes
7d0d69a4d Fix ExpressionRef
6ba8c57d2 Fix expression_test IsArithmetic
2b494cfb3 Update Travis CI to Bionic & Xcode 11.2
a3dde6877 Require Xcode >= 11.2 on macOS 10.15 (Catalina)
6fd4f072d Autodiff Codegen Part 2: Conditionals
52d6477a4 Detect and disable -fstack-check on macOS 10.15 with Xcode 11
46ca461b7 Fix `gradient_check_relative_precision` docs typo
4247d420f Autodiff Codegen Part 1: Expressions
ba62397d8 Run clang-format on jet.h
667062dcc Introduce BlockSparseMatrixData
17becf461 Remove a CHECK failure from covariance_impl.cc
d7f428e5c Add a missing cast in rotation.h
ea4d66e7e clang-tidy fixes.
be15b842a Integrate the SchurEliminatorForOneFBlock for the case <2,3,6>
087b28f1b Remove use of SetUsage as it creates compilation problems.
573046d7f Protect declarations of lapack functions under CERES_NO_LAPACK
71d638ef3 Add a specialized schur eliminator.
2ffddaccf Use override & final instead of just using virtual.
e4577dd6d Use override instead of virtual for subclasses.
3e5db5bc2 Fixing documentation typo.
82d325b73 Avoid memory allocations in Accelerate Sparse[Refactor/Solve]().
f66b51382 Fix some clang-tidy warnings.
0428e2dd0 Fix missing #include of <memory>
487c1aa51 Expose SubsetPreconditioner in the API
bf709ecac Move EvaluationCallback from Solver::Options to Problem::Options.
059bcb7f8 Drop ROS dependency on catkin
c4dbc927d Default to any other sparse libraries over Accelerate
db1f5b57a Allow some methods in Problem to use const double*.
a60c14525 Explicitly delete the copy constructor and copy assignment operator
084042c25 Lint changes from William Rucklidge
93d869020 Use selfAdjoingView<Upper> in InvertPSDMatrix.
a0cd0854a Speed up InvertPSDMatrix
7b53262b7 Allow Solver::Options::max_num_line_search_step_size_iterations = 0.
3e2cdca54 Make LineSearchMinizer work correctly with negative valued functions.
3ff12a878 Fix a clang-tidy warning in problem_test.cc
57441fe90 Fix two bugs.
1b852c57e Add Problem::EvaluateResidualBlock.
54ba6c27b Fix missing declaration warnings in Ceres code
fac46d50e Modernize ProductParameterization.
53dc6213f Add some missing string-to-enum-to-string convertors.
c0aa9a263 Add checks in rotation.h for inplace operations.
0f57fa82d Update Bazel WORKSPACE for newest Bazel
f8e5fba7b TripletSparseMatrix: guard against self-assignment
939253c20 Fix Eigen alignment issues.
bf67daf79 Add the missing <array> header to fixed_array.h
25e1cdbb6 Switch to FixedArray implementation from abseil.
d467a627b IdentityTransformation -> IdentityParameterization
eaec6a9d0 Fix more typos in CostFunctionToFunctor documentation.
99b5aa4aa Fix typos in CostFunctionToFunctor documentation.
ee7e2cb3c Set Homebrew paths via HINTS not CMAKE_PREFIX_PATH
4f8a01853 Revert "Fix custom Eigen on macos (EIGEN_INCLUDE_DIR_HINTS)"
e6c5c7226 Fix custom Eigen on macos (EIGEN_INCLUDE_DIR_HINTS)
5a56d522e Add the 3,3,3 template specialization.
df5c23116 Reorder initializer list to make -Wreorder happy
0fcfdb0b4 Fix the build breakage caused by the last commit.
9b9e9f0dc Reduce machoness of macro definition in cost_functor_to_function_test.cc
21d40daa0 Remove UTF-8 chars
9350e57a4 Enable optional use of sanitizers
0456edffb Update Travis CI Linux distro to 16.04 (Xenial)
bef0dfe35 Fix a typo in cubic_interpolation.h
056ba9bb1 Add AutoDiffFirstOrderFunction
6e527392d Update googletest/googlemock to db9b85e2.
1b2940749 Clarify documentation of BiCubicInterpolator::Evaluate for out-of-bounds values
Change-Id: Id61dd832e8fbe286deb0799aa1399d4017031dae
git-subtree-dir: third_party/ceres
git-subtree-split: 399cda773035d99eaf1f4a129a666b3c4df9d1b1
diff --git a/docs/source/nnls_solving.rst b/docs/source/nnls_solving.rst
index 713d54d..285df3a 100644
--- a/docs/source/nnls_solving.rst
+++ b/docs/source/nnls_solving.rst
@@ -58,8 +58,8 @@
algorithms can be divided into two major categories [NocedalWright]_.
1. **Trust Region** The trust region approach approximates the
- objective function using using a model function (often a quadratic)
- over a subset of the search space known as the trust region. If the
+ objective function using a model function (often a quadratic) over
+ a subset of the search space known as the trust region. If the
model function succeeds in minimizing the true objective function
the trust region is expanded; conversely, otherwise it is
contracted and the model optimization problem is solved again.
@@ -166,10 +166,10 @@
will assume that the matrix :math:`\frac{1}{\sqrt{\mu}} D` has been concatenated
at the bottom of the matrix :math:`J` and similarly a vector of zeros
has been added to the bottom of the vector :math:`f` and the rest of
-our discussion will be in terms of :math:`J` and :math:`f`, i.e, the
+our discussion will be in terms of :math:`J` and :math:`F`, i.e, the
linear least squares problem.
-.. math:: \min_{\Delta x} \frac{1}{2} \|J(x)\Delta x + f(x)\|^2 .
+.. math:: \min_{\Delta x} \frac{1}{2} \|J(x)\Delta x + F(x)\|^2 .
:label: simple
For all but the smallest problems the solution of :eq:`simple` in
@@ -648,11 +648,11 @@
access to :math:`S` via its product with a vector, one way to
evaluate :math:`Sx` is to observe that
- .. math:: x_1 &= E^\top x
- .. math:: x_2 &= C^{-1} x_1
- .. math:: x_3 &= Ex_2\\
- .. math:: x_4 &= Bx\\
- .. math:: Sx &= x_4 - x_3
+ .. math:: x_1 &= E^\top x\\
+ x_2 &= C^{-1} x_1\\
+ x_3 &= Ex_2\\
+ x_4 &= Bx\\
+ Sx &= x_4 - x_3
:label: schurtrick1
Thus, we can run PCG on :math:`S` with the same computational
@@ -693,7 +693,7 @@
.. _section-preconditioner:
Preconditioner
---------------
+==============
The convergence rate of Conjugate Gradients for
solving :eq:`normal` depends on the distribution of eigenvalues
@@ -726,34 +726,96 @@
based preconditioners have much better convergence behavior than the
Jacobi preconditioner, but are also much more expensive.
+For a survey of the state of the art in preconditioning linear least
+squares problems with general sparsity structure see [GouldScott]_.
+
+Ceres Solver comes with an number of preconditioners suited for
+problems with general sparsity as well as the special sparsity
+structure encountered in bundle adjustment problems.
+
+``JACOBI``
+----------
+
The simplest of all preconditioners is the diagonal or Jacobi
preconditioner, i.e., :math:`M=\operatorname{diag}(A)`, which for
block structured matrices like :math:`H` can be generalized to the
-block Jacobi preconditioner. Ceres implements the block Jacobi
-preconditioner and refers to it as ``JACOBI``. When used with
-:ref:`section-cgnr` it refers to the block diagonal of :math:`H` and
-when used with :ref:`section-iterative_schur` it refers to the block
-diagonal of :math:`B` [Mandel]_.
+block Jacobi preconditioner. The ``JACOBI`` preconditioner in Ceres
+when used with :ref:`section-cgnr` refers to the block diagonal of
+:math:`H` and when used with :ref:`section-iterative_schur` refers to
+the block diagonal of :math:`B` [Mandel]_. For detailed performance
+data about the performance of ``JACOBI`` on bundle adjustment problems
+see [Agarwal]_.
+
+
+``SCHUR_JACOBI``
+----------------
Another obvious choice for :ref:`section-iterative_schur` is the block
diagonal of the Schur complement matrix :math:`S`, i.e, the block
-Jacobi preconditioner for :math:`S`. Ceres implements it and refers to
-is as the ``SCHUR_JACOBI`` preconditioner.
+Jacobi preconditioner for :math:`S`. In Ceres we refer to it as the
+``SCHUR_JACOBI`` preconditioner. For detailed performance data about
+the performance of ``SCHUR_JACOBI`` on bundle adjustment problems see
+[Agarwal]_.
+
+
+``CLUSTER_JACOBI`` and ``CLUSTER_TRIDIAGONAL``
+----------------------------------------------
For bundle adjustment problems arising in reconstruction from
community photo collections, more effective preconditioners can be
constructed by analyzing and exploiting the camera-point visibility
-structure of the scene [KushalAgarwal]_. Ceres implements the two
-visibility based preconditioners described by Kushal & Agarwal as
-``CLUSTER_JACOBI`` and ``CLUSTER_TRIDIAGONAL``. These are fairly new
-preconditioners and Ceres' implementation of them is in its early
-stages and is not as mature as the other preconditioners described
-above.
+structure of the scene.
+
+The key idea is to cluster the cameras based on the visibility
+structure of the scene. The similarity between a pair of cameras
+:math:`i` and :math:`j` is given by:
+
+ .. math:: S_{ij} = \frac{|V_i \cap V_j|}{|V_i| |V_j|}
+
+Here :math:`V_i` is the set of scene points visible in camera
+:math:`i`. This idea was first exploited by [KushalAgarwal]_ to create
+the ``CLUSTER_JACOBI`` and the ``CLUSTER_TRIDIAGONAL`` preconditioners
+which Ceres implements.
+
+The performance of these two preconditioners depends on the speed and
+clustering quality of the clustering algorithm used when building the
+preconditioner. In the original paper, [KushalAgarwal]_ used the
+Canonical Views algorithm [Simon]_, which while producing high quality
+clusterings can be quite expensive for large graphs. So, Ceres
+supports two visibility clustering algorithms - ``CANONICAL_VIEWS``
+and ``SINGLE_LINKAGE``. The former is as the name implies Canonical
+Views algorithm of [Simon]_. The latter is the the classic `Single
+Linkage Clustering
+<https://en.wikipedia.org/wiki/Single-linkage_clustering>`_
+algorithm. The choice of clustering algorithm is controlled by
+:member:`Solver::Options::visibility_clustering_type`.
+
+``SUBSET``
+----------
+
+This is a preconditioner for problems with general sparsity. Given a
+subset of residual blocks of a problem, it uses the corresponding
+subset of the rows of the Jacobian to construct a preconditioner
+[Dellaert]_.
+
+Suppose the Jacobian :math:`J` has been horizontally partitioned as
+
+ .. math:: J = \begin{bmatrix} P \\ Q \end{bmatrix}
+
+Where, :math:`Q` is the set of rows corresponding to the residual
+blocks in
+:member:`Solver::Options::residual_blocks_for_subset_preconditioner`. The
+preconditioner is the matrix :math:`(Q^\top Q)^{-1}`.
+
+The efficacy of the preconditioner depends on how well the matrix
+:math:`Q` approximates :math:`J^\top J`, or how well the chosen
+residual blocks approximate the full problem.
+
.. _section-ordering:
Ordering
---------
+========
The order in which variables are eliminated in a linear solver can
have a significant of impact on the efficiency and accuracy of the
@@ -992,6 +1054,11 @@
search, if a step size satisfying the search conditions cannot be
found within this number of trials, the line search will stop.
+ The minimum allowed value is 0 for trust region minimizer and 1
+ otherwise. If 0 is specified for the trust region minimizer, then
+ line search will not be used when solving constrained optimization
+ problems.
+
As this is an 'artificial' constraint (one imposed by the user, not
the underlying math), if ``WOLFE`` line search is being used, *and*
points satisfying the Armijo sufficient (function) decrease
@@ -1125,7 +1192,7 @@
.. member:: double Solver::Options::min_lm_diagonal
- Default: ``1e6``
+ Default: ``1e-6``
The ``LEVENBERG_MARQUARDT`` strategy, uses a diagonal matrix to
regularize the trust region step. This is the lower bound on
@@ -1229,6 +1296,29 @@
recommend that you try ``CANONICAL_VIEWS`` first and if it is too
expensive try ``SINGLE_LINKAGE``.
+.. member:: std::unordered_set<ResidualBlockId> residual_blocks_for_subset_preconditioner
+
+ ``SUBSET`` preconditioner is a preconditioner for problems with
+ general sparsity. Given a subset of residual blocks of a problem,
+ it uses the corresponding subset of the rows of the Jacobian to
+ construct a preconditioner.
+
+ Suppose the Jacobian :math:`J` has been horizontally partitioned as
+
+ .. math:: J = \begin{bmatrix} P \\ Q \end{bmatrix}
+
+ Where, :math:`Q` is the set of rows corresponding to the residual
+ blocks in
+ :member:`Solver::Options::residual_blocks_for_subset_preconditioner`. The
+ preconditioner is the matrix :math:`(Q^\top Q)^{-1}`.
+
+ The efficacy of the preconditioner depends on how well the matrix
+ :math:`Q` approximates :math:`J^\top J`, or how well the chosen
+ residual blocks approximate the full problem.
+
+ If ``Solver::Options::preconditioner_type == SUBSET``, then
+ ``residual_blocks_for_subset_preconditioner`` must be non-empty.
+
.. member:: DenseLinearAlgebraLibrary Solver::Options::dense_linear_algebra_library_type
Default:``EIGEN``
@@ -1408,6 +1498,10 @@
on each Newton/Trust region step using a coordinate descent
algorithm. For more details, see :ref:`section-inner-iterations`.
+ **Note** Inner iterations cannot be used with :class:`Problem`
+ objects that have an :class:`EvaluationCallback` associated with
+ them.
+
.. member:: double Solver::Options::inner_iteration_tolerance
Default: ``1e-3``
@@ -1559,7 +1653,7 @@
.. member:: double Solver::Options::gradient_check_relative_precision
- Default: ``1e08``
+ Default: ``1e-8``
Precision to check for in the gradient checker. If the relative
difference between an element in a Jacobian exceeds this number,
@@ -1598,63 +1692,40 @@
which break this finite difference heuristic, but they do not come
up often in practice.
-.. member:: vector<IterationCallback> Solver::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:`Solver::Options::update_state_every_iteration`. If the user
- wishes to have access to the updated parameter blocks when his/her
- callbacks are executed, then set
- :member:`Solver::Options::update_state_every_iteration` to true.
-
- The solver does NOT take ownership of these pointers.
-
.. member:: bool Solver::Options::update_state_every_iteration
Default: ``false``
- If true, the user's parameter blocks are updated at the end of
- every Minimizer iteration, otherwise they are updated when the
- Minimizer terminates. This is useful if, for example, the user
- wishes to visualize the state of the optimization every iteration
- (in combination with an IterationCallback).
+ If ``update_state_every_iteration`` is ``true``, then Ceres Solver
+ will guarantee that at the end of every iteration and before any
+ user :class:`IterationCallback` is called, the parameter blocks are
+ updated to the current best solution found by the solver. Thus the
+ IterationCallback can inspect the values of the parameter blocks
+ for purposes of computation, visualization or termination.
- **Note**: If :member:`Solver::Options::evaluation_callback` is set,
- then the behaviour of this flag is slightly different in each case:
+ If ``update_state_every_iteration`` is ``false`` then there is no
+ such guarantee, and user provided :class:`IterationCallback` s
+ should not expect to look at the parameter blocks and interpret
+ their values.
- 1. If :member:`Solver::Options::update_state_every_iteration` is
- false, then the user's state is changed at every residual and/or
- jacobian evaluation. Any user provided IterationCallbacks should
- **not** inspect and depend on the user visible state while the
- solver is running, since they it have undefined contents.
+.. member:: vector<IterationCallback> Solver::Options::callbacks
- 2. If :member:`Solver::Options::update_state_every_iteration` is
- false, then the user's state is changed at every residual and/or
- jacobian evaluation, BUT the solver will ensure that before the
- user provided `IterationCallbacks` are called, the user visible
- state will be updated to the current best point found by the
- solver.
+ 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.
-.. member:: bool Solver::Options::evaluation_callback
+ By default, parameter blocks are updated only at the end of the
+ optimization, i.e., when the :class:`Minimizer` terminates. This
+ means that by default, if an :class:`IterationCallback` inspects
+ the parameter blocks, they will not see them changing in the course
+ of the optimization.
- Default: ``NULL``
+ To tell Ceres to update the parameter blocks at the end of each
+ iteration and before calling the user's callback, set
+ :member:`Solver::Options::update_state_every_iteration` to
+ ``true``.
- If non-``NULL``, gets notified when Ceres is about to evaluate the
- residuals and/or Jacobians. This enables sharing computation between
- residuals, which in some cases is important for efficient cost
- evaluation. See :class:`EvaluationCallback` for details.
-
- **Note**: Evaluation callbacks are incompatible with inner
- iterations.
-
- **Warning**: This interacts with
- :member:`Solver::Options::update_state_every_iteration`. See the
- documentation for that option for more details.
-
- The solver does `not` take ownership of the pointer.
+ The solver does NOT take ownership of these pointers.
:class:`ParameterBlockOrdering`
===============================
@@ -1715,62 +1786,6 @@
Number of groups with one or more elements.
-:class:`EvaluationCallback`
-===========================
-
-.. class:: EvaluationCallback
-
- Interface for receiving callbacks before Ceres evaluates residuals or
- Jacobians:
-
- .. code-block:: c++
-
- class EvaluationCallback {
- public:
- virtual ~EvaluationCallback() {}
- virtual void PrepareForEvaluation()(bool evaluate_jacobians
- bool new_evaluation_point) = 0;
- };
-
- ``PrepareForEvaluation()`` is called before Ceres requests residuals
- or jacobians for a given setting of the parameters. User parameters
- (the double* values provided to the cost functions) are fixed until
- the next call to ``PrepareForEvaluation()``. If
- ``new_evaluation_point == true``, then this is a new point that is
- different from the last evaluated point. Otherwise, it is the same
- point that was evaluated previously (either jacobian or residual) and
- the user can use cached results from previous evaluations. If
- ``evaluate_jacobians`` is true, then Ceres will request jacobians in
- the upcoming cost evaluation.
-
- Using this callback interface, Ceres can notify you when it is about
- to evaluate the residuals or jacobians. With the callback, you can
- share computation between residual blocks by doing the shared
- computation in PrepareForEvaluation() before Ceres calls
- CostFunction::Evaluate() on all the residuals. It also enables
- caching results between a pure residual evaluation and a residual &
- jacobian evaluation, via the new_evaluation_point argument.
-
- One use case for this callback is if the cost function compute is
- moved to the GPU. In that case, the prepare call does the actual cost
- function evaluation, and subsequent calls from Ceres to the actual
- cost functions merely copy the results from the GPU onto the
- corresponding blocks for Ceres to plug into the solver.
-
- **Note**: Ceres provides no mechanism to share data other than the
- notification from the callback. Users must provide access to
- pre-computed shared data to their cost functions behind the scenes;
- this all happens without Ceres knowing. One approach is to put a
- pointer to the shared data in each cost function (recommended) or to
- use a global shared variable (discouraged; bug-prone). As far as
- Ceres is concerned, it is evaluating cost functions like any other;
- it just so happens that behind the scenes the cost functions reuse
- pre-computed data to execute faster.
-
- See ``evaluation_callback_test.cc`` for code that explicitly verifies
- the preconditions between ``PrepareForEvaluation()`` and
- ``CostFunction::Evaluate()``.
-
:class:`IterationCallback`
==========================
@@ -1779,7 +1794,7 @@
:class:`IterationSummary` describes the state of the minimizer at
the end of each iteration.
-.. member:: int32 IterationSummary::iteration
+.. member:: int IterationSummary::iteration
Current iteration number.
@@ -2211,7 +2226,7 @@
Number of threads actually used by the solver for Jacobian and
residual evaluation. This number is not equal to
:member:`Solver::Summary::num_threads_given` if none of `OpenMP`
- or `CXX11_THREADS` is available.
+ or `CXX_THREADS` is available.
.. member:: LinearSolverType Solver::Summary::linear_solver_type_given