internal/ceres/test_util.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: keir@google.com (Keir Mierle)
  30
  31 #include <string>
  32 #include "ceres/internal/port.h"
  33 #include "ceres/problem.h"
  34 #include "ceres/solver.h"
  35 #include "ceres/stringprintf.h"
  36 #include "gtest/gtest.h"
  37
  38
  39 #ifndef CERES_INTERNAL_TEST_UTIL_H_
  40 #define CERES_INTERNAL_TEST_UTIL_H_
  41
  42 namespace ceres {
  43 namespace internal {
  44
  45 // Expects that x and y have a relative difference of no more than
  46 // max_abs_relative_difference. If either x or y is zero, then the relative
  47 // difference is interpreted as an absolute difference.
  48 bool ExpectClose(double x, double y, double max_abs_relative_difference);
  49
  50 // Expects that for all i = 1,.., n - 1
  51 //
  52 //   |p[i] - q[i]| / max(|p[i]|, |q[i]|) < tolerance
  53 void ExpectArraysClose(int n,
  54                        const double* p,
  55                        const double* q,
  56                        double tolerance);
  57
  58 // Expects that for all i = 1,.., n - 1
  59 //
  60 //   |p[i] / max_norm_p - q[i] / max_norm_q| < tolerance
  61 //
  62 // where max_norm_p and max_norm_q are the max norms of the arrays p
  63 // and q respectively.
  64 void ExpectArraysCloseUptoScale(int n,
  65                                 const double* p,
  66                                 const double* q,
  67                                 double tolerance);
  68
  69 // Construct a fully qualified path for the test file depending on the
  70 // local build/testing environment.
  71 std::string TestFileAbsolutePath(const std::string& filename);
  72
  73 // Struct used for configuring the solver. Used by end-to-end tests.
  74 struct SolverConfig {
  75   SolverConfig(
  76       LinearSolverType linear_solver_type,
  77       SparseLinearAlgebraLibraryType
  78       sparse_linear_algebra_library_type = NO_SPARSE,
  79       bool use_automatic_ordering = true,
  80       PreconditionerType preconditioner_type = IDENTITY,
  81       int num_threads = 1)
  82       : linear_solver_type(linear_solver_type),
  83         sparse_linear_algebra_library_type(sparse_linear_algebra_library_type),
  84         use_automatic_ordering(use_automatic_ordering),
  85         preconditioner_type(preconditioner_type),
  86         num_threads(num_threads) {
  87   }
  88
  89   std::string ToString() const {
  90     return StringPrintf(
  91         "(%s, %s, %s, %s, %d)",
  92         LinearSolverTypeToString(linear_solver_type),
  93         SparseLinearAlgebraLibraryTypeToString(
  94             sparse_linear_algebra_library_type),
  95         use_automatic_ordering ? "AUTOMATIC" : "USER",
  96         PreconditionerTypeToString(preconditioner_type),
  97         num_threads);
  98   }
  99
 100   void UpdateOptions(Solver::Options* options) const {
 101     options->linear_solver_type = linear_solver_type;
 102     options->sparse_linear_algebra_library_type =
 103         sparse_linear_algebra_library_type;
 104     options->preconditioner_type = preconditioner_type;
 105     options->num_threads = num_threads;
 106     options->num_linear_solver_threads = num_threads;
 107
 108     if (use_automatic_ordering) {
 109       options->linear_solver_ordering.reset();
 110     }
 111   }
 112
 113   LinearSolverType linear_solver_type;
 114   SparseLinearAlgebraLibraryType sparse_linear_algebra_library_type;
 115   bool use_automatic_ordering;
 116   PreconditionerType preconditioner_type;
 117   int num_threads;
 118 };
 119
 120 SolverConfig ThreadedSolverConfig(
 121     LinearSolverType linear_solver_type,
 122     SparseLinearAlgebraLibraryType
 123     sparse_linear_algebra_library_type = NO_SPARSE,
 124     bool use_automatic_ordering = true,
 125     PreconditionerType preconditioner_type = IDENTITY);
 126
 127 // A templated test fixture, that is used for testing Ceres end to end
 128 // by computing a solution to the problem for a given solver
 129 // configuration and comparing it to a reference solver configuration.
 130 //
 131 // It is assumed that the SystemTestProblem has an Solver::Options
 132 // struct that contains the reference Solver configuration.
 133 template <class SystemTestProblem>
 134 class SystemTest : public::testing::Test {
 135  protected:
 136   virtual void SetUp() {
 137     SystemTestProblem system_test_problem;
 138     SolveAndEvaluateFinalResiduals(
 139         *system_test_problem.mutable_solver_options(),
 140         system_test_problem.mutable_problem(),
 141         &expected_final_residuals_);
 142   }
 143
 144   void RunSolverForConfigAndExpectResidualsMatch(const SolverConfig& config) {
 145     LOG(INFO) << "Running solver configuration: "
 146               << config.ToString();
 147
 148     SystemTestProblem system_test_problem;
 149     config.UpdateOptions(system_test_problem.mutable_solver_options());
 150     std::vector<double> final_residuals;
 151     SolveAndEvaluateFinalResiduals(
 152         *system_test_problem.mutable_solver_options(),
 153         system_test_problem.mutable_problem(),
 154         &final_residuals);
 155
 156     // We compare solutions by comparing their residual vectors. We do
 157     // not compare parameter vectors because it is much more brittle
 158     // and error prone to do so, since the same problem can have
 159     // nearly the same residuals at two completely different positions
 160     // in parameter space.
 161     CHECK_EQ(expected_final_residuals_.size(), final_residuals.size());
 162     for (int i = 0; i < final_residuals.size(); ++i) {
 163       EXPECT_NEAR(final_residuals[i],
 164                   expected_final_residuals_[i],
 165                   SystemTestProblem::kResidualTolerance)
 166           << "Not close enough residual:" << i;
 167     }
 168   }
 169
 170   void SolveAndEvaluateFinalResiduals(const Solver::Options& options,
 171                                       Problem* problem,
 172                                       std::vector<double>* final_residuals) {
 173     Solver::Summary summary;
 174     Solve(options, problem, &summary);
 175     CHECK_NE(summary.termination_type, ceres::FAILURE);
 176     problem->Evaluate(Problem::EvaluateOptions(),
 177                       NULL,
 178                       final_residuals,
 179                       NULL,
 180                       NULL);
 181   }
 182
 183   std::vector<double> expected_final_residuals_;
 184 };
 185
 186 }  // namespace internal
 187 }  // namespace ceres
 188
 189 #endif  // CERES_INTERNAL_TEST_UTIL_H_