10ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// Ceres Solver - A fast non-linear least squares minimizer 20ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// Copyright 2010, 2011, 2012 Google Inc. All rights reserved. 30ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// http://code.google.com/p/ceres-solver/ 40ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// 50ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// Redistribution and use in source and binary forms, with or without 60ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// modification, are permitted provided that the following conditions are met: 70ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// 80ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// * Redistributions of source code must retain the above copyright notice, 90ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// this list of conditions and the following disclaimer. 100ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// * Redistributions in binary form must reproduce the above copyright notice, 110ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// this list of conditions and the following disclaimer in the documentation 120ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// and/or other materials provided with the distribution. 130ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// * Neither the name of Google Inc. nor the names of its contributors may be 140ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// used to endorse or promote products derived from this software without 150ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// specific prior written permission. 160ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// 170ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 180ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 190ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 200ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 210ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 220ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 230ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 240ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 250ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 260ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 270ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// POSSIBILITY OF SUCH DAMAGE. 280ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// 290ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// Author: sameeragarwal@google.com (Sameer Agarwal) 300ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// keir@google.com (Keir Mierle) 310ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong 320ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong#ifndef CERES_INTERNAL_EVALUATOR_H_ 330ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong#define CERES_INTERNAL_EVALUATOR_H_ 340ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong 351d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling#include <map> 360ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong#include <string> 370ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong#include <vector> 381d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 391d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling#include "ceres/execution_summary.h" 400ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong#include "ceres/internal/port.h" 410ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong#include "ceres/types.h" 420ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong 430ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kongnamespace ceres { 440ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong 450ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kongstruct CRSMatrix; 460ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong 470ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kongnamespace internal { 480ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong 490ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kongclass Program; 500ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kongclass SparseMatrix; 510ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong 520ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// The Evaluator interface offers a way to interact with a least squares cost 530ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// function that is useful for an optimizer that wants to minimize the least 540ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// squares objective. This insulates the optimizer from issues like Jacobian 550ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong// storage, parameterization, etc. 560ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kongclass Evaluator { 570ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong public: 580ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong virtual ~Evaluator(); 590ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong 600ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong struct Options { 610ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong Options() 620ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong : num_threads(1), 630ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong num_eliminate_blocks(-1), 640ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong linear_solver_type(DENSE_QR) {} 650ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong 660ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong int num_threads; 670ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong int num_eliminate_blocks; 680ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong LinearSolverType linear_solver_type; 690ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong }; 700ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong 710ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong static Evaluator* Create(const Options& options, 720ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong Program* program, 730ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong string* error); 740ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong 750ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // This is used for computing the cost, residual and Jacobian for 760ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // returning to the user. For actually solving the optimization 770ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // problem, the optimization algorithm uses the ProgramEvaluator 780ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // objects directly. 790ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // 800ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // The residual, gradients and jacobian pointers can be NULL, in 810ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // which case they will not be evaluated. cost cannot be NULL. 820ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // 830ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // The parallelism of the evaluator is controlled by num_threads; it 840ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // should be at least 1. 850ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // 860ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // Note: That this function does not take a parameter vector as 870ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // input. The parameter blocks are evaluated on the values contained 880ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // in the arrays pointed to by their user_state pointers. 890ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // 900ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // Also worth noting is that this function mutates program by 910ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // calling Program::SetParameterOffsetsAndIndex() on it so that an 920ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // evaluator object can be constructed. 930ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong static bool Evaluate(Program* program, 940ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong int num_threads, 950ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong double* cost, 960ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong vector<double>* residuals, 970ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong vector<double>* gradient, 980ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong CRSMatrix* jacobian); 990ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong 1000ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // Build and return a sparse matrix for storing and working with the Jacobian 1010ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // of the objective function. The jacobian has dimensions 1020ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // NumEffectiveParameters() by NumParameters(), and is typically extremely 1030ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // sparse. Since the sparsity pattern of the Jacobian remains constant over 1040ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // the lifetime of the optimization problem, this method is used to 1050ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // instantiate a SparseMatrix object with the appropriate sparsity structure 1060ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // (which can be an expensive operation) and then reused by the optimization 1070ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // algorithm and the various linear solvers. 1080ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // 1090ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // It is expected that the classes implementing this interface will be aware 1100ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // of their client's requirements for the kind of sparse matrix storage and 1110ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // layout that is needed for an efficient implementation. For example 1120ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // CompressedRowOptimizationProblem creates a compressed row representation of 1130ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // the jacobian for use with CHOLMOD, where as BlockOptimizationProblem 1140ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // creates a BlockSparseMatrix representation of the jacobian for use in the 1150ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // Schur complement based methods. 1160ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong virtual SparseMatrix* CreateJacobian() const = 0; 1170ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong 1181d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 1191d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling // Options struct to control Evaluator::Evaluate; 1201d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling struct EvaluateOptions { 1211d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling EvaluateOptions() 1221d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling : apply_loss_function(true) { 1231d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling } 1241d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 1251d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling // If false, the loss function correction is not applied to the 1261d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling // residual blocks. 1271d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling bool apply_loss_function; 1281d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling }; 1291d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 1300ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // Evaluate the cost function for the given state. Returns the cost, 1310ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // residuals, and jacobian in the corresponding arguments. Both residuals and 1320ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // jacobian are optional; to avoid computing them, pass NULL. 1330ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // 1340ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // If non-NULL, the Jacobian must have a suitable sparsity pattern; only the 1350ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // values array of the jacobian is modified. 1360ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // 1370ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // state is an array of size NumParameters(), cost is a pointer to a single 1380ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // double, and residuals is an array of doubles of size NumResiduals(). 1391d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling virtual bool Evaluate(const EvaluateOptions& evaluate_options, 1401d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling const double* state, 1410ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong double* cost, 1420ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong double* residuals, 1430ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong double* gradient, 1440ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong SparseMatrix* jacobian) = 0; 1450ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong 1461d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling // Variant of Evaluator::Evaluate where the user wishes to use the 1471d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling // default EvaluateOptions struct. This is mostly here as a 1481d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling // convenience method. 1491d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling bool Evaluate(const double* state, 1501d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling double* cost, 1511d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling double* residuals, 1521d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling double* gradient, 1531d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling SparseMatrix* jacobian) { 1541d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling return Evaluate(EvaluateOptions(), 1551d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling state, 1561d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling cost, 1571d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling residuals, 1581d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling gradient, 1591d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling jacobian); 1601d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling } 1611d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 1620ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // Make a change delta (of size NumEffectiveParameters()) to state (of size 1630ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // NumParameters()) and store the result in state_plus_delta. 1640ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // 1650ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // In the case that there are no parameterizations used, this is equivalent to 1660ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // 1670ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // state_plus_delta[i] = state[i] + delta[i] ; 1680ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // 1690ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // however, the mapping is more complicated in the case of parameterizations 1700ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // like quaternions. This is the same as the "Plus()" operation in 1710ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // local_parameterization.h, but operating over the entire state vector for a 1720ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // problem. 1730ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong virtual bool Plus(const double* state, 1740ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong const double* delta, 1750ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong double* state_plus_delta) const = 0; 1760ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong 1770ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // The number of parameters in the optimization problem. 1780ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong virtual int NumParameters() const = 0; 1790ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong 1800ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // This is the effective number of parameters that the optimizer may adjust. 1810ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // This applies when there are parameterizations on some of the parameters. 1820ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong virtual int NumEffectiveParameters() const = 0; 1830ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong 1840ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong // The number of residuals in the optimization problem. 1850ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong virtual int NumResiduals() const = 0; 1861d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 1871d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling // The following two methods return copies instead of references so 1881d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling // that the base class implementation does not have to worry about 1891d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling // life time issues. Further, these calls are not expected to be 1901d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling // frequent or performance sensitive. 1911d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling virtual map<string, int> CallStatistics() const { 1921d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling return map<string, int>(); 1931d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling } 1941d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling 1951d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling virtual map<string, double> TimeStatistics() const { 1961d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling return map<string, double>(); 1971d2624a10e2c559f8ba9ef89eaa30832c0a83a96Sascha Haeberling } 1980ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong}; 1990ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong 2000ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong} // namespace internal 2010ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong} // namespace ceres 2020ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong 2030ae28bd5885b5daa526898fcf7c323dc2c3e1963Angus Kong#endif // CERES_INTERNAL_EVALUATOR_H_ 204