blob: eeda2989846ddc70f3cacdad1d50873a1bb15f23 [file] [log] [blame]
Keir Mierle8ebb0732012-04-30 23:09:08 -07001// 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#ifndef CERES_INTERNAL_MINIMIZER_H_
32#define CERES_INTERNAL_MINIMIZER_H_
33
34#include <vector>
35#include "ceres/solver.h"
36#include "ceres/iteration_callback.h"
37
38namespace ceres {
39namespace internal {
40
41class Evaluator;
42class LinearSolver;
Sameer Agarwalaa9a83c2012-05-29 17:40:17 -070043class SparseMatrix;
44class TrustRegionStrategy;
Keir Mierle8ebb0732012-04-30 23:09:08 -070045
46// Interface for non-linear least squares solvers.
47class Minimizer {
48 public:
49 // Options struct to control the behaviour of the Minimizer. Please
50 // see solver.h for detailed information about the meaning and
51 // default values of each of these parameters.
52 struct Options {
Sameer Agarwalaa9a83c2012-05-29 17:40:17 -070053 Options() {
54 Init(Solver::Options());
55 }
56
Keir Mierle8ebb0732012-04-30 23:09:08 -070057 explicit Options(const Solver::Options& options) {
Sameer Agarwalaa9a83c2012-05-29 17:40:17 -070058 Init(options);
59 }
60
61 void Init(const Solver::Options& options) {
Keir Mierle8ebb0732012-04-30 23:09:08 -070062 max_num_iterations = options.max_num_iterations;
63 max_solver_time_sec = options.max_solver_time_sec;
Sameer Agarwalaa9a83c2012-05-29 17:40:17 -070064 max_step_solver_retries = 5;
Keir Mierle8ebb0732012-04-30 23:09:08 -070065 gradient_tolerance = options.gradient_tolerance;
66 parameter_tolerance = options.parameter_tolerance;
67 function_tolerance = options.function_tolerance;
68 min_relative_decrease = options.min_relative_decrease;
69 eta = options.eta;
Keir Mierle8ebb0732012-04-30 23:09:08 -070070 jacobi_scaling = options.jacobi_scaling;
Sameer Agarwal82f4b882012-05-06 21:05:28 -070071 lsqp_dump_directory = options.lsqp_dump_directory;
Keir Mierle8ebb0732012-04-30 23:09:08 -070072 lsqp_iterations_to_dump = options.lsqp_iterations_to_dump;
Sameer Agarwal82f4b882012-05-06 21:05:28 -070073 lsqp_dump_format_type = options.lsqp_dump_format_type;
Keir Mierle8ebb0732012-04-30 23:09:08 -070074 num_eliminate_blocks = options.num_eliminate_blocks;
Sameer Agarwalaa9a83c2012-05-29 17:40:17 -070075 max_num_consecutive_invalid_steps =
76 options.max_num_consecutive_invalid_steps;
77 min_trust_region_radius = options.min_trust_region_radius;
78 evaluator = NULL;
79 trust_region_strategy = NULL;
80 jacobian = NULL;
Keir Mierle8ebb0732012-04-30 23:09:08 -070081 }
82
83 int max_num_iterations;
84 int max_solver_time_sec;
Sameer Agarwalaa9a83c2012-05-29 17:40:17 -070085
86 // Number of times the linear solver should be retried in case of
87 // numerical failure. The retries are done by exponentially scaling up
88 // mu at each retry. This leads to stronger and stronger
89 // regularization making the linear least squares problem better
90 // conditioned at each retry.
91 int max_step_solver_retries;
Keir Mierle8ebb0732012-04-30 23:09:08 -070092 double gradient_tolerance;
93 double parameter_tolerance;
94 double function_tolerance;
95 double min_relative_decrease;
96 double eta;
Keir Mierle8ebb0732012-04-30 23:09:08 -070097 bool jacobi_scaling;
Keir Mierle8ebb0732012-04-30 23:09:08 -070098 vector<int> lsqp_iterations_to_dump;
Sameer Agarwal82f4b882012-05-06 21:05:28 -070099 DumpFormatType lsqp_dump_format_type;
100 string lsqp_dump_directory;
Keir Mierle8ebb0732012-04-30 23:09:08 -0700101 int num_eliminate_blocks;
Sameer Agarwalaa9a83c2012-05-29 17:40:17 -0700102 int max_num_consecutive_invalid_steps;
103 int min_trust_region_radius;
Keir Mierle8ebb0732012-04-30 23:09:08 -0700104
105 // List of callbacks that are executed by the Minimizer at the end
106 // of each iteration.
107 //
Sameer Agarwalaa9a83c2012-05-29 17:40:17 -0700108 // The Options struct does not own these pointers.
Keir Mierle8ebb0732012-04-30 23:09:08 -0700109 vector<IterationCallback*> callbacks;
Sameer Agarwalaa9a83c2012-05-29 17:40:17 -0700110
111 // Object responsible for evaluating the cost, residuals and
112 // Jacobian matrix. The Options struct does not own this pointer.
113 Evaluator* evaluator;
114
115 // Object responsible for actually computing the trust region
116 // step, and sizing the trust region radius. The Options struct
117 // does not own this pointer.
118 TrustRegionStrategy* trust_region_strategy;
119
120 // Object holding the Jacobian matrix. It is assumed that the
121 // sparsity structure of the matrix has already been initialized
122 // and will remain constant for the life time of the
123 // optimization. The Options struct does not own this pointer.
124 SparseMatrix* jacobian;
Keir Mierle8ebb0732012-04-30 23:09:08 -0700125 };
126
127 virtual ~Minimizer() {}
Sameer Agarwalaa9a83c2012-05-29 17:40:17 -0700128
129 // Note: The minimizer is expected to update the state of the
130 // parameters array every iteration. This is required for the
131 // StateUpdatingCallback to work.
Keir Mierle8ebb0732012-04-30 23:09:08 -0700132 virtual void Minimize(const Options& options,
Sameer Agarwalaa9a83c2012-05-29 17:40:17 -0700133 double* parameters,
Keir Mierle8ebb0732012-04-30 23:09:08 -0700134 Solver::Summary* summary) = 0;
135};
136
137} // namespace internal
138} // namespace ceres
139
140#endif // CERES_INTERNAL_MINIMIZER_H_