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
