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)
30
// keir@google.com (Keir Mierle)
32
#ifndef CERES_INTERNAL_EVALUATOR_H_
33
#define CERES_INTERNAL_EVALUATOR_H_
36
#include "ceres/internal/port.h"
37
#include "ceres/types.h"
45
// The Evaluator interface offers a way to interact with a least squares cost
46
// function that is useful for an optimizer that wants to minimize the least
47
// squares objective. This insulates the optimizer from issues like Jacobian
48
// storage, parameterization, etc.
56
num_eliminate_blocks(-1),
57
linear_solver_type(DENSE_QR) {}
60
int num_eliminate_blocks;
61
LinearSolverType linear_solver_type;
64
static Evaluator* Create(const Options& options,
68
// Build and return a sparse matrix for storing and working with the Jacobian
69
// of the objective function. The jacobian has dimensions
70
// NumEffectiveParameters() by NumParameters(), and is typically extremely
71
// sparse. Since the sparsity pattern of the Jacobian remains constant over
72
// the lifetime of the optimization problem, this method is used to
73
// instantiate a SparseMatrix object with the appropriate sparsity structure
74
// (which can be an expensive operation) and then reused by the optimization
75
// algorithm and the various linear solvers.
77
// It is expected that the classes implementing this interface will be aware
78
// of their client's requirements for the kind of sparse matrix storage and
79
// layout that is needed for an efficient implementation. For example
80
// CompressedRowOptimizationProblem creates a compressed row representation of
81
// the jacobian for use with CHOLMOD, where as BlockOptimizationProblem
82
// creates a BlockSparseMatrix representation of the jacobian for use in the
83
// Schur complement based methods.
84
virtual SparseMatrix* CreateJacobian() const = 0;
86
// Evaluate the cost function for the given state. Returns the cost,
87
// residuals, and jacobian in the corresponding arguments. Both residuals and
88
// jacobian are optional; to avoid computing them, pass NULL.
90
// If non-NULL, the Jacobian must have a suitable sparsity pattern; only the
91
// values array of the jacobian is modified.
93
// state is an array of size NumParameters(), cost is a pointer to a single
94
// double, and residuals is an array of doubles of size NumResiduals().
95
virtual bool Evaluate(const double* state,
98
SparseMatrix* jacobian) = 0;
100
// Make a change delta (of size NumEffectiveParameters()) to state (of size
101
// NumParameters()) and store the result in state_plus_delta.
103
// In the case that there are no parameterizations used, this is equivalent to
105
// state_plus_delta[i] = state[i] + delta[i] ;
107
// however, the mapping is more complicated in the case of parameterizations
108
// like quaternions. This is the same as the "Plus()" operation in
109
// local_parameterization.h, but operating over the entire state vector for a
111
virtual bool Plus(const double* state,
113
double* state_plus_delta) const = 0;
115
// The number of parameters in the optimization problem.
116
virtual int NumParameters() const = 0;
118
// This is the effective number of parameters that the optimizer may adjust.
119
// This applies when there are parameterizations on some of the parameters.
120
virtual int NumEffectiveParameters() const = 0;
122
// The number of residuals in the optimization problem.
123
virtual int NumResiduals() const = 0;
126
} // namespace internal
129
#endif // CERES_INTERNAL_EVALUATOR_H_