Evaluation callback API

This adds a callback mechanism to for users to get notified just
before jacobian and residual evaluations. This will enable
aggressive caching and sharing of compute between cost functions.

Change-Id: I67993726920218edf71ab9ae70c34c204756c71a

include/ceres/evaluation_callback.h

@@ -0,0 +1,75 @@
+// Ceres Solver - A fast non-linear least squares minimizer
+// Copyright 2018 Google Inc. All rights reserved.
+// http://ceres-solver.org/
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are met:
+//
+// * Redistributions of source code must retain the above copyright notice,
+//   this list of conditions and the following disclaimer.
+// * Redistributions in binary form must reproduce the above copyright notice,
+//   this list of conditions and the following disclaimer in the documentation
+//   and/or other materials provided with the distribution.
+// * Neither the name of Google Inc. nor the names of its contributors may be
+//   used to endorse or promote products derived from this software without
+//   specific prior written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+// POSSIBILITY OF SUCH DAMAGE.
+//
+// Author: mierle@gmail.com (Keir Mierle)
+
+#ifndef CERES_PUBLIC_EVALUATION_CALLBACK_H_
+#define CERES_PUBLIC_EVALUATION_CALLBACK_H_
+
+namespace ceres {
+
+// 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.
+class CERES_EXPORT EvaluationCallback {
+ public:
+  virtual ~EvaluationCallback() {}
+
+  // 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.
+  virtual void PrepareForEvaluation(bool evaluate_jacobians,
+                                    bool new_evaluation_point) = 0;
+};
+
+}  // namespace ceres
+
+#endif  // CERES_PUBLIC_EVALUATION_CALLBACK_H_

include/ceres/solver.h

@@ -35,6 +35,7 @@
 #include <string>
 #include <vector>
 #include "ceres/crs_matrix.h"
+#include "ceres/evaluation_callback.h"
 #include "ceres/internal/disable_warnings.h"
 #include "ceres/internal/macros.h"
 #include "ceres/internal/port.h"
@@ -136,6 +137,7 @@ class CERES_EXPORT Solver {
       gradient_check_relative_precision = 1e-8;
       gradient_check_numeric_derivative_relative_step_size = 1e-6;
       update_state_every_iteration = false;
+      evaluation_callback = NULL;
     }
 
     // Returns true if the options struct has a valid
@@ -740,8 +742,23 @@ class CERES_EXPORT Solver {
     // 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.
+    // wishes to visualize the state of the optimization every iteration
+    // (in combination with an IterationCallback).
+    //
+    // NOTE: If an evaluation_callback is provided, then the behaviour
+    // of this flag is slightly different in each case:
+    //
+    // (1) If update_state_every_iteration = 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 there will be undefined contents.
+    //
+    // (2) If update_state_every_iteration is true, 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.
     bool update_state_every_iteration;
 
     // Callbacks that are executed at the end of each iteration of the
@@ -751,15 +768,28 @@ class CERES_EXPORT Solver {
     // executed.
 
     // Callbacks 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 Minimizer
-    // terminates. This behaviour is controlled by
-    // update_state_every_variable. If the user wishes to have access
-    // to the update parameter blocks when his/her callbacks are
-    // executed, then set update_state_every_iteration to true.
+    // this vector. By default, parameter blocks are updated only at the
+    // end of the optimization, i.e when the Minimizer terminates. This
+    // behaviour is controlled by update_state_every_iteration. If the
+    // user wishes to have access to the updated parameter blocks when
+    // his/her callbacks are executed, then set
+    // update_state_every_iteration to true.
     //
     // The solver does NOT take ownership of these pointers.
     std::vector<IterationCallback*> callbacks;
+
+    // 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 evaluation_callback.h for details.
+    //
+    // NOTE: Evaluation callbacks are incompatible with inner iterations.
+    //
+    // WARNING: This interacts with update_state_every_iteration. See
+    // the documentation for that option for more details.
+    //
+    // The solver does NOT take ownership of the pointer.
+    EvaluationCallback* evaluation_callback;
   };
 
   struct CERES_EXPORT Summary {