Ceres: Update to the latest actual version
[blender.git] / extern / ceres / 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_