internal/ceres/evaluator.h - ceres-solver - Git at Google


            
            // 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_
	// 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_