1a02191e04bc25c4935f804f2c080ae28663d096dBen Murdoch// Ceres Solver - A fast non-linear least squares minimizer 2c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// Copyright 2010, 2011, 2012 Google Inc. All rights reserved. 3c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// http://code.google.com/p/ceres-solver/ 4c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// 5a02191e04bc25c4935f804f2c080ae28663d096dBen Murdoch// Redistribution and use in source and binary forms, with or without 6c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// modification, are permitted provided that the following conditions are met: 7c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// 858537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles)// * Redistributions of source code must retain the above copyright notice, 91320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// this list of conditions and the following disclaimer. 101320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// * Redistributions in binary form must reproduce the above copyright notice, 11eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch// this list of conditions and the following disclaimer in the documentation 12c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// and/or other materials provided with the distribution. 1303b57e008b61dfcb1fbad3aea950ae0e001748b0Torne (Richard Coles)// * Neither the name of Google Inc. nor the names of its contributors may be 1403b57e008b61dfcb1fbad3aea950ae0e001748b0Torne (Richard Coles)// used to endorse or promote products derived from this software without 15a02191e04bc25c4935f804f2c080ae28663d096dBen Murdoch// specific prior written permission. 16a02191e04bc25c4935f804f2c080ae28663d096dBen Murdoch// 17c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 18c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 21c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles)// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// POSSIBILITY OF SUCH DAMAGE. 28c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// 29c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// Author: sameeragarwal@google.com (Sameer Agarwal) 30c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// keir@google.com (Keir Mierle) 31c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 32c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#ifndef CERES_INTERNAL_EVALUATOR_H_ 33c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#define CERES_INTERNAL_EVALUATOR_H_ 34c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 35c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#include <map> 36c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#include <string> 37868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles)#include <vector> 38c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 39c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#include "ceres/execution_summary.h" 40c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#include "ceres/internal/port.h" 41c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#include "ceres/types.h" 42c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 43c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)namespace ceres { 44c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 45c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)struct CRSMatrix; 46868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) 47c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)namespace internal { 48c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 49c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)class Program; 50c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)class SparseMatrix; 51c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 52c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// The Evaluator interface offers a way to interact with a least squares cost 53868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles)// function that is useful for an optimizer that wants to minimize the least 54c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// squares objective. This insulates the optimizer from issues like Jacobian 55c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// storage, parameterization, etc. 56c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)class Evaluator { 57c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) public: 58c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) virtual ~Evaluator(); 59c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 60c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) struct Options { 61c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) Options() 62868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) : num_threads(1), 63c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) num_eliminate_blocks(-1), 64c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) linear_solver_type(DENSE_QR), 65c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) dynamic_sparsity(false) {} 66c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 67c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) int num_threads; 68c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) int num_eliminate_blocks; 69868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) LinearSolverType linear_solver_type; 70868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) bool dynamic_sparsity; 71c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) }; 72c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 73c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) static Evaluator* Create(const Options& options, 74c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) Program* program, 75c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) string* error); 76c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 77c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // This is used for computing the cost, residual and Jacobian for 78868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) // returning to the user. For actually solving the optimization 79c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // problem, the optimization algorithm uses the ProgramEvaluator 80c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // objects directly. 81c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 82c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // The residual, gradients and jacobian pointers can be NULL, in 83c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // which case they will not be evaluated. cost cannot be NULL. 84c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 85c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // The parallelism of the evaluator is controlled by num_threads; it 86c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // should be at least 1. 87c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 88c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Note: That this function does not take a parameter vector as 89868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) // input. The parameter blocks are evaluated on the values contained 90868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) // in the arrays pointed to by their user_state pointers. 91c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 92c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Also worth noting is that this function mutates program by 93c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // calling Program::SetParameterOffsetsAndIndex() on it so that an 94c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // evaluator object can be constructed. 95c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) static bool Evaluate(Program* program, 96c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) int num_threads, 97c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) double* cost, 98868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) vector<double>* residuals, 99c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) vector<double>* gradient, 100c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) CRSMatrix* jacobian); 101c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 102c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Build and return a sparse matrix for storing and working with the Jacobian 103c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // of the objective function. The jacobian has dimensions 104c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // NumEffectiveParameters() by NumParameters(), and is typically extremely 105c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // sparse. Since the sparsity pattern of the Jacobian remains constant over 106c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // the lifetime of the optimization problem, this method is used to 107c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // instantiate a SparseMatrix object with the appropriate sparsity structure 108c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // (which can be an expensive operation) and then reused by the optimization 109c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // algorithm and the various linear solvers. 110c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 111c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // It is expected that the classes implementing this interface will be aware 112c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // of their client's requirements for the kind of sparse matrix storage and 113c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // layout that is needed for an efficient implementation. For example 114c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // CompressedRowOptimizationProblem creates a compressed row representation of 115c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // the jacobian for use with CHOLMOD, where as BlockOptimizationProblem 116c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // creates a BlockSparseMatrix representation of the jacobian for use in the 117a02191e04bc25c4935f804f2c080ae28663d096dBen Murdoch // Schur complement based methods. 118 virtual SparseMatrix* CreateJacobian() const = 0; 119 120 121 // Options struct to control Evaluator::Evaluate; 122 struct EvaluateOptions { 123 EvaluateOptions() 124 : apply_loss_function(true) { 125 } 126 127 // If false, the loss function correction is not applied to the 128 // residual blocks. 129 bool apply_loss_function; 130 }; 131 132 // Evaluate the cost function for the given state. Returns the cost, 133 // residuals, and jacobian in the corresponding arguments. Both residuals and 134 // jacobian are optional; to avoid computing them, pass NULL. 135 // 136 // If non-NULL, the Jacobian must have a suitable sparsity pattern; only the 137 // values array of the jacobian is modified. 138 // 139 // state is an array of size NumParameters(), cost is a pointer to a single 140 // double, and residuals is an array of doubles of size NumResiduals(). 141 virtual bool Evaluate(const EvaluateOptions& evaluate_options, 142 const double* state, 143 double* cost, 144 double* residuals, 145 double* gradient, 146 SparseMatrix* jacobian) = 0; 147 148 // Variant of Evaluator::Evaluate where the user wishes to use the 149 // default EvaluateOptions struct. This is mostly here as a 150 // convenience method. 151 bool Evaluate(const double* state, 152 double* cost, 153 double* residuals, 154 double* gradient, 155 SparseMatrix* jacobian) { 156 return Evaluate(EvaluateOptions(), 157 state, 158 cost, 159 residuals, 160 gradient, 161 jacobian); 162 } 163 164 // Make a change delta (of size NumEffectiveParameters()) to state (of size 165 // NumParameters()) and store the result in state_plus_delta. 166 // 167 // In the case that there are no parameterizations used, this is equivalent to 168 // 169 // state_plus_delta[i] = state[i] + delta[i] ; 170 // 171 // however, the mapping is more complicated in the case of parameterizations 172 // like quaternions. This is the same as the "Plus()" operation in 173 // local_parameterization.h, but operating over the entire state vector for a 174 // problem. 175 virtual bool Plus(const double* state, 176 const double* delta, 177 double* state_plus_delta) const = 0; 178 179 // The number of parameters in the optimization problem. 180 virtual int NumParameters() const = 0; 181 182 // This is the effective number of parameters that the optimizer may adjust. 183 // This applies when there are parameterizations on some of the parameters. 184 virtual int NumEffectiveParameters() const = 0; 185 186 // The number of residuals in the optimization problem. 187 virtual int NumResiduals() const = 0; 188 189 // The following two methods return copies instead of references so 190 // that the base class implementation does not have to worry about 191 // life time issues. Further, these calls are not expected to be 192 // frequent or performance sensitive. 193 virtual map<string, int> CallStatistics() const { 194 return map<string, int>(); 195 } 196 197 virtual map<string, double> TimeStatistics() const { 198 return map<string, double>(); 199 } 200}; 201 202} // namespace internal 203} // namespace ceres 204 205#endif // CERES_INTERNAL_EVALUATOR_H_ 206