include/ceres/cost_function.h

   1 // Ceres Solver - A fast non-linear least squares minimizer
   2 // Copyright 2015 Google Inc. All rights reserved.
   3 // http://ceres-solver.org/
   4 //
   5 // Redistribution and use in source and binary forms, with or without
   6 // modification, are permitted provided that the following conditions are met:
   7 //
   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.
  16 //
  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.
  28 //
  29 // Author: sameeragarwal@google.com (Sameer Agarwal)
  30 //         keir@google.m (Keir Mierle)
  31 //
  32 // This is the interface through which the least squares solver accesses the
  33 // residual and Jacobian of the least squares problem. Users are expected to
  34 // subclass CostFunction to define their own terms in the least squares problem.
  35 //
  36 // It is recommended that users define templated residual functors for use as
  37 // arguments for AutoDiffCostFunction (see autodiff_cost_function.h), instead of
  38 // directly implementing the CostFunction interface. This often results in both
  39 // shorter code and faster execution than hand-coded derivatives. However,
  40 // specialized cases may demand direct implementation of the lower-level
  41 // CostFunction interface; for example, this is true when calling legacy code
  42 // which is not templated on numeric types.
  43
  44 #ifndef CERES_PUBLIC_COST_FUNCTION_H_
  45 #define CERES_PUBLIC_COST_FUNCTION_H_
  46
  47 #include <vector>
  48 #include "ceres/internal/macros.h"
  49 #include "ceres/internal/port.h"
  50 #include "ceres/types.h"
  51 #include "ceres/internal/disable_warnings.h"
  52
  53 namespace ceres {
  54
  55 // This class implements the computation of the cost (a.k.a. residual) terms as
  56 // a function of the input (control) variables, and is the interface for users
  57 // to describe their least squares problem to Ceres. In other words, this is the
  58 // modelling layer between users and the Ceres optimizer. The signature of the
  59 // function (number and sizes of input parameter blocks and number of outputs)
  60 // is stored in parameter_block_sizes_ and num_residuals_ respectively. User
  61 // code inheriting from this class is expected to set these two members with the
  62 // corresponding accessors. This information will be verified by the Problem
  63 // when added with AddResidualBlock().
  64 class CERES_EXPORT CostFunction {
  65  public:
  66   CostFunction() : num_residuals_(0) {}
  67
  68   virtual ~CostFunction() {}
  69
  70   // Inputs:
  71   //
  72   // parameters is an array of pointers to arrays containing the
  73   // various parameter blocks. parameters has the same number of
  74   // elements as parameter_block_sizes_.  Parameter blocks are in the
  75   // same order as parameter_block_sizes_.i.e.,
  76   //
  77   //   parameters_[i] = double[parameter_block_sizes_[i]]
  78   //
  79   // Outputs:
  80   //
  81   // residuals is an array of size num_residuals_.
  82   //
  83   // jacobians is an array of size parameter_block_sizes_ containing
  84   // pointers to storage for jacobian blocks corresponding to each
  85   // parameter block. Jacobian blocks are in the same order as
  86   // parameter_block_sizes, i.e. jacobians[i], is an
  87   // array that contains num_residuals_* parameter_block_sizes_[i]
  88   // elements. Each jacobian block is stored in row-major order, i.e.,
  89   //
  90   //   jacobians[i][r*parameter_block_size_[i] + c] =
  91   //                              d residual[r] / d parameters[i][c]
  92   //
  93   // If jacobians is NULL, then no derivatives are returned; this is
  94   // the case when computing cost only. If jacobians[i] is NULL, then
  95   // the jacobian block corresponding to the i'th parameter block must
  96   // not to be returned.
  97   //
  98   // The return value indicates whether the computation of the
  99   // residuals and/or jacobians was successful or not.
 100   //
 101   // This can be used to communicate numerical failures in jacobian
 102   // computations for instance.
 103   //
 104   // A more interesting and common use is to impose constraints on the
 105   // parameters. If the initial values of the parameter blocks satisfy
 106   // the constraints, then returning false whenever the constraints
 107   // are not satisfied will prevent the solver from moving into the
 108   // infeasible region. This is not a very sophisticated mechanism for
 109   // enforcing constraints, but is often good enough.
 110   //
 111   // Note that it is important that the initial values of the
 112   // parameter block must be feasible, otherwise the solver will
 113   // declare a numerical problem at iteration 0.
 114   virtual bool Evaluate(double const* const* parameters,
 115                         double* residuals,
 116                         double** jacobians) const = 0;
 117
 118   const std::vector<int32>& parameter_block_sizes() const {
 119     return parameter_block_sizes_;
 120   }
 121
 122   int num_residuals() const {
 123     return num_residuals_;
 124   }
 125
 126  protected:
 127   std::vector<int32>* mutable_parameter_block_sizes() {
 128     return &parameter_block_sizes_;
 129   }
 130
 131   void set_num_residuals(int num_residuals) {
 132     num_residuals_ = num_residuals;
 133   }
 134
 135  private:
 136   // Cost function signature metadata: number of inputs & their sizes,
 137   // number of outputs (residuals).
 138   std::vector<int32> parameter_block_sizes_;
 139   int num_residuals_;
 140   CERES_DISALLOW_COPY_AND_ASSIGN(CostFunction);
 141 };
 142
 143 }  // namespace ceres
 144
 145 #include "ceres/internal/reenable_warnings.h"
 146
 147 #endif  // CERES_PUBLIC_COST_FUNCTION_H_