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/
5
// Redistribution and use in source and binary forms, with or without
6
// modification, are permitted provided that the following conditions are met:
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.
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.
29
// Author: sameeragarwal@google.com (Sameer Agarwal)
31
// When an iteration callback is specified, Ceres calls the callback after each
32
// optimizer step and pass it an IterationSummary object, defined below.
34
#ifndef CERES_PUBLIC_ITERATION_CALLBACK_H_
35
#define CERES_PUBLIC_ITERATION_CALLBACK_H_
37
#include "ceres/types.h"
41
// This struct describes the state of the optimizer after each
42
// iteration of the minimization.
43
struct IterationSummary {
44
// Current iteration number.
47
// Whether or not the algorithm made progress in this iteration.
48
bool step_is_successful;
50
// Value of the objective function.
53
// Change in the value of the objective function in this
54
// iteration. This can be positive or negative. Negative change
55
// means that the step was not successful.
58
// Infinity norm of the gradient vector.
59
double gradient_max_norm;
61
// 2-norm of the size of the step computed by the optimization
65
// For trust region algorithms, the ratio of the actual change in
66
// cost and the change in the cost of the linearized approximation.
67
double relative_decrease;
69
// Value of the regularization parameter for Levenberg-Marquardt
70
// algorithm at the end of the current iteration.
73
// For the inexact step Levenberg-Marquardt algorithm, this is the
74
// relative accuracy with which the Newton(LM) step is solved. This
75
// number affects only the iterative solvers capable of solving
76
// linear systems inexactly. Factorization-based exact solvers
80
// Number of iterations taken by the linear solver to solve for the
82
int linear_solver_iterations;
84
// TODO(sameeragarwal): Change to use a higher precision timer using
86
// Time (in seconds) spent inside the linear least squares solver.
87
int iteration_time_sec;
89
// Time (in seconds) spent inside the linear least squares solver.
90
int linear_solver_time_sec;
93
// Interface for specifying callbacks that are executed at the end of
94
// each iteration of the Minimizer. The solver uses the return value
95
// of operator() to decide whether to continue solving or to
96
// terminate. The user can return three values.
98
// SOLVER_ABORT indicates that the callback detected an abnormal
99
// situation. The solver returns without updating the parameter blocks
100
// (unless Solver::Options::update_state_every_iteration is set
101
// true). Solver returns with Solver::Summary::termination_type set to
104
// SOLVER_TERMINATE_SUCCESSFULLY indicates that there is no need to
105
// optimize anymore (some user specified termination criterion has
106
// been met). Solver returns with Solver::Summary::termination_type
107
// set to USER_SUCCESS.
109
// SOLVER_CONTINUE indicates that the solver should continue
112
// For example, the following Callback is used internally by Ceres to
113
// log the progress of the optimization.
115
// Callback for logging the state of the minimizer to STDERR or STDOUT
116
// depending on the user's preferences and logging level.
118
// class LoggingCallback : public IterationCallback {
120
// explicit LoggingCallback(bool log_to_stdout)
121
// : log_to_stdout_(log_to_stdout) {}
123
// ~LoggingCallback() {}
125
// CallbackReturnType operator()(const IterationSummary& summary) {
126
// const char* kReportRowFormat =
127
// "% 4d: f:% 8e d:% 3.2e g:% 3.2e h:% 3.2e "
128
// "rho:% 3.2e mu:% 3.2e eta:% 3.2e li:% 3d";
129
// string output = StringPrintf(kReportRowFormat,
130
// summary.iteration,
132
// summary.cost_change,
133
// summary.gradient_max_norm,
134
// summary.step_norm,
135
// summary.relative_decrease,
138
// summary.linear_solver_iterations);
139
// if (log_to_stdout_) {
140
// cout << output << endl;
142
// VLOG(1) << output;
144
// return SOLVER_CONTINUE;
148
// const bool log_to_stdout_;
151
class IterationCallback {
153
virtual ~IterationCallback() {}
154
virtual CallbackReturnType operator()(const IterationSummary& summary) = 0;
159
#endif // CERES_PUBLIC_ITERATION_CALLBACK_H_
added
removed
include/ceres/iteration_callback.h
