Ceres: Update to the latest actual version
[blender.git] / extern / ceres / include / ceres / gradient_checker.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 // Copyright 2007 Google Inc. All Rights Reserved.
29 //
30 // Authors: wjr@google.com (William Rucklidge),
31 //          keir@google.com (Keir Mierle),
32 //          dgossow@google.com (David Gossow)
33
34 #ifndef CERES_PUBLIC_GRADIENT_CHECKER_H_
35 #define CERES_PUBLIC_GRADIENT_CHECKER_H_
36
37 #include <vector>
38 #include <string>
39
40 #include "ceres/cost_function.h"
41 #include "ceres/dynamic_numeric_diff_cost_function.h"
42 #include "ceres/internal/eigen.h"
43 #include "ceres/internal/fixed_array.h"
44 #include "ceres/internal/macros.h"
45 #include "ceres/internal/scoped_ptr.h"
46 #include "ceres/local_parameterization.h"
47 #include "glog/logging.h"
48
49 namespace ceres {
50
51 // GradientChecker compares the Jacobians returned by a cost function against
52 // derivatives estimated using finite differencing.
53 //
54 // The condition enforced is that
55 //
56 //    (J_actual(i, j) - J_numeric(i, j))
57 //   ------------------------------------  <  relative_precision
58 //   max(J_actual(i, j), J_numeric(i, j))
59 //
60 // where J_actual(i, j) is the jacobian as computed by the supplied cost
61 // function (by the user) multiplied by the local parameterization Jacobian
62 // and J_numeric is the jacobian as computed by finite differences, multiplied
63 // by the local parameterization Jacobian as well.
64 //
65 // How to use: Fill in an array of pointers to parameter blocks for your
66 // CostFunction, and then call Probe(). Check that the return value is 'true'.
67 class GradientChecker {
68  public:
69   // This will not take ownership of the cost function or local
70   // parameterizations.
71   //
72   // function: The cost function to probe.
73   // local_parameterization: A vector of local parameterizations for each
74   // parameter. May be NULL or contain NULL pointers to indicate that the
75   // respective parameter does not have a local parameterization.
76   // options: Options to use for numerical differentiation.
77   GradientChecker(
78       const CostFunction* function,
79       const std::vector<const LocalParameterization*>* local_parameterizations,
80       const NumericDiffOptions& options);
81
82   // Contains results from a call to Probe for later inspection.
83   struct ProbeResults {
84     // The return value of the cost function.
85     bool return_value;
86
87     // Computed residual vector.
88     Vector residuals;
89
90     // The sizes of the Jacobians below are dictated by the cost function's
91     // parameter block size and residual block sizes. If a parameter block
92     // has a local parameterization associated with it, the size of the "local"
93     // Jacobian will be determined by the local parameterization dimension and
94     // residual block size, otherwise it will be identical to the regular
95     // Jacobian.
96
97     // Derivatives as computed by the cost function.
98     std::vector<Matrix> jacobians;
99
100     // Derivatives as computed by the cost function in local space.
101     std::vector<Matrix> local_jacobians;
102
103     // Derivatives as computed by nuerical differentiation in local space.
104     std::vector<Matrix> numeric_jacobians;
105
106     // Derivatives as computed by nuerical differentiation in local space.
107     std::vector<Matrix> local_numeric_jacobians;
108
109     // Contains the maximum relative error found in the local Jacobians.
110     double maximum_relative_error;
111
112     // If an error was detected, this will contain a detailed description of
113     // that error.
114     std::string error_log;
115   };
116
117   // Call the cost function, compute alternative Jacobians using finite
118   // differencing and compare results. If local parameterizations are given,
119   // the Jacobians will be multiplied by the local parameterization Jacobians
120   // before performing the check, which effectively means that all errors along
121   // the null space of the local parameterization will be ignored.
122   // Returns false if the Jacobians don't match, the cost function return false,
123   // or if the cost function returns different residual when called with a
124   // Jacobian output argument vs. calling it without. Otherwise returns true.
125   //
126   // parameters: The parameter values at which to probe.
127   // relative_precision: A threshold for the relative difference between the
128   // Jacobians. If the Jacobians differ by more than this amount, then the
129   // probe fails.
130   // results: On return, the Jacobians (and other information) will be stored
131   // here. May be NULL.
132   //
133   // Returns true if no problems are detected and the difference between the
134   // Jacobians is less than error_tolerance.
135   bool Probe(double const* const* parameters,
136              double relative_precision,
137              ProbeResults* results) const;
138
139  private:
140   CERES_DISALLOW_IMPLICIT_CONSTRUCTORS(GradientChecker);
141
142   std::vector<const LocalParameterization*> local_parameterizations_;
143   const CostFunction* function_;
144   internal::scoped_ptr<CostFunction> finite_diff_cost_function_;
145 };
146
147 }  // namespace ceres
148
149 #endif  // CERES_PUBLIC_GRADIENT_CHECKER_H_