Add documentation about CostFunction::Evaluate. Change-Id: I1df42c14f20c7c03f2a8ae21e75dda98cc592214
diff --git a/docs/source/modeling.rst b/docs/source/modeling.rst index a34e696..8773d62 100644 --- a/docs/source/modeling.rst +++ b/docs/source/modeling.rst
@@ -107,6 +107,24 @@ :math:`i^{\textrm{th}}` parameter block must not be returned, this is the case when the a parameter block is marked constant. + **NOTE** The return value indicates whether the computation of the + residuals and/or jacobians was successful or not. + + This can be used to communicate numerical failures in Jacobian + computations for instance. + + A more interesting and common use is to impose constraints on the + parameters. If the initial values of the parameter blocks satisfy + the constraints, then returning false whenever the constraints are + not satisfied will prevent the solver from moving into the + infeasible region. This is not a very sophisticated mechanism for + enforcing constraints, but is often good enough for things like + non-negativity constraints. + + Note that it is important that the initial values of the parameter + block must be feasible, otherwise the solver will declare a + numerical problem at iteration 0. + :class:`SizedCostFunction` -------------------------- @@ -151,6 +169,9 @@ The function must write the computed value in the last argument (the only non-``const`` one) and return true to indicate success. + Please see :class:`CostFunction` for details on how the return + value may be used to impose simple constraints on the parameter + block. For example, consider a scalar error :math:`e = k - x^\top y`, where both :math:`x` and :math:`y` are two-dimensional vector @@ -257,7 +278,9 @@ must define a class with a ``operator()`` (a functor) that computes the residuals. The functor must write the computed value in the last argument (the only non-``const`` one) and return ``true`` to - indicate success. e.g., an object of the form + indicate success. Please see :class:`CostFunction` for details on + how the return value may be used to impose simple constraints on + the parameter block. e.g., an object of the form .. code-block:: c++
diff --git a/include/ceres/autodiff_cost_function.h b/include/ceres/autodiff_cost_function.h index e758d3a..2cc3f50 100644 --- a/include/ceres/autodiff_cost_function.h +++ b/include/ceres/autodiff_cost_function.h
@@ -40,8 +40,11 @@ // this is hidden, and you should write the function as if T were a scalar type // (e.g. a double-precision floating point number). // -// The function must write the computed value in the last argument (the only -// non-const one) and return true to indicate success. +// The function must write the computed value in the last argument +// (the only non-const one) and return true to indicate +// success. Please see cost_function.h for details on how the return +// value maybe used to impose simple constraints on the parameter +// block. // // For example, consider a scalar error e = k - x'y, where both x and y are // two-dimensional column vector parameters, the prime sign indicates
diff --git a/include/ceres/cost_function.h b/include/ceres/cost_function.h index 9b010f7..8013e96 100644 --- a/include/ceres/cost_function.h +++ b/include/ceres/cost_function.h
@@ -93,6 +93,24 @@ // the case when computing cost only. If jacobians[i] is NULL, then // the jacobian block corresponding to the i'th parameter block must // not to be returned. + // + // The return value indicates whether the computation of the + // residuals and/or jacobians was successful or not. + // + // This can be used to communicate numerical failures in jacobian + // computations for instance. + // + // A more interesting and common use is to impose constraints on the + // parameters. If the initial values of the parameter blocks satisfy + // the constraints, then returning false whenever the constraints + // are not satisfied will prevent the solver from moving into the + // infeasible region. This is not a very sophisticated mechanism for + // enforcing constraints, but is often good enough for things like + // non-negativity constraints. + // + // Note that it is important that the initial values of the + // parameter block must be feasible, otherwise the solver will + // declare a numerical problem at iteration 0. virtual bool Evaluate(double const* const* parameters, double* residuals, double** jacobians) const = 0;
diff --git a/include/ceres/numeric_diff_cost_function.h b/include/ceres/numeric_diff_cost_function.h index 4c84d4c..020d085 100644 --- a/include/ceres/numeric_diff_cost_function.h +++ b/include/ceres/numeric_diff_cost_function.h
@@ -36,8 +36,10 @@ // To get an numerically differentiated cost function, you must define // a class with a operator() (a functor) that computes the residuals. // -// The function must write the computed value in the last argument (the only -// non-const one) and return true to indicate success. +// The function must write the computed value in the last argument +// (the only non-const one) and return true to indicate success. +// Please see cost_function.h for details on how the return value +// maybe used to impose simple constraints on the parameter block. // // For example, consider a scalar error e = k - x'y, where both x and y are // two-dimensional column vector parameters, the prime sign indicates