1// Ceres Solver - A fast non-linear least squares minimizer 2// Copyright 2010, 2011, 2012 Google Inc. All rights reserved. 3// http://code.google.com/p/ceres-solver/ 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 40namespace ceres { 41 42// This struct describes the state of the optimizer after each 43// iteration of the minimization. 44struct IterationSummary { 45 IterationSummary() 46 : iteration(0), 47 step_is_valid(false), 48 step_is_nonmonotonic(false), 49 step_is_successful(false), 50 cost(0.0), 51 cost_change(0.0), 52 gradient_max_norm(0.0), 53 step_norm(0.0), 54 eta(0.0), 55 step_size(0.0), 56 line_search_function_evaluations(0), 57 line_search_gradient_evaluations(0), 58 line_search_iterations(0), 59 linear_solver_iterations(0), 60 iteration_time_in_seconds(0.0), 61 step_solver_time_in_seconds(0.0), 62 cumulative_time_in_seconds(0.0) {} 63 64 // Current iteration number. 65 int32 iteration; 66 67 // Step was numerically valid, i.e., all values are finite and the 68 // step reduces the value of the linearized model. 69 // 70 // Note: step_is_valid is false when iteration = 0. 71 bool step_is_valid; 72 73 // Step did not reduce the value of the objective function 74 // sufficiently, but it was accepted because of the relaxed 75 // acceptance criterion used by the non-monotonic trust region 76 // algorithm. 77 // 78 // Note: step_is_nonmonotonic is false when iteration = 0; 79 bool step_is_nonmonotonic; 80 81 // Whether or not the minimizer accepted this step or not. If the 82 // ordinary trust region algorithm is used, this means that the 83 // relative reduction in the objective function value was greater 84 // than Solver::Options::min_relative_decrease. However, if the 85 // non-monotonic trust region algorithm is used 86 // (Solver::Options:use_nonmonotonic_steps = true), then even if the 87 // relative decrease is not sufficient, the algorithm may accept the 88 // step and the step is declared successful. 89 // 90 // Note: step_is_successful is false when iteration = 0. 91 bool step_is_successful; 92 93 // Value of the objective function. 94 double cost; 95 96 // Change in the value of the objective function in this 97 // iteration. This can be positive or negative. 98 double cost_change; 99 100 // Infinity norm of the gradient vector. 101 double gradient_max_norm; 102 103 // 2-norm of the size of the step computed by the optimization 104 // algorithm. 105 double step_norm; 106 107 // For trust region algorithms, the ratio of the actual change in 108 // cost and the change in the cost of the linearized approximation. 109 double relative_decrease; 110 111 // Size of the trust region at the end of the current iteration. For 112 // the Levenberg-Marquardt algorithm, the regularization parameter 113 // mu = 1.0 / trust_region_radius. 114 double trust_region_radius; 115 116 // For the inexact step Levenberg-Marquardt algorithm, this is the 117 // relative accuracy with which the Newton(LM) step is solved. This 118 // number affects only the iterative solvers capable of solving 119 // linear systems inexactly. Factorization-based exact solvers 120 // ignore it. 121 double eta; 122 123 // Step sized computed by the line search algorithm. 124 double step_size; 125 126 // Number of function value evaluations used by the line search algorithm. 127 int line_search_function_evaluations; 128 129 // Number of function gradient evaluations used by the line search algorithm. 130 int line_search_gradient_evaluations; 131 132 // Number of iterations taken by the line search algorithm. 133 int line_search_iterations; 134 135 // Number of iterations taken by the linear solver to solve for the 136 // Newton step. 137 int linear_solver_iterations; 138 139 // All times reported below are wall times. 140 141 // Time (in seconds) spent inside the minimizer loop in the current 142 // iteration. 143 double iteration_time_in_seconds; 144 145 // Time (in seconds) spent inside the trust region step solver. 146 double step_solver_time_in_seconds; 147 148 // Time (in seconds) since the user called Solve(). 149 double cumulative_time_in_seconds; 150}; 151 152// Interface for specifying callbacks that are executed at the end of 153// each iteration of the Minimizer. The solver uses the return value 154// of operator() to decide whether to continue solving or to 155// terminate. The user can return three values. 156// 157// SOLVER_ABORT indicates that the callback detected an abnormal 158// situation. The solver returns without updating the parameter blocks 159// (unless Solver::Options::update_state_every_iteration is set 160// true). Solver returns with Solver::Summary::termination_type set to 161// USER_ABORT. 162// 163// SOLVER_TERMINATE_SUCCESSFULLY indicates that there is no need to 164// optimize anymore (some user specified termination criterion has 165// been met). Solver returns with Solver::Summary::termination_type 166// set to USER_SUCCESS. 167// 168// SOLVER_CONTINUE indicates that the solver should continue 169// optimizing. 170// 171// For example, the following Callback is used internally by Ceres to 172// log the progress of the optimization. 173// 174// Callback for logging the state of the minimizer to STDERR or STDOUT 175// depending on the user's preferences and logging level. 176// 177// class LoggingCallback : public IterationCallback { 178// public: 179// explicit LoggingCallback(bool log_to_stdout) 180// : log_to_stdout_(log_to_stdout) {} 181// 182// ~LoggingCallback() {} 183// 184// CallbackReturnType operator()(const IterationSummary& summary) { 185// const char* kReportRowFormat = 186// "% 4d: f:% 8e d:% 3.2e g:% 3.2e h:% 3.2e " 187// "rho:% 3.2e mu:% 3.2e eta:% 3.2e li:% 3d"; 188// string output = StringPrintf(kReportRowFormat, 189// summary.iteration, 190// summary.cost, 191// summary.cost_change, 192// summary.gradient_max_norm, 193// summary.step_norm, 194// summary.relative_decrease, 195// summary.trust_region_radius, 196// summary.eta, 197// summary.linear_solver_iterations); 198// if (log_to_stdout_) { 199// cout << output << endl; 200// } else { 201// VLOG(1) << output; 202// } 203// return SOLVER_CONTINUE; 204// } 205// 206// private: 207// const bool log_to_stdout_; 208// }; 209// 210class IterationCallback { 211 public: 212 virtual ~IterationCallback() {} 213 virtual CallbackReturnType operator()(const IterationSummary& summary) = 0; 214}; 215 216} // namespace ceres 217 218#endif // CERES_PUBLIC_ITERATION_CALLBACK_H_ 219