206 lines
8.1 KiB
C
206 lines
8.1 KiB
C
|
// Ceres Solver - A fast non-linear least squares minimizer
|
||
|
|
// Copyright 2015 Google Inc. All rights reserved.
|
||
|
|
// http://ceres-solver.org/
|
||
|
|
//
|
||
|
|
// Redistribution and use in source and binary forms, with or without
|
||
|
|
// modification, are permitted provided that the following conditions are met:
|
||
|
|
//
|
||
|
|
// * Redistributions of source code must retain the above copyright notice,
|
||
|
|
// this list of conditions and the following disclaimer.
|
||
|
|
// * Redistributions in binary form must reproduce the above copyright notice,
|
||
|
|
// this list of conditions and the following disclaimer in the documentation
|
||
|
|
// and/or other materials provided with the distribution.
|
||
|
|
// * Neither the name of Google Inc. nor the names of its contributors may be
|
||
|
|
// used to endorse or promote products derived from this software without
|
||
|
|
// specific prior written permission.
|
||
|
|
//
|
||
|
|
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
||
|
|
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||
|
|
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||
|
|
// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
|
||
|
|
// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
||
|
|
// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
||
|
|
// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
||
|
|
// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
||
|
|
// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
||
|
|
// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
||
|
|
// POSSIBILITY OF SUCH DAMAGE.
|
||
|
|
//
|
||
|
|
// Author: sameeragarwal@google.com (Sameer Agarwal)
|
||
|
|
// keir@google.com (Keir Mierle)
|
||
|
|
|
||
|
|
#ifndef CERES_INTERNAL_EVALUATOR_H_
|
||
|
|
#define CERES_INTERNAL_EVALUATOR_H_
|
||
|
|
|
||
|
|
#include <map>
|
||
|
|
#include <string>
|
||
|
|
#include <vector>
|
||
|
|
|
||
|
|
#include "ceres/execution_summary.h"
|
||
|
|
#include "ceres/internal/port.h"
|
||
|
|
#include "ceres/types.h"
|
||
|
|
|
||
|
|
namespace ceres {
|
||
|
|
|
||
|
|
struct CRSMatrix;
|
||
|
|
|
||
|
|
namespace internal {
|
||
|
|
|
||
|
|
class Program;
|
||
|
|
class SparseMatrix;
|
||
|
|
|
||
|
|
// The Evaluator interface offers a way to interact with a least squares cost
|
||
|
|
// function that is useful for an optimizer that wants to minimize the least
|
||
|
|
// squares objective. This insulates the optimizer from issues like Jacobian
|
||
|
|
// storage, parameterization, etc.
|
||
|
|
class Evaluator {
|
||
|
|
public:
|
||
|
|
virtual ~Evaluator();
|
||
|
|
|
||
|
|
struct Options {
|
||
|
|
Options()
|
||
|
|
: num_threads(1),
|
||
|
|
num_eliminate_blocks(-1),
|
||
|
|
linear_solver_type(DENSE_QR),
|
||
|
|
dynamic_sparsity(false) {}
|
||
|
|
|
||
|
|
int num_threads;
|
||
|
|
int num_eliminate_blocks;
|
||
|
|
LinearSolverType linear_solver_type;
|
||
|
|
bool dynamic_sparsity;
|
||
|
|
};
|
||
|
|
|
||
|
|
static Evaluator* Create(const Options& options,
|
||
|
|
Program* program,
|
||
|
|
std::string* error);
|
||
|
|
|
||
|
|
// This is used for computing the cost, residual and Jacobian for
|
||
|
|
// returning to the user. For actually solving the optimization
|
||
|
|
// problem, the optimization algorithm uses the ProgramEvaluator
|
||
|
|
// objects directly.
|
||
|
|
//
|
||
|
|
// The residual, gradients and jacobian pointers can be NULL, in
|
||
|
|
// which case they will not be evaluated. cost cannot be NULL.
|
||
|
|
//
|
||
|
|
// The parallelism of the evaluator is controlled by num_threads; it
|
||
|
|
// should be at least 1.
|
||
|
|
//
|
||
|
|
// Note: That this function does not take a parameter vector as
|
||
|
|
// input. The parameter blocks are evaluated on the values contained
|
||
|
|
// in the arrays pointed to by their user_state pointers.
|
||
|
|
//
|
||
|
|
// Also worth noting is that this function mutates program by
|
||
|
|
// calling Program::SetParameterOffsetsAndIndex() on it so that an
|
||
|
|
// evaluator object can be constructed.
|
||
|
|
static bool Evaluate(Program* program,
|
||
|
|
int num_threads,
|
||
|
|
double* cost,
|
||
|
|
std::vector<double>* residuals,
|
||
|
|
std::vector<double>* gradient,
|
||
|
|
CRSMatrix* jacobian);
|
||
|
|
|
||
|
|
// Build and return a sparse matrix for storing and working with the Jacobian
|
||
|
|
// of the objective function. The jacobian has dimensions
|
||
|
|
// NumEffectiveParameters() by NumParameters(), and is typically extremely
|
||
|
|
// sparse. Since the sparsity pattern of the Jacobian remains constant over
|
||
|
|
// the lifetime of the optimization problem, this method is used to
|
||
|
|
// instantiate a SparseMatrix object with the appropriate sparsity structure
|
||
|
|
// (which can be an expensive operation) and then reused by the optimization
|
||
|
|
// algorithm and the various linear solvers.
|
||
|
|
//
|
||
|
|
// It is expected that the classes implementing this interface will be aware
|
||
|
|
// of their client's requirements for the kind of sparse matrix storage and
|
||
|
|
// layout that is needed for an efficient implementation. For example
|
||
|
|
// CompressedRowOptimizationProblem creates a compressed row representation of
|
||
|
|
// the jacobian for use with CHOLMOD, where as BlockOptimizationProblem
|
||
|
|
// creates a BlockSparseMatrix representation of the jacobian for use in the
|
||
|
|
// Schur complement based methods.
|
||
|
|
virtual SparseMatrix* CreateJacobian() const = 0;
|
||
|
|
|
||
|
|
|
||
|
|
// Options struct to control Evaluator::Evaluate;
|
||
|
|
struct EvaluateOptions {
|
||
|
|
EvaluateOptions()
|
||
|
|
: apply_loss_function(true) {
|
||
|
|
}
|
||
|
|
|
||
|
|
// If false, the loss function correction is not applied to the
|
||
|
|
// residual blocks.
|
||
|
|
bool apply_loss_function;
|
||
|
|
};
|
||
|
|
|
||
|
|
// Evaluate the cost function for the given state. Returns the cost,
|
||
|
|
// residuals, and jacobian in the corresponding arguments. Both residuals and
|
||
|
|
// jacobian are optional; to avoid computing them, pass NULL.
|
||
|
|
//
|
||
|
|
// If non-NULL, the Jacobian must have a suitable sparsity pattern; only the
|
||
|
|
// values array of the jacobian is modified.
|
||
|
|
//
|
||
|
|
// state is an array of size NumParameters(), cost is a pointer to a single
|
||
|
|
// double, and residuals is an array of doubles of size NumResiduals().
|
||
|
|
virtual bool Evaluate(const EvaluateOptions& evaluate_options,
|
||
|
|
const double* state,
|
||
|
|
double* cost,
|
||
|
|
double* residuals,
|
||
|
|
double* gradient,
|
||
|
|
SparseMatrix* jacobian) = 0;
|
||
|
|
|
||
|
|
// Variant of Evaluator::Evaluate where the user wishes to use the
|
||
|
|
// default EvaluateOptions struct. This is mostly here as a
|
||
|
|
// convenience method.
|
||
|
|
bool Evaluate(const double* state,
|
||
|
|
double* cost,
|
||
|
|
double* residuals,
|
||
|
|
double* gradient,
|
||
|
|
SparseMatrix* jacobian) {
|
||
|
|
return Evaluate(EvaluateOptions(),
|
||
|
|
state,
|
||
|
|
cost,
|
||
|
|
residuals,
|
||
|
|
gradient,
|
||
|
|
jacobian);
|
||
|
|
}
|
||
|
|
|
||
|
|
// Make a change delta (of size NumEffectiveParameters()) to state (of size
|
||
|
|
// NumParameters()) and store the result in state_plus_delta.
|
||
|
|
//
|
||
|
|
// In the case that there are no parameterizations used, this is equivalent to
|
||
|
|
//
|
||
|
|
// state_plus_delta[i] = state[i] + delta[i] ;
|
||
|
|
//
|
||
|
|
// however, the mapping is more complicated in the case of parameterizations
|
||
|
|
// like quaternions. This is the same as the "Plus()" operation in
|
||
|
|
// local_parameterization.h, but operating over the entire state vector for a
|
||
|
|
// problem.
|
||
|
|
virtual bool Plus(const double* state,
|
||
|
|
const double* delta,
|
||
|
|
double* state_plus_delta) const = 0;
|
||
|
|
|
||
|
|
// The number of parameters in the optimization problem.
|
||
|
|
virtual int NumParameters() const = 0;
|
||
|
|
|
||
|
|
// This is the effective number of parameters that the optimizer may adjust.
|
||
|
|
// This applies when there are parameterizations on some of the parameters.
|
||
|
|
virtual int NumEffectiveParameters() const = 0;
|
||
|
|
|
||
|
|
// The number of residuals in the optimization problem.
|
||
|
|
virtual int NumResiduals() const = 0;
|
||
|
|
|
||
|
|
// The following two methods return copies instead of references so
|
||
|
|
// that the base class implementation does not have to worry about
|
||
|
|
// life time issues. Further, these calls are not expected to be
|
||
|
|
// frequent or performance sensitive.
|
||
|
|
virtual std::map<std::string, int> CallStatistics() const {
|
||
|
|
return std::map<std::string, int>();
|
||
|
|
}
|
||
|
|
|
||
|
|
virtual std::map<std::string, double> TimeStatistics() const {
|
||
|
|
return std::map<std::string, double>();
|
||
|
|
}
|
||
|
|
};
|
||
|
|
|
||
|
|
} // namespace internal
|
||
|
|
} // namespace ceres
|
||
|
|
|
||
|
|
#endif // CERES_INTERNAL_EVALUATOR_H_
|