include/ceres/iteration_callback.h

   1 // Ceres Solver - A fast non-linear least squares minimizer
   2 // Copyright 2015 Google Inc. All rights reserved.
   3 // http://ceres-solver.org/
   4 //
   5 // Redistribution and use in source and binary forms, with or without
   6 // modification, are permitted provided that the following conditions are met:
   7 //
   8 // * Redistributions of source code must retain the above copyright notice,
   9 //   this list of conditions and the following disclaimer.
  10 // * Redistributions in binary form must reproduce the above copyright notice,
  11 //   this list of conditions and the following disclaimer in the documentation
  12 //   and/or other materials provided with the distribution.
  13 // * Neither the name of Google Inc. nor the names of its contributors may be
  14 //   used to endorse or promote products derived from this software without
  15 //   specific prior written permission.
  16 //
  17 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  18 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  21 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  22 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  23 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  25 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  26 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  27 // POSSIBILITY OF SUCH DAMAGE.
  28 //
  29 // Author: sameeragarwal@google.com (Sameer Agarwal)
  30 //
  31 // When an iteration callback is specified, Ceres calls the callback
  32 // after each minimizer step (if the minimizer has not converged) and
  33 // passes it an IterationSummary object, defined below.
  34
  35 #ifndef CERES_PUBLIC_ITERATION_CALLBACK_H_
  36 #define CERES_PUBLIC_ITERATION_CALLBACK_H_
  37
  38 #include "ceres/types.h"
  39 #include "ceres/internal/disable_warnings.h"
  40
  41 namespace ceres {
  42
  43 // This struct describes the state of the optimizer after each
  44 // iteration of the minimization.
  45 struct CERES_EXPORT IterationSummary {
  46   IterationSummary()
  47       : iteration(0),
  48         step_is_valid(false),
  49         step_is_nonmonotonic(false),
  50         step_is_successful(false),
  51         cost(0.0),
  52         cost_change(0.0),
  53         gradient_max_norm(0.0),
  54         gradient_norm(0.0),
  55         step_norm(0.0),
  56         eta(0.0),
  57         step_size(0.0),
  58         line_search_function_evaluations(0),
  59         line_search_gradient_evaluations(0),
  60         line_search_iterations(0),
  61         linear_solver_iterations(0),
  62         iteration_time_in_seconds(0.0),
  63         step_solver_time_in_seconds(0.0),
  64         cumulative_time_in_seconds(0.0) {}
  65
  66   // Current iteration number.
  67   int32 iteration;
  68
  69   // Step was numerically valid, i.e., all values are finite and the
  70   // step reduces the value of the linearized model.
  71   //
  72   // Note: step_is_valid is always true when iteration = 0.
  73   bool step_is_valid;
  74
  75   // Step did not reduce the value of the objective function
  76   // sufficiently, but it was accepted because of the relaxed
  77   // acceptance criterion used by the non-monotonic trust region
  78   // algorithm.
  79   //
  80   // Note: step_is_nonmonotonic is always false when iteration = 0;
  81   bool step_is_nonmonotonic;
  82
  83   // Whether or not the minimizer accepted this step or not. If the
  84   // ordinary trust region algorithm is used, this means that the
  85   // relative reduction in the objective function value was greater
  86   // than Solver::Options::min_relative_decrease. However, if the
  87   // non-monotonic trust region algorithm is used
  88   // (Solver::Options:use_nonmonotonic_steps = true), then even if the
  89   // relative decrease is not sufficient, the algorithm may accept the
  90   // step and the step is declared successful.
  91   //
  92   // Note: step_is_successful is always true when iteration = 0.
  93   bool step_is_successful;
  94
  95   // Value of the objective function.
  96   double cost;
  97
  98   // Change in the value of the objective function in this
  99   // iteration. This can be positive or negative.
 100   double cost_change;
 101
 102   // Infinity norm of the gradient vector.
 103   double gradient_max_norm;
 104
 105   // 2-norm of the gradient vector.
 106   double gradient_norm;
 107
 108   // 2-norm of the size of the step computed by the optimization
 109   // algorithm.
 110   double step_norm;
 111
 112   // For trust region algorithms, the ratio of the actual change in
 113   // cost and the change in the cost of the linearized approximation.
 114   double relative_decrease;
 115
 116   // Size of the trust region at the end of the current iteration. For
 117   // the Levenberg-Marquardt algorithm, the regularization parameter
 118   // mu = 1.0 / trust_region_radius.
 119   double trust_region_radius;
 120
 121   // For the inexact step Levenberg-Marquardt algorithm, this is the
 122   // relative accuracy with which the Newton(LM) step is solved. This
 123   // number affects only the iterative solvers capable of solving
 124   // linear systems inexactly. Factorization-based exact solvers
 125   // ignore it.
 126   double eta;
 127
 128   // Step sized computed by the line search algorithm.
 129   double step_size;
 130
 131   // Number of function value evaluations used by the line search algorithm.
 132   int line_search_function_evaluations;
 133
 134   // Number of function gradient evaluations used by the line search algorithm.
 135   int line_search_gradient_evaluations;
 136
 137   // Number of iterations taken by the line search algorithm.
 138   int line_search_iterations;
 139
 140   // Number of iterations taken by the linear solver to solve for the
 141   // Newton step.
 142   int linear_solver_iterations;
 143
 144   // All times reported below are wall times.
 145
 146   // Time (in seconds) spent inside the minimizer loop in the current
 147   // iteration.
 148   double iteration_time_in_seconds;
 149
 150   // Time (in seconds) spent inside the trust region step solver.
 151   double step_solver_time_in_seconds;
 152
 153   // Time (in seconds) since the user called Solve().
 154   double cumulative_time_in_seconds;
 155 };
 156
 157 // Interface for specifying callbacks that are executed at the end of
 158 // each iteration of the Minimizer. The solver uses the return value
 159 // of operator() to decide whether to continue solving or to
 160 // terminate. The user can return three values.
 161 //
 162 // SOLVER_ABORT indicates that the callback detected an abnormal
 163 // situation. The solver returns without updating the parameter blocks
 164 // (unless Solver::Options::update_state_every_iteration is set
 165 // true). Solver returns with Solver::Summary::termination_type set to
 166 // USER_ABORT.
 167 //
 168 // SOLVER_TERMINATE_SUCCESSFULLY indicates that there is no need to
 169 // optimize anymore (some user specified termination criterion has
 170 // been met). Solver returns with Solver::Summary::termination_type
 171 // set to USER_SUCCESS.
 172 //
 173 // SOLVER_CONTINUE indicates that the solver should continue
 174 // optimizing.
 175 //
 176 // For example, the following Callback is used internally by Ceres to
 177 // log the progress of the optimization.
 178 //
 179 // Callback for logging the state of the minimizer to STDERR or STDOUT
 180 // depending on the user's preferences and logging level.
 181 //
 182 //   class LoggingCallback : public IterationCallback {
 183 //    public:
 184 //     explicit LoggingCallback(bool log_to_stdout)
 185 //         : log_to_stdout_(log_to_stdout) {}
 186 //
 187 //     ~LoggingCallback() {}
 188 //
 189 //     CallbackReturnType operator()(const IterationSummary& summary) {
 190 //       const char* kReportRowFormat =
 191 //           "% 4d: f:% 8e d:% 3.2e g:% 3.2e h:% 3.2e "
 192 //           "rho:% 3.2e mu:% 3.2e eta:% 3.2e li:% 3d";
 193 //       string output = StringPrintf(kReportRowFormat,
 194 //                                    summary.iteration,
 195 //                                    summary.cost,
 196 //                                    summary.cost_change,
 197 //                                    summary.gradient_max_norm,
 198 //                                    summary.step_norm,
 199 //                                    summary.relative_decrease,
 200 //                                    summary.trust_region_radius,
 201 //                                    summary.eta,
 202 //                                    summary.linear_solver_iterations);
 203 //       if (log_to_stdout_) {
 204 //         cout << output << endl;
 205 //       } else {
 206 //         VLOG(1) << output;
 207 //       }
 208 //       return SOLVER_CONTINUE;
 209 //     }
 210 //
 211 //    private:
 212 //     const bool log_to_stdout_;
 213 //   };
 214 //
 215 class CERES_EXPORT IterationCallback {
 216  public:
 217   virtual ~IterationCallback() {}
 218   virtual CallbackReturnType operator()(const IterationSummary& summary) = 0;
 219 };
 220
 221 }  // namespace ceres
 222
 223 #include "ceres/internal/reenable_warnings.h"
 224
 225 #endif  // CERES_PUBLIC_ITERATION_CALLBACK_H_