1// Ceres Solver - A fast non-linear least squares minimizer
2// Copyright 2010, 2011, 2012 Google Inc. All rights reserved.
3// http://code.google.com/p/ceres-solver/
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
53namespace 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().
64class 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 for things like
110  // non-negativity constraints.
111  //
112  // Note that it is important that the initial values of the
113  // parameter block must be feasible, otherwise the solver will
114  // declare a numerical problem at iteration 0.
115  virtual bool Evaluate(double const* const* parameters,
116                        double* residuals,
117                        double** jacobians) const = 0;
118
119  const vector<int32>& parameter_block_sizes() const {
120    return parameter_block_sizes_;
121  }
122
123  int num_residuals() const {
124    return num_residuals_;
125  }
126
127 protected:
128  vector<int32>* mutable_parameter_block_sizes() {
129    return &parameter_block_sizes_;
130  }
131
132  void set_num_residuals(int num_residuals) {
133    num_residuals_ = num_residuals;
134  }
135
136 private:
137  // Cost function signature metadata: number of inputs & their sizes,
138  // number of outputs (residuals).
139  vector<int32> parameter_block_sizes_;
140  int num_residuals_;
141  CERES_DISALLOW_COPY_AND_ASSIGN(CostFunction);
142};
143
144}  // namespace ceres
145
146#include "ceres/internal/reenable_warnings.h"
147
148#endif  // CERES_PUBLIC_COST_FUNCTION_H_
149