Document block-level evaluation of LossFunction

Note in LossFunction::Evaluate docs that s = ||f_i||^2 is the squared norm of the entire residual block rather than its individual scalar components, and add a modeling FAQ explaining why independent measurements should be placed in separate ResidualBlocks when using a LossFunction.

Fixes https://github.com/ceres-solver/ceres-solver/issues/264

Change-Id: If5a9a2297e165ba71fdf4f93036dfa9d8256e15d

docs/source/modeling_faqs.rst

diff --git a/docs/source/modeling_faqs.rst b/docs/source/modeling_faqs.rst
index 13d4b7d..5f6891a 100644
--- a/docs/source/modeling_faqs.rst
+++ b/docs/source/modeling_faqs.rst
@@ -56,6 +56,24 @@
 vanishes as :math:`r(x) \to 0`, making the Gauss-Newton system singular near the
 solution.
 
+Do not pack multiple independent measurements into a single residual block when using a :class:`LossFunction`
+=============================================================================================================
+
+A :class:`LossFunction` operates on the squared norm
+:math:`s = \|f_i(x)\|^2 = \sum_{j=1}^{k_i} f_{ij}(x)^2` of an entire residual
+block, not on its individual scalar components :math:`f_{ij}(x)` separately.
+For a multi-dimensional measurement such as a 2D image reprojection error, this
+is desirable: :math:`\rho(\|f_i(x)\|^2)` is isotropic (rotationally invariant
+in measurement space) and down-weights both coordinates together whenever the
+feature match is an outlier.
+
+Conversely, you should not pack multiple independent measurements into a single
+:class:`CostFunction` if you intend to use a non-trivial :class:`LossFunction`.
+A single outlier component will inflate :math:`\|f_i(x)\|^2` and cause the
+:class:`LossFunction` to down-weight every other inlier measurement in the same
+residual block. Independent measurements that can fail independently should be
+added as separate residual blocks.
+
 When using Quaternions, consider using :class:`QuaternionManifold`
 ==================================================================
 

docs/source/nnls_modeling.rst

diff --git a/docs/source/nnls_modeling.rst b/docs/source/nnls_modeling.rst
index 975056e..bc2648b 100644
--- a/docs/source/nnls_modeling.rst
+++ b/docs/source/nnls_modeling.rst
@@ -1005,9 +1005,10 @@
 
    Here the convention is that the contribution of a term to the cost
    function is given by :math:`\frac{1}{2}\rho(s)`, where :math:`s
-   =\|f_i\|^2`. Calling the method with a negative value of :math:`s`
-   is an error and the implementations are not required to handle that
-   case.
+   =\|f_i\|^2` is the squared norm of the entire residual block (not of
+   its individual scalar components). Calling the method with a negative
+   value of :math:`s` is an error and the implementations are not
+   required to handle that case.
 
    Most sane choices of :math:`\rho` satisfy: