Fix the documentation for CostFunction::Evaluate.
The documentation was overly complex and had mismatched
symbols leading to confusion.
Change-Id: I25709e61ff3f9b9775d8f14a9e63f61931256dac
diff --git a/docs/source/nnls_modeling.rst b/docs/source/nnls_modeling.rst
index 36ee550..88df6b8 100644
--- a/docs/source/nnls_modeling.rst
+++ b/docs/source/nnls_modeling.rst
@@ -61,14 +61,16 @@
=====================
For each term in the objective function, a :class:`CostFunction` is
-responsible for computing a vector of residuals and if asked a vector
-of Jacobian matrices, i.e., given :math:`\left[x_{i_1}, ... ,
-x_{i_k}\right]`, compute the vector
-:math:`f_i\left(x_{i_1},...,x_{i_k}\right)` and the matrices
+responsible for computing a vector of residuals and Jacobian
+matrices. Concretely, consider a function
+:math:`f\left(x_{1},...,x_{k}\right)` that depends on parameter blocks
+:math:`\left[x_{1}, ... , x_{k}\right]`.
- .. math:: J_{ij} = \frac{\partial}{\partial
- x_{i_j}}f_i\left(x_{i_1},...,x_{i_k}\right),\quad \forall j
- \in \{1, \ldots, k\}
+Then, given :math:`\left[x_{1}, ... , x_{k}\right]`,
+:class:`CostFunction` is responsible for computing the vector
+:math:`f\left(x_{1},...,x_{k}\right)` and the Jacobian matrices
+
+.. math:: J_i = \frac{\partial}{\partial x_i} f(x_1, ..., x_k) \quad \forall i \in \{1, \ldots, k\}
.. class:: CostFunction
@@ -100,37 +102,43 @@
Compute the residual vector and the Jacobian matrices.
- ``parameters`` is an array of pointers to arrays containing the
- various parameter blocks. ``parameters`` has the same number of
- elements as :member:`CostFunction::parameter_block_sizes_` and the
- parameter blocks are in the same order as
- :member:`CostFunction::parameter_block_sizes_`.
+ ``parameters`` is an array of arrays of size
+ :member:`CostFunction::parameter_block_sizes_.size()` and
+ ``parameters[i]`` is an array of size
+ ``parameter_block_sizes_[i]`` that contains the
+ :math:`i^{\text{th}}` parameter block that the ``CostFunction``
+ depends on.
+
+ ``parameters`` is never ``NULL``.
``residuals`` is an array of size ``num_residuals_``.
- ``jacobians`` is an array of size
- :member:`CostFunction::parameter_block_sizes_` containing pointers
- to storage for Jacobian matrices corresponding to each parameter
- block. The Jacobian matrices are in the same order as
- :member:`CostFunction::parameter_block_sizes_`. ``jacobians[i]`` is
- an array that contains :member:`CostFunction::num_residuals_` x
- :member:`CostFunction::parameter_block_sizes_` ``[i]``
- elements. Each Jacobian matrix is stored in row-major order, i.e.,
- ``jacobians[i][r * parameter_block_size_[i] + c]`` =
- :math:`\frac{\partial residual[r]}{\partial parameters[i][c]}`
+ ``residuals`` is never ``NULL``.
+ ``jacobians`` is an array of arrays of size
+ :member:`CostFunction::parameter_block_sizes_.size()`.
- If ``jacobians`` is ``NULL``, then no derivatives are returned;
- this is the case when computing cost only. If ``jacobians[i]`` is
- ``NULL``, then the Jacobian matrix corresponding to the
- :math:`i^{\textrm{th}}` parameter block must not be returned, this
- is the case when a parameter block is marked constant.
+ If ``jacobians`` is ``NULL``, the user is only expected to compute
+ the residuals.
- **NOTE** The return value indicates whether the computation of the
- residuals and/or jacobians was successful or not.
+ ``jacobians[i]`` is a row-major array of size ``num_residuals x
+ parameter_block_sizes_[i]``.
- This can be used to communicate numerical failures in Jacobian
- computations for instance.
+ If ``jacobians[i]`` is **not** ``NULL``, the user is required to
+ compute the Jacobian of the residual vector with respect to
+ ``parameters[i]`` and store it in this array, i.e.
+
+ ``jacobians[i][r * parameter_block_sizes_[i] + c]`` =
+ :math:`\frac{\displaystyle \partial \text{residual}[r]}{\displaystyle \partial \text{parameters}[i][c]}`
+
+ If ``jacobians[i]`` is ``NULL``, then this computation can be
+ skipped. This is the case when the corresponding parameter block is
+ marked constant.
+
+ 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.
:class:`SizedCostFunction`
==========================
