da9ee2c7993e7b5b4816838d0aca32368ec3fdd1
[blender.git] / 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_