← Back to branch summary

~ubuntu-branches/ubuntu/trusty/blender/trusty

« back to all changes in this revision

Viewing changes to extern/libmv/third_party/ceres/include/ceres/autodiff_cost_function.h

  • Committer: Package Import Robot
  • Author(s): Jeremy Bicha
  • Date: 2013-03-06 12:08:47 UTC
  • mfrom: (1.5.1) (14.1.8 experimental)
  • Revision ID: package-import@ubuntu.com-20130306120847-frjfaryb2zrotwcg
Tags: 2.66a-1ubuntu1
https://launchpad.net/bugs/1076930
https://launchpad.net/bugs/1089256
https://launchpad.net/bugs/1052743
https://launchpad.net/bugs/999024
* Resynchronize with Debian (LP: #1076930, #1089256, #1052743, #999024,
  #1122888, #1147084)
* debian/control:
  - Lower build-depends on libavcodec-dev since we're not
    doing the libav9 transition in Ubuntu yet

Show diffs side-by-side

added added

removed removed

Lines of Context:
extern/libmv/third_party/ceres/include/ceres/autodiff_cost_function.h
 
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
//
 
31
// Helpers for making CostFunctions as needed by the least squares framework,
 
32
// with Jacobians computed via automatic differentiation. For more information
 
33
// on automatic differentation, see the wikipedia article at
 
34
// http://en.wikipedia.org/wiki/Automatic_differentiation
 
35
//
 
36
// To get an auto differentiated cost function, you must define a class with a
 
37
// templated operator() (a functor) that computes the cost function in terms of
 
38
// the template parameter T. The autodiff framework substitutes appropriate
 
39
// "jet" objects for T in order to compute the derivative when necessary, but
 
40
// this is hidden, and you should write the function as if T were a scalar type
 
41
// (e.g. a double-precision floating point number).
 
42
//
 
43
// The function must write the computed value in the last argument (the only
 
44
// non-const one) and return true to indicate success.
 
45
//
 
46
// For example, consider a scalar error e = k - x'y, where both x and y are
 
47
// two-dimensional column vector parameters, the prime sign indicates
 
48
// transposition, and k is a constant. The form of this error, which is the
 
49
// difference between a constant and an expression, is a common pattern in least
 
50
// squares problems. For example, the value x'y might be the model expectation
 
51
// for a series of measurements, where there is an instance of the cost function
 
52
// for each measurement k.
 
53
//
 
54
// The actual cost added to the total problem is e^2, or (k - x'k)^2; however,
 
55
// the squaring is implicitly done by the optimization framework.
 
56
//
 
57
// To write an auto-differentiable cost function for the above model, first
 
58
// define the object
 
59
//
 
60
//   class MyScalarCostFunction {
 
61
//     MyScalarCostFunction(double k): k_(k) {}
 
62
//
 
63
//     template <typename T>
 
64
//     bool operator()(const T* const x , const T* const y, T* e) const {
 
65
//       e[0] = T(k_) - x[0] * y[0] + x[1] * y[1];
 
66
//       return true;
 
67
//     }
 
68
//
 
69
//    private:
 
70
//     double k_;
 
71
//   };
 
72
//
 
73
// Note that in the declaration of operator() the input parameters x and y come
 
74
// first, and are passed as const pointers to arrays of T. If there were three
 
75
// input parameters, then the third input parameter would come after y. The
 
76
// output is always the last parameter, and is also a pointer to an array. In
 
77
// the example above, e is a scalar, so only e[0] is set.
 
78
//
 
79
// Then given this class definition, the auto differentiated cost function for
 
80
// it can be constructed as follows.
 
81
//
 
82
//   CostFunction* cost_function
 
83
//       = new AutoDiffCostFunction<MyScalarCostFunction, 1, 2, 2>(
 
84
//           new MyScalarCostFunction(1.0));              ^  ^  ^
 
85
//                                                        |  |  |
 
86
//                            Dimension of residual ------+  |  |
 
87
//                            Dimension of x ----------------+  |
 
88
//                            Dimension of y -------------------+
 
89
//
 
90
// In this example, there is usually an instance for each measumerent of k.
 
91
//
 
92
// In the instantiation above, the template parameters following
 
93
// "MyScalarCostFunction", "1, 2, 2", describe the functor as computing a
 
94
// 1-dimensional output from two arguments, both 2-dimensional.
 
95
//
 
96
// The autodiff cost function also supports cost functions with a
 
97
// runtime-determined number of residuals. For example:
 
98
//
 
99
//   CostFunction* cost_function
 
100
//       = new AutoDiffCostFunction<MyScalarCostFunction, DYNAMIC, 2, 2>(
 
101
//           new CostFunctionWithDynamicNumResiduals(1.0),   ^     ^  ^
 
102
//           runtime_number_of_residuals); <----+            |     |  |
 
103
//                                              |            |     |  |
 
104
//                                              |            |     |  |
 
105
//             Actual number of residuals ------+            |     |  |
 
106
//             Indicate dynamic number of residuals ---------+     |  |
 
107
//             Dimension of x -------------------------------------+  |
 
108
//             Dimension of y ----------------------------------------+
 
109
//
 
110
// The framework can currently accommodate cost functions of up to 6 independent
 
111
// variables, and there is no limit on the dimensionality of each of them.
 
112
//
 
113
// WARNING #1: Since the functor will get instantiated with different types for
 
114
// T, you must to convert from other numeric types to T before mixing
 
115
// computations with other variables of type T. In the example above, this is
 
116
// seen where instead of using k_ directly, k_ is wrapped with T(k_).
 
117
//
 
118
// WARNING #2: A common beginner's error when first using autodiff cost
 
119
// functions is to get the sizing wrong. In particular, there is a tendency to
 
120
// set the template parameters to (dimension of residual, number of parameters)
 
121
// instead of passing a dimension parameter for *every parameter*. In the
 
122
// example above, that would be <MyScalarCostFunction, 1, 2>, which is missing
 
123
// the last '2' argument. Please be careful when setting the size parameters.
 
124
 
 
125
#ifndef CERES_PUBLIC_AUTODIFF_COST_FUNCTION_H_
 
126
#define CERES_PUBLIC_AUTODIFF_COST_FUNCTION_H_
 
127
 
 
128
#include <glog/logging.h>
 
129
#include "ceres/internal/autodiff.h"
 
130
#include "ceres/internal/scoped_ptr.h"
 
131
#include "ceres/sized_cost_function.h"
 
132
#include "ceres/types.h"
 
133
 
 
134
namespace ceres {
 
135
 
 
136
// A cost function which computes the derivative of the cost with respect to
 
137
// the parameters (a.k.a. the jacobian) using an autodifferentiation framework.
 
138
// The first template argument is the functor object, described in the header
 
139
// comment. The second argument is the dimension of the residual (or
 
140
// ceres::DYNAMIC to indicate it will be set at runtime), and subsequent
 
141
// arguments describe the size of the Nth parameter, one per parameter.
 
142
//
 
143
// The constructors take ownership of the cost functor.
 
144
//
 
145
// If the number of residuals (argument "M" below) is ceres::DYNAMIC, then the
 
146
// two-argument constructor must be used. The second constructor takes a number
 
147
// of residuals (in addition to the templated number of residuals). This allows
 
148
// for varying the number of residuals for a single autodiff cost function at
 
149
// runtime.
 
150
template <typename CostFunctor,
 
151
          int M,        // Number of residuals, or ceres::DYNAMIC.
 
152
          int N0,       // Number of parameters in block 0.
 
153
          int N1 = 0,   // Number of parameters in block 1.
 
154
          int N2 = 0,   // Number of parameters in block 2.
 
155
          int N3 = 0,   // Number of parameters in block 3.
 
156
          int N4 = 0,   // Number of parameters in block 4.
 
157
          int N5 = 0>   // Number of parameters in block 5.
 
158
class AutoDiffCostFunction :
 
159
  public SizedCostFunction<M, N0, N1, N2, N3, N4, N5> {
 
160
 public:
 
161
  // Takes ownership of functor. Uses the template-provided value for the
 
162
  // number of residuals ("M").
 
163
  explicit AutoDiffCostFunction(CostFunctor* functor)
 
164
      : functor_(functor) {
 
165
    CHECK_NE(M, DYNAMIC) << "Can't run the fixed-size constructor if the "
 
166
                          << "number of residuals is set to ceres::DYNAMIC.";
 
167
  }
 
168
 
 
169
  // Takes ownership of functor. Ignores the template-provided number of
 
170
  // residuals ("M") in favor of the "num_residuals" argument provided.
 
171
  //
 
172
  // This allows for having autodiff cost functions which return varying
 
173
  // numbers of residuals at runtime.
 
174
  AutoDiffCostFunction(CostFunctor* functor, int num_residuals)
 
175
      : functor_(functor) {
 
176
    CHECK_EQ(M, DYNAMIC) << "Can't run the dynamic-size constructor if the "
 
177
                          << "number of residuals is not ceres::DYNAMIC.";
 
178
    SizedCostFunction<M, N0, N1, N2, N3, N4, N5>::set_num_residuals(num_residuals);
 
179
  }
 
180
 
 
181
  virtual ~AutoDiffCostFunction() {}
 
182
 
 
183
  // Implementation details follow; clients of the autodiff cost function should
 
184
  // not have to examine below here.
 
185
  //
 
186
  // To handle varardic cost functions, some template magic is needed. It's
 
187
  // mostly hidden inside autodiff.h.
 
188
  virtual bool Evaluate(double const* const* parameters,
 
189
                        double* residuals,
 
190
                        double** jacobians) const {
 
191
    if (!jacobians) {
 
192
      return internal::VariadicEvaluate<
 
193
          CostFunctor, double, N0, N1, N2, N3, N4, N5>
 
194
          ::Call(*functor_, parameters, residuals);
 
195
    }
 
196
    return internal::AutoDiff<CostFunctor, double,
 
197
           N0, N1, N2, N3, N4, N5>::Differentiate(
 
198
               *functor_,
 
199
               parameters,
 
200
               SizedCostFunction<M, N0, N1, N2, N3, N4, N5>::num_residuals(),
 
201
               residuals,
 
202
               jacobians);
 
203
  }
 
204
 
 
205
 private:
 
206
  internal::scoped_ptr<CostFunctor> functor_;
 
207
};
 
208
 
 
209
}  // namespace ceres
 
210
 
 
211
#endif  // CERES_PUBLIC_AUTODIFF_COST_FUNCTION_H_