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#include "ceres/internal/disable_warnings.h" 40 41namespace ceres { 42 43// This struct describes the state of the optimizer after each 44// iteration of the minimization. 45struct 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 false 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 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 false 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// 215class 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_ 226