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