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 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 { IterationSummaryIterationSummary46 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 // 215 class CERES_EXPORT IterationCallback { 216 public: ~IterationCallback()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